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