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