FilePanel

//
// $Id: FilePanel.java 1721 2015-03-29 17:48:44Z etienne_sf $
//
// jupload - A file upload applet.
// Copyright 2007 The JUpload Team
//
// Created: ?
// Creator: William JinHua Kwong
// Last modified: $Date: 2015-03-29 19:48:44 +0200 (dim., 29 mars 2015) $
//
// This program is free software; you can redistribute it and/or modify it under
// the terms of the GNU General Public License as published by the Free Software
// Foundation; either version 2 of the License, or (at your option) any later
// version. This program is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
// details. You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software Foundation, Inc.,
// 675 Mass Ave, Cambridge, MA 02139, USA.
package wjhk.jupload2.gui.filepanel;

import java.awt.Color;
import java.awt.Component;
import java.awt.Font;
import java.awt.Point;
import java.io.File;
import java.util.List;

import javax.swing.ActionMap;
import javax.swing.JComponent;
import javax.swing.TransferHandler;

import wjhk.jupload2.filedata.DefaultFileData;
import wjhk.jupload2.filedata.FileData;
import wjhk.jupload2.gui.JUploadPanel;
import wjhk.jupload2.upload.UploadFilePacket;

/**
 * Defines the interface used in the applet, when dealing with the file panel.
 */
public interface FilePanel {

    /** This enumeration lists the available display modes, for the file list. */
    static public enum FileListViewMode {
        /** The flat view is the 'historical' one. It displays a table containing all files to upload */
        FLAT,
        /**
         * The map to File System mode, is when the hierarchy is a part of the local file system. The root of the
         * hierarchy (visible root) is the common root to to all files and folder. It is actually a <B>hierarchical view
         * of the FLAT view</B>, using the same data structure. Only the display changes.<BR/>
         * For instance, if /tmp/f1/f2/file.txt and /tmp/f1/f11/file.txt have been added, /tmp/f1 is the common root. So
         * this mode displays: f2 and f11 as the first visible hierarchy level. f2 contains file.txt, and f11 also
         * contains a file.txt file.
         *
         * @see DefaultFileData#getRoot(java.util.List)
         */
        TREE_VIEW,
        /**
         * In independent tree view mode, each added file/folder is added to the root. This root is the root that will
         * be sent to the server, during the upload.<BR/>
         * For instance, if /tmp/f1/f2/file.txt and /tmp/f1/f11/file.txt have been both added, then, two file.txt
         * (coming from different folders, so they are actually different files with the same name) are attached to the
         * hierarchical view.<BR/>
         * If if /tmp/f1 is added, then: f1 is attached to the root. And the hierarchy will contain: f1, f2 as a
         * subfolder of f1, file.txt as a file in f2.
         */
        INDEPENDENT_TREE_VIEW
    };

    /**
     * Set the view mode, for the file list.
     *
     * @return The current view mode.
     * @see #fileListViewMode
     */
    public FileListViewMode getFileListMode();

    /**
     * Set the view mode, for the file list.
     *
     * @param fileListViewMode The view mode to set.
     * @see #fileListViewMode
     */
    public void setFileListViewMode(FileListViewMode fileListViewMode);

    /**
     * Add multiple files to this panel.
     *
     * @param f An array of files to add.
     */
    public void addFiles(File[] f);

    /**
     * Retrieve all currently stored files.
     *
     * @return an array of files, currently managed by this instance.
     */
    public List<FileData> getFiles();

    /**
     * Retrieve the number of file entries in the JTable.
     *
     * @return the current number of files, held by this instance.
     */
    public int getFilesLength();

    /**
     * Removes all currently selected file entries.
     */
    public void removeSelected();

    /**
     * Removes all file entries.
     */
    public void removeAll();

    /**
     * Remove an array of files, typically an {@link UploadFilePacket}.
     *
     * @param fileData The files to remove.
     */
    public void remove(FileData[] files);

    /**
     * Remove a specified file entry.
     *
     * @param fileData The file to be removed.
     */
    public void remove(FileData fileData);

    /**
     * Clears the current selection of the JTable.
     */
    public void clearSelection();

    /**
     * Requests focus for the JTable.
     */
    public void focusTable();

    /**
     * Ask for the file contained below the specific point on the screen.
     *
     * @param point The point
     * @return The return instance of File.
     */
    public FileData getFileDataAt(Point point);

    /**
     * Return the component on which drop event can occur. Used by {@link JUploadPanel}, when initializing the
     * DropTarget.
     *
     * @return The drop component target
     */
    public Component getDropComponent();

    /**
     * Transfer handler, to manage copy/paste operations.
     *
     * @param newHandler
     * @see JComponent#setTransferHandler(TransferHandler)
     */
    public void setTransferHandler(TransferHandler newHandler);

    /**
     * Allows to get standard action map, like paste action.
     *
     * @return Get the current actionMap
     * @see JComponent#getActionMap()
     */
    public ActionMap getActionMap();

    /**
     * Set color of files list grid border.
     *
     * @param color awt Color
     */
    public void setGridBorderColor(Color color);

    /**
     * Set back color of table header
     *
     * @param color awt Color
     */
    public void setTableHeaderBackColor(Color color);

    /**
     * Set text color of table header
     *
     * @param color awt Color
     */
    public void setTableHeaderTextColor(Color color);

    /**
     * Set table header text font
     *
     * @param color awt Color
     */
    public void setTableHeaderFont(Font font);

    /**
     * Removes all files, which have the uploadFlag set to false.
     *
     * @see FileData#getUploadFlag()
     */
    public void removeFileNotToUpload();

    /** Removes empty folders in the TreeView hierarchy. This methods also calls the {@link #reload()} method */
    public void cleanHierarchy();

    /** Force the reloading of the file structure, and the refreshing of the display */
    public void reload();
}