]>
Commit | Line | Data |
---|---|---|
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 |
14 | wxWidgets defines a common API across platforms, but uses the native graphical |
15 | user interface (GUI) on each platform, so your program will take on the native | |
16 | look and feel that users are familiar with. Unfortunately native toolkits and | |
17 | hardware do not always support the functionality that the wxWidgets API | |
18 | requires. This chapter collects notes about differences among supported platforms | |
19 | and 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 |
40 | wxGTK is a port of wxWidgets using the GTK+ library. |
41 | It makes use of GTK+'s native widgets wherever possible and uses | |
42 | wxWidgets' generic controls when needed. GTK+ itself has been | |
43 | ported to a number of systems, but so far only the original X11 | |
44 | version is supported. Support for other GTK+ backends is planned, | |
45 | such as the new DirectFB backend. | |
3c4f71cc | 46 | |
928f1a07 FM |
47 | All work is being done on GTK+ version 2.0 and above. Support for |
48 | GTK+ 1.2 will be deprecated in a later release. | |
3c4f71cc | 49 | |
5bb7884b | 50 | You will need GTK+ 2.6 or higher which is available from: |
3c4f71cc | 51 | |
928f1a07 | 52 | http://www.gtk.org |
3c4f71cc | 53 | |
928f1a07 | 54 | The newer version of GTK+ you use, the more native widgets and |
7ecc54df BP |
55 | features will be utilized. We have gone to great lengths to |
56 | allow compiling wxWidgets applications with the latest version of | |
928f1a07 | 57 | GTK+, with the resulting binary working on systems even with a |
7ecc54df | 58 | much earlier version of GTK+. You will have to ensure that the |
928f1a07 | 59 | application is launched with lazy symbol binding for that. |
3c4f71cc | 60 | |
928f1a07 FM |
61 | In order to configure wxWidgets to compile wxGTK you will |
62 | need use the @c --with-gtk argument to the @c configure script. | |
63 | This is the default for many systems. | |
3c4f71cc | 64 | |
928f1a07 FM |
65 | GTK+ 1.2 can still be used, albeit discouraged. For that you can |
66 | pass @c --with-gtk=1 to the @c configure script. | |
3c4f71cc | 67 | |
1dfb6ff0 | 68 | For further information, please see the files in @c docs/gtk |
928f1a07 | 69 | in 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 | 81 | wxOSX/Carbon is a port of wxWidgets for the Macintosh OS platform. |
c6b6ccd4 | 82 | Currently MacOS X 10.5 or higher are supported. wxOSX/Carbon can |
5bb7884b | 83 | be compiled both using Apple's command line developer tools |
c1098adf | 84 | as well as Apple's Xcode IDE. wxOSX/Carbon supports both the Intel |
5bb7884b RR |
85 | and PowerPC architectures and can be used to produce |
86 | "universal binaries" in order create application which can run | |
2b8471fb | 87 | both architecture. Unfortunately, wxOSX/Carbon does not support any |
5bb7884b RR |
88 | 64-bit architecture since Apple decided not to port its Carbon |
89 | API 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 |
92 | be removed entirely in a future OS version. It's recommended you look into | |
93 | switching your app over to wxOSX/Cocoa as soon as possible. | |
94 | ||
f5fd8c24 | 95 | For further information, please see the files in @c docs/osx |
928f1a07 | 96 | in the distribution. |
3c4f71cc VS |
97 | |
98 | ||
99 | ||
0f6c9085 | 100 | @subsection page_port_wxosx_cocoa wxOSX/Cocoa |
5bb7884b | 101 | |
2b8471fb | 102 | wxOSX/Cocoa is another port of wxWidgets for the Macintosh OS |
c6b6ccd4 SC |
103 | platform. Currently MacOS X 10.5 or higher are supported. |
104 | In contrast to wxOSX/Carbon, it uses the Cocoa API | |
2b8471fb KO |
105 | in place of Carbon. Much work has gone into this port and many |
106 | controls are functional, but the port has not reached the maturity | |
bce3699f | 107 | of the wxOSX/Carbon port yet. It is possible to use wxOSX/Cocoa |
5bb7884b RR |
108 | on 64-bit architectures. |
109 | ||
0f6c9085 KO |
110 | In order to configure wxWidgets to compile wxOSX/Cocoa you will |
111 | need to type: | |
112 | ||
113 | @verbatim configure --with-osx_cocoa @endverbatim | |
114 | ||
f5fd8c24 | 115 | For further information, please see the files in @c docs/osx |
1dfb6ff0 FM |
116 | in the distribution. |
117 | ||
0f6c9085 | 118 | @note There was a previous effort towards a Cocoa port called |
bce3699f | 119 | wxCocoa, which was implemented totally with Cocoa API unlike the OSX/Cocoa port |
2b8471fb | 120 | which uses OS X C APIs to share code, and while it is no longer being actively |
bce3699f | 121 | developed, 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 |
127 | wxOS2 is a port of wxWidgets for the IBM OS/2 Warp3 and Warp4 platforms. |
128 | This port is currently under construction and in beta phase. | |
469e56bf | 129 | |
1dfb6ff0 FM |
130 | For further information, please see the files in @c docs/os2 |
131 | in 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 |
141 | wxX11 is a port of wxWidgets using X11 (The X Window System) |
142 | as the underlying graphics backend. wxX11 draws its widgets | |
143 | using the wxUniversal widget set which is now part of wxWidgets. | |
144 | wxX11 is well-suited for a number of special applications such | |
145 | as those running on systems with few resources (PDAs) or for | |
bbc5b7f8 | 146 | applications which need to use a special themed look. |
3c4f71cc | 147 | |
928f1a07 FM |
148 | In order to configure wxWidgets to compile wxX11 you will |
149 | need to type: | |
3c4f71cc | 150 | |
928f1a07 | 151 | @verbatim configure --with-x11 --with-universal @endverbatim |
3c4f71cc | 152 | |
1dfb6ff0 | 153 | For further information, please see the files in @c docs/x11 |
928f1a07 FM |
154 | in the distribution. There is also a page on the use of |
155 | wxWidgets 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 | ||
165 | wxMotif is a port of wxWidgets for X11 systems using Motif libraries. | |
166 | Motif libraries provide a clean and fast user interface at the expense | |
167 | of the beauty and candy of newer interfaces like GTK. | |
168 | ||
169 | For further information, please see the files in @c docs/motif | |
170 | in 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 |
181 | wxMSW is a port of wxWidgets for the Windows platforms including Windows 95, |
182 | 98, ME, 2000, NT, XP and Vista in ANSI and Unicode modes (for Windows 9x and | |
183 | ME through the MSLU extension library). wxMSW ensures native look and feel for | |
184 | XP when using wxWidgets version 2.3.3 or higher.wxMSW can be compiled with a | |
185 | great variety of compilers including Microsoft Studio VC++, Borland 5.5, | |
186 | MinGW32, Cygwin and Watcom as well as cross-compilation with a Linux-hosted | |
928f1a07 | 187 | MinGW32 tool chain. |
3c4f71cc | 188 | |
928f1a07 FM |
189 | For further information, please see the files in docs/msw |
190 | in the distribution. | |
3c4f71cc | 191 | |
928f1a07 | 192 | @subsection page_port_wxmsw_themedborders Themed borders on Windows |
3c4f71cc | 193 | |
3ed3a1c8 | 194 | Starting with wxWidgets 2.8.5, you can specify the @c wxBORDER_THEME style to have wxWidgets |
928f1a07 FM |
195 | use a themed border. Using the default XP theme, this is a thin 1-pixel blue border, |
196 | with an extra 1-pixel border in the window client background colour (usually white) to | |
197 | separate the client area's scrollbars from the border. | |
3c4f71cc | 198 | |
928f1a07 FM |
199 | If you don't specify a border style for a wxTextCtrl in rich edit mode, wxWidgets now gives |
200 | the control themed borders automatically, where previously they would take the Windows 95-style | |
7ecc54df | 201 | sunken border. Other native controls such as wxTextCtrl in non-rich edit mode, and wxComboBox |
928f1a07 | 202 | already paint themed borders where appropriate. To use themed borders on other windows, such |
3ed3a1c8 | 203 | as wxPanel, pass the @c wxBORDER_THEME style, or (apart from wxPanel) pass no border style. |
3c4f71cc | 204 | |
3ed3a1c8 BP |
205 | In general, specifying @c wxBORDER_THEME will cause a border of some kind to be used, chosen by the platform |
206 | and control class. To leave the border decision entirely to wxWidgets, pass @c wxBORDER_DEFAULT. | |
207 | This is not to be confused with specifying @c wxBORDER_NONE, which says that there should | |
928f1a07 | 208 | definitely be @e no border. |
3c4f71cc | 209 | |
928f1a07 | 210 | @subsubsection page_port_wxmsw_themedborders_details More detail on border implementation |
3c4f71cc | 211 | |
928f1a07 FM |
212 | The way that wxMSW decides whether to apply a themed border is as follows. |
213 | The theming code calls wxWindow::GetBorder() to obtain a border. If no border style has been | |
214 | passed to the window constructor, GetBorder() calls GetDefaultBorder() for this window. | |
215 | If wxBORDER_THEME was passed to the window constructor, GetBorder() calls GetDefaultBorderForControl(). | |
3c4f71cc | 216 | |
928f1a07 FM |
217 | The implementation of wxWindow::GetDefaultBorder() on wxMSW calls wxWindow::CanApplyThemeBorder() |
218 | which is a virtual function that tells wxWidgets whether a control can have a theme | |
219 | applied explicitly (some native controls already paint a theme in which case we should not | |
220 | apply it ourselves). Note that wxPanel is an exception to this rule because in many cases | |
221 | we wish to create a window with no border (for example, notebook pages). So wxPanel | |
222 | overrides GetDefaultBorder() in order to call the generic wxWindowBase::GetDefaultBorder(), | |
223 | returning wxBORDER_NONE. | |
3c4f71cc | 224 | |
928f1a07 | 225 | @subsection page_port_wxmsw_wince wxWinCE |
3c4f71cc | 226 | |
928f1a07 FM |
227 | wxWinCE is the name given to wxMSW when compiled on Windows CE devices; |
228 | most of wxMSW is common to Win32 and Windows CE but there are | |
229 | some simplifications, enhancements, and differences in | |
230 | behaviour. | |
3c4f71cc | 231 | |
928f1a07 FM |
232 | For building instructions, see docs/msw/wince in the |
233 | distribution, also the section about Visual Studio 2005 project | |
234 | files below. The rest of this section documents issues you | |
235 | need 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 |
239 | Mobile applications generally have fewer features and |
240 | simpler user interfaces. Simply omit whole sizers, static | |
241 | lines and controls in your dialogs, and use comboboxes instead | |
242 | of listboxes where appropriate. You also need to reduce | |
243 | the amount of spacing used by sizers, for which you can | |
244 | use 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 |
254 | topsizer->Add( CreateTextSizer( message ), 0, wxALL, wxLARGESMALL(10,0) ); | |
3ed3a1c8 | 255 | @endcode |
3c4f71cc | 256 | |
928f1a07 FM |
257 | There is only ever one instance of a Windows CE application running, |
258 | and wxWidgets will take care of showing the current instance and | |
259 | shutting down the second instance if necessary. | |
3c4f71cc | 260 | |
928f1a07 FM |
261 | You can test the return value of wxSystemSettings::GetScreenType() |
262 | for a qualitative assessment of what kind of display is available, | |
263 | or use wxGetDisplaySize() if you need more information. | |
3c4f71cc | 264 | |
928f1a07 FM |
265 | You can also use wxGetOsVersion to test for a version of Windows CE at |
266 | run-time (see the next section). However, because different builds | |
267 | are currently required to target different kinds of device, these | |
268 | values are hard-wired according to the build, and you cannot | |
269 | dynamically adapt the same executable for different major Windows CE | |
270 | platforms. This would require a different approach to the way | |
271 | wxWidgets adapts its behaviour (such as for menubars) to suit the | |
272 | style of device. | |
273 | ||
274 | See the "Life!" example (demos/life) for an example of | |
275 | an 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 | ||
284 | Use 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 | ||
295 | wxGetOsVersion 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 | ||
304 | Top level windows (dialogs, frames) are created always full-screen. Fit() of sizers will not rescale top | |
305 | level windows but instead will scale window content. | |
306 | ||
307 | If the screen orientation changes, the windows will automatically be resized | |
308 | so no further action needs to be taken (unless you want to change the layout | |
309 | according to the orientation, which you could detect in idle time, for example). | |
310 | When input panel (SIP) is shown, top level windows (frames and dialogs) resize | |
3ed3a1c8 | 311 | accordingly (see wxTopLevelWindow::HandleSettingChange()). |
928f1a07 FM |
312 | |
313 | @subsubsection page_port_wxmsw_wince_toplevel Closing top-level windows in wxWinCE | |
314 | ||
315 | You won't get a wxCloseEvent when the user clicks on the X in the titlebar | |
316 | on Smartphone and PocketPC; the window is simply hidden instead. However the system may send the | |
317 | event to force the application to close down. | |
318 | ||
319 | @subsubsection page_port_wxmsw_wince_hibernation Hibernation in wxWinCE | |
320 | ||
3ed3a1c8 | 321 | Smartphone and PocketPC will send a @c wxEVT_HIBERNATE to the application object in low |
928f1a07 | 322 | memory conditions. Your application should release memory and close dialogs, |
3ed3a1c8 BP |
323 | and 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 | |
325 | in 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 | 329 | Special hardware buttons are sent to a window via the @c wxEVT_HOTKEY event |
928f1a07 | 330 | under Smartphone and PocketPC. You should first register each required button with |
3ed3a1c8 | 331 | wxWindow::RegisterHotKey(), and unregister the button when you're done with it. For example: |
928f1a07 | 332 | |
3ed3a1c8 | 333 | @code |
928f1a07 FM |
334 | win->RegisterHotKey(0, wxMOD_WIN, WXK_SPECIAL1); |
335 | win->UnregisterHotKey(0); | |
3ed3a1c8 | 336 | @endcode |
928f1a07 | 337 | |
3ed3a1c8 | 338 | You may have to register the buttons in a @c wxEVT_ACTIVATE event handler |
928f1a07 FM |
339 | since other applications will grab the buttons. |
340 | ||
341 | There is currently no method of finding out the names of the special | |
342 | buttons or how many there are. | |
3c4f71cc | 343 | |
928f1a07 | 344 | @subsubsection page_port_wxmsw_wince_dialogs Dialogs in wxWinCE |
3c4f71cc | 345 | |
928f1a07 FM |
346 | PocketPC dialogs have an OK button on the caption, and so you should generally |
347 | not repeat an OK button on the dialog. You can add a Cancel button if necessary, but some dialogs | |
348 | simply don't offer you the choice (the guidelines recommend you offer an Undo facility | |
349 | to make up for it). When the user clicks on the OK button, your dialog will receive | |
3ed3a1c8 BP |
350 | a @c wxID_OK event by default. If you wish to change this, call wxDialog::SetAffirmativeId() |
351 | with the required identifier to be used. Or, override wxDialog::DoOK() (return @false to | |
928f1a07 | 352 | have wxWidgets simply call Close to dismiss the dialog). |
3c4f71cc | 353 | |
928f1a07 FM |
354 | Smartphone dialogs do @e not have an OK button on the caption, and are closed |
355 | using one of the two menu buttons. You need to assign these using wxTopLevelWindow::SetLeftMenu | |
3ed3a1c8 | 356 | and 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 | 369 | For implementing property sheets (flat tabs), use a wxNotebook with @c wxNB_FLAT|wxNB_BOTTOM |
928f1a07 FM |
370 | and have the notebook left, top and right sides overlap the dialog by about 3 pixels |
371 | to eliminate spurious borders. You can do this by using a negative spacing in your | |
372 | sizer Add() call. The cross-platform property sheet dialog wxPropertySheetDialog is | |
373 | provided, to show settings in the correct style on PocketPC and on other platforms. | |
3c4f71cc | 374 | |
928f1a07 FM |
375 | Notifications (bubble HTML text with optional buttons and links) will also be |
376 | implemented in the future for PocketPC. | |
3c4f71cc | 377 | |
928f1a07 FM |
378 | Modeless dialogs probably don't make sense for PocketPC and Smartphone, since |
379 | frames and dialogs are normally full-screen, and a modeless dialog is normally | |
380 | intended 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 |
384 | On PocketPC, a frame must always have a menubar, even if it's empty. |
385 | An empty menubar/toolbar is automatically provided for dialogs, to hide | |
386 | any existing menubar for the duration of the dialog. | |
387 | ||
388 | Menubars and toolbars are implemented using a combined control, | |
389 | but you can use essentially the usual wxWidgets API; wxWidgets will combine the menubar | |
390 | and toolbar. However, there are some restrictions: | |
391 | ||
3ed3a1c8 | 392 | @li You must create the frame's primary toolbar with wxFrame::CreateToolBar(), |
928f1a07 FM |
393 | because this uses the special wxToolMenuBar class (derived from wxToolBar) |
394 | to implement the combined toolbar and menubar. Otherwise, you can create and manage toolbars | |
395 | using the wxToolBar class as usual, for example to implement an optional | |
396 | formatting toolbar above the menubar as Pocket Word does. But don't assign | |
397 | a wxToolBar to a frame using SetToolBar - you should always use CreateToolBar | |
398 | for 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 | |
401 | in wxMSW. Provide the tool bitmaps either with the correct system button background, | |
402 | or with transparency (for example, using XPMs). | |
403 | @li Adding controls to wxToolMenuBar is not supported. However, wxToolBar supports | |
404 | controls. | |
405 | ||
7ecc54df | 406 | Unlike in all other ports, a wxDialog has a wxToolBar automatically created |
3ed3a1c8 BP |
407 | for you. You may either leave it blank, or access it with wxDialog::GetToolBar() |
408 | and add buttons, then calling wxToolBar::Realize(). You cannot set or recreate | |
928f1a07 FM |
409 | the toolbar. |
410 | ||
411 | @subsubsection page_port_wxmsw_wince_smart Menubars and toolbars in Smartphone | |
412 | ||
413 | On Smartphone, there are only two menu buttons, so a menubar is simulated | |
414 | using a nested menu on the right menu button. Any toolbars are simply ignored on | |
415 | Smartphone. | |
416 | ||
417 | @subsubsection page_port_wxmsw_wince_closing Closing windows in wxWinCE | |
418 | ||
419 | The guidelines state that applications should not have a Quit menu item, | |
420 | since the user should not have to know whether an application is in memory | |
421 | or not. The close button on a window does not call the window's | |
422 | close handler; it simply hides the window. However, the guidelines say that | |
423 | the Ctrl+Q accelerator can be used to quit the application, so wxWidgets | |
424 | defines this accelerator by default and if your application handles | |
425 | wxID_EXIT, it will do the right thing. | |
426 | ||
427 | @subsubsection page_port_wxmsw_wince_ctx Context menus in wxWinCE | |
428 | ||
3ed3a1c8 | 429 | To enable context menus in PocketPC, you currently need to call wxWindow::EnableContextMenu(), |
928f1a07 FM |
430 | a wxWinCE-only function. Otherwise the context menu event (wxContextMenuEvent) will |
431 | never be sent. This API is subject to change. | |
432 | ||
433 | Context menus are not supported in Smartphone. | |
434 | ||
435 | @subsubsection page_port_wxmsw_wince_ctrl Control differences on wxWinCE | |
436 | ||
437 | These controls and styles are specific to wxWinCE: | |
438 | ||
3ed3a1c8 | 439 | @li wxTextCtrl The @c wxTE_CAPITALIZE style causes a CAPEDIT control to |
928f1a07 FM |
440 | be created, which capitalizes the first letter. |
441 | ||
442 | These 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 | ||
447 | Tooltips are not currently supported for controls, since on PocketPC controls with | |
448 | tooltips are distinct controls, and it will be hard to add dynamic | |
449 | tooltip support. | |
450 | ||
451 | Control 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 | 453 | appropriately by virtue of their GetDefaultBorder() function, but if you |
3ed3a1c8 | 454 | wish to specify a style explicitly you can use @c wxDEFAULT_CONTROL_BORDER |
928f1a07 FM |
455 | which will give a simple border on PocketPC and Smartphone, and the sunken border on |
456 | other platforms. | |
457 | ||
458 | @subsubsection page_port_wxmsw_wince_help Online help in wxWinCE | |
459 | ||
460 | You can use the help controller wxWinceHelpController which controls | |
461 | simple @c .htm files, usually installed in the Windows directory. | |
462 | See 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 | ||
466 | To install your application, you need to build a CAB file using | |
467 | the parameters defined in a special .inf file. The CabWiz program | |
468 | in your SDK will compile the CAB file from the .inf file and | |
469 | files that it specifies. | |
470 | ||
471 | For delivery, you can simply ask the user to copy the CAB file to the | |
472 | device and execute the CAB file using File Explorer. Or, you can | |
473 | write a program for the desktop PC that will find the ActiveSync | |
474 | Application Manager and install the CAB file on the device, | |
475 | which is obviously much easier for the user. | |
476 | ||
477 | Here 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 | ||
494 | You may also check out <tt>demos/life/setup/wince</tt> which contains | |
495 | scripts to create a PocketPC installation for ARM-based | |
496 | devices. In particular, @c build.bat builds the distribution and | |
497 | copies it to a directory called @c Deliver. | |
498 | ||
499 | @subsubsection page_port_wxmsw_wince_filedlg wxFileDialog in PocketPC | |
500 | ||
501 | Allowing the user to access files on memory cards, or on arbitrary | |
502 | parts of the filesystem, is a pain; the standard file dialog only | |
503 | shows folders under My Documents or folders on memory cards | |
504 | (not the system or card root directory, for example). This is | |
505 | a known problem for PocketPC developers. | |
506 | ||
507 | If you need a file dialog that allows access to all folders, | |
508 | you 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 | ||
515 | If you wish to use runtime type information (RTTI) with eVC++ 4, you need to download | |
516 | an extra library, @c ccrtrtti.lib, and link with it. At the time of | |
517 | writing you can get it from here: | |
518 | ||
519 | @verbatim | |
520 | http://support.microsoft.com/kb/830482/en-us | |
521 | @endverbatim | |
522 | ||
523 | Otherwise you will get linker errors similar to this: | |
524 | ||
525 | @verbatim | |
526 | wxwince26d.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 | ||
531 | Note that there is no separate emulator configuration for Windows Mobile 5.0: the | |
532 | emulator runs the ARM code directly. | |
533 | ||
534 | <b>Visual Studio 2005 project files</b> | |
535 | ||
536 | Unfortunately, Visual Studio 2005, required to build Windows Mobile 5.0 applications, | |
537 | doesn't do a perfect job of converting the project files from eVC++ format. | |
538 | ||
539 | When you have converted the wxWidgets workspace, edit the configuration properties | |
540 | for each configuration and in the Librarian, add a relative path ..\\..\\lib to | |
541 | each library path. For example: | |
542 | <tt>..\\$(PlatformName)\\$(ConfigurationName)\\wx_mono.lib</tt>. | |
543 | ||
544 | Then, for a sample you want to compile, edit the configuration properties | |
545 | and make sure | |
546 | <tt>..\\..\\lib\\$(PlatformName)\\$(ConfigurationName)</tt> | |
547 | is in the Linker/General/Additional Library Directories property. | |
548 | Also 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 | 553 | Alternately, you could edit all the names to be identical to the original eVC++ |
928f1a07 FM |
554 | names, but this will probably be more fiddly. |
555 | ||
556 | @subsubsection page_port_wxmsw_wince_issues Remaining issues | |
557 | ||
558 | These are some of the remaining problems to be sorted out, and features | |
559 | to be supported. | |
560 | ||
561 | @li <b>Windows Mobile 5 issues.</b> It is not possible to get the HMENU for | |
562 | the command bar on Mobile 5, so the menubar functions need to be rewritten | |
563 | to get the individual menus without use of a menubar handle. Also the | |
564 | new Mobile 5 convention of using only two menus (and no bitmap buttons) needs to be | |
565 | considered. | |
566 | @li <b>Sizer speed.</b> Particularly for dialogs containing notebooks, | |
567 | layout seems slow. Some analysis is required. | |
568 | @li <b>Notification boxes.</b> The balloon-like notification messages, and their | |
569 | icons, 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), | |
571 | and the remaining area, by calling SHSipInfo. We also may need to be able to show and hide | |
572 | the SIP programmatically, with SHSipPreference. See also the <em>Input Dialogs</em> topic in | |
573 | the <em>Programming Windows CE</em> guide for more on this, and how to have dialogs | |
3ed3a1c8 | 574 | show 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 |
576 | the 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 | 578 | missing 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 |
580 | local pages or navigating the web. We should create a version of wxHtmlWindow that uses this | |
581 | control, or have a separately-named control (wxHtmlCtrl), with a syntax as close as possible | |
582 | to wxHtmlWindow. | |
583 | @li <b>Tooltip control.</b> PocketPC uses special TTBUTTON and TTSTATIC controls for adding | |
584 | tooltips, with the tooltip separated from the label with a double tilde. We need to support | |
585 | this using SetToolTip.(Unfortunately it does not seem possible to dynamically remove the tooltip, | |
586 | so an extra style may be required.) | |
587 | @li <b>Focus.</b> In the wxPropertySheetDialog demo on Smartphone, it's not possible to navigate | |
588 | between controls. The focus handling in wxWidgets needs investigation. See in particular | |
589 | src/common/containr.cpp, and note that the default OnActivate handler in src/msw/toplevel.cpp | |
590 | sets 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 | 592 | by 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 |
594 | than preprocessor tests, so that the same WinCE application can run on different | |
595 | versions 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 | |
597 | frame's menubar. See for example the find dialog in the dialogs sample. However, the menubar is restored | |
598 | if pressing Cancel (the window is closed). This reflects the fact that modeless dialogs are | |
599 | not very useful on Windows CE; however, we could perhaps destroy/restore a modeless dialog's menubar | |
600 | on deactivation and activation. | |
601 | @li <b>Home screen plugins.</b> Figure out how to make home screen plugins for use with wxWidgets | |
602 | applications (see http://www.codeproject.com/ce/CTodayWindow.asp for inspiration). | |
603 | Although we can't use wxWidgets to create the plugin (too large), we could perhaps write | |
604 | a generic plugin that takes registry information from a given application, with | |
605 | options to display information in a particular way using icons and text from | |
606 | a specified location. | |
607 | @li <b>Further abstraction.</b> We should be able to abstract away more of the differences | |
608 | between 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 - | |
610 | should be catered for, either by hard-wiring the capability into all dialogs and panels, | |
611 | or by providing a standard component and sizer. | |
612 | ||
613 | ||
614 | @section page_port_nativedocs Documentation for the native toolkits | |
615 | ||
616 | It's sometimes useful to interface directly with the underlying toolkit | |
617 | used by wxWidgets to e.g. use toolkit-specific features. | |
618 | In such case (or when you want to e.g. write a port-specific patch) it can be | |
619 | necessary 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 | */ |