com.google.gwt.user.client.ui

## Class FormPanel

- java.lang.Object
- - com.google.gwt.user.client.ui.UIObject
  - - com.google.gwt.user.client.ui.Widget
    - - com.google.gwt.user.client.ui.Panel
      - - com.google.gwt.user.client.ui.SimplePanel
        - - com.google.gwt.user.client.ui.FormPanel

- All Implemented Interfaces:
    HasAttachHandlers, HasHandlers, EventListener, AcceptsOneWidget, FiresFormEvents, HasOneWidget, HasVisibility, HasWidgets, HasWidgets.ForIsWidget, com.google.gwt.user.client.ui.impl.FormPanelImplHost, IsWidget, java.lang.Iterable<Widget>

      public class FormPanel
      extends SimplePanel
      implements FiresFormEvents, com.google.gwt.user.client.ui.impl.FormPanelImplHost

  A panel that wraps its contents in an HTML <FORM> element.

  This panel can be used to achieve interoperability with servers that accept traditional HTML form encoding. The following widgets (those that implement `HasName`) will be submitted to the server if they are contained within this panel:

  - `TextBox`
  - `PasswordTextBox`
  - `RadioButton`
  - `SimpleRadioButton`
  - `CheckBox`
  - `SimpleCheckBox`
  - `TextArea`
  - `ListBox`
  - `FileUpload`
  - `Hidden`
  In particular, `FileUpload` is only useful when used within a FormPanel, because the browser will only upload files using form submission.

  ### Example

  >     public class FormPanelExample implements EntryPoint {

  >       public void onModuleLoad() {
  >         // Create a FormPanel and point it at a service.
  >         final FormPanel form = new FormPanel();
  >         form.setAction("/myFormHandler");

  >         // Because we're going to add a FileUpload widget, we'll need to set the
  >         // form to use the POST method, and multipart MIME encoding.
  >         form.setEncoding(FormPanel.ENCODING_MULTIPART);
  >         form.setMethod(FormPanel.METHOD_POST);

  >         // Create a panel to hold all of the form widgets.
  >         VerticalPanel panel = new VerticalPanel();
  >         form.setWidget(panel);

  >         // Create a TextBox, giving it a name so that it will be submitted.
  >         final TextBox tb = new TextBox();
  >         tb.setName("textBoxFormElement");
  >         panel.add(tb);

  >         // Create a ListBox, giving it a name and some values to be associated with
  >         // its options.
  >         ListBox lb = new ListBox();
  >         lb.setName("listBoxFormElement");
  >         lb.addItem("foo", "fooValue");
  >         lb.addItem("bar", "barValue");
  >         lb.addItem("baz", "bazValue");
  >         panel.add(lb);

  >         // Create a FileUpload widget.
  >         FileUpload upload = new FileUpload();
  >         upload.setName("uploadFormElement");
  >         panel.add(upload);

  >         // Add a 'submit' button.
  >         panel.add(new Button("Submit", new ClickHandler() {
  >           public void onClick(ClickEvent event) {
  >             form.submit();
  >           }
  >         }));

  >         // Add an event handler to the form.
  >         form.addSubmitHandler(new FormPanel.SubmitHandler() {
  >           public void onSubmit(SubmitEvent event) {
  >             // This event is fired just before the form is submitted. We can take
  >             // this opportunity to perform validation.
  >             if (tb.getText().length() == 0) {
  >               Window.alert("The text box must not be empty");
  >               event.cancel();
  >             }
  >           }
  >         });
  >         form.addSubmitCompleteHandler(new FormPanel.SubmitCompleteHandler() {
  >           public void onSubmitComplete(SubmitCompleteEvent event) {
  >             // When the form submission is successfully completed, this event is
  >             // fired. Assuming the service returned a response of type text/html,
  >             // we can get the result text here (see the FormPanel documentation for
  >             // further explanation).
  >             Window.alert(event.getResults());
  >           }
  >         });

  >         RootPanel.get().add(form);
  >       }
  >     }

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `(package private) static interface` | `FormPanel.IFrameTemplate`
    `static class` | `FormPanel.SubmitCompleteEvent` Fired when a form has been submitted successfully.
    `static interface` | `FormPanel.SubmitCompleteHandler` Handler for `FormPanel.SubmitCompleteEvent` events.
    `static class` | `FormPanel.SubmitEvent` Fired when the form is submitted.
    `static interface` | `FormPanel.SubmitHandler` Handler for `FormPanel.SubmitEvent` events.

    - ### Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.UIObject

      `UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled`

    - ### Nested classes/interfaces inherited from interface com.google.gwt.user.client.ui.HasWidgets

      `HasWidgets.ForIsWidget`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `ENCODING_MULTIPART` Used with `setEncoding(String)` to specify that the form will be submitted using MIME encoding (necessary for `FileUpload` to work properly).
    `static java.lang.String` | `ENCODING_URLENCODED` Used with `setEncoding(String)` to specify that the form will be submitted using traditional URL encoding.
    `static java.lang.String` | `METHOD_GET` Used with `setMethod(String)` to specify that the form will be submitted using an HTTP GET request.
    `static java.lang.String` | `METHOD_POST` Used with `setMethod(String)` to specify that the form will be submitted using an HTTP POST request (necessary for `FileUpload` to work properly).

    - ### Fields inherited from class com.google.gwt.user.client.ui.SimplePanel

      `widget`

    - ### Fields inherited from class com.google.gwt.user.client.ui.Widget

      `eventsToSink`

    - ### Fields inherited from class com.google.gwt.user.client.ui.UIObject

      `DEBUG_ID_PREFIX, MISSING_ELEMENT_ERROR, SETELEMENT_TWICE_ERROR`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `FormPanel()` Creates a new FormPanel.
    `protected` | `FormPanel(Element element)` This constructor may be used by subclasses to explicitly use an existing element.
    `protected` | `FormPanel(Element element, boolean createIFrame)` This constructor may be used by subclasses to explicitly use an existing element.
    `` | `FormPanel(NamedFrame frameTarget)` Creates a FormPanel that targets a `NamedFrame`.
    `` | `FormPanel(java.lang.String target)` Creates a new FormPanel.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addFormHandler(FormHandler handler)` Deprecated. Use `addSubmitCompleteHandler(com.google.gwt.user.client.ui.FormPanel.SubmitCompleteHandler)` and `addSubmitHandler(com.google.gwt.user.client.ui.FormPanel.SubmitHandler)` instead
    `HandlerRegistration` | `addSubmitCompleteHandler(FormPanel.SubmitCompleteHandler handler)` Adds a `FormPanel.SubmitCompleteEvent` handler.
    `HandlerRegistration` | `addSubmitHandler(FormPanel.SubmitHandler handler)` Adds a `FormPanel.SubmitEvent` handler.
    `java.lang.String` | `getAction()` Gets the 'action' associated with this form.
    `java.lang.String` | `getEncoding()` Gets the encoding used for submitting this form.
    `java.lang.String` | `getMethod()` Gets the HTTP method used for submitting this form.
    `(package private) Element` | `getSynthesizedIFrame()`
    `java.lang.String` | `getTarget()` Gets the form's 'target'.
    `protected void` | `onAttach()` This method is called when a widget is attached to the browser's document.
    `protected void` | `onDetach()` This method is called when a widget is detached from the browser's document.
    `boolean` | `onFormSubmit()` Fired when a form is submitted.
    `void` | `onFrameLoad()` Called when the target frame is done loading.
    `void` | `removeFormHandler(FormHandler handler)` Deprecated. Use the `HandlerRegistration.removeHandler()` method on the object returned by and add*Handler method instead
    `void` | `reset()` Resets the form, clearing all fields.
    `void` | `setAction(SafeUri url)` Sets the 'action' associated with this form.
    `void` | `setAction(java.lang.String url)` Sets the 'action' associated with this form.
    `void` | `setEncoding(java.lang.String encodingType)` Sets the encoding used for submitting this form.
    `void` | `setMethod(java.lang.String method)` Sets the HTTP method used for submitting this form.
    `void` | `submit()` Submits the form.
    `static FormPanel` | `wrap(Element element)` Creates a FormPanel that wraps an existing <form> element.
    `static FormPanel` | `wrap(Element element, boolean createIFrame)` Creates a FormPanel that wraps an existing <form> element.

    - ### Methods inherited from class com.google.gwt.user.client.ui.SimplePanel

      `add, getContainerElement, getWidget, iterator, remove, setWidget, setWidget`

    - ### Methods inherited from class com.google.gwt.user.client.ui.Panel

      `add, adopt, adopt, clear, disown, doAttachChildren, doDetachChildren, orphan, remove`

    - ### Methods inherited from class com.google.gwt.user.client.ui.Widget

      `addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, ensureHandlers, fireEvent, getHandlerCount, getHandlerManager, getLayoutData, getParent, isAttached, isOrWasAttached, onBrowserEvent, onLoad, onUnload, removeFromParent, replaceElement, setLayoutData, setParent, sinkEvents`

    - ### Methods inherited from class com.google.gwt.user.client.ui.UIObject

      `addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, onEnsureDebugId, removeStyleDependentName, removeStyleName, resolvePotentialElement, setElement, setElement, setHeight, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkBitlessEvent, toString, unsinkEvents`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### ENCODING_MULTIPART

          public static final java.lang.String ENCODING_MULTIPART

      Used with `setEncoding(String)` to specify that the form will be submitted using MIME encoding (necessary for `FileUpload` to work properly).
      See Also:
        Constant Field Values

    - #### ENCODING_URLENCODED

          public static final java.lang.String ENCODING_URLENCODED

      Used with `setEncoding(String)` to specify that the form will be submitted using traditional URL encoding.
      See Also:
        Constant Field Values

    - #### METHOD_GET

          public static final java.lang.String METHOD_GET

      Used with `setMethod(String)` to specify that the form will be submitted using an HTTP GET request.
      See Also:
        Constant Field Values

    - #### METHOD_POST

          public static final java.lang.String METHOD_POST

      Used with `setMethod(String)` to specify that the form will be submitted using an HTTP POST request (necessary for `FileUpload` to work properly).
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### FormPanel

          public FormPanel()

      Creates a new FormPanel. When created using this constructor, it will be submitted to a hidden <iframe> element, and the results of the submission made available via `FormPanel.SubmitCompleteHandler`.

      The back-end server is expected to respond with a content-type of 'text/html', meaning that the text returned will be treated as HTML. If any other content-type is specified by the server, then the result HTML sent in the onFormSubmit event will be unpredictable across browsers, and the `onSubmitComplete` event may not fire at all.

      Tip:
        The initial implementation of FormPanel specified that the server respond with a content-type of 'text/plain'. This has been intentionally changed to specify 'text/html' because 'text/plain' cannot be made to work properly on all browsers.

    - #### FormPanel

          public FormPanel(NamedFrame frameTarget)

      Creates a FormPanel that targets a `NamedFrame`. The target frame is not physically attached to the form, and must therefore still be added to a panel elsewhere.

      When the FormPanel targets an external frame in this way, it will not fire the FormSubmitComplete event.

      Parameters:
        `frameTarget` - the `NamedFrame` to be targetted

    - #### FormPanel

          public FormPanel(java.lang.String target)

      Creates a new FormPanel. When created using this constructor, it will be submitted either by replacing the current page, or to the named <iframe>.

      When the FormPanel targets an external frame in this way, it will not fire the FormSubmitComplete event.

      Parameters:
        `target` - the name of the <iframe> to receive the results of the submission, or `null` to specify that the current page be replaced

    - #### FormPanel

          protected FormPanel(Element element)

      This constructor may be used by subclasses to explicitly use an existing element. This element must be a <form> element.

      The specified form element's target attribute will not be set, and the `FormSubmitCompleteEvent` will not be fired.

      Parameters:
        `element` - the element to be used

    - #### FormPanel

          protected FormPanel(Element element,
                   boolean createIFrame)

      This constructor may be used by subclasses to explicitly use an existing element. This element must be a <form> element.

      If the createIFrame parameter is set to `true`, then the wrapped form's target attribute will be set to a hidden iframe. If not, the form's target will be left alone, and the FormSubmitComplete event will not be fired.

      Parameters:
        `element` - the element to be used
        `createIFrame` - `true` to create an <iframe> element that will be targeted by this form

  - ### Method Detail

    - #### wrap

          public static FormPanel wrap(Element element)

      Creates a FormPanel that wraps an existing <form> element. This element must already be attached to the document. If the element is removed from the document, you must call `RootPanel.detachNow(Widget)`.

      The specified form element's target attribute will not be set, and the `FormSubmitCompleteEvent` will not be fired.

      Parameters:
        `element` - the element to be wrapped

    - #### wrap

          public static FormPanel wrap(Element element,
                       boolean createIFrame)

      Creates a FormPanel that wraps an existing <form> element. This element must already be attached to the document. If the element is removed from the document, you must call `RootPanel.detachNow(Widget)`.

      If the createIFrame parameter is set to `true`, then the wrapped form's target attribute will be set to a hidden iframe. If not, the form's target will be left alone, and the FormSubmitComplete event will not be fired.

      Parameters:
        `element` - the element to be wrapped
        `createIFrame` - `true` to create an <iframe> element that will be targeted by this form

    - #### addFormHandler

          @Deprecated
          public void addFormHandler(FormHandler handler)

      Deprecated. Use `addSubmitCompleteHandler(com.google.gwt.user.client.ui.FormPanel.SubmitCompleteHandler)` and `addSubmitHandler(com.google.gwt.user.client.ui.FormPanel.SubmitHandler)` instead
      Description copied from interface: `FiresFormEvents`
      Adds a handler interface to receive click events.
      Specified by:
        `addFormHandler` in interface `FiresFormEvents`
      Parameters:
        `handler` - the handler interface to add

    - #### addSubmitCompleteHandler

          public HandlerRegistration addSubmitCompleteHandler(FormPanel.SubmitCompleteHandler handler)

      Adds a `FormPanel.SubmitCompleteEvent` handler.
      Parameters:
        `handler` - the handler
      Returns:
        the handler registration used to remove the handler

    - #### addSubmitHandler

          public HandlerRegistration addSubmitHandler(FormPanel.SubmitHandler handler)

      Adds a `FormPanel.SubmitEvent` handler.
      Parameters:
        `handler` - the handler
      Returns:
        the handler registration used to remove the handler

    - #### getAction

          public java.lang.String getAction()

      Gets the 'action' associated with this form. This is the URL to which it will be submitted.
      Returns:
        the form's action

    - #### getEncoding

          public java.lang.String getEncoding()

      Gets the encoding used for submitting this form. This should be either `ENCODING_MULTIPART` or `ENCODING_URLENCODED`.
      Returns:
        the form's encoding

    - #### getMethod

          public java.lang.String getMethod()

      Gets the HTTP method used for submitting this form. This should be either `METHOD_GET` or `METHOD_POST`.
      Returns:
        the form's method

    - #### getTarget

          public java.lang.String getTarget()

      Gets the form's 'target'. This is the name of the `NamedFrame` that will receive the results of submission, or `null` if none has been specified.
      Returns:
        the form's target.

    - #### onFormSubmit

          public boolean onFormSubmit()

      Fired when a form is submitted.
      Specified by:
        `onFormSubmit` in interface `com.google.gwt.user.client.ui.impl.FormPanelImplHost`
      Returns:
        true if the form is submitted, false if canceled

    - #### onFrameLoad

          public void onFrameLoad()

      Description copied from interface: `com.google.gwt.user.client.ui.impl.FormPanelImplHost`
      Called when the target frame is done loading.
      Specified by:
        `onFrameLoad` in interface `com.google.gwt.user.client.ui.impl.FormPanelImplHost`

    - #### removeFormHandler

          @Deprecated
          public void removeFormHandler(FormHandler handler)

      Deprecated. Use the `HandlerRegistration.removeHandler()` method on the object returned by and add*Handler method instead
      Description copied from interface: `FiresFormEvents`
      Removes a previously added handler interface.
      Specified by:
        `removeFormHandler` in interface `FiresFormEvents`
      Parameters:
        `handler` - the handler interface to remove

    - #### reset

          public void reset()

      Resets the form, clearing all fields.

    - #### setAction

          public void setAction(java.lang.String url)

      Sets the 'action' associated with this form. This is the URL to which it will be submitted.
      Parameters:
        `url` - the form's action

    - #### setAction

          public void setAction(SafeUri url)

      Sets the 'action' associated with this form. This is the URL to which it will be submitted.
      Parameters:
        `url` - the form's action

    - #### setEncoding

          public void setEncoding(java.lang.String encodingType)

      Sets the encoding used for submitting this form. This should be either `ENCODING_MULTIPART` or `ENCODING_URLENCODED`.
      Parameters:
        `encodingType` - the form's encoding

    - #### setMethod

          public void setMethod(java.lang.String method)

      Sets the HTTP method used for submitting this form. This should be either `METHOD_GET` or `METHOD_POST`.
      Parameters:
        `method` - the form's method

    - #### submit

          public void submit()

      Submits the form.

      The FormPanel must not be detached (i.e. removed from its parent or otherwise disconnected from a `RootPanel`) until the submission is complete. Otherwise, notification of submission will fail.

    - #### onAttach

          protected void onAttach()

      Description copied from class: `Widget`

      This method is called when a widget is attached to the browser's document. To receive notification after a Widget has been added to the document, override the `Widget.onLoad()` method or use `Widget.addAttachHandler(com.google.gwt.event.logical.shared.AttachEvent.Handler)`.

      It is strongly recommended that you override `Widget.onLoad()` or `Widget.doAttachChildren()` instead of this method to avoid inconsistencies between logical and physical attachment states.

      Subclasses that override this method must call `super.onAttach()` to ensure that the Widget has been attached to its underlying Element.

      Overrides:
        `onAttach` in class `Widget`
      See Also:
        `Widget.onLoad()`, `Widget.doAttachChildren()`

    - #### onDetach

          protected void onDetach()

      Description copied from class: `Widget`

      This method is called when a widget is detached from the browser's document. To receive notification before a Widget is removed from the document, override the `Widget.onUnload()` method or use `Widget.addAttachHandler(com.google.gwt.event.logical.shared.AttachEvent.Handler)`.

      It is strongly recommended that you override `Widget.onUnload()` or `Widget.doDetachChildren()` instead of this method to avoid inconsistencies between logical and physical attachment states.

      Subclasses that override this method must call `super.onDetach()` to ensure that the Widget has been detached from the underlying Element. Failure to do so will result in application memory leaks due to circular references between DOM Elements and JavaScript objects.

      Overrides:
        `onDetach` in class `Widget`
      See Also:
        `Widget.onUnload()`, `Widget.doDetachChildren()`

    - #### getSynthesizedIFrame

          Element getSynthesizedIFrame()