src/java.desktop/share/classes/java/awt/doc-files/DesktopProperties.html
author aivanov
Wed, 25 Sep 2019 22:45:43 +0100
changeset 58595 fa9f28a0e175
parent 58325 d32a3b1ca84a
child 58679 9c3209ff7550
permissions -rw-r--r--
8231144: Wrap contents of plain HTML files into contentContainer Reviewed-by: prr, serb
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
<!--
58325
d32a3b1ca84a 8225372: accessibility errors in tables in java.desktop files
serb
parents: 55366
diff changeset
     8
 Copyright (c) 2005, 2019, 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">
58595
fa9f28a0e175 8231144: Wrap contents of plain HTML files into contentContainer
aivanov
parents: 58325
diff changeset
    34
<div class="contentContainer">
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
    35
<h1>AWT Desktop Properties</h1>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    36
90ce3da70b43 Initial load
duke
parents:
diff changeset
    37
The following refers to standard AWT desktop properties that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    38
may be obtained via the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    39
<a href="../Toolkit.html#getDesktopProperty(java.lang.String)">
90ce3da70b43 Initial load
duke
parents:
diff changeset
    40
<code>Toolkit.getDesktopProperty</code></a> method.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    42
Each desktop property is named by a unique string, which
90ce3da70b43 Initial load
duke
parents:
diff changeset
    43
is the "name" of that property.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
Desktop properties supported by the AWT but not documented
90ce3da70b43 Initial load
duke
parents:
diff changeset
    46
elsewhere - typically because there is no suitable
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
method or class - are documented here.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    48
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    49
Desktop properties documented elsewhere are those which are
90ce3da70b43 Initial load
duke
parents:
diff changeset
    50
tightly coupled with a method or class which documents them.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    51
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    52
Since desktop properties abstract an underlying platform
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
setting, they may not be available in environments that do
90ce3da70b43 Initial load
duke
parents:
diff changeset
    54
not support them. In the event that a desktop property is
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
unavailable for any reason, the implementation will return
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
<code>null</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
The following table summarizes the desktop properties documented
90ce3da70b43 Initial load
duke
parents:
diff changeset
    59
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
    60
<br><br>
58325
d32a3b1ca84a 8225372: accessibility errors in tables in java.desktop files
serb
parents: 55366
diff changeset
    61
<table border=1>
d32a3b1ca84a 8225372: accessibility errors in tables in java.desktop files
serb
parents: 55366
diff changeset
    62
<thead>
d32a3b1ca84a 8225372: accessibility errors in tables in java.desktop files
serb
parents: 55366
diff changeset
    63
<tr>
d32a3b1ca84a 8225372: accessibility errors in tables in java.desktop files
serb
parents: 55366
diff changeset
    64
<th scope="col">Property Name</th>
d32a3b1ca84a 8225372: accessibility errors in tables in java.desktop files
serb
parents: 55366
diff changeset
    65
<th scope="col">Value Type</th>
d32a3b1ca84a 8225372: accessibility errors in tables in java.desktop files
serb
parents: 55366
diff changeset
    66
<th scope="col">Summary Description</th>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
</tr>
58325
d32a3b1ca84a 8225372: accessibility errors in tables in java.desktop files
serb
parents: 55366
diff changeset
    68
</thead>
d32a3b1ca84a 8225372: accessibility errors in tables in java.desktop files
serb
parents: 55366
diff changeset
    69
<tbody>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    70
<tr>
58325
d32a3b1ca84a 8225372: accessibility errors in tables in java.desktop files
serb
parents: 55366
diff changeset
    71
<th scope="row"><A href="#awt.font.desktophints">awt.font.desktophints</A></th>
55366
de1d2a535c08 8225368: broken links in java.desktop files
psadhukhan
parents: 52831
diff changeset
    72
<td>{@link java.util.Map java.util.Map}</td>
52831
4e9739110cf1 8213048: Invalid use of HTML5 in java.awt files
kaddepalli
parents: 50358
diff changeset
    73
<td>Font smoothing (text antialiasing) settings.</td>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    74
</tr>
1962
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
    75
<tr>
58325
d32a3b1ca84a 8225372: accessibility errors in tables in java.desktop files
serb
parents: 55366
diff changeset
    76
<th scope="row"><A href="#sun.awt.enableExtraMouseButtons">sun.awt.enableExtraMouseButtons</A></th>
55366
de1d2a535c08 8225368: broken links in java.desktop files
psadhukhan
parents: 52831
diff changeset
    77
<td>{@link java.lang.Boolean java.lang.Boolean}</td>
52831
4e9739110cf1 8213048: Invalid use of HTML5 in java.awt files
kaddepalli
parents: 50358
diff changeset
    78
<td>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
    79
</tr>
58325
d32a3b1ca84a 8225372: accessibility errors in tables in java.desktop files
serb
parents: 55366
diff changeset
    80
</tbody>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
</table>
21254
f6d36ee3f269 8025824: [cleanup] Fix tidy errors and warnings in preformatted HTML files related to 2d/awt/swing
yan
parents: 5506
diff changeset
    82
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
<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
    84
