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{style}{The style may be one of the following:
 101
 102 \begin{twocollist}\itemsep=0pt
 103 \twocolitem{{\bf wxSOLID}}{Solid style.}
 104 \twocolitem{{\bf wxTRANSPARENT}}{No pen is used.}
 105 \twocolitem{{\bf wxDOT}}{Dotted style.}
 106 \twocolitem{{\bf wxLONG\_DASH}}{Long dashed style.}
 107 \twocolitem{{\bf wxSHORT\_DASH}}{Short dashed style.}
 108 \twocolitem{{\bf wxDOT\_DASH}}{Dot and dash style.}
 109 \twocolitem{{\bf wxSTIPPLE}}{Use the stipple bitmap.}
 110 \twocolitem{{\bf wxUSER\_DASH}}{Use the user dashes: see \helpref{wxPen::SetDashes}{wxpensetdashes}.}
 111 \twocolitem{{\bf wxBDIAGONAL\_HATCH}}{Backward diagonal hatch.}
 112 \twocolitem{{\bf wxCROSSDIAG\_HATCH}}{Cross-diagonal hatch.}
 113 \twocolitem{{\bf wxFDIAGONAL\_HATCH}}{Forward diagonal hatch.}
 114 \twocolitem{{\bf wxCROSS\_HATCH}}{Cross hatch.}
 115 \twocolitem{{\bf wxHORIZONTAL\_HATCH}}{Horizontal hatch.}
 116 \twocolitem{{\bf wxVERTICAL\_HATCH}}{Vertical hatch.}
 117 \end{twocollist}}
 118
 119 \wxheading{Remarks}
 120
 121 Different versions of Windows and different versions of other platforms
 122 support {\it very} different subsets of the styles above - there is no
 123 similarity even between Windows95 and Windows98 - so handle with care.
 124
 125 If the named colour form is used, an appropriate {\bf wxColour} structure
 126 is found in the colour database.
 127
 128 \wxheading{See also}
 129
 130 \helpref{wxPen::SetStyle}{wxpensetstyle}, \helpref{wxPen::SetColour}{wxpensetcolour},\rtfsp
 131 \helpref{wxPen::SetWidth}{wxpensetwidth}, \helpref{wxPen::SetStipple}{wxpensetstipple}
 132
 133 \membersection{wxPen::\destruct{wxPen}}
 134
 135 \func{}{\destruct{wxPen}}{\void}
 136
 137 Destructor.
 138
 139 \wxheading{Remarks}
 140
 141 The destructor may not delete the underlying pen object of the native windowing
 142 system, since wxBrush uses a reference counting system for efficiency.
 143
 144 Although all remaining pens are deleted when the application exits,
 145 the application should try to clean up all pens itself. This is because
 146 wxWindows cannot know if a pointer to the pen object is stored in an
 147 application data structure, and there is a risk of double deletion.
 148
 149 \membersection{wxPen::GetCap}\label{wxpengetcap}
 150
 151 \constfunc{int}{GetCap}{\void}
 152
 153 Returns the pen cap style, which may be one of {\bf wxCAP\_ROUND}, {\bf wxCAP\_PROJECTING} and
 154 \rtfsp{\bf wxCAP\_BUTT}. The default is {\bf wxCAP\_ROUND}.
 155
 156 \wxheading{See also}
 157
 158 \helpref{wxPen::SetCap}{wxpensetcap}
 159
 160 \membersection{wxPen::GetColour}\label{wxpengetcolour}
 161
 162 \constfunc{wxColour\&}{GetColour}{\void}
 163
 164 Returns a reference to the pen colour.
 165
 166 \wxheading{See also}
 167
 168 \helpref{wxPen::SetColour}{wxpensetcolour}
 169
 170 \membersection{wxPen::GetDashes}\label{wxpengetdashes}
 171
 172 \constfunc{int}{GetDashes}{\param{wxDash**}{ dashes}}
 173
 174 Gets an array of dashes (defined as char in X, DWORD under Windows).
 175 {\it dashes} is a pointer to the internal array. Do not deallocate or store this pointer.
 176 The function returns the number of dashes associated with this pen.
 177
 178 \wxheading{See also}
 179
 180 \helpref{wxPen::SetDashes}{wxpensetdashes}
 181
 182 \membersection{wxPen::GetJoin}\label{wxpengetjoin}
 183
 184 \constfunc{int}{GetJoin}{\void}
 185
 186 Returns the pen join style, which may be one of {\bf wxJOIN\_BEVEL}, {\bf wxJOIN\_ROUND} and
 187 \rtfsp{\bf wxJOIN\_MITER}. The default is {\bf wxJOIN\_ROUND}.
 188
 189 \wxheading{See also}
 190
 191 \helpref{wxPen::SetJoin}{wxpensetjoin}
 192
 193 \membersection{wxPen::GetStipple}\label{wxpengetstipple}
 194
 195 \constfunc{wxBitmap* }{GetStipple}{\void}
 196
 197 Gets a pointer to the stipple bitmap.
 198
 199 \wxheading{See also}
 200
 201 \helpref{wxPen::SetStipple}{wxpensetstipple}
 202
 203 \membersection{wxPen::GetStyle}\label{wxpengetstyle}
 204
 205 \constfunc{int}{GetStyle}{\void}
 206
 207 Returns the pen style.
 208
 209 \wxheading{See also}
 210
 211 \helpref{wxPen::wxPen}{wxpenconstr}, \helpref{wxPen::SetStyle}{wxpensetstyle}
 212
 213 \membersection{wxPen::GetWidth}\label{wxpengetwidth}
 214
 215 \constfunc{int}{GetWidth}{\void}
 216
 217 Returns the pen width.
 218
 219 \wxheading{See also}
 220
 221 \helpref{wxPen::SetWidth}{wxpensetwidth}
 222
 223 \membersection{wxPen::Ok}\label{wxpenok}
 224
 225 \constfunc{bool}{Ok}{\void}
 226
 227 Returns TRUE if the pen is initialised.
 228
 229 \membersection{wxPen::SetCap}\label{wxpensetcap}
 230
 231 \func{void}{SetCap}{\param{int}{ capStyle}}
 232
 233 Sets the pen cap style, which may be one of {\bf wxCAP\_ROUND}, {\bf wxCAP\_PROJECTING} and
 234 \rtfsp{\bf wxCAP\_BUTT}. The default is {\bf wxCAP\_ROUND}.
 235
 236 \wxheading{See also}
 237
 238 \helpref{wxPen::GetCap}{wxpengetcap}
 239
 240 \membersection{wxPen::SetColour}\label{wxpensetcolour}
 241
 242 \func{void}{SetColour}{\param{wxColour\&}{ colour}}
 243
 244 \func{void}{SetColour}{\param{const wxString\& }{colourName}}
 245
 246 \func{void}{SetColour}{\param{int}{ red}, \param{int}{ green}, \param{int}{ blue}}
 247
 248 The pen's colour is changed to the given colour.
 249
 250 \wxheading{See also}
 251
 252 \helpref{wxPen::GetColour}{wxpengetcolour}
 253
 254 \membersection{wxPen::SetDashes}\label{wxpensetdashes}
 255
 256 \func{void}{SetDashes}{\param{int }{n}, \param{wxDash*}{ dashes}}
 257
 258 Associates an array of pointers to dashes (defined as char in X, DWORD under Windows)
 259 with the pen. The array is not deallocated by wxPen, but neither must it be
 260 deallocated by the calling application until the pen is deleted or this
 261 function is called with a NULL array.
 262
 263 %TODO: describe in detail.
 264 \wxheading{See also}
 265
 266 \helpref{wxPen::GetDashes}{wxpengetdashes}
 267
 268 \membersection{wxPen::SetJoin}\label{wxpensetjoin}
 269
 270 \func{void}{SetJoin}{\param{int}{join\_style}}
 271
 272 Sets the pen join style, which may be one of {\bf wxJOIN\_BEVEL}, {\bf wxJOIN\_ROUND} and
 273 \rtfsp{\bf wxJOIN\_MITER}. The default is {\bf wxJOIN\_ROUND}.
 274
 275 \wxheading{See also}
 276
 277 \helpref{wxPen::GetJoin}{wxpengetjoin}
 278
 279 \membersection{wxPen::SetStipple}\label{wxpensetstipple}
 280
 281 \func{void}{SetStipple}{\param{wxBitmap* }{stipple}}
 282
 283 Sets the bitmap for stippling.
 284
 285 \wxheading{See also}
 286
 287 \helpref{wxPen::GetStipple}{wxpengetstipple}
 288
 289 \membersection{wxPen::SetStyle}\label{wxpensetstyle}
 290
 291 \func{void}{SetStyle}{\param{int}{ style}}
 292
 293 Set the pen style.
 294
 295 \wxheading{See also}
 296
 297 \helpref{wxPen::wxPen}{wxpenconstr}
 298
 299 \membersection{wxPen::SetWidth}\label{wxpensetwidth}
 300
 301 \func{void}{SetWidth}{\param{int}{ width}}
 302
 303 Sets the pen width.
 304
 305 \wxheading{See also}
 306
 307 \helpref{wxPen::GetWidth}{wxpengetwidth}
 308
 309 \membersection{wxPen::operator $=$}\label{wxpenassignment}
 310
 311 \func{wxPen\&}{operator $=$}{\param{const wxPen\& }{pen}}
 312
 313 Assignment operator, using reference counting. Returns a reference
 314 to `this'.
 315
 316 \membersection{wxPen::operator $==$}\label{wxpenequals}
 317
 318 \func{bool}{operator $==$}{\param{const wxPen\& }{pen}}
 319
 320 Equality operator. Two pens are equal if they contain pointers
 321 to the same underlying pen data. It does not compare each attribute,
 322 so two independently-created pens using the same parameters will
 323 fail the test.
 324
 325 \membersection{wxPen::operator $!=$}\label{wxpennotequals}
 326
 327 \func{bool}{operator $!=$}{\param{const wxPen\& }{pen}}
 328
 329 Inequality operator. Two pens are not equal if they contain pointers
 330 to different underlying pen data. It does not compare each attribute.
 331
 332 \section{\class{wxPenList}}\label{wxpenlist}
 333
 334 There is only one instance of this class: {\bf wxThePenList}.  Use
 335 this object to search for a previously created pen of the desired
 336 type and create it if not already found. In some windowing systems,
 337 the pen may be a scarce resource, so it can pay to reuse old
 338 resources if possible. When an application finishes, all pens will
 339 be deleted and their resources freed, eliminating the possibility of
 340 `memory leaks'. However, it is best not to rely on this automatic
 341 cleanup because it can lead to double deletion in some circumstances.
 342
 343 There are two mechanisms in recent versions of wxWindows which make the
 344 pen list less useful than it once was. Under Windows, scarce resources
 345 are cleaned up internally if they are not being used. Also, a referencing
 346 counting mechanism applied to all GDI objects means that some sharing
 347 of underlying resources is possible. You don't have to keep track of pointers,
 348 working out when it is safe delete a pen, because the referencing counting does
 349 it for you. For example, you can set a pen in a device context, and then
 350 immediately delete the pen you passed, because the pen is `copied'.
 351
 352 So you may find it easier to ignore the pen list, and instead create
 353 and copy pens as you see fit. If your Windows resource meter suggests
 354 your application is using too many resources, you can resort to using
 355 GDI lists to share objects explicitly.
 356
 357 The only compelling use for the pen list is for wxWindows to keep
 358 track of pens in order to clean them up on exit. It is also kept for
 359 backward compatibility with earlier versions of wxWindows.
 360
 361 \wxheading{See also}
 362
 363 \helpref{wxPen}{wxpen}
 364
 365 \latexignore{\rtfignore{\wxheading{Members}}}
 366
 367 \membersection{wxPenList::wxPenList}
 368
 369 \func{void}{wxPenList}{\void}
 370
 371 Constructor. The application should not construct its own pen list:
 372 use the object pointer {\bf wxThePenList}.
 373
 374 \membersection{wxPenList::AddPen}\label{wxpenlistaddpen}
 375
 376 \func{void}{AddPen}{\param{wxPen*}{ pen}}
 377
 378 Used internally by wxWindows to add a pen to the list.
 379
 380 \membersection{wxPenList::FindOrCreatePen}\label{wxpenlistfindorcreatepen}
 381
 382 \func{wxPen*}{FindOrCreatePen}{\param{const wxColour\& }{colour}, \param{int}{ width}, \param{int}{ style}}
 383
 384 Finds a pen with the specified attributes and returns it, else creates a new pen, adds it
 385 to the pen list, and returns it.
 386
 387 \func{wxPen*}{FindOrCreatePen}{\param{const wxString\& }{colourName}, \param{int}{ width}, \param{int}{ style}}
 388
 389 Finds a pen with the specified attributes and returns it, else creates a new pen, adds it
 390 to the pen list, and returns it.
 391
 392 \wxheading{Parameters}
 393
 394 \docparam{colour}{Colour object.}
 395
 396 \docparam{colourName}{Colour name, which should be in the \helpref{colour database}{wxcolourdatabase}.}
 397
 398 \docparam{width}{Width of pen.}
 399
 400 \docparam{style}{Pen style. See \helpref{wxPen::wxPen}{wxpenconstr} for a list of styles.}
 401
 402 \membersection{wxPenList::RemovePen}\label{wxpenlistremovepen}
 403
 404 \func{void}{RemovePen}{\param{wxPen*}{ pen}}
 405
 406 Used by wxWindows to remove a pen from the list.
 407
 408