Using a Self-Written COM Object

How to use a self-written COM object within Widgets.

IMPORTANT: The information in this page referes to Widget which work under YWE 3.0.2 or previous versions. It might not work properly if you're using later versions of YWE! I hope to update the information soon.

=Introduction= Since version 2.0 of Yahoo Widget Engine, Widgets can communicate with COM objects (Only in the Windows version). Widgets can use COM to send/get information to/from applications or DLL files. This can be used to create Widgets with a lot more abilities than those which are provided by the YWE API. Not only is it possible to communicate with applications/DLL files which others wrote, it is also possible to write your own COM objects, especially for your Widget.

Next you're going to read how to use self-written COM objects within Widgets. You'll also find a sample Widget which demonstrates the use of self-written COM objects within Widgets. Finally, you may want to read the "FAQ" section for more information.

=Using the COM Object= One thing you need to know about COM objects, is that they must be registered on the user's computer before they can be used. If the COM object wasn't registered on the user's computer, the Widget will have to register it before it can use it. Otherwise the Widget only needs to create an instance of the COM object.

So make sure you have all the files needed for the COM object's registration. In case you write the COM object in a DLL file, you'll need to put both the *.dll file and the *.tlb file (which is generated when you compile the DLL file) in the Widget's folder.

Now you can start writing the Widget.

YWE 2.0 Widgets can use the COM.createObject command to create an instance of the COM objects in order to communicate with it. Always write this command inside a try...catch block, since if the instance of the COM object can't be created, either because there's an error or because it isn't registered yet, an error will be thrown.

Here's the code for creating the instance of the COM object:

try {  var comObject = COM.createObject(progID | CLSID);

if (comObject != null) {     // It is now safe to communicate with the COM object. } }

Replace progID | CLSID with the progID or CLSID of your COM object. You choose the progID and CLSID of your COM object while writting it.

It is always safe to check if the COM instance has been created successfully by comparing it to a null value. If the instance was created it is possible to use it to communicate with the COM object, otherwise, the comObject's value is a null object.

In this article, I'll show how to register COM objects which are written in a DLL file using regsvr32. However, if you write your COM object in an EXE file you can program it to register itself and then the Widget only needs to run the EXE file.

So, if the COM object hasn't been registered yet, an error will be thrown, and the Widget will catch it. Now you have to register the DLL file of the COM object:

catch(e) {  // An error has occurred. Most likely the COM object isn't registered on the user's computer. runCommand("regsvr32 /s COMObject.dll");

try {     var comObject = COM.createObject(progID | CLSID);

if (comObject != null) {        // It is now safe to communicate with the COM object. }     else {        // An instance of the COM object couldn't be created. }  }   catch(e2) {      // An instance of the COM object couldn't be created. } }

As you see, I run regsvr32 /s in order to register the DLL file of the COM object ("COMObject.dll") in background. Remember that the file must be in the same folder as the *.kon file of the Widget, or you'll have to specify its full path.

Notice that calling regsvr32 doesn't ensure that the file is registered. Many errors can happen which might prevent the file from being registered. Hence, always try to create an instance of the COM object again after registering it and check to see if it was created successfully (by comparing it to "null").

Now you can start communicating with the COM object. You might want to read pages 179-182 in the Yahoo® Widget Engine v. 3.0 Reference Guide for more information about using COM objects within Widgets.

Tip 1:

It is highly recommended to notify the users and even ask them to for permission to register the COM object on their computer. Many users want to know exactly what is being installed on their computer, and since most Widgets don't register COM objects, it is the Widget's author's responsibility to notify the user.

It is also recommended to add an option in the "Widget Preferences" window which can be used to unregister the COM object in case the user wants to remove it from the computer.

You can easily unregister the COM object by using regsvr32 again:

runCommand("regsvr32 /s /u COMObject.dll");

This will remove the Registry entries which were written during the COM object's registration process.

Don't forget to notify the user that the Widget won't be able to work properly if the COM object isn't registered.

Tip 2:

C++ users - any JavaScript object will be considered a "VARIANT *" by C++ COM objects, and any class instance will be "IDispatch *".

=Sample Widget= The best way to understand how a Widget can use a self-written COM object is to see the source code of a real one. So here's a demonstration Widget which shows how to use a self-written COM object. It uses a COM object which I wrote in a DLL file using MS Visual C++ 2005. I also included the source code of the COM object which I wrote thanks to a really useful article written by Stephane Rodriguez (You can find a link to it in the "FAQ" section).

I must admit that I'm a C++ beginner so the COM object might not be written well.

The Widget is called "Hello World" and it's really simple. All it does is to call a COM object which pops a message box on screen when the user clicks a button.

Click here to download it

=FAQ=

Why would I want to write my own COM object?
There can be many reasons to use a self-written COM object. You can use the benefits of other programming languages (Such as: C++, .NET language and etc.) to call Windows API commands, execute complex tasks and other things which JavaScript is incapable of.

What do I need to know?
COM objects can be written in many programming languages. I know of COM objects which were written using C++, Visual Basic and .NET languages, but I'm sure there are many others. So of course, you must know how to create a COM object using one of these languages.

For those of you who want to write COM objects in C++ or .NET languages, I recommend these articles:
 * Creating C++ COM objects by Stephane Rodriguez
 * Exposing .NET Components to COM by Nick Parker

You can also take a look at the demonstration Widget which is available for download above in order to see an example of a C++ COM object.

What do the Widget's users need?
Nothing except the Windows version of YWE v. 2.0 and above. Every Windows version of YWE (starting from v. 2.0) can run Widgets which use self-written COM objects.

What does the Widget install on the user's computer?
When using a COM object which was written in a DLL file you must include the DLL file in the Widget's package together with the TLB (*.tlb) file which is generated when the DLL file is compiled and is used for communication with it. These 2 files will be installed on the user's computer and the DLL file will be registered on the user's computer by the Widget. The registration process is being done using regsvr32 which is available on any Windows machine. It will write the appropriate entries to the Registry while registering the COM object. It is possible to unregister the COM object later if the user wants to remove the Widget.

If the COM object is written in an EXE file, the EXE file must be included in the Widget's package and can be set to register itself.

Will I be able to upload the Widget to the Gallery?
There are already many Widgets which use self-written COM objects in the Gallery. As far as I know, as long as the source code of the COM object is attached to the Widget's package, it will be checked by the Gallery censors, and if it doesn't contain any nasty code it will be accepted.

I want my Widget to use COM but will it work on the Mac too?
Unfortunately, COM is a technology which is only available within the Windows platform. However, it usually possible to use AppleScript in Mac systems while using COM in Windows systems to do the same tasks.

=Summary= COM is really powerful and can bring Widgets to a higher level. Writing your own COM objects can be both fun and useful as you are free to let your Widget do tasks which JavaScript is unable to deal with. However, don't use it unless you have to - sometimes you can use VBScript instead of using COM which takes more resources.

I hope you find this information useful.