Themed Menus

From MythTV Official Wiki
Revision as of 14:54, 27 July 2013 by Jstichnoth (Talk | contribs)

Jump to: navigation, search

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.


Important.png 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.

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.

The menu element

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.


Important.png 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.


Important.png 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.

Customizable menus

Currently there are four implementations of Themed Menus.

In the tables below that describe the available actions,

Playback OSD menu

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

Playback OSD compact menu

Cutlist editor menu

(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

Cutlist editor compact menu