]> git.saurik.com Git - wxWidgets.git/blame - docs/doxygen/mainpages/platdetails.h
Implement hatched/stippled pens/brushes in wxGraphicsContext for Cairo.
[wxWidgets.git] / docs / doxygen / mainpages / platdetails.h
CommitLineData
4514447c
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: platdetails.h
3// Purpose: Platform details page of the Doxygen manual
4// Author: wxWidgets team
5// RCS-ID: $Id$
526954c5 6// Licence: wxWindows licence
4514447c
FM
7/////////////////////////////////////////////////////////////////////////////
8
9
880efa2a 10/**
4514447c 11
29f86fc1 12@page page_port Platform Details
4514447c 13
928f1a07
FM
14wxWidgets defines a common API across platforms, but uses the native graphical
15user interface (GUI) on each platform, so your program will take on the native
16look and feel that users are familiar with. Unfortunately native toolkits and
17hardware do not always support the functionality that the wxWidgets API
18requires. This chapter collects notes about differences among supported platforms
19and ports.
4514447c 20
928f1a07 21@li @ref page_port_wxgtk
0f6c9085 22@li @ref page_port_wxosx
928f1a07 23@li @ref page_port_wxos2
928f1a07 24@li @ref page_port_wxx11
1dfb6ff0 25@li @ref page_port_wxmotif
928f1a07
FM
26@li @ref page_port_wxmsw
27@li @ref page_port_nativedocs
4514447c
FM
28
29
928f1a07 30<hr>
4514447c
FM
31
32
33
928f1a07 34@section page_port_wxgtk wxGTK
469e56bf 35
928f1a07 36@htmlonly
fd779edb 37<img src="logo_gtk.png" alt="GTK logo" title="GTK logo" class="logo">
928f1a07 38@endhtmlonly
3c4f71cc 39
928f1a07
FM
40wxGTK is a port of wxWidgets using the GTK+ library.
41It makes use of GTK+'s native widgets wherever possible and uses
42wxWidgets' generic controls when needed. GTK+ itself has been
43ported to a number of systems, but so far only the original X11
44version is supported. Support for other GTK+ backends is planned,
45such as the new DirectFB backend.
3c4f71cc 46
928f1a07
FM
47All work is being done on GTK+ version 2.0 and above. Support for
48GTK+ 1.2 will be deprecated in a later release.
3c4f71cc 49
5bb7884b 50You will need GTK+ 2.6 or higher which is available from:
3c4f71cc 51
928f1a07 52http://www.gtk.org
3c4f71cc 53
928f1a07 54The newer version of GTK+ you use, the more native widgets and
7ecc54df
BP
55features will be utilized. We have gone to great lengths to
56allow compiling wxWidgets applications with the latest version of
928f1a07 57GTK+, with the resulting binary working on systems even with a
7ecc54df 58much earlier version of GTK+. You will have to ensure that the
928f1a07 59application is launched with lazy symbol binding for that.
3c4f71cc 60
928f1a07
FM
61In order to configure wxWidgets to compile wxGTK you will
62need use the @c --with-gtk argument to the @c configure script.
63This is the default for many systems.
3c4f71cc 64
928f1a07
FM
65GTK+ 1.2 can still be used, albeit discouraged. For that you can
66pass @c --with-gtk=1 to the @c configure script.
3c4f71cc 67
1dfb6ff0 68For further information, please see the files in @c docs/gtk
928f1a07 69in the distribution.
3c4f71cc
VS
70
71
0f6c9085 72@section page_port_wxosx wxOSX
3c4f71cc 73
928f1a07 74@htmlonly
fd779edb 75<img src="logo_osxleopard.png" alt="Mac OS X (Leopard) logo"
928f1a07
FM
76 title="Mac OS X (Leopard) logo" class="logo">
77@endhtmlonly
469e56bf 78
0f6c9085
KO
79@subsection page_port_wxosx_carbon wxOSX/Carbon
80
2b8471fb 81wxOSX/Carbon is a port of wxWidgets for the Macintosh OS platform.
c6b6ccd4 82Currently MacOS X 10.5 or higher are supported. wxOSX/Carbon can
5bb7884b 83be compiled both using Apple's command line developer tools
c1098adf 84as well as Apple's Xcode IDE. wxOSX/Carbon supports both the Intel
5bb7884b
RR
85and PowerPC architectures and can be used to produce
86"universal binaries" in order create application which can run
2b8471fb 87both architecture. Unfortunately, wxOSX/Carbon does not support any
5bb7884b
RR
8864-bit architecture since Apple decided not to port its Carbon
89API entirely to 64-bit.
3c4f71cc 90
0f6c9085
KO
91@note Carbon has been deprecated by Apple as of OS X 10.5 and will likely
92be removed entirely in a future OS version. It's recommended you look into
93switching your app over to wxOSX/Cocoa as soon as possible.
94
f5fd8c24 95For further information, please see the files in @c docs/osx
928f1a07 96in the distribution.
3c4f71cc
VS
97
98
99
0f6c9085 100@subsection page_port_wxosx_cocoa wxOSX/Cocoa
5bb7884b 101
2b8471fb 102wxOSX/Cocoa is another port of wxWidgets for the Macintosh OS
c6b6ccd4
SC
103platform. Currently MacOS X 10.5 or higher are supported.
104In contrast to wxOSX/Carbon, it uses the Cocoa API
2b8471fb
KO
105in place of Carbon. Much work has gone into this port and many
106controls are functional, but the port has not reached the maturity
bce3699f 107of the wxOSX/Carbon port yet. It is possible to use wxOSX/Cocoa
5bb7884b
RR
108on 64-bit architectures.
109
0f6c9085
KO
110In order to configure wxWidgets to compile wxOSX/Cocoa you will
111need to type:
112
113@verbatim configure --with-osx_cocoa @endverbatim
114
f5fd8c24 115For further information, please see the files in @c docs/osx
1dfb6ff0
FM
116in the distribution.
117
0f6c9085 118@note There was a previous effort towards a Cocoa port called
bce3699f 119wxCocoa, which was implemented totally with Cocoa API unlike the OSX/Cocoa port
2b8471fb 120which uses OS X C APIs to share code, and while it is no longer being actively
bce3699f 121developed, docs for it are available in @c docs/cocoa in the distribution.
2b8471fb
KO
122
123
3c4f71cc 124
928f1a07 125@section page_port_wxos2 wxOS2
469e56bf 126
928f1a07
FM
127wxOS2 is a port of wxWidgets for the IBM OS/2 Warp3 and Warp4 platforms.
128This port is currently under construction and in beta phase.
469e56bf 129
1dfb6ff0
FM
130For further information, please see the files in @c docs/os2
131in the distribution.
132
3c4f71cc
VS
133
134
928f1a07 135@section page_port_wxx11 wxX11
469e56bf 136
928f1a07 137@htmlonly
fd779edb 138<img src="logo_x11.png" alt="X.org logo" title="X.org logo" class="logo">
928f1a07 139@endhtmlonly
469e56bf 140
928f1a07
FM
141wxX11 is a port of wxWidgets using X11 (The X Window System)
142as the underlying graphics backend. wxX11 draws its widgets
143using the wxUniversal widget set which is now part of wxWidgets.
144wxX11 is well-suited for a number of special applications such
145as those running on systems with few resources (PDAs) or for
bbc5b7f8 146applications which need to use a special themed look.
3c4f71cc 147
928f1a07
FM
148In order to configure wxWidgets to compile wxX11 you will
149need to type:
3c4f71cc 150
928f1a07 151@verbatim configure --with-x11 --with-universal @endverbatim
3c4f71cc 152
1dfb6ff0 153For further information, please see the files in @c docs/x11
928f1a07
FM
154in the distribution. There is also a page on the use of
155wxWidgets for embedded applications on the wxWidgets web site.
3c4f71cc
VS
156
157
158
1dfb6ff0
FM
159@section page_port_wxmotif wxMotif
160
161@htmlonly
fd779edb 162<img src="logo_motif.png" alt="Motif logo" title="Motif logo" class="logo">
1dfb6ff0
FM
163@endhtmlonly
164
165wxMotif is a port of wxWidgets for X11 systems using Motif libraries.
166Motif libraries provide a clean and fast user interface at the expense
167of the beauty and candy of newer interfaces like GTK.
168
169For further information, please see the files in @c docs/motif
170in the distribution.
171
172
3c4f71cc
VS
173
174
928f1a07 175@section page_port_wxmsw wxMSW
469e56bf 176
928f1a07 177@htmlonly
fd779edb 178<img src="logo_win.png" alt="Windows logo" title="Windows logo" class="logo">
928f1a07 179@endhtmlonly
469e56bf 180
7ecc54df
BP
181wxMSW is a port of wxWidgets for the Windows platforms including Windows 95,
18298, ME, 2000, NT, XP and Vista in ANSI and Unicode modes (for Windows 9x and
183ME through the MSLU extension library). wxMSW ensures native look and feel for
184XP when using wxWidgets version 2.3.3 or higher.wxMSW can be compiled with a
185great variety of compilers including Microsoft Studio VC++, Borland 5.5,
186MinGW32, Cygwin and Watcom as well as cross-compilation with a Linux-hosted
928f1a07 187MinGW32 tool chain.
3c4f71cc 188
928f1a07
FM
189For further information, please see the files in docs/msw
190in the distribution.
3c4f71cc 191
928f1a07 192@subsection page_port_wxmsw_themedborders Themed borders on Windows
3c4f71cc 193
3ed3a1c8 194Starting with wxWidgets 2.8.5, you can specify the @c wxBORDER_THEME style to have wxWidgets
928f1a07
FM
195use a themed border. Using the default XP theme, this is a thin 1-pixel blue border,
196with an extra 1-pixel border in the window client background colour (usually white) to
197separate the client area's scrollbars from the border.
3c4f71cc 198
928f1a07
FM
199If you don't specify a border style for a wxTextCtrl in rich edit mode, wxWidgets now gives
200the control themed borders automatically, where previously they would take the Windows 95-style
7ecc54df 201sunken border. Other native controls such as wxTextCtrl in non-rich edit mode, and wxComboBox
928f1a07 202already paint themed borders where appropriate. To use themed borders on other windows, such
3ed3a1c8 203as wxPanel, pass the @c wxBORDER_THEME style, or (apart from wxPanel) pass no border style.
3c4f71cc 204
3ed3a1c8
BP
205In general, specifying @c wxBORDER_THEME will cause a border of some kind to be used, chosen by the platform
206and control class. To leave the border decision entirely to wxWidgets, pass @c wxBORDER_DEFAULT.
207This is not to be confused with specifying @c wxBORDER_NONE, which says that there should
928f1a07 208definitely be @e no border.
3c4f71cc 209
928f1a07 210@subsubsection page_port_wxmsw_themedborders_details More detail on border implementation
3c4f71cc 211
928f1a07
FM
212The way that wxMSW decides whether to apply a themed border is as follows.
213The theming code calls wxWindow::GetBorder() to obtain a border. If no border style has been
214passed to the window constructor, GetBorder() calls GetDefaultBorder() for this window.
215If wxBORDER_THEME was passed to the window constructor, GetBorder() calls GetDefaultBorderForControl().
3c4f71cc 216
928f1a07
FM
217The implementation of wxWindow::GetDefaultBorder() on wxMSW calls wxWindow::CanApplyThemeBorder()
218which is a virtual function that tells wxWidgets whether a control can have a theme
219applied explicitly (some native controls already paint a theme in which case we should not
220apply it ourselves). Note that wxPanel is an exception to this rule because in many cases
221we wish to create a window with no border (for example, notebook pages). So wxPanel
222overrides GetDefaultBorder() in order to call the generic wxWindowBase::GetDefaultBorder(),
223returning wxBORDER_NONE.
3c4f71cc 224
928f1a07 225@subsection page_port_wxmsw_wince wxWinCE
3c4f71cc 226
928f1a07
FM
227wxWinCE is the name given to wxMSW when compiled on Windows CE devices;
228most of wxMSW is common to Win32 and Windows CE but there are
229some simplifications, enhancements, and differences in
230behaviour.
3c4f71cc 231
928f1a07
FM
232For building instructions, see docs/msw/wince in the
233distribution, also the section about Visual Studio 2005 project
234files below. The rest of this section documents issues you
235need to be aware of when programming for Windows CE devices.
3c4f71cc 236
928f1a07 237@subsubsection page_port_wxmsw_wince_ General issues for wxWinCE programming
3c4f71cc 238
928f1a07
FM
239Mobile applications generally have fewer features and
240simpler user interfaces. Simply omit whole sizers, static
241lines and controls in your dialogs, and use comboboxes instead
242of listboxes where appropriate. You also need to reduce
243the amount of spacing used by sizers, for which you can
244use a macro such as this:
3c4f71cc 245
3ed3a1c8 246@code
928f1a07
FM
247#if defined(__WXWINCE__)
248 #define wxLARGESMALL(large,small) small
249#else
250 #define wxLARGESMALL(large,small) large
251#endif
3c4f71cc 252
928f1a07
FM
253// Usage
254topsizer->Add( CreateTextSizer( message ), 0, wxALL, wxLARGESMALL(10,0) );
3ed3a1c8 255@endcode
3c4f71cc 256
928f1a07
FM
257There is only ever one instance of a Windows CE application running,
258and wxWidgets will take care of showing the current instance and
259shutting down the second instance if necessary.
3c4f71cc 260
928f1a07
FM
261You can test the return value of wxSystemSettings::GetScreenType()
262for a qualitative assessment of what kind of display is available,
263or use wxGetDisplaySize() if you need more information.
3c4f71cc 264
928f1a07
FM
265You can also use wxGetOsVersion to test for a version of Windows CE at
266run-time (see the next section). However, because different builds
267are currently required to target different kinds of device, these
268values are hard-wired according to the build, and you cannot
269dynamically adapt the same executable for different major Windows CE
270platforms. This would require a different approach to the way
271wxWidgets adapts its behaviour (such as for menubars) to suit the
272style of device.
273
274See the "Life!" example (demos/life) for an example of
275an application that has been tailored for PocketPC and Smartphone use.
276
277@note don't forget to have this line in your .rc file, as for
278 desktop Windows applications:
279
280@verbatim #include "wx/msw/wx.rc" @endverbatim
281
282@subsubsection page_port_wxmsw_wince_sdk Testing for WinCE SDKs
283
284Use these preprocessor symbols to test for the different types of device or SDK:
285
286@li @b __SMARTPHONE__ Generic mobile devices with phone buttons and a small display
287@li @b __PDA__ Generic mobile devices with no phone
288@li @b __HANDHELDPC__ Generic mobile device with a keyboard
289@li @b __WXWINCE__ Microsoft-powered Windows CE devices, whether PocketPC, Smartphone or Standard SDK
290@li @b WIN32_PLATFORM_WFSP Microsoft-powered smartphone
291@li @b __POCKETPC__ Microsoft-powered PocketPC devices with touch-screen
292@li @b __WINCE_STANDARDSDK__ Microsoft-powered Windows CE devices, for generic Windows CE applications
293@li @b __WINCE_NET__ Microsoft-powered Windows CE .NET devices (_WIN32_WCE is 400 or greater)
294
295wxGetOsVersion will return these values:
296
297@li @b wxWINDOWS_POCKETPC The application is running under PocketPC.
298@li @b wxWINDOWS_SMARTPHONE The application is running under Smartphone.
299@li @b wxWINDOWS_CE The application is running under Windows CE (built with the Standard SDK).
300
301
302@subsubsection page_port_wxmsw_wince_sizing Window sizing in wxWinCE
303
304Top level windows (dialogs, frames) are created always full-screen. Fit() of sizers will not rescale top
305level windows but instead will scale window content.
306
307If the screen orientation changes, the windows will automatically be resized
308so no further action needs to be taken (unless you want to change the layout
309according to the orientation, which you could detect in idle time, for example).
310When input panel (SIP) is shown, top level windows (frames and dialogs) resize
3ed3a1c8 311accordingly (see wxTopLevelWindow::HandleSettingChange()).
928f1a07
FM
312
313@subsubsection page_port_wxmsw_wince_toplevel Closing top-level windows in wxWinCE
314
315You won't get a wxCloseEvent when the user clicks on the X in the titlebar
316on Smartphone and PocketPC; the window is simply hidden instead. However the system may send the
317event to force the application to close down.
318
319@subsubsection page_port_wxmsw_wince_hibernation Hibernation in wxWinCE
320
3ed3a1c8 321Smartphone and PocketPC will send a @c wxEVT_HIBERNATE to the application object in low
928f1a07 322memory conditions. Your application should release memory and close dialogs,
3ed3a1c8
BP
323and wake up again when the next @c wxEVT_ACTIVATE or @c wxEVT_ACTIVATE_APP message is received.
324(@c wxEVT_ACTIVATE_APP is generated whenever a @c wxEVT_ACTIVATE event is received
325in Smartphone and PocketPC, since these platforms do not support @c WM_ACTIVATEAPP.)
928f1a07
FM
326
327@subsubsection page_port_wxmsw_wince_hwbutt Hardware buttons in wxWinCE
328
3ed3a1c8 329Special hardware buttons are sent to a window via the @c wxEVT_HOTKEY event
928f1a07 330under Smartphone and PocketPC. You should first register each required button with
3ed3a1c8 331wxWindow::RegisterHotKey(), and unregister the button when you're done with it. For example:
928f1a07 332
3ed3a1c8 333@code
928f1a07
FM
334win->RegisterHotKey(0, wxMOD_WIN, WXK_SPECIAL1);
335win->UnregisterHotKey(0);
3ed3a1c8 336@endcode
928f1a07 337
3ed3a1c8 338You may have to register the buttons in a @c wxEVT_ACTIVATE event handler
928f1a07
FM
339since other applications will grab the buttons.
340
341There is currently no method of finding out the names of the special
342buttons or how many there are.
3c4f71cc 343
928f1a07 344@subsubsection page_port_wxmsw_wince_dialogs Dialogs in wxWinCE
3c4f71cc 345
928f1a07
FM
346PocketPC dialogs have an OK button on the caption, and so you should generally
347not repeat an OK button on the dialog. You can add a Cancel button if necessary, but some dialogs
348simply don't offer you the choice (the guidelines recommend you offer an Undo facility
349to make up for it). When the user clicks on the OK button, your dialog will receive
3ed3a1c8
BP
350a @c wxID_OK event by default. If you wish to change this, call wxDialog::SetAffirmativeId()
351with the required identifier to be used. Or, override wxDialog::DoOK() (return @false to
928f1a07 352have wxWidgets simply call Close to dismiss the dialog).
3c4f71cc 353
928f1a07
FM
354Smartphone dialogs do @e not have an OK button on the caption, and are closed
355using one of the two menu buttons. You need to assign these using wxTopLevelWindow::SetLeftMenu
3ed3a1c8 356and wxTopLevelWindow::SetRightMenu(), for example:
3c4f71cc 357
3ed3a1c8 358@code
928f1a07
FM
359#ifdef __SMARTPHONE__
360 SetLeftMenu(wxID_OK);
361 SetRightMenu(wxID_CANCEL, _("Cancel"));
362#elif defined(__POCKETPC__)
363 // No OK/Cancel buttons on PocketPC, OK on caption will close
364#else
365 topsizer->Add( CreateButtonSizer( wxOK|wxCANCEL ), 0, wxEXPAND | wxALL, 10 );
366#endif
3ed3a1c8 367@endcode
3c4f71cc 368
3ed3a1c8 369For implementing property sheets (flat tabs), use a wxNotebook with @c wxNB_FLAT|wxNB_BOTTOM
928f1a07
FM
370and have the notebook left, top and right sides overlap the dialog by about 3 pixels
371to eliminate spurious borders. You can do this by using a negative spacing in your
372sizer Add() call. The cross-platform property sheet dialog wxPropertySheetDialog is
373provided, to show settings in the correct style on PocketPC and on other platforms.
3c4f71cc 374
928f1a07
FM
375Notifications (bubble HTML text with optional buttons and links) will also be
376implemented in the future for PocketPC.
3c4f71cc 377
928f1a07
FM
378Modeless dialogs probably don't make sense for PocketPC and Smartphone, since
379frames and dialogs are normally full-screen, and a modeless dialog is normally
380intended to co-exist with the main application frame.
3c4f71cc 381
928f1a07 382@subsubsection page_port_wxmsw_wince_ppc Menubars and toolbars in PocketPC
3c4f71cc 383
928f1a07
FM
384On PocketPC, a frame must always have a menubar, even if it's empty.
385An empty menubar/toolbar is automatically provided for dialogs, to hide
386any existing menubar for the duration of the dialog.
387
388Menubars and toolbars are implemented using a combined control,
389but you can use essentially the usual wxWidgets API; wxWidgets will combine the menubar
390and toolbar. However, there are some restrictions:
391
3ed3a1c8 392@li You must create the frame's primary toolbar with wxFrame::CreateToolBar(),
928f1a07
FM
393because this uses the special wxToolMenuBar class (derived from wxToolBar)
394to implement the combined toolbar and menubar. Otherwise, you can create and manage toolbars
395using the wxToolBar class as usual, for example to implement an optional
396formatting toolbar above the menubar as Pocket Word does. But don't assign
397a wxToolBar to a frame using SetToolBar - you should always use CreateToolBar
398for the main frame toolbar.
399@li Deleting and adding tools to wxToolMenuBar after Realize is called is not supported.
400@li For speed, colours are not remapped to the system colours as they are
401in wxMSW. Provide the tool bitmaps either with the correct system button background,
402or with transparency (for example, using XPMs).
403@li Adding controls to wxToolMenuBar is not supported. However, wxToolBar supports
404controls.
405
7ecc54df 406Unlike in all other ports, a wxDialog has a wxToolBar automatically created
3ed3a1c8
BP
407for you. You may either leave it blank, or access it with wxDialog::GetToolBar()
408and add buttons, then calling wxToolBar::Realize(). You cannot set or recreate
928f1a07
FM
409the toolbar.
410
411@subsubsection page_port_wxmsw_wince_smart Menubars and toolbars in Smartphone
412
413On Smartphone, there are only two menu buttons, so a menubar is simulated
414using a nested menu on the right menu button. Any toolbars are simply ignored on
415Smartphone.
416
417@subsubsection page_port_wxmsw_wince_closing Closing windows in wxWinCE
418
419The guidelines state that applications should not have a Quit menu item,
420since the user should not have to know whether an application is in memory
421or not. The close button on a window does not call the window's
422close handler; it simply hides the window. However, the guidelines say that
423the Ctrl+Q accelerator can be used to quit the application, so wxWidgets
424defines this accelerator by default and if your application handles
425wxID_EXIT, it will do the right thing.
426
427@subsubsection page_port_wxmsw_wince_ctx Context menus in wxWinCE
428
3ed3a1c8 429To enable context menus in PocketPC, you currently need to call wxWindow::EnableContextMenu(),
928f1a07
FM
430a wxWinCE-only function. Otherwise the context menu event (wxContextMenuEvent) will
431never be sent. This API is subject to change.
432
433Context menus are not supported in Smartphone.
434
435@subsubsection page_port_wxmsw_wince_ctrl Control differences on wxWinCE
436
437These controls and styles are specific to wxWinCE:
438
3ed3a1c8 439@li wxTextCtrl The @c wxTE_CAPITALIZE style causes a CAPEDIT control to
928f1a07
FM
440be created, which capitalizes the first letter.
441
442These controls are missing from wxWinCE:
443
444@li MDI classes MDI is not supported under Windows CE.
445@li wxMiniFrame Not supported under Windows CE.
446
447Tooltips are not currently supported for controls, since on PocketPC controls with
448tooltips are distinct controls, and it will be hard to add dynamic
449tooltip support.
450
451Control borders on PocketPC and Smartphone should normally be specified with
3ed3a1c8 452@c wxBORDER_SIMPLE instead of @c wxBORDER_SUNKEN. Controls will usually adapt
928f1a07 453appropriately by virtue of their GetDefaultBorder() function, but if you
3ed3a1c8 454wish to specify a style explicitly you can use @c wxDEFAULT_CONTROL_BORDER
928f1a07
FM
455which will give a simple border on PocketPC and Smartphone, and the sunken border on
456other platforms.
457
458@subsubsection page_port_wxmsw_wince_help Online help in wxWinCE
459
460You can use the help controller wxWinceHelpController which controls
461simple @c .htm files, usually installed in the Windows directory.
462See the Windows CE reference for how to format the HTML files.
463
464@subsubsection page_port_wxmsw_wince_install Installing your PocketPC and Smartphone applications
465
466To install your application, you need to build a CAB file using
467the parameters defined in a special .inf file. The CabWiz program
468in your SDK will compile the CAB file from the .inf file and
469files that it specifies.
470
471For delivery, you can simply ask the user to copy the CAB file to the
472device and execute the CAB file using File Explorer. Or, you can
473write a program for the desktop PC that will find the ActiveSync
474Application Manager and install the CAB file on the device,
475which is obviously much easier for the user.
476
477Here are some links that may help.
478
479@li A setup builder that takes CABs and builds a setup program is at
480 http://www.eskimo.com/~scottlu/win/index.html.
481@li Sample installation files can be found in
482 <tt>Windows CE Tools/wce420/POCKET PC 2003/Samples/Win32/AppInst</tt>.
483@li An installer generator using wxPython can be found at
484 http://ppcquicksoft.iespana.es/ppcquicksoft/myinstall.html.
485@li Miscellaneous Windows CE resources can be found at
486 http://www.orbworks.com/pcce/resources.html.
487@li Installer creation instructions with a setup.exe for installing to PPC can be found at
488 http://www.pocketpcdn.com/articles/creatingsetup.html.
489@li Microsoft instructions are at
490 http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnce30/html/appinstall30.asp?frame=true
491@li Troubleshooting WinCE application installations:
492 http://support.microsoft.com/default.aspx?scid=KB;en-us;q181007
493
494You may also check out <tt>demos/life/setup/wince</tt> which contains
495scripts to create a PocketPC installation for ARM-based
496devices. In particular, @c build.bat builds the distribution and
497copies it to a directory called @c Deliver.
498
499@subsubsection page_port_wxmsw_wince_filedlg wxFileDialog in PocketPC
500
501Allowing the user to access files on memory cards, or on arbitrary
502parts of the filesystem, is a pain; the standard file dialog only
503shows folders under My Documents or folders on memory cards
504(not the system or card root directory, for example). This is
505a known problem for PocketPC developers.
506
507If you need a file dialog that allows access to all folders,
508you can use wxGenericFileDialog instead. You will need to include
509@c wx/generic/filedlgg.h.
510
511@subsubsection page_port_wxmsw_wince_evc Embedded Visual C++ Issues
512
513<b>Run-time type information</b>
514
515If you wish to use runtime type information (RTTI) with eVC++ 4, you need to download
516an extra library, @c ccrtrtti.lib, and link with it. At the time of
517writing you can get it from here:
518
519@verbatim
520http://support.microsoft.com/kb/830482/en-us
521@endverbatim
522
523Otherwise you will get linker errors similar to this:
524
525@verbatim
526wxwince26d.lib(control.obj) : error LNK2001: unresolved external symbol "const type_info::`vftable'" (??_7type_info@@6B@)
527@endverbatim
528
529<b>Windows Mobile 5.0 emulator</b>
530
531Note that there is no separate emulator configuration for Windows Mobile 5.0: the
532emulator runs the ARM code directly.
533
534<b>Visual Studio 2005 project files</b>
535
536Unfortunately, Visual Studio 2005, required to build Windows Mobile 5.0 applications,
537doesn't do a perfect job of converting the project files from eVC++ format.
538
539When you have converted the wxWidgets workspace, edit the configuration properties
540for each configuration and in the Librarian, add a relative path ..\\..\\lib to
541each library path. For example:
542<tt>..\\$(PlatformName)\\$(ConfigurationName)\\wx_mono.lib</tt>.
543
544Then, for a sample you want to compile, edit the configuration properties
545and make sure
546<tt>..\\..\\lib\\$(PlatformName)\\$(ConfigurationName)</tt>
547is in the Linker/General/Additional Library Directories property.
548Also change the Linker/Input/Additional Dependencies property to something like
549<tt>coredll.lib wx_mono.lib wx_wxjpeg.lib wx_wxpng.lib wx_wxzlib.lib wx_wxexpat.lib
550 commctrl.lib winsock.lib wininet.lib</tt>
551(since the library names in the wxWidgets workspace were changed by VS 2005).
552
7ecc54df 553Alternately, you could edit all the names to be identical to the original eVC++
928f1a07
FM
554names, but this will probably be more fiddly.
555
556@subsubsection page_port_wxmsw_wince_issues Remaining issues
557
558These are some of the remaining problems to be sorted out, and features
559to be supported.
560
561@li <b>Windows Mobile 5 issues.</b> It is not possible to get the HMENU for
562the command bar on Mobile 5, so the menubar functions need to be rewritten
563to get the individual menus without use of a menubar handle. Also the
564new Mobile 5 convention of using only two menus (and no bitmap buttons) needs to be
565considered.
566@li <b>Sizer speed.</b> Particularly for dialogs containing notebooks,
567layout seems slow. Some analysis is required.
568@li <b>Notification boxes.</b> The balloon-like notification messages, and their
569icons, should be implemented. This will be quite straightforward.
570@li <b>SIP size.</b> We need to be able to get the area taken up by the SIP (input panel),
571and the remaining area, by calling SHSipInfo. We also may need to be able to show and hide
572the SIP programmatically, with SHSipPreference. See also the <em>Input Dialogs</em> topic in
573the <em>Programming Windows CE</em> guide for more on this, and how to have dialogs
3ed3a1c8 574show the SIP automatically using the @c WC_SIPREF control.
928f1a07
FM
575@li <b>wxStaticBitmap.</b> The About box in the "Life!" demo shows a bitmap that is
576the correct size on the emulator, but too small on a VGA Pocket Loox device.
577@li <b>wxStaticLine.</b> Lines don't show up, and the documentation suggests that
3ed3a1c8 578missing styles are implemented with @c WM_PAINT.
928f1a07
FM
579@li <b>HTML control.</b> PocketPC has its own HTML control which can be used for showing
580local pages or navigating the web. We should create a version of wxHtmlWindow that uses this
581control, or have a separately-named control (wxHtmlCtrl), with a syntax as close as possible
582to wxHtmlWindow.
583@li <b>Tooltip control.</b> PocketPC uses special TTBUTTON and TTSTATIC controls for adding
584tooltips, with the tooltip separated from the label with a double tilde. We need to support
585this using SetToolTip.(Unfortunately it does not seem possible to dynamically remove the tooltip,
586so an extra style may be required.)
587@li <b>Focus.</b> In the wxPropertySheetDialog demo on Smartphone, it's not possible to navigate
588between controls. The focus handling in wxWidgets needs investigation. See in particular
589src/common/containr.cpp, and note that the default OnActivate handler in src/msw/toplevel.cpp
590sets the focus to the first child of the dialog.
591@li <b>OK button.</b> We should allow the OK button on a dialog to be optional, perhaps
3ed3a1c8 592by using @c wxCLOSE_BOX to indicate when the OK button should be displayed.
928f1a07
FM
593@li <b>Dynamic adaptation.</b> We should probably be using run-time tests more
594than preprocessor tests, so that the same WinCE application can run on different
595versions of the operating system.
596@li <b>Modeless dialogs.</b> When a modeless dialog is hidden with the OK button, it doesn't restore the
597frame's menubar. See for example the find dialog in the dialogs sample. However, the menubar is restored
598if pressing Cancel (the window is closed). This reflects the fact that modeless dialogs are
599not very useful on Windows CE; however, we could perhaps destroy/restore a modeless dialog's menubar
600on deactivation and activation.
601@li <b>Home screen plugins.</b> Figure out how to make home screen plugins for use with wxWidgets
602applications (see http://www.codeproject.com/ce/CTodayWindow.asp for inspiration).
603Although we can't use wxWidgets to create the plugin (too large), we could perhaps write
604a generic plugin that takes registry information from a given application, with
605options to display information in a particular way using icons and text from
606a specified location.
607@li <b>Further abstraction.</b> We should be able to abstract away more of the differences
608between desktop and mobile applications, in particular for sizer layout.
609@li <b>Dialog captions.</b> The blue, bold captions on dialogs - with optional help button -
610should be catered for, either by hard-wiring the capability into all dialogs and panels,
611or by providing a standard component and sizer.
612
613
614@section page_port_nativedocs Documentation for the native toolkits
615
616It's sometimes useful to interface directly with the underlying toolkit
617used by wxWidgets to e.g. use toolkit-specific features.
618In such case (or when you want to e.g. write a port-specific patch) it can be
619necessary to use the underlying toolkit API directly:
620
bce3699f
FM
621- wxMSW port uses win32 API: see MSDN docs at http://msdn2.microsoft.com/en-us/library/ms649779.aspx
622- wxGTK port uses GTK+ and other lower-level libraries; see
623 - GTK+ docs at http://library.gnome.org/devel/gtk/unstable/
624 - GDK docs at http://library.gnome.org/devel/gdk/unstable/
625 - GLib docs at http://library.gnome.org/devel/glib/unstable/
626 - GObject docs at http://library.gnome.org/devel/gobject/unstable/
627 - Pango docs at http://library.gnome.org/devel/pango/unstable/
628- wxMac port uses the Carbon API: see Carbon docs at http://developer.apple.com/carbon
629- wxCocoa port uses the Cocoa API: see Cocoa docs at http://developer.apple.com/cocoa
4514447c
FM
630
631*/