1\section{\class{wxAutomationObject}}\label{wxautomationobject} 2 3The {\bf wxAutomationObject} class represents an OLE automation object containing a single data member, 4an IDispatch pointer. It contains a number of functions that make it easy to perform 5automation operations, and set and get properties. The class makes heavy use of the \helpref{wxVariant}{wxvariant} class. 6 7The usage of these classes is quite close to OLE automation usage in Visual Basic. The API is 8high-level, and the application can specify multiple properties in a single string. The following example 9gets the current Excel instance, and if it exists, makes the active cell bold. 10 11{\small 12\begin{verbatim} 13 wxAutomationObject excelObject; 14 if (excelObject.GetInstance("Excel.Application")) 15 excelObject.PutProperty("ActiveCell.Font.Bold", true); 16\end{verbatim} 17} 18 19Note that this class obviously works under Windows only. 20 21\wxheading{Derived from} 22 23\helpref{wxObject}{wxobject} 24 25\wxheading{Include files} 26 27<wx/msw/ole/automtn.h> 28 29\wxheading{See also} 30 31\helpref{wxVariant}{wxvariant} 32 33\latexignore{\rtfignore{\wxheading{Members}}} 34 35\membersection{wxAutomationObject::wxAutomationObject}\label{wxautomationobjectctor} 36 37\func{}{wxAutomationObject}{\param{WXIDISPATCH*}{ dispatchPtr = NULL}} 38 39Constructor, taking an optional IDispatch pointer which will be released when the 40object is deleted. 41 42\membersection{wxAutomationObject::\destruct{wxAutomationObject}}\label{wxautomationobjectdtor} 43 44\func{}{\destruct{wxAutomationObject}}{\void} 45 46Destructor. If the internal IDispatch pointer is non-null, it will be released. 47 48\membersection{wxAutomationObject::CallMethod}\label{wxautomationobjectcallmethod} 49 50\constfunc{wxVariant}{CallMethod}{\param{const wxString\&}{ method}, \param{int}{ noArgs}, 51 \param{wxVariant }{args[]}} 52 53\constfunc{wxVariant}{CallMethod}{\param{const wxString\&}{ method}, \param{...}{}} 54 55Calls an automation method for this object. The first form takes a method name, number of 56arguments, and an array of variants. The second form takes a method name and zero to six 57constant references to variants. Since the variant class has constructors for the basic 58data types, and C++ provides temporary objects automatically, both of the following lines 59are syntactically valid: 60 61{\small 62\begin{verbatim} 63 wxVariant res = obj.CallMethod("Sum", wxVariant(1.2), wxVariant(3.4)); 64 wxVariant res = obj.CallMethod("Sum", 1.2, 3.4); 65\end{verbatim} 66} 67 68Note that {\it method} can contain dot-separated property names, to save the application 69needing to call GetProperty several times using several temporary objects. For example: 70 71{\small 72\begin{verbatim} 73 object.CallMethod("ActiveCell.Font.ShowDialog", "My caption"); 74\end{verbatim} 75} 76 77\membersection{wxAutomationObject::CreateInstance}\label{wxautomationobjectcreateinstance} 78 79\constfunc{bool}{CreateInstance}{\param{const wxString\&}{ classId}} 80 81Creates a new object based on the class id, returning true if the object was successfully created, 82or false if not. 83 84\membersection{wxAutomationObject::GetDispatchPtr}\label{wxautomationobjectgetdispatchptr} 85 86\constfunc{IDispatch*}{GetDispatchPtr}{\void} 87 88Gets the IDispatch pointer. 89 90\membersection{wxAutomationObject::GetInstance}\label{wxautomationobjectgetinstance} 91 92\constfunc{bool}{GetInstance}{\param{const wxString\&}{ classId}} 93 94Retrieves the current object associated with a class id, and attaches the IDispatch pointer 95to this object. Returns true if a pointer was successfully retrieved, false otherwise. 96 97Note that this cannot cope with two instances of a given OLE object being active simultaneously, 98such as two copies of Excel running. Which object is referenced cannot currently be specified. 99 100\membersection{wxAutomationObject::GetObject}\label{wxautomationobjectgetobject} 101 102\constfunc{bool}{GetObject}{\param{wxAutomationObject\&}{obj} \param{const wxString\&}{ property}, 103 \param{int}{ noArgs = 0}, \param{wxVariant }{args[] = NULL}} 104 105Retrieves a property from this object, assumed to be a dispatch pointer, and initialises {\it obj} with it. 106To avoid having to deal with IDispatch pointers directly, use this function in preference 107to \helpref{wxAutomationObject::GetProperty}{wxautomationobjectgetproperty} when retrieving objects 108from other objects. 109 110Note that an IDispatch pointer is stored as a void* pointer in wxVariant objects. 111 112\wxheading{See also} 113 114\helpref{wxAutomationObject::GetProperty}{wxautomationobjectgetproperty} 115 116\membersection{wxAutomationObject::GetProperty}\label{wxautomationobjectgetproperty} 117 118\constfunc{wxVariant}{GetProperty}{\param{const wxString\&}{ property}, \param{int}{ noArgs}, 119 \param{wxVariant }{args[]}} 120 121\constfunc{wxVariant}{GetProperty}{\param{const wxString\&}{ property}, \param{...}{}} 122 123Gets a property value from this object. The first form takes a property name, number of 124arguments, and an array of variants. The second form takes a property name and zero to six 125constant references to variants. Since the variant class has constructors for the basic 126data types, and C++ provides temporary objects automatically, both of the following lines 127are syntactically valid: 128 129{\small 130\begin{verbatim} 131 wxVariant res = obj.GetProperty("Range", wxVariant("A1")); 132 wxVariant res = obj.GetProperty("Range", "A1"); 133\end{verbatim} 134} 135 136Note that {\it property} can contain dot-separated property names, to save the application 137needing to call GetProperty several times using several temporary objects. 138 139\membersection{wxAutomationObject::Invoke}\label{wxautomationobjectinvoke} 140 141\constfunc{bool}{Invoke}{\param{const wxString\&}{ member}, \param{int}{ action}, 142 \param{wxVariant\& }{retValue}, \param{int}{ noArgs}, \param{wxVariant}{ args[]}, 143 \param{const wxVariant*}{ ptrArgs[] = 0}} 144 145This function is a low-level implementation that allows access to the IDispatch Invoke function. 146It is not meant to be called directly by the application, but is used by other convenience functions. 147 148\wxheading{Parameters} 149 150\docparam{member}{The member function or property name.} 151 152\docparam{action}{Bitlist: may contain DISPATCH\_PROPERTYPUT, DISPATCH\_PROPERTYPUTREF, 153DISPATCH\_METHOD.} 154 155\docparam{retValue}{Return value (ignored if there is no return value)}. 156 157\docparam{noArgs}{Number of arguments in {\it args} or {\it ptrArgs}.} 158 159\docparam{args}{If non-null, contains an array of variants.} 160 161\docparam{ptrArgs}{If non-null, contains an array of constant pointers to variants.} 162 163\wxheading{Return value} 164 165true if the operation was successful, false otherwise. 166 167\wxheading{Remarks} 168 169Two types of argument array are provided, so that when possible pointers are used for efficiency. 170 171\membersection{wxAutomationObject::PutProperty}\label{wxautomationobjectputproperty} 172 173\constfunc{bool}{PutProperty}{\param{const wxString\&}{ property}, \param{int}{ noArgs}, 174 \param{wxVariant }{args[]}} 175 176\func{bool}{PutProperty}{\param{const wxString\&}{ property}, \param{...}{}} 177 178Puts a property value into this object. The first form takes a property name, number of 179arguments, and an array of variants. The second form takes a property name and zero to six 180constant references to variants. Since the variant class has constructors for the basic 181data types, and C++ provides temporary objects automatically, both of the following lines 182are syntactically valid: 183 184{\small 185\begin{verbatim} 186 obj.PutProperty("Value", wxVariant(23)); 187 obj.PutProperty("Value", 23); 188\end{verbatim} 189} 190 191Note that {\it property} can contain dot-separated property names, to save the application 192needing to call GetProperty several times using several temporary objects. 193 194\membersection{wxAutomationObject::SetDispatchPtr}\label{wxautomationobjectsetdispatchptr} 195 196\func{void}{SetDispatchPtr}{\param{WXIDISPATCH*}{ dispatchPtr}} 197 198Sets the IDispatch pointer. This function does not check if there is already an IDispatch pointer. 199 200You may need to cast from IDispatch* to WXIDISPATCH* when calling this function. 201 202