A Pictorial Tutorial
After you’ve written your first couple of sidebar gadgets, you may find yourself wanting to access system functionality that isn’t exposed by the gadget APIs. If you know how to do what you want using C++, then all you need is an ActiveX control in order to expose that functionality to your gadget. This blog post will show you how.
If you missed the first part of this tutorial, you can find it here:
Taking Control
Next, let’s create a simple ActiveX control. I’m going to use Visual Studio and the ATL framework; together they make it very easy. Before we start, though, we need to decide what functionality we will implement in our ActiveX control. To start off, I’m going to make a function named ‘Echo’ that takes a string, and simply returns the same string. Later we’ll do something a little more interesting.
Start up visual studio. From the File menu, select New Project. You’ll get a “New Project” dialog box, where you’ll pick a project template named “ATL Project”, and give the project a name “TestActiveX”:
Next the ATL Project Wizard will pop up – just click the “Finish” button, we’ll accept all the default settings:
Switch your VS explorer window over to “Class View”, right-click on “TestActiveX”, and add a new class to your project:
The “Add Class” dialog will pop up – select the “ATL Simple Object” template and click the “Add” button:
Now you’ll see the “ATL Simple Object Wizard” – give the object a simple name (I used “TestControl”), and click “Next”:
On the “Options” pane that comes up next, go ahead and select the “ISupportErrorInfo” option – I want the control to return decent error information to the calling script if something goes wrong. Then click “Finish”:
Now let’s add the function that’s actually going to do the work. Add a new method to your ITestControl interface, as shown below:
Yet another wizard will pop up – in this one, tell VS that you want to name your method “Echo”, and add the first of two parameters by entering the appropriate information and clicking “Add”, as shown below:
Now tell VS that the method should return a string back to the script. We do this by selecting a parameter type of “BSTR *” and selecting the parameter attributes as shown below:
All the rest of the method default values are fine, so click “Finish” to complete the operation and add the “Echo” method to our ActiveX object:
Now we have a fully-functional ActiveX control, but it doesn’t do anything – remember, we want the “Echo” function to return the string that is passed in. So let us add that bit of implementation. Double-click on the “Echo” method of the CTestControl class, in the class explorer:
Where it says “TODO: Add your implementation code here”, add the following source code:
STDMETHODIMP CTestControl::Echo(BSTR input, BSTR* output)
{
// TODO: Add your implementation code here
*output = SysAllocString(input);
if (*output)
{
return S_OK;
}
return AtlReportError(
CLSID_TestControl,
L"Could not allocate echoed string",
GUID_NULL, // system-defined error code
E_OUTOFMEMORY);
}
These lines appear simple, but they cover some important aspects of automation code. Note the use of the BSTR type, and SysAllocString. These are core features of almost all scriptable ActiveX controls, so if you’re not familiar with them, you should spend a few minutes up on http://msdn.microsoft.com/library and look them up.
Another interesting element – the use of AtlReportError. Remember we selected the “ISupportErrorInfo” option when we created our control class? This is where we close the loop on that functionality – you can use AtlReportError to return a nice legible error message to the calling script; in this case, the text “Could not allocate echoed string”. If this error is returned, the script will see an exception coming out of the function call, and can get that text message out of the exception object. (If you go back and look, you’ll see that our test gadget will catch and display exception errors.)
Now our initial ActiveX control implementation is complete – you can press F7 to build and register your new ActiveX control.
What About The Gadget?
Ok, now we have this cool new Echo function – but we wanted a gadget that would use this functionality. Let’s do it; replace this line in your gadget.html:
out("Hello, world!");
With these lines:
var myControl = new ActiveXObject(“TestActiveX.TestControl”);
out(myControl.Echo(“Bruce Williams”));
Add the gadget to your sidebar, and viola!
...unfortunately, the MSN Spaces blog engine won't let me publish this tutorial in one go (although it did let me type it all in...), so I'm going to have to break it up into chunks. Tune in for part 3...
Conclusion
I hope you enjoyed this tutorial, and found it useful. I welcome any feedback and corrections – send them to Bruce.Williams@microsoft.com.
Tools 
+-+Windows+Live&referrer=){kind=small}
