OpenBox Configuration Guide

Index

1. Overview
2. Skinning
1. What can be skinned
2. Resources
1. FontResource
2. ImageResource
3. Example
3. Elements
1. Overview
2. UI Related
3. Text Widgets
4. Example
3. Menu
1. Overview
2. Menu Nodes
3. Example
4. Internationalization

Overview

Configuration of OpenBox takes place in three files: two configuration files skin.xml and menu.xml, and a simple path pointer file skin.pth.

• skin.xml describes what is commonly referred to as the "skin" of the dash - how and where to display the menu, images, etc. It can be in a seperate directory than the dash itself.
• menu.xml describes the menu structure of the dash, including any scripts, etc.
• skin.pth simply contains a pointer to the root of the skin directory. For example if the target skin is in /skin2/, then the skin.pth should just be "skin2/". The trailing '/' is important.

Skinning

Skins are composed of 2 seperate sets of items.

• Resources - The raw "physical" resources required in the dash. These are the images, fonts and sounds that the dash needs to load in order to display the skin.
• Elements - The actual "widget" on the tv screen. A widget is basically an instruction on how and when to use a loaded Resource. Resources can be re-used.

Resources

In the skin.xml file there is a node named "Resources". This should contain a series of Resource nodes. Each Resource node represents a file resource used in the skin (for example, menu background, selected text font, menu entry background image, etc). However, in the Resource node description, we do not specify what we use the resource for, only what the resource is. That way resources can be re-used in various ways in the Elements section.

There are a couple different resource classes, each representing a different type of file resource.

• FontResource - Represents a TTF Font file to be used in the skin.
• ImageResource - Represents a (BMP/JPG/PNG/GIF) image to be used in the skin.

FontResource

A FontResource entry must have the following attributes:

Attribute	Description	Example
Name	Every loaded resource must have an unique name attached to it. This is what the Element entry will use to refer to the resource	Font1
Size	The pixel size for the font. If you want the same font with multiple sizes you have to make seperate FontElements for each size.	25
File	The relative path to the font file from the skin.xml file's path. For example, if the skin.xml and the font are in the same directory then just make the entry be "filename.ttf", even if this is not the root directory of the dashboard..	filename.ttf

ImageResource

A ImageResource entry must have the following attributes:

Attribute Name	Description	Example
Name	Every loaded resource must have an unique name attached to it. This is what the Element entry will use to refer to the resource	Font1
File	Relative path to the image file from the skin.xml file's path.	image.png

Example

Below is an example of the Resources section of the skin:

<Resources> <Font> <Name>Font1</Name> <Alpha>255</Alpha> <File>menufont.ttf</File> <Size>25</Size> </Font> <Font> <Name>Milhouse</Name> <Alpha>255</Alpha> <File>menufont2.ttf</File> <Size>30</Size> </Font> <Image> <Name>Background</Name> <Alpha>255</Alpha> <File>x3d4.jpg</File> </Image> <Image> <Name>Dialog</Name> <Alpha>255</Alpha> <File>dialogback.png</File> </Image> <Image> <Name>Entry_BG</Name> <Alpha>255</Alpha> <File>entry_bg.png</File> </Image> <Image> <Name>Entry_BG2</Name> <Alpha>255</Alpha> <File>entrybg_sel.png</File> </Image> </Resources>

Elements

Overview

Elements are the hints to the dash on how and when to use the Resources. Common Elements describe the background image, position and color of the temperature/tray state, etc, as well as the size/position/background image of the menu, etc. As well, Elements exist to describe the font/position/size/background of the dialog and question boxes.

Similiar to Resources, a root node exists in the skin.xml file called Elements. It's children are the series of Element objects that make up the skin.

Every Element has some (or all) of the following properties:

