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