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