829N/A Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved. 829N/A DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 829N/A This code is free software; you can redistribute it and/or modify it 829N/A under the terms of the GNU General Public License version 2 only, as 829N/A published by the Free Software Foundation. Sun designates this 829N/A particular file as subject to the "Classpath" exception as provided 829N/A by Sun in the LICENSE file that accompanied this code. 829N/A This code is distributed in the hope that it will be useful, but WITHOUT 829N/A ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 829N/A FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 829N/A version 2 for more details (a copy is included in the LICENSE file that 829N/A accompanied this code). 829N/A You should have received a copy of the GNU General Public License version 829N/A 2 along with this work; if not, write to the Free Software Foundation, 829N/A Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 829N/A Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 829N/A<
h1 align=center>AWT Desktop Properties</
h1>
829N/AThe following refers to standard AWT desktop properties that
829N/AEach desktop property is named by a unique string, which
829N/Ais the "name" of that property.
829N/ADesktop properties supported by the AWT but not documented
829N/Aelsewhere - typically because there is no suitable
829N/Amethod or class - are documented here.
829N/ADesktop properties documented elsewhere are those which are
829N/Atightly coupled with a method or class which documents them.
829N/ASince desktop properties abstract an underlying platform
829N/Asetting, they may not be available in environments that do
829N/Anot support them. In the event that a desktop property is
829N/Aunavailable for any reason, the implementation will return
The following table summarizes the desktop properties documented
here, and their value types.
<
table align="center" border="0" cellspacing="0" cellpadding="2" width="%95 summary="Standard AWT Desktop Properties"> <th valign="TOP" align="LEFT">Property Name</th> <th valign="TOP" align="LEFT">Value Type</th> <th valign="TOP" align="LEFT">Summary Description</th> <td valign="TOP">Font smoothing (text antialiasing) settings.<a/></td> <h2>Desktop Font Rendering Hints</h2> Modern desktops support various forms of text antialiasing (font smoothing). These are applied by platform-specific heavyweight components. However an application may want to render text using the same text antialiasing on a drawing surface or lightweight (non-platform) component using This is particularly important when creating are required to appear consistent with native desktop components or other The standard desktop property named can be used to obtain the rendering hints that best match the desktop settings. can be directly applied to a <code>Graphics2D</code>. It is a <code>Map</code> as more than one hint may be needed. If non-null this can be directly applied to the <code>Graphics2D</code>. <h3>Advanced Usage Tips</h3> <h4>Listening for changes</h4> An application can listen for changes in the property <code>PropertyChangeListener</code></a> : Listening for changes is recommended as users can, on rare occasions, reconfigure a desktop environment whilst applications are running in a way that may affect the selection of these hints, and furthermore many desktop environments support dynamic reconfiguration of these running applications to conform to the new settings. There is no direct way to discover if dynamic reconfiguration is expected of running applications but the default assumption should be that it is expected, since most modern desktop environments do provide this capability. <h4>Text Measurement</h4> Text always needs to be measured using the same as used for rendering. The text anti-aliasing hint is a component of the <code>FontRenderContext</code>. obtained from the <code>Graphics</code> object on which the hint has been set will measure text appropriately. This is not a unique requirement for clients that specify this hint directly, since the value of the <code>FontRenderContext</code> should never be assumed, so is discussed here principally as a reminder. <h4>Saving and restoring Graphics State</h4> Sometimes an application may need to apply these hints on a shared Graphics only temporarily, restoring the previous values after they have been applied to text rendering operations. The following sample code shows one way to do this. * Get rendering hints from a Graphics instance. * "hintsToSave" is a Map of RenderingHint key-values. * For each hint key present in that map, the value of that * hint is obtained from the Graphics and stored as the value * for the key in savedHints. RenderingHints getRenderingHints(Graphics2D g2d, RenderingHints hintsToSave, RenderingHints savedHints) { if (savedHints == null) { savedHints = new RenderingHints(null); oldHints = getRenderingHints(graphic2D, map, null); <li>The return value will always be null or a <code>Map</code> <li>If the return value is null, then no desktop properties are available, and dynamic updates will not be available. This is a typical behaviour if the JDK does not recognise the desktop environment, or it is one which has no such settings. The <b>Headless</b> toolkit is one such example. Therefore it is important to test against null before using the map. <li>If non-null the value will be a <code>Map</code> of <code>RenderingHints</code> such that every key is an instance of <li>The map may contain the default value for a hint. This is needed in the event there is a previously a non-default value for the hint set on the <code>Graphics2D</code>. If the map did not contain the default value, then <code>addRenderingHints(Map)</code> would leave the previous hint which may not correspond to the desktop setting. An application can use <code>setRenderingHints(Map)</code> to reinitialise all hints, but this would affect unrelated hints too. <li>A multi-screen desktop may support per-screen device settings in which case the returned value is for the default screen of the desktop. An application may want to use the settings for the screen on which they will be applied. The per-screen device hints may be obtained by per-device property names which are constructed as the String concatenation An application can also listen for changes on these properties. However this is an extremely unlikely configuration, so to help ease of development, if only a single, desktop-wide setting is supported, then querying each of these per-device settings will return null. So to determine if there are per-device settings it is sufficient to determine that there is a non-null return for any screen device using the per-device property name.