Thursday, January 22, 2009

Extending MediaBox: Creating a Simple Component

Note: If you're reading this article in a feed aggregator like planet.maemo.org, it might be truncated. Please click the link to the original feed to read the full article.

Get your text editor ready because this time I'm showing you the basics of plugin development for MediaBox.

Last time, I have explained the component system of MediaBox. If you haven't read this article yet, please do so as it will help you understand what's going on.
Now we're going to write a simple plugin that displays a short notification when the application has started.

As I have told you before, a plugin is a directory with some components in it. MediaBox looks for the plugin directories in its components directory. So we put a new directory in there with two empty files __init__.py and StartupNotifier.py in it:

mediabox
|
+-- components
|
+-- my_first_plugin
|
+-- __init__.py
|
+-- StartupNotifier.py

Every plugin needs the __init__.py file. This is the place where components are loaded and messages are defined. In this example, we will only load our StartupNotifier component, though.

Put the following code into __init__.py:

def get_classes():

from StartupNotifier import StartupNotifier
return [StartupNotifier]

The function get_classes is called by MediaBox to load the components. This function must return a list of the classes (not instantiated objects) of your components.

Now we are going to fill StartupNotifier.py with life. It is a simple component, so we derive StartupNotifier from the Component baseclass:

from com import Component, msgs

class StartupNotifier(Component):

def __init__(self):

Component.__init__(self)


def handle_message(self, msg, *args):

if (msg == msgs.CORE_EV_APP_STARTED):
self.call_service(msgs.NOTIFY_SVC_SHOW_INFO,
"Application Startup Complete")

That's all. This simple form of a component is called a mediator component, because it just listens for and emits messages. When a component wants to listen to the message bus, it simply overrides the method handle_message and checks for the message types it's interested in. The call_service method on the other hand sends a service call to the message bus.

When you now start MediaBox, you will be greeted by your new plugin.

Next time will be a bit more theoretical again. Then I'll talk about the different types of components and what they do in MediaBox.

Saturday, January 17, 2009

Extending MediaBox: The Component System Explained

I am going to write a bit about extending MediaBox with new plugins. Let's start with the basics of the component system first. I will show you some code examples in a later article.

Since version 0.96 MediaBox uses a component system for extensions. It is essential to understand this system when implementing plugins.

Components in MediaBox are independent objects connected to a message bus, where they can send messages or listen to messages from other components. Every component gets connected to the bus automatically when created. You don't have to take care about this step.

A plugin is a collection of one or more components grouped into a directory. The YouTube plugin, for instance, consists of a YouTube device component and a component for the preferences dialog.

Plugins can also add new messages to the vocabulary of messages that can be sent across the message bus.

Here's a little ASCII-art to summarize this all.

consist of connect to
Plugins -------------> Components ---------------> Message Bus
| | | |
| emit | | listen for |
| | | |
| | | |
| define v v transports |
+------------------> Messages <----------------------+


Let's take a closer look at the message stuff now.
As explained above, the vocabulary of messages that can be sent across the message bus is defined by the plugins. Most of the messages are defined by the "core" plugin (which is not really a plugin but contains many of the core components of MediaBox).

Some messages are of type event. They are used to notify other components about something that has just happened, e.g. that a new UPnP device has been discovered.
Some messages are of type action. They are used by components to trigger actions in other components.
There are also messages of type service call. While events and messages may be handled by any component that listents for these messages, a service call is only sent to one component and not visible to others. The message bus remembers which component can handle a particular service call and will route all subsequent calls for the same service to the same component again.

To sum it up with ASCII-art:

+------> Event
is either of type |
Message -------------------+------> Action
|
+------> Service Call


When a plugin defines a new message, it has to give it a name. The name is all uppercase and consists of a domain name, the message type, and some descriptive name.
The domain name helps to avoid name clashes of messages defined by different plugins. It should be the name of your plugin.
The message type tells programmers about the type of message. It is one of EV for events, ACT for actions, and SVC for service calls.

