added wxListBox::HitTest() from Ryan (patch 1446207)

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

diff --git a/docs/latex/wx/wxmsw.tex b/docs/latex/wx/wxmsw.tex
index 69df7b1157c4850560bec1dd0f7887788408edc1..ca86dc1fb10da1f8b0ba322c55f21127c92e1338 100644 (file)
--- a/docs/latex/wx/wxmsw.tex
+++ b/docs/latex/wx/wxmsw.tex
@@ -1,3 +1,14 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        wxmsw.tex
+%% Purpose:     wxMSW and wxWinCE platform specific informations
+%% Author:      wxWidgets Team
+%% Modified by:
+%% Created:
+%% RCS-ID:      $Id$
+%% Copyright:   (c) wxWidgets Team
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+

 \section{wxMSW port}\label{wxmswport}
 
 wxMSW is a port of wxWidgets for the Windows platforms
 \section{wxMSW port}\label{wxmswport}
 
 wxMSW is a port of wxWidgets for the Windows platforms


@@ -20,7 +31,7 @@ most of wxMSW is common to Win32 and Windows CE but there are
 some simplifications, enhancements, and differences in
 behaviour.
 
 some simplifications, enhancements, and differences in
 behaviour.
 

-For installation instructions, see docs/msw/wince in the
+For building 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.
 
 distribution. The rest of this section documents issues you
 need to be aware of when programming for Windows CE devices.
 


@@ -64,6 +75,13 @@ style of device.
 See the "Life!" example (demos/life) for an example of
 an application that has been tailored for PocketPC and Smartphone use.
 
 See the "Life!" example (demos/life) for an example of
 an application that has been tailored for PocketPC and Smartphone use.
 

+{\bf Note:} don't forget to have this line in your .rc file, as for
+desktop Windows applications:
+
+\begin{verbatim}
+#include "wx/msw/wx.rc"
+\end{verbatim}
+

 \subsubsection{Testing for WinCE SDKs}
 
 Use these preprocessor symbols to test for the different types of device or SDK:
 \subsubsection{Testing for WinCE SDKs}
 
 Use these preprocessor symbols to test for the different types of device or SDK:


@@ -99,8 +117,8 @@ 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).
 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.
+When input panel (SIP) is shown, top level windows (frames and dialogs) resize
+accordingly (see \helpref{wxTopLevelWindow::HandleSettingChange}{wxtoplevelwindowhandlesettingchange}).

 
 \subsubsection{Closing top-level windows in wxWinCE}
 
 
 \subsubsection{Closing top-level windows in wxWinCE}
 


@@ -127,7 +145,7 @@ and unregister the button when you're done with it. For example:
   win->UnregisterHotKey(0);
 \end{verbatim}
 
   win->UnregisterHotKey(0);
 \end{verbatim}
 

-You may have to register the buttons in a wxEVT_ACTIVATE event handler
+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
 since other applications will grab the buttons.
 
 There is currently no method of finding out the names of the special


@@ -139,13 +157,13 @@ 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
 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
