+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name: brush.tex
+%% Purpose: wxPen docs
+%% Author:
+%% Modified by:
+%% Created:
+%% RCS-ID: $Id$
+%% Copyright: (c) wxWidgets
+%% License: wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
\section{\class{wxBrush}}\label{wxbrush}
A brush is a drawing tool for filling in areas. It is used for painting
\helpref{wxGDIObject}{wxgdiobject}\\
\helpref{wxObject}{wxobject}
+\wxheading{Include files}
+
+<wx/brush.h>
+
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+
+\wxheading{Predefined objects}
+
+Objects:
+
+{\bf wxNullBrush}
+
+Pointers:
+
+{\bf wxBLUE\_BRUSH\\
+wxGREEN\_BRUSH\\
+wxWHITE\_BRUSH\\
+wxBLACK\_BRUSH\\
+wxGREY\_BRUSH\\
+wxMEDIUM\_GREY\_BRUSH\\
+wxLIGHT\_GREY\_BRUSH\\
+wxTRANSPARENT\_BRUSH\\
+wxCYAN\_BRUSH\\
+wxRED\_BRUSH}
+
\wxheading{Remarks}
-On a monochrome display, wxWindows shows
+On a monochrome display, wxWidgets shows
all brushes as white unless the colour is really black.
Do not initialize objects on the stack before the program commences,
list of brushes {\bf wxTheBrushList}, and calling the member function
\rtfsp{\bf FindOrCreateBrush}.
-wxBrush uses a reference counting system, so assignments between brushes are very
-cheap. You can therefore use actual wxBrush objects instead of pointers without
-efficiency problems. Bear in mind, though, that changing a brush's properties may
-affect another brush which has been involved in an assignment with the first brush,
-because of the way internal brush data is shared.
-
-TODO: an overview for wxBrush.
+This class uses \helpref{reference counting and copy-on-write}{trefcount}
+internally so that assignments between two instances of this class are very
+cheap. You can therefore use actual objects instead of pointers without
+efficiency problems. If an instance of this class is changed it will create
+its own data internally so that other instances, which previously shared the
+data using the reference counting, are not affected.
+%TODO: an overview for wxBrush.
\wxheading{See also}
\helpref{wxBrushList}{wxbrushlist}, \helpref{wxDC}{wxdc}, \helpref{wxDC::SetBrush}{wxdcsetbrush}
\latexignore{\rtfignore{\wxheading{Members}}}
-\membersection{wxBrush::wxBrush}
+
+\membersection{wxBrush::wxBrush}\label{wxbrushctor}
\func{}{wxBrush}{\void}
-Default constructor. The brush will be uninitialised, and \helpref{wxBrush::Ok}{wxbrushok} will
-return FALSE.
+Default constructor. The brush will be uninitialised, and \helpref{wxBrush:IsOk}{wxbrushisok} will
+return false.
-\func{}{wxBrush}{\param{const wxColour\&}{ colour}, \param{int}{ style}}
+\func{}{wxBrush}{\param{const wxColour\&}{ colour}, \param{int}{ style = {\tt wxSOLID}}}
Constructs a brush from a colour object and style.
\func{}{wxBrush}{\param{const wxBrush\&}{ brush}}
-Copy constructor. This uses reference counting so is a cheap operation.
+Copy constructor, uses \helpref{reference counting}{trefcount}.
\wxheading{Parameters}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxTRANSPARENT}}{Transparent (no fill).}
\twocolitem{{\bf wxSOLID}}{Solid.}
+\twocolitem{{\bf wxSTIPPLE}}{Uses a bitmap as a stipple.}
\twocolitem{{\bf wxBDIAGONAL\_HATCH}}{Backward diagonal hatch.}
\twocolitem{{\bf wxCROSSDIAG\_HATCH}}{Cross-diagonal hatch.}
\twocolitem{{\bf wxFDIAGONAL\_HATCH}}{Forward diagonal hatch.}
\helpref{wxBrushList}{wxbrushlist}, \helpref{wxColour}{wxcolour}, \helpref{wxColourDatabase}{wxcolourdatabase}
-\membersection{wxBrush::\destruct{wxBrush}}
-\func{void}{\destruct{wxBrush}}{\void}
+\membersection{wxBrush::\destruct{wxBrush}}\label{wxbrushdtor}
+
+\func{}{\destruct{wxBrush}}{\void}
Destructor.
+See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
\wxheading{Remarks}
-The destructor may not delete the underlying brush object of the native windowing
-system, since wxBrush uses a reference counting system for efficiency.
-
Although all remaining brushes are deleted when the application exits,
the application should try to clean up all brushes itself. This is because
-wxWindows cannot know if a pointer to the brush object is stored in an
+wxWidgets cannot know if a pointer to the brush object is stored in an
application data structure, and there is a risk of double deletion.
+
\membersection{wxBrush::GetColour}\label{wxbrushgetcolour}
\constfunc{wxColour\&}{GetColour}{\void}
\helpref{wxBrush::SetColour}{wxbrushsetcolour}
+
\membersection{wxBrush::GetStipple}\label{wxbrushgetstipple}
\constfunc{wxBitmap *}{GetStipple}{\void}
Gets a pointer to the stipple bitmap. If the brush does not have a wxSTIPPLE style,
-this bitmap may be non-NULL but uninitialised (\helpref{wxBitmap::Ok}{wxbitmapok} returns FALSE).
+this bitmap may be non-NULL but uninitialised (\helpref{wxBitmap:IsOk}{wxbitmapisok} returns false).
\wxheading{See also}
\helpref{wxBrush::SetStipple}{wxbrushsetstipple}
+
\membersection{wxBrush::GetStyle}\label{wxbrushgetstyle}
\constfunc{int}{GetStyle}{\void}
\twocolitem{{\bf wxHORIZONTAL\_HATCH}}{Horizontal hatch.}
\twocolitem{{\bf wxVERTICAL\_HATCH}}{Vertical hatch.}
\twocolitem{{\bf wxSTIPPLE}}{Stippled using a bitmap.}
+\twocolitem{{\bf wxSTIPPLE\_MASK\_OPAQUE}}{Stippled using a bitmap's mask.}
\end{twocollist}
\wxheading{See also}
\helpref{wxBrush::SetStyle}{wxbrushsetstyle}, \helpref{wxBrush::SetColour}{wxbrushsetcolour},\rtfsp
\helpref{wxBrush::SetStipple}{wxbrushsetstipple}
-\membersection{wxBrush::Ok}\label{wxbrushok}
-\constfunc{bool}{Ok}{\void}
+\membersection{wxBrush::IsHatch}\label{wxbrushishatch}
+
+\constfunc{bool}{IsHatch}{\void}
+
+Returns true if the style of the brush is any of hatched fills.
+
+\wxheading{See also}
+
+\helpref{wxBrush::GetStyle}{wxbrushgetstyle}
+
+
+\membersection{wxBrush::IsOk}\label{wxbrushisok}
-Returns TRUE if the brush is initialised. It will return FALSE if the default
+\constfunc{bool}{IsOk}{\void}
+
+Returns true if the brush is initialised. It will return false if the default
constructor has been used (for example, the brush is a member of a class, or
NULL has been assigned to it).
+
\membersection{wxBrush::SetColour}\label{wxbrushsetcolour}
\func{void}{SetColour}{\param{wxColour\& }{colour}}
Sets the brush colour using a colour name from the colour database.
-\func{void}{SetColour}{\param{const unsigned char}{ red}, \param{const unsigned char}{ green}, \param{const unsigned char}{ blue}}
+\func{void}{SetColour}{\param{unsigned char}{ red}, \param{unsigned char}{ green}, \param{unsigned char}{ blue}}
Sets the brush colour using red, green and blue values.
\helpref{wxBrush::GetColour}{wxbrushgetcolour}
+
\membersection{wxBrush::SetStipple}\label{wxbrushsetstipple}
\func{void}{SetStipple}{\param{const wxBitmap\&}{ bitmap}}
\wxheading{Remarks}
-The style will be set to wxSTIPPLE.
+The style will be set to wxSTIPPLE, unless the bitmap has a mask associated
+to it, in which case the style will be set to wxSTIPPLE\_MASK\_OPAQUE.
+
+If the wxSTIPPLE variant is used, the bitmap will be used to fill out the
+area to be drawn. If the wxSTIPPLE\_MASK\_OPAQUE is used, the current
+text foreground and text background determine what colours are used for
+displaying and the bits in the mask (which is a mono-bitmap actually)
+determine where to draw what.
-Note that there is a big difference between stippling in X and Windows.
-On X, the stipple is a mask between the wxBitmap and current colour.
-On Windows, the current colour is ignored, and the bitmap colour is used.
-However, for pre-defined modes like wxCROSS\_HATCH, the behaviour is the
-same for both platforms.
+Note that under Windows 95, only 8x8 pixel large stipple bitmaps are
+supported, Windows 98 and NT as well as GTK support arbitrary bitmaps.
\wxheading{See also}
\helpref{wxBitmap}{wxbitmap}
+
\membersection{wxBrush::SetStyle}\label{wxbrushsetstyle}
\func{void}{SetStyle}{\param{int}{ style}}
\twocolitem{{\bf wxHORIZONTAL\_HATCH}}{Horizontal hatch.}
\twocolitem{{\bf wxVERTICAL\_HATCH}}{Vertical hatch.}
\twocolitem{{\bf wxSTIPPLE}}{Stippled using a bitmap.}
+\twocolitem{{\bf wxSTIPPLE\_MASK\_OPAQUE}}{Stippled using a bitmap's mask.}
\end{twocollist}}
\wxheading{See also}
\helpref{wxBrush::GetStyle}{wxbrushgetstyle}
+
\membersection{wxBrush::operator $=$}\label{wxbrushassignment}
\func{wxBrush\&}{operator $=$}{\param{const wxBrush\& }{brush}}
-Assignment operator, using reference counting. Returns a reference
-to `this'.
+Assignment operator, using \helpref{reference counting}{trefcount}.
+
\membersection{wxBrush::operator $==$}\label{wxbrushequals}
\func{bool}{operator $==$}{\param{const wxBrush\& }{brush}}
-Equality operator. Two brushes are equal if they contain pointers
-to the same underlying brush data. It does not compare each attribute,
-so two independently-created brushes using the same parameters will
-fail the test.
+Equality operator.
+See \helpref{reference-counted object comparison}{refcountequality} for more info.
+
\membersection{wxBrush::operator $!=$}\label{wxbrushnotequals}
\func{bool}{operator $!=$}{\param{const wxBrush\& }{brush}}
-Inequality operator. Two brushes are not equal if they contain pointers
-to different underlying brush data. It does not compare each attribute.
+Inequality operator.
+See \helpref{reference-counted object comparison}{refcountequality} for more info.
+
\section{\class{wxBrushList}}\label{wxbrushlist}
\helpref{wxList}{wxlist}\\
\helpref{wxObject}{wxobject}
+\wxheading{Include files}
+
+<wx/gdicmn.h>
+
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+
\wxheading{Remarks}
There is only one instance of this class: {\bf wxTheBrushList}. Use
`memory leaks'. However, it is best not to rely on this automatic
cleanup because it can lead to double deletion in some circumstances.
-There are two mechanisms in recent versions of wxWindows which make the
+There are two mechanisms in recent versions of wxWidgets which make the
brush list less useful than it once was. Under Windows, scarce resources
-are cleaned up internally if they are not being used. Also, a referencing
+are cleaned up internally if they are not being used. Also, a reference
counting mechanism applied to all GDI objects means that some sharing
of underlying resources is possible. You don't have to keep track of pointers,
-working out when it is safe delete a brush, because the referencing counting does
+working out when it is safe delete a brush, because the reference counting does
it for you. For example, you can set a brush in a device context, and then
immediately delete the brush you passed, because the brush is `copied'.
your application is using too many resources, you can resort to using
GDI lists to share objects explicitly.
-The only compelling use for the brush list is for wxWindows to keep
+The only compelling use for the brush list is for wxWidgets to keep
track of brushes in order to clean them up on exit. It is also kept for
-backward compatibility with earlier versions of wxWindows.
+backward compatibility with earlier versions of wxWidgets.
\wxheading{See also}
\latexignore{\rtfignore{\wxheading{Members}}}
+
\membersection{wxBrushList::wxBrushList}\label{wxbrushlistconstr}
\func{void}{wxBrushList}{\void}
Constructor. The application should not construct its own brush list:
use the object pointer {\bf wxTheBrushList}.
-\membersection{wxBrushList::AddBrush}\label{wxbrushlistaddbrush}
-
-\func{void}{AddBrush}{\param{wxBrush *}{brush}}
-
-Used internally by wxWindows to add a brush to the list.
\membersection{wxBrushList::FindOrCreateBrush}\label{wxbrushlistfindorcreatebrush}
-\func{wxBrush *}{FindOrCreateBrush}{\param{const wxColour\& }{colour}, \param{int}{ style}}
-
-Finds a brush with the specified attributes and returns it, else creates a new brush, adds it
-to the brush list, and returns it.
-
-\func{wxBrush *}{FindOrCreateBrush}{\param{const wxString\& }{colourName}, \param{int}{ style}}
+\func{wxBrush *}{FindOrCreateBrush}{\param{const wxColour\& }{colour}, \param{int}{ style = wxSOLID}}
Finds a brush with the specified attributes and returns it, else creates a new brush, adds it
to the brush list, and returns it.
-Finds a brush of the given specification, or creates one and adds it to the list.
-
\wxheading{Parameters}
\docparam{colour}{Colour object.}
-\docparam{colourName}{Colour name, which should be in the colour database.}
-
\docparam{style}{Brush style. See \helpref{wxBrush::SetStyle}{wxbrushsetstyle} for a list of styles.}
-\membersection{wxBrushList::RemoveBrush}\label{wxbrushlistremovebrush}
-
-\func{void}{RemoveBrush}{\param{wxBrush *}{brush}}
-
-Used by wxWindows to remove a brush from the list.
-
projects / wxWidgets.git / blobdiff