OpenBox Configuration Guide

by d0wnlab
http://th0mas.xbox-scene.com
th0mas.sixbit.org@gmail.com

Last Updated Aug. 22nd, 2005

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.


Skinning

Skins are composed of 2 seperate sets of items.


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

A FontResource entry must have the following attributes:
AttributeDescriptionExample
NameEvery loaded resource must have an unique name attached to it. This is what the Element entry will use to refer to the resourceFont1
SizeThe pixel size for the font. If you want the same font with multiple sizes you have to make seperate FontElements for each size.25
FileThe 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 NameDescriptionExample
NameEvery loaded resource must have an unique name attached to it. This is what the Element entry will use to refer to the resourceFont1
FileRelative 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:
AttributeDescriptionExample
ResourceName 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
DimensionsParent node, contains four children nodes who should all have a single integer content: Width, Height, Top, Left. See example below.See Example
ContentA 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
ColorContains 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
AlignSet 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

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.

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:
NameDescriptionExample
NameEvery node needs a name. This is what will be displayed in the menu.Games
SkinIDSee Advanced Skinning.Main
StatusIf 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
HotKeySets 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:

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:
NameDescriptionExample
TrayOpenThe text used to describe an open tray state.Tray Open!
TrayNoDiskText used to describe a closed, empty DVD drive.No Disk Loaded.
TrayDiskText used to describe a closed, occupied DVD drive.Disk!
TrayOpeningText used to describe an opening tray.Opening!
TrayClosingText used to describe closing tray.Closing!
TrayBusyText used to describe busy tray.Busy!
CopyFailed_OpenSourceError message when a file copy failed. %s will reference the file that could not be opened. Can contain multi-line messages.See Example
CopyFailed_SourceMissingError message when a file could not be found. %s will be the file that could not be found.
CopyFailed_OpenDestinationError when a file could not be opened for writing in a file copy. %s is the file that could not be opened.
CopyFailed_UnknownError 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.


Last Updated: October 29th, 2005