Frames have Ctrl+Q accelerator set automatically, as per the

PocketPC guidelines Documented issues in manual under wxWinCE topic. wxDEFAULT_DIALOG_STYLES rationalised so we can make use of styles such as wxCLOSE_BOX in future (OK button on titlebar) Added Set/GetAffirmativeId and DoOK so that titlebar OK button can be customised git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@32823 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
2005-03-14 17:15:06 +00:00
parent f8a10a3d2b
commit 9ceeecb94e
10 changed files with 323 additions and 62 deletions
--- a/docs/latex/wx/cppconst.tex
+++ b/docs/latex/wx/cppconst.tex
@@ -42,27 +42,24 @@ to one of the symbols above so this should be tested first.}
 \twocolitem{\_\_X\_\_}{any X11-based GUI toolkit except GTK+}
 \end{twocollist}

-Mac situation is a bit confusing so a few extra words to explain it: there are
-2 wx ports to Mac OS. One of them, wxMac, exists in 2 versions: Classic and
+There are two wxWidgets ports to Mac OS. One of them, wxMac, exists in two versions: Classic and
 Carbon. The Classic version is the only one to work on Mac OS version 8. The
 Carbon version may be built either as CFM or Mach-O (binary format, like ELF)
 and the former may run under OS 9 while the latter only runs under OS X.
 Finally, there is a new Cocoa port which can only be used under OS X. To
 summarize:
+
 \begin{itemize}
-    \item If you want to test for all Mac platforms, classic and OS X, you
-        should test both \texttt{\_\_WXMAC\_\_} and \texttt{\_\_WXCOCOA\_\_}
-    \item If you want to test for any GUI Mac port under OS X, use
-        \texttt{\_\_WXOSX\_\_}
-    \item If you want to test for any port under Mac OS X, including, for
-        example, wxGTK and also wxBase, use \texttt{\_\_DARWIN\_\_} (see below)
+\item If you want to test for all Mac platforms, classic and OS X, you
+should test both \texttt{\_\_WXMAC\_\_} and \texttt{\_\_WXCOCOA\_\_}.
+\item If you want to test for any GUI Mac port under OS X, use 
+\texttt{\_\_WXOSX\_\_}.
+\item If you want to test for any port under Mac OS X, including, for
+example, wxGTK and also wxBase, use \texttt{\_\_DARWIN\_\_} (see below).
 \end{itemize}

-
-Note to implementors: although some of the symbols above don't start with 
-\texttt{\_\_WX} prefix, they really should always use it, so please do start
-any new symbols with it.
-
+The convention is to use the \texttt{\_\_WX} prefix for these
+symbols, although this has not always been followed.

 \subsection{Operating systems}\label{osconst}

@@ -110,15 +107,20 @@ compiler used.

 \subsection{Hardware type}\label{hardwareconst}

-Combination of these symbols with GUI symbols describes real hardware
-(like \_\_PDA\_\_ $&&$ \_\_WXWINCE\_\_ $==$ PocketPC devices).
+% Note: previous documentation referred to __SMARTPHONE__ as a generic (non-MS-specific) symbol
+% but we should go back to using it for a specific SDK, because trying to be
+% generic doesn't really work

 \begin{twocollist}\itemsep=0pt
-\twocolitem{\_\_SMARTPHONE\_\_}{Mobile devices with dialog capability through 
-phone buttons and small display}
-\twocolitem{\_\_PDA\_\_}{Personal digital assistant usually with touch screen and
-middle sized screen}
-\twocolitem{\_\_HANDHELD\_\_}{Small enough but powerful computer}
+\twocolitem{\_\_SMARTPHONE\_\_}{Microsoft-powered mobile devices with phone buttons and a small display}
+\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)}
+% Note to doc writers: these symbols are pretty useless because of the blurred
+% dividing lines between these machines, plus they're not actually used.
+%\twocolitem{\_\_PDA\_\_}{Personal digital assistant usually with touch screen and
+%middle sized screen (not yet defined anywhere)}
+%\twocolitem{\_\_HANDHELD\_\_}{Small enough but powerful computer (not yet defined anywhere)}
 \end{twocollist}


--- a/docs/latex/wx/dialog.tex
+++ b/docs/latex/wx/dialog.tex
@@ -184,6 +184,15 @@ of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxHELP, wxNO\_DEFAULT.

 The sizer lays out the buttons in a manner appropriate to the platform.

+\membersection{wxDialog::DoOK}\label{wxdialogdook}
+
+\func{virtual bool}{DoOK}{\void}
+
+This function is called when the titlebar OK button is pressed (PocketPC only).
+A command event for the identifier returned by GetAffirmativeId is sent by
+default. You can override this function. If the function returns false, wxWidgets
+will call Close() for the dialog.
+
 \membersection{wxDialog::EndModal}\label{wxdialogendmodal}

 \func{void}{EndModal}{\param{int }{retCode}}
