»
S
I
D
E
B
A
R
«
Building Your First App: The Metadata Box
9 November 2009 by Rob Spectre
This entry is part 7 of 9 in the series Building Your First App

In our last installment we turned a significant corner with the construction of our list container. Now we can finish up the interface creation on our first app by creating the metadata box. The metadata box is the interface object next to the list container that displays to the user more information about the item they have selected in the list container. Examples of metadata boxes can be seen in the screenshots for AL TV and Associated Press. Typically they include a thumbnail of the video selected and some helpful information like a description.

To get started, we’re going to abstract this interface from the rest of the application by creating a new group control.

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

By putting the metadata box in a separate group, it makes future maintenance much easier by keeps parts of the interface logically separate as we continue to develop the app. Inside that group control, we place our first interface element – the video thumbnail.

1
2
3
4
5
6
7
8
9
10
<control type="group">
  <control type="image">
    <visible>true</visible>
    <posx>635</posx>
    <posy>265</posy>
    <width>560</width>
    <height>230</height>
    <texture>$INFO[Container(100).ListItem.Thumb]</texture>
  </control>
</control>

You’ll notice that the thumbnail image control looks much like the many other image controls we’ve created so far with one significant difference in the element. Instead of a static file name, we have a dynamic INFO tag that leverages the Boxee API. We can break down the INFO tag into two parts.

Container(100)
This part of the tag tells the image to get its texture from the list container with id “111″.

ListItem.Thumb
This part of the tag tells the image to look for the thumbnail for the ListItem currently selected in the list container referenced in the first part of the tag.

This small example highlights one advantage of developing on Boxee – all controls can reference each other within the context of an app. We will do this again to add some description data underneath the thumbnail we just created using a label control.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<control type="group">
  <control type="image">
    <visible>true</visible>
    <posx>635</posx>
    <posy>265</posy>
    <width>560</width>
    <height>230</height>
    <texture>$INFO[Container(100).ListItem.Thumb]</texture>
  </control>
  <control type="label">
    <visible>true</visible>
    <posx>635</posx>
    <posy>500</posy>
    <width>560</width>
    <height>115</height>
    <font>light23</font>
    <align>left</align>
    <aligny>center</aligny>
    <label>[B]Description:[/B] $INFO[Container(100).ListItem.property(description)]</label>
    <background>grey</background>
    <textcolor>white</textcolor>
    <wrapmultiline>true</wrapmultiline>
  </control>
</control>

The label control is similar to an image control with positional and dimensional elements, a content element (with label instead of texture), and some additional formatting element (e.g. align, font, textcolor). The important bit we need to pay attention to is the label element’s INFO tag.

Like our thumbnail, it references the list container we built in the last step but instead of getting the ListItem’s thumbnail, it gets the ListItem description. Why does it use “property” instead of just appending the name of the ListItem element? A longstanding bug in the Boxee API requires the developer to use “property(description)” instead of “Description” to ensure more consistent performance.

For more information on all the things you can do with label controls, refer to the Boxee developer docs.

