Added first batch of docs and notes for wxPython.

[wxWidgets.git] / docs / latex / wx / autoobj.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.