<b>Desktop Property: <a id="awt.font.desktophints">"awt.font.desktophints"</A></b>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    86
Modern desktops support various forms of text antialiasing (font smoothing).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    87
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    88
These are applied by platform-specific heavyweight components.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    89
However an application may want to render text using the same text
90ce3da70b43 Initial load
duke
parents:
diff changeset
    90
antialiasing on a drawing surface or lightweight (non-platform) component using
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
<a href="../Graphics2D.html"> <code>Graphics2D</code></a> methods.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    92
This is particularly important when creating
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
<a href="../../../javax/swing/JComponent.html"> Swing components</a> which
90ce3da70b43 Initial load
duke
parents:
diff changeset
    94
are required to appear consistent with native desktop components or other
90ce3da70b43 Initial load
duke
parents:
diff changeset
    95
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
    96
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
<h3>Basic Usage</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    98
The standard desktop property named
90ce3da70b43 Initial load
duke
parents:
diff changeset
    99
<b>"awt.font.desktophints"</b>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
can be used to obtain the rendering hints that best match the desktop settings.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   101
90ce3da70b43 Initial load
duke
parents:
diff changeset
   102
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
   103
<a href="../../util/Map.html"> Map</a> of
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
<a href="../RenderingHints.html"> <code>RenderingHints</code></a> which
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
can be directly applied to a <code>Graphics2D</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
It is a <code>Map</code> as more than one hint may be needed.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   108
If non-null this can be directly applied to the <code>Graphics2D</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
<pre><code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
Toolkit tk = Toolkit.getDefaultToolkit();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   111
Map map = (Map)(tk.getDesktopProperty("awt.font.desktophints"));
90ce3da70b43 Initial load
duke
parents:
diff changeset
   112
if (map != null) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   113
    graphics2D.addRenderingHints(map);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   114
}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
</code></pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   116
<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
   117
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
<h4>Listening for changes</h4>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   119
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   120
An application can listen for changes in the property
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
using a <a href="../../beans/PropertyChangeListener.html">
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
<code>PropertyChangeListener</code></a> :
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
<pre><code>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   124
tk.addPropertyChangeListener("awt.font.desktophints", pcl);
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
</code></pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
Listening for changes is recommended as users can, on rare occasions,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   127
reconfigure a desktop environment whilst applications are running
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
in a way that may affect the selection of these hints, and furthermore
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
many desktop environments support dynamic reconfiguration of these
90ce3da70b43 Initial load
duke
parents:
diff changeset
   130
running applications to conform to the new settings.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   132
There is no direct way to discover if dynamic reconfiguration
90ce3da70b43 Initial load
duke
parents:
diff changeset
   133
is expected of running applications but the default assumption
90ce3da70b43 Initial load
duke
parents:
diff changeset
   134
should be that it is expected, since most modern desktop environments
90ce3da70b43 Initial load
duke
parents:
diff changeset
   135
do provide this capability.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   136
<h4>Text Measurement</h4>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   137
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   138
Text always needs to be measured using the same
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
<a href="../font/FontRenderContext.html"> <code>FontRenderContext</code></a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   140
as used for rendering. The text anti-aliasing hint is a component of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
the <code>FontRenderContext</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   142
A <a href="../FontMetrics.html"> <code>FontMetrics</code></a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   143
obtained from the <code>Graphics</code> object on which the hint
90ce3da70b43 Initial load
duke
parents:
diff changeset
   144
has been set will measure text appropriately.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   145
This is not a unique requirement for clients that specify this hint
90ce3da70b43 Initial load
duke
parents:
diff changeset
   146
directly, since the value of the <code>FontRenderContext</code> should
90ce3da70b43 Initial load
duke
parents:
diff changeset
   147
never be assumed, so is discussed here principally as a reminder.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   148
<h4>Saving and restoring Graphics State</h4>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   149
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   150
Sometimes an application may need to apply these hints on a shared
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
Graphics only temporarily, restoring the previous values after they
90ce3da70b43 Initial load
duke
parents:
diff changeset
   152
have been applied to text rendering operations.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   153
The following sample code shows one way to do this.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   154
<pre><code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   155
/**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   156
  * Get rendering hints from a Graphics instance.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   157
  * "hintsToSave" is a Map of RenderingHint key-values.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   158
  * For each hint key present in that map, the value of that
90ce3da70b43 Initial load
duke
parents:
diff changeset
   159
  * hint is obtained from the Graphics and stored as the value
90ce3da70b43 Initial load
duke
parents:
diff changeset
   160
  * for the key in savedHints.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   161
  */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   162
RenderingHints getRenderingHints(Graphics2D g2d,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   163
                                  RenderingHints hintsToSave,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   164
                                  RenderingHints savedHints) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   165
     if (savedHints == null) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   166
         savedHints = new RenderingHints(null);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   167
     } else {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   168
         savedHints.clear();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   169
     }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   170
     if (hintsToSave.size() == 0) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   171
         return savedHints;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   172
     }
