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     @class wxVariantDataSafeArray
 220
 221     This class represents a thin wrapper for Microsoft Windows SAFEARRAY type.
 222
 223     It is used for converting between wxVariant and OLE VARIANT
 224     with type set to VT_ARRAY, which has more than one dimension.
 225     When wxVariant stores wxVariantDataSafeArray, it returns "safearray" as its type.
 226
 227     wxVariantDataSafeArray does NOT manage the SAFEARRAY it points to.
 228     If you want to pass it to a wxAutomationObject as a parameter:
 229         -# Assign a SAFEARRAY pointer to it and store it in a wxVariant.
 230         -# Call the wxAutomationObject method (CallMethod(), SetProperty() or Invoke())
 231         -# wxAutomationObject will destroy the array after the approapriate automation call.
 232
 233     An example of creating a 2-dimensional SAFEARRAY containing VARIANTs
 234     and storing it in a wxVariant
 235     @code
 236     SAFEARRAYBOUND bounds[2]; // 2 dimensions
 237     wxSafeArray<VT_VARIANT> safeArray;
 238     unsigned rowCount = 1000;
 239     unsigned colCount = 20;
 240
 241     bounds[0].lLbound = 0; // elements start at 0
 242     bounds[0].cElements = rowCount;
 243     bounds[1].lLbound = 0; // elements start at 0
 244     bounds[1].cElements = colCount;
 245
 246     if ( !safeArray.Create(bounds, 2) )
 247         return false;
 248
 249     long indices[2];
 250
 251     for ( unsigned row = 0; row < rowCount; row++ )
 252     {
 253         indices[0] = row;
 254         for ( unsigned col = 0; col < colCount; col++ )
 255         {
 256             indices[1] = col;
 257             if ( !safeArray.SetElement(indices, wxString::Format("R%u C%u", row+1, col+1)) )
 258                return false;
 259         }
 260     }
 261     range.PutProperty("Value", wxVariant(new wxVariantDataSafeArray(sa.Detach())));
 262     @endcode
 263
 264     If you you received wxVariantDataSafeArray as a result of wxAutomationObject method call:
 265     (1) Get the data out of the array.
 266     (2) Destroy the array.
 267     @code
 268     wxVariant result;
 269     result = range.GetProperty("Value");
 270     if ( result.GetType() == "safearray" )
 271     {
 272         wxSafeArray<VT_VARIANT> safeArray;
 273         wxVariantDataSafeArray* const
 274             sa = wxStaticCastVariantData(variant.GetData(), wxVariantDataSafeArray);
 275
 276         if ( !safeArray.Attach(sa.GetValue() )
 277         {
 278             if ( !safeArray.HasArray() )
 279                 SafeArrayDestroy(sa.GetValue()); // we have to dispose the SAFEARRAY ourselves
 280             return false;
 281         }
 282
 283         // get the data from the SAFEARRAY using wxSafeArray::GetElement()
 284         // SAFEARRAY will be disposed by safeArray's dtor
 285     }
 286     @endcode
 287
 288     @onlyfor{wxmsw}
 289     @since 2.9.5
 290
 291     @library{wxcore}
 292     @category{data}
 293
 294     @see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataErrorCode
 295
 296     @header{wx/msw/ole/oleutils.h}
 297 */
 298 class wxVariantDataSafeArray : public wxVariantData
 299 {
 300 public:
 301     /**
 302         Constructor initializes the object to @a value.
 303     */
 304     explicit wxVariantDataSafeArray(SAFEARRAY* value = NULL);
 305
 306     /**
 307         Returns the stored array.
 308     */
 309     SAFEARRAY* GetValue() const;
 310
 311     /**
 312         Set the stored array.
 313     */
 314     void SetValue(SAFEARRAY* value);
 315
 316     /**
 317         Returns true if @a data is of wxVariantDataSafeArray type
 318         and contains the same SAFEARRAY* value.
 319     */
 320     virtual bool Eq(wxVariantData& data) const;
 321
 322     /**
 323         Fills the provided string with the textual representation of this
 324         object.
 325
 326         Only the address of SAFEARRAY pointer is output.
 327     */
 328     virtual bool Write(wxString& str) const;
 329
 330     /**
 331         Returns a copy of itself.
 332     */
 333     wxVariantData* Clone() const;
 334
 335     /**
 336         Returns "safearray".
 337     */
 338     virtual wxString GetType() const;
 339
 340     /**
 341         Converts the value of this object to wxAny.
 342     */
 343     virtual bool GetAsAny(wxAny* any) const;
 344 };
 345
 346 /**
 347     @class wxAutomationObject
 348
 349     The @b wxAutomationObject class represents an OLE automation object containing
 350     a single data member,
 351     an IDispatch pointer. It contains a number of functions that make it easy to
 352     perform
 353     automation operations, and set and get properties. The class makes heavy use of
 354     the wxVariant class.
 355
 356     The usage of these classes is quite close to OLE automation usage in Visual
 357     Basic. The API is
 358     high-level, and the application can specify multiple properties in a single
 359     string. The following example
 360     gets the current Excel instance, and if it exists, makes the active cell bold.
 361
 362     @code
 363     wxAutomationObject excelObject;
 364       if (excelObject.GetInstance("Excel.Application"))
 365           excelObject.PutProperty("ActiveCell.Font.Bold", @true);
 366     @endcode
 367
 368     Note that this class obviously works under Windows only.
 369
 370     @onlyfor{wxmsw}
 371
 372     @library{wxcore}
 373     @category{data}
 374
 375     @see wxVariant, wxVariantDataCurrency, wxVariantDataErrorCode, wxVariantDataSafeArray
 376 */
 377 class wxAutomationObject : public wxObject
 378 {
 379 public:
 380     /**
 381         Constructor, taking an optional IDispatch pointer which will be released when
 382         the
 383         object is deleted.
 384     */
 385     wxAutomationObject(WXIDISPATCH* dispatchPtr = NULL);
 386
 387     /**
 388         Destructor. If the internal IDispatch pointer is non-null, it will be released.
 389     */
 390     ~wxAutomationObject();
 391
 392     //@{
 393     /**
 394         Calls an automation method for this object. The first form takes a method name,
 395         number of
 396         arguments, and an array of variants. The second form takes a method name and
 397         zero to six
 398         constant references to variants. Since the variant class has constructors for
 399         the basic
 400         data types, and C++ provides temporary objects automatically, both of the
 401         following lines
 402         are syntactically valid:
 403
 404         Note that @a method can contain dot-separated property names, to save the
 405         application
 406         needing to call GetProperty several times using several temporary objects. For
 407         example:
 408     */
 409     wxVariant CallMethod(const wxString& method, int noArgs,
 410                          wxVariant args[]) const;
 411     const wxVariant  CallMethod(const wxString& method, ... ) const;
 412     //@}
 413
 414     /**
 415         Creates a new object based on the ProgID, returning @true if the object was
 416         successfully created,
 417         or @false if not.
 418     */
 419     bool CreateInstance(const wxString& progId) const;
 420
 421     /**
 422         Checks if the object is in a valid state.
 423
 424         Returns @true if the object was successfully initialized or @false if
 425         it has no valid IDispatch pointer.
 426
 427         @see GetDispatchPtr()
 428      */
 429     bool IsOk() const;
 430
 431     /**
 432         Gets the IDispatch pointer.
 433
 434         Notice that the return value of this function is an untyped pointer but
 435         it can be safely cast to @c IDispatch.
 436     */
 437     void* GetDispatchPtr() const;
 438
 439     /**
 440         Retrieves the current object associated with the specified ProgID, and
 441         attaches the IDispatch pointer to this object.
 442
 443         If attaching to an existing object failed and @a flags includes
 444         wxAutomationInstance_CreateIfNeeded flag, a new object will be created.
 445         Otherwise this function will normally log an error message which may be
 446         undesirable if the object may or may not exist. The
 447         wxAutomationInstance_SilentIfNone flag can be used to prevent the error
 448         from being logged in this case.
 449
 450         Returns @true if a pointer was successfully retrieved, @false
 451         otherwise.
 452
 453         Note that this cannot cope with two instances of a given OLE object being
 454         active simultaneously,
 455         such as two copies of Excel running. Which object is referenced cannot
 456         currently be specified.
 457
 458         @param progId COM ProgID, e.g. "Excel.Application"
 459         @param flags The creation flags (this parameters was added in wxWidgets
 460             2.9.2)
 461     */
 462     bool GetInstance(const wxString& progId,
 463                      int flags = wxAutomationInstance_CreateIfNeeded) const;
 464
 465     /**
 466         Retrieves a property from this object, assumed to be a dispatch pointer, and
 467         initialises @a obj with it.
 468         To avoid having to deal with IDispatch pointers directly, use this function in
 469         preference
 470         to GetProperty() when retrieving objects
 471         from other objects.
 472         Note that an IDispatch pointer is stored as a void* pointer in wxVariant
 473         objects.
 474
 475         @see GetProperty()
 476     */
 477     bool GetObject(wxAutomationObject& obj, const wxString& property,
 478                    int noArgs = 0,
 479                    wxVariant args[] = NULL) const;
 480
 481     //@{
 482     /**
 483         Gets a property value from this object. The first form takes a property name,
 484         number of
 485         arguments, and an array of variants. The second form takes a property name and
 486         zero to six
 487         constant references to variants. Since the variant class has constructors for
 488         the basic
 489         data types, and C++ provides temporary objects automatically, both of the
 490         following lines
 491         are syntactically valid:
 492
 493         Note that @a property can contain dot-separated property names, to save the
 494         application
 495         needing to call GetProperty several times using several temporary objects.
 496     */
 497     wxVariant GetProperty(const wxString& property, int noArgs,
 498                           wxVariant args[]) const;
 499     const wxVariant  GetProperty(const wxString& property, ... ) const;
 500     //@}
 501
 502     /**
 503         This function is a low-level implementation that allows access to the IDispatch
 504         Invoke function.
 505         It is not meant to be called directly by the application, but is used by other
 506         convenience functions.
 507
 508         @param member
 509             The member function or property name.
 510         @param action
 511             Bitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF,
 512             DISPATCH_METHOD.
 513         @param retValue
 514             Return value (ignored if there is no return value)
 515         @param noArgs
 516             Number of arguments in args or ptrArgs.
 517         @param args
 518             If non-null, contains an array of variants.
 519         @param ptrArgs
 520             If non-null, contains an array of constant pointers to variants.
 521
 522         @return @true if the operation was successful, @false otherwise.
 523
 524         @remarks Two types of argument array are provided, so that when possible
 525                  pointers are used for efficiency.
 526     */
 527     bool Invoke(const wxString& member, int action,
 528                 wxVariant& retValue, int noArgs,
 529                 wxVariant args[],
 530                 const wxVariant* ptrArgs[] = 0) const;
 531
 532     //@{
 533     /**
 534         Puts a property value into this object. The first form takes a property name,
 535         number of
 536         arguments, and an array of variants. The second form takes a property name and
 537         zero to six
 538         constant references to variants. Since the variant class has constructors for
 539         the basic
 540         data types, and C++ provides temporary objects automatically, both of the
 541         following lines
 542         are syntactically valid:
 543
 544         Note that @a property can contain dot-separated property names, to save the
 545         application
 546         needing to call GetProperty several times using several temporary objects.
 547     */
 548     bool PutProperty(const wxString& property, int noArgs,
 549                      wxVariant args[]);
 550     const bool PutProperty(const wxString& property, ... );
 551     //@}
 552
 553     /**
 554         Sets the IDispatch pointer. This function does not check if there is already an
 555         IDispatch pointer.
 556         You may need to cast from IDispatch* to WXIDISPATCH* when calling this function.
 557     */
 558     void SetDispatchPtr(WXIDISPATCH* dispatchPtr);
 559
 560     /**
 561         Returns the locale identifier used in automation calls.
 562
 563         The default is LOCALE_SYSTEM_DEFAULT but the objects obtained by
 564         GetObject() inherit the locale identifier from the one that created
 565         them.
 566
 567         @since 2.9.5
 568     */
 569     LCID GetLCID() const;
 570
 571     /**
 572         Sets the locale identifier to be used in automation calls performed by
 573         this object.
 574
 575         The default value is LOCALE_SYSTEM_DEFAULT.
 576
 577         Notice that any automation objects created by this one inherit the same
 578         LCID.
 579
 580         @since 2.9.5
 581     */
 582     void SetLCID(LCID lcid);
 583
 584 };
 585