Fix wxBufferedDC so that it adheres to its documented behavior (which is in use in...

[wxWidgets.git] / docs / latex / wx / pen.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        pen.tex
%% Purpose:     wxPen docs
%% Author:
%% Modified by:
%% Created:
%% RCS-ID:      $Id$
%% Copyright:   (c) wxWidgets
%% License:     wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{\class{wxPen}}\label{wxpen}

A pen is a drawing tool for drawing outlines. It is used for drawing
lines and painting the outline of rectangles, ellipses, etc. It has a
colour, a width and a style.

\wxheading{Derived from}

\helpref{wxGDIObject}{wxgdiobject}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/pen.h>

\wxheading{Predefined objects}

Objects:

{\bf wxNullPen}

Pointers:

{\bf wxRED\_PEN\\
wxCYAN\_PEN\\
wxGREEN\_PEN\\
wxBLACK\_PEN\\
wxWHITE\_PEN\\
wxTRANSPARENT\_PEN\\
wxBLACK\_DASHED\_PEN\\
wxGREY\_PEN\\
wxMEDIUM\_GREY\_PEN\\
wxLIGHT\_GREY\_PEN}

\wxheading{Remarks}

On a monochrome display, wxWidgets shows all non-white pens as black.

Do not initialize objects on the stack before the program commences,
since other required structures may not have been set up yet. Instead,
define global pointers to objects and create them in {\it OnInit} or
when required.

An application may wish to dynamically create pens with different
characteristics, and there is the consequent danger that a large number
of duplicate pens will be created. Therefore an application may wish to
get a pointer to a pen by using the global list of pens {\bf
wxThePenList}, and calling the member function {\bf FindOrCreatePen}.
See the entry for \helpref{wxPenList}{wxpenlist}.

wxPen uses a reference counting system, so assignments between brushes are very
cheap. You can therefore use actual wxPen objects instead of pointers without
efficiency problems. Once one wxPen object changes its data it will create its
own pen data internally so that other pens, which previously shared the
data using the reference counting, are not affected.

%TODO: an overview for wxPen.
\wxheading{See also}

\helpref{wxPenList}{wxpenlist}, \helpref{wxDC}{wxdc}, \helpref{wxDC::SetPen}{wxdcsetpen}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxPen::wxPen}\label{wxpenctor}

\func{}{wxPen}{\void}

Default constructor. The pen will be uninitialised, and \helpref{wxPen:IsOk}{wxpenisok} will
return false.

\func{}{wxPen}{\param{const wxColour\&}{ colour}, \param{int}{ width = $1$}, \param{int}{ style = {\tt wxSOLID}}}

Constructs a pen from a colour object, pen width and style.

\func{}{wxPen}{\param{const wxString\& }{colourName}, \param{int}{ width}, \param{int}{ style}}

Constructs a pen from a colour name, pen width and style.

\func{}{wxPen}{\param{const wxBitmap\&}{ stipple}, \param{int}{ width}}

Constructs a stippled pen from a stipple bitmap and a width.

\func{}{wxPen}{\param{const wxPen\&}{ pen}}

Copy constructor, uses \helpref{reference counting}{trefcount}.

\wxheading{Parameters}

\docparam{colour}{A colour object.}

\docparam{colourName}{A colour name.}

\docparam{width}{Pen width. Under Windows, the pen width cannot be greater than 1 if
the style is wxDOT, wxLONG\_DASH, wxSHORT\_DASH, wxDOT\_DASH, or wxUSER\_DASH.}

\docparam{stipple}{A stipple bitmap.}

\docparam{pen}{A pointer or reference to a pen to copy.}

\docparam{style}{The style may be one of the following:

\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxSOLID}}{Solid style.}
\twocolitem{{\bf wxTRANSPARENT}}{No pen is used.}
\twocolitem{{\bf wxDOT}}{Dotted style.}
\twocolitem{{\bf wxLONG\_DASH}}{Long dashed style.}
\twocolitem{{\bf wxSHORT\_DASH}}{Short dashed style.}
\twocolitem{{\bf wxDOT\_DASH}}{Dot and dash style.}
\twocolitem{{\bf wxSTIPPLE}}{Use the stipple bitmap.}
\twocolitem{{\bf wxUSER\_DASH}}{Use the user dashes: see \helpref{wxPen::SetDashes}{wxpensetdashes}.}
\twocolitem{{\bf wxBDIAGONAL\_HATCH}}{Backward diagonal hatch.}
\twocolitem{{\bf wxCROSSDIAG\_HATCH}}{Cross-diagonal hatch.}
\twocolitem{{\bf wxFDIAGONAL\_HATCH}}{Forward diagonal hatch.}
\twocolitem{{\bf wxCROSS\_HATCH}}{Cross hatch.}
\twocolitem{{\bf wxHORIZONTAL\_HATCH}}{Horizontal hatch.}
\twocolitem{{\bf wxVERTICAL\_HATCH}}{Vertical hatch.}
\end{twocollist}}

