\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}
\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. Windows only. }
\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{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}.
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}.}
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}
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
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}}
}
\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}
\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}
\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.
\membersection{wxWindow::GetName}\label{wxwindowgetname}
-\constfunc{virtual wxString\& }{GetName}{\void}
+\constfunc{virtual wxString }{GetName}{\void}
Returns the window's name.
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}}
\helpref{wxRegion}{wxregion}, \helpref{wxRegionIterator}{wxregioniterator}, \helpref{wxWindow::OnPaint}{wxwindowonpaint}
+\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}
\constfunc{long}{GetWindowStyleFlag}{\void}
Gets the window style that was passed to the consructor or {\bf Create} member.
+{\bf GetWindowStyle} is synonymous.
\membersection{wxWindow::InitDialog}\label{wxwindowinitdialog}
\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}
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}
\func{virtual void}{MakeModal}{\param{const 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}
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}
\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.
\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}
\wxheading{See also}
-\helpref{wxScrollEvent}{wxscrollevent},\rtfsp
+\helpref{wxScrollWinEvent}{wxscrollwinevent},\rtfsp
\helpref{Event handling overview}{eventhandlingoverview}
\membersection{wxWindow::OnSetFocus}\label{wxwindowonsetfocus}
\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}
\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.}
\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}
\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}}
\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}
\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,
+instead the regions to be invalidated are calculated automatically. }
\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}
\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}
\docparam{autoLayout}{Set this to TRUE if you wish the Layout function to be called
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.
+
\wxheading{See also}
\helpref{wxWindow::SetConstraints}{wxwindowsetconstraints}
\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.
+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::GetBackgroundColour}{wxwindowgetbackgroundcolour},\rtfsp
\func{virtual void}{SetCursor}{\param{const wxCursor\&}{cursor}}
-Sets the window's 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.}
-\begin{comment}
-\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.
-\end{comment
-
\wxheading{See also}
\helpref{::wxSetCursor}{wxsetcursor}, \helpref{wxCursor}{wxcursor}
\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}
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
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
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}}
\helpref{wxWindow::GetTitle}{wxwindowgettitle}
-\membersection{wxWindow::Show}
+\membersection{wxWindow::SetValidator}\label{wxwindowsetvalidator}
+
+\func{virtual void}{SetValidator}{\param{const wxValidator\&}{ validator}}
+
+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::Show}\label{wxwindowshow}
\func{virtual bool}{Show}{\param{const bool}{ show}}
projects / wxWidgets.git / blobdiff