The Font of Wisdom: A Basic Boxely App, Part 1

by Kurt Cagle
March 27, 2007

AOL's Boxely is part of a wave of emerging technologies that mix the flexibility of XML with an object-oriented language (in this case JavaScript) in order to build fairly sophisticated applications. It's still quite new, new enough that people are just beginning to explore its possibilities, and new enough as well that learning to program in Boxely can be ... challenging. However, as I've increasingly come to discover, the challenge is generally worth the initial effort, and once you understand the way that Boxely applications are built, you'll find that creating new applications tends to go quite rapidly.

As a writer exploring Boxely, I was faced with a bit of a conundrum. While the language isn't that hard to learn, doing anything beyond the most trivial application does require the use of a number of interconnecting pieces, so I spent some time trying to come up with an application that was both somewhat useful and at the same time illustrated many of the core concepts in building more sophisticated applications. The first one I settled on, and the focus of this two-article series, is a simple application that lets you walk through the various fonts available on your system and display how they look with various selections of text. Besides being fairly simple to write, it has the advantage of exercising most of the different facets of Boxely, and as such can give you a useful idea of what's involved in writing such applications.

Setting Up Boxely

Before you can do anything with Boxely, you need to get a copy of it. In general, your best strategy is to go to the Boxely home page at dev.aol.com/boxely to grab the latest version. Boxely Preview 0.9.10.2 (released on January 29, 2007) was applied for creating the application described in this article series. Currently, Boxely works exclusively on the Windows XP platform (I have not had a chance to see whether it works under Vista) and defaults to placing the application code in your Program Files directory under the name AOLOCP. While there is an installation process that places the folder in place, the way that Boxely works requires that you become somewhat more intimately involved with the contents of this directory than you're likely to do with most applications.

A typical Boxely application exists in two parts: the general run-time engine, which is contained in the \Program Files\AOLOCP\RuntimeSupport directory, provides most of the base classes for defining "gadgets" and "services"; these need to be on any system utilizing Boxely (in other words, the user will need to install the Boxely base system first, just as they would Java or .NET) or on a local network. The individual applications in turn are contained in their own folders (which can be located anywhere), usually with a name that reflects the name of the application itself.

