Overview of the Simple Content Format
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 comprised of formatted text and images, whereas a dialog page is a specialized version of a content page that provides the user with a choice amongst selectable options, similar to a dialog. The page types are mutually exclusive: they cannot be combined, and therefore each content ID must represent only one type of page.
Elements of SCF
The following table provides a list of elements that are available in SCF.
Element name |
Description |
Usage |
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. |
|
|
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 valid). The br element can be used in a menu item to cause it to wrap to multiple lines. |
|
|
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). For more information, see "Use the expected button behaviors" in Designing the User Experience for the Gadget. |
|
|
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 only valid within a txt element. For more information, see "Use default text colors wherever possible" in Designing the User Experience for the Gadget. |
|
|
The content element specifies a collection of static text and images, laid out in a flow manner. |
|
|
The dialog element specifies text, buttons, and possibly a single image to be displayed on a page that requires a response from the user. |
|
|
The div element specifies that a dividing line should occur at the specified point in a sequence of rendered menu items. |
|
|
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 only valid within a txt element. |
|
|
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. |
|
|
The item element describes a single item in the containing menu, as specified by a menu element. |
|
|
The menu element specifies the list of menu items that constitutes a menu page. |
|
|
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. For more information, see "Use default text colors wherever possible" in Designing the User Experience for the Gadget. |
|
In addition to the usage in the previous table, the menu pages have more in-depth capabilities, which are described in the following sections.
Menu Pages and Navigation Events
You can use the menu element to create both menu pages and context menus. 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.
For more information, see "Design context menus for a range of devices" in Designing the User Experience for the Gadget.
Using the Menu Element
The menu element contains a list of item element children. 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 content ID 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 may not be supported by all devices.
Determining an Image Format
SCF is format-independent, however, we highly recommend devices that support SCF and that also support a standard set of formats, including JPEG, GIF, and BMP. Gadgets may determine the device's supported image formats by querying for the SIDESHOW_CAPABILITY_SUPPORTED_IMAGE_FORMATS device capability.
For more information, see "Device Capabilities" and "Limit device resource usage" in Sending Data.
Examples
The first example illustrates a first page with a menu that displays several menu items.
<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>
The second example illustrates the day's appointments.
<body>
<menu id=”300” title=”Today’s Appointments”>
<item target=”11” imgid=”1” menuid=”50”>10:00a-11:00a Design Meeting</item>
<item target=”12” imgid=”1” menuid=”50”>11:30a-1:00p Team Lunch</item>
<item target=”13” imgid=”1” menuid=”50”>3:00p-4:00p Pick up kids</item>
</menu>
</body>
Navigation Events
A change in the current content the user is viewing is called a "navigation event". Navigation events are delivered to the gadget via the ISideShowEvents::ApplicationEvent Method method. There are three main types of navigation events defined for the Simple Content Format:
The events contain information such as the content ID of the origin page, the content ID of the destination page, and which buttons were pressed to cause the navigation to occur. In the case of menu events, the selected menu item is included, and in the case of a context menu event, information about the page on which the context menu was invoked is also included.
For more information, see "Invest in good task flow design" in Designing the User Experience for the Gadget.