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     Automation object creation flags.
  11
  12     These flags can be used with wxAutomationObject::GetInstance().
  13
  14     @since 2.9.2
  15 */
  16 enum wxAutomationInstanceFlags
  17 {
  18     /**
  19         Only use the existing instance, never create a new one.
  20
  21         This flag can be used to forbid the creation of a new instance if none
  22         is currently running.
  23      */
  24     wxAutomationInstance_UseExistingOnly = 0,
  25
  26     /**
  27         Create a new instance if there are no existing ones.
  28
  29         This flag corresponds to the default behaviour of
  30         wxAutomationObject::GetInstance() and means that if getting an existing
  31         instance failed, we should call wxAutomationObject::CreateInstance() to
  32         create a new one.
  33      */
  34     wxAutomationInstance_CreateIfNeeded = 1,
  35
  36     /**
  37         Do not show an error message if no existing instance is currently
  38         running.
  39
  40         All other errors will still be reported as usual.
  41      */
  42     wxAutomationInstance_SilentIfNone = 2
  43 };
  44
  45
  46 /**
  47     @class wxAutomationObject
  48
  49     The @b wxAutomationObject class represents an OLE automation object containing
  50     a single data member,
  51     an IDispatch pointer. It contains a number of functions that make it easy to
  52     perform
  53     automation operations, and set and get properties. The class makes heavy use of
  54     the wxVariant class.
  55
  56     The usage of these classes is quite close to OLE automation usage in Visual
  57     Basic. The API is
  58     high-level, and the application can specify multiple properties in a single
  59     string. The following example
  60     gets the current Excel instance, and if it exists, makes the active cell bold.
  61
  62     @code
  63     wxAutomationObject excelObject;
  64       if (excelObject.GetInstance("Excel.Application"))
  65           excelObject.PutProperty("ActiveCell.Font.Bold", @true);
  66     @endcode
  67
  68     Note that this class obviously works under Windows only.
  69
  70     @onlyfor{wxmsw}
  71
  72     @library{wxcore}
  73     @category{data}
  74
  75     @see wxVariant
  76 */
  77 class wxAutomationObject : public wxObject
  78 {
  79 public:
  80     /**
  81         Constructor, taking an optional IDispatch pointer which will be released when
  82         the
  83         object is deleted.
  84     */
  85     wxAutomationObject(WXIDISPATCH* dispatchPtr = NULL);
  86
  87     /**
  88         Destructor. If the internal IDispatch pointer is non-null, it will be released.
  89     */
  90     ~wxAutomationObject();
  91
  92     //@{
  93     /**
  94         Calls an automation method for this object. The first form takes a method name,
  95         number of
  96         arguments, and an array of variants. The second form takes a method name and
  97         zero to six
  98         constant references to variants. Since the variant class has constructors for
  99         the basic
 100         data types, and C++ provides temporary objects automatically, both of the
 101         following lines
 102         are syntactically valid:
 103
 104         Note that @a method can contain dot-separated property names, to save the
 105         application
 106         needing to call GetProperty several times using several temporary objects. For
 107         example:
 108     */
 109     wxVariant CallMethod(const wxString& method, int noArgs,
 110                          wxVariant args[]) const;
 111     const wxVariant  CallMethod(const wxString& method, ... ) const;
 112     //@}
 113
 114     /**
 115         Creates a new object based on the ProgID, returning @true if the object was
 116         successfully created,
 117         or @false if not.
 118     */
 119     bool CreateInstance(const wxString& progId) const;
 120
 121     /**
 122         Checks if the object is in a valid state.
 123
 124         Returns @true if the object was successfully initialized or @false if
 125         it has no valid IDispatch pointer.
 126
 127         @see GetDispatchPtr()
 128      */
 129     bool IsOk() const;
 130
 131     /**
 132         Gets the IDispatch pointer.
 133
 134         Notice that the return value of this function is an untyped pointer but
 135         it can be safely cast to @c IDispatch.
 136     */
 137     void* GetDispatchPtr() const;
 138
 139     /**
 140         Retrieves the current object associated with the specified ProgID, and
 141         attaches the IDispatch pointer to this object.
 142
 143         If attaching to an existing object failed and @a flags includes
 144         wxAutomationInstance_CreateIfNeeded flag, a new object will be created.
 145         Otherwise this function will normally log an error message which may be
 146         undesirable if the object may or may not exist. The
 147         wxAutomationInstance_SilentIfNone flag can be used to prevent the error
 148         from being logged in this case.
 149
 150         Returns @true if a pointer was successfully retrieved, @false
 151         otherwise.
 152
 153         Note that this cannot cope with two instances of a given OLE object being
 154         active simultaneously,
 155         such as two copies of Excel running. Which object is referenced cannot
 156         currently be specified.
 157
 158         @param progId COM ProgID, e.g. "Excel.Application"
 159         @param flags The creation flags (this parameters was added in wxWidgets
 160             2.9.2)
 161     */
 162     bool GetInstance(const wxString& progId,
 163                      int flags = wxAutomationInstance_CreateIfNeeded) const;
 164
 165     /**
 166         Retrieves a property from this object, assumed to be a dispatch pointer, and
 167         initialises @a obj with it.
 168         To avoid having to deal with IDispatch pointers directly, use this function in
 169         preference
 170         to GetProperty() when retrieving objects
 171         from other objects.
 172         Note that an IDispatch pointer is stored as a void* pointer in wxVariant
 173         objects.
 174
 175         @see GetProperty()
 176     */
 177     bool GetObject(wxAutomationObject& obj, const wxString& property,
 178                    int noArgs = 0,
 179                    wxVariant args[] = NULL) const;
 180
 181     //@{
 182     /**
 183         Gets a property value from 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     wxVariant GetProperty(const wxString& property, int noArgs,
 198                           wxVariant args[]) const;
 199     const wxVariant  GetProperty(const wxString& property, ... ) const;
 200     //@}
 201
 202     /**
 203         This function is a low-level implementation that allows access to the IDispatch
 204         Invoke function.
 205         It is not meant to be called directly by the application, but is used by other
 206         convenience functions.
 207
 208         @param member
 209             The member function or property name.
 210         @param action
 211             Bitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF,
 212             DISPATCH_METHOD.
 213         @param retValue
 214             Return value (ignored if there is no return value)
 215         @param noArgs
 216             Number of arguments in args or ptrArgs.
 217         @param args
 218             If non-null, contains an array of variants.
 219         @param ptrArgs
 220             If non-null, contains an array of constant pointers to variants.
 221
 222         @return @true if the operation was successful, @false otherwise.
 223
 224         @remarks Two types of argument array are provided, so that when possible
 225                  pointers are used for efficiency.
 226     */
 227     bool Invoke(const wxString& member, int action,
 228                 wxVariant& retValue, int noArgs,
 229                 wxVariant args[],
 230                 const wxVariant* ptrArgs[] = 0) const;
 231
 232     //@{
 233     /**
 234         Puts a property value into this object. The first form takes a property name,
 235         number of
 236         arguments, and an array of variants. The second form takes a property name and
 237         zero to six
 238         constant references to variants. Since the variant class has constructors for
 239         the basic
 240         data types, and C++ provides temporary objects automatically, both of the
 241         following lines
 242         are syntactically valid:
 243
 244         Note that @a property can contain dot-separated property names, to save the
 245         application
 246         needing to call GetProperty several times using several temporary objects.
 247     */
 248     bool PutProperty(const wxString& property, int noArgs,
 249                      wxVariant args[]);
 250     const bool PutProperty(const wxString& property, ... );
 251     //@}
 252
 253     /**
 254         Sets the IDispatch pointer. This function does not check if there is already an
 255         IDispatch pointer.
 256         You may need to cast from IDispatch* to WXIDISPATCH* when calling this function.
 257     */
 258     void SetDispatchPtr(WXIDISPATCH* dispatchPtr);
 259 };
 260