Version: 2.9.4
Public Member Functions
wxAutomationObject Class Reference

#include </home/zeitlin/src/wx/github/interface/wx/msw/ole/automtn.h>

Inheritance diagram for wxAutomationObject:

Detailed Description

The wxAutomationObject class represents an OLE automation object containing a single data member, an IDispatch pointer.

It contains a number of functions that make it easy to perform automation operations, and set and get properties. The class makes heavy use of the wxVariant class.

The usage of these classes is quite close to OLE automation usage in Visual Basic. The API is high-level, and the application can specify multiple properties in a single string. The following example gets the current Excel instance, and if it exists, makes the active cell bold.

    wxAutomationObject excelObject;
      if (excelObject.GetInstance("Excel.Application"))
          excelObject.PutProperty("ActiveCell.Font.Bold", @true);

Note that this class obviously works under Windows only.

Availability:  only available for the wxMSW port.

Library:  wxCore
Category:  Data Structures
参照:
wxVariant

Public Member Functions

 wxAutomationObject (WXIDISPATCH *dispatchPtr=NULL)
 Constructor, taking an optional IDispatch pointer which will be released when the object is deleted.
 ~wxAutomationObject ()
 Destructor.
bool CreateInstance (const wxString &progId) const
 Creates a new object based on the ProgID, returning true if the object was successfully created, or false if not.
bool IsOk () const
 Checks if the object is in a valid state.
void * GetDispatchPtr () const
 Gets the IDispatch pointer.
bool GetInstance (const wxString &progId, int flags=wxAutomationInstance_CreateIfNeeded) const
 Retrieves the current object associated with the specified ProgID, and attaches the IDispatch pointer to this object.
bool GetObject (wxAutomationObject &obj, const wxString &property, int noArgs=0, wxVariant args[]=NULL) const
 Retrieves a property from this object, assumed to be a dispatch pointer, and initialises obj with it.
bool Invoke (const wxString &member, int action, wxVariant &retValue, int noArgs, wxVariant args[], const wxVariant *ptrArgs[]=0) const
 This function is a low-level implementation that allows access to the IDispatch Invoke function.
void SetDispatchPtr (WXIDISPATCH *dispatchPtr)
 Sets the IDispatch pointer.
wxVariant CallMethod (const wxString &method, int noArgs, wxVariant args[]) const
 Calls an automation method for this object.
const wxVariant CallMethod (const wxString &method,...) const
 Calls an automation method for this object.
wxVariant GetProperty (const wxString &property, int noArgs, wxVariant args[]) const
 Gets a property value from this object.
const wxVariant GetProperty (const wxString &property,...) const
 Gets a property value from this object.
bool PutProperty (const wxString &property, int noArgs, wxVariant args[])
 Puts a property value into this object.
const bool PutProperty (const wxString &property,...)
 Puts a property value into this object.

List of all members.


Constructor & Destructor Documentation

wxAutomationObject::wxAutomationObject ( WXIDISPATCH *  dispatchPtr = NULL)

Constructor, taking an optional IDispatch pointer which will be released when the object is deleted.

wxAutomationObject::~wxAutomationObject ( )

Destructor.

If the internal IDispatch pointer is non-null, it will be released.


Member Function Documentation

wxVariant wxAutomationObject::CallMethod ( const wxString method,
int  noArgs,
wxVariant  args[] 
) const

Calls an automation method for this object.

The first form takes a method name, number of arguments, and an array of variants. The second form takes a method name and zero to six constant references to variants. Since the variant class has constructors for the basic data types, and C++ provides temporary objects automatically, both of the following lines are syntactically valid:

Note that method can contain dot-separated property names, to save the application needing to call GetProperty several times using several temporary objects. 以下に例を示します:

const wxVariant wxAutomationObject::CallMethod ( const wxString method,
  ... 
) const

Calls an automation method for this object.

The first form takes a method name, number of arguments, and an array of variants. The second form takes a method name and zero to six constant references to variants. Since the variant class has constructors for the basic data types, and C++ provides temporary objects automatically, both of the following lines are syntactically valid:

Note that method can contain dot-separated property names, to save the application needing to call GetProperty several times using several temporary objects. 以下に例を示します:

bool wxAutomationObject::CreateInstance ( const wxString progId) const

Creates a new object based on the ProgID, returning true if the object was successfully created, or false if not.

void* wxAutomationObject::GetDispatchPtr ( ) const

Gets the IDispatch pointer.

