1 <!doctype html>
   2 <html lang="en">
   3 <head>
   4   <meta charset="utf-8"/>
   5   <title>AWT Desktop Properties</title>
   6 </head>
   7 <!--
   8  Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
  11  This code is free software; you can redistribute it and/or modify it
  12  under the terms of the GNU General Public License version 2 only, as
  13  published by the Free Software Foundation.  Oracle designates this
  14  particular file as subject to the "Classpath" exception as provided
  15  by Oracle in the LICENSE file that accompanied this code.
  17  This code is distributed in the hope that it will be useful, but WITHOUT
  18  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20  version 2 for more details (a copy is included in the LICENSE file that
  21  accompanied this code).
  23  You should have received a copy of the GNU General Public License version
  24  2 along with this work; if not, write to the Free Software Foundation,
  25  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  27  Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  28  or visit www.oracle.com if you need additional information or have any
  29  questions.
  30 -->
  32 <body>
  34 <h1>AWT Desktop Properties</h1>
  36 The following refers to standard AWT desktop properties that
  37 may be obtained via the
  38 <a href="../Toolkit.html#getDesktopProperty(java.lang.String)">
  39 <code>Toolkit.getDesktopProperty</code></a> method.
  40 <p>
  41 Each desktop property is named by a unique string, which
  42 is the "name" of that property.
  43 <p>
  44 Desktop properties supported by the AWT but not documented
  45 elsewhere - typically because there is no suitable
  46 method or class - are documented here.
  47 <p>
  48 Desktop properties documented elsewhere are those which are
  49 tightly coupled with a method or class which documents them.
  50 <p>
  51 Since desktop properties abstract an underlying platform
  52 setting, they may not be available in environments that do
  53 not support them. In the event that a desktop property is
  54 unavailable for any reason, the implementation will return
  55 <code>null</code>.
  56 <p>
  57 The following table summarizes the desktop properties documented
  58 here, and their value types.
  59 <br><br>
  60 <table align="center" border="0" cellspacing="0" cellpadding="2"
  61   summary="Standard AWT Desktop Properties">
  62 <tr bgcolor="#ccccff">
  63 <th valign="TOP" align="LEFT">Property Name</th>
  64 <th valign="TOP" align="LEFT">Value Type</th>
  65 <th valign="TOP" align="LEFT">Summary Description</th>
  66 </tr>
  67 <tr>
  68 <td valign="TOP"><A href="#awt.font.desktophints">awt.font.desktophints</A></td>
  69 <td valign="TOP"><a href="../../util/Map.html">java.util.Map</a></td>
  70 <td valign="TOP">Font smoothing (text antialiasing) settings.</td>
  71 </tr>
  72 <tr>
  73 <td valign="TOP"><A href="#sun.awt.enableExtraMouseButtons">sun.awt.enableExtraMouseButtons</A></td>
  74 <td valign="TOP"><a href="../../lang/Boolean.html">java.lang.Boolean</a></td>
  75 <td valign="TOP">Controls if mouse events from extra buttons are to be generated or not</td>
  76 </tr>
  77 </table>
  79 <h2>Desktop Font Rendering Hints</h2>
  80 <b>Desktop Property: <a id="awt.font.desktophints">"awt.font.desktophints"</A></b>
  81 <p>
  82 Modern desktops support various forms of text antialiasing (font smoothing).
  83 <p>
  84 These are applied by platform-specific heavyweight components.
  85 However an application may want to render text using the same text
  86 antialiasing on a drawing surface or lightweight (non-platform) component using
  87 <a href="../Graphics2D.html"> <code>Graphics2D</code></a> methods.
  88 This is particularly important when creating
  89 <a href="../../../javax/swing/JComponent.html"> Swing components</a> which
  90 are required to appear consistent with native desktop components or other
  91 Swing components.
  93 <h3>Basic Usage</h3>
  94 The standard desktop property named
  95 <b>"awt.font.desktophints"</b>
  96 can be used to obtain the rendering hints that best match the desktop settings.
  98 The return value is a
  99 <a href="../../util/Map.html"> Map</a> of
 100 <a href="../RenderingHints.html"> <code>RenderingHints</code></a> which
 101 can be directly applied to a <code>Graphics2D</code>.
 102 <p>
 103 It is a <code>Map</code> as more than one hint may be needed.
 104 If non-null this can be directly applied to the <code>Graphics2D</code>.
 105 <pre><code>
 106 Toolkit tk = Toolkit.getDefaultToolkit();
 107 Map map = (Map)(tk.getDesktopProperty("awt.font.desktophints"));
 108 if (map != null) {
 109     graphics2D.addRenderingHints(map);
 110 }
 111 </code></pre>
 112 <h3>Advanced Usage Tips</h3>
 114 <h4>Listening for changes</h4>
 115 <p>
 116 An application can listen for changes in the property
 117 using a <a href="../../beans/PropertyChangeListener.html">
 118 <code>PropertyChangeListener</code></a> :
 119 <pre><code>
 120 tk.addPropertyChangeListener("awt.font.desktophints", pcl);
 121 </code></pre>
 122 Listening for changes is recommended as users can, on rare occasions,
 123 reconfigure a desktop environment whilst applications are running
 124 in a way that may affect the selection of these hints, and furthermore
 125 many desktop environments support dynamic reconfiguration of these
 126 running applications to conform to the new settings.
 127 <p>
 128 There is no direct way to discover if dynamic reconfiguration
 129 is expected of running applications but the default assumption
 130 should be that it is expected, since most modern desktop environments
 131 do provide this capability.
 132 <h4>Text Measurement</h4>
 133 <p>
 134 Text always needs to be measured using the same
 135 <a href="../font/FontRenderContext.html"> <code>FontRenderContext</code></a>
 136 as used for rendering. The text anti-aliasing hint is a component of
 137 the <code>FontRenderContext</code>.
 138 A <a href="../FontMetrics.html"> <code>FontMetrics</code></a>
 139 obtained from the <code>Graphics</code> object on which the hint
 140 has been set will measure text appropriately.
 141 This is not a unique requirement for clients that specify this hint
 142 directly, since the value of the <code>FontRenderContext</code> should
 143 never be assumed, so is discussed here principally as a reminder.
 144 <h4>Saving and restoring Graphics State</h4>
 145 <p>
 146 Sometimes an application may need to apply these hints on a shared
 147 Graphics only temporarily, restoring the previous values after they
 148 have been applied to text rendering operations.
 149 The following sample code shows one way to do this.
 150 <pre><code>
 151 /**
 152   * Get rendering hints from a Graphics instance.
 153   * "hintsToSave" is a Map of RenderingHint key-values.
 154   * For each hint key present in that map, the value of that
 155   * hint is obtained from the Graphics and stored as the value
 156   * for the key in savedHints.
 157   */
 158 RenderingHints getRenderingHints(Graphics2D g2d,
 159                                   RenderingHints hintsToSave,
 160                                   RenderingHints savedHints) {
 161      if (savedHints == null) {
 162          savedHints = new RenderingHints(null);
 163      } else {
 164          savedHints.clear();
 165      }
 166      if (hintsToSave.size() == 0) {
 167          return savedHints;
 168      }
 169      /* RenderingHints.keySet() returns Set&lt;Object&gt; */
 170      for (Object o : hintsToSave.keySet()) {
 171          RenderingHints.Key key = (RenderingHints.Key)o;
 172          Object value = g2d.getRenderingHint(key);
 173          savedHints.put(key, value);
 174      }
 175      return savedHints;
 176 }
 179 Toolkit tk = Toolkit.getDefaultToolkit();
 180 Map map = (Map)(tk.getDesktopProperty("awt.font.desktophints"));
 181 Map oldHints;
 182 if (map != null) {
 183      oldHints = getRenderingHints(graphic2D, map, null);
 184      graphics2D.addRenderingHints(map);
 185      ..
 186      graphics2D.addRenderingHints(oldHints);
 187 }
 188 </code></pre>
 190 <h3>Details</h3>
 191 <ul>
 192 <li>The return value will always be null or a <code>Map</code>
 193 <br><br>
 194 <li>If the return value is null, then no desktop properties are available,
 195 and dynamic updates will not be available. This is a typical behaviour if
 196 the JDK does not recognise the desktop environment, or it is one which
 197 has no such settings. The <b>Headless</b> toolkit is one such example.
 198 Therefore it is important to test against null before using the map.
 199 <br><br>
 200 <li>If non-null the value will be a <code>Map</code> of
 201 <code>RenderingHints</code> such that every key is an instance of
 202 <code>RenderingHints.Key</code> and the value is a legal value for that key.
 203 <br><br>
 204 <li>The map may contain the default value for a hint. This is
 205 needed in the event there is a previously a non-default value for the hint
 206 set on the <code>Graphics2D</code>. If the map did not contain
 207 the default value, then <code>addRenderingHints(Map)</code> would leave
 208 the previous hint which may not correspond to the desktop setting.
 209 <p>
 210 An application can use <code>setRenderingHints(Map)</code> to reinitialise
 211 all hints, but this would affect unrelated hints too.
 212 <br><br>
 213 <li>A multi-screen desktop may support per-screen device settings in which
 214 case the returned value is for the default screen of the desktop.
 215 An application may want to use the settings for the screen on
 216 which they will be applied.
 217 The per-screen device hints may be obtained by per-device property names
 218 which are constructed as the String concatenation
 219 <pre><code>
 220 "awt.font.desktophints" + "." + GraphicsDevice.getIDstring();
 221 </code></pre>
 222 <p>
 223 An application can also listen for changes on these properties.
 224 <p>
 225 However this is an extremely unlikely configuration, so to help
 226 ease of development, if only a single, desktop-wide setting is supported,
 227 then querying each of these per-device settings will return null.
 228 So to determine if there are per-device settings it is sufficient to
 229 determine that there is a non-null return for any screen device using
 230 the per-device property name.
 231 </ul>
 232 <h2>Mouse Functionality</h2>
 233 <b>Desktop Property: <a id="sun.awt.enableExtraMouseButtons">"sun.awt.enableExtraMouseButtons"</A></b>
 234 <p>
 235 This property determines if events from extra mouse buttons (if they are exist and are
 236 enabled by the underlying operating system) are allowed to be processed and posted into
 237 {@code EventQueue}.
 238 <br>
 239 The value could be changed by passing "sun.awt.enableExtraMouseButtons"
 240 property value into java before application starts. This could be done with the following command:
 241 <pre>
 242 java -Dsun.awt.enableExtraMouseButtons=false Application
 243 </pre>
 244 Once set on application startup, it is impossible to change this value after.
 245 <br>
 246 Current value could also be queried using getDesktopProperty("sun.awt.enableExtraMouseButtons")
 247 method.
 248 <br>
 249 If the property is set to {@code true} then
 250 <ul>
 251 <li> it is still legal to create {@code MouseEvent} objects with
 252 standard buttons and, if the mouse has more
 253 then three buttons, it is also legal to use buttons from the range started
 254 from 0 up to {@link java.awt.MouseInfo#getNumberOfButtons() getNumberOfButtons()}.
 256 <li> it is legal to use standard button masks when using {@code Robot.mousePress()}
 257 and {@code Robot.mouseRelease()} methods and, if the mouse has more then three buttons,
 258 it is also legal to use masks for existing extended mouse buttons.
 259 That way, if there are more then three buttons on the mouse then it is allowed to
 260 use button masks corresponding to the buttons
 261 in the range from 1 up to {@link java.awt.MouseInfo#getNumberOfButtons() getNumberOfButtons()}
 262 </ul>
 263 <br>
 264 If the property is set to {@code false} then
 265 <ul>
 266 <li> it is legal to create {@code MouseEvent} objects with standard buttons
 267 only: {@code NOBUTTON}, {@code BUTTON1}, {@code BUTTON2} and
 268 {@code BUTTON3}
 269 <li> it is legal to use standard button masks only:
 270 {@code InputEvent.BUTTON1_DOWN_MASK}, {@code InputEvent.BUTTON2_DOWN_MASK},
 271 {@code InputEvent.BUTTON3_DOWN_MASK}
 272 </ul>
 274 This property should be used when there is no need in listening mouse events fired as a result of
 275 activity with extra mouse button.
 276 By default this property is set to {@code true}.
 277 </body>
 278 </html>