Menu theme development guide

From MythTV Official Wiki
Revision as of 03:58, 15 March 2006 by 207.192.228.146

Jump to: navigation, search

Introduction

Menu themes allow the user to customize where certain myth features are located. By creating a customized menu theme, users can tailor MythTV to their own usage. The goal of this guide is to familiarize users with the menu's XML format and to create a comprehensive list of actions that will allow the user to invoke plugins and other menus. This document assumes that mythtv is installed in the "/usr" directory. If it is installed in the "/usr/local" directory, substitute everywhere that says "/usr/" with "/usr/local/". This document is currently incomplete.

Overview

Menu themes are a series of XML documents. The XML document defines what "buttons" are shown on each menu. Each XML document describes one menu.

First Step

The first step is to create a directory to hold the menu's XML document. If unsure, a good place is in the home folder. The directory can be called anything that is not already a theme of any kind. To find out what not to call the menu theme, use the following command in a terminal:

$ ls /usr/share/mythtv/themes

Type the following to create a directory for a menutheme in "~/mymenuthemes/mymenu".

$ cd ~
$ mkdir mymenuthemes
$ cd mymenuthemes
$ mkdir mymenu
$ cd mymenu

It is generally a good idea to sketch out how the new menu is to be laid out. This will decrease the chance of error as well as speed up the development process.

Creating a Main Menu

To create the main menu, create a new document called "mainmenu.xml" For example, this command can be typed at the terminal:

$ gedit mainmenu.xml

The first line of the document will always be

<mythmenu name="MAIN">

After the mythmenu tag, one or more button tags will define the buttons shown on the screen. Finally, the document will end with

</mythmenu>

Buttons

A button defines what text appears on the screen and what action will be taken when the user selects the button.

<button>
   <type>SOME_TYPE</type>
   <text>My Text</text>
   <text lang="XX">My Text in XX</text>
   <action>SOME_TYPE_ACTION</action>
   <depends>myplugin</depends>
</button>

Below is a description of each tag

  • <type> This tag defines what kind of button this is. This will determine what picture is shown when the button is highlighted. A list of known types can be found in Appendix A: Types.
  • <text> The default text that appears on the screen. This is generally written in English.
  • <text lang="XX"> Text that will appear if the user's local is XX. There may be more than one of these tags
  • <action> The action that will result when the user selects the button. A complete list of known actions can be found in Appendix B: Actions
  • <depends> Indicates that the button will only be shown if the indicated plugin is installed

More Menus

One menu is usually not enough. To organize things, other menus can be created. A new menu will be an xml document of any name. New menus also start out with the tag <mythmenu name="NAME">. Replace "NAME" with an identifier of choice. Remember that the xml document must end with </mythmenu>.

Linking to another Menu

To link to another menu, create a button that looks like this:

<button>
   <type>MENU_TYPE</type>
   <text>Go to another Menu</text>
   <text lang="XX">Ogay otay notheray enumay</text>
   <action>MENU newmenu.xml</action>
</button>

Putting it all together

After all of the xml files have been created, simply (as root) copy the folder into your mythtv installation themes folder. This will usually be in /usr/share/mythtv/themes. After that, run mythfrontend.

/home/you/mymenuthemes/mymenu$ su
/home/you/mymenuthemes/mymenu# cd ..
/home/you/mymenuthemes# cp -r mymenu /usr/share/mythtv/themes
/home/you/mymenuthemes# exit
/home/you/mymenuthemes$ mythfrontend

To activate the new theme, go to the appearance settings in mythfrontend and select the new theme. Remember, if you want to switch back to another theme, your theme has to have a link somewhere to the appearace settings (SETTINGS APPEARANCE).

Helpful Tips

Sometimes there is an action that is desired, but not quite possible. For example, one cannot call mythdvd to do the action DVD_PLAY from the main menu. The action could be hardcoded into the menu itself. For example, a button can be written like so:

  <button>
     <type>DVD</type>
     <text>Watch DVD</text>
     <action>EXEC xine --fullscreen dvd:/</action>
     <depends>mythdvd</depends>
  </button>

This should probably only be used on a personal level since another user may not have the custom program.

Appendix A: Types

Other graphical theme writers may include other types in their themes. These types are the ones referenced to in the default theme.

TV

  • TV
  • TV_RECPRIORITIES_SETTINGS_GENERAL
  • TV_RECPRIORITIES_CHANNEL
  • TV_PROGRAM_GUIDE
  • TV_PROGFIND
  • TV_SEARCH_WORDS
  • TV_SEARCH_LISTS
  • TV_MANUAL_SCHEDULE
  • TV_RECPRIORITIES
  • TV_CONFLICTS
  • TV_SEARCH_TITLES
  • TV_SEARCH_KEYWORDS
  • TV_SEARCH_PEOPLE
  • TV_SEARCH_NEW_TITLES
  • TV_SEARCH_MOVIES
  • TV_SEARCH_CATEGORIES
  • TV_SEARCH_CHANNELS
  • TV_SEARCH_TIMES
  • TV_SETTINGS_GENERAL
  • TV_SETTINGS_PROGRAM_GUIDE
  • TV_SETTINGS_PLAYBACK
  • TV_SETTINGS_RECORDING_PROFILES
  • TV_SETTINGS_RECPRIORITIES
  • TV_WATCH_TV
  • TV_SCHEDULE_RECORDINGS
  • TV_WATCH_RECORDINGS
  • TV_DELETE
  • TV_STATUS

