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