The basic wiring for a vista sidebar gadget..
[This should be read as a supplement to gadget development verview ].
Writing a gadget is quite easy.. It is just HTML and a little bit of wiring up notifications for docking + undocking, visibility, etc. I am hoping this post and helps you have a gadget with flyouts, notification for docking/undocking, saving settings, etc. in less than 20 mins..
---
The sample code is here packaged in zip, with a VS solution so you can edit the files easily from Visual Studio.
To install, extract the zip file to
“%userprofile%\AppData\Local\Microsoft\Windows Sidebar\Gadgets\Sample.Gadget”
Should end up with a structure similar to this: (with only a few files highlighted)
\Users\jaimer\AppData\Local\Microsoft\Windows Sidebar\Gadgets\Sample.Gadget the full path to our gadget directory
...\Sample.Gadget\en-us\gadget.xml The manifest file... relatively easy to understand..
...\Sample.Gadget\en-us\simplest.html this will be the gadget file used for this sample -- the gagdget knows to load this file because we told it in the gadget.xml
...\Sample.Gadget\en-us\settings.html the UI for the gadget's settings..
...\Sample.Gadget\en-us\css\main.css centralized place for our style sheets ...
\Gadgets\Sample.Gadget\en-us\js\generic.js I have put some generic JS code here.. [stuff that I use for all my gadgets] ..
A few of the interesting snippets in this sample gadget is:
gadget.xml - aka gadget manifest
Only file name that can not be changed; sidebar specifically looks for this filename
Most relevant entry is the
<base type="HTML" apiVersion="1.0.0" src="Simplest.html"/>
This tells the sidebar gadget what file to load as entrypoint..
Simplest.html -- our gadget user interface
The HTML file loaded by sidebar; aka our UI... interesting snippets:
- include for the stylesheets and JS files:
<link href="css/main.css" rel="stylesheet" type="text/css"/>
<script src="js/generic.js" type="text/javascript" language="javascript"></script>
<script src="js/custom.js" type="text/javascript" language="javascript"></script>
- wired the Init () call that will do all the wiring work
<
body onload="init();" class="DockedModeDisplayArea" >
Generic.js
The wiring is done in the init function.. we do a bit of the wiring here:
function
init ( )
{
System.Gadget.settingsUI = "settings.html"; //This tells the gadget the HTML file to launch for settings
System.Gadget.onSettingsClosed = settingsClosed; //wire ourselves to settings closed event to save them
System.Gadget.visibilityChanged = visibilityChanged; // stop working if we are not visible System.Gadget.onUndock = chkdockedState; //let me know if I get undocked so I can look different System.Gadget.onDock = chkdockedState;
System.Gadget.onShowSettings = showSettings ; // let me know if settings are being shown System.Gadget.Flyout.onHide = flyoutHiding; //let me know if flyout is showing/hiding. I can pass data to it via document property
System.Gadget.Flyout.onShow = flyoutShowing;
}
that is all the code needed to wire every thing side bar does ( drag drop is not some thing you can wire into .. Pretty easy! The rest is your business logic to populate what happens on each action.. and the code to show the Flyout
custom.js
Notice that simplest.html has
<a href="" onclick="showFlyout('login', 10000);">Show Flyout</a><br />
This will be the code to show our flyout . showing it is as simple as setting:
System.Gadget.Flyout.file = "loginFlyout.html"; //file name to be shown..
System.Gadget.Flyout.show = true;
To hide the Flyout, set:
System.Gadget.Flyout.show = true;
The code I am showing hides the flyout after 10 seconds..
I hide it for no reason other than to show you how to hide it..
Note that the Flyout is only visible when the gadget has focus.. if gadget loses focus, the flyout hides automatically.
settings.html
This file shows UI for entering settings...
Notice that the sidebar puts the "frame" for the settings screen...
Sidebar handles the frame title, OK, Cancel button ... and you get the notification via the System.Gadget.onSettingsClosed event.. to cancel this dialog from closing [say it failed validation] you can listen for the onClosingEvent. You can see all the sample logic, to load and save settings inside the settings.js file
That is it! With this quick sample you should have a gadget rendering UI in no time.. Unfortunately all we can do now is render UI, maybe desktop status, a game or any thing else that works disconnected.. Next post we will wire this to some data :)
To run the sample,
- add your gadget to the vista sidebar
- Click on the ShowFlyout Anchor
- Click any where out side of the gadget to have the flyout go away (or wait 10 secs)
- Right click any where in the gadget
- Select Options, to show the SettingsUI
- Click OK -- you will see a validation error appear.... this was again added randomly as an example
- Click OK again
- Start now hacking away at the gadget and make some thing cool :)
The whole sample is here