]> git.saurik.com Git - wxWidgets.git/blame - interface/pen.h
don't blit too much when copying static box border in OnPaint()
[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
107 On a monochrome display, wxWidgets shows all non-white pens as black.
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.
111 Instead, define global pointers to objects and create them in wxApp::OnInit
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
117 the global list of pens wxThePenList, and calling the member function
118 wxPenList::FindOrCreatePen().
119 See the entry for wxPenList.
120
121 This class uses reference counting and copy-on-write internally so that
122 assignments between two instances of this class are very cheap.
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
8024723d
FM
132 ::wxNullPen, ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN, ::wxBLACK_PEN,
133 ::wxWHITE_PEN, ::wxTRANSPARENT_PEN, ::wxBLACK_DASHED_PEN, ::wxGREY_PEN,
134 ::wxMEDIUM_GREY_PEN, ::wxLIGHT_GREY_PEN
7c913512 135
e54c96f1 136 @see wxPenList, wxDC, wxDC::SetPen
23324ae1
FM
137*/
138class wxPen : public wxGDIObject
139{
140public:
23324ae1 141 /**
8024723d
FM
142 Default constructor. The pen will be uninitialised, and wxPen:IsOk will return @false.
143 */
144 wxPen();
145
146 /**
147 Constructs a pen from a colour object, pen width and style.
148 */
1413ac04 149 wxPen(const wxColour& colour, int width = 1, wxPenStyle style = wxPENSTYLE_SOLID);
8024723d
FM
150
151 /**
152 Constructs a stippled pen from a stipple bitmap and a width.
153 */
154 wxPen(const wxBitmap& stipple, int width);
155
156 /**
157 Copy constructor, uses @ref overview_refcount "reference counting".
158
7c913512 159 @param colour
4cc4bfaf 160 A colour object.
7c913512 161 @param colourName
4cc4bfaf 162 A colour name.
7c913512 163 @param width
4cc4bfaf
FM
164 Pen width. Under Windows, the pen width cannot be greater than 1 if
165 the style is wxDOT, wxLONG_DASH, wxSHORT_DASH, wxDOT_DASH, or wxUSER_DASH.
7c913512 166 @param stipple
4cc4bfaf 167 A stipple bitmap.
7c913512 168 @param pen
4cc4bfaf 169 A pointer or reference to a pen to copy.
7c913512 170 @param style
8024723d
FM
171 The style may be one of the ::wxPenStyle values.
172
23324ae1 173 @remarks Different versions of Windows and different versions of other
4cc4bfaf
FM
174 platforms support very different subsets of the styles
175 above - there is no similarity even between Windows95
176 and Windows98 - so handle with care.
8024723d 177
4cc4bfaf 178 @see SetStyle(), SetColour(), SetWidth(), SetStipple()
23324ae1 179 */
7c913512 180 wxPen(const wxPen& pen);
23324ae1
FM
181
182 /**
183 Destructor.
184 See @ref overview_refcountdestruct "reference-counted object destruction" for
185 more info.
8024723d 186
23324ae1 187 @remarks Although all remaining pens are deleted when the application
4cc4bfaf
FM
188 exits, the application should try to clean up all pens
189 itself. This is because wxWidgets cannot know if a
190 pointer to the pen object is stored in an application
191 data structure, and there is a risk of double deletion.
23324ae1
FM
192 */
193 ~wxPen();
194
195 /**
196 Returns the pen cap style, which may be one of @b wxCAP_ROUND, @b
197 wxCAP_PROJECTING and
198 @b wxCAP_BUTT. The default is @b wxCAP_ROUND.
8024723d 199
4cc4bfaf 200 @see SetCap()
23324ae1 201 */
8024723d 202 wxPenCap GetCap() const;
23324ae1
FM
203
204 /**
205 Returns a reference to the pen colour.
8024723d 206
4cc4bfaf 207 @see SetColour()
23324ae1 208 */
328f5751 209 wxColour GetColour() const;
23324ae1
FM
210
211 /**
212 Gets an array of dashes (defined as char in X, DWORD under Windows).
4cc4bfaf 213 @a dashes is a pointer to the internal array. Do not deallocate or store this
23324ae1
FM
214 pointer.
215 The function returns the number of dashes associated with this pen.
8024723d 216
4cc4bfaf 217 @see SetDashes()
23324ae1 218 */
328f5751 219 int GetDashes(wxDash** dashes) const;
23324ae1
FM
220
221 /**
222 Returns the pen join style, which may be one of @b wxJOIN_BEVEL, @b
223 wxJOIN_ROUND and
224 @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
8024723d 225
4cc4bfaf 226 @see SetJoin()
23324ae1 227 */
8024723d 228 wxPenJoin GetJoin() const;
23324ae1
FM
229
230 /**
231 Gets a pointer to the stipple bitmap.
8024723d 232
4cc4bfaf 233 @see SetStipple()
23324ae1 234 */
328f5751 235 wxBitmap* GetStipple() const;
23324ae1
FM
236
237 /**
238 Returns the pen style.
8024723d 239
4cc4bfaf 240 @see wxPen(), SetStyle()
23324ae1 241 */
8024723d 242 wxPenStyle GetStyle() const;
23324ae1
FM
243
244 /**
245 Returns the pen width.
8024723d 246
4cc4bfaf 247 @see SetWidth()
23324ae1 248 */
328f5751 249 int GetWidth() const;
23324ae1
FM
250
251 /**
252 Returns @true if the pen is initialised.
253 */
328f5751 254 bool IsOk() const;
23324ae1
FM
255
256 /**
257 Sets the pen cap style, which may be one of @b wxCAP_ROUND, @b wxCAP_PROJECTING
258 and
259 @b wxCAP_BUTT. The default is @b wxCAP_ROUND.
8024723d 260
4cc4bfaf 261 @see GetCap()
23324ae1 262 */
8024723d 263 void SetCap(wxPenCap capStyle);
23324ae1
FM
264
265 //@{
266 /**
267 The pen's colour is changed to the given colour.
8024723d 268
4cc4bfaf 269 @see GetColour()
23324ae1
FM
270 */
271 void SetColour(wxColour& colour);
7c913512
FM
272 void SetColour(const wxString& colourName);
273 void SetColour(unsigned char red, unsigned char green,
274 unsigned char blue);
23324ae1
FM
275 //@}
276
277 /**
278 Associates an array of pointers to dashes (defined as char in X, DWORD under
279 Windows)
280 with the pen. The array is not deallocated by wxPen, but neither must it be
281 deallocated by the calling application until the pen is deleted or this
282 function is called with a @NULL array.
8024723d 283
4cc4bfaf 284 @see GetDashes()
23324ae1
FM
285 */
286 void SetDashes(int n, wxDash* dashes);
287
288 /**
289 Sets the pen join style, which may be one of @b wxJOIN_BEVEL, @b wxJOIN_ROUND
290 and
291 @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
8024723d 292
4cc4bfaf 293 @see GetJoin()
23324ae1 294 */
8024723d 295 void SetJoin(wxPenJoin join_style);
23324ae1
FM
296
297 /**
298 Sets the bitmap for stippling.
8024723d 299
4cc4bfaf 300 @see GetStipple()
23324ae1
FM
301 */
302 void SetStipple(wxBitmap* stipple);
303
304 /**
305 Set the pen style.
8024723d 306
4cc4bfaf 307 @see wxPen()
23324ae1 308 */
8024723d 309 void SetStyle(wxPenStyle style);
23324ae1
FM
310
311 /**
312 Sets the pen width.
8024723d 313
4cc4bfaf 314 @see GetWidth()
23324ae1
FM
315 */
316 void SetWidth(int width);
317
318 /**
319 Inequality operator.
320 See @ref overview_refcountequality "reference-counted object comparison" for
321 more info.
322 */
323 bool operator !=(const wxPen& pen);
324
325 /**
326 Assignment operator, using @ref overview_trefcount "reference counting".
327 */
328 wxPen operator =(const wxPen& pen);
329
330 /**
331 Equality operator.
332 See @ref overview_refcountequality "reference-counted object comparison" for
333 more info.
334 */
335 bool operator ==(const wxPen& pen);
336};
e54c96f1 337
e54c96f1
FM
338/**
339 FIXME
340*/
341wxPen wxNullPen;
342
e54c96f1
FM
343/**
344 FIXME
345*/
346wxPen wxRED_PEN;
347
348/**
349 FIXME
350*/
351wxPen wxCYAN_PEN;
352
353/**
354 FIXME
355*/
356wxPen wxGREEN_PEN;
357
358/**
359 FIXME
360*/
361wxPen wxBLACK_PEN;
362
363/**
364 FIXME
365*/
366wxPen wxWHITE_PEN;
367
368/**
369 FIXME
370*/
371wxPen wxTRANSPARENT_PEN;
372
373/**
374 FIXME
375*/
376wxPen wxBLACK_DASHED_PEN;
377
378/**
379 FIXME
380*/
381wxPen wxGREY_PEN;
382
383/**
384 FIXME
385*/
386wxPen wxMEDIUM_GREY_PEN;
387
388/**
389 FIXME
390*/
391wxPen wxLIGHT_GREY_PEN;
392
393
8024723d
FM
394
395/**
396 @class wxPenList
397 @wxheader{gdicmn.h}
398
399 There is only one instance of this class: ::wxThePenList.
400 Use this object to search for a previously created pen of the desired
401 type and create it if not already found. In some windowing systems,
402 the pen may be a scarce resource, so it can pay to reuse old
403 resources if possible. When an application finishes, all pens will
404 be deleted and their resources freed, eliminating the possibility of
405 'memory leaks'. However, it is best not to rely on this automatic
406 cleanup because it can lead to double deletion in some circumstances.
407
408 There are two mechanisms in recent versions of wxWidgets which make the
409 pen list less useful than it once was. Under Windows, scarce resources
410 are cleaned up internally if they are not being used. Also, a referencing
411 counting mechanism applied to all GDI objects means that some sharing
412 of underlying resources is possible. You don't have to keep track of pointers,
413 working out when it is safe delete a pen, because the referencing counting does
414 it for you. For example, you can set a pen in a device context, and then
415 immediately delete the pen you passed, because the pen is 'copied'.
416
417 So you may find it easier to ignore the pen list, and instead create
418 and copy pens as you see fit. If your Windows resource meter suggests
419 your application is using too many resources, you can resort to using
420 GDI lists to share objects explicitly.
421
422 The only compelling use for the pen list is for wxWidgets to keep
423 track of pens in order to clean them up on exit. It is also kept for
424 backward compatibility with earlier versions of wxWidgets.
425
426 @library{wxcore}
427 @category{gdi}
428
429 @stdobjects
430 ::wxThePenList
431
432 @see wxPen
433*/
434class wxPenList
435{
436public:
437 /**
438 Constructor. The application should not construct its own pen list:
439 use the object pointer ::wxThePenList.
440 */
441 wxPenList();
442
443 /**
444 Finds a pen with the specified attributes and returns it, else creates a
445 new pen, adds it to the pen list, and returns it.
446
447 @param colour
448 Colour object.
449 @param width
450 Width of pen.
451 @param style
452 Pen style. See ::wxPenStyle for a list of styles.
453 */
5d2d8f6a
VZ
454 wxPen* FindOrCreatePen(const wxColour& colour,
455 int width = 1,
456 wxPenStyle style = wxPENSTYLE_SOLID);
8024723d
FM
457};
458
459/**
460 The global list of wxPen objects ready to be re-used (for better performances).
461*/
462wxPenList* wxThePenList;
463