These are some examples of actual messages defined by components belonging to MediaBox:

  • CORE_EV_APP_IDLE_BEGIN (event: MediaBox is announcing to go idle in order to save battery)

  • CORE_EV_APP_IDLE_END (event: MediaBox is announcing to wake up from idle state)

  • NOTIFY_SVC_SHOW_MESSAGE (service call: show a short message)

  • HWKEY_EV_UP (event: user pressed up on the d-pad)

  • HWKEY_EV_DOWN (event: user pressed down on the d-pad)

  • HWKEY_EV_LEFT (event: user pressed left on the d-pad)

  • HWKEY_EV_RIGHT (event: user pressed right on the d-pad)

  • UI_ACT_SELECT_VIEWER (action: select a viewer)


Some messages take parameters. NOTIFY_SVC_SHOW_MESSAGE, for instance, takes as parameter the text of the message to show. Some service calls even have a return value.

These are the basics of the component system. Next time I will show you how components are integrated in MediaBox, and how to create a simple plugin.

Saturday, January 10, 2009

Making Themes for MediaBox

Today I'm showing you how to make new themes for MediaBox.

Every theme is a subdirectory in /usr/lib/mediabox/theme or in ~/.mediabox/themes (MediaBox 0.96.2 or higher).
You can test your themes in ~/.mediabox/themes and when distributing the theme as an installer package, it will install into /usr/lib/mediabox/theme.

There are a two files that are absolutely necessary for a theme to work, and every theme must include them.

The one is PREVIEW.png, which is a PNG image of size 112 x 67 pixels, showing a preview image of your theme. This is the icon that the users will see in the theme selector.

The other file that is necessary is a simple text file called info. This file describes the theme and looks like this:
name:        MyTheme
description: My example theme for MediaBox
author: Your Name




Of course, with only these two files, your theme will be pretty empty. Actually, MediaBox will load everything that it doesn't find in the current theme from the default theme. Thus, every theme inherits from default.

When you look into the directory of the default theme (/usr/lib/mediabox/theme/default), you will see a lot of images in PNG format. These are the theme elements. Your theme can override any of these images by providing a PNG image of the same name and the same size. I have to stress that it is absolutely necessary that the theme elements provided by your theme are exactly the same size as the ones in the default theme! For instance, the element mb_panel.png is of size 64 x 64 pixels. If your theme provides mb_panel.png, it must be of size 64 x 64 pixels, too.

A theme can have a bunch of .def files, which are text files containing font and color definitions. The name and number of the .def files is not important. Below are example entries of a .def file:
#
# Virtual Keyboard
#
color_mb_vkb_background: #000000
color_mb_vkb_text: #dddddd
font_mb_vkb: Nokia Sans Cn bold 20


Empty lines and lines starting with a # symbol are ignored by MediaBox and can be used for adding comments and making the file better readable.
The other lines contain key-value pairs, where key and value are separated by a : symbol. If the key name starts with color_, then MediaBox treats it as a color definition. If the key name starts with font_, then MediaBox treats it as a font definition.

Color values are given in hexadecimal RGB (6 digits) or RGBA (8 digits) notation, prepended by a # symbol. Most color keys take RGB values only.

Font definitions are given in Pango syntax, containing the font name, optionally a style (bold or italic), and the font size in points. Although the Nokia internet tablets have a screen resolution of 225 dpi, the system renders fonts with 96 dpi.

Any keys defined in the .def files of the default theme can be overriden by your theme in .def files.

Once your theme is ready, you may want to distribute it as a installer package for the application manager. I have created a build script for this task. If you have upload permission for the maemo-extras repository, you can then upload your theme with the Maemo Extras Assistant web site and promote it to the extras repository, so that other users can enjoy it, too.

Theme packages always depend on mediabox-compat-theme with a certain version number. For MediaBox 0.96 and some following releases, this version number will be 1.0. So as long as MediaBox provides mediabox-compat-theme, version 1.0, your theme will remain compatible. At a later point some minor changes or extensions to your theme may be necessary to fully restore compatibility again.