»
S
I
D
E
B
A
R
«
Hello World – In Video!
3 February 2010 by Rob Spectre

Mark Tucker over at shazaml.com has put together a great six minute screencast showing how to develop a quick “Hello World” app on Boxee.  Mark’s video is very detailed and pro-quality, showing how to create a test app on Windows.  Great work here.

Using The Sidebar In Your Apps
12 January 2010 by Joshua Jonah

Hi my name is Joshua, I am a boxee and all around Python developer who will now be contributing to gonzee.tv. I have a background in web application and social networking development, but I’m also a huge HTPC nut. Boxee is the perfect middle ground. I hope my articles help you out in times of need.

Without further ado…

The sidebar is used in the factory boxee sections. It’s on the side and lets you sort, filter, and otherwise manipulate the list in the factory boxee sections.

Boxee Movies section with sidebar visible</code>

The sidebar would be a great place to put things like preferences, sorting, and less used items within an app. The information is out of the way, but still in a comfortable place that is consistent throughout the boxee interface.

I’ve been wanting to use this in my own apps to really pull the experience together, so I started tearing apart the boxee skins. There are many “classes” and other things in the boxee skin files that you can use in your own apps to save code and increase consistency. I would recommend any developer to take a look.

I’ve recovered the base code required to have the sidebar working on your app:

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
<control type="group" id="9000">
    <include>BrowseListsAnimation</include> # This is required for some reason.
 
    # Put your main app xml here.
    #
    # For example a list:
    <control type="list" id="600">
        <description>Media items</description>
        <posx>40</posx>
        <posy>160</posy>
        <width>600</width>
        <height>520</height>
        <onleft>8000</onleft> # Notice pushing left activates the sidebar from this list.
        <onright>-</onright>
        <onup>200</onup>
        <ondown>-</ondown>
        <scrolltime>200</scrolltime>
        <pagecontrol>-</pagecontrol>
        <orientation>vertical</orientation>
        <itemlayout width="600" height="60">
            <control type="label">
                <posx>0</posx>
                <posy>0</posy>
                <width>560</width>
                <height>40</height>
                <font>font28</font>
                <align>left</align>
                <label>$INFO[ListItem.Label]</label>
                <textcolor>grey</textcolor>
            </control>
        </itemlayout>
        <focusedlayout width="1280" height="60">
            <control type="label">
                <posx>0</posx>
                <posy>0</posy>
                <width>560</width>
                <height>40</height>
                <font>font28</font>
                <align>left</align>
                <scroll>true</scroll>
                <scrollspeed>30</scrollspeed>
                <label>$INFO[ListItem.Label]</label>
                <textcolor>white</textcolor>
            </control>
        </focusedlayout>
    </control>
</control>
 
<control type="group" id="8000"> # This is the sidebar
    <include>BrowseLeftMenuAnimation</include>   # Required for some reason.
    <include>BrowseLeftMenuBackground</include>  # This includes everything to draw the
                                                 # background of the sidebar
    <control type="grouplist">                   # A grouplist is a good idea so that if
        <include>BrowseLeftMenu</include>        # there's too many controls, it can scroll.
        <control type="label" id="402">
            <include>BrowseLeftMenuTitle</include>      # <- there are some 'classes' I found
            <label>[UPPERCASE]Available Feeds[/UPPERCASE]</label>
        </control>
 
        # Include whatever you want on the sidebar here.
        # Make sure to add "<onright>9000</onright>" to the elements so you can get back to
        # your app.
 
    </control>
</control>

Make sure to remove all of the comments before trying this code, the boxee XML parser doesn’t like python comments (#).

This will get you an empty window with a sidebar on the left.

Enjoy.

Building Your First App – Release It!
13 November 2009 by Rob Spectre
This entry is part 9 of 9 in the series Building Your First App

At long last, we are at the final step of building your first Boxee application – release!  After designing, coding and debugging our app we’re ready to release it in the wild by submitting it to Boxee for inclusion in the App Box.

The App Box is similar to the iTunes App Store developers are familiar with for the iPhone.  It is the default repository for all Boxee software, all fully tested and confirmed to work on the platforms for which it is submitted.  The submission process, however, is far less intrusive than Apple’s and ultimately produces the highest quality experience for the Boxee community of 700,000 users.   Plus the submission process gets your app tested on hardware profiles you likely don’t have access to – a huge plus to guarantee your app looks good on all the devices running Boxee.

Let’s get started submitting the app we just built.

1) Make an App Thumbnail

