Home » openjdk-7 » java » awt » [javadoc | source]

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

Home » openjdk-7 » java » awt » [javadoc | source]