Notice that the return value of this function is an untyped pointer but it can be safely cast to IDispatch.

bool wxAutomationObject::GetInstance ( const wxString progId,
int  flags = wxAutomationInstance_CreateIfNeeded 
) const

Retrieves the current object associated with the specified ProgID, and attaches the IDispatch pointer to this object.

If attaching to an existing object failed and flags includes wxAutomationInstance_CreateIfNeeded flag, a new object will be created. Otherwise this function will normally log an error message which may be undesirable if the object may or may not exist. The wxAutomationInstance_SilentIfNone flag can be used to prevent the error from being logged in this case.

Returns true if a pointer was successfully retrieved, false otherwise.

Note that this cannot cope with two instances of a given OLE object being active simultaneously, such as two copies of Excel running. Which object is referenced cannot currently be specified.

Parameters:
progIdCOM ProgID, e.g. "Excel.Application"
flagsThe creation flags (this parameters was added in wxWidgets 2.9.2)
bool wxAutomationObject::GetObject ( wxAutomationObject obj,
const wxString property,
int  noArgs = 0,
wxVariant  args[] = NULL 
) const

Retrieves a property from this object, assumed to be a dispatch pointer, and initialises obj with it.

To avoid having to deal with IDispatch pointers directly, use this function in preference to GetProperty() when retrieving objects from other objects. Note that an IDispatch pointer is stored as a void* pointer in wxVariant objects.

参照:
GetProperty()
wxVariant wxAutomationObject::GetProperty ( const wxString property,
int  noArgs,
wxVariant  args[] 
) const

Gets a property value from this object.

The first form takes a property name, number of arguments, and an array of variants. The second form takes a property name and zero to six constant references to variants. Since the variant class has constructors for the basic data types, and C++ provides temporary objects automatically, both of the following lines are syntactically valid:

Note that property can contain dot-separated property names, to save the application needing to call GetProperty several times using several temporary objects.

const wxVariant wxAutomationObject::GetProperty ( const wxString property,
  ... 
) const

Gets a property value from this object.

The first form takes a property name, number of arguments, and an array of variants. The second form takes a property name and zero to six constant references to variants. Since the variant class has constructors for the basic data types, and C++ provides temporary objects automatically, both of the following lines are syntactically valid:

Note that property can contain dot-separated property names, to save the application needing to call GetProperty several times using several temporary objects.

bool wxAutomationObject::Invoke ( const wxString member,
int  action,
wxVariant retValue,
int  noArgs,
wxVariant  args[],
const wxVariant ptrArgs[] = 0 
) const

This function is a low-level implementation that allows access to the IDispatch Invoke function.

It is not meant to be called directly by the application, but is used by other convenience functions.

Parameters:
memberThe member function or property name.
actionBitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF, DISPATCH_METHOD.
retValueReturn value (ignored if there is no return value)
noArgsNumber of arguments in args or ptrArgs.
argsIf non-null, contains an array of variants.
ptrArgsIf non-null, contains an array of constant pointers to variants.
Returns:
true if the operation was successful, false otherwise.
注意:
Two types of argument array are provided, so that when possible pointers are used for efficiency.
bool wxAutomationObject::IsOk ( ) const

Checks if the object is in a valid state.

Returns true if the object was successfully initialized or false if it has no valid IDispatch pointer.

参照:
GetDispatchPtr()
const bool wxAutomationObject::PutProperty ( const wxString property,
  ... 
)

Puts a property value into this object.

The first form takes a property name, number of arguments, and an array of variants. The second form takes a property name and zero to six constant references to variants. Since the variant class has constructors for the basic data types, and C++ provides temporary objects automatically, both of the following lines are syntactically valid:

Note that property can contain dot-separated property names, to save the application needing to call GetProperty several times using several temporary objects.

bool wxAutomationObject::PutProperty ( const wxString property,
int  noArgs,
wxVariant  args[] 
)

Puts a property value into this object.

The first form takes a property name, number of arguments, and an array of variants. The second form takes a property name and zero to six constant references to variants. Since the variant class has constructors for the basic data types, and C++ provides temporary objects automatically, both of the following lines are syntactically valid:

Note that property can contain dot-separated property names, to save the application needing to call GetProperty several times using several temporary objects.

void wxAutomationObject::SetDispatchPtr ( WXIDISPATCH *  dispatchPtr)

Sets the IDispatch pointer.

This function does not check if there is already an IDispatch pointer. You may need to cast from IDispatch* to WXIDISPATCH* when calling this function.

 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Defines