Attribute	Description	Example
Resource	Name of the loaded Resource that is used in the Element. Depending on what is the Element's content (see below), the resource must be either a FontResource or ImageResource. Keep this sensible or the outcome is undocumented (probably a crash).	Image1
Dimensions	Parent node, contains four children nodes who should all have a single integer content: Width, Height, Top, Left. See example below.	See Example
Content	A text string that describes the role of the Element. Note that this is case sensitive. For example, an Element with Content "BackgroundImage" refers to the.. background image to be used in the skin. In this case, it is assumed that the Resource named in the Element is an ImageResource that refers to a 640x480 image suitable for loading. See below for extensive detail of all possible Content values and the expected configuration.	BackgroundImage
Color	Contains 3 child nodes - Red, Green, Blue, all of which should have a number from 0-255. Used in conjunction with Elements that refer to drawing text to the screen, this describes what color to draw the text.	See Example
Align	Set to "Left", "Right", or "Center" to align text widgets in those ways.	Center

Content Descriptions

The Content child node of each Element determines what its used for in the skin. Below is a list of all the possible values for the Content node, and how they effect the usage of the Element.

UI Related Skin Content

• BackgroundImage - Element will be used to describe the background of the skin. Associated Resource should be an ImageResource of size 640x480. Element should contain Dimensions/Content/Resource nodes.
• MenuFont - Element is used to describe the color/font of all (non-selected) menu entries. Associated Resource should be a FontResource. Element should contain Content/Resource/Color nodes.
• MenuSelectedFont - Element is used to describe the color/font of the selected menu entry. Associated Resource should be a FontResource. Element should contain Content/Resource/Color nodes.
• Menu - Element is used to determine the position and size of the menu. Does not use any Resource. Should have Dimensions, and Align for menu text position.
• MenuEntryBG - Element is used as the background image for each non-selected entry in the menu. The Dimensions are used to determine how much space is given between each entry. Resource should be an ImageResource of whatever size you want each entry in the menu to take up. Element should contain Content/Resource/Dimensions.
• MenuEntrySelectedBG - Same as MenuEntryBG but will be used for the selected menu item. Should be the same dimensions as the MenuEntryBG.
• MessageBackground - Element is used to determine the background image and the dimensions/position of the background of a dialog box. Resource should be an ImageResource. Element should contain Content/Dimensions/Resource.
• MessageTitle - Element is used to determine the font/position/color of the title of any dialog boxes displayed using the skin. Resource should be a FontResource. Element should contain Content/Resource/Dimensions/Color/Align.
• MessageText - Element is used to determine the font/position/color of the text of any dialog boxes displayed using the skin. Resource should be a FontResource. Element should contain Content/Resource/Dimensions/Color/Align.
• QuestionBackground - Same as MessageBackground, but for question boxes instead.
• QuestionTitle - Same as MessageTitle, but for question boxes.
• QuestionText - Same as MessageText, but for question boxes.
• ProgressBarBackground - Same as MessageBackground, but for progress bar dialogs instead.
• ProgessBarTitle - Same as MessageTitle, but for progress bar dialog titles.
• ProgessBarText - Same as MessageText, but for progress bar dialog text.
• ProgressBarPercent - Determines the font/color/position of the actual percent done for the progress bar (ie "55%").
• ProgressBar - Determines the image to use and it's position to be drawn for an actual graphic progress bar. Will be drawn underneath the text for layering purposes. Can have alpha components. It will be used from left to right: that is a progress bar dialog at 50% will be drawn to have the left half of the picture specified in this node drawn, and the other half left undrawn (so the background will show through).

Text Widgets Elements

The following Content values specify widgets for a variety of status text messages. Each of these elements should have their Resource refer to a FontResource object. They should have Dimensions/Color/Align/Content/Resource children nodes.

• BoardTemp - Displays the BoardTemp in Celsius.
• CPUTemp - Displays the CPU temp in Celsius.
• TrayState - Displays the current tray state.
• FanSpeed - Displays the current fanspeed.
• Status - The currently selected menu entry can have a line of text associated with it. An element with this Content tag will display that text.

Example

Menu

Overview

The Menu system consists of a tree of MenuNodes. Different menu nodes will do different things when clicked on. For example, a SubMenuNode will change the current Menu to it's children. A Script will execute it's children nodes in series. A BootXBE node will launch it's associated XBE. It's pretty straightforward. Consult the example when you have problems.

