interface/wx/msw/ole/automtn.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        msw/ole/automtn.h
   3 // Purpose:     interface of wxAutomationObject
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     Automation object creation flags.
  10
  11     These flags can be used with wxAutomationObject::GetInstance().
  12
  13     @since 2.9.2
  14 */
  15 enum wxAutomationInstanceFlags
  16 {
  17     /**
  18         Only use the existing instance, never create a new one.
  19
  20         This flag can be used to forbid the creation of a new instance if none
  21         is currently running.
  22      */
  23     wxAutomationInstance_UseExistingOnly = 0,
  24
  25     /**
  26         Create a new instance if there are no existing ones.
  27
  28         This flag corresponds to the default behaviour of
  29         wxAutomationObject::GetInstance() and means that if getting an existing
  30         instance failed, we should call wxAutomationObject::CreateInstance() to
  31         create a new one.
  32      */
  33     wxAutomationInstance_CreateIfNeeded = 1,
  34
  35     /**
  36         Do not show an error message if no existing instance is currently
  37         running.
  38
  39         All other errors will still be reported as usual.
  40      */
  41     wxAutomationInstance_SilentIfNone = 2
  42 };
  43
  44 /**
  45     @class wxVariantDataCurrency
  46
  47     This class represents a thin wrapper for Microsoft Windows CURRENCY type.
  48
  49     It is used for converting between wxVariant and OLE VARIANT
  50     with type set to VT_CURRENCY. When wxVariant stores
  51     wxVariantDataCurrency, it returns "currency" as its type.
  52
  53     An example of setting and getting CURRENCY value to and from wxVariant:
  54     @code
  55     CURRENCY cy;
  56     wxVariant variant;
  57
  58     // set wxVariant to currency type
  59     if ( SUCCEEDED(VarCyFromR8(123.45, &cy)) )  // set cy to 123.45
  60     {
  61         variant.SetData(new wxVariantDataCurrency(cy));
  62
  63         // or instead of the line above you could write:
  64         // wxVariantDataCurrency wxCy;
  65         // wxCy.SetValue(cy);
  66         // variant.SetData(wxCy.Clone());
  67     }
  68
  69     // get CURRENCY value from wxVariant
  70     if ( variant.GetType() == "currency" )
  71     {
  72         wxVariantDataCurrency*
  73             wxCy = wxDynamicCastVariantData(variant.GetData(), wxVariantDataCurrency);
  74         cy = wxCy->GetValue();
  75     }
  76     @endcode
  77
  78     @onlyfor{wxmsw}
  79     @since 2.9.5
  80
  81     @library{wxcore}
  82     @category{data}
  83
  84     @see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataErrorCode
  85
  86     @header{wx/msw/ole/oleutils.h}
  87 */
  88 class wxVariantDataCurrency : public wxVariantData
  89 {
  90 public:
  91     /**
  92         Default constructor initializes the object to 0.0.
  93     */
  94     wxVariantDataCurrency();
  95
  96     /**
  97         Constructor from CURRENCY.
  98     */
  99     wxVariantDataCurrency(CURRENCY value);
 100
 101     /**
 102         Returns the stored CURRENCY value.
 103     */
 104     CURRENCY GetValue() const;
 105
 106     /**
 107         Sets the stored value to @a value.
 108     */
 109     void SetValue(CURRENCY value);
 110
 111     /**
 112         Returns true if @a data is of wxVariantDataCurency type
 113         and contains the same CURRENCY value.
 114     */
 115     virtual bool Eq(wxVariantData& data) const;
 116
 117     /**
 118         Fills the provided string with the textual representation of this
 119         object.
 120
 121         The implementation of this method using @c VarBstrFromCy() Windows API
 122         function with LOCALE_USER_DEFAULT.
 123     */
 124     virtual bool Write(wxString& str) const;
 125
 126     /**
 127         Returns a copy of itself.
 128     */
 129     wxVariantData* Clone() const;
 130
 131     /**
 132         Returns "currency".
 133     */
 134     virtual wxString GetType() const;
 135
 136     /**
 137         Converts the value of this object to wxAny.
 138     */
 139     virtual bool GetAsAny(wxAny* any) const;
 140 };
 141
 142
 143 /**
 144     @class wxVariantDataErrorCode
 145
 146     This class represents a thin wrapper for Microsoft Windows SCODE type
 147     (which is the same as HRESULT).
 148
 149     It is used for converting between a wxVariant and OLE VARIANT with type set
 150     to VT_ERROR. When wxVariant stores wxVariantDataErrorCode, it returns
 151     "errorcode" as its type. This class can be used for returning error codes
 152     of automation calls or exchanging values with other applications: e.g.
 153     Microsoft Excel returns VARIANTs with VT_ERROR type for cell values with
 154     errors (one of XlCVError constants, displayed as e.g. "#DIV/0!" or "#REF!"
 155     there) etc. See wxVariantDataCurrency for an example of how to  exchange
 156     values between wxVariant and a native type not directly supported by it.
 157
 158     @onlyfor{wxmsw}
 159     @since 2.9.5
 160
 161     @library{wxcore}
 162     @category{data}
 163
 164     @see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataCurrency
 165
 166     @header{wx/msw/ole/oleutils.h}
 167 */
 168 class wxVariantDataErrorCode : public wxVariantData
 169 {
 170 public:
 171     /**
 172         Constructor initializes the object to @a value or S_OK if no value was
 173         passed.
 174     */
 175     wxVariantDataErrorCode(SCODE value = S_OK);
 176
 177     /**
 178         Returns the stored SCODE value.
 179     */
 180     SCODE GetValue() const;
 181
 182     /**
 183         Set the stored value to @a value.
 184     */
 185     void SetValue(SCODE value);
 186
 187     /**
 188         Returns true if @a data is of wxVariantDataErrorCode type
 189         and contains the same SCODE value.
 190     */
 191     virtual bool Eq(wxVariantData& data) const;
 192
 193     /**
 194         Fills the provided string with the textual representation of this
 195         object.
 196
 197         The error code is just a number, so it's output as such.
 198     */
 199     virtual bool Write(wxString& str) const;
 200
 201     /**
 202         Returns a copy of itself.
 203     */
 204     wxVariantData* Clone() const;
 205
 206     /**
 207         Returns "errorcode".
 208     */
 209     virtual wxString GetType() const { return wxS("errorcode"); }
 210
 211     /**
 212         Converts the value of this object to wxAny.
 213     */
 214     virtual bool GetAsAny(wxAny* any) const;
 215 };
 216
 217 /**
 218     @class wxVariantDataSafeArray
 219
 220     This class represents a thin wrapper for Microsoft Windows SAFEARRAY type.
 221
 222     It is used for converting between wxVariant and OLE VARIANT
 223     with type set to VT_ARRAY, which has more than one dimension.
 224     When wxVariant stores wxVariantDataSafeArray, it returns "safearray" as its type.
 225
 226     wxVariantDataSafeArray does NOT manage the SAFEARRAY it points to.
 227     If you want to pass it to a wxAutomationObject as a parameter:
 228         -# Assign a SAFEARRAY pointer to it and store it in a wxVariant.
 229         -# Call the wxAutomationObject method (CallMethod(), SetProperty() or Invoke())
 230         -# wxAutomationObject will destroy the array after the approapriate automation call.
 231
 232     An example of creating a 2-dimensional SAFEARRAY containing VARIANTs
 233     and storing it in a wxVariant
 234     @code
 235     SAFEARRAYBOUND bounds[2]; // 2 dimensions
 236     wxSafeArray<VT_VARIANT> safeArray;
 237     unsigned rowCount = 1000;
 238     unsigned colCount = 20;
 239
 240     bounds[0].lLbound = 0; // elements start at 0
 241     bounds[0].cElements = rowCount;
 242     bounds[1].lLbound = 0; // elements start at 0
 243     bounds[1].cElements = colCount;
 244
 245     if ( !safeArray.Create(bounds, 2) )
 246         return false;
 247
 248     long indices[2];
 249
 250     for ( unsigned row = 0; row < rowCount; row++ )
 251     {
 252         indices[0] = row;
 253         for ( unsigned col = 0; col < colCount; col++ )
 254         {
 255             indices[1] = col;
 256             if ( !safeArray.SetElement(indices, wxString::Format("R%u C%u", row+1, col+1)) )
 257                return false;
 258         }
 259     }
 260     range.PutProperty("Value", wxVariant(new wxVariantDataSafeArray(sa.Detach())));
 261     @endcode
 262
 263     If you you received wxVariantDataSafeArray as a result of wxAutomationObject method call:
 264     (1) Get the data out of the array.
 265     (2) Destroy the array.
 266     @code
 267     wxVariant result;
 268     result = range.GetProperty("Value");
 269     if ( result.GetType() == "safearray" )
 270     {
 271         wxSafeArray<VT_VARIANT> safeArray;
 272         wxVariantDataSafeArray* const
 273             sa = wxStaticCastVariantData(variant.GetData(), wxVariantDataSafeArray);
 274
 275         if ( !safeArray.Attach(sa.GetValue() )
 276         {
 277             if ( !safeArray.HasArray() )
 278                 SafeArrayDestroy(sa.GetValue()); // we have to dispose the SAFEARRAY ourselves
 279             return false;
 280         }
 281
 282         // get the data from the SAFEARRAY using wxSafeArray::GetElement()
 283         // SAFEARRAY will be disposed by safeArray's dtor
 284     }
 285     @endcode
 286
 287     @onlyfor{wxmsw}
 288     @since 2.9.5
 289
 290     @library{wxcore}
 291     @category{data}
 292
 293     @see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataErrorCode
 294
 295     @header{wx/msw/ole/oleutils.h}
 296 */
 297 class wxVariantDataSafeArray : public wxVariantData
 298 {
 299 public:
 300     /**
 301         Constructor initializes the object to @a value.
 302     */
 303     explicit wxVariantDataSafeArray(SAFEARRAY* value = NULL);
 304
 305     /**
 306         Returns the stored array.
 307     */
 308     SAFEARRAY* GetValue() const;
 309
 310     /**
 311         Set the stored array.
 312     */
 313     void SetValue(SAFEARRAY* value);
 314
 315     /**
 316         Returns true if @a data is of wxVariantDataSafeArray type
 317         and contains the same SAFEARRAY* value.
 318     */
 319     virtual bool Eq(wxVariantData& data) const;
 320
 321     /**
 322         Fills the provided string with the textual representation of this
 323         object.
 324
 325         Only the address of SAFEARRAY pointer is output.
 326     */
 327     virtual bool Write(wxString& str) const;
 328
 329     /**
 330         Returns a copy of itself.
 331     */
 332     wxVariantData* Clone() const;
 333
 334     /**
 335         Returns "safearray".
 336     */
 337     virtual wxString GetType() const;
 338
 339     /**
 340         Converts the value of this object to wxAny.
 341     */
 342     virtual bool GetAsAny(wxAny* any) const;
 343 };
 344
 345 /**
 346     @class wxAutomationObject
 347
 348     The @b wxAutomationObject class represents an OLE automation object containing
 349     a single data member,
 350     an IDispatch pointer. It contains a number of functions that make it easy to
 351     perform
 352     automation operations, and set and get properties. The class makes heavy use of
 353     the wxVariant class.
 354
 355     The usage of these classes is quite close to OLE automation usage in Visual
 356     Basic. The API is
 357     high-level, and the application can specify multiple properties in a single
 358     string. The following example
 359     gets the current Excel instance, and if it exists, makes the active cell bold.
 360
 361     @code
 362     wxAutomationObject excelObject;
 363       if (excelObject.GetInstance("Excel.Application"))
 364           excelObject.PutProperty("ActiveCell.Font.Bold", @true);
 365     @endcode
 366
 367     Note that this class obviously works under Windows only.
 368
 369     @onlyfor{wxmsw}
 370
 371     @library{wxcore}
 372     @category{data}
 373
 374     @see wxVariant, wxVariantDataCurrency, wxVariantDataErrorCode, wxVariantDataSafeArray
 375 */
 376 class wxAutomationObject : public wxObject
 377 {
 378 public:
 379     /**
 380         Constructor, taking an optional IDispatch pointer which will be released when
 381         the
 382         object is deleted.
 383     */
 384     wxAutomationObject(WXIDISPATCH* dispatchPtr = NULL);
 385
 386     /**
 387         Destructor. If the internal IDispatch pointer is non-null, it will be released.
 388     */
 389     ~wxAutomationObject();
 390
 391     //@{
 392     /**
 393         Calls an automation method for this object. The first form takes a method name,
 394         number of
 395         arguments, and an array of variants. The second form takes a method name and
 396         zero to six
 397         constant references to variants. Since the variant class has constructors for
 398         the basic
 399         data types, and C++ provides temporary objects automatically, both of the
 400         following lines
 401         are syntactically valid:
 402
 403         Note that @a method can contain dot-separated property names, to save the
 404         application
 405         needing to call GetProperty several times using several temporary objects. For
 406         example:
 407     */
 408     wxVariant CallMethod(const wxString& method, int noArgs,
 409                          wxVariant args[]) const;
 410     const wxVariant  CallMethod(const wxString& method, ... ) const;
 411     //@}
 412
 413     /**
 414         Creates a new object based on the ProgID, returning @true if the object was
 415         successfully created,
 416         or @false if not.
 417     */
 418     bool CreateInstance(const wxString& progId) const;
 419
 420     /**
 421         Checks if the object is in a valid state.
 422
 423         Returns @true if the object was successfully initialized or @false if
 424         it has no valid IDispatch pointer.
 425
 426         @see GetDispatchPtr()
 427      */
 428     bool IsOk() const;
 429
 430     /**
 431         Gets the IDispatch pointer.
 432
 433         Notice that the return value of this function is an untyped pointer but
 434         it can be safely cast to @c IDispatch.
 435     */
 436     void* GetDispatchPtr() const;
 437
 438     /**
 439         Retrieves the current object associated with the specified ProgID, and
 440         attaches the IDispatch pointer to this object.
 441
 442         If attaching to an existing object failed and @a flags includes
 443         wxAutomationInstance_CreateIfNeeded flag, a new object will be created.
 444         Otherwise this function will normally log an error message which may be
 445         undesirable if the object may or may not exist. The
 446         wxAutomationInstance_SilentIfNone flag can be used to prevent the error
 447         from being logged in this case.
 448
 449         Returns @true if a pointer was successfully retrieved, @false
 450         otherwise.
 451
 452         Note that this cannot cope with two instances of a given OLE object being
 453         active simultaneously,
 454         such as two copies of Excel running. Which object is referenced cannot
 455         currently be specified.
 456
 457         @param progId COM ProgID, e.g. "Excel.Application"
 458         @param flags The creation flags (this parameters was added in wxWidgets
 459             2.9.2)
 460     */
 461     bool GetInstance(const wxString& progId,
 462                      int flags = wxAutomationInstance_CreateIfNeeded) const;
 463
 464     /**
 465         Retrieves a property from this object, assumed to be a dispatch pointer, and
 466         initialises @a obj with it.
 467         To avoid having to deal with IDispatch pointers directly, use this function in
 468         preference
 469         to GetProperty() when retrieving objects
 470         from other objects.
 471         Note that an IDispatch pointer is stored as a void* pointer in wxVariant
 472         objects.
 473
 474         @see GetProperty()
 475     */
 476     bool GetObject(wxAutomationObject& obj, const wxString& property,
 477                    int noArgs = 0,
 478                    wxVariant args[] = NULL) const;
 479
 480     //@{
 481     /**
 482         Gets a property value from this object. The first form takes a property name,
 483         number of
 484         arguments, and an array of variants. The second form takes a property name and
 485         zero to six
 486         constant references to variants. Since the variant class has constructors for
 487         the basic
 488         data types, and C++ provides temporary objects automatically, both of the
 489         following lines
 490         are syntactically valid:
 491
 492         Note that @a property can contain dot-separated property names, to save the
 493         application
 494         needing to call GetProperty several times using several temporary objects.
 495     */
 496     wxVariant GetProperty(const wxString& property, int noArgs,
 497                           wxVariant args[]) const;
 498     const wxVariant  GetProperty(const wxString& property, ... ) const;
 499     //@}
 500
 501     /**
 502         This function is a low-level implementation that allows access to the IDispatch
 503         Invoke function.
 504         It is not meant to be called directly by the application, but is used by other
 505         convenience functions.
 506
 507         @param member
 508             The member function or property name.
 509         @param action
 510             Bitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF,
 511             DISPATCH_METHOD.
 512         @param retValue
 513             Return value (ignored if there is no return value)
 514         @param noArgs
 515             Number of arguments in args or ptrArgs.
 516         @param args
 517             If non-null, contains an array of variants.
 518         @param ptrArgs
 519             If non-null, contains an array of constant pointers to variants.
 520
 521         @return @true if the operation was successful, @false otherwise.
 522
 523         @remarks Two types of argument array are provided, so that when possible
 524                  pointers are used for efficiency.
 525     */
 526     bool Invoke(const wxString& member, int action,
 527                 wxVariant& retValue, int noArgs,
 528                 wxVariant args[],
 529                 const wxVariant* ptrArgs[] = 0) const;
 530
 531     //@{
 532     /**
 533         Puts a property value into this object. The first form takes a property name,
 534         number of
 535         arguments, and an array of variants. The second form takes a property name and
 536         zero to six
 537         constant references to variants. Since the variant class has constructors for
 538         the basic
 539         data types, and C++ provides temporary objects automatically, both of the
 540         following lines
 541         are syntactically valid:
 542
 543         Note that @a property can contain dot-separated property names, to save the
 544         application
 545         needing to call GetProperty several times using several temporary objects.
 546     */
 547     bool PutProperty(const wxString& property, int noArgs,
 548                      wxVariant args[]);
 549     const bool PutProperty(const wxString& property, ... );
 550     //@}
 551
 552     /**
 553         Sets the IDispatch pointer. This function does not check if there is already an
 554         IDispatch pointer.
 555         You may need to cast from IDispatch* to WXIDISPATCH* when calling this function.
 556     */
 557     void SetDispatchPtr(WXIDISPATCH* dispatchPtr);
 558
 559     /**
 560         Returns the locale identifier used in automation calls.
 561
 562         The default is LOCALE_SYSTEM_DEFAULT but the objects obtained by
 563         GetObject() inherit the locale identifier from the one that created
 564         them.
 565
 566         @since 2.9.5
 567     */
 568     LCID GetLCID() const;
 569
 570     /**
 571         Sets the locale identifier to be used in automation calls performed by
 572         this object.
 573
 574         The default value is LOCALE_SYSTEM_DEFAULT.
 575
 576         Notice that any automation objects created by this one inherit the same
 577         LCID.
 578
 579         @since 2.9.5
 580     */
 581     void SetLCID(LCID lcid);
 582
 583 };
 584