Difference between revisions of "OSD development guide"

From MythTV Official Wiki
Jump to: navigation, search
(Font Container: Completed section, cloned theme from other theming guide)
(Deleted very, very outdated text in favor of redirect to current info)
 
(9 intermediate revisions by 3 users not shown)
Line 1: Line 1:
MythTV supports theming of the On Screen Display (OSD) items used when watching Live TV or recordings.  This theme development guide covers the steps necessary to develop your own look-and-feel for the OSD.
+
#REDIRECT [[MythUI Theme Development]]
 
 
== Technical Details ==
 
=== Layout Coordinates ===
 
All x,y coordinates used in OSD themes are based on a grid of 640x480.  In contrast to the menu themes, which use 800x600 for 4:3 displays and 1280x720 for 16:9 (widescreen), the grid used for OSD elements stays the same regardless of the actual aspect-ratio of the display being used.  ''(this last bit is merely an assumption I'm making--edit if it's wrong)''
 
 
 
=== Filenames ===
 
OSD themes can be put in a subdirectory of their own under the themes directory (typically "/usr/share/mythtv/themes") or they may reside in the same directory as the other theme files of a set.  Since there is no difference in the was OSD themes are handled based on the aspect ratio, there is no need to add "-widescreen" to the end of the directory name.  OSD themes are stored in a file named simply "osd.xml".
 
 
 
== List of Containers ==
 
OSD themes are XML documents with the top-level container being named "mythtvosdtheme".  Within the mythtvosdtheme container, there are a number of other container types that can be used.
 
 
 
=== Timeformat Container ===
 
This is a container with only one thing inside, namely the format string to be used for displaying the time in the display for the elements that show the time.  If you use the special token '''FROMSETTINGS''', MythTV will use the time format specified in General settings.
 
 
 
{| border=1 cellspacing=0 cellpadding=2
 
|-
 
!width="100pt"|Type
 
!width="500pt"|Description
 
|-
 
|align=center|format string
 
|Format of time to be displayed
 
''or'' special token 'FROMSETTINGS'
 
|}
 
 
 
=== Fadeaway Container ===
 
Similar to timeformat, this container only has one value which is the number of ms it should take for a display element to be faded to 100% transparency when it is being removed from the screen.
 
{| border=1 cellspacing=0 cellpadding=2
 
|-
 
!width="100pt"|Type
 
!width="500pt"|Description
 
|-
 
|align=center|Integer
 
|Duration of fade effect in ms
 
|}
 
 
 
=== Font Container ===
 
'''Warning!'''  The font declarations for osd.xml are ''very'' different from the font declarations used in the other types of themes--read this section ''carefully''.
 
 
 
As with all the other types of themes, you will need to declare named fonts for use for any text elements in the display.  A font declaration looks something like the following:
 
<nowiki><font name="infofont">
 
  <filename>Vera.ttf</filename>
 
  <size>48</size>
 
  <size:small>32</size:small>
 
  <size:large>48</size:large>
 
  <color>
 
    <normal>#F7862B</normal>
 
    <outline>#101010</outline>
 
  </color>
 
  <shadow>2,3</shadow>
 
</font></nowiki>
 
 
 
The font tag has the following attributes:
 
{| cellpadding="4"
 
! Name
 
! Required
 
! Description
 
|-
 
| style="background:silver" | name
 
| style="background:silver" align="center" | Y
 
| style="background:silver" | The internal name for the font.  i.e. "MyFont"
 
|-
 
| size
 
| align="center"  | Y
 
| The size of the font (in points).
 
|-
 
| style="background:silver" | size:small
 
| style="background:silver" align="center" | N
 
| style="background:silver" | The size of the font (in points) when using small fonts.
 
|-
 
| size:large
 
| align="center"  | N
 
| The size of the font (in points) when using large fonts.
 
|-
 
| style="background:silver" | shadow
 
| style="background:silver" align="center" | N
 
| style="background:silver" | The offset for the drop shadow, orientated on the top left corner.  Negative values are allowed.
 
|-
 
| color
 
| align="center"  | N
 
| The container for the elements that define the color of various parts of the font glyphs.
 
|}
 
 
 
* It is unknown what effect (if any) the integer being supplied to color in the osd themes that ship with MythTV has.  It would be nice if it were setting an alpha-transparency level, but the source code doesn't appear to use it for anything.  Setting it to anything but an integer at the moment seems to ''break'' that particular font declaration.
 
 
 
 
 
The '''color''' element can contain any of the three following elements to control the colors of various parts of the glyphs being drawn.
 
{| cellpadding="4"
 
| <b>Name</b>
 
| <b>Required</b>
 
| <b>Description</b>
 
|-
 
| style="background:silver" | normal
 
| style="background:silver" align="center" | N
 
| style="background:silver" | The color of the "normal" part of the font.
 
|-
 
| outline
 
| align="center"  | N
 
| The color of the outline drawn around the font glyphs.
 
|-
 
| style="background:silver" | shadow
 
| style="background:silver" align="center" | N
 
| style="background:silver" | The color of the dropshadow (if any) used for the font glyphs.
 
|}
 
 
 
* How the size of the outline is specified, I have no idea at all about.
 
* It is unknown if there is any way to specify additional font faces within a ttf file to make use of ''bold'', ''italics'' and ''underline'' typefaces.
 
* It's important to provide all three sizes of fonts.  What might be perfect for you, may be too big/small for someone else.
 
 
 
=== Program Info Container ===
 
The program info container shows any information available about the content currently being watched, including the name, number, and icon of the channel, the name of the program being watched, and it's description.
 
 
 
=== Channel Number Container ===
 
The channel number container is merely a widget that displays the channel number as the user enters it to change the channel.
 
 
 
=== Browse Info Container ===
 
 
 
=== Status Container ===
 
The status container shows the current position information for the recording.
 
 
 
It allows the following elements:
 
* slidertext - Position info in text form e.g. 1:24 of 2:01
 
* extendedslidertext - Extends the position info with time remaining e.g. (0:37 minutes remaining)
 
* statusslider - Displays a fill type position bar or slider
 
* statusposition - Another slider? Maybe allows you to overlay a position marker on statusslider?
 
* progbefore - In livetv allows you to display an image indicating a programme exists before in the livetv chain
 
* progbefore - In livetv allows you to display an image indicating a programme exists after in the livetv chain
 
 
 
=== Notify CID Info Container ===
 
 
 
=== Notify Alert Text Container ===
 
 
 
=== Editmode Container ===
 
 
 
=== Settings Container ===
 
 
 
=== Base Dialog Container ===
 
 
 
=== News Scroller Container ===
 
 
 
=== Menu Container ===
 
 
 
=== Channel Editor Container ===
 
 
 
 
 
 
 
 
 
 
 
[[Category:Developer Documentation]]
 
[[Category:Themes]]
 

Latest revision as of 10:59, 28 August 2012