X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/bb24f84b70d0b295253b985978e7f4f4bd0b24d1..9e9574fe45b176ee74bba8fad7574cf9906145d1:/interface/wx/msw/ole/automtn.h diff --git a/interface/wx/msw/ole/automtn.h b/interface/wx/msw/ole/automtn.h index f29b9f86c0..ec0ec35efc 100644 --- a/interface/wx/msw/ole/automtn.h +++ b/interface/wx/msw/ole/automtn.h @@ -2,10 +2,346 @@ // Name: msw/ole/automtn.h // Purpose: interface of wxAutomationObject // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +/** + Automation object creation flags. + + These flags can be used with wxAutomationObject::GetInstance(). + + @since 2.9.2 +*/ +enum wxAutomationInstanceFlags +{ + /** + Only use the existing instance, never create a new one. + + This flag can be used to forbid the creation of a new instance if none + is currently running. + */ + wxAutomationInstance_UseExistingOnly = 0, + + /** + Create a new instance if there are no existing ones. + + This flag corresponds to the default behaviour of + wxAutomationObject::GetInstance() and means that if getting an existing + instance failed, we should call wxAutomationObject::CreateInstance() to + create a new one. + */ + wxAutomationInstance_CreateIfNeeded = 1, + + /** + Do not show an error message if no existing instance is currently + running. + + All other errors will still be reported as usual. + */ + wxAutomationInstance_SilentIfNone = 2 +}; + +/** + @class wxVariantDataCurrency + + This class represents a thin wrapper for Microsoft Windows CURRENCY type. + + It is used for converting between wxVariant and OLE VARIANT + with type set to VT_CURRENCY. When wxVariant stores + wxVariantDataCurrency, it returns "currency" as its type. + + An example of setting and getting CURRENCY value to and from wxVariant: + @code + CURRENCY cy; + wxVariant variant; + + // set wxVariant to currency type + if ( SUCCEEDED(VarCyFromR8(123.45, &cy)) ) // set cy to 123.45 + { + variant.SetData(new wxVariantDataCurrency(cy)); + + // or instead of the line above you could write: + // wxVariantDataCurrency wxCy; + // wxCy.SetValue(cy); + // variant.SetData(wxCy.Clone()); + } + + // get CURRENCY value from wxVariant + if ( variant.GetType() == "currency" ) + { + wxVariantDataCurrency* + wxCy = wxDynamicCastVariantData(variant.GetData(), wxVariantDataCurrency); + cy = wxCy->GetValue(); + } + @endcode + + @onlyfor{wxmsw} + @since 2.9.5 + + @library{wxcore} + @category{data} + + @see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataErrorCode + + @header{wx/msw/ole/oleutils.h} +*/ +class wxVariantDataCurrency : public wxVariantData +{ +public: + /** + Default constructor initializes the object to 0.0. + */ + wxVariantDataCurrency(); + + /** + Constructor from CURRENCY. + */ + wxVariantDataCurrency(CURRENCY value); + + /** + Returns the stored CURRENCY value. + */ + CURRENCY GetValue() const; + + /** + Sets the stored value to @a value. + */ + void SetValue(CURRENCY value); + + /** + Returns true if @a data is of wxVariantDataCurency type + and contains the same CURRENCY value. + */ + virtual bool Eq(wxVariantData& data) const; + + /** + Fills the provided string with the textual representation of this + object. + + The implementation of this method using @c VarBstrFromCy() Windows API + function with LOCALE_USER_DEFAULT. + */ + virtual bool Write(wxString& str) const; + + /** + Returns a copy of itself. + */ + wxVariantData* Clone() const; + + /** + Returns "currency". + */ + virtual wxString GetType() const; + + /** + Converts the value of this object to wxAny. + */ + virtual bool GetAsAny(wxAny* any) const; +}; + + +/** + @class wxVariantDataErrorCode + + This class represents a thin wrapper for Microsoft Windows SCODE type + (which is the same as HRESULT). + + It is used for converting between a wxVariant and OLE VARIANT with type set + to VT_ERROR. When wxVariant stores wxVariantDataErrorCode, it returns + "errorcode" as its type. This class can be used for returning error codes + of automation calls or exchanging values with other applications: e.g. + Microsoft Excel returns VARIANTs with VT_ERROR type for cell values with + errors (one of XlCVError constants, displayed as e.g. "#DIV/0!" or "#REF!" + there) etc. See wxVariantDataCurrency for an example of how to exchange + values between wxVariant and a native type not directly supported by it. + + @onlyfor{wxmsw} + @since 2.9.5 + + @library{wxcore} + @category{data} + + @see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataCurrency + + @header{wx/msw/ole/oleutils.h} +*/ +class wxVariantDataErrorCode : public wxVariantData +{ +public: + /** + Constructor initializes the object to @a value or S_OK if no value was + passed. + */ + wxVariantDataErrorCode(SCODE value = S_OK); + + /** + Returns the stored SCODE value. + */ + SCODE GetValue() const; + + /** + Set the stored value to @a value. + */ + void SetValue(SCODE value); + + /** + Returns true if @a data is of wxVariantDataErrorCode type + and contains the same SCODE value. + */ + virtual bool Eq(wxVariantData& data) const; + + /** + Fills the provided string with the textual representation of this + object. + + The error code is just a number, so it's output as such. + */ + virtual bool Write(wxString& str) const; + + /** + Returns a copy of itself. + */ + wxVariantData* Clone() const; + + /** + Returns "errorcode". + */ + virtual wxString GetType() const { return wxS("errorcode"); } + + /** + Converts the value of this object to wxAny. + */ + virtual bool GetAsAny(wxAny* any) const; +}; + +/** + @class wxVariantDataSafeArray + + This class represents a thin wrapper for Microsoft Windows SAFEARRAY type. + + It is used for converting between wxVariant and OLE VARIANT + with type set to VT_ARRAY, which has more than one dimension. + When wxVariant stores wxVariantDataSafeArray, it returns "safearray" as its type. + + wxVariantDataSafeArray does NOT manage the SAFEARRAY it points to. + If you want to pass it to a wxAutomationObject as a parameter: + -# Assign a SAFEARRAY pointer to it and store it in a wxVariant. + -# Call the wxAutomationObject method (CallMethod(), SetProperty() or Invoke()) + -# wxAutomationObject will destroy the array after the approapriate automation call. + + An example of creating a 2-dimensional SAFEARRAY containing VARIANTs + and storing it in a wxVariant + @code + SAFEARRAYBOUND bounds[2]; // 2 dimensions + wxSafeArray safeArray; + unsigned rowCount = 1000; + unsigned colCount = 20; + + bounds[0].lLbound = 0; // elements start at 0 + bounds[0].cElements = rowCount; + bounds[1].lLbound = 0; // elements start at 0 + bounds[1].cElements = colCount; + + if ( !safeArray.Create(bounds, 2) ) + return false; + + long indices[2]; + + for ( unsigned row = 0; row < rowCount; row++ ) + { + indices[0] = row; + for ( unsigned col = 0; col < colCount; col++ ) + { + indices[1] = col; + if ( !safeArray.SetElement(indices, wxString::Format("R%u C%u", row+1, col+1)) ) + return false; + } + } + range.PutProperty("Value", wxVariant(new wxVariantDataSafeArray(sa.Detach()))); + @endcode + + If you you received wxVariantDataSafeArray as a result of wxAutomationObject method call: + (1) Get the data out of the array. + (2) Destroy the array. + @code + wxVariant result; + result = range.GetProperty("Value"); + if ( result.GetType() == "safearray" ) + { + wxSafeArray safeArray; + wxVariantDataSafeArray* const + sa = wxStaticCastVariantData(variant.GetData(), wxVariantDataSafeArray); + + if ( !safeArray.Attach(sa.GetValue() ) + { + if ( !safeArray.HasArray() ) + SafeArrayDestroy(sa.GetValue()); // we have to dispose the SAFEARRAY ourselves + return false; + } + + // get the data from the SAFEARRAY using wxSafeArray::GetElement() + // SAFEARRAY will be disposed by safeArray's dtor + } + @endcode + + @onlyfor{wxmsw} + @since 2.9.5 + + @library{wxcore} + @category{data} + + @see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataErrorCode + + @header{wx/msw/ole/oleutils.h} +*/ +class wxVariantDataSafeArray : public wxVariantData +{ +public: + /** + Constructor initializes the object to @a value. + */ + explicit wxVariantDataSafeArray(SAFEARRAY* value = NULL); + + /** + Returns the stored array. + */ + SAFEARRAY* GetValue() const; + + /** + Set the stored array. + */ + void SetValue(SAFEARRAY* value); + + /** + Returns true if @a data is of wxVariantDataSafeArray type + and contains the same SAFEARRAY* value. + */ + virtual bool Eq(wxVariantData& data) const; + + /** + Fills the provided string with the textual representation of this + object. + + Only the address of SAFEARRAY pointer is output. + */ + virtual bool Write(wxString& str) const; + + /** + Returns a copy of itself. + */ + wxVariantData* Clone() const; + + /** + Returns "safearray". + */ + virtual wxString GetType() const; + + /** + Converts the value of this object to wxAny. + */ + virtual bool GetAsAny(wxAny* any) const; +}; + /** @class wxAutomationObject @@ -33,9 +369,9 @@ @onlyfor{wxmsw} @library{wxcore} - @category{misc} + @category{data} - @see wxVariant + @see wxVariant, wxVariantDataCurrency, wxVariantDataErrorCode, wxVariantDataSafeArray */ class wxAutomationObject : public wxObject { @@ -75,11 +411,11 @@ public: //@} /** - Creates a new object based on the class id, returning @true if the object was + Creates a new object based on the ProgID, returning @true if the object was successfully created, or @false if not. */ - bool CreateInstance(const wxString& classId) const; + bool CreateInstance(const wxString& progId) const; /** Checks if the object is in a valid state. @@ -93,20 +429,37 @@ public: /** Gets the IDispatch pointer. + + Notice that the return value of this function is an untyped pointer but + it can be safely cast to @c IDispatch. */ - IDispatch* GetDispatchPtr() const; + void* GetDispatchPtr() const; /** - Retrieves the current object associated with a class id, and attaches the - IDispatch pointer - to this object. Returns @true if a pointer was successfully retrieved, @false + Retrieves the current object associated with the specified ProgID, and + attaches the IDispatch pointer to this object. + + If attaching to an existing object failed and @a flags includes + wxAutomationInstance_CreateIfNeeded flag, a new object will be created. + Otherwise this function will normally log an error message which may be + undesirable if the object may or may not exist. The + wxAutomationInstance_SilentIfNone flag can be used to prevent the error + from being logged in this case. + + Returns @true if a pointer was successfully retrieved, @false otherwise. + Note that this cannot cope with two instances of a given OLE object being active simultaneously, such as two copies of Excel running. Which object is referenced cannot currently be specified. + + @param progId COM ProgID, e.g. "Excel.Application" + @param flags The creation flags (this parameters was added in wxWidgets + 2.9.2) */ - bool GetInstance(const wxString& classId) const; + bool GetInstance(const wxString& progId, + int flags = wxAutomationInstance_CreateIfNeeded) const; /** Retrieves a property from this object, assumed to be a dispatch pointer, and @@ -202,5 +555,30 @@ public: You may need to cast from IDispatch* to WXIDISPATCH* when calling this function. */ void SetDispatchPtr(WXIDISPATCH* dispatchPtr); + + /** + Returns the locale identifier used in automation calls. + + The default is LOCALE_SYSTEM_DEFAULT but the objects obtained by + GetObject() inherit the locale identifier from the one that created + them. + + @since 2.9.5 + */ + LCID GetLCID() const; + + /** + Sets the locale identifier to be used in automation calls performed by + this object. + + The default value is LOCALE_SYSTEM_DEFAULT. + + Notice that any automation objects created by this one inherit the same + LCID. + + @since 2.9.5 + */ + void SetLCID(LCID lcid); + };