@@ -201,6 +210,16 @@ invocation.
 \helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode},\rtfsp
 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}

+\membersection{wxDialog::GetAffirmativeId}\label{wxdialoggetaffirmativeid}
+
+\constfunc{int}{GetAffirmativeId}{\void}
+
+Gets the identifier to be used when the user presses an OK button in a PocketPC titlebar.
+
+\wxheading{See also}
+
+\helpref{wxDialog::SetAffirmativeId}{wxdialogsetaffirmativeid}
+
 \membersection{wxDialog::GetReturnCode}\label{wxdialoggetreturncode}

 \func{int}{GetReturnCode}{\void}
@@ -325,6 +344,17 @@ propagate the notification to child windows and controls.

 \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}

+\membersection{wxDialog::SetAffirmativeId}\label{wxdialogsetaffirmativeid}
+
+\func{void}{SetAffirmativeId}{\param{int }{id}}
+
+Sets the identifier to be used when the user presses an OK button in a PocketPC titlebar.
+By default, this is wxID\_OK.
+
+\wxheading{See also}
+
+\helpref{wxDialog::GetAffirmativeId}{wxdialoggetaffirmativeid}
+
 \membersection{wxDialog::SetIcon}\label{wxdialogseticon}

 \func{void}{SetIcon}{\param{const wxIcon\& }{icon}}
--- a/docs/latex/wx/helpinst.tex
+++ b/docs/latex/wx/helpinst.tex
@@ -40,6 +40,7 @@ not available, \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}. You need to
 {\bf both} CHM and HTB versions of the help file. For 32bit Windows only.
 \item wxExtHelpController, for controlling external browsers under Unix.
 The default browser is Netscape Navigator. The 'help' sample shows its use.
+\item wxWinceHelpController, for controlling a simple {\tt .htm} help controller for Windows CE applications.
 \item \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}, a sophisticated help controller using \helpref{wxHTML}{wxhtml}, in
 a similar style to the Microsoft HTML Help viewer and using some of the same files.
 Although it has an API compatible with other help controllers, it has more advanced features, so it is
--- a/docs/latex/wx/wxmsw.tex
+++ b/docs/latex/wx/wxmsw.tex
@@ -13,3 +13,190 @@ MinGW32 tool chain.
 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.
+
+See the "Life!" example (demos/life) for an example of
+an application that has been tailored for Windows CE use.
+
+\subsubsection{Testing for WinCE SDKs}
+
+Use these preprocessor symbols to test for the different SDKS:
+
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\_\_WXWINCE\_\_}{Microsoft-powered Windows CE devices, whether PocketPC, Smartphone or Standard SDK}
+\twocolitem{\_\_SMARTPHONE\_\_}{Microsoft-powered mobile devices with phone buttons and a small display}
+\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}
+
+\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{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. A cross-platform property sheet dialog will be implemented in the
+future, so you only need to provide the dialog's pages.
+
+Notifications (bubble HTML text with optional buttons and links) will also be
+implemented in the future for PocketPC.
+
+\subsubsection{Menubars and toolbars in wxWinCE}
+
+Menubars and toolbars can only be implemented using a combined control,
+but you can use the same syntax as before; wxWidgets will combine the menubar
+and toolbar. However, you cannot at present use arbitrary toolbar bitmaps
+(since they have to be loaded from a Windows resource), so only standard
+identifiers will work (wxID\_OPEN, wxID\_SAVE, wxID\_COPY and so on).
+
+The wxWidgets API doesn't currently provide us with a method of passing resource
+identifiers to AddTool, which is something that needs to be addressed.
+
+On PocketPC, a frame must always have a menubar, even if it's empty.
+
+On Smartphone, there are only two menu buttons, so a menubar is simulated
+using a nested menu on the right menu button.
+
+\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}
+
+This section is to be written.
+
+Can someone remind us why wxChoice was rewritten for Smartphone?
+
+\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 Custom toolbar buttons.} The bitmaps could be loaded from a resource
+named using the string normally used for a tool caption. Currently only buttons with
+standard identifiers can be used.
+\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 Property sheets.} We should have a class for handling property sheets
+on WinCE and desktop platforms (see previous section on dialogs).
+\item {\bf Notification boxes.} The balloon-like notification messages, and their
+icons, should be implemented. This will be quite straightforward.
+\item {\bf WM\_SETTINGCHANGE.} This message needs to be handled by calling SHHandleWMSettingChange.
+\item {\bf WM\_ACTIVATE.} This message needs to be handled by calling SHHandleWMActivate.
+\item {\bf WM\_HIBERNATE.} We need to handle this message.
+\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 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 Data storage.} Methods for saving data on Smartphone need to be supported and documented.
+\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}
+