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