jdk-sandbox: src/java.desktop/share/classes/java/awt/doc-files/DesktopProperties.html@71c04702a3d5 (annotated)

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

author	erikj
	Tue, 12 Sep 2017 19:03:39 +0200
changeset 47216	71c04702a3d5
parent 25859	jdk/src/java.desktop/share/classes/java/awt/doc-files/DesktopProperties.html@3317bb8137f4
child 48264	efda6932a433
permissions	-rw-r--r--