Using Pointers

If you have ever programmed in C or C++ you know how powerful (and annoying) pointers can be. The Component Object Model makes use of pointers to allow components and client code to interchange values. These pointers come in the form of either out or in/out parameters. SWTtoCOM provides several extension classes that implement the pointer functionality. See the au.com.swz.swttocom.types.pointers package for a list of available pointer classes.

To use a pointer class is easy and depends on whether the component is using the pointer for an out or in/out purpose. To use the pointer as an out value you simply need to create an instance of the pointer class and pass it as a parameter. The following example demonstrates a StringPointer being used as an out parameter.

StringPointer ptrIconPath = new StringPointer();
int nIconIndex = link.getIconLocation(ptrIconPath);
String iconPath = ptrIconPath.getValue();
.. Use the iconPath String as normal

If the out parameter is part of an event then the component is expecting the client code to populate the pointer with a value during event execution. The following example demonstrates how to populate a BooleanPointer in an event method of MSWord to prevent a document from closing.

public void documentBeforeClose(Document doc, BooleanPointer cancel) {
   cancel.setValue(true);
}

Finally to use a pointer as an in/out parameter the component is expecting the pointer to be populated on the making of the call and will populate the pointer before returning. The following example demonstrates using the IntPointer as an in/out parameter.

IntPointer ptrInt = new IntPointer();
ptrInt.setValue(25);
myComponent.getSetIndex(ptrInt);
int returnIndex = ptrInt.getValue();

NOTE: Pointers allocate system memory using the win32 GlobalAlloc function. This memory is automatically freed by SWTtoCOM via the generated wrapper code. Be very careful using methods other than getValue and setValue on pointers since this can have adverse side affects. For example calling the pointer dispose method in an event handler will almost certainly cause jvm instability and more than likely result in a GPF (General Protection Fault) once the event handler returns execution to the component.