docs/latex/wx/pen.tex

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