+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% 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
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. Once one wxBrush object changes its data it will create its
-own brush data internally so that other brushes, which previously shared the
+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.
\func{}{wxBrush}{\void}
-Default constructor. The brush will be uninitialised, and \helpref{wxBrush::Ok}{wxbrushok} will
+Default constructor. The brush will be uninitialised, and \helpref{wxBrush:IsOk}{wxbrushisok} will
return false.
\func{}{wxBrush}{\param{const wxColour\&}{ colour}, \param{int}{ style = {\tt wxSOLID}}}
\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}
\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
wxWidgets cannot know if a pointer to the brush object is stored in an
\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::GetStyle}{wxbrushgetstyle}
-\membersection{wxBrush::Ok}\label{wxbrushok}
+\membersection{wxBrush::IsOk}\label{wxbrushisok}
-\constfunc{bool}{Ok}{\void}
+\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
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.
\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}
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'.
use the object pointer {\bf wxTheBrushList}.
-\membersection{wxBrushList::AddBrush}\label{wxbrushlistaddbrush}
-
-\func{void}{AddBrush}{\param{wxBrush *}{brush}}
-
-Used internally by wxWidgets to add a brush to the list.
-
-
\membersection{wxBrushList::FindOrCreateBrush}\label{wxbrushlistfindorcreatebrush}
\func{wxBrush *}{FindOrCreateBrush}{\param{const wxColour\& }{colour}, \param{int}{ style = wxSOLID}}
\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 wxWidgets to remove a brush from the list.
-
-
projects / wxWidgets.git / blobdiff