com.google.gwt.user.client.ui

## Class FileUpload

- java.lang.Object
- - com.google.gwt.user.client.ui.UIObject
  - - com.google.gwt.user.client.ui.Widget
    - - com.google.gwt.user.client.ui.FocusWidget
      - - com.google.gwt.user.client.ui.FileUpload

- All Implemented Interfaces:
    HasAllDragAndDropHandlers, HasAllFocusHandlers, HasAllGestureHandlers, HasAllKeyHandlers, HasAllMouseHandlers, HasAllTouchHandlers, HasBlurHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasDragEndHandlers, HasDragEnterHandlers, HasDragHandlers, HasDragLeaveHandlers, HasDragOverHandlers, HasDragStartHandlers, HasDropHandlers, HasFocusHandlers, HasGestureChangeHandlers, HasGestureEndHandlers, HasGestureStartHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasMouseDownHandlers, HasMouseMoveHandlers, HasMouseOutHandlers, HasMouseOverHandlers, HasMouseUpHandlers, HasMouseWheelHandlers, HasTouchCancelHandlers, HasTouchEndHandlers, HasTouchMoveHandlers, HasTouchStartHandlers, HasAttachHandlers, HasHandlers, EventListener, Focusable, HasEnabled, HasFocus, HasName, HasVisibility, IsWidget, SourcesClickEvents, SourcesFocusEvents, SourcesKeyboardEvents, SourcesMouseEvents

      public class FileUpload
      extends FocusWidget
      implements HasName, HasChangeHandlers, HasEnabled

  A widget that wraps the HTML <input type='file'> element. This widget must be used with `FormPanel` if it is to be submitted to a server.

  ### 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);
  >       }
  >     }

  ### CSS Style Rules

  .gwt-FileUpload {}

  ### NOTICE about styling

  The developer should be aware that most browsers do not allow styling many properties of the rendered input-file element because of security restrictions.
  You can style certain properties like position, visibility, opacity, etc. But size, color, backgrounds etc. will not work either using css or calling widget methods like setSize().

- - ### Nested Class Summary

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

      `UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled`

  - ### Field Summary

    - ### 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
    --- | ---
    `` | `FileUpload()` Constructs a new file upload widget.
    `protected` | `FileUpload(Element element)` This constructor may be used by subclasses to explicitly use an existing element.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `HandlerRegistration` | `addChangeHandler(ChangeHandler handler)` Adds a `ChangeEvent` handler.
    `void` | `click()` Programmatic equivalent of the user clicking the button, opening the file selection browser.
    `java.lang.String` | `getFilename()` Gets the filename selected by the user.
    `java.lang.String` | `getName()` Gets the widget's name.
    `boolean` | `isEnabled()` Gets whether this widget is enabled.
    `void` | `setEnabled(boolean enabled)` Sets whether this widget is enabled.
    `void` | `setName(java.lang.String name)` Sets the widget's name.
    `static FileUpload` | `wrap(Element element)` Creates a FileUpload widget that wraps an existing <input type='file'> element.

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

      `addBlurHandler, addClickHandler, addClickListener, addDoubleClickHandler, addDragEndHandler, addDragEnterHandler, addDragHandler, addDragLeaveHandler, addDragOverHandler, addDragStartHandler, addDropHandler, addFocusHandler, addFocusListener, addGestureChangeHandler, addGestureEndHandler, addGestureStartHandler, addKeyboardListener, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addMouseDownHandler, addMouseListener, addMouseMoveHandler, addMouseOutHandler, addMouseOverHandler, addMouseUpHandler, addMouseWheelHandler, addMouseWheelListener, addTouchCancelHandler, addTouchEndHandler, addTouchMoveHandler, addTouchStartHandler, getFocusImpl, getTabIndex, onAttach, removeClickListener, removeFocusListener, removeKeyboardListener, removeMouseListener, removeMouseWheelListener, setAccessKey, setFocus, setTabIndex`

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

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

    - ### 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`

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

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

    - ### Methods inherited from interface com.google.gwt.event.shared.HasHandlers

      `fireEvent`

- - ### Constructor Detail

    - #### FileUpload

          public FileUpload()

      Constructs a new file upload widget.

    - #### FileUpload

          protected FileUpload(Element element)

      This constructor may be used by subclasses to explicitly use an existing element. This element must be an <input> element whose type is 'file'.
      Parameters:
        `element` - the element to be used

  - ### Method Detail

    - #### wrap

          public static FileUpload wrap(Element element)

      Creates a FileUpload widget that wraps an existing <input type='file'> element. This element must already be attached to the document. If the element is removed from the document, you must call `RootPanel.detachNow(Widget)`.
      Parameters:
        `element` - the element to be wrapped

    - #### addChangeHandler

          public HandlerRegistration addChangeHandler(ChangeHandler handler)

      Description copied from interface: `HasChangeHandlers`
      Adds a `ChangeEvent` handler.
      Specified by:
        `addChangeHandler` in interface `HasChangeHandlers`
      Parameters:
        `handler` - the change handler
      Returns:
        `HandlerRegistration` used to remove this handler

    - #### getFilename

          public java.lang.String getFilename()

      Gets the filename selected by the user. This property has no mutator, as browser security restrictions preclude setting it.
      Returns:
        the widget's filename

    - #### getName

          public java.lang.String getName()

      Description copied from interface: `HasName`
      Gets the widget's name.
      Specified by:
        `getName` in interface `HasName`
      Returns:
        the widget's name

    - #### isEnabled

          public boolean isEnabled()

      Gets whether this widget is enabled.
      Specified by:
        `isEnabled` in interface `HasEnabled`
      Overrides:
        `isEnabled` in class `FocusWidget`
      Returns:
        `true` if the widget is enabled

    - #### setEnabled

          public void setEnabled(boolean enabled)

      Sets whether this widget is enabled.
      Specified by:
        `setEnabled` in interface `HasEnabled`
      Overrides:
        `setEnabled` in class `FocusWidget`
      Parameters:
        `enabled` - `true` to enable the widget, `false` to disable it

    - #### setName

          public void setName(java.lang.String name)

      Description copied from interface: `HasName`
      Sets the widget's name.
      Specified by:
        `setName` in interface `HasName`
      Parameters:
        `name` - the widget's new name

    - #### click

          public void click()

      Programmatic equivalent of the user clicking the button, opening the file selection browser.

      NOTE: in certain browsers programmatic click is disabled if the element display is none, for instance in webkit you have to move the element off screen.