GraphicsEnvironment


1   /*
2    * @(#)GraphicsEnvironment.java 1.62 04/04/13
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   
9   package java.awt;
10  
11  import java.awt.image.BufferedImage  ;
12  import java.util.Hashtable  ;
13  import java.util.Locale  ;
14  import java.util.Map  ;
15  import java.io.InputStream  ;
16  import sun.java2d.HeadlessGraphicsEnvironment;
17  import sun.java2d.SunGraphicsEnvironment;
18  
19  /**
20   *
21   * The <code>GraphicsEnvironment</code> class describes the collection
22   * of {@link GraphicsDevice} objects and {@link java.awt.Font} objects
23   * available to a Java(tm) application on a particular platform.
24   * The resources in this <code>GraphicsEnvironment</code> might be local
25   * or on a remote machine.  <code>GraphicsDevice</code> objects can be
26   * screens, printers or image buffers and are the destination of
27   * {@link Graphics2D} drawing methods.  Each <code>GraphicsDevice</code>
28   * has a number of {@link GraphicsConfiguration} objects associated with
29   * it.  These objects specify the different configurations in which the
30   * <code>GraphicsDevice</code> can be used.  
31   * @see GraphicsDevice
32   * @see GraphicsConfiguration
33   * @version     1.62, 04/13/04
34   */
35  
36  public abstract class GraphicsEnvironment {
37      private static GraphicsEnvironment   localEnv;
38  
39      /**
40       * The headless state of the Toolkit and GraphicsEnvironment
41       */
42      private static Boolean   headless;
43  
44      /**
45       * The headless state assumed by default
46       */
47      private static Boolean   defaultHeadless;
48  
49      /**
50       * This is an abstract class and cannot be instantiated directly.
51       * Instances must be obtained from a suitable factory or query method.
52       */
53      protected GraphicsEnvironment() {
54      }
55  
56      /**
57       * Returns the local <code>GraphicsEnvironment</code>.
58       * @return the local <code>GraphicsEnvironment</code>
59       */
60      public static synchronized GraphicsEnvironment   getLocalGraphicsEnvironment() {
61      if (localEnv == null) {
62          String   nm = (String  ) java.security.AccessController.doPrivileged
63          (new sun.security.action.GetPropertyAction
64           ("java.awt.graphicsenv", null));
65  
66          try {
67  //          long t0 = System.currentTimeMillis();
68          localEnv =
69              (GraphicsEnvironment  ) Class.forName(nm).newInstance();
70  //      long t1 = System.currentTimeMillis();
71  //      System.out.println("GE creation took " + (t1-t0)+ "ms.");
72                  if (isHeadless()) {
73                      localEnv = new HeadlessGraphicsEnvironment(localEnv);
74                  }
75          } catch (ClassNotFoundException   e) {
76                  throw new Error  ("Could not find class: "+nm);
77              } catch (InstantiationException   e) {
78                  throw new Error  ("Could not instantiate Graphics Environment: "
79                  + nm);
80              } catch (IllegalAccessException   e) {
81                  throw new Error   ("Could not access Graphics Environment: "
82                   + nm);
83              }
84          }
85  
86      return localEnv;
87      }
88  
89      /**
90       * Tests whether or not a display, keyboard, and mouse can be
91       * supported in this environment.  If this method returns true,
92       * a HeadlessException is thrown from areas of the Toolkit
93       * and GraphicsEnvironment that are dependent on a display,
94       * keyboard, or mouse.
95       * @return <code>true</code> if this environment cannot support 
96       * a display, keyboard, and mouse; <code>false</code> 
97       * otherwise
98       * @see java.awt.HeadlessException
99       * @since 1.4
100      */
101     public static boolean isHeadless() {   
102         return getHeadlessProperty();
103     }
104 
105     /**
106      * @return warning message if headless state is assumed by default;
107      * null otherwise
108      * @since 1.5
109      */
110     static String   getHeadlessMessage() {
111         if (headless == null) {
112             getHeadlessProperty(); // initialize the values 
113         }
114         return defaultHeadless != Boolean.TRUE ? null :
115             "\nNo X11 DISPLAY variable was set, " +
116             "but this program performed an operation which requires it.";
117     }
118 
119     /**
120      * @return the value of the property "java.awt.headless"
121      * @since 1.4
122      */
123     private static boolean getHeadlessProperty() {
124         if (headless == null) {
125             java.security.AccessController.doPrivileged(
126             new java.security.PrivilegedAction  () {
127                 public Object   run() {
128                     String   nm = System.getProperty("java.awt.headless");
129                     
130                     if (nm == null) {
131                         /* No need to ask for DISPLAY when run in a browser */
132                         if (System.getProperty("javaplugin.version") != null) {
133                             headless = defaultHeadless = Boolean.FALSE; 
134                         } else {
135                             String   osName = System.getProperty("os.name");                        
136                             headless = defaultHeadless =
137                                 Boolean.valueOf(("Linux".equals(osName) || "SunOS".equals(osName)) &&
138                                                 (System.getenv("DISPLAY") == null));
139                         }
140                     } else if (nm.equals("true")) {
141                         headless = Boolean.TRUE;
142                     } else {
143                         headless = Boolean.FALSE;
144                     }
145                     return null;
146                 }
147                 }
148             );
149         }
150         return headless.booleanValue();
151     }
152 
153     /**
154      * Check for headless state and throw HeadlessException if headless
155      * @since 1.4
156      */
157     static void checkHeadless() throws HeadlessException   {
158         if (isHeadless()) {
159             throw new HeadlessException  ();
160         }
161     }
162 
163     /**
164      * Returns whether or not a display, keyboard, and mouse can be 
165      * supported in this graphics environment.  If this returns true,
166      * <code>HeadlessException</code> will be thrown from areas of the
167      * graphics environment that are dependent on a display, keyboard, or
168      * mouse.
169      * @return <code>true</code> if a display, keyboard, and mouse 
170      * can be supported in this environment; <code>false</code>
171      * otherwise
172      * @see java.awt.HeadlessException
173      * @see #isHeadless
174      * @since 1.4
175      */
176     public boolean isHeadlessInstance() {
177         // By default (local graphics environment), simply check the
178         // headless property.
179         return getHeadlessProperty();
180     }
181 
182     /**
183      * Returns an array of all of the screen <code>GraphicsDevice</code>
184      * objects.
185      * @return an array containing all the <code>GraphicsDevice</code>
186      * objects that represent screen devices
187      * @exception HeadlessException if isHeadless() returns true
188      * @see #isHeadless()
189      */
190     public abstract GraphicsDevice  [] getScreenDevices()
191         throws HeadlessException  ;
192 
193     /**
194      * Returns the default screen <code>GraphicsDevice</code>.
195      * @return the <code>GraphicsDevice</code> that represents the
196      * default screen device
197      * @exception HeadlessException if isHeadless() returns true
198      * @see #isHeadless()
199      */
200     public abstract GraphicsDevice   getDefaultScreenDevice()
201         throws HeadlessException  ;
202 
203     /**
204      * Returns a <code>Graphics2D</code> object for rendering into the
205      * specified {@link BufferedImage}.
206      * @param img the specified <code>BufferedImage</code>
207      * @return a <code>Graphics2D</code> to be used for rendering into
208      * the specified <code>BufferedImage</code>
209      */
210     public abstract Graphics2D   createGraphics(BufferedImage   img);
211 
212     /**
213      * Returns an array containing a one-point size instance of all fonts
214      * available in this <code>GraphicsEnvironment</code>.  Typical usage
215      * would be to allow a user to select a particular font.  Then, the
216      * application can size the font and set various font attributes by
217      * calling the <code>deriveFont</code> method on the choosen instance.
218      * <p>
219      * This method provides for the application the most precise control
220      * over which <code>Font</code> instance is used to render text.
221      * If a font in this <code>GraphicsEnvironment</code> has multiple
222      * programmable variations, only one
223      * instance of that <code>Font</code> is returned in the array, and
224      * other variations must be derived by the application.
225      * <p>
226      * If a font in this environment has multiple programmable variations,
227      * such as Multiple-Master fonts, only one instance of that font is
228      * returned in the <code>Font</code> array.  The other variations
229      * must be derived by the application.
230      *
231      * @return an array of <code>Font</code> objects
232      * @see #getAvailableFontFamilyNames
233      * @see java.awt.Font
234      * @see java.awt.Font#deriveFont
235      * @see java.awt.Font#getFontName
236      * @since 1.2
237      */
238     public abstract Font  [] getAllFonts();
239 
240     /**
241      * Returns an array containing the names of all font families in this
242      * <code>GraphicsEnvironment</code> localized for the default locale,
243      * as returned by <code>Locale.getDefault()</code>.
244      * <p>
245      * Typical usage would be for presentation to a user for selection of
246      * a particular family name. An application can then specify this name
247      * when creating a font, in conjunction with a style, such as bold or
248      * italic, giving the font system flexibility in choosing its own best
249      * match among multiple fonts in the same font family.
250      *
251      * @return an array of <code>String</code> containing font family names
252      * localized for the default locale, or a suitable alternative
253      * name if no name exists for this locale.
254      * @see #getAllFonts
255      * @see java.awt.Font
256      * @see java.awt.Font#getFamily
257      * @since 1.2
258      */
259     public abstract String  [] getAvailableFontFamilyNames();
260 
261     /**
262      * Returns an array containing the names of all font families in this
263      * <code>GraphicsEnvironment</code> localized for the specified locale.
264      * <p>
265      * Typical usage would be for presentation to a user for selection of
266      * a particular family name. An application can then specify this name
267      * when creating a font, in conjunction with a style, such as bold or
268      * italic, giving the font system flexibility in choosing its own best
269      * match among multiple fonts in the same font family.
270      *
271      * @param l a {@link Locale} object that represents a
272      * particular geographical, political, or cultural region.
273      * Specifying <code>null</code> is equivalent to
274      * specifying <code>Locale.getDefault()</code>.
275      * @return an array of <code>String</code> containing font family names
276      * localized for the specified <code>Locale</code>, or a
277      * suitable alternative name if no name exists for the specified locale.
278      * @see #getAllFonts
279      * @see java.awt.Font
280      * @see java.awt.Font#getFamily
281      * @since 1.2
282      */
283     public abstract String  [] getAvailableFontFamilyNames(Locale   l);
284 
285     /**
286      * Indicates a preference for locale-specific fonts in the mapping of
287      * logical fonts to physical fonts. Calling this method indicates that font
288      * rendering should primarily use fonts specific to the primary writing
289      * system (the one indicated by the default encoding and the initial
290      * default locale). For example, if the primary writing system is
291      * Japanese, then characters should be rendered using a Japanese font
292      * if possible, and other fonts should only be used for characters for
293      * which the Japanese font doesn't have glyphs.
294      * <p>
295      * The actual change in font rendering behavior resulting from a call
296      * to this method is implementation dependent; it may have no effect at
297      * all, or the requested behavior may already match the default behavior.
298      * The behavior may differ between font rendering in lightweight
299      * and peered components.  Since calling this method requests a
300      * different font, clients should expect different metrics, and may need
301      * to recalculate window sizes and layout. Therefore this method should
302      * be called before user interface initialisation.
303      * @since 1.5
304      */
305     public void preferLocaleFonts() {
306     sun.font.FontManager.preferLocaleFonts();
307     }
308 
309     /**
310      * Indicates a preference for proportional over non-proportional (e.g.
311      * dual-spaced CJK fonts) fonts in the mapping of logical fonts to
312      * physical fonts. If the default mapping contains fonts for which
313      * proportional and non-proportional variants exist, then calling
314      * this method indicates the mapping should use a proportional variant.
315      * <p>
316      * The actual change in font rendering behavior resulting from a call to
317      * this method is implementation dependent; it may have no effect at all.
318      * The behavior may differ between font rendering in lightweight and
319      * peered components. Since calling this method requests a
320      * different font, clients should expect different metrics, and may need
321      * to recalculate window sizes and layout. Therefore this method should
322      * be called before user interface initialisation.
323      * @since 1.5
324      */
325     public void preferProportionalFonts() {
326     sun.font.FontManager.preferProportionalFonts();
327     }
328 
329     /**
330      * Returns the Point where Windows should be centered.
331      * It is recommended that centered Windows be checked to ensure they fit
332      * within the available display area using getMaximumWindowBounds().
333      * @return the point where Windows should be centered
334      *
335      * @exception HeadlessException if isHeadless() returns true
336      * @see #getMaximumWindowBounds
337      * @since 1.4
338      */
339     public Point   getCenterPoint() throws HeadlessException   {
340     // Default implementation: return the center of the usable bounds of the
341     // default screen device.
342         Rectangle   usableBounds = 
343          SunGraphicsEnvironment.getUsableBounds(getDefaultScreenDevice());
344         return new Point  ((usableBounds.width / 2) + usableBounds.x,
345                          (usableBounds.height / 2) + usableBounds.y);    
346     }
347 
348     /**
349      * Returns the maximum bounds for centered Windows.
350      * These bounds account for objects in the native windowing system such as
351      * task bars and menu bars.  The returned bounds will reside on a single
352      * display with one exception: on multi-screen systems where Windows should
353      * be centered across all displays, this method returns the bounds of the
354      * entire display area.
355      * <p>
356      * To get the usable bounds of a single display, use 
357      * <code>GraphicsConfiguration.getBounds()</code> and
358      * <code>Toolkit.getScreenInsets()</code>.
359      * @return  the maximum bounds for centered Windows
360      *
361      * @exception HeadlessException if isHeadless() returns true
362      * @see #getCenterPoint
363      * @see GraphicsConfiguration#getBounds
364      * @see Toolkit#getScreenInsets
365      * @since 1.4
366      */
367     public Rectangle   getMaximumWindowBounds() throws HeadlessException   {
368     // Default implementation: return the usable bounds of the default screen
369     // device.  This is correct for Microsoft Windows and non-Xinerama X11.
370         return SunGraphicsEnvironment.getUsableBounds(getDefaultScreenDevice());
371     }
372 }
373 
374
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags