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