Commit | Line | Data |
---|---|---|
eb91c0be VZ |
1 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
2 | %% Name: tsamples.tex | |
3 | %% Purpose: Samples description | |
4 | %% Author: Vadim Zeitlin | |
5 | %% Modified by: | |
6 | %% Created: 02.11.99 | |
7 | %% RCS-ID: $Id$ | |
8 | %% Copyright: (c) wxWindows team | |
f6bcfd97 | 9 | %% License: wxWindows license |
eb91c0be | 10 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
963863ad VZ |
11 | % NB: please keep the subsections in alphabetic order! |
12 | ||
eb91c0be VZ |
13 | \section{wxWindows samples}\label{samples} |
14 | ||
15 | Probably the best way to learn wxWindows is by reading the source of some 50+ | |
16 | samples provided with it. Many aspects of wxWindows programming can be learnt | |
17 | from them, but sometimes it is not simple to just choose the right sample to | |
18 | look at. This overview aims at describing what each sample does/demonstrates to | |
19 | make it easier to find the relevant one if a simple grep through all sources | |
20 | didn't help. They also provide some notes about using the samples and what | |
21 | features of wxWindows are they supposed to test. | |
22 | ||
238ddd26 | 23 | There are currently more than 50 different samples as part of wxWindows and |
963863ad VZ |
24 | this list is not complete. You should start your tour of wxWindows with the |
25 | \helpref{minimal sample}{sampleminimal} which is the wxWindows version of | |
26 | "Hello, world!". It shows the basic structure of wxWindows program and is the | |
27 | most commented sample of all - looking at its source code is recommended. | |
28 | ||
29 | The next most useful sample is probably the \helpref{controls}{samplecontrols} | |
30 | one which shows many of wxWindows standard controls, such as buttons, | |
ecf527c0 | 31 | listboxes, checkboxes, comboboxes etc. |
963863ad VZ |
32 | |
33 | Other, more complicated controls, have their own samples. In this category you | |
34 | may find the following samples showing the corresponding controls: | |
35 | ||
36 | \begin{twocollist}\itemsep=0pt | |
37 | \twocolitem{\helpref{wxCalendarCtrl}{samplecalendar}}{Calendar a.k.a. date picker control} | |
38 | \twocolitem{\helpref{wxListCtrl}{samplelistctrl}}{List view control} | |
39 | \twocolitem{\helpref{wxTreeCtrl}{sampletreectrl}}{Tree view control} | |
40 | \twocolitem{\helpref{wxGrid}{samplegrid}}{Grid control} | |
41 | \end{twocollist} | |
42 | ||
43 | Finally, it might be helpful to do a search in the entire sample directory if | |
44 | you can't find the sample you showing the control you are interested in by | |
45 | name. Most of wxWindows classes, occur in at least one of the samples. | |
238ddd26 RR |
46 | |
47 | \subsection{Minimal sample}\label{sampleminimal} | |
48 | ||
49 | The minimal sample is what most people will know under the term Hello World, | |
50 | i.e. a minimal program that doesn't demonstrate anything apart from what is | |
51 | needed to write a program that will display a "hello" dialog. This is usually | |
52 | a good starting point for learning how to use wxWindows. | |
53 | ||
4f6aed9c VZ |
54 | \subsection{Calendar sample}\label{samplecalendar} |
55 | ||
56 | This font shows the \helpref{calendar control}{wxcalendarctrl} in action. It | |
57 | shows how to configure the control (see the different options in the calendar | |
58 | menu) and also how to process the notifications from it. | |
59 | ||
cddfbd9f RR |
60 | \subsection{Checklist sample}\label{samplechecklist} |
61 | ||
62 | This sample demonstrates the use of the \helpref{wxCheckListBox}{wxchecklistbox} | |
63 | class intercepting check, select and double click events. It also tests the | |
f6bcfd97 BP |
64 | use of various methods modifying the control, such as by deleting items |
65 | from it or inserting new once (these functions are actually implemented in | |
cddfbd9f RR |
66 | the parent class \helpref{wxListBox}{wxlistbox} so the sample tests that class |
67 | as well). The layout of the dialog is created using a \helpref{wxBoxSizer}{wxboxsizer} | |
68 | demonstrating a simple dynamic layout. | |
69 | ||
70 | \subsection{Config sample}\label{sampleconfig} | |
71 | ||
72 | This sample demonstrates the \helpref{wxConfig}{wxconfigbase} classes in a platform | |
f6bcfd97 | 73 | indenpedent way, i.e. it uses text based files to store a given configuration under |
cddfbd9f RR |
74 | Unix and uses the Registry under Windows. |
75 | ||
76 | See \helpref{wxConfig overview}{wxconfigoverview} for the descriptions of all | |
77 | features of this class. | |
78 | ||
32ab332f RR |
79 | \subsection{Controls sample}\label{samplecontrols} |
80 | ||
81 | The controls sample is the main test program for most simple controls used in | |
82 | wxWindows. The sample tests their basic functionality, events, placement, | |
83 | modification in terms of colour and font as well as the possibility to change | |
84 | the controls programmatically, such as adding item to a list box etc. Apart | |
85 | from that, the sample uses a \helpref{wxNotebook}{wxnotebook} and tests most | |
f6bcfd97 | 86 | features of this special control (using bitmap in the tabs, using |
32ab332f | 87 | \helpref{wxSizers}{wxsizer} and \helpref{constraints}{wxlayoutconstraints} within |
f6bcfd97 | 88 | notebook pages, advancing pages programmatically and vetoing a page change |
32ab332f RR |
89 | by intercepting the \helpref{wxNotebookEvent}{wxnotebookevent}. |
90 | ||
91 | The various controls tested are listed here: | |
ecf527c0 | 92 | |
32ab332f RR |
93 | \begin{twocollist}\itemsep=0pt |
94 | \twocolitem{\helpref{wxButton}{wxbutton}}{Push button control, displaying text} | |
95 | \twocolitem{\helpref{wxBitmapButton}{wxbitmapbutton}}{Push button control, displaying a bitmap} | |
96 | \twocolitem{\helpref{wxCheckBox}{wxcheckbox}}{Checkbox control} | |
97 | \twocolitem{\helpref{wxChoice}{wxchoice}}{Choice control (a combobox without the editable area)} | |
98 | \twocolitem{\helpref{wxComboBox}{wxcombobox}}{A choice with an editable area} | |
99 | \twocolitem{\helpref{wxGauge}{wxgauge}}{A control to represent a varying quantity, such as time remaining} | |
100 | \twocolitem{\helpref{wxStaticBox}{wxstaticbox}}{A static, or group box for visually grouping related controls} | |
101 | \twocolitem{\helpref{wxListBox}{wxlistbox}}{A list of strings for single or multiple selection} | |
102 | \twocolitem{wxSpinCtrl}{A spin ctrl with a text field and a `up-down' control} | |
103 | \twocolitem{\helpref{wxSpinButton}{wxspinbutton}}{A spin or `up-down' control} | |
104 | \twocolitem{\helpref{wxStaticText}{wxstatictext}}{One or more lines of non-editable text} | |
105 | \twocolitem{\helpref{wxStaticBitmap}{wxstaticbitmap}}{A control to display a bitmap} | |
106 | \twocolitem{\helpref{wxRadioBox}{wxradiobox}}{A group of radio buttons} | |
107 | \twocolitem{\helpref{wxRadioButton}{wxradiobutton}}{A round button to be used with others in a mutually exclusive way} | |
108 | \twocolitem{\helpref{wxSlider}{wxslider}}{A slider that can be dragged by the user} | |
109 | \end{twocollist} | |
110 | ||
111 | \subsection{Database sample}\label{sampledb} | |
112 | ||
113 | The database sample is a small test program showing how to use the ODBC | |
114 | classes written by Remstar Intl. These classes are documented in a separate | |
115 | manual available from the wxWindows homepage. Obviously, this sample | |
116 | requires a database with ODBC support to be correctly installed on your | |
117 | system. | |
118 | ||
cddfbd9f RR |
119 | \subsection{Dialogs sample}\label{sampledialogs} |
120 | ||
121 | This sample shows how to use the common dialogs available from wxWindows. These | |
f6bcfd97 BP |
122 | dialogs are described in details in the \helpref{Common dialogs overview}{commondialogsoverview}. |
123 | ||
124 | \subsection{Dialup sample}\label{sampledialup} | |
125 | ||
126 | This sample shows \helpref{wxDialUpManager}{wxdialupmanager} | |
127 | class. It displays in the status bar the information gathered through itsi | |
128 | nterface: in particular, the current connection status (online or offline) and | |
129 | whether the connection is permanent (in which case a string `LAN' appears in | |
130 | the thrid status bar field - but note that you may have be on a LAN not | |
131 | connected to the Internet, in which case you will not see this) or not. | |
132 | ||
133 | Using the menu entries, you may also dial or hang up the line if you have a | |
134 | modem attached and (this only makes sense for Windows) list the available | |
135 | connections. | |
cddfbd9f | 136 | |
238ddd26 RR |
137 | \subsection{Dynamic sample}\label{sampledynamic} |
138 | ||
139 | This sample is a very small sample that demonstrates the use of the | |
140 | \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} method. This method | |
141 | should be used whenever it is not known at compile time, which control | |
142 | will receive which event or which controls are actually going to be in | |
143 | a dialog or frame. This is most typically the case for any scripting | |
f6bcfd97 | 144 | language that would work as a wrapper for wxWindows or programs where |
238ddd26 RR |
145 | forms or similar datagrams can be created by the uses. |
146 | ||
0d7ea902 VZ |
147 | \subsection{Exec sample}\label{sampleexec} |
148 | ||
149 | The exec sample demonstrates the \helpref{wxExecute}{wxexecute} and | |
150 | \helpref{wxShell}{wxshell} functions. Both of them are used to execute the | |
151 | external programs and the sample shows how to do this synchronously (waiting | |
152 | until the program terminates) or asynchronously (notification will come later). | |
153 | ||
f6bcfd97 BP |
154 | It also shows how to capture the output of the child process in both |
155 | synchronous and asynchronous cases. | |
156 | ||
cddfbd9f RR |
157 | \subsection{Scroll subwindow sample}\label{samplescrollsub} |
158 | ||
528e0faf | 159 | This sample demonstrates the use of the \helpref{wxScrolledWindow}{wxscrolledwindow} |
f6bcfd97 | 160 | class including placing subwindows into it and drawing simple graphics. It uses the |
cddfbd9f RR |
161 | \helpref{SetTargetWindow}{wxscrolledwindowsettargetwindow} method and thus the effect |
162 | of scrolling does not show in the scrolled window itself, but in one of its subwindows. | |
163 | ||
164 | Additionally, this samples demonstrates how to optimize drawing operations in wxWindows, | |
165 | in particular using the \helpref{wxWindow::IsExposed}{wxwindowisexposed} method with | |
166 | the aim to prevent unnecessary drawing in the window and thus reducing or removing | |
167 | flicker on screen. | |
168 | ||
b4e87ec3 GRG |
169 | \subsection{Rotate sample}\label{samplerotate} |
170 | ||
171 | This is a simple example which demonstrates how to rotate an image with | |
172 | the \helpref{wxImage::Rotate}{wximagerotate} method. The rotation can | |
173 | be done without interpolation (left mouse button) which will be faster, | |
174 | or with interpolation (right mouse button) which is slower but gives | |
175 | better results. | |
176 | ||
775a998e VZ |
177 | \subsection{Font sample}\label{samplefont} |
178 | ||
179 | The font sample demonstrates \helpref{wxFont}{wxfont}, | |
180 | \helpref{wxFontEnumerator}{wxfontenumerator} and | |
181 | \helpref{wxFontMapper}{wxfontmapper} classes. It allows you to see the fonts | |
182 | available (to wxWindows) on the computer and shows all characters of the | |
183 | chosen font as well. | |
184 | ||
c03648c2 | 185 | \subsection{DnD sample}\label{samplednd} |
eb91c0be VZ |
186 | |
187 | This sample shows both clipboard and drag and drop in action. It is quite non | |
188 | trivial and may be safely used as a basis for implementing the clipboard and | |
189 | drag and drop operations in a real-life program. | |
190 | ||
191 | When you run the sample, its screen is split in several parts. On the top, | |
192 | there are two listboxes which show the standard derivations of | |
193 | \helpref{wxDropTarget}{wxdroptarget}: | |
194 | \helpref{wxTextDropTarget}{wxtextdroptarget} and | |
195 | \helpref{wxFileDropTarget}{wxfiledroptarget}. | |
196 | ||
197 | The middle of the sample window is taken by the log window which shows what is | |
198 | going on (of course, this only works in debug builds) and may be helpful to see | |
199 | the sequence of steps of data transfer. | |
200 | ||
0d7ea902 VZ |
201 | Finally, the last part is used for dragging text from it to either one of the |
202 | listboxes (only one will accept it) or another application. The last | |
203 | functionality available from the main frame is to paste a bitmap from the | |
204 | clipboard (or, in the case of Windows version, also a metafile) - it will be | |
205 | shown in a new frame. | |
eb91c0be VZ |
206 | |
207 | So far, everything we mentioned was implemented with minimal amount of code | |
208 | using standard wxWindows classes. The more advanced features are demonstrated | |
209 | if you create a shape frame from the main frame menu. A shape is a geometric | |
210 | object which has a position, size and color. It models some | |
211 | application-specific data in this sample. A shape object supports its own | |
212 | private \helpref{wxDataFormat}{wxdataformat} which means that you may cut and | |
213 | paste it or drag and drop (between one and the same or different shapes) from | |
214 | one sample instance to another (or the same). However, chances are that no | |
215 | other program supports this format and so shapes can also be rendered as | |
0d7ea902 VZ |
216 | bitmaps which allows them to be pasted/dropped in many other applications |
217 | (and, under Windows, also as metafiles which are supported by most of Windows | |
218 | programs as well - try Write/Wordpad, for example). | |
eb91c0be VZ |
219 | |
220 | Take a look at DnDShapeDataObject class to see how you may use | |
221 | \helpref{wxDataObject}{wxdataobject} to achieve this. | |
cd77c085 | 222 | |
963863ad VZ |
223 | \subsection{Grid sample}\label{samplegrid} |
224 | ||
225 | TODO. | |
226 | ||
61eff74f VS |
227 | \subsection{HTML samples}\label{samplehtml} |
228 | ||
229 | Eight HTML samples (you can find them in directory {\tt samples/html}) | |
230 | cover all features of HTML sub-library. | |
231 | ||
528e0faf | 232 | {\bf Test} demonstrates how to create \helpref{wxHtmlWindow}{wxhtmlwindow} |
61eff74f VS |
233 | and also shows most of supported HTML tags. |
234 | ||
235 | {\bf Widget} shows how you can embed ordinary controls or windows within | |
236 | HTML page. It also nicely explains how to write new tag handlers and extend | |
237 | the library to work with unsupported tags. | |
238 | ||
239 | {\bf About} may give you an idea how to write good-looking about boxes. | |
240 | ||
241 | {\bf Zip} demonstrates use of virtual file systems in wxHTML. The zip archives | |
242 | handler (ships with wxWindows) allows you to access HTML pages stored | |
243 | in compressed archive as if they were ordinary files. | |
244 | ||
f6bcfd97 | 245 | {\bf Virtual} is yet another virtual file systems demo. This one generates pages at run-time. |
61eff74f VS |
246 | You may find it useful if you need to display some reports in your application. |
247 | ||
528e0faf | 248 | {\bf Printing} explains use of \helpref{wxHtmlEasyPrinting}{wxhtmleasyprinting} |
61eff74f VS |
249 | class which serves as as-simple-as-possible interface for printing HTML |
250 | documents without much work. In fact, only few function calls are sufficient. | |
251 | ||
252 | {\bf Help} and {\bf Helpview} are variations on displaying HTML help | |
f6bcfd97 | 253 | (compatible with MS HTML Help Workshop). {\it Help} shows how to embed |
61eff74f VS |
254 | \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller} in your application |
255 | while {\it Helpview} is simple tool that only pops up help window and | |
256 | displays help books given at command line. | |
257 | ||
963863ad VZ |
258 | \subsection{Image sample}\label{sampleimage} |
259 | ||
260 | The image sample demonstrates the use of the \helpref{wxImage}{wximage} class | |
261 | and shows how to download images in a variety of formats, currently PNG, GIF, | |
262 | TIFF, JPEG, BMP, PNM and PCX. The top of the sample shows to rectangles, one | |
f6bcfd97 | 263 | of which is drawn directly in the window, the other one is drawn into a |
963863ad VZ |
264 | \helpref{wxBitmap}{wxbitmap}, converted to a wxImage, saved as a PNG image |
265 | and then reloaded from the PNG file again so that conversions between wxImage | |
266 | and wxBitmap as well as loading and save PNG files are tested. | |
267 | ||
105521d1 | 268 | At the bottom of the main frame is a test for using a monochrome bitmap by |
963863ad VZ |
269 | drawing into a \helpref{wxMemoryDC}{wxmemorydc}. The bitmap is then drawn |
270 | specifying the foreground and background colours with | |
271 | \helpref{wxDC::SetTextForeground}{wxdcsettextforeground} and | |
272 | \helpref{wxDC::SetTextBackground}{wxdcsettextbackground} (on the left). The | |
273 | bitmap is then converted to a wxImage and the foreground colour (black) is | |
274 | replaced with red using \helpref{wxImage::Replace}{wximagereplace}. | |
275 | ||
238ddd26 RR |
276 | \subsection{Layout sample}\label{samplelayout} |
277 | ||
278 | The layout sample demonstrates the two different layout systems offered | |
279 | by wxWindows. When starting the program, you will see a frame with some | |
280 | controls and some graphics. The controls will change their size whenever | |
281 | you resize the entire frame and the exact behaviour of the size changes | |
528e0faf JS |
282 | is determined using the \helpref{wxLayoutConstraints}{wxlayoutconstraints} |
283 | class. See also the \helpref{overview}{constraintsoverview} and the | |
284 | \helpref{wxIndividualLayoutConstraint}{wxindividuallayoutconstraint} | |
238ddd26 RR |
285 | class for further information. |
286 | ||
287 | The menu in this sample offers two more tests, one showing how to use | |
288 | a \helpref{wxBoxSizer}{wxboxsizer} in a simple dialog and the other one | |
528e0faf | 289 | showing how to use sizers in connection with a \helpref{wxNotebook}{wxnotebook} |
238ddd26 RR |
290 | class. See also \helpref{wxNotebookSizer}{wxnotebooksizer} and |
291 | \helpref{wxSizer}{wxsizer}. | |
292 | ||
963863ad | 293 | \subsection{Listctrl sample}\label{samplelistctrl} |
32ab332f | 294 | |
963863ad VZ |
295 | This sample shows \helpref{wxListCtrl}{wxlistctrl} control. Different modes |
296 | supported by the control (list, icons, small icons, report) may be chosen from | |
297 | the menu. | |
32ab332f | 298 | |
963863ad VZ |
299 | The sample also provides some timings for adding/deleting/sorting a lot of |
300 | (several thousands) controls into the control. | |
32ab332f | 301 | |
e5a2291a GRG |
302 | \subsection{Sockets sample}\label{samplesockets} |
303 | ||
304 | The sockets sample demonstrates how to use the communication facilities | |
305 | provided by \helpref{wxSocket}{wxsocketbase}. There are two different | |
528e0faf | 306 | applications in this sample: a server, which is implemented using a |
5adbbc29 GRG |
307 | \helpref{wxSocketServer}{wxsocketserver} object, and a client, which |
308 | is implemented as a \helpref{wxSocketClient}{wxsocketclient}. | |
309 | ||
310 | The server binds to the local address, using TCP port number 3000, | |
311 | sets up an event handler to be notified of incoming connection requests | |
312 | ({\bf wxSOCKET\_CONNECTION} events), and stands there, waiting for clients | |
313 | ({\it listening} in the socket parlance). For each accepted connection, | |
314 | a new \helpref{wxSocketBase}{wxsocketbase} object is created. These | |
315 | socket objects are independent from the server that created them, so | |
316 | they set up their own event handler, and then request to be notified | |
528e0faf | 317 | of {\bf wxSOCKET\_INPUT} (incoming data) or {\bf wxSOCKET\_LOST} |
5adbbc29 GRG |
318 | (connection closed at the remote end) events. In the sample, the event |
319 | handler is the same for all connections; to find out which socket the | |
f6bcfd97 BP |
320 | event is addressed to, the \helpref{GetSocket}{wxsocketeventgetsocket} function |
321 | is used. | |
e5a2291a GRG |
322 | |
323 | Although it might take some time to get used to the event-oriented | |
324 | system upon which wxSocket is built, the benefits are many. See, for | |
325 | example, that the server application, while being single-threaded | |
326 | (and of course without using fork() or ugly select() loops) can handle | |
327 | an arbitrary number of connections. | |
328 | ||
329 | The client starts up unconnected, so you can use the Connect... option | |
330 | to specify the address of the server you are going to connect to (the | |
331 | TCP port number is hard-coded as 3000). Once connected, a number of | |
332 | tests are possible. Currently, three tests are implemented. They show | |
333 | how to use the basic IO calls in \helpref{wxSocketBase}{wxsocketbase}, | |
528e0faf | 334 | such as \helpref{Read}{wxsocketbaseread}, \helpref{Write}{wxsocketbasewrite}, |
e5a2291a GRG |
335 | \helpref{ReadMsg}{wxsocketbasereadmsg} and \helpref{WriteMsg}{wxsocketbasewritemsg}, |
336 | and how to set up the correct IO flags depending on what you are going to | |
5adbbc29 GRG |
337 | do. See the comments in the code for more information. Note that because |
338 | both clients and connection objects in the server set up an event handler | |
339 | to catch {\bf wxSOCKET\_LOST} events, each one is immediately notified | |
340 | if the other end closes the connection. | |
e5a2291a | 341 | |
f6bcfd97 BP |
342 | There is also an URL test which shows how to use |
343 | the \helpref{wxURL}{wxurl} class to fetch data from a given URL. | |
b4e87ec3 | 344 | |
5adbbc29 | 345 | The sockets sample is work in progress. Some things to do: |
e5a2291a | 346 | |
ecf527c0 | 347 | \begin{itemize}\itemsep=0pt |
e5a2291a | 348 | \item More tests for basic socket functionality. |
b4e87ec3 | 349 | \item More tests for protocol classes (wxProtocol and its descendants). |
5adbbc29 | 350 | \item Tests for the recently added (and still in alpha stage) datagram sockets. |
e5a2291a | 351 | \item New samples which actually do something useful (suggestions accepted). |
e5a2291a GRG |
352 | \end{itemize} |
353 | ||
2286341c VZ |
354 | \subsection{Statbar sample}\label{samplestatbar} |
355 | ||
105521d1 | 356 | This sample shows how to create and use wxStatusBar. Although most of the |
2286341c VZ |
357 | samples have a statusbar, they usually only create a default one and only |
358 | do it once. | |
359 | ||
360 | Here you can see how to recreate the statusbar (with possibly different number | |
361 | of fields) and how to use it to show icons/bitmaps and/or put arbitrary | |
362 | controls into it. | |
363 | ||
238ddd26 RR |
364 | \subsection{Text sample}\label{sampletext} |
365 | ||
366 | This sample demonstrates four features: firstly the use and many variants of | |
367 | the \helpref{wxTextCtrl}{wxtextctrl} class (single line, multi line, read only, | |
368 | password, ignoring TAB, ignoring ENTER). | |
369 | ||
370 | Secondly it shows how to intercept a \helpref{wxKeyEvent}{wxkeyevent} in both | |
d17f05af | 371 | the raw form using the {\tt EVT\_KEY\_UP} and {\tt EVT\_KEY\_DOWN} macros and the |
f6bcfd97 | 372 | higher level from using the {\tt EVT\_CHAR} macro. All characters will be logged |
238ddd26 | 373 | in a log window at the bottom of the main window. By pressing some of the function |
f6bcfd97 BP |
374 | keys, you can test some actions in the text ctrl as well as get statistics on the |
375 | text ctrls, which is useful for testing if these stastitics actually are correct. | |
238ddd26 | 376 | |
528e0faf | 377 | Thirdly, on platforms which support it, the sample will offer to copy text to the |
238ddd26 RR |
378 | \helpref{wxClipboard}{wxclipboard} and to paste text from it. The GTK version will |
379 | use the so called PRIMARY SELECTION, which is the pseudo clipboard under X and | |
380 | best known from pasting text to the XTerm program. | |
381 | ||
382 | Last not least: some of the text controls have tooltips and the sample also shows | |
383 | how tooltips can be centrally disabled and their latency controlled. | |
384 | ||
c88275cb RR |
385 | \subsection{Thread sample}\label{samplethread} |
386 | ||
387 | This sample demonstrates the use of threads in connection with GUI programs. | |
388 | There are two fundamentally different ways to use threads in GUI programs and | |
389 | either way has to take care of the fact that the GUI library itself usually | |
390 | is not multi-threading safe, i.e. that it might crash if two threads try to | |
391 | access the GUI class simultaneously. One way to prevent that is have a normal | |
392 | GUI program in the main thread and some worker threads which work in the | |
393 | background. In order to make communication between the main thread and the | |
528e0faf | 394 | worker threads possible, wxWindows offers the \helpref{wxPostEvent}{wxpostevent} |
c88275cb RR |
395 | function and this sample makes use of this function. |
396 | ||
528e0faf | 397 | The other way to use a so called Mutex (such as those offered in the \helpref{wxMutex}{wxmutex} |
c88275cb | 398 | class) that prevent threads from accessing the GUI classes as long as any other |
528e0faf | 399 | thread accesses them. For this, wxWindows has the \helpref{wxMutexGuiEnter}{wxmutexguienter} |
c88275cb RR |
400 | and \helpref{wxMutexGuiLeave}{wxmutexguileave} functions, both of which are |
401 | used and tested in the sample as well. | |
402 | ||
403 | See also \helpref{Multithreading overview}{wxthreadoverview} and \helpref{wxThread}{wxthread}. | |
404 | ||
5ef2e633 VZ |
405 | \subsection{Toolbar sample}\label{sampletoolbar} |
406 | ||
407 | The toolbar sample shows the \helpref{wxToolBar}{wxtoolbar} class in action. | |
408 | ||
409 | The following things are demonstrated: | |
410 | ||
ecf527c0 JS |
411 | \begin{itemize}\itemsep=0pt |
412 | \item Creating the toolbar using \helpref{wxToolBar::AddTool}{wxtoolbaraddtool} | |
5ef2e633 VZ |
413 | and \helpref{wxToolBar::AddControl}{wxtoolbaraddcontrol}: see |
414 | MyApp::InitToolbar in the sample. | |
5ef2e633 | 415 | \item Using {\tt EVT\_UPDATE\_UI} handler for automatically enabling/disabling |
f6bcfd97 | 416 | toolbar buttons without having to explicitly call EnableTool. This is done |
5ef2e633 | 417 | in MyFrame::OnUpdateCopyAndCut. |
5ef2e633 VZ |
418 | \item Using \helpref{wxToolBar::DeleteTool}{wxtoolbardeletetool} and |
419 | \helpref{wxToolBar::InsertTool}{wxtoolbarinserttool} to dynamically update the | |
420 | toolbar. | |
5ef2e633 | 421 | \end{itemize} |
963863ad VZ |
422 | |
423 | \subsection{Treectrl sample}\label{sampletreectrl} | |
424 | ||
425 | This sample demonstrates using \helpref{wxTreeCtrl}{wxtreectrl} class. Here | |
426 | you may see how to process various notification messages sent by this control | |
427 | and also when they occur (by looking at the messages in the text control in | |
428 | the bottom part of the frame). | |
429 | ||
430 | Adding, inserting and deleting items and branches from the tree as well as | |
431 | sorting (in default alphabetical order as well as in custom one) is | |
432 | demonstrated here as well - try the corresponding menu entries. | |
ecf527c0 | 433 | |
f6bcfd97 BP |
434 | \subsection{Wizard sample}\label{samplewizard} |
435 | ||
436 | This sample shows so-called wizard dialog (implemented using | |
437 | \helpref{wxWizard}{wxwizard} and related classes). It shows almost all | |
438 | features supported: | |
439 | ||
440 | \begin{itemize}\itemsep=0pt | |
441 | \item Using bitmaps with the wizard and changing them depending on the page | |
442 | shown (notice that wxValidationPage in the sample has a different image from | |
443 | the other ones) | |
444 | \item Using \helpref{TransferDataFromWindow}{wxwindowtransferdatafromwindow} | |
445 | to verify that the data entered is correct before passing to the next page | |
446 | (done in wxValidationPage which forces the user to check a checkbox before | |
447 | continuing). | |
448 | \item Using more elaborated techniques to allow returning to the previous | |
449 | page, but not continuing to the next one or vice versa (in wxRadioboxPage) | |
450 | \item This (wxRadioboxPage) page also shows how the page may process {\tt | |
451 | Cancel} button itself instead of relying on the wizard parent to do it. | |
452 | \item Normally, the order of the pages in the wizard is known at compile-time, | |
453 | but sometimes it depends on the user choices: wxCheckboxPage shows how to | |
454 | dynamically decide which page to display next (see also | |
455 | \helpref{wxWizardPage}{wxwizardpage}) | |
456 | \end{itemize} | |
457 |