21254
f6d36ee3f269 8025824: [cleanup] Fix tidy errors and warnings in preformatted HTML files related to 2d/awt/swing
yan
parents: 5506
diff changeset
   173
     /* RenderingHints.keySet() returns Set&lt;Object&gt; */
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   174
     for (Object o : hintsToSave.keySet()) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   175
         RenderingHints.Key key = (RenderingHints.Key)o;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   176
         Object value = g2d.getRenderingHint(key);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   177
         savedHints.put(key, value);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   178
     }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   179
     return savedHints;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   180
}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   181
90ce3da70b43 Initial load
duke
parents:
diff changeset
   182
90ce3da70b43 Initial load
duke
parents:
diff changeset
   183
Toolkit tk = Toolkit.getDefaultToolkit();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   184
Map map = (Map)(tk.getDesktopProperty("awt.font.desktophints"));
90ce3da70b43 Initial load
duke
parents:
diff changeset
   185
Map oldHints;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   186
if (map != null) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   187
     oldHints = getRenderingHints(graphic2D, map, null);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   188
     graphics2D.addRenderingHints(map);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   189
     ..
90ce3da70b43 Initial load
duke
parents:
diff changeset
   190
     graphics2D.addRenderingHints(oldHints);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   191
}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   192
</code></pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   193
90ce3da70b43 Initial load
duke
parents:
diff changeset
   194
<h3>Details</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   195
<ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   196
<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
   197
<br><br>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   198
<li>If the return value is null, then no desktop properties are available,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   199
and dynamic updates will not be available. This is a typical behaviour if
90ce3da70b43 Initial load
duke
parents:
diff changeset
   200
the JDK does not recognise the desktop environment, or it is one which
90ce3da70b43 Initial load
duke
parents:
diff changeset
   201
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
   202
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
   203
<br><br>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   204
<li>If non-null the value will be a <code>Map</code> of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   205
<code>RenderingHints</code> such that every key is an instance of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   206
<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
   207
<br><br>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   208
<li>The map may contain the default value for a hint. This is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   209
needed in the event there is a previously a non-default value for the hint
90ce3da70b43 Initial load
duke
parents:
diff changeset
   210
set on the <code>Graphics2D</code>. If the map did not contain
90ce3da70b43 Initial load
duke
parents:
diff changeset
   211
the default value, then <code>addRenderingHints(Map)</code> would leave
90ce3da70b43 Initial load
duke
parents:
diff changeset
   212
the previous hint which may not correspond to the desktop setting.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   213
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   214
An application can use <code>setRenderingHints(Map)</code> to reinitialise
90ce3da70b43 Initial load
duke
parents:
diff changeset
   215
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
   216
<br><br>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   217
<li>A multi-screen desktop may support per-screen device settings in which
90ce3da70b43 Initial load
duke
parents:
diff changeset
   218
case the returned value is for the default screen of the desktop.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   219
An application may want to use the settings for the screen on
90ce3da70b43 Initial load
duke
parents:
diff changeset
   220
which they will be applied.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   221
The per-screen device hints may be obtained by per-device property names
90ce3da70b43 Initial load
duke
parents:
diff changeset
   222
which are constructed as the String concatenation
90ce3da70b43 Initial load
duke
parents:
diff changeset
   223
<pre><code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   224
"awt.font.desktophints" + "." + GraphicsDevice.getIDstring();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   225
</code></pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   226
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   227
An application can also listen for changes on these properties.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   228
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   229
However this is an extremely unlikely configuration, so to help
90ce3da70b43 Initial load
duke
parents:
diff changeset
   230
ease of development, if only a single, desktop-wide setting is supported,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   231
then querying each of these per-device settings will return null.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   232
So to determine if there are per-device settings it is sufficient to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   233
determine that there is a non-null return for any screen device using
90ce3da70b43 Initial load
duke
parents:
diff changeset
   234
the per-device property name.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   235
</ul>
1962
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   236
<h2>Mouse Functionality</h2>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   237
<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
   238
<p>
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   239
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
   240
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
   241
{@code EventQueue}.
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   242
<br>
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   243
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
   244
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
   245
<pre>
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   246
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
   247
</pre>
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   248
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
   249
<br>
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   250
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
   251
method.
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   252
<br>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   253
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
   254
<ul>
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   255
<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
   256
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
   257
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
   258
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
   259
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   260
<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
   261
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
   262
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
   263
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
   264
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
   265
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
   266
</ul>
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   267
<br>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   268
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
   269
<ul>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   270
<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
   271
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
   272
{@code BUTTON3}
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   273
<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
   274
{@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
   275
{@code InputEvent.BUTTON3_DOWN_MASK}
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   276
</ul>
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   277
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   278
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
   279
activity with extra mouse button.
6c293d33645b 6315717: Support for mouse with multiple scroll wheels and 4 or more buttons
dav
parents: 2
diff changeset
   280
By default this property is set to {@code true}.
58595
fa9f28a0e175 8231144: Wrap contents of plain HTML files into contentContainer
aivanov
parents: 58325
diff changeset
   281
</div>
50358
1ba28f0dbc33 8199150: Accessibility issues in java.desktop
serb
parents: 48264
diff changeset
   282
</main>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   283
</body>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   284
</html>