X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ed93168bf9d23bdc83184039c84d263ed6f87945..23aa4f09d26bd1eb5df7f7170276744a293cbe19:/docs/latex/wx/window.tex diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex index b5bc55cf75..8cb18c8594 100644 --- a/docs/latex/wx/window.tex +++ b/docs/latex/wx/window.tex @@ -21,20 +21,20 @@ window class. \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{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 +70,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,16 +122,24 @@ 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 wxCENTER\_FRAME} flag if you want to center the window +on its parent and not on the screen (actually, this flag is added automatically for all controls +because it makes no sense to center them on the screen)} \wxheading{Remarks} @@ -141,6 +151,28 @@ relative to the panel. \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} @@ -251,9 +283,9 @@ implements the following methods:\par 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}} } @@ -515,7 +547,7 @@ 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. \membersection{wxWindow::GetId}\label{wxwindowgetid} @@ -525,8 +557,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} @@ -556,7 +588,7 @@ implements the following methods:\par \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 +603,7 @@ by name. \membersection{wxWindow::GetName}\label{wxwindowgetname} -\constfunc{virtual wxString\& }{GetName}{\void} +\constfunc{virtual wxString }{GetName}{\void} Returns the window's name. @@ -596,22 +628,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}} @@ -721,11 +737,18 @@ only be called within an \helpref{OnPaint}{wxwindowonpaint} event handler. \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} @@ -764,12 +787,22 @@ 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 for this window. + +See \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} on when +this function gets called automatically using auto layout. \membersection{wxWindow::LoadFromResource}\label{wxwindowloadfromresource} @@ -803,7 +836,8 @@ or frame). \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} @@ -925,7 +959,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} @@ -1057,7 +1093,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. @@ -1424,7 +1462,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} @@ -1456,18 +1494,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.} @@ -1585,7 +1626,7 @@ implements the following methods:\par \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} @@ -1595,14 +1636,13 @@ 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, +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} @@ -1622,6 +1662,11 @@ be called automatically when the window is resized. \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} @@ -1639,12 +1684,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. +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 @@ -1685,10 +1735,9 @@ implements the following methods:\par \func{virtual void}{SetCursor}{\param{const wxCursor\&}{cursor}} -Sets the window's cursor. Notice that setting the cursor for this window also -sets it for all the children of the window unless they have their own cursor -(either explicitly set with the same function, or, in the case of Windows, a -standard one for some of standard controls). +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} @@ -1797,6 +1846,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 @@ -1840,26 +1893,6 @@ 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 @@ -2119,7 +2152,14 @@ Sets the window's title. Applicable only to frames and dialogs. \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}}