]>
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 | |
9 | %% Licence: wxWindows licence | |
10 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
11 | ||
12 | \section{wxWindows samples}\label{samples} | |
13 | ||
14 | Probably the best way to learn wxWindows is by reading the source of some 50+ | |
15 | samples provided with it. Many aspects of wxWindows programming can be learnt | |
16 | from them, but sometimes it is not simple to just choose the right sample to | |
17 | look at. This overview aims at describing what each sample does/demonstrates to | |
18 | make it easier to find the relevant one if a simple grep through all sources | |
19 | didn't help. They also provide some notes about using the samples and what | |
20 | features of wxWindows are they supposed to test. | |
21 | ||
238ddd26 RR |
22 | There are currently more than 50 different samples as part of wxWindows and |
23 | this list is not complete. | |
24 | ||
25 | \subsection{Minimal sample}\label{sampleminimal} | |
26 | ||
27 | The minimal sample is what most people will know under the term Hello World, | |
28 | i.e. a minimal program that doesn't demonstrate anything apart from what is | |
29 | needed to write a program that will display a "hello" dialog. This is usually | |
30 | a good starting point for learning how to use wxWindows. | |
31 | ||
4f6aed9c VZ |
32 | \subsection{Calendar sample}\label{samplecalendar} |
33 | ||
34 | This font shows the \helpref{calendar control}{wxcalendarctrl} in action. It | |
35 | shows how to configure the control (see the different options in the calendar | |
36 | menu) and also how to process the notifications from it. | |
37 | ||
cddfbd9f RR |
38 | \subsection{Checklist sample}\label{samplechecklist} |
39 | ||
40 | This sample demonstrates the use of the \helpref{wxCheckListBox}{wxchecklistbox} | |
41 | class intercepting check, select and double click events. It also tests the | |
42 | use of various methods modifiying the control, such as by deleting items | |
43 | from it or inserting new once (these fucntions are actually implememted in | |
44 | the parent class \helpref{wxListBox}{wxlistbox} so the sample tests that class | |
45 | as well). The layout of the dialog is created using a \helpref{wxBoxSizer}{wxboxsizer} | |
46 | demonstrating a simple dynamic layout. | |
47 | ||
48 | \subsection{Config sample}\label{sampleconfig} | |
49 | ||
50 | This sample demonstrates the \helpref{wxConfig}{wxconfigbase} classes in a platform | |
51 | indepedent way, i.e. it uses text based files to store a given configuration under | |
52 | Unix and uses the Registry under Windows. | |
53 | ||
54 | See \helpref{wxConfig overview}{wxconfigoverview} for the descriptions of all | |
55 | features of this class. | |
56 | ||
32ab332f RR |
57 | \subsection{Controls sample}\label{samplecontrols} |
58 | ||
59 | The controls sample is the main test program for most simple controls used in | |
60 | wxWindows. The sample tests their basic functionality, events, placement, | |
61 | modification in terms of colour and font as well as the possibility to change | |
62 | the controls programmatically, such as adding item to a list box etc. Apart | |
63 | from that, the sample uses a \helpref{wxNotebook}{wxnotebook} and tests most | |
64 | fetaures of this special control (using bitmap in the tabs, using | |
65 | \helpref{wxSizers}{wxsizer} and \helpref{constraints}{wxlayoutconstraints} within | |
66 | notebook pages, advanving pages programmatically and vetoing a page change | |
67 | by intercepting the \helpref{wxNotebookEvent}{wxnotebookevent}. | |
68 | ||
69 | The various controls tested are listed here: | |
70 | \begin{twocollist}\itemsep=0pt | |
71 | \twocolitem{\helpref{wxButton}{wxbutton}}{Push button control, displaying text} | |
72 | \twocolitem{\helpref{wxBitmapButton}{wxbitmapbutton}}{Push button control, displaying a bitmap} | |
73 | \twocolitem{\helpref{wxCheckBox}{wxcheckbox}}{Checkbox control} | |
74 | \twocolitem{\helpref{wxChoice}{wxchoice}}{Choice control (a combobox without the editable area)} | |
75 | \twocolitem{\helpref{wxComboBox}{wxcombobox}}{A choice with an editable area} | |
76 | \twocolitem{\helpref{wxGauge}{wxgauge}}{A control to represent a varying quantity, such as time remaining} | |
77 | \twocolitem{\helpref{wxStaticBox}{wxstaticbox}}{A static, or group box for visually grouping related controls} | |
78 | \twocolitem{\helpref{wxListBox}{wxlistbox}}{A list of strings for single or multiple selection} | |
79 | \twocolitem{wxSpinCtrl}{A spin ctrl with a text field and a `up-down' control} | |
80 | \twocolitem{\helpref{wxSpinButton}{wxspinbutton}}{A spin or `up-down' control} | |
81 | \twocolitem{\helpref{wxStaticText}{wxstatictext}}{One or more lines of non-editable text} | |
82 | \twocolitem{\helpref{wxStaticBitmap}{wxstaticbitmap}}{A control to display a bitmap} | |
83 | \twocolitem{\helpref{wxRadioBox}{wxradiobox}}{A group of radio buttons} | |
84 | \twocolitem{\helpref{wxRadioButton}{wxradiobutton}}{A round button to be used with others in a mutually exclusive way} | |
85 | \twocolitem{\helpref{wxSlider}{wxslider}}{A slider that can be dragged by the user} | |
86 | \end{twocollist} | |
87 | ||
88 | \subsection{Database sample}\label{sampledb} | |
89 | ||
90 | The database sample is a small test program showing how to use the ODBC | |
91 | classes written by Remstar Intl. These classes are documented in a separate | |
92 | manual available from the wxWindows homepage. Obviously, this sample | |
93 | requires a database with ODBC support to be correctly installed on your | |
94 | system. | |
95 | ||
cddfbd9f RR |
96 | \subsection{Dialogs sample}\label{sampledialogs} |
97 | ||
98 | This sample shows how to use the common dialogs available from wxWindows. These | |
99 | dialogs are desrcibed in details in the \helpref{Common dialogs overview}{commondialogsoverview}. | |
100 | ||
238ddd26 RR |
101 | \subsection{Dynamic sample}\label{sampledynamic} |
102 | ||
103 | This sample is a very small sample that demonstrates the use of the | |
104 | \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} method. This method | |
105 | should be used whenever it is not known at compile time, which control | |
106 | will receive which event or which controls are actually going to be in | |
107 | a dialog or frame. This is most typically the case for any scripting | |
108 | languge that would work as a wrapper for wxWindows or programs where | |
109 | forms or similar datagrams can be created by the uses. | |
110 | ||
0d7ea902 VZ |
111 | \subsection{Exec sample}\label{sampleexec} |
112 | ||
113 | The exec sample demonstrates the \helpref{wxExecute}{wxexecute} and | |
114 | \helpref{wxShell}{wxshell} functions. Both of them are used to execute the | |
115 | external programs and the sample shows how to do this synchronously (waiting | |
116 | until the program terminates) or asynchronously (notification will come later). | |
117 | ||
cddfbd9f RR |
118 | \subsection{Scroll subwindow sample}\label{samplescrollsub} |
119 | ||
120 | This sample demonstrates the use of the \helpref{wxScrolledWindow}{wxscrolledwindow} | |
121 | class including placing subwindows into it and drawing simple graphics. It uses the | |
122 | \helpref{SetTargetWindow}{wxscrolledwindowsettargetwindow} method and thus the effect | |
123 | of scrolling does not show in the scrolled window itself, but in one of its subwindows. | |
124 | ||
125 | Additionally, this samples demonstrates how to optimize drawing operations in wxWindows, | |
126 | in particular using the \helpref{wxWindow::IsExposed}{wxwindowisexposed} method with | |
127 | the aim to prevent unnecessary drawing in the window and thus reducing or removing | |
128 | flicker on screen. | |
129 | ||
775a998e VZ |
130 | \subsection{Font sample}\label{samplefont} |
131 | ||
132 | The font sample demonstrates \helpref{wxFont}{wxfont}, | |
133 | \helpref{wxFontEnumerator}{wxfontenumerator} and | |
134 | \helpref{wxFontMapper}{wxfontmapper} classes. It allows you to see the fonts | |
135 | available (to wxWindows) on the computer and shows all characters of the | |
136 | chosen font as well. | |
137 | ||
c03648c2 | 138 | \subsection{DnD sample}\label{samplednd} |
eb91c0be VZ |
139 | |
140 | This sample shows both clipboard and drag and drop in action. It is quite non | |
141 | trivial and may be safely used as a basis for implementing the clipboard and | |
142 | drag and drop operations in a real-life program. | |
143 | ||
144 | When you run the sample, its screen is split in several parts. On the top, | |
145 | there are two listboxes which show the standard derivations of | |
146 | \helpref{wxDropTarget}{wxdroptarget}: | |
147 | \helpref{wxTextDropTarget}{wxtextdroptarget} and | |
148 | \helpref{wxFileDropTarget}{wxfiledroptarget}. | |
149 | ||
150 | The middle of the sample window is taken by the log window which shows what is | |
151 | going on (of course, this only works in debug builds) and may be helpful to see | |
152 | the sequence of steps of data transfer. | |
153 | ||
0d7ea902 VZ |
154 | Finally, the last part is used for dragging text from it to either one of the |
155 | listboxes (only one will accept it) or another application. The last | |
156 | functionality available from the main frame is to paste a bitmap from the | |
157 | clipboard (or, in the case of Windows version, also a metafile) - it will be | |
158 | shown in a new frame. | |
eb91c0be VZ |
159 | |
160 | So far, everything we mentioned was implemented with minimal amount of code | |
161 | using standard wxWindows classes. The more advanced features are demonstrated | |
162 | if you create a shape frame from the main frame menu. A shape is a geometric | |
163 | object which has a position, size and color. It models some | |
164 | application-specific data in this sample. A shape object supports its own | |
165 | private \helpref{wxDataFormat}{wxdataformat} which means that you may cut and | |
166 | paste it or drag and drop (between one and the same or different shapes) from | |
167 | one sample instance to another (or the same). However, chances are that no | |
168 | other program supports this format and so shapes can also be rendered as | |
0d7ea902 VZ |
169 | bitmaps which allows them to be pasted/dropped in many other applications |
170 | (and, under Windows, also as metafiles which are supported by most of Windows | |
171 | programs as well - try Write/Wordpad, for example). | |
eb91c0be VZ |
172 | |
173 | Take a look at DnDShapeDataObject class to see how you may use | |
174 | \helpref{wxDataObject}{wxdataobject} to achieve this. | |
cd77c085 | 175 | |
61eff74f VS |
176 | \subsection{HTML samples}\label{samplehtml} |
177 | ||
178 | Eight HTML samples (you can find them in directory {\tt samples/html}) | |
179 | cover all features of HTML sub-library. | |
180 | ||
181 | {\bf Test} demonstrates how to create \helpref{wxHtmlWindow}{wxhtmlwindow} | |
182 | and also shows most of supported HTML tags. | |
183 | ||
184 | {\bf Widget} shows how you can embed ordinary controls or windows within | |
185 | HTML page. It also nicely explains how to write new tag handlers and extend | |
186 | the library to work with unsupported tags. | |
187 | ||
188 | {\bf About} may give you an idea how to write good-looking about boxes. | |
189 | ||
190 | {\bf Zip} demonstrates use of virtual file systems in wxHTML. The zip archives | |
191 | handler (ships with wxWindows) allows you to access HTML pages stored | |
192 | in compressed archive as if they were ordinary files. | |
193 | ||
194 | {\bf Virtual} is yet another VFS demo. This one generates pages at run-time. | |
195 | You may find it useful if you need to display some reports in your application. | |
196 | ||
197 | {\bf Printing} explains use of \helpref{wxHtmlEasyPrinting}{wxhtmleasyprinting} | |
198 | class which serves as as-simple-as-possible interface for printing HTML | |
199 | documents without much work. In fact, only few function calls are sufficient. | |
200 | ||
201 | {\bf Help} and {\bf Helpview} are variations on displaying HTML help | |
202 | (compatible with MS HTML Help Workshop). {\it Help} shows how to embed | |
203 | \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller} in your application | |
204 | while {\it Helpview} is simple tool that only pops up help window and | |
205 | displays help books given at command line. | |
206 | ||
238ddd26 RR |
207 | \subsection{Layout sample}\label{samplelayout} |
208 | ||
209 | The layout sample demonstrates the two different layout systems offered | |
210 | by wxWindows. When starting the program, you will see a frame with some | |
211 | controls and some graphics. The controls will change their size whenever | |
212 | you resize the entire frame and the exact behaviour of the size changes | |
213 | is determined using the \helpref{wxLayoutConstraints}{wxlayoutconstraints} | |
214 | class. See also the \helpref{overview}{constraintsoverview} and the | |
215 | \helpref{wxIndividualLayoutConstraint}{wxindividuallayoutconstraint} | |
216 | class for further information. | |
217 | ||
218 | The menu in this sample offers two more tests, one showing how to use | |
219 | a \helpref{wxBoxSizer}{wxboxsizer} in a simple dialog and the other one | |
220 | showing how to use sizers in connection with a \helpref{wxNotebook}{wxnotebook} | |
221 | class. See also \helpref{wxNotebookSizer}{wxnotebooksizer} and | |
222 | \helpref{wxSizer}{wxsizer}. | |
223 | ||
32ab332f RR |
224 | \subsection{Image sample}\label{sampleimage} |
225 | ||
226 | The image sample demonstrates the use of the \helpref{wxImage}{wximage} class | |
227 | and shows how to download images in a variety of formats, currently PNG, GIF, | |
228 | TIFF, JPEG, BMP, PNM and PCX. The top of the sample shows to rectangles, one | |
229 | of which is drawn directly in the window, the other one is drawn into a | |
230 | \helpref{wxBitmap}{wxbitmap}, converted to a wxImage, saved as a PNG image | |
231 | and then reloaded from the PNG file again so that conversions between wxImage | |
232 | and wxBitmap as well as loading and save PNG files are tested. | |
233 | ||
234 | At the bottom of the main frame is a test for using a mono-chrome bitmap by | |
235 | drawing into a \helpref{wxMemoryDC}{wxmemorydc}. The bitmap is then drawn | |
236 | specifying the foreground and background colours with | |
237 | \helpref{wxDC::SetTextForeground}{wxdcsettextforeground} and | |
238 | \helpref{wxDC::SetTextBackground}{wxdcsettextbackground} (on the left). The | |
239 | bitmap is then converted to a wxImage and the foreground colour (black) is | |
240 | replaced with red using \helpref{wxImage::Replace}{wximagereplace}. | |
241 | ||
e5a2291a GRG |
242 | \subsection{Sockets sample}\label{samplesockets} |
243 | ||
244 | The sockets sample demonstrates how to use the communication facilities | |
245 | provided by \helpref{wxSocket}{wxsocketbase}. There are two different | |
246 | applications in this sample: a server, which is implemented as a | |
247 | \helpref{wxSocketServer}{wxsocketserver} object, and a client, which is | |
248 | implemented with \helpref{wxSocketClient}{wxsocketclient}. | |
249 | ||
250 | The server binds to the local address, using TCP port number 3000, sets | |
251 | up an event handler to be notified of incoming connection requests | |
252 | ({\bf wxSOCKET\_CONNECTION} event), and stands there, waiting (listening | |
253 | in the socket parlance) for clients. For each incoming client, a new | |
254 | \helpref{wxSocketBase}{wxsocketbase} object is created, which represents | |
255 | the connection. Connections are independent from the server that created | |
256 | them, so they set up their own event handler, and stay awaiting for | |
257 | {\bf wxSOCKET\_INPUT} (incoming data) or {\bf wxSOCKET\_LOST} (connection | |
258 | closed at the remote end) events. This event handler is the same for all | |
259 | connections, and demonstrates how to determine which socket the event | |
260 | is addressed to by using the \helpref{Socket}{wxsocketeventsocket} function | |
261 | in the \helpref{wxSocketEvent}{wxsocketevent} class. | |
262 | ||
263 | Although it might take some time to get used to the event-oriented | |
264 | system upon which wxSocket is built, the benefits are many. See, for | |
265 | example, that the server application, while being single-threaded | |
266 | (and of course without using fork() or ugly select() loops) can handle | |
267 | an arbitrary number of connections. | |
268 | ||
269 | The client starts up unconnected, so you can use the Connect... option | |
270 | to specify the address of the server you are going to connect to (the | |
271 | TCP port number is hard-coded as 3000). Once connected, a number of | |
272 | tests are possible. Currently, three tests are implemented. They show | |
273 | how to use the basic IO calls in \helpref{wxSocketBase}{wxsocketbase}, | |
274 | such as \helpref{Read}{wxsocketbaseread}, \helpref{Write}{wxsocketbasewrite}, | |
275 | \helpref{ReadMsg}{wxsocketbasereadmsg} and \helpref{WriteMsg}{wxsocketbasewritemsg}, | |
276 | and how to set up the correct IO flags depending on what you are going to | |
277 | do. See the comments in the code for more information (a lengthy explanation | |
278 | on socket flags is available in \helpref{SetFlags}{wxsocketbasesetflags}). | |
279 | Note that because both clients and connection objects in the server set | |
280 | up an event handler to catch {\bf wxSOCKET\_LOST} events, each one is | |
281 | immediately notified if the other end closes the connection. | |
282 | ||
283 | The sockets sample is work in progress. Coming soon: | |
284 | ||
285 | \begin{itemize} | |
286 | ||
287 | \item More tests for basic socket functionality. | |
288 | ||
289 | \item Tests for the recently added datagram socket classes. | |
290 | ||
291 | \item Tests for protocol classes (wxProtocol and its descendants). | |
292 | ||
293 | \item New samples which actually do something useful (suggestions accepted). | |
294 | ||
295 | \end{itemize} | |
296 | ||
238ddd26 RR |
297 | \subsection{Text sample}\label{sampletext} |
298 | ||
299 | This sample demonstrates four features: firstly the use and many variants of | |
300 | the \helpref{wxTextCtrl}{wxtextctrl} class (single line, multi line, read only, | |
301 | password, ignoring TAB, ignoring ENTER). | |
302 | ||
303 | Secondly it shows how to intercept a \helpref{wxKeyEvent}{wxkeyevent} in both | |
304 | the raw form using the {\tt EVT_KEY_UP} and {\tt EVT_KEY_DOWN} macros and the | |
305 | higherlevel from using the {\tt EVT_CHAR} macro. All characters will be logged | |
306 | in a log window at the bottom of the main window. By pressing some of the function | |
307 | keys, you can test some actions in the text ctrl as well as get statitics on the | |
308 | text ctrls, which is useful for testing if these statitics actually are correct. | |
309 | ||
310 | Thirdly, on platforms which support it, the sample will offer to copy text to the | |
311 | \helpref{wxClipboard}{wxclipboard} and to paste text from it. The GTK version will | |
312 | use the so called PRIMARY SELECTION, which is the pseudo clipboard under X and | |
313 | best known from pasting text to the XTerm program. | |
314 | ||
315 | Last not least: some of the text controls have tooltips and the sample also shows | |
316 | how tooltips can be centrally disabled and their latency controlled. | |
317 | ||
c88275cb RR |
318 | \subsection{Thread sample}\label{samplethread} |
319 | ||
320 | This sample demonstrates the use of threads in connection with GUI programs. | |
321 | There are two fundamentally different ways to use threads in GUI programs and | |
322 | either way has to take care of the fact that the GUI library itself usually | |
323 | is not multi-threading safe, i.e. that it might crash if two threads try to | |
324 | access the GUI class simultaneously. One way to prevent that is have a normal | |
325 | GUI program in the main thread and some worker threads which work in the | |
326 | background. In order to make communication between the main thread and the | |
327 | worker threads possible, wxWindows offers the \helpref{wxPostEvent}{wxpostevent} | |
328 | function and this sample makes use of this function. | |
329 | ||
330 | The other way to use a so called Mutex (such as those offered in the \helpref{wxMutex}{wxmutex} | |
331 | class) that prevent threads from accessing the GUI classes as long as any other | |
332 | thread accesses them. For this, wxWindows has the \helpref{wxMutexGuiEnter}{wxmutexguienter} | |
333 | and \helpref{wxMutexGuiLeave}{wxmutexguileave} functions, both of which are | |
334 | used and tested in the sample as well. | |
335 | ||
336 | See also \helpref{Multithreading overview}{wxthreadoverview} and \helpref{wxThread}{wxthread}. | |
337 | ||
5ef2e633 VZ |
338 | \subsection{Toolbar sample}\label{sampletoolbar} |
339 | ||
340 | The toolbar sample shows the \helpref{wxToolBar}{wxtoolbar} class in action. | |
341 | ||
342 | The following things are demonstrated: | |
343 | ||
344 | \begin{itemize} | |
345 | ||
346 | \item Creating the toolbar using \helpref{wxToolBar::AddTool}{wxtoolbaraddtool} | |
347 | and \helpref{wxToolBar::AddControl}{wxtoolbaraddcontrol}: see | |
348 | MyApp::InitToolbar in the sample. | |
349 | ||
350 | \item Using {\tt EVT\_UPDATE\_UI} handler for automatically enabling/disabling | |
351 | toolbar buttons without having to explicitly call EnableTool. This is is done | |
352 | in MyFrame::OnUpdateCopyAndCut. | |
353 | ||
354 | \item Using \helpref{wxToolBar::DeleteTool}{wxtoolbardeletetool} and | |
355 | \helpref{wxToolBar::InsertTool}{wxtoolbarinserttool} to dynamically update the | |
356 | toolbar. | |
357 | ||
358 | \end{itemize} |