|
|
|
|
@ -0,0 +1,210 @@
|
|
|
|
|
\section{\class{wxAutomationObject}}\label{wxautomationobject}
|
|
|
|
|
|
|
|
|
|
The {\bf 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 \helpref{wxVariant}{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.
|
|
|
|
|
|
|
|
|
|
{\small
|
|
|
|
|
\begin{verbatim}
|
|
|
|
|
wxAutomationObject excelObject;
|
|
|
|
|
if (excelObject.GetInstance("Excel.Application"))
|
|
|
|
|
excelObject.PutProperty("ActiveCell.Font.Bold", TRUE);
|
|
|
|
|
\end{verbatim}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
Note that this class works under Windows only, and currently only for Visual C++.
|
|
|
|
|
|
|
|
|
|
\wxheading{Derived from}
|
|
|
|
|
|
|
|
|
|
\helpref{wxObject}{wxobject}
|
|
|
|
|
|
|
|
|
|
\wxheading{See also}
|
|
|
|
|
|
|
|
|
|
\helpref{wxVariant}{wxvariant}
|
|
|
|
|
|
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
|
|
|
|
|
|
\membersection{wxAutomationObject::wxAutomationObject}\label{wxautomationobjectctor}
|
|
|
|
|
|
|
|
|
|
\func{}{wxAutomationObject}{\param{WXIDISPATCH*}{ dispatchPtr = NULL}}
|
|
|
|
|
|
|
|
|
|
Constructor, taking an optional IDispatch pointer which will be released when the
|
|
|
|
|
object is deleted.
|
|
|
|
|
|
|
|
|
|
\membersection{wxAutomationObject::\destruct{wxAutomationObject}}\label{wxautomationobjectdtor}
|
|
|
|
|
|
|
|
|
|
\func{}{\destruct{wxAutomationObject}}{\void}
|
|
|
|
|
|
|
|
|
|
Destructor. If the internal IDispatch pointer is non-null, it will be released.
|
|
|
|
|
|
|
|
|
|
\membersection{wxAutomationObject::CallMethod}\label{wxautomationobjectcallmethod}
|
|
|
|
|
|
|
|
|
|
\constfunc{wxVariant}{CallMethod}{\param{const wxString\&}{ method}, \param{int}{ noArgs},
|
|
|
|
|
\param{wxVariant }{args[]}}
|
|
|
|
|
|
|
|
|
|
\constfunc{wxVariant}{CallMethod}{\param{const wxString\&}{ method}, \param{...}{}}
|
|
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
{\small
|
|
|
|
|
\begin{verbatim}
|
|
|
|
|
wxVariant res = obj.CallMethod("Sum", wxVariant(1.2), wxVariant(3.4));
|
|
|
|
|
wxVariant res = obj.CallMethod("Sum", 1.2, 3.4);
|
|
|
|
|
\end{verbatim}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
Note that {\it method} can contain dot-separated property names, to save the application
|
|
|
|
|
needing to call GetProperty several times using several temporary objects. For example:
|
|
|
|
|
|
|
|
|
|
{\small
|
|
|
|
|
\begin{verbatim}
|
|
|
|
|
object.CallMethod("ActiveCell.Font.ShowDialog", "My caption");
|
|
|
|
|
\end{verbatim}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
\membersection{wxAutomationObject::ConvertOleToVariant}\label{wxautomationobjectconvertoletovariant}
|
|
|
|
|
|
|
|
|
|
\constfunc{bool}{ConvertOleToVariant}{\param{const VARIANTARG\&}{ oleVariant}, \param{const wxVariant\&}{ variant}}
|
|
|
|
|
|
|
|
|
|
Converts the given VARIANTARG object to a wxVariant. IDispatch pointers are converted to the ``void*" type.
|
|
|
|
|
|
|
|
|
|
\membersection{wxAutomationObject::ConvertVariantToOle}\label{wxautomationobjectconvertvarianttoole}
|
|
|
|
|
|
|
|
|
|
\constfunc{bool}{ConvertVariantToOle}{\param{const wxVariant\&}{ variant}, \param{VARIANTARG\&}{ oleVariant}}
|
|
|
|
|
|
|
|
|
|
Converts the given wxVariant object to a VARIANTARG. The ``void*" type is assumed to be an
|
|
|
|
|
IDispatch pointer.
|
|
|
|
|
|
|
|
|
|
\membersection{wxAutomationObject::CreateInstance}\label{wxautomationobjectcreateinstance}
|
|
|
|
|
|
|
|
|
|
\constfunc{bool}{CreateInstance}{\param{const wxString\&}{ classId}}
|
|
|
|
|
|
|
|
|
|
Creates a new object based on the class id, returning TRUE if the object was successfully created,
|
|
|
|
|
or FALSE if not.
|
|
|
|
|
|
|
|
|
|
\membersection{wxAutomationObject::GetDispatchPtr}\label{wxautomationobjectgetdispatchptr}
|
|
|
|
|
|
|
|
|
|
\constfunc{IDispatch*}{GetDispatchPtr}{\void}
|
|
|
|
|
|
|
|
|
|
Gets the IDispatch pointer.
|
|
|
|
|
|
|
|
|
|
\membersection{wxAutomationObject::GetInstance}\label{wxautomationobjectgetinstance}
|
|
|
|
|
|
|
|
|
|
\constfunc{bool}{GetInstance}{\param{const wxString\&}{ classId}}
|
|
|
|
|
|
|
|
|
|
Retrieves the current object associated with a class id, and attaches the IDispatch pointer
|
|
|
|
|
to this object. Returns TRUE if a pointer was succesfully 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.
|
|
|
|
|
|
|
|
|
|
\membersection{wxAutomationObject::GetObject}\label{wxautomationobjectgetobject}
|
|
|
|
|
|
|
|
|
|
\constfunc{bool}{GetObject}{\param{wxAutomationObject\&}{obj} \param{const wxString\&}{ property},
|
|
|
|
|
\param{int}{ noArgs = 0}, \param{wxVariant }{args[] = NULL}}
|
|
|
|
|
|
|
|
|
|
Retrieves a property from this object, assumed to be a dispatch pointer, and initialises {\it obj} with it.
|
|
|
|
|
To avoid having to deal with IDispatch pointers directly, use this function in preference
|
|
|
|
|
to \helpref{wxAutomationObject::GetProperty}{wxautomationobjectgetproperty} when retrieving objects
|
|
|
|
|
from other objects.
|
|
|
|
|
|
|
|
|
|
Note that an IDispatch pointer is stored as a void* pointer in wxVariant objects.
|
|
|
|
|
|
|
|
|
|
\wxheading{See also}
|
|
|
|
|
|
|
|
|
|
\helpref{wxAutomationObject::GetProperty}{wxautomationobjectgetproperty}
|
|
|
|
|
|
|
|
|
|
\membersection{wxAutomationObject::GetProperty}\label{wxautomationobjectgetproperty}
|
|
|
|
|
|
|
|
|
|
\constfunc{wxVariant}{GetProperty}{\param{const wxString\&}{ property}, \param{int}{ noArgs},
|
|
|
|
|
\param{wxVariant }{args[]}}
|
|
|
|
|
|
|
|
|
|
\constfunc{wxVariant}{GetProperty}{\param{const wxString\&}{ property}, \param{...}{}}
|
|
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
{\small
|
|
|
|
|
\begin{verbatim}
|
|
|
|
|
wxVariant res = obj.GetProperty("Range", wxVariant("A1"));
|
|
|
|
|
wxVariant res = obj.GetProperty("Range", "A1");
|
|
|
|
|
\end{verbatim}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
Note that {\it property} can contain dot-separated property names, to save the application
|
|
|
|
|
needing to call GetProperty several times using several temporary objects.
|
|
|
|
|
|
|
|
|
|
\membersection{wxAutomationObject::Invoke}\label{wxautomationobjectinvoke}
|
|
|
|
|
|
|
|
|
|
\constfunc{bool}{Invoke}{\param{const wxString\&}{ member}, \param{int}{ action},
|
|
|
|
|
\param{wxVariant\& }{retValue}, \param{int}{ noArgs}, \param{wxVariant}{ args[]},
|
|
|
|
|
\param{const wxVariant*}{ ptrArgs[] = 0}}
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
\wxheading{Parameters}
|
|
|
|
|
|
|
|
|
|
\docparam{member}{The member function or property name.}
|
|
|
|
|
|
|
|
|
|
\docparam{action}{Bitlist: may contain DISPATCH\_PROPERTYPUT, DISPATCH\_PROPERTYPUTREF,
|
|
|
|
|
DISPATCH\_METHOD.}
|
|
|
|
|
|
|
|
|
|
\docparam{retValue}{Return value (ignored if there is no return value)}.
|
|
|
|
|
|
|
|
|
|
\docparam{noArgs}{Number of arguments in {\it args} or {\it ptrArgs}.}
|
|
|
|
|
|
|
|
|
|
\docparam{args}{If non-null, contains an array of variants.}
|
|
|
|
|
|
|
|
|
|
\docparam{ptrArgs}{If non-null, contains an array of constant pointers to variants.}
|
|
|
|
|
|
|
|
|
|
\wxheading{Return value}
|
|
|
|
|
|
|
|
|
|
TRUE if the operation was successful, FALSE otherwise.
|
|
|
|
|
|
|
|
|
|
\wxheading{Remarks}
|
|
|
|
|
|
|
|
|
|
Two types of argument array are provided, so that when possible pointers are used for efficiency.
|
|
|
|
|
|
|
|
|
|
\membersection{wxAutomationObject::PutProperty}\label{wxautomationobjectputproperty}
|
|
|
|
|
|
|
|
|
|
\constfunc{bool}{PutProperty}{\param{const wxString\&}{ property}, \param{int}{ noArgs},
|
|
|
|
|
\param{wxVariant }{args[]}}
|
|
|
|
|
|
|
|
|
|
\func{bool}{PutProperty}{\param{const wxString\&}{ property}, \param{...}{}}
|
|
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
{\small
|
|
|
|
|
\begin{verbatim}
|
|
|
|
|
obj.PutProperty("Value", wxVariant(23));
|
|
|
|
|
obj.PutProperty("Value", 23);
|
|
|
|
|
\end{verbatim}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
Note that {\it property} can contain dot-separated property names, to save the application
|
|
|
|
|
needing to call GetProperty several times using several temporary objects.
|
|
|
|
|
|
|
|
|
|
\membersection{wxAutomationObject::SetDispatchPtr}\label{wxautomationobjectsetdispatchptr}
|
|
|
|
|
|
|
|
|
|
\func{void}{SetDispatchPtr}{\param{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.
|
|
|
|
|
|
Julian Smart