Every node has a couple base variables:

Name	Description	Example
Name	Every node needs a name. This is what will be displayed in the menu.	Games
SkinID	See Advanced Skinning.	Main
Status	If this node exists and contains text, the text will be shown on the status line of the skin when this menu entry is the highlighted entry.	Access Games Menu
HotKey	Sets a hotkey to execute this menu item. Possible hotkeys are: "Ctrl_A", "Ctrl_B", "Ctrl_X", "Ctrl_Y", "Ctrl_Start", "Ctrl_Back", "Ctrl_LTrig", "Ctrl_RTrig", "Ctrl_Black", "Ctrl_White", "Ctrl_Up", "Ctrl_Down", "Ctrl_Left", "Ctrl_Right", "Ctrl_LStickY", "Ctrl_LStickX", "Ctrl_RStickY", "Ctrl_RStickX"	Ctrl_A

Menu Nodes

There are a number of different nodes that do specific actions. These are outlined below:

• BootXBE - launch a specific XBE. Has the following configuration attributes:

  Name	Description	Example
  Path	The full path to the XBE that is to be launched.	c:/msdash.xbe

  
  
• XBEMenu - Creates a submenu for the user to boot a game that is in a subdirectory of the target directory. For example, if 2 games exist in c:/games/doom and c:/games/quake, and the menu contains a XBEMenu with Directory = c:/games/, then when the user clicks on the XBEMenu node it will present them with a choice between "Doom" and "Quake". It has the following attributes to be configured:

  Name	Description	Example
  Directory	The directory we are to scan all subdirectories under.	c:/games/
  Target	The XBE filename we are looking for in the directories (usually "default.xbe")	default.xbe

  
  
• LaunchDVD - Attempts to mount the DVD drive and launch "d:/default.xbe". No further configuration parameters.
  
  
• DialogBox - Displays a message to the user. Used primarily in scripts to notify the user that a function is completed or about to be initiated. Pressing A or B has the same effect - the dialog box is removed and the script continues or returns. It has the following configuration parameters:

  Name	Description	Example
  Title	The title of the message.	Script Complete
  Message	The content of the message. Note that currently the messages do not line-wrap.

  
  
• QuestionBox - Displays a message on the screen. If the user presses "A" the "Yes" child script is executed. If the user presses "B" the "No" child script is executed. Has the following configuration parameters:

  Name	Description	Example
  Title	The title of the message.	Make a Choice
  Message	The question text. Note that currently the text does not line-wrap.
  Yes	Yes should contain below it, any of these described MenuNodes. If the users presses "A" when viewing the question, it will execute this node. If more than one node is to be executed, wrap them in a Script.	See Example
  No	Same as "Yes", but is executed in the event that the user presses the "B" button.

  
  
• XboxAction - When executed, this node will do some specific action related to the current state of the xbox. The action is determined by the text in the "Action" sub-Node. Some of these actions require a parameter (for example, changing the fan speed - the option required is.. the new fan speed.) These parameters, when needed, are stored in the "Option" sub-node. Listed below is the full description.

  Name	Description	Example
  Action	Text value that determines what action to complete when this node is executed. The possible actions are: Shutdown - shuts the xbox off. Reboot - reboots the xbox. OpenTray - Opens the dvd tray. CloseTray - Closes the dvd tray. BlinkLEDs - Changes the LED pattern. Option should contain the bitpacked code that determines the new color sequence. FanSpeed - Changes the speed of the fan. Option should contain the new fan speed.	Shutdown
  Option	Integer value used in conjunction with either the BlinkLEDs or FanSpeed actions.	70

  
  
