X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/34636400a0018eba4a1f63dda18cf32e944b959e..8a729bb860cec596f4ce5a59fabeb4404a266e97:/docs/latex/wx/window.tex diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex index 32d23e45ec..9e3be209fa 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,21 +23,29 @@ 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. Windows only. } +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{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{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 @@ -122,27 +137,58 @@ 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::Centre}\label{wxwindowcentre} -\func{virtual void}{Centre}{\param{int}{ direction = wxHORIZONTAL}} +\func{void}{Centre}{\param{int}{ direction = wxHORIZONTAL}} 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. \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 = wxHORIZONTAL}} + +Centres the window. + +\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::CenterOnParent}{wxwindowcenteronparent} + \membersection{wxWindow::Clear}\label{wxwindowclear} \func{void}{Clear}{\void} @@ -519,6 +565,8 @@ Returns the grandparent of a window, or NULL if there isn't one. Returns the platform-specific handle of the physical window. Cast it to an appropriate 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} \constfunc{int}{GetId}{\void} @@ -717,7 +765,7 @@ Returns a pointer to the current validator for the window, or NULL if there is n \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 consructor or {\bf Create} member. {\bf GetWindowStyle} is synonymous. \membersection{wxWindow::InitDialog}\label{wxwindowinitdialog} @@ -741,6 +789,20 @@ 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. + \membersection{wxWindow::IsRetained}\label{wxwindowisretained} \constfunc{virtual bool}{IsRetained}{\void} @@ -769,7 +831,8 @@ window). \func{void}{Layout}{\void} -Invokes the constraint-based layout algorithm for this window. +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. @@ -1363,9 +1426,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} @@ -1381,7 +1444,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} @@ -1464,18 +1527,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.} @@ -1487,7 +1553,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} @@ -1564,6 +1639,19 @@ 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 (e.g. a wxMiniFrame for a +floating toolbar). 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}} @@ -1622,7 +1710,9 @@ Sets the accelerator table for this window. See \helpref{wxAcceleratorTable}{wxa \func{void}{SetAutoLayout}{\param{const 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} @@ -1631,8 +1721,11 @@ from within wxWindow::OnSize functions.} \wxheading{Remarks} -Note that this function is actually disabled for wxWindow and only indirectly -takes affect for children of wxDialog, wxFrame, wxNotebook and wxSplitterWindow. +Note that this function is actually disabled for wxWindow. It has +effect for wxDialog, wxFrame, wxPanel and wxScrolledWindow. Windows +of other types that need to invoke the Layout algorithm should provide +an EVT_SIZE handler and call +\helpref{wxWindow::Layout}{wxwindowlayout} from within it. \wxheading{See also} @@ -1761,8 +1854,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} @@ -2105,6 +2199,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}}