]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/wxmsw.tex
interface headers reviewed
[wxWidgets.git] / docs / latex / wx / wxmsw.tex
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %% Name: wxmsw.tex
3 %% Purpose: wxMSW and wxWinCE platform specific informations
4 %% Author: wxWidgets Team
5 %% Modified by:
6 %% Created:
7 %% RCS-ID: $Id$
8 %% Copyright: (c) wxWidgets Team
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12 \section{wxMSW port}\label{wxmswport}
13
14 wxMSW is a port of wxWidgets for the Windows platforms
15 including Windows 95, 98, ME, 2000, NT, XP in ANSI and
16 Unicode mode (for Windows 95 through the MSLU extension
17 library). wxMSW ensures native look and feel for XP
18 as well when using wxWidgets version 2.3.3 or higher.
19 wxMSW can be compile with a great variety of compilers
20 including MS VC++, Borland 5.5, MinGW32, Cygwin and
21 Watcom as well as cross-compilation with a Linux hosted
22 MinGW32 tool chain.
23
24 For further information, please see the files in docs/msw
25 in the distribution.
26
27 \subsection{Themed borders on Windows}\label{wxmswthemedborders}
28
29 Starting with wxWidgets 2.8.5, you can specify the wxBORDER\_THEME style to have wxWidgets
30 use a themed border. Using the default XP theme, this is a thin 1-pixel blue border,
31 with an extra 1-pixel border in the window client background colour (usually white) to
32 separate the client area's scrollbars from the border.
33
34 If you don't specify a border style for a wxTextCtrl in rich edit mode, wxWidgets now gives
35 the control themed borders automatically, where previously they would take the Windows 95-style
36 sunken border. Other native controls such as wxTextCtrl in non-rich edit mode, and wxComboBox,
37 already paint themed borders where appropriate. To use themed borders on other windows, such
38 as wxPanel, pass the wxBORDER\_THEME style, or (apart from wxPanel) pass no border style.
39
40 In general, specifying wxBORDER\_THEME will cause a border of some kind to be used, chosen by the platform
41 and control class. To leave the border decision entirely to wxWidgets, pass wxBORDER\_DEFAULT.
42 This is not to be confused with specifying wxBORDER\_NONE, which says that there should
43 definitely be {\it no} border.
44
45 \wxheading{More detail on border implementation}
46
47 The way that wxMSW decides whether to apply a themed border is as follows.
48 The theming code calls wxWindow::GetBorder() to obtain a border. If no border style has been
49 passed to the window constructor, GetBorder() calls GetDefaultBorder() for this window.
50 If wxBORDER\_THEME was passed to the window constructor, GetBorder() calls GetDefaultBorderForControl().
51
52 The implementation of wxWindow::GetDefaultBorder() on wxMSW calls wxWindow::CanApplyThemeBorder()
53 which is a virtual function that tells wxWidgets whether a control can have a theme
54 applied explicitly (some native controls already paint a theme in which case we should not
55 apply it ourselves). Note that wxPanel is an exception to this rule because in many cases
56 we wish to create a window with no border (for example, notebook pages). So wxPanel
57 overrides GetDefaultBorder() in order to call the generic wxWindowBase::GetDefaultBorder(),
58 returning wxBORDER\_NONE.
59
60 \subsection{wxWinCE}\label{wxwince}
61
62 wxWinCE is the name given to wxMSW when compiled on Windows CE devices;
63 most of wxMSW is common to Win32 and Windows CE but there are
64 some simplifications, enhancements, and differences in
65 behaviour.
66
67 For building instructions, see docs/msw/wince in the
68 distribution, also the section about Visual Studio 2005 project
69 files below. The rest of this section documents issues you
70 need to be aware of when programming for Windows CE devices.
71
72 \subsubsection{General issues for wxWinCE programming}
73
74 Mobile applications generally have fewer features and
75 simpler user interfaces. Simply omit whole sizers, static
76 lines and controls in your dialogs, and use comboboxes instead
77 of listboxes where appropriate. You also need to reduce
78 the amount of spacing used by sizers, for which you can
79 use a macro such as this:
80
81 \begin{verbatim}
82 #if defined(__WXWINCE__)
83 #define wxLARGESMALL(large,small) small
84 #else
85 #define wxLARGESMALL(large,small) large
86 #endif
87
88 // Usage
89 topsizer->Add( CreateTextSizer( message ), 0, wxALL, wxLARGESMALL(10,0) );
90 \end{verbatim}
91
92 There is only ever one instance of a Windows CE application running,
93 and wxWidgets will take care of showing the current instance and
94 shutting down the second instance if necessary.
95
96 You can test the return value of wxSystemSettings::GetScreenType()
97 for a qualitative assessment of what kind of display is available,
98 or use wxGetDisplaySize() if you need more information.
99
100 You can also use wxGetOsVersion to test for a version of Windows CE at
101 run-time (see the next section). However, because different builds
102 are currently required to target different kinds of device, these
103 values are hard-wired according to the build, and you cannot
104 dynamically adapt the same executable for different major Windows CE
105 platforms. This would require a different approach to the way
106 wxWidgets adapts its behaviour (such as for menubars) to suit the
107 style of device.
108
109 See the "Life!" example (demos/life) for an example of
110 an application that has been tailored for PocketPC and Smartphone use.
111
112 {\bf Note:} don't forget to have this line in your .rc file, as for
113 desktop Windows applications:
114
115 \begin{verbatim}
116 #include "wx/msw/wx.rc"
117 \end{verbatim}
118
119 \subsubsection{Testing for WinCE SDKs}
120
121 Use these preprocessor symbols to test for the different types of device or SDK:
122
123 \begin{twocollist}\itemsep=0pt
124 \twocolitem{\_\_SMARTPHONE\_\_}{Generic mobile devices with phone buttons and a small display}
125 \twocolitem{\_\_PDA\_\_}{Generic mobile devices with no phone}
126 \twocolitem{\_\_HANDHELDPC\_\_}{Generic mobile device with a keyboard}
127 \twocolitem{\_\_WXWINCE\_\_}{Microsoft-powered Windows CE devices, whether PocketPC, Smartphone or Standard SDK}
128 \twocolitem{WIN32\_PLATFORM\_WFSP}{Microsoft-powered smartphone}
129 \twocolitem{\_\_POCKETPC\_\_}{Microsoft-powered PocketPC devices with touch-screen}
130 \twocolitem{\_\_WINCE\_STANDARDSDK\_\_}{Microsoft-powered Windows CE devices, for generic Windows CE applications}
131 \twocolitem{\_\_WINCE\_NET\_\_}{Microsoft-powered Windows CE .NET devices (\_WIN32\_WCE is 400 or greater)}
132 \end{twocollist}
133
134 wxGetOsVersion will return these values:
135
136 \begin{twocollist}\itemsep=0pt
137 \twocolitem{wxWINDOWS\_POCKETPC}{The application is running under PocketPC.}
138 \twocolitem{wxWINDOWS\_SMARTPHONE}{The application is running under Smartphone.}
139 \twocolitem{wxWINDOWS\_CE}{The application is running under Windows CE (built with the Standard SDK).}
140 \end{twocollist}
141
142 \subsubsection{Window sizing in wxWinCE}
143
144 Top level windows (dialogs, frames) are created always full-screen. Fit() of sizers will not rescale top
145 level windows but instead will scale window content.
146
147 If the screen orientation changes, the windows will automatically be resized
148 so no further action needs to be taken (unless you want to change the layout
149 according to the orientation, which you could detect in idle time, for example).
150 When input panel (SIP) is shown, top level windows (frames and dialogs) resize
151 accordingly (see \helpref{wxTopLevelWindow::HandleSettingChange}{wxtoplevelwindowhandlesettingchange}).
152
153 \subsubsection{Closing top-level windows in wxWinCE}
154
155 You won't get a wxCloseEvent when the user clicks on the X in the titlebar
156 on Smartphone and PocketPC; the window is simply hidden instead. However the system may send the
157 event to force the application to close down.
158
159 \subsubsection{Hibernation in wxWinCE}
160
161 Smartphone and PocketPC will send a wxEVT\_HIBERNATE to the application object in low
162 memory conditions. Your application should release memory and close dialogs,
163 and wake up again when the next wxEVT\_ACTIVATE or wxEVT\_ACTIVATE\_APP message is received.
164 (wxEVT\_ACTIVATE\_APP is generated whenever a wxEVT\_ACTIVATE event is received
165 in Smartphone and PocketPC, since these platforms do not support WM\_ACTIVATEAPP.)
166
167 \subsubsection{Hardware buttons in wxWinCE}
168
169 Special hardware buttons are sent to a window via the wxEVT\_HOTKEY event
170 under Smartphone and PocketPC. You should first register each required button with \helpref{wxWindow::RegisterHotKey}{wxwindowregisterhotkey},
171 and unregister the button when you're done with it. For example:
172
173 \begin{verbatim}
174 win->RegisterHotKey(0, wxMOD_WIN, WXK_SPECIAL1);
175 win->UnregisterHotKey(0);
176 \end{verbatim}
177
178 You may have to register the buttons in a wxEVT\_ACTIVATE event handler
179 since other applications will grab the buttons.
180
181 There is currently no method of finding out the names of the special
182 buttons or how many there are.
183
184 \subsubsection{Dialogs in wxWinCE}
185
186 PocketPC dialogs have an OK button on the caption, and so you should generally
187 not repeat an OK button on the dialog. You can add a Cancel button if necessary, but some dialogs
188 simply don't offer you the choice (the guidelines recommend you offer an Undo facility
189 to make up for it). When the user clicks on the OK button, your dialog will receive
190 a wxID\_OK event by default. If you wish to change this, call \helpref{wxDialog::SetAffirmativeId}{wxdialogsetaffirmativeid}
191 with the required identifier to be used. Or, override \helpref{wxDialog::DoOK}{wxdialogdook} (return false to
192 have wxWidgets simply call Close to dismiss the dialog).
193
194 Smartphone dialogs do {\it not} have an OK button on the caption, and are closed
195 using one of the two menu buttons. You need to assign these using \helpref{wxTopLevelWindow::SetLeftMenu}{wxtoplevelwindowsetleftmenu}
196 and \helpref{wxTopLevelWindow::SetRightMenu}{wxtoplevelwindowsetrightmenu}, for example:
197
198 \begin{verbatim}
199 #ifdef __SMARTPHONE__
200 SetLeftMenu(wxID_OK);
201 SetRightMenu(wxID_CANCEL, _("Cancel"));
202 #elif defined(__POCKETPC__)
203 // No OK/Cancel buttons on PocketPC, OK on caption will close
204 #else
205 topsizer->Add( CreateButtonSizer( wxOK|wxCANCEL ), 0, wxEXPAND | wxALL, 10 );
206 #endif
207 \end{verbatim}
208
209 For implementing property sheets (flat tabs), use a wxNotebook with wxNB\_FLAT|wxNB\_BOTTOM
210 and have the notebook left, top and right sides overlap the dialog by about 3 pixels
211 to eliminate spurious borders. You can do this by using a negative spacing in your
212 sizer Add() call. The cross-platform property sheet dialog \helpref{wxPropertySheetDialog}{wxpropertysheetdialog} is
213 provided, to show settings in the correct style on PocketPC and on other platforms.
214
215 Notifications (bubble HTML text with optional buttons and links) will also be
216 implemented in the future for PocketPC.
217
218 Modeless dialogs probably don't make sense for PocketPC and Smartphone, since
219 frames and dialogs are normally full-screen, and a modeless dialog is normally
220 intended to co-exist with the main application frame.
221
222 \subsubsection{Menubars and toolbars in wxWinCE}
223
224 \wxheading{Menubars and toolbars in PocketPC}
225
226 On PocketPC, a frame must always have a menubar, even if it's empty.
227 An empty menubar/toolbar is automatically provided for dialogs, to hide
228 any existing menubar for the duration of the dialog.
229
230 Menubars and toolbars are implemented using a combined control,
231 but you can use essentially the usual wxWidgets API; wxWidgets will combine the menubar
232 and toolbar. However, there are some restrictions:
233
234 \itemsep=0pt
235 \begin{itemize}
236 \item You must create the frame's primary toolbar with wxFrame::CreateToolBar,
237 because this uses the special wxToolMenuBar class (derived from wxToolBar)
238 to implement the combined toolbar and menubar. Otherwise, you can create and manage toolbars
239 using the wxToolBar class as usual, for example to implement an optional
240 formatting toolbar above the menubar as Pocket Word does. But don't assign
241 a wxToolBar to a frame using SetToolBar - you should always use CreateToolBar
242 for the main frame toolbar.
243 \item Deleting and adding tools to wxToolMenuBar after Realize is called is not supported.
244 \item For speed, colours are not remapped to the system colours as they are
245 in wxMSW. Provide the tool bitmaps either with the correct system button background,
246 or with transparency (for example, using XPMs).
247 \item Adding controls to wxToolMenuBar is not supported. However, wxToolBar supports
248 controls.
249 \end{itemize}
250
251 Unlike in all other ports, a wxDialog has a wxToolBar, automatically created
252 for you. You may either leave it blank, or access it with wxDialog::GetToolBar
253 and add buttons, then calling wxToolBar::Realize. You cannot set or recreate
254 the toolbar.
255
256 \wxheading{Menubars and toolbars in Smartphone}
257
258 On Smartphone, there are only two menu buttons, so a menubar is simulated
259 using a nested menu on the right menu button. Any toolbars are simply ignored on
260 Smartphone.
261
262 \subsubsection{Closing windows in wxWinCE}
263
264 The guidelines state that applications should not have a Quit menu item,
265 since the user should not have to know whether an application is in memory
266 or not. The close button on a window does not call the window's
267 close handler; it simply hides the window. However, the guidelines say that
268 the Ctrl+Q accelerator can be used to quit the application, so wxWidgets
269 defines this accelerator by default and if your application handles
270 wxID\_EXIT, it will do the right thing.
271
272 \subsubsection{Context menus in wxWinCE}
273
274 To enable context menus in PocketPC, you currently need to call wxWindow::EnableContextMenu,
275 a wxWinCE-only function. Otherwise the context menu event (wxContextMenuEvent) will
276 never be sent. This API is subject to change.
277
278 Context menus are not supported in Smartphone.
279
280 \subsubsection{Control differences on wxWinCE}
281
282 These controls and styles are specific to wxWinCE:
283
284 \itemsep=0pt
285 \begin{itemize}
286 \item {\bf wxTextCtrl} The wxTE\_CAPITALIZE style causes a CAPEDIT control to
287 be created, which capitalizes the first letter.
288 \end{itemize}
289
290 These controls are missing from wxWinCE:
291
292 \itemsep=0pt
293 \begin{itemize}
294 \item {\bf MDI classes} MDI is not supported under Windows CE.
295 \item {\bf wxMiniFrame} Not supported under Windows CE.
296 \end{itemize}
297
298 Tooltips are not currently supported for controls, since on PocketPC controls with
299 tooltips are distinct controls, and it will be hard to add dynamic
300 tooltip support.
301
302 Control borders on PocketPC and Smartphone should normally be specified with
303 wxBORDER\_SIMPLE instead of wxBORDER\_SUNKEN. Controls will usually adapt
304 appropriately by virtue of their GetDefaultBorder() function, but if you
305 wish to specify a style explicitly you can use wxDEFAULT\_CONTROL\_BORDER
306 which will give a simple border on PocketPC and Smartphone, and the sunken border on
307 other platforms.
308
309 \subsubsection{Online help in wxWinCE}
310
311 You can use the help controller wxWinceHelpController which controls
312 simple {\tt .htm} files, usually installed in the Windows directory.
313 See the Windows CE reference for how to format the HTML files.
314
315 \subsubsection{Installing your PocketPC and Smartphone applications}
316
317 To install your application, you need to build a CAB file using
318 the parameters defined in a special .inf file. The CabWiz program
319 in your SDK will compile the CAB file from the .inf file and
320 files that it specifies.
321
322 For delivery, you can simply ask the user to copy the CAB file to the
323 device and execute the CAB file using File Explorer. Or, you can
324 write a program for the desktop PC that will find the ActiveSync
325 Application Manager and install the CAB file on the device,
326 which is obviously much easier for the user.
327
328 Here are some links that may help.
329
330 \itemsep=0pt
331 \begin{itemize}
332 \item A setup builder that takes CABs and builds a setup program is at \urlref{http://www.eskimo.com/~scottlu/win/index.html}{http://www.eskimo.com/~scottlu/win/index.html}.
333 \item Sample installation files can be found in {\tt Windows CE Tools/wce420/POCKET PC 2003/Samples/Win32/AppInst}.
334 \item An installer generator using wxPython can be found at \urlref{http://ppcquicksoft.iespana.es/ppcquicksoft/myinstall.html}{http://ppcquicksoft.iespana.es/ppcquicksoft/myinstall.html}.
335 \item Miscellaneous Windows CE resources can be found at \urlref{http://www.orbworks.com/pcce/resources.html}{http://www.orbworks.com/pcce/resources.html}.
336 \item Installer creation instructions with a setup.exe for installing to PPC can be found at \urlref{http://www.pocketpcdn.com/articles/creatingsetup.html}{http://www.pocketpcdn.com/articles/creatingsetup.html}.
337 \item Microsoft instructions are at \urlref{http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnce30/html/appinstall30.asp?frame=true&hidetoc=true}{http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnce30/html/appinstall30.asp?frame=true&hidetoc=true}.
338 \item Troubleshooting WinCE application installations: \urlref{http://support.microsoft.com/default.aspx?scid=KB;en-us;q181007}{http://support.microsoft.com/default.aspx?scid=KB;en-us;q181007}
339 \end{itemize}
340
341 You may also check out {\tt demos/life/setup/wince} which contains
342 scripts to create a PocketPC installation for ARM-based
343 devices. In particular, {\tt build.bat} builds the distribution and
344 copies it to a directory called {\tt Deliver}.
345
346 \subsubsection{wxFileDialog in PocketPC}
347
348 Allowing the user to access files on memory cards, or on arbitrary
349 parts of the filesystem, is a pain; the standard file dialog only
350 shows folders under My Documents or folders on memory cards
351 (not the system or card root directory, for example). This is
352 a known problem for PocketPC developers.
353
354 If you need a file dialog that allows access to all folders,
355 you can use wxGenericFileDialog instead. You will need to include
356 {\tt wx/generic/filedlgg.h}.
357
358 \subsubsection{Embedded Visual C++ Issues}
359
360 \wxheading{Run-time type information}
361
362 If you wish to use runtime type information (RTTI) with eVC++ 4, you need to download
363 an extra library, {\tt ccrtrtti.lib}, and link with it. At the time of
364 writing you can get it from here:
365
366 \begin{verbatim}
367 http://support.microsoft.com/kb/830482/en-us
368 \end{verbatim}
369
370 Otherwise you will get linker errors similar to this:
371
372 \begin{verbatim}
373 wxwince26d.lib(control.obj) : error LNK2001: unresolved external symbol "const type_info::`vftable'" (??_7type_info@@6B@)
374 \end{verbatim}
375
376 \wxheading{Windows Mobile 5.0 emulator}
377
378 Note that there is no separate emulator configuration for Windows Mobile 5.0: the
379 emulator runs the ARM code directly.
380
381 \wxheading{Visual Studio 2005 project files}
382
383 Unfortunately, Visual Studio 2005, required to build Windows Mobile 5.0 applications,
384 doesn't do a perfect job of converting the project files from eVC++ format.
385
386 When you have converted the wxWidgets workspace, edit the configuration properties
387 for each configuration and in the Librarian, add a relative path ..$\backslash$..$\backslash$lib to
388 each library path. For example: {\tt ..$\backslash$\$(PlatformName)$\backslash$\$(ConfigurationName)$\backslash$wx\_mono.lib}.
389
390 Then, for a sample you want to compile, edit the configuration properties
391 and make sure {\tt ..$\backslash$..$\backslash$lib$\backslash$\$(PlatformName)$\backslash$\$(ConfigurationName)} is in the Linker/General/Additional
392 Library Directories property. Also change the Linker/Input/Additional Dependencies
393 property to something like {\tt coredll.lib wx\_mono.lib wx\_wxjpeg.lib wx\_wxpng.lib wx\_wxzlib.lib wx\_wxexpat.lib commctrl.lib winsock.lib wininet.lib}\rtfsp
394 (since the library names in the wxWidgets workspace were changed by VS 2005).
395
396 Alternately, you could could edit all the names to be identical to the original eVC++
397 names, but this will probably be more fiddly.
398
399 \subsubsection{Remaining issues}
400
401 These are some of the remaining problems to be sorted out, and features
402 to be supported.
403
404 \itemsep=0pt
405 \begin{itemize}
406 \item {\bf Windows Mobile 5 issues.} It is not possible to get the HMENU for
407 the command bar on Mobile 5, so the menubar functions need to be rewritten
408 to get the individual menus without use of a menubar handle. Also the
409 new Mobile 5 convention of using only two menus (and no bitmap buttons) needs to be
410 considered.
411 \item {\bf Sizer speed.} Particularly for dialogs containing notebooks,
412 layout seems slow. Some analysis is required.
413 \item {\bf Notification boxes.} The balloon-like notification messages, and their
414 icons, should be implemented. This will be quite straightforward.
415 \item {\bf SIP size.} We need to be able to get the area taken up by the SIP (input panel),
416 and the remaining area, by calling SHSipInfo. We also may need to be able to show and hide
417 the SIP programmatically, with SHSipPreference. See also the {\it Input Dialogs} topic in
418 the {\it Programming Windows CE} guide for more on this, and how to have dialogs
419 show the SIP automatically using the WC\_SIPREF control.
420 \item {\bf wxStaticBitmap.} The About box in the "Life!" demo shows a bitmap that is
421 the correct size on the emulator, but too small on a VGA Pocket Loox device.
422 \item {\bf wxStaticLine.} Lines don't show up, and the documentation suggests that
423 missing styles are implemented with WM\_PAINT.
424 \item {\bf HTML control.} PocketPC has its own HTML control which can be used for showing
425 local pages or navigating the web. We should create a version of wxHtmlWindow that uses this
426 control, or have a separately-named control (wxHtmlCtrl), with a syntax as close as possible to wxHtmlWindow.
427 \item {\bf Tooltip control.} PocketPC uses special TTBUTTON and TTSTATIC controls for adding
428 tooltips, with the tooltip separated from the label with a double tilde. We need to support this using SetToolTip.
429 (Unfortunately it does not seem possible to dynamically remove the tooltip, so an extra style may
430 be required.)
431 \item {\bf Focus.} In the wxPropertySheetDialog demo on Smartphone, it's not possible to navigate
432 between controls. The focus handling in wxWidgets needs investigation. See in particular src/common/containr.cpp,
433 and note that the default OnActivate handler in src/msw/toplevel.cpp sets the focus to the first child of the dialog.
434 \item {\bf OK button.} We should allow the OK button on a dialog to be optional, perhaps
435 by using wxCLOSE\_BOX to indicate when the OK button should be displayed.
436 \item {\bf Dynamic adaptation.} We should probably be using run-time tests more
437 than preprocessor tests, so that the same WinCE application can run on different
438 versions of the operating system.
439 \item {\bf Modeless dialogs.} When a modeless dialog is hidden with the OK button, it doesn't restore the
440 frame's menubar. See for example the find dialog in the dialogs sample. However, the menubar is restored
441 if pressing Cancel (the window is closed). This reflects the fact that modeless dialogs are
442 not very useful on Windows CE; however, we could perhaps destroy/restore a modeless dialog's menubar
443 on deactivation and activation.
444 \item {\bf Home screen plugins.} Figure out how to make home screen plugins for use with wxWidgets
445 applications (see {\tt http://www.codeproject.com/ce/CTodayWindow.asp} for inspiration).
446 Although we can't use wxWidgets to create the plugin (too large), we could perhaps write
447 a generic plugin that takes registry information from a given application, with
448 options to display information in a particular way using icons and text from
449 a specified location.
450 \item {\bf Further abstraction.} We should be able to abstract away more of the differences
451 between desktop and mobile applications, in particular for sizer layout.
452 \item {\bf Dialog captions.} The blue, bold captions on dialogs - with optional help button -
453 should be catered for, either by hard-wiring the capability into all dialogs and panels,
454 or by providing a standard component and sizer.
455 \end{itemize}
456