X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/937013e0fd914d4c42f9f5ec98da665986b93dfa..07fa8f78f82cd01ef4034a489419da9e86499b18:/docs/latex/wx/window.tex

diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex
index 0e3bbfb3e4..41cc692700 100644
--- a/docs/latex/wx/window.tex
+++ b/docs/latex/wx/window.tex
@@ -169,7 +169,7 @@ correctly sized. }
 
 \func{}{\destruct{wxWindow}}{\void}
 
-Destructor. Deletes all subwindows, then deletes itself. Instead of using
+Destructor. Deletes all sub-windows, then deletes itself. Instead of using
 the {\bf delete} operator explicitly, you should normally
 use \helpref{wxWindow::Destroy}{wxwindowdestroy} so that wxWidgets
 can delete a window only when it is safe to do so, in idle time.
@@ -295,13 +295,6 @@ A synonym for \helpref{Centre}{wxwindowcentre}.
 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}}
@@ -349,24 +342,7 @@ window is not a top level window, then behaviour is the same as
 
 \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}
@@ -404,6 +380,23 @@ implements the following methods:\par
 \end{twocollist}}
 }
 
+\membersection{wxWindow::ClientToWindowSize}\label{wxwindowclienttowindowsize}
+
+\func{virtual wxSize}{ClientToWindowSize}{\param{const wxSize\&}{ size}}
+
+Converts client area size \arg{size} to corresponding window size. In other
+words, the returned value is what would \helpref{GetSize}{wxwindowgetsize}
+return if this window had client area of given size.
+Components with $wxDefaultCoord$ value are left unchanged.
+
+Note that the conversion is not always exact, it assumes that non-client area
+doesn't change and so doesn't take into account things like menu bar
+(un)wrapping or (dis)appearance of the scrollbars.
+
+\wxheading{See also}
+
+\helpref{wxWindow::WindowToClientSize}{wxwindowwindowtoclientsize}
+
 
 \membersection{wxWindow::Close}\label{wxwindowclose}
 
@@ -648,7 +641,8 @@ Note that this is a static function, so it can be called without needing a wxWin
 
 \wxheading{See also}
 
-\helpref{wxWindow::SetFocus}{wxwindowsetfocus}
+\helpref{wxWindow::SetFocus}{wxwindowsetfocus},
+\helpref{wxWindow::HasFocus}{wxwindowhasfocus}
 
 
 
@@ -752,7 +746,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
-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
@@ -838,7 +833,7 @@ transparency level.}
 
 Merges the window's best size into the min size and returns the
 result.  This is the value used by sizers to determine the appropriate
-ammount of sapce to allocate for the widget.
+ammount of space to allocate for the widget.
 
 \wxheading{See also}
 
@@ -1165,12 +1160,33 @@ the button text. This function can be useful for meta-programs (such as testing
 tools or special-needs access programs) which need to identify windows
 by name.
 
+
+\membersection{wxWindow::GetMaxClientSize}\label{wxwindowgetmaxclientsize}
+
+\constfunc{wxSize}{GetMaxClientSize}{\void}
+
+Returns the maximum size of window's client area. 
+This is an indication to the sizer layout mechanism that this is the maximum
+possible size as well as the upper bound on window's size settable using
+\helpref{SetClientSize}{wxwindowsetclientsize}. 
+
+\wxheading{See also}
+
+\helpref{wxWindow::GetMaxSize}{wxwindowgetmaxsize}
+
+
 \membersection{wxWindow::GetMaxSize}\label{wxwindowgetmaxsize}
 
 \constfunc{wxSize}{GetMaxSize}{\void}
 
-Returns the maximum size of the window, an indication to the sizer layout mechanism
-that this is the maximum possible size. 
+Returns the maximum size of the window. This is an indication to the sizer
+layout mechanism that this is the maximum possible size as well as the upper
+bound on window's size settable using \helpref{SetSize}{wxwindowsetsize}. 
+
+\wxheading{See also}
+
+\helpref{wxWindow::GetMaxClientSize}{wxwindowgetmaxclientsize}
+
 
 \membersection{wxWindow::GetMinSize}\label{wxwindowgetminsize}
 
@@ -1181,6 +1197,26 @@ that this is the minimum required size. It normally just returns the value set
 by \helpref{SetMinSize}{wxwindowsetminsize}, but it can be overridden to do the
 calculation on demand.
 
