1 /*
2 * Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 /**
27 * Synth is a skinnable look and feel in which all painting is delegated. Synth
28 * does not provide a default look. In order to use Synth you need to specify a
29 * <a href="doc-files/synthFileFormat.html">file</a>, or provide a
30 * {@link javax.swing.plaf.synth.SynthStyleFactory}. Both configuration options
31 * require an understanding of the synth architecture, which is described below,
32 * as well as an understanding of Swing's architecture.
33 * <p>
34 * Unless otherwise specified null is not a legal value to any of the methods
35 * defined in the synth package and if passed in will result in a
36 * {@code NullPointerException}.
37 *
38 * <h2>Synth</h2>
39 * Each {@link javax.swing.plaf.ComponentUI} implementation in Synth associates
40 * itself with one {@link javax.swing.plaf.synth.SynthStyle} per
41 * {@link javax.swing.plaf.synth.Region}, most {@code Components} only have one
42 * {@code Region} and therefor only one {@code SynthStyle}. {@code SynthStyle}
43 * is used to access all style related properties: fonts, colors
44 * and other {@code Component} properties. In addition {@code SynthStyle}s are
45 * used to obtain {@link javax.swing.plaf.synth.SynthPainter}s for painting the
46 * background, border, focus and other portions of a {@code Component}. The
47 * {@code ComponentUI}s obtain {@code SynthStyle}s from a
48 * {@link javax.swing.plaf.synth.SynthStyleFactory}. A {@code SynthStyleFactory}
49 * can be provided directly by way of
50 * {@link javax.swing.plaf.synth.SynthLookAndFeel#setStyleFactory(javax.swing.plaf.synth.SynthStyleFactory)},
51 * or indirectly by way of {@link javax.swing.plaf.synth.SynthLookAndFeel#load}.
52 * The following example uses the {@code SynthLookAndFeel.load()} method to
53 * configure a {@code SynthLookAndFeel} and sets it as the current look and
54 * feel:
55 * <div class="example">
56 * <pre>{@code
57 * SynthLookAndFeel laf = new SynthLookAndFeel();
58 * laf.load(MyClass.class.getResourceAsStream("laf.xml"), MyClass.class);
59 * UIManager.setLookAndFeel(laf);
60 * }</pre>
61 * </div>
62 * <p>
63 * Many {@code JComponent}s are broken down into smaller pieces and identified
64 * by the type safe enumeration in {@link javax.swing.plaf.synth.Region}. For
65 * example, a {@code JTabbedPane} consists of a {@code Region} for the
66 * {@code JTabbedPane}({@link javax.swing.plaf.synth.Region#TABBED_PANE}), the
67 * content area ({@link javax.swing.plaf.synth.Region#TABBED_PANE_CONTENT}), the
68 * area behind the tabs
69 * ({@link javax.swing.plaf.synth.Region#TABBED_PANE_TAB_AREA}), and the tabs
70 * ({@link javax.swing.plaf.synth.Region#TABBED_PANE_TAB}). Each
71 * {@code Region} of each {@code JComponent} will have a {@code SynthStyle}.
72 * This allows you to customize individual pieces of each region of each
73 * {@code JComponent}.
74 * <p>
75 * Many of the Synth methods take a {@link javax.swing.plaf.synth.SynthContext}.
76 * This is used to provide information about the current {@code Component} and
77 * includes: the {@link javax.swing.plaf.synth.SynthStyle} associated with the
78 * current {@link javax.swing.plaf.synth.Region}, the state of the
79 * {@code Component} as a bitmask (refer to
80 * {@link javax.swing.plaf.synth.SynthConstants} for the valid states), and a
81 * {@link javax.swing.plaf.synth.Region} identifying the portion of the
82 * {@code Component} being painted.
83 * <p>
84 * All text rendering by non-{@code JTextComponent}s is delegated to a
85 * {@link javax.swing.plaf.synth.SynthGraphicsUtils}, which is obtained using
86 * the {@link javax.swing.plaf.synth.SynthStyle} method
87 * {@link javax.swing.plaf.synth.SynthStyle#getGraphicsUtils}. You can customize
88 * text rendering by supplying your own
89 * {@link javax.swing.plaf.synth.SynthGraphicsUtils}.
90 *
91 * <h2>Notes on specific components</h2>
92 * <h3>JTree</h3>
93 * Synth provides a region for the cells of a tree:
94 * {@code Region.TREE_CELL}. To specify the colors of the
95 * renderer you'll want to provide a style for the
96 * {@code TREE_CELL} region. The following illustrates this:
97 * <pre>{@code
98 * <style id="treeCellStyle">
99 * <opaque value="TRUE"/>
100 * <state>
101 * <color value="WHITE" type="TEXT_FOREGROUND"/>
102 * <color value="RED" type="TEXT_BACKGROUND"/>
103 * </state>
104 * <state value="SELECTED">
105 * <color value="RED" type="TEXT_FOREGROUND"/>
106 * <color value="WHITE" type="BACKGROUND"/>
107 * </state>
108 * </style>
109 * <bind style="treeCellStyle" type="region" key="TreeCell"/>
110 * }</pre>
111 * <p>
112 * This specifies a color combination of red on white, when selected, and white
113 * on red when not selected. To see the background you need to specify that
114 * labels are not opaque. The following XML fragment does that:
115 * <pre>{@code
116 * <style id="labelStyle">
117 * <opaque value="FALSE"/>
118 * </style>
119 * <bind style="labelStyle" type="region" key="Label"/>
120 * }</pre>
121 *
122 * <h3>JList and JTable</h3>
123 * The colors that the renderers for JList and JTable use are specified by way
124 * of the list and table Regions. The following XML fragment illustrates how to
125 * specify red on white, when selected, and white on red when not selected:
126 * <pre>{@code
127 * <style id="style">
128 * <opaque value="TRUE"/>
129 * <state>
130 * <color value="WHITE" type="TEXT_FOREGROUND"/>
131 * <color value="RED" type="TEXT_BACKGROUND"/>
132 * <color value="RED" type="BACKGROUND"/>
133 * </state>
134 * <state value="SELECTED">
135 * <color value="RED" type="TEXT_FOREGROUND"/>
136 * <color value="WHITE" type="TEXT_BACKGROUND"/>
137 * </state>
138 * </style>
139 * <bind style="style" type="region" key="Table"/>
140 * <bind style="style" type="region" key="List"/>
141 * }</pre>
142 */
143 package javax.swing.plaf.synth;