General

• Welcome
• Download
• Release History
• About Abstractics

Documentation

• Quick Start
• Layout Concepts
• Layout Examples
• Floating Components
• Component Factory
• Misc Properties
• Converter Utility
• JavaDoc

The Converter Utility

What is it? What is it used for?

In the previous section, the ComponentFactory was introduced and it was mentioned that it is possible to have attributes from the XML tag set properties on the resulting component. Components have all sorts of setThisAndThat() methods that are used to configure how they display. Being able to set these values from the XML is convenient. Attribute values in the XML are always strings, and so a utility to convert strings to Java objects became necessary.

The Converter utility can handle the simple conversions. It can convert strings into numbers (straightforward), a character (uses the first letter of the string), or a boolean ("true", "t", "yes", etc.). However, it can also convert strings into some common Swing objects.

Fonts

Every component has a setFont() method. Strings are converted into font objects according to the java.awt.Font.decode() method. Fonts are specified in "FontName,Style,Size" order. Spaces and dashes can also be used instead of commas.

• FontName can be any valid Swing font name. If not provided, defaults to "dialog".
• Style should be either PLAIN, BOLD, ITALIC, or BOLDITALIC (case-insensitive). If not provided, defaults to PLAIN.
• Size should be a valid decimal number. If not provided, defaults to 12.

As an example, the following would create a button with the font as "Arial", in bold, and size 14:

<cell type="button" font="Arial,bold,14">Some Button</cell>

Conversion of strings to fonts is handled by the ConverterFont class. This class maintains a cache of the font objects it creates. It holds a map of fonts keyed by the string representation of the font. This allows for better resource allocation, as well as allowing developers to pre-load fonts into the cache. See the JavaDoc for more information.

Colors

Every component has setForeground() and setBackground() methods. Strings are converted into java.awt.Color objects via the same notation used in HTML. Colors can be represented with a starting # sign, and then the hexadecimal value for RGB. (i.e. #FFCE90).

Conversion of strings to colors is handled by the ConverterColor class. This class maintains a cache of the color objects it creates. It holds a map of colors keyed by the string representation of the color. This allows for better resource allocation, as well as allowing developers to pre-load colors into the cache. See the JavaDoc for more information.

Dimensions

Every component has certain size methods, most notably the setPreferredSize() method. Strings can be converted into java.awt.Dimension objects by specifying a widthXheight notation, i.e. "150x200".

Icons/Images

Most images in Swing are handled by the javax.swing.Icon interface. Conversion of strings into icons is handled by the ConverterImageIcon class. This class translates strings into images by using the string as a URL to an image file (.jpg, .gif, etc.). Any valid URL will work, including file: and jar: URLs. As an example, the following would create a button that has a default icon from the file system, and a pressed icon from an HTTP URL:

<cell type="button" icon="file://c:/images/default.gif"
      pressedIcon="http://www.randomimages.com/images/someimage.jpg"/>
	

In addition, ConverterImageIcon also understands a resource: URL. This is a custom URL format that can read images from Java resources. Images for Swing applications are often bundled up inside of the JAR files with the classes. This URL format can specify a Java class and a path from that class. The format for a resource URL should be as follows:

resource:com.package.ClassName!/filedir/filename.gif
	

In the following example, the default icon is pulled from a file in the same location as the com.abstractics.Foo class, and the pressed icon is pulled from the images sub-package where that same class is:

<cell type="button" icon="resource:com.abstractics.Foo!/default.gif"
      pressedIcon="resource:com.abstractics.Foo!/images/default.gif"/>
	

As with other converter classes, the ConverterImageIcon class holds a cache of the images it creates. It holds a map of images keyed by the string representation of the image. This allows for better resource allocation, as well as allowing developers to pre-load images into the cache. Pre-loading images can be especially beneficial. Images can be loaded into the map before a panel is created, and they can be named whatever is wanted. Rather than dealing with URLs in the XML (and having to frequently repeat them), the image can be loaded into the cache with a common name and referenced that way instead. See the JavaDoc for more information.

Borders

All Swing JComponents have a setBorder(javax.swing.border.Border) method. Conversion of strings to borders is handled by the ConverterBorder class. This class has its own language to specify borders. The class can handle most of the border types that are produced by the Swing javax.swing.BorderFactory.

Border strings follow a type:parameters format. The type of border to create is determined by the string at the left of the colon. The parameters that follow the colon are dependent on the type that is being created.

matte border type is used for a simple line or graphic border (See BorderFactory.createMatteBorder()). The parameters consist of a size (single size, two numbers for top/bottom and left/right, or four numbers for top, right, bottom, and left, respectively) and then either a color or an image. The color/image string is handled by the ConverterColor/ConverterImageIcon classes mentioned above. Examples:

• matte:5 = Black line border, thickness of 5
• matte:5,blue = Blue line border, thickness of 5
• matte:2,#FFC782 = Color with RGB #FFC782 line border, thickness of 2
• matte:5,10,5,10,red = Red line border with size 5, 10, 5, and 10 in the top, right, bottom, and left respectively
• matte:5,10,blue = Blue line border with size 5 on top and bottom, and size 10 on left and right
• matte:10,file:/images/image.gif = Matte border filled with the image and a uniform 10 pixels all around

With colors and images, the text that follows the last comma in the String is first used to find a Color. If a color cannot be found, then it is used to find an image. If an image is not found, then nothing is done with the border.

bevel border type is used for beveled raised/lowered borders (See BorderFactory.createBevelBorder()). The parameters consist of a bevel type (either "raised" or "lowered") and then optional colors for highlight and shadow colors. Examples:

• bevel:raised = Creates a beveled border of the specified type, using brighter shades of the component's current background color for highlighting, and darker shading for shadows.
• bevel:lowered,blue,#C7C7B1 = Creates a beveled border of the specified type, using the specified highlight and shadow colors (respectively).
• bevel:raised,red,blue,yellow,green = Creates a beveled border of the specified type, using the specified colors for highlight outer, highlight inner, shadow outer, and shadow inner (respectively).

etched border type is used for etched raised/lowered borders (See BorderFactory.createEtchedBorder()). The parameters consist of an etch type (either "raised" or "lowered") and then optional colors for highlight and shadow color. Examples:

• etched:raised = Creates an etched border of the specified type, using the component's current background color for highlighting and shading.
• etched:lowered,blue,#C7C7B1 = Creates an etched border of the specified type, using the specified highlight and shadow colors (respectively).

And again, as with other converter classes, the ConverterBorder class holds a cache of the borders it creates. It holds a map of borders keyed by the string representation of the border. This allows for better resource allocation, as well as allowing developers to pre-load borders into the cache. Pre-loading borders can be especially beneficial. Complicated and/or custom borders can be loaded into the map before a panel is created, and they can be named whatever is wanted. Those borders can then be referenced directly by name in the XML. See the JavaDoc for more information.

Next: Miscellaneous Items