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