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