Building Your First App

• Building Your First App: Designing the Skin
• Building Your First App: Breaking Down The Controls
• Building Your First App: Creating The Skeleton
• Building Your First App: Hello World
• Building Your First App: Finishing The Graphics
• Building Your First App: The List Container
• Building Your First App: The Metadata Box
• Building Your First App: Animation
• Building Your First App – Release It!

In the last installment of this multi-part guide to creating your first Boxee app, we set up the skeleton of our app with the correct directory structure with appropriate configuration and media files.  Now we finally get our hands dirty by starting the real development of our app.

First, let’s step back and define some critical concepts. Every Boxee application is a set of windows and controls. Windows are the “screens” of the application – the individual interfaces that make up the whole application. For example, Pure Pwnage app has two windows – a window to select a season and a window to select an episode.

Each window is populated with controls. Controls are the individual elements of a window, like those we broke down in the second installment of this series. Examples of controls include the window’s background, the season select screen, and the episode thumbnail. We’ll go into greater detail on controls shortly.

To begin, we create a file in the 720p called main.xml. This file defines our main window and populates it with the controls we created earlier. Essentially main.xml is the heart of our first application.

First, we define an XML document with a root node for our default window.  Consider the following XML:

1
2
3
4
5
6
7

<?xml version="1.0"?>
<window type="window" id="14000">
    <defaultcontrol always="true">100</defaultcontrol>
    <allowoverlay>no</allowoverlay>
    <controls>
    </controls>
</window>

What does this all mean? Let’s break it down:

window:

This element defines the main window for our app and assigns it an id. If you recall in our last installment, our descriptor.xml defines a windowId when the application starts with the startWindow element. This tells Boxee which window to start first when the application is launched.

defaultcontrol:

Like the application needs a default window ID when it is launched, a window needs a default control ID when it begins. We define it here as “100,” which is a control we will create later.

allowoverlay:

This element governs the app’s behavior if Boxee is playing any media. For most applications, we want the interface to supersede what is currently playing, so we set this to “no”.

controls:

This element is the parent for all the controls we will define for this window. The background image, list container and metadata box will go in here.

For more detail on the various elements available to your window, you can refer to this guide on the XBMC wiki.

With our window defined, we are going to add two appropriately named controls – a group control and an image control. A group control is an arbitrary container intended to group together controls that have a similar purpose. To get our “Hello World” app running, we’ll create a group control to contain our image control:

1
2

        <control type="group">
        </control>

Then within that group control, we’ll place an image control for the background image that we created earlier. There are five elements in every image control: posx, posy, width, height, and texture. Boxee renders position elements with respect to the upper left hand corner of the screen and dimension elements with respect to the position coordinates you provide. Since this is a background image, we set our position to 0,0 or the upper left hand corner of the screen and our width/height to 1280×720 (for our 720p resolution application). Finally, we set the value of the texture element to the name of the file in the media folder we created for our background:

1
2
3
4
5
6
7

            <control type="image">
                <posx>0</posx>
                <posy>0</posy>
                <width>1280</width>
                <height>720</height>
                <texture>background.png</texture>
            </control>

So what should this look like when put together correctly? Viola!:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<?xml version="1.0"?>
<window type="window" id="14000">
    <defaultcontrol always="true">100</defaultcontrol>
    <allowoverlay>no</allowoverlay>
    <controls>
        <control type="group">
            <control type="image">
                <posx>0</posx>
                <posy>0</posy>
                <width>1280</width>
                <height>720</height>
                <texture>bg.png</texture>
            </control>
        </control>
    </controls>
</window>

Once we’ve completed this step, our work in the last step can now come to fruition. Since we included the “test-app” element in our descriptor.xml, Boxee will recognize our new app immediately on startup. Now open Boxee and when you go to Apps, you can execute your app and see the background you created!