item element 

Describes a single item in the containing menu, as specified by a menu element.

Element Information

Element type: xsd:complexType

Namespace: https://schemas.microsoft.com/sideshow/2006/scf

Schema name: Simple Content Format

Elements and Attributes

Parent Elements

menu element

Child Elements

br element

Attributes

Attribute

Type

Required

Description

Possible values

id

xsd:positiveInteger

Optional

An identifier value for the menu item, which is required to be unique within the menu page. Use this identifier to indicate the selected menu item when a context menu is invoked, thereby providing this information to the gadgets that are processing application events. This information can be particularly useful when multiple menu items have the same target attribute value.

The value 0 (zero) is reserved and is the default.

Any positive integer that is unique within the menu page.

target

xsd:positiveInteger

Required

The content identifier of the page to navigate to when the this element is selected.

Any positive integer that corresponds to the content identifier of a page.

imgid

xsd:positiveInteger

Optional

The content identifier of the binary image data to be used as an icon for the item, and rendered to the left of the corresponding menu item text.

The size of the rendered image is determined by the device, although the recommended size is 16x16 pixels.

Any positive integer that corresponds to the content identifier of the relevant binary image data.

def

MenuItemDefault (simple type)

Optional

Used to specify whether this menu item is the default menu item.

If multiple menu items are set as the default, the first such menu item is treated as the default.

If no menu items are set as the default, the first enabled menu item is treated as the default.

"1" (This menu item is the default.)

"0" (This menu item is not the default.)

enable

MenuItemEnabled (simple type)

Optional

Used to specify whether or not this menu item is enabled.

Devices should render menu items that are not enabled as dimmed and non-interactive, or they should not be rendered at all.

"1" (This menu item is enabled.)

"0" (This menu item is not enabled.)

menuid

xsd:positiveInteger

Optional

The content identifier of a menu page that serves as the context menu for this menu item.

This attribute is ignored for menu items on context menu pages.

The content identifier associated with the relevant context menu page.

Remarks

The text to be displayed as the menu item is contained within this element. The font for this text is determined by the device.

The item element uses the MenuItemDefault simpleType element to specify the valid values for its def attribute. The valid values are "0" and "1", designating that this menu item is not the default menu item and that this menu item is the default menu item, respectively.

The item element uses the MenuItemEnabled simpleType element to specify the valid values for its enable attribute. The valid values are "0" and "1", designating that this menu item is not enabled and that this menu item is enabled, respectively.

If a page the user is viewing or has viewed previously is updated, the device attempts to maintain the previously selected item on the updated page, as long as the item's id attribute is unchanged. If the updated page contains an item with the def attribute set to 1, that item is always selected.

The item element may contain only one (1) child br element, which enables the menu item to be displayed on—at most—two lines. If a menu item contains a br element, it always renders on two lines, with the start of the second line being the text immediately following the br element. Each line of text in a menu item is truncated if it does not fit on a single line. Note that the selected menu item may wrap onto two lines if it does not contain a br element; this enables the user to view additional menu item text while fitting more single-line menu items on a screen. If a gadget requires specific control over which text appears on the second line, the gadget should use an explicit br element to separate the lines.

Usage Example

<body>
    <menu id="100" title="Main Menu">
        <item id="1" target="5" imgid="1" menuid="200">Media</item>
        <item id="2" target="6" imgid="2" def="1">Calendar</item>
        <item id="3" target="7">E-mail</item>
        <div/>
        <item id="4" Target="8" enable="0">Settings</item>
    </menu>
</body>

Schema Definition

<xsd:element name="item">
    <xsd:complexType name="ItemType" mixed="true">
        <xsd:sequence minOccurs="0" maxOccurs="1">
            <xsd:element ref="br" />
        </xsd:sequence>
        <xsd:attribute name="id" type="xsd:positiveInteger" use="optional" />
        <xsd:attribute name="target" type="xsd:positiveInteger" use="required" />
        <xsd:attribute name="imgid" type="xsd:positiveInteger" use="optional" />
        <xsd:attribute name="def" type="MenuItemDefault" use="optional" />
        <xsd:attribute name="enable" type="MenuItemEnabled" use="optional" />
        <xsd:attribute name="menuid" type="xsd:positiveInteger" use="optional" />
    </xsd:complexType>
    <xsd:unique name="UniqueId">
        <xsd:selector xpath="./item" />
        <xsd:field xpath="@id" />
    </xsd:unique>
</xsd:element>

<xsd:simpleType name="MenuItemDefault">
    <xsd:restriction base="xsd:nonNegativeInteger">
        <xsd:minInclusive value="0" />
        <xsd:maxInclusive value="1" />
    </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="MenuItemEnabled">
    <xsd:restriction base="xsd:nonNegativeInteger">
        <xsd:minInclusive value="0" />
        <xsd:maxInclusive value="1" />
    </xsd:restriction>
</xsd:simpleType>

See Also

Concepts

menu element
br element