Creating a new Boxely application development environment is also currently a little awkward, though this will change once a Boxely IDE is released (it's in the works now). I decided to call my application FontViewer--not exactly highly original, but it works as an example. I then created a folder with that same name, placing it in the AOLOCP/userSamples directory. I then copied two files from the AOLOCP directory into this directory: BoxelyApp.exe and BoxelyApp.ini. The first file is the shell application that hooks into the runtime. You should change it to match the name of the application (FontViewer.exe). On the other hand, the second file, BoxelyApp.ini, contains the links to the Boxely runtime libraries, and its contents will look something like this:

[EERuntime] 
Path = "./RuntimeSupport" 
Configuration="defaultCfg" 
; Put box file to be loaded here. 
;boxFile = ./content/myBoxFile.box

The path in this case is relative to the installed AOLOCP folder, not the local EXE, and as such really only has significance (and needs to be changed) for networked situations. The Configuration option is used to determine what parameters are used for starting up the application, and currently should be kept as defaultCfg. The boxFile option is a pointer to the primary .box resource that is used as the initial GUI interface for the application. If this line is commented out (with a semi-colon at the start of the line), then the system will automatically look in the content subfolder to your newly created folder for a file called myApp.box.

Boxely automatically looks for an INI file with the same name as the runtime EXE file, so you should rename BoxelyApp.ini to FontViewer.ini in order for it to work properly. This is also the time to create two subfolders--content and resources--in the same directory; these hold the code and media (image, sound, and video files) for the application, respectively.

The next stage is to create the base myApp.box file. To create it, fire up your favorite XML editor (I'm using Oxygen 8.1 for screen shots and samples) and create a new XML file called myApp.box, as shown in Listing 1:

Listing 1. Skeleton Boxely document for fontViewer

<window xmlns="http://www.aol.com/boxely/box.xsd"
    xmlns:s="http://www.aol.com/boxely/style.xsd"
    xmlns:on="http://www.aol.com/boxely/reaction.xsd"
    xmlns:box="http://www.aol.com/boxely/box.xsd"
    xmlns:res="http://www.aol.com/boxely/resource.xsd"
    resizable="true"
    translucent="false" chromeless="false"
    s:width="500" s:height="300" title="FontViewer">
    <res:library>
    </res:library>
    <box id="fontViewer" s:width="500" s:height="300 s:fill="white">
    </box>
</window>

Boxely Windows

Before filling things in, it's worth spending a little time exploring the various objects at play here. The outermost container, the <window> element, represents the application window, and as such serves the same role as the <window> element in XUL. While it uses defaults, you can also set the window's width and height attributes to determine the overall dimensions (in this case a window of 500 pixels by 300 pixels). This window includes the expected chrome for Windows applications--the close, minimize, and maximize buttons--and they have the expected functionality (you can override these features as well, but this remains grist for a future article).

The <window> element as given here also defines five namespaces:

• The default namespace
• A style namespace (usually designated by an the s: prefix)
• A box namespace (typically defined with the box: prefix)
• A resource namespace (somewhat atypically defined with the res: namespace, when given a prefix at all)
• An event handling namespace (with the on: prefix)

Note that for legibility purposes the default namespace actually echoes the box namespace--a window is considered a highly specialized box, and uses that library's API. Keeping track of the right namespaces is perhaps one of the biggest challenges in developing any Boxely application, and will be one of the most useful features to automate when an IDE comes out.

There are a number of useful attributes defined here as well. The translucent attribute indicates whether the underlying window should be opaque or transparent, so that you can see through it. This is related, as well, to the chromeless attribute. When set to false (the default state), chromeless indicates that the Boxely Windows chrome--title bars, system buttons, and borders--are automatically wrapped around the window. When true, these items are not displayed, which can have the effect (if translucent is true) of letting you have applications with irregular borders in the background (such as a 24-bit PNG file with alpha channel enabled). The sample Car application uses this to create a car that can move around on the page without any obvious window wrappers.

The application itself is broken into two distinct sections--a <library> of resources (under the resource namespace) and a single <box>. The box is about what you'd expect--a rectangular region that can be used to partition the window into distinct areas (which can, in turn, contain other boxes) and that can be styled and otherwise manipulated to create various subcomponents and gadgets. Not surprisingly, this is the box for which Boxely is named. It's the core of the user-interface layout.

In this particular case, the box uses the s:flex property. You may have noticed the s: prefix before in the width and height of the window itself. The intent in Boxely is to break up the distinction between structure and presentation as much as possible, and to that end Boxely has actually moved a significant amount of what in XUL would be native object attributes into a special style namespace. This is consistent with one basic difference between the two languages--while XUL uses CSS in its HTML form to describe stylistic properties, Boxely uses an XML format for establishing these same properties. The overlap between Boxely and CSS style language is quite high in terms of property names and associations, but there are no formal CSS files anywhere in Boxely. (I'll come back to this concept later in this article.)

Once you save this file, you can actually run it by double-clicking on the newly created FontViewer.exe (or dragging the FontViewer.exe resource to your Start menu and then clicking it from there, as you might expect).

Figure 1. The base FontViewer window

The result (see Figure 1) isn't going to win any awards in the functionality department, but it does have all of the basic "chrome" that you'd expect of a window. You can resize it by dragging on a border, it has a title and the relevant minimize/maximize/close buttons, and it even includes a Window icon.

Applying the Boxely flex Attribute

The flex attribute may be new to you if you're coming from the HTML/CSS world. The idea behind it, however, is pretty straightforward. Imagine, for the moment, that inside each box there are two springs: one that runs horizontal and one that runs vertical. In a normal box, you would specify the dimensions, but in a layout like that used in Boxely (and XUL, which uses the same concept) you may want the system to automatically resize boxes according to "tension." If a box is contained in another box, for any tension other than zero the spring will push the sides of the box until they fill the available space. However, if you put two such flexed boxes together, then the strength of the flexion in each box will determine the available amount of space for that box. Thus, if you replace the single box with the following:

<box id="fontViewer" s:width="500" s:height="300" s:fill="white" s:orient="vertical">
    <box id="buttonContainer"  s:orient="horizontal" s:flex="1" 
	 s:stroke="blue" s:strokeWidth="2"></box>
    <box id="textDisplay" s:flex="4"  s:orient="vertical"
         s:stroke="red" s:strokeWidth="2"></box>
</box>

then the s:orient attribute for a given box will tell the direction in which the spring is placed and s:flex for each child box will indicate the amount of tension in the spring. Here, the fontViewer box has an orientation of vertical, with the buttonContainer and textDisplay boxes having s:flex values of 1 and 4, respectively. This means that the textDisplay box has four times the strength that the buttonContainer box does, and so should be four times as large in the absence of any other springs or fixed objects, as illustrated in Figure 2.

Figure 2. The FontViewer window with interior boxes buttonContainer and textDisplay

Note closely that orient applies to the behavior of child objects with respect to the parent, while flex applies to a given object relative to that parent object. If the box has a vertical orientation, then the flex of each of that box's children will be applied in the vertical direction, regardless of their own individual orientations.

Because changes of orientation are one of the most common box operations, a shortcut can be used to applying the s:orient attribute--using <vbox> for vertically oriented boxes and <hbox> for horizontally oriented ones. Thus, the above fragment can be rewritten as:

<vbox id="fontViewer" s:width="500" s:height="300" s:fill="white">
    <hbox id="buttonContainer"  s:flex="1" s:stroke="blue"
          s:strokeWidth="2"></hbox>
    <vbox id="textDisplay" s:flex="4" s:stroke="red" 
          s:strokeWidth="2"></vbox>
</vbox>

Boxely Gadgets

While such boxes are useful, an application that consists of nothing but boxes is likely to have fairly limited appeal unless you're about 18 months old. It is rather more useful at this stage to start putting "gadgets" into those boxes. However, Boxely out of the box has relatively few gadgets that it knows about natively--instead, these gadgets need to be imported into a Boxely app with a processing instruction, pulled either from user-defined resources or from natively defined gadgets in the Boxely toolkit. The toolkit itself contains a lot of the support code for the various libraries, but typically you will also want to pull in the Boxely core resources:

<?import href="box://ocpToolkit/content/core/coreGadgets.box"?>
<?import href="box://ocpToolkit/theme/default/toolkit.box"?>

The coreGadgets include the two that will be used in fontViewer--the text and the button gadgets. Placing in a couple of buttons to navigate through the various fonts and a couple of labels for displaying the font name and showing a representative sample of that font, the FontViewer application is beginning to take shape (Listing 2 and Figure 3).

Listing 2. FontViewer with the core interface elements in place

<?import href="box://ocpToolkit/content/core/coreGadgets.box"?>
<?import href="box://ocpToolkit/theme/default/toolkit.box"?>
<window xmlns="http://www.aol.com/boxely/box.xsd"
    xmlns:s="http://www.aol.com/boxely/style.xsd"
    xmlns:on="http://www.aol.com/boxely/reaction.xsd"
    xmlns:box="http://www.aol.com/boxely/box.xsd"
    xmlns:res="http://www.aol.com/boxely/resource.xsd"
    resizable="true"
    translucent="false" chromeless="false"
    s:width="500" s:height="300" title="FontViewer">
    <res:library>
    </res:library>
    
    <vbox id="fontViewer" s:width="500" s:height="300" s:fill="white">
        <hbox id="buttonContainer"  s:flex="1" s:stroke="blue" s:strokeWidth="2">
            <button label="Previous Font" s:flex="1"/>
            <text s:flex="10" value="Font Name" s:fontSize="24pt" s:hAlign="center"/>
            <button label="Next Font" s:flex="1"/>
        </hbox>
        <vbox id="textDisplay" s:flex="6"  s:stroke="red" s:strokeWidth="2">
            <text value="Font Sample" s:fontSize="18pt"/>
        </vbox>
    </vbox>
</window>

Figure 3. FontViewer with gadgets added

Conclusion

At this point, weíve developed a framework within which the core functions of our application can now be developed and inserted. We have a Boxely window, we have boxes inside the main window, and we have applied Boxely button and text gadgets.

In part two of this article series, we'll apply Boxely services and styles to complete our base FontViewer application.

References

• "Thinking Inside the Boxely" by Kurt Cagle, AOL Developer Network, February 23, 2007
• dev.aol.com/boxely: The Boxely home page