X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/954b8ae60391d18b87a604e7919c87c0c6ae208b..26de8b7d32fde0cf396d602dbbdb2e55f5caaeaf:/docs/latex/wx/window.tex diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex index 0929c65b7f..d1f4b13fac 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\_FULLREPAINT\_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 style. Currently only has 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}. @@ -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}.} @@ -120,27 +137,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} @@ -164,9 +236,18 @@ a screen coordinate will be passed out.} \docparam{pt}{The client 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 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 = FALSE}} The purpose of this call is to provide a safer way of destroying a window than using the {\it delete} operator. @@ -187,6 +268,14 @@ destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}. Applies to managed windows (wxFrame and wxDialog classes) only. +{\it Note} that calling Close does not guarantee that the window will be destroyed; but it +provides a way to simulate a manual close of a window, which may or may not be implemented by +destroying the window. The default implementation of wxDialog::OnCloseWindow does not +necessarily delete the dialog, since it will simply simulate an wxID\_CANCEL event which +itself only hides the dialog. + +To guarantee that the window will be destroyed, call \helpref{wxWindow::Destroy}{wxwindowdestroy} instead. + \wxheading{See also} \helpref{Window deletion overview}{windowdeletionoverview},\rtfsp @@ -225,6 +314,23 @@ You can also use these functions programmatically. A convenience macro is define \helpref{wxWindow::ConvertPixelsToDialog}{wxwindowconvertpixelstodialog} +\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} +\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 +units to pixels} +\twocolitem{{\bf wxDLG\_SZE(win, size)}}{Converts a wxSize from dialog +units to pixels} +\end{twocollist}} +} + + \membersection{wxWindow::ConvertPixelsToDialog}\label{wxwindowconvertpixelstodialog} \func{wxPoint}{ConvertPixelsToDialog}{\param{const wxPoint\&}{ pt}} @@ -248,6 +354,15 @@ Dialogs created using Dialog Editor optionally use dialog units. \helpref{wxWindow::ConvertDialogToPixels}{wxwindowconvertdialogtopixels} + +\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} +\end{twocollist}} +} + \membersection{wxWindow::Destroy}\label{wxwindowdestroy} \func{virtual bool}{Destroy}{\void} @@ -272,7 +387,7 @@ Destroys all children of a window. Called automatically by the destructor. \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). @@ -291,7 +406,7 @@ Windows only. \membersection{wxWindow::Enable}\label{wxwindowenable} -\func{virtual void}{Enable}{\param{const bool}{ enable}} +\func{virtual void}{Enable}{\param{bool}{ enable}} Enable or disable the window for user input. @@ -327,11 +442,20 @@ Find a child of this window, by identifier. 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} +\end{twocollist}} +} + \membersection{wxWindow::Fit}\label{wxwindowfit} \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::GetBackgroundColour}\label{wxwindowgetbackgroundcolour} @@ -346,6 +470,17 @@ Returns the background colour of the window. \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp \helpref{wxWindow::OnEraseBackground}{wxwindowonerasebackground} +\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::GetCharHeight} \constfunc{virtual int}{GetCharHeight}{\void} @@ -379,6 +514,14 @@ area which may be drawn on by the programmer, excluding title bar, border etc. \docparam{height}{Receives the client height in pixels.} +\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} +\end{twocollist}} +} + \membersection{wxWindow::GetConstraints}\label{wxwindowgetconstraints} \constfunc{wxLayoutConstraints*}{GetConstraints}{\void} @@ -399,7 +542,7 @@ Returns the associated drop target, which may be NULL. \wxheading{See also} -\helpref{wxWindow::SetDropTarget}{wxwindowsetdroptarget}, +\helpref{wxWindow::SetDropTarget}{wxwindowsetdroptarget}, \helpref{Drag and drop overview}{wxdndoverview} \membersection{wxWindow::GetEventHandler}\label{wxwindowgeteventhandler} @@ -417,6 +560,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} @@ -456,7 +605,9 @@ Returns the grandparent of a window, or NULL if there isn't one. \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. + +\pythonnote{This method will return an integer in wxPython.} \membersection{wxWindow::GetId}\label{wxwindowgetid} @@ -466,8 +617,8 @@ Returns the identifier of the window. \wxheading{Remarks} -Each window has an integer identifier. If the application has not provided one, -an identifier will be generated. +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. \wxheading{See also} @@ -487,9 +638,17 @@ if no parent, relative to the whole display. \docparam{y}{Receives the y position of the window.} +\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}} +} + \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. @@ -504,7 +663,7 @@ by name. \membersection{wxWindow::GetName}\label{wxwindowgetname} -\constfunc{virtual wxString\& }{GetName}{\void} +\constfunc{virtual wxString }{GetName}{\void} Returns the window's name. @@ -529,22 +688,6 @@ Returns the parent of the window, or NULL if there is no parent. Returns the size and position of the window as a \helpref{wxRect}{wxrect} object. -\membersection{wxWindow::GetReturnCode}\label{wxwindowgetreturncode} - -\func{int}{GetReturnCode}{\void} - -Gets the return code for this window. - -\wxheading{Remarks} - -A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns -a code to the application. - -\wxheading{See also} - -\helpref{wxWindow::SetReturnCode}{wxwindowsetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp -\helpref{wxDialog::EndModal}{wxdialogendmodal} - \membersection{wxWindow::GetScrollThumb}\label{wxwindowgetscrollthumb} \func{virtual int}{GetScrollThumb}{\param{int }{orientation}} @@ -589,11 +732,19 @@ This gets the size of the entire window in pixels. \docparam{height}{Receives the window height.} +\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)} +\end{twocollist}} +} + \membersection{wxWindow::GetTextExtent} \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 = FALSE}} Gets the dimensions of the string as it would be drawn on the window with the currently selected font. @@ -614,6 +765,17 @@ window with the currently selected font. \docparam{use16}{If TRUE, {\it string} contains 16-bit characters. The default is 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 +4-tuple, (width, height, descent, externalLeading) } +\end{twocollist}} +} + + \membersection{wxWindow::GetTitle}\label{wxwindowgettitle} \func{virtual wxString}{GetTitle}{\void} @@ -635,11 +797,18 @@ only be called within an \helpref{OnPaint}{wxwindowonpaint} event handler. \helpref{wxRegion}{wxregion}, \helpref{wxRegionIterator}{wxregioniterator}, \helpref{wxWindow::OnPaint}{wxwindowonpaint} -\membersection{wxWindow::GetWindowStyleFlag} +\membersection{wxWindow::GetValidator}\label{wxwindowgetvalidator} + +\constfunc{wxValidator*}{GetValidator}{\void} + +Returns a pointer to the current validator for the window, or NULL if there is none. + +\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} @@ -662,6 +831,28 @@ Returns TRUE if the window is enabled for input, FALSE otherwise. \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 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} @@ -678,12 +869,23 @@ Retained windows are only available on X platforms. Returns TRUE if the window is shown, FALSE if it has been hidden. +\membersection{wxWindow::IsTopLevel}\label{wxwindowistoplevel} + +\constfunc{bool}{IsTopLevel}{\void} + +Returns 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} @@ -714,10 +916,11 @@ 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} @@ -754,6 +957,14 @@ as the call: \helpref{wxWindow::SetSize}{wxwindowsetsize} +\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} +\end{twocollist}} +} + \membersection{wxWindow::OnActivate}\label{wxwindowonactivate} \func{void}{OnActivate}{\param{wxActivateEvent\&}{ event}} @@ -795,7 +1006,7 @@ Note that the ASCII values do not have explicit key codes: they are passed as AS 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 +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. @@ -831,7 +1042,9 @@ Note that the ASCII values do not have explicit key codes: they are passed as AS values. This function is only relevant to top-level windows (frames and dialogs), and under -Windows only. +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} @@ -963,7 +1176,9 @@ Called when the background of the window needs to be erased. \wxheading{Remarks} -This event is only generated under Windows. +This event is only generated under Windows. 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. @@ -990,7 +1205,7 @@ use the EVT\_KEY\_DOWN macro in an event table definition. Your {\bf OnKeyDown} 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 +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. @@ -1019,7 +1234,7 @@ use the EVT\_KEY\_UP macro in an event table definition. Your {\bf OnKeyUp} hand 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 +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. @@ -1202,7 +1417,7 @@ For example: \small{% \begin{verbatim} - void MyWindow::OnPaint(wxPaintEvent& event) + void MyWindow::OnPaint(wxPaintEvent\& event) { wxPaintDC dc(this); @@ -1222,13 +1437,13 @@ Here is an example of using the \helpref{wxRegionIterator}{wxregioniterator} cla {\small% \begin{verbatim} // Called when window needs to be repainted. -void MyWindow::OnPaint(wxPaintEvent& event) +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); + GetViewStart(&vbX,&vbY); int vX,vY,vW,vH; // Dimensions of client area in pixels wxRegionIterator upd(GetUpdateRegion()); // get the update rect list @@ -1261,9 +1476,9 @@ void MyWindow::OnPaint(wxPaintEvent& event) \membersection{wxWindow::OnScroll}\label{wxwindowonscroll} -\func{void}{OnScroll}{\param{wxScrollEvent\& }{event}} +\func{void}{OnScroll}{\param{wxScrollWinEvent\& }{event}} -Called when a scroll event is received from one of the window's built-in scrollbars. +Called when a scroll window event is received from one of the window's built-in scrollbars. \wxheading{Parameters} @@ -1279,7 +1494,7 @@ for horizontal events). \wxheading{See also} -\helpref{wxScrollEvent}{wxscrollevent},\rtfsp +\helpref{wxScrollWinEvent}{wxscrollwinevent},\rtfsp \helpref{Event handling overview}{eventhandlingoverview} \membersection{wxWindow::OnSetFocus}\label{wxwindowonsetfocus} @@ -1330,7 +1545,7 @@ used by the application. \func{void}{OnSysColourChanged}{\param{wxOnSysColourChangedEvent\& }{event}} -Called when the user has changed the system colours. +Called when the user has changed the system colours. Windows only. \wxheading{Parameters} @@ -1362,18 +1577,21 @@ default value is FALSE.} \membersection{wxWindow::PopupMenu}\label{wxwindowpopupmenu} -\func{virtual bool}{PopupMenu}{\param{wxMenu* }{menu}, \param{int }{x}, \param{int }{y}} +\func{bool}{PopupMenu}{\param{wxMenu* }{menu}, \param{const wxPoint\& }{pos}} + +\func{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. +menu item is selected, the corresponding menu event is generated and will be +processed as usually. \wxheading{Parameters} \docparam{menu}{Menu to pop up.} +\docparam{pos}{The position where the menu will appear.} + \docparam{x}{Required x position for the menu to appear.} \docparam{y}{Required y position for the menu to appear.} @@ -1385,7 +1603,16 @@ the commandInt member of the event to check the selected menu identifier. \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. +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::PushEventHandler}\label{wxwindowpusheventhandler} @@ -1427,7 +1654,7 @@ or frame). \membersection{wxWindow::Refresh}\label{wxwindowrefresh} -\func{virtual void}{Refresh}{\param{const bool}{ eraseBackground = TRUE}, \param{const wxRect* }{rect +\func{virtual void}{Refresh}{\param{bool}{ eraseBackground = TRUE}, \param{const wxRect* }{rect = NULL}} Causes a message or event to be generated to repaint the @@ -1462,6 +1689,18 @@ functions so should not be required by the application programmer. \docparam{child}{Child window to remove.} +\membersection{wxWindow::Reparent}\label{wxwindowreparent} + +\func{virtual bool}{Reparent}{\param{wxWindow* }{newParent}} + +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{newParent}{New parent.} + \membersection{wxWindow::ScreenToClient}\label{wxwindowscreentoclient} \constfunc{virtual void}{ScreenToClient}{\param{int* }{x}, \param{int* }{y}} @@ -1478,11 +1717,20 @@ Converts from screen to client window coordinates. \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}} +} + + \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} @@ -1492,14 +1740,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 optimise painting by checking for the invalidated region. This paramter 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} @@ -1509,10 +1755,12 @@ 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 layouting subwindows. \wxheading{Parameters} @@ -1536,12 +1784,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 @@ -1551,6 +1804,79 @@ calling this function. \helpref{wxWindow::Refresh}{wxwindowrefresh},\rtfsp \helpref{wxWindow::OnEraseBackground}{wxwindowonerasebackground} +\membersection{wxWindow::SetClientSize}\label{wxwindowsetclientsize} + +\func{virtual void}{SetClientSize}{\param{int}{ width}, \param{int}{ height}} + +\func{virtual void}{SetClientSize}{\param{const wxSize\&}{ size}} + +This sets the size of the window client area in pixels. Using this function to size a window +tends to be more device-independent than \helpref{wxWindow::SetSize}{wxwindowsetsize}, since the application need not +worry about what dimensions the border or title bar have when trying to fit the window +around panel items, for example. + +\wxheading{Parameters} + +\docparam{width}{The required client area width.} + +\docparam{height}{The required client area height.} + +\docparam{size}{The required client size.} + +\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)}}{} +\end{twocollist}} +} + +\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. + +\wxheading{Parameters} + +\docparam{cursor}{Specifies the cursor that the window should normally display.} + +\wxheading{See also} + +\helpref{::wxSetCursor}{wxsetcursor}, \helpref{wxCursor}{wxcursor} + +\membersection{wxWindow::SetEventHandler}\label{wxwindowseteventhandler} + +\func{void}{SetEventHandler}{\param{wxEvtHandler* }{handler}} + +Sets the event handler for this window. + +\wxheading{Parameters} + +\docparam{handler}{Specifies the handler to be set.} + +\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. + +It is usually better to use \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler} since +this sets up a chain of event handlers, where an event not handled by one event handler is +handed to the next one in the chain. + +\wxheading{See also} + +\helpref{wxWindow::GetEventHandler}{wxwindowgeteventhandler},\rtfsp +\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp +\helpref{wxWindow::PopEventHandler}{wxwindowpusheventhandler},\rtfsp +\helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent},\rtfsp +\helpref{wxEvtHandler}{wxevthandler} + \membersection{wxWindow::SetConstraints}\label{wxwindowsetconstraints} \func{void}{SetConstraints}{\param{wxLayoutConstraints* }{constraints}} @@ -1568,8 +1894,9 @@ 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. +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} @@ -1581,9 +1908,23 @@ If the window already has a drop target, it is deleted. \wxheading{See also} -\helpref{wxWindow::GetDropTarget}{wxwindowgetdroptarget}, +\helpref{wxWindow::GetDropTarget}{wxwindowgetdroptarget}, \helpref{Drag and drop overview}{wxdndoverview} +\membersection{wxWindow::SetExtraStyle}\label{wxwindowsetextrastyle} + +\func{void}{SetExtraStyle}{\param{long }{exStyle}} + +Sets the extra style bits for the window. The currently defined extra style +bits are: + +\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.} +\end{twocollist} + \membersection{wxWindow::SetFocus}\label{wxwindowsetfocus} \func{virtual void}{SetFocus}{\void} @@ -1620,6 +1961,10 @@ 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 @@ -1657,31 +2002,17 @@ Sets the window's name. \helpref{wxWindow::GetName}{wxwindowgetname} -\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}. +\membersection{wxWindow::SetPalette}\label{wxwindowsetpalette} -\wxheading{See also} +\func{virtual void}{SetPalette}{\param{wxPalette* }{palette}} -\helpref{wxWindow::GetReturnCode}{wxwindowgetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp -\helpref{wxDialog::EndModal}{wxdialogendmodal} +Obsolete - use \helpref{wxDC::SetPalette}{wxdcsetpalette} instead. \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 = TRUE}} Sets the scrollbar properties of a built-in scrollbar. @@ -1730,7 +2061,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 = TRUE}} Sets the page size of one of the built-in scrollbars. @@ -1768,7 +2099,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 = TRUE}} Sets the position of one of the built-in scrollbars. @@ -1795,7 +2126,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 = TRUE}} Sets the range of one of the built-in scrollbars. @@ -1884,6 +2215,15 @@ by wxWindows, or that the current value of the dimension should be used. \helpref{wxWindow::Move}{wxwindowmove} +\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)}}{} +\end{twocollist}} +} + \membersection{wxWindow::SetSizeHints}\label{wxwindowsetsizehints} \func{virtual void}{SetSizeHints}{\param{int}{ minW=-1}, \param{int}{ minH=-1}, \param{int}{ maxW=-1}, \param{int}{ maxH=-1}, @@ -1913,98 +2253,71 @@ given bounds. The resizing increments are only significant under Motif or Xt. -\membersection{wxWindow::SetClientSize} - -\func{virtual void}{SetClientSize}{\param{int}{ width}, \param{int}{ height}} +\membersection{wxWindow::SetSizer}\label{wxwindowsetsizer} -\func{virtual void}{SetClientSize}{\param{const wxSize\&}{ size}} +\func{void}{SetSizer}{\param{wxSizer* }{sizer}} -This sets the size of the window client area in pixels. Using this function to size a window -tends to be more device-independent than \helpref{wxWindow::SetSize}{wxwindowsetsize}, since the application need not -worry about what dimensions the border or title bar have when trying to fit the window -around panel items, for example. +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{width}{The required client area width.} - -\docparam{height}{The required client area height.} - -\docparam{size}{The required client size.} - -\membersection{wxWindow::SetPalette} +\docparam{sizer}{The sizer to set. Pass NULL to disassociate and delete the window's +sizer.} -\func{virtual void}{SetPalette}{\param{wxPalette* }{palette}} +\wxheading{Remarks} -Obsolete - use \helpref{wxDC::SetPalette}{wxdcsetpalette} instead. +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::SetCursor}\label{wxwindowsetcursor} +\membersection{wxWindow::SetTitle}\label{wxwindowsettitle} -\func{virtual void}{SetCursor}{\param{const wxCursor\&}{cursor}} +\func{virtual void}{SetTitle}{\param{const wxString\& }{title}} -Sets the window's cursor. +Sets the window's title. Applicable only to frames and dialogs. \wxheading{Parameters} -\docparam{cursor}{Specifies the cursor that the window should normally display.} - -\wxheading{Remarks} - -Under Windows, you sometimes need to call ::wxSetCursor in addition to this -function if you want the cursor to change immediately, because under Windows, -wxWindows only sets the global cursor when it detects mouse movement. +\docparam{title}{The window's title.} \wxheading{See also} -\helpref{::wxSetCursor}{wxsetcursor}, \helpref{wxCursor}{wxcursor} - -\membersection{wxWindow::SetEventHandler}\label{wxwindowseteventhandler} - -\func{void}{SetEventHandler}{\param{wxEvtHandler* }{handler}} - -Sets the event handler for this window. - -\wxheading{Parameters} - -\docparam{handler}{Specifies the handler to be set.} +\helpref{wxWindow::GetTitle}{wxwindowgettitle} -\wxheading{Remarks} +\membersection{wxWindow::SetValidator}\label{wxwindowsetvalidator} -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. +\func{virtual void}{SetValidator}{\param{const wxValidator\&}{ validator}} -It is usually better to use \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler} since -this sets up a chain of event handlers, where an event not handled by one event handler is -handed to the next one in the chain. +Deletes the current validator (if any) and sets the window validator, having called wxValidator::Clone to +create a new validator of this type. -\wxheading{See also} +\membersection{wxWindow::SetWindowStyle}\label{wxwindowsetwindowstyle} -\helpref{wxWindow::GetEventHandler}{wxwindowgeteventhandler},\rtfsp -\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp -\helpref{wxWindow::PopEventHandler}{wxwindowpusheventhandler},\rtfsp -\helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent},\rtfsp -\helpref{wxEvtHandler}{wxevthandler} +\func{void}{SetWindowStyle}{\param{long}{ style}} -\membersection{wxWindow::SetTitle}\label{wxwindowsettitle} +Identical to \helpref{SetWindowStyleFlag}{wxwindowsetwindowstyleflag}. -\func{virtual void}{SetTitle}{\param{const wxString\& }{title}} +\membersection{wxWindow::SetWindowStyleFlag}\label{wxwindowsetwindowstyleflag} -Sets the window's title. Applicable only to frames and dialogs. +\func{virtual void}{SetWindowStyleFlag}{\param{long}{ style}} -\wxheading{Parameters} +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. -\docparam{title}{The window's title.} +See \helpref{Windowstyles}{windowstyles} for more information about flags. \wxheading{See also} -\helpref{wxWindow::GetTitle}{wxwindowgettitle} +\helpref{GetWindowStyleFlag}{wxwindowgetwindowstyleflag} -\membersection{wxWindow::Show} +\membersection{wxWindow::Show}\label{wxwindowshow} -\func{virtual bool}{Show}{\param{const bool}{ show}} +\func{virtual bool}{Show}{\param{bool}{ show}} Shows or hides the window. @@ -2024,6 +2337,9 @@ hides the window.} Transfers values from child controls to data areas specified by their validators. Returns 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} \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow},\rtfsp @@ -2035,6 +2351,9 @@ 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. @@ -2050,6 +2369,9 @@ 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.