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, 2019, Oracle and/or its affiliates. All rights reserved. 9 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 10 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. 16 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). 22 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. 26 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 --> 31 32 <body> 33 <main role="main"> 34 <h1>AWT Desktop Properties</h1> 35 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 border=1> 61 <thead> 62 <tr> 63 <th scope="col">Property Name</th> 64 <th scope="col">Value Type</th> 65 <th scope="col">Summary Description</th> 66 </tr> 67 </thead> 68 <tbody> 69 <tr> 70 <th scope="row"><A href="#awt.font.desktophints">awt.font.desktophints</A></th> 71 <td>{@link java.util.Map java.util.Map}</td> 72 <td>Font smoothing (text antialiasing) settings.</td> 73 </tr> 74 <tr> 75 <th scope="row"><A href="#sun.awt.enableExtraMouseButtons">sun.awt.enableExtraMouseButtons</A></th> 76 <td>{@link java.lang.Boolean java.lang.Boolean}</td> 77 <td>Controls if mouse events from extra buttons are to be generated or not</td> 78 </tr> 79 </tbody> 80 </table> 81 82 <h2>Desktop Font Rendering Hints</h2> 83 <b>Desktop Property: <a id="awt.font.desktophints">"awt.font.desktophints"</A></b> 84 <p> 85 Modern desktops support various forms of text antialiasing (font smoothing). 86 <p> 87 These are applied by platform-specific heavyweight components. 88 However an application may want to render text using the same text 89 antialiasing on a drawing surface or lightweight (non-platform) component using 90 <a href="../Graphics2D.html"> <code>Graphics2D</code></a> methods. 91 This is particularly important when creating 92 <a href="../../../javax/swing/JComponent.html"> Swing components</a> which 93 are required to appear consistent with native desktop components or other 94 Swing components. 95 96 <h3>Basic Usage</h3> 97 The standard desktop property named 98 <b>"awt.font.desktophints"</b> 99 can be used to obtain the rendering hints that best match the desktop settings. 100 101 The return value is a 102 <a href="../../util/Map.html"> Map</a> of 103 <a href="../RenderingHints.html"> <code>RenderingHints</code></a> which 104 can be directly applied to a <code>Graphics2D</code>. 105 <p> 106 It is a <code>Map</code> as more than one hint may be needed. 107 If non-null this can be directly applied to the <code>Graphics2D</code>. 108 <pre><code> 109 Toolkit tk = Toolkit.getDefaultToolkit(); 110 Map map = (Map)(tk.getDesktopProperty("awt.font.desktophints")); 111 if (map != null) { 112 graphics2D.addRenderingHints(map); 113 } 114 </code></pre> 115 <h3>Advanced Usage Tips</h3> 116 117 <h4>Listening for changes</h4> 118 <p> 119 An application can listen for changes in the property 120 using a <a href="../../beans/PropertyChangeListener.html"> 121 <code>PropertyChangeListener</code></a> : 122 <pre><code> 123 tk.addPropertyChangeListener("awt.font.desktophints", pcl); 124 </code></pre> 125 Listening for changes is recommended as users can, on rare occasions, 126 reconfigure a desktop environment whilst applications are running 127 in a way that may affect the selection of these hints, and furthermore 128 many desktop environments support dynamic reconfiguration of these 129 running applications to conform to the new settings. 130 <p> 131 There is no direct way to discover if dynamic reconfiguration 132 is expected of running applications but the default assumption 133 should be that it is expected, since most modern desktop environments 134 do provide this capability. 135 <h4>Text Measurement</h4> 136 <p> 137 Text always needs to be measured using the same 138 <a href="../font/FontRenderContext.html"> <code>FontRenderContext</code></a> 139 as used for rendering. The text anti-aliasing hint is a component of 140 the <code>FontRenderContext</code>. 141 A <a href="../FontMetrics.html"> <code>FontMetrics</code></a> 142 obtained from the <code>Graphics</code> object on which the hint 143 has been set will measure text appropriately. 144 This is not a unique requirement for clients that specify this hint 145 directly, since the value of the <code>FontRenderContext</code> should 146 never be assumed, so is discussed here principally as a reminder. 147 <h4>Saving and restoring Graphics State</h4> 148 <p> 149 Sometimes an application may need to apply these hints on a shared 150 Graphics only temporarily, restoring the previous values after they 151 have been applied to text rendering operations. 152 The following sample code shows one way to do this. 153 <pre><code> 154 /** 155 * Get rendering hints from a Graphics instance. 156 * "hintsToSave" is a Map of RenderingHint key-values. 157 * For each hint key present in that map, the value of that 158 * hint is obtained from the Graphics and stored as the value 159 * for the key in savedHints. 160 */ 161 RenderingHints getRenderingHints(Graphics2D g2d, 162 RenderingHints hintsToSave, 163 RenderingHints savedHints) { 164 if (savedHints == null) { 165 savedHints = new RenderingHints(null); 166 } else { 167 savedHints.clear(); 168 } 169 if (hintsToSave.size() == 0) { 170 return savedHints; 171 } 172 /* RenderingHints.keySet() returns Set<Object> */ 173 for (Object o : hintsToSave.keySet()) { 174 RenderingHints.Key key = (RenderingHints.Key)o; 175 Object value = g2d.getRenderingHint(key); 176 savedHints.put(key, value); 177 } 178 return savedHints; 179 } 180 181 182 Toolkit tk = Toolkit.getDefaultToolkit(); 183 Map map = (Map)(tk.getDesktopProperty("awt.font.desktophints")); 184 Map oldHints; 185 if (map != null) { 186 oldHints = getRenderingHints(graphic2D, map, null); 187 graphics2D.addRenderingHints(map); 188 .. 189 graphics2D.addRenderingHints(oldHints); 190 } 191 </code></pre> 192 193 <h3>Details</h3> 194 <ul> 195 <li>The return value will always be null or a <code>Map</code> 196 <br><br> 197 <li>If the return value is null, then no desktop properties are available, 198 and dynamic updates will not be available. This is a typical behaviour if 199 the JDK does not recognise the desktop environment, or it is one which 200 has no such settings. The <b>Headless</b> toolkit is one such example. 201 Therefore it is important to test against null before using the map. 202 <br><br> 203 <li>If non-null the value will be a <code>Map</code> of 204 <code>RenderingHints</code> such that every key is an instance of 205 <code>RenderingHints.Key</code> and the value is a legal value for that key. 206 <br><br> 207 <li>The map may contain the default value for a hint. This is 208 needed in the event there is a previously a non-default value for the hint 209 set on the <code>Graphics2D</code>. If the map did not contain 210 the default value, then <code>addRenderingHints(Map)</code> would leave 211 the previous hint which may not correspond to the desktop setting. 212 <p> 213 An application can use <code>setRenderingHints(Map)</code> to reinitialise 214 all hints, but this would affect unrelated hints too. 215 <br><br> 216 <li>A multi-screen desktop may support per-screen device settings in which 217 case the returned value is for the default screen of the desktop. 218 An application may want to use the settings for the screen on 219 which they will be applied. 220 The per-screen device hints may be obtained by per-device property names 221 which are constructed as the String concatenation 222 <pre><code> 223 "awt.font.desktophints" + "." + GraphicsDevice.getIDstring(); 224 </code></pre> 225 <p> 226 An application can also listen for changes on these properties. 227 <p> 228 However this is an extremely unlikely configuration, so to help 229 ease of development, if only a single, desktop-wide setting is supported, 230 then querying each of these per-device settings will return null. 231 So to determine if there are per-device settings it is sufficient to 232 determine that there is a non-null return for any screen device using 233 the per-device property name. 234 </ul> 235 <h2>Mouse Functionality</h2> 236 <b>Desktop Property: <a id="sun.awt.enableExtraMouseButtons">"sun.awt.enableExtraMouseButtons"</A></b> 237 <p> 238 This property determines if events from extra mouse buttons (if they are exist and are 239 enabled by the underlying operating system) are allowed to be processed and posted into 240 {@code EventQueue}. 241 <br> 242 The value could be changed by passing "sun.awt.enableExtraMouseButtons" 243 property value into java before application starts. This could be done with the following command: 244 <pre> 245 java -Dsun.awt.enableExtraMouseButtons=false Application 246 </pre> 247 Once set on application startup, it is impossible to change this value after. 248 <br> 249 Current value could also be queried using getDesktopProperty("sun.awt.enableExtraMouseButtons") 250 method. 251 <br> 252 If the property is set to {@code true} then 253 <ul> 254 <li> it is still legal to create {@code MouseEvent} objects with 255 standard buttons and, if the mouse has more 256 then three buttons, it is also legal to use buttons from the range started 257 from 0 up to {@link java.awt.MouseInfo#getNumberOfButtons() getNumberOfButtons()}. 258 259 <li> it is legal to use standard button masks when using {@code Robot.mousePress()} 260 and {@code Robot.mouseRelease()} methods and, if the mouse has more then three buttons, 261 it is also legal to use masks for existing extended mouse buttons. 262 That way, if there are more then three buttons on the mouse then it is allowed to 263 use button masks corresponding to the buttons 264 in the range from 1 up to {@link java.awt.MouseInfo#getNumberOfButtons() getNumberOfButtons()} 265 </ul> 266 <br> 267 If the property is set to {@code false} then 268 <ul> 269 <li> it is legal to create {@code MouseEvent} objects with standard buttons 270 only: {@code NOBUTTON}, {@code BUTTON1}, {@code BUTTON2} and 271 {@code BUTTON3} 272 <li> it is legal to use standard button masks only: 273 {@code InputEvent.BUTTON1_DOWN_MASK}, {@code InputEvent.BUTTON2_DOWN_MASK}, 274 {@code InputEvent.BUTTON3_DOWN_MASK} 275 </ul> 276 277 This property should be used when there is no need in listening mouse events fired as a result of 278 activity with extra mouse button. 279 By default this property is set to {@code true}. 280 </main> 281 </body> 282 </html>