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