]>
Commit | Line | Data |
---|---|---|
a660d684 KB |
1 | \chapter{Introduction}\label{introduction} |
2 | \pagenumbering{arabic}% | |
3 | \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% | |
4 | \setfooter{\thepage}{}{}{}{}{\thepage}% | |
5 | ||
569ef72a | 6 | \section{What is wxWidgets?}\label{whatis} |
a660d684 | 7 | |
fc2171bd | 8 | wxWidgets is a C++ framework providing GUI (Graphical User |
121640d5 VZ |
9 | Interface) and other facilities on more than one platform. Version 2 and higher |
10 | currently support all desktop versions of MS Windows, Unix with GTK+ 1.x or 2.x, | |
11 | Unix with Motif, Unix with just X11, Unix with DirectFB, Mac OS X, OS/2. | |
a660d684 | 12 | |
fc2171bd | 13 | wxWidgets was originally developed at the Artificial Intelligence |
fa482912 | 14 | Applications Institute, University of Edinburgh, for internal use, |
bd330a69 | 15 | and was first made publicly available in 1992. |
fa482912 | 16 | Version 2 is a vastly improved version written and maintained by |
bd330a69 | 17 | Julian Smart, Robert Roebling, Vadim Zeitlin, Vaclav Slavik and many others. |
a660d684 | 18 | |
bd330a69 | 19 | This manual contains a class reference and topic overviews. |
fc2171bd | 20 | For a selection of wxWidgets tutorials, please see the documentation page on the \urlref{wxWidgets web site}{http://www.wxwidgets.org}. |
a660d684 KB |
21 | |
22 | Please note that in the following, ``MS Windows" often refers to all | |
121640d5 | 23 | platforms related to Microsoft Windows, including 32-bit and 64-bit |
a660d684 KB |
24 | variants, unless otherwise stated. All trademarks are acknowledged. |
25 | ||
569ef72a | 26 | \section{Why another cross-platform development tool?}\label{why} |
a660d684 | 27 | |
fc2171bd | 28 | wxWidgets was developed to provide a cheap and flexible way to maximize |
a660d684 | 29 | investment in GUI application development. While a number of commercial |
8a2c6ef8 | 30 | class libraries already existed for cross-platform development, |
a660d684 KB |
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 | ||
fc2171bd | 40 | Since wxWidgets was started, several other free or almost-free |
bd330a69 JS |
41 | GUI frameworks have emerged. However, none has the range of |
42 | features, flexibility, documentation and the well-established | |
fc2171bd | 43 | development team that wxWidgets has. |
bd330a69 | 44 | |
fc2171bd | 45 | As open source software, wxWidgets has benefited from comments, |
bd330a69 | 46 | ideas, bug fixes, enhancements and the sheer enthusiasm of |
fc2171bd | 47 | users. This gives wxWidgets a certain advantage over its |
bd330a69 JS |
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 | |
fc2171bd | 64 | it addresses the wrong platform or audience. wxWidgets helps to |
bd330a69 | 65 | insulate the programmer from these winds of change. Although |
fc2171bd | 66 | wxWidgets may not be suitable for every application (such as an |
bd330a69 JS |
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 | |
fc2171bd | 73 | worthwhile to use wxWidgets even if they are developing on only |
bd330a69 | 74 | one platform. |
a660d684 | 75 | |
fc2171bd | 76 | It is impossible to sum up the functionality of wxWidgets in a few paragraphs, but |
a660d684 KB |
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. | |
8a2c6ef8 | 82 | \item Available on a variety of popular platforms. |
ccaaf5b0 | 83 | \item Works with almost all popular C++ compilers and Python. |
fa482912 JS |
84 | \item Over 50 example programs. |
85 | \item Over 1000 pages of printable and on-line documentation. | |
8a2c6ef8 JS |
86 | \item Includes Tex2RTF, to allow you to produce your own documentation |
87 | in Windows Help, HTML and Word RTF formats. | |
a660d684 | 88 | \item Simple-to-use, object-oriented API. |
8a2c6ef8 JS |
89 | \item Flexible event system. |
90 | \item Graphics calls include lines, rounded rectangles, splines, polylines, etc. | |
f6bcfd97 | 91 | \item Constraint-based and sizer-based layouts. |
a660d684 | 92 | \item Print/preview and document/view architectures. |
8a2c6ef8 | 93 | \item Toolbar, notebook, tree control, advanced list control classes. |
ccaaf5b0 | 94 | \item PostScript generation under Unix, normal MS Windows printing on the PC. |
62448488 JS |
95 | \item MDI (Multiple Document Interface) support. |
96 | \item Can be used to create DLLs under Windows, dynamic libraries on Unix. | |
a660d684 KB |
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. | |
62448488 | 100 | \item An API for invoking help from applications. |
fa482912 | 101 | \item Ready-to-use HTML window (supporting a subset of HTML). |
8a2c6ef8 | 102 | \item Network support via a family of socket and protocol classes. |
f6bcfd97 | 103 | \item Support for platform independent image processing. |
ccaaf5b0 | 104 | \item Built-in support for many file formats (BMP, PNG, JPEG, GIF, XPM, PNM, PCX). |
a660d684 KB |
105 | \end{itemize} |
106 | ||
fc2171bd | 107 | \section{wxWidgets requirements}\label{requirements} |
a660d684 | 108 | |
fc2171bd | 109 | To make use of wxWidgets, you currently need one of the following setups. |
a660d684 | 110 | |
1d0b7ed3 | 111 | (a) MS-Windows: |
a660d684 KB |
112 | |
113 | \begin{enumerate}\itemsep=0pt | |
13cf3832 WS |
114 | \item A 32-bit or 64-bit PC running MS Windows. |
115 | \item A Windows compiler: MS Visual C++ (embedded Visual C++ for wxWinCE | |
116 | port), Borland C++, Watcom C++, Cygwin, MinGW, Metrowerks CodeWarrior, | |
117 | Digital Mars C++. See {\tt install.txt} for details about compiler | |
118 | version supported. | |
a660d684 KB |
119 | \end{enumerate} |
120 | ||
bd0df01f | 121 | (b) Unix: |
a660d684 KB |
122 | |
123 | \begin{enumerate}\itemsep=0pt | |
391e70ae VZ |
124 | \item Almost any C++ compiler, including GNU C++ and many Unix vendors |
125 | compilers such as Sun CC, HP-UX aCC or SGI mipsPro. | |
126 | \item Almost any Unix workstation, and one of: GTK+ 2.4 or higher (GTK+ 1.2.10 | |
127 | may still be supported but wxGTK1 port is not maintained any longer and lacks | |
128 | many features of wxGTK2), Motif 1.2 or higher or Lesstif. If using the wxX11 | |
129 | port, no such widget set is required. | |
a660d684 KB |
130 | \end{enumerate} |
131 | ||
1d0b7ed3 GD |
132 | (c) Mac OS/Mac OS X: |
133 | ||
134 | \begin{enumerate}\itemsep=0pt | |
391e70ae VZ |
135 | \item A PowerPC or Intel Mac running Mac OS X 10.3 or higher |
136 | \item The Apple Developer Tools (eg. GNU C++) or MetroWerks CodeWarrior (not | |
137 | actively supported) | |
1d0b7ed3 GD |
138 | \end{enumerate} |
139 | ||
391e70ae VZ |
140 | Under all platforms it's recommended to have large amounts of free hard disk |
141 | space. The exact amount needed depends on the port, compiler and build | |
142 | configurations but to give an example, a debug build of the library may take up | |
143 | to 500MB. | |
144 | ||
569ef72a | 145 | \section{Availability and location of wxWidgets}\label{where} |
a660d684 | 146 | |
fc2171bd JS |
147 | \winhelponly{wxWidgets is available by anonymous FTP and World Wide Web |
148 | from ftp://biolpc22.york.ac.uk/pub and/or http://www.wxwidgets.org.} | |
149 | \winhelpignore{wxWidgets is available by anonymous FTP and World Wide Web | |
f44b23b6 | 150 | from \urlref{ftp://biolpc22.york.ac.uk/pub}{ftp://biolpc22.york.ac.uk/pub} |
fc2171bd | 151 | and/or \urlref{http://www.wxwidgets.org}{http://www.wxwidgets.org}.} |
a660d684 | 152 | |
d958c9bd | 153 | You can also buy a CD-ROM using the form on the Web site. |
448af9a4 | 154 | |
569ef72a | 155 | \section{Acknowledgements}\label{acknowledgements} |
a660d684 | 156 | |
bd0df01f | 157 | Thanks are due to AIAI for being willing to release the original version of |
fc2171bd | 158 | wxWidgets into the public domain, and to our patient partners. |
bd0df01f | 159 | |
fc2171bd | 160 | We would particularly like to thank the following for their contributions to wxWidgets, and the many others who have been involved in |
bd0df01f JS |
161 | the project over the years. Apologies for any unintentional omissions from this list. |
162 | ||
ecd7e67e WS |
163 | Yiorgos Adamopoulos, Jamshid Afshar, Alejandro Aguilar-Sierra, AIAI, |
164 | Patrick Albert, Karsten Ballueder, Mattia Barbon, Michael Bedward, | |
165 | Kai Bendorf, Yura Bidus, Keith Gary Boyce, Chris Breeze, Pete Britton, | |
6652e1a7 | 166 | Ian Brown, C. Buckley, Marco Cavallini, Dmitri Chubraev, Robin Corbet, Cecil Coupe, |
ecd7e67e WS |
167 | Stefan Csomor, Andrew Davison, Gilles Depeyrot, Neil Dudman, Robin Dunn, |
168 | Hermann Dunkel, Jos van Eijndhoven, Chris Elliott, David Elliott, Tom Felici, | |
169 | Thomas Fettig, Matthew Flatt, Pasquale Foggia, Josep Fortiana, Todd Fries, | |
170 | Dominic Gallagher, Guillermo Rodriguez Garcia, Wolfram Gloger, Norbert Grotz, | |
171 | Stefan Gunter, Bill Hale, Patrick Halke, Stefan Hammes, Guillaume Helle, | |
6421f57a | 172 | Harco de Hilster, Kevin Hock, Cord Hockemeyer, Markus Holzem, Olaf Klein, Leif Jensen, |
ecd7e67e WS |
173 | Bart Jourquin, Guilhem Lavaux, Ron Lee, Jan Lessner, Nicholas Liebmann, |
174 | Torsten Liermann, Per Lindqvist, Thomas Runge, Tatu M\"{a}nnist\"{o}, | |
6421f57a | 175 | Scott Maxwell, Thomas Myers, Oliver Niedung, Stefan Neis, Ryan Norton, Hernan Otero, |
ecd7e67e WS |
176 | Ian Perrigo, Timothy Peters, Giordano Pezzoli, Harri Pasanen, Thomaso Paoletti, |
177 | Garrett Potts, Marcel Rasche, Robert Roebling, Dino Scaringella, | |
178 | Jobst Schmalenbach, Arthur Seaton, Paul Shirley, Wlodzimierz `ABX' Skiba, | |
179 | Vaclav Slavik, Julian Smart, Stein Somers, Petr Smilauer, Neil Smith, | |
180 | Kari Syst\"{a}, George Tasker, Arthur Tetzlaff-Deas, Jonathan Tonberg, | |
181 | Jyrki Tuomi, Janos Vegh, Andrea Venturoli, David Webster, Otto Wyss, | |
182 | Vadim Zeitlin, Xiaokun Zhu, Edward Zimmermann. | |
a660d684 KB |
183 | |
184 | `Graphplace', the basis for the wxGraphLayout library, is copyright Dr. Jos | |
185 | T.J. van Eijndhoven of Eindhoven University of Technology. The code has | |
186 | been used in wxGraphLayout with his permission. | |
187 | ||
bd0df01f | 188 | We also acknowledge the author of XFIG, the excellent Unix drawing tool, |
a660d684 KB |
189 | from the source of which we have borrowed some spline drawing code. |
190 | His copyright is included below. | |
191 | ||
192 | {\it XFig2.1 is copyright (c) 1985 by Supoj Sutanthavibul. Permission to | |
193 | use, copy, modify, distribute, and sell this software and its | |
194 | documentation for any purpose is hereby granted without fee, provided | |
195 | that the above copyright notice appear in all copies and that both that | |
196 | copyright notice and this permission notice appear in supporting | |
197 | documentation, and that the name of M.I.T. not be used in advertising or | |
198 | publicity pertaining to distribution of the software without specific, | |
199 | written prior permission. M.I.T. makes no representations about the | |
200 | suitability of this software for any purpose. It is provided ``as is'' | |
201 | without express or implied warranty.} | |
202 | ||
fc2171bd | 203 | \chapter{Multi-platform development with wxWidgets}\label{multiplat} |
a660d684 KB |
204 | \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% |
205 | \setfooter{\thepage}{}{}{}{}{\thepage}% | |
206 | ||
fc2171bd | 207 | This chapter describes the practical details of using wxWidgets. Please |
a660d684 KB |
208 | see the file install.txt for up-to-date installation instructions, and |
209 | changes.txt for differences between versions. | |
210 | ||
569ef72a | 211 | \section{Include files}\label{includefiles} |
a660d684 | 212 | |
bd0df01f | 213 | The main include file is {\tt "wx/wx.h"}; this includes the most commonly |
fc2171bd | 214 | used modules of wxWidgets. |
a660d684 KB |
215 | |
216 | To save on compilation time, include only those header files relevant to the | |
217 | source file. If you are using precompiled headers, you should include | |
218 | the following section before any other includes: | |
219 | ||
220 | \begin{verbatim} | |
221 | // For compilers that support precompilation, includes "wx.h". | |
bd0df01f | 222 | #include <wx/wxprec.h> |
a660d684 KB |
223 | |
224 | #ifdef __BORLANDC__ | |
225 | #pragma hdrstop | |
226 | #endif | |
227 | ||
228 | #ifndef WX_PRECOMP | |
bd0df01f JS |
229 | // Include your minimal set of headers here, or wx.h |
230 | #include <wx/wx.h> | |
a660d684 KB |
231 | #endif |
232 | ||
233 | ... now your other include files ... | |
234 | \end{verbatim} | |
235 | ||
bd0df01f | 236 | The file {\tt "wx/wxprec.h"} includes {\tt "wx/wx.h"}. Although this incantation |
a660d684 | 237 | may seem quirky, it is in fact the end result of a lot of experimentation, |
13cf3832 | 238 | and several Windows compilers to use precompilation which is largely automatic for |
ff782aec WS |
239 | compilers with necessary support. Currently it is used for Visual C++ (including |
240 | embedded Visual C++), Borland C++, Open Watcom C++, Digital Mars C++ | |
241 | and newer versions of GCC. | |
90c7e645 MR |
242 | Some compilers might need extra work from the application developer to set the |
243 | build environment up as necessary for the support. | |
a660d684 | 244 | |
569ef72a | 245 | \section{Libraries}\label{libraries} |
a660d684 | 246 | |
fc2171bd JS |
247 | Most ports of wxWidgets can create either a static library or a shared |
248 | library. wxWidgets can also be built in multilib and monolithic variants. | |
0497e172 JS |
249 | See the \helpref{libraries list}{librarieslist} for more |
250 | information on these. | |
a660d684 | 251 | |
569ef72a | 252 | \section{Configuration}\label{configuration} |
a660d684 | 253 | |
fc2171bd | 254 | When using project files and makefiles directly to build wxWidgets, |
0497e172 | 255 | options are configurable in the file |
ccaaf5b0 RR |
256 | \rtfsp{\tt "wx/XXX/setup.h"} where XXX is the required platform (such as msw, motif, gtk, mac). Some |
257 | settings are a matter of taste, some help with platform-specific problems, and | |
62448488 JS |
258 | others can be set to minimize the size of the library. Please see the setup.h file |
259 | and {\tt install.txt} files for details on configuration. | |
a660d684 | 260 | |
fc2171bd | 261 | When using the 'configure' script to configure wxWidgets (on Unix and other platforms where |
0497e172 JS |
262 | configure is available), the corresponding setup.h files are generated automatically |
263 | along with suitable makefiles. When using the RPM packages | |
fc2171bd | 264 | for installing wxWidgets on Linux, a correct setup.h is shipped in the package and |
ccaaf5b0 RR |
265 | this must not be changed. |
266 | ||
569ef72a | 267 | \section{Makefiles}\label{makefiles} |
a660d684 | 268 | |
fc2171bd | 269 | On Microsoft Windows, wxWidgets has a different set of makefiles for each |
0497e172 JS |
270 | compiler, because each compiler's 'make' tool is slightly different. |
271 | Popular Windows compilers that we cater for, and the corresponding makefile | |
272 | extensions, include: Microsoft Visual C++ (.vc), Borland C++ (.bcc), | |
273 | OpenWatcom C++ (.wat) and MinGW/Cygwin (.gcc). Makefiles are provided | |
fc2171bd | 274 | for the wxWidgets library itself, samples, demos, and utilities. |
0497e172 JS |
275 | |
276 | On Linux, Mac and OS/2, you use the 'configure' command to | |
277 | generate the necessary makefiles. You should also use this method when | |
278 | building with MinGW/Cygwin on Windows. | |
279 | ||
280 | We also provide project files for some compilers, such as | |
281 | Microsoft VC++. However, we recommend using makefiles | |
fc2171bd | 282 | to build the wxWidgets library itself, because makefiles |
0497e172 JS |
283 | can be more powerful and less manual intervention is required. |
284 | ||
285 | On Windows using a compiler other than MinGW/Cygwin, you would | |
fc2171bd | 286 | build the wxWidgets library from the build/msw directory |
0497e172 JS |
287 | which contains the relevant makefiles. |
288 | ||
289 | On Windows using MinGW/Cygwin, and on Unix, MacOS X and OS/2, you invoke | |
fc2171bd | 290 | 'configure' (found in the top-level of the wxWidgets source hierarchy), |
0497e172 JS |
291 | from within a suitable empty directory for containing makefiles, object files and |
292 | libraries. | |
293 | ||
294 | For details on using makefiles, configure, and project files, | |
295 | please see docs/xxx/install.txt in your distribution, where | |
296 | xxx is the platform of interest, such as msw, gtk, x11, mac. | |
a660d684 | 297 | |
569ef72a | 298 | \section{Windows-specific files}\label{windowsfiles} |
a660d684 | 299 | |
0db776b4 JS |
300 | wxWidgets application compilation under MS Windows requires at least one |
301 | extra file: a resource file. | |
a660d684 KB |
302 | |
303 | \subsection{Resource file}\label{resources} | |
304 | ||
305 | The least that must be defined in the Windows resource file (extension RC) | |
306 | is the following statement: | |
307 | ||
308 | \begin{verbatim} | |
0497e172 | 309 | #include "wx/msw/wx.rc" |
a660d684 KB |
310 | \end{verbatim} |
311 | ||
fc2171bd | 312 | which includes essential internal wxWidgets definitions. The resource script |
a660d684 KB |
313 | may also contain references to icons, cursors, etc., for example: |
314 | ||
315 | \begin{verbatim} | |
316 | wxicon icon wx.ico | |
317 | \end{verbatim} | |
318 | ||
319 | The icon can then be referenced by name when creating a frame icon. See | |
320 | the MS Windows SDK documentation. | |
321 | ||
322 | \normalbox{Note: include wx.rc {\it after} any ICON statements | |
323 | so programs that search your executable for icons (such | |
324 | as the Program Manager) find your application icon first.} | |
325 | ||
569ef72a | 326 | \section{Allocating and deleting wxWidgets objects}\label{allocatingobjects} |
a660d684 KB |
327 | |
328 | In general, classes derived from wxWindow must dynamically allocated | |
329 | with {\it new} and deleted with {\it delete}. If you delete a window, | |
330 | all of its children and descendants will be automatically deleted, | |
331 | so you don't need to delete these descendants explicitly. | |
332 | ||
bd0df01f | 333 | When deleting a frame or dialog, use {\bf Destroy} rather than {\bf delete} so |
fc2171bd | 334 | that the wxWidgets delayed deletion can take effect. This waits until idle time |
bd0df01f JS |
335 | (when all messages have been processed) to actually delete the window, to avoid |
336 | problems associated with the GUI sending events to deleted windows. | |
a660d684 | 337 | |
bd0df01f JS |
338 | Don't create a window on the stack, because this will interfere |
339 | with delayed deletion. | |
a660d684 KB |
340 | |
341 | If you decide to allocate a C++ array of objects (such as wxBitmap) that may | |
fc2171bd JS |
342 | be cleaned up by wxWidgets, make sure you delete the array explicitly |
343 | before wxWidgets has a chance to do so on exit, since calling {\it delete} on | |
a660d684 KB |
344 | array members will cause memory problems. |
345 | ||
346 | wxColour can be created statically: it is not automatically cleaned | |
347 | up and is unlikely to be shared between other objects; it is lightweight | |
348 | enough for copies to be made. | |
349 | ||
350 | Beware of deleting objects such as a wxPen or wxBitmap if they are still in use. | |
351 | Windows is particularly sensitive to this: so make sure you | |
bd0df01f | 352 | make calls like wxDC::SetPen(wxNullPen) or wxDC::SelectObject(wxNullBitmap) before deleting |
a660d684 KB |
353 | a drawing object that may be in use. Code that doesn't do this will probably work |
354 | fine on some platforms, and then fail under Windows. | |
355 | ||
569ef72a | 356 | \section{Architecture dependency}\label{architecturedependency} |
91b8de8d RR |
357 | |
358 | A problem which sometimes arises from writing multi-platform programs is that | |
f6bcfd97 | 359 | the basic C types are not defined the same on all platforms. This holds true |
91b8de8d RR |
360 | for both the length in bits of the standard types (such as int and long) as |
361 | well as their byte order, which might be little endian (typically | |
fc2171bd | 362 | on Intel computers) or big endian (typically on some Unix workstations). wxWidgets |
91b8de8d RR |
363 | defines types and macros that make it easy to write architecture independent |
364 | code. The types are: | |
365 | ||
366 | wxInt32, wxInt16, wxInt8, wxUint32, wxUint16 = wxWord, wxUint8 = wxByte | |
367 | ||
368 | where wxInt32 stands for a 32-bit signed integer type etc. You can also check | |
369 | which architecture the program is compiled on using the wxBYTE\_ORDER define | |
370 | which is either wxBIG\_ENDIAN or wxLITTLE\_ENDIAN (in the future maybe wxPDP\_ENDIAN | |
371 | as well). | |
372 | ||
373 | The macros handling bit-swapping with respect to the applications endianness | |
81c9effa | 374 | are described in the \helpref{Byte order macros}{byteordermacros} section. |
91b8de8d | 375 | |
569ef72a | 376 | \section{Conditional compilation}\label{conditionalcompilation} |
a660d684 | 377 | |
fc2171bd | 378 | One of the purposes of wxWidgets is to reduce the need for conditional |
a660d684 KB |
379 | compilation in source code, which can be messy and confusing to follow. |
380 | However, sometimes it is necessary to incorporate platform-specific | |
62448488 JS |
381 | features (such as metafile use under MS Windows). The symbols |
382 | listed in the file {\tt symbols.txt} may be used for this purpose, | |
383 | along with any user-supplied ones. | |
b8de493f | 384 | |
569ef72a | 385 | \section{C++ issues}\label{cpp} |
a660d684 | 386 | |
bd0df01f | 387 | The following documents some miscellaneous C++ issues. |
a660d684 | 388 | |
a203f6c0 | 389 | \subsection{Templates}\label{templates} |
a660d684 | 390 | |
fc2171bd | 391 | wxWidgets does not use templates (except for some advanced features that |
0497e172 | 392 | are switched off by default) since it is a notoriously unportable feature. |
a660d684 | 393 | |
a203f6c0 | 394 | \subsection{RTTI}\label{rtti} |
12a44087 | 395 | |
fc2171bd | 396 | wxWidgets does not use C++ run-time type information since wxWidgets provides |
12a44087 RR |
397 | its own run-time type information system, implemented using macros. |
398 | ||
a203f6c0 | 399 | \subsection{Type of NULL}\label{null} |
12a44087 RR |
400 | |
401 | Some compilers (e.g. the native IRIX cc) define NULL to be 0L so that | |
402 | no conversion to pointers is allowed. Because of that, all these | |
0497e172 | 403 | occurrences of NULL in the GTK+ port use an explicit conversion such |
12a44087 RR |
404 | as |
405 | ||
406 | {\small | |
407 | \begin{verbatim} | |
408 | wxWindow *my_window = (wxWindow*) NULL; | |
409 | \end{verbatim} | |
d2c2afc9 | 410 | }% |
12a44087 | 411 | |
fc2171bd | 412 | It is recommended to adhere to this in all code using wxWidgets as |
12a44087 RR |
413 | this make the code (a bit) more portable. |
414 | ||
a203f6c0 | 415 | \subsection{Precompiled headers}\label{precompiledheaders} |
a660d684 KB |
416 | |
417 | Some compilers, such as Borland C++ and Microsoft C++, support | |
418 | precompiled headers. This can save a great deal of compiling time. The | |
8a2c6ef8 | 419 | recommended approach is to precompile {\tt "wx.h"}, using this |
fc2171bd JS |
420 | precompiled header for compiling both wxWidgets itself and any |
421 | wxWidgets applications. For Windows compilers, two dummy source files | |
a660d684 KB |
422 | are provided (one for normal applications and one for creating DLLs) |
423 | to allow initial creation of the precompiled header. | |
424 | ||
425 | However, there are several downsides to using precompiled headers. One | |
426 | is that to take advantage of the facility, you often need to include | |
427 | more header files than would normally be the case. This means that | |
428 | changing a header file will cause more recompilations (in the case of | |
fc2171bd | 429 | wxWidgets, everything needs to be recompiled since everything includes {\tt "wx.h"}!) |
a660d684 KB |
430 | |
431 | A related problem is that for compilers that don't have precompiled | |
432 | headers, including a lot of header files slows down compilation | |
433 | considerably. For this reason, you will find (in the common | |
434 | X and Windows parts of the library) conditional | |
bd0df01f | 435 | compilation that under Unix, includes a minimal set of headers; |
a660d684 KB |
436 | and when using Visual C++, includes {\tt wx.h}. This should help provide |
437 | the optimal compilation for each compiler, although it is | |
f6bcfd97 | 438 | biased towards the precompiled headers facility available |
a660d684 KB |
439 | in Microsoft C++. |
440 | ||
569ef72a | 441 | \section{File handling}\label{filehandling} |
a660d684 KB |
442 | |
443 | When building an application which may be used under different | |
444 | environments, one difficulty is coping with documents which may be | |
445 | moved to different directories on other machines. Saving a file which | |
446 | has pointers to full pathnames is going to be inherently unportable. One | |
447 | approach is to store filenames on their own, with no directory | |
448 | information. The application searches through a number of locally | |
449 | defined directories to find the file. To support this, the class {\bf | |
450 | wxPathList} makes adding directories and searching for files easy, and | |
62448488 | 451 | the global function {\bf wxFileNameFromPath} allows the application to |
a660d684 KB |
452 | strip off the filename from the path if the filename must be stored. |
453 | This has undesirable ramifications for people who have documents of the | |
454 | same name in different directories. | |
455 | ||
456 | As regards the limitations of DOS 8+3 single-case filenames versus | |
bd0df01f | 457 | unrestricted Unix filenames, the best solution is to use DOS filenames |
a660d684 KB |
458 | for your application, and also for document filenames {\it if} the user |
459 | is likely to be switching platforms regularly. Obviously this latter | |
460 | choice is up to the application user to decide. Some programs (such as | |
461 | YACC and LEX) generate filenames incompatible with DOS; the best | |
bd0df01f | 462 | solution here is to have your Unix makefile rename the generated files |
a660d684 | 463 | to something more compatible before transferring the source to DOS. |
bd0df01f | 464 | Transferring DOS files to Unix is no problem, of course, apart from EOL |
a660d684 KB |
465 | conversion for which there should be a utility available (such as |
466 | dos2unix). | |
467 | ||
468 | See also the File Functions section of the reference manual for | |
469 | descriptions of miscellaneous file handling functions. | |
470 | ||
fc2171bd | 471 | \chapter{Utilities and libraries supplied with wxWidgets}\label{utilities} |
a660d684 KB |
472 | \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% |
473 | \setfooter{\thepage}{}{}{}{}{\thepage}% | |
474 | ||
598e55d7 VZ |
475 | In addition to the \helpref{wxWidgets libraries}{librarieslist}, some |
476 | additional utilities are supplied in the \tt{utils} hierarchy. | |
a660d684 | 477 | |
bd330a69 | 478 | For other user-contributed packages, please see the Contributions page |
fc2171bd | 479 | on the \urlref{wxWidgets Web site}{http://www.wxwidgets.org}. |
a660d684 | 480 | |
bd330a69 | 481 | \begin{description}\itemsep=0pt |
d8908b52 | 482 | \item[{\bf Helpview}] |
fc2171bd JS |
483 | Helpview is a program for displaying wxWidgets HTML |
484 | Help files. In many cases, you may wish to use the wxWidgets HTML | |
bd330a69 JS |
485 | Help classes from within your application, but this provides a |
486 | handy stand-alone viewer. See \helpref{wxHTML Notes}{wxhtml} for more details. | |
7af3ca16 | 487 | You can find it in {\tt samples/html/helpview}. |
d8908b52 | 488 | \item[{\bf Tex2RTF}] |
fc2171bd | 489 | Supplied with wxWidgets is a utility called Tex2RTF for converting\rtfsp |
bd330a69 | 490 | \LaTeX\ manuals HTML, MS HTML Help, wxHTML Help, RTF, and Windows |
fc2171bd | 491 | Help RTF formats. Tex2RTF is used for the wxWidgets manuals and can be used independently |
bd330a69 JS |
492 | by authors wishing to create on-line and printed manuals from the same\rtfsp |
493 | \LaTeX\ source. Please see the separate documentation for Tex2RTF. | |
7af3ca16 | 494 | You can find it under {\tt utils/tex2rtf}. |
d8908b52 | 495 | \item[{\bf Helpgen}] |
bd330a69 JS |
496 | Helpgen takes C++ header files and generates a Tex2RTF-compatible |
497 | documentation file for each class it finds, using comments as appropriate. | |
498 | This is a good way to start a reference for a set of classes. | |
31be2bd8 | 499 | Helpgen can be found in {\tt utils/HelpGen}. |
31be2bd8 JS |
500 | \item[{\bf Emulator}] |
501 | Xnest-based display emulator for X11-based PDA applications. On some | |
502 | systems, the Xnest window does not synchronise with the | |
503 | 'skin' window. This program can be found in {\tt utils/emulator}. | |
bd330a69 | 504 | \end{description} |
a660d684 KB |
505 | |
506 | \chapter{Programming strategies}\label{strategies} | |
507 | \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% | |
508 | \setfooter{\thepage}{}{}{}{}{\thepage}% | |
509 | ||
510 | This chapter is intended to list strategies that may be useful when | |
fc2171bd | 511 | writing and debugging wxWidgets programs. If you have any good tips, |
a660d684 KB |
512 | please submit them for inclusion here. |
513 | ||
569ef72a | 514 | \section{Strategies for reducing programming errors}\label{reducingerrors} |
a660d684 | 515 | |
a203f6c0 | 516 | \subsection{Use ASSERT}\label{useassert} |
a660d684 | 517 | |
598e55d7 VZ |
518 | It is good practice to use ASSERT statements liberally, that check for conditions |
519 | that should or should not hold, and print out appropriate error messages. | |
520 | ||
fc2171bd | 521 | These can be compiled out of a non-debugging version of wxWidgets |
a660d684 KB |
522 | and your application. Using ASSERT is an example of `defensive programming': |
523 | it can alert you to problems later on. | |
524 | ||
598e55d7 VZ |
525 | See \helpref{wxASSERT}{wxassert} for more info. |
526 | ||
a203f6c0 | 527 | \subsection{Use wxString in preference to character arrays}\label{usewxstring} |
a660d684 | 528 | |
598e55d7 VZ |
529 | Using \helpref{wxString}{wxstring} can be much safer and more convenient than using wxChar *. |
530 | ||
531 | You can reduce the possibility of memory leaks substantially, and it is much more | |
532 | convenient to use the overloaded operators than functions such as \tt{strcmp}. | |
533 | wxString won't add a significant overhead to your program; the overhead is compensated | |
534 | for by easier manipulation (which means less code). | |
a660d684 KB |
535 | |
536 | The same goes for other data types: use classes wherever possible. | |
537 | ||
569ef72a | 538 | \section{Strategies for portability}\label{portability} |
a660d684 | 539 | |
598e55d7 | 540 | \subsection{Use sizers}\label{usesizers} |
a660d684 KB |
541 | |
542 | Don't use absolute panel item positioning if you can avoid it. Different GUIs have | |
598e55d7 | 543 | very differently sized panel items. Consider using the \helpref{sizers}{sizeroverview} instead. |
a660d684 | 544 | |
a203f6c0 | 545 | \subsection{Use wxWidgets resource files}\label{useresources} |
a660d684 | 546 | |
fc2171bd | 547 | Use .xrc (wxWidgets resource files) where possible, because they can be easily changed |
598e55d7 | 548 | independently of source code. See the \helpref{XRC overview}{xrcoverview} for more info. |
a660d684 | 549 | |
6b037754 | 550 | \section{Strategies for debugging}\label{debugstrategies} |
a660d684 | 551 | |
a203f6c0 | 552 | \subsection{Positive thinking}\label{positivethinking} |
a660d684 | 553 | |
f6bcfd97 | 554 | It is common to blow up the problem in one's imagination, so that it seems to threaten |
a660d684 KB |
555 | weeks, months or even years of work. The problem you face may seem insurmountable: |
556 | but almost never is. Once you have been programming for some time, you will be able | |
557 | to remember similar incidents that threw you into the depths of despair. But | |
558 | remember, you always solved the problem, somehow! | |
559 | ||
560 | Perseverance is often the key, even though a seemingly trivial problem | |
561 | can take an apparently inordinate amount of time to solve. In the end, | |
562 | you will probably wonder why you worried so much. That's not to say it | |
563 | isn't painful at the time. Try not to worry -- there are many more important | |
564 | things in life. | |
565 | ||
a203f6c0 | 566 | \subsection{Simplify the problem}\label{simplifyproblem} |
a660d684 KB |
567 | |
568 | Reduce the code exhibiting the problem to the smallest program possible | |
569 | that exhibits the problem. If it is not possible to reduce a large and | |
570 | complex program to a very small program, then try to ensure your code | |
571 | doesn't hide the problem (you may have attempted to minimize the problem | |
572 | in some way: but now you want to expose it). | |
573 | ||
574 | With luck, you can add a small amount of code that causes the program | |
575 | to go from functioning to non-functioning state. This should give a clue | |
576 | to the problem. In some cases though, such as memory leaks or wrong | |
577 | deallocation, this can still give totally spurious results! | |
578 | ||
a203f6c0 | 579 | \subsection{Use a debugger}\label{usedebugger} |
a660d684 | 580 | |
f6bcfd97 BP |
581 | This sounds like facetious advice, but it is surprising how often people |
582 | don't use a debugger. Often it is an overhead to install or learn how to | |
a660d684 | 583 | use a debugger, but it really is essential for anything but the most |
6b037754 JS |
584 | trivial programs. |
585 | ||
a203f6c0 | 586 | \subsection{Use logging functions}\label{uselogging} |
6b037754 JS |
587 | |
588 | There is a variety of logging functions that you can use in your program: | |
589 | see \helpref{Logging functions}{logfunctions}. | |
a660d684 KB |
590 | |
591 | Using tracing statements may be more convenient than using the debugger | |
592 | in some circumstances (such as when your debugger doesn't support a lot | |
593 | of debugging code, or you wish to print a bunch of variables). | |
594 | ||
a203f6c0 | 595 | \subsection{Use the wxWidgets debugging facilities}\label{usedebuggingfacilities} |
6b037754 | 596 | |
598e55d7 | 597 | You can use \helpref{wxDebugContext}{wxdebugcontext} to check for |
fc2171bd JS |
598 | memory leaks and corrupt memory: in fact in debugging mode, wxWidgets will |
599 | automatically check for memory leaks at the end of the program if wxWidgets is suitably | |
6b037754 JS |
600 | configured. Depending on the operating system and compiler, more or less |
601 | specific information about the problem will be logged. | |
a660d684 | 602 | |
6b037754 JS |
603 | You should also use \helpref{debug macros}{debugmacros} as part of a `defensive programming' strategy, |
604 | scattering wxASSERTs liberally to test for problems in your code as early as possible. Forward thinking | |
605 | will save a surprising amount of time in the long run. | |
606 | ||
607 | See the \helpref{debugging overview}{debuggingoverview} for further information. | |
a660d684 | 608 |