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     @class wxVariantDataCurrency
  47
  48     This class represents a thin wrapper for Microsoft Windows CURRENCY type.
  49
  50     It is used for converting between wxVariant and OLE VARIANT
  51     with type set to VT_CURRENCY. When wxVariant stores
  52     wxVariantDataCurrency, it returns "currency" as its type.
  53
  54     An example of setting and getting CURRENCY value to and from wxVariant:
  55     @code
  56     CURRENCY cy;
  57     wxVariant variant;
  58
  59     // set wxVariant to currency type
  60     if ( SUCCEEDED(VarCyFromR8(123.45, &cy)) )  // set cy to 123.45
  61     {
  62         variant.SetData(new wxVariantDataCurrency(cy));
  63
  64         // or instead of the line above you could write:
  65         // wxVariantDataCurrency wxCy;
  66         // wxCy.SetValue(cy);
  67         // variant.SetData(wxCy.Clone());
  68     }
  69
  70     // get CURRENCY value from wxVariant
  71     if ( variant.GetType() == "currency" )
  72     {
  73         wxVariantDataCurrency*
  74             wxCy = wxDynamicCastVariantData(variant.GetData(), wxVariantDataCurrency);
  75         cy = wxCy->GetValue();
  76     }
  77     @endcode
  78
  79     @onlyfor{wxmsw}
  80     @since 2.9.5
  81
  82     @library{wxcore}
  83     @category{data}
  84
  85     @see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataErrorCode
  86
  87     @header{wx/msw/ole/oleutils.h}
  88 */
  89 class wxVariantDataCurrency : public wxVariantData
  90 {
  91 public:
  92     /**
  93         Default constructor initializes the object to 0.0.
  94     */
  95     wxVariantDataCurrency();
  96
  97     /**
  98         Constructor from CURRENCY.
  99     */
 100     wxVariantDataCurrency(CURRENCY value);
 101
 102     /**
 103         Returns the stored CURRENCY value.
 104     */
 105     CURRENCY GetValue() const;
 106
 107     /**
 108         Sets the stored value to @a value.
 109     */
 110     void SetValue(CURRENCY value);
 111
 112     /**
 113         Returns true if @a data is of wxVariantDataCurency type
 114         and contains the same CURRENCY value.
 115     */
 116     virtual bool Eq(wxVariantData& data) const;
 117
 118     /**
 119         Fills the provided string with the textual representation of this
 120         object.
 121
 122         The implementation of this method using @c VarBstrFromCy() Windows API
 123         function with LOCALE_USER_DEFAULT.
 124     */
 125     virtual bool Write(wxString& str) const;
 126
 127     /**
 128         Returns a copy of itself.
 129     */
 130     wxVariantData* Clone() const;
 131
 132     /**
 133         Returns "currency".
 134     */
 135     virtual wxString GetType() const;
 136
 137     /**
 138         Converts the value of this object to wxAny.
 139     */
 140     virtual bool GetAsAny(wxAny* any) const;
 141 };
 142
 143
 144 /**
 145     @class wxVariantDataErrorCode
 146
 147     This class represents a thin wrapper for Microsoft Windows SCODE type
 148     (which is the same as HRESULT).
 149
 150     It is used for converting between a wxVariant and OLE VARIANT with type set
 151     to VT_ERROR. When wxVariant stores wxVariantDataErrorCode, it returns
 152     "errorcode" as its type. This class can be used for returning error codes
 153     of automation calls or exchanging values with other applications: e.g.
 154     Microsoft Excel returns VARIANTs with VT_ERROR type for cell values with
 155     errors (one of XlCVError constants, displayed as e.g. "#DIV/0!" or "#REF!"
 156     there) etc. See wxVariantDataCurrency for an example of how to  exchange
 157     values between wxVariant and a native type not directly supported by it.
 158
 159     @onlyfor{wxmsw}
 160     @since 2.9.5
 161
 162     @library{wxcore}
 163     @category{data}
 164
 165     @see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataCurrency
 166
 167     @header{wx/msw/ole/oleutils.h}
 168 */
 169 class wxVariantDataErrorCode : public wxVariantData
 170 {
 171 public:
 172     /**
 173         Constructor initializes the object to @a value or S_OK if no value was
 174         passed.
 175     */
 176     wxVariantDataErrorCode(SCODE value = S_OK);
 177
 178     /**
 179         Returns the stored SCODE value.
 180     */
 181     SCODE GetValue() const;
 182
 183     /**
 184         Set the stored value to @a value.
 185     */
 186     void SetValue(SCODE value);
 187
 188     /**
 189         Returns true if @a data is of wxVariantDataErrorCode type
 190         and contains the same SCODE value.
 191     */
 192     virtual bool Eq(wxVariantData& data) const;
 193
 194     /**
 195         Fills the provided string with the textual representation of this
 196         object.
 197
 198         The error code is just a number, so it's output as such.
 199     */
 200     virtual bool Write(wxString& str) const;
 201
 202     /**
 203         Returns a copy of itself.
 204     */
 205     wxVariantData* Clone() const;
 206
 207     /**
 208         Returns "errorcode".
 209     */
 210     virtual wxString GetType() const { return wxS("errorcode"); }
 211
 212     /**
 213         Converts the value of this object to wxAny.
 214     */
 215     virtual bool GetAsAny(wxAny* any) const;
 216 };
 217
 218
 219 /**
 220     @class wxAutomationObject
 221
 222     The @b wxAutomationObject class represents an OLE automation object containing
 223     a single data member,
 224     an IDispatch pointer. It contains a number of functions that make it easy to
 225     perform
 226     automation operations, and set and get properties. The class makes heavy use of
 227     the wxVariant class.
 228
 229     The usage of these classes is quite close to OLE automation usage in Visual
 230     Basic. The API is
 231     high-level, and the application can specify multiple properties in a single
 232     string. The following example
 233     gets the current Excel instance, and if it exists, makes the active cell bold.
 234
 235     @code
 236     wxAutomationObject excelObject;
 237       if (excelObject.GetInstance("Excel.Application"))
 238           excelObject.PutProperty("ActiveCell.Font.Bold", @true);
 239     @endcode
 240
 241     Note that this class obviously works under Windows only.
 242
 243     @onlyfor{wxmsw}
 244
 245     @library{wxcore}
 246     @category{data}
 247
 248     @see wxVariant, wxVariantDataCurrency, wxVariantDataErrorCode
 249 */
 250 class wxAutomationObject : public wxObject
 251 {
 252 public:
 253     /**
 254         Constructor, taking an optional IDispatch pointer which will be released when
 255         the
 256         object is deleted.
 257     */
 258     wxAutomationObject(WXIDISPATCH* dispatchPtr = NULL);
 259
 260     /**
 261         Destructor. If the internal IDispatch pointer is non-null, it will be released.
 262     */
 263     ~wxAutomationObject();
 264
 265     //@{
 266     /**
 267         Calls an automation method for this object. The first form takes a method name,
 268         number of
 269         arguments, and an array of variants. The second form takes a method name and
 270         zero to six
 271         constant references to variants. Since the variant class has constructors for
 272         the basic
 273         data types, and C++ provides temporary objects automatically, both of the
 274         following lines
 275         are syntactically valid:
 276
 277         Note that @a method can contain dot-separated property names, to save the
 278         application
 279         needing to call GetProperty several times using several temporary objects. For
 280         example:
 281     */
 282     wxVariant CallMethod(const wxString& method, int noArgs,
 283                          wxVariant args[]) const;
 284     const wxVariant  CallMethod(const wxString& method, ... ) const;
 285     //@}
 286
 287     /**
 288         Creates a new object based on the ProgID, returning @true if the object was
 289         successfully created,
 290         or @false if not.
 291     */
 292     bool CreateInstance(const wxString& progId) const;
 293
 294     /**
 295         Checks if the object is in a valid state.
 296
 297         Returns @true if the object was successfully initialized or @false if
 298         it has no valid IDispatch pointer.
 299
 300         @see GetDispatchPtr()
 301      */
 302     bool IsOk() const;
 303
 304     /**
 305         Gets the IDispatch pointer.
 306
 307         Notice that the return value of this function is an untyped pointer but
 308         it can be safely cast to @c IDispatch.
 309     */
 310     void* GetDispatchPtr() const;
 311
 312     /**
 313         Retrieves the current object associated with the specified ProgID, and
 314         attaches the IDispatch pointer to this object.
 315
 316         If attaching to an existing object failed and @a flags includes
 317         wxAutomationInstance_CreateIfNeeded flag, a new object will be created.
 318         Otherwise this function will normally log an error message which may be
 319         undesirable if the object may or may not exist. The
 320         wxAutomationInstance_SilentIfNone flag can be used to prevent the error
 321         from being logged in this case.
 322
 323         Returns @true if a pointer was successfully retrieved, @false
 324         otherwise.
 325
 326         Note that this cannot cope with two instances of a given OLE object being
 327         active simultaneously,
 328         such as two copies of Excel running. Which object is referenced cannot
 329         currently be specified.
 330
 331         @param progId COM ProgID, e.g. "Excel.Application"
 332         @param flags The creation flags (this parameters was added in wxWidgets
 333             2.9.2)
 334     */
 335     bool GetInstance(const wxString& progId,
 336                      int flags = wxAutomationInstance_CreateIfNeeded) const;
 337
 338     /**
 339         Retrieves a property from this object, assumed to be a dispatch pointer, and
 340         initialises @a obj with it.
 341         To avoid having to deal with IDispatch pointers directly, use this function in
 342         preference
 343         to GetProperty() when retrieving objects
 344         from other objects.
 345         Note that an IDispatch pointer is stored as a void* pointer in wxVariant
 346         objects.
 347
 348         @see GetProperty()
 349     */
 350     bool GetObject(wxAutomationObject& obj, const wxString& property,
 351                    int noArgs = 0,
 352                    wxVariant args[] = NULL) const;
 353
 354     //@{
 355     /**
 356         Gets a property value from this object. The first form takes a property name,
 357         number of
 358         arguments, and an array of variants. The second form takes a property name and
 359         zero to six
 360         constant references to variants. Since the variant class has constructors for
 361         the basic
 362         data types, and C++ provides temporary objects automatically, both of the
 363         following lines
 364         are syntactically valid:
 365
 366         Note that @a property can contain dot-separated property names, to save the
 367         application
 368         needing to call GetProperty several times using several temporary objects.
 369     */
 370     wxVariant GetProperty(const wxString& property, int noArgs,
 371                           wxVariant args[]) const;
 372     const wxVariant  GetProperty(const wxString& property, ... ) const;
 373     //@}
 374
 375     /**
 376         This function is a low-level implementation that allows access to the IDispatch
 377         Invoke function.
 378         It is not meant to be called directly by the application, but is used by other
 379         convenience functions.
 380
 381         @param member
 382             The member function or property name.
 383         @param action
 384             Bitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF,
 385             DISPATCH_METHOD.
 386         @param retValue
 387             Return value (ignored if there is no return value)
 388         @param noArgs
 389             Number of arguments in args or ptrArgs.
 390         @param args
 391             If non-null, contains an array of variants.
 392         @param ptrArgs
 393             If non-null, contains an array of constant pointers to variants.
 394
 395         @return @true if the operation was successful, @false otherwise.
 396
 397         @remarks Two types of argument array are provided, so that when possible
 398                  pointers are used for efficiency.
 399     */
 400     bool Invoke(const wxString& member, int action,
 401                 wxVariant& retValue, int noArgs,
 402                 wxVariant args[],
 403                 const wxVariant* ptrArgs[] = 0) const;
 404
 405     //@{
 406     /**
 407         Puts a property value into this object. The first form takes a property name,
 408         number of
 409         arguments, and an array of variants. The second form takes a property name and
 410         zero to six
 411         constant references to variants. Since the variant class has constructors for
 412         the basic
 413         data types, and C++ provides temporary objects automatically, both of the
 414         following lines
 415         are syntactically valid:
 416
 417         Note that @a property can contain dot-separated property names, to save the
 418         application
 419         needing to call GetProperty several times using several temporary objects.
 420     */
 421     bool PutProperty(const wxString& property, int noArgs,
 422                      wxVariant args[]);
 423     const bool PutProperty(const wxString& property, ... );
 424     //@}
 425
 426     /**
 427         Sets the IDispatch pointer. This function does not check if there is already an
 428         IDispatch pointer.
 429         You may need to cast from IDispatch* to WXIDISPATCH* when calling this function.
 430     */
 431     void SetDispatchPtr(WXIDISPATCH* dispatchPtr);
 432
 433     /**
 434         Returns the locale identifier used in automation calls.
 435
 436         The default is LOCALE_SYSTEM_DEFAULT but the objects obtained by
 437         GetObject() inherit the locale identifier from the one that created
 438         them.
 439
 440         @since 2.9.5
 441     */
 442     LCID GetLCID() const;
 443
 444     /**
 445         Sets the locale identifier to be used in automation calls performed by
 446         this object.
 447
 448         The default value is LOCALE_SYSTEM_DEFAULT.
 449
 450         Notice that any automation objects created by this one inherit the same
 451         LCID.
 452
 453         @since 2.9.5
 454     */
 455     void SetLCID(LCID lcid);
 456
 457 };
 458