]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/msw/ole/automtn.h
Move code removing "-psn_xxx" command line arguments to common code.
[wxWidgets.git] / interface / wx / msw / ole / automtn.h
index 22f47a1d8d121ba2bc5bd31783335584c90366a7..ec0ec35efc4261d39c714ed5871f6c27d3f6f503 100644 (file)
 // 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<VT_VARIANT> 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<VT_VARIANT> 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
 
     @library{wxcore}
     @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);
+
 };