interface/msw/ole/automtn.h

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