Music

  • MUSIC
  • MUSIC_SETTINGS_GENERAL
  • MUSIC_SETTINGS_PLAYER
  • MUSIC_SETTINGS_RIP
  • MUSIC_PLAY
  • MUSIC_PLAYLIST
  • MUSIC_RIP
  • MUSIC_SCAN

VIDEO

  • VIDEO
  • VIDEO_SETTINGS_GENERAL
  • VIDEO_SETTINGS_PLAYER
  • VIDEO_FILE_TYPES
  • VIDEO_BROWSER
  • VIDEO_LIST
  • VIDEO_MANAGER

DVD

  • DVD
  • DVD_SETTINGS_GENERAL
  • DVD_SETTINGS_PLAY
  • DVD_SETTINGS_RIP
  • DVD_PLAY
  • VCD_PLAY
  • DVD_RIP

GAME

  • GAME
  • GAME_SETTINGS_GENERAL
  • GAME_SCAN

SETUP/SETTINGS

  • SETUP
  • SETTINGS_GENERAL
  • SETTINGS_APPEARANCE
  • SETTINGS_TV
  • SETTINGS_MUSIC
  • SETTINGS_VIDEO
  • SETTINGS_DVD
  • SETTINGS_FM
  • SETTINGS_IMAGES
  • SETTINGS_GAME
  • SETTINGS_WEATHER
  • SETTINGS_NEWS
  • SETTINGS_WEBPAGE
  • SETTINGS_RECIPE
  • SETTINGS_XBOX
  • SETUP_GENERAL
  • SETUP_CAPTURE_CARDS
  • SETUP_VIDEO_SOURCES
  • SETUP_INPUT_CONNECTIONS
  • SETUP_CHANNEL_EDITOR

MISC

  • FM
  • IMAGES
  • WEATHER
  • NEWS
  • WEBPAGE
  • RECIPE
  • SHUTDOWN

Appendix B: Actions

TV actions

  • TV_STATUS - Status of the myth backend
  • TV_WATCH_RECORDING - Go to the watch recording screen
  • TV_WATCH_LIVE - Watch live TV
  • TV_SET_RECPRIORITIES - View/Set Recording Priorities
  • TV_FIX_CONFLICTS - Show upcoming recordings and conflicts
  • TV_DELETE - Go to delete recordings screen
  • TV_PREVIOUS - Show previously recorded shows
  • TV_SCHEDULE - Schedule a recording
  • TV_PROGFIND - Go to program finder
  • TV_MANUAL - Manually set recording info
  • TV_CUSTOM_RECORD - Allow user to set a custom recording
  • TV_MANUALSCHEDULE -
  • TV_SEARCH_TITLE - Search for program by title
  • TV_SEARCH_KEYWORD - Search for program by keyword
  • TV_SEARCH_PEOPLE - Search for program by people
  • TV_SEARCH_POWER
  • TV_SEARCH_NEW - Search for new programs
  • TV_SEARCH_MOVIE - Search for movies
  • TV_SEARCH_CATEGORY - Search by category
  • TV_SEARCH_CHANNEL - Search within a channel
  • TV_SEARCH_TIME - Search within a time

Settings actions

Please note the space between SETTINGS and it's argument

  • SETTINGS MAINGENERAL - Main settings
  • SETTINGS APPEARANCE - Appearance Settings
  • SETTINGS XBOXSETTINGS - XBox Settings
  • SETTINGS GENERALRECPRIORITIES - Recording priority settings
  • SETTINGS CHANNELRECPRIORITIES - Channel recording priority
  • SETTINGS EPG - Electronic Program Guide settings
  • SETTINGS PLAYBACK - Playback settings
  • SETTINGS RECORDING - Recording settings
  • SETTINGS PLAYGROUP - ?
  • SETTINGS GENERAL - ?

Special Actions

  • EXEC someprogram - Executes a specified program
    • Example: EXEC xine --fullscreen --no-splash dvd:/
  • EXECTV someprogram %s %s %s - Executes a TV program. %s args are video, audio, and vbi devices
    • Example: EXECTV xawtv -f -device %s -dspdev %s -vbidev %s
  • MENU somemenu.xml - Jump to a new menu
    • Example: MENU settings.xml
  • UPMENU - Go to parent menu
  • CONFIGPLUGIN myplugin - Configure a plugin
    • Example: CONFIGPLUGIN mythdvd
  • PLUGIN myplugin - Activate a plugin
    • Example: PLUGIN mythdvd
  • SHUTDOWN - Shutdown myth
  • JUMP - ???