define _HPUX_SOURCE under HP-UX, otherwise many things are not defined in standard...

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

diff --git a/docs/latex/wx/wxmsw.tex b/docs/latex/wx/wxmsw.tex
index 637a048123eb5d9dc226a02b586693039cdf9fb4..d73426584cd7efcba412c3ff70627ae7a3535b95 100644 (file)
--- a/docs/latex/wx/wxmsw.tex
+++ b/docs/latex/wx/wxmsw.tex
@@ -20,7 +20,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 +64,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:


@@ -102,6 +109,37 @@ 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.
 
 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
 \subsubsection{Dialogs in wxWinCE}
 
 PocketPC dialogs have an OK button on the caption, and so you should generally


@@ -127,7 +165,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


@@ -136,16 +174,48 @@ provided, to show settings in the correct style on PocketPC and on other platfor
 Notifications (bubble HTML text with optional buttons and links) will also be
 implemented in the future for PocketPC.
 
 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}
 
 \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.
+\wxheading{Menubars and toolbars in PocketPC}

 
 On PocketPC, a frame must always have a menubar, even if it's empty.
 
 On PocketPC, a frame must always have a menubar, even if it's empty.

+An empty menubar/toolbar 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 after Realize is called is not supported.
+\item For speed, colours are not remapped to the system colours as they are
+in wxMSW. Provide the tool bitmaps either with the correct system button background,
+or with transparency (for example, using XPMs).
+\item Adding controls to wxToolMenuBar is not supported. However, wxToolBar supports
+controls.
+\end{itemize}
+
+Unlike in all other ports, a wxDialog has a wxToolBar, automatically created
+for you. You may either leave it blank, or access it with wxDialog::GetToolBar
+and add buttons, then calling wxToolBar::Realize. You cannot set or recreate
+the toolbar.
+
+\wxheading{Menubars and toolbars in Smartphone}

 
 On Smartphone, there are only two menu buttons, so a menubar is simulated
 
 On Smartphone, there are only two menu buttons, so a menubar is simulated

-using a nested menu on the right menu button. Toolbars are simply ignored on
+using a nested menu on the right menu button. Any toolbars are simply ignored on

 Smartphone.
 
 \subsubsection{Closing windows in wxWinCE}
 Smartphone.
 
 \subsubsection{Closing windows in wxWinCE}


@@ -160,14 +230,98 @@ wxID\_EXIT, it will do the right thing.
 
 \subsubsection{Control differences on wxWinCE}
 
 
 \subsubsection{Control differences on wxWinCE}
 

-This section is to be written.
+These controls and styles are specific to wxWinCE:
+
+\itemsep=0pt
+\begin{itemize}
+\item {\bf wxTextCtrl} The wxTE\_CAPITALIZE style causes a CAPEDIT control to
+be created, which capitalizes the first letter.
+\end{itemize}
+
+These controls are missing from wxWinCE:

 
 

-Can someone remind us why wxChoice was rewritten for Smartphone?
+\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}
+
+Tooltips are not currently supported for controls, since on PocketPC controls with
+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
 simple {\tt .htm} files, usually installed in the Windows directory.
 
 \subsubsection{Online help in wxWinCE}
 
 You can use the help controller wxWinceHelpController which controls
 simple {\tt .htm} files, usually installed in the Windows directory.

+See the Windows CE reference for how to format the HTML files.
+
+\subsubsection{Installing your PocketPC and Smartphone applications}
+
+To install your application, you need to build a CAB file using
+the parameters defined in a special .inf file. The CabWiz program
+in your SDK will compile the CAB file from the .inf file and
+files that it specifies.
+
+For delivery, you can simply ask the user to copy the CAB file to the
+device and execute the CAB file using File Explorer. Or, you can
+write a program for the desktop PC that will find the ActiveSync
+Application Manager and install the CAB file on the device,
+which is obviously much easier for the user.
+
+Here are some links that may help.
+
+\itemsep=0pt
+\begin{itemize}
+\item A setup builder that takes CABs and builds a setup program is at \urlref{http://www.eskimo.com/~scottlu/win/index.html}{http://www.eskimo.com/~scottlu/win/index.html}.
+\item Sample installation files can be found in {\tt Windows CE Tools/wce420/POCKET PC 2003/Samples/Win32/AppInst}.
+\item An installer generator using wxPython can be found at \urlref{http://ppcquicksoft.iespana.es/ppcquicksoft/myinstall.html}{http://ppcquicksoft.iespana.es/ppcquicksoft/myinstall.html}.
+\item Miscellaneous Windows CE resources can be found at \urlref{http://www.orbworks.com/pcce/resources.html}{http://www.orbworks.com/pcce/resources.html}.
+\item Installer creation instructions with a setup.exe for installing to PPC can be found at \urlref{http://www.pocketpcdn.com/articles/creatingsetup.html}{http://www.pocketpcdn.com/articles/creatingsetup.html}.
+\item Microsoft instructions are at \urlref{http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnce30/html/appinstall30.asp?frame=true&hidetoc=true}{http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnce30/html/appinstall30.asp?frame=true&hidetoc=true}.
+\item Troubleshooting WinCE application installations: \urlref{http://support.microsoft.com/default.aspx?scid=KB;en-us;q181007}{http://support.microsoft.com/default.aspx?scid=KB;en-us;q181007}
+\end{itemize}
+
+You may also check out {\tt demos/life/setup/wince} which contains
+scripts to create a PocketPC installation for ARM-based
+devices. In particular, {\tt build.bat} builds the distribution and
+copies it to a directory called {\tt Deliver}.
+
+\subsubsection{wxFileDialog in PocketPC}
+
+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
+a known problem for PocketPC developers, and a wxFileDialog
+replacement will need to be written.
+
+\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}
 


@@ -182,26 +336,40 @@ needs to be simplified (and speeded up).
 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.
 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 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
 \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.
+show the SIP automatically using the WC\_SIPREF control.

 \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 Tooltip control.} PocketPC uses special TTBUTTON and TTSTATIC controls for adding
+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