X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..a349dc1085c34b54deaaab3022b01dfd8aeb3cbd:/interface/wx/msw/ole/automtn.h diff --git a/interface/wx/msw/ole/automtn.h b/interface/wx/msw/ole/automtn.h index 818169b0b1..9e7f3287a8 100644 --- a/interface/wx/msw/ole/automtn.h +++ b/interface/wx/msw/ole/automtn.h @@ -3,9 +3,219 @@ // 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 wxAutomationObject @@ -33,9 +243,9 @@ @onlyfor{wxmsw} @library{wxcore} - @category{misc} + @category{data} - @see wxVariant + @see wxVariant, wxVariantDataCurrency, wxVariantDataErrorCode */ class wxAutomationObject : public wxObject { @@ -75,28 +285,55 @@ 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. + + Returns @true if the object was successfully initialized or @false if + it has no valid IDispatch pointer. + + @see GetDispatchPtr() + */ + bool IsOk() const; /** 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 @@ -192,5 +429,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); + };