<?php

/*
 * This file is part of the Symfony package.
 *
 * (c) Fabien Potencier <fabien@symfony.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

namespace Symfony\Component\Form;

/**
 * A form group bundling multiple form forms
 *
 * @author Bernhard Schussek <bernhard.schussek@symfony.com>
 */
interface FormInterface extends \ArrayAccess, \Traversable, \Countable
{
    /**
     * Sets the parent form.
     *
     * @param FormInterface $parent The parent form
     */
    function setParent(FormInterface $parent = null);

    /**
     * Returns the parent form.
     *
     * @return FormInterface The parent form
     */
    function getParent();

    /**
     * Returns whether the form has a parent.
     *
     * @return Boolean
     */
    function hasParent();

    /**
     * Adds a child to the form.
     *
     * @param FormInterface $child The FormInterface to add as a child
     */
    function add(FormInterface $child);

    /**
     * Returns whether a child with the given name exists.
     *
     * @param string $name
     *
     * @return Boolean
     */
    function has($name);

    /**
     * Removes a child from the form.
     *
     * @param string $name The name of the child to remove
     */
    function remove($name);

    /**
     * Returns all children in this group.
     *
     * @return array An array of FormInterface instances
     */
    function getChildren();

    /**
     * Return whether the form has children.
     *
     * @return Boolean
     */
    function hasChildren();

    /**
     * Returns all errors.
     *
     * @return array An array of FormError instances that occurred during binding
     */
    function getErrors();

    /**
     * Updates the field with default data.
     *
     * @param array $appData The data formatted as expected for the underlying object
     *
     * @return Form The current form
     */
    function setData($appData);

    /**
     * Returns the data in the format needed for the underlying object.
     *
     * @return mixed
     */
    function getData();

    /**
     * Returns the normalized data of the field.
     *
     * @return mixed  When the field is not bound, the default data is returned.
     *                When the field is bound, the normalized bound data is
     *                returned if the field is valid, null otherwise.
     */
    function getNormData();

    /**
     * Returns the data transformed by the value transformer.
     *
     * @return string
     */
    function getClientData();

    /**
     * Returns the extra data.
     *
     * @return array The bound data which do not belong to a child
     */
    function getExtraData();

    /**
     * Returns whether the field is bound.
     *
     * @return Boolean true if the form is bound to input values, false otherwise
     */
    function isBound();

    /**
     * Returns the supported types.
     *
     * @return array An array of FormTypeInterface
     */
    function getTypes();

    /**
     * Returns the name by which the form is identified in forms.
     *
     * @return string  The name of the form.
     */
    function getName();

    /**
     * Adds an error to this form.
     *
     * @param FormError $error
     */
    function addError(FormError $error);

    /**
     * Returns whether the form is valid.
     *
     * @return Boolean
     */
    function isValid();

    /**
     * Returns whether the form is required to be filled out.
     *
     * If the form has a parent and the parent is not required, this method
     * will always return false. Otherwise the value set with setRequired()
     * is returned.
     *
     * @return Boolean
     */
    function isRequired();

    /**
     * Returns whether this form can be read only.
     *
     * The content of a read-only form is displayed, but not allowed to be
     * modified. The validation of modified read-only forms should fail.
     *
     * Fields whose parents are read-only are considered read-only regardless of
     * their own state.
     *
     * @return Boolean
     */
    function isReadOnly();

    /**
     * Returns whether the form is empty.
     *
     * @return Boolean
     */
    function isEmpty();

    /**
     * Returns whether the data in the different formats is synchronized.
     *
     * @return Boolean
     */
    function isSynchronized();

    /**
     * Writes data into the form.
     *
     * @param mixed $data  The data
     */
    function bind($data);

    /**
     * Returns whether the form has an attribute with the given name.
     *
     * @param string $name The name of the attribute
     */
    function hasAttribute($name);

    /**
     * Returns the value of the attributes with the given name.
     *
     * @param string $name The name of the attribute
     */
    function getAttribute($name);

    /**
     * Returns the root of the form tree.
     *
     * @return FormInterface  The root of the tree
     */
    function getRoot();

    /**
     * Returns whether the field is the root of the form tree.
     *
     * @return Boolean
     */
    function isRoot();

    /**
     * Creates a view.
     *
     * @param FormView $parent The parent view
     *
     * @return FormView The view
     */
    function createView(FormView $parent = null);
}