+\wxheading{See also}
+
+\helpref{wxWindow::GetMinClientSize}{wxwindowgetminclientsize}
+
+
+\membersection{wxWindow::GetMinClientSize}\label{wxwindowgetminclientsize}
+
+\constfunc{virtual wxSize}{GetMinClientSize}{\void}
+
+Returns the minimum size of window's client area, an indication to the sizer
+layout mechanism that this is the minimum required size of its client area. It
+normally just returns the value set by
+\helpref{SetMinClientSize}{wxwindowsetminclientsize}, but it can be overridden
+to do the calculation on demand.
+
+\wxheading{See also}
+
+\helpref{wxWindow::GetMinSize}{wxwindowgetminsize}
+
+
 \membersection{wxWindow::GetName}\label{wxwindowgetname}
 
 \constfunc{virtual wxString }{GetName}{\void}
@@ -1539,6 +1575,24 @@ Returns the value previously passed to
 \helpref{wxWindow::SetWindowVariant}{wxwindowsetwindowvariant}.
 
 
+\membersection{wxWindow::HandleAsNavigationKey}\label{wxwindowhandleasnavigationkey}
+
+\func{bool}{HandleAsNavigationKey}{\param{const wxKeyEvent\&}{ event}}
+
+This function will generate the appropriate call to
+\helpref{Navigate}{wxwindownavigate} if the key event is one normally used for
+keyboard navigation and return \true in this case.
+
+\wxheading{Return value}
+
+Returns \true if the key pressed was for navigation and was handled, \false
+otherwise.
+
+\wxheading{See also}
+
+\helpref{Navigate}{wxwindownavigate}
+
+
 \membersection{wxWindow::HandleWindowEvent}\label{wxwindowhandlewindowevent}
 
 \func{bool}{HandleWindowEvent}{\param{wxEvent\& }{event}}
@@ -1579,6 +1633,18 @@ extra styles.
 Returns \texttt{true} if the window has the given \arg{flag} bit set.
 
 
+\membersection{wxWindow::HasFocus}\label{wxwindowhasfocus}
+
+\constfunc{virtual bool}{HasFocus}{\void}
+
+Returns \true if the window (or in case of composite controls, its main
+child window) has focus.
+
+\wxheading{See also}
+
+\helpref{FindFocus}{wxwindowfindfocus}
+
+
 \membersection{wxWindow::HasMultiplePages}\label{wxwindowhasmultiplepages}
 
 \constfunc{virtual bool}{HasMultiplePages}{\void}
@@ -1621,6 +1687,20 @@ wxWindow-derived class to ensure that background is painted correctly.
 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}
@@ -1823,7 +1903,7 @@ This is just a wrapper for \helpref{ScrollLines}{wxwindowscrolllines}$(-1)$.
 
 \func{void}{Lower}{\void}
 
-Lowers the window to the bottom of the window hierarchy (z-order).
+Lowers the window to the bottom of the window hierarchy (Z-order).
 
 \wxheading{See also}
 
@@ -1931,7 +2011,8 @@ changed.
 You may wish to call this from a text control custom keypress handler to do the default
 navigation behaviour for the tab key, since the standard default behaviour for
 a multiline text control with the wxTE\_PROCESS\_TAB style is to insert a tab
-and not navigate to the next control. See also \helpref{wxNavigationKeyEvent}{wxnavigationkeyevent}.
+and not navigate to the next control. See also \helpref{wxNavigationKeyEvent}{wxnavigationkeyevent} and
+\helpref{HandleAsNavigationKey}{wxwindowhandleasnavigationkey}.
 
 
 \membersection{wxWindow::NavigateIn}\label{wxwindownavigatein}
@@ -1943,20 +2024,30 @@ Performs a keyboard navigation action inside this window.
 See \helpref{Navigate}{wxwindownavigate} for more information.
 
 
-\membersection{wxWindow::NextControlId}\label{wxwindownextcontrolid}
+\membersection{wxWindow::NewControlId}\label{wxwindownewcontrolid}
+
+\func{static wxWindowID}{NewControlId}{\param{int}{ count = 1}}
+
+Create a new ID or range of IDs that are not currently in use.  The
+IDs will be reserved until assigned to a \helpref{wxWindowIDRef}{windowidsoverview}
+or unreserved with \helpref{UnreserveControlId}{wxwindowunreservecontrolid}.
+
+See \helpref{Window IDs overview}{windowidsoverview} for more information.
 
