Updated symbols

[wxWidgets.git] / docs / latex / wx / wxmsw.tex

\section{wxMSW port}\label{wxmswport}

wxMSW is a port of wxWidgets for the Windows platforms
including Windows 95, 98, ME, 2000, NT, XP in ANSI and
Unicode mode (for Windows 95 through the MSLU extension
library). wxMSW ensures native look and feel for XP
as well when using wxWidgets version 2.3.3 or higher.
wxMSW can be compile with a great variety of compilers
including MS VC++, Borland 5.5, MinGW32, Cygwin and
Watcom as well as cross-compilation with a Linux hosted
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 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}

\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}