001/**
002 * GeomSSApp -- The public interface for the the GeomSS application.
003 *
004 * Copyright (C) 2009-2015, by Joseph A. Huwaldt. All rights reserved.
005 *
006 * This library is free software; you can redistribute it and/or modify it under the terms
007 * of the GNU Lesser General Public License as published by the Free Software Foundation;
008 * either version 2.1 of the License, or (at your option) any later version.
009 *
010 * This library is distributed in the hope that it will be useful, but WITHOUT ANY
011 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
012 * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
013 *
014 * You should have received a copy of the GNU Lesser General Public License along with
015 * this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place -
016 * Suite 330, Boston, MA 02111-1307, USA. Or visit: http://www.gnu.org/licenses/lgpl.html
017 */
018package geomss;
019
020import geomss.geom.*;
021import geomss.geom.reader.GeomReader;
022import jahuwaldt.swing.Preferences;
023import java.awt.Frame;
024import java.awt.Window;
025import java.io.File;
026import java.util.List;
027import java.util.ResourceBundle;
028
029/**
030 * The public interface for the GeomSS application that is intended to be accessed from
031 * the BeanShell scripting environment.
032 * 
033 * <p> Modified by: Joseph A. Huwaldt </p>
034 * 
035 * @author Joseph A. Huwaldt, Date: May 3, 2009
036 * @version September 13, 2015
037 */
038public interface GeomSSApp {
039
040    /**
041     * @return a reference to the 3D scene.
042     */
043    public GeomSSScene getScene();
044
045    /**
046     * @return the parent Frame for this application.
047     */
048    public Frame getParentFrame();
049
050    /**
051     * @return a reference to the preferences for the GeomSS application.
052     */
053    public Preferences getPreferences();
054
055    /**
056     * @return the resource bundle for this application containing the localized
057     *         application Strings for the main application.
058     */
059    public ResourceBundle getResourceBundle();
060
061    /**
062     * Add the supplied window to the Windows menu of the main application. The window
063     * should be made visible before calling this method to avoid an inconsistent user
064     * interface state (a window listed in the "Windows" menu, but not visible). The
065     * window will be removed from the "Windows" menu when it's "dispose" method is
066     * called.
067     *
068     * @param window The window to be added to the Windows menu.
069     */
070    public void addToWindowsMenu(Window window);
071
072    /**
073     * Quit or exit the application after properly saving preferences, etc.
074     */
075    public void quit();
076
077    /**
078     * Read in a geometry file and return a GeometryList instance. All exceptions are
079     * handled by this method.
080     *
081     * @param theFile The file to be read in. If <code>null</code> is passed, this method
082     *                will do nothing.
083     * @return A GeometryList object containing the geometry read in from the file or
084     *         <code>null</code> if the user cancels the read at any point or if an
085     *         exception of any kind is thrown.
086     */
087    public GeometryList readGeomFile(File theFile);
088
089    /**
090     * Write out geometry to the specified file using the specified GeometryList instance
091     * (some GeomReader classes have specific requirements for the contents of this list).
092     * All exceptions are handled by this method.
093     *
094     * @param geometry The geometry object to be written out.
095     * @param theFile  The file to be written to.
096     * @param writer   The GeomReader to use to write out the file.
097     */
098    public void writeGeomFile(GeometryList geometry, File theFile, GeomReader writer);
099
100    /**
101     * @return a list of all known GeomReader objects that are capable of writing to a
102     *         file.
103     */
104    public List<GeomReader> getAllGeomWriters();
105
106    /**
107     * Save the entire global workspace to an XGSS file. All defined geometry and
108     * non-geometry variables in the global workspace will be saved to the specified file.
109     *
110     * @param theFile The file to write the workspace to in XGSS format.
111     */
112    public void saveWorkspace(File theFile);
113
114    /**
115     * Load the specified XGSS file into the current global workspace. All the geometry
116     * and non-geometry variables in the specified XGSS file will be loaded into the
117     * current global workspace. Any existing variables with the same names will be
118     * silently overwritten.
119     *
120     * @param theFile The XGSS file to load into the current workspace.
121     */
122    public void loadWorkspace(File theFile);
123
124    /**
125     * Save a copy of the current 3D view as a PNG file. The user will be asked to supply
126     * a file name for the image file.
127     */
128    public void saveAsPNG();
129
130    /**
131     * Save a copy of the current 3D view as a PNG file.
132     *
133     * @param file The file to be saved.
134     */
135    public void saveAsPNG(File file);
136
137    /**
138     * Save a copy of the current 3D view as a JPEG file. The user will be asked to supply
139     * a file name for the image file.
140     */
141    public void saveAsJPEG();
142
143    /**
144     * Save a copy of the current 3D view as a JPEG file.
145     *
146     * @param file The file to be saved.
147     */
148    public void saveAsJPEG(File file);
149
150    /**
151     * Print the current 3D view. The user will be asked to supply information on the
152     * print settings.
153     */
154    public void print();
155
156    /**
157     * Positions the input window at the location stored in the preferences using the
158     * supplied key (with "PosX" and "PosY" appended). If the preference key isn't found
159     * or if the returned values can not be turned into numbers, the
160     * setLocationByPlatform() flag is set for the window.
161     *
162     * @param prefsKey The prefix for the preference key to use ("PosX" and "PosY" will be
163     *                 appended in order to retrieve the actual preference values).
164     * @param window   The window to be positioned using the preference values.
165     * @see Window#setLocationByPlatform(boolean) 
166     */
167    public void posWindowFromPrefs(String prefsKey, Window window);
168
169    /**
170     * Save the location of the specified window in the application preferences using the
171     * supplied key (with "PosX" and "PosY" appended).
172     *
173     * @param prefsKey The prefix for the preference key to use ("PosX" and "PosY" will be
174     *                 appended in order to save the actual preference values).
175     * @param window   The window for which the position is to be saved in the
176     *                 preferences.
177     */
178    public void savePrefsWindowPos(String prefsKey, Window window);
179    
180}