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 Compact menus, which allow the user to collect and reorder their most commonly used menu items into a more convenient list and hierarchy.
- 1 Overview
- 2 Menu file description
- 2.1 The menu element
- 2.2 The item element
- 2.3 The itemlist element
- 2.4 The include element
- 2.5 Themed Menu file search path
- 3 Customizable menus
A Themed Menu is a simple XML description of a hierarchical menu,
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
text attribute is displayed as the menu
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.
<menu text="My Menu Title"> <menu text="My Submenu Title"> ... </menu> <menu text="My Other Submenu Title"> ... </menu> </menu>
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.
text attribute is required (otherwise the menu name
will be blank).
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.
<item action="PAUSE" text="Play" show="active" /> <item action="PAUSE" text="Pause" show="inactive" />
This is the name of the action to execute when the menu item is selected. See below for a comprehensive description of available actions.
action attribute is the only required attribute of
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.
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
typically used in two situations. The first situation is when the
action toggles some state, and you want different
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" />
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).
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
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.
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.
This is the name of the action group to expand. See below for a comprehensive description of available actiongroups.
actiongroup attribute is the only required 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.
include element allows rudimentary modularization by
including the contents of another Themed Menu XML file. It contains a
single required attribute,
<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.
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||Default text (active)||Default text (inactive)||show="active" condition
|3DNONE||3D||Deactivate 3D mode||None||If the video output device supports stereoscopic modes|
|3DSIDEBYSIDE||3D||Activate side-by-side 3D mode||Side by Side||The video output device supports stereoscopic modes|
|3DSIDEBYSIDEDISCARD||3D||Activate discard side-by-side 3D mode||Discard Side by Side||The video output device supports stereoscopic modes|
|3DTOPANDBOTTOM||3D||Activate top-and-bottom 3D mode||Top and Bottom||The video output device supports stereoscopic modes|
|3DTOPANDBOTTOMDISCARD||3D||Activate discard top-and-bottom 3D mode||Discard Top and Bottom||The video output device supports stereoscopic modes|
|ADJUSTSTRETCH||ADJUSTSTRETCH||Bring up the timestretch adjustment dialog||Adjust|
|ADJUSTSTRETCH0.5||ADJUSTSTRETCH||Set the timestretch value to 0.5x||0.5x|
|ADJUSTSTRETCH0.9||ADJUSTSTRETCH||Set the timestretch value to 0.9x||0.9x|
|ADJUSTSTRETCH1.0||ADJUSTSTRETCH||Set the timestretch value to 1.0x||1.0x|
|ADJUSTSTRETCH1.1||ADJUSTSTRETCH||Set the timestretch value to 1.1x||1.1x|
|ADJUSTSTRETCH1.2||ADJUSTSTRETCH||Set the timestretch value to 1.2x||1.2x|
|ADJUSTSTRETCH1.3||ADJUSTSTRETCH||Set the timestretch value to 1.3x||1.3x|
|ADJUSTSTRETCH1.4||ADJUSTSTRETCH||Set the timestretch value to 1.4x||1.4x|
|ADJUSTSTRETCH1.5||ADJUSTSTRETCH||Set the timestretch value to 1.5x||1.5x|
|AUTODETECT_FILL||Set the video fill mode to "Autodetect"||Auto Detect||Current video fill mode is "Autodetect"||The video output device is not HW-accelerated|
|CANCELPLAYLIST||Cancel the playlist in progress||Cancel Playlist||Playlist currently active|
|CREATEPBPVIEW||Open a Live TV Picture-by-Picture window||Open Live TV PBP||New PbP window possible (at least 1 free recorder, PiP not currently active, etc.)|
|CREATEPIPVIEW||Open a Live TV Picture-in-Picture window||Open Live TV PIP||New PiP window possible (at least 1 free recorder, PbP not currently active, etc.)|
|DEBUGOSD||Toggle OSD playback information overlay||Playback Data|
|DIALOG_JUMPREC_X_0||Open the "Jump to Recorded Program" dialog||Recorded Program|
|DISABLEEXTTEXT||Disable external text subtitles||Disable External Subtitles||External text subtitles currently not being displayed||Recording contains external text subtitles|
|DISABLEFORCEDSUBS||Disable forced subtitles||Disable Forced Subtitles||Forced subtitles current not enabled||Recording contains A/V or text subtitles|
|DISABLESUBS||Disable subtitle display||Disable Subtitles||Subtitles currently not being displayed||Recording contains subtitles|
|DISABLEUPMIX||Disable audio upmixer||Disable Audio Upmixer||Upmixing currently not enabled||Audio output device supports upmixing|
|DISABLEVISUALISATION||Disable audio visualizer||None||Video output device supports visualization|
|EDIT||Edit channel (if playing Live TV), or edit recording (otherwise)||Edit Channel||Edit Recording||Currently playing Live TV||Not playing DVD or BD|
|ENABLEEXTTEXT||Enable external text subtitles||Enable External Subtitles||External text subtitles currently being displayed||Recording contains external text subtitles|
|ENABLEFORCEDSUBS||Ensable forced subtitles||Enable Forced Subtitles||Forced subtitles current enabled||Recording contains A/V or text subtitles|
|ENABLESUBS||Enable subtitle display||Enable Subtitles||Subtitles currently being displayed||Recording contains subtitles|
|ENABLEUPMIX||Enable audio upmixer||Auto Detect||Upmixing currently enabled||Audio output device supports upmixing|
|FINDER||Open "Program Finder" window||Program Finder|
|GUIDE||Open "Program Guide" window||Program Guide|
|JUMPFFWD||Jump ahead||Jump Ahead||Current recording allows jumping|
|JUMPPREV||Jump to previously played recording||Last recording in the form Title: Subtitle||Previously played recording exists|
|JUMPRECPBP||Open a Recording Picture-by-Picture window||Open Recording PBP||New PbP window possible (at least 1 available PbP slot, PiP not currently active, etc.)|
|JUMPRECPIP||Open a Recording Picture-in-Picture window||Open Recording PIP||New PiP window possible (at least 1 available PiP slot, PbP not currently active, etc.)|
|JUMPRWND||Jump back||Jump Back||Current recording allows jumping|
|JUMPTODVDCHAPTERMENU||Jump to DVD chapter menu||DVD Chapter Menu||Currently watching a DVD|
|JUMPTODVDROOTMENU||Jump to DVD root menu||DVD Root Menu||Top Menu||Currently watching a DVD|
|JUMPTODVDTITLEMENU||Jump to DVD title menu||DVD Title Menu||Currently watching a DVD|
|JUMPTOPOPUPMENU||Jump to BluRay popup menu||Popup menu||Currently watching a BD|
|NEXTPIPWINDOW||Change active PiP/PbP window||Change Active Window||Currently displaying at least 1 PiP/PbP window|
|PAUSE||Toggle play/pause state||Play||Pause||Currently paused (not playing)|
|PREVCHAN||Jump to previous channel||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)||Stop Transcoding||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)||Autodetect||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)||High Quality||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)||Low Quality||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)||Medium Quality||Transcoding job currently active for this recording||Currently watching a recorded program|
|SCHEDULE||Open "Edit Recording Schedule" window||Edit Recording Schedule|
|SELECTSCAN_0||SELECTSCAN_||Set video scan type to "Detect"||Detect||Current scan type is "Detect"|
|SELECTSCAN_1||SELECTSCAN_||Set video scan type to "Interlaced (Normal)"||Interlaced (Normal)||Current scan type is "Interlaced (Normal)"|
|SELECTSCAN_2||SELECTSCAN_||Set video scan type to "Interlaced (Reversed)"||Interlaced (Reversed)||Current scan type is "Interlaced (Reversed)"|
|SELECTSCAN_3||SELECTSCAN_||Set video scan type to "Progressive"||Progressive||Current scan type is "Progressive"|
|SWAPPIP||Swap PiP/PbP windows||Swap Windows||Currently displaying at least 2 PiP/PbP windows|
|TOGGLEASPECT0||TOGGLEASPECT||Change aspect ratio to "Off"||Off||Current aspect ratio is "Off"|
|TOGGLEASPECT1||TOGGLEASPECT||Change aspect ratio to "4:3"||4:3||Current aspect ratio is "4:3"|
|TOGGLEASPECT2||TOGGLEASPECT||Change aspect ratio to "16:9"||Current aspect ratio is "16:9"||16:9|
|TOGGLEASPECT3||TOGGLEASPECT||Change aspect ratio to "14:9"||14:9||Current aspect ratio is "14:9"|
|TOGGLEASPECT4||TOGGLEASPECT||Change aspect ratio to "2.35:1"||2.35||Current aspect ratio is "2.35:1"|
|TOGGLEAUDIOSYNC||Bring up the audio synchronization adjustment dialog||Adjust Audio Sync|
|TOGGLEAUTOEXPIRE||Turn auto-expire on or off for this recording||Turn Auto-Expire OFF||Turn Auto-Expire ON||Auto-expire is currently enabled for this recording||Curently watching a recorded or in-progress recording|
|TOGGLEBROWSE||Toggle channel browse mode||Toggle Browse Mode||"Browse/change channels from Channel Group" setting is enabled|
|TOGGLECOMMSKIP0||TOGGLECOMMSKIP||Set commercial auto-skip to "Off"||Off||Current auto-skip mode is "Off"||Curently watching a recorded or in-progress recording|
|TOGGLECOMMSKIP1||TOGGLECOMMSKIP||Set commercial auto-skip to "On"||On||Current auto-skip mode is "On"||Curently watching a recorded or in-progress recording|
|TOGGLECOMMSKIP2||TOGGLECOMMSKIP||Set commercial auto-skip to "Notify"||Notify||Current auto-skip mode is "Notify"||Curently watching a recorded or in-progress recording|
|TOGGLEFILL0||TOGGLEFILL||Set the video fill mode to "Off"||Off||Current video fill mode is "Off"|
|TOGGLEFILL1||TOGGLEFILL||Set the video fill mode to "Half"||Half||Current video fill mode is "Half"|
|TOGGLEFILL2||TOGGLEFILL||Set the video fill mode to "Full"||Full||Current video fill mode is "Full"|
|TOGGLEFILL3||TOGGLEFILL||Set the video fill mode to "H.Stretch"||H.Stretch||Current video fill mode is "H.Stretch"|
|TOGGLEFILL4||TOGGLEFILL||Set the video fill mode to "V.Stretch"||V.Stretch||Current video fill mode is "V.Stretch"|
|TOGGLEFILL5||TOGGLEFILL||Set the video fill mode to "H.Fill"||H.Fill||Current video fill mode is "H.Fill"|
|TOGGLEFILL6||TOGGLEFILL||Set the video fill mode to "V.Fill"||V.Fill||Current video fill mode is "V.Fill"|
|TOGGLEMANUALZOOM||Toggle manual zoom mode||Manual Zoom Mode|
|TOGGLENIGHTMODE||Enable or disable night mode||Disable Night Mode||Enable Night Mode||Night mode currently enabled||Video output device supports picture attributes|
|TOGGLEPBPMODE||Close Picture-by-Picture windows||Close PBP(s)||PbP currently enabled|
|TOGGLEPICCONTROLS0||TOGGLEPICCONTROLS||Adjust picture attribute - "None"||None||Picture attributes currently set to studio levels||Video output device supports this picture attribute|
|TOGGLEPICCONTROLS1||TOGGLEPICCONTROLS||Adjust picture attribute - "Brightness"||Brightness||Picture attributes currently set to studio levels||Video output device supports this picture attribute|
|TOGGLEPICCONTROLS2||TOGGLEPICCONTROLS||Adjust picture attribute - "Contrast"||Contrast||Picture attributes currently set to studio levels||Video output device supports this picture attribute|
|TOGGLEPICCONTROLS3||TOGGLEPICCONTROLS||Adjust picture attribute - "Color"||Color||Picture attributes currently set to studio levels||Video output device supports this picture attribute|
|TOGGLEPICCONTROLS4||TOGGLEPICCONTROLS||Adjust picture attribute - "Hue"||Hue||Picture attributes currently set to studio levels||Video output device supports this picture attribute|
|TOGGLEPICCONTROLS6||TOGGLEPICCONTROLS||Adjust picture attribute - "Volume"||Volume||Picture attributes currently set to studio levels||Video output device supports this picture attribute|
|TOGGLEPIPMODE||Close Picture-in-Picture windows||Close PIP(s)||PiP currently enabled|
|TOGGLEPIPSTATE||Switch between Picture-in-Picture and Picture-by-Picture mode||Switch to PBP||Switch to PIP||Currently displaying PiP (not PbP)||PiP/PbP currently active, and other mode supported|
|TOGGLESLEEP30||TOGGLESLEEP||Enter sleep mode in 30 minutes||30 minute(s)|
|TOGGLESLEEP60||TOGGLESLEEP||Enter sleep mode in 60 minutes||60 minute(s)|
|TOGGLESLEEP90||TOGGLESLEEP||Enter sleep mode in 90 minutes||90 minute(s)|
|TOGGLESLEEP120||TOGGLESLEEP||Enter sleep mode in 120 minutes||120 minute(s)|
|TOGGLESLEEPON||TOGGLESLEEP||Turn sleep mode off||Sleep Off||Sleep mode currently enabled|
|TOGGLESTRETCH||Toggle timestretch mode||Toggle|
|TOGGLESTUDIOLEVELS||TOGGLEPICCONTROLS||Adjust picture attribute - "Studio levels"||Studio Levels||Picture attributes currently set to studio levels||Video output device supports this picture attribute|
|TOGGLESUBDELAY||Bring up the adjust subtitle delay dialog||Adjust Subtitle Delay||Text subtitles are currently enabled|
|TOGGLESUBZOOM||Bring up the adjust subtitle zoom dialog||Adjust Subtitle Zoom||Subtitles are currently enabled|
|TOGGLETTM||Toggle teletext menu||Toggle Teletext Menu||Teletext menu is available|
|VIEWSCHEDULED||Open "Upcoming Recordings" window||Upcoming Recordings|
The following is a list of available action groups, including the list of actions each action group expands to.
|Action Group||Action Group Description||List of Actions|
|3D||3D display modes|| 3DNONE |
|ADJUSTSTRETCH||Timestretch options|| ADJUSTSTRETCH |
|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 |
|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 |
|TOGGLECOMMSKIP||Commercial skip modes|| TOGGLECOMMSKIP0 |
|TOGGLEFILL||Video fill modes|| TOGGLEFILL0 |
|TOGGLEPICCONTROLS||Video picture control modes|| TOGGLEPICCONTROLS0 |
|TOGGLESLEEP||Sleep modes|| TOGGLESLEEPON |
|VISUALISER_||Audio visualizer modes||Varies|
The Playback OSD compact menu is read from menu_playback_compact.xml, and is displayed during playback via the MENUCOMPACT action (mapped by default to the 'Alt+M' key).
The default OSD compact menu is defined as follows:
<menu text="Playback Compact Menu"> <!-- Insert desired actions here. End by including the main menu so that all actions are ultimately available. The actions may need more descriptive text outside the context of the original menu; if so, it's best to find a string from tv_play.cpp that is already being translated. --> <include file="menu_playback.xml" /> </menu>
Note the inclusion of the main Playback OSD menu at the end. This mechanism is especially useful for remote controls with a limited number of buttons. One can map the menu button to the MENUCOMPACT action, and the original menu can be reached via the compact menu.
The cutlist editor menu is read from menu_cutlist.xml, and is displayed during cutlist editing via the MENU action (mapped by default to the 'M' key).
The cutlist editor actions are not part of any action groups at present.
Note: in the
text attribute for the Undo and Redo
actions, the placeholder '%1' will be replaced with a string
representing the action to undo or redo.
|Action Name||Action Description||show="active" condition
|DIALOG_CUTPOINT_CLEARMAP_0||Clear cutlist, i.e. remove all cutlist marks|
|DIALOG_CUTPOINT_CUTTOBEGINNING_0||Cut to beginning||Edit point is within the initial non-cut region|
|DIALOG_CUTPOINT_CUTTOEND_0||Cut to end||Edit point is within the final non-cut region|
|DIALOG_CUTPOINT_DELETE_0||Delete current region, i.e. delete this cut region or join surrounding cut regions||Edit point is within a cut region|
|DIALOG_CUTPOINT_INVERTMAP_0||Reverse cuts, i.e. change cut regions to non-cut regions and vice versa|
|DIALOG_CUTPOINT_LOADCOMMSKIP_0||Load detected commercials, replacing any existing cut regions|
|DIALOG_CUTPOINT_MOVENEXT_0||Move the start of the next cut, or the end of the current cut, to the current edit point||Edit point is within a non-cut region||(if the action is possible in the current context)|
|DIALOG_CUTPOINT_MOVEPREV_0||Move the end of the previous cut, or the start of the next cut, to the current edit point||Edit point is within a non-cut region||(if the action is possible in the current context)|
|DIALOG_CUTPOINT_NEWCUT_0||Add a new cut point or region||Edit point is within a non-cut region|
|DIALOG_CUTPOINT_REDO_0||Redo a previously undone action||The undo stack has at least one action to redo|
|DIALOG_CUTPOINT_REVERTEXIT_0||Exit cutlist editor without saving|
|DIALOG_CUTPOINT_REVERT_0||Revert all changes|
|DIALOG_CUTPOINT_SAVEEXIT_0||Save changes and exit|
|DIALOG_CUTPOINT_SAVEMAP_0||Save changes and continue|
|DIALOG_CUTPOINT_UNDO_0||Undo a previously undone action||The undo stack has at least one action to undo|
The cutlist editor compact menu is read from menu_cutlist_compact.xml, and is displayed during cutlist editing via the MENUCOMPACT action (mapped by default to the 'Alt+M' key).
The default cutlist editor compact menu is defined as follows:
<menu text="Edit Cut Points (Compact)"> <!-- Insert desired actions here. End by including the main menu so that all actions are ultimately available. The actions may need more descriptive text outside the context of the original menu; if so, it's best to find a string from tv_play.cpp that is already being translated. --> <include file="menu_cutlist.xml" /> </menu>