Scripting Tools: Using the free COM Object Viewer from Microsoft

Scripting Tools: Using the free COM Object Viewer from Microsoft

This article is hopefully the first in a series of articles aimed at introducing you to a number of useful utilities (and resources) that you can call upon while developing your Lua scripts for the Dolphin screen access products.

In this particular article we will outline the basic use of the Microsoft Windows 2000 Resource Kit utility: “OLE/COM Object Viewer” - available from Microsoft’s web site: http://www.microsoft.com/downloads/details.aspx?FamilyID=5233b70d-d9b2-4cb5-aeb6-45664be858b6&DisplayLang=en

Microsoft’s OLE/COM Object Viewer tool allows you to browse through the COM objects registered on your system. This can prove useful for discovering COM objects that you might be able to access from your Dolphin Lua scripts.

What is COM?

COM (Component Object Model) technology, introduced by Microsoft in 1993, enables software components to communicate with one another using any computer programming language that supports COM technology. COM is mainly used by programmers to create re-usable software components and to link these components together in order to create larger applications and services.

COM is used extensively in a wide variety of applications, such as Microsoft Word, Excel, Outlook, PowerPoint, Project, Skype, Internet Explorer, Windows Media Player, iTunes, Lotus Notes, QuickBooks, to name but a few, as well as being used in a number of Windows application services, such as Microsoft Message Queuing, Microsoft Active Directory and Microsoft Windows Management and Instrumentation.

Why can accessing COM objects sometimes be useful from a script?

Accessing a particular application’s COM objects from a script can sometimes be useful. For instance, if you access the BarShape property of a Microsoft Excel Chart object you can determine the shape of the bar used in an Excel 3-D bar or column chart. For instance, if the BarShape property’s value is 1 the bar shape used in the chart is a pyramid coming to point at the value, if its 2, it’s a pyramid truncated at the value, if its 3 it’s a cylinder, etc., etc. Similarly, the ChartTitle object in Excel contains the title of the chart and the Legend object contains the legend of the chart.

So accessing a particular application’s COM objects from a script can be very useful for getting data from an application which otherwise would be impossible (or at least, very difficult) to get by pure screen reading techniques alone.

As another example, you can get the sample rate of the current track in iTunes, or even the track’s rating, by accessing the SampleRate or Rating properties (respectfully) of the CurrentTrack object in iTunes’ application object.

Similarly in Microsoft Word you can access the hidden comments for a particular paragraph using COM, or in Outlook, you can programmatically retrieve the start and end times of a particular appointment in the Outlook Calendar by accessing the Start and End properties of that particular appointment’s Appointment object.

COM automation also allows Dolphin Lua script writers to write scripts to perform repetitive (or difficult) tasks in Microsoft Word, or Excel, or even control Word or Excel remotely, and automatically alter the contents of an active document or worksheet programmatically. This can greatly enhance a screen reader user’s productivity by automating certain tasks.

Dolphin scripting has built in support for COM via the LuaCOM library. Documentation and examples of how to use LuaCOM are given in the Dolphin scripting manual. In addition, the full LuaCOM user guide can also be read on-line here: http://www.tecgraf.puc-rio.br/~rcerq/luacom/pub/1.3/luacom-browseable/

LuaCOM support also includes the ability to use COM objects without type information and also the ability to implement COM connection points for event handling and bi-directional communication.

How can I find out what COM objects are currently registered on my PC?

Before we dive headlong into using Microsoft’s OLE/COM Object Viewer tool to discover what objects are registered on your system, it might be a good idea for you to first gain a rudimentary understanding of what an object model actually is by studying some different application’s object models. And while everyone seems to have a slightly different definition of what an object model actually is, you can simply think of an object model as a detailed hierarchical description of the class that an object belongs to, as well as its associations with other objects, the attributes (properties) that make it unique and also the operations (methods) that can be performed on it.

The Microsoft Word 2007 Object Model Reference can be found on the Microsoft Developer Network here: http://msdn.microsoft.com/en-us/library/bb225019.aspx

As you peruse the Microsoft Word 2007 object model, remember that your main objective here isn’t to learn by heart the complete Microsoft Word object model, but instead, you just want to get a basic overview of how a common application’s object model is organized.

Example code

