1 /*

     2  * Copyright 1997-2007 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 

    27 package java.awt;

    28 

    29 import java.awt.image.BufferedImage;

    30 import java.util.Locale;

    31 import sun.java2d.HeadlessGraphicsEnvironment;

    32 import sun.java2d.SunGraphicsEnvironment;

    33 

    34 /**

    35  *

    36  * The <code>GraphicsEnvironment</code> class describes the collection

    37  * of {@link GraphicsDevice} objects and {@link java.awt.Font} objects

    38  * available to a Java(tm) application on a particular platform.

    39  * The resources in this <code>GraphicsEnvironment</code> might be local

    40  * or on a remote machine.  <code>GraphicsDevice</code> objects can be

    41  * screens, printers or image buffers and are the destination of

    42  * {@link Graphics2D} drawing methods.  Each <code>GraphicsDevice</code>

    43  * has a number of {@link GraphicsConfiguration} objects associated with

    44  * it.  These objects specify the different configurations in which the

    45  * <code>GraphicsDevice</code> can be used.

    46  * @see GraphicsDevice

    47  * @see GraphicsConfiguration

    48  */

    49 

    50 public abstract class GraphicsEnvironment {

    51     private static GraphicsEnvironment localEnv;

    52 

    53     /**

    54      * The headless state of the Toolkit and GraphicsEnvironment

    55      */

    56     private static Boolean headless;

    57 

    58     /**

    59      * The headless state assumed by default

    60      */

    61     private static Boolean defaultHeadless;

    62 

    63     /**

    64      * This is an abstract class and cannot be instantiated directly.

    65      * Instances must be obtained from a suitable factory or query method.

    66      */

    67     protected GraphicsEnvironment() {

    68     }

    69 

    70     /**

    71      * Returns the local <code>GraphicsEnvironment</code>.

    72      * @return the local <code>GraphicsEnvironment</code>

    73      */

    74     public static synchronized GraphicsEnvironment getLocalGraphicsEnvironment() {

    75         if (localEnv == null) {

    76             String nm = (String) java.security.AccessController.doPrivileged

    77                 (new sun.security.action.GetPropertyAction

    78                  ("java.awt.graphicsenv", null));

    79 

    80             try {

    81 //                      long t0 = System.currentTimeMillis();

    82                 localEnv =

    83                     (GraphicsEnvironment) Class.forName(nm).newInstance();

    84 //              long t1 = System.currentTimeMillis();

    85 //              System.out.println("GE creation took " + (t1-t0)+ "ms.");

    86                 if (isHeadless()) {

    87                     localEnv = new HeadlessGraphicsEnvironment(localEnv);

    88                 }

    89             } catch (ClassNotFoundException e) {

    90                 throw new Error("Could not find class: "+nm);

    91             } catch (InstantiationException e) {

    92                 throw new Error("Could not instantiate Graphics Environment: "

    93                                 + nm);

    94             } catch (IllegalAccessException e) {

    95                 throw new Error ("Could not access Graphics Environment: "

    96                                  + nm);

    97             }

    98         }

    99 

   100         return localEnv;

   101     }

   102 

   103     /**

   104      * Tests whether or not a display, keyboard, and mouse can be

   105      * supported in this environment.  If this method returns true,

   106      * a HeadlessException is thrown from areas of the Toolkit

   107      * and GraphicsEnvironment that are dependent on a display,

   108      * keyboard, or mouse.

   109      * @return <code>true</code> if this environment cannot support

   110      * a display, keyboard, and mouse; <code>false</code>

   111      * otherwise

   112      * @see java.awt.HeadlessException

   113      * @since 1.4

   114      */

   115     public static boolean isHeadless() {

   116         return getHeadlessProperty();

   117     }

   118 

   119     /**

   120      * @return warning message if headless state is assumed by default;

   121      * null otherwise

   122      * @since 1.5

   123      */

   124     static String getHeadlessMessage() {

   125         if (headless == null) {

   126             getHeadlessProperty(); // initialize the values

   127         }

   128         return defaultHeadless != Boolean.TRUE ? null :

   129             "\nNo X11 DISPLAY variable was set, " +

   130             "but this program performed an operation which requires it.";

   131     }

   132 

   133     /**

   134      * @return the value of the property "java.awt.headless"

   135      * @since 1.4

   136      */

   137     private static boolean getHeadlessProperty() {

   138         if (headless == null) {

   139             java.security.AccessController.doPrivileged(

   140             new java.security.PrivilegedAction() {

   141                 public Object run() {

   142                     String nm = System.getProperty("java.awt.headless");

   143 

   144                     if (nm == null) {

   145                         /* No need to ask for DISPLAY when run in a browser */

   146                         if (System.getProperty("javaplugin.version") != null) {

   147                             headless = defaultHeadless = Boolean.FALSE;

   148                         } else {

   149                             String osName = System.getProperty("os.name");

   150                             headless = defaultHeadless =

   151                                 Boolean.valueOf(("Linux".equals(osName) || "SunOS".equals(osName)) &&

   152                                                 (System.getenv("DISPLAY") == null));

   153                         }

   154                     } else if (nm.equals("true")) {

   155                         headless = Boolean.TRUE;

   156                     } else {

   157                         headless = Boolean.FALSE;

   158                     }

   159                     return null;

   160                 }

   161                 }

   162             );

   163         }

   164         return headless.booleanValue();

   165     }

   166 

   167     /**

   168      * Check for headless state and throw HeadlessException if headless

   169      * @since 1.4

   170      */

   171     static void checkHeadless() throws HeadlessException {

   172         if (isHeadless()) {

   173             throw new HeadlessException();

   174         }

   175     }

   176 

   177     /**

   178      * Returns whether or not a display, keyboard, and mouse can be

   179      * supported in this graphics environment.  If this returns true,

   180      * <code>HeadlessException</code> will be thrown from areas of the

   181      * graphics environment that are dependent on a display, keyboard, or

   182      * mouse.

   183      * @return <code>true</code> if a display, keyboard, and mouse

   184      * can be supported in this environment; <code>false</code>

   185      * otherwise

   186      * @see java.awt.HeadlessException

   187      * @see #isHeadless

   188      * @since 1.4

   189      */

   190     public boolean isHeadlessInstance() {

   191         // By default (local graphics environment), simply check the

   192         // headless property.

   193         return getHeadlessProperty();

   194     }

   195 

   196     /**

   197      * Returns an array of all of the screen <code>GraphicsDevice</code>

   198      * objects.

   199      * @return an array containing all the <code>GraphicsDevice</code>

   200      * objects that represent screen devices

   201      * @exception HeadlessException if isHeadless() returns true

   202      * @see #isHeadless()

   203      */

   204     public abstract GraphicsDevice[] getScreenDevices()

   205         throws HeadlessException;

   206 

   207     /**

   208      * Returns the default screen <code>GraphicsDevice</code>.

   209      * @return the <code>GraphicsDevice</code> that represents the

   210      * default screen device

   211      * @exception HeadlessException if isHeadless() returns true

   212      * @see #isHeadless()

   213      */

   214     public abstract GraphicsDevice getDefaultScreenDevice()

   215         throws HeadlessException;

   216 

   217     /**

   218      * Returns a <code>Graphics2D</code> object for rendering into the

   219      * specified {@link BufferedImage}.

   220      * @param img the specified <code>BufferedImage</code>

   221      * @return a <code>Graphics2D</code> to be used for rendering into

   222      * the specified <code>BufferedImage</code>

   223      * @throws NullPointerException if <code>img</code> is null

   224      */

   225     public abstract Graphics2D createGraphics(BufferedImage img);

   226 

   227     /**

   228      * Returns an array containing a one-point size instance of all fonts

   229      * available in this <code>GraphicsEnvironment</code>.  Typical usage

   230      * would be to allow a user to select a particular font.  Then, the

   231      * application can size the font and set various font attributes by

   232      * calling the <code>deriveFont</code> method on the choosen instance.

   233      * <p>

   234      * This method provides for the application the most precise control

   235      * over which <code>Font</code> instance is used to render text.

   236      * If a font in this <code>GraphicsEnvironment</code> has multiple

   237      * programmable variations, only one

   238      * instance of that <code>Font</code> is returned in the array, and

   239      * other variations must be derived by the application.

   240      * <p>

   241      * If a font in this environment has multiple programmable variations,

   242      * such as Multiple-Master fonts, only one instance of that font is

   243      * returned in the <code>Font</code> array.  The other variations

   244      * must be derived by the application.

   245      *

   246      * @return an array of <code>Font</code> objects

   247      * @see #getAvailableFontFamilyNames

   248      * @see java.awt.Font

   249      * @see java.awt.Font#deriveFont

   250      * @see java.awt.Font#getFontName

   251      * @since 1.2

   252      */

   253     public abstract Font[] getAllFonts();

   254 

   255     /**

   256      * Returns an array containing the names of all font families in this

   257      * <code>GraphicsEnvironment</code> localized for the default locale,

   258      * as returned by <code>Locale.getDefault()</code>.

   259      * <p>

   260      * Typical usage would be for presentation to a user for selection of

   261      * a particular family name. An application can then specify this name

   262      * when creating a font, in conjunction with a style, such as bold or

   263      * italic, giving the font system flexibility in choosing its own best

   264      * match among multiple fonts in the same font family.

   265      *

   266      * @return an array of <code>String</code> containing font family names

   267      * localized for the default locale, or a suitable alternative

   268      * name if no name exists for this locale.

   269      * @see #getAllFonts

   270      * @see java.awt.Font

   271      * @see java.awt.Font#getFamily

   272      * @since 1.2

   273      */

   274     public abstract String[] getAvailableFontFamilyNames();

   275 

   276     /**

   277      * Returns an array containing the names of all font families in this

   278      * <code>GraphicsEnvironment</code> localized for the specified locale.

   279      * <p>

   280      * Typical usage would be for presentation to a user for selection of

   281      * a particular family name. An application can then specify this name

   282      * when creating a font, in conjunction with a style, such as bold or

   283      * italic, giving the font system flexibility in choosing its own best

   284      * match among multiple fonts in the same font family.

   285      *

   286      * @param l a {@link Locale} object that represents a

   287      * particular geographical, political, or cultural region.

   288      * Specifying <code>null</code> is equivalent to

   289      * specifying <code>Locale.getDefault()</code>.

   290      * @return an array of <code>String</code> containing font family names

   291      * localized for the specified <code>Locale</code>, or a

   292      * suitable alternative name if no name exists for the specified locale.

   293      * @see #getAllFonts

   294      * @see java.awt.Font

   295      * @see java.awt.Font#getFamily

   296      * @since 1.2

   297      */

   298     public abstract String[] getAvailableFontFamilyNames(Locale l);

   299 

   300     /**

   301      * Registers a <i>created</i> <code>Font</code>in this

   302      * <code>GraphicsEnvironment</code>.

   303      * A created font is one that was returned from calling

   304      * {@link Font#createFont}, or derived from a created font by

   305      * calling {@link Font#deriveFont}.

   306      * After calling this method for such a font, it is available to

   307      * be used in constructing new <code>Font</code>s by name or family name,

   308      * and is enumerated by {@link #getAvailableFontFamilyNames} and

   309      * {@link #getAllFonts} within the execution context of this

   310      * application or applet. This means applets cannot register fonts in

   311      * a way that they are visible to other applets.

   312      * <p>

   313      * Reasons that this method might not register the font and therefore

   314      * return <code>false</code> are:

   315      * <ul>

   316      * <li>The font is not a <i>created</i> <code>Font</code>.

   317      * <li>The font conflicts with a non-created <code>Font</code> already

   318      * in this <code>GraphicsEnvironment</code>. For example if the name

   319      * is that of a system font, or a logical font as described in the

   320      * documentation of the {@link Font} class. It is implementation dependent

   321      * whether a font may also conflict if it has the same family name

   322      * as a system font.

   323      * <p>Notice that an application can supersede the registration

   324      * of an earlier created font with a new one.

   325      * </ul>

   326      * @return true if the <code>font</code> is successfully

   327      * registered in this <code>GraphicsEnvironment</code>.

   328      * @throws NullPointerException if <code>font</code> is null

   329      * @since 1.6

   330      */

   331     public boolean registerFont(Font font) {

   332         if (font == null) {

   333             throw new NullPointerException("font cannot be null.");

   334         }

   335         return sun.font.FontManager.registerFont(font);

   336     }

   337 

   338     /**

   339      * Indicates a preference for locale-specific fonts in the mapping of

   340      * logical fonts to physical fonts. Calling this method indicates that font

   341      * rendering should primarily use fonts specific to the primary writing

   342      * system (the one indicated by the default encoding and the initial

   343      * default locale). For example, if the primary writing system is

   344      * Japanese, then characters should be rendered using a Japanese font

   345      * if possible, and other fonts should only be used for characters for

   346      * which the Japanese font doesn't have glyphs.

   347      * <p>

   348      * The actual change in font rendering behavior resulting from a call

   349      * to this method is implementation dependent; it may have no effect at

   350      * all, or the requested behavior may already match the default behavior.

   351      * The behavior may differ between font rendering in lightweight

   352      * and peered components.  Since calling this method requests a

   353      * different font, clients should expect different metrics, and may need

   354      * to recalculate window sizes and layout. Therefore this method should

   355      * be called before user interface initialisation.

   356      * @since 1.5

   357      */

   358     public void preferLocaleFonts() {

   359         sun.font.FontManager.preferLocaleFonts();

   360     }

   361 

   362     /**

   363      * Indicates a preference for proportional over non-proportional (e.g.

   364      * dual-spaced CJK fonts) fonts in the mapping of logical fonts to

   365      * physical fonts. If the default mapping contains fonts for which

   366      * proportional and non-proportional variants exist, then calling

   367      * this method indicates the mapping should use a proportional variant.

   368      * <p>

   369      * The actual change in font rendering behavior resulting from a call to

   370      * this method is implementation dependent; it may have no effect at all.

   371      * The behavior may differ between font rendering in lightweight and

   372      * peered components. Since calling this method requests a

   373      * different font, clients should expect different metrics, and may need

   374      * to recalculate window sizes and layout. Therefore this method should

   375      * be called before user interface initialisation.

   376      * @since 1.5

   377      */

   378     public void preferProportionalFonts() {

   379         sun.font.FontManager.preferProportionalFonts();

   380     }

   381 

   382     /**

   383      * Returns the Point where Windows should be centered.

   384      * It is recommended that centered Windows be checked to ensure they fit

   385      * within the available display area using getMaximumWindowBounds().

   386      * @return the point where Windows should be centered

   387      *

   388      * @exception HeadlessException if isHeadless() returns true

   389      * @see #getMaximumWindowBounds

   390      * @since 1.4

   391      */

   392     public Point getCenterPoint() throws HeadlessException {

   393     // Default implementation: return the center of the usable bounds of the

   394     // default screen device.

   395         Rectangle usableBounds =

   396          SunGraphicsEnvironment.getUsableBounds(getDefaultScreenDevice());

   397         return new Point((usableBounds.width / 2) + usableBounds.x,

   398                          (usableBounds.height / 2) + usableBounds.y);

   399     }

   400 

   401     /**

   402      * Returns the maximum bounds for centered Windows.

   403      * These bounds account for objects in the native windowing system such as

   404      * task bars and menu bars.  The returned bounds will reside on a single

   405      * display with one exception: on multi-screen systems where Windows should

   406      * be centered across all displays, this method returns the bounds of the

   407      * entire display area.

   408      * <p>

   409      * To get the usable bounds of a single display, use

   410      * <code>GraphicsConfiguration.getBounds()</code> and

   411      * <code>Toolkit.getScreenInsets()</code>.

   412      * @return  the maximum bounds for centered Windows

   413      *

   414      * @exception HeadlessException if isHeadless() returns true

   415      * @see #getCenterPoint

   416      * @see GraphicsConfiguration#getBounds

   417      * @see Toolkit#getScreenInsets

   418      * @since 1.4

   419      */

   420     public Rectangle getMaximumWindowBounds() throws HeadlessException {

   421     // Default implementation: return the usable bounds of the default screen

   422     // device.  This is correct for Microsoft Windows and non-Xinerama X11.

   423         return SunGraphicsEnvironment.getUsableBounds(getDefaultScreenDevice());

   424     }

   425 }