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