Difference between revisions of "Menu Root Object"

From MSX - Wiki
Jump to navigation Jump to search
 
(67 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
     "name": "Content Name",   
 
     "name": "Content Name",   
 
     "version": "1.0.0",  
 
     "version": "1.0.0",  
 +
    "reference": "http://link.to.menu",
 
     "flag": "content_flag",   
 
     "flag": "content_flag",   
 
     "reuse": true,
 
     "reuse": true,
 
     "cache": true,
 
     "cache": true,
 
     "restore": true,
 
     "restore": true,
 +
    "refocus": 0,
 +
    "transparent": 0,
 +
    "style": "default",
 
     "logo": "http://link.to.image",   
 
     "logo": "http://link.to.image",   
 +
    "logoSize": "large", 
 
     "headline": "Menu Headline",  
 
     "headline": "Menu Headline",  
 
     "background": "http://link.to.image",   
 
     "background": "http://link.to.image",   
Line 13: Line 18:
 
     "dictionary": "http://link.to.dictionary",
 
     "dictionary": "http://link.to.dictionary",
 
     "menu": [],
 
     "menu": [],
−
     "options": null
+
    "action": null,
 +
    "data": null,
 +
    "ready": null,
 +
     "options": null  
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
{| class="wikitable sortable"
 
{| class="wikitable sortable"
 +
|+ Property syntax of menu root object
 
|-
 
|-
 
! Property !! Type !! Default Value !! Mandatory !! Since Version !! class="unsortable" | Description  
 
! Property !! Type !! Default Value !! Mandatory !! Since Version !! class="unsortable" | Description  
Line 26: Line 35:
 
| <code>version</code> || <code>string</code> || <code>null</code> || No || data-sort-value=0|0.1.0 ||  
 
| <code>version</code> || <code>string</code> || <code>null</code> || No || data-sort-value=0|0.1.0 ||  
 
The version of the content. This property is only used if the menu data is loaded at startup and can be used to add a content version. This value is displayed in the about panel of the Media Station X application.
 
The version of the content. This property is only used if the menu data is loaded at startup and can be used to add a content version. This value is displayed in the about panel of the Media Station X application.
 +
|-
 +
| <code>reference</code> || <code>string</code> || <code>null</code> || No || data-sort-value=134|'''0.1.134''' ||
 +
The reference of the menu data. This property is only used if the menu data is loaded at startup and can be used to load the actual data (i.e. non-startup related data) from another location. This allows you to keep the start menu data more dynamic (e.g. by reloading it on the fly).
 +
 +
'''Note: Please note that most properties (e.g. <code>logo</code>, <code>headline</code>, <code>menu</code>, <code>options</code>, etc.) are ignored if this property is set, because the corresponding values are provided by the  referenced data. Additionally, please note that it is also possible to indicate request actions instead of URLs (e.g. <code>"request:interaction:{DATA_ID}@{URL}"</code>).'''
 
|-
 
|-
 
| <code>flag</code> || <code>string</code> || <code>null</code> || No || data-sort-value=120|'''0.1.120''' ||  
 
| <code>flag</code> || <code>string</code> || <code>null</code> || No || data-sort-value=120|'''0.1.120''' ||  
 
A custom content flag that can be evaluated by plugins and/or servers.
 
A custom content flag that can be evaluated by plugins and/or servers.
 +
 +
Since version '''0.1.144''', this flag can also be used to replace (and reload) the menu data at runtime. For more information, please see [[Replace Action]].
 +
 +
Since version '''0.1.153''', this flag can also be used to refocus menu items by using the <code>refocus</code> property.
 
|-
 
|-
 
| <code>reuse</code> || <code>boolean</code> || <code>true</code> || No || data-sort-value=0|0.1.0 ||  
 
| <code>reuse</code> || <code>boolean</code> || <code>true</code> || No || data-sort-value=0|0.1.0 ||  
Line 38: Line 56:
 
| <code>restore</code> || <code>boolean</code> || <code>true</code> || No || data-sort-value=120|'''0.1.120''' ||  
 
| <code>restore</code> || <code>boolean</code> || <code>true</code> || No || data-sort-value=120|'''0.1.120''' ||  
 
Indicates if the menu data is restorable. If this property is set to <code>false</code>, the menu data (and the related content data) is not restored when the application returns from a link action.
 
Indicates if the menu data is restorable. If this property is set to <code>false</code>, the menu data (and the related content data) is not restored when the application returns from a link action.
 +
|-
 +
| <code>refocus</code> || <code>number</code>{{pipe}}<code>boolean</code> || <code>0</code> || No || data-sort-value=153|'''0.1.153''' ||
 +
Indicates if a menu item should be refocused. The <code>flag</code> property is used to cache and restore the focus value.
 +
 +
* <code>0</code>{{pipe}}<code>false</code>: No menu item is refocused.
 +
* <code>1</code>{{pipe}}<code>true</code>: The cached focused menu item is refocused by using the item ID (and the item index as fallback).
 +
* <code>2</code>: The cached focused menu item is refocused by using the item index only.
 +
 +
'''Note: To use this property, the <code>flag</code> property must also be set, otherwise this property is ignored. If a menu item has a <code>focus</code> property set to <code>true</code>, the focus value is only cached but not restored.'''
 +
|-
 +
| <code>transparent</code> || <code>number</code>{{pipe}}<code>boolean</code> || <code>0</code> || No || data-sort-value=142|'''0.1.142''' ||
 +
Indicates if the corresponding content background is transparent. By default, the content background is set to a semi-transparent gray to darken the underlying video/image and make the content more visible.
 +
 +
* <code>0</code>{{pipe}}<code>false</code>: The content background is not transparent.
 +
* <code>1</code>{{pipe}}<code>true</code>: The content background is transparent.
 +
* <code>2</code>: The content background is only transparent if no video/audio is active or the active video/audio has set the extended property <code>"control:transparent"</code> to <code>"true"</code>. For more information, please see [[Extended Properties]].
 +
 +
'''Note: If the active menu item has its own <code>transparent</code> property, this property is ignored. If the corresponding content or content page has its own <code>transparent</code> property and becomes active, this property is also ignored.'''
 +
|-
 +
| <code>style</code> || <code>string</code> || <code>"default"</code> || No || data-sort-value=142|'''0.1.142''' ||
 +
The style of the menu.
 +
 +
* <code>"default"</code>: The menu is displayed in default style (the menu background is set to a semi-transparent gray and the menu separator is visible).
 +
* <code>"flat"</code>: The menu is displayed in flat style (the menu background and the menu separator are hidden).
 +
* <code>"flat-separator"</code>: The menu is displayed in flat separator style (the menu background is hidden and the menu separator is visible).
 +
* <code>"overlay"</code>: The menu is displayed in overlay style (the menu background is set to a dark overlay and the menu separator is hidden).
 +
* <code>"overlay-separator"</code>: The menu is displayed in overlay separator style (the menu background is set to a dark overlay and the menu separator is visible).
 
|-
 
|-
 
| <code>logo</code> || <code>string</code> || <code>null</code> || No || data-sort-value=60|'''0.1.60''' ||  
 
| <code>logo</code> || <code>string</code> || <code>null</code> || No || data-sort-value=60|'''0.1.60''' ||  
−
The logo image of the menu. This property can be used to display a logo instead of a headline. The area of the logo is 416x96 (WxH) pixels at layout resolution 720p. The logo is sized to fill the entire height (by keeping the ratio) and is positioned on the left side.
+
The logo image of the menu. This property can be used to display a logo instead of a headline. Please see property <code>logoSize</code> for the size of the area.
 +
|-
 +
| <code>logoSize</code> || <code>string</code> || <code>"large"</code> || No || data-sort-value=130|'''0.1.130''' ||
 +
The size of the logo area of the menu.
 +
 
 +
* <code>"small"</code>: The area of the logo is 416x48 (WxH) pixels at layout resolution 720p (624x72 at 1080p).
 +
* <code>"large"</code>: The area of the logo is 416x96 (WxH) pixels at layout resolution 720p (624x144 at 1080p).
 +
 
 +
The logo is sized to fill the entire height (by keeping the ratio) and is positioned on the left side.
 +
 
 +
'''Note: This property is ignored if no <code>logo</code> property is set.'''
 
|-
 
|-
 
| <code>headline</code> || <code>string</code> || <code>null</code> || No || data-sort-value=0|0.1.0 ||  
 
| <code>headline</code> || <code>string</code> || <code>null</code> || No || data-sort-value=0|0.1.0 ||  
Line 47: Line 102:
 
'''Note: Since version 0.1.60, this property is ignored if a <code>logo</code> property is set.'''
 
'''Note: Since version 0.1.60, this property is ignored if a <code>logo</code> property is set.'''
  
−
This property supports inline expressions. For more information, please see [[Inline Expressions]].
+
This property supports [[Inline Expressions]].
 
|-
 
|-
 
| <code>background</code> || <code>string</code> || <code>null</code> || No || data-sort-value=0|0.1.0 ||  
 
| <code>background</code> || <code>string</code> || <code>null</code> || No || data-sort-value=0|0.1.0 ||  
Line 54: Line 109:
 
| <code>extension</code> || <code>string</code> || <code>null</code> || No || data-sort-value=82|'''0.1.82''' ||  
 
| <code>extension</code> || <code>string</code> || <code>null</code> || No || data-sort-value=82|'''0.1.82''' ||  
 
The extension of each corresponding content screen. This property can be used to display a small label in the upper right corner of each corresponding content screen (e.g. to show the logged in user, the current date/time, etc.). This property has no effect if the corresponding content contains its own extension.
 
The extension of each corresponding content screen. This property can be used to display a small label in the upper right corner of each corresponding content screen (e.g. to show the logged in user, the current date/time, etc.). This property has no effect if the corresponding content contains its own extension.
−
 
+
This property supports [[Inline Expressions]] and [[Live Inline Expressions]].
−
This property supports inline expressions and live inline expressions. For more information about the inline expressions, please see [[Inline Expressions]]. For more information about the live inline expressions, please see [[Live Inline Expressions]].
 
 
|-
 
|-
 
| <code>dictionary</code> || <code>string</code> || <code>null</code> || No || data-sort-value=120|'''0.1.120''' ||  
 
| <code>dictionary</code> || <code>string</code> || <code>null</code> || No || data-sort-value=120|'''0.1.120''' ||  
−
A link to a dictionary file. This property is only used if the menu data is loaded at startup and can be used to setup a dictionary. A dictionary can be used to translate the application user interface. For more information, please see [[Dictionary Structure]].
+
A URL to a dictionary file. This property is only used if the menu data is loaded at startup and can be used to setup a dictionary. A dictionary can be used to translate the application user interface. For more information, please see [[Dictionary Structure]].
 
|-
 
|-
 
| <code>menu</code> || <code>array</code> || <code>null</code> || '''Yes''' || data-sort-value=0|0.1.0 ||  
 
| <code>menu</code> || <code>array</code> || <code>null</code> || '''Yes''' || data-sort-value=0|0.1.0 ||  
 
An array of menu items. Please see [[Menu Item Object]] for the data structure. This property is mandatory, because without it, no menu items can be displayed.
 
An array of menu items. Please see [[Menu Item Object]] for the data structure. This property is mandatory, because without it, no menu items can be displayed.
 +
|-
 +
| <code>action</code> || <code>string</code> || <code>null</code> || No || data-sort-value=0|0.1.0 ||
 +
The start action that is executed if the menu data is loaded at startup. This property is part of the hidden features. For more information, please see [[Start Action]].
 +
|-
 +
| <code>data</code> || <code>object</code> || <code>null</code> || No || data-sort-value=0|0.1.0 ||
 +
The additional data of the start action that is used if the action is executed. This property is part of the hidden features. For more information, please see [[Start Action]].
 +
|-
 +
| <code>ready</code> || <code>object</code> || <code>null</code> || No || data-sort-value=142|'''0.1.142''' ||
 +
A special ready object that can contain an <code>action</code> property (of type <code>string</code>) and an action-related <code>data</code> property (of type <code>object</code>). It can be used to execute an action when the menu is ready. Please see [[Internal Actions]] for possible values.
 
|-
 
|-
 
| <code>options</code> || <code>object</code> || <code>null</code> || No || data-sort-value=120|'''0.1.120''' ||  
 
| <code>options</code> || <code>object</code> || <code>null</code> || No || data-sort-value=120|'''0.1.120''' ||  
 
A special content page object that is displayed in a content panel if a menu item is selected and the menu button is pressed. The availability of options for the current selected item is indicated in the lower right corner of the content screen. Please see [[Content Page Object]] for the data structure.
 
A special content page object that is displayed in a content panel if a menu item is selected and the menu button is pressed. The availability of options for the current selected item is indicated in the lower right corner of the content screen. Please see [[Content Page Object]] for the data structure.
  
−
'''Note: If the selected menu item has its own options property, this property is ignored.'''
+
Since version '''0.1.130''', you can also set a [[Content Root Object]] as options.
 +
 
 +
'''Note: If the selected menu item has its own <code>options</code> property, this property is ignored.'''
 
|}
 
|}
  
 
== Related Hidden Features ==
 
== Related Hidden Features ==
−
* [[Settings Menu Item]]
+
* [[Start Action]]
 +
* [[Focus Separator]]
 +
* [[Option Shortcut]]
 +
* [[Replace Action]]
 +
 
 +
== See also ==
 +
* [[Menu Item Object]]
 +
* [[Menu Examples]]

Latest revision as of 09:50, 22 June 2023

{ 
    "name": "Content Name",   
    "version": "1.0.0", 
    "reference": "http://link.to.menu", 
    "flag": "content_flag",  
    "reuse": true,
    "cache": true,
    "restore": true,
    "refocus": 0,
    "transparent": 0,
    "style": "default",
    "logo": "http://link.to.image",   
    "logoSize": "large",   
    "headline": "Menu Headline", 
    "background": "http://link.to.image",   
    "extension": "Content Extension", 
    "dictionary": "http://link.to.dictionary",
    "menu": [],
    "action": null,
    "data": null,
    "ready": null,
    "options": null    
}
Property syntax of menu root object
Property Type Default Value Mandatory Since Version Description
name string null No 0.1.0

The name of the content. This property is only used if the menu data is loaded at startup and can be used to set the content name. This value is displayed in the about panel of the Media Station X application.

version string null No 0.1.0

The version of the content. This property is only used if the menu data is loaded at startup and can be used to add a content version. This value is displayed in the about panel of the Media Station X application.

reference string null No 0.1.134

The reference of the menu data. This property is only used if the menu data is loaded at startup and can be used to load the actual data (i.e. non-startup related data) from another location. This allows you to keep the start menu data more dynamic (e.g. by reloading it on the fly).

Note: Please note that most properties (e.g. logo, headline, menu, options, etc.) are ignored if this property is set, because the corresponding values are provided by the referenced data. Additionally, please note that it is also possible to indicate request actions instead of URLs (e.g. "request:interaction:{DATA_ID}@{URL}").

flag string null No 0.1.120

A custom content flag that can be evaluated by plugins and/or servers.

Since version 0.1.144, this flag can also be used to replace (and reload) the menu data at runtime. For more information, please see Replace Action.

Since version 0.1.153, this flag can also be used to refocus menu items by using the refocus property.

reuse boolean true No 0.1.0

Indicates if the menu data can be reused. If this property is set to false, the menu data is recreated each time it is displayed.

cache boolean true No 0.1.58

Indicates if the menu data is being cached. This property can be used to disable the cache feature.

restore boolean true No 0.1.120

Indicates if the menu data is restorable. If this property is set to false, the menu data (and the related content data) is not restored when the application returns from a link action.

refocus number|boolean 0 No 0.1.153

Indicates if a menu item should be refocused. The flag property is used to cache and restore the focus value.

  • 0|false: No menu item is refocused.
  • 1|true: The cached focused menu item is refocused by using the item ID (and the item index as fallback).
  • 2: The cached focused menu item is refocused by using the item index only.

Note: To use this property, the flag property must also be set, otherwise this property is ignored. If a menu item has a focus property set to true, the focus value is only cached but not restored.

transparent number|boolean 0 No 0.1.142

Indicates if the corresponding content background is transparent. By default, the content background is set to a semi-transparent gray to darken the underlying video/image and make the content more visible.

  • 0|false: The content background is not transparent.
  • 1|true: The content background is transparent.
  • 2: The content background is only transparent if no video/audio is active or the active video/audio has set the extended property "control:transparent" to "true". For more information, please see Extended Properties.

Note: If the active menu item has its own transparent property, this property is ignored. If the corresponding content or content page has its own transparent property and becomes active, this property is also ignored.

style string "default" No 0.1.142

The style of the menu.

  • "default": The menu is displayed in default style (the menu background is set to a semi-transparent gray and the menu separator is visible).
  • "flat": The menu is displayed in flat style (the menu background and the menu separator are hidden).
  • "flat-separator": The menu is displayed in flat separator style (the menu background is hidden and the menu separator is visible).
  • "overlay": The menu is displayed in overlay style (the menu background is set to a dark overlay and the menu separator is hidden).
  • "overlay-separator": The menu is displayed in overlay separator style (the menu background is set to a dark overlay and the menu separator is visible).
logo string null No 0.1.60

The logo image of the menu. This property can be used to display a logo instead of a headline. Please see property logoSize for the size of the area.

logoSize string "large" No 0.1.130

The size of the logo area of the menu.

  • "small": The area of the logo is 416x48 (WxH) pixels at layout resolution 720p (624x72 at 1080p).
  • "large": The area of the logo is 416x96 (WxH) pixels at layout resolution 720p (624x144 at 1080p).

The logo is sized to fill the entire height (by keeping the ratio) and is positioned on the left side.

Note: This property is ignored if no logo property is set.

headline string null No 0.1.0

The headline of the menu.

Note: Since version 0.1.60, this property is ignored if a logo property is set.

This property supports Inline Expressions.

background string null No 0.1.0

The background image that is used if no other background is set at lower levels. If the menu data is loaded at startup, this background image is used as default.

extension string null No 0.1.82

The extension of each corresponding content screen. This property can be used to display a small label in the upper right corner of each corresponding content screen (e.g. to show the logged in user, the current date/time, etc.). This property has no effect if the corresponding content contains its own extension. This property supports Inline Expressions and Live Inline Expressions.

dictionary string null No 0.1.120

A URL to a dictionary file. This property is only used if the menu data is loaded at startup and can be used to setup a dictionary. A dictionary can be used to translate the application user interface. For more information, please see Dictionary Structure.

menu array null Yes 0.1.0

An array of menu items. Please see Menu Item Object for the data structure. This property is mandatory, because without it, no menu items can be displayed.

action string null No 0.1.0

The start action that is executed if the menu data is loaded at startup. This property is part of the hidden features. For more information, please see Start Action.

data object null No 0.1.0

The additional data of the start action that is used if the action is executed. This property is part of the hidden features. For more information, please see Start Action.

ready object null No 0.1.142

A special ready object that can contain an action property (of type string) and an action-related data property (of type object). It can be used to execute an action when the menu is ready. Please see Internal Actions for possible values.

options object null No 0.1.120

A special content page object that is displayed in a content panel if a menu item is selected and the menu button is pressed. The availability of options for the current selected item is indicated in the lower right corner of the content screen. Please see Content Page Object for the data structure.

Since version 0.1.130, you can also set a Content Root Object as options.

Note: If the selected menu item has its own options property, this property is ignored.

Related Hidden Features[edit]

See also[edit]

Retrieved from "https://msx.benzac.de/wiki/index.php?title=Menu_Root_Object&oldid=3032"