Difference between revisions of "MythUI Theme Development"

From MythTV Official Wiki
Jump to: navigation, search
(Alphapulse)
Line 153: Line 153:
 
::Myth coordinates are calculated from the upper left corner of the screen (position 0,0).  In our themeinfo.xml file, we defined the <baseres> attribute, which defines the screen space we intend to work with.  This does '''not''' mean that it will only work on this resolution!  It simply tells MythTV how to reckon the coordinates.  On a 1280x720 theme, 128 pixels is 10% of the screen.  If one were to use the theme on a 1920x1080 screen, Myth is intelligent enough to still place the item 10% across the screen.  In short, baseres establishes the ''relative'' coordinate system that you intend to use in your theme, not a fixed resolution at which is will operate.  So, to create a widget 500 pixels right of the top left, 200 pixels down, and with a size of 300x100, we would use:
 
::Myth coordinates are calculated from the upper left corner of the screen (position 0,0).  In our themeinfo.xml file, we defined the <baseres> attribute, which defines the screen space we intend to work with.  This does '''not''' mean that it will only work on this resolution!  It simply tells MythTV how to reckon the coordinates.  On a 1280x720 theme, 128 pixels is 10% of the screen.  If one were to use the theme on a 1920x1080 screen, Myth is intelligent enough to still place the item 10% across the screen.  In short, baseres establishes the ''relative'' coordinate system that you intend to use in your theme, not a fixed resolution at which is will operate.  So, to create a widget 500 pixels right of the top left, 200 pixels down, and with a size of 300x100, we would use:
  
:::<pre><area>500,200,200,100<area></pre>
+
:::<pre><area>500,200,300,100<area></pre>
  
 
====<position>====
 
====<position>====
Line 174: Line 174:
  
 
:::<pre><alpha>128</alpha></pre>
 
:::<pre><alpha>128</alpha></pre>
 +
 +
====<alphapulse>====
 +
 +
::<alphapulse> is another exciting transparency/opacity effect that allows text or images to cycle through various levels of opacity.  It uses the following format:
 +
 +
:::<pre><alphapulse min="number value 0-255" max="number value 0-255"  change="number speed of cycling" />
 +
 +
::You'll notice that alphapulse has a slightly different format than other XML or HTML-style tags.  Since alphapulse takes multiple arguments, they're all built into the one tag, which indicates it has no paired tag by closing with "/>".  Min is the minimum transparency value in the cycle.  Max is the maximum transparency value in the cycle.  Change sets the speed at which the cycling occurs.  It is best to keep this value in single digits, or the pulse may become indistinguishable.  Here is an example of a widget or image pulsing between half and full opacity with a slow, steady speed of change:
 +
 +
:::<pre><alphapulse min="128" max="255" change="2"/></pre>
  
 
= Required MythUI Theme Files =
 
= Required MythUI Theme Files =

Revision as of 17:02, 20 February 2009

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.

Inheritance

A key component of the MythUI theme engine is the concept of inheritance. As each widget has a name, every similar widget thereafter can *inherit* from that name. Take, for example, this basic definition of a font:

<font name="MyFirstFont" face="Frutiger LT Std">
    <size>16</size>
    <color>#FFFFFF</color>
</font>

Don't worry, we'll explain how all this works later. But to illustrate the concept of inheritance, let's say somewhere later in my theme I want to define another font, and I want it to be exactly the same as the one above, except for a different color. This is make incredibly simple through inheritance.

<font name="MyFirstFontBlack" from="MyFirstFont">
    <color>#000000</color>
</font>

The font we just defined inherits the face and size from the first one, but redefines the color! As our definitions become more and more complex, inheritance will save us tons of work!

Preassigned Names

So, you might be asking, "how do I tell MythTV which information goes into which box?" Well, in addition to being able to name your own widgets and place information wherever you like, each screen in myth has preassigned names that it expects to find and use to display information. As an example, there will be a textarea in the "Watch Recordings" screen called called title. This hook is what Myth is looking for to insert the title. Consider this example:

<textarea name="title" from="MyFirstTextArea">
    <area>100,200,300,50</area>
    <font>MyFirstFontBlack</font>
</textarea>

Now we're seeing several of the concepts we've discussed in action. We've created a textarea widget with a name of "title." "Title" is one of the preassigned names used in several screens in MythTV including the Video browser and the Watch Recordings screen, among others. Myth will intelligently insert the title value for an object or selected item into this text area since it's on the lookout for a text area called "title." We also see the use of inheritance here with from="MyFirstTextArea". In this example, our themer has defined a basic text area elsewhere called MyFirstTextArea, and wants to use the attributes he assigned there in this text area. Rather than assigning the face, size, shadow, outline, etc. all over again, he simply uses inheritance to pull all those definitions in to this text area. Finally, we see that the themer has used the font name we created above, MyFirstFontBlack.