• FileAction - When executed, this node will do some specific action related to the filesystem. For example, copying a file, or creating a directory. FileActions could be chained together using a Script wrapper object, to create a sequence of events that, say, back up the important dash files, etc.

  Name	Description	Example
  Source	For operations requiring two files, this is the source file. For operations requiring one file, this is the filename used.	c:/xboxdash.xbe
  Destination	For operations requiring two files, this is the destination filename. For operations requiring a single file, this parameter is unused.	c:/backup/xboxdash.xbe
  Action	Determines what action to take when the node is executed. Possible values are: Delete - Deletes the file in Source. Move - Moves the file in Source to Destination. Copy - Copies the file in Source to Destination. CreateDirectory - Creates the directory named in Source. DeleteDirectory - Deletes a directory and all it's contents. CopyDirectory - Recursively copies an entire directory. Rename - Renames a file from Source to Destination.	Copy

  
  
• SubMenu - Simple container menu item. When clicked it changes the current menu to it's children. Has the following properties:

  Name	Description	Example
  Children	Should contain a list of nodes that create the menu that the system switches to when this node is selected	See Example

  
  
• Script - Container menu item. When this item is selected in the menu, it will execute each of it's child nodes in succession. Useful for scripting a series of events (ex: install exploit, back up hard drive, etc.). Has the following properties:

  Name	Description	Example
  Children	List of nodes that will be executed in order when this item is selected.	See Example

  
  
• LoadSkin - When it is executed it loads a skin whose skin.xml file's path is in the Path attribute.

  Name	Description	Example
  Path	The path to the skin.xml file for the new skin to load.	skin1/skin.xml

  
  

Menu Example

Below is an example menu configuration.

<Menu> <Name>Menu Root</Name> <Children> <XBEMenu> <Name>Games</Name> <Directory>f:/games/</Directory> <Target>default.xbe</Target> <HotKey>Ctrl_A</HotKey> </XBEMenu> <XBEMenu> <Name>Apps</Name> <Directory>f:/apps/</Directory> <Target>default.xbe</Target> </XBEMenu> <QuestionBox> <Name>Question!</Name> <Title>A or B?</Title> <Message>Select 'A' or 'B'</Message> <Yes> <DialogBox> <Name>Message!</Name> <Message>You Selected 'A'</Message> <Title>'A'</Title> </DialogBox> </Yes> <No> <DialogBox> <Name>Message!</Name> <Message>You Selected 'B'</Message> <Title>'B'</Title> </DialogBox> </No> </QuestionBox> <Script> <Name>Backup dash</Name> <Children> <FileAction> <Source>c:/backup/</Source> <Action>CreateDirectory</Action> </FileAction> <FileAction> <Source>c:/xboxdash.xbe</Source> <Destination>c:/backup/xboxdash.xbe</Destination> <Action>Copy</Action> </FileAction> <DialogBox> <Message>Dash Backup Successful.</Message> <Title>Success!</Title> </DialogBox> </Children> </Script> </Children> </Menu>

Internationalization

Intro

Pretty much all text strings used in the dashboard are configurable. In the config.xml file, there is a top-level node called "Dialog". In it are a series of nodes whose names refer to what the string is used for, and their content is the string to be used in the dash. The usable Dialog strings are as follows:

Name	Description	Example
TrayOpen	The text used to describe an open tray state.	Tray Open!
TrayNoDisk	Text used to describe a closed, empty DVD drive.	No Disk Loaded.
TrayDisk	Text used to describe a closed, occupied DVD drive.	Disk!
TrayOpening	Text used to describe an opening tray.	Opening!
TrayClosing	Text used to describe closing tray.	Closing!
TrayBusy	Text used to describe busy tray.	Busy!
CopyFailed_OpenSource	Error message when a file copy failed. %s will reference the file that could not be opened. Can contain multi-line messages.	See Example
CopyFailed_SourceMissing	Error message when a file could not be found. %s will be the file that could not be found.
CopyFailed_OpenDestination	Error when a file could not be opened for writing in a file copy. %s is the file that could not be opened.
CopyFailed_Unknown	Error when something happens preventing the file copying from working. The first use of %s will be the source file, the second will be the target file.

Example

Please see the contents of the OpenDash Windows Build 396 config.xml file for an example of the dialog usage.