1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
/////////////////////////////////////////////////////////////////////////////
// Name: msw/ole/automtn.h
// Purpose: interface of wxSafeArray
// Author: wxWidgets team
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@class wxSafeArray<varType>
wxSafeArray<varType> 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
*/
template <VARTYPE varType>
class wxSafeArray<varType>
{
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
<tt>rgIndices[0]</tt> and the left-most dimension is stored at
<tt>rgIndices[</tt>GetDim()<tt> – 1]</tt>.
@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
<tt>rgIndices[0]</tt> and the left-most dimension is stored at
<tt>rgIndices[</tt>GetDim()<tt> – 1]</tt>.
@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<varType>::ConvertToVariant(wxVariant&) const
*/
static bool ConvertToVariant(SAFEARRAY* psa, wxVariant& variant);
/**
Converts @a psa to wxArrayString.
@see wxSafeArray<varType>::ConvertToArrayString(wxArrayString&) const
*/
static bool ConvertToArrayString(SAFEARRAY* psa, wxArrayString& strings);
};
|
