Jaime Rodriguez : Vista Sidebar Gadgets

writing a .net activex control for your sidebar gadget..

jaimer — Tue, 03 Oct 2006 13:02:00 GMT

HTML is quite easy for people to get started with, pretty broadly known, light weight, rich enough (if you work hard at it or have nice graphics), etc.. so there is a good set of reasons why the sidebar folks chose HTML as the presentation technology [ I am guessign here]

However, there are some things that are a little harder to do with HTML [at least they are for me] ... for example, charting (pie charts) ...I tried using VML for this, and had issues.. (it was a little unstable on how it rendered, some times it would stop rendering, I could not figure why)... so for these very extreme scenarios, I am thinking ActiveX might be OK...

Note that by no means I am advocating activex as the best choice for gadgets, imho the activex registration (regsvr32) breaks the easy, per-user, non-impactful deployment model for gadgets... but I am thinking that there are enterprises (say internal, lob gadgets) that can get away with an impactful deployment model (via MSI or SMS) and benefit from the rich visualization of an activex -say for some BI KPIs...

Here is what I created code to do:

An Interface so I can 'raise' some events from my activex to my gadget (outward )
An interface so I can call from my gadget into the Active X... (inwar)
An ActiveX user control, written in C# that shows UI
some lame code to draw a piechart... just to make me feel good .... it does not update, etc.. very much a token .. I will skip on steps below
Wrote the code to call the activex from my gadget and sink to the events..

For reference, here are some good articles in creating .NET Activex controls for IE... I used a little bit from all of these..

http://msdn.microsoft.com/msdnmag/issues/02/01/UserCtrl/

http://www.codeproject.com/cs/miscctrl/exposingdotnetcontrols.asp

http://msdn.microsoft.com/library/default.asp?url=/workshop/author/om/event_model.asp

http://www.cisco-cert.com/dotnet_general/574541-How-to-fire-Javascript-events-from-a--NET-winforms-user-control-back-to-Javascript-in-IE

Come on dude, get to it... show us the code!..
OK .. here you go ... All of the code is commented, please go through it in the project... here I am showing only the 4 tasks above.. |f you are to reuse this, you will have to replace all the lines that have a TODO with your own guids or your own names code

// Outgoing interface, wired via ComSourceInterfaces on my main class -- see step 3
//TODO: Replace the Guid with our own
[Guid("56726927-833B-4cfb-94D3-D1501DFD30D2")]
[InterfaceType(ComInterfaceType.InterfaceIsIDispatch)]
public interface IGadgetControlEvents
{//TODO: The DispIds must be unique and must be here... I first skipped them and was getting a MethodNotImplementedException [DispId(1)]
void RightClickRelay(int x, int y);
[DispId(2)]
void MouseEnterRelay();
[DispId(3)]
void MouseLeaveRelay();
}

In my class, I had to expose the events ( showing only RightClick here... the rest you can see in the code)

// Right Mouse Click will be passed to the gadget... I was hoping I could popup the context menu..
protected override void OnMouseClick(MouseEventArgs e)
{
base.OnMouseClick(e);
if (e.Button == MouseButtons.Right)
{
// Did any one subscribe ???
if (RightClickRelay != null)
{
new SecurityPermission(SecurityPermissionFlag.UnmanagedCode).Assert();
// fire the event ..
RightClickRelay(e.X, e.Y);
CodeAccessPermission.RevertAssert();
}
}
}

2 -- Exposing an interface for gadget to call my Activex ..

// incoming interface -- so I can call from HTML Gadget ....
// wired simply by my control class implementing it..
// note: I had to implement extra interface because I had the eventing interface... if I did not have eventing, I would not have
// needed to explicitly implement this extra interface..

//TODO: Replace guid...
[Guid("341F46AA-0EA0-4b97-A294-E131D8CFF7E6")]
[InterfaceType(ComInterfaceType.InterfaceIsIDispatch)]
public interface IGadgetIncoming
{
void SetVariableName(string name, string value);
}

to wire the interface, simply implement it in my class ... (see step3 )

3.- Creating the activex .. it is simply a .NET Class Library with a UserControl and some attributes:

// TODO: Replace GUID
[Guid("A4B9C3C2-8DAC-451a-AEC1-DE3B042FB311")]
// TODO: Replace Prog Id
[ProgId("WindowsFormsUserControl.UserControl")]
//Wire up my eventing interface ..(ComSource)...
[ClassInterface(ClassInterfaceType.None), ComSourceInterfaces(typeof(IGadgetControlEvents))]
[ComVisible(true)]
public partial class UserControl1 : UserControl, IGadgetIncoming

5.- Using the object from my gadget

function sample::RightClickRelay ( x, y )
{
// ShowContextMenu ();
var o = document.getElementById('sample');
o.SetVariableName ( 'test1' , 'value1') ; }
</script>

---