The app thumbnail is what users see in the App Box as the icon to install your app.  Naturally, our app thumbnail should concisely represent what kind of content the app contains and should attract users to install it. The thumbnail should be 200×200 and placed in the Internet accessible location we defined in the <em>thumb</em> element of our <em>descriptor.xml</em>.

The standard background for a Boxee App thumbnail

If you would like to conform to the look of the rest of the App Box (always a good idea), you can use this black image as a background.

1) Zip up the app

All Boxee repositories distribute apps through zip files.  In order to speed up the review of your app, you can zip up your app so that it is ready to go for the quality assurance folks who will be putting your app through the paces. First we navigate to the <em>apps</em> directory in your local Boxee UserData folder and identify the folder containing our app – it should be the same as the <em>userid</em> we defined in our <em>descriptor.xml</em>.

Then zip the file with the convention <em>appid-version.zip</em>.  For example, if we were submitting Auto-Tune The News for the App Box, we would name our zip file <em>autotunethenews-1.0.zip</em>.

Note: Be sure to remove the <test-app> element from your descriptor.xml before submitting!

2) Sign up for Boxee JIRA

Before sending your zip file to Boxee for consideration, you need to sign up for an account in Boxee’s bug management software.  This will allow Boxee to get a hold of you in the event of any problems as well as use JIRA to submit your app.  You can sign up at http://jira.boxee.tv.

3) Follow the Application Submission Process

Once you’ve signed up on JIRA, you’re ready to start Boxee’s Application Submission Process.  Just hop on the developer wiki page linked here and you’re on your way!

When submitting your app to the Boxee App Box, expect that it will take 3-4 business days for your app to get checked by Boxee QA.  With over a dozen apps in the App Box, it is a process with which I have gained intimate familiarity and can offer a few tips to make your submission sail.

  • Debug Your App - Make sure you click on every button and every video in your app at least once.  Boxee QA will definitely be doing the same and you can save yourself (and them) a cycle of iteration by doing it yourself.
  • 1280×720 – Be sure you are always developing in a windowed Boxee client.  This will make Boxee default to 720p, which will ensure your app looks the best on all screens.  You can window your Boxee client by pressing the “\” key after you start.
  • 480i - Make sure your video is at least 480i quality.  If it’s not good enough for TV, it’s not good enough for Boxee.

Finally, there is one last step:

4) Tell people!

Be sure to post on the forums, your own blog and, if you would do me the courtesy, here on gonzee.tv to let the world know that you just published your first Boxee app!  Cable packages only get a few new channels a year – Boxee gets dozens of new apps a month.

Get on Twitter, Facebook, Cliqset, and every corner of the Internet to let them know you’re tired of television and ready to change the living room with your first Boxee app.

Building Your First App: Hello World
3 November 2009 by Rob Spectre
This entry is part 4 of 9 in the series Building Your First App

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!

Building Your First App: Designing the Skin
28 October 2009 by Rob Spectre
This entry is part 1 of 9 in the series Building Your First App

The Boxee family grows every month as more and more developers discover how easy it is to get started developing on this social platform for the living room.  Using tools such as Yahoo Pipes and popular scripting libraries for generating feeds, developers can go from zero to a published app in no time using Boxee’s default skin.  Just plug in a RSS feed that conforms to the Boxee spec and Boxee “just works.”

But where Boxee really shines as a development platform is with full skin apps.  A lot of Boxee RSS app developers are intimidated by the Boxee API, believing a strong Python background is necessary to build a full skin app.  However, this is just not the case.  Boxee apps can be as simple or as complex as the individual developer needs them to be with many applications requiring no Python application logic whatsoever to work well.  The XML-driven GUI available for Boxee developers gives you everything you need to take your RSS feed and provide a rich, compelling living room interface.

If you can make an RSS feed, you can make a Boxee skin app.

Last month, I got to work with prolific Boxee developer jendabom on building her first skin app for Boxee.  Together, we were able to take one of her RSS apps (Storyline) and make a full skin with a few emails and a couple afternoons worth of work .  From that correspondence, we’ve developed this series taking you step-by-step through building your first skin app.

