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}