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