And just like that, our metadata box is created. All that’s left is to drop it into our existing main.xml and adjust the position and dimensions to fit our content correctly.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
<?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 type="image">
             <posx>60</posx>
             <posy>230</posy>
             <width>502</width>
             <height>416</height>
             <texture>list.png</texture>
         </control>
         <control type="image">
             <posx>630</posx>
             <posy>255</posy>
             <width>574</width>
             <height>355</height>
             <texture>details.png</texture>
          </control>
          <control type="list" id="100">
	   <posx>60</posx>
	   <posy>230</posy>
	   <width>502</width>
	   <height>416</height>
	   <orientation>vertical</orientation>
	   <itemlayout width="502" height="65">
	    <control type="label">
		<posx>0</posx>
		<posy>0</posy>
		<width>502</width>
		<height>62</height>
		<font>font40</font>
		<align>left</align>
		<aligny>center</aligny>
		<label>$INFO[ListItem.Label]</label>
		<textcolor>white</textcolor>
	    </control>
	    </itemlayout>
	    <focusedlayout width="502" height="65">
	       <control type="image">
		   <posx>0</posx>
		   <posy>0</posy>
		   <width>502</width>
		   <height>65</height>
		   <texture>white.png</texture>
		   <colordiffuse>DD171717</colordiffuse>
	       </control>
	       <control type="label">
		   <visible>!Control.HasFocus(100)</visible>
		   <posx>0</posx>
		   <posy>0</posy>
		   <width>502</width>
		   <height>62</height>
		   <font>font40</font>
		   <align>left</align>
		   <aligny>center</aligny>
		   <label>$INFO[ListItem.Label]</label>
		   <textcolor>white</textcolor>
		   <selectedcolor>DD171717</selectedcolor>
	       </control>
	       <control type="label">
		   <visible>!Control.HasFocus(100)</visible>   
		   <posx>0</posx>
		   <posy>0</posy>
		   <width>502</width>
		   <height>62</height>
		   <font>font40</font>
		   <align>left</align>
		   <aligny>center</aligny>
		   <label>$INFO[ListItem.Label]</label>
		   <textcolor>white</textcolor>
		   <selectedcolor>DD171717</selectedcolor>
		   <scroll>true</scroll>
		   <scrollspeed>30</scrollspeed>
	       </control>
	    </focusedlayout>
	    <content type="url" url="rss://yourdomain.com/yourfeed.rss">
	    </content>
	</control>
        <control type="group">
           <control type="image">
              <visible>true</visible>
              <posx>635</posx>
              <posy>265</posy>
              <width>560</width>
              <height>230</height>
              <texture>$INFO[Container(100).ListItem.Thumb]</texture>
           </control>
           <control type="label">
              <visible>true</visible>
              <posx>635</posx>
              <posy>500</posy>
              <width>560</width>
              <height>115</height>
              <font>light23</font>
              <align>left</align>
              <aligny>center</aligny>
              <label>[B]Description:[/B] $INFO[Container(100).ListItem.property(description)]</label>
              <background>grey</background>
              <textcolor>white</textcolor>
              <wrapmultiline>true</wrapmultiline>
           </control>
         </control>
      </control>
   </controls>
</window>

And thus concludes the basic construction of our first app – we only have two more steps to go!

Building Your First App: Finishing The Graphics
5 November 2009 by Rob Spectre
This entry is part 5 of 9 in the series Building Your First App

In our last installment, we successfully got our app installed and running – though it is only displaying our background.  We have two more graphic assets that we need to position in our app before we can get to building the interactive controls of our application.

The two assets we have left are the blue background boxes for the list container and the metadata box we pulled out of our original design.  This is easily accomplished by placing one image control for each graphic in the group we created in the last step.

First, let’s look at what we have to work with from last time:

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>

An important rule to remember when placing your graphics is that Boxee renders controls sequentially. This means if you want a graphic to appear on top of another graphic (as we want with our list container box over our app background), we must place one after the other in the file. Thus, we add the image control after our bg.png in the same group control:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<?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 type="image">
             <posx>60</posx>
             <posy>230</posy>
             <width>502</width>
             <height>416</height>
             <texture>list.png</texture>
         </control>
      </control>
   </controls>
</window>

With our list graphic in place, adding the metadata box graphic is just as easy. Just add it after the list container graphic:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
<?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 type="image">
             <posx>60</posx>
             <posy>230</posy>
             <width>502</width>
             <height>416</height>
             <texture>list.png</texture>
         </control>
         <control type="image">
             <posx>630</posx>
             <posy>255</posy>
             <width>574</width>
             <height>355</height>
             <texture>details.png</texture>
          </control>
      </control>
   </controls>
</window>

Now, the next time we open our app in Boxee, we will see our original design faithfully reproduced within Boxee!

For more information on the possibilities of the image control, check out Boxee’s developer documentation.

»  Substance: WordPress   »  Style: Ahren Ahimsa
© 2009, all rights reserved.