Chapter 2. The Architecture
"The noblest pleasure is the joy of understanding."
—Leonardo da Vinci
IN THIS CHAPTER
- Gadgets Overview
- Technology Behind Gadget Development
- Gadget Object Model
- Sidebar Gadgets: The Road Ahead
Gadgets Overview
A gadget is a set of HTML, XML, JavaScript, CSS, and image files packed into one file. A gadget package with an extension .gadget is actually a Zip file that contains these files to run the gadget. Figure 2.1 shows a common layout for a simple gadget.
Normally a gadget contains these folders and files:
• en-US folder
• main.html
• Settings.html
• Flyout.html
• Main.js
• Gadget.xml (with proper mapping)
• Images folder
• Dragicon.png
• Logo.png
• Icon.png
FIGURE 2.1. A gadget contains a few HTML, JavaScript, CSS, and image files.
Table 2.1 explains all the files that come with a gadget. Note that the filenames are not fixed but mapped. Gadget.xml contains the reference to Main.html and other image files and Main.html contains further reference to Settings, Main.Js, and flyout file information.
TABLE 2.1. Different Files in a Typical Gadget
Figure 2.2 shows Simple Gadget inside Vista's Gadget Picker. Note that the Gadget Picker offers a brief description of the gadget at the bottom of the window.
FIGURE 2.2. A Gadget Picker window displays all the gadgets available in the computer in alphabetical order.
The Manifest File gadget.xml
The gadget package contains the file gadget.xml, which contains all the information needed by the Sidebar to identify and display the gadget, what this gadget is, and how to run this gadget. This is the gadget manifest file. It contains the metadata about the gadget, such as the name, author, information URL, copyright, and so on. The gadget.xml file also contains information such as the gadget's icon, the name to display, and any website associated with the gadget. It also contains the reference to an .html file that is used to run the gadget.
Figure 2.3 offers a look at the gadget's manifest file. Note the src, which is assigned the value main.html, decides the gadget's main window.
Most of the parameters in the manifest file are self explanatory; however, Table 2.2 provides further details about some of the parameters of the manifest file gadget.xml.
TABLE 2.2. Different Parameters Used in a Gadget's Manifest File
FIGURE 2.3. The Gadget.XML file contains the information that describes and distinguishes the gadget from other gadgets in the Sidebar.
Most of the time, a gadget has three HTML files, for the main window, the settings page, and a flyout window. A gadget can have different style sheet information as well as different JavaScript code files associated with each of these files. Different functionalities can also be encapsulated in different code files. This adds to the complexity of the gadget layout, but helps in the maintenance process. Figure 2.4 shows a layout for such a gadget.
FIGURE 2.4. A complex gadget can have multiple JavaScript and Stylesheet files.
User Interface and Presentation
The structure of the gadget comes from the three HTML pages that make up the user interface:
- Main.html—The gadget's small "home page." You see this page when the gadget is docked in the Sidebar as well as when undocked (displayed on the desktop).
- Settings.html—The page that enables user customization of the gadget. For example, this page would be the one that manages changing the city setting for a weather-based gadget.
- Flyout.html—The HTML page that typically shows information related to the user selection in the main.html page. This is an optional page.
Cascading Style Sheets
Style sheets are normally used to separate presentation of a web page from the structure, that is, the HTML of the page. Cascading Style Sheets (CSS) is used for a similar purpose in a gadget. A CSS file helps in the presentation of the gadget's HTML files. One can encapsulate all the presentation portion of the gadget's HTML pages in a CSS file. An excellent tutorial on CSS and HTML can be found at the following link: http://www.w3.org/Style/Examples/011/firstcss.
In a typical scenario, a single CSS file helps in the presentation of the main HTML page in the gadget. If the gadget's size changes when the gadget is undocked, having two CSS files, gadget.css and gadgetundocked.css, enables you to change the presentation accordingly.
Different style sheets can be used for the settings page as well as a flyout page. Settings.css is a style sheet for the settings.html page. A flyout can also use a separate CSS file if the flyout presentation is different than the main gadget window.
Style sheet information can also be included in the HTML page itself with a <STYLE> tag, but having a separate CSS file helps in modularity and maintenance in the long run.
The following is a list of different CSS files that can be used in gadget development:
- gadget.css, meant for the main window of the gadget
- undocked.css, used by the gadget when in floating (undocked) mode
- Settings.css, meant for presentation of the settings page
- Flyout.css, for the flyout window
Core Functionality of the Gadget: JavaScript
JavaScript provides the core functionality of the gadget. Structure (HTML) and presentation (CSS) make the bones and the body of the gadget, but it's the JavaScript that adds life to it.
The gadget's core, which makes a gadget dynamic, is one or more snippets of JavaScript code. Normally all these JavaScript files are put together in the js folder. These JavaScript files handle the gadget's functionality and are referenced in the corresponding HTML files (main, settings, or flyout), where the functionality is required.
Other JavaScript files are added for additional functionality, such as updating the gadget through the Internet (autoupdate.js) or adding menus and so on in the Settings.html (settings.js) page. All the CSS as well as JS files are optional; even the names are not hard-wired. Both scripts as well as style sheet information can be included in the HTML page itself, but for modularity are kept in separate files.
Resources, PNG, and Other Files
Images are a very important part of gadget development. They add professionalism to the gadget's look and feel. If you want your gadget to acquire space in the millions of users' desktops, it needs to look good. Images of the gadget are like wallpapers and icons in the computer. Everyone prefers a nice one.
Figure 2.5 shows the images required by a gadget. icon.png, Logo.png, and dragicon.png are found in the Gadget Picker gallery.
FIGURE 2.5. A typical gadget will contain an icon, a logo, a dragicon, and a background image.
The background image is used as the gadget's "wallpaper." It is a semitransparent image that appears in the gadget's background. The loading and info images are typically used for presenting the status to the user. Table 2.3 shows the list of images along with their specific purposes.
TABLE 2.3. Common Set of Images for a Gadget
loading.gif and info.gif have very important purposes. The loading.gif file visually informs the user that the gadget is trying to load the data from the Internet, which can be time consuming. Similarly, the info.gif file is used when the data has not loaded or the service is not responding. You'll learn more about using PNG and GIF files in Chapter 3, "An Approach to Design."
Technology Behind Gadget Development
Gadget development starts with HTML and JavaScript. A basic knowledge of standard web technologies such as CSS, XML, and Document Object Model (DOM Level 1) helps expedite the development process.
DOM Level 1 is a set of specification to access the elements of an HTML page. More information can be found at http://www.w3.org/TR/REC-DOM-Level-1/.
Windows Vista Sidebar exposes a rich Gadget Object Model for gadget development, which is a set of methods to access the files and features of the operating system. This can be used to create gadgets that can access operating system resources. The Gadget Object Model also supports ActiveX technology (COM), which can be further used to extend the gadget's functionality.
- Gadget technology can be divided into the following parts (see Figure 2.6):
- The gadget runs as an MSHTML component.
- It uses standard web technologies, HTML, CSS, XML, DOM Level 1, and JavaScript.
- Vista Sidebar exposes a Gadget Object Model for functionality related to the local computer.
- Gadgets also support ActiveX technology (COM) for advanced features.
FIGURE 2.6. A gadget is much more than a web page. It can access resources from the local computer, play a media file, or even run an Excel sheet.
MSHTML Component, the Core of the Gadget
The core of the gadget is an inherent object of the Windows Vista operating system called the Microsoft HTML (MSHTML) component. This component provides the hosting capabilities of an HTML page as a miniature web browser page, without any of the associated features such as the address bar, the navigation bar, menus, and so on.
A nice article on MSHTML component can be found at the website for the Microsoft Developer Network (MSDN) at http://msdn2.microsoft.com/en-us/library/bb508516.aspx (or search for it using the keyword "reusing MSHTML").
Gadget developers can use the images, CSS, and JavaScript in a similar way as they do to create web pages. The rich HTML rendering allows for the advanced graphics, user interactions, and cascading style sheets.
Standard Web Technologies
Standard web technologies such as HTML, CSS, and JavaScript make the most of the gadget's structure, presentation, and the behavior. Here is a comprehensive list of the technologies that come together for gadget development:
- HTML
- CSS
- JavaScript/VBScript
- XML/XHTML
- Document Object Model (DOM Level 1)
Document Object Model is the object model of the HTML page that is accessible from the gadget through JavaScript and is used to create dynamic and rich presentations. There is a slight difference between an HTML DOM and the DOM that comes with a gadget. Neither JavaScript alerts nor any kind of modal dialog is allowed in a gadget.
Sidebar Gadget as an HTML Application
A Sidebar gadget is more like an HTML application (HTA) than an HTML web page. A web page cannot access local resources, but HTML applications have access to all the local computer's resources.
The configuration of the core MSHTML component is similar to the set of permissions given to an HTML application or the Local Machine Zone security configuration. This model separates the Sidebar gadget in functionality from a simple web page.
Compared to web pages, gadgets are configured differently in several ways. Gadgets are treated as executable code and they can utilize any installed ActiveX objects. A Sidebar gadget has the Initialized and Script ActiveX Controls option, which, in Internet Explorer, is marked as not safe. Therefore, when programming gadgets, it is important to know the difference between various IE security permissions and any restrictions that apply.
Gadgets can also access data sources across domains: They can aggregate and collect data from multiple websites and web services. Conversely, a local web page trying to access cross-domain data, or another web page, initiates a security warning. Sidebar gadgets can also be made to download and install new ActiveX controls. This feature is disabled in Internet Explorer by default. A gadget can be made to act as spyware or malware, which can compromise the security of the user's computer. See Appendix A for more information on Security.
In contrast to the behavior of web pages, gadgets always
- Run on a secure zone, which means a gadget has permission to access all the system resources.
- Are enabled to initialize and script ActiveX controls without asking the user for permission, as is the case with a web page.
- Can access data sources across domains.
- Are enabled to download and install new ActiveX controls.
- Run with standard privileges and operations.
- Internet Explorer's Protected Mode does not apply.
These configurations in the MSHTML component make gadgets rich in capability, more like typical desktop applications, and for the same reason vulnerable to security issues. A cool-looking gadget can also be a Trojan, which appears to be legitimate, but is designed to have destructive effects. Table 2.3 compares a web page with an HTML application. More information about the HTML application can be found at http://msdn2.microsoft.com/en-us/library/ms536496.aspx.
TABLE 2.3. An HTML Application Is More Powerful Than an HTML Web Page
A gadget coming from an unverified developer can harm your computer. Normally the gadgets that appear on http://gallery.live.com are checked for security-related issues, before they are accepted for public distribution. But gadgets spread all over the Web may not be secure.
CAUTION
As a rule of thumb, if you don't know where the gadget is coming from, don't install it.
Another method is to sign a gadget with certificates to verify its authenticity.
Gadget Object Model
Windows Vista comes with a Gadget Object Model, which is a set of APIs that are exposed to JavaScript, enabling the gadget to interact with the operating system.
The gadget uses these APIs to interact with the operating system within the gadget's pages, to maintain session state, to manage input-output operations, and to access local files and folders in the system. Numerous methods, properties, and functions are available through the Gadget Object Model. The next section discusses the Gadget Object Model and discusses these APIs in detail.
More information on the Gadget Object Model can be found at MSDN keyword "Windows Sidebar Object Reference," http://msdn2.microsoft.com/en-us/library/aa965853(VS.85).aspx.
In later sections we discuss the Gadget Object Model in more detail.
ActiveX Technology
One of the important aspects of gadget development is its support for ActiveX components. ActiveX (COM) technology is used when you need a custom feature available in an already created ActiveX control, or to integrate a custom ActiveX component, such Windows Media Player, inside the gadget. For example, you may want to implement a gadget that displays a part of a Microsoft Excel worksheet in the gadget's flyout window.
An ActiveX component can be integrated in any of the HTML pages inside the gadget, the main window's HTML, the flyout page, or the settings page. Any of the ActiveX controls that are installed in the operating system, or any ActiveX control that you write yourself to interact with your own gadgets, can be used to extend a gadget's functionality.
An ActiveX object can be accessed from a gadget and provides considerable flexibility and power to the gadget:
- ActiveX can be directly embedded in the HTML page.
- Media Player, Microsoft Office, and other Windows applications can be accessed directly from the gadget.
- You can use existing ActiveX COM component by using the method CreateObject inside the script.
- You can also create custom ActiveX controls using any technology for use inside a gadget.
Gadget Object Model
The Gadget Object Model exposes a set of APIs available on the Vista operating system (see Figure 2.7). The System Object is the root of all the objects supported in the Sidebar. The available objects and APIs can be divided into four categories:
- APIs for user interaction with the gadget object and Sidebar events
- File system APIs that use the machine and network objects
- APIs for using advanced features with shell and environment objects
- Communication-related APIs for contact and messaging
FIGURE 2.7. The Gadget Object Model gives a complete set of APIs to access system resources.
These classes of API are discussed in more detail in the following sections.
User Interaction and Sidebar Events
The Gadget Object Model provides a rich set of methods, properties, and events for user interaction. All these APIs and events can be used inside a script file. User interaction can be divided into the following three sections, which themselves encompass two APIs, and several methods for Sidebar events:
- The core System.Gadget
- Sidebar Events
- T Gadget Settings System.Gadget.Settings
System.Gadget is a namespace that groups all the related APIs for user interaction. It helps the gadget interact with the user by allowing it to respond to user events such as moving the gadget on or off the Sidebar.
Sidebar Events are methods that are called when a particular event occurs in a gadget. These are normally used to set specific properties or user interface changes. For example, if you want to change the size of the gadget when the gadget is undocked (floating on the desktop), you have to use the OnUndock() method provided by the gadget.
Events such as OnDock, OnSettingsClosed, OnUnDock, and so on are available through System.Gadget. You can see the list of events later in this chapter, in the "Sidebar Events" section.
System.Gadget.Settings is used to maintain the session state or information pertaining to the current user. It enables the gadget to interact with various settings. The settings object is particularly important and is most frequently used in gadget development. This is useful to read, write, and update values of local variables and settings.
System.Gadget Objects
Apart from the interaction of a gadget and Sidebar, the Gadget Object Model is also responsible for handling the Sidebar events, settings page, and flyout window, as well as interacting with the SideShow Gadget.
The System.Gadget object is further divided into the following subobjects for these operations:
- System.Gadget— Used for interaction between the gadget and the Sidebar.
- System.Gadget.Sidebar— Used for handling the events and properties specific to the Sidebar, such as the onDockSideChanged event.
- System.Gadget.Flyout— Used to set the properties of the flyout window.
- System.Gadget.Settings— Used to read and write settings.
- System.Gadget.Sideshow— Helps to set Sidebar gadget properties and features when the gadget is interacting with SideShow devices.
Sidebar Events
A thorough understanding of the following common gadget events comes in handy in understanding the interaction between the Sidebar and the gadget:
- onDock— When the gadget is docked to the Sidebar, this event is called. It's used to resize the gadget, change images, or even refresh the data.
- onSettingsClosed— This event is useful if the gadget has custom settings and you need to update the gadget with changes to settings.
- onSettingsClosing— This event is triggered when the settings page is being closed. It is useful to save settings and so on.
- onShowSettings— This event fires when the settings page is opened. It's used to initialize defaults or get the current settings from local files or folders.
- onUndock— This event occurs when the gadget is dragged from the Sidebar to the Windows desktop. It's normally used to change the size of the gadget, its image, and so on.
- visibilityChanged— This event fires when the gadget's visibility changes from visible to invisible and vice versa.
Gadget Settings
System.Gadget.Settings is the object responsible for automatically distinguishing between gadgets. A Weather Gadget, for instance, can show weather for San Diego while another instance of the gadget can show the weather for Redmond, WA. This enables the user to create multiple gadgets and the Sidebar remembers which settings are associated with which gadget, automatically.
This object is dependent on the current user's choice and is on a per-user basis. Two important methods are
- System.Gadget.Settings.write("user-variable","value")— This method is used to set a user's reference as a value in a variable.
- System.Gadget.Settings.read ("user-variable")— This method is used to retrieve the same value from the user variable.
These methods are the basis of all the session state management in the gadget development. Please note that there is no setting stored in the local computer; the code in the settings file stores the user's preferences in a session that is managed by the Vista Sidebar.
In the Weather Gadget's settings page, when a city is selected and the user presses OK to close the settings window, the following occurs:
1. The OnSettingsClosing event fires.
2. A variable (for example, WeatherCity) is updated.
3. The variable is set. In this case, it's System.Gadget.Settings.write ("WeatherCity","San Diego").
4. When the OnSettingsClosed event fires, the gadget's main windows are refreshed and updated with the weather related to the selected city—in this case, San Diego. A background image is also updated to reflect the current value (see Figure 2.8).
FIGURE 2.8. Two instances of the gadget with different values of the variable WeatherCity.
The Vista Sidebar manages the session for the user, even if you close the sidebar or restart the computer.
APIs to Access the File System
The Sidebar provides the APIs that enable developers to communicate with the file system and acquire information about the hardware, network, and machine. For example, the CPU Meter Gadget and slideshow gadgets that come with the Vista operating system are both great examples of how a gadget uses those APIs rather than ActiveX controls.
The File System API are
- System.Shell
- System.Network
System.Shell to Access Files and Folders
System.Shell provides access to the Windows Vista shell for advanced access to folders, files, disk drives, and so on. For example, to open a web page, you can call System.Shell.execute with the URL in a couple of different ways.
For example, the following code opens a web browser pointing to the website www.innovatewithgadgets.com:
System.Shell.execute("http://www.innovatewithgadgets.com ");
Another example could be to get the path of the Pictures folder (a built-in folder) from the System.Shell object, using the following:
var myPicturePath = System.Shell.knownFolder ("Pictures");
The System.Shell.knownFolder method accepts the following strings and returns the respective folder paths:
- Desktop
- Startup
- StartMenu
- Documents
- Programs
- CommonStartup
- CommonPrograms
- PublicDesktop
- PublicFavorites
- PublicDocuments
- System
- SystemX86
- Profile
- Windows
- Pictures
- Music
- Videos
- ProgramFiles
- ProgramFilesCommon
- ProgramFilesX86
- ProgramFilesCommonX86
- AdminTools
- CommonAdminTools
- PublicMusic
- PublicPictures
- PublicVideos
- UserProfiles
- Downloads
- PublicDownloads
- GadgetsUser
- RecycleBinFolder
The earlier method with the list of strings provides a shortcut to all the frequently used folders in the local computer. This becomes very useful when creating a utility gadget that uses files from different folders.
The System.Environment object can also be used to read the path, as in System.Environment.getEnvironmentVariable ("Folder name").
System.Shell is further divided into the following objects used to access individual items, folders, the recycle bin, and disk drives respectively:
- System.Shell.Folder
- System.Shell.Item
- System.Shell.Recyclebin
- System.Shelldrive
System.Network
The System.Network object is used to determine network connectivity. For example, to access information on a wireless connection, use the following API: System.Network.Wireless.
Core Features to Interact with the System
Among other things, operating system functionality, hardware information, and ActiveX controls are handled by these objects:
- System.Machine
- System.Environment
System.Machine is used to determine the machine processor and memory characteristics. For example, if you want to find out the available memory of the computer you can try the availableMemory property in the following way inside JavaScript code:
VariableforMemory = System.Machine.availableMemory;
System.Environment is used to determine the information about the system and the logged-in user information. This information is accessed using the getEnvironmentVariable method. For example,
var tempValue = System.Environment.getEnvironmentVariable("Temp");
gives the path of the temporary folder location of the user Rajesh, which will be C:UsersRajeshAppDataLocalTemp folder, if the logged-in user is Rajesh.
The following two APIs are used to access information about the machine hardware and different CPUs on the computer.
- System.Machine
- System.Machine.CPU
To detect information about the power supply (specifically useful if the machine is operating from battery power), the PowerStatus method of the System.Machine API is used.
- System.Machine.PowerStatus
To access the system's sound and time information the following APIs are available:
- System.Sound
- System.Time
- System.Time.TimeZone
Communication and Other APIs
The Gadget Object Model also supports a set of communication APIs, starting with
- System.Contact
- System.MessageStore
System.Contact and related objects give access to the address book stored in the Contacts database of the local computer. It returns a collection object with all the contacts information.
The following set of APIs allows a gadget to access the information from the Windows Contact data store:
- System.Contact
- System.ContactManager
System.MessageStore gives access to folders collections, which store the emails in the local computer.
The following are useful APIs to access mail and other messages in Windows Mail:
- System.MessageStore
- System.MessageStoreFolder
- System.MessageStoreMessage
Other Miscellaneous Objects
The following two objects are related to debugging and tracing information for a gadget. This object can provide diagnostic capability to a gadget:
- System.debug
- System.Diagnostic.EventLog
These objects also help to diagnose any error during development of the gadget.
Sidebar Graphic Protocol
The Sidebar gadget also supports a set of objects for presentation in the gadget. They are also called graphic protocols and they enable easy access to graphics inside a gadget's HTML pages.
Sidebar has three specific protocols for image manipulations:
- gBackground— Background element/object
- gImage— Image object
- gText— Text object
These methods give you direct access to a lot of image manipulation features.
These gadget-specific protocols are great tools, and give better flexibility in designing gadgets with features such as
- Dynamic generation of thumbnails
- Alpha transparency
- Manipulating images
- Placing text and images over transparent regions
- Background image
For example, an addShadow method can be used to add a shadow to an image that is used with the gBackground protocol.
<g:background id="imageBG" src="imagesackground.png" />
imageBG.addShadow("black", 40, 40, 0, 0);
This adds a shadow with a radius of 40 and an alpha transparency value of 40.
More information on addshadow and other methods can be found at MSDN at http://msdn2.microsoft.com/en-us/library/aa359356(VS.85).aspx.
These protocols easily apply special filters on the images used in the gadget, such as shadow, glow, brightness, and so on, without any actual graphic manipulation. Appendix A further details these gadget protocols with a sample gadget GraphicDemo.gadget.
Sidebar Gadgets: The Road Ahead
Are gadgets here to stay, or are they just a phase? Should I be interested in gadget development? What is the future of Sidebar gadgets? With so many different gadget and widget engines available, which one should I use? Should I learn all of them? What is in store for gadget development in the future, if there is one? They're the kinds of questions that always come to mind whenever a new technology or platform shows up on the scene.
The truth is, Sidebar gadgets are here to stay. Microsoft has projected around 200 million sales of Vista operating system in the next two years. Although adoption has been slower than Microsoft would've liked, and although there are always problems successfully launching a new operating system, people have largely started embracing Windows Vista.
Gadgets are already the coolest new tool. Users are finding gadgets to be productive and time-saving applications. Thousands of useful Sidebar gadgets are already available in the Live Gallery (http://gallery.live.com) and the number is growing every day. It can only get better from here.
Fun gadgets and utility gadgets are currently very popular, but users are realizing the potential of gadgets in a business environment. In the future it's easy to imagine gadgets talking to Microsoft SharePoint, giving you updates on regular sales from an inventory management system. You will see gadgets operating on the same data as Microsoft BizTalk and Microsoft Dynamics. You can see gadgets interacting with task-tracking systems, pulling data from databases to give you network information at your fingertips.
The gadget platform is ripe with potential for innovations and products for the future.
Even as I type this, the World Wide Web Consortium (W3C) is working on standardizing widgets, defined as
"...small client-side applications for displaying and updating remote data, packaged in a way to allow a single download and installation on a client machine. The widget may execute outside of the typical web browser interface. Examples include clocks, stock tickers, news casters, games and weather forecasters. Some existing industry solutions go by the names 'widgets,' 'gadgets' or 'modules.'"
Although Microsoft is not directly working with W3C, most of the Microsoft Sidebar gadget design conforms to the standards defined in the Widgets 1.0 standard.
A working draft can be found at http://www.w3.org/TR/widgets/.
The W3C published a working draft in October 2007 based on standard specifications, including the following standards:
• Atom Auto discovery
• CSS 2.1 Specification
• Dashboard Reference, Apple Computer, Inc.
• HTML 4.01 Specifications
• Internationalized Resource Identifiers (IRIs)
• XHTML 1.0
• ZIP File Format Specification
The draft describes possible standardization on widget packaging, the widget configuration file, widget scripting interfaces, widget auto discovery, and the security model.
Most of the Windows Vista Sidebar gadget specifications are along the same lines, so eventually we may see more standardized Sidebar gadgets.