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

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

author	serb
	Thu, 31 May 2018 09:52:32 -0700
changeset 50358	1ba28f0dbc33
parent 48264	efda6932a433
child 52831	4e9739110cf1
permissions	-rw-r--r--