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