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