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