The way I attack a new app is first designing the interface in my favorite graphic design suite.  I use GIMP myself (as it is FOSS), but if you have access to something more professional like Photoshop or Paintshop Pro that would be good too.

The goal of this step is to layout the interface you are looking for in individual layers that can then be cut out into individual graphics elements that you will make into Boxee app controls.

Here are a few tips:

  • Set your canvas size to 720p (1280×720).  This will ensure your skin looks good on a variety of displays.
  • We can start by choosing between two basic interface options – List and Panel. An example of a “List” interface would be Auto-Tune The News or The Philip DeFranco Show.  An example of a “Panel” interface would be AL TV or KidMango.  Adjust your UI design to fit each paradigm appropriately.
  • Text over multi-color images == bad.  Try to avoid this pet peeve of Boxee QA.

Here’s an example of what jendabom came up with for Storyline:

StoryLineOnline

Adding Animation to an External Control
12 August 2009 by Rob Spectre

One of the elements I liked most in building the UI for AL TV was the drawer animation coming from under each thumbnail to provide the label of the ListItem. That UI mechanic is present all over the Boxee application and using it leaves more screen real estate to fit in a greater number of thumbnails.

Show me your drawers.

Show me your drawers.

The implementation was easy – two “slide” animations on the label and a background image for the ListItem in the panel container.

<animation effect="slide" start="0,-100" center="auto" time="200">Focus</animation>
<animation effect="slide" end="0,-100" center="auto" time="200">Unfocus</animation>

zOMG! Those thumbnails totally drop their drawers when you focus on them now.

Having opposite elements for Focus and Unfocus, the drawer slides cleanly out and back in as a ListItem receives and loses focus. When starting out developing my new Associated Press app, I knew I wanted to leverage a similar mechanic, but was unsure if it would fit with the app’s feel. The target length of experience, breadth of content, and probably userbase for each app probably didn’t share much on the Venn Diagram.

Making a news app look like a music video app wouldn’t please many users, after all, and the AP content lent itself to more of a scrolling ticker list design, a la Auto-Tune The News.

unfocused

Youkilis suspended?! But why?

A panel, album-cover like navigation was totally out for the AP experience, which I envisioned being brief, daily and ubersimple. Only one thumbnail visible from 30 feet away and text bigger than Jesus. A drawer would be great for the meta information like publish date and description, but those would be located in a label external to the list container. Without performing the animation within the list container, how would I be able to get the drawer effect I was looking for? The answer is the “condition” attribute. Just as the value of the animation elements used in AL TV were the conditions we desired – Focus and Unfocus – so to can we set arbitrary conditions using the Boxee API. Consider the following XML:

<animation effect="slide" start="0,-105" center="auto" time="200" condition="Control.HasFocus(111)">Conditional</animation>
<animation effect="slide" end="0,-105" center="auto" time="200" condition="!Control.HasFocus(111)">Conditional</animation>

Instead of the value of the animation element being our desired behavior, we instead choose “Conditional” and then use the condition attribute.

Ah.  With focus we can see the metadata, which tells us he was suspended for punching out a douchebag from the Detroit Tigers.  Well done drawer animation and well done Youkilis.

Ah. With focus we can see the metadata, which tells us he was suspended for punching out a douchebag from the Detroit Tigers. Well done drawer animation and well done Youkilis.

In this case, we use the Boxee API to determine if our list container does or does not have focus. If it does, pull out the drawer with the metadata. If it does not, slide that back up cleanly as the user clicks on other things. This simple animation did much for the professional, clean design of the app, except the slide would always happen before the list container was finished parsing the RSS feed. To prevent this, we can use the visible element to make sure it plays nicely and waits until the RSS is finished loading.

<visible>!Window.IsVisible(DialogProgress.xml)</visible>

This same attribute can be leveraged for all kinds of zooms, fades, and rotates to killer effect, limited only by your imagination in terms of the use cases. GetWindow, ActivateWindow, IsPaused and many other methods can trigger animations that would be useful to the user. You can see this tip in action with the Associated Press app, soon to be published in the App Box.

Site Launch
11 August 2009 by Rob Spectre

Woo! I finally decided to put up a site for my efforts in Boxee development.  This site is intended to be the primary resource for the collection of Boxee apps that I’ve released.  It will feature tips and tricks on developing Boxee, hints and helper for using Boxee and of course full release notes and support of the growing collection of Gonzee applications.

Welcome to gonzee.tv.

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