-\func{static int}{NextControlId}{\param{int }{winid}}
+\wxheading{Parameters}
+
+\docparam{count}{The number of sequential IDs to reserve.}
+
+\wxheading{Return value}
 
-If two controls are created consecutively using \texttt{wxID\_ANY} id, this
-function allows to retrieve the effective id of the latter control from the id
-of the former. This is useful for example to find the control following its 
-\helpref{wxStaticText}{wxstatictext} label if only the id of or pointer to the
-label is available to the caller but it is known that the two controls were
-created together.
+Returns the ID or the first ID of the range, or \texttt{wxID\_NONE} if the
+specified number of identifiers couldn't be allocated.
 
 \wxheading{See also}
 
-\helpref{PrevControlId}{wxwindowprevcontrolid}
+\helpref{UnreserveControlId}{wxwindowunreservecontrolid}
+\helpref{wxIdManager}{wxidmanager}
+\helpref{Window IDs overview}{windowidsoverview}
 
 
 %% VZ: wxWindow::OnXXX() functions should not be documented but I'm leaving
@@ -2517,15 +2608,6 @@ implements the following methods:\par
 \end{twocollist}}
 }
 
-
-\membersection{wxWindow::PrevControlId}\label{wxwindowprevcontrolid}
-
-\func{static int}{PrevControlId}{\param{int }{winid}}
-
-This is similar to \helpref{NextControlId}{wxwindownextcontrolid} but returns
-the id of the control created just before the one with the given \arg{winid}.
-
-
 \membersection{wxWindow::PushEventHandler}\label{wxwindowpusheventhandler}
 
 \func{void}{PushEventHandler}{\param{wxEvtHandler* }{handler}}
@@ -2562,7 +2644,7 @@ remove the event handler.
 
 \func{void}{Raise}{\void}
 
-Raises the window to the top of the window hierarchy (z-order).
+Raises the window to the top of the window hierarchy (Z-order).
 
 In current version of wxWidgets this works both for managed and child windows.
 
@@ -3091,8 +3173,9 @@ This sets the window to receive keyboard input.
 
 \wxheading{See also}
 
-\helpref{wxFocusEvent}{wxfocusevent}
-\helpref{wxPanel::SetFocus}{wxpanelsetfocus}
+\helpref{HasFocus}{wxwindowhasfocus},
+\helpref{wxFocusEvent}{wxfocusevent},
+\helpref{wxPanel::SetFocus}{wxpanelsetfocus},
 \helpref{wxPanel::SetFocusIgnoringChildren}{wxpanelsetfocusignoringchildren}
 
 
@@ -3257,6 +3340,23 @@ Sets the window's label.
 Sets the maximum size of the window, to indicate to the sizer layout mechanism
 that this is the maximum possible size.
 
+\wxheading{See also}
+
+\helpref{wxWindow::SetMaxClientSize}{wxwindowsetmaxclientsize}
+
+
+\membersection{wxWindow::SetMaxClientSize}\label{wxwindowsetmaxclientsize}
+
+\func{void}{SetMaxClientSize}{\param{const wxSize\& }{size}}
+
+Sets the maximum \emph{client} size of the window, to indicate to the sizer
+layout mechanism that this is the maximum possible size of its client area.
+
+\wxheading{See also}
+
+\helpref{wxWindow::SetMaxSize}{wxwindowsetmaxsize}
+
+
 \membersection{wxWindow::SetMinSize}\label{wxwindowsetminsize}
 
 \func{void}{SetMinSize}{\param{const wxSize\& }{size}}
@@ -3266,6 +3366,25 @@ that this is the minimum required size. You may need to call this
 if you change the window size after construction and before adding
 to its parent sizer.
 
+\wxheading{See also}
+
+\helpref{wxWindow::SetMinClientSize}{wxwindowsetminclientsize}
+
+
+\membersection{wxWindow::SetMinClientSize}\label{wxwindowsetminclientsize}
+
+\func{void}{SetMinClientSize}{\param{const wxSize\& }{size}}
+
+Sets the minimum \emph{client} size of the window, to indicate to the sizer
+layout mechanism that this is the minimum required size of window's client
+area. You may need to call this if you change the window size after
+construction and before adding to its parent sizer.
+
+\wxheading{See also}
+
+\helpref{wxWindow::SetMinSize}{wxwindowsetminsize}
+
+
 \membersection{wxWindow::SetName}\label{wxwindowsetname}
 
 \func{virtual void}{SetName}{\param{const wxString\& }{name}}
