]> git.saurik.com Git - wxWidgets.git/blob - docs/doxygen/mainpages/devtips.h
wxMessageBox off the main thread lost result code.
[wxWidgets.git] / docs / doxygen / mainpages / devtips.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: devtips.h
3 // Purpose: Cross-platform development page of the Doxygen manual
4 // Author: wxWidgets team
5 // Licence: wxWindows licence
6 /////////////////////////////////////////////////////////////////////////////
7
8 /**
9
10 @page page_multiplatform General Cross-Platform Development Tips
11
12 @tableofcontents
13
14 This chapter describes some tips related to cross-platform development.
15
16
17
18 @section page_multiplatform_includefiles Include Files
19
20 The main include file is @c "wx/wx.h"; this includes the most commonly used
21 modules of wxWidgets.
22
23 To save on compilation time, include only those header files relevant to the
24 source file. If you are using @b precompiled headers, you should include the
25 following section before any other includes:
26
27 @verbatim
28 // For compilers that support precompilation, includes "wx.h".
29 #include <wx/wxprec.h>
30
31 #ifdef __BORLANDC__
32 # pragma hdrstop
33 #endif
34
35 #ifndef WX_PRECOMP
36 // Include your minimal set of headers here, or wx.h
37 # include <wx/wx.h>
38 #endif
39
40 ... now your other include files ...
41 @endverbatim
42
43 The file @c "wx/wxprec.h" includes @c "wx/wx.h". Although this incantation may
44 seem quirky, it is in fact the end result of a lot of experimentation, and
45 several Windows compilers to use precompilation which is largely automatic for
46 compilers with necessary support. Currently it is used for Visual C++
47 (including embedded Visual C++), Borland C++, Open Watcom C++, Digital Mars C++
48 and newer versions of GCC. Some compilers might need extra work from the
49 application developer to set the build environment up as necessary for the
50 support.
51
52
53
54 @section page_multiplatform_libraries Libraries
55
56 All ports of wxWidgets can create either a @b static library or a @b shared
57 library.
58
59 When a program is linked against a @e static library, the machine code from the
60 object files for any external functions used by the program is copied from the
61 library into the final executable.
62
63 @e Shared libraries are handled with a more advanced form of linking, which
64 makes the executable file smaller. They use the extension @c ".so" (Shared
65 Object) under Linux and @c ".dll" (Dynamic Link Library) under Windows.
66
67 An executable file linked against a shared library contains only a small table
68 of the functions it requires, instead of the complete machine code from the
69 object files for the external functions. Before the executable file starts
70 running, the machine code for the external functions is copied into memory from
71 the shared library file on disk by the operating system - a process referred to
72 as @e dynamic linking.
73
74 Dynamic linking makes executable files smaller and saves disk space, because
75 one copy of a library can be shared between multiple programs. Most operating
76 systems also provide a virtual memory mechanism which allows one copy of a
77 shared library in physical memory to be used by all running programs, saving
78 memory as well as disk space.
79
80 Furthermore, shared libraries make it possible to update a library without
81 recompiling the programs which use it (provided the interface to the library
82 does not change).
83
84 wxWidgets can also be built in @b multilib and @b monolithic variants. See the
85 @ref page_libs for more information on these.
86
87
88
89 @section page_multiplatform_configuration Configuration
90
91 When using project files and makefiles directly to build wxWidgets, options are
92 configurable in the file @c "wx/XXX/setup.h" where XXX is the required
93 platform (such as @c msw, @c motif, @c gtk, @c mac).
94
95 Some settings are a matter of taste, some help with platform-specific problems,
96 and others can be set to minimize the size of the library. Please see the
97 @c "setup.h" file and @c "install.txt" files for details on configuration.
98
99 When using the @c "configure" script to configure wxWidgets (on Unix and other
100 platforms where configure is available), the corresponding @c "setup.h" files
101 are generated automatically along with suitable makefiles.
102
103 When using the RPM packages (or DEB or other forms of @e binaries) for
104 installing wxWidgets on Linux, a correct @c "setup.h" is shipped in the package
105 and this must not be changed.
106
107
108
109 @section page_multiplatform_makefiles Makefiles
110
111 On Microsoft Windows, wxWidgets has a different set of makefiles for each
112 compiler, because each compiler's @c 'make' tool is slightly different. Popular
113 Windows compilers that we cater for, and the corresponding makefile extensions,
114 include: Microsoft Visual C++ (.vc), Borland C++ (.bcc), OpenWatcom C++ (.wat)
115 and MinGW/Cygwin (.gcc). Makefiles are provided for the wxWidgets library
116 itself, samples, demos, and utilities.
117
118 On Linux, Mac and OS/2, you use the @c 'configure' command to generate the
119 necessary makefiles. You should also use this method when building with
120 MinGW/Cygwin on Windows.
121
122 We also provide project files for some compilers, such as Microsoft VC++.
123 However, we recommend using makefiles to build the wxWidgets library itself,
124 because makefiles can be more powerful and less manual intervention is
125 required.
126
127 On Windows using a compiler other than MinGW/Cygwin, you would build the
128 wxWidgets library from the @c "build/msw" directory which contains the relevant
129 makefiles.
130
131 On Windows using MinGW/Cygwin, and on Unix, MacOS X and OS/2, you invoke
132 'configure' (found in the top-level of the wxWidgets source hierarchy), from
133 within a suitable empty directory for containing makefiles, object files and
134 libraries.
135
136 For details on using makefiles, configure, and project files, please see
137 @c "docs/xxx/install.txt" in your distribution, where @c "xxx" is the platform
138 of interest, such as @c msw, @c gtk, @c x11, @c mac.
139
140 All wxWidgets makefiles are generated using Bakefile <http://www.bakefile.org/>.
141 wxWidgets also provides (in the @c "build/bakefiles/wxpresets" folder) the
142 wxWidgets bakefile presets. These files allow you to create bakefiles for your
143 own wxWidgets-based applications very easily.
144
145
146
147 @section page_multiplatform_winresources Windows Resource Files
148
149 wxWidgets application compilation under MS Windows requires at least one extra
150 file: a resource file.
151
152 The least that must be defined in the Windows resource file (extension RC) is
153 the following statement:
154
155 @verbatim
156 #include "wx/msw/wx.rc"
157 @endverbatim
158
159 which includes essential internal wxWidgets definitions. The resource script
160 may also contain references to icons, cursors, etc., for example:
161
162 @verbatim
163 wxicon icon wx.ico
164 @endverbatim
165
166 The icon can then be referenced by name when creating a frame icon. See the
167 Microsoft Windows SDK documentation.
168
169 @note Include "wx.rc" @e after any ICON statements so programs that search your
170 executable for icons (such as the Program Manager) find your application
171 icon first.
172
173
174
175 @section page_multiplatform_allocatingobjects Allocating and Deleting wxWidgets Objects
176
177 In general, classes derived from wxWindow must dynamically allocated with
178 @e new and deleted with @e delete. If you delete a window, all of its children
179 and descendants will be automatically deleted, so you don't need to delete
180 these descendants explicitly.
181
182 When deleting a frame or dialog, use @b Destroy rather than @b delete so that
183 the wxWidgets delayed deletion can take effect. This waits until idle time
184 (when all messages have been processed) to actually delete the window, to avoid
185 problems associated with the GUI sending events to deleted windows.
186
187 In general wxWindow-derived objects should always be allocated on the heap
188 as wxWidgets will destroy them itself. The only, but important, exception to
189 this rule are the modal dialogs, i.e. wxDialog objects which are shown using
190 wxDialog::ShowModal() method. They may be allocated on the stack and, indeed,
191 usually are local variables to ensure that they are destroyed on scope exit as
192 wxWidgets does not destroy them unlike with all the other windows. So while it
193 is still possible to allocate modal dialogs on the heap, you should still
194 destroy or delete them explicitly in this case instead of relying on wxWidgets
195 doing it.
196
197 If you decide to allocate a C++ array of objects (such as wxBitmap) that may be
198 cleaned up by wxWidgets, make sure you delete the array explicitly before
199 wxWidgets has a chance to do so on exit, since calling @e delete on array
200 members will cause memory problems.
201
202 wxColour can be created statically: it is not automatically cleaned
203 up and is unlikely to be shared between other objects; it is lightweight
204 enough for copies to be made.
205
206 Beware of deleting objects such as a wxPen or wxBitmap if they are still in
207 use. Windows is particularly sensitive to this, so make sure you make calls
208 like wxDC::SetPen(wxNullPen) or wxDC::SelectObject(wxNullBitmap) before
209 deleting a drawing object that may be in use. Code that doesn't do this will
210 probably work fine on some platforms, and then fail under Windows.
211
212
213
214 @section page_multiplatform_architecturedependency Architecture Dependency
215
216 A problem which sometimes arises from writing multi-platform programs is that
217 the basic C types are not defined the same on all platforms. This holds true
218 for both the length in bits of the standard types (such as int and long) as
219 well as their byte order, which might be little endian (typically on Intel
220 computers) or big endian (typically on some Unix workstations). wxWidgets
221 defines types and macros that make it easy to write architecture independent
222 code. The types are:
223
224 wxInt32, wxInt16, wxInt8, wxUint32, wxUint16 = wxWord, wxUint8 = wxByte
225
226 where wxInt32 stands for a 32-bit signed integer type etc. You can also check
227 which architecture the program is compiled on using the wxBYTE_ORDER define
228 which is either wxBIG_ENDIAN or wxLITTLE_ENDIAN (in the future maybe
229 wxPDP_ENDIAN as well).
230
231 The macros handling bit-swapping with respect to the applications endianness
232 are described in the @ref group_funcmacro_byteorder section.
233
234
235
236 @section page_multiplatform_conditionalcompilation Conditional Compilation
237
238 One of the purposes of wxWidgets is to reduce the need for conditional
239 compilation in source code, which can be messy and confusing to follow.
240 However, sometimes it is necessary to incorporate platform-specific features
241 (such as metafile use under MS Windows). The @ref page_wxusedef symbols listed
242 in the file @c setup.h may be used for this purpose, along with any
243 user-supplied ones.
244
245
246
247 @section page_multiplatform_cpp C++ Issues
248
249 The following documents some miscellaneous C++ issues.
250
251 @subsection page_multiplatform_cpp_templates Templates
252
253 wxWidgets does not use templates (except for some advanced features that are
254 switched off by default) since it is a notoriously unportable feature.
255
256 @subsection page_multiplatform_cpp_rtti Runtime Type Information (RTTI)
257
258 wxWidgets does not use C++ run-time type information since wxWidgets provides
259 its own run-time type information system, implemented using macros.
260
261 @subsection page_multiplatform_cpp_precompiledheaders Precompiled Headers
262
263 Some compilers, such as Borland C++ and Microsoft C++, support precompiled
264 headers. This can save a great deal of compiling time. The recommended approach
265 is to precompile @c "wx.h", using this precompiled header for compiling both
266 wxWidgets itself and any wxWidgets applications. For Windows compilers, two
267 dummy source files are provided (one for normal applications and one for
268 creating DLLs) to allow initial creation of the precompiled header.
269
270 However, there are several downsides to using precompiled headers. One is that
271 to take advantage of the facility, you often need to include more header files
272 than would normally be the case. This means that changing a header file will
273 cause more recompilations (in the case of wxWidgets, everything needs to be
274 recompiled since everything includes @c "wx.h").
275
276 A related problem is that for compilers that don't have precompiled headers,
277 including a lot of header files slows down compilation considerably. For this
278 reason, you will find (in the common X and Windows parts of the library)
279 conditional compilation that under Unix, includes a minimal set of headers; and
280 when using Visual C++, includes @c "wx.h". This should help provide the optimal
281 compilation for each compiler, although it is biased towards the precompiled
282 headers facility available in Microsoft C++.
283
284
285
286 @section page_multiplatform_filehandling File Handling
287
288 When building an application which may be used under different environments,
289 one difficulty is coping with documents which may be moved to different
290 directories on other machines. Saving a file which has pointers to full
291 pathnames is going to be inherently unportable.
292
293 One approach is to store filenames on their own, with no directory information.
294 The application then searches into a list of standard paths (platform-specific)
295 through the use of wxStandardPaths.
296
297 Eventually you may want to use also the wxPathList class.
298
299 Nowadays the limitations of DOS 8+3 filenames doesn't apply anymore. Most
300 modern operating systems allow at least 255 characters in the filename; the
301 exact maximum length, as well as the characters allowed in the filenames, are
302 OS-specific so you should try to avoid extremely long (> 255 chars) filenames
303 and/or filenames with non-ANSI characters.
304
305 Another thing you need to keep in mind is that all Windows operating systems
306 are case-insensitive, while Unix operating systems (Linux, Mac, etc) are
307 case-sensitive.
308
309 Also, for text files, different OSes use different End Of Lines (EOL). Windows
310 uses CR+LF convention, Linux uses LF only, Mac CR only.
311
312 The wxTextFile, wxTextInputStream, wxTextOutputStream classes help to abstract
313 from these differences. Of course, there are also 3rd party utilities such as
314 @c dos2unix and @c unix2dos which do the EOL conversions.
315
316 See also the @ref group_funcmacro_file section of the reference manual for the
317 description of miscellaneous file handling functions.
318
319
320
321 @section page_multiplatform_reducingerr Reducing Programming Errors
322
323 @subsection page_multiplatform_reducingerr_useassert Use ASSERT
324
325 It is good practice to use ASSERT statements liberally, that check for
326 conditions that should or should not hold, and print out appropriate error
327 messages.
328
329 These can be compiled out of a non-debugging version of wxWidgets and your
330 application. Using ASSERT is an example of `defensive programming': it can
331 alert you to problems later on.
332
333 See wxASSERT() for more info.
334
335 @subsection page_multiplatform_reducingerr_usewxstring Use wxString in Preference to Character Arrays
336
337 Using wxString can be much safer and more convenient than using @c wxChar*.
338
339 You can reduce the possibility of memory leaks substantially, and it is much
340 more convenient to use the overloaded operators than functions such as
341 @c strcmp. wxString won't add a significant overhead to your program; the
342 overhead is compensated for by easier manipulation (which means less code).
343
344 The same goes for other data types: use classes wherever possible.
345
346
347
348 @section page_multiplatform_gui GUI Design
349
350 @li <b>Use Sizers:</b> Don't use absolute panel item positioning if you can
351 avoid it. Every platform's native controls have very different sizes.
352 Consider using the @ref overview_sizer instead.
353 @li <b>Use wxWidgets Resource Files:</b> Use @c XRC (wxWidgets resource files)
354 where possible, because they can be easily changed independently of source
355 code. See the @ref overview_xrc for more info.
356
357
358
359 @section page_multiplatform_debug Debugging
360
361 @subsection page_multiplatform_debug_positivethinking Positive Thinking
362
363 It is common to blow up the problem in one's imagination, so that it seems to
364 threaten weeks, months or even years of work. The problem you face may seem
365 insurmountable: but almost never is. Once you have been programming for some
366 time, you will be able to remember similar incidents that threw you into the
367 depths of despair. But remember, you always solved the problem, somehow!
368
369 Perseverance is often the key, even though a seemingly trivial problem can take
370 an apparently inordinate amount of time to solve. In the end, you will probably
371 wonder why you worried so much. That's not to say it isn't painful at the time.
372 Try not to worry -- there are many more important things in life.
373
374 @subsection page_multiplatform_debug_simplifyproblem Simplify the Problem
375
376 Reduce the code exhibiting the problem to the smallest program possible that
377 exhibits the problem. If it is not possible to reduce a large and complex
378 program to a very small program, then try to ensure your code doesn't hide the
379 problem (you may have attempted to minimize the problem in some way: but now
380 you want to expose it).
381
382 With luck, you can add a small amount of code that causes the program to go
383 from functioning to non-functioning state. This should give a clue to the
384 problem. In some cases though, such as memory leaks or wrong deallocation, this
385 can still give totally spurious results!
386
387 @subsection page_multiplatform_debug_usedebugger Use a Debugger
388
389 This sounds like facetious advice, but it is surprising how often people don't
390 use a debugger. Often it is an overhead to install or learn how to use a
391 debugger, but it really is essential for anything but the most trivial
392 programs.
393
394 @subsection page_multiplatform_debug_uselogging Use Logging Functions
395
396 There is a variety of logging functions that you can use in your program: see
397 @ref group_funcmacro_log.
398
399 Using tracing statements may be more convenient than using the debugger in some
400 circumstances (such as when your debugger doesn't support a lot of debugging
401 code, or you wish to print a bunch of variables).
402
403 @subsection page_multiplatform_debug_usedebuggingfacilities Use the wxWidgets Debugging Facilities
404
405 You can use wxDebugContext to check for memory leaks and corrupt memory: in
406 fact in debugging mode, wxWidgets will automatically check for memory leaks at
407 the end of the program if wxWidgets is suitably configured. Depending on the
408 operating system and compiler, more or less specific information about the
409 problem will be logged.
410
411 You should also use @ref group_funcmacro_debug as part of a "defensive
412 programming" strategy, scattering wxASSERT()s liberally to test for problems in
413 your code as early as possible. Forward thinking will save a surprising amount
414 of time in the long run.
415
416 See the @ref overview_debugging for further information.
417
418 */
419