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 See the "Life!" example (demos/life) for an example of
  56 an application that has been tailored for Windows CE use.
  57
  58 \subsubsection{Testing for WinCE SDKs}
  59
  60 Use these preprocessor symbols to test for the different SDKS:
  61
  62 \begin{twocollist}\itemsep=0pt
  63 \twocolitem{\_\_WXWINCE\_\_}{Microsoft-powered Windows CE devices, whether PocketPC, Smartphone or Standard SDK}
  64 \twocolitem{\_\_SMARTPHONE\_\_}{Microsoft-powered mobile devices with phone buttons and a small display}
  65 \twocolitem{\_\_POCKETPC\_\_}{Microsoft-powered PocketPC devices with touch-screen}
  66 \twocolitem{\_\_WINCE\_STANDARDSDK\_\_}{Microsoft-powered Windows CE devices, for generic Windows CE applications}
  67 \twocolitem{\_\_WINCE\_NET\_\_}{Microsoft-powered Windows CE .NET devices (\_WIN32\_WCE is 400 or greater)}
  68 \end{twocollist}
  69
  70 \subsubsection{Window sizing in wxWinCE}
  71
  72 When creating frames and dialogs, create them with wxDefaultPosition and
  73 wxDefaultSize, which will tell WinCE to create them full-screen.
  74
  75 Don't call Fit() and Centre(), so the content sizes to
  76 the window rather than fitting the window to the content. (We really need a single API call
  77 that will do the right thing on each platform.)
  78
  79 If the screen orientation changes, the windows will automatically be resized
  80 so no further action needs to be taken (unless you want to change the layout
  81 according to the orientation, which you could detect in idle time, for example).
  82 However, if the input panel (SIP) is shown, windows do not yet resize accordingly. This will
  83 be implemented soon.
  84
  85 \subsubsection{Dialogs in wxWinCE}
  86
  87 PocketPC dialogs have an OK button on the caption, and so you should generally
  88 not repeat an OK button on the dialog. You can add a Cancel button if necessary, but some dialogs
  89 simply don't offer you the choice (the guidelines recommend you offer an Undo facility
  90 to make up for it). When the user clicks on the OK button, your dialog will receive
  91 a wxID\_OK event by default. If you wish to change this, call wxDialog::SetAffirmativeId
  92 with the required identifier to be used. Or, override wxDialog::DoOK (return false to
  93 have wxWidgets simply call Close to dismiss the dialog).
  94
  95 Smartphone dialogs do {\it not} have an OK button on the caption, and are closed
  96 using one of the two menu buttons. You need to assign these using wxTopLevelWindow::SetLeftMenu
  97 and wxTopLevelWindow::SetRightMenu, for example:
  98
  99 \begin{verbatim}
 100 #ifdef __SMARTPHONE__
 101     SetLeftMenu(wxID_OK);
 102     SetRightMenu(wxID_CANCEL, _("Cancel"));
 103 #elif defined(__POCKETPC__)
 104     // No OK/Cancel buttons on PocketPC, OK on caption will close
 105 #else
 106     topsizer->Add( CreateButtonSizer( wxOK|wxCANCEL ), 0, wxEXPAND | wxALL, 10 );
 107 #endif
 108 \end{verbatim}
 109
 110 For implementing property sheets (flat tabs), use a wxNotebook with wxNB_FLAT|wxNB_BOTTOM
 111 and have the notebook left, top and right sides overlap the dialog by about 3 pixels
 112 to eliminate spurious borders. You can do this by using a negative spacing in your
 113 sizer Add() call. A cross-platform property sheet dialog will be implemented in the
 114 future, so you only need to provide the dialog's pages.
 115
 116 Notifications (bubble HTML text with optional buttons and links) will also be
 117 implemented in the future for PocketPC.
 118
 119 \subsubsection{Menubars and toolbars in wxWinCE}
 120
 121 Menubars and toolbars can only be implemented using a combined control,
 122 but you can use the same syntax as before; wxWidgets will combine the menubar
 123 and toolbar. However, you cannot at present use arbitrary toolbar bitmaps
 124 (since they have to be loaded from a Windows resource), so only standard
 125 identifiers will work (wxID\_OPEN, wxID\_SAVE, wxID\_COPY and so on).
 126
 127 The wxWidgets API doesn't currently provide us with a method of passing resource
 128 identifiers to AddTool, which is something that needs to be addressed.
 129
 130 On PocketPC, a frame must always have a menubar, even if it's empty.
 131
 132 On Smartphone, there are only two menu buttons, so a menubar is simulated
 133 using a nested menu on the right menu button.
 134
 135 \subsubsection{Closing windows in wxWinCE}
 136
 137 The guidelines state that applications should not have a Quit menu item,
 138 since the user should not have to know whether an application is in memory
 139 or not. The close button on a window does not call the window's
 140 close handler; it simply hides the window. However, the guidelines say that
 141 the Ctrl+Q accelerator can be used to quit the application, so wxWidgets
 142 defines this accelerator by default and if your application handles
 143 wxID\_EXIT, it will do the right thing.
 144
 145 \subsubsection{Control differences on wxWinCE}
 146
 147 This section is to be written.
 148
 149 Can someone remind us why wxChoice was rewritten for Smartphone?
 150
 151 \subsubsection{Online help in wxWinCE}
 152
 153 You can use the help controller wxWinceHelpController which controls
 154 simple {\tt .htm} files, usually installed in the Windows directory.
 155
 156 \subsubsection{Remaining issues}
 157
 158 These are some of the remaining problems to be sorted out, and features
 159 to be supported.
 160
 161 \itemsep=0pt
 162 \begin{itemize}
 163 \item {\bf Custom toolbar buttons.} The bitmaps could be loaded from a resource
 164 named using the string normally used for a tool caption. Currently only buttons with
 165 standard identifiers can be used.
 166 \item {\bf Font dialog.} The generic font dialog is currently used, which
 167 needs to be simplified (and speeded up).
 168 \item {\bf Sizer speed.} Particularly for dialogs containing notebooks,
 169 layout seems slow. Some analysis is required.
 170 \item {\bf Property sheets.} We should have a class for handling property sheets
 171 on WinCE and desktop platforms (see previous section on dialogs).
 172 \item {\bf Notification boxes.} The balloon-like notification messages, and their
 173 icons, should be implemented. This will be quite straightforward.
 174 \item {\bf WM\_SETTINGCHANGE.} This message needs to be handled by calling SHHandleWMSettingChange.
 175 \item {\bf WM\_ACTIVATE.} This message needs to be handled by calling SHHandleWMActivate.
 176 \item {\bf WM\_HIBERNATE.} We need to handle this message.
 177 \item {\bf SIP size.} We need to be able to get the area taken up by the SIP (input panel),
 178 and the remaining area, by calling SHSipInfo. We also may need to be able to show and hide
 179 the SIP programmatically, with SHSipPreference. See also the {\it Input Dialogs} topic in
 180 the {\it Programming Windows CE} guide for more on this, and how to have dialogs
 181 show the SIP automatically using the WC_SIPREF control.
 182 \item {\bf Drawing.} The "Life!" demo shows some droppings being left on the window,
 183 indicating that drawing works a bit differently between desktop and mobile versions of
 184 Win32.
 185 \item {\bf wxStaticBitmap.} The About box in the "Life!" demo shows a bitmap that is
 186 the correct size on the emulator, but too small on a VGA Pocket Loox device.
 187 \item {\bf OK button.} We should allow the OK button on a dialog to be optional, perhaps
 188 by using wxCLOSE\_BOX to indicate when the OK button should be displayed.
 189 \item {\bf Data storage.} Methods for saving data on Smartphone need to be supported and documented.
 190 \item {\bf Dynamic adaptation.} We should probably be using run-time tests more
 191 than preprocessor tests, so that the same WinCE application can run on different
 192 versions of the operating system.
 193 \item {\bf Home screen plugins.} Figure out how to make home screen plugins for use with wxWidgets
 194 applications (see {\tt http://www.codeproject.com/ce/CTodayWindow.asp} for inspiration).
 195 Although we can't use wxWidgets to create the plugin (too large), we could perhaps write
 196 a generic plugin that takes registry information from a given application, with
 197 options to display information in a particular way using icons and text from
 198 a specified location.
 199 \item {\bf Further abstraction.} We should be able to abstract away more of the differences
 200 between desktop and mobile applications, in particular for sizer layout.
 201 \end{itemize}
 202