]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/autoobj.tex
merged 2.2 branch
[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 works under Windows only, and currently only for Visual C++.
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
39 Constructor, taking an optional IDispatch pointer which will be released when the
40 object is deleted.
41
42 \membersection{wxAutomationObject::\destruct{wxAutomationObject}}\label{wxautomationobjectdtor}
43
44 \func{}{\destruct{wxAutomationObject}}{\void}
45
46 Destructor. 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
55 Calls an automation method for this object. The first form takes a method name, number of
56 arguments, and an array of variants. The second form takes a method name and zero to six
57 constant references to variants. Since the variant class has constructors for the basic
58 data types, and C++ provides temporary objects automatically, both of the following lines
59 are 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
68 Note that {\it method} can contain dot-separated property names, to save the application
69 needing 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
81 Creates a new object based on the class id, returning TRUE if the object was successfully created,
82 or FALSE if not.
83
84 \membersection{wxAutomationObject::GetDispatchPtr}\label{wxautomationobjectgetdispatchptr}
85
86 \constfunc{IDispatch*}{GetDispatchPtr}{\void}
87
88 Gets the IDispatch pointer.
89
90 \membersection{wxAutomationObject::GetInstance}\label{wxautomationobjectgetinstance}
91
92 \constfunc{bool}{GetInstance}{\param{const wxString\&}{ classId}}
93
94 Retrieves the current object associated with a class id, and attaches the IDispatch pointer
95 to this object. Returns TRUE if a pointer was succesfully retrieved, FALSE otherwise.
96
97 Note that this cannot cope with two instances of a given OLE object being active simultaneously,
98 such 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
105 Retrieves a property from this object, assumed to be a dispatch pointer, and initialises {\it obj} with it.
106 To avoid having to deal with IDispatch pointers directly, use this function in preference
107 to \helpref{wxAutomationObject::GetProperty}{wxautomationobjectgetproperty} when retrieving objects
108 from other objects.
109
110 Note 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
123 Gets a property value from this object. The first form takes a property name, number of
124 arguments, and an array of variants. The second form takes a property name and zero to six
125 constant references to variants. Since the variant class has constructors for the basic
126 data types, and C++ provides temporary objects automatically, both of the following lines
127 are 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
136 Note that {\it property} can contain dot-separated property names, to save the application
137 needing 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
145 This function is a low-level implementation that allows access to the IDispatch Invoke function.
146 It 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,
153 DISPATCH\_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
165 TRUE if the operation was successful, FALSE otherwise.
166
167 \wxheading{Remarks}
168
169 Two 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
178 Puts a property value into this object. The first form takes a property name, number of
179 arguments, and an array of variants. The second form takes a property name and zero to six
180 constant references to variants. Since the variant class has constructors for the basic
181 data types, and C++ provides temporary objects automatically, both of the following lines
182 are syntactically valid:
183
184 {\small
185 \begin{verbatim}
186 obj.PutProperty("Value", wxVariant(23));
187 obj.PutProperty("Value", 23);
188 \end{verbatim}
189 }
190
191 Note that {\it property} can contain dot-separated property names, to save the application
192 needing 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
198 Sets the IDispatch pointer. This function does not check if there is already an IDispatch pointer.
199
200 You may need to cast from IDispatch* to WXIDISPATCH* when calling this function.
201