Theme development guide

From MythTV

MythTV supports frontend "skin" development, or theming. This theme development guide covers the steps necessary to develop your own look-and-feel for the user interface.

Introduction

The primary way to learn Myth themeing is by tinkering with an existing theme and learning as you go. This document aims to address that by providing information about the various tags and their attributes as well as "best practices".

Go to the Menu theme development guide for more information about theme menu's.

Types of Themes

There are three themeable areas in Myth

1. The core User Interface. What most people refer to when they talk about a "theme". This is what this document primarily addresses. UI themes are made by modifying the theme.xml as well as the various ui.xml files.
2. The OSD. The On Screen Display has it's own themeing system, and will be the convered in the OSD development guide. OSD themes are made by modifiying the osd.xml file.
3. The Menus. Menu themes allow you to customize the layout of Myth's menus, and will be covered in the menu theme development guide.

Each of these types of themes reside in subdirectories under the themes folder of Myth, /usr/local/share/mythtv/themes by default. The Myth frontend determines which kind of theme is in the subdirectory by looking for key files.

1. theme.xml for UI themes.
2. osd.xml for OSD themes.
3. main_menu.xml for menu themes.

If one were to create a UI theme along with a menu theme and OSD theme to go with it, one could put them all in the same subdirectory so that they'd all have the same name, however it's much better to follow a nameing convention where the UI theme acts as the base name (i.e. "Foo") and the OSD and menus each have something added to indicate what they are (i.e. "FooOSD" or "Foo-Menus").

From this point forward the word "theme" will refer to UI themes exclusivly.

System Setup

• In order to allow for consistent appearance of themes, it's imperitive that your display be configured so that you have 100 dots per inch (DPI). Running xdpyinfo | grep inch should result in resolution: 100x100 dots per inch being displayed in the console. If it doesn't, you'll need to adjust the DisplaySize section of your X config files.

• If you're using multiple machines (for example a Win32 machine with Photoshop on it) make sure that your clocks are in sync. Otherwise Myth may not pick up art changes, or may think art has changed more often than it has and cause you delays.

• It's best to work at the native resolution for your theme: 800x600 for square themes and 1280x720 for widescreen themes. Failing to do this may result in your pixmaps being rescaled more often than necessary.

Overscan and You

4:3 Cheatsheet PNG

16:9 Realistic Cheatsheet

From Billy Biggs' Overscan and Broadcast Television page: "In an NTSC television signal, there are 486 scanlines on which you can put an image, and in digital video there are usually 720 pixels on each scanline. However, on your television not all of this image is visible. The border of the image extends past the image you see on your screen. The part of the image you can't see is the overscan."

It's important to take overscan into account when designing your themes. With most televisions the edges of the screen are a dangerous area where objects in the picture may or may not appear outside the visible display area, or worse still, may fully appear on your television but not appear on someone else's. To avoid having an otherwise pleasant theme ruined by having elements cut off on the edge of the display, you may well wish to avoid placing visual elements right up against the edge of the available area, and instead place all your theme elements within the "safe area".

Few modern televisions overscan by more than 5% and in many cases it is possible to correct for this with your video card drivers, so a figure of 95% for the "safe area" is assumed to be realistic. Keeping theme elements within these areas does mean that you will have some blank space surrounding your theme, but in practice this should be hardly noticeable.

To assist with proper theme creation respecting these areas we have two files people can use--one for standard aspect ratio and one for widescreen themes, visible along the right-hand edge of this section.

Colors, colors, and fewer colors

Those of you making widescreen themes explicitly for digital panels will not really have to worry about this, but those of you making themes for (typically non-widescreen) CRTs may wish to pay heed: While one would assume that a video card would not output a video signal unsafe for displaying, this does not appear to always be the case. Digital Video and NTSC actually have different levels of brightness that they consider "safe", and exceeding these levels (either too high or too low) can cause unpleasant things to happen on the user's end: strange humming sounds if they are using an RF modulator, "bruising" on the display, etc. NTSC itself even has a different level for black in Japan than it does in North America.

The "safe" upper bounds for colors for an NTSC display is going to be (235,235,235). The lower bounds differs between NTSC-J and NTSC-M (North America), although the difference is fairly minimal. NTSC-J considers true black to be (0,0,0) while NTSC-M considers true black to be (16,16,16). You may wish to consider adjusting the palette and colors used by your 4:3 theme to be no brighter than (235,235,235) and no darker than (16,16,16) to avoid complications.

There is a very easy way to convert existing images to be NTSC "broadcast safe" using the Gimp. Simply open the image and from the menu bar select Layer->Colors->Levels, leave Input Levels alone, but change Output Levels to 16 and 235 respectively. The image will now be using "broadcast safe" colors for North American NTSC.

Theme Basics

All Those Files

A theme in Myth is controlled by several files:

• themeinfo.xml - This contains information describing the theme and its properties, from 0.21 it will be required for all themes.
• qtlook.txt - This file contains basic information that controls the appearance of the Qt based controls, it also contains the main background image.
• theme.xml - This file controls the appearance of your menus, as well as provides a place to declare your base fonts.
• ui.xml - This file contains all of the windows used in core Myth.
• *-ui.xml - These files contain the windows used by the various plugins

