About the Project Templates and Sample Code

Article
06/12/2009

The wizard uses a Visual Basic or C# project template to create a very basic sample gadget that displays a message saying, “Hello Windows SideShow World!” The wizard can also generate a sample property page. In the sample gadget, the property page lets the user choose either black or white for the color of the message text. Whether or not you choose to create a property page, the sample gadget code includes a context menu that enables the user to choose the text color from the device.

The following sections describe how the code in the project templates works.

Initializing the Gadget

You can see the code for the main entry point for the gadget, Main, in the file named GadgetEntry. Main performs three main tasks:

Handles the registration command line, if provided. The command line enables registering and unregistering the gadget, including registering the property page and specifying the gadget icon.
Creates a mutex to ensure that only one instance of the gadget exists at a time.
Runs the gadget’s form, which provides a Windows message loop that is needed for the gadget to work.

It is important to understand that the form remains hidden from the user and does not provide user interface elements on Windows or on devices.

You can see the code for the form in the file named GadgetForm. The function (or Sub) named InitializeSideShowGadget, which is called from the form’s constructor, first creates an ScfSideShowGadget object. This class, which inherits from SideShowGadget, represents a gadget specifically designed to handle content created using Simple Content Format.

InitializeSideShowGadget also performs the following steps:

Subscribes to SideShow events.
Adds glance content for the gadget.
Tests for a registry value that the gadget uses to save the text color setting.

Registry Helper Functions

Because it uses the registry to save text color settings, the sample code includes the following registry helper functions:

Function name	Description
GetTextColorFromRegistry	Retrieves the current text color string from the gadget’s registry key. The sample code only uses “Black” or “White.”
SaveTextColorToRegistry	Writes the text color value to the gadget’s registry key.
CheckForRegVal	Tests whether the text color value exists in the registry. If the value does not exist, the function attempts to create the value.

Displaying the Hello World Message

The function (or Sub) named UpdateContent contains the code for creating and sending the hello world message to the device. The code calls this routine when the form loads, when the user chooses the gadget from a device, and when the user changes the text color by using a context menu on the device. This routine is not called in response to the user changing a property page setting.

The code creates the gadget content by using objects from the Microsoft.SideShow.SimpleContentFormat namespace. Creating the SCF content is straightforward. The API represents various XML elements as objects. The sample code simply creates a text element and then adds it to a content element, as follows:

// Create the page content.
ScfElement textElement = Scf.Txt(ScfAlign.Center, true, m_textColor, helloWorld);
ScfElement myScfContent = Scf.Content(MyIDs.MainPage, pageTitle, MyIDs.ContextMenu, textElement);

The corresponding SCF markup would look something like this:

<body>
<content>
  <txt align = “c” wrap = “1” rgb = “FFFFFF”>
    Hello Windows SideShow World!
  </txt>
</content>
</body>

A single method call pushes the content to the devices, as follows:

oScfGadget.AddContent(myScfContent);

You should notice that elements, such as menus, menu items, and content pages are identified by integer IDs. In the sample code, all such IDs are declared as members of the MyIDs class, for convenience.

The function (or Sub) named UpdateContent uses SCF to add a context menu to the gadget. The following code creates the context menu and adds two items: one to enable the user to choose black text and one for white text.

oScfGadget.AddContent(
            Scf.Menu(MyIDs.ContextMenu, "Hello World Context Menu", 
            Scf.Item(MyIDs.BlackTextItem, null, null, MyIDs.MainPage, "Black text"),
            Scf.Item(MyIDs.WhiteTextItem, null, null, MyIDs.MainPage, "White text")));

oScfGadget.AddContent(
            Scf.Menu(MyIDs.ContextMenu, "Hello World Context Menu",
            Scf.Item(MyIDs.BlackTextItem, Nothing, MyIDs.ContextMenu, MyIDs.MainPage, "Black text"),
            Scf.Item(MyIDs.WhiteTextItem, Nothing, MyIDs.ContextMenu, MyIDs.MainPage, "White text")));

The corresponding SCF markup would look something like this:

<body>
    <menu id="2" title="Hello World Context Menu">
        <item id = “3” target="1">Black text</item>
        <item id = “4” target="1">White text</item>
    </menu>
</body>

The function (or Sub named OnContextMenuSelect handles the ContextMenuSelect event. This event occurs when the user selects a context menu item. The second parameter, e, contains the ID of the menu item the user selected.

Note that in C# code, the argument must be cast to the correct type, as follows:

ContextMenuSelectEventArgs args = (ContextMenuSelectEventArgs)e;

Visual Basic code automatically types the argument correctly.

The following example code shows how the sample determines which menu item the user selected.

switch (args.MenuItemId)
{
case MyIDs.BlackTextItem:
    m_textColor = Color.Black;
    break;
case MyIDs.WhiteTextItem:
default:
    m_textColor = Color.White;
    break;
}

Select Case (e.MenuItemId)
    Case MyIDs.BlackTextItem
        m_textColor = Color.Black
    Case MyIDs.WhiteTextItem
        m_textColor = Color.White
    Case Else
        m_textColor = Color.White
End Select

Providing a Property Page

The sample code can include a property page if you choose to create one when you run the gadget wizard. You can see the property page code in the file named GadgetPropPage.

The sample property page is contained in its own class, and this class is contained in the same assembly as the gadget. The property page class has a set of attributes that make it possible for Windows SideShow to instantiate the property page object:

A GUID that uniquely identifies the property page. This GUID must be different from the one that identifies the gadget.
The ClassInterface attribute, which enables COM interoperability through an interface.
The ComVisible attribute, which exposes the class to COM.

The sample code provides the property page user interface by using a Windows form. The property page form becomes visible when you open the property page by clicking the gadget name in Control Panel. You should notice that the form’s BorderStyle property is set to “None” because the property page container provides a window that has a border and a title bar. The sample code handles the following two events:

Load runs when the form loads. The sample code retrieves the current text color from the registry, and then sets the Checked property for the correct radio button.
PersistSettings runs when the user clicks OK on the property page. The sample code tests which radio button is currently selected, and then saves the appropriate color setting to the registry.

Providing a Custom Icon

The project templates include a custom icon file, named HW1.ico. This icon represents the gadget in Control Panel, in the property page title bar, and on devices. The icon file contains three versions of the icon in the following sizes: 48 by 48, 32 by 32, and 16 by 16 pixels. The project templates specify this icon as the application icon on the Application tab of the Visual Studio Project Designer. The sample code registers this icon by using the DefaultIconResourceId property, which signals Windows SideShow to use the application icon to represent the gadget.

Share via