-
Notifications
You must be signed in to change notification settings - Fork 5.2k
/
synthFileFormat.html
1042 lines (1014 loc) · 40.3 KB
/
synthFileFormat.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<title>Synth File Format</title>
<!--
Copyright (c) 1998, 2022, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
particular file as subject to the "Classpath" exception as provided
by Oracle in the LICENSE file that accompanied this code.
This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).
You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
-->
<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>
<main role="main">
<h1><a id="file">File Format</a></h1>
<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,java.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.
</p>
<p>
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>Note: Synth's file format allows for the definition of code to be executed.
Loading any code from a remote location should be used only
with extreme caution from a trusted source over a secure connection.
It is strongly discouraged for an application or a LookAndFeel to do so.
</p>
<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.
<h2>The synth element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!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> |
<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 id="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>
<h2>The style element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!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> |
<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 id="style.id"><samp>id</samp></a></dt>
<dd>Unique identifier for the style.</dd>
<dt><a id="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>
<h2>The state element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!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>) |
<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 id="state.id"><samp>id</samp></a></dt>
<dd>Unique identifier for the state.</dd>
<dt><a id="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 id="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 id="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 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.
<h2>The font element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a id="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 id="font.id"><samp>id</samp></a></dt>
<dd>Unique identifier for the Font.</dd>
<dt><a id="font.idref"><samp>idref</samp></a></dt>
<dd>Identifier of a previously defined font.</dd>
<dt><a id="font.name"><samp>name</samp></a></dt>
<dd>Name of the font.
<dt><a id="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 id="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>
<h2>The color element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a id="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 id="color.id"><samp>id</samp></a></dt>
<dd>Unique identifier for the color.</dd>
<dt><a id="color.idref"><samp>idref</samp></a></dt>
<dd>Identifier of a previously defined color.</dd>
<dt><a id="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 id="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>
<h2>The property element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a id="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 id="property.key"><samp>key</samp></a></dt>
<dd>Name of the property.</dd>
<dt><a id="property.type"><samp>type</samp></a></dt>
<dd>Indicates the type of the property.</dd>
<dt><a id="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 id="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 id="defaultsProperty.key"><samp>key</samp></a></dt>
<dd>Name of the property.</dd>
<dt><a id="defaultsProperty.type"><samp>type</samp></a></dt>
<dd>Indicates the type of the property.</dd>
<dt><a id="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>
<h2>The graphicsUtils element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a id="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 id="graphicsUtils.idref"><samp>idref</samp></a></dt>
<dd>Identifier 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>
<h2>The insets element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a id="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 id="insets.id"><samp>id</samp></a></dt>
<dd>Unique identifier for the Insets.</dd>
<dt><a id="insets.idref"><samp>idref</samp></a></dt>
<dd>Identifier of a previously defined Insets.</dd>
<dt><a id="insets.top"><samp>top</samp></a></dt>
<dd>Top component of the Insets.</dd>
<dt><a id="insets.bottom"><samp>bottom</samp></a></dt>
<dd>Bottom component of the Insets.</dd>
<dt><a id="insets.left"><samp>left</samp></a></dt>
<dd>Left component of the Insets.</dd>
<dt><a id="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>
<h2>The bind element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a id="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 id="bind.style"><samp>style</samp></a></dt>
<dd>Unique identifier of a previously defined style.</dd>
<dt><a id="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 id="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>
<h2>The painter element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a id="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 id="painter.idref"><samp>idref</samp></a></dt>
<dd>Identifier of a previously defined SynthPainter.</dd>
<dt><a id="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 id="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 class="striped">
<caption>Painters for SynthPainter methods</caption>
<thead>
<tr>
<th scope="col">Index
<th scope="col">State
<th scope="col">Method
<th scope="col">Painter
</thead>
<tbody>
<tr>
<th scope="row">1
<td>SELECTED
<td>paintButtonBackground<td>stateButtonBackgroundPainter
<tr>
<th scope="row">2
<td>SELECTED
<td>Anything but paintButtonBackground<td>stateFallbackPainter
<tr>
<th scope="row">3
<td>Anything but SELECTED
<td>paintButtonBackground<td>styleButtonBackgroundPainter
<tr>
<th scope="row">4
<td>Anything but SELECTED
<td>Anything but paintButtonBackground<td>fallbackPainter
</tbody>
</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>
<h2>The imagePainter element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a id="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 id="imagePainter.id"><samp>id</samp></a></dt>
<dd>Unique identifier for the imagePainter.</dd>
<dt><a id="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 id="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 id="imagePainter.path"><samp>path</samp></a></dt>
<dd>Path to the image. If SynthLookAndFeel.load is
passed a Class this will use the Class method getResource (with the
Class supplied 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 id="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 id="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 id="imagePainter.painterCenter"><samp>paintCenter</samp></a></dt>
<dd>Whether or not the center of the image should be drawn.</dd>
<dt><a id="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 id="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.
<h2>The imageIcon element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a id="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 id="imageIcon.id"><samp>id</samp></a></dt>
<dd>Unique identifier for the imageIcon.</dd>
<dt><a id="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>
<h2>The opaque element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a id="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 id="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>