Windows Driver Kit: Windows SideShow
Parsing the Simple Content Format
The Simple Content Format (SCF) is an XML-based content format for the Windows SideShow platform. The SCF format exposes three types of content in the schema: menu pages, content pages, and dialog pages. A menu page is essentially a list box that displays a list of selectable items from which a user can make a selection. A content page is composed of formatted text and images, whereas a dialog page is a specialized version of a content page that provides the user with a choice among selectable options, similar to a dialog box. The page types are mutually exclusive: they cannot be combined, and therefore each content ID must represent only one type of page.
For a sample implementation of an SCF renderer, install the simulator for Windows SideShow, which is available in the Windows SDK. The simulator shows the Microsoft firmware implementation and can be used as a guideline for how to render SCF pages.
Note Some elements of SCF resemble elements in HTML, and in most cases have similar functionality.
Image Support in the SCF
The SCF allows images to be used in all of its content pages. These images are specified in a manner similar to HTML, where they are referenced by their content ID from the XML. Therefore, images are provided as binary data in their own content IDs.
Device manufacturers should report the list of supported image formats when the ISideShowDriver::OnGetDeviceCapabilities method is called with the SIDESHOW_CAPABILITY_SUPPORTED_IMAGE_FORMATS device capability.
Page Layout
Page layout must be constructed in a top-down flow. The endpoint renderer should use the full width of the screen, but should lay out the page so that it does not require any horizontal scrolling. Vertical scrolling has no limit. Use the UP and DOWN buttons on the device for vertical scrolling.
Note Windows SideShow-compatible devices do not provide an alternate means to navigate large lists. By its very nature, a device should not set a limit unless it is imposed by an outside influence, such as the hardware limitation imposed by screen width. Instead, a developer who writes gadgets can paginate a long list and use navigation links to enable the user to navigate from one page to another, backward or forward.
Navigation Mechanisms for Vertical Scrolling
Developers have some choices about how they implement scrolling in their devices. One choice is line by line and another is page by page. It depends on the content being navigated. For a list, line by line may be more appropriate, whereas a content page may be more efficient scrolling page by page.
Developers may want to create a smart scrolling implementation that examines the page object that will need vertical scroll capability, and scroll the object in segments. For example, if you have a long list and the screen size of the device is three inches, the device could scroll only the amount of items in the list that will fit on one screen.
Another navigation mechanism the developer can use is to set the scroll speed faster the longer the user holds the button down. With this mechanism the user can easily scan items while scrolling.
A good practice is to allow users to see how far they have scrolled. Users can get a sense of where the content on the display appears within the page. This is typically done by displaying a scrollbar on the side of the screen.
Adding Emphasis to Text
Developers can use emphasis to make certain words stand out from the surrounding text. A typical type of emphasis is to add highlighting to text. If bold is not available for the device, an alternate solution is to switch or invert the background and foreground colors, so that a white background with black text changes to a black background with white text. Other emphases include italics, bold, and underline.
Tip If the renderer for the device cannot render emphasis, consider not providing a work-around at all, because the work-around could cause more confusion than plain text.
If a basic device does not have any formatting capabilities, developers can parse the XML on the driver and generate formatted results to appear on the screen or translate into different formats.
Content Pages
Content pages consist of text and images. There are implicit line breaks between each text or image element.
Typically, button elements on a content page are not rendered on the screen of a device, although they do override the actions that would be taken when the specified button is pressed. There is one exception to this rule: on devices with soft buttons, the associated button text can be rendered to show the behavior that is associated with each button. Content pages can allow for the override of the LEFT, RIGHT, BACK, and ENTER buttons.
Menu Pages
When creating a layout for a menu page, it is important to have an item selected when the menu page first renders to the screen. The SCF allows a menu item to be specified as the one selected by default when first rendering the page; the device should choose the first item with the def attribute, and make that the default selected item. If none of the items in the content specify the def attribute, the first enabled item in the menu is selected. The selected item must be easily distinguishable from a regular menu item. The best contrast for menu items in black and white is the reverse color scheme: if the item has black text with a white background then the selection should be rendered with the opposite colors. Menu items can be rendered on at most two lines, depending on whether they specify an explicit line break (the br element) in their text. Items that specify a line break should always be rendered on two lines, with the content on the second line being the text immediately following the br element. Items without an explicit break should be rendered on only one line. If text is too long to fit onto a single line, it should be truncated. When a single-line menu item is selected, however, it should wrap onto two lines to allow maximum visibility for any truncated text.
When a user returns to a previously viewed page, the context should be persisted so that the user views the page as it was when it was previously viewed. For example, the user should return to the previous page with the previous item selected, as determined by the id attribute of that item. If the menu page was refreshed while the user was not viewing the page, the selected item should continue to be the item with the same ID as the previously selected item. If there is no item with the same ID on the refreshed page, follow the guidelines above for the first view of the menu page to determine which item should be selected.
When rendering icons next to menu items, the icon should be displayed to the left of the item.
Menu pages can override the LEFT, RIGHT, and BACK buttons to navigate to specific pages; however, the ENTER button is reserved for selecting items.
Dialog Pages
Dialog pages are intended to have a similar layout to the familiar Win32 MessageBox. They specify a title, optional icon, and message text. In addition, a dialog page can specify buttons from which the user can make a selection. The recommended practice for dialog pages is to show buttons with their label text onscreen as soft buttons. Rather than directly map a button press to the specified target, as is done on content pages, a dialog page should allow the user to navigate among the onscreen buttons using UP, DOWN, LEFT, and RIGHT, and navigate to the selected button’s target only after ENTER has been pressed.
Context Menus
A context menu is defined in the same manner as a regular SCF menu page. The difference between a full menu page and a context menu is, primarily, that you cannot invoke a context menu on a context menu. In terms of rendering differences, the menu page uses the entire screen for the menu, whereas the context menu typically is an overlay that doesn't fully replace the content that was previously displayed. This page should be a transient page, preferably displayed in a pop-up window, while at the same time maintaining current page context. If the device already has a native menu user interface (UI), use it instead of creating your own. A menu item is invoked when the Select button is pressed.
A context menu has the same XML structure and elements as a menu page. The distinguishing factor is that it is referenced by one of the context menu attributes from another SCF page. Note that when selecting items from context menus, a Context Menu event (SCF_EVENT_CONTEXTMENU) should be fired.
Context menus should always contain Back and Home items that are provided by the device. These items should be appended to any context menu that is provided by the gadget. In cases where the gadget does not provide a context menu, a menu generated by the device containing only Back and Home should be provided. The behavior for the BACK button is described below. The behavior for the HOME button should be to return the user to the main device home page.
Navigation
The user navigates among pages by clicking a button or selecting a menu item. The SCF provides a navigation tree structure similar to that employed by websites. The top-level node of the tree is the root of the structure and represents the first or home page (content ID 1) that is displayed for that gadget. The branches are links to other page items that make up the rest of the tree structure. Each branch node can have other branches off of it, such as targets in a menu page, virtual buttons on a content page, or menus. Each node has a content ID and contains content that the user wants to view on the device. As the user navigates the tree, the endpoint renderer displays the content of each node that is reached.
Links to other pages consist of a reference to their content ID. If the target content ID is not available, a SIDESHOW_CONTENT_MISSING_EVENT event should be sent to the computer to request the content. No navigation, menu, or context menu events should be sent if the target content is not available. On a successful navigation from one page to the next (with the exception of selecting menu items), a navigation event should be sent back to the gadget. The navigation event is represented by the event ID SCF_EVENT_NAVIGATION and contains the SCF_NAVIGATION_EVENT structure as a payload.
Gadget Home Page
A content ID value of 1 indicates that the page is the top-level page. You should always display this page when entering the gadget. A constant for this value is provided in WindowsSideShow.h as CONTENT_ID_HOME.
BACK Button Behavior
The desired behavior for the BACK button is to behave similar to a "level up", taking the user to the previous hierarchical level of the gadget. The endpoint should maintain a stack of the visited menu pages, because menu pages are considered the markers of each level. Note that gadgets can override the behavior for the BACK button on any page by specifying a btn element with the page to navigate to. The following list describes best practices for managing a page stack:
Page State
The endpoint should restore the state of a page when executing a back operation. For example, a selected item on a previous page should remain selected and in view when the user performs a back operation. If the user had also scrolled to an item in a list (or on a content page), the visible portion of the page should stay the same when the user returns to that page.
Application Events for the SCF
The SCF defines three application events that must be sent to the computer when it is online. They are navigation events, menu action events, and context menu action events.
A navigation event occurs when a user successfully navigates to another page. It is identified by the enumeration value SCF_EVENT_NAVIGATION, which is passed as the value of the dwEventId member of the structure. A menu action event occurs when a user selects an item from a menu page. The menu action event is identified by the SCF_EVENT_MENUACTION enumeration value for dwEventId. Finally, the context menu action event is sent when a user selects an item from a context menu, and is identified by the SCF_EVENT_CONTEXTMENU enumeration value.
Each event has its own associated data structure that contains the data that is provided as the bEventData member of the APPLICATION_EVENT_DATA structure. A description of these events and their data structures follows.
C++ Parameter Structure: SCF_CONTEXTMENU_EVENT
The following C++ structure is defined in the file WindowsSideShow.h and shows the required parameters for the SCF_EVENT_CONTEXTMENU event. This structure is provided as the bEventData member of the APPLICATION_EVENT_DATA structure when posting application events to the platform. The cbEventData member of the APPLICATION_EVENT_DATA structure should be set to the size of the SCF_CONTEXTMENU_EVENT structure.
typedef struct tagSCF_CONTEXTMENU_EVENT
{
CONTENT_ID PreviousPage;
CONTENT_ID TargetPage;
UINT32 PreviousItemId;
CONTENT_ID MenuPage;
UINT32 MenuItemId;
} SCF_CONTEXTMENU_EVENT, *PSCF_CONTEXTMENU_EVENT;
The following table describes the members of the SCF_CONTEXTMENU_EVENT structure.
| Parameter | Type | Description |
|---|
| PreviousPage | CONTENT_ID | The content identifier of the page on which the context menu was invoked. |
| TargetPage | CONTENT_ID | The content identifier of the page to which the user is navigating. |
| PreviousItemId | UINT32 | The value that represents the menu item identifier on which the context menu was invoked. If the context menu was not invoked on a menu page, this value should be set to 0. |
| MenuPage | CONTENT_ID | The content identifier of the context menu on which the user selected an item. |
| MenuItemId | UINT32 | The menu item identifier of the item that was selected on the context menu. |
For more information about context menu events, see Application Events in the Microsoft Windows SideShow SDK.
C++ Parameter Structure: SCF_MENUACTION_EVENT
The following C++ structure is defined in the file WindowsSideShow.h and shows the required parameters for the SCF_EVENT_MENUACTION event. This structure is provided as the bEventData member of the APPLICATION_EVENT_DATA structure when posting application events to the platform. The cbEventData member of the APPLICATION_EVENT_DATA structure should be set to the size of the SCF_MENUACTION_EVENT structure.
typedef struct tagSCF_MENUACTION_EVENT
{
CONTENT_ID PreviousPage;
CONTENT_ID TargetPage;
UINT32 Button;
UINT32 ItemId;
} SCF_MENUACTION_EVENT, *PSCF_MENUACTION_EVENT;
The following table describes the members of the SCF_MENUACTION_EVENT structure.
| Parameter | Type | Description |
|---|
| PreviousPage | CONTENT_ID | The content identifier of the menu page on which an item was selected. |
| TargetPage | CONTENT_ID | The content identifier of the page to which the user is navigating. |
| Button | UINT32 | The enumeration value that represents the button that the user pressed to select the item.
Button values are defined in the SCF_BUTTON_IDS enumeration in WindowsSideShow,h.
|
| ItemId | UINT32 | The item identifier value of the selected menu item. If the menu item has no item identifier, this value should be 0. |
For more information about menu action events, see Application Events in the Microsoft Windows SideShow SDK.
C++ Parameter Structure: SCF_NAVIGATION_EVENT
The following C++ structure is defined in the file WindowsSideShow.h and shows the required parameters for the SCF_EVENT_NAVIGATION event. This structure is provided as the bEventData member of the APPLICATION_EVENT_DATA structure when posting application events to the platform. The cbEventData member of the APPLICATION_EVENT_DATA struct should be set to the size of the SCF_NAVIGATION_EVENT structure.
typedef struct tagSCF_NAVIGATION_EVENT
{
CONTENT_ID PreviousPage;
CONTENT_ID TargetPage;
UINT32 Button;
} SCF_NAVIGATION_EVENT, *PSCF_NAVIGATION_EVENT;
The following table describes the members of the SCF_NAVIGATION_EVENT structure.
| Parameter | Type | Description |
|---|
| PreviousPage | CONTENT_ID | The content identifier of the page on which the navigation occurred. |
| TargetPage | CONTENT_ID | The content identifier of the page to which the user is navigating. |
| Button | UINT32 | The enumeration value that represents the button that caused the navigation to occur.
Button values are defined in the SCF_BUTTON_IDS enumeration in WindowsSideShow,h.
|
For more information about navigation events see Application Events in the Microsoft Windows SideShow SDK.
Elements of SCF
The following table provides a list of elements that are available in SCF.
| Element Name | Description | Usage |
|---|
| body | The body element is the top-level element in a Simple Content Format XML specification. It contains one of the three basic types of content allowed by the Simple Content Format: menu pages, general content pages, and dialog pages. | <body>
<content>
<txt>Windows SideShow!</txt>
</content>
</body>
|
| br | The br element specifies that a line break should occur at the specified location in the rendered content. It can be nested within other elements.
The element should always be specified as "<br/>" (though <br></br> is still legal). It can be used in a menu item to cause it to wrap to multiple lines.
| <txt>Text block 1
<br/>
Text block 2</txt>
<item target=10>Line 1
<br/>
Line2</item>
|
| btn | The btn element specifies a mapping to one of a predefined number of virtual buttons that are equivalent across all devices; they cause navigation to the specified page ID.
The text of the button is specified in the element’s text section (and is not necessarily visible, but might be used in a help screen).
| <btn target=10 key="right">Forward</btn> |
| clr | The clr element specifies that the text contained within this element should be rendered in the specified color or as close to the specified color as the device can achieve. If a device cannot support color, it can use other methods of differentiating the text, or it can do nothing. This tag is valid only within a txt element. | <txt rgb="FFFFFF">White Text <clr rgb="000000">Black Text</clr> White Text</txt> |
| content | The content element specifies a collection of static text and images, laid out in a flow manner. | <content id="200"
title="Now Playing"
bg="50" bgfit="s"
menuid="1000">
<txt align="c"
wrap="0"><em>
Song Title</em>
</txt>
</content>
|
| dialog | The dialog element specifies text, buttons, and possibly a single image to be displayed on a page that requires a response from the user. | <dialog id="300"
title=" Power
Alert" imgid="100">
<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>
|
| div | The div element specifies that a dividing line should occur at the specified point in a sequence of rendered menu items. | <menu id="100" title="Main Menu">
<item id="1" target="6"
imgid="2" def="1">
Calendar
</item>
<div/>
<item id="2" target="8" enable="0">
Settings
</item>
</menu>
|
| em | The em element specifies that the text contained within this element should be emphasized. A device manufacturer can choose exactly what constitutes an emphasis format. We recommend bold type.
If a device is not capable of rendering emphasized text with formatting, it can use pre and post characters to delineate the emphasized text. This tag is valid only within a txt element.
| <txt>Windows SideShow gadgets can potentially save an <em>hour</em> of time per day!</txt> |
| img | The img element specifies information about an image that is included within the content page, including its content identifier, rendering preferences, and an alternative string that describes the image. | <img id=5 />
<img id=5></img>
<img id=5 align="c" fit="screen" alt="[Full Screen Image]" />
|
| item | The item element describes a single item in the containing menu, as specified by a menu element. | <menu id="100" title="Main Menu">
<item id="1" target="6"
imgid="2" def="1">
Calendar
</item>
</menu>
|
| menu | The menu element specifies the list of menu items that constitutes a menu page. | <menu id="100" title="Main Menu">
<item id="1" target="6"
imgid="2" def="1">
Calendar
</item>
</menu>
|
| txt | The txt element specifies that the text contained within it should be rendered on the associated device according to the alignment, wrap, and color characteristics provided by the corresponding attributes. | <txt>
This is the default text.
</txt>
<txt align="c" wrap="0">
Album Artist That Is
Truncated
</txt>
<txt rgb="0F0F0F">
This text is colored.
</txt>
|
In addition to the usage in the previous table, the menu pages, content pages, and dialog pages have more in-depth capabilities, which are described in the following sections and in the Windows SDK. For more information about the Simple Content Format, please see the Simple Content Format Reference in the Windows SDK.
Parsing Menu Pages
Menus provide fast, easy navigation through a list of items. Selecting an item in a menu can cause navigation to a new content page. Menus can also be used as context menus, when invoked in the context of a different content page.
Understanding Menus
A menu is a collection of ordered menu items with each item displayed in the order in which it was declared. In addition to displaying text for each menu item, developers can add an icon for each menu item. The icon will be displayed to the left of that item's text. A complete menu item can also include a target ID to navigate to on item selection. Icons are provided in their own content items, and should be in a common image format such as JPEG, GIF, or BMP. The endpoint renderer determines which icon to use by retrieving the number value of the imgid attribute in the item element.
Using the menu Element
The menu element contains a list of menu items. The attributes of a menu are shown in the following table.
| Attribute | Type | Required
or
Optional
| Description |
|---|
| id | Number | Required | The ID number of the current page. |
| selectaction | String | Optional | The action that the gadget will take when an item is selected in the menu. There are two options: either to navigate to the target immediately, or to display a context menu. All the menu items must operate in the same manner. An item can have both a menu ID and a target, but only one of these is invoked when the user selects the item based on the default action. The single exception is that if the item does not have a menu ID, it defaults to the target. The values are:
target – navigates to the content specified by the target of the menu item. This is the default.
menuid – invokes the context menu for the item.
|
| title | String | Optional | The text that will be displayed in the title bar.
The default is the name of the gadget.
|
Using the item Element
The item element describes a single item in the menu. It contains the text of the menu item within the tag. The font is determined by the device.
| Attribute | Type | Required
or
Optional
| Description |
|---|
| id | Number | Optional | The ID number of the menu item; it is required to be unique only within the menu page.
The default is 0 and is reserved.
|
| target | Number | Optional | When an item is selected, navigates to the content ID specified by the target attribute.
If a target is not specified, the default target is dependent on whether this menu is being used as a menu page or a context menu:
For an item on a menu page, the default target is the current page.
For an item on a context menu, if no target is specified, the renderer checks for a value in the target attribute of the selected item; if one exists then that becomes the default page. Otherwise, the current page becomes the default.
|
| imgid | Number | Optional | The image identifier of the icon to appear next to the menu item.
The default value is no image.
|
| def | 0,1 | Optional | If the value is 1, this is the default selected item on the page.
The default value is 0.
|
| enable | 0,1 | Optional | If the value is 1, this item is enabled. If the value is 0, the item is disabled.
If the device cannot display variations of color to indicate that an item is disabled, then the item should not be rendered at all. Typically, a disabled item is rendered in gray, and is not selectable.
The default value is 1.
|
| menuid | Number | Optional | Contains the content ID of the menu page that will act as the context menu for this item. This allows for per-item context menus. The value of this attribute is ignored when a menu is used as a context menu. Basically, a context menu cannot nest within another context menu. |
Using the div Element
The div element inserts a dividing line in the menu. It has no additional attributes, and might not be supported by all devices.
Examples
The first example illustrates a first page with a menu that displays several menu items.
<body>
<menu id="1" title="Main Menu">
<item id="1" target="5" imgid="100" menuid="200">Media</ item>
<item id="2" target="6" imgid="101" def="1">Calendar</item>
<item id="3" Target="7">E-mail</item>
<div/>
<item id="4" Target="8" enable="0">Settings</item>
</menu>
</body>
The second example illustrates the day's appointments.
<body>
<menu id="6" title="Today’s Appointments">
<item target="11" imgid="102" menuid="201">10:00a-11:00a Design Meeting</item>
<item target="12" imgid="102" menuid="201">11:30a-1:00p Team Lunch</item>
<item target="13" imgid="102" menuid="201">3:00p-4:00p Pick up kids</item>
</menu>
</body>