1 <!doctype html>
2 <html lang="en">
3 <head>
4 <meta charset="utf-8"/>
5 <title>Synth File Format</title>
6 <!--
7 Copyright (c) 1998, 2019, Oracle and/or its affiliates. All rights reserved.
8 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
9
10 This code is free software; you can redistribute it and/or modify it
11 under the terms of the GNU General Public License version 2 only, as
12 published by the Free Software Foundation. Oracle designates this
13 particular file as subject to the "Classpath" exception as provided
14 by Oracle in the LICENSE file that accompanied this code.
15
16 This code is distributed in the hope that it will be useful, but WITHOUT
17 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
18 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
19 version 2 for more details (a copy is included in the LICENSE file that
20 accompanied this code).
21
22 You should have received a copy of the GNU General Public License version
23 2 along with this work; if not, write to the Free Software Foundation,
24 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
25
26 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
27 or visit www.oracle.com if you need additional information or have any
28 questions.
29 -->
30
31 <style type="text/css">
32 div.dtd-fragment {
33 width: 100%;
34 border: none;
35 background-color: #eee;
36 }
37 pre.dtd-fragment {
38 margin-left: 0;
39 }
40 div.example {
41 width: 100%;
42 color: maroon;
43 }
44 </style>
45 </head>
46
47 <body>
48 <main role="main">
49 <h1><a id="file">File Format</a></h1>
50 <p>
51 Synth's file format (<a href="synth.dtd">dtd</a>)
52 allows for specifying all the pieces
53 necessary to create your own look and feel. A synth file is
54 loaded by way of the <A
55 HREF="../../../../../javax/swing/plaf/synth/SynthLookAndFeel.html#load(java.io.InputStream,java.lang.Class)">
56 SynthLookAndFeel.load(InputStream, Class)</a> or
57 <a href="../../../../../javax/swing/plaf/synth/SynthLookAndFeel.html#load(java.net.URL)">
58 SynthLookAndFeel.load(URL)</a> methods.
59 The following example uses the <code>load</code> method to configure
60 a <code>SynthLookAndFeel</code> and sets it as the current look
61 and feel:
62 </p>
63 <div class="example">
64 <pre>
65 SynthLookAndFeel laf = new SynthLookAndFeel();
66 laf.load(MyClass.class.getResourceAsStream("laf.xml"), MyClass.class);
67 UIManager.setLookAndFeel(laf);
68 </pre>
69 </div>
70 <p>
71 This example loads the look and feel from an input stream, using
72 the specified class as the resource base to resolve paths.
73 It is also possible to load a look and feel from an arbitrary URL
74 as in the following example.
75 </p>
76 <div class="example">
77 <pre>
78 SynthLookAndFeel laf = new SynthLookAndFeel();
79 laf.load(new URL("file:///C:/java/synth/laf/laf.xml"));
80 UIManager.setLookAndFeel(laf);
81 </pre>
82 </div>
83 <p>
84 The method <a
85 href="../../../../../javax/swing/plaf/synth/SynthLookAndFeel.html#load(java.net.URL)">
86 SynthLookAndFeel.load(URL)</a> can be used, for instance, to load a look
87 and feel from any of the following:
88 </p>
89 <ul>
90 <li>File, e.g. <code>file:///C:/java/synth/laf/laf.xml</code></li>
91 <li>Web server, e.g. <code>http://host/laf.xml</code></li>
92 <li>JAR file, e.g.
93 <code>jar:file:///C:/synth-laf.jar!/laf.xml</code></li>
94 <li>Remote JAR file, e.g.
95 <code>jar:http://host/synth-laf.jar!/laf.xml</code></li>
96 </ul>
97 <p>
98 While the DTD for synth is specified, the parser is not validating.
99 Parsing will fail only if a necessary attribute is not
100 specified, or of the wrong type.
101
102 <h2>The synth element</h2>
103 <div class="dtd-fragment">
104 <pre class="dtd-fragment">
105 <!ELEMENT <a id="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> |
106 <a href="#e.imagePainter">imagePainter</a> | <a href="#e.imageIcon">imageIcon</a> | <a href="#e.defaultsProperty">defaultsProperty</a>)*>
107 <!ATTLIST synth
108 <a href="#synth.version">version</a> CDATA #IMPLIED
109 >
110 </pre>
111 </div>
112 <p><em>Attribute definitions</em></p>
113 <dl><dt><a id="synth.version"><samp>version</samp></a></dt>
114 <dd>File format version, should be 1</dd>
115 </dl>
116 <p>
117 The <a href="#e.synth">synth</a> element contains all the other
118 elements that make up a SynthLookAndFeel definition.
119 </p>
120
121
122 <h2>The style element</h2>
123 <div class="dtd-fragment">
124 <pre class="dtd-fragment">
125 <!ELEMENT <a id="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> |
126 <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>) |
127 <a href="#e.imageIcon">imageIcon</a>)*>
128 <!ATTLIST style
129 <a href="#style.id">id</a> ID #IMPLIED
130 <a href="#style.clone">clone</a> IDREF #IMPLIED
131 >
132 </pre>
133 </div>
134 <p><em>Attribute definitions</em></p>
135 <dl>
136 <dt><a id="style.id"><samp>id</samp></a></dt>
137 <dd>Unique identifier for the style.</dd>
138 <dt><a id="style.clone"><samp>clone</samp></a></dt>
139 <dd>Identifier of a previously defined style that is copied
140 and used for the new style. This provides a convenient
141 mechanism for overriding only a portion of an existing
142 style.</dd>
143 </dl>
144 <p>
145 A style element corresponds to a
146 <code>SynthStyle</code>, with the child elements specifying
147 properties that apply to all states or state elements which
148 contain properties specific to a particular state. The following
149 example creates an opaque style with the id <code>button</code>,
150 insets of 4, 4, 4, 4 and a font of Dialog 12.
151 </p>
152 <div class="example">
153 <pre>
154 <style id="button">
155 <opaque value="true"/>
156 <insets top="4" left="4" right="4" bottom="4"/>
157 <font name="Dialog" size="12"/>
158 </style>
159 </pre>
160 </div>
161 <p>
162 The following example creates a new style with an id of
163 <code>clonedButton</code> that is a copy of the
164 style with id <code>button</code> and has a font of Dialog,
165 14. The resulting style will be opaque, have insets of 4, 4, 4,
166 4 and a font of Dialog 14.
167 </p>
168 <div class="example">
169 <pre>
170 <style id="clonedButton" clone="button">
171 <font name="Dialog" size="14"/>
172 </style>
173 </pre>
174 </div>
175
176 <h2>The state element</h2>
177 <div class="dtd-fragment">
178 <pre class="dtd-fragment">
179 <!ELEMENT <a id="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>) |
180 <a href="#e.property">property</a> | <a href="#e.imageIcon">imageIcon</a>)*>
181 <!ATTLIST state
182 <a href="#state.id">id</a> ID #IMPLIED
183 <a href="#state.clone">clone</a> IDREF #IMPLIED
184 <a href="#state.value">value</a> CDATA #IMPLIED
185 <a href="#state.idref">idref</a> IDREF #IMPLIED
186 >
187 </pre>
188 </div>
189 <p><em>Attribute definitions</em></p>
190 <dl>
191 <dt><a id="state.id"><samp>id</samp></a></dt>
192 <dd>Unique identifier for the state.</dd>
193 <dt><a id="state.clone"><samp>clone</samp></a></dt>
194 <dd>Identifier of a previously defined state that is copied
195 and used for the new state.</dd>
196 <dt><a id="state.value"><samp>value</samp></a></dt>
197 <dd>Identifies the state of the Component the properties are to apply
198 to. This is a list of: ENABLED,
199 MOUSE_OVER, PRESSED, DISABLED, FOCUSED, SELECTED or
200 DEFAULT. Multiple states should
201 be separated by 'and.' If you do not specify a value, the
202 contents apply to all states.
203 <dt><a id="state.idref"><samp>idref</samp></a></dt>
204 <dd>Indicates this state should be the same as a previously
205 defined state. This is useful for multiple styles that
206 wish to share the same visual properties for a particular
207 state.
208 </dd>
209 </dl>
210 <p>
211 The <a href="#e.state">state</a> element specifies the visual
212 properties that are to be used for
213 a particular state of a component. For example, you could
214 specify the background color when the Component is enabled should look
215 different than the background color when the component is
216 disabled. Not all Components support all states. For example, a
217 <code>Panel</code> only supports the states ENABLED and DISABLED.
218 </p>
219 <p>
220 The following example creates a state with a red background that
221 will be used when the component is in an a selected and pressed state:
222 </p>
223 <div class="example">
224 <pre>
225 <state value="SELECTED AND PRESSED">
226 <color value="RED" type="BACKGROUND"/>
227 </state>
228 </pre>
229 </div>
230 <p>
231 The state with the most individual matches will be
232 chosen. For example, the following defines two states:
233 </p>
234 <div class="example">
235 <pre>
236 <state value="SELECTED and PRESSED" id="one">
237 <color value="RED" type="BACKGROUND"/>
238 </state>
239 <state value="SELECTED" id="two">
240 <color value="RED" type="BACKGROUND"/>
241 </state>
242 </pre>
243 </div>
244 <p>
245 State <code>one</code> is used when the Component is SELECTED
246 and PRESSED, and state <code>two</code> when the Component is
247 SELECTED. If the state of the Component
248 contains at least SELECTED and PRESSED, state <code>one</code> will be
249 chosen, otherwise if the state is SELECTED, but not does not
250 contain PRESSED, state <code>two</code> will be used.
251
252 <h2>The font element</h2>
253 <div class="dtd-fragment">
254 <pre class="dtd-fragment">
255 <!ELEMENT <a id="e.font">font</a> EMPTY>
256 <!ATTLIST font
257 <a href="#font.id">id</a> ID #IMPLIED
258 <a href="#font.idref">clone</a> IDREF #IMPLIED
259 <a href="#font.name">name</a> CDATA #IMPLIED
260 <a href="#font.style">style</a> CDATA #IMPLIED
261 <a href="#font.size">size</a> CDATA #IMPLIED
262 >
263 </pre>
264 </div>
265 <p><em>Attribute definitions</em></p>
266 <dl>
267 <dt><a id="font.id"><samp>id</samp></a></dt>
268 <dd>Unique identifier for the Font.</dd>
269 <dt><a id="font.idref"><samp>idref</samp></a></dt>
270 <dd>Identifier of a previously defined font.</dd>
271 <dt><a id="font.name"><samp>name</samp></a></dt>
272 <dd>Name of the font.
273 <dt><a id="font.style"><samp>style</samp></a></dt>
274 <dd>Style of the font. This is a list of the styles defined by
275 Font separated by spaces: PLAIN, BOLD or ITALIC. If
276 unspecified PLAIN is used.
277 </dd>
278 <dt><a id="font.size"><samp>size</samp></a></dt>
279 <dd>Size of the font, in pixels</dd>
280 </dl>
281 <p>
282 Defines the font for the current <a href="#e.state">state</a>,
283 or <a href="#e.style">style</a>. You must
284 specify either an <a href="#font.idref">idref</a> or a
285 <a href="#font.name">name</a> and <a href="#font.size">size</a>.
286 </p>
287 <p>
288 The following example creates a style with a Font of
289 Dialog 12 Bold.
290 </p>
291 <div class="example">
292 <pre>
293 <style id="test">
294 <font name="DIALOG" size="12" style="BOLD"/>
295 </style>
296 </pre>
297 </div>
298 <p>
299 The following example creates a style with a font of
300 Dialog 12 Bold that will be used if the component is ENABLED,
301 otherwise Dialog 12 Italic will be used.
302 </p>
303 <div class="example">
304 <pre>
305 <style id="test">
306 <font name="DIALOG" size="12" style="ITALIC"/>
307 <state value="ENABLED">
308 <font name="DIALOG" size="12" style="BOLD"/>
309 </state>
310 </style>
311 </pre>
312 </div>
313 <p>
314 While you can supply a different font per state, in general
315 widgets will NOT revalidate when the state changes, so that you
316 may run into sizing problems if you try to use a font with a
317 significantly different size for different states.
318 </p>
319
320
321 <h2>The color element</h2>
322 <div class="dtd-fragment">
323 <pre class="dtd-fragment">
324 <!ELEMENT <a id="e.color">color</a> EMPTY>
325 <!ATTLIST color
326 <a href="#color.id">id</a> ID #IMPLIED
327 <a href="#color.idref">idref</a> IDREF #IMPLIED
328 <a href="#color.type">type</a> CDATA #IMPLIED
329 <a href="#color.value">value</a> CDATA #IMPLIED
330 >
331 </pre>
332 </div>
333 <p><em>Attribute definitions</em></p>
334 <dl>
335 <dt><a id="color.id"><samp>id</samp></a></dt>
336 <dd>Unique identifier for the color.</dd>
337 <dt><a id="color.idref"><samp>idref</samp></a></dt>
338 <dd>Identifier of a previously defined color.</dd>
339 <dt><a id="color.type"><samp>type</samp></a></dt>
340 <dd>Describes where this color should be used. This is
341 typically one of the constants defined by ColorType:
342 FOREGROUND, BACKGROUND, TEXT_FOREGROUND, TEXT_BACKGROUND
343 or FOCUS. Alternatively you can specify the complete path
344 to a class and field, for example
345 javax.swing.plaf.synth.ColorType.FOREGROUND, this
346 is useful for subclasses of synth that define additional
347 color types.
348 </dd>
349 <dt><a id="color.value"><samp>value</samp></a></dt>
350 <dd>
351 Value for the color. This accepts the following forms.
352 <ul>
353 <li>The name of a constant in the <code>Color</code> class,
354 for example <code> RED</code>.
355 <li>A hex value of the form <code>#RRGGBB</code> where
356 <code>RR</code> gives the red component, <code>GG</code>
357 the green component and <code>BB</code> the blue
358 component. You need not specify all color components. For
359 example, <code>#123</code> is equivalent to <code>#000123</code>.
360 <li>A hex value of the form <code>#ARRGGBB</code> or
361 <code>#AARRGGBB</code>. This is useful for alpha values
362 other than <code>0xFF</code>. The form
363 <code>#ARRGGBB</code> is equivalent to
364 <code>#0ARRGGBB</code>.
365 </ul>
366 </dd>
367 </dl>
368 <p>
369 <a href="#e.color">Color</a> defines a color and what portion of
370 the Component it should be applied to. The following example
371 will use a background color of RED when the component is
372 enabled.
373 </p>
374 <div class="example">
375 <pre>
376 <state value="ENABLED">
377 <color value="RED" type="BACKGROUND"/>
378 </state>
379 </pre>
380 </div>
381 <p>
382 The following example will have a red background when the
383 Component is enabled, otherwise blue.
384 </p>
385 <div class="example">
386 <pre>
387 <style id="test">
388 <state value="ENABLED">
389 <color value="RED" type="BACKGROUND"/>
390 </state>
391 <state>
392 <color value="#00FF00" type="BACKGROUND"/>
393 </state>
394 </style>
395 </pre>
396 </div>
397
398 <h2>The property element</h2>
399 <div class="dtd-fragment">
400 <pre class="dtd-fragment">
401 <!ELEMENT <a id="e.property">property</a> EMPTY>
402 <!ATTLIST property
403 <a href="#property.key">key</a> CDATA #REQUIRED
404 <a href="#property.type">type</a> (idref|boolean|dimension|insets|integer|string) "idref"
405 <a href="#property.value">value</a> CDATA #REQUIRED
406 >
407 </pre>
408 </div>
409 <p><em>Attribute definitions</em></p>
410 <dl>
411 <dt><a id="property.key"><samp>key</samp></a></dt>
412 <dd>Name of the property.</dd>
413 <dt><a id="property.type"><samp>type</samp></a></dt>
414 <dd>Indicates the type of the property.</dd>
415 <dt><a id="property.value"><samp>value</samp></a></dt>
416 <dd>Value for the property. For boolean properties this will be
417 be true or false, for integer properties this will be a
418 valid integer, for dimensions this will be the width and
419 height separated by a space, for insets properties this will
420 be the top, left, bottom and right separated by a space and
421 for idref properties this will be the unique id of a
422 previously defined object.</dd>
423 </dl>
424 <p>
425 <a href="#e.property">Property</a> elements are used to add key value pairs to a
426 <code>SynthStyle</code> that can be accessed by way of the
427 <code>get</code> method. Many <code>Component</code>s use the
428 key value pairs for configuring their visual appearance. Refer to
429 <a href="componentProperties.html">property table</a> for a list of the
430 properties each <code>Component</code> supports. The following
431 creates the properties
432 <code>ScrollBar.allowsAbsolutePositioning</code>,
433 <code>OptionPane.minimumSize</code>,
434 <code>ScrollPane.viewportBorderInsets</code>,
435 <code>Tree.rowHeight</code> and <code>foreground</code> with the
436 values false, a dimensions of 262x90, an insets of 5, 5, 5, 5,
437 the integer 20 and an instance of the
438 class ArrowButtonPainter.
439 </p>
440 <div class="example">
441 <pre>
442 <style id="test">
443 <property key="ScrollBar.allowsAbsolutePositioning" type="boolean" value="false"/>
444 <property key="OptionPane.minimumSize" type="dimension" value="262 90"/>
445 <property key="ScrollPane.viewportBorderInsets" type="insets" value="5 5 5 5"/>
446 <property key="Tree.rowHeight" type="integer" value="20"/>
447 <object class="ArrowButtonPainter" id="ArrowButtonPainter"/>
448 <property key="foreground" type="idref" value="ArrowButtonPainter"/>
449 </style>
450 </pre>
451 </div>
452 <p>
453 You can also specify properties that are to apply to specific
454 states. Whether or not the property is accessed for each state
455 depends upon how the property is used. For example, the
456 following specifies a default icon and an icon to use while the
457 mouse is over the component.
458 </p>
459 <div class="example">
460 <pre>
461 <style id="test">
462 <imageIcon id="defaultIcon" path="resources/myImage.png"/>
463 <property key="RadioButton.icon" value="defaultIcon"/>
464 <state value="MOUSE_OVER">
465 <imageIcon id="mouseOverIcon" path="resources/myMouseOverImage.png"/>
466 <property key="RadioButton.icon" value="mouseOverIcon"/>
467 </state>
468 </style>
469 </pre>
470 </div>
471 <div class="dtd-fragment">
472 <pre class="dtd-fragment">
473 <!ELEMENT <a id="e.defaultsProperty">defaultsProperty</a> EMPTY>
474 <!ATTLIST defaultsProperty
475 <a href="#defaultsProperty.key">key</a> CDATA #REQUIRED
476 <a href="#defaultsProperty.type">type</a> (idref|boolean|dimension|insets|integer|string) "idref"
477 <a href="#defaultsProperty.value">value</a> CDATA #REQUIRED
478 >
479 </pre>
480 </div>
481 <p><em>Attribute definitions</em></p>
482 <dl>
483 <dt><a id="defaultsProperty.key"><samp>key</samp></a></dt>
484 <dd>Name of the property.</dd>
485 <dt><a id="defaultsProperty.type"><samp>type</samp></a></dt>
486 <dd>Indicates the type of the property.</dd>
487 <dt><a id="defaultsProperty.value"><samp>value</samp></a></dt>
488 <dd>Value for the property. For boolean properties this will be
489 true or false, for integer properties this will be a
490 valid integer, for dimensions this will be the width and
491 height separated by a space, for insets properties this will
492 be the top, left, bottom and right separated by a space and
493 for idref properties this will be the unique id of a
494 previously defined object.</dd>
495 </dl>
496 <p>
497 <a href="#e.defaultsProperty">DefaultsProperty</a> elements are
498 used to define properties that will be placed in the
499 <code>UIDefaults</code> table that <code>SynthLookAndFeel</code>
500 supplies to the <code>UIManager</code>. The following assigns the
501 the Color red to the value Table.focusCellForeground.
502 </p>
503 <div class="example">
504 <pre>
505 <style id="test">
506 <object class="javax.swing.plaf.ColorUIResource" id="color">
507 <int>255</int>
508 <int>0</int>
509 <int>0</int>
510 </object>
511 <defaultsProperty key="Table.focusCellForeground" type="idref" value="color"/>
512 </style>
513 </pre>
514 </div>
515 <p>
516 This value could then be asked by way of
517 <code>UIManager.get("Table.focusCellForeground")</code>.
518 </p>
519
520 <h2>The graphicsUtils element</h2>
521 <div class="dtd-fragment">
522 <pre class="dtd-fragment">
523 <!ELEMENT <a id="e.graphicsUtils">graphicsUtils</a> EMPTY>
524 <!ATTLIST graphicsUtils
525 <a href="#graphicsUtils.idref">idref</a> IDREF #REQUIRED
526 >
527 </pre>
528 </div>
529 <p><em>Attribute definitions</em></p>
530 <dl>
531 <dt><a id="graphicsUtils.idref"><samp>idref</samp></a></dt>
532 <dd>Identifer of a previously defined SynthGraphicsUtils object
533 that is to be used as the SynthGraphicsUtils for the current
534 <a href="#e.style">style</a>.</dd>
535 </dl>
536 <p>
537 <a href="#e.graphicsUtils">GraphicsUtils</a> elements are
538 used to define the SynthGraphicsUtils that the current
539 <a href="#e.style">style</a> will use. The following example
540 creates a style with an instance of CustomGraphicsUtils for the
541 SynthGraphicsUtils.
542 </p>
543 <div class="example">
544 <pre>
545 <style id="test">
546 <object class="CustomGraphicsUtils" id="graphics"/>
547 <graphicsUtils idref="graphics"/>
548 </style>
549 </pre>
550 </div>
551
552 <h2>The insets element</h2>
553 <div class="dtd-fragment">
554 <pre class="dtd-fragment">
555 <!ELEMENT <a id="e.insets">insets</a> EMPTY>
556 <!ATTLIST insets
557 <a href="#insets.id">id</a> ID #IMPLIED
558 <a href="#insets.idref">idref</a> IDREF #IMPLIED
559 <a href="#insets.top">top</a> CDATA #IMPLIED
560 <a href="#insets.bottom">bottom</a> CDATA #IMPLIED
561 <a href="#insets.left">left</a> CDATA #IMPLIED
562 <a href="#insets.right">right</a> CDATA #IMPLIED
563 >
564 </pre>
565 </div>
566 <p><em>Attribute definitions</em></p>
567 <dl>
568 <dt><a id="insets.id"><samp>id</samp></a></dt>
569 <dd>Unique identifier for the Insets.</dd>
570 <dt><a id="insets.idref"><samp>idref</samp></a></dt>
571 <dd>Identifier of a previously defined Insets.</dd>
572 <dt><a id="insets.top"><samp>top</samp></a></dt>
573 <dd>Top component of the Insets.</dd>
574 <dt><a id="insets.bottom"><samp>bottom</samp></a></dt>
575 <dd>Bottom component of the Insets.</dd>
576 <dt><a id="insets.left"><samp>left</samp></a></dt>
577 <dd>Left component of the Insets.</dd>
578 <dt><a id="insets.right"><samp>right</samp></a></dt>
579 <dd>Right component of the Insets.</dd>
580 </dl>
581 <p>
582 <a href="#e.insets">Insets</a> elements are
583 used to define the Insets for the current <a href="#e.style">style</a>.
584 The insets will be set on any Components the
585 <a href="#e.style">style</a> is associated with. The following
586 example creates a style with insets of 1, 2, 3, 0.
587 </p>
588 <div class="example">
589 <pre>
590 <style id="test">
591 <insets top="1" bottom="2" left="3"/>
592 </style>
593 </pre>
594 </div>
595
596 <h2>The bind element</h2>
597 <div class="dtd-fragment">
598 <pre class="dtd-fragment">
599 <!ELEMENT <a id="e.bind">bind</a> EMPTY>
600 <!ATTLIST bind
601 <a href="#bind.style">style</a> IDREF #REQUIRED
602 <a href="#bind.type">type</a> (name|region) #REQUIRED
603 <a href="#bind.key">key</a> CDATA #REQUIRED
604 >
605 </pre>
606 </div>
607 <p><em>Attribute definitions</em></p>
608 <dl>
609 <dt><a id="bind.style"><samp>style</samp></a></dt>
610 <dd>Unique identifier of a previously defined style.</dd>
611 <dt><a id="bind.type"><samp>type</samp></a></dt>
612 <dd>One of name or region. For type name component.getName() is used,
613 otherwise the name of the Region is used.</dd>
614 <dt><a id="bind.key"><samp>key</samp></a></dt>
615 <dd>Regular expression applied to the name of the Component, or the
616 name of the Region, depending upon the value of
617 <a href="#bind.type">type</a>.</dd>
618 </dl>
619 <p>
620 <a href="#e.bind">Bind</a> elements specify which Regions a style
621 is to be used for. The following example applies the
622 <a href="#e.style">style</a> test to any Component whose name
623 starts with <code>test</code>.
624 </p>
625 <div class="example">
626 <pre>
627 <style id="test">
628 <insets top="1" bottom="2" left="3"/>
629 </style>
630 <bind style="test" type="name" key="test.*"/>
631 </pre>
632 </div>
633 <p>
634 Numerous styles may apply to a region, in which case each of
635 the matching styles is merged into a resulting style that is used.
636 Precedence is given to styles defined later in the file. For example,
637 the following defines two styles, a and b. Style a is applied to any
638 component with a name starting with test, and style b is used for
639 button regions.
640 </p>
641 <div class="example">
642 <pre>
643 <style id="a">
644 <font name="DIALOG" size="12" style="ITALIC"/>
645 <insets top="1" bottom="2" left="3"/>
646 </style>
647 <bind style="a" type="name" key="test.*"/>
648 <style id="b">
649 <font name="DIALOG" size="12" style="BOLD"/>
650 </style>
651 <bind style="b" type="region" key="button"/>
652 </pre>
653 </div>
654 <p>
655 For a button with the name test this is equivalent to:
656 </p>
657 <div class="example">
658 <pre>
659 <style>
660 <font name="DIALOG" size="12" style="BOLD"/>
661 <insets top="1" bottom="2" left="3"/>
662 </style>
663 </pre>
664 </div>
665 <p>
666 Merging happens for states of a style as well.
667 </p>
668 <div class="example">
669 <pre>
670 <style id="a">
671 <font name="DIALOG" size="12" style="ITALIC"/>
672 <insets top="1" bottom="2" left="3"/>
673 <state value="ENABLED">
674 <object id="customPainter" class="CustomPainter"/>
675 <painter idref="customPainter"/>
676 </state>
677 </style>
678 <bind style="a" type="name" key="test.*"/>
679 <style id="b">
680 <font name="DIALOG" size="12" style="BOLD"/>
681 <state value="ENABLED">
682 <font name="Lucida" size="12" style="ITALIC"/>
683 </state>
684 </style>
685 <bind style="b" type="region" key="button"/>
686 </pre>
687 </div>
688 <p>
689 For a button with the name test this is equivalent to:
690 </p>
691 <div class="example">
692 <pre>
693 <style>
694 <font name="DIALOG" size="12" style="BOLD"/>
695 <insets top="1" bottom="2" left="3"/>
696 <state value="ENABLED">
697 <object id="customPainter" class="CustomPainter"/>
698 <painter idref="customPainter"/>
699 <font name="Lucida" size="12" style="ITALIC"/>
700 </state>
701 </style>
702 </pre>
703 </div>
704
705 <h2>The painter element</h2>
706 <div class="dtd-fragment">
707 <pre class="dtd-fragment">
708 <!ELEMENT <a id="e.painter">painter</a> EMPTY>
709 <!ATTLIST painter
710 <a href="#painter.idref">idref</a> IDREF #IMPLIED
711 <a href="#painter.method">method</a> CDATA #IMPLIED
712 <a href="#painter.direction">direction</a> (north|south|east|west|top|left|bottom|right|horizontal|vertical|horizontal_split|vertical_split) #IMPLIED
713 >
714 </pre>
715 </div>
716 <p><em>Attribute definitions</em></p>
717 <dl>
718 <dt><a id="painter.idref"><samp>idref</samp></a></dt>
719 <dd>Identifier of a previously defined SynthPainter.</dd>
720 <dt><a id="painter.method"><samp>method</samp></a></dt>
721 <dd>Identifies the SynthPainter method this is to be used for. The name
722 corresponds to the method name of a paint method in SynthPainter
723 with the paint prefix dropped, the remainder is case
724 insensitive (using the latin1 case folding rules).
725 For example SynthPainter.paintButtonBackground is identified by
726 'buttonBackground' or 'buttonbackground'. If this is
727 not specified the painter is used for all methods that don't have a
728 a specific painter for them.</dd>
729 <dt><a id="painter.direction"><samp>direction</samp></a></dt>
730 <dd>Identifies the direction, or orientation, this painter is to be
731 used for. This is only useful for the SynthPainter methods that take
732 a direction or orientation. If this is not specified the painter is
733 used for all directions.</dd>
734 </dl>
735 <p>
736 <a href="#e.painter">Painter</a> defines a SynthPainter for the current
737 style or the state of the current style. The following example
738 binds an instance of the class <code>MyPainter</code>
739 which must be a <code>SynthPainter</code> to the style <code>test</code>.
740 </p>
741 <div class="example">
742 <pre>
743 <style id="test">
744 <object class="MyPainter" id="MyPainter"/>
745 <painter idref="MyPainter"/>
746 </style>
747 </pre>
748 </div>
749 <p>
750 The painter that is used for a particular method and state is determined
751 as follows:
752 <ol>
753 <li>Painter specified for the current state, method and direction.
754 <li>Painter specified for the current state and method.
755 <li>Painter specified for the current state.
756 <li>Painter specified for the style, method and direction.
757 <li>Painter specified for the style and method.
758 <li>Painter specified for the style.
759 </ol>
760 <p>
761 Consider the following:
762 </p>
763 <div class="example">
764 <pre>
765 <style id="test">
766 <painter idref="fallbackPainter"/>
767 <painter idref="styleButtonBackgroundPainter" method="buttonBackground"/>
768 <state value="SELECTED">
769 <painter idref="stateFallbackPainter"/>
770 <painter idref="stateButtonBackgroundPainter" method="buttonBackground"/>
771 </state>
772 </style>
773 </pre>
774 </div>
775 <p>
776 The following outlines which painter will be used for what
777 SynthPainter method:
778 </p>
779 <table border=1>
780 <caption>Painters for SynthPainter methods</caption>
781 <thead>
782 <tr>
783 <th scope="col">Index
784 <th scope="col">State
785 <th scope="col">Method
786 <th scope="col">Painter
787 </thead>
788 <tbody>
789 <tr>
790 <th scope="row">1
791 <td>SELECTED
792 <td>paintButtonBackground<td>stateButtonBackgroundPainter
793 <tr>
794 <th scope="row">2
795 <td>SELECTED
796 <td>Anything but paintButtonBackground<td>stateFallbackPainter
797 <tr>
798 <th scope="row">3
799 <td>Anything but SELECTED
800 <td>paintButtonBackground<td>styleButtonBackgroundPainter
801 <tr>
802 <th scope="row">4
803 <td>Anything but SELECTED
804 <td>Anything but paintButtonBackground<td>fallbackPainter
805 </tbody>
806 </table>
807
808 <p>
809 When several identical painters are declared, they are aggregated into
810 a single one. Two painters are identical if their <em>direction</em> and
811 <em>method</em> attributes values are equal. Consider the following:
812 </p>
813
814 <div class="example">
815 <pre>
816 <style id="panelStyle">
817 <imagePainter method="panelBackground" path="red.png" />
818 <imagePainter method="panelBackground" path="green.png" />
819 <imagePainter method="panelBackground" path="blue.png" />
820 </style>
821 </pre>
822 </div>
823
824 <p>
825 These three painters are identical for they use the same method and the
826 same direction (all directions by default). Synth aggregates these painters
827 to create a single one that will paint its children painters in the order
828 of declaration. Hence, Synth will first paint the red picture, then the green
829 one and finally the blue one. Each child painter can be seen as a layer of
830 the aggregate painter.
831 </p>
832 <p>
833 Painter aggregation, or multi-layering, is very useful to reuse elements.
834 Imagine you want to use an highlight effect on buttons and on selected
835 menu items. With painter aggregation, you just need to create a separate
836 highlighting painter instead of having buttons and menu items painters
837 handle it.
838 </p>
839
840 <h2>The imagePainter element</h2>
841 <div class="dtd-fragment">
842 <pre class="dtd-fragment">
843 <!ELEMENT <a id="e.imagePainter">imagePainter</a> EMPTY>
844 <!ATTLIST imagePainter
845 <a href="#imagePainter.id">id</a> ID #IMPLIED
846 <a href="#imagePainter.method">method</a> CDATA #IMPLIED
847 <a href="#imagePainter.direction">direction</a> (north|south|east|west|top|left|bottom|right|horizontal|vertical|horizontal_split|vertical_split) #IMPLIED
848 <a href="#imagePainter.path">path</a> CDATA #REQUIRED
849 <a href="#imagePainter.sourceInsets">sourceInsets</a> CDATA #IMPLIED
850 <a href="#imagePainter.destinationInsets">destinationInsets</a> CDATA #IMPLIED
851 <a href="#imagePainter.painterCenter">paintCenter</a> (true|false) "true"
852 <a href="#imagePainter.stretch">stretch</a> (true|false) "true"
853 <a href="#imagePainter.center">center</a> (true|false) "false"
854 >
855 </pre>
856 </div>
857 <p><em>Attribute definitions</em></p>
858 <dl>
859 <dt><a id="imagePainter.id"><samp>id</samp></a></dt>
860 <dd>Unique identifier for the imagePainter.</dd>
861 <dt><a id="imagePainter.method"><samp>method</samp></a></dt>
862 <dd>Identifies the SynthPainter method this is to be used for. The name
863 corresponds to the method name of a paint method in SynthPainter
864 with the paint prefix dropped, the remainder is case
865 insensitive (using the latin1 case folding rules).
866 For example SynthPainter.paintButtonBackground is identified by
867 'buttonBackground' or 'buttonbackground'. If this is
868 not specified the painter is used for all methods that don't have a
869 a specific painter for them.</dd>
870 <dt><a id="imagePainter.direction"><samp>direction</samp></a></dt>
871 <dd>Identifies the direction, or orientation, this image is to be
872 used for. This is only useful for the SynthPainter methods that take
873 a direction or orientation. If this is not specified the image is
874 used for all directions.</dd>
875 <dt><a id="imagePainter.path"><samp>path</samp></a></dt>
876 <dd>Path to the image. Path to the image. If SynthLookAndFeel.load is
877 passed a Class this will use the Class method getResource (with with the
878 Class suplied to the load method). If load is passed a URL this will use the
879 URL constructor URL(context, path) to resolve the path.</dd>
880 <dt><a id="imagePainter.sourceInsets"><samp>sourceInsets</samp></a></dt>
881 <dd>Insets on the source image. This is top, left, bottom, right with
882 each component separated by a space.</dd>
883 <dt><a id="imagePainter.destinationInsets"><samp>destinationInsets</samp></a></dt>
884 <dd>Insets of the destination image. This is top, left, bottom, right with
885 each component separated by a space. If not specified the
886 <a href="#imagePainter.sourceInsets">sourceInsets</a> are used.</dd>
887 <dt><a id="imagePainter.painterCenter"><samp>paintCenter</samp></a></dt>
888 <dd>Whether or not the center of the image should be drawn.</dd>
889 <dt><a id="imagePainter.stretch"><samp>stretch</samp></a></dt>
890 <dd>Whether or not the north, south, east and west components of the
891 resulting image should be scaled or tiled.</dd>
892 <dt><a id="imagePainter.center"><samp>center</samp></a></dt>
893 <dd>Whether or not the image is centered.</dd>
894 </dl>
895 <p>
896 The <a href="#e.imagePainter">ImagePainter</a> element defines a
897 painter for the current style or state that will render using
898 the specified image. ImagePainter offers two distinct rendering
899 modes. The first mode is used to center an image in the space
900 provided. This is
901 commonly used in rendering decorations on top of a widget, for
902 example, to specify an arrow for a scroll button use the center
903 mode. The following example illustrates this:
904 <div class="example">
905 <pre>
906 <style id="test">
907 <imagePainter path="resources/myImage.png" center="true"/>
908 </style>
909 </pre>
910 </div>
911 <p>
912 The second mode is used in scaling an image to fit in the
913 provided space. In this mode sourceInsets is used to specify a
914 border around an image where the north, south, east and west
915 edges of the border are either stretched or tiled (stretch
916 attribute), the four corners of the border drawn in place, and
917 the center is stretched. In this mode you must specify
918 sourceInsets. The following example illustrates an
919 ImagePainter that is using the image MyImage.png and insets of 2
920 all the way around:
921 </p>
922 <div class="example">
923 <pre>
924 <style id="test">
925 <imagePainter path="resources/myImage.png"
926 sourceInsets="2 2 2 2"/>
927 </style>
928 </pre>
929 </div>
930 <p>
931 Refer to the description of the <a href="#e.painter">painter</a>
932 element for details as to the precedence in choosing a painter and to
933 understand how identical painters are handled.
934
935
936 <h2>The imageIcon element</h2>
937 <div class="dtd-fragment">
938 <pre class="dtd-fragment">
939 <!ELEMENT <a id="e.imageIcon">imageIcon</a> EMPTY>
940 <!ATTLIST imageIcon
941 <a href="#imageIcon.id">id</a> ID #REQUIRED
942 <a href="#imageIcon.path">path</a> CDATA #REQUIRED
943 >
944 </pre>
945 </div>
946 <p><em>Attribute definitions</em></p>
947 <dl>
948 <dt><a id="imageIcon.id"><samp>id</samp></a></dt>
949 <dd>Unique identifier for the imageIcon.</dd>
950 <dt><a id="imageIcon.path"><samp>path</samp></a></dt>
951 <dd>Path to the image. This uses the Class method
952 getResource to resolve the path, with the Class supplied to
953 SynthLookAndFeel.load.</dd>
954 </dl>
955 <p>
956 <a href="#e.imageIcon">ImageIcon</a> is used to assign an Icon
957 implementation that is wrapping an Image to a unique identifier.
958 This is typically used for properties that take an Icon. The following
959 example binds an ImageIcon to the property RadioButton.icon.
960 </p>
961 <div class="example">
962 <pre>
963 <style id="test">
964 <imageIcon id="icon" path="resources/myImage.png"/>
965 <property key="RadioButton.icon" value="icon"/>
966 </style>
967 </pre>
968 </div>
969
970 <h2>The opaque element</h2>
971 <div class="dtd-fragment">
972 <pre class="dtd-fragment">
973 <!ELEMENT <a id="e.opaque">opaque</a> EMPTY>
974 <!ATTLIST opaque
975 <a href="#opaque.value">value</a> (true|false) "true"
976 >
977 </pre>
978 </div>
979 <p><em>Attribute definitions</em></p>
980 <dl>
981 <dt><a id="opaque.value"><samp>id</samp></a></dt>
982 <dd>Whether or not the style should be opaque, if unspecified the style
983 is opaque.</dd>
984 </dl>
985 <p>
986 The <a href="#e.opaque">opaque</a> element indicates whether or
987 not any Components the style is associated with are to be made opaque.
988 The painter will be asked to paint regardless of the opacity
989 of the associated Component. The following example creates a style
990 that is not opaque.
991 </p>
992 <div class="example">
993 <pre>
994 <style id="test">
995 <opaque value="FALSE">
996 <painter idref="painter"/>
997 </style>
998 </pre>
999 </div>
1000
1001 <h2><a id="ee.beansPersistance">The beansPersistance entity</a></h2>
1002 <p>
1003 Beans persistance can be used to embed any Object. This is
1004 typically used for embedding your own Painters, but can be used
1005 for other arbritrary objects as well. Refer to <a
1006 href="http://www.oracle.com/technetwork/java/persistence3-139471.html">
1007 http://www.oracle.com/technetwork/java/persistence3-139471.html</a>
1008 for details on beans persistance.
1009
1010
1011 <h2>Backing Style</h2>
1012 <p>
1013 In creating a Synth file it's good practice to create a backing
1014 style that is used by all components. This will make sure that
1015 any components that do not match a specific style will have
1016 a default font, foreground, background and opacity. The
1017 following example illustrates this:
1018 <div class="example">
1019 <pre>
1020 <synth>
1021 <style id="backingStyle">
1022 <opaque value="true"/>
1023 <font name="Dialog" size="12"/>
1024 <state>
1025 <color value="BLACK" type="BACKGROUND"/>
1026 <color value="WHITE" type="FOREGROUND"/>
1027 </state>
1028 </style>
1029 <bind style="backingStyle" type="region" key=".*"/>
1030 </synth>
1031 </pre>
1032 </div>
1033 </main>
1034 </body>
1035 </html>