|
2
|
1 |
<!--
|
|
|
2 |
Copyright 2005-2006 Sun Microsystems, Inc. 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. Sun designates this
|
|
|
8 |
particular file as subject to the "Classpath" exception as provided
|
|
|
9 |
by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
|
|
|
22 |
CA 95054 USA or visit www.sun.com if you need additional information or
|
|
|
23 |
have any questions.
|
|
|
24 |
-->
|
|
|
25 |
|
|
|
26 |
<html>
|
|
|
27 |
<body bgcolor=white>
|
|
|
28 |
|
|
|
29 |
<h1 align=center>AWT Desktop Properties</h1>
|
|
|
30 |
|
|
|
31 |
The following refers to standard AWT desktop properties that
|
|
|
32 |
may be obtained via the
|
|
|
33 |
<a href="../Toolkit.html#getDesktopProperty(java.lang.String)">
|
|
|
34 |
<code>Toolkit.getDesktopProperty</code></a> method.
|
|
|
35 |
<p>
|
|
|
36 |
Each desktop property is named by a unique string, which
|
|
|
37 |
is the "name" of that property.
|
|
|
38 |
<p>
|
|
|
39 |
Desktop properties supported by the AWT but not documented
|
|
|
40 |
elsewhere - typically because there is no suitable
|
|
|
41 |
method or class - are documented here.
|
|
|
42 |
<p>
|
|
|
43 |
Desktop properties documented elsewhere are those which are
|
|
|
44 |
tightly coupled with a method or class which documents them.
|
|
|
45 |
<p>
|
|
|
46 |
Since desktop properties abstract an underlying platform
|
|
|
47 |
setting, they may not be available in environments that do
|
|
|
48 |
not support them. In the event that a desktop property is
|
|
|
49 |
unavailable for any reason, the implementation will return
|
|
|
50 |
<code>null</code>.
|
|
|
51 |
<p>
|
|
|
52 |
The following table summarizes the desktop properties documented
|
|
|
53 |
here, and their value types.
|
|
|
54 |
<p>
|
|
|
55 |
<table align="center" border="0" cellspacing="0" cellpadding="2" width="%95
|
|
|
56 |
summary="Standard AWT Desktop Properties">
|
|
|
57 |
<tr bgcolor="#ccccff">
|
|
|
58 |
<th valign="TOP" align="LEFT">Property Name</th>
|
|
|
59 |
<th valign="TOP" align="LEFT">Value Type</th>
|
|
|
60 |
<th valign="TOP" align="LEFT">Summary Description</th>
|
|
|
61 |
</tr>
|
|
|
62 |
<tr>
|
|
|
63 |
<td valign="TOP"><A href=#awt.font.desktophints>awt.font.desktophints</A</td>
|
|
|
64 |
<td valign="TOP"><a href="../../util/Map.html">java.util.Map<a/></td>
|
|
|
65 |
<td valign="TOP">Font smoothing (text antialiasing) settings.<a/></td>
|
|
|
66 |
</tr>
|
|
|
67 |
</table>
|
|
|
68 |
<p>
|
|
|
69 |
<h2>Desktop Font Rendering Hints</h2>
|
|
|
70 |
<b>Desktop Property: <A name="awt.font.desktophints">"awt.font.desktophints"</A></b>
|
|
|
71 |
<p>
|
|
|
72 |
Modern desktops support various forms of text antialiasing (font smoothing).
|
|
|
73 |
<p>
|
|
|
74 |
These are applied by platform-specific heavyweight components.
|
|
|
75 |
However an application may want to render text using the same text
|
|
|
76 |
antialiasing on a drawing surface or lightweight (non-platform) component using
|
|
|
77 |
<a href="../Graphics2D.html"> <code>Graphics2D</code></a> methods.
|
|
|
78 |
This is particularly important when creating
|
|
|
79 |
<a href="../../../javax/swing/JComponent.html"> Swing components</a> which
|
|
|
80 |
are required to appear consistent with native desktop components or other
|
|
|
81 |
Swing components.
|
|
|
82 |
<p>
|
|
|
83 |
<h3>Basic Usage</h3>
|
|
|
84 |
The standard desktop property named
|
|
|
85 |
<b>"awt.font.desktophints"</b>
|
|
|
86 |
can be used to obtain the rendering hints that best match the desktop settings.
|
|
|
87 |
|
|
|
88 |
The return value is a
|
|
|
89 |
<a href="../../util/Map.html"> Map<a/> of
|
|
|
90 |
<a href="../RenderingHints.html"> <code>RenderingHints</code></a> which
|
|
|
91 |
can be directly applied to a <code>Graphics2D</code>.
|
|
|
92 |
<p>
|
|
|
93 |
It is a <code>Map</code> as more than one hint may be needed.
|
|
|
94 |
If non-null this can be directly applied to the <code>Graphics2D</code>.
|
|
|
95 |
<pre><code>
|
|
|
96 |
Toolkit tk = Toolkit.getDefaultToolkit();
|
|
|
97 |
Map map = (Map)(tk.getDesktopProperty("awt.font.desktophints"));
|
|
|
98 |
if (map != null) {
|
|
|
99 |
graphics2D.addRenderingHints(map);
|
|
|
100 |
}
|
|
|
101 |
</code></pre>
|
|
|
102 |
<h3>Advanced Usage Tips</h3>
|
|
|
103 |
<p>
|
|
|
104 |
<h4>Listening for changes</h4>
|
|
|
105 |
<p>
|
|
|
106 |
An application can listen for changes in the property
|
|
|
107 |
using a <a href="../../beans/PropertyChangeListener.html">
|
|
|
108 |
<code>PropertyChangeListener</code></a> :
|
|
|
109 |
<pre><code>
|
|
|
110 |
tk.addPropertyChangeListener("awt.font.desktophints", pcl);
|
|
|
111 |
</code></pre>
|
|
|
112 |
Listening for changes is recommended as users can, on rare occasions,
|
|
|
113 |
reconfigure a desktop environment whilst applications are running
|
|
|
114 |
in a way that may affect the selection of these hints, and furthermore
|
|
|
115 |
many desktop environments support dynamic reconfiguration of these
|
|
|
116 |
running applications to conform to the new settings.
|
|
|
117 |
<p>
|
|
|
118 |
There is no direct way to discover if dynamic reconfiguration
|
|
|
119 |
is expected of running applications but the default assumption
|
|
|
120 |
should be that it is expected, since most modern desktop environments
|
|
|
121 |
do provide this capability.
|
|
|
122 |
<h4>Text Measurement</h4>
|
|
|
123 |
<p>
|
|
|
124 |
Text always needs to be measured using the same
|
|
|
125 |
<a href="../font/FontRenderContext.html"> <code>FontRenderContext</code></a>
|
|
|
126 |
as used for rendering. The text anti-aliasing hint is a component of
|
|
|
127 |
the <code>FontRenderContext</code>.
|
|
|
128 |
A <a href="../FontMetrics.html"> <code>FontMetrics</code></a>
|
|
|
129 |
obtained from the <code>Graphics</code> object on which the hint
|
|
|
130 |
has been set will measure text appropriately.
|
|
|
131 |
This is not a unique requirement for clients that specify this hint
|
|
|
132 |
directly, since the value of the <code>FontRenderContext</code> should
|
|
|
133 |
never be assumed, so is discussed here principally as a reminder.
|
|
|
134 |
<h4>Saving and restoring Graphics State</h4>
|
|
|
135 |
<p>
|
|
|
136 |
Sometimes an application may need to apply these hints on a shared
|
|
|
137 |
Graphics only temporarily, restoring the previous values after they
|
|
|
138 |
have been applied to text rendering operations.
|
|
|
139 |
The following sample code shows one way to do this.
|
|
|
140 |
<pre><code>
|
|
|
141 |
/**
|
|
|
142 |
* Get rendering hints from a Graphics instance.
|
|
|
143 |
* "hintsToSave" is a Map of RenderingHint key-values.
|
|
|
144 |
* For each hint key present in that map, the value of that
|
|
|
145 |
* hint is obtained from the Graphics and stored as the value
|
|
|
146 |
* for the key in savedHints.
|
|
|
147 |
*/
|
|
|
148 |
RenderingHints getRenderingHints(Graphics2D g2d,
|
|
|
149 |
RenderingHints hintsToSave,
|
|
|
150 |
RenderingHints savedHints) {
|
|
|
151 |
if (savedHints == null) {
|
|
|
152 |
savedHints = new RenderingHints(null);
|
|
|
153 |
} else {
|
|
|
154 |
savedHints.clear();
|
|
|
155 |
}
|
|
|
156 |
if (hintsToSave.size() == 0) {
|
|
|
157 |
return savedHints;
|
|
|
158 |
}
|
|
|
159 |
/* RenderingHints.keySet() returns Set<Object> */
|
|
|
160 |
for (Object o : hintsToSave.keySet()) {
|
|
|
161 |
RenderingHints.Key key = (RenderingHints.Key)o;
|
|
|
162 |
Object value = g2d.getRenderingHint(key);
|
|
|
163 |
savedHints.put(key, value);
|
|
|
164 |
}
|
|
|
165 |
return savedHints;
|
|
|
166 |
}
|
|
|
167 |
|
|
|
168 |
|
|
|
169 |
Toolkit tk = Toolkit.getDefaultToolkit();
|
|
|
170 |
Map map = (Map)(tk.getDesktopProperty("awt.font.desktophints"));
|
|
|
171 |
Map oldHints;
|
|
|
172 |
if (map != null) {
|
|
|
173 |
oldHints = getRenderingHints(graphic2D, map, null);
|
|
|
174 |
graphics2D.addRenderingHints(map);
|
|
|
175 |
..
|
|
|
176 |
graphics2D.addRenderingHints(oldHints);
|
|
|
177 |
}
|
|
|
178 |
</code></pre>
|
|
|
179 |
|
|
|
180 |
<h3>Details</h3>
|
|
|
181 |
<ul>
|
|
|
182 |
<li>The return value will always be null or a <code>Map</code>
|
|
|
183 |
<p>
|
|
|
184 |
<li>If the return value is null, then no desktop properties are available,
|
|
|
185 |
and dynamic updates will not be available. This is a typical behaviour if
|
|
|
186 |
the JDK does not recognise the desktop environment, or it is one which
|
|
|
187 |
has no such settings. The <b>Headless</b> toolkit is one such example.
|
|
|
188 |
Therefore it is important to test against null before using the map.
|
|
|
189 |
<p>
|
|
|
190 |
<li>If non-null the value will be a <code>Map</code> of
|
|
|
191 |
<code>RenderingHints</code> such that every key is an instance of
|
|
|
192 |
<code>RenderingHints.Key</code> and the value is a legal value for that key.
|
|
|
193 |
<p>
|
|
|
194 |
<li>The map may contain the default value for a hint. This is
|
|
|
195 |
needed in the event there is a previously a non-default value for the hint
|
|
|
196 |
set on the <code>Graphics2D</code>. If the map did not contain
|
|
|
197 |
the default value, then <code>addRenderingHints(Map)</code> would leave
|
|
|
198 |
the previous hint which may not correspond to the desktop setting.
|
|
|
199 |
<p>
|
|
|
200 |
An application can use <code>setRenderingHints(Map)</code> to reinitialise
|
|
|
201 |
all hints, but this would affect unrelated hints too.
|
|
|
202 |
<p>
|
|
|
203 |
<li>A multi-screen desktop may support per-screen device settings in which
|
|
|
204 |
case the returned value is for the default screen of the desktop.
|
|
|
205 |
An application may want to use the settings for the screen on
|
|
|
206 |
which they will be applied.
|
|
|
207 |
The per-screen device hints may be obtained by per-device property names
|
|
|
208 |
which are constructed as the String concatenation
|
|
|
209 |
<pre><code>
|
|
|
210 |
"awt.font.desktophints" + "." + GraphicsDevice.getIDstring();
|
|
|
211 |
</code></pre>
|
|
|
212 |
<p>
|
|
|
213 |
An application can also listen for changes on these properties.
|
|
|
214 |
<p>
|
|
|
215 |
However this is an extremely unlikely configuration, so to help
|
|
|
216 |
ease of development, if only a single, desktop-wide setting is supported,
|
|
|
217 |
then querying each of these per-device settings will return null.
|
|
|
218 |
So to determine if there are per-device settings it is sufficient to
|
|
|
219 |
determine that there is a non-null return for any screen device using
|
|
|
220 |
the per-device property name.
|
|
|
221 |
</ul>
|
|
|
222 |
</body>
|
|
|
223 |
</html>
|