--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.desktop/share/classes/javax/swing/plaf/synth/doc-files/synthFileFormat.html Tue Sep 12 19:03:39 2017 +0200
@@ -0,0 +1,980 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+ <head>
+ <title>Synth File Format</title>
+ <style type="text/css">
+div.dtd-fragment {
+ width: 100%;
+ border: none;
+ background-color: #eee;
+}
+pre.dtd-fragment {
+ margin-left: 0;
+}
+div.example {
+ width: 100%;
+ color: maroon;
+}
+ </style>
+ </head>
+
+ <body>
+ <h2><a name="file">File Format</a></h2>
+ <p>
+ Synth's file format (<a href="synth.dtd">dtd</a>)
+ allows for specifying all the pieces
+ necessary to create your own look and feel. A synth file is
+ loaded by way of the <A HREF="../../../../../javax/swing/plaf/synth/SynthLookAndFeel.html#load(java.io.InputStream,%20java.lang.Class)">SynthLookAndFeel.load(InputStream, Class)</a> or
+ <a href="../../../../../javax/swing/plaf/synth/SynthLookAndFeel.html#load(java.net.URL)">SynthLookAndFeel.load(URL)</a> methods.
+ The following example uses the <code>load</code> method to configure
+ a <code>SynthLookAndFeel</code> and sets it as the current look
+ and feel:
+ </p>
+ <div class="example">
+ <pre>
+ SynthLookAndFeel laf = new SynthLookAndFeel();
+ laf.load(MyClass.class.getResourceAsStream("laf.xml"), MyClass.class);
+ UIManager.setLookAndFeel(laf);
+ </pre>
+ </div>
+ <p>
+ This example loads the look and feel from an input stream, using
+ the specified class as the resource base to resolve paths.
+ It is also possible to load a look and feel from an arbitrary URL
+ as in the following example.
+ </p>
+ <div class="example">
+ <pre>
+ SynthLookAndFeel laf = new SynthLookAndFeel();
+ laf.load(new URL("file:///C:/java/synth/laf/laf.xml"));
+ UIManager.setLookAndFeel(laf);
+ </pre>
+ </div>
+ <p>
+ The method <a href="../../../../../javax/swing/plaf/synth/SynthLookAndFeel.html#load(java.net.URL)">SynthLookAndFeel.load(URL)</a> can be
+ used, for instance, to load a look and feel from any of the following:
+ </p>
+ <ul>
+ <li>File, e.g. <code>file:///C:/java/synth/laf/laf.xml</code></li>
+ <li>Web server, e.g. <code>http://host/laf.xml</code></li>
+ <li>JAR file, e.g.
+ <code>jar:file:///C:/synth-laf.jar!/laf.xml</code></li>
+ <li>Remote JAR file, e.g.
+ <code>jar:http://host/synth-laf.jar!/laf.xml</code></li>
+ </ul>
+ <p>
+ While the DTD for synth is specified, the parser is not validating.
+ Parsing will fail only if a necessary attribute is not
+ specified, or of the wrong type.
+
+ <h3>The synth element</h3>
+<div class="dtd-fragment">
+<pre class="dtd-fragment">
+<!ELEMENT <a name="e.synth">synth</a> ((<a href="#ee.beansPersistance">%beansPersistance;</a>) | <a href="#e.style">style</a> | <a href="#e.bind">bind</a> | <a href="#e.font">font</a> | <a href="#e.color">color</a> |
+ <a href="#e.imagePainter">imagePainter</a> | <a href="#e.imageIcon">imageIcon</a> | <a href="#e.defaultsProperty">defaultsProperty</a>)*>
+<!ATTLIST synth
+ <a href="#synth.version">version</a> CDATA #IMPLIED
+>
+</pre>
+</div>
+ <p><em>Attribute definitions</em></p>
+ <dl><dt><a name="synth.version"><samp>version</samp></a></dt>
+ <dd>File format version, should be 1</dd>
+ </dl>
+ <p>
+ The <a href="#e.synth">synth</a> element contains all the other
+ elements that make up a SynthLookAndFeel definition.
+ </p>
+
+
+ <h3>The style element</h3>
+<div class="dtd-fragment">
+<pre class="dtd-fragment">
+<!ELEMENT <a name="e.style">style</a> (<a href="#e.property">property</a> | <a href="#e.defaultsProperty">defaultsProperty</a> | <a href="#e.state">state</a> | <a href="#e.font">font</a> | <a href="#e.graphicsUtils">graphicsUtils</a> |
+ <a href="#e.insets">insets</a> | <a href="#e.painter">painter</a> | <a href="#e.imagePainter">imagePainter</a> | <a href="#e.opaque">opaque</a> | (<a href="#ee.beansPersistance">%beansPersistance;</a>) |
+ <a href="#e.imageIcon">imageIcon</a>)*>
+<!ATTLIST style
+ <a href="#style.id">id</a> ID #IMPLIED
+ <a href="#style.clone">clone</a> IDREF #IMPLIED
+>
+</pre>
+</div>
+ <p><em>Attribute definitions</em></p>
+ <dl>
+ <dt><a name="style.id"><samp>id</samp></a></dt>
+ <dd>Unique identifier for the style.</dd>
+ <dt><a name="style.clone"><samp>clone</samp></a></dt>
+ <dd>Identifier of a previously defined style that is copied
+ and used for the new style. This provides a convenient
+ mechanism for overriding only a portion of an existing
+ style.</dd>
+ </dl>
+ <p>
+ A style element corresponds to a
+ <code>SynthStyle</code>, with the child elements specifying
+ properties that apply to all states or state elements which
+ contain properties specific to a particular state. The following
+ example creates an opaque style with the id <code>button</code>,
+ insets of 4, 4, 4, 4 and a font of Dialog 12.
+ </p>
+ <div class="example">
+ <pre>
+<style id="button">
+ <opaque value="true"/>
+ <insets top="4" left="4" right="4" bottom="4"/>
+ <font name="Dialog" size="12"/>
+</style>
+ </pre>
+ </div>
+ <p>
+ The following example creates a new style with an id of
+ <code>clonedButton</code> that is a copy of the
+ style with id <code>button</code> and has a font of Dialog,
+ 14. The resulting style will be opaque, have insets of 4, 4, 4,
+ 4 and a font of Dialog 14.
+ </p>
+ <div class="example">
+ <pre>
+<style id="clonedButton" clone="button">
+ <font name="Dialog" size="14"/>
+</style>
+ </pre>
+ </div>
+
+ <h3>The state element</h3>
+<div class="dtd-fragment">
+<pre class="dtd-fragment">
+<!ELEMENT <a name="e.state">state</a> (<a href="#e.color">color</a> | <a href="#e.font">font</a> | <a href="#e.painter">painter</a> | <a href="#e.imagePainter">imagePainter</a> | (<a href="#ee.beansPersistance">%beansPersistance;</a>) |
+ <a href="#e.property">property</a> | <a href="#e.imageIcon">imageIcon</a>)*>
+<!ATTLIST state
+ <a href="#state.id">id</a> ID #IMPLIED
+ <a href="#state.clone">clone</a> IDREF #IMPLIED
+ <a href="#state.value">value</a> CDATA #IMPLIED
+ <a href="#state.idref">idref</a> IDREF #IMPLIED
+>
+</pre>
+</div>
+ <p><em>Attribute definitions</em></p>
+ <dl>
+ <dt><a name="state.id"><samp>id</samp></a></dt>
+ <dd>Unique identifier for the state.</dd>
+ <dt><a name="state.clone"><samp>clone</samp></a></dt>
+ <dd>Identifier of a previously defined state that is copied
+ and used for the new state.</dd>
+ <dt><a name="state.value"><samp>value</samp></a></dt>
+ <dd>Identifies the state of the Component the properties are to apply
+ to. This is a list of: ENABLED,
+ MOUSE_OVER, PRESSED, DISABLED, FOCUSED, SELECTED or
+ DEFAULT. Multiple states should
+ be separated by 'and.' If you do not specify a value, the
+ contents apply to all states.
+ <dt><a name="state.idref"><samp>idref</samp></a></dt>
+ <dd>Indicates this state should be the same as a previously
+ defined state. This is useful for multiple styles that
+ wish to share the same visual properties for a particular
+ state.
+ </dd>
+ </dl>
+ <p>
+ The <a href="#e.state">state</a> element specifies the visual
+ properties that are to be used for
+ a particular state of a component. For example, you could
+ specify the background color when the Component is enabled should look
+ different than the background color when the component is
+ disabled. Not all Components support all states. For example, a
+ <code>Panel</code> only supports the states ENABLED and DISABLED.
+ </p>
+ <p>
+ The following example creates a state with a red background that
+ will be used when the component is in an a selected and pressed state:
+ </p>
+ <div class="example">
+ <pre>
+<state value="SELECTED AND PRESSED">
+ <color value="RED" type="BACKGROUND"/>
+</state>
+ </pre>
+</div>
+ <p>
+ The state with the most individual matches will be
+ chosen. For example, the following defines two states:
+ </p>
+ <div class="example">
+ <pre>
+<state value="SELECTED and PRESSED" id="one">
+ <color value="RED" type="BACKGROUND"/>
+</state>
+<state value="SELECTED" id="two">
+ <color value="RED" type="BACKGROUND"/>
+</state>
+ </pre>
+</div>
+ <p>
+ State <code>one</code> is used when the Component is SELECTED
+ and PRESSED, and state <code>two</code> when the Component is
+ SELECTED. If the state of the Component
+ contains at least SELECTED and PRESSED, state <code>one</code> will be
+ chosen, otherwise if the state is SELECTED, but not does not
+ contain PRESSED, state <code>two</code> will be used.
+
+ <h3>The font element</h3>
+<div class="dtd-fragment">
+<pre class="dtd-fragment">
+<!ELEMENT <a name="e.font">font</a> EMPTY>
+<!ATTLIST font
+ <a href="#font.id">id</a> ID #IMPLIED
+ <a href="#font.idref">clone</a> IDREF #IMPLIED
+ <a href="#font.name">name</a> CDATA #IMPLIED
+ <a href="#font.style">style</a> CDATA #IMPLIED
+ <a href="#font.size">size</a> CDATA #IMPLIED
+>
+</pre>
+</div>
+ <p><em>Attribute definitions</em></p>
+ <dl>
+ <dt><a name="font.id"><samp>id</samp></a></dt>
+ <dd>Unique identifier for the Font.</dd>
+ <dt><a name="font.idref"><samp>idref</samp></a></dt>
+ <dd>Identifier of a previously defined font.</dd>
+ <dt><a name="font.name"><samp>name</samp></a></dt>
+ <dd>Name of the font.
+ <dt><a name="font.style"><samp>style</samp></a></dt>
+ <dd>Style of the font. This is a list of the styles defined by
+ Font separated by spaces: PLAIN, BOLD or ITALIC. If
+ unspecified PLAIN is used.
+ </dd>
+ <dt><a name="font.size"><samp>size</samp></a></dt>
+ <dd>Size of the font, in pixels</dd>
+ </dl>
+ <p>
+ Defines the font for the current <a href="#e.state">state</a>,
+ or <a href="#e.style">style</a>. You must
+ specify either an <a href="#font.idref">idref</a> or a
+ <a href="#font.name">name</a> and <a href="#font.size">size</a>.
+ </p>
+ <p>
+ The following example creates a style with a Font of
+ Dialog 12 Bold.
+ </p>
+ <div class="example">
+ <pre>
+<style id="test">
+ <font name="DIALOG" size="12" style="BOLD"/>
+</style>
+ </pre>
+</div>
+ <p>
+ The following example creates a style with a font of
+ Dialog 12 Bold that will be used if the component is ENABLED,
+ otherwise Dialog 12 Italic will be used.
+ </p>
+ <div class="example">
+ <pre>
+<style id="test">
+ <font name="DIALOG" size="12" style="ITALIC"/>
+ <state value="ENABLED">
+ <font name="DIALOG" size="12" style="BOLD"/>
+ </state>
+</style>
+ </pre>
+</div>
+ <p>
+ While you can supply a different font per state, in general
+ widgets will NOT revalidate when the state changes, so that you
+ may run into sizing problems if you try to use a font with a
+ significantly different size for different states.
+ </p>
+
+
+ <h3>The color element</h3>
+<div class="dtd-fragment">
+<pre class="dtd-fragment">
+<!ELEMENT <a name="e.color">color</a> EMPTY>
+<!ATTLIST color
+ <a href="#color.id">id</a> ID #IMPLIED
+ <a href="#color.idref">idref</a> IDREF #IMPLIED
+ <a href="#color.type">type</a> CDATA #IMPLIED
+ <a href="#color.value">value</a> CDATA #IMPLIED
+>
+</pre>
+</div>
+ <p><em>Attribute definitions</em></p>
+ <dl>
+ <dt><a name="color.id"><samp>id</samp></a></dt>
+ <dd>Unique identifier for the color.</dd>
+ <dt><a name="color.idref"><samp>idref</samp></a></dt>
+ <dd>Identifier of a previously defined color.</dd>
+ <dt><a name="color.type"><samp>type</samp></a></dt>
+ <dd>Describes where this color should be used. This is
+ typically one of the constants defined by ColorType:
+ FOREGROUND, BACKGROUND, TEXT_FOREGROUND, TEXT_BACKGROUND
+ or FOCUS. Alternatively you can specify the complete path
+ to a class and field, for example
+ javax.swing.plaf.synth.ColorType.FOREGROUND, this
+ is useful for subclasses of synth that define additional
+ color types.
+ </dd>
+ <dt><a name="color.value"><samp>value</samp></a></dt>
+ <dd>
+ Value for the color. This accepts the following forms.
+ <ul>
+ <li>The name of a constant in the <code>Color</code> class,
+ for example <code> RED</code>.
+ <li>A hex value of the form <code>#RRGGBB</code> where
+ <code>RR</code> gives the red component, <code>GG</code>
+ the green component and <code>BB</code> the blue
+ component. You need not specify all color components. For
+ example, <code>#123</code> is equivalent to <code>#000123</code>.
+ <li>A hex value of the form <code>#ARRGGBB</code> or
+ <code>#AARRGGBB</code>. This is useful for alpha values
+ other than <code>0xFF</code>. The form
+ <code>#ARRGGBB</code> is equivalent to
+ <code>#0ARRGGBB</code>.
+ </ul>
+ </dd>
+ </dl>
+ <p>
+ <a href="#e.color">Color</a> defines a color and what portion of
+ the Component it should be applied to. The following example
+ will use a background color of RED when the component is
+ enabled.
+ </p>
+ <div class="example">
+ <pre>
+<state value="ENABLED">
+ <color value="RED" type="BACKGROUND"/>
+</state>
+ </pre>
+</div>
+ <p>
+ The following example will have a red background when the
+ Component is enabled, otherwise blue.
+ </p>
+ <div class="example">
+ <pre>
+<style id="test">
+ <state value="ENABLED">
+ <color value="RED" type="BACKGROUND"/>
+ </state>
+ <state>
+ <color value="#00FF00" type="BACKGROUND"/>
+ </state>
+</style>
+ </pre>
+</div>
+
+ <h3>The property element</h3>
+<div class="dtd-fragment">
+<pre class="dtd-fragment">
+<!ELEMENT <a name="e.property">property</a> EMPTY>
+<!ATTLIST property
+ <a href="#property.key">key</a> CDATA #REQUIRED
+ <a href="#property.type">type</a> (idref|boolean|dimension|insets|integer|string) "idref"
+ <a href="#property.value">value</a> CDATA #REQUIRED
+>
+</pre>
+</div>
+ <p><em>Attribute definitions</em></p>
+ <dl>
+ <dt><a name="property.key"><samp>key</samp></a></dt>
+ <dd>Name of the property.</dd>
+ <dt><a name="property.type"><samp>type</samp></a></dt>
+ <dd>Indicates the type of the property.</dd>
+ <dt><a name="property.value"><samp>value</samp></a></dt>
+ <dd>Value for the property. For boolean properties this will be
+ be true or false, for integer properties this will be a
+ valid integer, for dimensions this will be the width and
+ height separated by a space, for insets properties this will
+ be the top, left, bottom and right separated by a space and
+ for idref properties this will be the unique id of a
+ previously defined object.</dd>
+ </dl>
+ <p>
+ <a href="#e.property">Property</a> elements are used to add key value pairs to a
+ <code>SynthStyle</code> that can be accessed by way of the
+ <code>get</code> method. Many <code>Component</code>s use the
+ key value pairs for configuring their visual appearance. Refer to
+ <a href="componentProperties.html">property table</a> for a list of the
+ properties each <code>Component</code> supports. The following
+ creates the properties
+ <code>ScrollBar.allowsAbsolutePositioning</code>,
+ <code>OptionPane.minimumSize</code>,
+ <code>ScrollPane.viewportBorderInsets</code>,
+ <code>Tree.rowHeight</code> and <code>foreground</code> with the
+ values false, a dimensions of 262x90, an insets of 5, 5, 5, 5,
+ the integer 20 and an instance of the
+ class ArrowButtonPainter.
+ </p>
+ <div class="example">
+ <pre>
+<style id="test">
+ <property key="ScrollBar.allowsAbsolutePositioning" type="boolean" value="false"/>
+ <property key="OptionPane.minimumSize" type="dimension" value="262 90"/>
+ <property key="ScrollPane.viewportBorderInsets" type="insets" value="5 5 5 5"/>
+ <property key="Tree.rowHeight" type="integer" value="20"/>
+ <object class="ArrowButtonPainter" id="ArrowButtonPainter"/>
+ <property key="foreground" type="idref" value="ArrowButtonPainter"/>
+</style>
+ </pre>
+</div>
+ <p>
+ You can also specify properties that are to apply to specific
+ states. Whether or not the property is accessed for each state
+ depends upon how the property is used. For example, the
+ following specifies a default icon and an icon to use while the
+ mouse is over the component.
+ </p>
+ <div class="example">
+ <pre>
+<style id="test">
+ <imageIcon id="defaultIcon" path="resources/myImage.png"/>
+ <property key="RadioButton.icon" value="defaultIcon"/>
+ <state value="MOUSE_OVER">
+ <imageIcon id="mouseOverIcon" path="resources/myMouseOverImage.png"/>
+ <property key="RadioButton.icon" value="mouseOverIcon"/>
+ </state>
+</style>
+ </pre>
+</div>
+<div class="dtd-fragment">
+<pre class="dtd-fragment">
+<!ELEMENT <a name="e.defaultsProperty">defaultsProperty</a> EMPTY>
+<!ATTLIST defaultsProperty
+ <a href="#defaultsProperty.key">key</a> CDATA #REQUIRED
+ <a href="#defaultsProperty.type">type</a> (idref|boolean|dimension|insets|integer|string) "idref"
+ <a href="#defaultsProperty.value">value</a> CDATA #REQUIRED
+>
+</pre>
+</div>
+ <p><em>Attribute definitions</em></p>
+ <dl>
+ <dt><a name="defaultsProperty.key"><samp>key</samp></a></dt>
+ <dd>Name of the property.</dd>
+ <dt><a name="defaultsProperty.type"><samp>type</samp></a></dt>
+ <dd>Indicates the type of the property.</dd>
+ <dt><a name="defaultsProperty.value"><samp>value</samp></a></dt>
+ <dd>Value for the property. For boolean properties this will be
+ true or false, for integer properties this will be a
+ valid integer, for dimensions this will be the width and
+ height separated by a space, for insets properties this will
+ be the top, left, bottom and right separated by a space and
+ for idref properties this will be the unique id of a
+ previously defined object.</dd>
+ </dl>
+ <p>
+ <a href="#e.defaultsProperty">DefaultsProperty</a> elements are
+ used to define properties that will be placed in the
+ <code>UIDefaults</code> table that <code>SynthLookAndFeel</code>
+ supplies to the <code>UIManager</code>. The following assigns the
+ the Color red to the value Table.focusCellForeground.
+ </p>
+ <div class="example">
+ <pre>
+<style id="test">
+ <object class="javax.swing.plaf.ColorUIResource" id="color">
+ <int>255</int>
+ <int>0</int>
+ <int>0</int>
+ </object>
+ <defaultsProperty key="Table.focusCellForeground" type="idref" value="color"/>
+</style>
+ </pre>
+</div>
+ <p>
+ This value could then be asked by way of
+ <code>UIManager.get("Table.focusCellForeground")</code>.
+ </p>
+
+ <h3>The graphicsUtils element</h3>
+<div class="dtd-fragment">
+<pre class="dtd-fragment">
+<!ELEMENT <a name="e.graphicsUtils">graphicsUtils</a> EMPTY>
+<!ATTLIST graphicsUtils
+ <a href="#graphicsUtils.idref">idref</a> IDREF #REQUIRED
+>
+</pre>
+</div>
+ <p><em>Attribute definitions</em></p>
+ <dl>
+ <dt><a name="graphicsUtils.idref"><samp>idref</samp></a></dt>
+ <dd>Identifer of a previously defined SynthGraphicsUtils object
+ that is to be used as the SynthGraphicsUtils for the current
+ <a href="#e.style">style</a>.</dd>
+ </dl>
+ <p>
+ <a href="#e.graphicsUtils">GraphicsUtils</a> elements are
+ used to define the SynthGraphicsUtils that the current
+ <a href="#e.style">style</a> will use. The following example
+ creates a style with an instance of CustomGraphicsUtils for the
+ SynthGraphicsUtils.
+ </p>
+ <div class="example">
+ <pre>
+<style id="test">
+ <object class="CustomGraphicsUtils" id="graphics"/>
+ <graphicsUtils idref="graphics"/>
+</style>
+ </pre>
+</div>
+
+ <h3>The insets element</h3>
+<div class="dtd-fragment">
+<pre class="dtd-fragment">
+<!ELEMENT <a name="e.insets">insets</a> EMPTY>
+<!ATTLIST insets
+ <a href="#insets.id">id</a> ID #IMPLIED
+ <a href="#insets.idref">idref</a> IDREF #IMPLIED
+ <a href="#insets.top">top</a> CDATA #IMPLIED
+ <a href="#insets.bottom">bottom</a> CDATA #IMPLIED
+ <a href="#insets.left">left</a> CDATA #IMPLIED
+ <a href="#insets.right">right</a> CDATA #IMPLIED
+>
+</pre>
+</div>
+ <p><em>Attribute definitions</em></p>
+ <dl>
+ <dt><a name="insets.id"><samp>id</samp></a></dt>
+ <dd>Unique identifier for the Insets.</dd>
+ <dt><a name="insets.idref"><samp>idref</samp></a></dt>
+ <dd>Identifier of a previously defined Insets.</dd>
+ <dt><a name="insets.top"><samp>top</samp></a></dt>
+ <dd>Top component of the Insets.</dd>
+ <dt><a name="insets.bottom"><samp>bottom</samp></a></dt>
+ <dd>Bottom component of the Insets.</dd>
+ <dt><a name="insets.left"><samp>left</samp></a></dt>
+ <dd>Left component of the Insets.</dd>
+ <dt><a name="insets.right"><samp>right</samp></a></dt>
+ <dd>Right component of the Insets.</dd>
+ </dl>
+ <p>
+ <a href="#e.insets">Insets</a> elements are
+ used to define the Insets for the current <a href="#e.style">style</a>.
+ The insets will be set on any Components the
+ <a href="#e.style">style</a> is associated with. The following
+ example creates a style with insets of 1, 2, 3, 0.
+ </p>
+ <div class="example">
+ <pre>
+<style id="test">
+ <insets top="1" bottom="2" left="3"/>
+</style>
+ </pre>
+</div>
+
+ <h3>The bind element</h3>
+<div class="dtd-fragment">
+<pre class="dtd-fragment">
+<!ELEMENT <a name="e.bind">bind</a> EMPTY>
+<!ATTLIST bind
+ <a href="#bind.style">style</a> IDREF #REQUIRED
+ <a href="#bind.type">type</a> (name|region) #REQUIRED
+ <a href="#bind.key">key</a> CDATA #REQUIRED
+>
+</pre>
+</div>
+ <p><em>Attribute definitions</em></p>
+ <dl>
+ <dt><a name="bind.style"><samp>style</samp></a></dt>
+ <dd>Unique identifier of a previously defined style.</dd>
+ <dt><a name="bind.type"><samp>type</samp></a></dt>
+ <dd>One of name or region. For type name component.getName() is used,
+ otherwise the name of the Region is used.</dd>
+ <dt><a name="bind.key"><samp>key</samp></a></dt>
+ <dd>Regular expression applied to the name of the Component, or the
+ name of the Region, depending upon the value of
+ <a href="#bind.type">type</a>.</dd>
+ </dl>
+ <p>
+ <a href="#e.bind">Bind</a> elements specify which Regions a style
+ is to be used for. The following example applies the
+ <a href="#e.style">style</a> test to any Component whose name
+ starts with <code>test</code>.
+ </p>
+ <div class="example">
+ <pre>
+<style id="test">
+ <insets top="1" bottom="2" left="3"/>
+</style>
+<bind style="test" type="name" key="test.*"/>
+ </pre>
+</div>
+ <p>
+ Numerous styles may apply to a region, in which case each of
+ the matching styles is merged into a resulting style that is used.
+ Precedence is given to styles defined later in the file. For example,
+ the following defines two styles, a and b. Style a is applied to any
+ component with a name starting with test, and style b is used for
+ button regions.
+ </p>
+ <div class="example">
+ <pre>
+<style id="a">
+ <font name="DIALOG" size="12" style="ITALIC"/>
+ <insets top="1" bottom="2" left="3"/>
+</style>
+<bind style="a" type="name" key="test.*"/>
+<style id="b">
+ <font name="DIALOG" size="12" style="BOLD"/>
+</style>
+<bind style="b" type="region" key="button"/>
+ </pre>
+</div>
+ <p>
+ For a button with the name test this is equivalent to:
+ </p>
+ <div class="example">
+ <pre>
+<style>
+ <font name="DIALOG" size="12" style="BOLD"/>
+ <insets top="1" bottom="2" left="3"/>
+</style>
+ </pre>
+</div>
+ <p>
+ Merging happens for states of a style as well.
+ </p>
+ <div class="example">
+ <pre>
+<style id="a">
+ <font name="DIALOG" size="12" style="ITALIC"/>
+ <insets top="1" bottom="2" left="3"/>
+ <state value="ENABLED">
+ <object id="customPainter" class="CustomPainter"/>
+ <painter idref="customPainter"/>
+ </state>
+</style>
+<bind style="a" type="name" key="test.*"/>
+<style id="b">
+ <font name="DIALOG" size="12" style="BOLD"/>
+ <state value="ENABLED">
+ <font name="Lucida" size="12" style="ITALIC"/>
+ </state>
+</style>
+<bind style="b" type="region" key="button"/>
+ </pre>
+</div>
+ <p>
+ For a button with the name test this is equivalent to:
+ </p>
+ <div class="example">
+ <pre>
+<style>
+ <font name="DIALOG" size="12" style="BOLD"/>
+ <insets top="1" bottom="2" left="3"/>
+ <state value="ENABLED">
+ <object id="customPainter" class="CustomPainter"/>
+ <painter idref="customPainter"/>
+ <font name="Lucida" size="12" style="ITALIC"/>
+ </state>
+</style>
+ </pre>
+</div>
+
+ <h3>The painter element</h3>
+<div class="dtd-fragment">
+<pre class="dtd-fragment">
+<!ELEMENT <a name="e.painter">painter</a> EMPTY>
+<!ATTLIST painter
+ <a href="#painter.idref">idref</a> IDREF #IMPLIED
+ <a href="#painter.method">method</a> CDATA #IMPLIED
+ <a href="#painter.direction">direction</a> (north|south|east|west|top|left|bottom|right|horizontal|vertical|horizontal_split|vertical_split) #IMPLIED
+>
+</pre>
+</div>
+ <p><em>Attribute definitions</em></p>
+ <dl>
+ <dt><a name="painter.idref"><samp>idref</samp></a></dt>
+ <dd>Identifier of a previously defined SynthPainter.</dd>
+ <dt><a name="painter.method"><samp>method</samp></a></dt>
+ <dd>Identifies the SynthPainter method this is to be used for. The name
+ corresponds to the method name of a paint method in SynthPainter
+ with the paint prefix dropped, the remainder is case
+ insensitive (using the latin1 case folding rules).
+ For example SynthPainter.paintButtonBackground is identified by
+ 'buttonBackground' or 'buttonbackground'. If this is
+ not specified the painter is used for all methods that don't have a
+ a specific painter for them.</dd>
+ <dt><a name="painter.direction"><samp>direction</samp></a></dt>
+ <dd>Identifies the direction, or orientation, this painter is to be
+ used for. This is only useful for the SynthPainter methods that take
+ a direction or orientation. If this is not specified the painter is
+ used for all directions.</dd>
+ </dl>
+ <p>
+ <a href="#e.painter">Painter</a> defines a SynthPainter for the current
+ style or the state of the current style. The following example
+ binds an instance of the class <code>MyPainter</code>
+ which must be a <code>SynthPainter</code> to the style <code>test</code>.
+ </p>
+ <div class="example">
+ <pre>
+<style id="test">
+ <object class="MyPainter" id="MyPainter"/>
+ <painter idref="MyPainter"/>
+</style>
+ </pre>
+</div>
+ <p>
+ The painter that is used for a particular method and state is determined
+ as follows:
+ <ol>
+ <li>Painter specified for the current state, method and direction.
+ <li>Painter specified for the current state and method.
+ <li>Painter specified for the current state.
+ <li>Painter specified for the style, method and direction.
+ <li>Painter specified for the style and method.
+ <li>Painter specified for the style.
+ </ol>
+ <p>
+ Consider the following:
+ </p>
+ <div class="example">
+ <pre>
+<style id="test">
+ <painter idref="fallbackPainter"/>
+ <painter idref="styleButtonBackgroundPainter" method="buttonBackground"/>
+ <state value="SELECTED">
+ <painter idref="stateFallbackPainter"/>
+ <painter idref="stateButtonBackgroundPainter" method="buttonBackground"/>
+ </state>
+</style>
+ </pre>
+ </div>
+ <p>
+ The following outlines which painter will be used for what
+ SynthPainter method:
+ </p>
+ <table border=1 summary="Painters for SynthPainter methods">
+ <tr><th>State<th>Method<th>Painter
+ <tr><td>SELECTED<td>paintButtonBackground<td>stateButtonBackgroundPainter
+ <tr><td>SELECTED<td>Anything but paintButtonBackground<td>stateFallbackPainter
+ <tr><td>Anything but SELECTED<td>paintButtonBackground<td>styleButtonBackgroundPainter
+ <tr><td>Anything but SELECTED<td>Anything but paintButtonBackground<td>fallbackPainter
+ </table>
+
+ <p>
+ When several identical painters are declared, they are aggregated into
+ a single one. Two painters are identical if their <em>direction</em> and
+ <em>method</em> attributes values are equal. Consider the following:
+ </p>
+
+ <div class="example">
+ <pre>
+<style id="panelStyle">
+ <imagePainter method="panelBackground" path="red.png" />
+ <imagePainter method="panelBackground" path="green.png" />
+ <imagePainter method="panelBackground" path="blue.png" />
+</style>
+ </pre>
+ </div>
+
+ <p>
+ These three painters are identical for they use the same method and the
+ same direction (all directions by default). Synth aggregates these painters
+ to create a single one that will paint its children painters in the order
+ of declaration. Hence, Synth will first paint the red picture, then the green
+ one and finally the blue one. Each child painter can be seen as a layer of
+ the aggregate painter.
+ </p>
+ <p>
+ Painter aggregation, or multi-layering, is very useful to reuse elements.
+ Imagine you want to use an highlight effect on buttons and on selected
+ menu items. With painter aggregation, you just need to create a separate
+ highlighting painter instead of having buttons and menu items painters
+ handle it.
+ </p>
+
+ <h3>The imagePainter element</h3>
+<div class="dtd-fragment">
+<pre class="dtd-fragment">
+<!ELEMENT <a name="e.imagePainter">imagePainter</a> EMPTY>
+<!ATTLIST imagePainter
+ <a href="#imagePainter.id">id</a> ID #IMPLIED
+ <a href="#imagePainter.method">method</a> CDATA #IMPLIED
+ <a href="#imagePainter.direction">direction</a> (north|south|east|west|top|left|bottom|right|horizontal|vertical|horizontal_split|vertical_split) #IMPLIED
+ <a href="#imagePainter.path">path</a> CDATA #REQUIRED
+ <a href="#imagePainter.sourceInsets">sourceInsets</a> CDATA #IMPLIED
+ <a href="#imagePainter.destinationInsets">destinationInsets</a> CDATA #IMPLIED
+ <a href="#imagePainter.painterCenter">paintCenter</a> (true|false) "true"
+ <a href="#imagePainter.stretch">stretch</a> (true|false) "true"
+ <a href="#imagePainter.center">center</a> (true|false) "false"
+>
+</pre>
+</div>
+ <p><em>Attribute definitions</em></p>
+ <dl>
+ <dt><a name="imagePainter.id"><samp>id</samp></a></dt>
+ <dd>Unique identifier for the imagePainter.</dd>
+ <dt><a name="imagePainter.method"><samp>method</samp></a></dt>
+ <dd>Identifies the SynthPainter method this is to be used for. The name
+ corresponds to the method name of a paint method in SynthPainter
+ with the paint prefix dropped, the remainder is case
+ insensitive (using the latin1 case folding rules).
+ For example SynthPainter.paintButtonBackground is identified by
+ 'buttonBackground' or 'buttonbackground'. If this is
+ not specified the painter is used for all methods that don't have a
+ a specific painter for them.</dd>
+ <dt><a name="imagePainter.direction"><samp>direction</samp></a></dt>
+ <dd>Identifies the direction, or orientation, this image is to be
+ used for. This is only useful for the SynthPainter methods that take
+ a direction or orientation. If this is not specified the image is
+ used for all directions.</dd>
+ <dt><a name="imagePainter.path"><samp>path</samp></a></dt>
+ <dd>Path to the image. Path to the image. If SynthLookAndFeel.load is
+ passed a Class this will use the Class method getResource (with with the
+ Class suplied to the load method). If load is passed a URL this will use the
+ URL constructor URL(context, path) to resolve the path.</dd>
+ <dt><a name="imagePainter.sourceInsets"><samp>sourceInsets</samp></a></dt>
+ <dd>Insets on the source image. This is top, left, bottom, right with
+ each component separated by a space.</dd>
+ <dt><a name="imagePainter.destinationInsets"><samp>destinationInsets</samp></a></dt>
+ <dd>Insets of the destination image. This is top, left, bottom, right with
+ each component separated by a space. If not specified the
+ <a href="#imagePainter.sourceInsets">sourceInsets</a> are used.</dd>
+ <dt><a name="imagePainter.painterCenter"><samp>paintCenter</samp></a></dt>
+ <dd>Whether or not the center of the image should be drawn.</dd>
+ <dt><a name="imagePainter.stretch"><samp>stretch</samp></a></dt>
+ <dd>Whether or not the north, south, east and west components of the
+ resulting image should be scaled or tiled.</dd>
+ <dt><a name="imagePainter.center"><samp>center</samp></a></dt>
+ <dd>Whether or not the image is centered.</dd>
+ </dl>
+ <p>
+ The <a href="#e.imagePainter">ImagePainter</a> element defines a
+ painter for the current style or state that will render using
+ the specified image. ImagePainter offers two distinct rendering
+ modes. The first mode is used to center an image in the space
+ provided. This is
+ commonly used in rendering decorations on top of a widget, for
+ example, to specify an arrow for a scroll button use the center
+ mode. The following example illustrates this:
+ <div class="example">
+ <pre>
+<style id="test">
+ <imagePainter path="resources/myImage.png" center="true"/>
+</style>
+ </pre>
+</div>
+ <p>
+ The second mode is used in scaling an image to fit in the
+ provided space. In this mode sourceInsets is used to specify a
+ border around an image where the north, south, east and west
+ edges of the border are either stretched or tiled (stretch
+ attribute), the four corners of the border drawn in place, and
+ the center is stretched. In this mode you must specify
+ sourceInsets. The following example illustrates an
+ ImagePainter that is using the image MyImage.png and insets of 2
+ all the way around:
+ </p>
+ <div class="example">
+ <pre>
+<style id="test">
+ <imagePainter path="resources/myImage.png"
+ sourceInsets="2 2 2 2"/>
+</style>
+ </pre>
+</div>
+ <p>
+ Refer to the description of the <a href="#e.painter">painter</a>
+ element for details as to the precedence in choosing a painter and to
+ understand how identical painters are handled.
+
+
+ <h3>The imageIcon element</h3>
+<div class="dtd-fragment">
+<pre class="dtd-fragment">
+<!ELEMENT <a name="e.imageIcon">imageIcon</a> EMPTY>
+<!ATTLIST imageIcon
+ <a href="#imageIcon.id">id</a> ID #REQUIRED
+ <a href="#imageIcon.path">path</a> CDATA #REQUIRED
+>
+</pre>
+</div>
+ <p><em>Attribute definitions</em></p>
+ <dl>
+ <dt><a name="imageIcon.id"><samp>id</samp></a></dt>
+ <dd>Unique identifier for the imageIcon.</dd>
+ <dt><a name="imageIcon.path"><samp>path</samp></a></dt>
+ <dd>Path to the image. This uses the Class method
+ getResource to resolve the path, with the Class supplied to
+ SynthLookAndFeel.load.</dd>
+ </dl>
+ <p>
+ <a href="#e.imageIcon">ImageIcon</a> is used to assign an Icon
+ implementation that is wrapping an Image to a unique identifier.
+ This is typically used for properties that take an Icon. The following
+ example binds an ImageIcon to the property RadioButton.icon.
+ </p>
+ <div class="example">
+ <pre>
+<style id="test">
+ <imageIcon id="icon" path="resources/myImage.png"/>
+ <property key="RadioButton.icon" value="icon"/>
+</style>
+ </pre>
+</div>
+
+ <h3>The opaque element</h3>
+<div class="dtd-fragment">
+<pre class="dtd-fragment">
+<!ELEMENT <a name="e.opaque">opaque</a> EMPTY>
+<!ATTLIST opaque
+ <a href="#opaque.value">value</a> (true|false) "true"
+>
+</pre>
+</div>
+ <p><em>Attribute definitions</em></p>
+ <dl>
+ <dt><a name="opaque.value"><samp>id</samp></a></dt>
+ <dd>Whether or not the style should be opaque, if unspecified the style
+ is opaque.</dd>
+ </dl>
+ <p>
+ The <a href="#e.opaque">opaque</a> element indicates whether or
+ not any Components the style is associated with are to be made opaque.
+ The painter will be asked to paint regardless of the opacity
+ of the associated Component. The following example creates a style
+ that is not opaque.
+ </p>
+ <div class="example">
+ <pre>
+<style id="test">
+ <opaque value="FALSE">
+ <painter idref="painter"/>
+</style>
+ </pre>
+</div>
+
+ <h3><a name="ee.beansPersistance">The beansPersistance entity</a></h3>
+ <p>
+ Beans persistance can be used to embed any Object. This is
+ typically used for embedding your own Painters, but can be used
+ for other arbritrary objects as well. Refer to <a
+ href="http://www.oracle.com/technetwork/java/persistence3-139471.html">http://www.oracle.com/technetwork/java/persistence3-139471.html</a> for details on beans persistance.
+
+
+ <h3>Backing Style</h3>
+ <p>
+ In creating a Synth file it's good practice to create a backing
+ style that is used by all components. This will make sure that
+ any components that do not match a specific style will have
+ a default font, foreground, background and opacity. The
+ following example illustrates this:
+ <div class="example">
+ <pre>
+<synth>
+ <style id="backingStyle">
+ <opaque value="true"/>
+ <font name="Dialog" size="12"/>
+ <state>
+ <color value="BLACK" type="BACKGROUND"/>
+ <color value="WHITE" type="FOREGROUND"/>
+ </state>
+ </style>
+ <bind style="backingStyle" type="region" key=".*"/>
+</synth>
+ </pre>
+ </div>
+
+ </body>
+</html>