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