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