]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/msw/ole/automtn.h
No code changes, removed tabs from source file.
[wxWidgets.git] / interface / wx / msw / ole / automtn.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: msw/ole/automtn.h
3 // Purpose: interface of wxAutomationObject
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 Automation object creation flags.
11
12 These flags can be used with wxAutomationObject::GetInstance().
13
14 @since 2.9.2
15 */
16 enum wxAutomationInstanceFlags
17 {
18 /**
19 Only use the existing instance, never create a new one.
20
21 This flag can be used to forbid the creation of a new instance if none
22 is currently running.
23 */
24 wxAutomationInstance_UseExistingOnly = 0,
25
26 /**
27 Create a new instance if there are no existing ones.
28
29 This flag corresponds to the default behaviour of
30 wxAutomationObject::GetInstance() and means that if getting an existing
31 instance failed, we should call wxAutomationObject::CreateInstance() to
32 create a new one.
33 */
34 wxAutomationInstance_CreateIfNeeded = 1,
35
36 /**
37 Do not show an error message if no existing instance is currently
38 running.
39
40 All other errors will still be reported as usual.
41 */
42 wxAutomationInstance_SilentIfNone = 2
43 };
44
45
46 /**
47 @class wxAutomationObject
48
49 The @b wxAutomationObject class represents an OLE automation object containing
50 a single data member,
51 an IDispatch pointer. It contains a number of functions that make it easy to
52 perform
53 automation operations, and set and get properties. The class makes heavy use of
54 the wxVariant class.
55
56 The usage of these classes is quite close to OLE automation usage in Visual
57 Basic. The API is
58 high-level, and the application can specify multiple properties in a single
59 string. The following example
60 gets the current Excel instance, and if it exists, makes the active cell bold.
61
62 @code
63 wxAutomationObject excelObject;
64 if (excelObject.GetInstance("Excel.Application"))
65 excelObject.PutProperty("ActiveCell.Font.Bold", @true);
66 @endcode
67
68 Note that this class obviously works under Windows only.
69
70 @onlyfor{wxmsw}
71
72 @library{wxcore}
73 @category{data}
74
75 @see wxVariant
76 */
77 class wxAutomationObject : public wxObject
78 {
79 public:
80 /**
81 Constructor, taking an optional IDispatch pointer which will be released when
82 the
83 object is deleted.
84 */
85 wxAutomationObject(WXIDISPATCH* dispatchPtr = NULL);
86
87 /**
88 Destructor. If the internal IDispatch pointer is non-null, it will be released.
89 */
90 ~wxAutomationObject();
91
92 //@{
93 /**
94 Calls an automation method for this object. The first form takes a method name,
95 number of
96 arguments, and an array of variants. The second form takes a method name and
97 zero to six
98 constant references to variants. Since the variant class has constructors for
99 the basic
100 data types, and C++ provides temporary objects automatically, both of the
101 following lines
102 are syntactically valid:
103
104 Note that @a method can contain dot-separated property names, to save the
105 application
106 needing to call GetProperty several times using several temporary objects. For
107 example:
108 */
109 wxVariant CallMethod(const wxString& method, int noArgs,
110 wxVariant args[]) const;
111 const wxVariant CallMethod(const wxString& method, ... ) const;
112 //@}
113
114 /**
115 Creates a new object based on the ProgID, returning @true if the object was
116 successfully created,
117 or @false if not.
118 */
119 bool CreateInstance(const wxString& progId) const;
120
121 /**
122 Checks if the object is in a valid state.
123
124 Returns @true if the object was successfully initialized or @false if
125 it has no valid IDispatch pointer.
126
127 @see GetDispatchPtr()
128 */
129 bool IsOk() const;
130
131 /**
132 Gets the IDispatch pointer.
133
134 Notice that the return value of this function is an untyped pointer but
135 it can be safely cast to @c IDispatch.
136 */
137 void* GetDispatchPtr() const;
138
139 /**
140 Retrieves the current object associated with the specified ProgID, and
141 attaches the IDispatch pointer to this object.
142
143 If attaching to an existing object failed and @a flags includes
144 wxAutomationInstance_CreateIfNeeded flag, a new object will be created.
145 Otherwise this function will normally log an error message which may be
146 undesirable if the object may or may not exist. The
147 wxAutomationInstance_SilentIfNone flag can be used to prevent the error
148 from being logged in this case.
149
150 Returns @true if a pointer was successfully retrieved, @false
151 otherwise.
152
153 Note that this cannot cope with two instances of a given OLE object being
154 active simultaneously,
155 such as two copies of Excel running. Which object is referenced cannot
156 currently be specified.
157
158 @param progId COM ProgID, e.g. "Excel.Application"
159 @param flags The creation flags (this parameters was added in wxWidgets
160 2.9.2)
161 */
162 bool GetInstance(const wxString& progId,
163 int flags = wxAutomationInstance_CreateIfNeeded) const;
164
165 /**
166 Retrieves a property from this object, assumed to be a dispatch pointer, and
167 initialises @a obj with it.
168 To avoid having to deal with IDispatch pointers directly, use this function in
169 preference
170 to GetProperty() when retrieving objects
171 from other objects.
172 Note that an IDispatch pointer is stored as a void* pointer in wxVariant
173 objects.
174
175 @see GetProperty()
176 */
177 bool GetObject(wxAutomationObject& obj, const wxString& property,
178 int noArgs = 0,
179 wxVariant args[] = NULL) const;
180
181 //@{
182 /**
183 Gets a property value from this object. The first form takes a property name,
184 number of
185 arguments, and an array of variants. The second form takes a property name and
186 zero to six
187 constant references to variants. Since the variant class has constructors for
188 the basic
189 data types, and C++ provides temporary objects automatically, both of the
190 following lines
191 are syntactically valid:
192
193 Note that @a property can contain dot-separated property names, to save the
194 application
195 needing to call GetProperty several times using several temporary objects.
196 */
197 wxVariant GetProperty(const wxString& property, int noArgs,
198 wxVariant args[]) const;
199 const wxVariant GetProperty(const wxString& property, ... ) const;
200 //@}
201
202 /**
203 This function is a low-level implementation that allows access to the IDispatch
204 Invoke function.
205 It is not meant to be called directly by the application, but is used by other
206 convenience functions.
207
208 @param member
209 The member function or property name.
210 @param action
211 Bitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF,
212 DISPATCH_METHOD.
213 @param retValue
214 Return value (ignored if there is no return value)
215 @param noArgs
216 Number of arguments in args or ptrArgs.
217 @param args
218 If non-null, contains an array of variants.
219 @param ptrArgs
220 If non-null, contains an array of constant pointers to variants.
221
222 @return @true if the operation was successful, @false otherwise.
223
224 @remarks Two types of argument array are provided, so that when possible
225 pointers are used for efficiency.
226 */
227 bool Invoke(const wxString& member, int action,
228 wxVariant& retValue, int noArgs,
229 wxVariant args[],
230 const wxVariant* ptrArgs[] = 0) const;
231
232 //@{
233 /**
234 Puts a property value into this object. The first form takes a property name,
235 number of
236 arguments, and an array of variants. The second form takes a property name and
237 zero to six
238 constant references to variants. Since the variant class has constructors for
239 the basic
240 data types, and C++ provides temporary objects automatically, both of the
241 following lines
242 are syntactically valid:
243
244 Note that @a property can contain dot-separated property names, to save the
245 application
246 needing to call GetProperty several times using several temporary objects.
247 */
248 bool PutProperty(const wxString& property, int noArgs,
249 wxVariant args[]);
250 const bool PutProperty(const wxString& property, ... );
251 //@}
252
253 /**
254 Sets the IDispatch pointer. This function does not check if there is already an
255 IDispatch pointer.
256 You may need to cast from IDispatch* to WXIDISPATCH* when calling this function.
257 */
258 void SetDispatchPtr(WXIDISPATCH* dispatchPtr);
259 };
260