IAccessible::get_accRole

In the documentation for this method, it is clearly stated that it accepts two parameters.  The first is the accessible objects child id.  This variant is either equal to CHILDID_SELF, which defines that you are seeking information about the current object, or the child ID, which will get the role of the defined child.  This parameter should be of variant type VT_I4.  The second parameter is a variant pointer that will return the accessibility role of the object.  In the documentation this is stated as being an object role constant such as ROLE_SYSTEM_WINDOW or ROLE_SYSTEM_CLIENT.  This parameter is where I have run into problems with how get_accRole has been implemented by the creator of the object.

In addition to stating the second parameter should return an object role constant, it also states that the variant type MUST be of type VT_I4.  This does not seem to be enforced though.  I have run into numerous situations (developing in Microsoft Office) where the variant type is VT_BSTR.  A string is considered invalid for this variant and can cause quite a headache when unexpected.  This occurs in a Microsoft product none the less, the creators of MSAA.  This is just one case that I have run into where the value is invalid, and it begs the question, what other variant types might this return?  That is totally up to the developer implemented get_accRole in his object.  The simple solution to this problem is to always check the variant type that is returned before doing any operations on it to avoid errors.

IAccessible::get_accState

After research into the get_accRole method, it came as no surprise the get_accState suffers from the same issues.  As with get_accRole, get_accState takes two parameters.  The first is the child id, and the second is the out variable to hold the state constant.  The documentation for get_accState states that the second argument will return a variant type of VT_I4 that corresponds to one of the object state constants.  Though in using the accState with Microsoft Office and Lotus Notes I have run into times where the state is of variant type VT_BSTR (string).  Again the solution is to always check the variant type that is returned before using it in any operations.

—–

As I continue to dive deeper into the world of MSAA, I’ll keep this blog up to date with the inconsistencies I find.  If you have any that you have come across in working with MSAA tell me about them.  I’ll be glad to look into them to see if there is a workaround or a clean way to handle them.  I’ll leave with you with a code snippet that shows how to get the accRole and compare it with an object role constant.

Compare accessibility role:

//Code below assumes that IAccessible object and ChildID are both passed in parameters.
bool CompareAccRole(IAccessible* pIAccessible, VARIANT childID, LONG objectRoleConstant)
{
	VARIANT accObjectRole;
	HRESULT hr = pIAccessible->get_accRole(childID, &accObjectRole);
	if(hr == S_OK && accObjectRole.vt == VT_I4)
	{
		if(accObjectRole.lVal & objectRoleConstant)
			return true;
	}
	return false;	
}

Useful Links:

• IAccessible MSDN Documentation
• IAccessible::get_accRole MSDN Documentation
• Object Role Constants MSDN
• IAccessible::get_accState MSDN Documentation
• Object State Constants MSDN

First we obtain the hwnd of the Microsoft Excel Process:

//The main window in Microsoft Excel has a class name of XLMAIN
HWND excelWindow = FindWindow(L"XLMAIN", NULL);

We can then traverse the child windows until we find the one with classname EXCEL7:

//Use the EnumChildWindows function to iterate through all child windows until we find EXCEL7
EnumChildWindows(excelWindow, (WNDENUMPROC) EnumChildProc, (LPARAM)1);

static BOOL EnumChildProc(HWND hwnd, LPARAM)
{
     WCHAR szClassName[64];
     if(GetClassNameW(hwnd, szClassName, 64))
     {
          if(_wcsicmp(szClassName, L"EXCEL7") == 0)
          {
               //Get AccessibleObject
               Excel::Window* pWindow = NULL;
               HRESULT hr = AccessibleObjectFromWindow(hwnd, OBJID_NATIVEOM, __uuidof(Excel::Window), (void**)&pWindow);
               if(hr == S_OK)
               {
                    //Excel object is now in pWindow pointer, from this you can obtain the document or application
                    Excel::_Application* pApp = NULL;
                    pWindow->get_Application(&pApp);
                    pWindow->Release();
               }
               return false;     // Stops enumerating through children
          }
     }
     return true;
}

Next we obtain our Excel::Window object through AccessibleObjectFromWindow:

//Get AccessibleObject
Excel::Window* pWindow = NULL;
HRESULT hr = AccessibleObjectFromWindow(hwnd, OBJID_NATIVEOM, __uuidof(Excel::Window), (void**)&pWindow);

That’s it! We now have our Excel::Window COM Object. From this object we can obtain the Excel::Application and Excel::Workbook objects, allowing us full interaction with the active document. So with just a few lines of code, we now have access to automate an Excel 2007 document.

Full source code:

#include <windows.h>
#include <oleacc.h>
#include "msexcel.h"

