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!

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!

+

+

== Dependence ==

+

+

Some widgets, including textarea and imagetype, can use the depends clause to be shown only if another widget of the given name has content. For example:

+

+

<pre>

+

<textarea name="title" from="MyFirstTextArea" depends="coverart">

+

<area>100,200,300,50</area>

+

<font>MyFirstFontBlack</font>

+

</textarea>

+

</pre>

+

+

This widget will be shown only if the 'coverart' widget is currently displaying an image. If "coverart" is changed to "!coverart", the widget will only be shown if 'coverart' is not currently displaying an image. This allows for alternative use of space depending on the existence or absence of metadata such as images or text.

+

+

At present, a widget can depend on the following widget types: textarea, imagetype, progressbar, statetype.<br/>

+

The dependency is a logical expression allowing the operator & (AND) and | (OR). Expression is strictly evaluated from left to right. If the "dependee" widget doesn't exist it is assumed to not be visible.

Warning: as the & character isn't allowed in XML, it must be escaped using '''&amp;amp;''' instead

== Preassigned Names ==

== Preassigned Names ==

Line 185:

Line 211:

The above example would place a 300x100 item 10% across and 20% down the screen. Percentage may also be used to size an item, relative to its parent item (which can be the entire screen, the container size of a button, etc.).

The above example would place a 300x100 item 10% across and 20% down the screen. Percentage may also be used to size an item, relative to its parent item (which can be the entire screen, the container size of a button, etc.).

−

In the development branch (which will become 0.25) offsets can also be used:

+

You can also use offsets:

−

:<pre><area>20, 10, -20, -10</area</pre>

+

:<pre><area>20, 10, -20, -10</area></pre>

Would create an area that has a 20 pixel margin on the left and right, and a 10 pixel margin on the top and bottom. Negative numbers in the width / height fields indicate that a right / bottom margin of that size, is desired.

Would create an area that has a 20 pixel margin on the left and right, and a 10 pixel margin on the top and bottom. Negative numbers in the width / height fields indicate that a right / bottom margin of that size, is desired.

Line 210:

Line 236:

Percentage values can also be used with position.

Percentage values can also be used with position.

−

In the development branch (which will become 0.25) offsets can also combined with percentages:

+

You can also combine offsets with percentages:

:<pre><position>100%-20, 50%+20</position></pre>

:<pre><position>100%-20, 50%+20</position></pre>

Line 295:

Line 321:

{| cellpadding="4" border="1"

{| cellpadding="4" border="1"

| style="background:mediumslateblue" |face

| style="background:mediumslateblue" |face

−

|The font face is the plain English name of a font installed system-wide or whose TrueType font (.ttf), OpenType font (.otf), or TrueType font collection (.ttc) file is provided within the theme's directory structure. If the font license allows, distributing the font with your theme will ensure other users (even those without the font installed on their systems) use the proper font, so text size is correct and text items fit within the areas you've specified. And, it means users will not have to manually install fonts to their systems. To get more debugging info about which font files are being used run "mythfrontend -v gui,file".

+

|The font face is the plain English name of a font installed system-wide or whose TrueType font (.ttf), OpenType font (.otf), or TrueType font collection (.ttc) file is provided within the theme's directory structure. If the font license allows, distributing the font with your theme will ensure other users (even those without the font installed on their systems) use the proper font, so text size is correct and text items fit within the areas you've specified. And, it means users will not have to manually install fonts to their systems. To get more debugging info about which font files and faces are found within your theme directory run "mythfrontend -v gui,file" (on 0.24: mythfrontend -v "gui,file,extra", on trunk: mythfrontend -loglevel debug -v "gui,file"), and use the same name specified in the log output as the face name in your theme.

|-

|-

| style="background:mediumslateblue" |pixelsize

| style="background:mediumslateblue" |pixelsize

Line 358:

Line 384:

'''Note:''' Fonts must be installed on the system. If you include a non-standard font with your theme, your users will need to install it systemwide for it to be used in your theme. Myth will fall back to installed fonts if the font is not installed systemwide.

'''Note:''' Fonts must be installed on the system. If you include a non-standard font with your theme, your users will need to install it systemwide for it to be used in your theme. Myth will fall back to installed fonts if the font is not installed systemwide.

−

==The textarea widget==

+

== Animations ==

−

[[Image:Textarea.png|thumb|An example of a textarea.]]

+

'''Note''': This is available from version 0.25 and only when using the OpenGL painter.

−

The textarea widget is the simplest widget in MythUI. It will place a text area on the screen which can either be filled by the themer or (by using the name= tag) dynamically filled by MythTV. For purposes of simplicity, let's look at all the attributes which can be used in a textarea widget and then discuss each one.

+

<pre>

+

<window name="MythConfirmationDialog">

+

<area>-1,-1,706,298</area>

+

<animation trigger="AboutToShow">

+

<section>

+

<alpha start="0" end="255" easingcurve="OutQuart"/>

+

<zoom start="1000" end="100" easingcurve="OutQuart"/>

+

</section>

+

</animation>

+

...

+

</window>

+

</pre>

−

<pre>

+

{| cellpadding="4" border="1"

−

<textarea name="MyFirstTextArea">

+

|-

−

<area>x,y,w,h</area>

+

| style="background:mediumslateblue" |animation

−

<case>upper</case>

+

|

−

<font>MyFirstFontBlack</font>

+

Starting tag for a group of animations with a common trigger. It can take one attribute, ''trigger'', which dictates when the animation(s) should be started. Values are ''AboutToShow'', and ''AboutToHide'', which respectively occur when windows are shown and hidden. Default is ''AboutToShow''.

−

<cutdown>yes</cutdown>

−

<multiline>yes</multiline>

−

<align>left,top</align>

−

<colorcycle start="#000000" end="#ffffff" steps="255"/>

−

<value>I've created my first widget!</value>

+

|-

+

| style="background:mediumslateblue" |section

+

|

+

It can take two attributes, ''duration'', and ''centre''.

−

OR

+

''duration'' controls the length of the contained animations in milliseconds. Default is 500.

Possible children are ''alpha'', ''angle'', ''position'', ''zoom'', ''horizontalzoom'', and ''verticalzoom''.

−

<template>I have created %n widget(s)</template>

+

:<pre><section duration="500" centre="middle">...</section></pre>

−

</textarea>

+

|-

−

</pre>

+

| style="background:mediumslateblue" |duration

+

|

+

Specifies the duration of the animation in milliseconds. This will override any value specified in the ''section'' tag.

−

MythUI widgets are always opened with their widget type as the tag. So, we start our textarea widget and give it a name with <textarea name="MyFirstTextArea">. Let's look at each attribute.

+

|-

+

| style="background:mediumslateblue" |start

+

|

+

Specifies the start value of the animation. Default is 0 (or equivalent).

−

{| cellpadding="4" border="1"

−

| style="background:mediumslateblue" |area

−

|As explained above, this attribute sets the location and size of our text area. You could also use <position> if inheriting from another text area (by adding from="name ofothertextarea" to the textarea tag).

|-

|-

−

| style="background:mediumslateblue" |case

+

| style="background:mediumslateblue" |end

−

|This sets the capitalization of our text area. If not set, the text area will follow normal capitalization. Valid values are normal, upper,lower, capitaliseall (capitalize first letter of each word) and capitalisefirst (capitalize first letter of each sentence).

+

|

+

Specifies the end value of the animation. Default is 0 (or equivalent).

+

|-

|-

−

| style="background:mediumslateblue" |font

+

| style="background:mediumslateblue" |easingcurve

−

|A font name as defined earlier in the same UI file or in base.xml. In our example, we are using MyFirstFontBlack which we discussed defining earlier.

See [http://harmattan-dev.nokia.com/docs/library/html/qt4/qeasingcurve.html#Type-enum] for an overview of what each value means.

+

|-

|-

−

| style="background:mediumslateblue" |cutdown

+

| style="background:mediumslateblue" |reversible

−

|If the textarea runs over the defined area, the cutdown attribute will truncate it with ellipsis, "...". If you are concerned that a value inserted by myth will be too long for the text area you have assigned, you may want to set cutdown to "yes". Default behavior is to not cut down text.

+

|

+

Boolean attribute that specifies if the animation should repeatedly go back and forth between the start and end values. Default is ''false''.

+

|-

|-

−

| style="background:mediumslateblue" |multiline

+

| style="background:mediumslateblue" |looped

−

|The multiline attribute wraps text onto a new line if it runs out of space.

+

|

+

Boolean attribute that specifies if the animation should start again from the beginning once it has reached the end value. Default is ''false''.

|An attribute very like alphapulse, except the cycle is between colors instead of opacities. Colors in MythTV are always in hexadecimal format. The above example will cycle between white and black, with 255 steps in between. The cycling occurs at approximately 30 steps per second. Thus, our example will complete in just under eight seconds.

+

|

+

Controls the rotation (in degrees) of the widget. It uses the following format:

|Value is the attribute which sets the text to appear in the textarea. It is optional. In a text area which Myth is not filling in, it can be any text you wish to set. In a Myth-filled box, it will be the "fallback" value. If myth has no text to insert, the user will see this value instead. In a few instances, various variables can be inserted for the value to allow for compound text areas which include multiple pieces of information in a format of the themer's choosing, like %TITLE%, %SUBTITLE%, %DATE%, %STARS%, etc.

+

|

−

|-

+

Controls the position of the widget. It uses the following format:

−

| style="background:mediumslateblue" |template

+

−

|Template is preferable to using the <value> element when displaying variables. When a screen is loaded, the value element is displayed first, then replaced with template when the variable data is available. This can be values which exist in a map (such as most Program Info like %TITLE%, %SUBTITLE%, etc) but it can also be any named text area where you wish to put the inserted value in a textual context, such as prefacing the value with a label. Example:

+

:<pre><position start="posx,posy" end="posx,posy" /></pre>

−

<pre>

−

<template>Title: %1</template>

−

</pre>

−

When text is being inserted %1 should be used as the placeholder.

−

Any numerical insertion should use %n to take advantage of number/plural translation capabilities in Myth.

+

Specifying -1 for a coordinate will use the corresponding value from the widget's position. The following will for example move the widget from 100,100 to 400,400:

−

<pre>

−

<template>%n item(s)</template>

−

</pre>

−

Would display (1 item, or 3 items) when translated.

−

|}

−

==The imagetype widget==

+

<dl><dd><pre>

−

[[Image:Imagetype.png|thumb|An example of a imagetype (with a mask, and another imagetype overlaid).]]

+

<area>100,100,200,200</area>

+

<animation trigger="AboutToShow">

+

<section>

+

<position start="-1,-1" end="400,400" />

+

</section>

+

</animation>

+

</pre></dl>

−

The imagetype widget is another very simple widget. It takes a filename as input, applies masks, crops, and other manipulations, and displays it on the screen. Just as with the textarea widget, certain hardcoded name values on certain screens can be dynamically filled by MythTV.

+

|-

+

| style="background:mediumslateblue" |zoom

+

|

+

Controls the zoom attribute (in percent) of the widget. It uses the following format:

−

<pre>

+

:<pre><zoom start="integer value" end="integer value" /></pre>

−

<imagetype name="MyFirstImage">

−

<filename>imagefile.png</filename>

−

<area>300,200,210,70>

−

<alpha>150</alpha>

−

<preserveaspect>true</preserveaspect>

−

<crop>x,y,w,h</crop>

−

<mask>mymaskfile.png</mask>

−

<reflection axis="horizontal" shear="24" scale="85" length="35" />

−

<grayscale>true</grayscale>

−

<!-- Animation attributes (used instead of filename or gradient)-->

+

|-

+

| style="background:mediumslateblue" |horizontalzoom

+

|

+

Like ''zoom'' but only applies a horizontal zoom. It can be combined with ''verticalzoom''. It uses the following format:

An imagetype widget must have (one of) a filename, filepattern, or gradient. All the other attributes are optional. An imagetype will also take all global attributes such as area, position, alpha, and alphapulse.

+

|-

+

| style="background:mediumslateblue" |verticalzoom

+

|

+

Like ''zoom'' but only applies a vertical zoom. It can be combined with ''horizontalzoom''. It uses the following format:

|The filename attribute sets a filename for the image relative to the root of the theme directory. You can place an image in a subdirectory and include it in the filename value, like:

−

:<pre><filename>path/to/filename.png</filename></pre>

+

==The textarea widget==

+

[[Image:Textarea.png|thumb|An example of a textarea.]]

−

As with the textarea widget, if the imagetype is dynamically filled by MythTV and there is a filename set, the file will be the "fallback" when Myth has no value to insert.

+

The textarea widget is the simplest widget in MythUI. It will place a text area on the screen which can either be filled by the themer or (by using the name= tag) dynamically filled by MythTV. For purposes of simplicity, let's look at all the attributes which can be used in a textarea widget and then discuss each one.

−

The filename attribute can *also* be a directory name (which must end in "/"). This will select and display a random image from the directory. The directory can be relative to the theme directory or absolute path.

+

<pre>

−

|-

+

<textarea name="MyFirstTextArea">

−

| style="background:mediumslateblue" |preserveaspect

+

<area>x,y,w,h</area>

−

|preserveaspect will scale the image to the size specified, but will retain the original aspect ratio by leaving empty space within the defined area. This option is excellent for posters with variable sizes and aspects, or places where both a screenshot or fixed image might appear.

+

<case>upper</case>

−

|-

+

<font>MyFirstFontBlack</font>

−

| style="background:mediumslateblue" |crop

+

<cutdown>yes</cutdown>

−

|A crop, as evidenced by the name, crops the image to the specified x/y value, width, and height. This is useful for preview images which might have closed-captioning garbage.

+

<scroll direction="left" />

−

|-

+

<multiline>yes</multiline>

−

| style="background:mediumslateblue" |mask

+

<align>left,top</align>

−

|mask allows a second image to be set to alpha-mask the original. This is a black and transparent image of identical size to the imagetype area, where black is visible and transparent will be masked. This allows for smooth edges and exotic shapes to your image. Masks cannot be resized or scaled. NOTE: If the filename of the image is used elsewhere in unmasked form (or possibly with a different mask), the mask may be ignored.

+

<colorcycle start="#000000" end="#ffffff" steps="255"/>

−

|-

−

| style="background:mediumslateblue" |reflection

−

|reflection is an attribute which casts a reflection of the imagetype along either the horizontal or vertical axis. Valid values for axis are ''horizontal'' and ''vertical''. Shear is the angle of the reflection as a percentage value, from 0-100. Scale is the severity ("squishedness") of the reflection as a percentage value, from 0-100. Length is the size of the draw reflection compared to the size of the original image as a percentage value, from 0-100.

−

|-

−

| style="background:mediumslateblue" |grayscale

−

|grayscale determines whether a colour image should be displayed as grayscale instead.

−

|-

−

| style="background:mediumslateblue" |filepattern

−

|filepattern allows for simple flipbook animations. The low and high values define the first and last image numbers in a the series, and the "%1" in the filename is the place where the number variable is inserted. So, for a flipbook animation that cycles from myfile1.png to myfile99.png, the filepattern would look like:

−

:<pre><filepattern low="1" high="99">myfile%1.png</filepattern></pre>

+

<value>I've created my first widget!</value>

+

+

OR

+

+

<template>I have created my own %1!</template>

+

+

OR

−

Animations typically restart from the beginning when they've reached the end. An animation may also be cycled forward, then reversed when it reaches the end by adding ''cycle="reverse"'' to the attributes. e.g. 1-2-3-2-1 This may reduces the overall number of frames required and save memory.

+

<template>I have created %n widget(s)</template>

−

|-

−

| style="background:mediumslateblue" |delay

−

|delay is the time interval between cels in your flipbook animation. It is an integer value and defines the speed at which the animation is cycled.

−

|}

−

==The statetype widget==

+

</textarea>

+

</pre>

−

The statetype widget is a special widget used for an image, button, or other element that behaves or looks differently according to its status. An example of a statetype would be a button item which can be either selected or unselected. Statetypes are also used in menu watermark images (discussed in the menu-ui.xml article). The most important new attribute introduced in the statetype is a ''state''. Each state represents how a statetype behaves under a given condition.

+

MythUI widgets are always opened with their widget type as the tag. So, we start our textarea widget and give it a name with <textarea name="MyFirstTextArea">. Let's look at each attribute.

−

<pre>

+

{| cellpadding="4" border="1"

−

<statetype name="blah">

+

| style="background:mediumslateblue" |area

−

<area>10,10,100,100</area>

+

|As explained above, this attribute sets the location and size of our text area. You could also use <position> if inheriting from another text area (by adding from="name ofothertextarea" to the textarea tag).

−

<showempty>yes</showempty>

+

|-

−

<state name="selected">

+

| style="background:mediumslateblue" |case

−

<position>20,15</position>

+

|This sets the capitalization of our text area. If not set, the text area will follow normal capitalization. Valid values are normal, upper,lower, capitaliseall (capitalize first letter of each word) and capitalisefirst (capitalize first letter of each sentence).

−

<imagetype name="selectimage">

+

|-

−

<filename>selectimage.png</filename>

+

| style="background:mediumslateblue" |font

−

</imagetype>

+

|A font name as defined earlier in the same UI file or in base.xml. In our example, we are using MyFirstFontBlack which we discussed defining earlier.

−

</state>

−

<state name="normal">

−

<imagetype name="normalimage">

−

<filename>normalimage.png</filename>

−

</imagetype>

−

</state>

−

</statetype>

−

</pre>

−

−

{| cellpadding="4" border="1"

−

| style="background:mediumslateblue" |state

−

|The state attribute defines the behavior of a single state in the statetype (which is a collection of states). Instead of ''name'', some states use the ''type'' attribute. The names are unique depending on the context of the statetype. Commonly used state names are ''selected'', ''unselected'', ''active'', and ''inactive''. ''Type'' will always be ''on'', ''off'', ''half'', or ''full''. Which types are used depends on the context of the statetype. In the example, if the item were selected, the "selectimage.png" image would be displayed. If it were unselected, the "normalimage.png" image would be displayed. This is the simplest example of a statetype, but each state can has its own position, images, text, and virtually anything you can imagine!

|-

|-

−

| style="background:mediumslateblue" |showempty

+

| style="background:mediumslateblue" |cutdown

−

|The showempty attribute specifies that any empty state should still be displayed (as empty).

+

|If the textarea runs over the defined area, the cutdown attribute will truncate it with ellipsis, "...". If you are concerned that a value inserted by myth will be too long for the text area you have assigned, you may want to set cutdown to "yes". Default behavior is to not cut down text. In pre-0.25, cutdown can optionally take "left", "middle" and "right" as options, which indicate where the ellipsis should be applied. "yes" is equivalent to "right". If multiline is true, any cutdown will always be on the right.

−

|}

+

|-

−

+

| style="background:mediumslateblue" |multiline

−

==The button widget==

+

|The multiline attribute wraps text onto a new line if it runs out of space.

−

[[Image:Button.png|thumb|An example of a button (which is also an example of a statetype).]]

|An attribute very like alphapulse, except the cycle is between colors instead of opacities. Colors in MythTV are always in hexadecimal format. The above example will cycle between white and black, with 255 steps in between. The cycling occurs at approximately 30 steps per second. Thus, our example will complete in just under eight seconds.

+

|-

+

| style="background:mediumslateblue" |scroll

+

|If the "text" is to large for the specified area, starting with 0.25, it can be set to scroll within the area.

+

<pre>

+

<scroll direction="left" />

+

<scroll direction="right" />

+

<scroll direction="up" />

+

<scroll direction="down" />

+

<scroll direction="horizontal" />

+

<scroll direction="vertical" />

+

</pre>

+

The "horizontal" and "vertical" options will cause the text to bounce back and forth within the area.

+

Starting with 0.27, attributes are available to control the scroll rate and the delay before scrolling starts:

The 'rate' is in pixels per second, with a default of 70. The 'delay' is in seconds, with a default of 3.

−

<state name="active">

+

returnrate and returndelay are only applicable to direction="vertical" and direction="horizontal".

−

<imagetype name="background">

+

|-

−

<area>0,0,150,35</area>

+

| style="background:mediumslateblue" |value

−

<filename>buttonbackground.png</filename>

+

|Value is the attribute which sets the text to appear in the textarea. It is optional. In a text area which Myth is not filling in, it can be any text you wish to set. In a Myth-filled box, it will be the "fallback" value. If myth has no text to insert, the user will see this value instead. In a few instances, various variables can be inserted for the value to allow for compound text areas which include multiple pieces of information in a format of the themer's choosing, like %TITLE%, %SUBTITLE%, %DATE%, %STARS%, etc.

−

</imagetype>

+

|-

−

<textarea name="text">

+

| style="background:mediumslateblue" |template

−

<area>5,5,140,30</area>

+

|Template is preferable to using the <value> element when displaying variables. When a screen is loaded, the value element is displayed first, then replaced with template when the variable data is available. This can be values which exist in a map (such as most Program Info like %TITLE%, %SUBTITLE%, etc) but it can also be any named text area where you wish to put the inserted value in a textual context, such as prefacing the value with a label. Example:

−

<align>allcenter</align>

+

<pre>

−

<font>basemedium</font>

+

<template>Title: %1</template>

−

<font state="selected">basemedium</font>

+

</pre>

−

<font state="disabled">basemediumgrey</font>

+

When text is being inserted %1 should be used as the placeholder.

−

</textarea>

+

−

</state>

+

Any numerical insertion should use %n to take advantage of number/plural translation capabilities in Myth.

−

<state name="selected" from="active">

+

<pre>

−

<imagetype name="background">

+

<template>%n item(s)</template>

−

<area>0,0,150,35</area>

+

</pre>

−

<filename>buttonbackground_selected.png</filename>

+

Would display (1 item, or 3 items) when translated.

−

<alphapulse min="200" max="255" change="1"/>

+

|}

−

</imagetype>

+

−

</state>

+

==The imagetype widget==

−

<state name="disabled" from="active" />

+

[[Image:Imagetype.png|thumb|An example of a imagetype (with a mask, and another imagetype overlaid).]]

−

<state name="pushed" from="active">

−

<imagetype name="background">

−

<area>0,0,150,35</area>

−

<filename>buttonbackground.png</filename>

−

<alpha>255</alpha>

−

</imagetype>

−

<textarea name="text">

−

<position>8,8</position>

−

</textarea>

−

</state>

−

</statetype>

−

</button>

−

</pre>

−

After all of that text, there is absolutely nothing new about a button! No special attributes, no new material. The button widget contains a single '''statetype''', ''buttonstate''. The '''statetype''' contains four '''states''', ''active'', ''selected'', ''disabled'', and ''pushed''. ''active'' is a unselected, active button. ''selected'' is a selected, active button. ''disabled'' is an unselected or a "greyed out" button. ''pushed'' is the "down/pushed in" state of a button (mid-push). Each state must contain (or inherit) the '''textarea''' ''text''.

+

The imagetype widget is another very simple widget. It takes a filename as input, applies masks, crops, and other manipulations, and displays it on the screen. Just as with the textarea widget, certain hardcoded name values on certain screens can be dynamically filled by MythTV.

−

You may notice above the use of inheritance and the use of states in a font declaration. These font states carry over into the following state attributes and change the fonts of each type accordingly.

An imagetype widget must have (one of) a filename or filepattern. All the other attributes are optional. An imagetype will also take all global attributes such as area, position, alpha, and alphapulse.

−

<center>

−

====button statetypes====

{| cellpadding="4" border="1"

{| cellpadding="4" border="1"

−

| <b>Statetype Name</b>

+

| style="background:mediumslateblue" |filename

−

| <b>Included States</b>

+

|The filename attribute sets a filename for the image relative to the root of the theme directory. You can place an image in a subdirectory and include it in the filename value, like:

−

| <b>Optional named attributes:</b>

+

−

|-

+

:<pre><filename>path/to/filename.png</filename></pre>

−

| style="background:silver" | buttonstate

+

−

| style="background:silver" align="center" | active

+

As with the textarea widget, if the imagetype is dynamically filled by MythTV and there is a filename set, the file will be the "fallback" when Myth has no value to insert.

−

| style="background:silver" | '''textarea''' - ''text''

−

|-

−

| style="background:silver" |

−

| style="background:silver" align="center" | selected

−

| style="background:silver" | '''textarea''' - ''text''

−

|-

−

| style="background:silver" |

−

| style="background:silver" align="center" | disabled

−

| style="background:silver" | '''textarea''' - ''text''

−

|-

−

| style="background:silver" |

−

| style="background:silver" align="center" | pushed

−

| style="background:silver" | '''textarea''' - ''text''

−

|}

−

</center>

−

==The buttonlist widget==

+

The filename attribute can *also* be a directory name (which must end in "/"). This will select and display a random image from the directory. The directory can be relative to the theme directory or absolute path.

−

[[Image:Buttonlist.png|thumb|An example of a buttonlist.]]

+

|-

−

+

| style="background:mediumslateblue" |preserveaspect

−

The buttonlist widget is a series of dynamically-filled buttons. It is one of the most commonly used of all widgets, and is primarily built out of other widgets.

+

|preserveaspect will scale the image to the size specified, but will retain the original aspect ratio by leaving empty space within the defined area. This option is excellent for posters with variable sizes and aspects, or places where both a screenshot or fixed image might appear.

+

|-

+

| style="background:mediumslateblue" |crop

+

|A crop, as evidenced by the name, crops the image to the specified x/y value, width, and height. This is useful for preview images which might have closed-captioning garbage.

+

|-

+

| style="background:mediumslateblue" |mask

+

|mask allows a second image to be set to alpha-mask the original. This is a black and transparent image of identical size to the imagetype area, where black is visible and transparent will be masked. This allows for smooth edges and exotic shapes to your image. Masks cannot be resized or scaled. NOTE: If the filename of the image is used elsewhere in unmasked form (or possibly with a different mask), the mask may be ignored.

+

|-

+

| style="background:mediumslateblue" |reflection

+

|reflection is an attribute which casts a reflection of the imagetype along either the horizontal or vertical axis. Valid values for axis are ''horizontal'' and ''vertical''. Shear is the angle of the reflection as a percentage value, from 0-100. Scale is the severity ("squishedness") of the reflection as a percentage value, from 0-100. Length is the size of the draw reflection compared to the size of the original image as a percentage value, from 0-100. Spacing is the distance of the reflection from the axis of the reflection, which can be used to give the impression that the object is above the surface upon which the object is reflected.

+

|-

+

| style="background:mediumslateblue" |grayscale

+

|grayscale determines whether a colour image should be displayed as grayscale instead.

+

|-

+

| style="background:mediumslateblue" |filepattern

+

|filepattern allows for simple flipbook animations. The low and high values define the first and last image numbers in a the series, and the "%1" in the filename is the place where the number variable is inserted. So, for a flipbook animation that cycles from myfile1.png to myfile99.png, the filepattern would look like:

+

+

:<pre><filepattern low="1" high="99">myfile%1.png</filepattern></pre>

+

+

Animations typically restart from the beginning when they've reached the end. An animation may also be cycled forward, then reversed when it reaches the end by adding ''cycle="reverse"'' to the attributes. e.g. 1-2-3-2-1 This may reduces the overall number of frames required and save memory.

+

|-

+

| style="background:mediumslateblue" |delay

+

|delay is the time interval in milliseconds between cels in your flipbook animation. It is an integer value and defines the speed at which the animation is cycled.

+

|}

+

+

==The statetype widget==

+

+

The statetype widget is a special widget used for an image, button, or other element that behaves or looks differently according to its status. An example of a statetype would be a button item which can be either selected or unselected. Statetypes are also used in menu watermark images (discussed in the menu-ui.xml article). The most important new attribute introduced in the statetype is a ''state''. Each state represents how a statetype behaves under a given condition.

<pre>

<pre>

−

<buttonlist name="MyFirstButtonlist">

+

<statetype name="blah">

−

<area>0,0,349,250</area>

+

<area>10,10,100,100</area>

−

<layout>vertical</layout>

+

<showempty>yes</showempty>

−

<spacing>3</spacing>

+

<state name="selected">

−

<arrange>stack</arrange>

+

<position>20,15</position>

−

<align>center</align>

+

<imagetype name="selectimage">

−

<scrollstyle>free</scrollstyle>

+

<filename>selectimage.png</filename>

−

<wrapstyle>items</wrapstyle>

+

</imagetype>

−

<buttonarea>0,0,100%,97%</buttonarea>

+

</state>

−

<statetype name="buttonitem">

+

<state name="normal">

−

<state name="selectedinactive">

+

<imagetype name="normalimage">

−

<area>0,0,100%,30</area>

+

<filename>normalimage.png</filename>

−

<imagetype name="buttonbackground">

+

</imagetype>

−

<filename>buttonbackground.png</filename>

+

</state>

+

</statetype>

+

</pre>

+

+

{| cellpadding="4" border="1"

+

| style="background:mediumslateblue" |state

+

|The state attribute defines the behavior of a single state in the statetype (which is a collection of states). Instead of ''name'', some states use the ''type'' attribute. The names are unique depending on the context of the statetype. Commonly used state names are ''selected'', ''unselected'', ''active'', and ''inactive''. ''Type'' will always be ''on'', ''off'', ''half'', or ''full''. Which types are used depends on the context of the statetype. In the example, if the item were selected, the "selectimage.png" image would be displayed. If it were unselected, the "normalimage.png" image would be displayed. This is the simplest example of a statetype, but each state can have its own position, images, text, and virtually anything you can imagine!

+

|-

+

| style="background:mediumslateblue" |showempty

+

|The showempty attribute specifies that any empty state should still be displayed (as empty).

+

|}

+

+

==The button widget==

+

[[Image:Button.png|thumb|An example of a button (which is also an example of a statetype).]]

+

+

The button widget is the definition of an individual button item.

+

+

<pre>

+

<button name="MyFirstButton">

+

<position>0,0</position>

+

<statetype name="buttonstate">

+

<state name="active">

+

<imagetype name="background">

+

<area>0,0,150,35</area>

+

<filename>buttonbackground.png</filename>

</imagetype>

</imagetype>

−

<textarea name="buttontext">

+

<textarea name="text">

−

<area>5,10,85%,30</area>

+

<area>5,5,140,30</area>

−

<font>basesmall</font>

+

<align>allcenter</align>

−

<cutdown>yes</cutdown>

+

<font>basemedium</font>

−

<align>left,vcenter</align>

+

<font state="selected">basemedium</font>

+

<font state="disabled">basemediumgrey</font>

</textarea>

</textarea>

−

<statetype name="buttoncheck">

+

</state>

−

<position>91%,5</position>

+

<state name="selected" from="active">

−

<state type="off">

+

<imagetype name="background">

−

<imagetype name="checkoff">

+

<area>0,0,150,35</area>

−

<filename>lb-check-empty.png</filename>

+

<filename>buttonbackground_selected.png</filename>

−

</imagetype>

+

<alphapulse min="200" max="255" change="1"/>

−

</state>

+

</imagetype>

−

<state type="half">

+

</state>

−

<imagetype name="checkhalf">

+

<state name="disabled" from="active" />

−

<filename>lb-check-half.png</filename>

+

<state name="pushed" from="active">

−

</imagetype>

+

<imagetype name="background">

−

</state>

+

<area>0,0,150,35</area>

−

<state type="full">

+

<filename>buttonbackground.png</filename>

−

<imagetype name="checkfull">

+

<alpha>255</alpha>

−

<filename>lb-check-full.png</filename>

−

</imagetype>

−

</state>

−

</statetype>

−

<imagetype name="buttonarrow">

−

<position>92%,11</position>

−

<filename>rightarrow.png</filename>

</imagetype>

</imagetype>

+

<textarea name="text">

+

<position>8,8</position>

+

</textarea>

</state>

</state>

−

<state name="selectedactive" from="selectedinactive">

+

</statetype>

−

<imagetype name="buttonbackground">

+

</button>

−

<filename>buttonbackground_selected.png</filename>

+

</pre>

−

<alphapulse min="200" max="255" change="1"/>

+

−

</imagetype>

+

After all of that text, there is absolutely nothing new about a button! No special attributes, no new material. The button widget contains a single '''statetype''', ''buttonstate''. The '''statetype''' contains four '''states''', ''active'', ''selected'', ''disabled'', and ''pushed''. ''active'' is a unselected, active button. ''selected'' is a selected, active button. ''disabled'' is an unselected or a "greyed out" button. ''pushed'' is the "down/pushed in" state of a button (mid-push). Each state must contain (or inherit) the '''textarea''' ''text''.

−

</state>

+

−

<state name="inactive" from="selectedactive">

+

You may notice above the use of inheritance and the use of states in a font declaration. These font states carry over into the following state attributes and change the fonts of each type accordingly.

−

<imagetype name="buttonbackground">

+

−

<filename>buttonbackground_selected.png</filename>

+

<center>

−

<alpha>127</alpha>

+

====button statetypes====

−

</imagetype>

+

{| cellpadding="4" border="1"

−

<textarea name="buttontext">

+

| <b>Statetype Name</b>

−

<font>basesmallgrey</font>

+

| <b>Included States</b>

−

</textarea>

+

| <b>Optional named attributes:</b>

−

</state>

+

|-

−

<state name="active" from="inactive">

+

| style="background:silver" | buttonstate

−

<imagetype name="buttonbackground">

+

| style="background:silver" align="center" | active

−

<filename>buttonbackground_selected.png</filename>

+

| style="background:silver" | '''textarea''' - ''text''

−

<alpha>200</alpha>

+

|-

−

</imagetype>

+

| style="background:silver" |

−

<textarea name="buttontext">

+

| style="background:silver" align="center" | selected

−

<font>basesmall</font>

+

| style="background:silver" | '''textarea''' - ''text''

−

</textarea>

+

|-

−

</state>

+

| style="background:silver" |

−

</statetype>

+

| style="background:silver" align="center" | disabled

−

<statetype name="upscrollarrow">

+

| style="background:silver" | '''textarea''' - ''text''

−

<position>10,97%</position>

+

|-

−

<state type="off">

+

| style="background:silver" |

−

<imagetype name="upon">

+

| style="background:silver" align="center" | pushed

−

<filename>uparrow.png</filename>

+

| style="background:silver" | '''textarea''' - ''text''

−

<alpha>90</alpha>

+

|}

+

</center>

+

+

==The buttonlist widget==

+

[[Image:Buttonlist.png|thumb|An example of a buttonlist.]]

+

+

The buttonlist widget is a series of dynamically-filled buttons. It is one of the most commonly used of all widgets, and is primarily built out of other widgets.

+

+

<pre>

+

<buttonlist name="MyFirstButtonlist">

+

<area>0,0,349,250</area>

+

<layout>vertical</layout>

+

<spacing>3</spacing>

+

<arrange>stack</arrange>

+

<align>center</align>

+

<scrollstyle>free</scrollstyle>

+

<wrapstyle>items</wrapstyle>

+

<buttonarea>0,0,100%,97%</buttonarea>

+

<statetype name="buttonitem">

+

<state name="selectedinactive">

+

<area>0,0,100%,30</area>

+

<imagetype name="buttonbackground">

+

<filename>buttonbackground.png</filename>

</imagetype>

</imagetype>

−

</state>

+

<textarea name="buttontext">

−

<state type="full">

+

<area>5,10,85%,30</area>

−

<imagetype name="upoff">

+

<font>basesmall</font>

−

<filename>uparrow.png</filename>

+

<cutdown>yes</cutdown>

−

</imagetype>

+

<align>left,vcenter</align>

−

</state>

+

</textarea>

−

</statetype>

+

<statetype name="buttoncheck">

−

<statetype name="downscrollarrow">

+

<position>91%,5</position>

−

<position>40,97%</position>

+

<state type="off">

−

<state type="off">

+

<imagetype name="checkoff">

−

<imagetype name="dnon">

+

<filename>lb-check-empty.png</filename>

−

<filename>downarrow.png</filename>

+

</imagetype>

−

<alpha>90</alpha>

+

</state>

+

<state type="half">

+

<imagetype name="checkhalf">

+

<filename>lb-check-half.png</filename>

+

</imagetype>

+

</state>

+

<state type="full">

+

<imagetype name="checkfull">

+

<filename>lb-check-full.png</filename>

+

</imagetype>

+

</state>

+

</statetype>

+

<imagetype name="buttonarrow">

+

<position>92%,11</position>

+

<filename>rightarrow.png</filename>

</imagetype>

</imagetype>

</state>

</state>

−

<state type="full">

+

<state name="selectedactive" from="selectedinactive">

−

<imagetype name="dnoff">

+

<imagetype name="buttonbackground">

−

<filename>downarrow.png</filename>

+

<filename>buttonbackground_selected.png</filename>

+

<alphapulse min="200" max="255" change="1"/>

</imagetype>

</imagetype>

</state>

</state>

−

</statetype>

+

<state name="inactive" from="selectedactive">

−

</buttonlist>

+

<imagetype name="buttonbackground">

−

</pre>

+

<filename>buttonbackground_selected.png</filename>

−

+

<alpha>127</alpha>

−

A buttonlist is an extremely commonly used widget. It is a series of buttons which are dynamically filled depending on their context. It is also one of the most complicated widget structures in MythUI. A buttonlist widget contains the following structure, which is largely self-explanatory. The ''checkoff'', ''checkhalf'', and ''checkfull'' '''states''' pertain to those buttons which contain checkboxes (like in the MythMusic playlist).

+

</imagetype>

−

+

<textarea name="buttontext">

−

{| cellpadding="4" border="1"

+

<font>basesmallgrey</font>

−

| style="background:mediumslateblue" |layout

+

</textarea>

−

|Valid values for ''layout'' in a '''buttonlist''' are ''horizontal'', ''vertical'', and ''grid''. The default is ''horizontal''.

+

</state>

−

|-

+

<state name="active" from="inactive">

−

| style="background:mediumslateblue" |spacing

+

<imagetype name="buttonbackground">

−

|Spacing is an attribute to set a pixel value to reserve between each button in a button list.

+

<filename>buttonbackground_selected.png</filename>

−

|-

+

<alpha>200</alpha>

−

| style="background:mediumslateblue" |scrollstyle

+

</imagetype>

−

|Scrollstyle sets the scrolling behavior of the buttonlist. Valid options are ''center'' (selected item is always in the center) and ''free'' (selector freely moves through the list). The default is ''free''.

+

<textarea name="buttontext">

−

|-

+

<font>basesmall</font>

−

| style="background:mediumslateblue" |wrapstyle

+

</textarea>

−

|Wrapstyle sets the wrapping behavior of the buttonlist. Valid options are ''items'' (The list itself wraps at the ends), ''selection'' (the selector reaches the end of the list and "jumps" to the beginning), ''captive'' (same as none but prevent the buttonlist losing focus when attempting to move beyond the edge), and ''none'' (no wrap). The default is ''none''.

+

</state>

−

|-

+

</statetype>

−

| style="background:mediumslateblue" |buttonarea

+

<statetype name="upscrollarrow">

−

|Exactly the same arguments as a normal <area> tag, the buttonarea allows one to specify the portion of the buttonlist which is taken up by the buttons themselves, allowing one to make room for the up/down arrows as necessary.

+

<position>10,97%</position>

−

|-

+

<state type="off">

−

| style="background:mediumslateblue" |drawfrombottom

+

<imagetype name="upon">

−

|Place the buttons at the bottom of the buttonarea instead of the top. Accepts normal boolean values.

+

<filename>uparrow.png</filename>

−

|-

+

<alpha>90</alpha>

−

| style="background:mediumslateblue" |arrange

+

</imagetype>

−

| Button arrangement type.

+

</state>

−

{|border="1"

+

<state type="full">

−

|Fixed (default) - Use the fixed position layout engine.

+

<imagetype name="upoff">

−

|-

+

<filename>uparrow.png</filename>

−

|Stack - Stack buttons next to each other. Buttons will be <spacing> apart from each other.

+

</imagetype>

−

|-

+

</state>

−

|Fill - Buttons will be distributed over the entire <buttonarea>. The spacing between buttons may be different on either side of the selected button, if <scrollstyle> center is specified.

+

</statetype>

−

|-

+

<statetype name="downscrollarrow">

−

|Spread - Spread out the buttons as much as possible, while keeping the spacing between buttons consistent.

+

<position>40,97%</position>

−

|}

+

<state type="off">

+

<imagetype name="dnon">

+

<filename>downarrow.png</filename>

+

<alpha>90</alpha>

+

</imagetype>

+

</state>

+

<state type="full">

+

<imagetype name="dnoff">

+

<filename>downarrow.png</filename>

+

</imagetype>

+

</state>

+

</statetype>

+

</buttonlist>

+

</pre>

+

+

A buttonlist is an extremely commonly used widget. It is a series of buttons which are dynamically filled depending on their context. It is also one of the most complicated widget structures in MythUI. A buttonlist widget contains the following structure, which is largely self-explanatory. The ''checkoff'', ''checkhalf'', and ''checkfull'' '''states''' pertain to those buttons which contain checkboxes (like in the MythMusic playlist).

+

+

{| cellpadding="4" border="1"

+

| style="background:mediumslateblue" | layout

+

|Valid values for ''layout'' in a '''buttonlist''' are ''horizontal'', ''vertical'', and ''grid''. The default is ''horizontal''.

|Spacing is an attribute to set a pixel value to reserve between each button in a button list.

|-

|-

| style="background:mediumslateblue" | scrollstyle

| style="background:mediumslateblue" | scrollstyle

−

| |Sets the scrolling behavior of the buttonlist. Valid options are center (selected item is always in the center), groupcenter (selected item is allowed to float in the center of the group, so the group as a whole can stay centered) and free (selector freely moves through the list). groupcenter is only valid with <arrange>Stack, Fill '''or''' Spread</arrange>.

+

|Sets the scrolling behavior of the buttonlist. Valid options are:

+

{|border="1"

+

| center - Selected item is always in the center.

+

|-

+

| groupcenter - Selected item is allowed to float in the center of the group, so the group as a whole can stay centered. Valid only with <arrange>Stack, Fill '''or''' Spread</arrange>.

+

|-

+

| free - Selector moves freely through the list. With <arrange>Fixed</arrange>, the selector moves freely through the entire list. With <arrange>Stack, Fill '''or''' Spread</arrange>, selector moves freely only when the entire list fits on the screen or when the selector is near the beginning or the end of the list; otherwise, the selected item is always in the center.

+

|}

+

|-

+

| style="background:mediumslateblue" | wrapstyle

+

|Wrapstyle sets the wrapping behavior of the buttonlist. Valid options are ''items'' (The list itself wraps at the ends), ''selection'' (the selector reaches the end of the list and "jumps" to the beginning), ''captive'' (same as none but prevent the buttonlist losing focus when attempting to move beyond the edge), ''flowing'' (the selector will wrap from one line to the next in a grid layout), and ''none'' (no wrap). The default is ''none''.

+

|-

+

| style="background:mediumslateblue" | buttonarea

+

|Exactly the same arguments as a normal <area> tag, the buttonarea allows one to specify the portion of the buttonlist which is taken up by the buttons themselves, allowing one to make room for the up/down arrows as necessary.

+

|-

+

| style="background:mediumslateblue" | drawfrombottom

+

|Place the buttons at the bottom of the buttonarea instead of the top. Accepts normal boolean values.

+

|-

+

| style="background:mediumslateblue" | arrange

+

| Button arrangement type.

+

{|border="1"

+

|Fixed (default) - Use the fixed position layout engine.

+

|-

+

|Stack - Stack buttons next to each other. Buttons will be <spacing> apart from each other.

+

|-

+

|Fill - Buttons will be distributed over the entire <buttonarea>. The spacing between buttons may be different on either side of the selected button, if <scrollstyle> center is specified.

+

|-

+

|Spread - Spread out the buttons as much as possible, while keeping the spacing between buttons consistent.

|The browserarea attribute specifies the area to use for the webpage which may be different than the area if scrollbars are present.

+

|-

| style="background:mediumslateblue" |url

| style="background:mediumslateblue" |url

|The url attribute specifies the web address to open in the widget.

|The url attribute specifies the web address to open in the widget.

Line 1,147:

Line 1,328:

| style="background:mediumslateblue" |zoom

| style="background:mediumslateblue" |zoom

|The zoom attribute magnifies the page in the widget. 1.0 is the default, non-zoomed value.

|The zoom attribute magnifies the page in the widget. 1.0 is the default, non-zoomed value.

+

|-

+

| style="background:mediumslateblue" |scrollduration

+

|The scrollduration attribute sets the amount of time the web page will take to scroll to the new position (smooth scroll). 0 turns smooth scroll off.

|-

|-

| style="background:mediumslateblue" |background

| style="background:mediumslateblue" |background

Line 1,154:

Line 1,338:

|The interval at which the widget is repainted, in thousandths of a second.

|The interval at which the widget is repainted, in thousandths of a second.

|}

|}

+

+

The scrollbar widgets are optional and must be called "vertscrollbar" and "horizscrollbar". If not present web browser will show the normal Qt scrollbars.

+

+

==The scrollbar widget==

+

[[Image:Scrollbar.jpg|thumb|An example of a scrollbar widget.]]

+

+

This is a regular scrollbar widget that can be added to both the webbrowser and the buttonlist widgets.

+

+

<pre>

+

<scrollbar name="basevertscrollbar">

+

<area>1114,0,14,970</area>

+

<layout>vertical</layout>

+

<hidedelay>0</hidedelay>

+

<shape name="background">

+

<area>0,0,100%,100%</area>

+

<type>roundbox</type>

+

<line color="#aaaaaa" alpha="255" width="1" />

+

<fill style="gradient">

+

<gradient direction="diagonal">

+

<stop position="0" color="#999999" alpha="255" />

+

<stop position="100" color="#999999" alpha="120" />

+

</gradient>

+

</fill>

+

<cornerradius>12</cornerradius>

+

</shape>

+

<shape name="slider">

+

<area>0,0,14,40</area>

+

<type>roundbox</type>

+

<line color="#0895f8" alpha="255" width="1" />

+

<fill style="gradient">

+

<gradient direction="diagonal">

+

<stop position="0" color="#0767AB" alpha="255" />

+

<stop position="100" color="#0767AB" alpha="120" />

+

</gradient>

+

</fill>

+

<cornerradius>12</cornerradius>

+

</shape>

+

</scrollbar>

+

</pre>

+

+

{| cellpadding="4" border="1"

+

| style="background:mediumslateblue" |layout

+

|The layout attribute specifies the orientation of the scroll bar either vertical or horizontal.

+

|-

+

| style="background:mediumslateblue" |hidedelay

+

|The hidedelay specifies a delay after which the scroll bar will hide itself after the webbrowser or buttonlist has been scrolled. A value of 0 means the scrollbar will never hide.

+

|}

+

+

A '''shape''' or '''imagetype''' called ''slider'' must be defined.

==The shape widget==

==The shape widget==

Line 1,450:

Line 1,683:

It is not used in versions 0.24 and above.

It is not used in versions 0.24 and above.

−

== [[gallery-ui.xml]] ==

+

== [[gallery-ui.xml]] ==

−

+

−

The gallery-ui.xml file governs the layout and behavior of the MythGallery Plugin and its associated settings screens.

+

The gallery-ui.xml file governs the layout and behavior of the MythGallery Plugin and its associated settings screens.

−

+

−

== [[game-ui.xml]] ==

+

== [[game-ui.xml]] ==

−

+

−

The game-ui.xml file governs the layout and behavior of the MythGame Plugin and its associated settings screens.

+

The game-ui.xml file governs the layout and behavior of the MythGame Plugin and its associated settings screens.

−

+

−

== [[movies-ui.xml]] ==

+

== [[movies-ui.xml]] ==

−

+

−

The movies-ui.xml file governs the layout and behavior of the MythMovies Plugin and its associated settings screens.

+

The movies-ui.xml file governs the layout and behavior of the MythMovies Plugin and its associated settings screens.

−

+

−

== [[music-ui.xml]] ==

+

== [[music-ui.xml]] ==

−

+

−

The music-ui.xml file governs the layout and behavior of the MythMusic Plugin and its associated settings screens. MythMusic's MythUI port is in progress, and the linked page shows only those windows which have been ported.

+

The music-ui.xml file governs the layout and behavior of the MythMusic Plugin and its associated settings screens. MythMusic's MythUI port is in progress, and the linked page shows only those windows which have been ported.

−

+

−

== [[netvision-ui.xml]] ==

+

== [[netvision-ui.xml]] ==

+

+

The netvision-ui.xml file governs the layout and behavior of the MythNetvision Internet Video Plugin and its associated settings screens.

+

+

== [[news-ui.xml]] ==

+

+

The news-ui.xml file governs the layout and behavior of the MythNews Plugin and its associated settings screens.

+

+

== [[notification-ui.xml]] ==

+

+

The notification-ui.xml file governs the layout and behavior of the notification center cards (0.27 or higher only)

+

+

== [[osd.xml]] ==

+

+

The osd.xml file governs the layout and behavior of the On Screen Display (OSD). (Note: .24 or higher only)

+

+

== [[osd_subtitle.xml]] ==

−

The netvision-ui.xml file governs the layout and behavior of the MythNetvision Internet Video Plugin and its associated settings screens.

+

The osd_subtitle.xml file governs the formatting (text and background) of text-based captions and subtitles. (Note: .26 or higher only)

−

−

== [[news-ui.xml]] ==

−

−

The news-ui.xml file governs the layout and behavior of the MythNews Plugin and its associated settings screens.

−

−

== [[osd.xml]] ==

−

−

The osd.xml file governs the layout and behavior of the On Screen Display (OSD). (Note: .24 or higher only)

== [[recordings-ui.xml]] ==

== [[recordings-ui.xml]] ==

Revision as of 04:46, 15 July 2013

Warning: This is the primary source of documentation about theming in MythTV. Some features discussed here are only available in the development version. Development-only features will be discussed in blue.

MythTV supports UI theming. This theme development guide covers the steps necessary to develop your own look-and-feel for the user interface.

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:

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:

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 you want to define another font, and you want it to be exactly the same as the one above, except for a different color. This is made incredibly simple through inheritance.

This widget will be shown only if the 'coverart' widget is currently displaying an image. If "coverart" is changed to "!coverart", the widget will only be shown if 'coverart' is not currently displaying an image. This allows for alternative use of space depending on the existence or absence of metadata such as images or text.

At present, a widget can depend on the following widget types: textarea, imagetype, progressbar, statetype.
The dependency is a logical expression allowing the operator & (AND) and | (OR). Expression is strictly evaluated from left to right. If the "dependee" widget doesn't exist it is assumed to not be visible.

Warning: as the & character isn't allowed in XML, it must be escaped using &amp; instead

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 title. This hook is what Myth is looking for to insert the title. Consider this example:

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.

Windows as Popups

In MythUI, any window can be a popup above the window that spawned it. This is accomplished by setting the area of the window to less than fullscreen. It can be automatically centered by using -1,-1 as the position. Example:

In a 1280x720 theme:

<window name="mywindow">
<area>-1,-1,1000,600</area>

would position the window 140px from the left, 60px from the top.

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:

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:

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.

Drawing Order

Prior to MythUI, a draworder attribute was used to determine the order of widget rendering. This has been discarded in favor of a simpler "First Come, First Served" approach. Widgets are rendered in order of their definition in the XML file. To draw one widget over another, you simply define it after the first.

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:

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. A theme can contain multiple types (UI and OSD, UI and menu, etc.) and thus there can be multiple <type> definitions.

<baseres>: This is the value that myth uses to parse all the coordinates 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.

Common Attributes

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

name

Each widget in MythUI must have a name defined in the widget's opening tag. It must be a unique name within the window. Names can be either hard-coded values (whose widget images or text will be filled dynamically by myth) or unique values assigned by the themer (whose widget images or text are statically assigned by the themer).

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 it 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>

In cases where area is defined for a sub-attribute, e.g. for an image within a button, the area is reckoned from the top-left of the parent attribute rather than the top-left of the screen.

Area can also take percentage values, such as:

<area>10%,20%,300,100</area>

The above example would place a 300x100 item 10% across and 20% down the screen. Percentage may also be used to size an item, relative to its parent item (which can be the entire screen, the container size of a button, etc.).

You can also use offsets:

<area>20, 10, -20, -10</area>

Would create an area that has a 20 pixel margin on the left and right, and a 10 pixel margin on the top and bottom. Negative numbers in the width / height fields indicate that a right / bottom margin of that size, is desired.

Percentages and offset can be combined:

<area>100%-40, 50%+20, 100%, 100%-10</area>

Would create an area that starts 40 pixels from the right edge, and 20 pixels down from the middle. The size would go to the right edge horizontally, while leaving a 10 pixel margin from the bottom.

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>

Percentage values can also be used with position.

You can also combine offsets with percentages:

<position>100%-20, 50%+20</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:

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:

<alphapulse min="128" max="255" change="2"/>

minsize

Applies only to textarea, shape, and imagetype, when used with the variable sizing of buttonlists. Minimum size the item is allowed to shrink to. Takes two arguments: horizontal and vertical size. Percentages are allowed. In the case of <textarea>, the actual size of the text is determined, and the size of the textarea is shrunk if possible. Any <shape> or <imagetype> siblings to the <textarea> are then shrunk by the same amount.

As of 0.25-pre, three optional attributes are support: initiator, shrink and vanish.

The initiator attribute can be used to indicate whether this area should be used to influence the minimum size of siblings and parents. By default <textarea> elements are initiators.

The shrink attribute indicates which direction the textarea should be shrunk: narrow or short. Narrow is the default.

The vanish attribute indicates that if the textarea is empty, that it and all of it's siblings should just vanish, and not be drawn at all -- regardless of the minsize values.

Applies to focusable widgets only. Specifies text to be shown in an accompanying textarea called helptext when this widget is focused. This can be used to help a user to understand the function of a widget and guide them around the screen.

focusorder

Applies to focusable widgets only. Normally widgets accept focus in the order they appear in the XML, this offers a simple and easily understood mechanism. In more complicated layouts the order of widgets might not match the logical flow between them and this attribute allows a fixed order to be defined instead. It accepts a numerical value where '0' is the first widget, '1' would be the second etc. It is not necessary for all focusable widgets to have a defined focusorder, the default value applied to each is zero so if the intent is to ensure another widget is considered last then it only needs a value greater than zero. Two widgets can share the same value and if that should be the case then they are evaluated in the order they appear in the xml.

Note: Many MythUI attributes can take boolean arguments, which are represented here as "yes" or "no" for simplicity, but all boolean attributes can also take arguments of 0 and 1, or true and false.

Font definitions

While not specifically a widget, font definitions share much in common with widget definitions, and are thus included here. Here's a complete font definition:

The font face is the plain English name of a font installed system-wide or whose TrueType font (.ttf), OpenType font (.otf), or TrueType font collection (.ttc) file is provided within the theme's directory structure. If the font license allows, distributing the font with your theme will ensure other users (even those without the font installed on their systems) use the proper font, so text size is correct and text items fit within the areas you've specified. And, it means users will not have to manually install fonts to their systems. To get more debugging info about which font files and faces are found within your theme directory run "mythfrontend -v gui,file" (on 0.24: mythfrontend -v "gui,file,extra", on trunk: mythfrontend -loglevel debug -v "gui,file"), and use the same name specified in the log output as the face name in your theme.

pixelsize

Size is the font size used in pixels. Use pixelsize or size, not both. Pixelsize has some advantages: Themes are laid out using pixels to a fixed base size so it is easier to tell whether text is going to fit in the given area. Pixels are a finer unit of measure and allow for better fine tuning. When internally rescaling the units for a higher or lower resolution, less is lost to rounding, so text is less likely to be cut off. To convert from size to pixelsize use: (size / 72) * 100. For example:

by using (14 / 72) * 100 = 19.4 Pixelsize can only use whole number, so round up or down.

size

Size is the font size used in points. Use pixelsize or size, not both. (pixelsize is preferred)

color

Color is the hexadecimal value for the color of the font.

shadowcolor

Shadowcolor is the hexadecimal color value used for the drop shadow behind the text.

shadowoffset

Shadowoffset is the coordinate offset for the drop shadow. In our example, the drop shadow would be two pixels to the right, and two pixels down from the text.

shadowalpha

Shadowalpha sets the opacity of the drop shadow, with a value from 0-255

outlinecolor

Outlinecolor is a hexadecimal color value for an outline around the text.

outlinesize

Outlinesize is the pixel radius of a text outline.

outlinealpha

Outlinealpha sets the opacity of the text outline.

italics

italics takes boolean values of yes or no and change the text in the expected fashion.

weight

Weight changes the "press" of the pen when rendering fonts. Values can be numeric or textual, from 1-7 or ultralight, light, normal, demibold, bold, black, and ultrablack. Rounds to the nearest weights offered by the font family and there may be less than 7 available.

stretch

Stretch changes the horizontal stretch of fonts. Values can be numeric or textual, from 1-9 or ultracondensed, extracondensed, condensed, semicondensed, unstretched, semiexpanded, expanded, extraexpanded and ultraexpanded.

decoration

Decoration of the text. Values are underline, overline, and strikeout.

letterspacing

Number in pixels to add to the spacing between letters. Completely optional, only for use when attempting to expand the space words take up.

wordspacing

Number in pixels to add to the spacing between words. Completely optional, only for use when attempting to expand the space text areas take up.

Note: Fonts must be installed on the system. If you include a non-standard font with your theme, your users will need to install it systemwide for it to be used in your theme. Myth will fall back to installed fonts if the font is not installed systemwide.

Animations

Note: This is available from version 0.25 and only when using the OpenGL painter.

Starting tag for a group of animations with a common trigger. It can take one attribute, trigger, which dictates when the animation(s) should be started. Values are AboutToShow, and AboutToHide, which respectively occur when windows are shown and hidden. Default is AboutToShow.

section

It can take two attributes, duration, and centre.

duration controls the length of the contained animations in milliseconds. Default is 500.

Controls the zoom attribute (in percent) of the widget. It uses the following format:

<zoom start="integer value" end="integer value" />

horizontalzoom

Like zoom but only applies a horizontal zoom. It can be combined with verticalzoom. It uses the following format:

<horizontalzoom start="integer value" end="integer value" />

verticalzoom

Like zoom but only applies a vertical zoom. It can be combined with horizontalzoom. It uses the following format:

<verticalzoom start="integer value" end="integer value" />

The textarea widget

An example of a textarea.

The textarea widget is the simplest widget in MythUI. It will place a text area on the screen which can either be filled by the themer or (by using the name= tag) dynamically filled by MythTV. For purposes of simplicity, let's look at all the attributes which can be used in a textarea widget and then discuss each one.

MythUI widgets are always opened with their widget type as the tag. So, we start our textarea widget and give it a name with <textarea name="MyFirstTextArea">. Let's look at each attribute.

area

As explained above, this attribute sets the location and size of our text area. You could also use <position> if inheriting from another text area (by adding from="name ofothertextarea" to the textarea tag).

case

This sets the capitalization of our text area. If not set, the text area will follow normal capitalization. Valid values are normal, upper,lower, capitaliseall (capitalize first letter of each word) and capitalisefirst (capitalize first letter of each sentence).

font

A font name as defined earlier in the same UI file or in base.xml. In our example, we are using MyFirstFontBlack which we discussed defining earlier.

cutdown

If the textarea runs over the defined area, the cutdown attribute will truncate it with ellipsis, "...". If you are concerned that a value inserted by myth will be too long for the text area you have assigned, you may want to set cutdown to "yes". Default behavior is to not cut down text. In pre-0.25, cutdown can optionally take "left", "middle" and "right" as options, which indicate where the ellipsis should be applied. "yes" is equivalent to "right". If multiline is true, any cutdown will always be on the right.

multiline

The multiline attribute wraps text onto a new line if it runs out of space.

An attribute very like alphapulse, except the cycle is between colors instead of opacities. Colors in MythTV are always in hexadecimal format. The above example will cycle between white and black, with 255 steps in between. The cycling occurs at approximately 30 steps per second. Thus, our example will complete in just under eight seconds.

scroll

If the "text" is to large for the specified area, starting with 0.25, it can be set to scroll within the area.

The 'rate' is in pixels per second, with a default of 70. The 'delay' is in seconds, with a default of 3.
returnrate and returndelay are only applicable to direction="vertical" and direction="horizontal".

value

Value is the attribute which sets the text to appear in the textarea. It is optional. In a text area which Myth is not filling in, it can be any text you wish to set. In a Myth-filled box, it will be the "fallback" value. If myth has no text to insert, the user will see this value instead. In a few instances, various variables can be inserted for the value to allow for compound text areas which include multiple pieces of information in a format of the themer's choosing, like %TITLE%, %SUBTITLE%, %DATE%, %STARS%, etc.

template

Template is preferable to using the <value> element when displaying variables. When a screen is loaded, the value element is displayed first, then replaced with template when the variable data is available. This can be values which exist in a map (such as most Program Info like %TITLE%, %SUBTITLE%, etc) but it can also be any named text area where you wish to put the inserted value in a textual context, such as prefacing the value with a label. Example:

<template>Title: %1</template>

When text is being inserted %1 should be used as the placeholder.

Any numerical insertion should use %n to take advantage of number/plural translation capabilities in Myth.

<template>%n item(s)</template>

Would display (1 item, or 3 items) when translated.

The imagetype widget

An example of a imagetype (with a mask, and another imagetype overlaid).

The imagetype widget is another very simple widget. It takes a filename as input, applies masks, crops, and other manipulations, and displays it on the screen. Just as with the textarea widget, certain hardcoded name values on certain screens can be dynamically filled by MythTV.

An imagetype widget must have (one of) a filename or filepattern. All the other attributes are optional. An imagetype will also take all global attributes such as area, position, alpha, and alphapulse.

filename

The filename attribute sets a filename for the image relative to the root of the theme directory. You can place an image in a subdirectory and include it in the filename value, like:

<filename>path/to/filename.png</filename>

As with the textarea widget, if the imagetype is dynamically filled by MythTV and there is a filename set, the file will be the "fallback" when Myth has no value to insert.

The filename attribute can *also* be a directory name (which must end in "/"). This will select and display a random image from the directory. The directory can be relative to the theme directory or absolute path.

preserveaspect

preserveaspect will scale the image to the size specified, but will retain the original aspect ratio by leaving empty space within the defined area. This option is excellent for posters with variable sizes and aspects, or places where both a screenshot or fixed image might appear.

crop

A crop, as evidenced by the name, crops the image to the specified x/y value, width, and height. This is useful for preview images which might have closed-captioning garbage.

mask

mask allows a second image to be set to alpha-mask the original. This is a black and transparent image of identical size to the imagetype area, where black is visible and transparent will be masked. This allows for smooth edges and exotic shapes to your image. Masks cannot be resized or scaled. NOTE: If the filename of the image is used elsewhere in unmasked form (or possibly with a different mask), the mask may be ignored.

reflection

reflection is an attribute which casts a reflection of the imagetype along either the horizontal or vertical axis. Valid values for axis are horizontal and vertical. Shear is the angle of the reflection as a percentage value, from 0-100. Scale is the severity ("squishedness") of the reflection as a percentage value, from 0-100. Length is the size of the draw reflection compared to the size of the original image as a percentage value, from 0-100. Spacing is the distance of the reflection from the axis of the reflection, which can be used to give the impression that the object is above the surface upon which the object is reflected.

grayscale

grayscale determines whether a colour image should be displayed as grayscale instead.

filepattern

filepattern allows for simple flipbook animations. The low and high values define the first and last image numbers in a the series, and the "%1" in the filename is the place where the number variable is inserted. So, for a flipbook animation that cycles from myfile1.png to myfile99.png, the filepattern would look like:

<filepattern low="1" high="99">myfile%1.png</filepattern>

Animations typically restart from the beginning when they've reached the end. An animation may also be cycled forward, then reversed when it reaches the end by adding cycle="reverse" to the attributes. e.g. 1-2-3-2-1 This may reduces the overall number of frames required and save memory.

delay

delay is the time interval in milliseconds between cels in your flipbook animation. It is an integer value and defines the speed at which the animation is cycled.

The statetype widget

The statetype widget is a special widget used for an image, button, or other element that behaves or looks differently according to its status. An example of a statetype would be a button item which can be either selected or unselected. Statetypes are also used in menu watermark images (discussed in the menu-ui.xml article). The most important new attribute introduced in the statetype is a state. Each state represents how a statetype behaves under a given condition.

The state attribute defines the behavior of a single state in the statetype (which is a collection of states). Instead of name, some states use the type attribute. The names are unique depending on the context of the statetype. Commonly used state names are selected, unselected, active, and inactive. Type will always be on, off, half, or full. Which types are used depends on the context of the statetype. In the example, if the item were selected, the "selectimage.png" image would be displayed. If it were unselected, the "normalimage.png" image would be displayed. This is the simplest example of a statetype, but each state can have its own position, images, text, and virtually anything you can imagine!

showempty

The showempty attribute specifies that any empty state should still be displayed (as empty).

After all of that text, there is absolutely nothing new about a button! No special attributes, no new material. The button widget contains a single statetype, buttonstate. The statetype contains four states, active, selected, disabled, and pushed. active is a unselected, active button. selected is a selected, active button. disabled is an unselected or a "greyed out" button. pushed is the "down/pushed in" state of a button (mid-push). Each state must contain (or inherit) the textareatext.

You may notice above the use of inheritance and the use of states in a font declaration. These font states carry over into the following state attributes and change the fonts of each type accordingly.

button statetypes

Statetype Name

Included States

Optional named attributes:

buttonstate

active

textarea - text

selected

textarea - text

disabled

textarea - text

pushed

textarea - text

The buttonlist widget

An example of a buttonlist.

The buttonlist widget is a series of dynamically-filled buttons. It is one of the most commonly used of all widgets, and is primarily built out of other widgets.

A buttonlist is an extremely commonly used widget. It is a series of buttons which are dynamically filled depending on their context. It is also one of the most complicated widget structures in MythUI. A buttonlist widget contains the following structure, which is largely self-explanatory. The checkoff, checkhalf, and checkfullstates pertain to those buttons which contain checkboxes (like in the MythMusic playlist).

layout

Valid values for layout in a buttonlist are horizontal, vertical, and grid. The default is horizontal.

spacing

Spacing is an attribute to set a pixel value to reserve between each button in a button list.

scrollstyle

Sets the scrolling behavior of the buttonlist. Valid options are:

center - Selected item is always in the center.

groupcenter - Selected item is allowed to float in the center of the group, so the group as a whole can stay centered. Valid only with <arrange>Stack, Fill or Spread</arrange>.

free - Selector moves freely through the list. With <arrange>Fixed</arrange>, the selector moves freely through the entire list. With <arrange>Stack, Fill or Spread</arrange>, selector moves freely only when the entire list fits on the screen or when the selector is near the beginning or the end of the list; otherwise, the selected item is always in the center.

wrapstyle

Wrapstyle sets the wrapping behavior of the buttonlist. Valid options are items (The list itself wraps at the ends), selection (the selector reaches the end of the list and "jumps" to the beginning), captive (same as none but prevent the buttonlist losing focus when attempting to move beyond the edge), flowing (the selector will wrap from one line to the next in a grid layout), and none (no wrap). The default is none.

buttonarea

Exactly the same arguments as a normal <area> tag, the buttonarea allows one to specify the portion of the buttonlist which is taken up by the buttons themselves, allowing one to make room for the up/down arrows as necessary.

drawfrombottom

Place the buttons at the bottom of the buttonarea instead of the top. Accepts normal boolean values.

arrange

Button arrangement type.

Fixed (default) - Use the fixed position layout engine.

Stack - Stack buttons next to each other. Buttons will be <spacing> apart from each other.

Fill - Buttons will be distributed over the entire <buttonarea>. The spacing between buttons may be different on either side of the selected button, if <scrollstyle> center is specified.

Spread - Spread out the buttons as much as possible, while keeping the spacing between buttons consistent.

align

Aligns buttons in both horizontal and vertical directions. Valid values are: left, right, top, bottom, hcenter, vcenter, center and allcenter. Center is an alias for allcenter. Only valid with <arrange>Stack, Fill or Spread</arrange>.

searchposition

Sets the position of the popup search dialog when shown for the button list. You can use this to position the popup so it doesn't obscure the button list. eg <searchposition>-1,430</searchposition> will position the popup horizontally centered and 430 down. NEW in 0.25-pre

buttonlist statetypes

Statetype Name

Included States

Sub-statetype (if any)

Included States

buttonitem

selectedactive

buttoncheck

checkoff

checkhalf

checkfull

selectedinactive

buttoncheck

checkoff

checkhalf

checkfull

active

buttoncheck

checkoff

checkhalf

checkfull

inactive

buttoncheck

checkoff

checkhalf

checkfull

downscrollarrow

full

off

upscrollarrow

full

off

Additionally, each state in buttonitem can take a textarea named buttontext for the button's text and an imagetype called buttonarrow to indicate the button contains a submenu.

The buttontree widget

An example of a buttontree.

The buttontree widget is essentially a wrapper widget to contains a pre-set number of buttonlists. It is used in various places, notably the MythVideo List View.

Again we see that complicated widgets are actually just collections of simple widgets. The textedit widget includes a statetype named background. The statetype contains three states named active, selected, and inactive.active is a functional but not highlighted textedit widget. selected is an active, highlighted textedit widget. inactive is a "greyed out" or unusable textedit widget.

We complete the widget by defining an imagetype for the cursor in the textarea called cursor, and a textarea called text for where the actual text will be entered.

Yet another widget built out of less complicated widgets. The checkbox widget starts by defining a statetype called background. background contains three states, active, selected and disabled. Active is a functional checkbox which is not highlighted. Selected is a functional, highlighted checkbox. Disabled is a non-functional "greyed out" checkbox.

checkbox contains a second statetype called checkstate. This is a set of three states to indicate the fill status of the checkbox. The states are off, half and full. Off is a completely unfilled checkbox. Half is a half-checked box. Full is a fully checked checkbox. Note that the backgroundstatetype uses "name" states and the checkstatestatetype uses "type" states as discussed above in statetype.

checkbox statetypes

Statetype Name

Included States

background

active

selected

disabled

checkstate

off

half

full

The spinbox widget

The spinbox widget is the definition of a spinbox. A spinbox is a selection box containing multiple values which can be scrolled through (e.g. priority in the recording schedule editor -99 to 99). A spinbox is just a special type of buttonlist with helper functions to fill it with dynamic values.

No new elements in the spinbox. It can have a <layout> of horizontal (right and left keys scroll through values) or vertical (up and down keys scroll through values). The spinbox contains three statetypes named buttonitem (the button itself), downscrollarrow (the down arrow) and upscrollarrow (the up arrow). buttonitem contains three states, active (available but not highlighted), selected (available and highlighted) and inactive (unavailable, unhighlighted). Each state in buttonitem should contain (or inherit) a buttontexttextarea. upscrollarrow and downscrollarrow each contain two states (using the type= attribute), full and off.

spinbox statetypes

Statetype Name

Included States

State must contain:

buttonitem

active

textarea - buttontext

selected

textarea - buttontext

inactive

textarea - buttontext

upscrollarrow

full

off

downscrollarrow

full

off

The progressbar widget

The progressbar widget defines exactly what it sounds like, a progress bar when loading screens, for the web browser, et cetera.

The style attribute sets the type of progressbar. The options are reveal and slide. Reveal places the progressimageimagetype onscreen, but invisible, and reveals it as the item loads. Slide puts slides the progressimageimagetype into the area as the item loads.

The progressimageimagetype must be defined.

The clock widget

An example of a clock (composited with a few imagetypes).

The clock widget allows you to put a clock showing the system time in your theme. It takes all of the global attributes, font definitions, and behaves otherwise like a normal textarea, except it allows the themer to set the time format.

The template element, already seen in the textarea, allows the themer to define the time format. Placeholders are %TIME%, %DATE%, and %SHORTDATE%, these represent the time or date formats chosen by the user. To override the user-chosen defaults you can use the format described by QT Date/Time Format.

The webbrowser widget

An example of a webbrowser widget (as used in mythbrowser).

The webbrowser widget allows you to embed a web browser window in most Myth screens. When built against Qt 4.5, the webbrowser widget can now utilize Mozilla plugins, including flash. When built against an earlier version of Qt, HTML and most javascript will work.

The shape primitive you wish to draw. Eligible types are box, ellipse, and roundbox.

fill

The fill attributes for the shape. Color is expressed as a hexadecimal value, and alpha as a numerical value between 0 and 255. May also takes a style attribute. Valid styles are gradient and solid. When using the gradient style, the subattribute gradient should be used.

gradient

The gradient attribute takes a direction value. Valid values are vertical, horizontal, and diagonal. Gradients have stops defining endpoints for color and alpha. Each stop takes a position from 0-100, a color, and optionally, alpha.

line

The line attributes for the shape. Color is expressed as a hexadecimal value, alpha as a numerical value between 0 and 255 and width as number of pixels.

cornerradius

The corner radius of a rounded box.

The guidegrid widget

The guidegrid widget is a widget for producing an EPG (Electronic Programming Guide). It is used in both the liveTV and Guide scheduling screens.

Specifies whether to show genre text (not available for all grabbers). Defaults to yes.

showcategorycolors

Specifies whether to show genre color coding (not available for all grabbers). Defaults to yes.

categoryalpha

The alpha value of the guide grid items. Valid values are numbers from 0-255.

recordingcolor

The color of an in-progress recording, expressed in hex.

conflictingcolor

The color of an conflicting recording, expressed in hex.

cutdown

Whether to cut down titles in the guide. Valid values are yes and no.

multiline

Whether to allow multiple line guide entries. Valid values are yes and no.

textoffset

Offset value from the top left of the guide grid item. Expressed as x,y values.

recordstatus

Icon to display to indicate an item's recording status. Analogous to a state in other widgets. Takes a type (Valid values are SingleRecord, TimeslotRecord, ChannelRecord, AllRecord, WeekslotRecord, FindOneRecord, and OverrideRecord) and an image (path to a valid image file).

arrow

An arrow icon which indicates the recording continues backwards or forwards. Takes arguments of direction (valid values are left and right) and and image (path to a valid image file).

font

The font to be used in the entire grid. Valid values are any pre-defined font name.

The editbar widget

The editbar widget is a widget used in the OSD (and in the future, in other places) to perform editing of media.

A shape or imagetype to represent that the material to the left will be cut.

cuttoright

A shape or imagetype to represent that the material to the right will be cut.

keeptoleft

A shape or imagetype to represent that the material to the left will be kept.

keeptoright

A shape or imagetype to represent that the material to the right will be kept.

position

A shape or imagetype to represent the current position within the timeline.

The video widget

The video widget is used in MythMusic to display the visualisers (and in the future will be able to display video and more). This widget currently doesn't introduce any new elements. NEW in 0.25-pre.

<video name="MyFirstVideo">
<area>0,0,100,100</area>
</video>

The group widget

The group widget allows other widgets to be grouped together. The widgets become the children of the group so hiding a group will hide all children also moving a group will move all the children as well. Another use of the group widget is to allow a group of widgets to be shared among several screens for example you can create a group that contains the MythMusic playback controls which can then be added to any of the music screens which both saves time and helps to maintain a consistent look and feel. Groups can be nested so a group can itself contain other groups. This widget doesn't introduce any new elements. NEW in 0.25-pre.

Various MythUI Tickets have not yet been applied to Myth's Code. They will be documented temporarily on this page until they enter Myth's code, when they will be moved to the current page.

Tutorials

Once you have read the above, you may want to attempt the Theming MythNews tutorial, which guides you through most of the basics of defining widgets, inheritance, and laying them out on a page. Once you have completed this tutorial, you should have a better understanding of how all the MythUI parts fit together, and will be ready to attempt a theme of your own.

Required MythUI Theme Files

You can click any of the file titles to view a reference of the required windows and named widgets.

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.

Within base.xml, there are certain hardcoded window types which represent search dialogs, popup menus, progress bars, and other generic windows that are used throughout the UI. These must be defined.

The menu-ui.xml file is the file which determines the layout of Myth's core (non-popup) menus. It can be as simple as a single buttonlist, or can be enhanced with clocks, widgets, and other eye candy.

Optional MythUI Theme Files

The following are "optional" in that if they do not exist, the theme will fall back to those files stored in the default and default-wide directories. To finish a complete theme, however, they should all be themed.

The music-ui.xml file governs the layout and behavior of the MythMusic Plugin and its associated settings screens. MythMusic's MythUI port is in progress, and the linked page shows only those windows which have been ported.

The weather-ui.xml file governs the layout and behavior of the MythWeather Plugin and its associated settings screens.

zoneminder-ui.xml

The zoneminder-ui.xml file governs the layout and behavior of the MythZoneminder Plugin and its associated settings screens.

Testing Your Theme

During development it's helpful to make iterative changes and observe the results without having to exit and restart the frontend each time. You can trigger a theme reload by sending the USR1 signal to a mythfrontend process. On Linux this is as easy as:

kill -USR1 $(pidof mythfrontend)

Alternatively, you may bind a key to the RELOADTHEME jump point using the Edit Keys menu.

Validation

From 0.24 both a DTD and XSD (XML Schema Definition) are available for themes and they can be used to ensure that your theme conforms to the latest version of the xml and find a range of mistakes. The XSD is recommended over the DTD as it can be used to check conformity and formatting of values and not just markup.

To validate your theme a number of tools might be used, but xmllint is available from xmlsoft and runs from the command line: