remove C++ comment

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

diff --git a/docs/latex/wx/wxmsw.tex b/docs/latex/wx/wxmsw.tex
index d73426584cd7efcba412c3ff70627ae7a3535b95..7ed271eb6f148328ed8db836b94d0d1ef28fe8d6 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


@@ -13,6 +24,39 @@ MinGW32 tool chain.
 For further information, please see the files in docs/msw
 in the distribution.
 
 For further information, please see the files in docs/msw
 in the distribution.
 

+\subsection{Themed borders on Windows}\label{wxmswthemedborders}
+
+Starting with wxWidgets 2.8.5, you can specify the wxBORDER\_THEME style to have wxWidgets
+use a themed border. Using the default XP theme, this is a thin 1-pixel blue border,
+with an extra 1-pixel border in the window client background colour (usually white) to
+separate the client area's scrollbars from the border.
+
+If you don't specify a border style for a wxTextCtrl in rich edit mode, wxWidgets now gives
+the control themed borders automatically, where previously they would take the Windows 95-style
+sunken border. Other native controls such as wxTextCtrl in non-rich edit mode, and wxComboBox,
+already paint themed borders where appropriate. To use themed borders on other windows, such
+as wxPanel, pass the wxBORDER\_THEME style, or (apart from wxPanel) pass no border style.
+
+In general, specifying wxBORDER\_THEME will cause a border of some kind to be used, chosen by the platform
+and control class. To leave the border decision entirely to wxWidgets, pass wxBORDER\_DEFAULT.
+This is not to be confused with specifying wxBORDER\_NONE, which says that there should
+definitely be {\it no} border.
+
+\wxheading{More detail on border implementation}
+
+The way that wxMSW decides whether to apply a themed border is as follows.
+The theming code calls wxWindow::GetBorder() to obtain a border. If no border style has been
+passed to the window constructor, GetBorder() calls GetDefaultBorder() for this window.
+If wxBORDER\_THEME was passed to the window constructor, GetBorder() calls GetDefaultBorderForControl().
+
+The implementation of wxWindow::GetDefaultBorder() on wxMSW calls wxWindow::CanApplyThemeBorder()
+which is a virtual function that tells wxWidgets whether a control can have a theme
+applied explicitly (some native controls already paint a theme in which case we should not
+apply it ourselves). Note that wxPanel is an exception to this rule because in many cases
+we wish to create a window with no border (for example, notebook pages). So wxPanel
+overrides GetDefaultBorder() in order to call the generic wxWindowBase::GetDefaultBorder(),
+returning wxBORDER\_NONE.
+

 \subsection{wxWinCE}\label{wxwince}
 
 wxWinCE is the name given to wxMSW when compiled on Windows CE devices;
 \subsection{wxWinCE}\label{wxwince}
 
 wxWinCE is the name given to wxMSW when compiled on Windows CE devices;


@@ -21,7 +65,8 @@ some simplifications, enhancements, and differences in
 behaviour.
 
 For building instructions, see docs/msw/wince in the
 behaviour.
 
 For building instructions, see docs/msw/wince in the

-distribution. The rest of this section documents issues you
+distribution, also the section about Visual Studio 2005 project
+files below. 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}
 need to be aware of when programming for Windows CE devices.
 
 \subsubsection{General issues for wxWinCE programming}


@@ -96,18 +141,14 @@ wxGetOsVersion will return these values:
 
 \subsubsection{Window sizing in wxWinCE}
 
 
 \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.)
+Top level windows (dialogs, frames) are created always full-screen. Fit() of sizers will not rescale top
+level windows but instead will scale window content.

 
 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}
 


@@ -146,13 +187,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__


@@ -228,6 +269,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:


@@ -242,8 +291,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}


@@ -253,7 +300,7 @@ 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
 tooltip support.
 
 Control borders on PocketPC and Smartphone should normally be specified with

-wxSIMPLE\_BORDER instead of wxSUNKEN\_BORDER. Controls will usually adapt
+wxBORDER\_SIMPLE instead of wxBORDER\_SUNKEN. 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
 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


@@ -302,8 +349,11 @@ 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}
 
 
 \subsubsection{Embedded Visual C++ Issues}
 


@@ -323,6 +373,29 @@ Otherwise you will get linker errors similar to this:
 wxwince26d.lib(control.obj) : error LNK2001: unresolved external symbol "const type_info::`vftable'" (??_7type_info@@6B@)
 \end{verbatim}
 
 wxwince26d.lib(control.obj) : error LNK2001: unresolved external symbol "const type_info::`vftable'" (??_7type_info@@6B@)
 \end{verbatim}
 

+\wxheading{Windows Mobile 5.0 emulator}
+
+Note that there is no separate emulator configuration for Windows Mobile 5.0: the
+emulator runs the ARM code directly.
+
+\wxheading{Visual Studio 2005 project files}
+
+Unfortunately, Visual Studio 2005, required to build Windows Mobile 5.0 applications,
+doesn't do a perfect job of converting the project files from eVC++ format.
+
+When you have converted the wxWidgets workspace, edit the configuration properties
+for each configuration and in the Librarian, add a relative path ..$\backslash$..$\backslash$lib to
+each library path. For example: {\tt ..$\backslash$\$(PlatformName)$\backslash$\$(ConfigurationName)$\backslash$wx\_mono.lib}.
+
+Then, for a sample you want to compile, edit the configuration properties
+and make sure {\tt ..$\backslash$..$\backslash$lib$\backslash$\$(PlatformName)$\backslash$\$(ConfigurationName)} is in the Linker/General/Additional
+Library Directories property. Also change the Linker/Input/Additional Dependencies
+property to something like {\tt coredll.lib wx\_mono.lib wx\_wxjpeg.lib wx\_wxpng.lib wx\_wxzlib.lib wx\_wxexpat.lib commctrl.lib winsock.lib wininet.lib}\rtfsp
+(since the library names in the wxWidgets workspace were changed by VS 2005).
+
+Alternately, you could could edit all the names to be identical to the original eVC++
+names, but this will probably be more fiddly.
+

 \subsubsection{Remaining issues}
 
 These are some of the remaining problems to be sorted out, and features
 \subsubsection{Remaining issues}
 
 These are some of the remaining problems to be sorted out, and features


@@ -330,8 +403,11 @@ to be supported.
 
 \itemsep=0pt
 \begin{itemize}
 
 \itemsep=0pt
 \begin{itemize}

-\item {\bf Font dialog.} The generic font dialog is currently used, which
-needs to be simplified (and speeded up).
+\item {\bf Windows Mobile 5 issues.} It is not possible to get the HMENU for
+the command bar on Mobile 5, so the menubar functions need to be rewritten
+to get the individual menus without use of a menubar handle. Also the
+new Mobile 5 convention of using only two menus (and no bitmap buttons) needs to be
+considered.

 \item {\bf Sizer speed.} Particularly for dialogs containing notebooks,
 layout seems slow. Some analysis is required.
 \item {\bf Notification boxes.} The balloon-like notification messages, and their
 \item {\bf Sizer speed.} Particularly for dialogs containing notebooks,
 layout seems slow. Some analysis is required.
 \item {\bf Notification boxes.} The balloon-like notification messages, and their


@@ -345,11 +421,6 @@ show the SIP automatically using the WC\_SIPREF control.
 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.
 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.


@@ -378,5 +449,8 @@ 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.
 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.

+\item {\bf Dialog captions.} The blue, bold captions on dialogs - with optional help button -
+should be catered for, either by hard-wiring the capability into all dialogs and panels,
+or by providing a standard component and sizer.

 \end{itemize}
 
 \end{itemize}