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