GUI XML Documentation

From DevWiki

Back to Home

Overview

The Boxee UI API enables developers to build their own content portal and media applications on top of the Boxee platform. For more information on the basics of every application please read Anatomy of a Boxee App.

Your application UI is built using xml & python. Each xml file is a different window however one can design multiple views in one window. The UI, or skin, xml files are located in the 720p folder. There are many controls (lists, buttons, images, editboxes...) you can incorporate in your UI which represent the visual design of the application. For many controls you can embed python scripts which preform operations for retrieval of media information and/or UI related actions.

Animations are available and can be defined for each control on specific events. Conditional visiblility can be set to each control in your skin making many UI actions a breeze. Prompting the user for imput is also possible using the python api and much more. This document will define each control and animation available to you as well as go over different uses and how to handle events.

Note: For the remainder of this section of documentation, if your confused about the reference to any of the following please refer to the Anatomy of a Boxee App unless stated otherwise. Also note that any mention of python is always optional.

• window(s)
• skin folder
• 720p folder
• media folder
• descriptor
• python includes

Windows

Each window (screen) in your application is managed by its own xml file under the skin/Boxee Skin NG/720p folder. Each window must have its own unique ID number ranging from 14000-14099. Using IDs out of this range will stop python code from executing properly along with other unforeseen issues. In addition, the window IDs are used to launch specific windows in your skin.

Window Element

Elements that reside within the window tag

Example for the default window structure. ID's here can and should be changed to work appropriately with your UI.

<?xml version="1.0"?>
<window type="window" id="14000">
   <defaultcontrol always="true">120</defaultcontrol>
   <allowoverlay>no</allowoverlay>
   <onload>Control.SetVisible(122)</onload>
   <controls>
     ...
   </controls>
</window>

Controls

Controls define everything from buttons, labels, images, lists and more. Each control section will explain the selected control in detail. There are many different types of controls, all which represent UI elements displayed on-screen and most can be interacted with by the user. Each control, as the window it self, has a basic structure with default properties and specific properties which represent its behavior and look.

• Full List of Controls

Also important to read the following:

• Container Layouts

Control Events

The window and each control has event tags (like onclick, onfocus, onload etc.) which are triggered upon specific events. Each event supports the attribute lang="python" after which, python code may be inlined and wrapped with CDATA tags. It's important to note that Boxee currently supports Python 2.4. Below is a list of available event tags for focusable controls.

• onload (windows)
• onunload (windows)
• onfocus (controls)
• onclick (controls)
• onright (controls)
• onleft (controls)
• onup (controls)
• ondown (controls)

Example of onclick event with Button Control

<control type="button" id="1000">
   <width>88</width>
   <height>39</height>
   <label>VIDEO</label>
   <align>center</align>
   <textcolor>ffffffff</textcolor>
   <texturefocus>menuitem_on.png</texturefocus>
   <texturenofocus>-</texturenofocus>
   <visible>true</visible>
   <onclick lang="python">
<![CDATA[
mc.ShowDialogNotification('You pressed a button!')
]]>
   </onclick>
</control>

Conditional Visibility

The power of the skinning engine is based on the ability to show and hide controls using conditional statements (boolean conditions). Conditions can me compared and combined with no limit. The logic is simple yes/no logic. Take a look at the following examples.

• List of Conditionals

show list if button 100 has focus -> Control.HasFocus(100)
show list if button 100 is hidden and button 200 has focus -> !Control.IsVisible(100) + Control.HasFocus(200)

Default Control Properties

Default properties and events (tags and attributes) are available for all skin controls: Note that all tag names are lower case. XML tag names are case sensitive! Credit goes to the xbmc documentation

For fusable events, the following are also available:

Animations

The skinning engine supports animations of any control allowing them to rotate, slide, fade or any combination there-of. Combining animations with conditional statements ensure your skin will have stunning effects that appear as professional as a 1st party product. For further information, see the UI Animations section.

• UI Animations

Textures

For all <texture> properties in controls (like <textureonfocus>) it is suggested to use PNG and JPG as much as possible. For transparency use PNG. For animated textures, only animated GIF is supported. There are also SOME animated gifs that may not work. Use ImageReady CS and make sure you set the gif-anim to "restore to background" and they should work fine. The following attributes can be used within the texture tag to alter how the texture is rendered:

Example:

<texture border="3" align="right" aligny="top" flipy="true" diffuse="diffuse_mirror.png">keyboard_key.png</texture>

Label Formatting

In the Boxee framework, there are predefined font and color values. Labels can also be formatted using special tags in the text label property it self. The tags allow the use of different languages through a localization support, it enables the label to display application variables and system variables and it allow visual formatting of the label to bold, italics, full caps, lower case and colored, or all of them together.

Fonts

Since the early days of Boxee, there has only been one font. While this worked for a while we realized the need for some more styles. Now we support the Boxee default font, Sans and Serif. See Boxee Fonts

Color Values

In the Boxee framework, there are predefined font and color values. Colors can be manually defined using the scheme AARRGGBB where AA is alpha blending value, RR is red, GG is green and BB is blue. All color values are in HEX values between 0-255. Any color tag in your skin can accept the word values below (<textcolor>red</textcolor). Default colors are listed below but are subject to change between Boxee releases. Its best to use your own color codes to guarantee the colors in your application don't change if we change these default values:

Note that we changed these values with beta. The old color codes are no longer avilable and only the above will work.

Formatting

• $INFO[ListItem.Title,prefix,postfix]: used for application and system variables title=InfoLabels>.
• $LOCALIZE[12345]: used for specifying a localized string from the language strings.xml.
• [B]bold[/B]: format the block of the text to bold.
• [I]italics[/I]: format the block of the text to italic.
• [COLOR red]red text[/COLOR]: format the block of the text to the specific color.
• [UPPERCASE]force text uppercase[/UPPERCASE]: force block of text to uppercase
• [LOWERCASE]Force Text Lowercase[/LOWERCASE]: force block of text to lowercase
• [CR]: carriage return (line break).

Parsing

• Replaces any $LOCALIZE[number] blocks with the real string from strings.xml (number is the number of the string in the strings.xml file).
• Translates the [infolabel,prefix,postfix] blocks from left to right.
• If an empty string is returned from the infolabel, then nothing is rendered for that block.
• If a non-empty string is returned from the infolabel, then prefix string is applied, then the returned infolabel information, then the postfix string is applied. Note that any $COMMA fields are replaced by real commas, and $$ is replaced by $.
• Any pieces of information outside of the $INFO[] blocks are rendered unchanged.

Example:

<label>A good example of a $INFO[MusicPlayer.Title,song title: , $COMMA and a]$INFO[MusicPlayer.Artist, song artist:]</label>

If nothing is playing then the label will print:
A good example of a

If a song is playing but it has no Title (ie MusicPlayer.Title returns an empty string) but does have an artist, it will return:
A good example of a song artist: <Artist>

If a song is playing that has title and artist information, it will return:
A good example of a song title: <Title>, and a song artist: <Artist>

Example:

<label>This is a long label that features different [COLOR red]colors[/COLOR] and
[I]styles[/I] and [B]looks[/B].[CR][LOWERCASE]$LOCALIZE[12345][/LOWERCASE] can be used to force a
localize string to lowercase.[CR][UPPERCASE]$LOCALIZE[12345] else[/UPPERCASE] can be used to force
a localize string to uppercase.</label>

This is a long label that features different colors, styles and looks.
something can be used to force a localize string to lowercase.
SOMETHING ELSE can be used to force a localize string to uppercase.