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::Ok}{wxpenok} 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. This uses reference counting so is a cheap operation.
  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
 158 \wxheading{Remarks}
 159
 160 The destructor may not delete the underlying pen object of the native windowing
 161 system, since wxBrush uses a reference counting system for efficiency.
 162
 163 Although all remaining pens are deleted when the application exits,
 164 the application should try to clean up all pens itself. This is because
 165 wxWidgets cannot know if a pointer to the pen object is stored in an
 166 application data structure, and there is a risk of double deletion.
 167
 168 \membersection{wxPen::GetCap}\label{wxpengetcap}
 169
 170 \constfunc{int}{GetCap}{\void}
 171
 172 Returns the pen cap style, which may be one of {\bf wxCAP\_ROUND}, {\bf wxCAP\_PROJECTING} and
 173 \rtfsp{\bf wxCAP\_BUTT}. The default is {\bf wxCAP\_ROUND}.
 174
 175 \wxheading{See also}
 176
 177 \helpref{wxPen::SetCap}{wxpensetcap}
 178
 179 \membersection{wxPen::GetColour}\label{wxpengetcolour}
 180
 181 \constfunc{wxColour\&}{GetColour}{\void}
 182
 183 Returns a reference to the pen colour.
 184
 185 \wxheading{See also}
 186
 187 \helpref{wxPen::SetColour}{wxpensetcolour}
 188
 189 \membersection{wxPen::GetDashes}\label{wxpengetdashes}
 190
 191 \constfunc{int}{GetDashes}{\param{wxDash**}{ dashes}}
 192
 193 Gets an array of dashes (defined as char in X, DWORD under Windows).
 194 {\it dashes} is a pointer to the internal array. Do not deallocate or store this pointer.
 195 The function returns the number of dashes associated with this pen.
 196
 197 \wxheading{See also}
 198
 199 \helpref{wxPen::SetDashes}{wxpensetdashes}
 200
 201 \membersection{wxPen::GetJoin}\label{wxpengetjoin}
 202
 203 \constfunc{int}{GetJoin}{\void}
 204
 205 Returns the pen join style, which may be one of {\bf wxJOIN\_BEVEL}, {\bf wxJOIN\_ROUND} and
 206 \rtfsp{\bf wxJOIN\_MITER}. The default is {\bf wxJOIN\_ROUND}.
 207
 208 \wxheading{See also}
 209
 210 \helpref{wxPen::SetJoin}{wxpensetjoin}
 211
 212 \membersection{wxPen::GetStipple}\label{wxpengetstipple}
 213
 214 \constfunc{wxBitmap* }{GetStipple}{\void}
 215
 216 Gets a pointer to the stipple bitmap.
 217
 218 \wxheading{See also}
 219
 220 \helpref{wxPen::SetStipple}{wxpensetstipple}
 221
 222 \membersection{wxPen::GetStyle}\label{wxpengetstyle}
 223
 224 \constfunc{int}{GetStyle}{\void}
 225
 226 Returns the pen style.
 227
 228 \wxheading{See also}
 229
 230 \helpref{wxPen::wxPen}{wxpenctor}, \helpref{wxPen::SetStyle}{wxpensetstyle}
 231
 232 \membersection{wxPen::GetWidth}\label{wxpengetwidth}
 233
 234 \constfunc{int}{GetWidth}{\void}
 235
 236 Returns the pen width.
 237
 238 \wxheading{See also}
 239
 240 \helpref{wxPen::SetWidth}{wxpensetwidth}
 241
 242 \membersection{wxPen::Ok}\label{wxpenok}
 243
 244 \constfunc{bool}{Ok}{\void}
 245
 246 Returns true if the pen is initialised.
 247
 248 \membersection{wxPen::SetCap}\label{wxpensetcap}
 249
 250 \func{void}{SetCap}{\param{int}{ capStyle}}
 251
 252 Sets the pen cap style, which may be one of {\bf wxCAP\_ROUND}, {\bf wxCAP\_PROJECTING} and
 253 \rtfsp{\bf wxCAP\_BUTT}. The default is {\bf wxCAP\_ROUND}.
 254
 255 \wxheading{See also}
 256
 257 \helpref{wxPen::GetCap}{wxpengetcap}
 258
 259 \membersection{wxPen::SetColour}\label{wxpensetcolour}
 260
 261 \func{void}{SetColour}{\param{wxColour\&}{ colour}}
 262
 263 \func{void}{SetColour}{\param{const wxString\& }{colourName}}
 264
 265 \func{void}{SetColour}{\param{unsigned char}{ red}, \param{unsigned char}{ green}, \param{unsigned char}{ blue}}
 266
 267 The pen's colour is changed to the given colour.
 268
 269 \wxheading{See also}
 270
 271 \helpref{wxPen::GetColour}{wxpengetcolour}
 272
 273 \membersection{wxPen::SetDashes}\label{wxpensetdashes}
 274
 275 \func{void}{SetDashes}{\param{int }{n}, \param{wxDash*}{ dashes}}
 276
 277 Associates an array of pointers to dashes (defined as char in X, DWORD under Windows)
 278 with the pen. The array is not deallocated by wxPen, but neither must it be
 279 deallocated by the calling application until the pen is deleted or this
 280 function is called with a NULL array.
 281
 282 %TODO: describe in detail.
 283 \wxheading{See also}
 284
 285 \helpref{wxPen::GetDashes}{wxpengetdashes}
 286
 287 \membersection{wxPen::SetJoin}\label{wxpensetjoin}
 288
 289 \func{void}{SetJoin}{\param{int }{join\_style}}
 290
 291 Sets the pen join style, which may be one of {\bf wxJOIN\_BEVEL}, {\bf wxJOIN\_ROUND} and
 292 \rtfsp{\bf wxJOIN\_MITER}. The default is {\bf wxJOIN\_ROUND}.
 293
 294 \wxheading{See also}
 295
 296 \helpref{wxPen::GetJoin}{wxpengetjoin}
 297
 298 \membersection{wxPen::SetStipple}\label{wxpensetstipple}
 299
 300 \func{void}{SetStipple}{\param{wxBitmap* }{stipple}}
 301
 302 Sets the bitmap for stippling.
 303
 304 \wxheading{See also}
 305
 306 \helpref{wxPen::GetStipple}{wxpengetstipple}
 307
 308 \membersection{wxPen::SetStyle}\label{wxpensetstyle}
 309
 310 \func{void}{SetStyle}{\param{int}{ style}}
 311
 312 Set the pen style.
 313
 314 \wxheading{See also}
 315
 316 \helpref{wxPen::wxPen}{wxpenctor}
 317
 318 \membersection{wxPen::SetWidth}\label{wxpensetwidth}
 319
 320 \func{void}{SetWidth}{\param{int}{ width}}
 321
 322 Sets the pen width.
 323
 324 \wxheading{See also}
 325
 326 \helpref{wxPen::GetWidth}{wxpengetwidth}
 327
 328 \membersection{wxPen::operator $=$}\label{wxpenassignment}
 329
 330 \func{wxPen\&}{operator $=$}{\param{const wxPen\& }{pen}}
 331
 332 Assignment operator, using reference counting. Returns a reference
 333 to `this'.
 334
 335 \membersection{wxPen::operator $==$}\label{wxpenequals}
 336
 337 \func{bool}{operator $==$}{\param{const wxPen\& }{pen}}
 338
 339 Equality operator. Two pens are equal if they contain pointers
 340 to the same underlying pen data. It does not compare each attribute,
 341 so two independently-created pens using the same parameters will
 342 fail the test.
 343
 344 \membersection{wxPen::operator $!=$}\label{wxpennotequals}
 345
 346 \func{bool}{operator $!=$}{\param{const wxPen\& }{pen}}
 347
 348 Inequality operator. Two pens are not equal if they contain pointers
 349 to different underlying pen data. It does not compare each attribute.
 350
 351 \section{\class{wxPenList}}\label{wxpenlist}
 352
 353 There is only one instance of this class: {\bf wxThePenList}.  Use
 354 this object to search for a previously created pen of the desired
 355 type and create it if not already found. In some windowing systems,
 356 the pen may be a scarce resource, so it can pay to reuse old
 357 resources if possible. When an application finishes, all pens will
 358 be deleted and their resources freed, eliminating the possibility of
 359 `memory leaks'. However, it is best not to rely on this automatic
 360 cleanup because it can lead to double deletion in some circumstances.
 361
 362 There are two mechanisms in recent versions of wxWidgets which make the
 363 pen list less useful than it once was. Under Windows, scarce resources
 364 are cleaned up internally if they are not being used. Also, a referencing
 365 counting mechanism applied to all GDI objects means that some sharing
 366 of underlying resources is possible. You don't have to keep track of pointers,
 367 working out when it is safe delete a pen, because the referencing counting does
 368 it for you. For example, you can set a pen in a device context, and then
 369 immediately delete the pen you passed, because the pen is `copied'.
 370
 371 So you may find it easier to ignore the pen list, and instead create
 372 and copy pens as you see fit. If your Windows resource meter suggests
 373 your application is using too many resources, you can resort to using
 374 GDI lists to share objects explicitly.
 375
 376 The only compelling use for the pen list is for wxWidgets to keep
 377 track of pens in order to clean them up on exit. It is also kept for
 378 backward compatibility with earlier versions of wxWidgets.
 379
 380 \wxheading{See also}
 381
 382 \helpref{wxPen}{wxpen}
 383
 384 \latexignore{\rtfignore{\wxheading{Members}}}
 385
 386 \membersection{wxPenList::wxPenList}\label{wxpenlistctor}
 387
 388 \func{void}{wxPenList}{\void}
 389
 390 Constructor. The application should not construct its own pen list:
 391 use the object pointer {\bf wxThePenList}.
 392
 393 \membersection{wxPenList::FindOrCreatePen}\label{wxpenlistfindorcreatepen}
 394
 395 \func{wxPen*}{FindOrCreatePen}{\param{const wxColour\& }{colour}, \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 \func{wxPen*}{FindOrCreatePen}{\param{const wxString\& }{colourName}, \param{int}{ width}, \param{int}{ style}}
 401
 402 Finds a pen with the specified attributes and returns it, else creates a new pen, adds it
 403 to the pen list, and returns it.
 404
 405 \wxheading{Parameters}
 406
 407 \docparam{colour}{Colour object.}
 408
 409 \docparam{colourName}{Colour name, which should be in the \helpref{colour database}{wxcolourdatabase}.}
 410
 411 \docparam{width}{Width of pen.}
 412
 413 \docparam{style}{Pen style. See \helpref{wxPen::wxPen}{wxpenctor} for a list of styles.}