2362N/A Copyright (c) 2005, 2008, Oracle and/or its affiliates. All rights reserved. 0N/A DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A This code is free software; you can redistribute it and/or modify it 0N/A under the terms of the GNU General Public License version 2 only, as 2362N/A published by the Free Software Foundation. Oracle designates this 0N/A particular file as subject to the "Classpath" exception as provided 2362N/A by Oracle in the LICENSE file that accompanied this code. 0N/A This code is distributed in the hope that it will be useful, but WITHOUT 0N/A ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A version 2 for more details (a copy is included in the LICENSE file that 0N/A accompanied this code). 0N/A You should have received a copy of the GNU General Public License version 0N/A 2 along with this work; if not, write to the Free Software Foundation, 0N/A Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A<
h1 align=center>AWT Desktop Properties</
h1>
0N/AThe following refers to standard AWT desktop properties that
0N/Amay be obtained via the
0N/AEach desktop property is named by a unique string, which
0N/Ais the "name" of that property.
0N/ADesktop properties supported by the AWT but not documented
0N/Aelsewhere - typically because there is no suitable
0N/Amethod or class - are documented here.
0N/ADesktop properties documented elsewhere are those which are
0N/Atightly coupled with a method or class which documents them.
0N/ASince desktop properties abstract an underlying platform
0N/Asetting, they may not be available in environments that do
0N/Anot support them. In the event that a desktop property is
0N/Aunavailable for any reason, the implementation will return
0N/AThe following table summarizes the desktop properties documented
0N/Ahere, and their value types.
0N/A<
table align="center" border="0" cellspacing="0" cellpadding="2" width="%95 0N/A summary="Standard AWT Desktop Properties"> 0N/A<tr bgcolor="#
ccccff"> 0N/A<th valign="TOP" align="LEFT">Property Name</th> 0N/A<th valign="TOP" align="LEFT">Value Type</th> 0N/A<th valign="TOP" align="LEFT">Summary Description</th> 0N/A<td valign="TOP">Font smoothing (text antialiasing) settings.<a/></td> 870N/A<td valign="TOP">Controls if mouse events from extra buttons are to be generated or not<a/></td> 0N/A<h2>Desktop Font Rendering Hints</h2> 0N/AModern desktops support various forms of text antialiasing (font smoothing). 0N/AThese are applied by platform-specific heavyweight components. 0N/AHowever an application may want to render text using the same text 0N/Aantialiasing on a drawing surface or lightweight (non-platform) component using 0N/AThis is particularly important when creating 0N/Aare required to appear consistent with native desktop components or other 0N/AThe standard desktop property named 0N/Acan be used to obtain the rendering hints that best match the desktop settings. 0N/AThe return value is a 0N/Acan be directly applied to a <code>Graphics2D</code>. 0N/AIt is a <code>Map</code> as more than one hint may be needed. 0N/AIf non-null this can be directly applied to the <code>Graphics2D</code>. 0N/A<h3>Advanced Usage Tips</h3> 0N/A<h4>Listening for changes</h4> 0N/AAn application can listen for changes in the property 0N/A<code>PropertyChangeListener</code></a> : 0N/AListening for changes is recommended as users can, on rare occasions, 0N/Areconfigure a desktop environment whilst applications are running 0N/Ain a way that may affect the selection of these hints, and furthermore 0N/Amany desktop environments support dynamic reconfiguration of these 0N/Arunning applications to conform to the new settings. 0N/AThere is no direct way to discover if dynamic reconfiguration 0N/Ais expected of running applications but the default assumption 0N/Ashould be that it is expected, since most modern desktop environments 0N/Ado provide this capability. 0N/A<h4>Text Measurement</h4> 0N/AText always needs to be measured using the same 0N/Aas used for rendering. The text anti-aliasing hint is a component of 0N/Athe <code>FontRenderContext</code>. 0N/Aobtained from the <code>Graphics</code> object on which the hint 0N/Ahas been set will measure text appropriately. 0N/AThis is not a unique requirement for clients that specify this hint 0N/Adirectly, since the value of the <code>FontRenderContext</code> should 0N/Anever be assumed, so is discussed here principally as a reminder. 0N/A<h4>Saving and restoring Graphics State</h4> 0N/ASometimes an application may need to apply these hints on a shared 0N/AGraphics only temporarily, restoring the previous values after they 0N/Ahave been applied to text rendering operations. 0N/AThe following sample code shows one way to do this. 0N/A * Get rendering hints from a Graphics instance. 0N/A * "hintsToSave" is a Map of RenderingHint key-values. 0N/A * For each hint key present in that map, the value of that 0N/A * hint is obtained from the Graphics and stored as the value 0N/A * for the key in savedHints. 0N/ARenderingHints getRenderingHints(Graphics2D g2d, 0N/A RenderingHints hintsToSave, 0N/A RenderingHints savedHints) { 0N/A if (savedHints == null) { 0N/A savedHints = new RenderingHints(null); 0N/A oldHints = getRenderingHints(graphic2D, map, null); 0N/A<li>The return value will always be null or a <code>Map</code> 0N/A<li>If the return value is null, then no desktop properties are available, 0N/Aand dynamic updates will not be available. This is a typical behaviour if 0N/Athe JDK does not recognise the desktop environment, or it is one which 0N/Ahas no such settings. The <b>Headless</b> toolkit is one such example. 0N/ATherefore it is important to test against null before using the map. 0N/A<li>If non-null the value will be a <code>Map</code> of 0N/A<code>RenderingHints</code> such that every key is an instance of 0N/A<li>The map may contain the default value for a hint. This is 0N/Aneeded in the event there is a previously a non-default value for the hint 0N/Aset on the <code>Graphics2D</code>. If the map did not contain 0N/Athe default value, then <code>addRenderingHints(Map)</code> would leave 0N/Athe previous hint which may not correspond to the desktop setting. 0N/AAn application can use <code>setRenderingHints(Map)</code> to reinitialise 0N/Aall hints, but this would affect unrelated hints too. 0N/A<li>A multi-screen desktop may support per-screen device settings in which 0N/Acase the returned value is for the default screen of the desktop. 0N/AAn application may want to use the settings for the screen on 0N/Awhich they will be applied. 0N/AThe per-screen device hints may be obtained by per-device property names 0N/Awhich are constructed as the String concatenation 0N/AAn application can also listen for changes on these properties. 0N/AHowever this is an extremely unlikely configuration, so to help 0N/Aease of development, if only a single, desktop-wide setting is supported, 0N/Athen querying each of these per-device settings will return null. 0N/ASo to determine if there are per-device settings it is sufficient to 0N/Adetermine that there is a non-null return for any screen device using 0N/Athe per-device property name. 870N/A<h2>Mouse Functionality</h2> 870N/AThis property determines if events from extra mouse buttons (if they are exist and are 870N/Aenabled by the underlying operating system) are allowed to be processed and posted into 870N/Aproperty value into java before application starts. This could be done with the following command: 870N/AOnce set on application startup, it is impossible to change this value after. 870N/AIf the property is set to {@code true} then 870N/A<li> it is still legal to create {@code MouseEvent} objects with 870N/Astandard buttons and, if the mouse has more 870N/Athen three buttons, it is also legal to use buttons from the range started 870N/Ait is also legal to use masks for existing extended mouse buttons. 870N/AThat way, if there are more then three buttons on the mouse then it is allowed to 870N/Ause button masks corresponding to the buttons 870N/AIf the property is set to {@code false} then 870N/A<li> it is legal to create {@code MouseEvent} objects with standard buttons 870N/Aonly: {@code NOBUTTON}, {@code BUTTON1}, {@code BUTTON2} and 870N/A<li> it is legal to use standard button masks only: 870N/AThis property should be used when there is no need in listening mouse events fired as a result of 870N/Aactivity with extra mouse button. 870N/ABy default this property is set to {@code true}.