X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/c0d26c0f1829cfa09f68e7729a5d9290e5031759..86b79b93fbbb0c2e90e6595f7fea0f979b80881c:/docs/latex/wx/window.tex?ds=sidebyside diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex index b209a77e08..e9ed4dc011 100644 --- a/docs/latex/wx/window.tex +++ b/docs/latex/wx/window.tex @@ -21,7 +21,6 @@ class, wxWindows uses a unique protected virtual \texttt{DoGetXXX()} method and all \texttt{GetXXX()} ones are forwarded to it, so overriding the former changes the behaviour of the latter. - \wxheading{Derived from} \helpref{wxEvtHandler}{wxevthandler}\\ @@ -48,10 +47,14 @@ for this style. } \twocolitem{\windowstyle{wxTRANSPARENT\_WINDOW}}{The window is transparent, that is, it will not receive paint events. 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{wxWANTS\_CHARS}}{Use this to indicate that +the window wants to get all char/key events for all keys - even for +keys like TAB or ENTER which are usually used for dialog navigation +and which wouldn't be generated without this style. If you need to +use this style in order to get the arrows or etc., but would still like to have +normal keyboard navigation take place, you should create and send a +wxNavigationKeyEvent in response to the key events for Tab and +Shift-Tab.} \twocolitem{\windowstyle{wxNO\_FULL\_REPAINT\_ON\_RESIZE}}{Disables repainting the window completely when its size is changed - you will have to repaint the new window area manually if you use this style. Currently only has an effect for @@ -370,7 +373,6 @@ and then divided by 8. \wxheading{Remarks} Dialog units are used for maintaining a dialog's proportions even if the font changes. -Dialogs created using Dialog Editor optionally use dialog units. You can also use these functions programmatically. A convenience macro is defined: @@ -419,15 +421,12 @@ character height. \wxheading{Remarks} Dialog units are used for maintaining a dialog's proportions even if the font changes. -Dialogs created using Dialog Editor optionally use dialog units. \wxheading{See also} \helpref{wxWindow::ConvertDialogToPixels}{wxwindowconvertdialogtopixels} - -\pythonnote{In place of a single overloaded method name, wxPython -implements the following methods:\par +\pythonnote{In place of a single overloaded method name, wxPythonimplements 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} @@ -497,6 +496,7 @@ void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event) \end{verbatim} + \membersection{wxWindow::DragAcceptFiles}\label{wxwindowdragacceptfiles} \func{virtual void}{DragAcceptFiles}{\param{bool}{ accept}} @@ -551,6 +551,7 @@ Note that this is a static function, so it can be called without needing a wxWin \helpref{wxWindow::SetFocus}{wxwindowsetfocus} + \membersection{wxWindow::FindWindow}\label{wxwindowfindwindow} \func{wxWindow*}{FindWindow}{\param{long}{ id}} @@ -650,7 +651,8 @@ subwindows. Freezes the window or, in other words, prevents any updates from taking place on screen, the window is not redrawn at all. \helpref{Thaw}{wxwindowthaw} must -be called to reenable window redrawing. +be called to reenable window redrawing. Calls to these two functions may be +nested. This method is useful for visual appearance optimization (for example, it is a good idea to use it before inserting large amount of text into a @@ -665,6 +667,7 @@ directive. Gets the accelerator table for this window. See \helpref{wxAcceleratorTable}{wxacceleratortable}. + \membersection{wxWindow::GetAccessible}\label{wxwindowgetaccessible} \func{wxAccessibile*}{GetAccessible}{\void} @@ -752,12 +755,43 @@ Returns the average character width for this window. Returns a reference to the list of the window's children. +\membersection{wxControl::GetClassDefaultAttributes}\label{wxwindowgetclassdefaultattributes} + +\func{static wxVisualAttributes}{GetClassDefaultAttributes}{\param{wxWindowVariant}{ variant = \texttt{wxWINDOW\_VARIANT\_NORMAL}}} + +Returns the default font and colours which are used by the control. This is +useful if you want to use the same font or colour in your own control as in a +standard control -- which is a much better idea than hard coding specific +colours or fonts which might look completely out of place on the users +system, especially if it uses themes. + +The \arg{variant} parameter is only relevant under Mac currently and is +ignore under other platforms. Under Mac, it will change the size of the +returned font. See \helpref{wxWindow::SetWindowVariant}{wxwindowsetwindowvariant} +for more about this. + +This static method is ``overridden'' in many derived classes and so calling, +for example, \helpref{wxButton}{wxbutton}::GetClassDefaultAttributes() will typically +return the values appropriate for a button which will be normally different +from those returned by, say, \helpref{wxListCtrl}{wxlistctrl}::GetClassDefaultAttributes(). + +The \texttt{wxVisualAttributes} structure has at least the fields +\texttt{font}, \texttt{colFg} and \texttt{colBg}. All of them may be invalid +if it was not possible to determine the default control appearance or, +especially for the background colour, if the field doesn't make sense as is +the case for \texttt{colBg} for the controls with themed background. + +\wxheading{See also} + +\helpref{InheritAttributes}{wxwindowinheritattributes} + + \membersection{wxWindow::GetClientSize}\label{wxwindowgetclientsize} \constfunc{void}{GetClientSize}{\param{int* }{width}, \param{int* }{height}} \perlnote{In wxPerl this method takes no parameter and returns -a 2-element list {\tt ( width, height )}.} +a 2-element list {\tt (width, height)}.} \constfunc{wxSize}{GetClientSize}{\void} @@ -781,10 +815,11 @@ implements the following methods:\par \wxheading{See also} -\helpref{GetSize}{wxwindowgetsize} +\helpref{GetSize}{wxwindowgetsize},\rtfsp \helpref{GetVirtualSize}{wxwindowgetvirtualsize} + \membersection{wxWindow::GetConstraints}\label{wxwindowgetconstraints} \constfunc{wxLayoutConstraints*}{GetConstraints}{\void} @@ -799,6 +834,7 @@ Returns a pointer to the window's layout constraints, or NULL if there are none. Return the sizer that this window is a member of, if any, otherwise {\tt NULL}. + \membersection{wxWindow::GetCursor}\label{wxwindowgetcursor} \constfunc{const wxCursor\&}{GetCursor}{\void} @@ -809,6 +845,26 @@ Return the cursor associated with this window. \helpref{wxWindow::SetCursor}{wxwindowsetcursor} + +\membersection{wxControl::GetDefaultAttributes}\label{wxwindowgetdefaultattributes} + +\constfunc{virtual wxVisualAttributes}{GetDefaultAttributes}{\void} + +Currently this is the same as calling +\helpref{GetClassDefaultAttributes}{wxwindowgetclassdefaultattributes}(\helpref{GetWindowVariant}{wxwindowgetwindowvariant}()). + +One advantage of using this function compared to the static version is that +the call is automatically dispatched to the correct class (as usual with +virtual functions) and you don't have to specify the class name explicitly. + +The other one is that in the future this function could return different +results, for example it might return a different font for an ``Ok'' button +than for a generic button if the users GUI is configured to show such buttons +in bold font. Of course, the down side is that it is impossible to call this +function without actually having an object to apply it to whereas the static +version can be used without having to create an object first. + + \membersection{wxWindow::GetDropTarget}\label{wxwindowgetdroptarget} \constfunc{wxDropTarget*}{GetDropTarget}{\void} @@ -1108,7 +1164,6 @@ window with the currently selected font. \docparam{use16}{If {\tt true}, {\it string} contains 16-bit characters. The default is {\tt false}.} - \pythonnote{In place of a single overloaded method name, wxPython implements the following methods:\par \indented{2cm}{\begin{twocollist} @@ -1187,6 +1242,14 @@ 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::GetWindowVariant}\label{wxwindowgetwindowvariant} + +\constfunc{wxWindowVariant}{GetWindowVariant}{\void} + +Returns the value previous passed to +\helpref{wxWindow::SetWindowVariant}{wxwindowsetwindowvariant}. + + \membersection{wxWindow::HasCapture}\label{wxwindowhascapture} \constfunc{virtual bool}{HasCapture}{\void} @@ -1207,6 +1270,35 @@ Returns true if this window has the current mouse capture. Equivalent to calling \helpref{Show}{wxwindowshow}({\tt false}). +\membersection{wxWindow::InheritAttributes}\label{wxwindowinheritattributes} + +\func{void}{InheritAttributes}{\void} + +This function is (or should be, in case of custom controls) called during +window creation to intelligently set up the window visual attributes, that is +the font and the foreground and background colours. + +By ``intelligently'' the following is meant: by default, all windows use their +own \helpref{default}{wxwindowgetclassdefaultattributes} attributes. However +if some of the parents attributes are explicitly (that is, using +\helpref{SetFont}{wxwindowsetfont} and not +\helpref{SetDefaultFont}{wxwindowsetdefaultfont}) changed \emph{and} if the +corresponding attribute hadn't been explicitly set for this window itself, +then this window takes the same value as used by the parent. In addition, if +the window overrides \helpref{ShouldInheritColours}{wxwindowshouldinheritcolours} +to return \false, the colours will not be changed no matter what and only the +font might. + +This rather complicated logic is necessary in order to accomodate the +different usage scenarius. The most common one is when all default attributes +are used and in this case, nothing should be inherited as in modern GUIs +different controls use different fonts (and colours) than their siblings so +they can't inherit the same value from the parent. However it was also deemed +desirable to allow to simply change the attributes of all children at once by +just changing the font or colour of their common parent, hence in this case we +do inherit the parents attributes. + + \membersection{wxWindow::InitDialog}\label{wxwindowinitdialog} \func{void}{InitDialog}{\void} @@ -1996,7 +2088,7 @@ be treated as damaged.} \membersection{wxWindow::RefreshRect}\label{wxwindowrefreshrect} -\func{void}{Refresh}{\param{const wxRect\& }{rect}} +\func{void}{RefreshRect}{\param{const wxRect\& }{rect}} Redraws the contents of the given rectangle: the area inside it will be repainted. @@ -2241,6 +2333,10 @@ from within wxWindow::OnSize functions.} Sets the background colour of the window. +Please see \helpref{InheritAttributes}{wxwindowinheritattributes} for +explanation of the difference between this method and +\helpref{SetDefaultBackgroundColour}{wxwindowsetdefaultbackgroundcolour}. + \wxheading{Parameters} \docparam{colour}{The colour to be used as the background colour.} @@ -2356,6 +2452,45 @@ explicitly. When setting both a wxLayoutConstraints and a \helpref{wxSizer}{wxsi sizer will have effect. +\membersection{wxWindow::SetDefaultBackgroundColour}\label{wxwindowsetdefaultbackgroundcolour} + +\func{void}{SetDefaultBackgroundColour}{\param{const wxColour\& }{colour}} + +Sets the background colour of the window but prevents it from being inherited +by the children of this window. + +\wxheading{See also} + +\helpref{SetBackgroundColour}{wxwindowsetbackgroundcolour},\rtfsp +\helpref{InheritAttributes}{wxwindowinheritattributes} + + +\membersection{wxWindow::SetDefaultFont}\label{wxwindowsetdefaultfont} + +\func{void}{SetDefaultBackgroundColour}{\param{const wxColour\& }{colour}} + +Sets the font of the window but prevents it from being inherited by the +children of this window. + +\wxheading{See also} + +\helpref{SetFont}{wxwindowsetfont},\rtfsp +\helpref{InheritAttributes}{wxwindowinheritattributes} + + +\membersection{wxWindow::SetDefaultForegroundColour}\label{wxwindowsetdefaultforegroundcolour} + +\func{void}{SetDefaultForegroundColour}{\param{const wxColour\& }{colour}} + +Sets the foreground colour of the window but prevents it from being inherited +by the children of this window. + +\wxheading{See also} + +\helpref{SetForegroundColour}{wxwindowsetforegroundcolour},\rtfsp +\helpref{InheritAttributes}{wxwindowinheritattributes} + + \membersection{wxWindow::SetDropTarget}\label{wxwindowsetdroptarget} \func{void}{SetDropTarget}{\param{wxDropTarget*}{ target}} @@ -2370,6 +2505,7 @@ If the window already has a drop target, it is deleted. \helpref{Drag and drop overview}{wxdndoverview} + \membersection{wxWindow::SetEventHandler}\label{wxwindowseteventhandler} \func{void}{SetEventHandler}{\param{wxEvtHandler* }{handler}} @@ -2463,7 +2599,11 @@ can be overridden to do something in addition to this in the derived classes. \func{void}{SetFont}{\param{const wxFont\& }{font}} -Sets the font for this window. +Sets the font for this window. This function should not be called for the +parent window if you don't want its font to be inherited by its children, +use \helpref{SetDefaultFont}{wxwindowsetdefaultfont} instead in this case and +see \helpref{InheritAttributes}{wxwindowinheritattributes} for more +explanations. \wxheading{Parameters} @@ -2471,7 +2611,8 @@ Sets the font for this window. \wxheading{See also} -\helpref{wxWindow::GetFont}{wxwindowgetfont} +\helpref{wxWindow::GetFont}{wxwindowgetfont},\\ +\helpref{InheritAttributes}{wxwindowinheritattributes} \membersection{wxWindow::SetForegroundColour}\label{wxwindowsetforegroundcolour} @@ -2480,6 +2621,10 @@ Sets the font for this window. Sets the foreground colour of the window. +Please see \helpref{InheritAttributes}{wxwindowinheritattributes} for +explanation of the difference between this method and +\helpref{SetDefaultForegroundColour}{wxwindowsetdefaultforegroundcolour}. + \wxheading{Parameters} \docparam{colour}{The colour to be used as the foreground colour.} @@ -2498,7 +2643,8 @@ their parent windows. \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp \helpref{wxWindow::SetBackgroundColour}{wxwindowsetbackgroundcolour},\rtfsp -\helpref{wxWindow::GetBackgroundColour}{wxwindowgetbackgroundcolour} +\helpref{wxWindow::GetBackgroundColour}{wxwindowgetbackgroundcolour},\rtfsp +\helpref{wxWindow::ShouldInheritColours}{wxwindowshouldinheritcolours} \membersection{wxWindow::SetHelpText}\label{wxwindowsethelptext} @@ -2533,6 +2679,7 @@ on creation and should not be modified subsequently. \helpref{Window identifiers}{windowids} + \membersection{wxWindow::SetName}\label{wxwindowsetname} \func{virtual void}{SetName}{\param{const wxString\& }{name}} @@ -2607,6 +2754,7 @@ from your \helpref{wxSizeEvent}{wxsizeevent} handler function. \begin{comment} + \membersection{wxWindow::SetScrollPage}\label{wxwindowsetscrollpage} \func{virtual void}{SetScrollPage}{\param{int }{orientation}, \param{int }{pageSize}, \param{bool }{refresh = {\tt true}}} @@ -2674,6 +2822,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{bool }{refresh = {\tt true}}} @@ -2781,6 +2930,10 @@ implements the following methods:\par \func{virtual void}{SetSizeHints}{\param{int}{ minW=-1}, \param{int}{ minH=-1}, \param{int}{ maxW=-1}, \param{int}{ maxH=-1}, \param{int}{ incW=-1}, \param{int}{ incH=-1}} +\func{void}{SetSizeHints}{\param{const wxSize\&}{ minSize}, +\param{const wxSize\&}{ maxSize=wxDefaultSize}, \param{const wxSize\&}{ incSize=wxDefaultSize}} + + Allows specification of minimum and maximum window sizes, and window size increments. If a pair of values is not set (or set to -1), the default values will be used. @@ -2798,6 +2951,12 @@ If a pair of values is not set (or set to -1), the default values will be used. \docparam{incH}{Specifies the increment for sizing the height (Motif/Xt only).} +\docparam{minSize}{Minimum size.} + +\docparam{maxSize}{Maximum size.} + +\docparam{incSize}{Increment size (Motif/Xt only).} + \wxheading{Remarks} If this function is called, the user will not be able to size the window outside the @@ -2909,6 +3068,10 @@ Sets the virtual size of the window in pixels. \func{virtual void}{SetVirtualSizeHints}{\param{int}{ minW},\param{int}{ minH}, \param{int}{ maxW=-1}, \param{int}{ maxH=-1}} +\func{void}{SetVirtualSizeHints}{\param{const wxSize\&}{ minSize=wxDefaultSize}, +\param{const wxSize\&}{ maxSize=wxDefaultSize}} + + Allows specification of minimum and maximum virtual window sizes. If a pair of values is not set (or set to -1), the default values will be used. @@ -2923,6 +3086,10 @@ will be used. \docparam{maxH}{Specifies the maximum height allowable.} +\docparam{minSize}{Minimum size.} + +\docparam{maxSize}{Maximum size.} + \wxheading{Remarks} If this function is called, the user will not be able to size the virtual area @@ -2951,6 +3118,40 @@ See \helpref{Window styles}{windowstyles} for more information about flags. \helpref{GetWindowStyleFlag}{wxwindowgetwindowstyleflag} +\membersection{wxWindow::SetWindowVariant}\label{wxwindowsetwindowvariant} + +\func{void}{SetWindowVariant}{\param{wxWindowVariant}{variant}} + +This function can be called under all platforms but only does anything under +Mac OS X 10.3+ currently. Under this system, each of the standard control can +exist in several sizes which correpond to the elements of wxWindowVariant +enum: +\begin{verbatim} +enum wxWindowVariant +{ + wxWINDOW_VARIANT_NORMAL, // Normal size + wxWINDOW_VARIANT_SMALL, // Smaller size (about 25 % smaller than normal ) + wxWINDOW_VARIANT_MINI, // Mini size (about 33 % smaller than normal ) + wxWINDOW_VARIANT_LARGE, // Large size (about 25 % larger than normal ) +}; +\end{verbatim} + +By default the controls use the normal size, of course, but this function can +be used to change this. + + +\membersection{wxWindow::ShouldInheritColours}\label{wxwindowshouldinheritcolours} + +\func{virtual bool}{ShouldInheritColours}{\void} + +Return \true from here to allow the colours of this window to be changed by +\helpref{InheritAttributes}{wxwindowinheritattributes}, returning \false +forbids inheriting them from the parent window. + +The base class version returns \false, but this method is overridden in +\helpref{wxControl}{wxcontrol} where it returns \true. + + \membersection{wxWindow::Show}\label{wxwindowshow} \func{virtual bool}{Show}{\param{bool}{ show = {\tt true}}} @@ -2973,12 +3174,14 @@ done because it already was in the requested state. \helpref{wxWindow::IsShown}{wxwindowisshown} + \membersection{wxWindow::Thaw}\label{wxwindowthaw} \func{virtual void}{Thaw}{\void} -Reenables window updating after a previous call to -\helpref{Freeze}{wxwindowfreeze}. +Reenables window updating after a previous call to +\helpref{Freeze}{wxwindowfreeze}. To really thaw the control, it must be called +exactly the same number of times as \helpref{Freeze}{wxwindowfreeze}. \membersection{wxWindow::TransferDataFromWindow}\label{wxwindowtransferdatafromwindow}