Themed Menus
The Themed Menu feature allows users and themers to customize the content and structure of hierarchical pop-up menus. This customization is in the form of an XML file in the Theme directory or under the user's home directory.
Users may be most interested in the new Custom menus, which allow the user to collect and reorder their most commonly used menu items into a more convenient list and hierarchy.
Note: Themed Menus are currently in Beta release.
As such, more menus will eventually become customizable, and many of the action names will be deprecated and renamed.
Contents
Overview
A Themed Menu is a simple XML description of a hierarchical menu,
consisting of menu
, item
, and
itemlist
elements. Here is an example of a themed menu
for the Playback OSD.
<?xml version="1.0"?> <menu text="My Themed Menu"> <menu text="Submenu"> <item action="TOGGLESUBDELAY" text="Adjust Subtitle Delay" /> <item action="TOGGLEAUDIOSYNC" text="Adjust Audio Sync" /> <item action="ADJUSTSTRETCH" text="Adjust Time Stretch" /> </menu> <menu text="Another submenu"> <item action="PAUSE" text="Play" show="active" /> <item action="PAUSE" text="Pause" show="inactive" /> </menu> </menu>
This example defines a menu which, at the top level, consists of two submenus, titled "Submenu" and "Another submenu". Navigating to the first submenu shows a list of three actions. The second submenu would actually offer only one action, labeled "Play" or "Pause" depending on current state of playback.
In addition to the item
element, the
itemlist
element expands an action group into a list of
actions, which is especially useful when the actions depend on the
particular recording or context, such as a list of track names.
Menu file description
A Themed Menu XML file contains a single top-level menu
element, whose text
attribute is displayed as the menu
title.
Below we describe in detail the set of available XML elements, along with each element's available attributes.
Menu items are enclosed within a menu
element. Nesting
menu
elements creates a submenu hierarchy.
Example:
<menu text="My Menu Title"> <menu text="My Submenu Title"> ... </menu> <menu text="My Other Submenu Title"> ... </menu> </menu>
The text
attribute
This is the text displayed as the title of the menu or submenu. The text is translated using MythTV's translation infrastucture, so it is wise to reuse existing, already-translated strings for Themed Menus that are distributed to others.
The text
attribute is required (otherwise the menu name
will be blank).
The item
element
The item
element describes a menu item with a concrete
action. Each item contains internal "show" and "current" state that
can be used to partially control the display of the item.
A given item is displayed only if it is actually allowed in the current context. For example, the actions related to jumping to DVD menus would only be shown during DVD/BD playback. Similarly, most of the Picture-In-Picture actions can only be shown while PiP/PbP is active.
Example:
<item action="PAUSE" text="Play" show="active" /> <item action="PAUSE" text="Pause" show="inactive" />
The action
attribute
This is the name of the action to execute when the menu item is selected. See below for a comprehensive description of available actions.
The action
attribute is the only required attribute of
the item
element.
Note: All action names are subject to future renaming.
The action names correspond to their internal MythTV names and are being exposed externally for the first time. Future normalization and cleanup will likely deprecate and change many of the current action names.
The text
attribute
This is the text that appears in the menu item. Every action has a
default, translatable text string, so in most cases the
text
attribute can and should be omitted. Some actions
actually have two default strings, one for the "active" state and one
for the "inactive" state.
If you need to specify or change the text attribute, and you plan to distribute your XML file to others, try to consider the translation issues. In partcular, try to reuse strings that are already translated.
The show
attribute
The show
attribute can take two possible values: "active"
and "inactive". If the show
attribute is present, then
the menu item is displayed only when its "show" state matches the
show
attribute.
show="active"
and show="inactive"
are
typically used in two situations. The first situation is when the
action toggles some state, and you want different text
attributes depending on the current state. Example:
<item action="PAUSE" text="Play" show="active" /> <item action="PAUSE" text="Pause" show="inactive" />
The second situation is when you want to suppress a menu item when the action would essentially be a no-op, such as disabling subtitles when subtitles are already turned off. Example:
<item action="DISABLESUBS" text="Disable Subtitles" show="inactive" /> <item action="ENABLESUBS" text="Enable Subtitles" show="inactive" />
If the show
attribute is not specified, the menu item
will always be shown (provided the action is allowed in the current
context; see the discussion above).
The current
attribute
When a menu is opened, normally the first menu item is highlighted.
This can be overridden using current="active"
. If that
action is active in the current context, that menu item will be
highlighted rather than the first item. For example:
<menu text="Change Aspect Ratio"> <item action="TOGGLEASPECT0" text="Off" current="active" /> <item action="TOGGLEASPECT1" text="4:3" current="active" /> <item action="TOGGLEASPECT3" text="14:9" current="active" /> <item action="TOGGLEASPECT2" text="16:9" current="active" /> <item action="TOGGLEASPECT4" text="2.35:1" current="active" /> </menu>
In this example, when the "Change Aspect Ratio" menu is opened, the current aspect ratio will be highlighted.
If multiple items in a menu match the current="active"
test, an arbitrary one is chosen to be highlighted.
There is one exception to this rule. When navigating back from a submenu into its parent menu, that submenu is always highlighted.
The itemlist
element
The itemlist
element expands into a list (possibly
zero-length) of menu items. In some cases, it is precisely equivalent
to a list of item
elements, and is just a convenience.
In other cases, the set of items is dynamically generated as part of
the current context, such as a list of available tracks or DVD titles.
The actiongroup
attribute
This is the name of the action group to expand. See below for a comprehensive description of available actiongroups.
The actiongroup
</code> attribute is the only required
attribute of the itemlist
element.
Note: All action group names are subject to future renaming.
The action group names correspond to prefixes of internal MythTV action names and other internal MythTV logic. Future normalization and cleanup will likely deprecate and change many of the current action group names.
The current
attribute
This is equivalent to the current
attribute in the
item
element, as though the attribute were applied to all
items in the expansion of the action group.
The include
element
The include
element allows rudimentary modularization by
including the contents of another Themed Menu XML file. It contains a
single required attribute, file
. Example:
<menu text="Playback Compact Menu"> <item action="EDIT" /> <item action="DEBUGOSD" /> <include file="menu_playback.xml" /> </menu>
There is a limited recursive include depth, in order to avoid infinite recursion.
Themed Menu file search path
When loading a Themed Menu XML file, the first location searched is $MYTHCONFDIR (or, if MYTHCONFDIR is not defined, ~/.mythtv/). If the file is not found, it then uses the standard MythUI theme search path.
This means that a theme developer can provide an overridden version of a Themed Menu, and ultimately the user can override all of these.
Currently there are four implementations of Themed Menus.
In the tables below that describe the available actions,
The Playback OSD menu is read from menu_playback.xml, and is displayed during playback via the MENU action (mapped by default to the 'M' key).
Action Name | Action Group | Action Description | show="active" condition (default true) |
Display condition (default true) |
3DNONE | 3D | Deactivate 3D mode | If the video output device supports stereoscopic modes | |
3DSIDEBYSIDE | 3D | Activate side-by-side 3D mode | If the video output device supports stereoscopic modes | |
3DSIDEBYSIDEDISCARD | 3D | Activate discard side-by-side 3D mode | If the video output device supports stereoscopic modes | |
3DTOPANDBOTTOM | 3D | Activate top-and-bottom 3D mode | If the video output device supports stereoscopic modes | |
3DTOPANDBOTTOMDISCARD | 3D | Activate discard top-and-bottom 3D mode | If the video output device supports stereoscopic modes | |
ADJUSTSTRETCH | ADJUSTSTRETCH | Bring up the timestretch adjustment dialog. | ||
ADJUSTSTRETCH0.5 | ADJUSTSTRETCH | Set the timestretch value to 0.5x. | ||
ADJUSTSTRETCH0.9 | ADJUSTSTRETCH | Set the timestretch value to 0.9x. | ||
ADJUSTSTRETCH1.0 | ADJUSTSTRETCH | Set the timestretch value to 1.0x. | ||
ADJUSTSTRETCH1.1 | ADJUSTSTRETCH | Set the timestretch value to 1.1x. | ||
ADJUSTSTRETCH1.2 | ADJUSTSTRETCH | Set the timestretch value to 1.2x. | ||
ADJUSTSTRETCH1.3 | ADJUSTSTRETCH | Set the timestretch value to 1.3x. | ||
ADJUSTSTRETCH1.4 | ADJUSTSTRETCH | Set the timestretch value to 1.4x. | ||
ADJUSTSTRETCH1.5 | ADJUSTSTRETCH | Set the timestretch value to 1.5x. | ||
AUTODETECT_FILL | Set the video fill mode to "Autodetect" | Current video fill mode is "Autodetect" | If the video output device is not HW-accelerated | |
CANCELPLAYLIST | Cancel the playlist in progress | Playlist currently active | ||
CREATEPBPVIEW | Open a Live TV Picture-by-Picture window | New PbP window possible (at least 1 free recorder, PiP not currently active, etc.) | ||
CREATEPIPVIEW | Open a Live TV Picture-in-Picture window | New PiP window possible (at least 1 free recorder, PbP not currently active, etc.) | ||
DEBUGOSD | Toggle OSD playback information overlay | |||
DIALOG_JUMPREC_X_0 | Open the "Jump to Recorded Program" dialog | |||
DISABLEEXTTEXT | Disable external text subtitles | External text subtitles currently not being displayed | Recording contains external text subtitles | |
DISABLEFORCEDSUBS | Disable forced subtitles | Forced subtitles current not enabled | Recording contains A/V or text subtitles | |
DISABLESUBS | Disable subtitle display | Subtitles currently not being displayed | Recording contains subtitles | |
DISABLEUPMIX | Disable audio upmixer | Upmixing currently not enabled | Audio output device supports upmixing | |
DISABLEVISUALISATION | Disable audio visualizer | Video output device supports visualization | ||
EDIT | Edit channel (if playing Live TV), or edit recording (otherwise) | Currently playing Live TV | Not playing DVD or BD | |
ENABLEEXTTEXT | Enable external text subtitles | External text subtitles currently being displayed | Recording contains external text subtitles | |
ENABLEFORCEDSUBS | Ensable forced subtitles | Forced subtitles current enabled | Recording contains A/V or text subtitles | |
ENABLESUBS | Enable subtitle display | Subtitles currently being displayed | Recording contains subtitles | |
ENABLEUPMIX | Enable audio upmixer | Upmixing currently enabled | Audio output device supports upmixing | |
FINDER | Open "Program Finder" window | |||
GUIDE | Open "Program Guide" window | |||
JUMPFFWD | Jump ahead | Current recording allows jumping | ||
JUMPPREV | Jump to previously played recording | Previously played recording exists | ||
JUMPRECPBP | Open a Recording Picture-by-Picture window | New PbP window possible (at least 1 available PbP slot, PiP not currently active, etc.) | ||
JUMPRECPIP | Open a Recording Picture-in-Picture window | New PiP window possible (at least 1 available PiP slot, PbP not currently active, etc.) | ||
JUMPRWND | Jump back | Current recording allows jumping | ||
JUMPTODVDCHAPTERMENU | Jump to DVD chapter menu | Currently watching a DVD | ||
JUMPTODVDROOTMENU | Jump to DVD root menu | Currently watching a DVD | ||
JUMPTODVDTITLEMENU | Jump to DVD title menu | Currently watching a DVD | ||
JUMPTOPOPUPMENU | Jump to BluRay popup menu | Currently watching a BD | ||
NEXTPIPWINDOW | Change active PiP/PbP window | Currently displaying at least 1 PiP/PbP window | ||
PAUSE | Toggle play/pause state | Currently paused (not playing) | ||
PREVCHAN | Jump to previous channel | Watching Live TV, and there exists a previously watched channel | ||
QUEUETRANSCODE | Start or stop a transcoding job for the current recording (using default transcoding profile) | Transcoding job currently active for this recording | Currently watching a recorded program | |
QUEUETRANSCODE_AUTO | Start or stop a transcoding job for the current recording (using auto-detect transcoding profile) | Transcoding job currently active for this recording | Currently watching a recorded program | |
QUEUETRANSCODE_HIGH | Start or stop a transcoding job for the current recording (using high-quality transcoding profile) | Transcoding job currently active for this recording | Currently watching a recorded program | |
QUEUETRANSCODE_LOW | Start or stop a transcoding job for the current recording (using low-quality transcoding profile) | Transcoding job currently active for this recording | Currently watching a recorded program | |
QUEUETRANSCODE_MEDIUM | Start or stop a transcoding job for the current recording (using medium-quality transcoding profile) | Transcoding job currently active for this recording | Currently watching a recorded program | |
SCHEDULE | Open "Edit Recording Schedule" window | |||
SELECTSCAN_0 | SELECTSCAN_ | Set video scan type to "Detect" | Current scan type is "Detect" | |
SELECTSCAN_1 | SELECTSCAN_ | Set video scan type to "Interlaced (Normal)" | Current scan type is "Interlaced (Normal)" | |
SELECTSCAN_2 | SELECTSCAN_ | Set video scan type to "Interlaced (Reversed)" | Current scan type is "Interlaced (Reversed)" | |
SELECTSCAN_3 | SELECTSCAN_ | Set video scan type to "Progressive" | Current scan type is "Progressive" | |
SWAPPIP | Swap PiP/PbP windows | Currently displaying at least 2 PiP/PbP windows | ||
TOGGLEASPECT0 | TOGGLEASPECT | Change aspect ratio to "Off" | Current aspect ratio is "Off" | |
TOGGLEASPECT1 | TOGGLEASPECT | Change aspect ratio to "4:3" | Current aspect ratio is "4:3" | |
TOGGLEASPECT2 | TOGGLEASPECT | Change aspect ratio to "16:9" | Current aspect ratio is "16:9" | |
TOGGLEASPECT3 | TOGGLEASPECT | Change aspect ratio to "14:9" | Current aspect ratio is "14:9" | |
TOGGLEASPECT4 | TOGGLEASPECT | Change aspect ratio to "2.35:1" | Current aspect ratio is "2.35:1" | |
TOGGLEAUDIOSYNC | Bring up the audio synchronization adjustment dialog. | |||
TOGGLEAUTOEXPIRE | Turn auto-expire on or off for this recording | Auto-expire is currently enabled for this recording | Curently watching a recorded or in-progress recording | |
TOGGLEBROWSE | Toggle channel browse mode | "Browse/change channels from Channel Group" setting is enabled | ||
TOGGLECOMMSKIP0 | TOGGLECOMMSKIP | Set commercial auto-skip to "Off" | Current auto-skip mode is "Off" | Curently watching a recorded or in-progress recording |
TOGGLECOMMSKIP1 | TOGGLECOMMSKIP | Set commercial auto-skip to "On" | Current auto-skip mode is "On" | Curently watching a recorded or in-progress recording |
TOGGLECOMMSKIP2 | TOGGLECOMMSKIP | Set commercial auto-skip to "Notify" | Current auto-skip mode is "Notify" | Curently watching a recorded or in-progress recording |
TOGGLEFILL0 | TOGGLEFILL | Set the video fill mode to "Off" | Current video fill mode is "Off" | |
TOGGLEFILL1 | TOGGLEFILL | Set the video fill mode to "Half" | Current video fill mode is "Half" | |
TOGGLEFILL2 | TOGGLEFILL | Set the video fill mode to "Full" | Current video fill mode is "Full" | |
TOGGLEFILL3 | TOGGLEFILL | Set the video fill mode to "H.Stretch" | Current video fill mode is "H.Stretch" | |
TOGGLEFILL4 | TOGGLEFILL | Set the video fill mode to "V.Stretch" | Current video fill mode is "V.Stretch" | |
TOGGLEFILL5 | TOGGLEFILL | Set the video fill mode to "H.Fill" | Current video fill mode is "H.Fill" | |
TOGGLEFILL6 | TOGGLEFILL | Set the video fill mode to "V.Fill" | Current video fill mode is "V.Fill" | |
TOGGLEMANUALZOOM | Toggle manual zoom mode | |||
TOGGLENIGHTMODE | Enable or disable night mode | Night mode currently enabled | Video output device supports picture attributes | |
TOGGLEPBPMODE | Close Picture-by-Picture windows | PbP currently enabled | ||
TOGGLEPICCONTROLS0 | TOGGLEPICCONTROLS | Adjust picture attribute - "None" | Picture attributes currently set to studio levels | Video output device supports this picture attribute |
TOGGLEPICCONTROLS1 | TOGGLEPICCONTROLS | Adjust picture attribute - "Brightness" | Picture attributes currently set to studio levels | Video output device supports this picture attribute |
TOGGLEPICCONTROLS2 | TOGGLEPICCONTROLS | Adjust picture attribute - "Contrast" | Picture attributes currently set to studio levels | Video output device supports this picture attribute |
TOGGLEPICCONTROLS3 | TOGGLEPICCONTROLS | Adjust picture attribute - "Color" | Picture attributes currently set to studio levels | Video output device supports this picture attribute |
TOGGLEPICCONTROLS4 | TOGGLEPICCONTROLS | Adjust picture attribute - "Hue" | Picture attributes currently set to studio levels | Video output device supports this picture attribute |
TOGGLEPICCONTROLS6 | TOGGLEPICCONTROLS | Adjust picture attribute - "Volume" | Picture attributes currently set to studio levels | Video output device supports this picture attribute |
TOGGLEPIPMODE | Close Picture-in-Picture windows | PiP currently enabled | ||
TOGGLEPIPSTATE | Switch between Picture-in-Picture and Picture-by-Picture mode | Currently displaying PiP (not PbP) | PiP/PbP currently active, and other mode supported | |
TOGGLESLEEP30 | TOGGLESLEEP | Enter sleep mode in 30 minutes | ||
TOGGLESLEEP60 | TOGGLESLEEP | Enter sleep mode in 60 minutes | ||
TOGGLESLEEP90 | TOGGLESLEEP | Enter sleep mode in 90 minutes | ||
TOGGLESLEEP120 | TOGGLESLEEP | Enter sleep mode in 120 minutes | ||
TOGGLESLEEPON | TOGGLESLEEP | Turn sleep mode off | Sleep mode currently enabled | |
TOGGLESTRETCH | Toggle timestretch mode | |||
TOGGLESTUDIOLEVELS | TOGGLEPICCONTROLS | Adjust picture attribute - "Studio levels" | Picture attributes currently set to studio levels | Video output device supports this picture attribute |
TOGGLESUBDELAY | Bring up the adjust subtitle delay dialog | Text subtitles are currently enabled | ||
TOGGLESUBZOOM | Bring up the adjust subtitle zoom dialog | Subtitles are currently enabled | ||
TOGGLETTM | Toggle teletext menu | Teletext menu is available | ||
VIEWSCHEDULED | Open "Upcoming Recordings" window |
(list of available actiongroups)
Action Group | Action Group Description | List of Actions |
3D | 3D display modes | 3DNONE 3DSIDEBYSIDE 3DSIDEBYSIDEDISCARD 3DTOPANDBOTTOM 3DTOPANDBOTTOMDISCARD |
ADJUSTSTRETCH | Timestretch options | ADJUSTSTRETCH ADJUSTSTRETCH0.5 ADJUSTSTRETCH0.9 ADJUSTSTRETCH1.0 ADJUSTSTRETCH1.1 ADJUSTSTRETCH1.2 ADJUSTSTRETCH1.3 ADJUSTSTRETCH1.4 ADJUSTSTRETCH1.5 |
CHANGROUP_ | List of available channel groups (provided the "Browse/change channels from Channel Group" setting is enabled) | Varies |
DEINTERLACER_ | List of available deinterlacers | Varies |
JUMPTOCHAPTER | List of available chapters | Varies |
JUMPTOTITLE | List of available titles | Varies |
SELECTAUDIO_ | List of available audio tracks | Varies |
SELECTCC608_ | List of available EIA-608 closed caption tracks | Varies |
SELECTCC708_ | List of available EIA-708 closed caption tracks | Varies |
SELECTRAWTEXT_ | List of available text subtitle tracks | Varies |
SELECTSCAN_ | List of available video scan modes | SELECTSCAN_0 SELECTSCAN_3 SELECTSCAN_1 SELECTSCAN_2 |
SELECTSUBTITLE_ | List of available A/V subtitle tracks | Varies |
SELECTTTC_ | List of available teletext caption tracks | Varies |
SWITCHTOANGLE | List of available DVD/BD angles | Varies |
SWITCHTOINPUT_ | List of available input cards within Live TV | Varies |
SWITCHTOSOURCE_ | List of available input sources within Live TV | Varies |
TOGGLEASPECT | Video aspect ratio modes | TOGGLEASPECT0 TOGGLEASPECT1 TOGGLEASPECT3 TOGGLEASPECT2 TOGGLEASPECT4 |
TOGGLECOMMSKIP | Commercial skip modes | TOGGLECOMMSKIP0 TOGGLECOMMSKIP2 TOGGLECOMMSKIP1 |
TOGGLEFILL | Video fill modes | TOGGLEFILL0 TOGGLEFILL1 TOGGLEFILL2 TOGGLEFILL3 TOGGLEFILL4 TOGGLEFILL5 TOGGLEFILL6 |
TOGGLEPICCONTROLS | Video picture control modes | TOGGLEPICCONTROLS0 TOGGLEPICCONTROLS1 TOGGLEPICCONTROLS2 TOGGLEPICCONTROLS3 TOGGLEPICCONTROLS4 TOGGLESTUDIOLEVELS TOGGLEPICCONTROLS6 |
TOGGLESLEEP | Sleep modes | TOGGLESLEEPON TOGGLESLEEP30 TOGGLESLEEP60 TOGGLESLEEP90 TOGGLESLEEP120 |
VISUALISER_ | Audio visualizer modes | Varies |
(list of available actions)
Action Name | Action Group | Action Description | show="active" condition | show="inactive" condition |
DIALOG_CUTPOINT_CLEARMAP_0 | ||||
DIALOG_CUTPOINT_CUTTOBEGINNING_0 | ||||
DIALOG_CUTPOINT_CUTTOEND_0 | ||||
DIALOG_CUTPOINT_DELETE_0 | ||||
DIALOG_CUTPOINT_INVERTMAP_0 | ||||
DIALOG_CUTPOINT_LOADCOMMSKIP_0 | ||||
DIALOG_CUTPOINT_MOVENEXT_0 | ||||
DIALOG_CUTPOINT_MOVEPREV_0 | ||||
DIALOG_CUTPOINT_NEWCUT_0 | ||||
DIALOG_CUTPOINT_REDO_0 | ||||
DIALOG_CUTPOINT_REVERTEXIT_0 | ||||
DIALOG_CUTPOINT_REVERT_0 | ||||
DIALOG_CUTPOINT_SAVEEXIT_0 | ||||
DIALOG_CUTPOINT_SAVEMAP_0 | ||||
DIALOG_CUTPOINT_UNDO_0 |