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