← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to interface/wx/msw/ole/automtn.h

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

Lines of Context:
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: automtn.h 66967 2011-02-19 12:33:08Z VZ $
 
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