Best Practices

It's important for both your sanity and code sharing to make your themes legible. The commonly used practice in Myth themes is to indent each nested tag four spaces (NOT a tab). So, the most simple example of this coding style is something like:

<textarea name="MyCodingStyleExample">
    <area>0,0,100,50</area>
    <font>MyFirstFontBlack</font>
    <value>Wow!  Look at how clean this is!</value>
</textarea>

From the above example, it's simple to see what attributes "belong" to which widget. It's also best to leave a blank space between each widget in your theme file so that they are independent logical units. Here's an example:

<textarea name="title" from="basetextarea">
    <area>20,10,710,80</area>
    <font>baselarge</font>
</textarea>
                
<textarea name="director" from="basetextarea">
    <area>160,65,350,35</area>
    <font>basesmallyellow</font>
</textarea>

If you keep these simple practices in mind when creating your theme, it will be much simpler for both you and those you share the theme with to understand how it works.

Creating your first MythUI Theme File

Let's go through the creation of the most basic of all MythTV theme files to reinforce our understanding of terminology and basic XML.

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.

If you've been following along, congratulations, you've finished your first Myth theme element!

MythUI Widget Types

In this section, we'll explore the widgets that you can use in a MythUI theme, and explain how each of them works. You'll see an example of each widget in action, and a discussion of the possible attributes and how they work.

Global Attributes

Before discussing individual widgets, let's discuss attributes which will apply to almost all of the widgets we will use.

<area>

The most commonly used attribute of any widget is <area>. As the name implies, it sets the location and size of a widget. <area> takes four arguments. They are:
<area>posx,posy,width,height</area>
Myth coordinates are calculated from the upper left corner of the screen (position 0,0). In our themeinfo.xml file, we defined the <baseres> attribute, which defines the screen space we intend to work with. This does not mean that it will only work on this resolution! It simply tells MythTV how to reckon the coordinates. On a 1280x720 theme, 128 pixels is 10% of the screen. If one were to use the theme on a 1920x1080 screen, Myth is intelligent enough to still place the item 10% across the screen. In short, baseres establishes the relative coordinate system that you intend to use in your theme, not a fixed resolution at which is will operate. So, to create a widget 500 pixels right of the top left, 200 pixels down, and with a size of 300x100, we would use:
<area>500,200,300,100<area>

<position>

<position> is a lot like <area>, except it does not scale the widget. It looks like this:
<position>posx,posy</position>
Position might be used in a few circumstances. If you want to place an image on the screen, but leave it at native resolution, or if you want to place a widget on the screen, but use the size of the definition it inherits from, you might use position. Here's an example of the position tag placing a widget or image at location 650x400:
<position>650,400<position>

<alpha>

<alpha> is a very exciting effect that affects the transparency/opacity of a widget or image. It uses the following format:
<alpha>''number value 0-255''</alpha>
<alpha> sets the transparency from 0 (totally transparent) to 255 (totally solid). This allows for great and subtle see-through effects. If you don't set an alpha value, the widget or image will be 100% opaque. Here's an example of an item set to 50% opacity:
<alpha>128</alpha>

<alphapulse>

<alphapulse> is another exciting transparency/opacity effect that allows text or images to cycle through various levels of opacity. It uses the following format:
<alphapulse min="number value 0-255" max="number value 0-255"  change="number speed of cycling" />
You'll notice that alphapulse has a slightly different format than other XML or HTML-style tags. Since alphapulse takes multiple arguments, they're all built into the one tag, which indicates it has no paired tag by closing with "/>". Min is the minimum transparency value in the cycle. Max is the maximum transparency value in the cycle. Change sets the speed at which the cycling occurs. It is best to keep this value in single digits, or the pulse may become indistinguishable. Here is an example of a widget or image pulsing between half and full opacity with a slow, steady speed of change:
<pre><alphapulse min="128" max="255" change="2"/>

Required MythUI Theme Files

base.xml

The base.xml file is the first file loaded by your theme. The base.xml file is the core definitions for each widget in your theme. Here you will define popup menus, font names, progress bars, dropdown menus, and all the other basic widgets used in the Myth UI. The base.xml file is a fantastic place to put all the definitions you intend to use later, which you can then call by name.

Optional MythUI Theme Files