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