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 * 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}