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
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>wxWidgets: Container Classes</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="page_container">
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0" style="width: 100%;">
<tbody>
<tr>
<td id="projectlogo">
<a href="http://www.wxwidgets.org/" target="_new">
<img alt="wxWidgets" src="logo.png"/>
</a>
</td>
<td style="padding-left: 0.5em; text-align: right;">
<span id="projectnumber">Version: 3.0.2</span>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.2 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Categories</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Documentation</a></li><li class="navelem"><a class="el" href="page_topics.html">Programming Guides</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Container Classes </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#overview_container_legacy">Legacy Classes</a></li>
<li class="level1"><a href="#overview_container_std">STL Build</a></li>
</ul>
</div>
<div class="textblock"><p>For historical reasons, wxWidgets uses custom container classes internally.</p>
<p>This was unfortunately unavoidable during a long time when the standard library wasn't widely available and can't be easily changed even now that it is for compatibility reasons. If you are building your own version of the library and don't care about compatibility nor slight (less than 5%) size penalty imposed by the use of STL classes, you may choose to use the "STL" build of wxWidgets in which these custom classes are replaced with their standard counterparts and only read the section <a class="el" href="overview_container.html#overview_container_std">STL Build</a> explaining how to do it.</p>
<p>Otherwise you will need to know about the custom wxWidgets container classes such as <a class="el" href="classwx_list_3_01_t_01_4.html" title="The wxList<T> class provides linked list functionality.">wxList<T></a> and <a class="el" href="classwx_array_3_01_t_01_4.html" title="This section describes the so called "dynamic arrays".">wxArray<T></a> if only to use wxWidgets functions that work with them, e.g. <a class="el" href="classwx_window.html#ad500085ad0511879b5e018706c91a494" title="Returns a reference to the list of the window's children.">wxWindow::GetChildren()</a>, and you should find the information about using these classes below useful.</p>
<p>Notice that we recommend that you use standard classes directly in your own code instead of the container classes provided by wxWidgets in any case as the standard classes are easier to use and may also be safer because of extra run-time checks they may perform as well as more efficient.</p>
<p>Finally notice that recent versions of wxWidgets also provide standard-like classes such as <a class="el" href="classwx_vector_3_01_t_01_4.html" title="wxVector<T> is a template class which implements most of the std::vector class and can be used like i...">wxVector<T></a>, <a class="el" href="classwx_stack_3_01_t_01_4.html" title="wxStack<T> is similar to std::stack and can be used exactly like it.">wxStack<T></a> or wxDList which can be used exactly like the std::vector<T>, std::stack<T> and std::list<T*>, respectively, and actually are just typedefs for the corresponding types if wxWidgets is compiled in STL mode. These classes could be useful if you wish to avoid the use of the standard library in your code for some reason.</p>
<p>To summarize, you should use the standard container classes such as std::vector<T> and std::list<T> if possible and <a class="el" href="classwx_vector_3_01_t_01_4.html" title="wxVector<T> is a template class which implements most of the std::vector class and can be used like i...">wxVector<T></a> or wxDList<T> if it isn't and only use legacy wxWidgets containers such as <a class="el" href="classwx_array_3_01_t_01_4.html" title="This section describes the so called "dynamic arrays".">wxArray<T></a> and <a class="el" href="classwx_list_3_01_t_01_4.html" title="The wxList<T> class provides linked list functionality.">wxList<T></a> when you must, i.e. when you use a wxWidgets function taking or returning a container of such type.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="group__group__class__containers.html">Containers</a></dd></dl>
<h1><a class="anchor" id="overview_container_legacy"></a>
Legacy Classes</h1>
<p>The list classes in wxWidgets are doubly-linked lists which may either own the objects they contain (meaning that the list deletes the object when it is removed from the list or the list itself is destroyed) or just store the pointers depending on whether or not you called <a class="el" href="classwx_list_3_01_t_01_4.html#aacdd6247511c440656421c518ca11f88" title="If destroy is true, instructs the list to call delete on objects stored in the list whenever they are...">wxList<T>::DeleteContents()</a> method.</p>
<p>Dynamic arrays resemble C arrays but with two important differences: they provide run-time range checking in debug builds and they automatically expand the allocated memory when there is no more space for new items. They come in two sorts: the "plain" arrays which store either built-in types such as "char", "int" or "bool" or the pointers to arbitrary objects, or "object arrays" which own the object pointers to which they store.</p>
<p>For the same portability reasons, the container classes implementation in wxWidgets don't use templates, but are rather based on C preprocessor i.e. are implemented using the macros: WX_DECLARE_LIST() and WX_DEFINE_LIST() for the linked lists and WX_DECLARE_ARRAY(), <a class="el" href="dynarray_8h.html#a515e9265b474d8a152ec3ec42179abde" title="This macro declares a new object array class named name and containing the elements of type T...">WX_DECLARE_OBJARRAY()</a> and <a class="el" href="dynarray_8h.html#a52cebddf0dbdeb2d7dbbfb88656f0f79" title="This macro defines the methods of the array class name not defined by the WX_DECLARE_OBJARRAY() macro...">WX_DEFINE_OBJARRAY()</a> for the dynamic arrays.</p>
<p>The "DECLARE" macro declares a new container class containing the elements of given type and is needed for all three types of container classes: lists, arrays and objarrays. The "DEFINE" classes must be inserted in your program in a place where the <em>full</em> declaration of container element class is in scope (i.e. not just forward declaration), otherwise destructors of the container elements will not be called!</p>
<p>As array classes never delete the items they contain anyhow, there is no <a class="el" href="dynarray_8h.html#aa9c653860ef656116ad6914e79e17340" title="This macro defines a new array class named name and containing the elements of type T...">WX_DEFINE_ARRAY()</a> macro for them.</p>
<p>Examples of usage of these macros may be found in <a class="el" href="classwx_list_3_01_t_01_4.html" title="The wxList<T> class provides linked list functionality.">wxList<T></a> and <a class="el" href="classwx_array_3_01_t_01_4.html" title="This section describes the so called "dynamic arrays".">wxArray<T></a> documentation.</p>
<p>Finally, wxWidgets predefines several commonly used container classes. wxList is defined for compatibility with previous versions as a list containing wxObjects and wxStringList as a list of C-style strings (char *), both of these classes are deprecated and should not be used in new programs. The following array classes are defined: wxArrayInt, wxArrayLong, wxArrayPtrVoid and <a class="el" href="classwx_array_string.html" title="wxArrayString is an efficient container for storing wxString objects.">wxArrayString</a>. The first three store elements of corresponding types, but <a class="el" href="classwx_array_string.html" title="wxArrayString is an efficient container for storing wxString objects.">wxArrayString</a> is somewhat special: it is an optimized version of wxArray which uses its knowledge about <a class="el" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> reference counting schema.</p>
<h1><a class="anchor" id="overview_container_std"></a>
STL Build</h1>
<p>To build wxWidgets with the standard containers you need to set wxUSE_STD_CONTAINERS option to 1 in <code>wx/msw/setup.h</code> for wxMSW builds or specify <code>–enable-std_containers</code> option to configure (which is also implicitly enabled by <code>–enable-stl</code> option) in Unix builds.</p>
<p>The standard container build is mostly, but not quite, compatible with the default one. Here are the most important differences:</p>
<ul>
<li>wxList::compatibility_iterator must be used instead of wxList::Node* when iterating over the list contents. The compatibility_iterator class has the same semantics as a Node pointer but it is an object and not a pointer, so you need to write <div class="fragment"><div class="line"><span class="keywordflow">for</span> ( wxWindowList::compatibility_iterator it = list.GetFirst();</div>
<div class="line"> it;</div>
<div class="line"> it = it->GetNext() )</div>
<div class="line"> ...</div>
</div><!-- fragment --> instead of the old <div class="fragment"><div class="line"><span class="keywordflow">for</span> ( wxWindowList::Node *n = list.GetFirst(); n; n = n->GetNext() )</div>
<div class="line"> ...</div>
</div><!-- fragment --></li>
<li><a class="el" href="classwx_sorted_array_string.html" title="wxSortedArrayString is an efficient container for storing wxString objects which always keeps the str...">wxSortedArrayString</a> and <a class="el" href="classwx_array_string.html" title="wxArrayString is an efficient container for storing wxString objects.">wxArrayString</a> are separate classes now and the former doesn't derive from the latter. If you need to convert a sorted array to a normal one, you must copy all the elements. Alternatively, you may avoid the use of <a class="el" href="classwx_sorted_array_string.html" title="wxSortedArrayString is an efficient container for storing wxString objects which always keeps the str...">wxSortedArrayString</a> by using a normal array and calling its Sort() method when needed.</li>
<li>WX_DEFINE_ARRAY_INT(bool) cannot be used because of the differences in std::vector<bool> specialization compared with the generic std::vector<> class. Please either use std::vector<bool> directly or use an integer array instead. </li>
</ul>
</div></div><!-- contents -->
<address class="footer">
<small>
Generated on Thu Nov 27 2014 13:46:42 for wxWidgets by <a href="http://www.doxygen.org/index.html" target="_new">Doxygen</a> 1.8.2
</small>
</address>
<script src="wxwidgets.js" type="text/javascript"></script>
</div><!-- #page_container -->
</body>
</html>
|
