wxWinCE:
- Added wxNB_FLAT for flat-look notebooks on Windows CE.
-- Titlebar OK button on PocketPC now looks for OK, Cancel, Close buttons.
+- Titlebar OK button on PocketPC now sends command set by SetAffirmativeId.
+ You can also override wxDialog::DoOK if you need more flexibility.
- Dialog size now takes into account SIP or menubar.
- Panels more naturally white on PocketPC.
- wxDIALOG_EX_CONTEXTHELP ignored on WinCE since it interferes
with correct titlebar style.
+- Frames have Ctrl+Q accelerator set automatically, as per the
+ PocketPC guidelines
+- Documented issues in manual under wxWinCE topic.
2.5.4
\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}
\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}
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}}
\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}
\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}}
{\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
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}
+
#define wxDIALOG_NO_PARENT 0x0001 // Don't make owned by apps top window
#ifdef __WXWINCE__
-# ifdef __SMARTPHONE__
-# define wxDEFAULT_DIALOG_STYLE (wxMAXIMIZE | wxCAPTION)
-# else
-# define wxDEFAULT_DIALOG_STYLE (0)
-# endif
-#else // !__WXWINCE__
-# define wxDEFAULT_DIALOG_STYLE (wxSYSTEM_MENU | wxCAPTION | wxCLOSE_BOX)
+#define wxDEFAULT_DIALOG_STYLE (wxCAPTION | wxMAXIMIZE | wxCLOSE_BOX)
+#else
+#define wxDEFAULT_DIALOG_STYLE (wxCAPTION | wxSYSTEM_MENU | wxCLOSE_BOX)
#endif
extern WXDLLEXPORT_DATA(const wxChar*) wxDialogNameStr;
void Init();
- // the modal dialogs have a return code - usually the id of the last
+ // Modal dialogs have a return code - usually the id of the last
// pressed button
void SetReturnCode(int returnCode) { m_returnCode = returnCode; }
int GetReturnCode() const { return m_returnCode; }
+ // The identifier for the affirmative button
+ void SetAffirmativeId(int affirmativeId) { m_affirmativeId = affirmativeId; }
+ int GetAffirmativeId() const { return m_affirmativeId; }
+
#if wxUSE_STATTEXT // && wxUSE_TEXTCTRL
// splits text up at newlines and places the
// lines into a vertical wxBoxSizer
#endif // wxUSE_BUTTON
protected:
- // the return code from modal dialog
+ // The return code from modal dialog
int m_returnCode;
+ // The identifier for the affirmative button (usually wxID_OK)
+ int m_affirmativeId;
+
DECLARE_NO_COPY_CLASS(wxDialogBase)
DECLARE_EVENT_TABLE()
WX_DECLARE_CONTROL_CONTAINER();
// Responds to colour changes
void OnSysColourChanged(wxSysColourChangedEvent& event);
+#ifdef __POCKETPC__
+ // Responds to the OK button in a PocketPC titlebar. This
+ // can be overridden, or you can change the id used for
+ // sending the event with SetAffirmativeId. Returns false
+ // if the event was not processed.
+ virtual bool DoOK();
+#endif
+
// Windows callbacks
WXLRESULT MSWWindowProc(WXUINT message, WXWPARAM wParam, WXLPARAM lParam);
void wxDialogBase::Init()
{
m_returnCode = 0;
-
+ m_affirmativeId = wxID_OK;
+
// the dialogs have this flag on by default to prevent the events from the
// dialog controls from reaching the parent frame which is usually
// undesirable and can lead to unexpected and hard to find bugs
yes->SetFocus();
}
}
+
+ if (flags & wxOK)
+ SetAffirmativeId(wxID_OK);
+ else if (flags & wxYES)
+ SetAffirmativeId(wxID_YES);
return sizer;
}
Refresh();
}
+#ifdef __POCKETPC__
+// Responds to the OK button in a PocketPC titlebar. This
+// can be overridden, or you can change the id used for
+// sending the event, by calling SetAffirmativeId.
+bool wxDialog::DoOK()
+{
+ wxButton *btn = wxDynamicCast(FindWindow(GetAffirmativeId()), wxButton);
+
+ if ( btn && btn->IsEnabled() )
+ {
+ // If we have this button, press it
+ btn->MSWCommand(BN_CLICKED, 0 /* unused */);
+ return true;
+ }
+ else
+ {
+ wxCommandEvent event(wxEVT_COMMAND_BUTTON_CLICKED, GetAffirmativeId());
+ event.SetEventObject(this);
+
+ return GetEventHandler()->ProcessEvent(event);
+ }
+}
+#endif
+
+
// ---------------------------------------------------------------------------
// dialog window proc
// ---------------------------------------------------------------------------
{
switch ( LOWORD(wParam) )
{
-#ifndef __SMARTPHONE__
+#ifdef __POCKETPC__
case IDOK:
- // First, try the OK button, since it's closest in meaning.
- wxButton *btn = wxDynamicCast(FindWindow(wxID_OK), wxButton);
-
- // Next, try Cancel or Close buttons
- if (!btn)
- btn = wxDynamicCast(FindWindow(wxID_CANCEL), wxButton);
- if (!btn)
- btn = wxDynamicCast(FindWindow(wxID_CLOSE), wxButton);
-
- if ( btn && btn->IsEnabled() )
- {
- // if we do have a cancel button, do press it
- btn->MSWCommand(BN_CLICKED, 0 /* unused */);
- processed = true;
- break;
- }
- else
- {
- // Finally, if there aren't appropriate buttons,
- // act as if it were the normal close button.
+ processed = DoOK();
+ if (!processed)
processed = !Close();
- }
-
-#else // ifdef __SMARTPHONE__
+#endif
+#ifdef __SMARTPHONE__
case IDM_LEFT:
case IDM_RIGHT:
processed = HandleCommand( LOWORD(wParam) , 0 , NULL );
msflags |= WS_POPUP;
#endif
- // normally we consider that all windows without caption must be popups,
+ // normally we consider that all windows without a caption must be popups,
// but CE is an exception: there windows normally do not have the caption
// but shouldn't be made popups as popups can't have menus and don't look
// like normal windows anyhow
+
+ // TODO: Smartphone appears to like wxCAPTION, but we should check that
+ // we need it.
+#if defined(__SMARTPHONE__) || !defined(__WXWINCE__)
if ( style & wxCAPTION )
msflags |= WS_CAPTION;
#ifndef __WXWINCE__
else
msflags |= WS_POPUP;
#endif // !__WXWINCE__
+#endif
// next translate the individual flags
if ( style & wxMINIMIZE_BOX )
msflags |= WS_MINIMIZEBOX;
if ( style & wxMAXIMIZE_BOX )
msflags |= WS_MAXIMIZEBOX;
+
+#ifndef __WXWINCE__
if ( style & wxSYSTEM_MENU )
msflags |= WS_SYSMENU;
+#endif
// NB: under CE these 2 styles are not supported currently, we should
// call Minimize()/Maximize() "manually" if we want to support them
if ( style & wxMINIMIZE )
msflags |= WS_MINIMIZE;
+
+#if !defined(__POCKETPC__)
if ( style & wxMAXIMIZE )
msflags |= WS_MAXIMIZE;
+#endif
// Keep this here because it saves recoding this function in wxTinyFrame
if ( style & (wxTINY_CAPTION_VERT | wxTINY_CAPTION_HORIZ) )
ret = CreateFrame(title, pos, sizeReal);
}
+#ifndef __WXWINCE__
if ( ret && !(GetWindowStyleFlag() & wxCLOSE_BOX) )
{
EnableCloseButton(false);
}
+#endif
// for some reason we need to manually send ourselves this message as
// otherwise the mnemonics are always shown -- even if they're configured
);
}
- // Native look is full screen window on Smartphones and Standard SDK
-#if defined(__WXWINCE__)
+ // Native look is full screen window on Smartphones and Standard SDK.
+ // TODO: check that we need this (if we're passing default values to ctor).
+ // Also check that there really is a difference between PocketPC and Smartphone in this regard.
+#if defined(__WXWINCE__) && (defined(__SMARTPHONE__) || defined(__WINCE_STANDARDSDK__))
if ( style & wxMAXIMIZE )
{
this->Maximize();
// under CE, add a "Ok" button in the dialog title bar and make it full
// screen
//
- // VZ: we should probably allow for overriding this, e.g. by including
- // MAXIMIZED flag in the dialog style by default and doing this
- // only if it is present...
-
+ // TODO: find the window for this HWND, and take into account
+ // wxMAXIMIZE and wxCLOSE_BOX. For now, assume both are present.
+ //
// Standard SDK doesn't have aygshell.dll: see
// include/wx/msw/wince/libraries.h
#if defined(__WXWINCE__) && !defined(__WINCE_STANDARDSDK__) && !defined(__HANDHELDPC__)
projects / wxWidgets.git / commitdiff
