Developer Blog

How to Use Dialogs in Your Boxee App

A great new feature in our last client release that devs have been asking about is the introduction of the “dialog” window type to our platform UI. Dialogs allow you to define frequently used combinations of UI elements in a separate XML file and activate them from any window. This allows you to reduce the amount of duplicate markup in your app and make future maintenance far simple than duplicating similar controls in each window. In this post we’ll look at a simple example demonstrating how to use this feature.

First, we create a simple skin with two controls: a background image and a button control in a file called main.xml and assign it Window ID 14000.

<?xml version="1.0"?>
<window type="window" id="14000">
	<defaultcontrol always="true">100</defaultcontrol>
	<allowoverlay>no</allowoverlay>
	<controls>
		<control type="image" id="101">
			<posx>0</posx>
			<posy>0</posy>
			<width>1280</width>
			<height>720</height>
			<texture>background-main.png</texture>
		</control>
		<control type="button" id="100">
			<posx>200</posx>
			<posy>200</posy>
			<width>145</width>
			<height>145</height>
			<label>Click Me!</label>
			<font>font36b</font>
			<textcolor>white</textcolor>
			<focusedcolor>gray</focusedcolor>
			<texturefocus>-</texturefocus>
			<texturenofocus>-</texturenofocus>
		</control>
	</controls>
</window>

The result looks a little like this:

Next, we create our dialog window with three controls in a file named dialog.xml and assign it Window ID 14001.

  1. A diffused background image to darken the window we just created behind our new dialog.
  2. A button control to close our dialog window.
  3. A Boxee logo (who doesn’t need to see more of them?)
<?xml version="1.0"?>
<window type="dialog" id="14001">
 <defaultcontrol always="true">300</defaultcontrol>
 <allowoverlay>no</allowoverlay>
	 <controls>
	 	<control type="group" id="7001">
			<control type="image">
				<width>1280</width>
				<height>720</height>
				<texture>white.png</texture>
				<colordiffuse>DD202020</colordiffuse>
			</control>
			<control type="button" id="300">
				<posx>565</posx>
				<posy>75</posy>
				<width>145</width>
				<height>145</height>
				<label>Close Me!</label>
				<font>font36b</font>
				<textcolor>green</textcolor>
				<focusedcolor>green</focusedcolor>
				<texturefocus>-</texturefocus>
				<texturenofocus>-</texturenofocus>
			</control>
			<control type="image">
				<posx>244</posx>
				<posy>100</posy>
				<width>792</width>
				<height>612</height>
				<texture>logo.png</texture>
			</control>
		</control>
	 </controls>
</window>

Now we need to activate our dialog from our main window. To do this, we add an onclick event to the button control in main.xml and introduce an easy ActivateWindow() method using the ID of our dialog (14001) as the argument.

		<control type="button" id="100">
			<posx>200</posx>
			<posy>200</posy>
			<width>145</width>
			<height>145</height>
			<label>Click Me!</label>
			<font>font36b</font>
			<textcolor>white</textcolor>
			<focusedcolor>gray</focusedcolor>
			<texturefocus>-</texturefocus>
			<texturenofocus>-</texturenofocus>
			<onclick lang="python"><![CDATA[
mc.ActivateWindow(14001)
]]></onclick>
		</control>

Once we restart the app, we can now see the three controls we created in our dialog appear over our window. Bamf!

But, it is not merely enough to display a dialog window - we need the user to be able to close it as well. So we use the xbmc module to execute a method called “Dialog.Close()”. We do this by first importing the xbmc module in an onload event for the dialog.

<?xml version="1.0"?>
<window type="dialog" id="14001">
 <defaultcontrol always="true">300</defaultcontrol>
 <allowoverlay>no</allowoverlay>
 <onload lang="python"><![CDATA[
import xbmc
mc.LogDebug(message)
]]>
</onload>

We then can execute it by adding the following onclick event to our dialog’s button control.

			<control type="button" id="300">
				<posx>565</posx>
				<posy>75</posy>
				<width>145</width>
				<height>145</height>
				<label>Close Me!</label>
				<font>font36b</font>
				<textcolor>green</textcolor>
				<focusedcolor>green</focusedcolor>
				<texturefocus>-</texturefocus>
				<texturenofocus>-</texturenofocus>
				<onclick lang="python"><![CDATA[
xbmc.executebuiltin("Dialog.Close(14001)")
]]></onclick>
			</control>

Once we restart the app, we can now toggle between our dialog window and our main window!

The uses for dialogs in Boxee apps are limited only by your own creativity and can help keep your app’s XML tight and maintainable. Enjoy!

Complete examples:

main.xml

<?xml version="1.0"?>
<window type="window" id="14000">
	<defaultcontrol always="true">100</defaultcontrol>
	<allowoverlay>no</allowoverlay>
	<controls>
		<control type="image" id="101">
			<posx>0</posx>
			<posy>0</posy>
			<width>1280</width>
			<height>720</height>
			<texture>background-main.png</texture>
		</control>
		<control type="button" id="100">
			<posx>200</posx>
			<posy>200</posy>
			<width>145</width>
			<height>145</height>
			<label>Click Me!</label>
			<font>font36b</font>
			<textcolor>white</textcolor>
			<focusedcolor>gray</focusedcolor>
			<texturefocus>-</texturefocus>
			<texturenofocus>-</texturenofocus>
			<onclick lang="python"><![CDATA[
mc.ActivateWindow(14001)
]]></onclick>
		</control>
	</controls>
</window>

dialog.xml

<?xml version="1.0"?>
<window type="dialog" id="14001">
 <defaultcontrol always="true">300</defaultcontrol>
 <allowoverlay>no</allowoverlay>
 <onload lang="python"><![CDATA[
import xbmc
mc.LogDebug(message)
]]>
</onload>
	 <controls>
	 	<control type="group" id="7001">
			<control type="image">
				<width>1280</width>
				<height>720</height>
				<texture>white.png</texture>
				<colordiffuse>DD202020</colordiffuse>
			</control>
			<control type="button" id="300">
				<posx>565</posx>
				<posy>75</posy>
				<width>145</width>
				<height>145</height>
				<label>Close Me!</label>
				<font>font36b</font>
				<textcolor>green</textcolor>
				<focusedcolor>green</focusedcolor>
				<texturefocus>-</texturefocus>
				<texturenofocus>-</texturenofocus>
				<onclick lang="python"><![CDATA[
xbmc.executebuiltin("Dialog.Close(14001)")
]]></onclick>
			</control>
			<control type="image">
				<posx>244</posx>
				<posy>100</posy>
				<width>792</width>
				<height>612</height>
				<texture>logo.png</texture>
			</control>
		</control>
	 </controls>
</window>
October 1, 2010 at 4:10 pm