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