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