For further information, please see the files in docs/msw
in the distribution.
+\subsection{wxWinCE}\label{wxwince}
+
+wxWinCE is the name given to wxMSW when compiled on Windows CE devices;
+most of wxMSW is common to Win32 and Windows CE but there are
+some simplifications, enhancements, and differences in
+behaviour.
+
+For installation instructions, see docs/msw/wince in the
+distribution. The rest of this section documents issues you
+need to be aware of when programming for Windows CE devices.
+
+\subsubsection{General issues for wxWinCE programming}
+
+Mobile applications generally have fewer features and
+simpler user interfaces. Simply omit whole sizers, static
+lines and controls in your dialogs, and use comboboxes instead
+of listboxes where appropriate. You also need to reduce
+the amount of spacing used by sizers, for which you can
+use a macro such as this:
+
+\begin{verbatim}
+#if defined(__WXWINCE__)
+ #define wxLARGESMALL(large,small) small
+#else
+ #define wxLARGESMALL(large,small) large
+#endif
+
+// Usage
+topsizer->Add( CreateTextSizer( message ), 0, wxALL, wxLARGESMALL(10,0) );
+\end{verbatim}
+
+There is only ever one instance of a Windows CE application running,
+and wxWidgets will take care of showing the current instance and
+shutting down the second instance if necessary.
+
+You can test the return value of wxSystemSettings::GetScreenType()
+for a qualitative assessment of what kind of display is available,
+or use wxGetDisplaySize() if you need more information.
+
+You can also use wxGetOsVersion to test for a version of Windows CE at
+run-time (see the next section). However, because different builds
+are currently required to target different kinds of device, these
+values are hard-wired according to the build, and you cannot
+dynamically adapt the same executable for different major Windows CE
+platforms. This would require a different approach to the way
+wxWidgets adapts its behaviour (such as for menubars) to suit the
+style of device.
+
+See the "Life!" example (demos/life) for an example of
+an application that has been tailored for PocketPC and Smartphone use.
+
+\subsubsection{Testing for WinCE SDKs}
+
+Use these preprocessor symbols to test for the different types of device or SDK:
+
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\_\_SMARTPHONE\_\_}{Generic mobile devices with phone buttons and a small display}
+\twocolitem{\_\_PDA\_\_}{Generic mobile devices with no phone}
+\twocolitem{\_\_HANDHELDPC\_\_}{Generic mobile device with a keyboard}
+\twocolitem{\_\_WXWINCE\_\_}{Microsoft-powered Windows CE devices, whether PocketPC, Smartphone or Standard SDK}
+\twocolitem{WIN32\_PLATFORM\_WFSP}{Microsoft-powered smartphone}
+\twocolitem{\_\_POCKETPC\_\_}{Microsoft-powered PocketPC devices with touch-screen}
+\twocolitem{\_\_WINCE\_STANDARDSDK\_\_}{Microsoft-powered Windows CE devices, for generic Windows CE applications}
+\twocolitem{\_\_WINCE\_NET\_\_}{Microsoft-powered Windows CE .NET devices (\_WIN32\_WCE is 400 or greater)}
+\end{twocollist}
+
+wxGetOsVersion will return these values:
+
+\begin{twocollist}\itemsep=0pt
+\twocolitem{wxWINDOWS\_POCKETPC}{The application is running under PocketPC.}
+\twocolitem{wxWINDOWS\_SMARTPHONE}{The application is running under Smartphone.}
+\twocolitem{wxWINDOWS\_CE}{The application is running under Windows CE (built with the Standard SDK).}
+\end{twocollist}
+
+\subsubsection{Window sizing in wxWinCE}
+
+When creating frames and dialogs, create them with wxDefaultPosition and
+wxDefaultSize, which will tell WinCE to create them full-screen.
+
+Don't call Fit() and Centre(), so the content sizes to
+the window rather than fitting the window to the content. (We really need a single API call
+that will do the right thing on each platform.)
+
+If the screen orientation changes, the windows will automatically be resized
+so no further action needs to be taken (unless you want to change the layout
+according to the orientation, which you could detect in idle time, for example).
+However, if the input panel (SIP) is shown, windows do not yet resize accordingly. This will
+be implemented soon.
+
+\subsubsection{Closing top-level windows in wxWinCE}
+
+You won't get a wxCloseEvent when the user clicks on the X in the titlebar
+on Smartphone and PocketPC; the window is simply hidden instead. However the system may send the
+event to force the application to close down.
+
+\subsubsection{Hibernation in wxWinCE}
+
+Smartphone and PocketPC will send a wxEVT\_HIBERNATE to the application object in low
+memory conditions. Your application should release memory and close dialogs,
+and wake up again when the next wxEVT\_ACTIVATE or wxEVT\_ACTIVATE\_APP message is received.
+(wxEVT\_ACTIVATE\_APP is generated whenever a wxEVT\_ACTIVATE event is received
+in Smartphone and PocketPC, since these platforms do not support WM\_ACTIVATEAPP.)
+
+\subsubsection{Hardware buttons in wxWinCE}
+
+Special hardware buttons are sent to a window via the wxEVT\_HOTKEY event
+under Smartphone and PocketPC. You should first register each required button with \helpref{wxWindow::RegisterHotKey}{wxwindowregisterhotkey},
+and unregister the button when you're done with it. For example:
+
+\begin{verbatim}
+ win->RegisterHotKey(0, wxMOD_WIN, WXK_SPECIAL1);
+ win->UnregisterHotKey(0);
+\end{verbatim}
+
+You may have to register the buttons in a wxEVT_ACTIVATE event handler
+since other applications will grab the buttons.
+
+There is currently no method of finding out the names of the special
+buttons or how many there are.
+
+\subsubsection{Dialogs in wxWinCE}
+
+PocketPC dialogs have an OK button on the caption, and so you should generally
+not repeat an OK button on the dialog. You can add a Cancel button if necessary, but some dialogs
+simply don't offer you the choice (the guidelines recommend you offer an Undo facility
+to make up for it). When the user clicks on the OK button, your dialog will receive
+a wxID\_OK event by default. If you wish to change this, call wxDialog::SetAffirmativeId
+with the required identifier to be used. Or, override wxDialog::DoOK (return false to
+have wxWidgets simply call Close to dismiss the dialog).
+
+Smartphone dialogs do {\it not} have an OK button on the caption, and are closed
+using one of the two menu buttons. You need to assign these using wxTopLevelWindow::SetLeftMenu
+and wxTopLevelWindow::SetRightMenu, for example:
+
+\begin{verbatim}
+#ifdef __SMARTPHONE__
+ SetLeftMenu(wxID_OK);
+ SetRightMenu(wxID_CANCEL, _("Cancel"));
+#elif defined(__POCKETPC__)
+ // No OK/Cancel buttons on PocketPC, OK on caption will close
+#else
+ topsizer->Add( CreateButtonSizer( wxOK|wxCANCEL ), 0, wxEXPAND | wxALL, 10 );
+#endif
+\end{verbatim}
+
+For implementing property sheets (flat tabs), use a wxNotebook with wxNB_FLAT|wxNB_BOTTOM
+and have the notebook left, top and right sides overlap the dialog by about 3 pixels
+to eliminate spurious borders. You can do this by using a negative spacing in your
+sizer Add() call. The cross-platform property sheet dialog \helpref{wxPropertySheetDialog}{wxpropertysheetdialog} is
+provided, to show settings in the correct style on PocketPC and on other platforms.
+
+Notifications (bubble HTML text with optional buttons and links) will also be
+implemented in the future for PocketPC.
+
+Modeless dialogs probably don't make sense for PocketPC and Smartphone, since
+frames and dialogs are normally full-screen, and a modeless dialog is normally
+intended to co-exist with the main application frame.
+
+\subsubsection{Menubars and toolbars in wxWinCE}
+
+\wxheading{Menubars and toolbars in PocketPC}
+
+On PocketPC, a frame must always have a menubar, even if it's empty.
+An empty menubar is automatically provided for dialogs, to hide
+any existing menubar for the duration of the dialog.
+
+Menubars and toolbars are implemented using a combined control,
+but you can use essentially the usual wxWidgets API; wxWidgets will combine the menubar
+and toolbar. However, there are some restrictions:
+
+\itemsep=0pt
+\begin{itemize}
+\item You must create the frame's primary toolbar with wxFrame::CreateToolBar,
+because this uses the special wxToolMenuBar class (derived from wxToolBar)
+to implement the combined toolbar and menubar. Otherwise, you can create and manage toolbars
+using the wxToolBar class as usual, for example to implement an optional
+formatting toolbar above the menubar as Pocket Word does. But don't assign
+a wxToolBar to a frame using SetToolBar - you should always use CreateToolBar
+for the main frame toolbar.
+\item Deleting and adding tools to wxToolMenuBar is not supported.
+\end{itemize}
+
+\wxheading{Menubars and toolbars in Smartphone}
+
+On Smartphone, there are only two menu buttons, so a menubar is simulated
+using a nested menu on the right menu button. Any toolbars are simply ignored on
+Smartphone.
+
+\subsubsection{Closing windows in wxWinCE}
+
+The guidelines state that applications should not have a Quit menu item,
+since the user should not have to know whether an application is in memory
+or not. The close button on a window does not call the window's
+close handler; it simply hides the window. However, the guidelines say that
+the Ctrl+Q accelerator can be used to quit the application, so wxWidgets
+defines this accelerator by default and if your application handles
+wxID\_EXIT, it will do the right thing.
+
+\subsubsection{Control differences on wxWinCE}
+
+These controls are missing from wxWinCE:
+
+\itemsep=0pt
+\begin{itemize}
+\item {\bf wxCheckListBox} This can be implemented using a wxListCtrl in report mode
+with checked/unchecked images.
+\end{itemize}
+
+This section is currently incomplete.
+
+\subsubsection{Online help in wxWinCE}
+
+You can use the help controller wxWinceHelpController which controls
+simple {\tt .htm} files, usually installed in the Windows directory.
+
+\subsubsection{Remaining issues}
+
+These are some of the remaining problems to be sorted out, and features
+to be supported.
+
+\itemsep=0pt
+\begin{itemize}
+\item {\bf Font dialog.} The generic font dialog is currently used, which
+needs to be simplified (and speeded up).
+\item {\bf Sizer speed.} Particularly for dialogs containing notebooks,
+layout seems slow. Some analysis is required.
+\item {\bf Notification boxes.} The balloon-like notification messages, and their
+icons, should be implemented. This will be quite straightforward.
+\item {\bf SIP size.} We need to be able to get the area taken up by the SIP (input panel),
+and the remaining area, by calling SHSipInfo. We also may need to be able to show and hide
+the SIP programmatically, with SHSipPreference. See also the {\it Input Dialogs} topic in
+the {\it Programming Windows CE} guide for more on this, and how to have dialogs
+show the SIP automatically using the WC_SIPREF control.
+\item {\bf Drawing.} The "Life!" demo shows some droppings being left on the window,
+indicating that drawing works a bit differently between desktop and mobile versions of
+Win32.
+\item {\bf wxStaticBitmap.} The About box in the "Life!" demo shows a bitmap that is
+the correct size on the emulator, but too small on a VGA Pocket Loox device.
+\item {\bf wxStaticLine.} Lines don't show up, and the documentation suggests that
+missing styles are implemented with WM\_PAINT.
+\item {\bf wxCheckListBox.} This class needs to be implemented in terms of a wxListCtrl
+in report mode, using icons for checkbox states. This is necessary because owner-draw listboxes
+are not supported on Windows CE.
+\item {\bf OK button.} We should allow the OK button on a dialog to be optional, perhaps
+by using wxCLOSE\_BOX to indicate when the OK button should be displayed.
+\item {\bf Dynamic adaptation.} We should probably be using run-time tests more
+than preprocessor tests, so that the same WinCE application can run on different
+versions of the operating system.
+\item {\bf Home screen plugins.} Figure out how to make home screen plugins for use with wxWidgets
+applications (see {\tt http://www.codeproject.com/ce/CTodayWindow.asp} for inspiration).
+Although we can't use wxWidgets to create the plugin (too large), we could perhaps write
+a generic plugin that takes registry information from a given application, with
+options to display information in a particular way using icons and text from
+a specified location.
+\item {\bf Further abstraction.} We should be able to abstract away more of the differences
+between desktop and mobile applications, in particular for sizer layout.
+\end{itemize}
+
projects / wxWidgets.git / blobdiff