Another method of learning how to access COM objects from your Dolphin Lua scripts is of course by studying some examples. Below we have an example script that reads out the selected text in a Microsoft Word document by accessing the Text property of the Selection object in the currently active Microsoft Word document:

Using Microsoft’s free OLE/COM Object Viewer tool from the Windows 2000 Resource Kit

Now that we have had a brief taster of how to access the Microsoft Word application object in order to retrieve the selected text in the currently active document, it is time to download and install the COM Object Viewer utility from Microsoft’s web site: http://www.microsoft.com/downloads/details.aspx?FamilyID=5233b70d-d9b2-4cb5-aeb6-45664be858b6&DisplayLang=en

Once you have “OLE View” up and running on your PC you are now ready to begin browsing the objects currently registered on your PC in order to find other scriptable objects on your system.

1. First of all, under the “Object Classes” branch of the “OLE View” tree-view, open the branch named “All Objects” (as shown below). (“OLE View” may appear to pause for a few seconds while opening this branch depending on the number of objects that you currentlyave registered on your PC).

Now, not all of the objects registered on your system can be accessed from a Dolphin Lua script. However, a good rule of thumb is that if there is an “IDispatch” tree-view item under a particular object in the tree-view, then that object may be accessible from a script.

2. As an example, let’s suppose that you are interested in accessing a particular application’s objects from a Dolphin Lua script, such as Microsoft Word, then what you would do is first of all locate the “Microsoft Word Application” tree-view branch under “All Objects” in OLE View and open it. (I know that the Microsoft Word object model is already well documented on the MSDN web site, but you would use exactly this same technique for discovering whether other application’s objects are accessible via scripts and what the methods of those objects are).

3. Once you have opened the “Microsoft Word Application” object branch in the OLE View tree-view, check to see if there is a sub-branch called “IDispatch” underneath it. If there isn’t, then this particular object is not accessible from a script. If there is, then it may be possible to access this object from a script.

3. Anyway, once you have opened the “Microsoft Word Application” object branch in the OLE View tree-view, in the right-hand window pane there will now be displayed the ProgID (program ID) of this object. (You will probably need to use the screen reader’s virtual focus in order to get the focus over to that pane). You will need the object’s ProgID in order to reference it from your Dolphin Lua script when you call the luacom.CreateObject() or luacom.GetObject() functions at a later date. Incidentally, you don’t need to include the trailing numbers that follow the ProgID string. These are used for versioning purposes and omitting them indicates that you want to use the latest installed version of the application object. So therefore the ProgID for the Microsoft Word application object is “Word.Application” and you would access it from your Dolphin Lua script like so:

4. Next, you need to highlight the “IDispatch” sub-branch of the “Microsoft Word Application” object and then press SHIFT+10 and choose the option “View” from the context-menu that should pop-up.

5. When the “IDispatch Viewer” window pops up press the “View TypeInfo” button in order to open the “ITypeInfo Viewer” window.

6. When the “ITypeInfo Viewer” window has opened open up the “Methods” branch in the ITypeInfo tree-view (shown below). This will display all of the methods that belong to this object as sub-branches of the “Methods” tree-view branch.

7. For instance, if you highlight the method called “Keyboard” (which according to the Microsoft Word Object Model Reference returns or sets the keyboard language used by Microsoft Word - http://msdn.microsoft.com/en-us/library/bb221388.aspx) you will see in the right-hand window pane of the “ITypeInfo Viewer” window that this method accepts a single parameter of type long, which is the language and layout combination to which Microsoft Word should set the keyboard. And if this argument is omitted, this method returns a value of type long, which is the current language and layout setting of the keyboard. (You may need to use your screen reader’s virtual focus in order to get the focus into the right-hand window pane).

Therefore you would access the Word application object’s Keyboard() method from your Dolphin Lua script like so:

Now, although in this particular example we have discovered the methods and ProgID of the Microsoft Word application object, you can also use this same tool and exactly the same technique for objects registered by other applications on your system.

Using this technique you will be able to discover other objects that are scriptable on your system and if you are uncertain of how to interpret the information that OLE View displays in its method pane, then by Googling the ProgID and a couple of the method names you will quite often find a wealth of information, documentation (and sometimes even sample scripts) available on the Internet about accessing a particular object’s methods and properties.