docs/latex/wx/pen.tex

   1 \section{\class{wxPen}}\label{wxpen}
   2
   3 A pen is a drawing tool for drawing outlines. It is used for drawing
   4 lines and painting the outline of rectangles, ellipses, etc. It has a
   5 colour, a width and a style.
   6
   7 \wxheading{Derived from}
   8
   9 \helpref{wxGDIObject}{wxgdiobject}\\
  10 \helpref{wxObject}{wxobject}
  11
  12 \wxheading{Include files}
  13
  14 <wx/pen.h>
  15
  16 \wxheading{Predefined objects}
  17
  18 Objects:
  19
  20 {\bf wxNullPen}
  21
  22 Pointers:
  23
  24 {\bf wxRED\_PEN\\
  25 wxCYAN\_PEN\\
  26 wxGREEN\_PEN\\
  27 wxBLACK\_PEN\\
  28 wxWHITE\_PEN\\
  29 wxTRANSPARENT\_PEN\\
  30 wxBLACK\_DASHED\_PEN\\
  31 wxGREY\_PEN\\
  32 wxMEDIUM\_GREY\_PEN\\
  33 wxLIGHT\_GREY\_PEN}
  34
  35 \wxheading{Remarks}
  36
  37 On a monochrome display, wxWindows shows all non-white pens as black.
  38
  39 Do not initialize objects on the stack before the program commences,
  40 since other required structures may not have been set up yet. Instead,
  41 define global pointers to objects and create them in {\it OnInit} or
  42 when required.
  43
  44 An application may wish to dynamically create pens with different
  45 characteristics, and there is the consequent danger that a large number
  46 of duplicate pens will be created. Therefore an application may wish to
  47 get a pointer to a pen by using the global list of pens {\bf
  48 wxThePenList}, and calling the member function {\bf FindOrCreatePen}.
  49 See the entry for \helpref{wxPenList}{wxpenlist}.
  50
  51 wxPen uses a reference counting system, so assignments between brushes are very
  52 cheap. You can therefore use actual wxPen objects instead of pointers without
  53 efficiency problems. Once one wxPen object changes its data it will create its
  54 own pen data internally so that other pens, which previously shared the
  55 data using the reference counting, are not affected.
  56
  57 %TODO: an overview for wxPen.
  58 \wxheading{See also}
  59
  60 \helpref{wxPenList}{wxpenlist}, \helpref{wxDC}{wxdc}, \helpref{wxDC::SetPen}{wxdcsetpen}
  61
  62 \latexignore{\rtfignore{\wxheading{Members}}}
  63
  64 \membersection{wxPen::wxPen}\label{wxpenconstr}
  65
  66 \func{}{wxPen}{\void}
  67
  68 Default constructor. The pen will be uninitialised, and \helpref{wxPen::Ok}{wxpenok} will
  69 return FALSE.
  70
  71 \func{}{wxPen}{\param{const wxColour\&}{ colour}, \param{int}{ width}, \param{int}{ style}}
  72
  73 Constructs a pen from a colour object, pen width and style.
  74
  75 \func{}{wxPen}{\param{const wxString\& }{colourName}, \param{int}{ width}, \param{int}{ style}}
  76
  77 Constructs a pen from a colour name, pen width and style.
  78
  79 \func{}{wxPen}{\param{const wxBitmap\&}{ stipple}, \param{int}{ width}}
  80
  81 Constructs a stippled pen from a stipple bitmap and a width.
  82
  83 \func{}{wxPen}{\param{const wxPen\&}{ pen}}
  84
  85 Copy constructor. This uses reference counting so is a cheap operation.
  86
  87 \wxheading{Parameters}
  88
  89 \docparam{colour}{A colour object.}
  90
  91 \docparam{colourName}{A colour name.}
  92
  93 \docparam{width}{Pen width. Under Windows, the pen width cannot be greater than 1 if
  94 the style is wxDOT, wxLONG\_DASH, wxSHORT\_DASH, wxDOT\_DASH, or wxUSER\_DASH.}
  95
  96 \docparam{stipple}{A stipple bitmap.}
  97
  98 \docparam{pen}{A pointer or reference to a pen to copy.}
  99
 100 \docparam{width}{Pen width. Under Windows, the pen width cannot be greater than 1 if
 101 the style is wxDOT, wxLONG\_DASH, wxSHORT\_DASH, wxDOT\_DASH, or wxUSER\_DASH.}
 102
 103 \docparam{style}{The style may be one of the following:
 104
 105 \begin{twocollist}\itemsep=0pt
 106 \twocolitem{{\bf wxSOLID}}{Solid style.}
 107 \twocolitem{{\bf wxTRANSPARENT}}{No pen is used.}
 108 \twocolitem{{\bf wxDOT}}{Dotted style.}
 109 \twocolitem{{\bf wxLONG\_DASH}}{Long dashed style.}
 110 \twocolitem{{\bf wxSHORT\_DASH}}{Short dashed style.}
 111 \twocolitem{{\bf wxDOT\_DASH}}{Dot and dash style.}
 112 \twocolitem{{\bf wxSTIPPLE}}{Use the stipple bitmap.}
 113 \twocolitem{{\bf wxUSER\_DASH}}{Use the user dashes: see \helpref{wxPen::SetDashes}{wxpensetdashes}.}
 114 \twocolitem{{\bf wxBDIAGONAL\_HATCH}}{Backward diagonal hatch.}
 115 \twocolitem{{\bf wxCROSSDIAG\_HATCH}}{Cross-diagonal hatch.}
 116 \twocolitem{{\bf wxFDIAGONAL\_HATCH}}{Forward diagonal hatch.}
 117 \twocolitem{{\bf wxCROSS\_HATCH}}{Cross hatch.}
 118 \twocolitem{{\bf wxHORIZONTAL\_HATCH}}{Horizontal hatch.}
 119 \twocolitem{{\bf wxVERTICAL\_HATCH}}{Vertical hatch.}
 120 \end{twocollist}}
 121
 122 \wxheading{Remarks}
 123
 124 If the named colour form is used, an appropriate {\bf wxColour} structure
 125 is found in the colour database.
 126
 127 {\it style} may be one of wxSOLID, wxDOT, wxLONG\_DASH, wxSHORT\_DASH and
 128 wxDOT\_DASH.
 129
 130 \wxheading{See also}
 131
 132 \helpref{wxPen::SetStyle}{wxpensetstyle}, \helpref{wxPen::SetColour}{wxpensetcolour},\rtfsp
 133 \helpref{wxPen::SetWidth}{wxpensetwidth}, \helpref{wxPen::SetStipple}{wxpensetstipple}
 134
 135 \membersection{wxPen::\destruct{wxPen}}
 136
 137 \func{}{\destruct{wxPen}}{\void}
 138
 139 Destructor.
 140
 141 \wxheading{Remarks}
 142
 143 The destructor may not delete the underlying pen object of the native windowing
 144 system, since wxBrush uses a reference counting system for efficiency.
 145
 146 Although all remaining pens are deleted when the application exits,
 147 the application should try to clean up all pens itself. This is because
 148 wxWindows cannot know if a pointer to the pen object is stored in an
 149 application data structure, and there is a risk of double deletion.
 150
 151 \membersection{wxPen::GetCap}\label{wxpengetcap}
 152
 153 \constfunc{int}{GetCap}{\void}
 154
 155 Returns the pen cap style, which may be one of {\bf wxCAP\_ROUND}, {\bf wxCAP\_PROJECTING} and
 156 \rtfsp{\bf wxCAP\_BUTT}. The default is {\bf wxCAP\_ROUND}.
 157
 158 \wxheading{See also}
 159
 160 \helpref{wxPen::SetCap}{wxpensetcap}
 161
 162 \membersection{wxPen::GetColour}\label{wxpengetcolour}
 163
 164 \constfunc{wxColour\&}{GetColour}{\void}
 165
 166 Returns a reference to the pen colour.
 167
 168 \wxheading{See also}
 169
 170 \helpref{wxPen::SetColour}{wxpensetcolour}
 171
 172 \membersection{wxPen::GetDashes}\label{wxpengetdashes}
 173
 174 \constfunc{int}{GetDashes}{\param{wxDash**}{ dashes}}
 175
 176 Gets an array of dashes (defined as char in X, DWORD under Windows).
 177 {\it dashes} is a pointer to the internal array. Do not deallocate or store this pointer.
 178 The function returns the number of dashes associated with this pen.
 179
 180 \wxheading{See also}
 181
 182 \helpref{wxPen::SetDashes}{wxpensetdashes}
 183
 184 \membersection{wxPen::GetJoin}\label{wxpengetjoin}
 185
 186 \constfunc{int}{GetJoin}{\void}
 187
 188 Returns the pen join style, which may be one of {\bf wxJOIN\_BEVEL}, {\bf wxJOIN\_ROUND} and
 189 \rtfsp{\bf wxJOIN\_MITER}. The default is {\bf wxJOIN\_ROUND}.
 190
 191 \wxheading{See also}
 192
 193 \helpref{wxPen::SetJoin}{wxpensetjoin}
 194
 195 \membersection{wxPen::GetStipple}\label{wxpengetstipple}
 196
 197 \constfunc{wxBitmap* }{GetStipple}{\void}
 198
 199 Gets a pointer to the stipple bitmap.
 200
 201 \wxheading{See also}
 202
 203 \helpref{wxPen::SetStipple}{wxpensetstipple}
 204
 205 \membersection{wxPen::GetStyle}\label{wxpengetstyle}
 206
 207 \constfunc{int}{GetStyle}{\void}
 208
 209 Returns the pen style.
 210
 211 \wxheading{See also}
 212
 213 \helpref{wxPen::wxPen}{wxpenconstr}, \helpref{wxPen::SetStyle}{wxpensetstyle}
 214
 215 \membersection{wxPen::GetWidth}\label{wxpengetwidth}
 216
 217 \constfunc{int}{GetWidth}{\void}
 218
 219 Returns the pen width.
 220
 221 \wxheading{See also}
 222
 223 \helpref{wxPen::SetWidth}{wxpensetwidth}
 224
 225 \membersection{wxPen::Ok}\label{wxpenok}
 226
 227 \constfunc{bool}{Ok}{\void}
 228
 229 Returns TRUE if the pen is initialised.
 230
 231 \membersection{wxPen::SetCap}\label{wxpensetcap}
 232
 233 \func{void}{SetCap}{\param{int}{ capStyle}}
 234
 235 Sets the pen cap style, which may be one of {\bf wxCAP\_ROUND}, {\bf wxCAP\_PROJECTING} and
 236 \rtfsp{\bf wxCAP\_BUTT}. The default is {\bf wxCAP\_ROUND}.
 237
 238 \wxheading{See also}
 239
 240 \helpref{wxPen::GetCap}{wxpengetcap}
 241
 242 \membersection{wxPen::SetColour}\label{wxpensetcolour}
 243
 244 \func{void}{SetColour}{\param{wxColour\&}{ colour}}
 245
 246 \func{void}{SetColour}{\param{const wxString\& }{colourName}}
 247
 248 \func{void}{SetColour}{\param{int}{ red}, \param{int}{ green}, \param{int}{ blue}}
 249
 250 The pen's colour is changed to the given colour.
 251
 252 \wxheading{See also}
 253
 254 \helpref{wxPen::GetColour}{wxpengetcolour}
 255
 256 \membersection{wxPen::SetDashes}\label{wxpensetdashes}
 257
 258 \func{void}{SetDashes}{\param{int }{n}, \param{wxDash*}{ dashes}}
 259
 260 Associates an array of pointers to dashes (defined as char in X, DWORD under Windows)
 261 with the pen. The array is not deallocated by wxPen, but neither must it be
 262 deallocated by the calling application until the pen is deleted or this
 263 function is called with a NULL array.
 264
 265 %TODO: describe in detail.
 266 \wxheading{See also}
 267
 268 \helpref{wxPen::GetDashes}{wxpengetdashes}
 269
 270 \membersection{wxPen::SetJoin}\label{wxpensetjoin}
 271
 272 \func{void}{SetJoin}{\param{int}{join\_style}}
 273
 274 Sets the pen join style, which may be one of {\bf wxJOIN\_BEVEL}, {\bf wxJOIN\_ROUND} and
 275 \rtfsp{\bf wxJOIN\_MITER}. The default is {\bf wxJOIN\_ROUND}.
 276
 277 \wxheading{See also}
 278
 279 \helpref{wxPen::GetJoin}{wxpengetjoin}
 280
 281 \membersection{wxPen::SetStipple}\label{wxpensetstipple}
 282
 283 \func{void}{SetStipple}{\param{wxBitmap* }{stipple}}
 284
 285 Sets the bitmap for stippling.
 286
 287 \wxheading{See also}
 288
 289 \helpref{wxPen::GetStipple}{wxpengetstipple}
 290
 291 \membersection{wxPen::SetStyle}\label{wxpensetstyle}
 292
 293 \func{void}{SetStyle}{\param{int}{ style}}
 294
 295 Set the pen style.
 296
 297 \wxheading{See also}
 298
 299 \helpref{wxPen::wxPen}{wxpenconstr}
 300
 301 \membersection{wxPen::SetWidth}\label{wxpensetwidth}
 302
 303 \func{void}{SetWidth}{\param{int}{ width}}
 304
 305 Sets the pen width.
 306
 307 \wxheading{See also}
 308
 309 \helpref{wxPen::GetWidth}{wxpengetwidth}
 310
 311 \membersection{wxPen::operator $=$}\label{wxpenassignment}
 312
 313 \func{wxPen\&}{operator $=$}{\param{const wxPen\& }{pen}}
 314
 315 Assignment operator, using reference counting. Returns a reference
 316 to `this'.
 317
 318 \membersection{wxPen::operator $==$}\label{wxpenequals}
 319
 320 \func{bool}{operator $==$}{\param{const wxPen\& }{pen}}
 321
 322 Equality operator. Two pens are equal if they contain pointers
 323 to the same underlying pen data. It does not compare each attribute,
 324 so two independently-created pens using the same parameters will
 325 fail the test.
 326
 327 \membersection{wxPen::operator $!=$}\label{wxpennotequals}
 328
 329 \func{bool}{operator $!=$}{\param{const wxPen\& }{pen}}
 330
 331 Inequality operator. Two pens are not equal if they contain pointers
 332 to different underlying pen data. It does not compare each attribute.
 333
 334 \section{\class{wxPenList}}\label{wxpenlist}
 335
 336 There is only one instance of this class: {\bf wxThePenList}.  Use
 337 this object to search for a previously created pen of the desired
 338 type and create it if not already found. In some windowing systems,
 339 the pen may be a scarce resource, so it can pay to reuse old
 340 resources if possible. When an application finishes, all pens will
 341 be deleted and their resources freed, eliminating the possibility of
 342 `memory leaks'. However, it is best not to rely on this automatic
 343 cleanup because it can lead to double deletion in some circumstances.
 344
 345 There are two mechanisms in recent versions of wxWindows which make the
 346 pen list less useful than it once was. Under Windows, scarce resources
 347 are cleaned up internally if they are not being used. Also, a referencing
 348 counting mechanism applied to all GDI objects means that some sharing
 349 of underlying resources is possible. You don't have to keep track of pointers,
 350 working out when it is safe delete a pen, because the referencing counting does
 351 it for you. For example, you can set a pen in a device context, and then
 352 immediately delete the pen you passed, because the pen is `copied'.
 353
 354 So you may find it easier to ignore the pen list, and instead create
 355 and copy pens as you see fit. If your Windows resource meter suggests
 356 your application is using too many resources, you can resort to using
 357 GDI lists to share objects explicitly.
 358
 359 The only compelling use for the pen list is for wxWindows to keep
 360 track of pens in order to clean them up on exit. It is also kept for
 361 backward compatibility with earlier versions of wxWindows.
 362
 363 \wxheading{See also}
 364
 365 \helpref{wxPen}{wxpen}
 366
 367 \latexignore{\rtfignore{\wxheading{Members}}}
 368
 369 \membersection{wxPenList::wxPenList}
 370
 371 \func{void}{wxPenList}{\void}
 372
 373 Constructor. The application should not construct its own pen list:
 374 use the object pointer {\bf wxThePenList}.
 375
 376 \membersection{wxPenList::AddPen}\label{wxpenlistaddpen}
 377
 378 \func{void}{AddPen}{\param{wxPen*}{ pen}}
 379
 380 Used internally by wxWindows to add a pen to the list.
 381
 382 \membersection{wxPenList::FindOrCreatePen}\label{wxpenlistfindorcreatepen}
 383
 384 \func{wxPen*}{FindOrCreatePen}{\param{const wxColour\& }{colour}, \param{int}{ width}, \param{int}{ style}}
 385
 386 Finds a pen with the specified attributes and returns it, else creates a new pen, adds it
 387 to the pen list, and returns it.
 388
 389 \func{wxPen*}{FindOrCreatePen}{\param{const wxString\& }{colourName}, \param{int}{ width}, \param{int}{ style}}
 390
 391 Finds a pen with the specified attributes and returns it, else creates a new pen, adds it
 392 to the pen list, and returns it.
 393
 394 \wxheading{Parameters}
 395
 396 \docparam{colour}{Colour object.}
 397
 398 \docparam{colourName}{Colour name, which should be in the \helpref{colour database}{wxcolourdatabase}.}
 399
 400 \docparam{width}{Width of pen.}
 401
 402 \docparam{style}{Pen style. See \helpref{wxPen::wxPen}{wxpenconstr} for a list of styles.}
 403
 404 \membersection{wxPenList::RemovePen}\label{wxpenlistremovepen}
 405
 406 \func{void}{RemovePen}{\param{wxPen*}{ pen}}
 407
 408 Used by wxWindows to remove a pen from the list.
 409
 410