docs/latex/wx/wxmsw.tex

   1 \section{wxMSW port}\label{wxmswport}
   2
   3 wxMSW is a port of wxWidgets for the Windows platforms
   4 including Windows 95, 98, ME, 2000, NT, XP in ANSI and
   5 Unicode mode (for Windows 95 through the MSLU extension
   6 library). wxMSW ensures native look and feel for XP
   7 as well when using wxWidgets version 2.3.3 or higher.
   8 wxMSW can be compile with a great variety of compilers
   9 including MS VC++, Borland 5.5, MinGW32, Cygwin and
  10 Watcom as well as cross-compilation with a Linux hosted
  11 MinGW32 tool chain.
  12
  13 For further information, please see the files in docs/msw
  14 in the distribution.
  15
  16 \subsection{wxWinCE}\label{wxwince}
  17
  18 wxWinCE is the name given to wxMSW when compiled on Windows CE devices;
  19 most of wxMSW is common to Win32 and Windows CE but there are
  20 some simplifications, enhancements, and differences in
  21 behaviour.
  22
  23 For installation instructions, see docs/msw/wince in the
  24 distribution. The rest of this section documents issues you
  25 need to be aware of when programming for Windows CE devices.
  26
  27 \subsubsection{General issues for wxWinCE programming}
  28
  29 Mobile applications generally have fewer features and
  30 simpler user interfaces. Simply omit whole sizers, static
  31 lines and controls in your dialogs, and use comboboxes instead
  32 of listboxes where appropriate. You also need to reduce
  33 the amount of spacing used by sizers, for which you can
  34 use a macro such as this:
  35
  36 \begin{verbatim}
  37 #if defined(__WXWINCE__)
  38     #define wxLARGESMALL(large,small) small
  39 #else
  40     #define wxLARGESMALL(large,small) large
  41 #endif
  42
  43 // Usage
  44 topsizer->Add( CreateTextSizer( message ), 0, wxALL, wxLARGESMALL(10,0) );
  45 \end{verbatim}
  46
  47 There is only ever one instance of a Windows CE application running,
  48 and wxWidgets will take care of showing the current instance and
  49 shutting down the second instance if necessary.
  50
  51 You can test the return value of wxSystemSettings::GetScreenType()
  52 for a qualitative assessment of what kind of display is available,
  53 or use wxGetDisplaySize() if you need more information.
  54
  55 You can also use wxGetOsVersion to test for a version of Windows CE at
  56 run-time (see the next section). However, because different builds
  57 are currently required to target different kinds of device, these
  58 values are hard-wired according to the build, and you cannot
  59 dynamically adapt the same executable for different major Windows CE
  60 platforms. This would require a different approach to the way
  61 wxWidgets adapts its behaviour (such as for menubars) to suit the
  62 style of device.
  63
  64 See the "Life!" example (demos/life) for an example of
  65 an application that has been tailored for PocketPC and Smartphone use.
  66
  67 \subsubsection{Testing for WinCE SDKs}
  68
  69 Use these preprocessor symbols to test for the different types of device or SDK:
  70
  71 \begin{twocollist}\itemsep=0pt
  72 \twocolitem{\_\_SMARTPHONE\_\_}{Generic mobile devices with phone buttons and a small display}
  73 \twocolitem{\_\_PDA\_\_}{Generic mobile devices with no phone}
  74 \twocolitem{\_\_HANDHELDPC\_\_}{Generic mobile device with a keyboard}
  75 \twocolitem{\_\_WXWINCE\_\_}{Microsoft-powered Windows CE devices, whether PocketPC, Smartphone or Standard SDK}
  76 \twocolitem{WIN32\_PLATFORM\_WFSP}{Microsoft-powered smartphone}
  77 \twocolitem{\_\_POCKETPC\_\_}{Microsoft-powered PocketPC devices with touch-screen}
  78 \twocolitem{\_\_WINCE\_STANDARDSDK\_\_}{Microsoft-powered Windows CE devices, for generic Windows CE applications}
  79 \twocolitem{\_\_WINCE\_NET\_\_}{Microsoft-powered Windows CE .NET devices (\_WIN32\_WCE is 400 or greater)}
  80 \end{twocollist}
  81
  82 wxGetOsVersion will return these values:
  83
  84 \begin{twocollist}\itemsep=0pt
  85 \twocolitem{wxWINDOWS\_POCKETPC}{The application is running under PocketPC.}
  86 \twocolitem{wxWINDOWS\_SMARTPHONE}{The application is running under Smartphone.}
  87 \twocolitem{wxWINDOWS\_CE}{The application is running under Windows CE (built with the Standard SDK).}
  88 \end{twocollist}
  89
  90 \subsubsection{Window sizing in wxWinCE}
  91
  92 When creating frames and dialogs, create them with wxDefaultPosition and
  93 wxDefaultSize, which will tell WinCE to create them full-screen.
  94
  95 Don't call Fit() and Centre(), so the content sizes to
  96 the window rather than fitting the window to the content. (We really need a single API call
  97 that will do the right thing on each platform.)
  98
  99 If the screen orientation changes, the windows will automatically be resized
 100 so no further action needs to be taken (unless you want to change the layout
 101 according to the orientation, which you could detect in idle time, for example).
 102 However, if the input panel (SIP) is shown, windows do not yet resize accordingly. This will
 103 be implemented soon.
 104
 105 \subsubsection{Dialogs in wxWinCE}
 106
 107 PocketPC dialogs have an OK button on the caption, and so you should generally
 108 not repeat an OK button on the dialog. You can add a Cancel button if necessary, but some dialogs
 109 simply don't offer you the choice (the guidelines recommend you offer an Undo facility
 110 to make up for it). When the user clicks on the OK button, your dialog will receive
 111 a wxID\_OK event by default. If you wish to change this, call wxDialog::SetAffirmativeId
 112 with the required identifier to be used. Or, override wxDialog::DoOK (return false to
 113 have wxWidgets simply call Close to dismiss the dialog).
 114
 115 Smartphone dialogs do {\it not} have an OK button on the caption, and are closed
 116 using one of the two menu buttons. You need to assign these using wxTopLevelWindow::SetLeftMenu
 117 and wxTopLevelWindow::SetRightMenu, for example:
 118
 119 \begin{verbatim}
 120 #ifdef __SMARTPHONE__
 121     SetLeftMenu(wxID_OK);
 122     SetRightMenu(wxID_CANCEL, _("Cancel"));
 123 #elif defined(__POCKETPC__)
 124     // No OK/Cancel buttons on PocketPC, OK on caption will close
 125 #else
 126     topsizer->Add( CreateButtonSizer( wxOK|wxCANCEL ), 0, wxEXPAND | wxALL, 10 );
 127 #endif
 128 \end{verbatim}
 129
 130 For implementing property sheets (flat tabs), use a wxNotebook with wxNB_FLAT|wxNB_BOTTOM
 131 and have the notebook left, top and right sides overlap the dialog by about 3 pixels
 132 to eliminate spurious borders. You can do this by using a negative spacing in your
 133 sizer Add() call. The cross-platform property sheet dialog \helpref{wxPropertySheetDialog}{wxpropertysheetdialog} is
 134 provided, to show settings in the correct style on PocketPC and on other platforms.
 135
 136 Notifications (bubble HTML text with optional buttons and links) will also be
 137 implemented in the future for PocketPC.
 138
 139 \subsubsection{Menubars and toolbars in wxWinCE}
 140
 141 Menubars and toolbars can only be implemented using a combined control,
 142 but you can use the same syntax as before; wxWidgets will combine the menubar
 143 and toolbar.
 144
 145 On PocketPC, a frame must always have a menubar, even if it's empty.
 146
 147 On Smartphone, there are only two menu buttons, so a menubar is simulated
 148 using a nested menu on the right menu button. Toolbars are simply ignored on
 149 Smartphone.
 150
 151 \subsubsection{Closing windows in wxWinCE}
 152
 153 The guidelines state that applications should not have a Quit menu item,
 154 since the user should not have to know whether an application is in memory
 155 or not. The close button on a window does not call the window's
 156 close handler; it simply hides the window. However, the guidelines say that
 157 the Ctrl+Q accelerator can be used to quit the application, so wxWidgets
 158 defines this accelerator by default and if your application handles
 159 wxID\_EXIT, it will do the right thing.
 160
 161 \subsubsection{Control differences on wxWinCE}
 162
 163 This section is to be written.
 164
 165 Can someone remind us why wxChoice was rewritten for Smartphone?
 166
 167 \subsubsection{Online help in wxWinCE}
 168
 169 You can use the help controller wxWinceHelpController which controls
 170 simple {\tt .htm} files, usually installed in the Windows directory.
 171
 172 \subsubsection{Remaining issues}
 173
 174 These are some of the remaining problems to be sorted out, and features
 175 to be supported.
 176
 177 \itemsep=0pt
 178 \begin{itemize}
 179 \item {\bf Font dialog.} The generic font dialog is currently used, which
 180 needs to be simplified (and speeded up).
 181 \item {\bf Sizer speed.} Particularly for dialogs containing notebooks,
 182 layout seems slow. Some analysis is required.
 183 \item {\bf Notification boxes.} The balloon-like notification messages, and their
 184 icons, should be implemented. This will be quite straightforward.
 185 \item {\bf WM\_SETTINGCHANGE.} This message needs to be handled by calling SHHandleWMSettingChange.
 186 \item {\bf WM\_ACTIVATE.} This message needs to be handled by calling SHHandleWMActivate.
 187 \item {\bf WM\_HIBERNATE.} We need to handle this message.
 188 \item {\bf SIP size.} We need to be able to get the area taken up by the SIP (input panel),
 189 and the remaining area, by calling SHSipInfo. We also may need to be able to show and hide
 190 the SIP programmatically, with SHSipPreference. See also the {\it Input Dialogs} topic in
 191 the {\it Programming Windows CE} guide for more on this, and how to have dialogs
 192 show the SIP automatically using the WC_SIPREF control.
 193 \item {\bf Drawing.} The "Life!" demo shows some droppings being left on the window,
 194 indicating that drawing works a bit differently between desktop and mobile versions of
 195 Win32.
 196 \item {\bf wxStaticBitmap.} The About box in the "Life!" demo shows a bitmap that is
 197 the correct size on the emulator, but too small on a VGA Pocket Loox device.
 198 \item {\bf wxStaticLine.} Lines don't show up, and the documentation suggests that
 199 missing styles are implemented with WM\_PAINT.
 200 \item {\bf OK button.} We should allow the OK button on a dialog to be optional, perhaps
 201 by using wxCLOSE\_BOX to indicate when the OK button should be displayed.
 202 \item {\bf Dynamic adaptation.} We should probably be using run-time tests more
 203 than preprocessor tests, so that the same WinCE application can run on different
 204 versions of the operating system.
 205 \item {\bf Home screen plugins.} Figure out how to make home screen plugins for use with wxWidgets
 206 applications (see {\tt http://www.codeproject.com/ce/CTodayWindow.asp} for inspiration).
 207 Although we can't use wxWidgets to create the plugin (too large), we could perhaps write
 208 a generic plugin that takes registry information from a given application, with
 209 options to display information in a particular way using icons and text from
 210 a specified location.
 211 \item {\bf Further abstraction.} We should be able to abstract away more of the differences
 212 between desktop and mobile applications, in particular for sizer layout.
 213 \end{itemize}
 214