don't call wxString::Len() from operator==; use IsSameAs() instead of move the length...

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

diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex
index 1ce3f15b5f9dfb081a2e6559f342b3f4f3ed1a1b..cf6e0c3ecab346b34e6c04dc51c7de9a8eabfb7e 100644 (file)
--- a/docs/latex/wx/window.tex
+++ b/docs/latex/wx/window.tex
@@ -52,15 +52,16 @@ window class or on all platforms.
 
 \twocolwidtha{5cm}%
 \begin{twocollist}\itemsep=0pt
 
 \twocolwidtha{5cm}%
 \begin{twocollist}\itemsep=0pt

+\twocolitem{\windowstyle{wxBORDER\_DEFAULT}}{The window class will decide the kind of border to show, if any.}

 \twocolitem{\windowstyle{wxBORDER\_SIMPLE}}{Displays a thin border around the window. wxSIMPLE\_BORDER is the old name
 for this style. }
 \twocolitem{\windowstyle{wxBORDER\_SIMPLE}}{Displays a thin border around the window. wxSIMPLE\_BORDER is the old name
 for this style. }

-\twocolitem{\windowstyle{wxBORDER\_DOUBLE}}{Displays a double border. wxDOUBLE\_BORDER is the old name for this style. Windows and Mac only.}

 \twocolitem{\windowstyle{wxBORDER\_SUNKEN}}{Displays a sunken border. wxSUNKEN\_BORDER is the old name for this style.}
 \twocolitem{\windowstyle{wxBORDER\_RAISED}}{Displays a raised border. wxRAISED\_BORDER is the old name for this style. }
 \twocolitem{\windowstyle{wxBORDER\_STATIC}}{Displays a border suitable for a static control.  wxSTATIC\_BORDER is the old name for this style. Windows only. }
 \twocolitem{\windowstyle{wxBORDER\_SUNKEN}}{Displays a sunken border. wxSUNKEN\_BORDER is the old name for this style.}
 \twocolitem{\windowstyle{wxBORDER\_RAISED}}{Displays a raised border. wxRAISED\_BORDER is the old name for this style. }
 \twocolitem{\windowstyle{wxBORDER\_STATIC}}{Displays a border suitable for a static control.  wxSTATIC\_BORDER is the old name for this style. Windows only. }

-\twocolitem{\windowstyle{wxBORDER\_THEME}}{Displays a themed border where possible. Currently this has an effect on Windows XP and above only.
-For more information on themed borders, please see \helpref{Themed borders on Windows}{wxmswthemedborders}.}
+\twocolitem{\windowstyle{wxBORDER\_THEME}}{Displays a native border suitable for a control, on the current platform. On Windows XP or Vista, this will be a themed border; on most other platforms
+a sunken border will be used. For more information for themed borders on Windows, please see \helpref{Themed borders on Windows}{wxmswthemedborders}.}

 \twocolitem{\windowstyle{wxBORDER\_NONE}}{Displays no border, overriding the default border style for the window. wxNO\_BORDER is the old name for this style.}
 \twocolitem{\windowstyle{wxBORDER\_NONE}}{Displays no border, overriding the default border style for the window. wxNO\_BORDER is the old name for this style.}

+\twocolitem{\windowstyle{wxBORDER\_DOUBLE}}{This style is obsolete and should not be used.}

 \twocolitem{\windowstyle{wxTRANSPARENT\_WINDOW}}{The window is transparent, that is, it will not receive paint
 events. Windows only.}
 \twocolitem{\windowstyle{wxTAB\_TRAVERSAL}}{Use this to enable tab traversal for non-dialog windows.}
 \twocolitem{\windowstyle{wxTRANSPARENT\_WINDOW}}{The window is transparent, that is, it will not receive paint
 events. Windows only.}
 \twocolitem{\windowstyle{wxTAB\_TRAVERSAL}}{Use this to enable tab traversal for non-dialog windows.}


