]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/pen.tex
ugh. Nesting the (per class) plugin sentries can require them to
[wxWidgets.git] / docs / latex / wx / pen.tex
CommitLineData
a660d684
KB
1\section{\class{wxPen}}\label{wxpen}
2
3A pen is a drawing tool for drawing outlines. It is used for drawing
4lines and painting the outline of rectangles, ellipses, etc. It has a
5colour, a width and a style.
6
954b8ae6
JS
7\wxheading{Derived from}
8
9\helpref{wxGDIObject}{wxgdiobject}\\
10\helpref{wxObject}{wxobject}
11
12\wxheading{Include files}
13
14<wx/pen.h>
15
20e85460
JS
16\wxheading{Predefined objects}
17
18Objects:
19
20{\bf wxNullPen}
21
22Pointers:
23
24{\bf wxRED\_PEN\\
25wxCYAN\_PEN\\
26wxGREEN\_PEN\\
27wxBLACK\_PEN\\
28wxWHITE\_PEN\\
29wxTRANSPARENT\_PEN\\
30wxBLACK\_DASHED\_PEN\\
31wxGREY\_PEN\\
32wxMEDIUM\_GREY\_PEN\\
33wxLIGHT\_GREY\_PEN}
34
a660d684
KB
35\wxheading{Remarks}
36
37On a monochrome display, wxWindows shows all non-white pens as black.
38
39Do not initialize objects on the stack before the program commences,
40since other required structures may not have been set up yet. Instead,
41define global pointers to objects and create them in {\it OnInit} or
42when required.
43
44An application may wish to dynamically create pens with different
45characteristics, and there is the consequent danger that a large number
46of duplicate pens will be created. Therefore an application may wish to
47get a pointer to a pen by using the global list of pens {\bf
48wxThePenList}, and calling the member function {\bf FindOrCreatePen}.
49See the entry for \helpref{wxPenList}{wxpenlist}.
50
12a44087
RR
51wxPen uses a reference counting system, so assignments between brushes are very
52cheap. You can therefore use actual wxPen objects instead of pointers without
53efficiency problems. Once one wxPen object changes its data it will create its
54own pen data internally so that other pens, which previously shared the
55data using the reference counting, are not affected.
56
5b6aa0ff 57%TODO: an overview for wxPen.
a660d684
KB
58\wxheading{See also}
59
60\helpref{wxPenList}{wxpenlist}, \helpref{wxDC}{wxdc}, \helpref{wxDC::SetPen}{wxdcsetpen}
61
62\latexignore{\rtfignore{\wxheading{Members}}}
63
64\membersection{wxPen::wxPen}\label{wxpenconstr}
65
66\func{}{wxPen}{\void}
67
68Default constructor. The pen will be uninitialised, and \helpref{wxPen::Ok}{wxpenok} will
69return FALSE.
70
eaaa6a06 71\func{}{wxPen}{\param{const wxColour\&}{ colour}, \param{int}{ width}, \param{int}{ style}}
a660d684
KB
72
73Constructs a pen from a colour object, pen width and style.
74
eaaa6a06 75\func{}{wxPen}{\param{const wxString\& }{colourName}, \param{int}{ width}, \param{int}{ style}}
a660d684
KB
76
77Constructs a pen from a colour name, pen width and style.
78
eaaa6a06 79\func{}{wxPen}{\param{const wxBitmap\&}{ stipple}, \param{int}{ width}}
a660d684
KB
80
81Constructs a stippled pen from a stipple bitmap and a width.
82
83\func{}{wxPen}{\param{const wxPen\&}{ pen}}
84
85Copy constructor. This uses reference counting so is a cheap operation.
86
a660d684
KB
87\wxheading{Parameters}
88
89\docparam{colour}{A colour object.}
90
91\docparam{colourName}{A colour name.}
92
93\docparam{width}{Pen width. Under Windows, the pen width cannot be greater than 1 if
94the style is wxDOT, wxLONG\_DASH, wxSHORT\_DASH, wxDOT\_DASH, or wxUSER\_DASH.}
95
96\docparam{stipple}{A stipple bitmap.}
97
98\docparam{pen}{A pointer or reference to a pen to copy.}
99
a660d684
KB
100\docparam{style}{The style may be one of the following:
101
102\begin{twocollist}\itemsep=0pt
103\twocolitem{{\bf wxSOLID}}{Solid style.}
104\twocolitem{{\bf wxTRANSPARENT}}{No pen is used.}
105\twocolitem{{\bf wxDOT}}{Dotted style.}
106\twocolitem{{\bf wxLONG\_DASH}}{Long dashed style.}
107\twocolitem{{\bf wxSHORT\_DASH}}{Short dashed style.}
108\twocolitem{{\bf wxDOT\_DASH}}{Dot and dash style.}
109\twocolitem{{\bf wxSTIPPLE}}{Use the stipple bitmap.}
110\twocolitem{{\bf wxUSER\_DASH}}{Use the user dashes: see \helpref{wxPen::SetDashes}{wxpensetdashes}.}
111\twocolitem{{\bf wxBDIAGONAL\_HATCH}}{Backward diagonal hatch.}
112\twocolitem{{\bf wxCROSSDIAG\_HATCH}}{Cross-diagonal hatch.}
113\twocolitem{{\bf wxFDIAGONAL\_HATCH}}{Forward diagonal hatch.}
114\twocolitem{{\bf wxCROSS\_HATCH}}{Cross hatch.}
115\twocolitem{{\bf wxHORIZONTAL\_HATCH}}{Horizontal hatch.}
116\twocolitem{{\bf wxVERTICAL\_HATCH}}{Vertical hatch.}
117\end{twocollist}}
118
119\wxheading{Remarks}
120
2259e007
RR
121Different versions of Windows and different versions of other platforms
122support {\it very} different subsets of the styles above - there is no
123similarity even between Windows95 and Windows98 - so handle with care.
124
a660d684
KB
125If the named colour form is used, an appropriate {\bf wxColour} structure
126is found in the colour database.
127
a660d684
KB
128\wxheading{See also}
129
130\helpref{wxPen::SetStyle}{wxpensetstyle}, \helpref{wxPen::SetColour}{wxpensetcolour},\rtfsp
131\helpref{wxPen::SetWidth}{wxpensetwidth}, \helpref{wxPen::SetStipple}{wxpensetstipple}
132
5873607e
VZ
133\perlnote{Constructors supported by wxPerl are:\par
134\begin{itemize}
135\item{Wx::Pen->new( colour, width, style )}
136\item{Wx::Pen->new( colourName, width, style )}
137\item{Wx::Pen->new( stipple, width )}
138\end{itemize}
139}
140
a660d684
KB
141\membersection{wxPen::\destruct{wxPen}}
142
143\func{}{\destruct{wxPen}}{\void}
144
145Destructor.
146
147\wxheading{Remarks}
148
149The destructor may not delete the underlying pen object of the native windowing
150system, since wxBrush uses a reference counting system for efficiency.
151
152Although all remaining pens are deleted when the application exits,
153the application should try to clean up all pens itself. This is because
154wxWindows cannot know if a pointer to the pen object is stored in an
155application data structure, and there is a risk of double deletion.
156
157\membersection{wxPen::GetCap}\label{wxpengetcap}
158
159\constfunc{int}{GetCap}{\void}
160
161Returns the pen cap style, which may be one of {\bf wxCAP\_ROUND}, {\bf wxCAP\_PROJECTING} and
162\rtfsp{\bf wxCAP\_BUTT}. The default is {\bf wxCAP\_ROUND}.
163
164\wxheading{See also}
165
166\helpref{wxPen::SetCap}{wxpensetcap}
167
168\membersection{wxPen::GetColour}\label{wxpengetcolour}
169
170\constfunc{wxColour\&}{GetColour}{\void}
171
172Returns a reference to the pen colour.
173
174\wxheading{See also}
175
176\helpref{wxPen::SetColour}{wxpensetcolour}
177
178\membersection{wxPen::GetDashes}\label{wxpengetdashes}
179
180\constfunc{int}{GetDashes}{\param{wxDash**}{ dashes}}
181
182Gets an array of dashes (defined as char in X, DWORD under Windows).
183{\it dashes} is a pointer to the internal array. Do not deallocate or store this pointer.
184The function returns the number of dashes associated with this pen.
185
186\wxheading{See also}
187
188\helpref{wxPen::SetDashes}{wxpensetdashes}
189
190\membersection{wxPen::GetJoin}\label{wxpengetjoin}
191
192\constfunc{int}{GetJoin}{\void}
193
194Returns the pen join style, which may be one of {\bf wxJOIN\_BEVEL}, {\bf wxJOIN\_ROUND} and
195\rtfsp{\bf wxJOIN\_MITER}. The default is {\bf wxJOIN\_ROUND}.
196
197\wxheading{See also}
198
199\helpref{wxPen::SetJoin}{wxpensetjoin}
200
201\membersection{wxPen::GetStipple}\label{wxpengetstipple}
202
203\constfunc{wxBitmap* }{GetStipple}{\void}
204
205Gets a pointer to the stipple bitmap.
206
207\wxheading{See also}
208
209\helpref{wxPen::SetStipple}{wxpensetstipple}
210
211\membersection{wxPen::GetStyle}\label{wxpengetstyle}
212
213\constfunc{int}{GetStyle}{\void}
214
215Returns the pen style.
216
217\wxheading{See also}
218
219\helpref{wxPen::wxPen}{wxpenconstr}, \helpref{wxPen::SetStyle}{wxpensetstyle}
220
221\membersection{wxPen::GetWidth}\label{wxpengetwidth}
222
223\constfunc{int}{GetWidth}{\void}
224
225Returns the pen width.
226
227\wxheading{See also}
228
229\helpref{wxPen::SetWidth}{wxpensetwidth}
230
231\membersection{wxPen::Ok}\label{wxpenok}
232
233\constfunc{bool}{Ok}{\void}
234
235Returns TRUE if the pen is initialised.
236
237\membersection{wxPen::SetCap}\label{wxpensetcap}
238
239\func{void}{SetCap}{\param{int}{ capStyle}}
240
241Sets the pen cap style, which may be one of {\bf wxCAP\_ROUND}, {\bf wxCAP\_PROJECTING} and
242\rtfsp{\bf wxCAP\_BUTT}. The default is {\bf wxCAP\_ROUND}.
243
244\wxheading{See also}
245
246\helpref{wxPen::GetCap}{wxpengetcap}
247
248\membersection{wxPen::SetColour}\label{wxpensetcolour}
249
250\func{void}{SetColour}{\param{wxColour\&}{ colour}}
251
252\func{void}{SetColour}{\param{const wxString\& }{colourName}}
253
eaaa6a06 254\func{void}{SetColour}{\param{int}{ red}, \param{int}{ green}, \param{int}{ blue}}
a660d684
KB
255
256The pen's colour is changed to the given colour.
257
258\wxheading{See also}
259
260\helpref{wxPen::GetColour}{wxpengetcolour}
261
262\membersection{wxPen::SetDashes}\label{wxpensetdashes}
263
264\func{void}{SetDashes}{\param{int }{n}, \param{wxDash*}{ dashes}}
265
266Associates an array of pointers to dashes (defined as char in X, DWORD under Windows)
267with the pen. The array is not deallocated by wxPen, but neither must it be
268deallocated by the calling application until the pen is deleted or this
269function is called with a NULL array.
270
5b6aa0ff 271%TODO: describe in detail.
a660d684
KB
272\wxheading{See also}
273
274\helpref{wxPen::GetDashes}{wxpengetdashes}
275
276\membersection{wxPen::SetJoin}\label{wxpensetjoin}
277
278\func{void}{SetJoin}{\param{int}{join\_style}}
279
280Sets the pen join style, which may be one of {\bf wxJOIN\_BEVEL}, {\bf wxJOIN\_ROUND} and
281\rtfsp{\bf wxJOIN\_MITER}. The default is {\bf wxJOIN\_ROUND}.
282
283\wxheading{See also}
284
285\helpref{wxPen::GetJoin}{wxpengetjoin}
286
287\membersection{wxPen::SetStipple}\label{wxpensetstipple}
288
289\func{void}{SetStipple}{\param{wxBitmap* }{stipple}}
290
291Sets the bitmap for stippling.
292
293\wxheading{See also}
294
295\helpref{wxPen::GetStipple}{wxpengetstipple}
296
297\membersection{wxPen::SetStyle}\label{wxpensetstyle}
298
299\func{void}{SetStyle}{\param{int}{ style}}
300
301Set the pen style.
302
303\wxheading{See also}
304
305\helpref{wxPen::wxPen}{wxpenconstr}
306
307\membersection{wxPen::SetWidth}\label{wxpensetwidth}
308
eaaa6a06 309\func{void}{SetWidth}{\param{int}{ width}}
a660d684
KB
310
311Sets the pen width.
312
313\wxheading{See also}
314
315\helpref{wxPen::GetWidth}{wxpengetwidth}
316
317\membersection{wxPen::operator $=$}\label{wxpenassignment}
318
319\func{wxPen\&}{operator $=$}{\param{const wxPen\& }{pen}}
320
321Assignment operator, using reference counting. Returns a reference
322to `this'.
323
324\membersection{wxPen::operator $==$}\label{wxpenequals}
325
326\func{bool}{operator $==$}{\param{const wxPen\& }{pen}}
327
328Equality operator. Two pens are equal if they contain pointers
329to the same underlying pen data. It does not compare each attribute,
330so two independently-created pens using the same parameters will
331fail the test.
332
333\membersection{wxPen::operator $!=$}\label{wxpennotequals}
334
335\func{bool}{operator $!=$}{\param{const wxPen\& }{pen}}
336
337Inequality operator. Two pens are not equal if they contain pointers
338to different underlying pen data. It does not compare each attribute.
339
340\section{\class{wxPenList}}\label{wxpenlist}
341
342There is only one instance of this class: {\bf wxThePenList}. Use
343this object to search for a previously created pen of the desired
344type and create it if not already found. In some windowing systems,
345the pen may be a scarce resource, so it can pay to reuse old
346resources if possible. When an application finishes, all pens will
347be deleted and their resources freed, eliminating the possibility of
348`memory leaks'. However, it is best not to rely on this automatic
349cleanup because it can lead to double deletion in some circumstances.
350
351There are two mechanisms in recent versions of wxWindows which make the
352pen list less useful than it once was. Under Windows, scarce resources
353are cleaned up internally if they are not being used. Also, a referencing
354counting mechanism applied to all GDI objects means that some sharing
355of underlying resources is possible. You don't have to keep track of pointers,
356working out when it is safe delete a pen, because the referencing counting does
357it for you. For example, you can set a pen in a device context, and then
358immediately delete the pen you passed, because the pen is `copied'.
359
360So you may find it easier to ignore the pen list, and instead create
361and copy pens as you see fit. If your Windows resource meter suggests
362your application is using too many resources, you can resort to using
363GDI lists to share objects explicitly.
364
365The only compelling use for the pen list is for wxWindows to keep
366track of pens in order to clean them up on exit. It is also kept for
367backward compatibility with earlier versions of wxWindows.
368
369\wxheading{See also}
370
371\helpref{wxPen}{wxpen}
372
373\latexignore{\rtfignore{\wxheading{Members}}}
374
375\membersection{wxPenList::wxPenList}
376
377\func{void}{wxPenList}{\void}
378
379Constructor. The application should not construct its own pen list:
380use the object pointer {\bf wxThePenList}.
381
382\membersection{wxPenList::AddPen}\label{wxpenlistaddpen}
383
384\func{void}{AddPen}{\param{wxPen*}{ pen}}
385
386Used internally by wxWindows to add a pen to the list.
387
388\membersection{wxPenList::FindOrCreatePen}\label{wxpenlistfindorcreatepen}
389
eaaa6a06 390\func{wxPen*}{FindOrCreatePen}{\param{const wxColour\& }{colour}, \param{int}{ width}, \param{int}{ style}}
a660d684
KB
391
392Finds a pen with the specified attributes and returns it, else creates a new pen, adds it
393to the pen list, and returns it.
394
eaaa6a06 395\func{wxPen*}{FindOrCreatePen}{\param{const wxString\& }{colourName}, \param{int}{ width}, \param{int}{ style}}
a660d684
KB
396
397Finds a pen with the specified attributes and returns it, else creates a new pen, adds it
398to the pen list, and returns it.
399
400\wxheading{Parameters}
401
402\docparam{colour}{Colour object.}
403
dbdb39b2
JS
404\docparam{colourName}{Colour name, which should be in the \helpref{colour database}{wxcolourdatabase}.}
405
406\docparam{width}{Width of pen.}
a660d684
KB
407
408\docparam{style}{Pen style. See \helpref{wxPen::wxPen}{wxpenconstr} for a list of styles.}
409
410\membersection{wxPenList::RemovePen}\label{wxpenlistremovepen}
411
412\func{void}{RemovePen}{\param{wxPen*}{ pen}}
413
414Used by wxWindows to remove a pen from the list.
415
416