Creating interesting Gadgets - User Interface Elements
Categories
Vista Sidebar Gadgets are changing the way that we consume data. Over the next few weeks I will be looking at some of the interesting behaviors that you can add to your gadgets to make them interesting and I'll be using different Gadgets that I find on MicrosoftGadgets.com to highlight various features along the way. To get things started I'd like to talk about the various UI elements that you can use to present information to your users.
The default view
Below is an image of one of the core Windows Vista Gadgets (a gadget that ships with the core Vista operating system and therefore is located in your C:\Program Files\Windows Sidebar\Gadgets folder), the Notes Gadget. Here we see the Notes Gadget in its standard docked state in the Sidebar:
This UI is a simple HTML file which displays an image as its default background that gives it an appearance of a stack of notes. The default view (HTML file) for a Gadget is a configuration setting in the XML manifest file of the Gadget:
<gadget>
<hosts>
<host name="sidebar">
<base type="HTML" apiVersion="1.0.0" src="TestGadget.html" />
</host>
</hosts>
</gadget>
Customizable Gadgets
The Notes Gadget provides the user with the option of creating new notes or deleting an existing notes and they perform those interactions by mouse'ing over the Gadget and having additional UI elements displayed. Here we see the additional UI elements that appear when we mouseover the Notes Gadget:
The elements on the upper-left side of the Gadget are added by the Vista Gadget system and allow the user to perform different actions. The [x] icon is standard for all Gadgets and allows the user to remove the Gadget from the Sidebar. Underneath that we have a spanner icon that allows the user to manage the settings of the Gadget, this icon is only present when an HTML file has been associated with the System.Gadget.settingsUI property. Setting this is done at runtime like so:
System.Gadget.settingsUI = "settings.html"
With the settingsUI property assigned, the Gadget will display the spanner and when the user clicks on that, the contents of the settings.html file will be displayed to allow the user to make configuration changes to their Gadget.
Here the settings UI for the Notes Gadget allows the user to choose their note color and change their font settings. When the user has made their choices and pressed OK, the Gadget would use the Gadget.Settings API to persist that configuration information. Reading and writing configuration settings is as simple as this:
var settingValue = System.Gadget.Settings.readString("SettingName"); // reading
System.Gadget.Settings.writeString("SettingName", mytextbox.value); // writing
It's important to note that the Settings.html file in the above image did not contain the Title bar with the text "Notes" and nor did it contain the OK or Cancel buttons as these were all provided by the Gadget runtime. The Title bar text was read by the runtime from the title that is supplied in the Gadget's manifest file.
Providing a detailed view
Another useful UI feature of Gadgets are Flyout's. Flyout's are used when your Gadget contains some summary information and you want to allow the user to click on that summary data to see a more detailed view of that data. One of the standard Gadget's which makes use of Flyout's is the Feed Headlines Gadget (another of the standard Vista Sidebar Gadgets). By default the Feed Headlines Gadget displays a summary of recent feed items in a list.
The user can then click on an item in the list to display a detailed view of that item. Clicking on the item displays the following Flyout with the detailed content for the RSS item displayed:
Again, the Flyout is simply another HTML page which you set on the file property Flyout object. When it comes time to display the Flyout you simply set the value of the show property of the Flyout to 'true':
System.Gadget.Flyout.file = "flyout.html"
System.Gadget.Flyout.show = true;
As with the Configuration Settings view, the Title bar and surrounding chrome for the Flyout view are provided by the Gadget infrastructure. To populate data into the Flyout window the Feed Headlines Gadget makes use of the onShow event of the Flyout object to determine when the Flyout is available and then the document property of the Flyout to gain access to the DOM of the HTML document for the flyout view:
System.Gadget.Flyout.onShow = function() {
addContentToFlyout();
}
function addContentToFlyout() {
if(System.Gadget.Flyout.show) {
var flyoutDiv = System.Gadget.Flyout.document;
flyoutDiv.getElementById("flyoutTitleLink").innerHTML = tempTitle;
flyoutDiv.getElementById("flyoutTitleLink").href = g_feedURL;
....
}
}