@@ -218,6 +219,26 @@ called by the user code.
 \docparam{child}{Child window to add.}
 
 
 \docparam{child}{Child window to add.}
 
 

+\membersection{wxWindow::AlwaysShowScrollbars}\label{wxwindowalwaysshowscrollbars}
+
+\func{void}{AlwaysShowScrollbars}{\param{bool}{ hflag}, \param{bool}{ vflag}}
+
+Call this function to force one or both scrollbars to be always shown, even if
+the window is big enough to show its entire contents without scrolling.
+
+\newsince{2.9.0}
+
+\wxheading{Parameters}
+
+\docparam{hflag}{Whether the horizontal scroll bar should always be visible.}
+
+\docparam{vflag}{Whether the vertical scroll bar should always be visible.}
+
+\wxheading{Remarks}
+
+This function is currently only implemented under Mac/Carbon.
+
+

 \membersection{wxWindow::CacheBestSize}\label{wxwindowcachebestsize}
 
 \constfunc{void}{CacheBestSize}{\param{const wxSize\& }{size}}
 \membersection{wxWindow::CacheBestSize}\label{wxwindowcachebestsize}
 
 \constfunc{void}{CacheBestSize}{\param{const wxSize\& }{size}}


@@ -225,6 +246,16 @@ called by the user code.
 Sets the cached best size value.
 
 
 Sets the cached best size value.
 
 

+\membersection{wxWindow::CanSetTransparent}\label{wxwindowcansettransparent}
+
+\func{bool}{CanSetTransparent}{\void}
+
+Returns \true if the system supports transparent windows and calling 
+\helpref{SetTransparent}{wxwindowsettransparent} may succeed. If this function
+returns \false, transparent windows are definitely not supported by the current
+system.
+
+

 \membersection{wxWindow::CaptureMouse}\label{wxwindowcapturemouse}
 
 \func{virtual void}{CaptureMouse}{\void}
 \membersection{wxWindow::CaptureMouse}\label{wxwindowcapturemouse}
 
 \func{virtual void}{CaptureMouse}{\void}


@@ -264,13 +295,6 @@ A synonym for \helpref{Centre}{wxwindowcentre}.
 A synonym for \helpref{CentreOnParent}{wxwindowcentreonparent}.
 
 
 A synonym for \helpref{CentreOnParent}{wxwindowcentreonparent}.
 
 

-\membersection{wxWindow::CenterOnScreen}\label{wxwindowcenteronscreen}
-
-\func{void}{CenterOnScreen}{\param{int}{ direction}}
-
-A synonym for \helpref{CentreOnScreen}{wxwindowcentreonscreen}.
-
-

 \membersection{wxWindow::Centre}\label{wxwindowcentre}
 
 \func{void}{Centre}{\param{int}{ direction = wxBOTH}}
 \membersection{wxWindow::Centre}\label{wxwindowcentre}
 
 \func{void}{Centre}{\param{int}{ direction = wxBOTH}}


@@ -318,24 +342,7 @@ window is not a top level window, then behaviour is the same as
 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

-\helpref{wxWindow::CentreOnScreen}{wxwindowcenteronscreen}
-
-
-\membersection{wxWindow::CentreOnScreen}\label{wxwindowcentreonscreen}
-
-\func{void}{CentreOnScreen}{\param{int}{ direction = wxBOTH}}
-
-Centres the window on screen. This only works for top level windows -
-otherwise, the window will still be centered on its parent.
-
-\wxheading{Parameters}
-
-\docparam{direction}{Specifies the direction for the centering. May be {\tt wxHORIZONTAL}, {\tt wxVERTICAL}\rtfsp
-or {\tt wxBOTH}.}
-
-\wxheading{See also}
-
-\helpref{wxWindow::CentreOnParent}{wxwindowcenteronparent}
+\helpref{wxTopLevelWindow::CentreOnScreen}{wxtoplevelwindowcenteronscreen}

 
 
 \membersection{wxWindow::ClearBackground}\label{wxwindowclearbackground}
 
 
 \membersection{wxWindow::ClearBackground}\label{wxwindowclearbackground}


