1 \section{\class{wxPen
}}\label{wxpen
}
3 A pen is a drawing tool for drawing outlines. It is used for drawing
4 lines and painting the outline of rectangles, ellipses, etc. It has a
5 colour, a width and a style.
9 On a monochrome display, wxWindows shows all non-white pens as black.
11 Do not initialize objects on the stack before the program commences,
12 since other required structures may not have been set up yet. Instead,
13 define global pointers to objects and create them in
{\it OnInit
} or
16 An application may wish to dynamically create pens with different
17 characteristics, and there is the consequent danger that a large number
18 of duplicate pens will be created. Therefore an application may wish to
19 get a pointer to a pen by using the global list of pens
{\bf
20 wxThePenList
}, and calling the member function
{\bf FindOrCreatePen
}.
21 See the entry for
\helpref{wxPenList
}{wxpenlist
}.
23 wxPen uses a reference counting system, so assignments between brushes are very
24 cheap. You can therefore use actual wxPen objects instead of pointers without
25 efficiency problems. Once one wxPen object changes its data it will create its
26 own pen data internally so that other pens, which previously shared the
27 data using the reference counting, are not affected.
29 %TODO: an overview for wxPen.
32 \helpref{wxPenList
}{wxpenlist
},
\helpref{wxDC
}{wxdc
},
\helpref{wxDC::SetPen
}{wxdcsetpen
}
34 \latexignore{\rtfignore{\wxheading{Members
}}}
36 \membersection{wxPen::wxPen
}\label{wxpenconstr
}
40 Default constructor. The pen will be uninitialised, and
\helpref{wxPen::Ok
}{wxpenok
} will
43 \func{}{wxPen
}{\param{const wxColour\&
}{ colour
},
\param{int
}{ width
},
\param{int
}{ style
}}
45 Constructs a pen from a colour object, pen width and style.
47 \func{}{wxPen
}{\param{const wxString\&
}{colourName
},
\param{int
}{ width
},
\param{int
}{ style
}}
49 Constructs a pen from a colour name, pen width and style.
51 \func{}{wxPen
}{\param{const wxBitmap\&
}{ stipple
},
\param{int
}{ width
}}
53 Constructs a stippled pen from a stipple bitmap and a width.
55 \func{}{wxPen
}{\param{const wxPen\&
}{ pen
}}
57 Copy constructor. This uses reference counting so is a cheap operation.
59 \wxheading{Parameters
}
61 \docparam{colour
}{A colour object.
}
63 \docparam{colourName
}{A colour name.
}
65 \docparam{width
}{Pen width. Under Windows, the pen width cannot be greater than
1 if
66 the style is wxDOT, wxLONG
\_DASH, wxSHORT
\_DASH, wxDOT
\_DASH, or wxUSER
\_DASH.
}
68 \docparam{stipple
}{A stipple bitmap.
}
70 \docparam{pen
}{A pointer or reference to a pen to copy.
}
72 \docparam{width
}{Pen width. Under Windows, the pen width cannot be greater than
1 if
73 the style is wxDOT, wxLONG
\_DASH, wxSHORT
\_DASH, wxDOT
\_DASH, or wxUSER
\_DASH.
}
75 \docparam{style
}{The style may be one of the following:
77 \begin{twocollist
}\itemsep=
0pt
78 \twocolitem{{\bf wxSOLID
}}{Solid style.
}
79 \twocolitem{{\bf wxTRANSPARENT
}}{No pen is used.
}
80 \twocolitem{{\bf wxDOT
}}{Dotted style.
}
81 \twocolitem{{\bf wxLONG
\_DASH}}{Long dashed style.
}
82 \twocolitem{{\bf wxSHORT
\_DASH}}{Short dashed style.
}
83 \twocolitem{{\bf wxDOT
\_DASH}}{Dot and dash style.
}
84 \twocolitem{{\bf wxSTIPPLE
}}{Use the stipple bitmap.
}
85 \twocolitem{{\bf wxUSER
\_DASH}}{Use the user dashes: see
\helpref{wxPen::SetDashes
}{wxpensetdashes
}.
}
86 \twocolitem{{\bf wxBDIAGONAL
\_HATCH}}{Backward diagonal hatch.
}
87 \twocolitem{{\bf wxCROSSDIAG
\_HATCH}}{Cross-diagonal hatch.
}
88 \twocolitem{{\bf wxFDIAGONAL
\_HATCH}}{Forward diagonal hatch.
}
89 \twocolitem{{\bf wxCROSS
\_HATCH}}{Cross hatch.
}
90 \twocolitem{{\bf wxHORIZONTAL
\_HATCH}}{Horizontal hatch.
}
91 \twocolitem{{\bf wxVERTICAL
\_HATCH}}{Vertical hatch.
}
96 If the named colour form is used, an appropriate
{\bf wxColour
} structure
97 is found in the colour database.
99 {\it style
} may be one of wxSOLID, wxDOT, wxLONG
\_DASH, wxSHORT
\_DASH and
104 \helpref{wxPen::SetStyle
}{wxpensetstyle
},
\helpref{wxPen::SetColour
}{wxpensetcolour
},
\rtfsp
105 \helpref{wxPen::SetWidth
}{wxpensetwidth
},
\helpref{wxPen::SetStipple
}{wxpensetstipple
}
107 \membersection{wxPen::
\destruct{wxPen
}}
109 \func{}{\destruct{wxPen
}}{\void}
115 The destructor may not delete the underlying pen object of the native windowing
116 system, since wxBrush uses a reference counting system for efficiency.
118 Although all remaining pens are deleted when the application exits,
119 the application should try to clean up all pens itself. This is because
120 wxWindows cannot know if a pointer to the pen object is stored in an
121 application data structure, and there is a risk of double deletion.
123 \membersection{wxPen::GetCap
}\label{wxpengetcap
}
125 \constfunc{int
}{GetCap
}{\void}
127 Returns the pen cap style, which may be one of
{\bf wxCAP
\_ROUND},
{\bf wxCAP
\_PROJECTING} and
128 \rtfsp{\bf wxCAP
\_BUTT}. The default is
{\bf wxCAP
\_ROUND}.
132 \helpref{wxPen::SetCap
}{wxpensetcap
}
134 \membersection{wxPen::GetColour
}\label{wxpengetcolour
}
136 \constfunc{wxColour\&
}{GetColour
}{\void}
138 Returns a reference to the pen colour.
142 \helpref{wxPen::SetColour
}{wxpensetcolour
}
144 \membersection{wxPen::GetDashes
}\label{wxpengetdashes
}
146 \constfunc{int
}{GetDashes
}{\param{wxDash**
}{ dashes
}}
148 Gets an array of dashes (defined as char in X, DWORD under Windows).
149 {\it dashes
} is a pointer to the internal array. Do not deallocate or store this pointer.
150 The function returns the number of dashes associated with this pen.
154 \helpref{wxPen::SetDashes
}{wxpensetdashes
}
156 \membersection{wxPen::GetJoin
}\label{wxpengetjoin
}
158 \constfunc{int
}{GetJoin
}{\void}
160 Returns the pen join style, which may be one of
{\bf wxJOIN
\_BEVEL},
{\bf wxJOIN
\_ROUND} and
161 \rtfsp{\bf wxJOIN
\_MITER}. The default is
{\bf wxJOIN
\_ROUND}.
165 \helpref{wxPen::SetJoin
}{wxpensetjoin
}
167 \membersection{wxPen::GetStipple
}\label{wxpengetstipple
}
169 \constfunc{wxBitmap*
}{GetStipple
}{\void}
171 Gets a pointer to the stipple bitmap.
175 \helpref{wxPen::SetStipple
}{wxpensetstipple
}
177 \membersection{wxPen::GetStyle
}\label{wxpengetstyle
}
179 \constfunc{int
}{GetStyle
}{\void}
181 Returns the pen style.
185 \helpref{wxPen::wxPen
}{wxpenconstr
},
\helpref{wxPen::SetStyle
}{wxpensetstyle
}
187 \membersection{wxPen::GetWidth
}\label{wxpengetwidth
}
189 \constfunc{int
}{GetWidth
}{\void}
191 Returns the pen width.
195 \helpref{wxPen::SetWidth
}{wxpensetwidth
}
197 \membersection{wxPen::Ok
}\label{wxpenok
}
199 \constfunc{bool
}{Ok
}{\void}
201 Returns TRUE if the pen is initialised.
203 \membersection{wxPen::SetCap
}\label{wxpensetcap
}
205 \func{void
}{SetCap
}{\param{int
}{ capStyle
}}
207 Sets the pen cap style, which may be one of
{\bf wxCAP
\_ROUND},
{\bf wxCAP
\_PROJECTING} and
208 \rtfsp{\bf wxCAP
\_BUTT}. The default is
{\bf wxCAP
\_ROUND}.
212 \helpref{wxPen::GetCap
}{wxpengetcap
}
214 \membersection{wxPen::SetColour
}\label{wxpensetcolour
}
216 \func{void
}{SetColour
}{\param{wxColour\&
}{ colour
}}
218 \func{void
}{SetColour
}{\param{const wxString\&
}{colourName
}}
220 \func{void
}{SetColour
}{\param{int
}{ red
},
\param{int
}{ green
},
\param{int
}{ blue
}}
222 The pen's colour is changed to the given colour.
226 \helpref{wxPen::GetColour
}{wxpengetcolour
}
228 \membersection{wxPen::SetDashes
}\label{wxpensetdashes
}
230 \func{void
}{SetDashes
}{\param{int
}{n
},
\param{wxDash*
}{ dashes
}}
232 Associates an array of pointers to dashes (defined as char in X, DWORD under Windows)
233 with the pen. The array is not deallocated by wxPen, but neither must it be
234 deallocated by the calling application until the pen is deleted or this
235 function is called with a NULL array.
237 %TODO: describe in detail.
240 \helpref{wxPen::GetDashes
}{wxpengetdashes
}
242 \membersection{wxPen::SetJoin
}\label{wxpensetjoin
}
244 \func{void
}{SetJoin
}{\param{int
}{join
\_style}}
246 Sets the pen join style, which may be one of
{\bf wxJOIN
\_BEVEL},
{\bf wxJOIN
\_ROUND} and
247 \rtfsp{\bf wxJOIN
\_MITER}. The default is
{\bf wxJOIN
\_ROUND}.
251 \helpref{wxPen::GetJoin
}{wxpengetjoin
}
253 \membersection{wxPen::SetStipple
}\label{wxpensetstipple
}
255 \func{void
}{SetStipple
}{\param{wxBitmap*
}{stipple
}}
257 Sets the bitmap for stippling.
261 \helpref{wxPen::GetStipple
}{wxpengetstipple
}
263 \membersection{wxPen::SetStyle
}\label{wxpensetstyle
}
265 \func{void
}{SetStyle
}{\param{int
}{ style
}}
271 \helpref{wxPen::wxPen
}{wxpenconstr
}
273 \membersection{wxPen::SetWidth
}\label{wxpensetwidth
}
275 \func{void
}{SetWidth
}{\param{int
}{ width
}}
281 \helpref{wxPen::GetWidth
}{wxpengetwidth
}
283 \membersection{wxPen::operator $=$
}\label{wxpenassignment
}
285 \func{wxPen\&
}{operator $=$
}{\param{const wxPen\&
}{pen
}}
287 Assignment operator, using reference counting. Returns a reference
290 \membersection{wxPen::operator $==$
}\label{wxpenequals
}
292 \func{bool
}{operator $==$
}{\param{const wxPen\&
}{pen
}}
294 Equality operator. Two pens are equal if they contain pointers
295 to the same underlying pen data. It does not compare each attribute,
296 so two independently-created pens using the same parameters will
299 \membersection{wxPen::operator $!=$
}\label{wxpennotequals
}
301 \func{bool
}{operator $!=$
}{\param{const wxPen\&
}{pen
}}
303 Inequality operator. Two pens are not equal if they contain pointers
304 to different underlying pen data. It does not compare each attribute.
306 \section{\class{wxPenList
}}\label{wxpenlist
}
308 There is only one instance of this class:
{\bf wxThePenList
}. Use
309 this object to search for a previously created pen of the desired
310 type and create it if not already found. In some windowing systems,
311 the pen may be a scarce resource, so it can pay to reuse old
312 resources if possible. When an application finishes, all pens will
313 be deleted and their resources freed, eliminating the possibility of
314 `memory leaks'. However, it is best not to rely on this automatic
315 cleanup because it can lead to double deletion in some circumstances.
317 There are two mechanisms in recent versions of wxWindows which make the
318 pen list less useful than it once was. Under Windows, scarce resources
319 are cleaned up internally if they are not being used. Also, a referencing
320 counting mechanism applied to all GDI objects means that some sharing
321 of underlying resources is possible. You don't have to keep track of pointers,
322 working out when it is safe delete a pen, because the referencing counting does
323 it for you. For example, you can set a pen in a device context, and then
324 immediately delete the pen you passed, because the pen is `copied'.
326 So you may find it easier to ignore the pen list, and instead create
327 and copy pens as you see fit. If your Windows resource meter suggests
328 your application is using too many resources, you can resort to using
329 GDI lists to share objects explicitly.
331 The only compelling use for the pen list is for wxWindows to keep
332 track of pens in order to clean them up on exit. It is also kept for
333 backward compatibility with earlier versions of wxWindows.
337 \helpref{wxPen
}{wxpen
}
339 \latexignore{\rtfignore{\wxheading{Members
}}}
341 \membersection{wxPenList::wxPenList
}
343 \func{void
}{wxPenList
}{\void}
345 Constructor. The application should not construct its own pen list:
346 use the object pointer
{\bf wxThePenList
}.
348 \membersection{wxPenList::AddPen
}\label{wxpenlistaddpen
}
350 \func{void
}{AddPen
}{\param{wxPen*
}{ pen
}}
352 Used internally by wxWindows to add a pen to the list.
354 \membersection{wxPenList::FindOrCreatePen
}\label{wxpenlistfindorcreatepen
}
356 \func{wxPen*
}{FindOrCreatePen
}{\param{const wxColour\&
}{colour
},
\param{int
}{ width
},
\param{int
}{ style
}}
358 Finds a pen with the specified attributes and returns it, else creates a new pen, adds it
359 to the pen list, and returns it.
361 \func{wxPen*
}{FindOrCreatePen
}{\param{const wxString\&
}{colourName
},
\param{int
}{ width
},
\param{int
}{ style
}}
363 Finds a pen with the specified attributes and returns it, else creates a new pen, adds it
364 to the pen list, and returns it.
366 \wxheading{Parameters
}
368 \docparam{colour
}{Colour object.
}
370 \docparam{colourName
}{Colour name, which should be in the colour database.
}
372 \docparam{style
}{Pen style. See
\helpref{wxPen::wxPen
}{wxpenconstr
} for a list of styles.
}
374 \membersection{wxPenList::RemovePen
}\label{wxpenlistremovepen
}
376 \func{void
}{RemovePen
}{\param{wxPen*
}{ pen
}}
378 Used by wxWindows to remove a pen from the list.