]>
Commit | Line | Data |
---|---|---|
1 | \chapter{Introduction}\label{introduction} | |
2 | \pagenumbering{arabic}% | |
3 | \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% | |
4 | \setfooter{\thepage}{}{}{}{}{\thepage}% | |
5 | ||
6 | \section{What is wxWindows?} | |
7 | ||
8 | wxWindows is a C++ framework providing GUI (Graphical User | |
9 | Interface) and other facilities on more than one platform. Version 2 currently | |
10 | supports all desktop versions of MS Windows, Unix with GTK+, Unix with Motif, | |
11 | and MacOS. An OS/2 port is in progress. | |
12 | ||
13 | wxWindows was originally developed at the Artificial Intelligence | |
14 | Applications Institute, University of Edinburgh, for internal use, | |
15 | and was first made publicly available in 1992. | |
16 | Version 2 is a vastly improved version written and maintained by | |
17 | Julian Smart, Robert Roebling, Vadim Zeitlin, Vaclav Slavik and many others. | |
18 | ||
19 | This manual contains a class reference and topic overviews. | |
20 | For a selection of wxWindows tutorials, please see the documentation page on the \urlref{wxWindows web site}{http://www.wxwindows.org}. | |
21 | ||
22 | Please note that in the following, ``MS Windows" often refers to all | |
23 | platforms related to Microsoft Windows, including 16-bit and 32-bit | |
24 | variants, unless otherwise stated. All trademarks are acknowledged. | |
25 | ||
26 | \section{Why another cross-platform development tool?} | |
27 | ||
28 | wxWindows was developed to provide a cheap and flexible way to maximize | |
29 | investment in GUI application development. While a number of commercial | |
30 | class libraries already existed for cross-platform development, | |
31 | none met all of the following criteria: | |
32 | ||
33 | \begin{enumerate}\itemsep=0pt | |
34 | \item low price; | |
35 | \item source availability; | |
36 | \item simplicity of programming; | |
37 | \item support for a wide range of compilers. | |
38 | \end{enumerate} | |
39 | ||
40 | Since wxWindows was started, several other free or almost-free | |
41 | GUI frameworks have emerged. However, none has the range of | |
42 | features, flexibility, documentation and the well-established | |
43 | development team that wxWindows has. | |
44 | ||
45 | As open source software, wxWindows has benefited from comments, | |
46 | ideas, bug fixes, enhancements and the sheer enthusiasm of | |
47 | users. This gives wxWindows a certain advantage over its | |
48 | commercial competitors (and over free libraries without an | |
49 | independent development team), plus a robustness against the | |
50 | transience of one individual or company. This openness and | |
51 | availability of source code is especially important when the | |
52 | future of thousands of lines of application code may depend upon | |
53 | the longevity of the underlying class library. | |
54 | ||
55 | Version 2 goes much further than previous versions in terms of | |
56 | generality and features, allowing applications to be produced | |
57 | that are often indistinguishable from those produced using | |
58 | single-platform toolkits such as Motif, GTK+ and MFC. | |
59 | ||
60 | The importance of using a platform-independent class library | |
61 | cannot be overstated, since GUI application development is very | |
62 | time-consuming, and sustained popularity of particular GUIs | |
63 | cannot be guaranteed. Code can very quickly become obsolete if | |
64 | it addresses the wrong platform or audience. wxWindows helps to | |
65 | insulate the programmer from these winds of change. Although | |
66 | wxWindows may not be suitable for every application (such as an | |
67 | OLE-intensive program), it provides access to most of the | |
68 | functionality a GUI program normally requires, plus many extras | |
69 | such as network programming, PostScript output, and HTML | |
70 | rendering; and it can of course be extended as needs dictate. | |
71 | As a bonus, it provides a far cleaner and easier programming | |
72 | interface than the native APIs. Programmers may find it | |
73 | worthwhile to use wxWindows even if they are developing on only | |
74 | one platform. | |
75 | ||
76 | It is impossible to sum up the functionality of wxWindows in a few paragraphs, but | |
77 | here are some of the benefits: | |
78 | ||
79 | \begin{itemize}\itemsep=0pt | |
80 | \item Low cost (free, in fact!) | |
81 | \item You get the source. | |
82 | \item Available on a variety of popular platforms. | |
83 | \item Works with almost all popular C++ compilers and Python. | |
84 | \item Over 50 example programs. | |
85 | \item Over 1000 pages of printable and on-line documentation. | |
86 | \item Includes Tex2RTF, to allow you to produce your own documentation | |
87 | in Windows Help, HTML and Word RTF formats. | |
88 | \item Simple-to-use, object-oriented API. | |
89 | \item Flexible event system. | |
90 | \item Graphics calls include lines, rounded rectangles, splines, polylines, etc. | |
91 | \item Constraint-based and sizer-based layouts. | |
92 | \item Print/preview and document/view architectures. | |
93 | \item Toolbar, notebook, tree control, advanced list control classes. | |
94 | \item PostScript generation under Unix, normal MS Windows printing on the PC. | |
95 | \item MDI (Multiple Document Interface) support. | |
96 | \item Can be used to create DLLs under Windows, dynamic libraries on Unix. | |
97 | \item Common dialogs for file browsing, printing, colour selection, etc. | |
98 | \item Under MS Windows, support for creating metafiles and copying | |
99 | them to the clipboard. | |
100 | \item An API for invoking help from applications. | |
101 | \item Ready-to-use HTML window (supporting a subset of HTML). | |
102 | \item Dialog Editor for building dialogs. | |
103 | \item Network support via a family of socket and protocol classes. | |
104 | \item Support for platform independent image processing. | |
105 | \item Built-in support for many file formats (BMP, PNG, JPEG, GIF, XPM, PNM, PCX). | |
106 | \end{itemize} | |
107 | ||
108 | \begin{comment} | |
109 | \section{Changes from version 2.0}\label{versionchanges20} | |
110 | ||
111 | These are a few of the differences between versions 2.0 and 2.2. | |
112 | ||
113 | Removals: | |
114 | ||
115 | \begin{itemize}\itemsep=0pt | |
116 | \item GTK 1.0 no longer supported. | |
117 | \end{itemize} | |
118 | ||
119 | Additions and changes: | |
120 | ||
121 | \begin{itemize}\itemsep=0pt | |
122 | \item Corrected many classes to conform better to documented behaviour. | |
123 | \item Added handlers for more image formats (Now GIF, JPEG, PCX, BMP, XPM, PNG, PNM). | |
124 | \item Improved support for socket and network functions. | |
125 | \item Support for different national font encodings. | |
126 | \item Sizer based layout system. | |
127 | \item HTML widget and help system. | |
128 | \item Added some controls (e.g. wxSpinCtrl) and supplemented many. | |
129 | \item Many optical improvements to GTK port. | |
130 | \item Support for menu accelerators in GTK port. | |
131 | \item Enhanced and improved support for scrolling, including child windows. | |
132 | \item Complete rewrite of clipboard and drag and drop classes. | |
133 | \item Improved support for ODBC databases. | |
134 | \item Improved tab traversal in dialogs. | |
135 | \end{itemize} | |
136 | \end{comment} | |
137 | ||
138 | \section{wxWindows requirements}\label{requirements} | |
139 | ||
140 | To make use of wxWindows, you currently need one of the following setups. | |
141 | ||
142 | (a) MS-Windows: | |
143 | ||
144 | \begin{enumerate}\itemsep=0pt | |
145 | \item A 486 or higher PC running MS Windows. | |
146 | \item A Windows compiler: most are supported, but please see {\tt install.txt} for | |
147 | details. Supported compilers include Microsoft Visual C++ 4.0 or higher, Borland C++, Cygwin, | |
148 | Metrowerks CodeWarrior. | |
149 | \item At least 60 MB of disk space. | |
150 | \end{enumerate} | |
151 | ||
152 | (b) Unix: | |
153 | ||
154 | \begin{enumerate}\itemsep=0pt | |
155 | \item Almost any C++ compiler, including GNU C++ (EGCS 1.1.1 or above). | |
156 | \item Almost any Unix workstation, and one of: GTK+ 1.2, Motif 1.2 or higher, Lesstif. | |
157 | \item At least 60 MB of disk space. | |
158 | \end{enumerate} | |
159 | ||
160 | (c) Mac OS/Mac OS X: | |
161 | ||
162 | \begin{enumerate}\itemsep=0pt | |
163 | \item A PowerPC Mac running Mac OS 8.6/9.x (eg. Classic) or Mac OS X 10.x. | |
164 | \item CodeWarrior 5.3, 6 or 7 for Classic Mac OS. | |
165 | \item The Apple Developer Tools (eg. GNU C++) or CodeWarrior 7 for Mac OS X. | |
166 | \item At least 60 MB of disk space. | |
167 | \end{enumerate} | |
168 | ||
169 | \section{Availability and location of wxWindows} | |
170 | ||
171 | \winhelponly{wxWindows is available by anonymous FTP and World Wide Web | |
172 | from ftp://www.remstar.com/pub/wxwin and/or http://www.wxwindows.org.} | |
173 | \winhelpignore{wxWindows is available by anonymous FTP and World Wide Web | |
174 | from \urlref{ftp://www.remstar.com/pub/wxwin}{ftp://www.remstar.com/pub/wxwin} | |
175 | and/or \urlref{http://www.wxwindows.org}{http://www.wxwindows.org}.} | |
176 | ||
177 | You can also buy a CD-ROM using the form on the Web site. | |
178 | ||
179 | \section{Acknowledgments} | |
180 | ||
181 | Thanks are due to AIAI for being willing to release the original version of | |
182 | wxWindows into the public domain, and to our patient partners. | |
183 | ||
184 | We would particularly like to thank the following for their contributions to wxWindows, and the many others who have been involved in | |
185 | the project over the years. Apologies for any unintentional omissions from this list. | |
186 | ||
187 | Yiorgos Adamopoulos, Jamshid Afshar, Alejandro Aguilar-Sierra, AIAI, Patrick Albert, Karsten Ballueder, Michael Bedward, Kai Bendorf, Yura Bidus, Keith | |
188 | Gary Boyce, Chris Breeze, Pete Britton, Ian Brown, C. Buckley, Dmitri Chubraev, Robin Corbet, Cecil Coupe, Andrew Davison, Neil Dudman, Robin | |
189 | Dunn, Hermann Dunkel, Jos van Eijndhoven, Tom Felici, Thomas Fettig, Matthew Flatt, Pasquale Foggia, Josep Fortiana, Todd Fries, Dominic Gallagher, | |
190 | Guillermo Rodriguez Garcia, Wolfram Gloger, Norbert Grotz, Stefan Gunter, Bill Hale, Patrick Halke, Stefan Hammes, Guillaume Helle, Harco de Hilster, Cord Hockemeyer, Markus | |
191 | Holzem, Olaf Klein, Leif Jensen, Bart Jourquin, Guilhem Lavaux, Jan Lessner, Nicholas Liebmann, Torsten Liermann, Per Lindqvist, Thomas Runge, Tatu | |
192 | M\"{a}nnist\"{o}, Scott Maxwell, Thomas Myers, Oliver Niedung, Stefan Neis, Hernan Otero, Ian Perrigo, Timothy Peters, Giordano Pezzoli, Harri Pasanen, Thomaso Paoletti, | |
193 | Garrett Potts, Marcel Rasche, Robert Roebling, Dino Scaringella, Jobst Schmalenbach, Arthur Seaton, Paul Shirley, Vaclav Slavik, Stein Somers, Petr Smilauer, Neil Smith, | |
194 | Kari Syst\"{a}, Arthur Tetzlaff-Deas, Jonathan Tonberg, Jyrki Tuomi, David Webster, Janos Vegh, Andrea Venturoli, Vadim Zeitlin, Xiaokun Zhu, Edward Zimmermann. | |
195 | ||
196 | `Graphplace', the basis for the wxGraphLayout library, is copyright Dr. Jos | |
197 | T.J. van Eijndhoven of Eindhoven University of Technology. The code has | |
198 | been used in wxGraphLayout with his permission. | |
199 | ||
200 | We also acknowledge the author of XFIG, the excellent Unix drawing tool, | |
201 | from the source of which we have borrowed some spline drawing code. | |
202 | His copyright is included below. | |
203 | ||
204 | {\it XFig2.1 is copyright (c) 1985 by Supoj Sutanthavibul. Permission to | |
205 | use, copy, modify, distribute, and sell this software and its | |
206 | documentation for any purpose is hereby granted without fee, provided | |
207 | that the above copyright notice appear in all copies and that both that | |
208 | copyright notice and this permission notice appear in supporting | |
209 | documentation, and that the name of M.I.T. not be used in advertising or | |
210 | publicity pertaining to distribution of the software without specific, | |
211 | written prior permission. M.I.T. makes no representations about the | |
212 | suitability of this software for any purpose. It is provided ``as is'' | |
213 | without express or implied warranty.} | |
214 | ||
215 | \chapter{Multi-platform development with wxWindows}\label{multiplat} | |
216 | \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% | |
217 | \setfooter{\thepage}{}{}{}{}{\thepage}% | |
218 | ||
219 | This chapter describes the practical details of using wxWindows. Please | |
220 | see the file install.txt for up-to-date installation instructions, and | |
221 | changes.txt for differences between versions. | |
222 | ||
223 | \section{Include files} | |
224 | ||
225 | The main include file is {\tt "wx/wx.h"}; this includes the most commonly | |
226 | used modules of wxWindows. | |
227 | ||
228 | To save on compilation time, include only those header files relevant to the | |
229 | source file. If you are using precompiled headers, you should include | |
230 | the following section before any other includes: | |
231 | ||
232 | \begin{verbatim} | |
233 | // For compilers that support precompilation, includes "wx.h". | |
234 | #include <wx/wxprec.h> | |
235 | ||
236 | #ifdef __BORLANDC__ | |
237 | #pragma hdrstop | |
238 | #endif | |
239 | ||
240 | #ifndef WX_PRECOMP | |
241 | // Include your minimal set of headers here, or wx.h | |
242 | #include <wx/wx.h> | |
243 | #endif | |
244 | ||
245 | ... now your other include files ... | |
246 | \end{verbatim} | |
247 | ||
248 | The file {\tt "wx/wxprec.h"} includes {\tt "wx/wx.h"}. Although this incantation | |
249 | may seem quirky, it is in fact the end result of a lot of experimentation, | |
250 | and several Windows compilers to use precompilation (those tested are Microsoft Visual C++, Borland C++ | |
251 | and Watcom C++). | |
252 | ||
253 | Borland precompilation is largely automatic. Visual C++ requires specification of {\tt "wx/wxprec.h"} as | |
254 | the file to use for precompilation. Watcom C++ is automatic apart from the specification of | |
255 | the .pch file. Watcom C++ is strange in requiring the precompiled header to be used only for | |
256 | object files compiled in the same directory as that in which the precompiled header was created. | |
257 | Therefore, the wxWindows Watcom C++ makefiles go through hoops deleting and recreating | |
258 | a single precompiled header file for each module, thus preventing an accumulation of many | |
259 | multi-megabyte .pch files. | |
260 | ||
261 | \section{Libraries} | |
262 | ||
263 | The GTK and Motif ports of wxWindow can create either a static library or a shared | |
264 | library on most Unix or Unix-like systems. The static library is called libwx\_gtk.a | |
265 | and libwx\_motif.a whereas the name of the shared library is dependent on the | |
266 | system it is created on and the version you are using. The library name for the | |
267 | GTK version of wxWindows 2.2 on Linux and Solaris will be libwx\_gtk-2.2.so.0.0.0, | |
268 | on HP-UX, it will be libwx\_gtk-2.2.sl, on AIX just libwx\_gtk.a etc. | |
269 | ||
270 | Under Windows, use the library wx.lib (release) or wxd.lib (debug) for stand-alone Windows | |
271 | applications, or wxdll.lib (wxdlld.lib) for creating DLLs. | |
272 | ||
273 | \section{Configuration} | |
274 | ||
275 | Options are configurable in the file | |
276 | \rtfsp{\tt "wx/XXX/setup.h"} where XXX is the required platform (such as msw, motif, gtk, mac). Some | |
277 | settings are a matter of taste, some help with platform-specific problems, and | |
278 | others can be set to minimize the size of the library. Please see the setup.h file | |
279 | and {\tt install.txt} files for details on configuration. | |
280 | ||
281 | Under Unix (GTK and Motif) the corresponding setup.h files are generated automatically | |
282 | when configuring the wxWindows using the "configure" script. When using the RPM packages | |
283 | for installing wxWindows on Linux, a correct setup.h is shipped in the package and | |
284 | this must not be changed. | |
285 | ||
286 | \section{Makefiles} | |
287 | ||
288 | At the moment there is no attempt to make Unix makefiles and | |
289 | PC makefiles compatible, i.e. one makefile is required for | |
290 | each environment. The Unix ports use a sophisticated system based | |
291 | on the GNU autoconf tool and this system will create the | |
292 | makefiles as required on the respective platform. Although the | |
293 | makefiles are not identical in Windows, Mac and Unix, care has | |
294 | been taken to make them relatively similar so that moving from | |
295 | one platform to another will be painless. | |
296 | ||
297 | Sample makefiles for Unix (suffix .unx), MS C++ (suffix .DOS and .NT), Borland | |
298 | C++ (.BCC and .B32) and Symantec C++ (.SC) are included for the library, demos | |
299 | and utilities. | |
300 | ||
301 | The controlling makefile for wxWindows is in the MS-Windows | |
302 | directory {\tt src/msw} for the different Windows compiler and | |
303 | in the build directory when using the Unix ports. The build | |
304 | directory can be chosen by the user. It is the directory in | |
305 | which the "configure" script is run. This can be the normal | |
306 | base directory (by running {\tt ./configure} there) or any other | |
307 | directory (e.g. {\tt ../configure} after creating a build-directory | |
308 | in the directory level above the base directory). | |
309 | ||
310 | Please see the platform-specific {\tt install.txt} file for further details. | |
311 | ||
312 | \section{Windows-specific files} | |
313 | ||
314 | wxWindows application compilation under MS Windows requires at least two | |
315 | extra files, resource and module definition files. | |
316 | ||
317 | \subsection{Resource file}\label{resources} | |
318 | ||
319 | The least that must be defined in the Windows resource file (extension RC) | |
320 | is the following statement: | |
321 | ||
322 | \begin{verbatim} | |
323 | rcinclude "wx/msw/wx.rc" | |
324 | \end{verbatim} | |
325 | ||
326 | which includes essential internal wxWindows definitions. The resource script | |
327 | may also contain references to icons, cursors, etc., for example: | |
328 | ||
329 | \begin{verbatim} | |
330 | wxicon icon wx.ico | |
331 | \end{verbatim} | |
332 | ||
333 | The icon can then be referenced by name when creating a frame icon. See | |
334 | the MS Windows SDK documentation. | |
335 | ||
336 | \normalbox{Note: include wx.rc {\it after} any ICON statements | |
337 | so programs that search your executable for icons (such | |
338 | as the Program Manager) find your application icon first.} | |
339 | ||
340 | \subsection{Module definition file} | |
341 | ||
342 | A module definition file (extension DEF) is required for 16-bit applications, and | |
343 | looks like the following: | |
344 | ||
345 | \begin{verbatim} | |
346 | NAME Hello | |
347 | DESCRIPTION 'Hello' | |
348 | EXETYPE WINDOWS | |
349 | STUB 'WINSTUB.EXE' | |
350 | CODE PRELOAD MOVEABLE DISCARDABLE | |
351 | DATA PRELOAD MOVEABLE MULTIPLE | |
352 | HEAPSIZE 1024 | |
353 | STACKSIZE 8192 | |
354 | \end{verbatim} | |
355 | ||
356 | The only lines which will usually have to be changed per application are | |
357 | NAME and DESCRIPTION. | |
358 | ||
359 | \section{Allocating and deleting wxWindows objects} | |
360 | ||
361 | In general, classes derived from wxWindow must dynamically allocated | |
362 | with {\it new} and deleted with {\it delete}. If you delete a window, | |
363 | all of its children and descendants will be automatically deleted, | |
364 | so you don't need to delete these descendants explicitly. | |
365 | ||
366 | When deleting a frame or dialog, use {\bf Destroy} rather than {\bf delete} so | |
367 | that the wxWindows delayed deletion can take effect. This waits until idle time | |
368 | (when all messages have been processed) to actually delete the window, to avoid | |
369 | problems associated with the GUI sending events to deleted windows. | |
370 | ||
371 | Don't create a window on the stack, because this will interfere | |
372 | with delayed deletion. | |
373 | ||
374 | If you decide to allocate a C++ array of objects (such as wxBitmap) that may | |
375 | be cleaned up by wxWindows, make sure you delete the array explicitly | |
376 | before wxWindows has a chance to do so on exit, since calling {\it delete} on | |
377 | array members will cause memory problems. | |
378 | ||
379 | wxColour can be created statically: it is not automatically cleaned | |
380 | up and is unlikely to be shared between other objects; it is lightweight | |
381 | enough for copies to be made. | |
382 | ||
383 | Beware of deleting objects such as a wxPen or wxBitmap if they are still in use. | |
384 | Windows is particularly sensitive to this: so make sure you | |
385 | make calls like wxDC::SetPen(wxNullPen) or wxDC::SelectObject(wxNullBitmap) before deleting | |
386 | a drawing object that may be in use. Code that doesn't do this will probably work | |
387 | fine on some platforms, and then fail under Windows. | |
388 | ||
389 | \section{Architecture dependency} | |
390 | ||
391 | A problem which sometimes arises from writing multi-platform programs is that | |
392 | the basic C types are not defined the same on all platforms. This holds true | |
393 | for both the length in bits of the standard types (such as int and long) as | |
394 | well as their byte order, which might be little endian (typically | |
395 | on Intel computers) or big endian (typically on some Unix workstations). wxWindows | |
396 | defines types and macros that make it easy to write architecture independent | |
397 | code. The types are: | |
398 | ||
399 | wxInt32, wxInt16, wxInt8, wxUint32, wxUint16 = wxWord, wxUint8 = wxByte | |
400 | ||
401 | where wxInt32 stands for a 32-bit signed integer type etc. You can also check | |
402 | which architecture the program is compiled on using the wxBYTE\_ORDER define | |
403 | which is either wxBIG\_ENDIAN or wxLITTLE\_ENDIAN (in the future maybe wxPDP\_ENDIAN | |
404 | as well). | |
405 | ||
406 | The macros handling bit-swapping with respect to the applications endianness | |
407 | are described in the \helpref{Byte order macros}{byteordermacros} section. | |
408 | ||
409 | \section{Conditional compilation} | |
410 | ||
411 | One of the purposes of wxWindows is to reduce the need for conditional | |
412 | compilation in source code, which can be messy and confusing to follow. | |
413 | However, sometimes it is necessary to incorporate platform-specific | |
414 | features (such as metafile use under MS Windows). The symbols | |
415 | listed in the file {\tt symbols.txt} may be used for this purpose, | |
416 | along with any user-supplied ones. | |
417 | ||
418 | \section{C++ issues} | |
419 | ||
420 | The following documents some miscellaneous C++ issues. | |
421 | ||
422 | \subsection{Templates} | |
423 | ||
424 | wxWindows does not use templates since it is a notoriously unportable feature. | |
425 | ||
426 | \subsection{RTTI} | |
427 | ||
428 | wxWindows does not use run-time type information since wxWindows provides | |
429 | its own run-time type information system, implemented using macros. | |
430 | ||
431 | \subsection{Type of NULL} | |
432 | ||
433 | Some compilers (e.g. the native IRIX cc) define NULL to be 0L so that | |
434 | no conversion to pointers is allowed. Because of that, all these | |
435 | occurrences of NULL in the GTK port use an explicit conversion such | |
436 | as | |
437 | ||
438 | {\small | |
439 | \begin{verbatim} | |
440 | wxWindow *my_window = (wxWindow*) NULL; | |
441 | \end{verbatim} | |
442 | } | |
443 | ||
444 | It is recommended to adhere to this in all code using wxWindows as | |
445 | this make the code (a bit) more portable. | |
446 | ||
447 | \subsection{Precompiled headers} | |
448 | ||
449 | Some compilers, such as Borland C++ and Microsoft C++, support | |
450 | precompiled headers. This can save a great deal of compiling time. The | |
451 | recommended approach is to precompile {\tt "wx.h"}, using this | |
452 | precompiled header for compiling both wxWindows itself and any | |
453 | wxWindows applications. For Windows compilers, two dummy source files | |
454 | are provided (one for normal applications and one for creating DLLs) | |
455 | to allow initial creation of the precompiled header. | |
456 | ||
457 | However, there are several downsides to using precompiled headers. One | |
458 | is that to take advantage of the facility, you often need to include | |
459 | more header files than would normally be the case. This means that | |
460 | changing a header file will cause more recompilations (in the case of | |
461 | wxWindows, everything needs to be recompiled since everything includes {\tt "wx.h"}!) | |
462 | ||
463 | A related problem is that for compilers that don't have precompiled | |
464 | headers, including a lot of header files slows down compilation | |
465 | considerably. For this reason, you will find (in the common | |
466 | X and Windows parts of the library) conditional | |
467 | compilation that under Unix, includes a minimal set of headers; | |
468 | and when using Visual C++, includes {\tt wx.h}. This should help provide | |
469 | the optimal compilation for each compiler, although it is | |
470 | biased towards the precompiled headers facility available | |
471 | in Microsoft C++. | |
472 | ||
473 | \section{File handling} | |
474 | ||
475 | When building an application which may be used under different | |
476 | environments, one difficulty is coping with documents which may be | |
477 | moved to different directories on other machines. Saving a file which | |
478 | has pointers to full pathnames is going to be inherently unportable. One | |
479 | approach is to store filenames on their own, with no directory | |
480 | information. The application searches through a number of locally | |
481 | defined directories to find the file. To support this, the class {\bf | |
482 | wxPathList} makes adding directories and searching for files easy, and | |
483 | the global function {\bf wxFileNameFromPath} allows the application to | |
484 | strip off the filename from the path if the filename must be stored. | |
485 | This has undesirable ramifications for people who have documents of the | |
486 | same name in different directories. | |
487 | ||
488 | As regards the limitations of DOS 8+3 single-case filenames versus | |
489 | unrestricted Unix filenames, the best solution is to use DOS filenames | |
490 | for your application, and also for document filenames {\it if} the user | |
491 | is likely to be switching platforms regularly. Obviously this latter | |
492 | choice is up to the application user to decide. Some programs (such as | |
493 | YACC and LEX) generate filenames incompatible with DOS; the best | |
494 | solution here is to have your Unix makefile rename the generated files | |
495 | to something more compatible before transferring the source to DOS. | |
496 | Transferring DOS files to Unix is no problem, of course, apart from EOL | |
497 | conversion for which there should be a utility available (such as | |
498 | dos2unix). | |
499 | ||
500 | See also the File Functions section of the reference manual for | |
501 | descriptions of miscellaneous file handling functions. | |
502 | ||
503 | \chapter{Utilities and libraries supplied with wxWindows}\label{utilities} | |
504 | \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% | |
505 | \setfooter{\thepage}{}{}{}{}{\thepage}% | |
506 | ||
507 | In addition to the core wxWindows library, a number of further | |
508 | libraries and utilities are supplied with each distribution. | |
509 | ||
510 | Some are under the 'contrib' hierarchy which mirrors the | |
511 | structure of the main wxWindows hierarchy. See also the 'utils' | |
512 | hierarchy. The first place to look for documentation about | |
513 | these tools and libraries is under the wxWindows 'docs' hierarchy, | |
514 | for example \tt{docs/htmlhelp/fl.chm}. | |
515 | ||
516 | For other user-contributed packages, please see the Contributions page | |
517 | on the \urlref{wxWindows Web site}{http://www.wxwindows.org}. | |
518 | ||
519 | \begin{description}\itemsep=0pt | |
520 | \item[{\bf Helpview}] | |
521 | Helpview is a program for displaying wxWindows HTML | |
522 | Help files. In many cases, you may wish to use the wxWindows HTML | |
523 | Help classes from within your application, but this provides a | |
524 | handy stand-alone viewer. See \helpref{wxHTML Notes}{wxhtml} for more details. | |
525 | You can find it in \tt{samples/html/helpview}. | |
526 | ||
527 | \item[{\bf Tex2RTF}] | |
528 | Supplied with wxWindows is a utility called Tex2RTF for converting\rtfsp | |
529 | \LaTeX\ manuals HTML, MS HTML Help, wxHTML Help, RTF, and Windows | |
530 | Help RTF formats. Tex2RTF is used for the wxWindows manuals and can be used independently | |
531 | by authors wishing to create on-line and printed manuals from the same\rtfsp | |
532 | \LaTeX\ source. Please see the separate documentation for Tex2RTF. | |
533 | You can find it under \tt{utils/tex2rtf}. | |
534 | ||
535 | \item[{\bf Helpgen}] | |
536 | Helpgen takes C++ header files and generates a Tex2RTF-compatible | |
537 | documentation file for each class it finds, using comments as appropriate. | |
538 | This is a good way to start a reference for a set of classes. | |
539 | ||
540 | \item[{\bf Dialog Editor}] | |
541 | Dialog Editor allows interactive construction of dialogs using | |
542 | absolute positioning, producing WXR output files. This tool is generally deprecated | |
543 | in favour of sizer-based tools. You can find Dialog Editor | |
544 | in \tt{utils/dialoged}. | |
545 | ||
546 | \item[{\bf XRC resource system}] | |
547 | This is the sizer-aware replacement for the WXR resource system, and uses | |
548 | XML-based resource specifications that can be generated by tools | |
549 | such as \urlref{wxDesigner}{http://www.roebling.de} and XRC's own wxrcedit. | |
550 | You can find this in \tt{contrib/src/xrc}, \tt{contrib/include/wx/xrc}, \tt{contrib/samples/xrc}, and \tt{contrib/utils/wxrcedit}. | |
551 | For more information, see the \helpref{XML-based resource system overview}{xrcoverview}. | |
552 | ||
553 | \item[{\bf Object Graphics Library}] | |
554 | OGL defines an API for applications that need to display objects connected by lines. | |
555 | The objects can be moved around and interacted with. | |
556 | You can find this in \tt{contrib/src/ogl}, \tt{contrib/include/wx/ogl}, and \tt{contrib/samples/ogl}. | |
557 | ||
558 | \item[{\bf Frame Layout library}] | |
559 | FL provides sophisticated pane dragging and docking facilities. | |
560 | You can find this in \tt{contrib/src/fl}, \tt{contrib/include/wx/fl}, and \tt{contrib/samples/fl}. | |
561 | ||
562 | \item[{\bf Gizmos library}] | |
563 | Gizmos is a collection of useful widgets and other classes. Classes include wxLEDNumberCtrl, | |
564 | wxEditableListBox, wxMultiCellCanvas. | |
565 | You can find this in \tt{contrib/src/fl}, \tt{contrib/include/wx/fl}, and \tt{contrib/samples/fl}. | |
566 | ||
567 | \item[{\bf Net library}] | |
568 | Net is a collection of very simple mail and web related classes. Currently | |
569 | there is only wxEmail, which makes it easy to send email messages via MAPI on Windows or sendmail on Unix. | |
570 | You can find this in \tt{contrib/src/net} and \tt{contrib/include/wx/net}. | |
571 | ||
572 | \item[{\bf Animate library}] | |
573 | Animate allows you to load animated GIFs and play them on a window. The library can be extended | |
574 | to use other animation formats. | |
575 | You can find this in \tt{contrib/src/animate}, \tt{contrib/include/wx/animate}, and \tt{contrib/samples/animate}. | |
576 | ||
577 | \item[{\bf Canvas library}] | |
578 | Canvas supports high-level, double-buffered drawing operations with transformations. | |
579 | You can find this in \tt{contrib/src/canvas}, \tt{contrib/include/wx/canvas}, and \tt{contrib/samples/canvas}. | |
580 | ||
581 | \item[{\bf MMedia library}] | |
582 | Mmedia supports a variety of multimedia functionality. The status of this library is currently unclear. | |
583 | You can find this in \tt{contrib/src/mmedia}, \tt{contrib/include/wx/mmedia}, and \tt{contrib/samples/mmedia}. | |
584 | ||
585 | \item[{\bf Styled Text Control library}] | |
586 | STC is a wrapper around Scintilla, a syntax-highlighting text editor. | |
587 | You can find this in \tt{contrib/src/stc}, \tt{contrib/include/wx/stc}, and \tt{contrib/samples/stc}. | |
588 | ||
589 | \item[{\bf Plot}] | |
590 | Plot is a simple curve plotting library. | |
591 | You can find this in \tt{contrib/src/plot}, \tt{contrib/include/wx/plot}, and \tt{contrib/samples/plot}. | |
592 | \end{description} | |
593 | ||
594 | \chapter{Programming strategies}\label{strategies} | |
595 | \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% | |
596 | \setfooter{\thepage}{}{}{}{}{\thepage}% | |
597 | ||
598 | This chapter is intended to list strategies that may be useful when | |
599 | writing and debugging wxWindows programs. If you have any good tips, | |
600 | please submit them for inclusion here. | |
601 | ||
602 | \section{Strategies for reducing programming errors} | |
603 | ||
604 | \subsection{Use ASSERT} | |
605 | ||
606 | Although I haven't done this myself within wxWindows, it is good | |
607 | practice to use ASSERT statements liberally, that check for conditions that | |
608 | should or should not hold, and print out appropriate error messages. | |
609 | These can be compiled out of a non-debugging version of wxWindows | |
610 | and your application. Using ASSERT is an example of `defensive programming': | |
611 | it can alert you to problems later on. | |
612 | ||
613 | \subsection{Use wxString in preference to character arrays} | |
614 | ||
615 | Using wxString can be much safer and more convenient than using char *. | |
616 | Again, I haven't practiced what I'm preaching, but I'm now trying to use | |
617 | wxString wherever possible. You can reduce the possibility of memory | |
618 | leaks substantially, and it is much more convenient to use the overloaded | |
619 | operators than functions such as strcmp. wxString won't add a significant | |
620 | overhead to your program; the overhead is compensated for by easier | |
621 | manipulation (which means less code). | |
622 | ||
623 | The same goes for other data types: use classes wherever possible. | |
624 | ||
625 | \section{Strategies for portability} | |
626 | ||
627 | \subsection{Use relative positioning or constraints} | |
628 | ||
629 | Don't use absolute panel item positioning if you can avoid it. Different GUIs have | |
630 | very differently sized panel items. Consider using the constraint system, although this | |
631 | can be complex to program. | |
632 | ||
633 | Alternatively, you could use alternative .wrc (wxWindows resource files) on different | |
634 | platforms, with slightly different dimensions in each. Or space your panel items out | |
635 | to avoid problems. | |
636 | ||
637 | \subsection{Use wxWindows resource files} | |
638 | ||
639 | Use .wrc (wxWindows resource files) where possible, because they can be easily changed | |
640 | independently of source code. Bitmap resources can be set up to load different | |
641 | kinds of bitmap depending on platform (see the section on resource files). | |
642 | ||
643 | \section{Strategies for debugging}\label{debugstrategies} | |
644 | ||
645 | \subsection{Positive thinking} | |
646 | ||
647 | It is common to blow up the problem in one's imagination, so that it seems to threaten | |
648 | weeks, months or even years of work. The problem you face may seem insurmountable: | |
649 | but almost never is. Once you have been programming for some time, you will be able | |
650 | to remember similar incidents that threw you into the depths of despair. But | |
651 | remember, you always solved the problem, somehow! | |
652 | ||
653 | Perseverance is often the key, even though a seemingly trivial problem | |
654 | can take an apparently inordinate amount of time to solve. In the end, | |
655 | you will probably wonder why you worried so much. That's not to say it | |
656 | isn't painful at the time. Try not to worry -- there are many more important | |
657 | things in life. | |
658 | ||
659 | \subsection{Simplify the problem} | |
660 | ||
661 | Reduce the code exhibiting the problem to the smallest program possible | |
662 | that exhibits the problem. If it is not possible to reduce a large and | |
663 | complex program to a very small program, then try to ensure your code | |
664 | doesn't hide the problem (you may have attempted to minimize the problem | |
665 | in some way: but now you want to expose it). | |
666 | ||
667 | With luck, you can add a small amount of code that causes the program | |
668 | to go from functioning to non-functioning state. This should give a clue | |
669 | to the problem. In some cases though, such as memory leaks or wrong | |
670 | deallocation, this can still give totally spurious results! | |
671 | ||
672 | \subsection{Use a debugger} | |
673 | ||
674 | This sounds like facetious advice, but it is surprising how often people | |
675 | don't use a debugger. Often it is an overhead to install or learn how to | |
676 | use a debugger, but it really is essential for anything but the most | |
677 | trivial programs. | |
678 | ||
679 | \subsection{Use logging functions} | |
680 | ||
681 | There is a variety of logging functions that you can use in your program: | |
682 | see \helpref{Logging functions}{logfunctions}. | |
683 | ||
684 | Using tracing statements may be more convenient than using the debugger | |
685 | in some circumstances (such as when your debugger doesn't support a lot | |
686 | of debugging code, or you wish to print a bunch of variables). | |
687 | ||
688 | \subsection{Use the wxWindows debugging facilities} | |
689 | ||
690 | You can use wxDebugContext to check for | |
691 | memory leaks and corrupt memory: in fact in debugging mode, wxWindows will | |
692 | automatically check for memory leaks at the end of the program if wxWindows is suitably | |
693 | configured. Depending on the operating system and compiler, more or less | |
694 | specific information about the problem will be logged. | |
695 | ||
696 | You should also use \helpref{debug macros}{debugmacros} as part of a `defensive programming' strategy, | |
697 | scattering wxASSERTs liberally to test for problems in your code as early as possible. Forward thinking | |
698 | will save a surprising amount of time in the long run. | |
699 | ||
700 | See the \helpref{debugging overview}{debuggingoverview} for further information. | |
701 | ||
702 | \subsection{Check Windows debug messages} | |
703 | ||
704 | Under Windows, it is worth running your program with | |
705 | \urlref{DbgView}{http://www.sysinternals.com} running or | |
706 | some other program that shows Windows-generated debug messages. It is | |
707 | possible it will show invalid handles being used. You may have fun seeing | |
708 | what commercial programs cause these normally hidden errors! Microsoft | |
709 | recommend using the debugging version of Windows, which shows up even | |
710 | more problems. However, I doubt it is worth the hassle for most | |
711 | applications. wxWindows is designed to minimize the possibility of such | |
712 | errors, but they can still happen occasionally, slipping through unnoticed | |
713 | because they are not severe enough to cause a crash. | |
714 | ||
715 | \subsection{Genetic mutation} | |
716 | ||
717 | If we had sophisticated genetic algorithm tools that could be applied | |
718 | to programming, we could use them. Until then, a common -- if rather irrational -- | |
719 | technique is to just make arbitrary changes to the code until something | |
720 | different happens. You may have an intuition why a change will make a difference; | |
721 | otherwise, just try altering the order of code, comment lines out, anything | |
722 | to get over an impasse. Obviously, this is usually a last resort. | |
723 |