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