]> git.saurik.com Git - wxWidgets.git/blobdiff - docs/latex/wx/window.tex
added wxRegEx::GetMatchCount (patch 938995)
[wxWidgets.git] / docs / latex / wx / window.tex
index b209a77e080234fcbc296fd7853382ae2c739d88..e9ed4dc0114b142575745061f956c5c3841a811b 100644 (file)
@@ -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}