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; 144