Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: pen.h | |
8024723d | 3 | // Purpose: interface of wxPen* classes |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
8024723d FM |
9 | /** |
10 | The possible styles for a wxPen. | |
11 | */ | |
12 | enum wxPenStyle | |
13 | { | |
1413ac04 FM |
14 | wxPENSTYLE_INVALID = -1, |
15 | ||
8024723d FM |
16 | wxPENSTYLE_SOLID, |
17 | /**< Solid style. */ | |
18 | ||
19 | wxPENSTYLE_DOT, | |
20 | /**< Dotted style. */ | |
21 | ||
22 | wxPENSTYLE_LONG_DASH, | |
23 | /**< Long dashed style. */ | |
24 | ||
25 | wxPENSTYLE_SHORT_DASH, | |
26 | /**< Short dashed style. */ | |
27 | ||
28 | wxPENSTYLE_DOT_DASH, | |
29 | /**< Dot and dash style. */ | |
30 | ||
31 | wxPENSTYLE_USER_DASH, | |
32 | /**< Use the user dashes: see wxPen::SetDashes. */ | |
33 | ||
34 | wxPENSTYLE_TRANSPARENT, | |
35 | /**< No pen is used. */ | |
36 | ||
37 | wxPENSTYLE_STIPPLE_MASK_OPAQUE, | |
38 | /**< @todo WHAT's this? */ | |
39 | ||
40 | wxPENSTYLE_STIPPLE_MASK, | |
41 | /**< @todo WHAT's this? */ | |
42 | ||
43 | wxPENSTYLE_STIPPLE, | |
44 | /**< Use the stipple bitmap. */ | |
45 | ||
46 | wxPENSTYLE_BDIAGONAL_HATCH, | |
47 | /**< Backward diagonal hatch. */ | |
48 | ||
49 | wxPENSTYLE_CROSSDIAG_HATCH, | |
50 | /**< Cross-diagonal hatch. */ | |
51 | ||
52 | wxPENSTYLE_FDIAGONAL_HATCH, | |
53 | /**< Forward diagonal hatch. */ | |
54 | ||
55 | wxPENSTYLE_CROSS_HATCH, | |
56 | /**< Cross hatch. */ | |
57 | ||
58 | wxPENSTYLE_HORIZONTAL_HATCH, | |
59 | /**< Horizontal hatch. */ | |
60 | ||
61 | wxPENSTYLE_VERTICAL_HATCH, | |
62 | /**< Vertical hatch. */ | |
63 | ||
64 | wxPENSTYLE_FIRST_HATCH = wxPENSTYLE_BDIAGONAL_HATCH, | |
1413ac04 | 65 | wxPENSTYLE_LAST_HATCH = wxPENSTYLE_VERTICAL_HATCH |
8024723d FM |
66 | }; |
67 | ||
68 | /** | |
69 | The possible join values of a wxPen. | |
70 | ||
71 | @todo use wxPENJOIN_ prefix | |
72 | */ | |
73 | enum wxPenJoin | |
74 | { | |
75 | wxJOIN_INVALID = -1, | |
76 | ||
77 | wxJOIN_BEVEL = 120, | |
78 | wxJOIN_MITER, | |
79 | wxJOIN_ROUND, | |
80 | }; | |
81 | ||
82 | ||
83 | /** | |
84 | The possible cap values of a wxPen. | |
85 | ||
86 | @todo use wxPENCAP_ prefix | |
87 | */ | |
88 | enum wxPenCap | |
89 | { | |
90 | wxCAP_INVALID = -1, | |
91 | ||
92 | wxCAP_ROUND = 130, | |
93 | wxCAP_PROJECTING, | |
94 | wxCAP_BUTT | |
95 | }; | |
96 | ||
97 | ||
98 | ||
23324ae1 FM |
99 | /** |
100 | @class wxPen | |
101 | @wxheader{pen.h} | |
7c913512 | 102 | |
23324ae1 | 103 | A pen is a drawing tool for drawing outlines. It is used for drawing |
8024723d FM |
104 | lines and painting the outline of rectangles, ellipses, etc. |
105 | It has a colour, a width and a style. | |
106 | ||
4d7b68d1 | 107 | @note On a monochrome display, wxWidgets shows all non-white pens as black. |
8024723d FM |
108 | |
109 | Do not initialize objects on the stack before the program commences, | |
110 | since other required structures may not have been set up yet. | |
74bf4e64 | 111 | Instead, define global pointers to objects and create them in wxApp::OnInit() |
8024723d FM |
112 | or when required. |
113 | ||
114 | An application may wish to dynamically create pens with different characteristics, | |
115 | and there is the consequent danger that a large number of duplicate pens will | |
116 | be created. Therefore an application may wish to get a pointer to a pen by using | |
74bf4e64 | 117 | the global list of pens ::wxThePenList, and calling the member function |
8024723d | 118 | wxPenList::FindOrCreatePen(). |
4d7b68d1 | 119 | See wxPenList for more info. |
8024723d | 120 | |
74bf4e64 FM |
121 | This class uses @ref overview_refcount "reference counting and copy-on-write" internally |
122 | so that assignments between two instances of this class are very cheap. | |
8024723d FM |
123 | You can therefore use actual objects instead of pointers without efficiency problems. |
124 | If an instance of this class is changed it will create its own data internally | |
125 | so that other instances, which previously shared the data using the reference | |
126 | counting, are not affected. | |
7c913512 | 127 | |
23324ae1 FM |
128 | @library{wxcore} |
129 | @category{gdi} | |
7c913512 | 130 | |
23324ae1 | 131 | @stdobjects |
4d7b68d1 FM |
132 | ::wxNullPen, ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN, ::wxBLACK_PEN, ::wxWHITE_PEN, |
133 | ::wxTRANSPARENT_PEN, ::wxBLACK_DASHED_PEN, ::wxGREY_PEN, ::wxMEDIUM_GREY_PEN, | |
134 | ::wxLIGHT_GREY_PEN | |
7c913512 | 135 | |
74bf4e64 | 136 | @see wxPenList, wxDC, wxDC::SetPen() |
23324ae1 FM |
137 | */ |
138 | class wxPen : public wxGDIObject | |
139 | { | |
140 | public: | |
23324ae1 | 141 | /** |
74bf4e64 | 142 | Default constructor. The pen will be uninitialised, and IsOk() will return @false. |
8024723d FM |
143 | */ |
144 | wxPen(); | |
145 | ||
146 | /** | |
147 | Constructs a pen from a colour object, pen width and style. | |
8024723d | 148 | |
7c913512 | 149 | @param colour |
4cc4bfaf | 150 | A colour object. |
7c913512 | 151 | @param width |
4cc4bfaf | 152 | Pen width. Under Windows, the pen width cannot be greater than 1 if |
74bf4e64 | 153 | the style is @c wxDOT, @c wxLONG_DASH, @c wxSHORT_DASH, @c wxDOT_DASH, or @c wxUSER_DASH. |
7c913512 | 154 | @param style |
8024723d FM |
155 | The style may be one of the ::wxPenStyle values. |
156 | ||
23324ae1 | 157 | @remarks Different versions of Windows and different versions of other |
4cc4bfaf FM |
158 | platforms support very different subsets of the styles |
159 | above - there is no similarity even between Windows95 | |
160 | and Windows98 - so handle with care. | |
8024723d | 161 | |
74bf4e64 FM |
162 | @see SetStyle(), SetColour(), SetWidth() |
163 | */ | |
164 | wxPen(const wxColour& colour, int width = 1, wxPenStyle style = wxPENSTYLE_SOLID); | |
165 | ||
166 | /** | |
167 | Constructs a stippled pen from a stipple bitmap and a width. | |
168 | ||
169 | @param width | |
170 | Pen width. Under Windows, the pen width cannot be greater than 1 if | |
171 | the style is @c wxDOT, @c wxLONG_DASH, @c wxSHORT_DASH, @c wxDOT_DASH, or @c wxUSER_DASH. | |
172 | @param stipple | |
173 | A stipple bitmap. | |
174 | ||
175 | @see SetWidth(), SetStipple() | |
176 | */ | |
177 | wxPen(const wxBitmap& stipple, int width); | |
178 | ||
179 | /** | |
180 | Copy constructor, uses @ref overview_refcount. | |
181 | ||
182 | @param pen | |
183 | A pointer or reference to a pen to copy. | |
23324ae1 | 184 | */ |
7c913512 | 185 | wxPen(const wxPen& pen); |
23324ae1 FM |
186 | |
187 | /** | |
188 | Destructor. | |
74bf4e64 | 189 | @see @ref overview_refcount_destruct "reference-counted object destruction" |
8024723d | 190 | |
23324ae1 | 191 | @remarks Although all remaining pens are deleted when the application |
4cc4bfaf FM |
192 | exits, the application should try to clean up all pens |
193 | itself. This is because wxWidgets cannot know if a | |
194 | pointer to the pen object is stored in an application | |
195 | data structure, and there is a risk of double deletion. | |
23324ae1 FM |
196 | */ |
197 | ~wxPen(); | |
198 | ||
199 | /** | |
74bf4e64 FM |
200 | Returns the pen cap style, which may be one of @c wxCAP_ROUND, @c |
201 | wxCAP_PROJECTING and @c wxCAP_BUTT. | |
202 | ||
203 | The default is @c wxCAP_ROUND. | |
8024723d | 204 | |
4cc4bfaf | 205 | @see SetCap() |
23324ae1 | 206 | */ |
231b9591 | 207 | virtual wxPenCap GetCap() const; |
23324ae1 FM |
208 | |
209 | /** | |
210 | Returns a reference to the pen colour. | |
8024723d | 211 | |
4cc4bfaf | 212 | @see SetColour() |
23324ae1 | 213 | */ |
231b9591 | 214 | virtual wxColour GetColour() const; |
23324ae1 FM |
215 | |
216 | /** | |
217 | Gets an array of dashes (defined as char in X, DWORD under Windows). | |
4cc4bfaf | 218 | @a dashes is a pointer to the internal array. Do not deallocate or store this |
23324ae1 | 219 | pointer. |
74bf4e64 FM |
220 | |
221 | @return The number of dashes associated with this pen. | |
8024723d | 222 | |
4cc4bfaf | 223 | @see SetDashes() |
23324ae1 | 224 | */ |
231b9591 | 225 | virtual int GetDashes(wxDash** dashes) const; |
23324ae1 FM |
226 | |
227 | /** | |
74bf4e64 FM |
228 | Returns the pen join style, which may be one of @c wxJOIN_BEVEL, @c |
229 | wxJOIN_ROUND and @c wxJOIN_MITER. | |
230 | ||
231 | The default is @c wxJOIN_ROUND. | |
8024723d | 232 | |
4cc4bfaf | 233 | @see SetJoin() |
23324ae1 | 234 | */ |
231b9591 | 235 | virtual wxPenJoin GetJoin() const; |
23324ae1 FM |
236 | |
237 | /** | |
238 | Gets a pointer to the stipple bitmap. | |
8024723d | 239 | |
4cc4bfaf | 240 | @see SetStipple() |
23324ae1 | 241 | */ |
231b9591 | 242 | virtual wxBitmap* GetStipple() const; |
23324ae1 FM |
243 | |
244 | /** | |
245 | Returns the pen style. | |
8024723d | 246 | |
4cc4bfaf | 247 | @see wxPen(), SetStyle() |
23324ae1 | 248 | */ |
231b9591 | 249 | virtual wxPenStyle GetStyle() const; |
23324ae1 FM |
250 | |
251 | /** | |
252 | Returns the pen width. | |
8024723d | 253 | |
4cc4bfaf | 254 | @see SetWidth() |
23324ae1 | 255 | */ |
231b9591 | 256 | virtual int GetWidth() const; |
23324ae1 FM |
257 | |
258 | /** | |
259 | Returns @true if the pen is initialised. | |
260 | */ | |
328f5751 | 261 | bool IsOk() const; |
23324ae1 FM |
262 | |
263 | /** | |
74bf4e64 FM |
264 | Sets the pen cap style, which may be one of @c wxCAP_ROUND, @c wxCAP_PROJECTING |
265 | and @c wxCAP_BUTT. The default is @c wxCAP_ROUND. | |
8024723d | 266 | |
4cc4bfaf | 267 | @see GetCap() |
23324ae1 | 268 | */ |
231b9591 | 269 | virtual void SetCap(wxPenCap capStyle); |
23324ae1 FM |
270 | |
271 | //@{ | |
272 | /** | |
273 | The pen's colour is changed to the given colour. | |
8024723d | 274 | |
4cc4bfaf | 275 | @see GetColour() |
23324ae1 | 276 | */ |
231b9591 FM |
277 | virtual void SetColour(wxColour& colour); |
278 | virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue); | |
23324ae1 FM |
279 | //@} |
280 | ||
281 | /** | |
282 | Associates an array of pointers to dashes (defined as char in X, DWORD under | |
74bf4e64 FM |
283 | Windows) with the pen. |
284 | ||
285 | The array is not deallocated by wxPen, but neither must it be deallocated by | |
286 | the calling application until the pen is deleted or this function is called | |
287 | with a @NULL array. | |
8024723d | 288 | |
4cc4bfaf | 289 | @see GetDashes() |
23324ae1 | 290 | */ |
231b9591 | 291 | virtual void SetDashes(int n, wxDash* dashes); |
23324ae1 FM |
292 | |
293 | /** | |
74bf4e64 FM |
294 | Sets the pen join style, which may be one of @c wxJOIN_BEVEL, @c wxJOIN_ROUND |
295 | and @c wxJOIN_MITER. | |
296 | ||
297 | The default is @c wxJOIN_ROUND. | |
8024723d | 298 | |
4cc4bfaf | 299 | @see GetJoin() |
23324ae1 | 300 | */ |
231b9591 | 301 | virtual void SetJoin(wxPenJoin join_style); |
23324ae1 FM |
302 | |
303 | /** | |
304 | Sets the bitmap for stippling. | |
8024723d | 305 | |
4cc4bfaf | 306 | @see GetStipple() |
23324ae1 | 307 | */ |
231b9591 | 308 | virtual void SetStipple(wxBitmap* stipple); |
23324ae1 FM |
309 | |
310 | /** | |
311 | Set the pen style. | |
8024723d | 312 | |
4cc4bfaf | 313 | @see wxPen() |
23324ae1 | 314 | */ |
231b9591 | 315 | virtual void SetStyle(wxPenStyle style); |
23324ae1 FM |
316 | |
317 | /** | |
318 | Sets the pen width. | |
8024723d | 319 | |
4cc4bfaf | 320 | @see GetWidth() |
23324ae1 | 321 | */ |
231b9591 | 322 | virtual void SetWidth(int width); |
23324ae1 FM |
323 | |
324 | /** | |
325 | Inequality operator. | |
4d7b68d1 | 326 | |
74bf4e64 | 327 | See @ref overview_refcount_equality "reference-counted object comparison" for |
23324ae1 FM |
328 | more info. |
329 | */ | |
330 | bool operator !=(const wxPen& pen); | |
331 | ||
332 | /** | |
74bf4e64 | 333 | Assignment operator, using @ref overview_refcount. |
23324ae1 FM |
334 | */ |
335 | wxPen operator =(const wxPen& pen); | |
336 | ||
337 | /** | |
338 | Equality operator. | |
4d7b68d1 | 339 | |
74bf4e64 | 340 | See @ref overview_refcount_equality "reference-counted object comparison" for |
23324ae1 FM |
341 | more info. |
342 | */ | |
343 | bool operator ==(const wxPen& pen); | |
344 | }; | |
e54c96f1 | 345 | |
e54c96f1 | 346 | /** |
231b9591 | 347 | An empty pen. |
e54c96f1 FM |
348 | */ |
349 | wxPen wxNullPen; | |
350 | ||
e54c96f1 | 351 | /** |
231b9591 | 352 | Red pen. |
e54c96f1 | 353 | */ |
4d7b68d1 | 354 | wxPen* wxRED_PEN; |
e54c96f1 FM |
355 | |
356 | /** | |
231b9591 | 357 | Cyan pen. |
e54c96f1 | 358 | */ |
4d7b68d1 | 359 | wxPen* wxCYAN_PEN; |
e54c96f1 FM |
360 | |
361 | /** | |
231b9591 | 362 | Green pen. |
e54c96f1 | 363 | */ |
4d7b68d1 | 364 | wxPen* wxGREEN_PEN; |
e54c96f1 FM |
365 | |
366 | /** | |
231b9591 | 367 | Black pen. |
e54c96f1 | 368 | */ |
4d7b68d1 | 369 | wxPen* wxBLACK_PEN; |
e54c96f1 FM |
370 | |
371 | /** | |
231b9591 | 372 | White pen. |
e54c96f1 | 373 | */ |
4d7b68d1 | 374 | wxPen* wxWHITE_PEN; |
e54c96f1 FM |
375 | |
376 | /** | |
231b9591 | 377 | Transparent pen. |
e54c96f1 | 378 | */ |
4d7b68d1 | 379 | wxPen* wxTRANSPARENT_PEN; |
e54c96f1 FM |
380 | |
381 | /** | |
231b9591 | 382 | Black dashed pen. |
e54c96f1 | 383 | */ |
4d7b68d1 | 384 | wxPen* wxBLACK_DASHED_PEN; |
e54c96f1 FM |
385 | |
386 | /** | |
231b9591 | 387 | Grey pen. |
e54c96f1 | 388 | */ |
4d7b68d1 | 389 | wxPen* wxGREY_PEN; |
e54c96f1 FM |
390 | |
391 | /** | |
231b9591 | 392 | Medium-grey pen. |
e54c96f1 | 393 | */ |
4d7b68d1 | 394 | wxPen* wxMEDIUM_GREY_PEN; |
e54c96f1 FM |
395 | |
396 | /** | |
231b9591 | 397 | Light-grey pen. |
e54c96f1 | 398 | */ |
4d7b68d1 | 399 | wxPen* wxLIGHT_GREY_PEN; |
e54c96f1 FM |
400 | |
401 | ||
8024723d FM |
402 | |
403 | /** | |
404 | @class wxPenList | |
405 | @wxheader{gdicmn.h} | |
406 | ||
407 | There is only one instance of this class: ::wxThePenList. | |
408 | Use this object to search for a previously created pen of the desired | |
409 | type and create it if not already found. In some windowing systems, | |
410 | the pen may be a scarce resource, so it can pay to reuse old | |
411 | resources if possible. When an application finishes, all pens will | |
412 | be deleted and their resources freed, eliminating the possibility of | |
413 | 'memory leaks'. However, it is best not to rely on this automatic | |
414 | cleanup because it can lead to double deletion in some circumstances. | |
415 | ||
416 | There are two mechanisms in recent versions of wxWidgets which make the | |
417 | pen list less useful than it once was. Under Windows, scarce resources | |
418 | are cleaned up internally if they are not being used. Also, a referencing | |
419 | counting mechanism applied to all GDI objects means that some sharing | |
420 | of underlying resources is possible. You don't have to keep track of pointers, | |
421 | working out when it is safe delete a pen, because the referencing counting does | |
422 | it for you. For example, you can set a pen in a device context, and then | |
423 | immediately delete the pen you passed, because the pen is 'copied'. | |
424 | ||
425 | So you may find it easier to ignore the pen list, and instead create | |
426 | and copy pens as you see fit. If your Windows resource meter suggests | |
427 | your application is using too many resources, you can resort to using | |
428 | GDI lists to share objects explicitly. | |
429 | ||
430 | The only compelling use for the pen list is for wxWidgets to keep | |
431 | track of pens in order to clean them up on exit. It is also kept for | |
432 | backward compatibility with earlier versions of wxWidgets. | |
433 | ||
434 | @library{wxcore} | |
435 | @category{gdi} | |
436 | ||
437 | @stdobjects | |
438 | ::wxThePenList | |
439 | ||
440 | @see wxPen | |
441 | */ | |
442 | class wxPenList | |
443 | { | |
444 | public: | |
445 | /** | |
446 | Constructor. The application should not construct its own pen list: | |
447 | use the object pointer ::wxThePenList. | |
448 | */ | |
449 | wxPenList(); | |
450 | ||
451 | /** | |
452 | Finds a pen with the specified attributes and returns it, else creates a | |
453 | new pen, adds it to the pen list, and returns it. | |
454 | ||
455 | @param colour | |
456 | Colour object. | |
457 | @param width | |
458 | Width of pen. | |
459 | @param style | |
460 | Pen style. See ::wxPenStyle for a list of styles. | |
461 | */ | |
5d2d8f6a VZ |
462 | wxPen* FindOrCreatePen(const wxColour& colour, |
463 | int width = 1, | |
464 | wxPenStyle style = wxPENSTYLE_SOLID); | |
8024723d FM |
465 | }; |
466 | ||
467 | /** | |
468 | The global list of wxPen objects ready to be re-used (for better performances). | |
469 | */ | |
470 | wxPenList* wxThePenList; | |
471 |