So, the control is pretty trivial... download the sample code, replace the TODOs ( use GuidGen to generate your guids) and you will reuse it ... There were however a couple of note worthy issues I have not figured out .. [will get to these as soon as I have time ]

I implemetned the right click so that I could fire the context menu of the gadget .. but the event is raised and I handled it in Javascript, but still could not fire the context menu ..
I implemented MouseEnter/Mouse Leave because gadgets show the little drag & drop handle when MouseEnter or it gets focus... One way to get around it, was that I put a Table around it... this way, the table detects when MousEnter/leave happens and lets the sidebar know ... This works for the most part, but if you run you mouse very fast into the gadget, some times table does not fire it ..
When you put the activex, you lose the easy drag & drop functionality gadget has.. you an only drag & drop from outside the activex..

None of these are blockers, in fact some of the MS gadgets themselves (notes) have these issues but I would like to solve them for a different post ...

You can download the code for this project here...
There are two directories in the download, the sample.gadget and the ActiveX code itself..

For dev/test deployment, the project in Visual Studio is using the "Register for COM Interop" checkbox in the Build section of the Project properties to do the registration ... if you are not rebuilding it, or installing it in a box where you are not building it, you will have to register it manually from a .NET Command prompt (or a command prompt with regasm in the path)..

regasm /register /codebase WindowsFormsuserControl.dll

This leaves the whole topic of how to deploy at run-time... are you going to need admin, etc.. I will have to get back to these questions in a future (but will try to not make it to far into the future) post.. .

Cheers,

Using Atlas to make webservices calls from sidebar gadget..

jaimer — Tue, 03 Oct 2006 01:58:00 GMT

Last post we did a REST call using XmlHttp from a sidebar gadget... but let's admit it, we were all doing xmlhttp calls in 2000 and we were 'geeks'... it was not until 2005? that this exact same code became "cool" because it was called AJAX ... So here is the ticket to get you to the cool group -- every one knows I will never make that :(

Pre-requisites (or stuff you get with the sample code located here)

