First attempt to document raw bitmap access
[wxWidgets.git] / interface / 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$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
8024723d
FM
9/**
10 The possible styles for a wxPen.
11*/
12enum 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*/
73enum 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*/
88enum 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*/
138class wxPen : public wxGDIObject
139{
140public:
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*/
349wxPen wxNullPen;
350
e54c96f1 351/**
231b9591 352 Red pen.
e54c96f1 353*/
4d7b68d1 354wxPen* wxRED_PEN;
e54c96f1
FM
355
356/**
231b9591 357 Cyan pen.
e54c96f1 358*/
4d7b68d1 359wxPen* wxCYAN_PEN;
e54c96f1
FM
360
361/**
231b9591 362 Green pen.
e54c96f1 363*/
4d7b68d1 364wxPen* wxGREEN_PEN;
e54c96f1
FM
365
366/**
231b9591 367 Black pen.
e54c96f1 368*/
4d7b68d1 369wxPen* wxBLACK_PEN;
e54c96f1
FM
370
371/**
231b9591 372 White pen.
e54c96f1 373*/
4d7b68d1 374wxPen* wxWHITE_PEN;
e54c96f1
FM
375
376/**
231b9591 377 Transparent pen.
e54c96f1 378*/
4d7b68d1 379wxPen* wxTRANSPARENT_PEN;
e54c96f1
FM
380
381/**
231b9591 382 Black dashed pen.
e54c96f1 383*/
4d7b68d1 384wxPen* wxBLACK_DASHED_PEN;
e54c96f1
FM
385
386/**
231b9591 387 Grey pen.
e54c96f1 388*/
4d7b68d1 389wxPen* wxGREY_PEN;
e54c96f1
FM
390
391/**
231b9591 392 Medium-grey pen.
e54c96f1 393*/
4d7b68d1 394wxPen* wxMEDIUM_GREY_PEN;
e54c96f1
FM
395
396/**
231b9591 397 Light-grey pen.
e54c96f1 398*/
4d7b68d1 399wxPen* 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*/
442class wxPenList
443{
444public:
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*/
470wxPenList* wxThePenList;
471