wxWidgets/docs/latex/wx/autoobj.tex
1999-02-15 20:41:29 +00:00

215 lines
8.4 KiB
TeX

\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{Include files}
<wx/msw/ole/automtn.h>
\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.