@@ -721,7 +728,8 @@ subwindows.
 Freezes the window or, in other words, prevents any updates from taking place
 on screen, the window is not redrawn at all. \helpref{Thaw}{wxwindowthaw} must
 be called to reenable window redrawing. Calls to these two functions may be
 Freezes the window or, in other words, prevents any updates from taking place
 on screen, the window is not redrawn at all. \helpref{Thaw}{wxwindowthaw} must
 be called to reenable window redrawing. Calls to these two functions may be

-nested.
+nested but to ensure that the window is properly repainted again, you must thaw
+it exactly as many times as you froze it.

 
 This method is useful for visual appearance optimization (for example, it
 is a good idea to use it before doing many large text insertions in a row into
 
 This method is useful for visual appearance optimization (for example, it
 is a good idea to use it before doing many large text insertions in a row into


@@ -774,19 +782,32 @@ Returns the background colour of the window.
 
 \constfunc{virtual wxBackgroundStyle}{GetBackgroundStyle}{\void}
 
 
 \constfunc{virtual wxBackgroundStyle}{GetBackgroundStyle}{\void}
 

-Returns the background style of the window. The background style indicates
-whether background colour should be determined by the system (wxBG\_STYLE\_SYSTEM),
-be set to a specific colour (wxBG\_STYLE\_COLOUR), or should be left to the
-application to implement (wxBG\_STYLE\_CUSTOM).
-
-On GTK+, use of wxBG\_STYLE\_CUSTOM allows the flicker-free drawing of a custom
-background, such as a tiled bitmap. Currently the style has no effect on other platforms.
+Returns the background style of the window. The background style can be one of:
+\begin{twocollist}\itemsep=0pt
+\twocolitem{wxBG\_STYLE\_SYSTEM}{Use the default background, as determined by
+the system or the current theme.}
+\twocolitem{wxBG\_STYLE\_COLOUR}{Use a solid colour for the background, this
+style is set automatically if you call 
+\helpref{SetBackgroundColour}{wxwindowsetbackgroundcolour} so you only need to
+set it explicitly if you had changed the background style to something else
+before.}
+\twocolitem{wxBG\_STYLE\_CUSTOM}{Don't draw the background at all, it's
+supposed that it is drawn by the user-defined erase background event handler.
+This style should be used to avoid flicker when the background is entirely
+custom-drawn.}
+\twocolitem{wxBG\_STYLE\_TRANSPARET}{The background is (partially) transparent,
+this style is automatically set if you call 
+\helpref{SetTransparent}{wxwindowsettransparent} which is used to set the
+transparency level.}
+\end{twocollist}

 
 \wxheading{See also}
 
 \helpref{wxWindow::SetBackgroundColour}{wxwindowsetbackgroundcolour},\rtfsp
 \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp
 
 \wxheading{See also}
 
 \helpref{wxWindow::SetBackgroundColour}{wxwindowsetbackgroundcolour},\rtfsp
 \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp

-\helpref{wxWindow::SetBackgroundStyle}{wxwindowsetbackgroundstyle}
+\helpref{wxWindow::SetBackgroundStyle}{wxwindowsetbackgroundstyle},\rtfsp
+\helpref{wxWindow::SetTransparent}{wxwindowsettransparent}
+

 
 \membersection{wxWindow::GetEffectiveMinSize}\label{wxwindowgeteffectiveminsize}
 
 
 \membersection{wxWindow::GetEffectiveMinSize}\label{wxwindowgeteffectiveminsize}
 


@@ -1153,6 +1174,20 @@ name in the window constructor or via \helpref{wxWindow::SetName}{wxwindowsetnam
 \helpref{wxWindow::SetName}{wxwindowsetname}
 
 
 \helpref{wxWindow::SetName}{wxwindowsetname}
 
 

+\membersection{wxWindow::GetNextSibling}\label{wxwindowgetnextsibling}
+
+\constfunc{wxWindow *}{GetNextSibling}{\void}
+
+Returns the next window after this one among the parent children or \NULL if
+this window is the last child.
+
+\newsince{2.8.8}
+
+\wxheading{See also}
+
+\helpref{GetPrevSibling}{wxwindowgetprevsibling}
+
+

 \membersection{wxWindow::GetParent}\label{wxwindowgetparent}
 
 \constfunc{virtual wxWindow*}{GetParent}{\void}
 \membersection{wxWindow::GetParent}\label{wxwindowgetparent}
 
 \constfunc{virtual wxWindow*}{GetParent}{\void}


@@ -1160,6 +1195,33 @@ name in the window constructor or via \helpref{wxWindow::SetName}{wxwindowsetnam
 Returns the parent of the window, or NULL if there is no parent.
 
 
 Returns the parent of the window, or NULL if there is no parent.
 
 

+\membersection{wxWindow::GetPopupMenuSelectionFromUser}\label{wxwindowgetpopupmenuselectionfromuser}
+
+\func{int}{GetPopupMenuSelectionFromUser}{\param{wxMenu\&}{ menu}, \param{const wxPoint\&}{ pos}}
+
+\func{int}{GetPopupMenuSelectionFromUser}{\param{wxMenu\&}{ menu}, \param{int}{ x}, \param{int}{ y}}
+
+This function shows a popup menu at the given position in this window and
+returns the selected id. It can be more convenient than the general purpose
+\helpref{PopupMenu}{wxwindowpopupmenu} function for simple menus proposing a
+choice in a list of strings to the user.
+
+\wxheading{Parameters}
+
+\docparam{menu}{The menu to show}
+
+\docparam{pos}{The position at which to show the menu in client coordinates}
+
+\docparam{x}{The horizontal position of the menu}
+
+\docparam{y}{The vertical position of the menu}
+
+\wxheading{Return value}
+
+The selected menu item id or \texttt{wxID\_NONE} if none selected or an error
+occurred.
+
+

 \membersection{wxWindow::GetPosition}\label{wxwindowgetposition}
 
 \constfunc{virtual void}{GetPosition}{\param{int* }{x}, \param{int* }{y}}
 \membersection{wxWindow::GetPosition}\label{wxwindowgetposition}
 
 \constfunc{virtual void}{GetPosition}{\param{int* }{x}, \param{int* }{y}}


@@ -1199,6 +1261,20 @@ method:\par
 \helpref{GetScreenPosition}{wxwindowgetscreenposition}
 
 
 \helpref{GetScreenPosition}{wxwindowgetscreenposition}
 
 

+\membersection{wxWindow::GetPrevSibling}\label{wxwindowgetprevsibling}
+
+\constfunc{wxWindow *}{GetPrevSibling}{\void}
+
+Returns the previous window before this one among the parent children or \NULL if
+this window is the first child.
+
+\newsince{2.8.8}
+
+\wxheading{See also}
+
+\helpref{GetNextSibling}{wxwindowgetnextsibling}
+
+

 \membersection{wxWindow::GetRect}\label{wxwindowgetrect}
 
 \constfunc{virtual wxRect}{GetRect}{\void}
 \membersection{wxWindow::GetRect}\label{wxwindowgetrect}
 
 \constfunc{virtual wxRect}{GetRect}{\void}


@@ -1440,6 +1516,13 @@ Returns the value previously passed to
 \helpref{wxWindow::SetWindowVariant}{wxwindowsetwindowvariant}.
 
 
 \helpref{wxWindow::SetWindowVariant}{wxwindowsetwindowvariant}.
 
 

+\membersection{wxWindow::HandleWindowEvent}\label{wxwindowhandlewindowevent}
+
+\func{bool}{HandleWindowEvent}{\param{wxEvent\& }{event}}
+
+Shorthand for \texttt{\helpref{GetEventHandler}{wxwindowgeteventhandler}()->\helpref{SafelyProcessEvent}{wxevthandlersafelyprocessevent}(event)}.
+
+

 \membersection{wxWindow::HasCapture}\label{wxwindowhascapture}
 
 \constfunc{virtual bool}{HasCapture}{\void}
 \membersection{wxWindow::HasCapture}\label{wxwindowhascapture}
 
 \constfunc{virtual bool}{HasCapture}{\void}


@@ -1515,6 +1598,20 @@ wxWindow-derived class to ensure that background is painted correctly.
 Equivalent to calling \helpref{Show}{wxwindowshow}({\tt false}).
 
 
 Equivalent to calling \helpref{Show}{wxwindowshow}({\tt false}).
 
 

+\membersection{wxWindow::HideWithEffect}\label{wxwindowhidewitheffect}
+
+\func{virtual bool}{HideWithEffect}{\param{wxShowEffect }{effect}, \param{unsigned }{timeout = $0$}, \param{wxDirection }{dir = wxBOTTOM}}
+
+This function hides a window, like \helpref{Hide()}{wxwindowhide}, but using a
+special visual effect if possible.
+
+The parameters of this function are the same as for 
+\helpref{ShowWithEffect()}{wxwindowshowwitheffect}, please see their
+description there.
+
+\newsince{2.9.0}
+
+

 \membersection{wxWindow::InheritAttributes}\label{wxwindowinheritattributes}
 
 \func{void}{InheritAttributes}{\void}
 \membersection{wxWindow::InheritAttributes}\label{wxwindowinheritattributes}
 
 \func{void}{InheritAttributes}{\void}


@@ -1635,6 +1732,21 @@ Returns {\tt true} if the window is retained, {\tt false} otherwise.
 Retained windows are only available on X platforms.
 
 
 Retained windows are only available on X platforms.
 
 

+\membersection{wxWindow::IsScrollbarAlwaysShown}\label{wxwindowisscrollbaralwaysshown}
+
+\func{bool}{IsScrollbarAlwaysShown}{\param{int}{ orient}}
+
+Return whether a scrollbar is always shown.
+
+\wxheading{Parameters}
+
+\docparam{orient}{Orientation to check, either {\tt wxHORIZONTAL} or {\tt wxVERTICAL}.}
+
+\wxheading{See also}
+
+\helpref{wxWindow::AlwaysShowScrollbars}{wxwindowalwaysshowscrollbars}
+
+

 \membersection{wxWindow::IsShown}\label{wxwindowisshown}
 
 \constfunc{virtual bool}{IsShown}{\void}
 \membersection{wxWindow::IsShown}\label{wxwindowisshown}
 
 \constfunc{virtual bool}{IsShown}{\void}


@@ -2765,19 +2877,15 @@ applications on the system.
 
 \func{virtual void}{SetBackgroundStyle}{\param{wxBackgroundStyle}{ style}}
 
 
 \func{virtual void}{SetBackgroundStyle}{\param{wxBackgroundStyle}{ style}}
 

-Sets the background style of the window. The background style indicates
-whether background colour should be determined by the system (wxBG\_STYLE\_SYSTEM),
-be set to a specific colour (wxBG\_STYLE\_COLOUR), or should be left to the
-application to implement (wxBG\_STYLE\_CUSTOM).
-
-On GTK+, use of wxBG\_STYLE\_CUSTOM allows the flicker-free drawing of a custom
-background, such as a tiled bitmap. Currently the style has no effect on other platforms.
+Sets the background style of the window. see 
+\helpref{GetBackgroundStyle()}{wxwindowgetbackgroundstyle} for the description
+of the possible style values.

 
 \wxheading{See also}
 
 \helpref{wxWindow::SetBackgroundColour}{wxwindowsetbackgroundcolour},\rtfsp
 \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp
 
 \wxheading{See also}
 
 \helpref{wxWindow::SetBackgroundColour}{wxwindowsetbackgroundcolour},\rtfsp
 \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp

-\helpref{wxWindow::GetBackgroundStyle}{wxwindowgetbackgroundstyle}
+\helpref{wxWindow::SetTransparent}{wxwindowsettransparent}

 
 
 
 
 
 


@@ -3517,6 +3625,20 @@ See also: \helpref{GetToolTip}{wxwindowgettooltip},
  \helpref{wxToolTip}{wxtooltip}
 
 
  \helpref{wxToolTip}{wxtooltip}
 
 

+\membersection{wxWindow::SetTransparent}\label{wxwindowsettransparent}
+
+\func{bool}{SetTransparent}{\param{wxByte }{alpha}}
+
+Set the transparency of the window. If the system supports transparent windows,
+returns \true, otherwise returns \false and the window remains fully opaque.
+See also \helpref{CanSetTransparent}{wxwindowcansettransparent}.
+
+The parameter \arg{alpha} is in the range $0..255$ where $0$ corresponds to a
+fully transparent window and $255$ to the fully opaque one. The constants
+\texttt{wxIMAGE\_ALPHA\_TRANSPARENT} and \texttt{wxIMAGE\_ALPHA\_OPAQUE} can be
+used.
+
+

 \membersection{wxWindow::SetValidator}\label{wxwindowsetvalidator}
 
 \func{virtual void}{SetValidator}{\param{const wxValidator\&}{ validator}}
 \membersection{wxWindow::SetValidator}\label{wxwindowsetvalidator}
 
 \func{virtual void}{SetValidator}{\param{const wxValidator\&}{ validator}}


@@ -3647,6 +3769,39 @@ done because it already was in the requested state.
 \helpref{wxRadioBox::Show}{wxradioboxshow}
 
 
 \helpref{wxRadioBox::Show}{wxradioboxshow}
 
 

+\membersection{wxWindow::ShowWithEffect}\label{wxwindowshowwitheffect}
+
+\func{virtual bool}{ShowWithEffect}{\param{wxShowEffect }{effect}, \param{unsigned }{timeout = $0$}, \param{wxDirection }{dir = wxBOTTOM}}
+
+This function shows a window, like \helpref{Show()}{wxwindowshow}, but using a
+special visual effect if possible.
+
+Possible values for \arg{effect} are:
+\begin{twocollist}\itemsep=0pt
+\twocolitem{wxSHOW\_EFFECT\_ROLL}{Roll window effect}
+\twocolitem{wxSHOW\_EFFECT\_SLIDE}{Sliding window effect}
+\twocolitem{wxSHOW\_EFFECT\_BLEND}{Fade in or out effect}
+\twocolitem{wxSHOW\_EFFECT\_EXPAND}{Expanding or collapsing effect}
+\end{twocollist}
+
+For the roll and slide effects the \arg{dir} parameter specifies the animation
+direction: it can be one of \texttt{wxTOP}, \texttt{wxBOTTOM}, \texttt{wxLEFT} 
+or \texttt{wxRIGHT}. For the other effects, this parameter is unused.
+
+The \arg{timeout} parameter specifies the time of the animation, in
+milliseconds. If the default value of $0$ is used, the default animation time
+for the current platform is used.
+
+Currently this function is only implemented in wxMSW and does the same thing as
+Show() in the other ports.
+
+\newsince{2.9.0}
+
+\wxheading{See also}
+
+\helpref{HideWithEffect}{wxwindowhidewitheffect}
+
+

 \membersection{wxWindow::Thaw}\label{wxwindowthaw}
 
 \func{virtual void}{Thaw}{\void}
 \membersection{wxWindow::Thaw}\label{wxwindowthaw}
 
 \func{virtual void}{Thaw}{\void}