001    /* GraphicsEnvironment.java -- information about the graphics environment
002       Copyright (C) 2002, 2004, 2005  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.awt;
040    
041    import gnu.java.awt.ClasspathToolkit;
042    import gnu.classpath.SystemProperties;
043    import java.awt.image.BufferedImage;
044    import java.util.Locale;
045    
046    /**
047     * This descibes the collection of GraphicsDevice and Font objects available
048     * on a given platform. The resources might be local or remote, and specify
049     * the valid configurations for displaying graphics.
050     *
051     * @author Eric Blake (ebb9@email.byu.edu)
052     * @see GraphicsDevice
053     * @see GraphicsConfiguration
054     * @since 1.4
055     * @status updated to 1.4
056     */
057    public abstract class GraphicsEnvironment
058    {
059      private static GraphicsEnvironment localGraphicsEnvironment;
060    
061      /**
062       * The environment must be obtained from a factory or query method, hence
063       * this constructor is protected.
064       */
065      protected GraphicsEnvironment()
066      {
067      }
068    
069      /**
070       * Returns the local graphics environment. If the java.awt.graphicsenv
071       * system property is set, it instantiates the specified class,
072       * otherwise it assume that the awt toolkit is a ClasspathToolkit
073       * and delegates to it to create the instance.
074       *
075       * @return the local environment
076       */
077      public static GraphicsEnvironment getLocalGraphicsEnvironment()
078      {
079        if (localGraphicsEnvironment != null)
080          return localGraphicsEnvironment;
081    
082        String graphicsenv = SystemProperties.getProperty("java.awt.graphicsenv",
083                                                          null);
084        if (graphicsenv != null)
085          {
086            try
087              {
088                // We intentionally use the bootstrap class loader.
089                localGraphicsEnvironment = (GraphicsEnvironment)
090                    Class.forName(graphicsenv).newInstance();
091                return localGraphicsEnvironment;
092              }
093            catch (Exception x)
094              {
095                throw (InternalError)
096                    new InternalError("Unable to instantiate java.awt.graphicsenv")
097                        .initCause(x);
098              }
099          }
100        else
101          {
102            ClasspathToolkit tk;
103            tk = ((ClasspathToolkit) Toolkit.getDefaultToolkit());
104            localGraphicsEnvironment = tk.getLocalGraphicsEnvironment();
105            return localGraphicsEnvironment;
106          }
107      }
108    
109      /**
110       * Check if the local environment is headless, meaning that it does not
111       * support a display, keyboard, or mouse. Many methods in the Abstract
112       * Windows Toolkit (java.awt) throw a {@link HeadlessException} if this
113       * returns true.
114       *
115       * This method returns true if the java.awt.headless property is set
116       * to "true".
117       *
118       * @return true if the environment is headless, meaning that graphics are
119       *         unsupported
120       * @since 1.4
121       */
122      public static boolean isHeadless()
123      {
124        String headless = SystemProperties.getProperty("java.awt.headless", null);
125        return "true".equalsIgnoreCase(headless);
126      }
127    
128      /**
129       * Check if the given environment is headless, meaning that it does not
130       * support a display, keyboard, or mouse. Many methods in the Abstract
131       * Windows Toolkit (java.awt) throw a {@link HeadlessException} if this
132       * returns true. This default implementation returns isHeadless(), so
133       * subclasses need only override it if they differ.
134       *
135       * @return true if the environment is headless, meaning that graphics are
136       *         unsupported
137       * @since 1.4
138       */
139      public boolean isHeadlessInstance()
140      {
141        return isHeadless();
142      }
143    
144      /**
145       * Get an array of all the GraphicsDevice objects.
146       *
147       * @return the available graphics devices, may be 0 length
148       * @throws HeadlessException if the environment is headless
149       */
150      public abstract GraphicsDevice[] getScreenDevices();
151    
152      /**
153       * Get the default screen GraphicsDevice object.
154       *
155       * @return the default screen device
156       * @throws HeadlessException if the environment is headless
157       */
158      public abstract GraphicsDevice getDefaultScreenDevice();
159    
160      /**
161       * Return a Graphics2D object which will render into the specified image.
162       *
163       * @param image the image to render into
164       * @return the object that renders into the image
165       */
166      public abstract Graphics2D createGraphics(BufferedImage image);
167    
168      /**
169       * Returns an array of the one-point size fonts available in this
170       * environment. From there, the user can select the font and derive the
171       * correct one of proper size and attributes, using <code>deriveFont</code>.
172       * Only one master version of each font appears in this array; if a font
173       * can be derived from another, it must be created in that way.
174       *
175       * @return the array of available fonts
176       * @see #getAvailableFontFamilyNames()
177       * @see Font#deriveFont(int, float)
178       * @since 1.2
179       */
180      public abstract Font[] getAllFonts();
181    
182      /**
183       * Returns an array of the font family names available in this environment.
184       * This allows flexibility in choosing the style of font, while still letting
185       * the Font class decide its best match.
186       *
187       * @return the array of available font families
188       * @see #getAllFonts()
189       * @see Font#getFamily()
190       * @since 1.2
191       */
192      public abstract String[] getAvailableFontFamilyNames();
193    
194      /**
195       * Returns an array of the font family names available in this environment,
196       * localized to the current Locale if l is non-null. This allows
197       * flexibility in choosing the style of font, while still letting the Font
198       * class decide its best match.
199       *
200       * @param l the locale to use
201       * @return the array of available font families, localized
202       * @see #getAllFonts()
203       * @see Font#getFamily()
204       * @since 1.2
205       */
206      public abstract String[] getAvailableFontFamilyNames(Locale l);
207    
208      /**
209       * Returns the point where a window should be centered. You should probably
210       * also check that the window fits within the screen bounds. The default
211       * simply returns the center of the maximum window bounds; subclasses should
212       * override this if native objects (like scrollbars) make that off-centered.
213       *
214       * @return the centering point
215       * @throws HeadlessException if the environment is headless
216       * @see #getMaximumWindowBounds()
217       * @since 1.4
218       */
219      public Point getCenterPoint()
220      {
221        Rectangle r = getMaximumWindowBounds();
222        return new Point(r.x + r.width / 2, r.y + r.height / 2);
223      }
224    
225      /**
226       * Returns the maximum bounds for a centered window object. The default
227       * implementation simply returns the bounds of the default configuration
228       * of the default screen; subclasses should override this to if native
229       * objects (like scrollbars) reduce what is truly available. Also,
230       * subclasses should override this if the window should be centered across
231       * a multi-screen display.
232       *
233       * @return the maximum window bounds
234       * @throws HeadlessException if the environment is headless
235       * @see #getCenterPoint()
236       * @see GraphicsConfiguration#getBounds()
237       * @see Toolkit#getScreenInsets(GraphicsConfiguration)
238       * @since 1.4
239       */
240      public Rectangle getMaximumWindowBounds()
241      {
242        return getDefaultScreenDevice().getDefaultConfiguration().getBounds();
243      }
244    } // class GraphicsEnvironment