\wxheading{Remarks}

Different versions of Windows and different versions of other platforms
support {\it very} different subsets of the styles above - there is no
similarity even between Windows95 and Windows98 - so handle with care.

If the named colour form is used, an appropriate {\bf wxColour} structure
is found in the colour database.

\wxheading{See also}

\helpref{wxPen::SetStyle}{wxpensetstyle}, \helpref{wxPen::SetColour}{wxpensetcolour},\rtfsp
\helpref{wxPen::SetWidth}{wxpensetwidth}, \helpref{wxPen::SetStipple}{wxpensetstipple}

\perlnote{Constructors supported by wxPerl are:\par
\begin{itemize}
\item{Wx::Pen->new( colour, width, style )}
\item{Wx::Pen->new( colourName, width, style )}
\item{Wx::Pen->new( stipple, width )}
\end{itemize}
}

\membersection{wxPen::\destruct{wxPen}}\label{wxpendtor}

\func{}{\destruct{wxPen}}{\void}

Destructor.

\wxheading{Remarks}

The destructor may not delete the underlying pen object of the native windowing
system, since wxBrush uses a reference counting system for efficiency.

Although all remaining pens are deleted when the application exits,
the application should try to clean up all pens itself. This is because
wxWidgets cannot know if a pointer to the pen object is stored in an
application data structure, and there is a risk of double deletion.

\membersection{wxPen::GetCap}\label{wxpengetcap}

\constfunc{int}{GetCap}{\void}

Returns the pen cap style, which may be one of {\bf wxCAP\_ROUND}, {\bf wxCAP\_PROJECTING} and
\rtfsp{\bf wxCAP\_BUTT}. The default is {\bf wxCAP\_ROUND}.

\wxheading{See also}

\helpref{wxPen::SetCap}{wxpensetcap}

\membersection{wxPen::GetColour}\label{wxpengetcolour}

\constfunc{wxColour\&}{GetColour}{\void}

Returns a reference to the pen colour.

\wxheading{See also}

\helpref{wxPen::SetColour}{wxpensetcolour}

\membersection{wxPen::GetDashes}\label{wxpengetdashes}

\constfunc{int}{GetDashes}{\param{wxDash**}{ dashes}}

Gets an array of dashes (defined as char in X, DWORD under Windows).
{\it dashes} is a pointer to the internal array. Do not deallocate or store this pointer.
The function returns the number of dashes associated with this pen.

\wxheading{See also}

\helpref{wxPen::SetDashes}{wxpensetdashes}

\membersection{wxPen::GetJoin}\label{wxpengetjoin}

\constfunc{int}{GetJoin}{\void}

Returns the pen join style, which may be one of {\bf wxJOIN\_BEVEL}, {\bf wxJOIN\_ROUND} and
\rtfsp{\bf wxJOIN\_MITER}. The default is {\bf wxJOIN\_ROUND}.

\wxheading{See also}

\helpref{wxPen::SetJoin}{wxpensetjoin}

\membersection{wxPen::GetStipple}\label{wxpengetstipple}

\constfunc{wxBitmap* }{GetStipple}{\void}

Gets a pointer to the stipple bitmap.

\wxheading{See also}

\helpref{wxPen::SetStipple}{wxpensetstipple}

\membersection{wxPen::GetStyle}\label{wxpengetstyle}

\constfunc{int}{GetStyle}{\void}

Returns the pen style.

\wxheading{See also}

\helpref{wxPen::wxPen}{wxpenctor}, \helpref{wxPen::SetStyle}{wxpensetstyle}

\membersection{wxPen::GetWidth}\label{wxpengetwidth}

\constfunc{int}{GetWidth}{\void}

Returns the pen width.

\wxheading{See also}

\helpref{wxPen::SetWidth}{wxpensetwidth}

\membersection{wxPen::IsOk}\label{wxpenisok}

\constfunc{bool}{IsOk}{\void}

Returns true if the pen is initialised.

\membersection{wxPen::SetCap}\label{wxpensetcap}

\func{void}{SetCap}{\param{int}{ capStyle}}

Sets the pen cap style, which may be one of {\bf wxCAP\_ROUND}, {\bf wxCAP\_PROJECTING} and
\rtfsp{\bf wxCAP\_BUTT}. The default is {\bf wxCAP\_ROUND}.

\wxheading{See also}

\helpref{wxPen::GetCap}{wxpengetcap}

\membersection{wxPen::SetColour}\label{wxpensetcolour}

\func{void}{SetColour}{\param{wxColour\&}{ colour}}

\func{void}{SetColour}{\param{const wxString\& }{colourName}}

\func{void}{SetColour}{\param{unsigned char}{ red}, \param{unsigned char}{ green}, \param{unsigned char}{ blue}}

The pen's colour is changed to the given colour.

