While Windows Sidebar may seem like something new and complex, it’s just the old Active Desktop, complete with three new tags and an API that takes care of storing settings, reporting layout changes, and providing basic system information. A gadget is therefore an HTML page on the desktop displayed by the Internet Explorer engine running in the sidebar.exe process.
How does a web page displayed in Internet Explorer differ from one displayed as a gadget? In the case of Active Desktop, introduced in Windows 95, the difference was small. The page on the desktop had a gray frame instead of an Internet Explorer window. Windows Sidebar shows us several support buttons instead of a frame. All installed gadgets on the computer are displayed in the gallery, regardless of whether the gadget is on the desktop or not. From this gallery, it is dragged to the desktop and thus launched.
Appearance
The sidebar allows us to take advantage of two sizes of the gadget. In Windows Vista, the size was switched depending on whether the gadget was docked in the sidebar or floated on the desktop. In Windows 7, the user selects between sizes using the side button. These side buttons appear in the sidebar to the right of the gadget. There can be up to three – closing, resizing and adjusting the gadget, along with a place to drag the gadget elsewhere. In the gallery, each gadget has its own image, manufacturer’s picture, version number and some description. The gadget is installed by dragging it to the desktop. In fact, only the image is displayed during dragging. The HTML page itself is displayed after it is placed.
A gadget can also have its own side window referred to as flyout. It is most often used to display more detailed information. However, it can cause limitations if we invoke it after clicking on an element. You can also drag and drop the gadget by dragging its contents, except for areas where we are capturing the OnMouseClick javascript event.
The simple setup makes the sidebar easier by simply setting System.Gadget.settingsUI to the HTML page containing the settings form. The form page must initialize the elements to the set values after opening and save the form values in the settings when closing when the Settings.ClosingEvent event occurs. The gadget itself will also have a Settings.ClosingEvent event, which is a good idea to process and reload the values from the settings.
Structure
The gadget consists of several files that are packed in a ZIP archive and with the extension .gadget. The Office Open XML format has the same approach. A gadget.xml file is placed in the root directory, specifying which HTML file should be interpreted as the contents of the gadget window. It also contains the version of the gadget, description, information about the author and the API version for which the gadget is designed. You can create multiple cultures by placing each manifest gadget.xml in a separate directory named after the appropriate language code (cs-CZ, en-US, …).
<html>
<head>
<title>Můj gadget</title>
<script src="script.js" type="text/javascript"></script>
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body scroll="no" unselectable="on" id="body" onload="init();">
<g:background id="imgBackground">
<div id="DockedModeDisplayArea"></div>
<div id="UnDockedModeDisplayArea"></div>
</g:background>
</body>
</html>In the main part of the gadget, the visibility of the two main parts changes with each other according to the size selected by the user. The unselectable attribute turns off text marking with the mouse. If links are set to attribute hidefocus, their dotted framing will not be displayed when they have focus.
API
Windows Sidebar provides services that are accessible via object System. Through this object, the gadget can respond to resizing, to being connected or disconnected from the network, to save settings, and so on.
Interesting objects
System.ContactManager
Contains a collection of Windows Mail contacts.
System.Machine
It provides data about your computer’s memory and individual processor cores.
System.Machine.PowerStatus
Provides battery status data.
System.MessageStore
Contains the folder names of Windows Mail. For each folder, it provides the number of messages and the number of unread messages.
System.Network.Wireless
It contains information about the SSID, signal strength, and DNS servers of the wireless connection.
System.Shell.RecycleBin
It contains information about the status of the trash can and methods for emptying it.
Interesting features
window.navigator.onLine
Returns true if the computer is connected to the network, false otherwise.
System.Gadget.Flyout.document
Returns the DOM of the gadget’s side window.
System.Gadget.Flyout.file
Specifies the path to the HTML file representing the contents of the gadget’s sidewindow.
System.Gadget.Flyout.show
Specifies or returns whether the gadget’s sidebar is displayed.
System.System.Gadget.settingsUI
Specifies the page that represents the settings window.
Interesting methods
System.Gadget.Settings.readString
Reads the string stored in the settings.
System.Gadget.Settings.writeString
Saves the string under the given key in the settings. The key can be up to 1024 characters long, the value up to 2048 characters.
System.Debug.outputString
It prints a string to an error output, which we can then read in Visual Studio if we are debugging attached to a sidebar.exe process.
System.Diagnostics.EventLog.writeEntry
Writes the event to the system log of the appropriate level. Windows Sidebar is given as the source.
System.Environment. getEnvirenmentVariable
You can use this method to determine the value of an operating system environment variable.
System.Shell.execute
Runs the application or executes a script.
Interesting events
document.body.online
Occurs when the computer connects to the network.
document.body.offline
Occurs when the computer disconnects from the network.
System.Settings.ClosingEvent
Occurs when the user has closed the gadget settings window. A good time to show changes.
System.Gadget.Flyout.onHide
It occurs if the user has hidden the side window of the gadget.
System.Gadget.Flyout.onShow
Occurs when the user has viewed a side window of the gadget.
System.Machine.PowerStatus.powerLineStatusChanged
Occurs when the power supply method of the computer changes.
Expansion tags
In addition to the JavaScript object System, we also have three XHTML extension tags. One for the background, the second for the image, and the third for the text. All tags have a number of interesting attributes – blur, opacity and rotation that determine blurring, transparency and rotation. Via JavaScript, it is also possible to set the color glow or shadow using the addGlow and addShadow methods.
| g | :background | attribute g:image | g:text | Description |
|---|---|---|---|---|
| align | X | Text alignment | ||
| blur | X | X | X | Glow of Text |
| Brigness | X | X | X | Text brightness |
| color | X | Text color | ||
| font | X | Text font | ||
| fontsize | X | Text size | ||
| height | X | X | Block height in pixels | |
| left | X | X | Offset the block from the left in pixels | |
| Opacities | X | X | X | block transparency |
| rotation | X | X | X | Rotate the block in degrees |
| softEdge | X | X | Round corners | |
| Src | X | X | Image file path | |
| Top | X | X | Block offset from top in pixels | |
| value | X | displayed text | ||
| width | X | X | Block width in pixels |
g:background
The g:background tag is inserted immediately into the body element. Via JavaScript, the image can be set via property System.Gadget.background. JPEG, BMP, GIF, and PNG formats are supported. Only PNG supports alpha channel transparency.
g:image
g:image represents an image. It should be offset by at least one pixel from the edge of the gadget, otherwise there may be an error in its rendering. The src attribute specifies the path to the image. As with backgrounds, JPEG, BMP, GIF, and semi-transparent formats supporting PNG are supported.
g:text
g:text is an extension of the well-known tag p. Text can be enriched with various effects. Since Windows 7, it is possible to explicitly specify the size of the text via the autoscaleDPI element in the manifest.
GIMAGE protocol
For more efficient loading of images using the Windows cache, the GIMAGE protocol is used. Its use looks like this:
var src = "gimage:///" + System.Gadget.path + "\\images\\mujobrazek.png";
var img = System.Gadget.background.addImageObject(src 2, 2);
img.id = "mujobrazek";First, the path to the image is compiled, which is located in the gadget’s archive. Then a new g:image element is inserted into the g:background element, offset by 2 pixels from the edges. The method returns a pointer to it. Finally, its identifier is set.
Silverlight
You can also insert a Silverlight object into the gadget and take advantage of all the convenience there. Protocol x-gadget refers directly to the root folder of the archive.
<object width="100%" height="100%" data="data:application/x-silverlight-2," type="application/x-silverlight-2">
<param name="source" value="x-gadget:///ClientBin/SilverlightGadget.xap" />
</object>Debugging
During the development of the gadget, I recommend maintaining its functionality both in the sidebar environment and in Internet Explorer. Creating an archive, removing the old version, and installing the new version and then connecting to the sidebar.exe process is very tedious for the first stage of development. This method is suitable for control monitoring of activity, but for classic development, it is better to use the Developer Tools available in IE under the F12 key. If an error occurs in JavaScript, the line on which the error occurred is highlighted. In the right part of the window, you can see local values, the call stack or run javascript commands. A breakpoint can be placed anywhere in the JavaScript code.
In Visual Studio, when you connect to the sidebar.exe process, you will see the output that the gadget sends using the System.Debug.outputString method. You can log into the system log via method System.Diagnostics.EventLog.writeEntry.