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