SideShow Content and Endpoints


If you refer to Listing 8-1, you will notice that one of the parameters to the registry creation command was the identifier for the content endpoint for our gadget.

 ScfSideShowGadget.ScfEndpointId 

This specifies the endpoints in the device that we want to send content to. You can think of an endpoint as able to understand and display messages delivered to it in a particular format. This is directly analogous to ports on a TCP/IP device. A process behind a port is sent messages addressed to that port and knows what to do with them. As an example, a Web server behind port 80 is sent Hypertext Transfer Protocol (HTTP) requests and knows how to fetch Web page content and return it.

In the case of the endpoints for SideShow devices, a process behind a content endpoint is sent messages in the format for that endpoint and knows how to render them on the display.

The SideShow device implemented by the simulator program VirtualSideShow.exe supports two endpoints. These are the SCF endpoint and the ICAL endpoint. The SCF endpoint sends general messages to the device. The ICAL endpoint allows the host machine to deliver calendar information. It is used by the Outlook gadget application, which can send both SCF and ICAL content.

Note 

The configuration mechanism for SideShow devices and applications ensures that your gadget program will never be connected to a device that cannot support the endpoints that you have specified in the registry keys you created at installation.

Displaying Content on the SideShow Device

Content displayed by the SideShow device is described in Simple Content Format, which is based on the Extensible Markup Language (XML). As an example, you could express a simple two-line message as follows:

 <body>    <content  title="Ultimate Flashlight">       <txt rgb="000000">Welcome to the Ultimate Flashlight SideShow</txt>       <txt rgb="FFFFFF">Charge the flashlight for best results.</txt>    </content> </body> 

The previous content element gives an ID number for this content item and a title. It also contains the two text items to be displayed by the SideShow device.

You can get this content into the SideShow device by creating an instance of the device and then adding the content element to it.

 private static readonly Guid gadgetGUID =    new Guid("{}"); private static void doUpdateDevice() {    ScfSideShowGadget memoGadget = new ScfSideShowGadget(gadgetGUID);    memoGadget.AddContent(    "<body><content id=\"1\" title=\"Ultimate Flashlight\">"+    "<txt rgb=\"000000\">Welcome to the Ultimate Flashlight SideShow</txt>"+    "<txt rgb=\"FFFFFF\">Charge the flashlight for best results.</txt>"+    "</content></body>"); } 

The Guid has the same value as the GUID created for our gadget application and stored in the registry key. This is used to create an instance of the ScfSideShowGadget class that serves as the link between our program and any connected SideShow devices. Note that this instance could potentially represent multiple devices, each of which could have its own particular capabilities. There is a means by which you can enumerate the properties of the devices that are connected; we shall see how to do this in the section titled "Image Scaling" later on in this chapter. For the purpose of the code that we are creating in the rest of this chapter, we will assume that the memoGadget variable refers to an instance of ScfSideShowGadget connected to a single SideShow device, the SideShow emulator.

When the method AddContent is called on memoGadget, it delivers the XML content to the SideShow device, which describes the message to be displayed. The container of the message is the content element, which has an ID property set to the value 1. This property item is the root of all others on the display. It is the one that will be displayed when the user selects our item on the SideShow display.

The message itself is made up of two strings of text. The first string is displayed with the rgb color values set to 000000 (black) and the second with the rgb colors ffffff (white). You can specify additional properties to set the alignment of the text and whether it wraps around at the edge of the display. The result is the display that you see in Figure 8-8.

image from book
Figure 8-8: Displaying text on the device.

The XML describes the items that are to be placed on the display and gives layout information for them, but this information is not absolute; the device itself will perform the layout based on the instructions provided. The newly downloaded content immediately replaces existing content if the device already contains a content item with the same ID.

This means that the process of driving the SideShow device is that of creating content and then calling the AddContent method on the gadget to deliver it. Precisely which method delivers the message is not important because the infrastructure underneath your program handles that; possible methods include USB, WiFi, or Bluetooth.

Handling Content Delivery Errors

The AddContent method will always return without error, irrespective of whether a device is present or selected. However, you can discover how many devices are present by calling a method on the gadget.

 if (memoGadget.GetDeviceCount() == 0) {    MessageBox.Show("No SideShow device connected"); } else {    memoGadget.AddContent(element); } 

This code will update the device only if a connection exists; otherwise, it displays a message. If multiple devices are connected, a single call of AddContent will update all of them.

Note 

If your gadget application is running using the Single-Threaded Apartment model, that is, the method performing the communication has the [STAThread] attribute set, as for a Windows Forms application, you will experience problems receiving events and sending updates to the SideShow device.

