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 license
   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{misc}
  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 class id, returning @true if the object was
  79         successfully created,
  80         or @false if not.
  81     */
  82     bool CreateInstance(const wxString& classId) const;
  83
  84     /**
  85         Gets the IDispatch pointer.
  86     */
  87     IDispatch* GetDispatchPtr() const;
  88
  89     /**
  90         Retrieves the current object associated with a class id, and attaches the
  91         IDispatch pointer
  92         to this object. Returns @true if a pointer was successfully retrieved, @false
  93         otherwise.
  94         Note that this cannot cope with two instances of a given OLE object being
  95         active simultaneously,
  96         such as two copies of Excel running. Which object is referenced cannot
  97         currently be specified.
  98     */
  99     bool GetInstance(const wxString& classId) const;
 100
 101     /**
 102         Retrieves a property from this object, assumed to be a dispatch pointer, and
 103         initialises @a obj with it.
 104         To avoid having to deal with IDispatch pointers directly, use this function in
 105         preference
 106         to GetProperty() when retrieving objects
 107         from other objects.
 108         Note that an IDispatch pointer is stored as a void* pointer in wxVariant
 109         objects.
 110
 111         @see GetProperty()
 112     */
 113     bool GetObject(wxAutomationObject& obj, const wxString& property,
 114                    int noArgs = 0,
 115                    wxVariant args[] = NULL) const;
 116
 117     //@{
 118     /**
 119         Gets a property value from this object. The first form takes a property name,
 120         number of
 121         arguments, and an array of variants. The second form takes a property name and
 122         zero to six
 123         constant references to variants. Since the variant class has constructors for
 124         the basic
 125         data types, and C++ provides temporary objects automatically, both of the
 126         following lines
 127         are syntactically valid:
 128
 129         Note that @a property can contain dot-separated property names, to save the
 130         application
 131         needing to call GetProperty several times using several temporary objects.
 132     */
 133     wxVariant GetProperty(const wxString& property, int noArgs,
 134                           wxVariant args[]) const;
 135     const wxVariant  GetProperty(const wxString& property, ... ) const;
 136     //@}
 137
 138     /**
 139         This function is a low-level implementation that allows access to the IDispatch
 140         Invoke function.
 141         It is not meant to be called directly by the application, but is used by other
 142         convenience functions.
 143
 144         @param member
 145             The member function or property name.
 146         @param action
 147             Bitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF,
 148             DISPATCH_METHOD.
 149         @param retValue
 150             Return value (ignored if there is no return value)
 151         @param noArgs
 152             Number of arguments in args or ptrArgs.
 153         @param args
 154             If non-null, contains an array of variants.
 155         @param ptrArgs
 156             If non-null, contains an array of constant pointers to variants.
 157
 158         @return @true if the operation was successful, @false otherwise.
 159
 160         @remarks Two types of argument array are provided, so that when possible
 161                  pointers are used for efficiency.
 162     */
 163     bool Invoke(const wxString& member, int action,
 164                 wxVariant& retValue, int noArgs,
 165                 wxVariant args[],
 166                 const wxVariant* ptrArgs[] = 0) const;
 167
 168     //@{
 169     /**
 170         Puts a property value into this object. The first form takes a property name,
 171         number of
 172         arguments, and an array of variants. The second form takes a property name and
 173         zero to six
 174         constant references to variants. Since the variant class has constructors for
 175         the basic
 176         data types, and C++ provides temporary objects automatically, both of the
 177         following lines
 178         are syntactically valid:
 179
 180         Note that @a property can contain dot-separated property names, to save the
 181         application
 182         needing to call GetProperty several times using several temporary objects.
 183     */
 184     bool PutProperty(const wxString& property, int noArgs,
 185                      wxVariant args[]);
 186     const bool PutProperty(const wxString& property, ... );
 187     //@}
 188
 189     /**
 190         Sets the IDispatch pointer. This function does not check if there is already an
 191         IDispatch pointer.
 192         You may need to cast from IDispatch* to WXIDISPATCH* when calling this function.
 193     */
 194     void SetDispatchPtr(WXIDISPATCH* dispatchPtr);
 195 };
 196