    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 files COPYING and Copyright.html. *
    009 * COPYING can be found at the root of the source code distribution tree.    *
    010 * Or, see https://support.hdfgroup.org/products/licenses.html               *
    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 *
    030 * <p>
    031 * TreeView defines APIs for opening a file and displaying the file structure in
    032 * a tree structure.
    033 * </p>
    034 *
    035 * <p>
    036 * TreeView uses folders and leaf nodes to represent groups and data objects in
    037 * the file. You can expand or collapse folders to navigate data objects in the
    038 * file.
    039 * </p>
    040 *
    041 * <p>
    042 * From the TreeView, you can open the data content or metadata of the selected
    043 * object. You can select object(s) to delete or add new objects to the file.
    044 * </p>
    045 *
    046 * @author Peter X. Cao
    047 * @version 2.4 9/6/2007
    048 */
    049public abstract interface TreeView {
    050    /**
    051     * Opens a file and retrieves the file structure of the file. It also can be
    052     * used to create a new file by setting the accessID to FileFormat.CREATE.
    053     *
    054     * <p>
    055     * Subclasses must implement this function to take appropriate steps to open
    056     * a file.
    057     * </p>
    058     *
    059     * @param filename
    060     *            the name of the file to open.
    061     * @param accessID
    062     *            identifier for the file access. Valid value of accessID is:
    063     *            <ul>
    064     *            <li>FileFormat.READ --- allow read-only access to file.</li>
    065     *            <li>FileFormat.WRITE --- allow read and write access to file.</li>
    066     *            <li>FileFormat.CREATE --- create a new file.</li>
    067     *            </ul>
    068     *
    069     * @return the FileFormat of this file if successful; otherwise returns
    070     *         null.
    071     *
    072     * @throws Exception if a failure occurred
    073     */
    074    public abstract FileFormat openFile(String filename, int accessID) throws Exception;
    075    public abstract FileFormat reopenFile(FileFormat theFile, int newFileAccessMode) throws Exception;
    076
    077    /**
    078     * close a file
    079     *
    080     * @param file
    081     *            the file to close
    082     *
    083     * @throws Exception if a failure occurred
    084     */
    085    public abstract void closeFile(FileFormat file) throws Exception;
    086
    087    /**
    088     * save a file
    089     *
    090     * @param file
    091     *            the file to save
    092     *
    093     * @throws Exception if a failure occurred
    094     */
    095    public abstract void saveFile(FileFormat file) throws Exception;
    096
    097    /**
    098     * change the display option.
    099     *
    100     * @param displaymode
    101     *            the default displaymode
    102     */
    103    public abstract void setDefaultDisplayMode(boolean displaymode);
    104
    105    /**
    106     * Gets the selected the file. When multiple files are open, we need to know
    107     * which file is currently selected.
    108     *
    109     * @return the FileFormat of the selected file.
    110     */
    111    public abstract FileFormat getSelectedFile();
    112
    113    /**
    114     * @return the current selected object in the tree.
    115     */
    116    public abstract HObject getCurrentObject();
    117
    118    /**
    119     * Display the content of a data object.
    120     *
    121     * @param dataObject
    122     *            the data object
    123     *
    124     * @return the dataview that displays the data content
    125     *
    126     * @throws Exception if a failure occurred
    127     */
    128    public abstract DataView showDataContent(HObject dataObject)
    129            throws Exception;
    130
    131    /**
    132     * Displays the meta data of a data object.
    133     *
    134     * @param dataObject
    135     *            the data object
    136     *
    137     * @return the MetaDataView that displays the MetaData of the data object
    138     *
    139     * @throws Exception if a failure occurred
    140     */
    141    public abstract MetaDataView showMetaData(HObject dataObject)
    142            throws Exception;
    143
    144    /**
    145     * Adds an already created HObject to the tree under the
    146     * TreeItem containing the specified parent group.
    147     *
    148     * @param newObject
    149     *            the object to add.
    150     * @param parentGroup
    151     *            the parent group to add the object to.
    152     *
    153     * @return the TreeItem object
    154     */
    155    public abstract TreeItem addObject(HObject newObject, Group parentGroup);
    156
    157    /**
    158     * @return the Tree which holds the file structure.
    159     */
    160    public abstract Tree getTree();
    161
    162    /**
    163     * @return the list of currently open files.
    164     */
    165    public abstract List<FileFormat> getCurrentFiles();
    166
    167    /**
    168     * @param obj the object to find
    169     *
    170     * @return the tree item that contains the given data object.
    171     */
    172    public abstract TreeItem findTreeItem(HObject obj);
    173
    174}