Glance Content

The SideShow device can display glance content on the top-level menu display, which you can use to show important items of information, for example, your next appointment, an incoming e-mail message, or the name of the currently playing media item. You can use the method AddGlanceContent to send a message.

 ScfSideShowGadget memoGadget = new ScfSideShowGadget(gadgetId); memoGadget.AddGlanceContent("Check Sector 7G"); 

The SideShow device displays the text string underneath the friendly name of the gadget, as shown in Figure 8-9.

image from book
Figure 8-9: Displaying glance content.

Glance content can contain a number of lines of text. You break the lines by including a line-feed character. You may group the top two lines of the content together on the display. You should make sure that the design of your output places all the important detail in the top two lines because not all devices will display more than two lines of content.

 memoGadget.AddGlanceContent("Check Sector 7G"); 

Note 

Some devices-for example, digital picture frames-show only SideShow glance content, so you should make sure that the information in the content is as self-contained as possible.

The Simple Content Format Helper Classes

As we have seen, the messages to the SideShow device are simple text strings containing XML documents. You can create all the XML content manually if you wish, but the Microsoft.SideShow.SimpleContentFormat namespace provides some helper classes that you can use to generate XML much more easily.

 private static void doUpdateDevice() {        ScfSideShowGadget memoGadget = new ScfSideShowGadget(gadgetId);        ScfElement element = Scf.Content(           1,                                  // id           "Ultimate Flashlight",              // title              Scf.Txt(                 ScfAlign.Left,                // alignment                 true,                         // want text wrapping                 Color.Black,                  // text color                 "Welcome to the Ultimate Flashlight SideShow"),              Scf.Txt(                 ScfAlign.Left,                // alignment                 true,                         // want text wrapping                 Color.White,                  // text color                 "Charge the flashlight for best results.")        );        memoGadget.AddContent(element); } 

This code creates the same XML as you saw in the section "Displaying Content on the SideShow Device." It does this by using static methods provided by the Scf class.

The Scf.Content method receives the ID number for the content item, the title of the content, and a number of additional parameters that give content elements. There can be as many of these as you need, each of which is placed in one horizontal row on the display. The elements can be text items, a line break, an image, or a button. The method returns a content element that you can then add to the device. In the previous code, the content generated contains two text elements that represent the same content as the hand-coded XML in the previous section.

Creating Graphical Content

Some SideShow devices can display graphical content as well as text. You do this by downloading image content items to the device and then referring to them in the pages.

 System.Reflection.Assembly assembly = System.Reflection.Assembly.GetExecutingAssembly(); Bitmap pic = new Bitmap(    assembly.GetManifestResourceStream("FlashlightMemo.images.Entrance.jpg")); memoGadget.AddContent(    2,                                       // id number    ImageContentTransforms.None,             // process flags    pic);                                    // source image 

The preceding code extracts an image from the executing assembly and then adds this image as a content item to the SideShow device. The content item has the ID number 2. The ImageContentTransforms enumeration specifies the kind of image processing performed as the program converts the image into content. The following list describes some options in this enumeration:

  • ImageContentTransforms.None This requests that the program perform no transformations when it transfers the content. This means that if the image is larger than the display, only the part that will fit on the screen will be visible when rendered. The SideShow device will provide a vertical scroll bar to allow the user to view the lower part of the image if required, but it is possible to scroll only down the image-there is no provision for horizontal scrolling.

  • ImageContentTransforms.ReduceColorDepth This indicates that the program should reduce the color depth of the source image to reflect that available on the target device. You should always use this flag because it reduces the amount of data transferred to the target device.

  • ImageContentTransforms.StretchToFit This indicates that the image content size should change automatically to reflect the size of the target display. If you use this flag, it will always be possible to see the entire image, although it may be necessary to scroll down to see parts of it.

  • ImageContentTransforms.KeepAspectRatio If you specify this flag, it means that the program should preserve the aspect ratio of the image during scaling operations. This means that the ratio of height to width of the image will remain the same as the original.

If this option is not set, the program scales the image to best fit the target, which may result in distortion leading to circles in the image becoming ellipses.

You can combine transformations using the bitwise OR operator.

 memoGadget.AddContent(    200,                                                // id number    ImageContentTransforms.ReduceColorDepth |    ImageContentTransforms.KeepAspectRatio |    ImageContentTransforms.StretchToFit,                // process flags    pic); 

This set of transformations would scale the image and preserve its aspect ratio.

Rendering Images

Once you load your graphical content and give it a particular identifier, the program can then render it as part of a display item.

 memoGadget.AddContent(Scf.Content(    1,                                        // page id    "Main Entrance",                          // title       Scf.Img(          200,                                // id of image content item       ScfAlign.Center,                       // position options       ScfImageFit.Screen,                    // scale options       "Main Entrance")                       // alternate text    ) ); 

The method Scf.Image creates an item of content that renders a previously downloaded image resource. You can control the position of the image on the screen by using the ScfAlign enumeration, which lets you position the image in the center, left, or right of the display. The ScfImageFit enumeration has a number of values, which select the way that the program scales a given image to fit on the display, as described in the following list:

  • ScfImageFit.Native This requests that the program draw the image with the dimensions it had as originally set in the content. If the ImageContentTransforms option has been set to none, this will result in the display of only part of the image if the image is larger than the display. Although it is possible to scroll down such an image, it is not possible to scroll across.

  • ScfImageFit.Auto This specifies that the program stretch the image so that it and any associated content will fit on the screen without the user having to perform any scrolling.

  • ScfImageFit.Screen If you select this option, the program stretches the image so that it fits the display of the SideShow device. If the ImageContentTransforms applied to the image includes the KeepAspectRatio option, the image may not completely fill the display, and the program will add a border to preserve the aspect ratio of the original image.

  • ScfImageFit.Width This option specifies that the program scale the image so that it fills the width the display and add a scroll bar, if required.

Sample Image Display

The following code loads a bitmap from the executing assembly and then creates a content element that contains that image.

 System.Reflection.Assembly assembly = System.Reflection.Assembly.GetExecutingAssembly(); Bitmap pic = new Bitmap(assembly.GetManifestResourceStream("FlashlightMemo.images.   Entrance.jpg")); memoGadget.AddContent(    200,                                                   // id number    ImageContentTransforms.KeepAspectRatio |    ImageContentTransforms.StretchToFit |    ImageContentTransforms.ReduceColorDepth,               // process flags    pic); memoGadget.AddContent(Scf.Content(    1,                                                     // page id    "Main Entrance",                                       // title       Scf.Img(          200,                                             // id of image content item          ScfAlign.Center,                                 // position options          ScfImageFit.Screen,                              // scale options          "Main Entrance")                                 // alternate text    ) ); 

This code produces the display shown in Figure 8-10. The code has scaled the image and drawn it to retain its shape but fill the maximum possible display area. If the image is not present in the identified resource, the code displays alternate text instead.

image from book
Figure 8-10: Displaying images on the device.

Image Scaling

If you want to show images in a specific size, you can do this by resizing the image before loading it into the device, and then using native scaling.

 System.Reflection.Assembly assembly = System.Reflection.Assembly.GetExecutingAssembly(); Bitmap pic = new Bitmap(assembly.GetManifestResourceStream(   "FlashlightMemo.images.Entrance.jpg")); int newWidth = 200; pic = new Bitmap(pic, newWidth, (int)(newWidth * ((float)pic.Height / pic.Width))); memoGadget.AddContent(      200,                                            // id number      ImageContentTransforms.ReduceColorDepth,        // process flags      pic); memoGadget.AddContent(Scf.Content(      1,                                              // page id      "Main Entrance",                                // title         Scf.Img(            200,                                      // id of image content item            ScfAlign.Center,                          // position options            ScfImageFit.Native,                       // scale options            "Main Entrance"),                         // alternate text         Scf.Txt(            ScfAlign.Left,                            // text alignment            true,                                     // want word wrap            Color.White,                              // white text            "Check main doors to ensure they are locked.")      ) ); 

This version of the drawing code places a 200-pixel-wide image in the center of the screen and adds text underneath it.

Figure 8-11 shows how this would appear on a device. It is possible to obtain the widths of the displays of the Sideshow devices connected to your gadget application, but it is not possible to direct content to a specific device. You could, however, determine the minimum value for all the devices.

 int minWidth = int.MaxValue; foreach (DeviceCapabilities cap in memoGadget.GetCapabilitiesForDevices()) {    if (cap.GetClientAreaWidth() < minWidth)    {       minWidth = cap.GetClientAreaWidth();    } } 

image from book
Figure 8-11: A scaled image with text.

The GetCapabilitiesForDevices method delivers a list of device capability information items that the program can examine to discover the properties of each device connected to the gadget application. The previous code works through this list and determines the smallest display in use.

Note 

It is important that your gadget does not assume that only a particular type of SideShow device is connected. You should use the capabilities information to determine whether all devices are capable of the actions that you require.




Embedded Programming with the Microsoft .Net Micro Framework
Embedded Programming with the Microsoft .NET Micro Framework
ISBN: 0735623651
EAN: 2147483647
Year: 2007
Pages: 118

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net