btn element 

Specifies a mapping for a button on a content, dialog or menu page.

Element Information

Element type: xsd:complexType

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

Schema name: Simple Content Format

Elements and Attributes

Parent Elements

content element

dialog element

menu element

Child Elements

None.

Attributes

Attribute

Type

Required

Description

Possible values

key

ButtonKey (simple type)

Required

The key to map to this dialog button. For more information about the ButtonKey simple type, see the Remarks section in this topic.

"enter"

"back"

"home"

"left"

"right"

target

xsd:positiveInteger

Required

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

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

Remarks

The ButtonKey simple type defines the type that contains valid values for the key attribute of the btn element. The valid values are "enter", "back", "left" and "right" representing the set of buttons that can be overridden from the recommended set required to interact with SCF content (the recommended set also includes "menu", "up" and "down", which always have fixed functions). Software on each device maps the physical buttons to the virtual buttons. When a user clicks a virtual button that is specified in a btn element, the device navigates to the page by using the content identifier that matches the value of the corresponding target attribute.

Each virtual button can be referenced only once on each page.

The default behavior for the "enter" button on a menu page is to select the item; it can not be overriden on a menu page with the exception of changing the selectaction attribute of the menu element.

The default behavior of the "back" button is to return the user to the last visited menu page in the stack, or to the home screen when there are no more menu pages in the stack. This allows for a "level up" style behavior where the user can quickly and easily return to the previous "level" of the gadget. However, this algorithm is not always applicable to all gadgets, and it may be necessary to override the behavior of the back button by using the btn element. As with all btn element targets, the content ID must specify the specific ID to navigate to; relative IDs are not supported.

Usage Example

The following code example displays text and button keys as a user interface.

<body>
    <dialog id="300" title="Windows Power Alert" imgid="Warning">
        <txt align="l">Windows has detected that your battery is running low.  Would you like to go into hibernate?</txt>
        <btn key="Enter" target="10">Yes</btn>
        <btn key="Back" target="11">No</btn>
    </dialog>
</body>

Schema Definition

The following schema defines text and two button keys.

<xsd:element name="btn">
    <xsd:complexType>
        <xsd:simpleContent>
            <xsd:extension base="xsd:string">
                <xsd:attribute name="key" type="ButtonKey" use="required" />
                <xsd:attribute name="target" type="xsd:positiveInteger" use="required" />
            </xsd:extension>
        </xsd:simpleContent>
    </xsd:complexType>
</xsd:element>

See Also

Concepts

content element
dialog element