X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/aeab10d07c1f4ef78c0c9152de115fa216922e6c..820b49cdbf6fa6e6aac6bbb66e84ea9f5f5f745d:/docs/latex/wx/window.tex diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex index d2abf20559..af3fa74832 100644 --- a/docs/latex/wx/window.tex +++ b/docs/latex/wx/window.tex @@ -1,8 +1,15 @@ \section{\class{wxWindow}}\label{wxwindow} -wxWindow is the base class for all windows. Any -children of the window will be deleted automatically by the destructor -before the window itself is deleted. +wxWindow is the base class for all windows. Any children of the window will be deleted +automatically by the destructor before the window itself is deleted. + +Please note that we documented a number of handler functions (OnChar(), OnMouse() etc.) in this +help text. These must not be called by a user program and are documented only for illustration. +On several platforms, only a few of these handlers are actually written (they are not always +needed) and if you are uncertain on how to add a certain behaviour to a window class, intercept +the respective event as usual and call \helpref{wxEvent::Skip}{wxeventskip} so that the native +platform can implement its native behaviour or just ignore the event if nothing needs to be +done. \wxheading{Derived from} @@ -16,25 +23,33 @@ before the window itself is deleted. \wxheading{Window styles} The following styles can apply to all windows, although they will not always make sense for a particular -window class. +window class or on all platforms. \twocolwidtha{5cm}% \begin{twocollist}\itemsep=0pt \twocolitem{\windowstyle{wxSIMPLE\_BORDER}}{Displays a thin border around the window. wxBORDER is the old name -for this style.} +for this style. } \twocolitem{\windowstyle{wxDOUBLE\_BORDER}}{Displays a double border. Windows only.} \twocolitem{\windowstyle{wxSUNKEN\_BORDER}}{Displays a sunken border.} -\twocolitem{\windowstyle{wxRAISED\_BORDER}}{Displays a raised border.} -\twocolitem{\windowstyle{wxSTATIC\_BORDER}}{Displays a border suitable for a static control.} +\twocolitem{\windowstyle{wxRAISED\_BORDER}}{Displays a raised border. GTK only. } +\twocolitem{\windowstyle{wxSTATIC\_BORDER}}{Displays a border suitable for a static control. Windows only. } \twocolitem{\windowstyle{wxTRANSPARENT\_WINDOW}}{The window is transparent, that is, it will not receive paint events. Windows only.} \twocolitem{\windowstyle{wxNO\_3D}}{Prevents the children of this window taking on 3D styles, even though the application-wide policy is for 3D controls. Windows only.} \twocolitem{\windowstyle{wxTAB\_TRAVERSAL}}{Use this to enable tab traversal for non-dialog windows.} -\twocolitem{\windowstyle{wxVSCROLL}}{Use this style to enable a vertical scrollbar.} -\twocolitem{\windowstyle{wxHSCROLL}}{Use this style to enable a horizontal scrollbar.} +\twocolitem{\windowstyle{wxWANTS\_CHARS}}{Use this to indicate that the window +wants to get all char events - even for keys like TAB or ENTER which are +usually used for dialog navigation and which wouldn't be generated without +this style} +\twocolitem{\windowstyle{wxNO\_FULL\_REPAINT\_ON\_RESIZE}}{Disables repainting +the window completely when its size is changed - you will have to repaint the +new window area manually if you use this style. Currently only has an effect for +Windows.} +\twocolitem{\windowstyle{wxVSCROLL}}{Use this style to enable a vertical scrollbar. (Still used?) } +\twocolitem{\windowstyle{wxHSCROLL}}{Use this style to enable a horizontal scrollbar. (Still used?) } \twocolitem{\windowstyle{wxCLIP\_CHILDREN}}{Use this style to eliminate flicker caused by the background being -repainted, then children being painted over them. Windows-only.} +repainted, then children being painted over them. Windows only.} \end{twocollist} See also \helpref{window styles overview}{windowstyles}. @@ -45,7 +60,7 @@ See also \helpref{window styles overview}{windowstyles}. \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxWindow::wxWindow} +\membersection{wxWindow::wxWindow}\label{wxwindowctor} \func{}{wxWindow}{\void} @@ -70,7 +85,9 @@ should generate a default position for the window. If using the wxWindow class d an actual position.} \docparam{size}{Window size. wxDefaultSize is (-1, -1) which indicates that wxWindows -should generate a default size for the window.} +should generate a default size for the window. If no suitable size can be found, the +window will be sized to 20x20 pixels so that the window is visible but obviously not +correctly sized. } \docparam{style}{Window style. For generic window styles, please see \helpref{wxWindow}{wxwindow}.} @@ -88,7 +105,6 @@ can delete a window only when it is safe to do so, in idle time. \wxheading{See also} \helpref{Window deletion overview}{windowdeletionoverview},\rtfsp -\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp \helpref{wxWindow::Destroy}{wxwindowdestroy},\rtfsp \helpref{wxCloseEvent}{wxcloseevent} @@ -110,6 +126,12 @@ functions so should not be required by the application programmer. Directs all mouse input to this window. Call \helpref{wxWindow::ReleaseMouse}{wxwindowreleasemouse} to release the capture. +Note that wxWindows maintains the stack of windows having captured the mouse +and when the mouse is released the capture returns to the window which had had +captured it previously and it is only really released if there were no previous +window. In particular, this means that you must release the mouse as many times +as you capture it. + \wxheading{See also} \helpref{wxWindow::ReleaseMouse}{wxwindowreleasemouse} @@ -120,27 +142,82 @@ release the capture. A synonym for \helpref{Centre}{wxwindowcentre}. +\membersection{wxWindow::CenterOnParent}\label{wxwindowcenteronparent} + +\func{void}{CenterOnParent}{\param{int}{ direction}} + +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{virtual void}{Centre}{\param{int}{ direction = wxHORIZONTAL}} +\func{void}{Centre}{\param{int}{ direction = wxBOTH}} Centres the window. \wxheading{Parameters} \docparam{direction}{Specifies the direction for the centering. May be {\tt wxHORIZONTAL}, {\tt wxVERTICAL}\rtfsp -or {\tt wxBOTH}.} +or {\tt wxBOTH}. It may also include {\tt wxCENTRE\_ON\_SCREEN} flag +if you want to center the window on the entire screen and not on its +parent window.} + +The flag {\tt wxCENTRE\_FRAME} is obsolete and should not be used any longer +(it has no effect). \wxheading{Remarks} -The actual behaviour depends on the derived window. For a frame or dialog box, -centring is relative to the whole display. For a panel item, centring is -relative to the panel. +If the window is a top level one (i.e. doesn't have a parent), it will be +centered relative to the screen anyhow. \wxheading{See also} \helpref{wxWindow::Center}{wxwindowcenter} +\membersection{wxWindow::CentreOnParent}\label{wxwindowcentreonparent} + +\func{void}{CentreOnParent}{\param{int}{ direction = wxBOTH}} + +Centres the window on its parent. This is a more readable synonym for +\helpref{Centre}{wxwindowcentre}. + +\wxheading{Parameters} + +\docparam{direction}{Specifies the direction for the centering. May be {\tt wxHORIZONTAL}, {\tt wxVERTICAL}\rtfsp +or {\tt wxBOTH}.} + +\wxheading{Remarks} + +This methods provides for a way to center top level windows over their +parents instead of the entire screen. If there is no parent or if the +window is not a top level window, then behaviour is the same as +\helpref{wxWindow::Centre}{wxwindowcentre}. + +\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} + \membersection{wxWindow::Clear}\label{wxwindowclear} \func{void}{Clear}{\void} @@ -152,6 +229,9 @@ cause an erase background event to be generated. \constfunc{virtual void}{ClientToScreen}{\param{int* }{x}, \param{int* }{y}} +\perlnote{In wxPerl this method returns a 2-element list intead of +modifying its parameters.} + \constfunc{virtual wxPoint}{ClientToScreen}{\param{const wxPoint\&}{ pt}} Converts to screen coordinates from coordinates relative to this window. @@ -167,23 +247,22 @@ a screen coordinate will be passed out.} \pythonnote{In place of a single overloaded method name, wxPython implements the following methods:\par \indented{2cm}{\begin{twocollist} -\twocolitem{\bf{ClientToScreen(point)}}{Accepts and returns a wxPoint} -\twocolitem{\bf{ClientToScreenXY(x, y)}}{Returns a 2-tuple, (x, y)} +\twocolitem{{\bf ClientToScreen(point)}}{Accepts and returns a wxPoint} +\twocolitem{{\bf ClientToScreenXY(x, y)}}{Returns a 2-tuple, (x, y)} \end{twocollist}} } - \membersection{wxWindow::Close}\label{wxwindowclose} -\func{virtual bool}{Close}{\param{const bool}{ force = FALSE}} +\func{virtual bool}{Close}{\param{bool}{ force = {\tt FALSE}}} The purpose of this call is to provide a safer way of destroying a window than using the {\it delete} operator. \wxheading{Parameters} -\docparam{force}{FALSE if the window's close handler should be able to veto the destruction -of this window, TRUE if it cannot.} +\docparam{force}{{\tt FALSE} if the window's close handler should be able to veto the destruction +of this window, {\tt TRUE} if it cannot.} \wxheading{Remarks} @@ -207,7 +286,6 @@ To guarantee that the window will be destroyed, call \helpref{wxWindow::Destroy} \wxheading{See also} \helpref{Window deletion overview}{windowdeletionoverview},\rtfsp -\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp \helpref{wxWindow::Destroy}{wxwindowdestroy},\rtfsp \helpref{wxCloseEvent}{wxcloseevent} @@ -245,15 +323,15 @@ You can also use these functions programmatically. A convenience macro is define \pythonnote{In place of a single overloaded method name, wxPython implements the following methods:\par \indented{2cm}{\begin{twocollist} -\twocolitem{\bf{ConvertDialogPointToPixels(point)}}{Accepts and returns a wxPoint} -\twocolitem{\bf{ConvertDialogSizeToPixels(size)}}{Accepts and returns a wxSize} +\twocolitem{{\bf ConvertDialogPointToPixels(point)}}{Accepts and returns a wxPoint} +\twocolitem{{\bf ConvertDialogSizeToPixels(size)}}{Accepts and returns a wxSize} \end{twocollist}} Additionally, the following helper functions are defined:\par \indented{2cm}{\begin{twocollist} -\twocolitem{\bf{wxDLG_PNT(win, point)}}{Converts a wxPoint from dialog +\twocolitem{{\bf wxDLG\_PNT(win, point)}}{Converts a wxPoint from dialog units to pixels} -\twocolitem{\bf{wxDLG_SZE(win, size)}}{Converts a wxSize from dialog +\twocolitem{{\bf wxDLG\_SZE(win, size)}}{Converts a wxSize from dialog units to pixels} \end{twocollist}} } @@ -286,8 +364,8 @@ Dialogs created using Dialog Editor optionally use dialog units. \pythonnote{In place of a single overloaded method name, wxPython implements the following methods:\par \indented{2cm}{\begin{twocollist} -\twocolitem{\bf{ConvertDialogPointToPixels(point)}}{Accepts and returns a wxPoint} -\twocolitem{\bf{ConvertDialogSizeToPixels(size)}}{Accepts and returns a wxSize} +\twocolitem{{\bf ConvertDialogPointToPixels(point)}}{Accepts and returns a wxPoint} +\twocolitem{{\bf ConvertDialogSizeToPixels(size)}}{Accepts and returns a wxSize} \end{twocollist}} } @@ -304,7 +382,7 @@ windows. \wxheading{Return value} -TRUE if the window has either been successfully deleted, or it has been added +{\tt TRUE} if the window has either been successfully deleted, or it has been added to the list of windows pending real deletion. \membersection{wxWindow::DestroyChildren} @@ -313,38 +391,41 @@ to the list of windows pending real deletion. Destroys all children of a window. Called automatically by the destructor. +\membersection{wxWindow::Disable}\label{wxwindowdisable} + +\func{void}{Disable}{\void} + +Disables the window, same as \helpref{Enable({\tt FALSE})}{wxwindowenable}. + \membersection{wxWindow::DragAcceptFiles}\label{wxwindowdragacceptfiles} -\func{virtual void}{DragAcceptFiles}{\param{const bool}{ accept}} +\func{virtual void}{DragAcceptFiles}{\param{bool}{ accept}} Enables or disables elibility for drop file events (OnDropFiles). \wxheading{Parameters} -\docparam{accept}{If TRUE, the window is eligible for drop file events. If FALSE, the window +\docparam{accept}{If {\tt TRUE}, the window is eligible for drop file events. If {\tt FALSE}, the window will not accept drop file events.} \wxheading{Remarks} Windows only. -\wxheading{See also} - -\helpref{wxWindow::OnDropFiles}{wxwindowondropfiles} - \membersection{wxWindow::Enable}\label{wxwindowenable} -\func{virtual void}{Enable}{\param{const bool}{ enable}} +\func{virtual void}{Enable}{\param{bool}{ enable = {\tt TRUE}}} Enable or disable the window for user input. \wxheading{Parameters} -\docparam{enable}{If TRUE, enables the window for input. If FALSE, disables the window.} +\docparam{enable}{If {\tt TRUE}, enables the window for input. If {\tt FALSE}, disables the window.} \wxheading{See also} -\helpref{wxWindow::IsEnabled}{wxwindowisenabled} +\helpref{wxWindow::IsEnabled}{wxwindowisenabled},\rtfsp +\helpref{wxWindow::Disable}{wxwindowdisable} \membersection{wxWindow::FindFocus}\label{wxwindowfindfocus} @@ -373,8 +454,8 @@ Find a child of this window, by name. \pythonnote{In place of a single overloaded method name, wxPython implements the following methods:\par \indented{2cm}{\begin{twocollist} -\twocolitem{\bf{FindWindowById(id)}}{Accepts an integer} -\twocolitem{\bf{FindWindowByName(name)}}{Accepts a string} +\twocolitem{{\bf FindWindowById(id)}}{Accepts an integer} +\twocolitem{{\bf FindWindowByName(name)}}{Accepts a string} \end{twocollist}} } @@ -382,7 +463,22 @@ implements the following methods:\par \func{virtual void}{Fit}{\void} -Sizes the window so that it fits around its subwindows. +Sizes the window so that it fits around its subwindows. This function won't do +anything if there are no subwindows. + +\membersection{wxWindow::Freeze}\label{wxwindowfreeze} + +\func{virtual void}{Freeze}{\void} + +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. + +This method is useful for visual appearance optimization (for example, it +is a good idea to use it before inserting large amount of text into a +wxTextCtrl under wxGTK) but is not implemented on all platforms nor for all +controls so it is mostly just a hint to wxWindows and not a mandatory +directive. \membersection{wxWindow::GetBackgroundColour}\label{wxwindowgetbackgroundcolour} @@ -394,8 +490,24 @@ Returns the background colour of the window. \helpref{wxWindow::SetBackgroundColour}{wxwindowsetbackgroundcolour},\rtfsp \helpref{wxWindow::SetForegroundColour}{wxwindowsetforegroundcolour},\rtfsp -\helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp -\helpref{wxWindow::OnEraseBackground}{wxwindowonerasebackground} +\helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour} + +\membersection{wxWindow::GetBestSize}\label{wxwindowgetbestsize} + +\constfunc{virtual wxSize}{GetBestSize}{\void} + +This functions returns the best acceptable minimal size for the window. For +example, for a static control, it will be the minimal size such that the +control label is not truncated. For windows containing subwindows (typically +\helpref{wxPanel}{wxpanel}), the size returned by this function will be the +same as the size the window would have had after calling +\helpref{Fit}{wxwindowfit}. + +\membersection{wxWindow::GetCaret}\label{wxwindowgetcaret} + +\constfunc{wxCaret *}{GetCaret}{\void} + +Returns the \helpref{caret}{wxcaret} associated with the window. \membersection{wxWindow::GetCharHeight} @@ -419,10 +531,14 @@ Returns a reference to the list of the window's children. \constfunc{virtual void}{GetClientSize}{\param{int* }{width}, \param{int* }{height}} +\perlnote{In wxPerl this method takes no parameter and returns +a 2-element list {\tt ( width, height )}.} + \constfunc{virtual wxSize}{GetClientSize}{\void} -This gets the size of the window `client area' in pixels. The client area is the -area which may be drawn on by the programmer, excluding title bar, border etc. +This gets the size of the window `client area' in pixels. +The client area is the area which may be drawn on by the programmer, +excluding title bar, border, scrollbars, etc. \wxheading{Parameters} @@ -433,22 +549,27 @@ area which may be drawn on by the programmer, excluding title bar, border etc. \pythonnote{In place of a single overloaded method name, wxPython implements the following methods:\par \indented{2cm}{\begin{twocollist} -\twocolitem{\bf{wxGetClientSizeTuple()}}{Returns a 2-tuple of (width, height)} -\twocolitem{\bf{wxGetClientSize()}}{Returns a wxSize object} +\twocolitem{{\bf GetClientSizeTuple()}}{Returns a 2-tuple of (width, height)} +\twocolitem{{\bf GetClientSize()}}{Returns a wxSize object} \end{twocollist}} } +\wxheading{See also} + +\helpref{GetSize}{wxwindowgetsize} + \membersection{wxWindow::GetConstraints}\label{wxwindowgetconstraints} \constfunc{wxLayoutConstraints*}{GetConstraints}{\void} Returns a pointer to the window's layout constraints, or NULL if there are none. -\membersection{wxWindow::GetDefaultItem}\label{wxwindowgetdefaultitem} +\membersection{wxWindow::GetContainingSizer}\label{wxwindowgetcontainingsizer} -\constfunc{wxButton*}{GetDefaultItem}{\void} +\constfunc{const wxSizer *}{GetContainingSizer}{\void} -Returns a pointer to the button which is the default for this window, or NULL. +Return the sizer that this window is a member of, if any, otherwise +{\tt NULL}. \membersection{wxWindow::GetDropTarget}\label{wxwindowgetdroptarget} @@ -476,6 +597,12 @@ own event handler. \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent},\rtfsp \helpref{wxEvtHandler}{wxevthandler}\rtfsp +\membersection{wxWindow::GetExtraStyle}\label{wxwindowgetextrastyle} + +\constfunc{long}{GetExtraStyle}{\void} + +Returns the extra style bits for the window. + \membersection{wxWindow::GetFont}\label{wxwindowgetfont} \constfunc{wxFont\&}{GetFont}{\void} @@ -510,53 +637,47 @@ be used at all. Returns the grandparent of a window, or NULL if there isn't one. -\membersection{wxWindow::GetHandle} +\membersection{wxWindow::GetHandle}\label{wxwindowgethandle} \constfunc{void*}{GetHandle}{\void} Returns the platform-specific handle of the physical window. Cast it to an appropriate -handle, such as {\bf HWND} for Windows or {\bf Widget} for Motif. +handle, such as {\bf HWND} for Windows, {\bf Widget} for Motif or {\bf GtkWidget} for GTK. -\membersection{wxWindow::GetId}\label{wxwindowgetid} +\pythonnote{This method will return an integer in wxPython.} -\constfunc{int}{GetId}{\void} +\membersection{wxWindow::GetHelpText}\label{wxwindowgethelptext} -Returns the identifier of the window. +\constfunc{virtual wxString}{GetHelpText}{\void} -\wxheading{Remarks} +Gets the help text to be used as context-sensitive help for this window. -Each window has an integer identifier. If the application has not provided one, -an identifier will be generated. +Note that the text is actually stored by the current \helpref{wxHelpProvider}{wxhelpprovider} implementation, +and not in the window object itself. \wxheading{See also} -\helpref{wxWindow::SetId}{wxwindowsetid}\rtfsp -\helpref{Window identifiers}{windowids} +\helpref{SetHelpText}{wxwindowsethelptext}, \helpref{wxHelpProvider}{wxhelpprovider} -\membersection{wxWindow::GetPosition} +\membersection{wxWindow::GetId}\label{wxwindowgetid} -\constfunc{virtual void}{GetPosition}{\param{int* }{x}, \param{int* }{y}} +\constfunc{int}{GetId}{\void} -This gets the position of the window in pixels, relative to the parent window or -if no parent, relative to the whole display. +Returns the identifier of the window. -\wxheading{Parameters} +\wxheading{Remarks} -\docparam{x}{Receives the x position of the window.} +Each window has an integer identifier. If the application has not provided one +(or the default Id -1) an unique identifier with a negative value will be generated. -\docparam{y}{Receives the y position of the window.} +\wxheading{See also} -\pythonnote{In place of a single overloaded method name, wxPython -implements the following methods:\par -\indented{2cm}{\begin{twocollist} -\twocolitem{\bf{GetPosition()}}{Returns a wxPoint} -\twocolitem{\bf{GetPositionTuple()}}{Returns a tuple (x, y)} -\end{twocollist}} -} +\helpref{wxWindow::SetId}{wxwindowsetid},\rtfsp +\helpref{Window identifiers}{windowids} \membersection{wxWindow::GetLabel} -\constfunc{virtual wxString\& }{GetLabel}{\void} +\constfunc{virtual wxString }{GetLabel}{\void} Generic way of getting a label from any window, for identification purposes. @@ -571,7 +692,7 @@ by name. \membersection{wxWindow::GetName}\label{wxwindowgetname} -\constfunc{virtual wxString\& }{GetName}{\void} +\constfunc{virtual wxString }{GetName}{\void} Returns the window's name. @@ -590,27 +711,43 @@ name in the window constructor or via \helpref{wxWindow::SetName}{wxwindowsetnam Returns the parent of the window, or NULL if there is no parent. -\membersection{wxWindow::GetRect}\label{wxwindowgetrect} +\membersection{wxWindow::GetPosition}\label{wxwindowgetposition} -\constfunc{virtual wxRect}{GetRect}{\void} +\constfunc{virtual void}{GetPosition}{\param{int* }{x}, \param{int* }{y}} -Returns the size and position of the window as a \helpref{wxRect}{wxrect} object. +\constfunc{wxPoint}{GetPosition}{\void} + +This gets the position of the window in pixels, relative to the parent window or +if no parent, relative to the whole display. -\membersection{wxWindow::GetReturnCode}\label{wxwindowgetreturncode} +\wxheading{Parameters} -\func{int}{GetReturnCode}{\void} +\docparam{x}{Receives the x position of the window.} -Gets the return code for this window. +\docparam{y}{Receives the y position of the window.} -\wxheading{Remarks} +\pythonnote{In place of a single overloaded method name, wxPython +implements the following methods:\par +\indented{2cm}{\begin{twocollist} +\twocolitem{{\bf GetPosition()}}{Returns a wxPoint} +\twocolitem{{\bf GetPositionTuple()}}{Returns a tuple (x, y)} +\end{twocollist}} +} -A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns -a code to the application. +\perlnote{In wxPerl there are two methods instead of a single overloaded +method:\par +\indented{2cm}{\begin{twocollist} +\twocolitem{{\bf GetPosition()}}{Returns a Wx::Point} +\twocolitem{{\bf GetPositionXY()}}{Returns a 2-element list + {\tt ( x, y )}} +\end{twocollist} +}} -\wxheading{See also} +\membersection{wxWindow::GetRect}\label{wxwindowgetrect} + +\constfunc{virtual wxRect}{GetRect}{\void} -\helpref{wxWindow::SetReturnCode}{wxwindowsetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp -\helpref{wxDialog::EndModal}{wxdialogendmodal} +Returns the size and position of the window as a \helpref{wxRect}{wxrect} object. \membersection{wxWindow::GetScrollThumb}\label{wxwindowgetscrollthumb} @@ -648,7 +785,8 @@ Returns the built-in scrollbar range. \constfunc{virtual wxSize}{GetSize}{\void} -This gets the size of the entire window in pixels. +This gets the size of the entire window in pixels, +including title bar, border, scrollbars, etc. \wxheading{Parameters} @@ -659,16 +797,36 @@ This gets the size of the entire window in pixels. \pythonnote{In place of a single overloaded method name, wxPython implements the following methods:\par \indented{2cm}{\begin{twocollist} -\twocolitem{\bf{GetSize()}}{Returns a wxSize} -\twocolitem{\bf{GetSizeTuple()}}{Returns a 2-tuple (width, height)} +\twocolitem{{\bf GetSize()}}{Returns a wxSize} +\twocolitem{{\bf GetSizeTuple()}}{Returns a 2-tuple (width, height)} \end{twocollist}} } -\membersection{wxWindow::GetTextExtent} +\perlnote{In wxPerl there are two methods instead of a single overloaded +method:\par +\indented{2cm}{\begin{twocollist} +\twocolitem{{\bf GetSize()}}{Returns a Wx::Size} +\twocolitem{{\bf GetSizeWH()}}{Returns a 2-element list + {\tt ( width, height )}} +\end{twocollist} +}} + +\wxheading{See also} + +\helpref{GetClientSize}{wxwindowgetclientsize} + +\membersection{wxWindow::GetSizer}\label{wxwindowgetsizer} + +\constfunc{wxSizer *}{GetSizer}{\void} + +Return the sizer associated with the window by a previous call to +\helpref{SetSizer()}{wxwindowsetsizer} or {\tt NULL}. + +\membersection{wxWindow::GetTextExtent}\label{wxwindowgettextextent} \constfunc{virtual void}{GetTextExtent}{\param{const wxString\& }{string}, \param{int* }{x}, \param{int* }{y}, \param{int* }{descent = NULL}, \param{int* }{externalLeading = NULL}, - \param{const wxFont* }{font = NULL}, \param{const bool}{ use16 = FALSE}} + \param{const wxFont* }{font = NULL}, \param{bool}{ use16 = {\tt FALSE}}} Gets the dimensions of the string as it would be drawn on the window with the currently selected font. @@ -687,18 +845,21 @@ window with the currently selected font. \docparam{font}{Font to use instead of the current window font (optional).} -\docparam{use16}{If TRUE, {\it string} contains 16-bit characters. The default is FALSE.} +\docparam{use16}{If {\tt TRUE}, {\it string} contains 16-bit characters. The default is {\tt FALSE}.} \pythonnote{In place of a single overloaded method name, wxPython implements the following methods:\par \indented{2cm}{\begin{twocollist} -\twocolitem{\bf{GetTextExtent(string)}}{Returns a 2-tuple, (width, height)} -\twocolitem{\bf{GetFullTextExtent(string, font=NULL)}}{Returns a +\twocolitem{{\bf GetTextExtent(string)}}{Returns a 2-tuple, (width, height)} +\twocolitem{{\bf GetFullTextExtent(string, font=NULL)}}{Returns a 4-tuple, (width, height, descent, externalLeading) } \end{twocollist}} } +\perlnote{In wxPerl this method takes only the {\tt string} and optionally + {\tt font} parameters, and returns a 4-element list + {\tt ( x, y, descent, externalLeading )}.} \membersection{wxWindow::GetTitle}\label{wxwindowgettitle} @@ -719,7 +880,8 @@ only be called within an \helpref{OnPaint}{wxwindowonpaint} event handler. \wxheading{See also} -\helpref{wxRegion}{wxregion}, \helpref{wxRegionIterator}{wxregioniterator}, \helpref{wxWindow::OnPaint}{wxwindowonpaint} +\helpref{wxRegion}{wxregion},\rtfsp +\helpref{wxRegionIterator}{wxregioniterator} \membersection{wxWindow::GetValidator}\label{wxwindowgetvalidator} @@ -727,38 +889,63 @@ only be called within an \helpref{OnPaint}{wxwindowonpaint} event handler. Returns a pointer to the current validator for the window, or NULL if there is none. -\membersection{wxWindow::GetWindowStyleFlag} +\membersection{wxWindow::GetWindowStyleFlag}\label{wxwindowgetwindowstyleflag} \constfunc{long}{GetWindowStyleFlag}{\void} -Gets the window style that was passed to the consructor or {\bf Create} member. +Gets the window style that was passed to the constructor or {\bf Create} +method. {\bf GetWindowStyle()} is another name for the same function. -\membersection{wxWindow::InitDialog}\label{wxwindowinitdialog} +\membersection{wxWindow::Hide}\label{wxwindowhide} -\func{void}{InitDialog}{\void} +\func{bool}{Hide}{\void} -Sends an \helpref{wxWindow::OnInitDialog}{wxwindowoninitdialog} event, which -in turn transfers data to the dialog via validators. +Equivalent to calling \helpref{Show}{wxwindowshow}({\tt FALSE}). -\wxheading{See also} +\membersection{wxWindow::InitDialog}\label{wxwindowinitdialog} + +\func{void}{InitDialog}{\void} -\helpref{wxWindow::OnInitDialog}{wxwindowoninitdialog} +Sends an {\tt wxEVT\_INIT\_DIALOG} event, whose handler usually transfers data +to the dialog via validators. \membersection{wxWindow::IsEnabled}\label{wxwindowisenabled} \constfunc{virtual bool}{IsEnabled}{\void} -Returns TRUE if the window is enabled for input, FALSE otherwise. +Returns {\tt TRUE} if the window is enabled for input, {\tt FALSE} otherwise. \wxheading{See also} \helpref{wxWindow::Enable}{wxwindowenable} +\membersection{wxWindow:IsExposed}\label{wxwindowisexposed} + +\constfunc{bool}{IsExposed}{\param{int }{x}, \param{int }{y}} + +\constfunc{bool}{IsExposed}{\param{wxPoint }{\&pt}} + +\constfunc{bool}{IsExposed}{\param{int }{x}, \param{int }{y}, \param{int }{w}, \param{int }{h}} + +\constfunc{bool}{IsExposed}{\param{wxRect }{\&rect}} + +Returns {\tt TRUE} if the given point or rectange area has been exposed since the +last repaint. Call this in an paint event handler to optimize redrawing by +only redrawing those areas, which have been exposed. + +\pythonnote{In place of a single overloaded method name, wxPython +implements the following methods:\par +\indented{2cm}{\begin{twocollist} +\twocolitem{{\bf IsExposed(x,y, w=0,h=0}}{} +\twocolitem{{\bf IsExposedPoint(pt)}}{} +\twocolitem{{\bf IsExposedRect(rect)}}{} +\end{twocollist}}} + \membersection{wxWindow::IsRetained}\label{wxwindowisretained} \constfunc{virtual bool}{IsRetained}{\void} -Returns TRUE if the window is retained, FALSE otherwise. +Returns {\tt TRUE} if the window is retained, {\tt FALSE} otherwise. \wxheading{Remarks} @@ -768,14 +955,25 @@ Retained windows are only available on X platforms. \constfunc{virtual bool}{IsShown}{\void} -Returns TRUE if the window is shown, FALSE if it has been hidden. +Returns {\tt TRUE} if the window is shown, {\tt FALSE} if it has been hidden. + +\membersection{wxWindow::IsTopLevel}\label{wxwindowistoplevel} + +\constfunc{bool}{IsTopLevel}{\void} + +Returns {\tt TRUE} if the given window is a top-level one. Currently all frames and +dialogs are considered to be top-level windows (even if they have a parent +window). \membersection{wxWindow::Layout}\label{wxwindowlayout} \func{void}{Layout}{\void} -Invokes the constraint-based layout algorithm for this window. It is called -automatically by the default {\bf wxWindow::OnSize} member. +Invokes the constraint-based layout algorithm or the sizer-based algorithm +for this window. + +See \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} on when +this function gets called automatically using auto layout. \membersection{wxWindow::LoadFromResource}\label{wxwindowloadfromresource} @@ -795,7 +993,7 @@ default resource table will be used.} \wxheading{Return value} -TRUE if the operation succeeded, otherwise FALSE. +{\tt TRUE} if the operation succeeded, otherwise {\tt FALSE}. \membersection{wxWindow::Lower}\label{wxwindowlower} @@ -806,15 +1004,16 @@ or frame). \membersection{wxWindow::MakeModal}\label{wxwindowmakemodal} -\func{virtual void}{MakeModal}{\param{const bool }{flag}} +\func{virtual void}{MakeModal}{\param{bool }{flag}} Disables all other windows in the application so that -the user can only interact with this window. +the user can only interact with this window. (This function +is not implemented anywhere). \wxheading{Parameters} -\docparam{flag}{If TRUE, this call disables all other windows in the application so that -the user can only interact with this window. If FALSE, the effect is reversed.} +\docparam{flag}{If {\tt TRUE}, this call disables all other windows in the application so that +the user can only interact with this window. If {\tt FALSE}, the effect is reversed.} \membersection{wxWindow::Move}\label{wxwindowmove} @@ -849,749 +1048,867 @@ as the call: \pythonnote{In place of a single overloaded method name, wxPython implements the following methods:\par \indented{2cm}{\begin{twocollist} -\twocolitem{\bf{Move(point)}}{Accepts a wxPoint} -\twocolitem{\bf{MoveXY(x, y)}}{Accepts a pair of integers} +\twocolitem{{\bf Move(point)}}{Accepts a wxPoint} +\twocolitem{{\bf MoveXY(x, y)}}{Accepts a pair of integers} \end{twocollist}} } -\membersection{wxWindow::OnActivate}\label{wxwindowonactivate} - -\func{void}{OnActivate}{\param{wxActivateEvent\&}{ event}} +%% VZ: wxWindow::OnXXX() functions should not be documented but I'm leaving +%% the old docs here in case we want to move any still needed bits to +%% the right location (i.e. probably the corresponding events docs) +%% +%% \membersection{wxWindow::OnActivate}\label{wxwindowonactivate} +%% +%% \func{void}{OnActivate}{\param{wxActivateEvent\&}{ event}} +%% +%% Called when a window is activated or deactivated. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{Object containing activation information.} +%% +%% \wxheading{Remarks} +%% +%% If the window is being activated, \helpref{wxActivateEvent::GetActive}{wxactivateeventgetactive} returns {\tt TRUE}, +%% otherwise it returns {\tt FALSE} (it is being deactivated). +%% +%% \wxheading{See also} +%% +%% \helpref{wxActivateEvent}{wxactivateevent},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnChar}\label{wxwindowonchar} +%% +%% \func{void}{OnChar}{\param{wxKeyEvent\&}{ event}} +%% +%% Called when the user has pressed a key that is not a modifier (SHIFT, CONTROL or ALT). +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{Object containing keypress information. See \helpref{wxKeyEvent}{wxkeyevent} for +%% details about this class.} +%% +%% \wxheading{Remarks} +%% +%% This member function is called in response to a keypress. To intercept this event, +%% use the EVT\_CHAR macro in an event table definition. Your {\bf OnChar} handler may call this +%% default function to achieve default keypress functionality. +%% +%% Note that the ASCII values do not have explicit key codes: they are passed as ASCII +%% values. +%% +%% Note that not all keypresses can be intercepted this way. If you wish to intercept modifier +%% keypresses, then you will need to use \helpref{wxWindow::OnKeyDown}{wxwindowonkeydown} or +%% \helpref{wxWindow::OnKeyUp}{wxwindowonkeyup}. +%% +%% Most, but not all, windows allow keypresses to be intercepted. +%% +%% {\bf Tip:} be sure to call {\tt event.Skip()} for events that you don't process in this function, +%% otherwise menu shortcuts may cease to work under Windows. +%% +%% \wxheading{See also} +%% +%% \helpref{wxWindow::OnKeyDown}{wxwindowonkeydown}, \helpref{wxWindow::OnKeyUp}{wxwindowonkeyup},\rtfsp +%% \helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnCharHook}{wxwindowoncharhook},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnCharHook}\label{wxwindowoncharhook} +%% +%% \func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}} +%% +%% This member is called to allow the window to intercept keyboard events +%% before they are processed by child windows. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{Object containing keypress information. See \helpref{wxKeyEvent}{wxkeyevent} for +%% details about this class.} +%% +%% \wxheading{Remarks} +%% +%% This member function is called in response to a keypress, if the window is active. To intercept this event, +%% use the EVT\_CHAR\_HOOK macro in an event table definition. If you do not process a particular +%% keypress, call \helpref{wxEvent::Skip}{wxeventskip} to allow default processing. +%% +%% An example of using this function is in the implementation of escape-character processing for wxDialog, +%% where pressing ESC dismisses the dialog by {\bf OnCharHook} 'forging' a cancel button press event. +%% +%% Note that the ASCII values do not have explicit key codes: they are passed as ASCII +%% values. +%% +%% This function is only relevant to top-level windows (frames and dialogs), and under +%% Windows only. Under GTK the normal EVT\_CHAR\_ event has the functionality, i.e. +%% you can intercepts it and if you don't call \helpref{wxEvent::Skip}{wxeventskip} +%% the window won't get the event. +%% +%% \wxheading{See also} +%% +%% \helpref{wxKeyEvent}{wxkeyevent},\rtfsp +%% \helpref{wxWindow::OnCharHook}{wxwindowoncharhook},\rtfsp +%% %% GD: OnXXX functions are not documented +%% %%\helpref{wxApp::OnCharHook}{wxapponcharhook},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnCommand}\label{wxwindowoncommand} +%% +%% \func{virtual void}{OnCommand}{\param{wxEvtHandler\& }{object}, \param{wxCommandEvent\& }{event}} +%% +%% This virtual member function is called if the control does not handle the command event. +%% +%% \wxheading{Parameters} +%% +%% \docparam{object}{Object receiving the command event.} +%% +%% \docparam{event}{Command event} +%% +%% \wxheading{Remarks} +%% +%% This virtual function is provided mainly for backward compatibility. You can also intercept commands +%% from child controls by using an event table, with identifiers or identifier ranges to identify +%% the control(s) in question. +%% +%% \wxheading{See also} +%% +%% \helpref{wxCommandEvent}{wxcommandevent},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnClose}\label{wxwindowonclose} +%% +%% \func{virtual bool}{OnClose}{\void} +%% +%% Called when the user has tried to close a a frame +%% or dialog box using the window manager (X) or system menu (Windows). +%% +%% {\bf Note:} This is an obsolete function. +%% It is superceded by the \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow} event +%% handler. +%% +%% \wxheading{Return value} +%% +%% If {\tt TRUE} is returned by OnClose, the window will be deleted by the system, otherwise the +%% attempt will be ignored. Do not delete the window from within this handler, although +%% you may delete other windows. +%% +%% \wxheading{See also} +%% +%% \helpref{Window deletion overview}{windowdeletionoverview},\rtfsp +%% \helpref{wxWindow::Close}{wxwindowclose},\rtfsp +%% \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp +%% \helpref{wxCloseEvent}{wxcloseevent} +%% +%% \membersection{wxWindow::OnCloseWindow}\label{wxwindowonclosewindow} +%% +%% \func{void}{OnCloseWindow}{\param{wxCloseEvent\& }{event}} +%% +%% This is an event handler function called when the user has tried to close a a frame +%% or dialog box using the window manager (X) or system menu (Windows). It is +%% called via the \helpref{wxWindow::Close}{wxwindowclose} function, so +%% that the application can also invoke the handler programmatically. +%% +%% Use the EVT\_CLOSE event table macro to handle close events. +%% +%% You should check whether the application is forcing the deletion of the window +%% using \helpref{wxCloseEvent::GetForce}{wxcloseeventgetforce}. If this is {\tt TRUE}, +%% destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}. +%% If not, it is up to you whether you respond by destroying the window. +%% +%% (Note: GetForce is now superceded by CanVeto. So to test whether forced destruction of +%% the window is required, test for the negative of CanVeto. If CanVeto returns {\tt FALSE}, +%% it is not possible to skip window deletion.) +%% +%% If you don't destroy the window, you should call \helpref{wxCloseEvent::Veto}{wxcloseeventveto} to +%% let the calling code know that you did not destroy the window. This allows the \helpref{wxWindow::Close}{wxwindowclose} function +%% to return {\tt TRUE} or {\tt FALSE} depending on whether the close instruction was honoured or not. +%% +%% \wxheading{Remarks} +%% +%% The \helpref{wxWindow::OnClose}{wxwindowonclose} virtual function remains +%% for backward compatibility with earlier versions of wxWindows. The +%% default {\bf OnCloseWindow} handler for wxFrame and wxDialog will call {\bf OnClose}, +%% destroying the window if it returns {\tt TRUE} or if the close is being forced. +%% +%% \wxheading{See also} +%% +%% \helpref{Window deletion overview}{windowdeletionoverview},\rtfsp +%% \helpref{wxWindow::Close}{wxwindowclose},\rtfsp +%% \helpref{wxWindow::OnClose}{wxwindowonclose},\rtfsp +%% \helpref{wxWindow::Destroy}{wxwindowdestroy},\rtfsp +%% \helpref{wxCloseEvent}{wxcloseevent},\rtfsp +%% \helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession} +%% %% GD: OnXXX functions are not documented +%% %%\helpref{wxApp::OnEndSession}{wxapponendsession} +%% +%% \membersection{wxWindow::OnDropFiles}\label{wxwindowondropfiles} +%% +%% \func{void}{OnDropFiles}{\param{wxDropFilesEvent\&}{ event}} +%% +%% Called when files have been dragged from the file manager to the window. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{Drop files event. For more information, see \helpref{wxDropFilesEvent}{wxdropfilesevent}.} +%% +%% \wxheading{Remarks} +%% +%% The window must have previously been enabled for dropping by calling +%% \rtfsp\helpref{wxWindow::DragAcceptFiles}{wxwindowdragacceptfiles}. +%% +%% This event is only generated under Windows. +%% +%% To intercept this event, use the EVT\_DROP\_FILES macro in an event table definition. +%% +%% \wxheading{See also} +%% +%% \helpref{wxDropFilesEvent}{wxdropfilesevent}, \helpref{wxWindow::DragAcceptFiles}{wxwindowdragacceptfiles},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnEraseBackground}\label{wxwindowonerasebackground} +%% +%% \func{void}{OnEraseBackground}{\param{wxEraseEvent\&}{ event}} +%% +%% Called when the background of the window needs to be erased. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{Erase background event. For more information, see \helpref{wxEraseEvent}{wxeraseevent}.} +%% +%% \wxheading{Remarks} +%% +%% Under non-Windows platforms, this event is simulated (simply generated just before the +%% paint event) and may cause flicker. It is therefore recommended that +%% you set the text background colour explicitly in order to prevent flicker. +%% The default background colour under GTK is grey. +%% +%% To intercept this event, use the EVT\_ERASE\_BACKGROUND macro in an event table definition. +%% +%% \wxheading{See also} +%% +%% \helpref{wxEraseEvent}{wxeraseevent}, \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnKeyDown}\label{wxwindowonkeydown} +%% +%% \func{void}{OnKeyDown}{\param{wxKeyEvent\&}{ event}} +%% +%% Called when the user has pressed a key, before it is translated into an ASCII value using other +%% modifier keys that might be pressed at the same time. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{Object containing keypress information. See \helpref{wxKeyEvent}{wxkeyevent} for +%% details about this class.} +%% +%% \wxheading{Remarks} +%% +%% This member function is called in response to a key down event. To intercept this event, +%% use the EVT\_KEY\_DOWN macro in an event table definition. Your {\bf OnKeyDown} handler may call this +%% default function to achieve default keypress functionality. +%% +%% Note that not all keypresses can be intercepted this way. If you wish to intercept special +%% keys, such as shift, control, and function keys, then you will need to use \helpref{wxWindow::OnKeyDown}{wxwindowonkeydown} or +%% \helpref{wxWindow::OnKeyUp}{wxwindowonkeyup}. +%% +%% Most, but not all, windows allow keypresses to be intercepted. +%% +%% {\bf Tip:} be sure to call {\tt event.Skip()} for events that you don't process in this function, +%% otherwise menu shortcuts may cease to work under Windows. +%% +%% \wxheading{See also} +%% +%% \helpref{wxWindow::OnChar}{wxwindowonchar}, \helpref{wxWindow::OnKeyUp}{wxwindowonkeyup},\rtfsp +%% \helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnCharHook}{wxwindowoncharhook},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnKeyUp}\label{wxwindowonkeyup} +%% +%% \func{void}{OnKeyUp}{\param{wxKeyEvent\&}{ event}} +%% +%% Called when the user has released a key. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{Object containing keypress information. See \helpref{wxKeyEvent}{wxkeyevent} for +%% details about this class.} +%% +%% \wxheading{Remarks} +%% +%% This member function is called in response to a key up event. To intercept this event, +%% use the EVT\_KEY\_UP macro in an event table definition. Your {\bf OnKeyUp} handler may call this +%% default function to achieve default keypress functionality. +%% +%% Note that not all keypresses can be intercepted this way. If you wish to intercept special +%% keys, such as shift, control, and function keys, then you will need to use \helpref{wxWindow::OnKeyDown}{wxwindowonkeydown} or +%% \helpref{wxWindow::OnKeyUp}{wxwindowonkeyup}. +%% +%% Most, but not all, windows allow key up events to be intercepted. +%% +%% \wxheading{See also} +%% +%% \helpref{wxWindow::OnChar}{wxwindowonchar}, \helpref{wxWindow::OnKeyDown}{wxwindowonkeydown},\rtfsp +%% \helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnCharHook}{wxwindowoncharhook},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnKillFocus}\label{wxwindowonkillfocus} +%% +%% \func{void}{OnKillFocus}{\param{wxFocusEvent\& }{event}} +%% +%% Called when a window's focus is being killed. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{The focus event. For more information, see \helpref{wxFocusEvent}{wxfocusevent}.} +%% +%% \wxheading{Remarks} +%% +%% To intercept this event, use the macro EVT\_KILL\_FOCUS in an event table definition. +%% +%% Most, but not all, windows respond to this event. +%% +%% \wxheading{See also} +%% +%% \helpref{wxFocusEvent}{wxfocusevent}, \helpref{wxWindow::OnSetFocus}{wxwindowonsetfocus},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnIdle}\label{wxwindowonidle} +%% +%% \func{void}{OnIdle}{\param{wxIdleEvent\& }{event}} +%% +%% Provide this member function for any processing which needs to be done +%% when the application is idle. +%% +%% \wxheading{See also} +%% +%% %% GD: OnXXX functions are not documented +%% %%\helpref{wxApp::OnIdle}{wxapponidle} +%% \helpref{wxIdleEvent}{wxidleevent} +%% +%% \membersection{wxWindow::OnInitDialog}\label{wxwindowoninitdialog} +%% +%% \func{void}{OnInitDialog}{\param{wxInitDialogEvent\&}{ event}} +%% +%% Default handler for the wxEVT\_INIT\_DIALOG event. Calls \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow}. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{Dialog initialisation event.} +%% +%% \wxheading{Remarks} +%% +%% Gives the window the default behaviour of transferring data to child controls via +%% the validator that each control has. +%% +%% \wxheading{See also} +%% +%% \helpref{wxValidator}{wxvalidator}, \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow} +%% +%% \membersection{wxWindow::OnMenuCommand}\label{wxwindowonmenucommand} +%% +%% \func{void}{OnMenuCommand}{\param{wxCommandEvent\& }{event}} +%% +%% Called when a menu command is received from a menu bar. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{The menu command event. For more information, see \helpref{wxCommandEvent}{wxcommandevent}.} +%% +%% \wxheading{Remarks} +%% +%% A function with this name doesn't actually exist; you can choose any member function to receive +%% menu command events, using the EVT\_COMMAND macro for individual commands or EVT\_COMMAND\_RANGE for +%% a range of commands. +%% +%% \wxheading{See also} +%% +%% \helpref{wxCommandEvent}{wxcommandevent},\rtfsp +%% \helpref{wxWindow::OnMenuHighlight}{wxwindowonmenuhighlight},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnMenuHighlight}\label{wxwindowonmenuhighlight} +%% +%% \func{void}{OnMenuHighlight}{\param{wxMenuEvent\& }{event}} +%% +%% Called when a menu select is received from a menu bar: that is, the +%% mouse cursor is over a menu item, but the left mouse button has not been +%% pressed. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{The menu highlight event. For more information, see \helpref{wxMenuEvent}{wxmenuevent}.} +%% +%% \wxheading{Remarks} +%% +%% You can choose any member function to receive +%% menu select events, using the EVT\_MENU\_HIGHLIGHT macro for individual menu items or EVT\_MENU\_HIGHLIGHT\_ALL macro +%% for all menu items. +%% +%% The default implementation for \helpref{wxFrame::OnMenuHighlight}{wxframeonmenuhighlight} displays help +%% text in the first field of the status bar. +%% +%% This function was known as {\bf OnMenuSelect} in earlier versions of wxWindows, but this was confusing +%% since a selection is normally a left-click action. +%% +%% \wxheading{See also} +%% +%% \helpref{wxMenuEvent}{wxmenuevent},\rtfsp +%% \helpref{wxWindow::OnMenuCommand}{wxwindowonmenucommand},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% +%% \membersection{wxWindow::OnMouseEvent}\label{wxwindowonmouseevent} +%% +%% \func{void}{OnMouseEvent}{\param{wxMouseEvent\&}{ event}} +%% +%% Called when the user has initiated an event with the +%% mouse. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{The mouse event. See \helpref{wxMouseEvent}{wxmouseevent} for +%% more details.} +%% +%% \wxheading{Remarks} +%% +%% Most, but not all, windows respond to this event. +%% +%% To intercept this event, use the EVT\_MOUSE\_EVENTS macro in an event table definition, or individual +%% mouse event macros such as EVT\_LEFT\_DOWN. +%% +%% \wxheading{See also} +%% +%% \helpref{wxMouseEvent}{wxmouseevent},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnMove}\label{wxwindowonmove} +%% +%% \func{void}{OnMove}{\param{wxMoveEvent\& }{event}} +%% +%% Called when a window is moved. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{The move event. For more information, see \helpref{wxMoveEvent}{wxmoveevent}.} +%% +%% \wxheading{Remarks} +%% +%% Use the EVT\_MOVE macro to intercept move events. +%% +%% \wxheading{Remarks} +%% +%% Not currently implemented. +%% +%% \wxheading{See also} +%% +%% \helpref{wxMoveEvent}{wxmoveevent},\rtfsp +%% \helpref{wxFrame::OnSize}{wxframeonsize},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnPaint}\label{wxwindowonpaint} +%% +%% \func{void}{OnPaint}{\param{wxPaintEvent\& }{event}} +%% +%% Sent to the event handler when the window must be refreshed. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{Paint event. For more information, see \helpref{wxPaintEvent}{wxpaintevent}.} +%% +%% \wxheading{Remarks} +%% +%% Use the EVT\_PAINT macro in an event table definition to intercept paint events. +%% +%% Note that In a paint event handler, the application must {\it always} create a \helpref{wxPaintDC}{wxpaintdc} object, +%% even if you do not use it. Otherwise, under MS Windows, refreshing for this and other windows will go wrong. +%% +%% For example: +%% +%% \small{% +%% \begin{verbatim} +%% void MyWindow::OnPaint(wxPaintEvent\& event) +%% { +%% wxPaintDC dc(this); +%% +%% DrawMyDocument(dc); +%% } +%% \end{verbatim} +%% }% +%% +%% You can optimize painting by retrieving the rectangles +%% that have been damaged and only repainting these. The rectangles are in +%% terms of the client area, and are unscrolled, so you will need to do +%% some calculations using the current view position to obtain logical, +%% scrolled units. +%% +%% Here is an example of using the \helpref{wxRegionIterator}{wxregioniterator} class: +%% +%% {\small% +%% \begin{verbatim} +%% // Called when window needs to be repainted. +%% void MyWindow::OnPaint(wxPaintEvent\& event) +%% { +%% wxPaintDC dc(this); +%% +%% // Find Out where the window is scrolled to +%% int vbX,vbY; // Top left corner of client +%% GetViewStart(&vbX,&vbY); +%% +%% int vX,vY,vW,vH; // Dimensions of client area in pixels +%% wxRegionIterator upd(GetUpdateRegion()); // get the update rect list +%% +%% while (upd) +%% { +%% vX = upd.GetX(); +%% vY = upd.GetY(); +%% vW = upd.GetW(); +%% vH = upd.GetH(); +%% +%% // Alternatively we can do this: +%% // wxRect rect; +%% // upd.GetRect(&rect); +%% +%% // Repaint this rectangle +%% ...some code... +%% +%% upd ++ ; +%% } +%% } +%% \end{verbatim} +%% }% +%% +%% \wxheading{See also} +%% +%% \helpref{wxPaintEvent}{wxpaintevent},\rtfsp +%% \helpref{wxPaintDC}{wxpaintdc},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnScroll}\label{wxwindowonscroll} +%% +%% \func{void}{OnScroll}{\param{wxScrollWinEvent\& }{event}} +%% +%% Called when a scroll window event is received from one of the window's built-in scrollbars. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{Command event. Retrieve the new scroll position by +%% calling \helpref{wxScrollEvent::GetPosition}{wxscrolleventgetposition}, and the +%% scrollbar orientation by calling \helpref{wxScrollEvent::GetOrientation}{wxscrolleventgetorientation}.} +%% +%% \wxheading{Remarks} +%% +%% Note that it is not possible to distinguish between horizontal and vertical scrollbars +%% until the function is executing (you can't have one function for vertical, another +%% for horizontal events). +%% +%% \wxheading{See also} +%% +%% \helpref{wxScrollWinEvent}{wxscrollwinevent},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnSetFocus}\label{wxwindowonsetfocus} +%% +%% \func{void}{OnSetFocus}{\param{wxFocusEvent\& }{event}} +%% +%% Called when a window's focus is being set. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{The focus event. For more information, see \helpref{wxFocusEvent}{wxfocusevent}.} +%% +%% \wxheading{Remarks} +%% +%% To intercept this event, use the macro EVT\_SET\_FOCUS in an event table definition. +%% +%% Most, but not all, windows respond to this event. +%% +%% \wxheading{See also} +%% +%% \helpref{wxFocusEvent}{wxfocusevent}, \helpref{wxWindow::OnKillFocus}{wxwindowonkillfocus},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnSize}\label{wxwindowonsize} +%% +%% \func{void}{OnSize}{\param{wxSizeEvent\& }{event}} +%% +%% Called when the window has been resized. This is not a virtual function; you should +%% provide your own non-virtual OnSize function and direct size events to it using EVT\_SIZE +%% in an event table definition. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{Size event. For more information, see \helpref{wxSizeEvent}{wxsizeevent}.} +%% +%% \wxheading{Remarks} +%% +%% You may wish to use this for frames to resize their child windows as appropriate. +%% +%% Note that the size passed is of +%% the whole window: call \helpref{wxWindow::GetClientSize}{wxwindowgetclientsize} for the area which may be +%% used by the application. +%% +%% When a window is resized, usually only a small part of the window is damaged and you +%% may only need to repaint that area. However, if your drawing depends on the size of the window, +%% you may need to clear the DC explicitly and repaint the whole window. In which case, you +%% may need to call \helpref{wxWindow::Refresh}{wxwindowrefresh} to invalidate the entire window. +%% +%% \wxheading{See also} +%% +%% \helpref{wxSizeEvent}{wxsizeevent},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} +%% +%% \membersection{wxWindow::OnSysColourChanged}\label{wxwindowonsyscolourchanged} +%% +%% \func{void}{OnSysColourChanged}{\param{wxOnSysColourChangedEvent\& }{event}} +%% +%% Called when the user has changed the system colours. Windows only. +%% +%% \wxheading{Parameters} +%% +%% \docparam{event}{System colour change event. For more information, see \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}.} +%% +%% \wxheading{See also} +%% +%% \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent},\rtfsp +%% \helpref{Event handling overview}{eventhandlingoverview} -Called when a window is activated or deactivated. +\membersection{wxWindow::PopEventHandler}\label{wxwindowpopeventhandler} -\wxheading{Parameters} +\constfunc{wxEvtHandler*}{PopEventHandler}{\param{bool }{deleteHandler = {\tt FALSE}}} -\docparam{event}{Object containing activation information.} +Removes and returns the top-most event handler on the event handler stack. -\wxheading{Remarks} +\wxheading{Parameters} -If the window is being activated, \helpref{wxActivateEvent::GetActive}{wxactivateeventgetactive} returns TRUE, -otherwise it returns FALSE (it is being deactivated). +\docparam{deleteHandler}{If this is {\tt TRUE}, the handler will be deleted after it is removed. The +default value is {\tt FALSE}.} \wxheading{See also} -\helpref{wxActivateEvent}{wxactivateevent},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} +\helpref{wxWindow::SetEventHandler}{wxwindowseteventhandler},\rtfsp +\helpref{wxWindow::GetEventHandler}{wxwindowgeteventhandler},\rtfsp +\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp +\helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent},\rtfsp +\helpref{wxEvtHandler}{wxevthandler}\rtfsp + +\membersection{wxWindow::PopupMenu}\label{wxwindowpopupmenu} -\membersection{wxWindow::OnChar}\label{wxwindowonchar} +\func{bool}{PopupMenu}{\param{wxMenu* }{menu}, \param{const wxPoint\& }{pos}} -\func{void}{OnChar}{\param{wxKeyEvent\&}{ event}} +\func{bool}{PopupMenu}{\param{wxMenu* }{menu}, \param{int }{x}, \param{int }{y}} -Called when the user has pressed a key that is not a modifier (SHIFT, CONTROL or ALT). +Pops up the given menu at the specified coordinates, relative to this +window, and returns control when the user has dismissed the menu. If a +menu item is selected, the corresponding menu event is generated and will be +processed as usually. \wxheading{Parameters} -\docparam{event}{Object containing keypress information. See \helpref{wxKeyEvent}{wxkeyevent} for -details about this class.} +\docparam{menu}{Menu to pop up.} -\wxheading{Remarks} +\docparam{pos}{The position where the menu will appear.} -This member function is called in response to a keypress. To intercept this event, -use the EVT\_CHAR macro in an event table definition. Your {\bf OnChar} handler may call this -default function to achieve default keypress functionality. +\docparam{x}{Required x position for the menu to appear.} -Note that the ASCII values do not have explicit key codes: they are passed as ASCII -values. +\docparam{y}{Required y position for the menu to appear.} -Note that not all keypresses can be intercepted this way. If you wish to intercept modifier -keypresses, then you will need to use \helpref{wxWindow::OnKeyDown}{wxwindowonkeydown} or -\helpref{wxWindow::OnKeyUp}{wxwindowonkeyup}. +\wxheading{See also} -Most, but not all, windows allow keypresses to be intercepted. +\helpref{wxMenu}{wxmenu} -\wxheading{See also} +\wxheading{Remarks} -\helpref{wxWindow::OnKeyDown}{wxwindowonkeydown}, \helpref{wxWindow::OnKeyUp}{wxwindowonkeyup},\rtfsp -\helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnCharHook}{wxwindowoncharhook},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} +Just before the menu is popped up, \helpref{wxMenu::UpdateUI}{wxmenuupdateui} is called +to ensure that the menu items are in the correct state. The menu does not get deleted +by the window. + +\pythonnote{In place of a single overloaded method name, wxPython +implements the following methods:\par +\indented{2cm}{\begin{twocollist} +\twocolitem{{\bf PopupMenu(menu, point)}}{Specifies position with a wxPoint} +\twocolitem{{\bf PopupMenuXY(menu, x, y)}}{Specifies position with two integers (x, y)} +\end{twocollist}} +} -\membersection{wxWindow::OnCharHook}\label{wxwindowoncharhook} +\membersection{wxWindow::PushEventHandler}\label{wxwindowpusheventhandler} -\func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}} +\func{void}{PushEventHandler}{\param{wxEvtHandler* }{handler}} -This member is called to allow the window to intercept keyboard events -before they are processed by child windows. +Pushes this event handler onto the event stack for the window. \wxheading{Parameters} -\docparam{event}{Object containing keypress information. See \helpref{wxKeyEvent}{wxkeyevent} for -details about this class.} +\docparam{handler}{Specifies the handler to be pushed.} \wxheading{Remarks} -This member function is called in response to a keypress, if the window is active. To intercept this event, -use the EVT\_CHAR\_HOOK macro in an event table definition. If you do not process a particular -keypress, call \helpref{wxEvent::Skip}{wxeventskip} to allow default processing. - -An example of using this function is in the implementation of escape-character processing for wxDialog, -where pressing ESC dismisses the dialog by {\bf OnCharHook} 'forging' a cancel button press event. - -Note that the ASCII values do not have explicit key codes: they are passed as ASCII -values. +An event handler is an object that is capable of processing the events +sent to a window. By default, the window is its own event handler, but +an application may wish to substitute another, for example to allow +central implementation of event-handling for a variety of different +window classes. -This function is only relevant to top-level windows (frames and dialogs), and under -Windows only. +\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler} allows +an application to set up a chain of event handlers, where an event not handled by one event handler is +handed to the next one in the chain. Use \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler} to +remove the event handler. \wxheading{See also} -\helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnCharHook}{wxwindowoncharhook},\rtfsp -\helpref{wxApp::OnCharHook}{wxapponcharhook},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} - -\membersection{wxWindow::OnCommand}\label{wxwindowoncommand} +\helpref{wxWindow::SetEventHandler}{wxwindowseteventhandler},\rtfsp +\helpref{wxWindow::GetEventHandler}{wxwindowgeteventhandler},\rtfsp +\helpref{wxWindow::PopEventHandler}{wxwindowpusheventhandler},\rtfsp +\helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent},\rtfsp +\helpref{wxEvtHandler}{wxevthandler} -\func{virtual void}{OnCommand}{\param{wxEvtHandler\& }{object}, \param{wxCommandEvent\& }{event}} +\membersection{wxWindow::Raise}\label{wxwindowraise} -This virtual member function is called if the control does not handle the command event. +\func{void}{Raise}{\void} -\wxheading{Parameters} +Raises the window to the top of the window hierarchy if it is a managed window (dialog +or frame). -\docparam{object}{Object receiving the command event.} +\membersection{wxWindow::Refresh}\label{wxwindowrefresh} -\docparam{event}{Command event} +\func{virtual void}{Refresh}{\param{bool}{ eraseBackground = {\tt TRUE}}, \param{const wxRect* }{rect += NULL}} -\wxheading{Remarks} +Causes a message or event to be generated to repaint the +window. -This virtual function is provided mainly for backward compatibility. You can also intercept commands -from child controls by using an event table, with identifiers or identifier ranges to identify -the control(s) in question. +\wxheading{Parameters} -\wxheading{See also} +\docparam{eraseBackground}{If {\tt TRUE}, the background will be +erased.} -\helpref{wxCommandEvent}{wxcommandevent},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} +\docparam{rect}{If non-NULL, only the given rectangle will +be treated as damaged.} -\membersection{wxWindow::OnClose}\label{wxwindowonclose} +\membersection{wxWindow::ReleaseMouse}\label{wxwindowreleasemouse} -\func{virtual bool}{OnClose}{\void} +\func{virtual void}{ReleaseMouse}{\void} -Called when the user has tried to close a a frame -or dialog box using the window manager (X) or system menu (Windows). +Releases mouse input captured with \helpref{wxWindow::CaptureMouse}{wxwindowcapturemouse}. -{\bf Note:} This is an obsolete function. -It is superceded by the \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow} event -handler. +\wxheading{See also} -\wxheading{Return value} +\helpref{wxWindow::CaptureMouse}{wxwindowcapturemouse} -If TRUE is returned by OnClose, the window will be deleted by the system, otherwise the -attempt will be ignored. Do not delete the window from within this handler, although -you may delete other windows. +\membersection{wxWindow::RemoveChild}\label{wxwindowremovechild} -\wxheading{See also} +\func{virtual void}{RemoveChild}{\param{wxWindow* }{child}} -\helpref{Window deletion overview}{windowdeletionoverview},\rtfsp -\helpref{wxWindow::Close}{wxwindowclose},\rtfsp -\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp -\helpref{wxCloseEvent}{wxcloseevent} +Removes a child window. This is called automatically by window deletion +functions so should not be required by the application programmer. -\membersection{wxWindow::OnCloseWindow}\label{wxwindowonclosewindow} +\wxheading{Parameters} -\func{void}{OnCloseWindow}{\param{wxCloseEvent\& }{event}} +\docparam{child}{Child window to remove.} -This is an event handler function called when the user has tried to close a a frame -or dialog box using the window manager (X) or system menu (Windows). It is -called via the \helpref{wxWindow::Close}{wxwindowclose} function, so -that the application can also invoke the handler programmatically. +\membersection{wxWindow::RemoveEventHandler}{wxwindowremoveeventhandler} -Use the EVT\_CLOSE event table macro to handle close events. +\func{bool}{RemoveEventHandler}{\param{wxEvtHandler *}{handler}} -You should check whether the application is forcing the deletion of the window -using \helpref{wxCloseEvent::GetForce}{wxcloseeventgetforce}. If this is TRUE, -destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}. -If not, it is up to you whether you respond by destroying the window. +Find the given {\it handler} in the windows event handler chain and remove (but +not delete) it from it. -(Note: GetForce is now superceded by CanVeto. So to test whether forced destruction of -the window is required, test for the negative of CanVeto. If CanVeto returns FALSE, -it is not possible to skip window deletion.) +\wxheading{Parameters} -If you don't destroy the window, you should call \helpref{wxCloseEvent::Veto}{wxcloseeventveto} to -let the calling code know that you did not destroy the window. This allows the \helpref{wxWindow::Close}{wxwindowclose} function -to return TRUE or FALSE depending on whether the close instruction was honoured or not. +\docparam{handler}{The event handler to remove, must be non {\tt NULL} and +must be present in this windows event handlers chain} -\wxheading{Remarks} +\wxheading{Return value} -The \helpref{wxWindow::OnClose}{wxwindowonclose} virtual function remains -for backward compatibility with earlier versions of wxWindows. The -default {\bf OnCloseWindow} handler for wxFrame and wxDialog will call {\bf OnClose}, -destroying the window if it returns TRUE or if the close is being forced. +Returns {\tt TRUE} if it was found and {\tt FALSE} otherwise (this also results +in an assert failure so this function should only be called when the +handler is supposed to be there). \wxheading{See also} -\helpref{Window deletion overview}{windowdeletionoverview},\rtfsp -\helpref{wxWindow::Close}{wxwindowclose},\rtfsp -\helpref{wxWindow::OnClose}{wxwindowonclose},\rtfsp -\helpref{wxWindow::Destroy}{wxwindowdestroy},\rtfsp -\helpref{wxCloseEvent}{wxcloseevent},\rtfsp -\helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession},\rtfsp -\helpref{wxApp::OnEndSession}{wxapponendsession} +\helpref{PushEventHandler}{wxwindowpusheventhandler},\rtfsp +\helpref{PopEventHandler}{wxwindowpopeventhandler} -\membersection{wxWindow::OnDropFiles}\label{wxwindowondropfiles} +\membersection{wxWindow::Reparent}\label{wxwindowreparent} -\func{void}{OnDropFiles}{\param{wxDropFilesEvent\&}{ event}} +\func{virtual bool}{Reparent}{\param{wxWindow* }{newParent}} -Called when files have been dragged from the file manager to the window. +Reparents the window, i.e the window will be removed from its +current parent window (e.g. a non-standard toolbar in a wxFrame) +and then re-inserted into another. Available on Windows and GTK. \wxheading{Parameters} -\docparam{event}{Drop files event. For more information, see \helpref{wxDropFilesEvent}{wxdropfilesevent}.} +\docparam{newParent}{New parent.} -\wxheading{Remarks} +\membersection{wxWindow::ScreenToClient}\label{wxwindowscreentoclient} + +\constfunc{virtual void}{ScreenToClient}{\param{int* }{x}, \param{int* }{y}} -The window must have previously been enabled for dropping by calling -\rtfsp\helpref{wxWindow::DragAcceptFiles}{wxwindowdragacceptfiles}. +\constfunc{virtual wxPoint}{ScreenToClient}{\param{const wxPoint\& }{pt}} -This event is only generated under Windows. +Converts from screen to client window coordinates. -To intercept this event, use the EVT\_DROP\_FILES macro in an event table definition. +\wxheading{Parameters} -\wxheading{See also} +\docparam{x}{Stores the screen x coordinate and receives the client x coordinate.} -\helpref{wxDropFilesEvent}{wxdropfilesevent}, \helpref{wxWindow::DragAcceptFiles}{wxwindowdragacceptfiles},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} +\docparam{y}{Stores the screen x coordinate and receives the client x coordinate.} -\membersection{wxWindow::OnEraseBackground}\label{wxwindowonerasebackground} +\docparam{pt}{The screen position for the second form of the function.} -\func{void}{OnEraseBackground}{\param{wxEraseEvent\&}{ event}} +\pythonnote{In place of a single overloaded method name, wxPython +implements the following methods:\par +\indented{2cm}{\begin{twocollist} +\twocolitem{{\bf ScreenToClient(point)}}{Accepts and returns a wxPoint} +\twocolitem{{\bf ScreenToClientXY(x, y)}}{Returns a 2-tuple, (x, y)} +\end{twocollist}} +} -Called when the background of the window needs to be erased. +\membersection{wxWindow::ScrollLines}\label{wxwindowscrolllines} -\wxheading{Parameters} +\func{virtual bool}{ScrollLines}{\param{int }{lines}} -\docparam{event}{Erase background event. For more information, see \helpref{wxEraseEvent}{wxeraseevent}.} +Scrolls the window by the given number of lines down (if {\it lines} is +positive) or up. -\wxheading{Remarks} +\wxheading{Return value} + +Returns {\tt TRUE} if the window was scrolled, {\tt FALSE} if it was already +on top/bottom and nothing was done. -This event is only generated under Windows. +\wxheading{Remarks} -To intercept this event, use the EVT\_ERASE\_BACKGROUND macro in an event table definition. +This function is currently only implemented under MSW and wxTextCtrl under +wxGTK (it also works for wxScrolledWindow derived classes under all +platforms). \wxheading{See also} -\helpref{wxEraseEvent}{wxeraseevent}, \helpref{Event handling overview}{eventhandlingoverview} +\helpref{ScrollPages}{wxwindowscrollpages} -\membersection{wxWindow::OnKeyDown}\label{wxwindowonkeydown} +\membersection{wxWindow::ScrollPages}\label{wxwindowscrollpages} -\func{void}{OnKeyDown}{\param{wxKeyEvent\&}{ event}} +\func{virtual bool}{ScrollPages}{\param{int }{pages}} -Called when the user has pressed a key, before it is translated into an ASCII value using other -modifier keys that might be pressed at the same time. +Scrolls the window by the given number of pages down (if {\it pages} is +positive) or up. -\wxheading{Parameters} +\wxheading{Return value} -\docparam{event}{Object containing keypress information. See \helpref{wxKeyEvent}{wxkeyevent} for -details about this class.} +Returns {\tt TRUE} if the window was scrolled, {\tt FALSE} if it was already +on top/bottom and nothing was done. \wxheading{Remarks} -This member function is called in response to a key down event. To intercept this event, -use the EVT\_KEY\_DOWN macro in an event table definition. Your {\bf OnKeyDown} handler may call this -default function to achieve default keypress functionality. - -Note that not all keypresses can be intercepted this way. If you wish to intercept special -keys, such as shift, control, and function keys, then you will need to use \helpref{wxWindow::OnKeyDown}{wxwindowonkeydown} or -\helpref{wxWindow::OnKeyUp}{wxwindowonkeyup}. - -Most, but not all, windows allow keypresses to be intercepted. +This function is currently only implemented under MSW and wxTextCtrl under +wxGTK (it also works for wxScrolledWindow derived classes under all +platforms). \wxheading{See also} -\helpref{wxWindow::OnChar}{wxwindowonchar}, \helpref{wxWindow::OnKeyUp}{wxwindowonkeyup},\rtfsp -\helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnCharHook}{wxwindowoncharhook},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} - -\membersection{wxWindow::OnKeyUp}\label{wxwindowonkeyup} - -\func{void}{OnKeyUp}{\param{wxKeyEvent\&}{ event}} - -Called when the user has released a key. - -\wxheading{Parameters} - -\docparam{event}{Object containing keypress information. See \helpref{wxKeyEvent}{wxkeyevent} for -details about this class.} - -\wxheading{Remarks} - -This member function is called in response to a key up event. To intercept this event, -use the EVT\_KEY\_UP macro in an event table definition. Your {\bf OnKeyUp} handler may call this -default function to achieve default keypress functionality. - -Note that not all keypresses can be intercepted this way. If you wish to intercept special -keys, such as shift, control, and function keys, then you will need to use \helpref{wxWindow::OnKeyDown}{wxwindowonkeydown} or -\helpref{wxWindow::OnKeyUp}{wxwindowonkeyup}. - -Most, but not all, windows allow key up events to be intercepted. - -\wxheading{See also} - -\helpref{wxWindow::OnChar}{wxwindowonchar}, \helpref{wxWindow::OnKeyDown}{wxwindowonkeydown},\rtfsp -\helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnCharHook}{wxwindowoncharhook},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} - -\membersection{wxWindow::OnKillFocus}\label{wxwindowonkillfocus} - -\func{void}{OnKillFocus}{\param{wxFocusEvent\& }{event}} - -Called when a window's focus is being killed. - -\wxheading{Parameters} - -\docparam{event}{The focus event. For more information, see \helpref{wxFocusEvent}{wxfocusevent}.} - -\wxheading{Remarks} - -To intercept this event, use the macro EVT\_KILL\_FOCUS in an event table definition. - -Most, but not all, windows respond to this event. - -\wxheading{See also} - -\helpref{wxFocusEvent}{wxfocusevent}, \helpref{wxWindow::OnSetFocus}{wxwindowonsetfocus},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} - -\membersection{wxWindow::OnIdle}\label{wxwindowonidle} - -\func{void}{OnIdle}{\param{wxIdleEvent\& }{event}} - -Provide this member function for any processing which needs to be done -when the application is idle. - -\wxheading{See also} - -\helpref{wxApp::OnIdle}{wxapponidle}, \helpref{wxIdleEvent}{wxidleevent} - -\membersection{wxWindow::OnInitDialog}\label{wxwindowoninitdialog} - -\func{void}{OnInitDialog}{\param{wxInitDialogEvent\&}{ event}} - -Default handler for the wxEVT\_INIT\_DIALOG event. Calls \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow}. - -\wxheading{Parameters} - -\docparam{event}{Dialog initialisation event.} - -\wxheading{Remarks} - -Gives the window the default behaviour of transferring data to child controls via -the validator that each control has. - -\wxheading{See also} - -\helpref{wxValidator}{wxvalidator}, \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow} - -\membersection{wxWindow::OnMenuCommand}\label{wxwindowonmenucommand} - -\func{void}{OnMenuCommand}{\param{wxCommandEvent\& }{event}} - -Called when a menu command is received from a menu bar. - -\wxheading{Parameters} - -\docparam{event}{The menu command event. For more information, see \helpref{wxCommandEvent}{wxcommandevent}.} - -\wxheading{Remarks} - -A function with this name doesn't actually exist; you can choose any member function to receive -menu command events, using the EVT\_COMMAND macro for individual commands or EVT\_COMMAND\_RANGE for -a range of commands. - -\wxheading{See also} - -\helpref{wxCommandEvent}{wxcommandevent},\rtfsp -\helpref{wxWindow::OnMenuHighlight}{wxwindowonmenuhighlight},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} - -\membersection{wxWindow::OnMenuHighlight}\label{wxwindowonmenuhighlight} - -\func{void}{OnMenuHighlight}{\param{wxMenuEvent\& }{event}} - -Called when a menu select is received from a menu bar: that is, the -mouse cursor is over a menu item, but the left mouse button has not been -pressed. - -\wxheading{Parameters} - -\docparam{event}{The menu highlight event. For more information, see \helpref{wxMenuEvent}{wxmenuevent}.} - -\wxheading{Remarks} - -You can choose any member function to receive -menu select events, using the EVT\_MENU\_HIGHLIGHT macro for individual menu items or EVT\_MENU\_HIGHLIGHT\_ALL macro -for all menu items. - -The default implementation for \helpref{wxFrame::OnMenuHighlight}{wxframeonmenuhighlight} displays help -text in the first field of the status bar. - -This function was known as {\bf OnMenuSelect} in earlier versions of wxWindows, but this was confusing -since a selection is normally a left-click action. - -\wxheading{See also} - -\helpref{wxMenuEvent}{wxmenuevent},\rtfsp -\helpref{wxWindow::OnMenuCommand}{wxwindowonmenucommand},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} - - -\membersection{wxWindow::OnMouseEvent}\label{wxwindowonmouseevent} - -\func{void}{OnMouseEvent}{\param{wxMouseEvent\&}{ event}} - -Called when the user has initiated an event with the -mouse. - -\wxheading{Parameters} - -\docparam{event}{The mouse event. See \helpref{wxMouseEvent}{wxmouseevent} for -more details.} - -\wxheading{Remarks} - -Most, but not all, windows respond to this event. - -To intercept this event, use the EVT\_MOUSE\_EVENTS macro in an event table definition, or individual -mouse event macros such as EVT\_LEFT\_DOWN. - -\wxheading{See also} - -\helpref{wxMouseEvent}{wxmouseevent},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} - -\membersection{wxWindow::OnMove}\label{wxwindowonmove} - -\func{void}{OnMove}{\param{wxMoveEvent\& }{event}} - -Called when a window is moved. - -\wxheading{Parameters} - -\docparam{event}{The move event. For more information, see \helpref{wxMoveEvent}{wxmoveevent}.} - -\wxheading{Remarks} - -Use the EVT\_MOVE macro to intercept move events. - -\wxheading{Remarks} - -Not currently implemented. - -\wxheading{See also} - -\helpref{wxMoveEvent}{wxmoveevent},\rtfsp -\helpref{wxFrame::OnSize}{wxframeonsize},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} - -\membersection{wxWindow::OnPaint}\label{wxwindowonpaint} - -\func{void}{OnPaint}{\param{wxPaintEvent\& }{event}} - -Sent to the event handler when the window must be refreshed. - -\wxheading{Parameters} - -\docparam{event}{Paint event. For more information, see \helpref{wxPaintEvent}{wxpaintevent}.} - -\wxheading{Remarks} - -Use the EVT\_PAINT macro in an event table definition to intercept paint events. - -In a paint event handler, the application should always create a \helpref{wxPaintDC}{wxpaintdc} object. - -For example: - -\small{% -\begin{verbatim} - void MyWindow::OnPaint(wxPaintEvent& event) - { - wxPaintDC dc(this); - - DrawMyDocument(dc); - } -\end{verbatim} -}% - -You can optimize painting by retrieving the rectangles -that have been damaged and only repainting these. The rectangles are in -terms of the client area, and are unscrolled, so you will need to do -some calculations using the current view position to obtain logical, -scrolled units. - -Here is an example of using the \helpref{wxRegionIterator}{wxregioniterator} class: - -{\small% -\begin{verbatim} -// Called when window needs to be repainted. -void MyWindow::OnPaint(wxPaintEvent& event) -{ - wxPaintDC dc(this); - - // Find Out where the window is scrolled to - int vbX,vbY; // Top left corner of client - ViewStart(&vbX,&vbY); - - int vX,vY,vW,vH; // Dimensions of client area in pixels - wxRegionIterator upd(GetUpdateRegion()); // get the update rect list - - while (upd) - { - vX = upd.GetX(); - vY = upd.GetY(); - vW = upd.GetW(); - vH = upd.GetH(); - - // Alternatively we can do this: - // wxRect rect; - // upd.GetRect(&rect); - - // Repaint this rectangle - ...some code... - - upd ++ ; - } -} -\end{verbatim} -}% - -\wxheading{See also} - -\helpref{wxPaintEvent}{wxpaintevent},\rtfsp -\helpref{wxPaintDC}{wxpaintdc},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} - -\membersection{wxWindow::OnScroll}\label{wxwindowonscroll} - -\func{void}{OnScroll}{\param{wxScrollEvent\& }{event}} - -Called when a scroll event is received from one of the window's built-in scrollbars. - -\wxheading{Parameters} - -\docparam{event}{Command event. Retrieve the new scroll position by -calling \helpref{wxScrollEvent::GetPosition}{wxscrolleventgetposition}, and the -scrollbar orientation by calling \helpref{wxScrollEvent::GetOrientation}{wxscrolleventgetorientation}.} - -\wxheading{Remarks} - -Note that it is not possible to distinguish between horizontal and vertical scrollbars -until the function is executing (you can't have one function for vertical, another -for horizontal events). - -\wxheading{See also} - -\helpref{wxScrollEvent}{wxscrollevent},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} - -\membersection{wxWindow::OnSetFocus}\label{wxwindowonsetfocus} - -\func{void}{OnSetFocus}{\param{wxFocusEvent\& }{event}} - -Called when a window's focus is being set. - -\wxheading{Parameters} - -\docparam{event}{The focus event. For more information, see \helpref{wxFocusEvent}{wxfocusevent}.} - -\wxheading{Remarks} - -To intercept this event, use the macro EVT\_SET\_FOCUS in an event table definition. - -Most, but not all, windows respond to this event. - -\wxheading{See also} - -\helpref{wxFocusEvent}{wxfocusevent}, \helpref{wxWindow::OnKillFocus}{wxwindowonkillfocus},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} - -\membersection{wxWindow::OnSize}\label{wxwindowonsize} - -\func{void}{OnSize}{\param{wxSizeEvent\& }{event}} - -Called when the window has been resized. - -\wxheading{Parameters} - -\docparam{event}{Size event. For more information, see \helpref{wxSizeEvent}{wxsizeevent}.} - -\wxheading{Remarks} - -You may wish to use this for frames to resize their child windows as appropriate. - -Note that the size passed is of -the whole window: call \helpref{wxWindow::GetClientSize}{wxwindowgetclientsize} for the area which may be -used by the application. - -\wxheading{See also} - -\helpref{wxSizeEvent}{wxsizeevent},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} - -\membersection{wxWindow::OnSysColourChanged}\label{wxwindowonsyscolourchanged} - -\func{void}{OnSysColourChanged}{\param{wxOnSysColourChangedEvent\& }{event}} - -Called when the user has changed the system colours. - -\wxheading{Parameters} - -\docparam{event}{System colour change event. For more information, see \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}.} - -\wxheading{See also} - -\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} - -\membersection{wxWindow::PopEventHandler}\label{wxwindowpopeventhandler} - -\constfunc{wxEvtHandler*}{PopEventHandler}{\param{bool }{deleteHandler = FALSE}} - -Removes and returns the top-most event handler on the event handler stack. - -\wxheading{Parameters} - -\docparam{deleteHandler}{If this is TRUE, the handler will be deleted after it is removed. The -default value is FALSE.} - -\wxheading{See also} - -\helpref{wxWindow::SetEventHandler}{wxwindowseteventhandler},\rtfsp -\helpref{wxWindow::GetEventHandler}{wxwindowgeteventhandler},\rtfsp -\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp -\helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent},\rtfsp -\helpref{wxEvtHandler}{wxevthandler}\rtfsp - -\membersection{wxWindow::PopupMenu}\label{wxwindowpopupmenu} - -\func{virtual bool}{PopupMenu}{\param{wxMenu* }{menu}, \param{int }{x}, \param{int }{y}} - -Pops up the given menu at the specified coordinates, relative to this -window, and returns control when the user has dismissed the menu. If a -menu item is selected, the callback defined for the menu is called with -wxMenu and wxCommandEvent reference arguments. The callback should access -the commandInt member of the event to check the selected menu identifier. - -\wxheading{Parameters} - -\docparam{menu}{Menu to pop up.} - -\docparam{x}{Required x position for the menu to appear.} - -\docparam{y}{Required y position for the menu to appear.} - -\wxheading{See also} - -\helpref{wxMenu}{wxmenu} - -\wxheading{Remarks} - -Just before the menu is popped up, \helpref{wxMenu::UpdateUI}{wxmenuupdateui} is called -to ensure that the menu items are in the correct state. - -\membersection{wxWindow::PushEventHandler}\label{wxwindowpusheventhandler} - -\func{void}{PushEventHandler}{\param{wxEvtHandler* }{handler}} - -Pushes this event handler onto the event stack for the window. - -\wxheading{Parameters} - -\docparam{handler}{Specifies the handler to be pushed.} - -\wxheading{Remarks} - -An event handler is an object that is capable of processing the events -sent to a window. By default, the window is its own event handler, but -an application may wish to substitute another, for example to allow -central implementation of event-handling for a variety of different -window classes. - -\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler} allows -an application to set up a chain of event handlers, where an event not handled by one event handler is -handed to the next one in the chain. Use \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler} to -remove the event handler. - -\wxheading{See also} - -\helpref{wxWindow::SetEventHandler}{wxwindowseteventhandler},\rtfsp -\helpref{wxWindow::GetEventHandler}{wxwindowgeteventhandler},\rtfsp -\helpref{wxWindow::PopEventHandler}{wxwindowpusheventhandler},\rtfsp -\helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent},\rtfsp -\helpref{wxEvtHandler}{wxevthandler} - -\membersection{wxWindow::Raise}\label{wxwindowraise} - -\func{void}{Raise}{\void} - -Raises the window to the top of the window hierarchy if it is a managed window (dialog -or frame). - -\membersection{wxWindow::Refresh}\label{wxwindowrefresh} - -\func{virtual void}{Refresh}{\param{const bool}{ eraseBackground = TRUE}, \param{const wxRect* }{rect -= NULL}} - -Causes a message or event to be generated to repaint the -window. - -\wxheading{Parameters} - -\docparam{eraseBackground}{If TRUE, the background will be -erased.} - -\docparam{rect}{If non-NULL, only the given rectangle will -be treated as damaged.} - -\membersection{wxWindow::ReleaseMouse}\label{wxwindowreleasemouse} - -\func{virtual void}{ReleaseMouse}{\void} - -Releases mouse input captured with \helpref{wxWindow::CaptureMouse}{wxwindowcapturemouse}. - -\wxheading{See also} - -\helpref{wxWindow::CaptureMouse}{wxwindowcapturemouse} - -\membersection{wxWindow::RemoveChild}\label{wxwindowremovechild} - -\func{virtual void}{RemoveChild}{\param{wxWindow* }{child}} - -Removes a child window. This is called automatically by window deletion -functions so should not be required by the application programmer. - -\wxheading{Parameters} - -\docparam{child}{Child window to remove.} - -\membersection{wxWindow::ScreenToClient}\label{wxwindowscreentoclient} - -\constfunc{virtual void}{ScreenToClient}{\param{int* }{x}, \param{int* }{y}} - -\constfunc{virtual wxPoint}{ScreenToClient}{\param{const wxPoint\& }{pt}} - -Converts from screen to client window coordinates. - -\wxheading{Parameters} - -\docparam{x}{Stores the screen x coordinate and receives the client x coordinate.} - -\docparam{y}{Stores the screen x coordinate and receives the client x coordinate.} - -\docparam{pt}{The screen position for the second form of the function.} - -\pythonnote{In place of a single overloaded method name, wxPython -implements the following methods:\par -\indented{2cm}{\begin{twocollist} -\twocolitem{\bf{ScreenToClient(point)}}{Accepts and returns a wxPoint} -\twocolitem{\bf{ScreenToClientXY(x, y)}}{Returns a 2-tuple, (x, y)} -\end{twocollist}} -} - +\helpref{ScrollLines}{wxwindowscrolllines} \membersection{wxWindow::ScrollWindow}\label{wxwindowscrollwindow} \func{virtual void}{ScrollWindow}{\param{int }{dx}, \param{int }{dy}, \param{const wxRect*}{ rect = NULL}} -Physically scrolls the pixels in the window. +Physically scrolls the pixels in the window and move child windows accordingly. \wxheading{Parameters} @@ -1601,14 +1918,12 @@ Physically scrolls the pixels in the window. \docparam{rect}{Rectangle to invalidate. If this is NULL, the whole window is invalidated. If you pass a rectangle corresponding to the area of the window exposed by the scroll, your painting handler -can optimise painting by checking for the invalidated region.} +can optimize painting by checking for the invalidated region. This parameter is ignored under GTK.} \wxheading{Remarks} -Available only under Windows. - Use this function to optimise your scrolling implementations, to minimise the area that must be -redrawn. +redrawn. Note that it is rarely required to call this function from a user program. \membersection{wxWindow::SetAcceleratorTable}\label{wxwindowsetacceleratortable} @@ -1618,14 +1933,17 @@ Sets the accelerator table for this window. See \helpref{wxAcceleratorTable}{wxa \membersection{wxWindow::SetAutoLayout}\label{wxwindowsetautolayout} -\func{void}{SetAutoLayout}{\param{const bool}{ autoLayout}} +\func{void}{SetAutoLayout}{\param{bool}{ autoLayout}} Determines whether the \helpref{wxWindow::Layout}{wxwindowlayout} function will -be called automatically when the window is resized. +be called automatically when the window is resized. Use in connection with +\helpref{wxWindow::SetSizer}{wxwindowsetsizer} and +\helpref{wxWindow::SetConstraints}{wxwindowsetconstraints} for laying out +subwindows. \wxheading{Parameters} -\docparam{autoLayout}{Set this to TRUE if you wish the Layout function to be called +\docparam{autoLayout}{Set this to {\tt TRUE} if you wish the Layout function to be called from within wxWindow::OnSize functions.} \wxheading{See also} @@ -1645,12 +1963,17 @@ Sets the background colour of the window. \wxheading{Remarks} The background colour is usually painted by the default\rtfsp -\helpref{wxWindow::OnEraseBackground}{wxwindowonerasebackground} event handler function. +\helpref{wxWindow::OnEraseBackground}{wxwindowonerasebackground} event handler function +under Windows and automatically under GTK. Note that setting the background colour does not cause an immediate refresh, so you may wish to call \helpref{wxWindow::Clear}{wxwindowclear} or \helpref{wxWindow::Refresh}{wxwindowrefresh} after calling this function. +Use this function with care under GTK as the new appearance of the window might +not look equally well when used with "Themes", i.e GTK's ability to change its +look as the user wishes with run-time loadable modules. + \wxheading{See also} \helpref{wxWindow::GetBackgroundColour}{wxwindowgetbackgroundcolour},\rtfsp @@ -1660,6 +1983,12 @@ calling this function. \helpref{wxWindow::Refresh}{wxwindowrefresh},\rtfsp \helpref{wxWindow::OnEraseBackground}{wxwindowonerasebackground} +\membersection{wxWindow::SetCaret}\label{wxwindowsetcaret} + +\constfunc{void}{SetCaret}{\param{wxCaret *}{caret}} + +Sets the \helpref{caret}{wxcaret} associated with the window. + \membersection{wxWindow::SetClientSize}\label{wxwindowsetclientsize} \func{virtual void}{SetClientSize}{\param{int}{ width}, \param{int}{ height}} @@ -1682,18 +2011,30 @@ around panel items, for example. \pythonnote{In place of a single overloaded method name, wxPython implements the following methods:\par \indented{2cm}{\begin{twocollist} -\twocolitem{\bf{SetClientSize(size)}}{Accepts a wxSize} -\twocolitem{\bf{SetClientSizeWH(width, height)}}{} +\twocolitem{{\bf SetClientSize(size)}}{Accepts a wxSize} +\twocolitem{{\bf SetClientSizeWH(width, height)}}{} \end{twocollist}} } +\membersection{wxWindow::SetContainingSizer}\label{wxwindowsetcontainingsizer} + +\func{void}{SetContainingSizer}{\param{wxSizer* }{sizer}} + +This normally does not need to be called by user code. It is called +when a window is added to a sizer, and is used so the window can +remove itself from the sizer when it is destroyed. + \membersection{wxWindow::SetCursor}\label{wxwindowsetcursor} \func{virtual void}{SetCursor}{\param{const wxCursor\&}{cursor}} -Sets the window's cursor. Notice that setting the cursor for this window does -not set it for its children so you'll need to explicitly call SetCursor() for -them too if you need it. +% VZ: the docs are correct, if the code doesn't behave like this, it must be +% changed +Sets the window's cursor. Notice that the window cursor also sets it for the +children of the window implicitly. + +The {\it cursor} may be {\tt wxNullCursor} in which case the window cursor will +be reset back to default. \wxheading{Parameters} @@ -1703,6 +2044,40 @@ them too if you need it. \helpref{::wxSetCursor}{wxsetcursor}, \helpref{wxCursor}{wxcursor} +\membersection{wxWindow::SetConstraints}\label{wxwindowsetconstraints} + +\func{void}{SetConstraints}{\param{wxLayoutConstraints* }{constraints}} + +Sets the window to have the given layout constraints. The window +will then own the object, and will take care of its deletion. +If an existing layout constraints object is already owned by the +window, it will be deleted. + +\wxheading{Parameters} + +\docparam{constraints}{The constraints to set. Pass NULL to disassociate and delete the window's +constraints.} + +\wxheading{Remarks} + +You must call \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} to tell a window to use +the constraints automatically in OnSize; otherwise, you must override OnSize and call Layout() +explicitly. When setting both a wxLayoutConstraints and a \helpref{wxSizer}{wxsizer}, only the +sizer will have effect. + +\membersection{wxWindow::SetDropTarget}\label{wxwindowsetdroptarget} + +\func{void}{SetDropTarget}{\param{wxDropTarget*}{ target}} + +Associates a drop target with this window. + +If the window already has a drop target, it is deleted. + +\wxheading{See also} + +\helpref{wxWindow::GetDropTarget}{wxwindowgetdroptarget}, +\helpref{Drag and drop overview}{wxdndoverview} + \membersection{wxWindow::SetEventHandler}\label{wxwindowseteventhandler} \func{void}{SetEventHandler}{\param{wxEvtHandler* }{handler}} @@ -1733,38 +2108,37 @@ handed to the next one in the chain. \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent},\rtfsp \helpref{wxEvtHandler}{wxevthandler} -\membersection{wxWindow::SetConstraints}\label{wxwindowsetconstraints} - -\func{void}{SetConstraints}{\param{wxLayoutConstraints* }{constraints}} - -Sets the window to have the given layout constraints. The window -will then own the object, and will take care of its deletion. -If an existing layout constraints object is already owned by the -window, it will be deleted. - -\wxheading{Parameters} - -\docparam{constraints}{The constraints to set. Pass NULL to disassociate and delete the window's -constraints.} - -\wxheading{Remarks} - -You must call \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} to tell a window to use -the constraints automatically in OnSize; otherwise, you must -override OnSize and call Layout explicitly. - -\membersection{wxWindow::SetDropTarget}\label{wxwindowsetdroptarget} - -\func{void}{SetDropTarget}{\param{wxDropTarget*}{ target}} - -Associates a drop target with this window. +\membersection{wxWindow::SetExtraStyle}\label{wxwindowsetextrastyle} -If the window already has a drop target, it is deleted. +\func{void}{SetExtraStyle}{\param{long }{exStyle}} -\wxheading{See also} +Sets the extra style bits for the window. The currently defined extra style +bits are: -\helpref{wxWindow::GetDropTarget}{wxwindowgetdroptarget}, -\helpref{Drag and drop overview}{wxdndoverview} +\twocolwidtha{5cm}% +\begin{twocollist}\itemsep=0pt +\twocolitem{\windowstyle{wxWS\_EX\_VALIDATE\_RECURSIVELY}}{TransferDataTo/FromWindow() +and Validate() methods will recursively descend into all children of the +window if it has this style flag set.} +\twocolitem{\windowstyle{wxWS\_EX\_BLOCK\_EVENTS}}{Normally, the command +events are propagared upwards to the window parent recursively until a handler +for them is found. Using this style allows to prevent them from being +propagated beyond this window. Notice that wxDialog has this style on by +default for the reasons explained in the +\helpref{event processing overview}{eventprocessing}.} +\twocolitem{\windowstyle{wxWS\_EX\_TRANSIENT}}{This can be used to prevent a +window from being used as an implicit parent for the dialogs which were +created without a parent. It is useful for the windows which can disappear at +any moment as creating childs of such windows results in fatal problems.} +\twocolitem{\windowstyle{wxFRAME\_EX\_CONTEXTHELP}}{Under Windows, puts a query button on the +caption. When pressed, Windows will go into a context-sensitive help mode and wxWindows will send +a wxEVT\_HELP event if the user clicked on an application window. +This style cannot be used together with wxMAXIMIZE\_BOX or wxMINIMIZE\_BOX, so +you should use the style of +{\tt wxDEFAULT\_FRAME\_STYLE & ~(wxMINIMIZE\_BOX | wxMAXIMIZE\_BOX)} for the +frames having this style (the dialogs don't have minimize nor maximize box by +default)} +\end{twocollist} \membersection{wxWindow::SetFocus}\label{wxwindowsetfocus} @@ -1802,12 +2176,29 @@ The interpretation of foreground colour is open to interpretation according to the window class; it may be the text colour or other colour, or it may not be used at all. +Note that when using this functions under GTK, you will disable the so called "themes", +i.e. the user chosen apperance of windows and controls, including the themes of +their parent windows. + \wxheading{See also} \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp \helpref{wxWindow::SetBackgroundColour}{wxwindowsetbackgroundcolour},\rtfsp \helpref{wxWindow::GetBackgroundColour}{wxwindowgetbackgroundcolour} +\membersection{wxWindow::SetHelpText}\label{wxwindowsethelptext} + +\func{virtual void}{SetHelpText}{\param{const wxString\& }{helpText}} + +Sets the help text to be used as context-sensitive help for this window. + +Note that the text is actually stored by the current \helpref{wxHelpProvider}{wxhelpprovider} implementation, +and not in the window object itself. + +\wxheading{See also} + +\helpref{GetHelpText}{wxwindowgethelptext}, \helpref{wxHelpProvider}{wxhelpprovider} + \membersection{wxWindow::SetId}\label{wxwindowsetid} \func{void}{SetId}{\param{int}{ id}} @@ -1845,31 +2236,11 @@ Sets the window's name. Obsolete - use \helpref{wxDC::SetPalette}{wxdcsetpalette} instead. -\membersection{wxWindow::SetReturnCode}\label{wxwindowsetreturncode} - -\func{void}{SetReturnCode}{\param{int }{retCode}} - -Sets the return code for this window. - -\wxheading{Parameters} - -\docparam{retCode}{The integer return code, usually a control identifier.} - -\wxheading{Remarks} - -A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns -a code to the application. The function \helpref{wxDialog::EndModal}{wxdialogendmodal} calls {\bf SetReturnCode}. - -\wxheading{See also} - -\helpref{wxWindow::GetReturnCode}{wxwindowgetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp -\helpref{wxDialog::EndModal}{wxdialogendmodal} - \membersection{wxWindow::SetScrollbar}\label{wxwindowsetscrollbar} \func{virtual void}{SetScrollbar}{\param{int }{orientation}, \param{int }{position},\rtfsp \param{int }{thumbSize}, \param{int }{range},\rtfsp -\param{const bool }{refresh = TRUE}} +\param{bool }{refresh = {\tt TRUE}}} Sets the scrollbar properties of a built-in scrollbar. @@ -1883,7 +2254,7 @@ Sets the scrollbar properties of a built-in scrollbar. \docparam{range}{The maximum position of the scrollbar.} -\docparam{refresh}{TRUE to redraw the scrollbar, FALSE otherwise.} +\docparam{refresh}{{\tt TRUE} to redraw the scrollbar, {\tt FALSE} otherwise.} \wxheading{Remarks} @@ -1918,7 +2289,7 @@ from your \helpref{wxWindow::OnSize}{wxwindowonsize} event handler function. \begin{comment} \membersection{wxWindow::SetScrollPage}\label{wxwindowsetscrollpage} -\func{virtual void}{SetScrollPage}{\param{int }{orientation}, \param{int }{pageSize}, \param{const bool }{refresh = TRUE}} +\func{virtual void}{SetScrollPage}{\param{int }{orientation}, \param{int }{pageSize}, \param{bool }{refresh = {\tt TRUE}}} Sets the page size of one of the built-in scrollbars. @@ -1928,7 +2299,7 @@ Sets the page size of one of the built-in scrollbars. \docparam{pageSize}{Page size in scroll units.} -\docparam{refresh}{TRUE to redraw the scrollbar, FALSE otherwise.} +\docparam{refresh}{{\tt TRUE} to redraw the scrollbar, {\tt FALSE} otherwise.} \wxheading{Remarks} @@ -1956,7 +2327,7 @@ handling of pages and ranges. \membersection{wxWindow::SetScrollPos}\label{wxwindowsetscrollpos} -\func{virtual void}{SetScrollPos}{\param{int }{orientation}, \param{int }{pos}, \param{const bool }{refresh = TRUE}} +\func{virtual void}{SetScrollPos}{\param{int }{orientation}, \param{int }{pos}, \param{bool }{refresh = {\tt TRUE}}} Sets the position of one of the built-in scrollbars. @@ -1966,7 +2337,7 @@ Sets the position of one of the built-in scrollbars. \docparam{pos}{Position in scroll units.} -\docparam{refresh}{TRUE to redraw the scrollbar, FALSE otherwise.} +\docparam{refresh}{{\tt TRUE} to redraw the scrollbar, {\tt FALSE} otherwise.} \wxheading{Remarks} @@ -1983,7 +2354,7 @@ application to take note of scrollbar attributes and redraw contents accordingly \begin{comment} \membersection{wxWindow::SetScrollRange}\label{wxwindowsetscrollrange} -\func{virtual void}{SetScrollRange}{\param{int }{orientation}, \param{int }{range}, \param{const bool }{refresh = TRUE}} +\func{virtual void}{SetScrollRange}{\param{int }{orientation}, \param{int }{range}, \param{bool }{refresh = {\tt TRUE}}} Sets the range of one of the built-in scrollbars. @@ -1993,7 +2364,7 @@ Sets the range of one of the built-in scrollbars. \docparam{range}{Scroll range.} -\docparam{refresh}{TRUE to redraw the scrollbar, FALSE otherwise.} +\docparam{refresh}{{\tt TRUE} to redraw the scrollbar, {\tt FALSE} otherwise.} \wxheading{Remarks} @@ -2075,9 +2446,9 @@ by wxWindows, or that the current value of the dimension should be used. \pythonnote{In place of a single overloaded method name, wxPython implements the following methods:\par \indented{2cm}{\begin{twocollist} -\twocolitem{\bf{SetDimensions(x, y, width, height, sizeFlags=wxSIZE_AUTO)}}{} -\twocolitem{\bf{SetSize(size)}}{} -\twocolitem{\bf{SetPosition(point)}}{} +\twocolitem{{\bf SetDimensions(x, y, width, height, sizeFlags=wxSIZE\_AUTO)}}{} +\twocolitem{{\bf SetSize(size)}}{} +\twocolitem{{\bf SetPosition(point)}}{} \end{twocollist}} } @@ -2110,6 +2481,27 @@ given bounds. The resizing increments are only significant under Motif or Xt. +\membersection{wxWindow::SetSizer}\label{wxwindowsetsizer} + +\func{void}{SetSizer}{\param{wxSizer* }{sizer}} + +Sets the window to have the given layout sizer. The window +will then own the object, and will take care of its deletion. +If an existing layout constraints object is already owned by the +window, it will be deleted. + +\wxheading{Parameters} + +\docparam{sizer}{The sizer to set. Pass NULL to disassociate and delete the window's +sizer.} + +\wxheading{Remarks} + +You must call \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} to tell a window to use +the sizer automatically in OnSize; otherwise, you must override OnSize and call Layout() +explicitly. When setting both a wxSizer and a \helpref{wxLayoutConstraints}{wxlayoutconstraints}, +only the sizer will have effect. + \membersection{wxWindow::SetTitle}\label{wxwindowsettitle} \func{virtual void}{SetTitle}{\param{const wxString\& }{title}} @@ -2131,27 +2523,83 @@ Sets the window's title. Applicable only to frames and dialogs. Deletes the current validator (if any) and sets the window validator, having called wxValidator::Clone to create a new validator of this type. +\membersection{wxWindow::SetToolTip}\label{wxwindowsettooltip} + +\func{void}{SetToolTip}{\param{const wxString\& }{tip}} + +\func{void}{SetToolTip}{\param{wxToolTip* }{tip}} + +Attach a tooltip to the window. + +See also: \helpref{GetToolTip}{wxwindowgettooltip}, + \helpref{wxToolTip}{wxtooltip} + + +\membersection{wxWindow::GetToolTip}\label{wxwindowgettooltip} + +\constfunc{wxToolTip*}{GetToolTip}{\void} + +Get the associated tooltip or NULL if none. + + + +\membersection{wxWindow::SetWindowStyle}\label{wxwindowsetwindowstyle} + +\func{void}{SetWindowStyle}{\param{long}{ style}} + +Identical to \helpref{SetWindowStyleFlag}{wxwindowsetwindowstyleflag}. + +\membersection{wxWindow::SetWindowStyleFlag}\label{wxwindowsetwindowstyleflag} + +\func{virtual void}{SetWindowStyleFlag}{\param{long}{ style}} + +Sets the style of the window. Please note that some styles cannot be changed +after the window creation and that \helpref{Refresh()}{wxwindowrefresh} might +be called after changing the others for the change to take place immediately. + +See \helpref{Window styles}{windowstyles} for more information about flags. + +\wxheading{See also} + +\helpref{GetWindowStyleFlag}{wxwindowgetwindowstyleflag} + \membersection{wxWindow::Show}\label{wxwindowshow} -\func{virtual bool}{Show}{\param{const bool}{ show}} +\func{virtual bool}{Show}{\param{bool}{ show = {\tt TRUE}}} -Shows or hides the window. +Shows or hides the window. You may need to call \helpref{Raise}{wxwindowraise} +for a top level window if you want to bring it to top, although this is not +needed if Show() is called immediately after the frame creation. \wxheading{Parameters} -\docparam{show}{If TRUE, displays the window and brings it to the front. Otherwise, -hides the window.} +\docparam{show}{If {\tt TRUE} displays the window. Otherwise, hides it.} + +\wxheading{Return value} + +{\tt TRUE} if the window has been shown or hidden or {\tt FALSE} if nothing was +done because it already was in the requested state. \wxheading{See also} \helpref{wxWindow::IsShown}{wxwindowisshown} +\membersection{wxWindow::Thaw}\label{wxwindowthaw} + +\func{virtual void}{Thaw}{\void} + +Reenables window updating after a previous call to +\helpref{Freeze}{wxwindowfreeze}. + \membersection{wxWindow::TransferDataFromWindow}\label{wxwindowtransferdatafromwindow} \func{virtual bool}{TransferDataFromWindow}{\void} Transfers values from child controls to data areas specified by their validators. Returns -FALSE if a transfer failed. +{\tt FALSE} if a transfer failed. + +If the window has {\tt wxWS\_EX\_VALIDATE\_RECURSIVELY} extra style flag set, +the method will also call TransferDataFromWindow() of all child windows. \wxheading{See also} @@ -2164,9 +2612,12 @@ FALSE if a transfer failed. Transfers values to child controls from data areas specified by their validators. +If the window has {\tt wxWS\_EX\_VALIDATE\_RECURSIVELY} extra style flag set, +the method will also call TransferDataToWindow() of all child windows. + \wxheading{Return value} -Returns FALSE if a transfer failed. +Returns {\tt FALSE} if a transfer failed. \wxheading{See also} @@ -2179,9 +2630,12 @@ Returns FALSE if a transfer failed. Validates the current values of the child controls using their validators. +If the window has {\tt wxWS\_EX\_VALIDATE\_RECURSIVELY} extra style flag set, +the method will also call Validate() of all child windows. + \wxheading{Return value} -Returns FALSE if any of the validations failed. +Returns {\tt FALSE} if any of the validations failed. \wxheading{See also}