Window Structure

From Official Kodi Wiki
Revision as of 16:57, 25 June 2006 by >Dankula (→‎Window Header)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

About the Window XML Files

Each window in an XBMC skin is represented by a single .xml file. See here for a list of the standard windows and links to their .xml files.

Each .xml file has the same basic structure – it starts with some heading information that pertains to the window as a whole, and then contains a <controls> block within which all the controls that describe the window are defined.

Window Header

<xml> <window>

 <id>4567</id>
 <defaultcontrol always="false">2</defaultcontrol>
 <allowoverlay>yes</allowoverlay>
 <type>dialog</type>
 <visible>Window.IsActive(Home)</visible>
 <animation effect="fade" time="100">WindowOpen</animation>
 <animation effect="slide" end="0,576" time="100">WindowClose</animation>
 <zorder>1</zorder>
 <coordinates>
   <system>1</system>
   <posx>40</posx>
   <posy>50</posy>
   <origin x="100" y="50">Window.IsActive(Home)</origin>
 </coordinates>
 <previouswindow>MyVideos</previouswindow
 <controls>
    ...
 </controls>

</window> </xml>

One thing to note is that all tag names are lower case. XML tag names are case sensitive!

The header contains the following tags:

id
The id number of the window. This is unique over all the .xml files. See the window list for the list of standard window ids
defaultcontrol
This specifies the default control of the window. This is the id of the control that will receive focus when the window is first opened. Note that most XBMC windows save the current focus when you leave the window, and will return to the last focused item when you return to a window. This behaviour can be stopped by specifying the attribute always="true".
allowoverlay
Setting this tag to true, or yes, indicates that the music or video overlay may be shown when this window is active. If this tag is not present, the state of the previous (or parent) window is used.
type
Specifies the type of window this is. Current options are window, dialog and buttonmenu. Only one window is alowed at a time. A dialog can overlay a window (allowing 2 or more “windows” simultaneously). The buttonmenu is basically a dialog with the added option to place many buttons with just one (changing) label.
visible
Specifies the conditions under which a dialog will be visible. XBMC evaluates this at render time, and shows or hides a dialog depending on the evaluation of this tag. See here for more details. Applies only to <type>dialog</type>.
animation
Specifies the animation effect to perform when opening or closing the window. See here for more details.
zorder
This specifies the “depth” that the window should be drawn at. Windows with higher zorder are drawn on top of windows with lower z-order. All dialogs by default have zorder 1, so if you have a particular dialog that you want underneath all others, give it a zorder of 0. (Note that the normal render order is: The base window, then the overlays (music + video), then dialogs. <zorder> only effects the rendering of the dialogs.
coordinates
This block is used to specify how XBMC should compute the coordinates of all controls.
system
Specifies the coordinate system. If set to 1, all control coordinates are relative to the <posx> and <posy> coordinates in this block.
posx
Sets the horizontal “origin” position of the window. Defaults to 0 if not present.
posy
Sets the vertical “origin” position of the window. Defaults to 0 if not present.
origin
Sets a conditional origin for the window. The window will display at (x,y) whenever the origin condition is met. You can have as many origin tags as you like – they are evaluated in the order present in the file, and the first one for which the condition is met wins. If none of the origin conditions are met, we fall back to the <posx> and <posy> tags.
previouswindow
This can be used to specify a window to force XBMC to go to on press of the Back button. Normally XBMC keeps a “window stack” of previous windows to handle this. This tag allows you to override this behaviour. The value can be either the name of the window, or its id.
controls
This is the block the defines all controls that will appear on this window.

The <controls> block and <controlgroup>

The <controls> block contains within it 2 possible further blocks: <xml> <controls>

 <control>
    ...
 </control>
 <controlgroup id="1">
   <control>
      ...
   </control>
 </controlgroup>

</controls> </xml> It can either contain multiple <control> definitions, or it can contain groups of <control> definitions, surrounded by a <controlgroup> block. The <controlgroup> block allows grouping a set of controls together so that they act as a block for navigational purposes. The idea is that you can have 2 groups of controls, and each <controlgroup> will remember the previously focused item, so that navigation between (for instance) two separate button groupings feels natural to the user. When the user moves away from a <controlgroup>, the group saves the last focused item. When the user moves onto a <controlgroup>, we first look at where the user last was within that controlgroup, and if found, we refocus that item. If not found, we focus the control referenced in the navigation portion of the last focused <control>. Control groups can have an id so that you can reference them for visibility conditions using the ControlGroup(groupID).HasFocus(controlID) visibility condition.

The exciting stuff is ofcourse the <control>...</control> part, where all the controls are defined.

The Different Types of Controls

XBMC supports many different types of controls.

Click here for the control types and what they all do.

Some of these controls are required on specific windows, as they're necessary for that window to perform it's duty, or, the contents of the control are only valid on a particular window. The mandatory controls for each window are listed in the window list. While the controls are mandatory, you can ofcourse move them about and change their appearance within the windows to your hearts content!

Adding Extra Windows

All of the windows in the window list are defined within the executeable of XBMC itself, as most of them have a specific purpose. However, the skinner may add extra windows as and when they are needed or wanted. The only restriction to this is that only controls that do not require specific source code to operate can be used. This is not too much of a restriction though, as many skinners have found out.

To add an extra window, all you need to do is design up the window's .xml file in the usual way, assign it an <id> outside of the ones defined in the window list, and then name the file customN.xml, where N is a number. You can have as many as you like, as long as they have unique <id>'s, and are named differently. Then just define the <type> of window you want, the coordinate system and so on, add the controls and setup the navigation. To activate your window, you can do it by adding a button control elsewhere in the skin, or you can get it to popup on a press of the controller or remote via keymap.xml and so on. Basically you just need to run XBMC.ActivateWindow(id) from a suitable place.