Customizing the Focus Rectangle

In Flash, when a focusable control receives focus, a rectangle is drawn around it to indicate that it is currently active/selected. The default focus rectangle drawn by the Flash Player is an ugly yellow border. Components typically override this behavior and draw their own (hopefully nicer) focus rectangles.

In Aspire UI, the focus rectangle is drawn in the same way skins of component instances are rendered - using a bitmap image. By default, the “FocusRect.png” file in the theme folder is used. This means that the look of the focus rectangle is theme-specific and can be easily customized by the theme designer.

Both the “classic” and “xp” themes that ship with the Aspire UI library use the same image - the focus rectangle is rendered to look similar to the one used in the Windows operating system, which most end-users should be familiar with.

The “rules.xml” in the theme folder states the rendering rules to use when using the various assets in the folder. In the case of the “FocusRect.png” asset in the “classic” and “xp” themes, you will see the following:

    <FocusRect edge="1" repeat="xy" />

The “edge” attribute specifies that the “FocusRect.png” bitmap image has a non-scaling edge of 1 pixel each side, and the “repeat” attribute specifies that both the horizontal and vertical middle scaleable portion should be repeated instead of stretched when resizing.

By modifying the “FocusRect.png” asset (and its corresponding rendering rule in the “rules.xml” file if necessary), you can easily customize the look of the focus rectangle used throughout your application.

It is also possible to render the focus rectangle differently for different controls in the same application, by using different bitmap images. This may be desirable if the default focus rectangle is unsuitable for certain controls in your application, perhaps due to color contrast considerations or other reasons.

Let's examine the use of an alternative bitmap image to render the focus rectangle. For the purpose of this tutorial, we are going to render the focus rectangle as a rounded bluish-tinted rectangle, like the one used in Adobe Flash CS3 components.

First, we need to create the PNG image. The following bitmap will be used:

Copy/download/save the above image as “FocusRectBlu.png”. Note that the background of the image is transparent instead of opaque. This is important because the focus rectangle should not cover any underlying objects below - remember this when designing your own focus rectangle.

Store the image in your theme folder, which by default is ”<deploy>/assets/skins/default”, where <deploy> indicates the path to your working folder, where your compiled SWF will reside and the “assets” folder exists.

Next, we need to modify the “rules.xml” file to include the new asset. Open the XML file and insert the following node:

    <FocusRectBlu />

It doesn't matter where in the XML you insert the node, but it is recommended that you keep the nodes in alphabetical order, so perhaps it would be best to insert it after the FocusRect node, like:

    <FocusRect edge="1" repeat="xy" />
    <FocusRectBlu />

Incidentally, for the “FocusRectBlu.png” asset, we do not need to specify any attributes (rules) because it happens to work well with the default rule¹⁾.

With that done, the “FocusRectBlu.png” asset is now available for use in the application.

Now that we have a customized focus rectangle, we need to instruct UI controls to use it.

Each uiComponent instance, regardless of whether it is a container or control, has a focusRect property. This property can be set to a Boolean value (true/false), or a String value indicating the bitmap asset to use when rendering the focus rectangle (omitting the .png file extension).

            btn2.focusRect = "FocusRectBlu";

In the above case, only btn2 will use the “FocusRectBlu.png” asset when rendering its focus rectangle; the other btn1 and btn3 will still use “FocusRect.png”.

Note that this property has an inheriting nature - if this property is not set for a particular instance, the instance will use the value set for its container and this cascades recursively upwards until we get to the top-level container²⁾. The default value is null, which means the instance should use the value set for its container. In other words, what this means is that you only need to set this property for a container to cause all (grand)children of that container to use the same value - pretty convenient and nifty. In the example above, instead of setting the focusRect property for btn2, you can set the property at the box container level, and all three child instances will use that value:

            box.focusRect = "FocusRectBlu";

If the focusRect property is set to false, or set to a String value pointing to a non-existent bitmap asset, no focus rectangle would be drawn.