+a wxID\_OK event by default. If you wish to change this, call \helpref{wxDialog::SetAffirmativeId}{wxdialogsetaffirmativeid}
+with the required identifier to be used. Or, override \helpref{wxDialog::DoOK}{wxdialogdook} (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
 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:
+using one of the two menu buttons. You need to assign these using \helpref{wxTopLevelWindow::SetLeftMenu}{wxtoplevelwindowsetleftmenu}
+and \helpref{wxTopLevelWindow::SetRightMenu}{wxtoplevelwindowsetrightmenu}, for example:

 
 \begin{verbatim}
 #ifdef __SMARTPHONE__
 
 \begin{verbatim}
 #ifdef __SMARTPHONE__


@@ -158,7 +176,7 @@ and wxTopLevelWindow::SetRightMenu, for example:
 #endif
 \end{verbatim}
 
 #endif
 \end{verbatim}
 

-For implementing property sheets (flat tabs), use a wxNotebook with wxNB_FLAT|wxNB_BOTTOM
+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
 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


@@ -221,6 +239,14 @@ 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.
 
 defines this accelerator by default and if your application handles
 wxID\_EXIT, it will do the right thing.
 

+\subsubsection{Context menus in wxWinCE}
+
+To enable context menus in PocketPC, you currently need to call wxWindow::EnableContextMenu,
+a wxWinCE-only function. Otherwise the context menu event (wxContextMenuEvent) will
+never be sent. This API is subject to change.
+
+Context menus are not supported in Smartphone.
+

 \subsubsection{Control differences on wxWinCE}
 
 These controls and styles are specific to wxWinCE:
 \subsubsection{Control differences on wxWinCE}
 
 These controls and styles are specific to wxWinCE:


@@ -235,8 +261,6 @@ These controls are missing from wxWinCE:
 
 \itemsep=0pt
 \begin{itemize}
 
 \itemsep=0pt
 \begin{itemize}

-\item {\bf wxCheckListBox} This can be implemented using a wxListCtrl in report mode
-with checked/unchecked images.

 \item {\bf MDI classes} MDI is not supported under Windows CE.
 \item {\bf wxMiniFrame} Not supported under Windows CE.
 \end{itemize}
 \item {\bf MDI classes} MDI is not supported under Windows CE.
 \item {\bf wxMiniFrame} Not supported under Windows CE.
 \end{itemize}


@@ -245,6 +269,13 @@ Tooltips are not currently supported for controls, since on PocketPC controls wi
 tooltips are distinct controls, and it will be hard to add dynamic
 tooltip support.
 
 tooltips are distinct controls, and it will be hard to add dynamic
 tooltip support.
 

+Control borders on PocketPC and Smartphone should normally be specified with
+wxSIMPLE\_BORDER instead of wxSUNKEN\_BORDER. Controls will usually adapt
+appropriately by virtue of their GetDefaultBorder() function, but if you
+wish to specify a style explicitly you can use wxDEFAULT\_CONTROL\_BORDER
+which will give a simple border on PocketPC and Smartphone, and the sunken border on
+other platforms.
+

 \subsubsection{Online help in wxWinCE}
 
 You can use the help controller wxWinceHelpController which controls
 \subsubsection{Online help in wxWinCE}
 
 You can use the help controller wxWinceHelpController which controls


@@ -288,8 +319,29 @@ Allowing the user to access files on memory cards, or on arbitrary
 parts of the filesystem, is a pain; the standard file dialog only
 shows folders under My Documents or folders on memory cards
 (not the system or card root directory, for example). This is
 parts of the filesystem, is a pain; the standard file dialog only
 shows folders under My Documents or folders on memory cards
 (not the system or card root directory, for example). This is

-a known problem for PocketPC developers, and a wxFileDialog
-replacement will need to be written.
+a known problem for PocketPC developers.
+
+If you need a file dialog that allows access to all folders,
+you can use wxGenericFileDialog instead. You will need to include 
+{\tt wx/generic/filedlgg.h}.
+
+\subsubsection{Embedded Visual C++ Issues}
+
+\wxheading{Run-time type information}
+
+If you wish to use runtime type information (RTTI) with eVC++ 4, you need to download
+an extra library, {\tt ccrtrtti.lib}, and link with it. At the time of
+writing you can get it from here:
+
+\begin{verbatim}
+http://support.microsoft.com/kb/830482/en-us
+\end{verbatim}
+
+Otherwise you will get linker errors similar to this:
+
+\begin{verbatim}
+wxwince26d.lib(control.obj) : error LNK2001: unresolved external symbol "const type_info::`vftable'" (??_7type_info@@6B@)
+\end{verbatim}

 
 \subsubsection{Remaining issues}
 
 
 \subsubsection{Remaining issues}
 


@@ -309,18 +361,10 @@ and the remaining area, by calling SHSipInfo. We also may need to be able to sho
 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.
 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 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 wxFileDialog.} A more flexible dialog needs to be written (probably using wxGenericFileDialog)
-that can access arbitrary locations.

 \item {\bf HTML control.} PocketPC has its own HTML control which can be used for showing
 local pages or navigating the web. We should create a version of wxHtmlWindow that uses this
 control, or have a separately-named control (wxHtmlCtrl), with a syntax as close as possible to wxHtmlWindow.
 \item {\bf HTML control.} PocketPC has its own HTML control which can be used for showing
 local pages or navigating the web. We should create a version of wxHtmlWindow that uses this
 control, or have a separately-named control (wxHtmlCtrl), with a syntax as close as possible to wxHtmlWindow.


@@ -328,11 +372,19 @@ control, or have a separately-named control (wxHtmlCtrl), with a syntax as close
 tooltips, with the tooltip separated from the label with a double tilde. We need to support this using SetToolTip.
 (Unfortunately it does not seem possible to dynamically remove the tooltip, so an extra style may
 be required.)
 tooltips, with the tooltip separated from the label with a double tilde. We need to support this using SetToolTip.
 (Unfortunately it does not seem possible to dynamically remove the tooltip, so an extra style may
 be required.)

+\item {\bf Focus.} In the wxPropertySheetDialog demo on Smartphone, it's not possible to navigate
+between controls. The focus handling in wxWidgets needs investigation. See in particular src/common/containr.cpp,
+and note that the default OnActivate handler in src/msw/toplevel.cpp sets the focus to the first child of the dialog.

 \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 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 Modeless dialogs.} When a modeless dialog is hidden with the OK button, it doesn't restore the
+frame's menubar. See for example the find dialog in the dialogs sample. However, the menubar is restored
+if pressing Cancel (the window is closed). This reflects the fact that modeless dialogs are
+not very useful on Windows CE; however, we could perhaps destroy/restore a modeless dialog's menubar
+on deactivation and activation.

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


@@ -342,4 +394,3 @@ 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}
 \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}

-