1 /*
   2  * Copyright (c) 1997, 2014, Oracle and/or its affiliates. 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.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 
  27 package java.awt;
  28 
  29 import java.awt.image.BufferedImage;
  30 import java.security.AccessController;
  31 import java.security.PrivilegedAction;
  32 import java.util.Locale;
  33 
  34 import sun.font.FontManager;
  35 import sun.font.FontManagerFactory;
  36 import sun.java2d.HeadlessGraphicsEnvironment;
  37 import sun.java2d.SunGraphicsEnvironment;
  38 import sun.security.action.GetPropertyAction;
  39 
  40 /**
  41  *
  42  * The {@code GraphicsEnvironment} class describes the collection
  43  * of {@link GraphicsDevice} objects and {@link java.awt.Font} objects
  44  * available to a Java(tm) application on a particular platform.
  45  * The resources in this {@code GraphicsEnvironment} might be local
  46  * or on a remote machine.  {@code GraphicsDevice} objects can be
  47  * screens, printers or image buffers and are the destination of
  48  * {@link Graphics2D} drawing methods.  Each {@code GraphicsDevice}
  49  * has a number of {@link GraphicsConfiguration} objects associated with
  50  * it.  These objects specify the different configurations in which the
  51  * {@code GraphicsDevice} can be used.
  52  * @see GraphicsDevice
  53  * @see GraphicsConfiguration
  54  */
  55 
  56 public abstract class GraphicsEnvironment {
  57     private static GraphicsEnvironment localEnv;
  58 
  59     /**
  60      * The headless state of the Toolkit and GraphicsEnvironment
  61      */
  62     private static Boolean headless;
  63 
  64     /**
  65      * The headless state assumed by default
  66      */
  67     private static Boolean defaultHeadless;
  68 
  69     /**
  70      * This is an abstract class and cannot be instantiated directly.
  71      * Instances must be obtained from a suitable factory or query method.
  72      */
  73     protected GraphicsEnvironment() {
  74     }
  75 
  76     /**
  77      * Returns the local {@code GraphicsEnvironment}.
  78      * @return the local {@code GraphicsEnvironment}
  79      */
  80     public static synchronized GraphicsEnvironment getLocalGraphicsEnvironment() {
  81         if (localEnv == null) {
  82             localEnv = createGE();
  83         }
  84 
  85         return localEnv;
  86     }
  87 
  88     /**
  89      * Creates and returns the GraphicsEnvironment, according to the
  90      * system property 'java.awt.graphicsenv'.
  91      *
  92      * @return the graphics environment
  93      */
  94     private static GraphicsEnvironment createGE() {
  95         GraphicsEnvironment ge;
  96         String nm = AccessController.doPrivileged(new GetPropertyAction("java.awt.graphicsenv", null));
  97         try {
  98 //          long t0 = System.currentTimeMillis();
  99             Class<?> geCls;
 100             try {
 101                 // First we try if the bootstrap class loader finds the
 102                 // requested class. This way we can avoid to run in a privileged
 103                 // block.
 104                 geCls = Class.forName(nm);
 105             } catch (ClassNotFoundException ex) {
 106                 // If the bootstrap class loader fails, we try again with the
 107                 // application class loader.
 108                 ClassLoader cl = ClassLoader.getSystemClassLoader();
 109                 geCls = Class.forName(nm, true, cl);
 110             }
 111             ge = (GraphicsEnvironment)geCls.newInstance();
 112 //          long t1 = System.currentTimeMillis();
 113 //          System.out.println("GE creation took " + (t1-t0)+ "ms.");
 114             if (isHeadless()) {
 115                 ge = new HeadlessGraphicsEnvironment(ge);
 116             }
 117         } catch (ClassNotFoundException e) {
 118             throw new Error("Could not find class: "+nm);
 119         } catch (InstantiationException e) {
 120             throw new Error("Could not instantiate Graphics Environment: "
 121                             + nm);
 122         } catch (IllegalAccessException e) {
 123             throw new Error ("Could not access Graphics Environment: "
 124                              + nm);
 125         }
 126         return ge;
 127     }
 128 
 129     /**
 130      * Tests whether or not a display, keyboard, and mouse can be
 131      * supported in this environment.  If this method returns true,
 132      * a HeadlessException is thrown from areas of the Toolkit
 133      * and GraphicsEnvironment that are dependent on a display,
 134      * keyboard, or mouse.
 135      * @return {@code true} if this environment cannot support
 136      * a display, keyboard, and mouse; {@code false}
 137      * otherwise
 138      * @see java.awt.HeadlessException
 139      * @since 1.4
 140      */
 141     public static boolean isHeadless() {
 142         return getHeadlessProperty();
 143     }
 144 
 145     /**
 146      * @return warning message if headless state is assumed by default;
 147      * null otherwise
 148      * @since 1.5
 149      */
 150     static String getHeadlessMessage() {
 151         if (headless == null) {
 152             getHeadlessProperty(); // initialize the values
 153         }
 154         return defaultHeadless != Boolean.TRUE ? null :
 155             "\nNo X11 DISPLAY variable was set, " +
 156             "but this program performed an operation which requires it.";
 157     }
 158 
 159     /**
 160      * @return the value of the property "java.awt.headless"
 161      * @since 1.4
 162      */
 163     private static boolean getHeadlessProperty() {
 164         if (headless == null) {
 165             AccessController.doPrivileged((PrivilegedAction<Void>) () -> {
 166                 String nm = System.getProperty("java.awt.headless");
 167 
 168                 if (nm == null) {
 169                     /* No need to ask for DISPLAY when run in a browser */
 170                     if (System.getProperty("javaplugin.version") != null) {
 171                         headless = defaultHeadless = Boolean.FALSE;
 172                     } else {
 173                         String osName = System.getProperty("os.name");
 174                         if (osName.contains("OS X") && "sun.awt.HToolkit".equals(
 175                                 System.getProperty("awt.toolkit")))
 176                         {
 177                             headless = defaultHeadless = Boolean.TRUE;
 178                         } else {
 179                             final String display = System.getenv("DISPLAY");
 180                             headless = defaultHeadless =
 181                                 ("Linux".equals(osName) ||
 182                                  "SunOS".equals(osName) ||
 183                                  "FreeBSD".equals(osName) ||
 184                                  "NetBSD".equals(osName) ||
 185                                  "OpenBSD".equals(osName) ||
 186                                  "AIX".equals(osName)) &&
 187                                  (display == null || display.trim().isEmpty());
 188                         }
 189                     }
 190                 } else {
 191                     headless = Boolean.valueOf(nm);
 192                 }
 193                 return null;
 194             });
 195         }
 196         return headless;
 197     }
 198 
 199     /**
 200      * Check for headless state and throw HeadlessException if headless
 201      * @since 1.4
 202      */
 203     static void checkHeadless() throws HeadlessException {
 204         if (isHeadless()) {
 205             throw new HeadlessException();
 206         }
 207     }
 208 
 209     /**
 210      * Returns whether or not a display, keyboard, and mouse can be
 211      * supported in this graphics environment.  If this returns true,
 212      * {@code HeadlessException} will be thrown from areas of the
 213      * graphics environment that are dependent on a display, keyboard, or
 214      * mouse.
 215      * @return {@code true} if a display, keyboard, and mouse
 216      * can be supported in this environment; {@code false}
 217      * otherwise
 218      * @see java.awt.HeadlessException
 219      * @see #isHeadless
 220      * @since 1.4
 221      */
 222     public boolean isHeadlessInstance() {
 223         // By default (local graphics environment), simply check the
 224         // headless property.
 225         return getHeadlessProperty();
 226     }
 227 
 228     /**
 229      * Returns an array of all of the screen {@code GraphicsDevice}
 230      * objects.
 231      * @return an array containing all the {@code GraphicsDevice}
 232      * objects that represent screen devices
 233      * @exception HeadlessException if isHeadless() returns true
 234      * @see #isHeadless()
 235      */
 236     public abstract GraphicsDevice[] getScreenDevices()
 237         throws HeadlessException;
 238 
 239     /**
 240      * Returns the default screen {@code GraphicsDevice}.
 241      * @return the {@code GraphicsDevice} that represents the
 242      * default screen device
 243      * @exception HeadlessException if isHeadless() returns true
 244      * @see #isHeadless()
 245      */
 246     public abstract GraphicsDevice getDefaultScreenDevice()
 247         throws HeadlessException;
 248 
 249     /**
 250      * Returns a {@code Graphics2D} object for rendering into the
 251      * specified {@link BufferedImage}.
 252      * @param img the specified {@code BufferedImage}
 253      * @return a {@code Graphics2D} to be used for rendering into
 254      * the specified {@code BufferedImage}
 255      * @throws NullPointerException if {@code img} is null
 256      */
 257     public abstract Graphics2D createGraphics(BufferedImage img);
 258 
 259     /**
 260      * Returns an array containing a one-point size instance of all fonts
 261      * available in this {@code GraphicsEnvironment}.  Typical usage
 262      * would be to allow a user to select a particular font.  Then, the
 263      * application can size the font and set various font attributes by
 264      * calling the {@code deriveFont} method on the chosen instance.
 265      * <p>
 266      * This method provides for the application the most precise control
 267      * over which {@code Font} instance is used to render text.
 268      * If a font in this {@code GraphicsEnvironment} has multiple
 269      * programmable variations, only one
 270      * instance of that {@code Font} is returned in the array, and
 271      * other variations must be derived by the application.
 272      * <p>
 273      * If a font in this environment has multiple programmable variations,
 274      * such as Multiple-Master fonts, only one instance of that font is
 275      * returned in the {@code Font} array.  The other variations
 276      * must be derived by the application.
 277      *
 278      * @return an array of {@code Font} objects
 279      * @see #getAvailableFontFamilyNames
 280      * @see java.awt.Font
 281      * @see java.awt.Font#deriveFont
 282      * @see java.awt.Font#getFontName
 283      * @since 1.2
 284      */
 285     public abstract Font[] getAllFonts();
 286 
 287     /**
 288      * Returns an array containing the names of all font families in this
 289      * {@code GraphicsEnvironment} localized for the default locale,
 290      * as returned by {@code Locale.getDefault()}.
 291      * <p>
 292      * Typical usage would be for presentation to a user for selection of
 293      * a particular family name. An application can then specify this name
 294      * when creating a font, in conjunction with a style, such as bold or
 295      * italic, giving the font system flexibility in choosing its own best
 296      * match among multiple fonts in the same font family.
 297      *
 298      * @return an array of {@code String} containing font family names
 299      * localized for the default locale, or a suitable alternative
 300      * name if no name exists for this locale.
 301      * @see #getAllFonts
 302      * @see java.awt.Font
 303      * @see java.awt.Font#getFamily
 304      * @since 1.2
 305      */
 306     public abstract String[] getAvailableFontFamilyNames();
 307 
 308     /**
 309      * Returns an array containing the names of all font families in this
 310      * {@code GraphicsEnvironment} localized for the specified locale.
 311      * <p>
 312      * Typical usage would be for presentation to a user for selection of
 313      * a particular family name. An application can then specify this name
 314      * when creating a font, in conjunction with a style, such as bold or
 315      * italic, giving the font system flexibility in choosing its own best
 316      * match among multiple fonts in the same font family.
 317      *
 318      * @param l a {@link Locale} object that represents a
 319      * particular geographical, political, or cultural region.
 320      * Specifying {@code null} is equivalent to
 321      * specifying {@code Locale.getDefault()}.
 322      * @return an array of {@code String} containing font family names
 323      * localized for the specified {@code Locale}, or a
 324      * suitable alternative name if no name exists for the specified locale.
 325      * @see #getAllFonts
 326      * @see java.awt.Font
 327      * @see java.awt.Font#getFamily
 328      * @since 1.2
 329      */
 330     public abstract String[] getAvailableFontFamilyNames(Locale l);
 331 
 332     /**
 333      * Registers a <i>created</i> {@code Font} in this
 334      * {@code GraphicsEnvironment}.
 335      * A created font is one that was returned from calling
 336      * {@link Font#createFont}, or derived from a created font by
 337      * calling {@link Font#deriveFont}.
 338      * After calling this method for such a font, it is available to
 339      * be used in constructing new {@code Font}s by name or family name,
 340      * and is enumerated by {@link #getAvailableFontFamilyNames} and
 341      * {@link #getAllFonts} within the execution context of this
 342      * application or applet. This means applets cannot register fonts in
 343      * a way that they are visible to other applets.
 344      * <p>
 345      * Reasons that this method might not register the font and therefore
 346      * return {@code false} are:
 347      * <ul>
 348      * <li>The font is not a <i>created</i> {@code Font}.
 349      * <li>The font conflicts with a non-created {@code Font} already
 350      * in this {@code GraphicsEnvironment}. For example if the name
 351      * is that of a system font, or a logical font as described in the
 352      * documentation of the {@link Font} class. It is implementation dependent
 353      * whether a font may also conflict if it has the same family name
 354      * as a system font.
 355      * <p>Notice that an application can supersede the registration
 356      * of an earlier created font with a new one.
 357      * </ul>
 358      *
 359      * @param  font the font to be registered
 360      * @return true if the {@code font} is successfully
 361      * registered in this {@code GraphicsEnvironment}.
 362      * @throws NullPointerException if {@code font} is null
 363      * @since 1.6
 364      */
 365     public boolean registerFont(Font font) {
 366         if (font == null) {
 367             throw new NullPointerException("font cannot be null.");
 368         }
 369         FontManager fm = FontManagerFactory.getInstance();
 370         return fm.registerFont(font);
 371     }
 372 
 373     /**
 374      * Indicates a preference for locale-specific fonts in the mapping of
 375      * logical fonts to physical fonts. Calling this method indicates that font
 376      * rendering should primarily use fonts specific to the primary writing
 377      * system (the one indicated by the default encoding and the initial
 378      * default locale). For example, if the primary writing system is
 379      * Japanese, then characters should be rendered using a Japanese font
 380      * if possible, and other fonts should only be used for characters for
 381      * which the Japanese font doesn't have glyphs.
 382      * <p>
 383      * The actual change in font rendering behavior resulting from a call
 384      * to this method is implementation dependent; it may have no effect at
 385      * all, or the requested behavior may already match the default behavior.
 386      * The behavior may differ between font rendering in lightweight
 387      * and peered components.  Since calling this method requests a
 388      * different font, clients should expect different metrics, and may need
 389      * to recalculate window sizes and layout. Therefore this method should
 390      * be called before user interface initialisation.
 391      * @since 1.5
 392      */
 393     public void preferLocaleFonts() {
 394         FontManager fm = FontManagerFactory.getInstance();
 395         fm.preferLocaleFonts();
 396     }
 397 
 398     /**
 399      * Indicates a preference for proportional over non-proportional (e.g.
 400      * dual-spaced CJK fonts) fonts in the mapping of logical fonts to
 401      * physical fonts. If the default mapping contains fonts for which
 402      * proportional and non-proportional variants exist, then calling
 403      * this method indicates the mapping should use a proportional variant.
 404      * <p>
 405      * The actual change in font rendering behavior resulting from a call to
 406      * this method is implementation dependent; it may have no effect at all.
 407      * The behavior may differ between font rendering in lightweight and
 408      * peered components. Since calling this method requests a
 409      * different font, clients should expect different metrics, and may need
 410      * to recalculate window sizes and layout. Therefore this method should
 411      * be called before user interface initialisation.
 412      * @since 1.5
 413      */
 414     public void preferProportionalFonts() {
 415         FontManager fm = FontManagerFactory.getInstance();
 416         fm.preferProportionalFonts();
 417     }
 418 
 419     /**
 420      * Returns the Point where Windows should be centered.
 421      * It is recommended that centered Windows be checked to ensure they fit
 422      * within the available display area using getMaximumWindowBounds().
 423      * @return the point where Windows should be centered
 424      *
 425      * @exception HeadlessException if isHeadless() returns true
 426      * @see #getMaximumWindowBounds
 427      * @since 1.4
 428      */
 429     public Point getCenterPoint() throws HeadlessException {
 430     // Default implementation: return the center of the usable bounds of the
 431     // default screen device.
 432         Rectangle usableBounds =
 433          SunGraphicsEnvironment.getUsableBounds(getDefaultScreenDevice());
 434         return new Point((usableBounds.width / 2) + usableBounds.x,
 435                          (usableBounds.height / 2) + usableBounds.y);
 436     }
 437 
 438     /**
 439      * Returns the maximum bounds for centered Windows.
 440      * These bounds account for objects in the native windowing system such as
 441      * task bars and menu bars.  The returned bounds will reside on a single
 442      * display with one exception: on multi-screen systems where Windows should
 443      * be centered across all displays, this method returns the bounds of the
 444      * entire display area.
 445      * <p>
 446      * To get the usable bounds of a single display, use
 447      * {@code GraphicsConfiguration.getBounds()} and
 448      * {@code Toolkit.getScreenInsets()}.
 449      * @return  the maximum bounds for centered Windows
 450      *
 451      * @exception HeadlessException if isHeadless() returns true
 452      * @see #getCenterPoint
 453      * @see GraphicsConfiguration#getBounds
 454      * @see Toolkit#getScreenInsets
 455      * @since 1.4
 456      */
 457     public Rectangle getMaximumWindowBounds() throws HeadlessException {
 458     // Default implementation: return the usable bounds of the default screen
 459     // device.  This is correct for Microsoft Windows and non-Xinerama X11.
 460         return SunGraphicsEnvironment.getUsableBounds(getDefaultScreenDevice());
 461     }
 462 }
--- EOF ---