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
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>