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