\wxheading{See also}

\helpref{wxPen::GetColour}{wxpengetcolour}

\membersection{wxPen::SetDashes}\label{wxpensetdashes}

\func{void}{SetDashes}{\param{int }{n}, \param{wxDash*}{ dashes}}

Associates an array of pointers to dashes (defined as char in X, DWORD under Windows)
with the pen. The array is not deallocated by wxPen, but neither must it be
deallocated by the calling application until the pen is deleted or this
function is called with a NULL array.

%TODO: describe in detail.
\wxheading{See also}

\helpref{wxPen::GetDashes}{wxpengetdashes}

\membersection{wxPen::SetJoin}\label{wxpensetjoin}

\func{void}{SetJoin}{\param{int }{join\_style}}

Sets the pen join style, which may be one of {\bf wxJOIN\_BEVEL}, {\bf wxJOIN\_ROUND} and
\rtfsp{\bf wxJOIN\_MITER}. The default is {\bf wxJOIN\_ROUND}.

\wxheading{See also}

\helpref{wxPen::GetJoin}{wxpengetjoin}

\membersection{wxPen::SetStipple}\label{wxpensetstipple}

\func{void}{SetStipple}{\param{wxBitmap* }{stipple}}

Sets the bitmap for stippling.

\wxheading{See also}

\helpref{wxPen::GetStipple}{wxpengetstipple}

\membersection{wxPen::SetStyle}\label{wxpensetstyle}

\func{void}{SetStyle}{\param{int}{ style}}

Set the pen style.

\wxheading{See also}

\helpref{wxPen::wxPen}{wxpenctor}

\membersection{wxPen::SetWidth}\label{wxpensetwidth}

\func{void}{SetWidth}{\param{int}{ width}}

Sets the pen width.

\wxheading{See also}

\helpref{wxPen::GetWidth}{wxpengetwidth}

\membersection{wxPen::operator $=$}\label{wxpenassignment}

\func{wxPen\&}{operator $=$}{\param{const wxPen\& }{pen}}

Assignment operator, using \helpref{reference counting}{trefcount}.

\membersection{wxPen::operator $==$}\label{wxpenequals}

\func{bool}{operator $==$}{\param{const wxPen\& }{pen}}

Equality operator. Two pens are equal if they contain pointers
to the same underlying pen data. It does not compare each attribute,
so two independently-created pens using the same parameters will
fail the test.

\membersection{wxPen::operator $!=$}\label{wxpennotequals}

\func{bool}{operator $!=$}{\param{const wxPen\& }{pen}}

Inequality operator. Two pens are not equal if they contain pointers
to different underlying pen data. It does not compare each attribute.

\section{\class{wxPenList}}\label{wxpenlist}

There is only one instance of this class: {\bf wxThePenList}.  Use
this object to search for a previously created pen of the desired
type and create it if not already found. In some windowing systems,
the pen may be a scarce resource, so it can pay to reuse old
resources if possible. When an application finishes, all pens will
be deleted and their resources freed, eliminating the possibility of
`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 wxWidgets which make the
pen list less useful than it once was. Under Windows, scarce resources
are cleaned up internally if they are not being used. Also, a referencing
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 pen, because the referencing counting does
it for you. For example, you can set a pen in a device context, and then
immediately delete the pen you passed, because the pen is `copied'.

So you may find it easier to ignore the pen list, and instead create
and copy pens as you see fit. If your Windows resource meter suggests
your application is using too many resources, you can resort to using
GDI lists to share objects explicitly.

The only compelling use for the pen list is for wxWidgets to keep
track of pens in order to clean them up on exit. It is also kept for
backward compatibility with earlier versions of wxWidgets.

\wxheading{See also}

\helpref{wxPen}{wxpen}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxPenList::wxPenList}\label{wxpenlistctor}

\func{void}{wxPenList}{\void}

Constructor. The application should not construct its own pen list:
use the object pointer {\bf wxThePenList}.

\membersection{wxPenList::FindOrCreatePen}\label{wxpenlistfindorcreatepen}

\func{wxPen*}{FindOrCreatePen}{\param{const wxColour\& }{colour}, \param{int}{ width}, \param{int}{ style}}

Finds a pen with the specified attributes and returns it, else creates a new pen, adds it
to the pen list, and returns it.

\func{wxPen*}{FindOrCreatePen}{\param{const wxString\& }{colourName}, \param{int}{ width}, \param{int}{ style}}

Finds a pen with the specified attributes and returns it, else creates a new pen, adds it
to the pen list, and returns it.

\wxheading{Parameters}

\docparam{colour}{Colour object.}

\docparam{colourName}{Colour name, which should be in the \helpref{colour database}{wxcolourdatabase}.}

\docparam{width}{Width of pen.}

\docparam{style}{Pen style. See \helpref{wxPen::wxPen}{wxpenctor} for a list of styles.}