Since AoI 2.5, it is possible to write theming plugins that change the way AoI looks. "Theming" has several aspects:

• providing new icons to replace the existing one;
• providing color sets that tell AoI which color it should use for different parts of the windows;
• setting the look of the tool buttons and the tool palette, optionnally providing a custom button class.

Now let's review the steps necessary to the accomplishment of such a task. We'll study the ElectricWax plugin as a sample plugin in order to illustrate how theme plugins are built. Since Themes are indeed plugins, it's best to study the structure of plugin files first. Let's go!

Install the ElectricWax plugin, copy the plugin file ('ElectricWax.jar') from the Plugins directory to somewhere you can work comfortably without disrupting the AoI installation. Unzip the ElectricWax plugin file. If your archiver doesn't deal with .jar files, then rename it to ElectrixWax.zip. Jar files (Java ARchive) are nothing but zip files with some special content. Once unzipped, the archive shows 4 folders and one file. This file is called extensions.xml and it's this very file which describes the plugin. It's an XML file, if you don't know what XML is about a quick googling should provide links to introductory content about XML. You can also pick it up as we go, it's not difficult and a basic understanding is enough to pack up theme plugins. Let's open the file. Here it goes:

<?xml version="1.0"?>

<extension name="ElectricWaxTheme" version="1.0">
<author>Gary Rose</author>
<date>2007/06/27</date>
<description>
In addition to an alternative set of tools/user icons, the theme also features several GUI colour styles, eg Win XP, Win Vista, Mac Aqua, Mac Graphite. Theme1 uses a "Grey" coloured outline for selected icons, whereas Theme2 uses an "Amber" outline.
</description>
<resource type="UITheme" id="gary.ElectricWax" name="Theme1/theme.xml"/>
<resource type="UITheme" id="gary.ElectricWax2" name="Theme2/theme.xml"/>
<resource type="TranslateBundle" id="ElectricWax" name="electricwax.electricwax"/>
</extension>

