1 \chapter{Introduction
}\label{introduction
}
2 \pagenumbering{arabic
}%
3 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
4 \setfooter{\thepage}{}{}{}{}{\thepage}%
6 \section{What is wxWindows?
}
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
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.
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.
}
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.
29 \section{Why another cross-platform development tool?
}
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:
36 \begin{enumerate
}\itemsep=
0pt
38 \item source availability;
39 \item simplicity of programming;
40 \item support for a wide range of compilers.
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.
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.
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.
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.
75 It is impossible to sum up the functionality of wxWindows in a few paragraphs, but
76 here are some of the benefits:
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.
83 \item Several 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 layout option.
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
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 Dialog Editor for building dialogs.
102 \item Network support via a family of socket and protocol classes.
105 \section{Changes from version
1.xx
}\label{versionchanges
}
107 These are a few of the major differences between versions
1.xx and
2.0.
111 \begin{itemize
}\itemsep=
0pt
112 \item XView is no longer supported;
113 \item all controls (panel items) no longer have labels attached to them;
114 \item wxForm has been removed;
115 \item wxCanvasDC, wxPanelDC removed (replaced by wxClientDC, wxWindowDC, wxPaintDC which
116 can be used for any window);
117 \item wxMultiText, wxTextWindow, wxText removed and replaced by wxTextCtrl;
118 \item classes no longer divided into generic and platform-specific parts, for efficiency.
121 Additions and changes:
123 \begin{itemize
}\itemsep=
0pt
124 \item class hierarchy changed, and restrictions about subwindow nesting lifted;
125 \item header files reorganised to conform to normal C++ standards;
126 \item classes less dependent on each another, to reduce executable size;
127 \item wxString used instead of char* wherever possible;
128 \item the number of separate but mandatory utilities reduced;
129 \item the event system has been overhauled, with
130 virtual functions and callbacks being replaced with MFC-like event tables;
131 \item new controls, such as wxTreeCtrl, wxListCtrl, wxSpinButton;
132 \item less inconsistency about what events can be handled, so for example
133 mouse clicks or key presses on controls can now be intercepted;
134 \item the status bar is now a separate class, wxStatusBar, and is
135 implemented in generic wxWindows code;
136 \item some renaming of controls for greater consistency;
137 \item wxBitmap has the notion of bitmap handlers to allow for extension to new formats
139 \item new dialogs: wxPageSetupDialog, wxFileDialog, wxDirDialog,
140 wxMessageDialog, wxSingleChoiceDialog, wxTextEntryDialog;
141 \item GDI objects are reference-counted and are now passed to most functions
142 by reference, making memory management far easier;
143 \item wxSystemSettings class allows querying for various system-wide properties
144 such as dialog font, colours, user interface element sizes, and so on;
145 \item better platform look and feel conformance;
146 \item toolbar functionality now separated out into a family of classes with the
148 \item device contexts are no longer accessed using wxWindow::GetDC - they are created
149 temporarily with the window as an argument;
150 \item events from sliders and scrollbars can be handled more flexibly;
151 \item the handling of window close events has been changed in line with the new
153 \item the concept of
{\it validator
} has been added to allow much easier coding of
154 the relationship between controls and application data;
155 \item the documentation has been revised, with more cross-referencing.
158 Platform-specific changes:
160 \begin{itemize
}\itemsep=
0pt
161 \item The Windows header file (windows.h) is no longer included by wxWindows headers;
162 \item wx.dll supported under Visual C++;
163 \item the full range of Windows
95 window decorations are supported, such as modal frame
165 \item MDI classes brought out of wxFrame into separate classes, and made more flexible.
168 \section{wxWindows requirements
}\label{requirements
}
170 To make use of wxWindows, you currently need one or both of the
175 \begin{enumerate
}\itemsep=
0pt
176 \item A
486 or higher PC running MS Windows.
177 \item A Windows compiler: most are supported, but please see
{\tt install.txt
} for
178 details. Supported compilers include Microsoft Visual C++
4.0 or higher, Borland C++, Cygwin,
179 Metrowerks CodeWarrior.
180 \item At least
60 MB of disk space.
185 \begin{enumerate
}\itemsep=
0pt
186 \item Almost any C++ compiler, including GNU C++ (EGCS
1.1.1 or above).
187 \item Almost any Unix workstation, and one of: GTK+
1.0, GTK+
1.2, Motif
1.2 or higher, Lesstif.
188 \item At least
60 MB of disk space.
191 \section{Availability and location of wxWindows
}
193 wxWindows is available by anonymous FTP and World Wide Web:
196 ftp://www.remstar.com/pub/wxwin
197 http://www.wxwindows.org
200 You can also buy a CD-ROM using the form on the Web site, or by contacting:
203 12 North Street West\\
207 julian.smart@ukonline.co.uk
209 \section{Acknowledgments
}
211 Thanks are due to AIAI for being willing to release the original version of
212 wxWindows into the public domain, and to our patient partners.
214 We would particularly like to thank the following for their contributions to wxWindows, and the many others who have been involved in
215 the project over the years. Apologies for any unintentional omissions from this list.
217 Yiorgos Adamopoulos, Jamshid Afshar, Alejandro Aguilar-Sierra, AIAI, Patrick Albert, Karsten Ballueder, Michael Bedward, Kai Bendorf, Yura Bidus, Keith
218 Gary Boyce, Chris Breeze, Pete Britton, Ian Brown, C. Buckley, Dmitri Chubraev, Robin Corbet, Cecil Coupe, Andrew Davison, Neil Dudman, Robin
219 Dunn, Hermann Dunkel, Jos van Eijndhoven, Tom Felici, Thomas Fettig, Matthew Flatt, Pasquale Foggia, Josep Fortiana, Todd Fries, Dominic Gallagher,
220 Wolfram Gloger, Norbert Grotz, Stefan Gunter, Bill Hale, Patrick Halke, Stefan Hammes, Guillaume Helle, Harco de Hilster, Cord Hockemeyer, Markus
221 Holzem, Olaf Klein, Leif Jensen, Bart Jourquin, Guilhem Lavaux, Jan Lessner, Nicholas Liebmann, Torsten Liermann, Per Lindqvist, Thomas Runge, Tatu
222 M\"
{a
}nnist\"
{o
}, Scott Maxwell, Thomas Myers, Oliver Niedung, Hernan Otero, Ian Perrigo, Timothy Peters, Giordano Pezzoli, Harri Pasanen, Thomaso Paoletti,
223 Garrett Potts, Marcel Rasche, Robert Roebling, Dino Scaringella, Jobst Schmalenbach, Arthur Seaton, Paul Shirley, Vaclav Slavik, Stein Somers, Petr Smilauer, Neil Smith,
224 Kari Syst\"
{a
}, Arthur Tetzlaff-Deas, Jonathan Tonberg, Jyrki Tuomi, Janos Vegh, Andrea Venturoli, Vadim Zeitlin, Xiaokun Zhu, Edward Zimmermann.
226 `Graphplace', the basis for the wxGraphLayout library, is copyright Dr. Jos
227 T.J. van Eijndhoven of Eindhoven University of Technology. The code has
228 been used in wxGraphLayout with his permission.
230 We also acknowledge the author of XFIG, the excellent Unix drawing tool,
231 from the source of which we have borrowed some spline drawing code.
232 His copyright is included below.
234 {\it XFig2.1 is copyright (c)
1985 by Supoj Sutanthavibul. Permission to
235 use, copy, modify, distribute, and sell this software and its
236 documentation for any purpose is hereby granted without fee, provided
237 that the above copyright notice appear in all copies and that both that
238 copyright notice and this permission notice appear in supporting
239 documentation, and that the name of M.I.T. not be used in advertising or
240 publicity pertaining to distribution of the software without specific,
241 written prior permission. M.I.T. makes no representations about the
242 suitability of this software for any purpose. It is provided ``as is''
243 without express or implied warranty.
}
245 \chapter{Multi-platform development with wxWindows
}\label{multiplat
}
246 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
247 \setfooter{\thepage}{}{}{}{}{\thepage}%
249 This chapter describes the practical details of using wxWindows. Please
250 see the file install.txt for up-to-date installation instructions, and
251 changes.txt for differences between versions.
253 \section{Include files
}
255 The main include file is
{\tt "wx/wx.h"
}; this includes the most commonly
256 used modules of wxWindows.
258 To save on compilation time, include only those header files relevant to the
259 source file. If you are using precompiled headers, you should include
260 the following section before any other includes:
263 // For compilers that support precompilation, includes "wx.h".
264 #include <wx/wxprec.h>
271 // Include your minimal set of headers here, or wx.h
275 ... now your other include files ...
278 The file
{\tt "wx/wxprec.h"
} includes
{\tt "wx/wx.h"
}. Although this incantation
279 may seem quirky, it is in fact the end result of a lot of experimentation,
280 and several Windows compilers to use precompilation (those tested are Microsoft Visual C++, Borland C++
283 Borland precompilation is largely automatic. Visual C++ requires specification of
{\tt "wx/wxprec.h"
} as
284 the file to use for precompilation. Watcom C++ is automatic apart from the specification of
285 the .pch file. Watcom C++ is strange in requiring the precompiled header to be used only for
286 object files compiled in the same directory as that in which the precompiled header was created.
287 Therefore, the wxWindows Watcom C++ makefiles go through hoops deleting and recreating
288 a single precompiled header file for each module, thus preventing an accumulation of many
289 multi-megabyte .pch files.
293 Please the wxGTK or wxMotif documentation for use of the Unix version of wxWindows.
294 Under Windows, use the library wx.lib for stand-alone Windows
295 applications, or wxdll.lib for creating DLLs.
297 \section{Configuration
}
299 Options are configurable in the file
300 \rtfsp{\tt "wx/XXX/setup.h"
} where XXX is the required platform (such as msw, motif, gtk, mac). Some settings are a matter
301 of taste, some help with platform-specific problems, and
302 others can be set to minimize the size of the library. Please see the setup.h file
303 and
{\tt install.txt
} files for details on configuration.
307 At the moment there is no attempt to make Unix makefiles and
308 PC makefiles compatible, i.e. one makefile is required for
309 each environment. wxGTK has its own configure system which can also
310 be used with wxMotif, although wxMotif has a simple makefile system of its own.
312 Sample makefiles for Unix (suffix .UNX), MS C++ (suffix .DOS and .NT), Borland
313 C++ (.BCC and .B32) and Symantec C++ (.SC) are included for the library, demos
316 The controlling makefile for wxWindows is in the platform-specific
317 directory, such as
{\tt src/msw
} or
{\tt src/motif
}.
319 Please see the platform-specific
{\tt install.txt
} file for further details.
321 \section{Windows-specific files
}
323 wxWindows application compilation under MS Windows requires at least two
324 extra files, resource and module definition files.
326 \subsection{Resource file
}\label{resources
}
328 The least that must be defined in the Windows resource file (extension RC)
329 is the following statement:
332 rcinclude "wx/msw/wx.rc"
335 which includes essential internal wxWindows definitions. The resource script
336 may also contain references to icons, cursors, etc., for example:
342 The icon can then be referenced by name when creating a frame icon. See
343 the MS Windows SDK documentation.
345 \normalbox{Note: include wx.rc
{\it after
} any ICON statements
346 so programs that search your executable for icons (such
347 as the Program Manager) find your application icon first.
}
349 \subsection{Module definition file
}
351 A module definition file (extension DEF) is required for
16-bit applications, and
352 looks like the following:
359 CODE PRELOAD MOVEABLE DISCARDABLE
360 DATA PRELOAD MOVEABLE MULTIPLE
365 The only lines which will usually have to be changed per application are
366 NAME and DESCRIPTION.
368 \section{Allocating and deleting wxWindows objects
}
370 In general, classes derived from wxWindow must dynamically allocated
371 with
{\it new
} and deleted with
{\it delete
}. If you delete a window,
372 all of its children and descendants will be automatically deleted,
373 so you don't need to delete these descendants explicitly.
375 When deleting a frame or dialog, use
{\bf Destroy
} rather than
{\bf delete
} so
376 that the wxWindows delayed deletion can take effect. This waits until idle time
377 (when all messages have been processed) to actually delete the window, to avoid
378 problems associated with the GUI sending events to deleted windows.
380 Don't create a window on the stack, because this will interfere
381 with delayed deletion.
383 If you decide to allocate a C++ array of objects (such as wxBitmap) that may
384 be cleaned up by wxWindows, make sure you delete the array explicitly
385 before wxWindows has a chance to do so on exit, since calling
{\it delete
} on
386 array members will cause memory problems.
388 wxColour can be created statically: it is not automatically cleaned
389 up and is unlikely to be shared between other objects; it is lightweight
390 enough for copies to be made.
392 Beware of deleting objects such as a wxPen or wxBitmap if they are still in use.
393 Windows is particularly sensitive to this: so make sure you
394 make calls like wxDC::SetPen(wxNullPen) or wxDC::SelectObject(wxNullBitmap) before deleting
395 a drawing object that may be in use. Code that doesn't do this will probably work
396 fine on some platforms, and then fail under Windows.
398 \section{Architecture dependency
}
400 A problem which sometimes arises from writing multi-platform programs is that
401 the basic C types are not defiend the same on all platforms. This holds true
402 for both the length in bits of the standard types (such as int and long) as
403 well as their byte order, which might be little endian (typically
404 on Intel computers) or big endian (typically on some Unix workstations). wxWindows
405 defines types and macros that make it easy to write architecture independent
408 wxInt32, wxInt16, wxInt8, wxUint32, wxUint16 = wxWord, wxUint8 = wxByte
410 where wxInt32 stands for a
32-bit signed integer type etc. You can also check
411 which architecture the program is compiled on using the wxBYTE
\_ORDER define
412 which is either wxBIG
\_ENDIAN or wxLITTLE
\_ENDIAN (in the future maybe wxPDP
\_ENDIAN
415 The macros handling bit-swapping with respect to the applications endianness
416 are described in the
\helpref{Macros
}{macros
} section.
418 \section{Conditional compilation
}
420 One of the purposes of wxWindows is to reduce the need for conditional
421 compilation in source code, which can be messy and confusing to follow.
422 However, sometimes it is necessary to incorporate platform-specific
423 features (such as metafile use under MS Windows). The symbols
424 listed in the file
{\tt symbols.txt
} may be used for this purpose,
425 along with any user-supplied ones.
429 The following documents some miscellaneous C++ issues.
431 \subsection{Templates
}
433 wxWindows does not use templates since it is a notoriously unportable feature.
437 wxWindows does not use run-time type information since wxWindows provides
438 its own run-time type information system, implemented using macros.
440 \subsection{Type of NULL
}
442 Some compilers (e.g. the native IRIX cc) define NULL to be
0L so that
443 no conversion to pointers is allowed. Because of that, all these
444 occurences of NULL in the GTK port use an explicit conversion such
449 wxWindow *my_window = (wxWindow*) NULL;
453 It is recommended to adhere to this in all code using wxWindows as
454 this make the code (a bit) more portable.
456 \subsection{Precompiled headers
}
458 Some compilers, such as Borland C++ and Microsoft C++, support
459 precompiled headers. This can save a great deal of compiling time. The
460 recommended approach is to precompile
{\tt "wx.h"
}, using this
461 precompiled header for compiling both wxWindows itself and any
462 wxWindows applications. For Windows compilers, two dummy source files
463 are provided (one for normal applications and one for creating DLLs)
464 to allow initial creation of the precompiled header.
466 However, there are several downsides to using precompiled headers. One
467 is that to take advantage of the facility, you often need to include
468 more header files than would normally be the case. This means that
469 changing a header file will cause more recompilations (in the case of
470 wxWindows, everything needs to be recompiled since everything includes
{\tt "wx.h"
}!)
472 A related problem is that for compilers that don't have precompiled
473 headers, including a lot of header files slows down compilation
474 considerably. For this reason, you will find (in the common
475 X and Windows parts of the library) conditional
476 compilation that under Unix, includes a minimal set of headers;
477 and when using Visual C++, includes
{\tt wx.h
}. This should help provide
478 the optimal compilation for each compiler, although it is
479 biassed towards the precompiled headers facility available
482 \section{File handling
}
484 When building an application which may be used under different
485 environments, one difficulty is coping with documents which may be
486 moved to different directories on other machines. Saving a file which
487 has pointers to full pathnames is going to be inherently unportable. One
488 approach is to store filenames on their own, with no directory
489 information. The application searches through a number of locally
490 defined directories to find the file. To support this, the class
{\bf
491 wxPathList
} makes adding directories and searching for files easy, and
492 the global function
{\bf wxFileNameFromPath
} allows the application to
493 strip off the filename from the path if the filename must be stored.
494 This has undesirable ramifications for people who have documents of the
495 same name in different directories.
497 As regards the limitations of DOS
8+
3 single-case filenames versus
498 unrestricted Unix filenames, the best solution is to use DOS filenames
499 for your application, and also for
document filenames
{\it if
} the user
500 is likely to be switching platforms regularly. Obviously this latter
501 choice is up to the application user to decide. Some programs (such as
502 YACC and LEX) generate filenames incompatible with DOS; the best
503 solution here is to have your Unix makefile rename the generated files
504 to something more compatible before transferring the source to DOS.
505 Transferring DOS files to Unix is no problem, of course, apart from EOL
506 conversion for which there should be a utility available (such as
509 See also the File Functions section of the reference manual for
510 descriptions of miscellaneous file handling functions.
513 \chapter{Utilities supplied with wxWindows
}\label{utilities
}
514 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
515 \setfooter{\thepage}{}{}{}{}{\thepage}%
517 A number of `extras' are supplied with wxWindows, to complement
518 the GUI functionality in the main class library. These are found
519 below the utils directory and usually have their own source, library
520 and documentation directories. For other user-contributed packages,
521 see the directory ftp://www.remstar.com/pub/wxwin/contrib, which is
522 more easily accessed via the Contributions page on the Web site.
524 \section{wxHelp
}\label{wxhelp
}
526 wxHelp is a stand-alone program, written using wxWindows,
527 for displaying hypertext help. It is necessary since not all target
528 systems (notably X) supply an adequate
529 standard for on-line help. wxHelp is modelled on the MS Windows help
530 system, with contents, search and browse buttons, but does not reformat
531 text to suit the size of window, as WinHelp does, and its input files
532 are uncompressed ASCII with some embedded font commands and an .xlp
533 extension. Most wxWindows documentation (user manuals and class
534 references) is supplied in wxHelp format, and also in Windows Help
535 format. The wxWindows
2.0 project will presently use an HTML widget
536 in a new and improved wxHelp implementation, under X.
538 Note that an application can be programmed to use Windows Help under
539 MS Windows, and wxHelp under X. An alternative help viewer under X is
540 Mosaic, a World Wide Web viewer that uses HTML as its native hypertext
541 format. However, this is not currently integrated with wxWindows
544 wxHelp works in two modes---edit and end-user. In edit mode, an ASCII
545 file may be marked up with different fonts and colours, and divided into
546 sections. In end-user mode, no editing is possible, and the user browses
547 principally by clicking on highlighted blocks.
549 When an application invokes wxHelp, subsequent sections, blocks or
550 files may be viewed using the same instance of wxHelp since the two
551 programs are linked using wxWindows interprocess communication
552 facilities. When the application exits, that application's instance of
553 wxHelp may be made to exit also. See the
{\bf wxHelpControllerBase
} entry in the
554 reference section for how an application controls wxHelp.
556 \section{Tex2RTF
}\label{textortf
}
558 Supplied with wxWindows is a utility called Tex2RTF for converting
\rtfsp
559 \LaTeX\ manuals to the following formats:
563 wxWindows help system format (XLP).
565 Rich Text Format suitable for importing into a word processor.
566 \item[Windows Help RTF
]
567 Rich Text Format suitable for compiling into a WinHelp HLP file with the
570 HTML is the native format for Mosaic, the main hypertext viewer for
571 the World Wide Web. Since it is freely available it is a good candidate
572 for being the wxWindows help system under X, as an alternative to wxHelp.
575 Tex2RTF is used for the wxWindows manuals and can be used independently
576 by authors wishing to create on-line and printed manuals from the same
\rtfsp
577 \LaTeX\ source. Please see the separate documentation for Tex2RTF.
579 \section{wxTreeLayout
}
581 This is a simple class library for drawing trees in a reasonably pretty
582 fashion. It provides only minimal default drawing capabilities, since
583 the algorithm is meant to be used for implementing custom tree-based
586 Directed graphs may also be drawn using this library, if cycles are
587 removed before the nodes and arcs are passed to the algorithm.
589 Tree displays are used in many applications: directory browsers,
590 hypertext systems, class browsers, and decision trees are a few
593 See the separate manual and the directory utils/wxtree.
595 \section{wxGraphLayout
}
597 The wxGraphLayout class is based on a tool called `graphplace' by Dr.
598 Jos T.J. van Eijndhoven of Eindhoven University of Technology. Given a
599 (possibly cyclic) directed graph, it does its best to lay out the nodes
600 in a sensible manner. There are many applications (such as diagramming)
601 where it is required to display a graph with no human intervention. Even
602 if manual repositioning is later required, this algorithm can make a good
605 See the separate manual and the directory utils/wxgraph.
607 \section{Colours
}\label{coloursampler
}
609 A colour sampler for viewing colours and their names on each
613 \chapter{Tutorial
}\label{tutorial
}
614 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
615 \setfooter{\thepage}{}{}{}{}{\thepage}%
620 \chapter{Programming strategies
}\label{strategies
}
621 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
622 \setfooter{\thepage}{}{}{}{}{\thepage}%
624 This chapter is intended to list strategies that may be useful when
625 writing and debugging wxWindows programs. If you have any good tips,
626 please submit them for inclusion here.
628 \section{Strategies for reducing programming errors
}
630 \subsection{Use ASSERT
}
632 Although I haven't done this myself within wxWindows, it is good
633 practice to use ASSERT statements liberally, that check for conditions that
634 should or should not hold, and print out appropriate error messages.
635 These can be compiled out of a non-debugging version of wxWindows
636 and your application. Using ASSERT is an example of `defensive programming':
637 it can alert you to problems later on.
639 \subsection{Use wxString in preference to character arrays
}
641 Using wxString can be much safer and more convenient than using char *.
642 Again, I haven't practised what I'm preaching, but I'm now trying to use
643 wxString wherever possible. You can reduce the possibility of memory
644 leaks substantially, and it's much more convenient to use the overloaded
645 operators than functions such as strcmp. wxString won't add a significant
646 overhead to your program; the overhead is compensated for by easier
647 manipulation (which means less code).
649 The same goes for other data types: use classes wherever possible.
651 \section{Strategies for portability
}
653 \subsection{Use relative positioning or constraints
}
655 Don't use absolute panel item positioning if you can avoid it. Different GUIs have
656 very differently sized panel items. Consider using the constraint system, although this
657 can be complex to program.
659 Alternatively, you could use alternative .wrc (wxWindows resource files) on different
660 platforms, with slightly different dimensions in each. Or space your panel items out
663 \subsection{Use wxWindows resource files
}
665 Use .wrc (wxWindows resource files) where possible, because they can be easily changed
666 independently of source code. Bitmap resources can be set up to load different
667 kinds of bitmap depending on platform (see the section on resource files).
669 \section{Strategies for debugging
}\label{debugstrategies
}
671 \subsection{Positive thinking
}
673 It's common to blow up the problem in one's imagination, so that it seems to threaten
674 weeks, months or even years of work. The problem you face may seem insurmountable:
675 but almost never is. Once you have been programming for some time, you will be able
676 to remember similar incidents that threw you into the depths of despair. But
677 remember, you always solved the problem, somehow!
679 Perseverance is often the key, even though a seemingly trivial problem
680 can take an apparently inordinate amount of time to solve. In the end,
681 you will probably wonder why you worried so much. That's not to say it
682 isn't painful at the time. Try not to worry -- there are many more important
685 \subsection{Simplify the problem
}
687 Reduce the code exhibiting the problem to the smallest program possible
688 that exhibits the problem. If it is not possible to reduce a large and
689 complex program to a very small program, then try to ensure your code
690 doesn't hide the problem (you may have attempted to minimize the problem
691 in some way: but now you want to expose it).
693 With luck, you can add a small amount of code that causes the program
694 to go from functioning to non-functioning state. This should give a clue
695 to the problem. In some cases though, such as memory leaks or wrong
696 deallocation, this can still give totally spurious results!
698 \subsection{Use a debugger
}
700 This sounds like facetious advice, but it's surprising how often people
701 don't use a debugger. Often it's an overhead to install or learn how to
702 use a debugger, but it really is essential for anything but the most
705 \subsection{Use logging functions
}
707 There is a variety of logging functions that you can use in your program:
708 see
\helpref{Logging functions
}{logfunctions
}.
710 Using tracing statements may be more convenient than using the debugger
711 in some circumstances (such as when your debugger doesn't support a lot
712 of debugging code, or you wish to print a bunch of variables).
714 \subsection{Use the wxWindows debugging facilities
}
716 You can use wxDebugContext to check for
717 memory leaks and corrupt memory: in fact in debugging mode, wxWindows will
718 automatically check for memory leaks at the end of the program if wxWindows is suitably
719 configured. Depending on the operating system and compiler, more or less
720 specific information about the problem will be logged.
722 You should also use
\helpref{debug macros
}{debugmacros
} as part of a `defensive programming' strategy,
723 scattering wxASSERTs liberally to test for problems in your code as early as possible. Forward thinking
724 will save a surprising amount of time in the long run.
726 See the
\helpref{debugging overview
}{debuggingoverview
} for further information.
728 \subsection{Check Windows debug messages
}
730 Under Windows, it's worth running your program with DbgView (available from
731 {\tt http://www.sysinternals.com
} running or
732 some other program that shows Windows-generated debug messages. It's
733 possible it'll show invalid handles being used. You may have fun seeing
734 what commercial programs cause these normally hidden errors! Microsoft
735 recommend using the debugging version of Windows, which shows up even
736 more problems. However, I doubt it's worth the hassle for most
737 applications. wxWindows is designed to minimize the possibility of such
738 errors, but they can still happen occasionally, slipping through unnoticed
739 because they are not severe enough to cause a crash.
741 \subsection{Genetic mutation
}
743 If we had sophisticated genetic algorithm tools that could be applied
744 to programming, we could use them. Until then, a common -- if rather irrational --
745 technique is to just make arbitrary changes to the code until something
746 different happens. You may have an intuition why a change will make a difference;
747 otherwise, just try altering the order of code, comment lines out, anything
748 to get over an impasse. Obviously, this is usually a last resort.