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}