1 /////////////////////////////////////////////////////////////////////////////
2 // Name:        msw/ole/automtn.h
3 // Purpose:     interface of wxSafeArray
4 // Author:      wxWidgets team
5 // Licence:     wxWindows licence
6 /////////////////////////////////////////////////////////////////////////////
7 
8 
9 /**
10     @class wxSafeArray<varType>
11 
12     wxSafeArray<varType> is wxWidgets wrapper for working with MS Windows @c
13     SAFEARRAY used in Component Object Model (COM) and OLE Automation APIs.
14 
15     It also has convenience functions for converting between @c SAFEARRAY and
16     wxVariant with list type or wxArrayString.
17 
18     wxSafeArray is a template class which must be created with an appropriate
19     type matching the underlying @c VARIANT type (such as @c VT_VARIANT or @c
20     VT_BSTR).
21 
22     See wxVariantDataSafeArray documentation for examples of using it.
23 
24     @onlyfor{wxmsw}
25     @since 3.0
26 
27     @library{wxcore}
28     @category{data}
29 
30     @see wxAutomationObject, wxVariantDataSafeArray, wxVariant
31 */
32 template <VARTYPE varType>
33 class wxSafeArray<varType>
34 {
35 public:
36 
37     /**
38         The default constructor.
39     */
40     wxSafeArray();
41 
42     /**
43         The destructor unlocks and destroys the owned @c SAFEARRAY.
44     */
45     ~wxSafeArray();
46 
47     /**
48         Creates and locks a zero-based one-dimensional @c SAFEARRAY with the
49         given number of elements.
50     */
51     bool Create(size_t count);
52 
53     /**
54         Creates and locks a @c SAFEARRAY.
55 
56         See @c SafeArrayCreate() in MSDN documentation for more information.
57     */
58     bool Create(SAFEARRAYBOUND* bound, size_t dimensions);
59 
60     /**
61         Creates a zero-based one-dimensional @c SAFEARRAY from wxVariant
62         with the list type.
63 
64         Can be called only for wxSafeArray<@c VT_VARIANT>.
65     */
66     bool CreateFromListVariant(const wxVariant& variant);
67 
68     /**
69         Creates a zero-based one-dimensional @c SAFEARRAY from wxArrayString.
70 
71         Can be called only for wxSafeArray<@c VT_BSTR>.
72     */
73     bool CreateFromArrayString(const wxArrayString& strings);
74 
75     /**
76         Attaches and locks an existing @c SAFEARRAY.
77 
78         The array must have the same @c VARTYPE as this wxSafeArray was
79         instantiated with.
80     */
81     bool Attach(SAFEARRAY* array);
82 
83     /**
84         Unlocks the owned @c SAFEARRAY, returns it and gives up its ownership.
85     */
86     SAFEARRAY* Detach();
87 
88     /**
89         Unlocks and destroys the owned @c SAFEARRAY.
90     */
91     void Destroy();
92 
93     /**
94         Returns @true if it has a valid @c SAFEARRAY.
95     */
HasArray()96     bool HasArray() const { return m_array != NULL; }
97 
98     /**
99         Returns the number of dimensions.
100     */
101     size_t GetDim() const;
102 
103     /**
104         Returns lower bound for dimension @a dim in @a bound.
105 
106         Dimensions start at @c 1.
107     */
108     bool GetLBound(size_t dim, long& bound) const;
109 
110     /**
111         Returns upper bound for dimension @a dim in @a bound.
112 
113         Dimensions start at @c 1.
114     */
115     bool GetUBound(size_t dim, long& bound) const;
116 
117     /**
118         Returns element count for dimension @a dim. Dimensions start at @c 1.
119     */
120     size_t GetCount(size_t dim) const;
121 
122     /**
123         Change the value of the specified element.
124 
125         @a indices have the same row-column order as @c rgIndices i
126         @c SafeArrayPutElement(), i.e., the right-most dimension is
127         <tt>rgIndices[0]</tt> and the left-most dimension is stored at
128         <tt>rgIndices[</tt>GetDim()<tt> – 1]</tt>.
129 
130         @a element must be of type matching @c varType this wxSafeArray was
131         created with. For example, wxString for wxSafeArray<@c VT_BSTR>,
132         wxVariant for wxSafeArray<@c VT_VARIANT>, or @c double for
133         wxSafeArray<@c VT_R8>.
134     */
135     bool SetElement(long* indices, const externT& element);
136 
137     /**
138         Retrieve the value of the specified element.
139 
140         @a indices have the same row-column order as @c rgIndices in
141         @c SafeArrayGetElement(), i.e., the right-most dimension is
142         <tt>rgIndices[0]</tt> and the left-most dimension is stored at
143         <tt>rgIndices[</tt>GetDim()<tt> – 1]</tt>.
144 
145         @a element must be of type matching @c varType this wxSafeArray was
146         created with. For example, wxString for wxSafeArray<@c VT_BSTR>,
147         wxVariant for wxSafeArray<@c VT_VARIANT>, or @c double for
148         wxSafeArray<@c VT_R8>.
149     */
150     bool GetElement(long* indices, externT& element) const;
151 
152     /**
153         Converts the array to a wxVariant with the list type, regardless of the
154         underlying @c SAFEARRAY type.
155 
156         If the array is multidimensional, it is flattened using the algorithm
157         originally employed in wxConvertOleToVariant().
158     */
159     bool ConvertToVariant(wxVariant& variant) const;
160 
161     /**
162         Converts an array to wxArrayString.
163 
164         Can be called only for wxSafeArray<@c VT_BSTR>. If the array is
165         multidimensional, it is flattened using the algorithm originally
166         employed in wxConvertOleToVariant().
167     */
168     bool ConvertToArrayString(wxArrayString& strings) const;
169 
170     /**
171         Converts @a psa to wxVariant.
172 
173         @see wxSafeArray<varType>::ConvertToVariant(wxVariant&) const
174     */
175     static bool ConvertToVariant(SAFEARRAY* psa, wxVariant& variant);
176 
177     /**
178         Converts @a psa to wxArrayString.
179 
180         @see wxSafeArray<varType>::ConvertToArrayString(wxArrayString&) const
181 
182     */
183     static bool ConvertToArrayString(SAFEARRAY* psa, wxArrayString& strings);
184 };
185