diff --git a/interface/wx/msw/ole/automtn.h b/interface/wx/msw/ole/automtn.h index 352b022a60..e178107543 100644 --- a/interface/wx/msw/ole/automtn.h +++ b/interface/wx/msw/ole/automtn.h @@ -370,6 +370,185 @@ public: virtual bool GetAsAny(wxAny* any) const; }; +/** + @class wxSafeArray + + wxSafeArray is wxWidgets wrapper for working with MS Windows @c + SAFEARRAY used in Component Object Model (COM) and OLE Automation APIs. + + It also has convenience functions for converting between @c SAFEARRAY and + wxVariant with list type or wxArrayString. + + wxSafeArray is a template class which must be created with an appropriate + type matching the underlying @c VARIANT type (such as @c VT_VARIANT or @c + VT_BSTR). + + See wxVariantDataSafeArray documentation for examples of using it. + + @onlyfor{wxmsw} + @since 3.0 + + @library{wxcore} + @category{data} + + @see wxAutomationObject, wxVariantDataSafeArray, wxVariant + + @header{wx/msw/ole/safearray.h} +*/ +template +class wxSafeArray +{ +public: + + /** + The default constructor. + */ + wxSafeArray(); + + /** + The destructor unlocks and destroys the owned @c SAFEARRAY. + */ + ~wxSafeArray(); + + /** + Creates and locks a zero-based one-dimensional @c SAFEARRAY with the + given number of elements. + */ + bool Create(size_t count); + + /** + Creates and locks a @c SAFEARRAY. + + See @c SafeArrayCreate() in MSDN documentation for more information. + */ + bool Create(SAFEARRAYBOUND* bound, size_t dimensions); + + /** + Creates a zero-based one-dimensional @c SAFEARRAY from wxVariant + with the list type. + + Can be called only for wxSafeArray<@c VT_VARIANT>. + */ + bool CreateFromListVariant(const wxVariant& variant); + + /** + Creates a zero-based one-dimensional @c SAFEARRAY from wxArrayString. + + Can be called only for wxSafeArray<@c VT_BSTR>. + */ + bool CreateFromArrayString(const wxArrayString& strings); + + /** + Attaches and locks an existing @c SAFEARRAY. + + The array must have the same @c VARTYPE as this wxSafeArray was + instantiated with. + */ + bool Attach(SAFEARRAY* array); + + /** + Unlocks the owned @c SAFEARRAY, returns it and gives up its ownership. + */ + SAFEARRAY* Detach(); + + /** + Unlocks and destroys the owned @c SAFEARRAY. + */ + void Destroy(); + + /** + Returns @true if it has a valid @c SAFEARRAY. + */ + bool HasArray() const { return m_array != NULL; } + + /** + Returns the number of dimensions. + */ + size_t GetDim() const; + + /** + Returns lower bound for dimension @a dim in @a bound. + + Dimensions start at @c 1. + */ + bool GetLBound(size_t dim, long& bound) const; + + /** + Returns upper bound for dimension @a dim in @a bound. + + Dimensions start at @c 1. + */ + bool GetUBound(size_t dim, long& bound) const; + + /** + Returns element count for dimension @a dim. Dimensions start at @c 1. + */ + size_t GetCount(size_t dim) const; + + /** + Change the value of the specified element. + + @a indices have the same row-column order as @c rgIndices i + @c SafeArrayPutElement(), i.e., the right-most dimension is + rgIndices[0] and the left-most dimension is stored at + rgIndices[GetDim() – 1]. + + @a element must be of type matching @c varType this wxSafeArray was + created with. For example, wxString for wxSafeArray<@c VT_BSTR>, + wxVariant for wxSafeArray<@c VT_VARIANT>, or @c double for + wxSafeArray<@c VT_R8>. + */ + bool SetElement(long* indices, const externT& element); + + /** + Retrieve the value of the specified element. + + @a indices have the same row-column order as @c rgIndices in + @c SafeArrayGetElement(), i.e., the right-most dimension is + rgIndices[0] and the left-most dimension is stored at + rgIndices[GetDim() – 1]. + + @a element must be of type matching @c varType this wxSafeArray was + created with. For example, wxString for wxSafeArray<@c VT_BSTR>, + wxVariant for wxSafeArray<@c VT_VARIANT>, or @c double for + wxSafeArray<@c VT_R8>. + */ + bool GetElement(long* indices, externT& element) const; + + /** + Converts the array to a wxVariant with the list type, regardless of the + underlying @c SAFEARRAY type. + + If the array is multidimensional, it is flattened using the algorithm + originally employed in wxConvertOleToVariant(). + */ + bool ConvertToVariant(wxVariant& variant) const; + + /** + Converts an array to wxArrayString. + + Can be called only for wxSafeArray<@c VT_BSTR>. If the array is + multidimensional, it is flattened using the algorithm originally + employed in wxConvertOleToVariant(). + */ + bool ConvertToArrayString(wxArrayString& strings) const; + + /** + Converts @a psa to wxVariant. + + @see wxSafeArray::ConvertToVariant(wxVariant&) const + */ + static bool ConvertToVariant(SAFEARRAY* psa, wxVariant& variant); + + /** + Converts @a psa to wxArrayString. + + @see wxSafeArray::ConvertToArrayString(wxArrayString&) const + + */ + static bool ConvertToArrayString(SAFEARRAY* psa, wxArrayString& strings); +}; + /** @class wxAutomationObject