Functions and Directives

Function GetObject() Foundation

Returns a reference to an existing COM/ActiveX component.

Syntax
GetObject( [<cFile>], [<cProgID>], [<lCreate>] ) --> oAutomationObject | NIL
Parameters
<cFile>
The optional argument <cFile> is the name of a file. The file name must be specified including fully-qualified path. If <cFile> is omitted, <cProgID> is required.
<cProgID>
The argument <cProgID> is the ProgID (Programmatic Identifier) of the ActiveX component to be returned.
A ProgID has the syntax:
ApplicationName.ObjectName.Version 
where the last part (.Version) is optional. Version defaults to the highest version installed. Use regedit.exe and inspect the entries under HKEY_CLASSES_ROOT for valid <ProgIDs>.
<lCreate>
The optional argument <lCreate> specifies whether a new instance shall be created if it does not exist, yet. This parameter defaults to .T. (true).
Return

The function returns an object of class AutomationObject. If the COM/ActiveX component does not exist and/or cannot be created, return value is NIL. In case GetObject() returns NIL, the functions ComLastError() and ComLastMessage() can be used to query the error number and the error message.

Description

The AutomationObject returned can be used to access the methods and properties of the COM/ActiveX component, in the same way as with an ordinary Xbase++ object. Method calls as well as read or write access to a property (instance variable) is routed automatically to the COM/ActiveX component.

Unlike CreateObject(), GetObject() tries to return a running COM/ActiveX component. If the object does not exist and .F. was not passed with parameter <lCreate>, GetObject() creates a new COM/ActiveX component.

For performance reasons, CreateObject() returns an instance of class AutomationObject. However, if an Xbase++ application needs to react to COM/ActiveX events, an instance of class ActiveXObject is required instead. Please see the example below that illustrates how to create an ActiveXObject from an AutomationObject. Also see method AutomationObject:dynamicCast()for further information.

Examples
Example of how to use the GetObject() function.
#pragma library( "ascom10.lib" ) 

PROCEDURE Main 
   LOCAL oApp 

   oApp := GetObject( , "Word.Application" ) 

   IF NIL == oApp 
     // Word.Application could not be created. 
     ? "Error: ", ComLastError() 
     ? "Description:" 
     ? ComLastMessage() 
     RETURN 
   ENDIF 

   // Access a property of the Word application 
   ? oApp:visible 
   // Assign a property 
   oApp:visible := ! oApp:visible 
   // Call a method 
   oApp:quit() 
   // destroy the reference 
   oApp:destroy() 
RETURN 
Reacting to COM/ActiveX events of an object returned by GetObject()
#pragma library( "ascom10.lib" ) 

PROCEDURE Main 
   LOCAL oApp 

   oApp := GetObject( , "Word.Application" ) 

   IF NIL == oApp 
     // Word.Application could not be created. 
     ? "Error: ", ComLastError() 
     ? "Description:" 
     ? ComLastMessage() 
     RETURN 
   ENDIF 

   // Create an ActiveXObject from the AutomationObject 
   // returned by the GetObject() function 
   oApp := oApp:dynamicCast( ActiveXObject() ) 

   // Set callback code block for "Quit" event 
   oApp:quit := {|| QOUT("Finished!") } 

   oApp:visible := .T. 

   WAIT "Quit word for executing code block" 

   // Clean up 
   oApp:quit() 
   oApp:destroy() 
RETURN 
Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.