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