Create an Atlas website ( might want to check http://atlas.asp.net, if you don't know Atlas, you will need an hour there)
Create a Web Service... mine has the very creative name of "WebService.asmx" and it has a function called GetVolume that returns an object .... [arguably a 'complex type']

The client code:

Copy the atlasruntime.js from a machine that has Atlas installed to your gadget's js directory (or any where that you can get to from your gadget)..
By default, my atlas install put the files under \Program files\Microsoft asp.net\atlas\v2.0.50727\atlas\scriptlibrary\debug
The trick: Atlas by default uses frames to get around cross-site scripting... That gets messy if you are trying to generate a proxy with out using the Atlas' server side script manager.. so instead I forced Atlas to use xmlhttp with out frames.. and when it goes directly it is a breeze.. The caveat is that the parameter to forceXmlHttp is hidden some where that I could not [though did not look too hard] get to easily... if you download the sample code for this project, search atlasruntime.js for 'jaimer' to see the change.. for those going at it alone, it is line 2317 ... in atlasruntime.js ( Sept CTP ) ... the code around it looks like this:

Sys.Net.WebRequest = function() {
Sys.Net.WebRequest.initializeBase(this, [true]);
var _url = null;
...... //lots of stuff here
var _delegateRequest = null;
//jaimer Changed this line... from
// var _forceXmlHttp = false; /* to */
var _forceXmlHttp= true;
Create a proxy to your web service from your gadget code..
[So I added a new Javascript file, called AtlasServiceProxy.js and I put the same stuff that atlas gets by making the call to WebService.asmx/js [this is what they use to get the proxy] ... If you have an aspx website, with a webservice, you can just navigate to it using IE, and add the /js after the webservice URL ... (e.g. http://jaimersvr/AtlasWs/Webservice.asmx/js ] and it should look like the one below.. Notice I did have to add one line, the this.path = <url to my webservice> ..

Type.registerNamespace('AtlasSample');
AtlasSample.WebService=new function()
{
// These parameters can of course be set at runtime... In my case, I hardcoded them here for brevity
this.path = "http://jaimersvr/AtlasWS/WebService.asmx" ;
this.appPath = "http://jaimersvr/AtlasWS/" ;
var cm=Sys.Net.ServiceMethod.createProxyMethod; cm(this,"EchoString","s"); }
OK, I think that is all we needed... we are now ready to party w/ ajax.. :) To run the sample, simply click in the button in the gadget...

WHY BOTHER using Atlas to call webservices instead of just plain old XmlHttp like we did on my last post??...
Well, there is one nice reason to do this: Atlas does some nice JSON serialization on the back-end and front-end, so the results come back as objects instead of as an XML file you need to parse... for example, my webservice returns an object... that looks like this in C#:

public class VolumeObject {
public string At10m;
public string At50m;
public string At100m ;
}
using Atlas, I do not need to write the XML de-serialization code ...

/*digress: why this weird object I started with a simple Echo function ... that returned what you sent.. but then I decided to do a more complex object .. so I thought an echo would do... here you get the echo at 10m ( LOUD ) at 50m ( LOud) and at 100m when it fades (loud) .... you can stop gagging now :) */

The code for this sample is located here, there is a client side component ( sample.gadget) and a server side component ( AtlasWS ) ... You will as usual have to change the URLs in AtlasServiceProxy.js from pointing to my servers to pointing to yours..

Cheers. ..

Making REST calls and using state (aka cookies) from a sidebar gadget...

jaimer — Fri, 29 Sep 2006 05:52:00 GMT

This will walk you through how to make REST (GET,POST) calls from a sidebar gadget using XmlHttp.. ( 20 mins or less, if you have asp .net)

There are plenty of samples on the web for using XmlHttp, so will go quick and we will touch in a few of the 'more intricate' scenarios people have asked about: Cookies + Session State + redirects when sidebar gadgets call a back-end...

The code for this sample is located here; there is a

client side component (sample.gadget) -- note that for this sample, login.js script points to my local webserver.. you will have to update that to point to your back-end..
server side component ( UsernameSite) .. this code uses ASP .NET, you can use any backend you want.. I used the easiest one for me.

Here is the gist of the Client-side code:
loginFlyout.html
Just has form data... trivial HTML form prompting for username & password for form user authentication. The "useGet" determines if making a POST or GET request, though practically they are the same code.

generic.js has the function to get the XmlHttp object, first we check for native IE 7 object, if not possible we use MSXML..

login.js has the code to send the XmlHttp request.. Note that for this samples we used Synchronous calls... that is usually bad :( ... but it saves mein sample code and keeps it simpler so I left as an exercise for you to change ..

function submitForm()
{
var item ; var DataToSend = "" ; var x ;

//parse the form to get the fields out ... and build the payload
for ( x = 0 ; x < document.form1.elements.length ; x++ )
{
DataToSend += document.form1.elements[x].id + "=" + document.form1.elements[x].value + "&" ;
}

var xmlhttp = GetXMLHTTP() ;
var useGET = document.getElementById('useGET').value;
if ( useGET )
{
xmlhttp.open("GET","http://jaimersvr/UsernameSite/Logon.aspx?ReturnUrl=%2fUsernamesite%2fSessionPage.aspx&" + DataToSend, false);
// Note this is a Synchronous call.. you should not do this.. call it async.. I did it this way to keep code simple .. .
xmlhttp.send();
}
else
{
xmlhttp.open("POST","http://jaimersvr/UsernameSite/Logon.aspx?ReturnUrl=%2fUsernamesite%2fSessionPage.aspx", false);
xmlhttp.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
// Note this is a Synchronous call.. you should not do this.. call it async.. I did it this way to keep code simple .. .
xmlhttp.send(DataToSend );
}

// This is example for a flyout communicating with main document ...
// check the System.Gadget.document documentation
System.Gadget.document.getElementById ('result').innerHTML = xmlhttp.responseText;

}

That is all the client side code ... :)
I will not explain the server side code unless I start getting requests for it.. I am guessing any one who is familiar with ASPX will know how to install it ... and those that are not familiar will be OK just knowing that REST works well from within sidebar..

Here is what the end to end sample does:

The xmlhttp call is doing is calling the login.aspx page on the server side ...
At successful login, the Loginaspx does a Redirect to SessionPage.aspx,
SessionPage.aspx merely displays the status of some session variables.. Every time you call this page, the variables get increased..

Here is how to run it:

Click the "ShowFlyout" URL in the gadget
Enter "test" (minus quotes) as Email address
Enter "test" (minus quotes) as Password
Click GetSession Data
Repeat previous step to see the variables get incremented
Add a new instance of this same gadget to the sidebar and repeat the first 4 steps; notice that multiple instances of the gadget are sharing the same back-end session data ... {good for some people, is it bad for any?}

Here are some of my observations:

Session Variables work fine... even the cookie is persisting fine ... [not sure who is doing the work, I am guessing xmlhttp]

Here are the gotchas or issues I saw (which for most part might not be an issue):

IE in Windows Vista runs in a different trust level, called Protected Mode... Read about it here.
This translates to the cookie we are persisting in our gadget and the cookie IE is reading are *not* shared.. You can have a separate cookie for each if that works for your model (e.g. the cookie just tells you my login or some thing like that)... but as far as passing state, no deal.. [ I have some ideas on how to get that to work, but might be too much]
I have also seldomly experienced an issue where the domain cookie that is to be persisted is not incrementing.. I have not figured this out.. it happens seldomly and goes away on its own.. If you are having problems with cookies, you can verify if things are working fine using a utility like IECV..

Hope that was useful; if the instructions are too hard ... let me know ..

The basic wiring for a vista sidebar gadget..

jaimer — Thu, 28 Sep 2006 22:54:00 GMT

[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:

wired the Init () call that will do all the wiring work

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