As you're working on your theme, you find that some changes can be observed immediately, while others require a restart of the frontend. Namely, changes to theme.xml or qtlook.txt require restarting myth (or changing the theme twice) in order to see them. Changes to any of the ui XML files simply requires entering the window that you've changed again.

Square vs Wide

For standard definition television which has a 4:3 aspect ratio, Myth uses "square" themes based on an 800x600 srceen. With the advent of HDTV, a lot more screen space became available for use. Widescreen themes in Myth are based on a 16:9 aspect ratio, 1280x720 (HDTV 720p) screen. If the user's display is different than base resolution for the type of theme Myth will automatically scale the fonts and graphics to match the new resolution (which is why laying things out at 100 DPI is so critical).

• Any theme ending in "-wide" is considered to be a wide screen theme by the Myth frontend.

N.B. It is ultimately intended that base resolution and aspect ratio will be determined by the themeinfo.xml file, so it would be a very good idea for theme designers to keep their source image files in as high as resolution as possible, with HD (and very HD) theme resolutions in mind.

Font Inheritence and Declaration

Local vs Global

Fonts are primarily defined in the theme.xml file. You can declare fonts on a per window basis, however that results in a lot of duplication within the theme forces the Myth UI to create and destroy fonts on the fly that it could simply create once and keep around. A good guideline to follow, is that a given font will be used in more than one window it belongs in theme.xml. If it will be used only in one window then make it a local font.

Inheritance

In order to make it easier on theme developers, the notion of font inheritance was built into Myth prior to the 0.18 release. Using font inheritance makes it much easier to achieve a consistent look and feel, as well as make sweeping changes without much hassle. A font is considered to inherit from a base font, when it includes a base attribute. The base attribute is a way of saying "Make this font exactly like the base font, except for the things I change.".

Declaring a Font

A font declaration looks something like the following:

   <font name="basefont"  face="Nimbus Sans L"> 
        <color>#ffffff</color>
        <dropcolor>#3B4045</dropcolor>
        <size>20</size>
        <size:small>18</size:small>
        <size:big>22</size:big>
        <bold>yes</bold>
    </font>

The font tag has the following attributes:

• All fonts must have either a base (which provides a face), or a face attribute.
• It's possible to declare both a base and a face. In which case, all of the attributes of the base font will be used, but the face overridden,

In addition to the above attributes fonts may also use the following child elements:

• The size elements are only required for fonts without a base, for all others it's optional.
• It's important to provide all three sizes of fonts. What might be perfect for you, may be too big/small for someone else.
• The bold, italics and underline are expressed with a yes/no syntax. i.e. <bold>yes</bold>
• For standard definition TV it's a good idea to use bold fonts, as many TVs make the narrower fonts hard to read.

theme.xml sections

The file theme.xml is the foundation of a theme. It contains the global fonts, as well as determines the appearance of the menus within Myth. The coordinate system used is such that:

• The top left corner of the screen is (0,0).
• All bounding boxes are expressed as (x,y,width,height).

background

This element controls the appearance of the background for the menus and has the following attributes:

In addition, the following child elements are also valid:

titles

Each menu can potentially have it's own title image. This section provides a map for those titles.

There are no attributes for the title elements. There are however child elements:

• It's important to note that each image needs a mode attribute that maps it to a menu. For example: <image mode="TV">title_tv.png</image> maps the title_tv.png to any menu that has a type of "TV".

genericbutton

The generic button section defines the characteristics of a button on your menu.

It has no attributes but does have the following elements

• If buttonspread, and button center are off, the spacing of your buttons is controlled by the size of your inactive image.

text & activetext

Defining your text and activetext elements is much like declaring a font.

The text and activetext have no attributes, however they do have the following elements.

• Much like with font declarations, the bold, italics and centered elements all use yes/no for their values.

shadow

The shadow element has no attributes, however it does have the following elements:

• Light colors with an offset of -1, -1 can produce an inset look.

outline

The outline element has no attributes, however it does have the following elements:

uparrow/downarrow

If there are more menu items to be displayed than what can fit in your button area, Myth will show an indicator on screen to let the user know that there are more items off screen. This indicator is context sensitive in that it will only show the indicator if there are more items in that direction. For example, while the menu may start with a down arrow showing, the up arrow will not appear until the top menu item has scrolled off screen.

These are pretty simple elements that have the following child elements:

buttondef

The buttondefs allow you to create unique buttons for each of the menu items in Myth as well as tie a watermark to a given option. These button defs are optional, you can omit this section completely if you don't feel the need for lots of eye candy.

The buttondef element also has the following sub elements:

• If you don't want special art for each button, create a blank (transparent) PNG and use that.

Windows and Containers

The Myth UI is composed of themed menus (controlled by theme.xml) and windows. The windows are composed of one or more containers, which in turn contain the actual controls used to display information and interact with the user.

Windows

The basic anatomy of a window declaration looks something like this:

  <window name="examplewindow">
      <!-- local font declarations -->
      <!-- containers -->
  </window>

• Fonts may be declared inside of windows just like in theme.xml. The difference here is that they're local to the window they're declared in and will override any global fonts of the same name.
• Details of what windows do what will be in later sections.

containers

ui.xml

The file ui.xml contains all the windows for the core of mythfrontend. Plugins maintain their own ui files, and we'll cover them later.

What's what

base.xml

The file base.xml contains a base theme to be applied before other theme files.

What's what