@@ -3524,7 +3643,7 @@ a wxWidgets-supplied default height.\\
 a wxWidgets-supplied default size.\\
 {\bf wxSIZE\_USE\_EXISTING}: existing dimensions should be used
 if $wxDefaultCoord$ values are supplied.\\
-{\bf wxSIZE\_ALLOW\_MINUS\_ONE}: allow negative dimensions (ie. value of $wxDefaultCoord$) to be interpreted
+{\bf wxSIZE\_ALLOW\_MINUS\_ONE}: allow negative dimensions (i.e. value of $wxDefaultCoord$) to be interpreted
 as real dimensions, not default values.
 {\bf wxSIZE\_FORCE}: normally, if the position and the size of the window are
 already the same as the parameters of this function, nothing is done. but with
@@ -3541,6 +3660,10 @@ The first form sets the position and optionally size, of the window.
 Parameters may be $wxDefaultCoord$ to indicate either that a default should be supplied
 by wxWidgets, or that the current value of the dimension should be used.
 
+Notice that for \helpref{top level window}{wxtoplevelwindow} the size will not
+be changed if it is outside of the valid range as set by 
+\helpref{SetSizeHints}{wxtoplevelwindowsetsizehints}.
+
 \wxheading{See also}
 
 \helpref{wxWindow::Move}{wxwindowmove}
@@ -3603,8 +3726,11 @@ only the sizer will have effect.
 
 \func{void}{SetSizerAndFit}{\param{wxSizer* }{sizer}, \param{bool }{deleteOld=true}}
 
-The same as \helpref{SetSizer}{wxwindowsetsizer}, except it also sets the size hints
-for the window based on the sizer's minimum size.
+This method calls \helpref{SetSizer}{wxwindowsetsizer} and then 
+\helpref{wxSizer::SetSizeHints}{wxsizersetsizehints} which sets the initial
+window size to the size needed to accommodate all sizer elements and sets the
+size hints which, if this window is a top level one, prevent the user from
+resizing it to be less than this minimial size.
 
 
 \membersection{wxWindow::SetThemeEnabled}\label{wxwindowsetthemeenabled}
@@ -3903,6 +4029,25 @@ This function is currently only implemented under MSW.
 
 \helpref{wxWindow::RegisterHotKey}{wxwindowregisterhotkey}
 
+\membersection{wxWindow::UnreserveControlId}\label{wxwindowunreservecontrolid}
+
+\func{static void}{UnreserveControlId}{\param{wxWindowID}{ id}, \param{int}{ count = 1}}
+
+Unreserve an ID or range of IDs that was reserved by \helpref{NewControlId}{wxwindownewcontrolid}.
+
+See \helpref{Window IDs overview}{windowidsoverview} for more information.
+
+\wxheading{Parameters}
+
+\docparam{id}{The starting ID of the range of IDs to unreserve.}
+
+\docparam{count}{The number of sequential IDs to unreserve.}
+
+\wxheading{See also}
+
+\helpref{NewControlId}{wxwindownewcontrolid}
+\helpref{wxIdManager}{wxidmanager}
+\helpref{Window IDs overview}{windowidsoverview}
 
 \membersection{wxWindow::Update}\label{wxwindowupdate}
 
@@ -4001,3 +4146,19 @@ Interface Guidelines forbid moving the mouse cursor programmatically.
 
 \docparam{y}{The new y position for the cursor.}
 
+\membersection{wxWindow::WindowToClientSize}\label{wxwindowwindowtoclientsize}
+
+\func{virtual wxSize}{WindowToClientSize}{\param{const wxSize\&}{ size}}
+
+Converts window size \arg{size} to corresponding client area size. In other
+words, the returned value is what would
+\helpref{GetClientSize}{wxwindowgetclientsize} return if this window had
+given window size. Components with $wxDefaultCoord$ value are left unchanged. 
+
+Note that the conversion is not always exact, it assumes that non-client area
+doesn't change and so doesn't take into account things like menu bar
+(un)wrapping or (dis)appearance of the scrollbars.
+
+\wxheading{See also}
+
+\helpref{wxWindow::ClientToWindowSize}{wxwindowclienttowindowsize}
