Package eu.webtoolkit.jwt

Class WFileDropWidget

  • public class WFileDropWidget
extends WContainerWidget
    A widget that allows dropping files and directories for upload.

    This widget accepts files that are dropped into it. A signal is triggered whenever one or more files or directories are dropped. The filename, type and size of files is immediately available through the WFileDropWidget.File interface. Similarly, information about directories is available through the WFileDropWidget.Directory interface (which is a subclass of WFileDropWidget.File).

    The file upload is done sequentially. All files before the getCurrentIndex() have either finished, failed or have been cancelled.

    The widget has the default style-class 'Wt-filedropzone'. The style-class 'Wt-dropzone-hover' is added when files are hovered over the widget.

    Apart from dropping files, users can also use the browser-specific dialog to select files or directories. Note that the dialog will support either selecting files or directories, but not both at the same time. The dialog can be opened by clicking the widget. The type of dialog that is opened can be configured with setOnClickFilePicker(). The dialog can also be opened programmatically in response to another event (e.g. a user clicking a button outside this widget) using openFilePicker() and openDirectoryPicker().

    • Method Detail

      • getUploads

        public java.util.List<WFileDropWidget.File> getUploads()
        Returns the vector of uploads managed by this widget.

        The files in this vector are handled sequentially by the widget. All WFileDropWidget.File objects in this vector have either finished or failed if they are before the getCurrentIndex(), depending on the return value of isUploadFinished(). The other files are still being handled.

        Remark: Since version 4.7.0, this method returns a copy of the vector because we changed the internal vector to hold values of type std::unique_ptr.

        See Also:
        getCurrentIndex()

      • getCurrentIndex

        public int getCurrentIndex()
        Return the index of the file that is currently being handled.

        If nothing is to be done, this will return the size of the vector returned by getUploads().

      • cancelUpload

        public void cancelUpload​(WFileDropWidget.File file)
        Cancels the upload of a file.

        If you cancel a file that is still waiting to be uploaded, it will stay in the getUploads() vector, but it will be skipped.

      • remove

        public boolean remove​(WFileDropWidget.File file)
        Removes the file.

        This can be used to free resources of files that were already uploaded. A file can only be removed if its index in getUploads() is before the current index. A directory can be removed as soon as the drop() signal is emitted.

        Note: This method is only important if you intend to use this widget to upload a lot of files. Otherwise, simply removing the widget will also clean up all resources.

      • cleanDirectoryResources

        public void cleanDirectoryResources()
        Cleans up resources of WFileDropWidget.Directory objects.

        This can be used to free resources. The drop() signal returns raw pointers for objects that are managed by this widget. The WFileDropWidget.Directory objects are no longer needed after the drop() signal, so whenever you don't need them anymore, it is safe to call this method. Note that no WFileDropWidget.File objects are removed by this method since these objects can only be removed after their upload has completed.

        Note: This method is only important if you intend to use this widget to upload a lot of files. Otherwise, simply removing the widget will also clean up all resources.

        See Also:
        remove(WFileDropWidget.File file)

      • setAcceptDrops

        public void setAcceptDrops​(boolean enable)
        When set to false, the widget no longer accepts any files.

      • setHoverStyleClass

        public void setHoverStyleClass​(java.lang.String className)
        Deprecated.
        Override the css rule '.Wt-filedropzone.Wt-dropzone-hover' instead.
        Set the style class that is applied when a file is hovered over the widget.

      • setFilters

        public void setFilters​(java.lang.String acceptAttributes)
        Sets input accept attributes.

        The accept attribute may be specified to provide user agents with a hint of what file types will be accepted. Use html input accept attributes as input. This only affects the popup that is shown when users click on the widget. A user can still drop any file type.

      • setDropIndicationEnabled

        public void setDropIndicationEnabled​(boolean enable)
        Highlight widget if a file is dragged anywhere on the page.

        As soon as a drag enters anywhere on the page the styleclass 'Wt-dropzone-indication' is added to this widget. This can be useful to point the user to the correct place to drop the file. Once the user drags a file over the widget itself, the styleclass 'hover-style' is also added. This can be enabled for multiple dropwidgets if only one of them is visible at the same time.

        See Also:
        setGlobalDropEnabled(boolean enable)

      • setGlobalDropEnabled

        public void setGlobalDropEnabled​(boolean enable)
        Allow dropping the files anywhere on the page.

        If enabled, a drop anywhere on the page will be forwarded to this widget.

        See Also:
        setDropIndicationEnabled(boolean enable)

      • setJavaScriptFilter

        public void setJavaScriptFilter​(java.lang.String filterFn,
                                long chunksize,
                                java.util.List<java.lang.String> imports)
        Supply a function to process file data before it is uploaded to the server.

      • setAcceptDirectories

        public void setAcceptDirectories​(boolean enable,
                                 boolean recursive)
        Allow users to drop directories.

        Dropping a directory will emit the drop() signal with a WFileDropWidget.Directory object (which inherits WFileDropWidget.File). A directory can also be recognized by the isDirectory() method. After downcasting the object, the method getContents() can be used to iterate over the contents.

        Subdirectories are also included in the contents. The contents of subdirectories itself is only included if recursive is true.

        Only WFileDropWidget.File objects for which isDirectory() is false are uploaded to the server. The contents of a directory is 'flattened' into the getUploads() vector. The directory structure is still available through the getPath() method that describes the file's path relative to the dropped directory.

        See Also:
        openFilePicker(), openDirectoryPicker()

      • isAcceptDirectories

        public boolean isAcceptDirectories()
        Returns if directories are accepted.

        Dropping a directory will upload all of its contents. This can be done either non-recursively (default) or recursively. The directory structure is available during the initial drop() signal or through the getPath() method.

      • isAcceptDirectoriesRecursive

        public boolean isAcceptDirectoriesRecursive()
        Returns if directory contents is uploaded recursively or not.

      • getOnClickFilePicker

        public FilePickerType getOnClickFilePicker()
        Returns the type of file picker that is opened when a user clicks the widget.

      • openFilePicker

        public void openFilePicker()
        Programmatically open the file picker.

        Users can click the widget to open a browser-specific dialog to select either files or directories (see setOnClickFilePicker()). This method allows developers to also open the dialog by other means, e.g. buttons outside the widget to open either the file- or directory picker.

        See Also:
        openDirectoryPicker()

      • openDirectoryPicker

        public void openDirectoryPicker()
        Programmatically open the directory picker.

        Users can click the widget to open a browser-specific dialog to select either files or directories (see setOnClickFilePicker()). This method allows developers to also open the dialog by other means, e.g. buttons outside the widget to open either the file- or directory picker.

        Warning: Due to limitations in the directory picker api, empty directories will not be returned when selected through the dialog.

        See Also:
        openFilePicker()

      • newUpload

        public Signal1<WFileDropWidget.File> newUpload()
        The signal triggers when the upload of a file is about to begin.

        After this signal is triggered, the upload automatically starts. The upload can still fail if the file is too large or if there is a network error.

      • tooLarge

        public Signal2<WFileDropWidget.File,​java.lang.Long> tooLarge()
        The signal triggers when a file is too large for upload.

        This signal is triggered when the widget attempts to upload the file.

        The second argument is the size of the file in bytes.

      • uploadFailed

        public Signal1<WFileDropWidget.File> uploadFailed()
        The signal triggers when an upload failed.

        This signal will trigger when the widget skips over one of the files in the list for an unknown reason (e.g. happens when you drop a folder).

      • proceedToNextFile

        public void proceedToNextFile()
        Indicate that the next file can be handled.

        Internally indicate handling of the next file. Any resource handling the upload needs to call this when the file is handled.

      • enableAjax

        protected void enableAjax()
        Description copied from class: WWidget
        Progresses to an Ajax-enabled widget.

        This method is called when the progressive bootstrap method is used, and support for AJAX has been detected. The default behavior will upgrade the widget's event handling to use AJAX instead of full page reloads, and propagate the call to its children.

        You may want to reimplement this method if you want to make changes to widget when AJAX is enabled. You should always call the base implementation.

        Overrides:
        enableAjax in class WWebWidget
        See Also:
        WApplication.enableAjax()

      • getUploadResource

        protected WResource getUploadResource()
        Resource to upload data to.

        This returns a resource to upload data to. By default this returns a resource where the file contents can be POSTed. This can be overridden to allow for custom upload mechanisms.

        This can be used to implement upload protocols that are different from the normal upload flow. The request may include extra information in their payload, or be located on a public fixed URL and require custom handling of the request.

        On the client side, the JS function wtCustomSend(isValid, url, upload, APP) can implement a custom upload mechanism, with:

        • isValid: whether a valid file is uploaded
        • url: the upload location
        • upload: a file object with:
          • id: generated upload identifier
          • filename: upload file name
          • type: file type
          • size: file size

        To use this function, define the JS boolean wtUseCustomSend, which is false by default. Example: 

        
 Wt::WApplication::instance().setJavaScriptMember("wtUseCustomSend", "true");
 Wt::WApplication::instance().setJavaScriptMember("wtCustomSend",
 "function(isValid, url, upload) { * ... * };");

      • requestSend

        protected JSignal1<java.lang.Integer> requestSend()