static BOOL EnumChildProc(HWND hwnd, LPARAM)
{
     WCHAR szClassName[64];
     if(GetClassNameW(hwnd, szClassName, 64))
     {
          if(_wcsicmp(szClassName, L"EXCEL7") == 0)
          {
               //Get AccessibleObject
               Excel::Window* pWindow = NULL;
               HRESULT hr = AccessibleObjectFromWindow(hwnd, OBJID_NATIVEOM, __uuidof(Excel::Window), (void**)&pWindow);
               if(hr == S_OK)
               {
                    //Excel object is now in pWindow pointer, from this you can obtain the document or application
                    Excel::_Application* pApp = NULL;
                    pWindow->get_Application(&pApp);
                    pWindow->Release();
               }
               return false;     // Stops enumerating through children
          }
     }
	 return true;
}
int main( int argc, CHAR* argv[])
{
     //The main window in Microsoft Excel has a class name of XLMAIN
     HWND excelWindow = FindWindow(L"XLMAIN", NULL);

     //Use the EnumChildWindows function to iterate through all child windows until we find _WwG
     EnumChildWindows(excelWindow, (WNDENUMPROC) EnumChildProc, (LPARAM)1);

     return 0;
}

Useful Links for this post:

• AccessibleObjectFromWindow Documentation
• Using Visual C++ to Automate Office
• EnumChildWindows Documentation

Key phrases: Accessing Excel 2007 COM object using AccessibleObjectFromWindow, Automating Excel 2007 with Microsoft Active Accessibility MSAA
Update: I’ve updated the full source to utilize get_Application. get_Document was in place previously, which was leftover from my Word source code.

First we obtain the hwnd of the Microsoft Word Process:

//The main window in Microsoft Word has a class name of OpusApp
HWND wordWindow = FindWindow(L"OpusApp", NULL);

We can then traverse the child windows until we find the one with classname _WwG:

//Use the EnumChildWindows function to iterate through all child windows until we find _WwG
EnumChildWindows(wordWindow, (WNDENUMPROC) EnumChildProc, (LPARAM)1);

static BOOL EnumChildProc(HWND hwnd, LPARAM)
{
     WCHAR szClassName[64];
     if(GetClassNameW(hwnd, szClassName, 64))
     {
          if(_wcsicmp(szClassName, L"_WwG") == 0)
          {
               //Get AccessibleObject
               Word::Window* pWindow = NULL;
               HRESULT hr = AccessibleObjectFromWindow(hwnd, OBJID_NATIVEOM, __uuidof(Word::Window), (void**)&pWindow);
               if(hr == S_OK)
               {
                    //Word object is now in pWindow pointer, from this you can obtain the document or application
                    Word::_Document* pDoc = NULL;
                    pWindow->get_Document(&pDoc);
               }
               return false;     // Stops enumerating through children
          }
     }
	 return true;
}

Next we obtain our Word::Window object through AccessibleObjectFromWindow:

Word::Window* pWindow = NULL;
HRESULT hr = AccessibleObjectFromWindow(hwnd, OBJID_NATIVEOM, __uuidof(Word::Window), (void**)&pWindow);

That’s it!  We now have our Word::Window COM Object.  From this object we can obtain the Word::Application and Word::Document objects, allowing us full interaction with the active document.  So with just a few lines of code, we now have access to automate a word 2007 document.

Full source code:

#include <windows.h>
#include <oleacc.h>
#include "msword.h"

static BOOL EnumChildProc(HWND hwnd, LPARAM)
{
	WCHAR szClassName[64];
	if(GetClassNameW(hwnd, szClassName, 64))
	{
		if(_wcsicmp(szClassName, L"_WwG") == 0)
		{
			//Get AccessibleObject
			Word::Window* pWindow = NULL;
			HRESULT hr = AccessibleObjectFromWindow(hwnd, OBJID_NATIVEOM, __uuidof(Word::Window), (void**)&pWindow);
			if(hr == S_OK)
			{
				//Word object is now in pWindow pointer, from this you can obtain the document or application
				Word::_Document* pDoc = NULL;
				pWindow->get_Document(&pDoc);
			}
			return false;     // Stops enumerating through children
		}
	}
	return true;
}
int main( int argc, CHAR* argv[])
{
	//The main window in Microsoft Word has a class name of OpusApp
	HWND wordWindow = FindWindow(L"OpusApp", NULL);

	//Use the EnumChildWindows function to iterate through all child windows until we find _WwG
	EnumChildWindows(wordWindow, (WNDENUMPROC) EnumChildProc, (LPARAM)1);

	return 0;
}

The logic to find the correct window can be changed for multiple instances of Word.  Also, you must have the Word type library imported to use the Word COM API.  We’ll leave those two for another topic on another date. Check back later in the week for a follow up post on how to access Microsoft Excel 2007 in the same manner.

Useful Links for this post:

• AccessibleObjectFromWindow Documentation
• Using Visual C++ to Automate Office
• EnumChildWindows Documentation

Key phrases: Accessing Word 2007 COM object using AccessibleObjectFromWindow, Automating Word 2007 with Microsoft Active Accessibility MSAA

• Microsoft’s documentation on IAccessible interface
• Sara Ford’s Weblog on Accessibility
• User Interface Element References for Control in Accessibility

Over the past 6 months, I used MSAA to develop against Microsoft Access 2003.  Although it was a painful process to get working, the end result gives quite a bit of flexibility in automating Access.  That being said, there are still a lot of hurdles to overcome, and Accessibility has definitely left many things to be desired.  In the next few weeks I will be posting about my first impressions of Accessibility and it’s inconsistencies.