MythUI Theme Development

From MythTV Official Wiki
Revision as of 01:01, 20 February 2009 by Iamlindoro (talk | contribs)

Jump to: navigation, search

Overview

As of MythTV version .22, the theme engine is much more flexible and robust. This guide will serve as a comprehensive reference for developing a MythTV theme, including documentation of all available MythTV widgets and the basic XML files that must be completed to have a working theme.

Terminology

Conceptually, MythTV themes are fairly simple. They are a series of XML theme files, and any associated media called by those files such as images. Within each XML theme file, individual screens in MythTV are defined as windows. Each window contains MythUI Widgets, and the widgets contain various attributes. Take this simple example of a MythUI theme file:

<mythuitheme>
    <window name="MyFirstWindow">
        <textarea name="MyFirstTextArea">
            <area>0,0,1280,720</area>
            <font>basesmall</font>
            <value>This is some text!</value>
        </textarea>
    </window>
</mythuitheme>

Let's discuss the code we just looked at. Every tag in XML must be opened and closed, just like in HTML. If you don't match all of your tags, your theme will not work! Every MythUI theme file (with one exception to be explained later) opens with the <mythuitheme> tag and ends with </mythuitheme>. Inside of the theme, we defined a window called "MyFirstWindow." Inside of that window, we created a textarea widget with three attributes, area, font, and value. How each of these things works will be explained in a bit, but this is the most basic kind of structure found in every themed screen in MythTV.

Required Files

The bare minimum of files required to make a Myth Theme load are as follows:

themeinfo.xml

The themeinfo is the one exception to the rule about all MythUI themes opening and closing with <mythuitheme>. The themeinfo uses the following format:

<themeinfo>
    <name>LoremIpsumTheme</name>
    <aspect>16:9</aspect>
    <author>
        <name>Loren J. Ipsum</name>
        <email>lorenj@ipsum.com</email>
    </author>

    <types>
        <type>UI</type>
    </types>

    <baseres>1920x1080</baseres>

    <version>
        <major>1</major>
        <minor>1</minor>
    </version>

    <detail>
        <thumbnail name="preview">preview.jpg</thumbnail>
        <description>We're defining a basic theme.  This is going to be fun!</description>
        <errata>Use this space for notes!</errata>
    </detail>
</themeinfo>

Let's briefly look at what each attribute in the themeinfo.xml file does.

<name>: This is the name of your theme as will be displayed in the theme selection menu.

<aspect>: This is the aspect ratio of your theme. Myth does not currently use this value for calculations, so this is purely informational.

<author>: This contains two subattributes, <name> and <email>. they provide identifying information about the theme's author(s).

<types>: This contains one subattribute, <type>. It defines what type of theme this is. There are three eligible types, UI, OSD, and menu. UI themes are overall myth themes. OSD themes govern the on-screen display during video playback. Menu themes define the tree structure of Myth's menus.

<baseres>: This is the value that myth uses to parse all the co-ordinates in your theme. It is the number of coordinates you are giving yourself to work with and the resolution you are targeting with your theme. We'll talk more about this later when talking about the <area> attribute.

<version>: This contains two subattributes, <major> and <minor>. They define the Major and Minor version numbers of your theme. In the example above, the version is defined as "1.1".

<detail>: This has three subattributes, <thumbnail>, <description>, and <errata>. <thumbnail> defines an image in your theme directory to act as a preview in the Theme selection dialog. <description> describes the theme. <errata> can be used for notes and license information for your theme.

base.xml

The base.xml file is the core