1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxPen* classes
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 The possible styles for a wxPen.
14 wxPENSTYLE_INVALID
= -1,
23 /**< Long dashed style. */
25 wxPENSTYLE_SHORT_DASH
,
26 /**< Short dashed style. */
29 /**< Dot and dash style. */
32 /**< Use the user dashes: see wxPen::SetDashes. */
34 wxPENSTYLE_TRANSPARENT
,
35 /**< No pen is used. */
37 wxPENSTYLE_STIPPLE_MASK_OPAQUE
,
38 /**< @todo WHAT's this? */
40 wxPENSTYLE_STIPPLE_MASK
,
41 /**< @todo WHAT's this? */
44 /**< Use the stipple bitmap. */
46 wxPENSTYLE_BDIAGONAL_HATCH
,
47 /**< Backward diagonal hatch. */
49 wxPENSTYLE_CROSSDIAG_HATCH
,
50 /**< Cross-diagonal hatch. */
52 wxPENSTYLE_FDIAGONAL_HATCH
,
53 /**< Forward diagonal hatch. */
55 wxPENSTYLE_CROSS_HATCH
,
58 wxPENSTYLE_HORIZONTAL_HATCH
,
59 /**< Horizontal hatch. */
61 wxPENSTYLE_VERTICAL_HATCH
,
62 /**< Vertical hatch. */
64 wxPENSTYLE_FIRST_HATCH
= wxPENSTYLE_BDIAGONAL_HATCH
,
65 wxPENSTYLE_LAST_HATCH
= wxPENSTYLE_VERTICAL_HATCH
69 The possible join values of a wxPen.
71 @todo use wxPENJOIN_ prefix
84 The possible cap values of a wxPen.
86 @todo use wxPENCAP_ prefix
103 A pen is a drawing tool for drawing outlines. It is used for drawing
104 lines and painting the outline of rectangles, ellipses, etc.
105 It has a colour, a width and a style.
107 On a monochrome display, wxWidgets shows all non-white pens as black.
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
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.
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.
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
136 @see wxPenList, wxDC, wxDC::SetPen
138 class wxPen
: public wxGDIObject
142 Default constructor. The pen will be uninitialised, and wxPen:IsOk will return @false.
147 Constructs a pen from a colour object, pen width and style.
149 wxPen(const wxColour
& colour
, int width
= 1, wxPenStyle style
= wxPENSTYLE_SOLID
);
152 Constructs a stippled pen from a stipple bitmap and a width.
154 wxPen(const wxBitmap
& stipple
, int width
);
157 Copy constructor, uses @ref overview_refcount "reference counting".
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.
169 A pointer or reference to a pen to copy.
171 The style may be one of the ::wxPenStyle values.
173 @remarks Different versions of Windows and different versions of other
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.
178 @see SetStyle(), SetColour(), SetWidth(), SetStipple()
180 wxPen(const wxPen
& pen
);
184 See @ref overview_refcountdestruct "reference-counted object destruction" for
187 @remarks Although all remaining pens are deleted when the application
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.
196 Returns the pen cap style, which may be one of @b wxCAP_ROUND, @b
198 @b wxCAP_BUTT. The default is @b wxCAP_ROUND.
202 virtual wxPenCap
GetCap() const;
205 Returns a reference to the pen colour.
209 virtual wxColour
GetColour() const;
212 Gets an array of dashes (defined as char in X, DWORD under Windows).
213 @a dashes is a pointer to the internal array. Do not deallocate or store this
215 The function returns the number of dashes associated with this pen.
219 virtual int GetDashes(wxDash
** dashes
) const;
222 Returns the pen join style, which may be one of @b wxJOIN_BEVEL, @b
224 @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
228 virtual wxPenJoin
GetJoin() const;
231 Gets a pointer to the stipple bitmap.
235 virtual wxBitmap
* GetStipple() const;
238 Returns the pen style.
240 @see wxPen(), SetStyle()
242 virtual wxPenStyle
GetStyle() const;
245 Returns the pen width.
249 virtual int GetWidth() const;
252 Returns @true if the pen is initialised.
257 Sets the pen cap style, which may be one of @b wxCAP_ROUND, @b wxCAP_PROJECTING
259 @b wxCAP_BUTT. The default is @b wxCAP_ROUND.
263 virtual void SetCap(wxPenCap capStyle
);
267 The pen's colour is changed to the given colour.
271 virtual void SetColour(wxColour
& colour
);
272 virtual void SetColour(unsigned char red
, unsigned char green
, unsigned char blue
);
276 Associates an array of pointers to dashes (defined as char in X, DWORD under
278 with the pen. The array is not deallocated by wxPen, but neither must it be
279 deallocated by the calling application until the pen is deleted or this
280 function is called with a @NULL array.
284 virtual void SetDashes(int n
, wxDash
* dashes
);
287 Sets the pen join style, which may be one of @b wxJOIN_BEVEL, @b wxJOIN_ROUND
289 @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
293 virtual void SetJoin(wxPenJoin join_style
);
296 Sets the bitmap for stippling.
300 virtual void SetStipple(wxBitmap
* stipple
);
307 virtual void SetStyle(wxPenStyle style
);
314 virtual void SetWidth(int width
);
318 See @ref overview_refcountequality "reference-counted object comparison" for
321 bool operator !=(const wxPen
& pen
);
324 Assignment operator, using @ref overview_trefcount "reference counting".
326 wxPen
operator =(const wxPen
& pen
);
330 See @ref overview_refcountequality "reference-counted object comparison" for
333 bool operator ==(const wxPen
& pen
);
369 wxPen wxTRANSPARENT_PEN
;
374 wxPen wxBLACK_DASHED_PEN
;
384 wxPen wxMEDIUM_GREY_PEN
;
389 wxPen wxLIGHT_GREY_PEN
;
397 There is only one instance of this class: ::wxThePenList.
398 Use this object to search for a previously created pen of the desired
399 type and create it if not already found. In some windowing systems,
400 the pen may be a scarce resource, so it can pay to reuse old
401 resources if possible. When an application finishes, all pens will
402 be deleted and their resources freed, eliminating the possibility of
403 'memory leaks'. However, it is best not to rely on this automatic
404 cleanup because it can lead to double deletion in some circumstances.
406 There are two mechanisms in recent versions of wxWidgets which make the
407 pen list less useful than it once was. Under Windows, scarce resources
408 are cleaned up internally if they are not being used. Also, a referencing
409 counting mechanism applied to all GDI objects means that some sharing
410 of underlying resources is possible. You don't have to keep track of pointers,
411 working out when it is safe delete a pen, because the referencing counting does
412 it for you. For example, you can set a pen in a device context, and then
413 immediately delete the pen you passed, because the pen is 'copied'.
415 So you may find it easier to ignore the pen list, and instead create
416 and copy pens as you see fit. If your Windows resource meter suggests
417 your application is using too many resources, you can resort to using
418 GDI lists to share objects explicitly.
420 The only compelling use for the pen list is for wxWidgets to keep
421 track of pens in order to clean them up on exit. It is also kept for
422 backward compatibility with earlier versions of wxWidgets.
436 Constructor. The application should not construct its own pen list:
437 use the object pointer ::wxThePenList.
442 Finds a pen with the specified attributes and returns it, else creates a
443 new pen, adds it to the pen list, and returns it.
450 Pen style. See ::wxPenStyle for a list of styles.
452 wxPen
* FindOrCreatePen(const wxColour
& colour
,
454 wxPenStyle style
= wxPENSTYLE_SOLID
);
458 The global list of wxPen objects ready to be re-used (for better performances).
460 wxPenList
* wxThePenList
;