Package org.zkoss.zul

## Class Fileupload

- java.lang.Object
- - org.zkoss.zk.ui.AbstractComponent
  - - org.zkoss.zk.ui.HtmlBasedComponent
    - - org.zkoss.zul.impl.XulElement
      - - org.zkoss.zul.impl.LabelElement
        - - org.zkoss.zul.impl.LabelImageElement
          - - org.zkoss.zul.Button
            - - org.zkoss.zul.Fileupload

- All Implemented Interfaces:
    `java.io.Serializable`, `java.lang.Cloneable`, `Component`, `Disable`, `Scope`, `Uploadable`, `ComponentCtrl`
  Direct Known Subclasses:
    `Fileupload`

      public class Fileupload
      extends Button

  A fileupload dialog used to let user upload a file.

  There are two ways to use `Fileupload`:

  ### 1. Open as a modal dialog:

  You don't create `Fileupload` directly. Rather, use `get()` or `get(String, String)`.

  5.0.2: If the event thread is disabled, an onUpload event (`UploadEvent`) is posted to all root components when the upload dialog is closed. If you want the event being sent to a particular component, specify the component in the desktop's attribute called `org.zkoss.zul.Fileupload.target`. For example,

      desktop.setAttribute("org.zkoss.zul.Fileupload.target", mainWindow);
      Fileupload.get();

  ### 2. Embed as part of the page:

  You can create it as a component and then listen to the onUpload event (`UploadEvent`).

  See also ZK Component Reference: Fileupload.

  A non-XUL extension.

  Author:
    tomyeh
  See Also:
    `Filedownload`, Serialized Form

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.zkoss.zul.impl.LabelImageElement

      `LabelImageElement.ExtraCtrl`

    - ### Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent

      `AbstractComponent.Children, AbstractComponent.ForwardInfo, AbstractComponent.TargetInfo`

    - ### Nested classes/interfaces inherited from interface org.zkoss.zk.ui.ext.Uploadable

      `Uploadable.Error`

  - ### Field Summary

    - ### Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent

      `_zclass`

    - ### Fields inherited from interface org.zkoss.zk.ui.Component

      `APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE`

    - ### Fields inherited from interface org.zkoss.zk.ui.sys.ComponentCtrl

      `AFTER_CHILD_ADDED, AFTER_CHILD_REMOVED, AFTER_CLONED, AFTER_PAGE_ATTACHED, AFTER_PAGE_DETACHED, AFTER_PARENT_CHANGED, CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Fileupload()` |
    `Fileupload​(java.lang.String label)` |
    `Fileupload​(java.lang.String label, java.lang.String image)` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static Media` | `get()` | Opens a modal dialog with the default message and title, and let user upload a file.
    `static Media` | `get​(boolean alwaysNative)` | Opens a modal dialog with the default message and title, and let user upload a file.
    `static Media[]` | `get​(int max)` | Opens a modal dialog to upload multiple files with the default message and title.
    `static Media[]` | `get​(int max, boolean alwaysNative)` | Opens a modal dialog to upload multiple files with the default message and title.
    `static Media[]` | `get​(int max, EventListener<UploadEvent> listener)` | Opens a modal dialog to upload multiple files with the default message and title.
    `static Media` | `get​(java.lang.String message, java.lang.String title)` | Opens a modal dialog with the specified message and title, and let user upload a file.
    `static Media` | `get​(java.lang.String message, java.lang.String title, boolean alwaysNative)` | Opens a modal dialog with the specified message and title, and let user upload a file.
    `static Media[]` | `get​(java.lang.String message, java.lang.String title, int max)` | Opens a modal dialog to upload multiple files with the specified message and title.
    `static Media[]` | `get​(java.lang.String message, java.lang.String title, int max, boolean alwaysNative)` | Opens a modal dialog to upload multiple files with the specified message, title and options.
    `static Media[]` | `get​(java.lang.String message, java.lang.String title, int max, int maxsize, boolean alwaysNative)` | Opens a modal dialog to upload multiple files with the specified message, title and options.
    `protected static Media[]` | `get​(java.util.Map<java.lang.String,​java.lang.Object> params, java.lang.String message, java.lang.String title, int max, int maxsize, boolean alwaysNative)` | The implementation of all public get methods.
    `static Media[]` | `get​(java.util.Map<java.lang.String,​java.lang.Object> params, java.lang.String message, java.lang.String title, int max, int maxsize, boolean alwaysNative, EventListener<UploadEvent> listener)` | Opens a modal dialog to upload multiple files with the specified message, title and options.
    `static Media[]` | `get​(java.util.Map<java.lang.String,​java.lang.Object> params, java.lang.String message, java.lang.String title, java.lang.String accept, int max, int maxsize, boolean alwaysNative, EventListener<UploadEvent> listener)` | Opens a modal dialog to upload multiple files with the specified message, title and options.
    `static Media[]` | `get​(EventListener<UploadEvent> listener)` | Opens a modal dialog to upload multiple files with the default message and title.
    `static java.lang.String` | `getTemplate()` | Returns the template used to create the upload modal dialog.
    `static void` | `setTemplate​(java.lang.String uri)` | Sets the template used to create the upload modal dialog.

    - ### Methods inherited from class org.zkoss.zul.Button

      `clone, getAutodisable, getDir, getHref, getOrient, getTarget, getType, getUpload, getZclass, isChildable, isDisabled, renderCrawlable, renderProperties, service, setAutodisable, setDir, setDisabled, setHref, setOrient, setTarget, setType, setUpload, updateByClient`

    - ### Methods inherited from class org.zkoss.zul.impl.LabelImageElement

      `getExtraCtrl, getHoverImage, getHoverImageContent, getIconSclass, getIconSclasses, getIconTooltip, getIconTooltips, getImage, getImageContent, getPropertyAccess, isImageAssigned, setHoverImage, setHoverImageContent, setHoverImageContent, setIconSclass, setIconSclasses, setIconTooltip, setIconTooltips, setImage, setImageContent, setImageContent`

    - ### Methods inherited from class org.zkoss.zul.impl.LabelElement

      `getLabel, setLabel`

    - ### Methods inherited from class org.zkoss.zul.impl.XulElement

      `getContext, getCtrlKeys, getPopup, getTooltip, setContext, setContext, setContextAttributes, setCtrlKeys, setPopup, setPopup, setPopupAttributes, setTooltip, setTooltip, setTooltipAttributes`

    - ### Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent

      `addSclass, evalCSSFlex, focus, getAction, getClientAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTabindex, getTabindexInteger, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, removeSclass, removeSclass, setAction, setClass, setClientAction, setDraggable, setDroppable, setFocus, setHeight, setHeight0, setHeightDirectly, setHflex, setHflex0, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTabindex, setTabindex, setTooltiptext, setTop, setTopDirectly, setVflex, setVflex0, setVflexDirectly, setWidth, setWidth0, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly`

    - ### Methods inherited from class org.zkoss.zk.ui.AbstractComponent

      `addAnnotation, addCallback, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildAdded, beforeChildRemoved, beforeParentChanged, destroyIndexCacheMap, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, disableHostChanged, enableBindingAnnotation, enableHostChanged, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getCallback, getChildren, getClientAttribute, getClientDataAttribute, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getForwards, getId, getIndexCacheMap, getLastChild, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRedrawCallback, getRoot, getShadowFellowIfAny, getShadowRoots, getShadowVariable, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, initIndexCacheMap, insertBefore, invalidate, isDisabledHostChanged, isInitialized, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageAttached, onPageDetached, onParentChanged, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeCallback, removeChild, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, renderPropertiesOnly, replace, response, response, response, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setClientDataAttribute, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setParent, setStubonly, setStubonly, setSubBindingAnnotationCount, setTemplate, setVisible, setVisibleDirectly, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateSubBindingAnnotationCount, willPassivate, willPassivate, willSerialize, willSerialize`

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

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

- - ### Constructor Detail

    - #### Fileupload

          public Fileupload()

    - #### Fileupload

          public Fileupload​(java.lang.String label)

    - #### Fileupload

          public Fileupload​(java.lang.String label,
                            java.lang.String image)

  - ### Method Detail

    - #### get

          public static Media get()

      Opens a modal dialog with the default message and title, and let user upload a file.
      Returns:
        null if the uploaded content, or null if not uploaded. Notice, by default, the event thread is disabled, and this method won't suspend and always returns null. To retrieve the uploaded content, the developer has to listen the onUpload event. For more information, refer to ZK Component Reference: Fileupload.

    - #### get

          public static Media get​(boolean alwaysNative)

      Opens a modal dialog with the default message and title, and let user upload a file.
      Parameters:
        `alwaysNative` - whether to treat the uploaded file as binary stream, regardless its content type. If false (the default), it will convert to `Image`, `Audio`, binary stream, or text files depending on the content type.
      Returns:
        null if the uploaded content, or null if not uploaded. Notice, by default, the event thread is disabled, and this method won't suspend and always returns null. To retrieve the uploaded content, the developer has to listen the onUpload event. For more information, refer to ZK Component Reference: Fileupload.
      Since:
        3.0.0
      See Also:
        `Configuration.getUploadCharset()`, `Configuration.getUploadCharsetFinder()`

    - #### get

          public static Media get​(java.lang.String message,
                                  java.lang.String title)

      Opens a modal dialog with the specified message and title, and let user upload a file.
      Parameters:
        `message` - the message. If null, the default is used.
        `title` - the title. If null, the default is used.
      Returns:
        null if the uploaded content, or null if not uploaded. Notice, by default, the event thread is disabled, and this method won't suspend and always returns null. To retrieve the uploaded content, the developer has to listen the onUpload event. For more information, refer to ZK Component Reference: Fileupload.

    - #### get

          public static Media get​(java.lang.String message,
                                  java.lang.String title,
                                  boolean alwaysNative)

      Opens a modal dialog with the specified message and title, and let user upload a file.
      Parameters:
        `message` - the message. If null, the default is used.
        `title` - the title. If null, the default is used.
        `alwaysNative` - whether to treat the uploaded file as binary stream, regardless its content type. If false (the default), it will convert to `Image`, `Audio`, binary stream, or text files depending on the content type.
      Returns:
        null if the uploaded content, or null if not uploaded. Notice, by default, the event thread is disabled, and this method won't suspend and always returns null. To retrieve the uploaded content, the developer has to listen the onUpload event. For more information, refer to ZK Component Reference: Fileupload.
      Since:
        3.0.0
      See Also:
        `Configuration.getUploadCharset()`, `Configuration.getUploadCharsetFinder()`

    - #### get

          public static Media[] get​(EventListener<UploadEvent> listener)

      Opens a modal dialog to upload multiple files with the default message and title.
      Parameters:
        `listener` - The callback event listener when the event thread is disabled, the listener will be invoked, if it is not null. Note: the target of the listener is always null.
      Returns:
        null if the uploaded content, or null if not uploaded. Notice, by default, the event thread is disabled, and this method won't suspend and always returns null. Set the listener parameter to retrieve the upload content when the upload has finished. . For more information, refer to ZK Component Reference: Fileupload.

    - #### get

          public static Media[] get​(int max,
                                    EventListener<UploadEvent> listener)

      Opens a modal dialog to upload multiple files with the default message and title.
      Parameters:
        `max` - the maximal allowed number that an user can upload at once. If non-positive, 1 is assumed.
        `listener` - The callback event listener when the event thread is disabled, the listener will be invoked, if it is not null. Note: the target of the listener is always null.
      Returns:
        null if the uploaded content, or null if not uploaded. Notice, by default, the event thread is disabled, and this method won't suspend and always returns null. Set the listener parameter to retrieve the upload content when the upload has finished. . For more information, refer to

    - #### get

          public static Media[] get​(int max)

      Opens a modal dialog to upload multiple files with the default message and title.
      Parameters:
        `max` - the maximal allowed number that an user can upload at once. If non-positive, 1 is assumed.
      Returns:
        null if the uploaded content, or null if not uploaded. Notice, by default, the event thread is disabled, and this method won't suspend and always returns null. To retrieve the uploaded content, the developer has to listen the onUpload event. For more information, refer to ZK Component Reference: Fileupload.

    - #### get

          public static Media[] get​(int max,
                                    boolean alwaysNative)

      Opens a modal dialog to upload multiple files with the default message and title.
      Parameters:
        `max` - the maximal allowed number that an user can upload at once. If non-positive, 1 is assumed.
        `alwaysNative` - whether to treat the uploaded files as binary stream, regardless its content type. If false (the default), it will convert to `Image`, `Audio`, binary stream, or text files depending on the content type.
      Returns:
        null if the uploaded content, or null if not uploaded. Notice, by default, the event thread is disabled, and this method won't suspend and always returns null. To retrieve the uploaded content, the developer has to listen the onUpload event. For more information, refer to ZK Component Reference: Fileupload.
      Since:
        3.0.0
      See Also:
        `Configuration.getUploadCharset()`, `Configuration.getUploadCharsetFinder()`

    - #### get

          public static Media[] get​(java.lang.String message,
                                    java.lang.String title,
                                    int max)

      Opens a modal dialog to upload multiple files with the specified message and title.

      The returned format depending on the content type.

      Parameters:
        `max` - the maximal allowed number that an user can upload at once. If non-positive, 1 is assumed. If max is larger than 1000, 1000 is assumed.
      Returns:
        null if the uploaded content, or null if not uploaded. Notice, by default, the event thread is disabled, and this method won't suspend and always returns null. To retrieve the uploaded content, the developer has to listen the onUpload event. For more information, refer to ZK Component Reference: Fileupload.

    - #### get

          public static Media[] get​(java.lang.String message,
                                    java.lang.String title,
                                    int max,
                                    boolean alwaysNative)

      Opens a modal dialog to upload multiple files with the specified message, title and options.
      Parameters:
        `max` - the maximal allowed number that an user can upload at once. If non-positive, 1 is assumed. If max is larger than 1000, 1000 is assumed.
        `alwaysNative` - whether to treat the uploaded files as binary stream, regardless its content type. If false (the default), it will convert to `Image`, `Audio`, binary stream, or text files depending on the content type.
      Returns:
        null if the uploaded content, or null if not uploaded. Notice, by default, the event thread is disabled, and this method won't suspend and always returns null. To retrieve the uploaded content, the developer has to listen the onUpload event. For more information, refer to ZK Component Reference: Fileupload.
      Since:
        3.0.0

    - #### get

          public static Media[] get​(java.lang.String message,
                                    java.lang.String title,
                                    int max,
                                    int maxsize,
                                    boolean alwaysNative)

      Opens a modal dialog to upload multiple files with the specified message, title and options.
      Parameters:
        `max` - the maximal allowed number that an user can upload at once. If non-positive, 1 is assumed. If max is larger than 1000, 1000 is assumed.
        `maxsize` - the maximal upload size of the component.
        `alwaysNative` - whether to treat the uploaded files as binary stream, regardless its content type. If false (the default), it will convert to `Image`, `Audio`, binary stream, or text files depending on the content type.
      Returns:
        null if the uploaded content, or null if not uploaded. Notice, by default, the event thread is disabled, and this method won't suspend and always returns null. To retrieve the uploaded content, the developer has to listen the onUpload event. For more information, refer to ZK Component Reference: Fileupload.
      Since:
        3.6.0

    - #### get

          public static Media[] get​(java.util.Map<java.lang.String,​java.lang.Object> params,
                                    java.lang.String message,
                                    java.lang.String title,
                                    int max,
                                    int maxsize,
                                    boolean alwaysNative,
                                    EventListener<UploadEvent> listener)

      Opens a modal dialog to upload multiple files with the specified message, title and options.
      Parameters:
        `max` - the maximal allowed number that an user can upload at once. If non-positive, 1 is assumed. If max is larger than 1000, 1000 is assumed.
        `maxsize` - the maximal upload size of the component.
        `alwaysNative` - whether to treat the uploaded files as binary stream, regardless its content type. If false (the default), it will convert to `Image`, `Audio`, binary stream, or text files depending on the content type.
        `listener` - The callback event listener when the event thread is disabled, the listener will be invoked, if it is not null. Note: the target of the listener is always null.
      Returns:
        null if the uploaded content, or null if not uploaded. Notice, by default, the event thread is disabled, and this method won't suspend and always returns null. To retrieve the uploaded content, the developer has to listen the onUpload event or set the listener parameter to retrieve the upload content when the upload has finished. . For more information, refer to ZK Component Reference: Fileupload.
      Since:
        6.5.3

    - #### get

          public static Media[] get​(java.util.Map<java.lang.String,​java.lang.Object> params,
                                    java.lang.String message,
                                    java.lang.String title,
                                    java.lang.String accept,
                                    int max,
                                    int maxsize,
                                    boolean alwaysNative,
                                    EventListener<UploadEvent> listener)

      Opens a modal dialog to upload multiple files with the specified message, title and options.
      Parameters:
        `accept` - specifies the types of files that the server accepts, the setting only works with HTML5 supported browsers
        `max` - the maximal allowed number that an user can upload at once. If non-positive, 1 is assumed. If max is larger than 1000, 1000 is assumed.
        `maxsize` - the maximal upload size of the component.
        `alwaysNative` - whether to treat the uploaded files as binary stream, regardless its content type. If false (the default), it will convert to `Image`, `Audio`, binary stream, or text files depending on the content type.
        `listener` - The callback event listener when the event thread is disabled, the listener will be invoked, if it is not null. Note: the target of the listener is always null.
      Returns:
        null if the uploaded content, or null if not uploaded. Notice, by default, the event thread is disabled, and this method won't suspend and always returns null. To retrieve the uploaded content, the developer has to listen the onUpload event or set the listener parameter to retrieve the upload content when the upload has finished. . For more information, refer to ZK Component Reference: Fileupload.
      Since:
        7.0.2

    - #### get

          protected static Media[] get​(java.util.Map<java.lang.String,​java.lang.Object> params,
                                       java.lang.String message,
                                       java.lang.String title,
                                       int max,
                                       int maxsize,
                                       boolean alwaysNative)

      The implementation of all public get methods. In other words, all public `get` methods will prepare an empty map and invoke this method to retrieve the media. It is designed to allow applications to customize the creation of the dialog, such as adding more parameters.
      Since:
        5.0.11

    - #### setTemplate

          public static void setTemplate​(java.lang.String uri)

      Sets the template used to create the upload modal dialog.

      The template must follow the default template: ~./zul/html/fileuploaddlg.zul

      In other words, just adjust the label and layout and don't change the component's ID.

      Note: the template has no effect, if you use `Fileupload` as a component (and embed it to a page).

    - #### getTemplate

          public static java.lang.String getTemplate()

      Returns the template used to create the upload modal dialog.