The file begins with the mandatory xml preamble. Then an <extension> structure is defined: all plugin description lies within this element. There are a few obvious properties like name, author, date, etc. Version is very important because the Scripts and Plugins Manager only upgrades plugins that have a version greater than the version of the local plugin file. So obviously it is essential that the version number is properly incremented over time. The description element is also straightforward. Now, the three resource element at the end of the extension element are what trully defines the plugin. The first resource to be defined is the first of the two theme that this plugin contains. The resource type is set to "UITheme". Resources that define a theme are always set this type. The id that follows is a character string that must be unique to the resource. We use the 'gary' root name followed by a dot and the theme name. Then there is a the resource name, which in the case of themes identify the XML file that describes the theme. Read this last sentence again. Yes, the name of the resource points to the actual theme file. Now you understand why there are two folders named Theme1 and Theme2. Each one of them contains each theme icons and definition file. The definition file need not be named "theme.xml", it can have any valid name for an XML file. But using theme.xml file is handy. The second resource is similar to the first one except that it defines the second theme available within this plugin. The third resource is not a theme. It's a translate bundle, or, said differently, a set of translations. What would be translate in a theme? The names for the different color sets. Admittedly, it's not that important since not understanding the name of a color set does not stop anybody from using it. Yet it brings a nice touch to our theme plugin. The "TranslateBundle" resource has, as any other resource, a unique id defined by a character string, here "ElectricWax". The name tells where to find the bundle, here in the electricwax folder (that's the "electricwax" character string in front of the dot). This folder contains the electricwax.properties file which names the character strings to be localized as well as their default values. Thes default values are generally the english version of these strings. The electricwax_fr.properties file contains the french translation for the strings. The second "electricwax" name after the dot in the resource name corresponds to the name of the properties file. We're now done with the plugin definition and structure. Oh wait, there is this META-INF folder, right? Never mind about this one, it's optional since theme plugin files don't actually contain code.

Ok, now is the time to see what's in a theme definition file. You'll find below the contents of Theme1/theme.xml, minus some color sets definition to keep a reasonable length.

</theme>

The whole of the theme definition is contained in the single theme element. The element name contains (surprise!) the name of the theme as it will appear in AoI preferences window.

The next two elements, button and palette margins, are two important parameters that define the aspect of the tool palette. This panel holds all the tool buttons like create spline mesh button, create sphere button, resize button, etc. The button margin is how much space there is around each button in pixels. Thus, the space between the left edge of the palette and the left edge of a left button is button margin pixels. The same is true for the right side. There are twice the button margin pixels in between two buttons. The palette margin defines how many pixels there are between an edge of the palette and a button, left aside the button margin. Thus, there palette margin + button margin pixels from the left edge of the palette to the left edge of a left button, twice the button margin in between two buttons and button margin + palette margin pixels between the right edge of a right button and the right edge of the palette. This design allows to put some space in between the buttons which is handy for button style for which selection draws a rectangle around a button.

Then we have our first colorset. Since our color sets name are localized, the name of the colorrset must be the reference to a property in the electricwax. properties file. It will be substituted by the string in the relevant localized properties file. However, we need to tell AoI the properties to look for are not AoI default localization files but ours. This is done by adding "ElectricWax:" at the beginning of the property name. Why "ElectricWax" and not say "electricwaxplugin" or whatever? Look at the TranslateBundle resource definition. We stated as unique ID "ElectrixWax". Following the colorset name are the different colors. For each color, the R, G and B attributes stand for Red, Green and Blue values (out of 255). Here is the list of the meaning of the colors:

• applicationbackground: this is pretty obvious, I think ;)
• palettebackground: remember our tool palette?
• viewerbackground: the background for the 3D views in the editing windows, either camera or front, back etc.
• viewerline: a line drawn in a 3D view (eg. a mesh edge) will be rendered using this color
• viewerhandle: selection or curves handles
• viewerhighlight: selection color, I believe
• viewerspecialhighlight: selection color used for skeletons
• viewerdisabled: the color of the disabled mesh when the skeleton is edited
• viewersurface: the color of the mesh when the display setting is set to shaded (flat)
  
• viewertransparent: the color of the mesh when the display mode is set to transparent
• dockablebarcolor1 and 2: the colors of the gradient used to draw the title bars for object list, advanced renderer, etc.
• dockabletitlecolor: the color of the title in the title bar
• textcolor: the color of labels in the editor windows

You can have several color sets for each plugin so the user can choose the color set that best suits his environement.

Finally comes the button class definition (the button type). A button is referred to by its Java class names. The one used here, DefaultToolButton, is the traditional button as we know it : one icon for no selected state, one for selected state. No fancy behavior. However, you can derive your own button (see ToolButton class in AoI code), include the class code in the plugin and specify this class as button to use in the tool palette and other locations of the editing windows.

Now that' we're done with the theme definition file, we have to detail how you can override AoI default icons. Unzip ArtOfIllusion. jar as we did with ElectricWax.jar and have a look in artofillusion/Icons. Here they are, all of them unslected icons. The selected state ones cna be found in artofillusion/Icon/selected. You can override some or all of these icons by placing icons bearing the same name (minus the extension, see later) at the root of your theme folder. In the example of ElectricWax, the unselected icons are thus placed in Theme1 and Theme2 folders (resp.). Following the same scheme, the selected state icons are placed in a selected folder at the root of the theme folder, eg Theme1/selected. You can either provide a .gif or a .png file for a given icon. This allows replacing a .gif icon file by a .png one, the png format giving access to a higher number of colors within the icon.

Can you also override icons for plugins? The answer is yes! Unzip the plugin file, locate the icons and their selected counterparts and add your custom icons to your theme. They will automatically replace those of the plugin next time you run Art of Illusion.

Well, that's about all you need to setup a brilliant AoI theme.  Gentlemen, to your drawing boards! Err, your mousepads, that is. 

Leave a comment

Only registered users can leave comments.
Please login or register.

Powered by AkoComment Tweaked Special Edition v.1.4