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