    001/*****************************************************************************
    002 * Copyright by The HDF Group.                                               *
    003 * Copyright by the Board of Trustees of the University of Illinois.         *
    004 * All rights reserved.                                                      *
    005 *                                                                           *
    006 * This file is part of the HDF Java Products distribution.                  *
    007 * The full copyright notice, including terms governing use, modification,   *
    008 * and redistribution, is contained in the COPYING file, which can be found  *
    009 * at the root of the source code distribution tree,                         *
    010 * or in https://www.hdfgroup.org/licenses.                                  *
    011 * If you do not have access to either file, you may request a copy from     *
    012 * help@hdfgroup.org.                                                        *
    013 ****************************************************************************/
    014
    015package hdf.view.TreeView;
    016
    017import java.util.List;
    018
    019import org.eclipse.swt.widgets.Tree;
    020import org.eclipse.swt.widgets.TreeItem;
    021
    022import hdf.object.FileFormat;
    023import hdf.object.Group;
    024import hdf.object.HObject;
    025import hdf.view.DataView.DataView;
    026import hdf.view.MetaDataView.MetaDataView;
    027
    028/**
    029 * TreeView defines APIs for opening a file and displaying the file structure in
    030 * a tree structure.
    031 *
    032 * TreeView uses folders and leaf nodes to represent groups and data objects in
    033 * the file. You can expand or collapse folders to navigate data objects in the
    034 * file.
    035 *
    036 * From the TreeView, you can open the data content or metadata of the selected
    037 * object. You can select object(s) to delete or add new objects to the file.
    038 *
    039 * @author Peter X. Cao
    040 * @version 2.4 9/6/2007
    041 */
    042public abstract interface TreeView {
    043    /**
    044     * Opens a file and retrieves the file structure of the file. It also can be
    045     * used to create a new file by setting the accessID to FileFormat.CREATE.
    046     *
    047     * Subclasses must implement this function to take appropriate steps to open
    048     * a file.
    049     *
    050     * @param filename
    051     *            the name of the file to open.
    052     * @param accessID
    053     *            identifier for the file access. Valid value of accessID is:
    054     *            <ul>
    055     *            <li>FileFormat.READ --- allow read-only access to file.</li>
    056     *            <li>FileFormat.WRITE --- allow read and write access to file.</li>
    057     *            <li>FileFormat.CREATE --- create a new file.</li>
    058     *            </ul>
    059     *
    060     * @return the FileFormat of this file if successful; otherwise returns
    061     *         null.
    062     *
    063     * @throws Exception if a failure occurred
    064     */
    065    public abstract FileFormat openFile(String filename, int accessID) throws Exception;
    066    /**
    067     * Reopens a file and retrieves the file structure of the file.
    068     *
    069     * Subclasses must implement this function to take appropriate steps to re-open
    070     * a file.
    071     *
    072     * @param theFile
    073     *            the file to re-open.
    074     * @param newFileAccessMode
    075     *            identifier for the new file access. Valid value of newFileAccessMode is:
    076     *            <ul>
    077     *            <li>FileFormat.READ --- allow read-only access to file.</li>
    078     *            <li>FileFormat.WRITE --- allow read and write access to file.</li>
    079     *            <li>FileFormat.CREATE --- create a new file.</li>
    080     *            </ul>
    081     *
    082     * @return the FileFormat of this file if successful; otherwise returns
    083     *         null.
    084     *
    085     * @throws Exception if a failure occurred
    086     */
    087    public abstract FileFormat reopenFile(FileFormat theFile, int newFileAccessMode) throws Exception;
    088
    089    /**
    090     * close a file
    091     *
    092     * @param file
    093     *            the file to close
    094     *
    095     * @throws Exception if a failure occurred
    096     */
    097    public abstract void closeFile(FileFormat file) throws Exception;
    098
    099    /**
    100     * save a file
    101     *
    102     * @param file
    103     *            the file to save
    104     *
    105     * @throws Exception if a failure occurred
    106     */
    107    public abstract void saveFile(FileFormat file) throws Exception;
    108
    109    /**
    110     * change the display option.
    111     *
    112     * @param displaymode
    113     *            the default displaymode
    114     */
    115    public abstract void setDefaultDisplayMode(boolean displaymode);
    116
    117    /**
    118     * Gets the selected the file. When multiple files are open, we need to know
    119     * which file is currently selected.
    120     *
    121     * @return the FileFormat of the selected file.
    122     */
    123    public abstract FileFormat getSelectedFile();
    124
    125    /**
    126     * @return the current selected object in the tree.
    127     */
    128    public abstract HObject getCurrentObject();
    129
    130    /**
    131     * Display the content of a data object.
    132     *
    133     * @param dataObject
    134     *            the data object
    135     *
    136     * @return the dataview that displays the data content
    137     *
    138     * @throws Exception if a failure occurred
    139     */
    140    public abstract DataView showDataContent(HObject dataObject)
    141            throws Exception;
    142
    143    /**
    144     * Adds an already created HObject to the tree under the
    145     * TreeItem containing the specified parent group.
    146     *
    147     * @param newObject
    148     *            the object to add.
    149     * @param parentGroup
    150     *            the parent group to add the object to.
    151     *
    152     * @return the TreeItem object
    153     */
    154    public abstract TreeItem addObject(HObject newObject, Group parentGroup);
    155
    156    /**
    157     * @return the Tree which holds the file structure.
    158     */
    159    public abstract Tree getTree();
    160
    161    /**
    162     * @return the list of currently open files.
    163     */
    164    public abstract List<FileFormat> getCurrentFiles();
    165
    166    /**
    167     * @param obj the object to find
    168     *
    169     * @return the tree item that contains the given data object.
    170     */
    171    public abstract TreeItem findTreeItem(HObject obj);
    172
    173}