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
 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::IsOk}\label{wxpenisok}
 243
 244 \constfunc{bool}{IsOk}{\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 \helpref{reference counting}{trefcount}.
 333
 334 \membersection{wxPen::operator $==$}\label{wxpenequals}
 335
 336 \func{bool}{operator $==$}{\param{const wxPen\& }{pen}}
 337
 338 Equality operator. Two pens are equal if they contain pointers
 339 to the same underlying pen data. It does not compare each attribute,
 340 so two independently-created pens using the same parameters will
 341 fail the test.
 342
 343 \membersection{wxPen::operator $!=$}\label{wxpennotequals}
 344
 345 \func{bool}{operator $!=$}{\param{const wxPen\& }{pen}}
 346
 347 Inequality operator. Two pens are not equal if they contain pointers
 348 to different underlying pen data. It does not compare each attribute.
 349
 350 \section{\class{wxPenList}}\label{wxpenlist}
 351
 352 There is only one instance of this class: {\bf wxThePenList}.  Use
 353 this object to search for a previously created pen of the desired
 354 type and create it if not already found. In some windowing systems,
 355 the pen may be a scarce resource, so it can pay to reuse old
 356 resources if possible. When an application finishes, all pens will
 357 be deleted and their resources freed, eliminating the possibility of
 358 `memory leaks'. However, it is best not to rely on this automatic
 359 cleanup because it can lead to double deletion in some circumstances.
 360
 361 There are two mechanisms in recent versions of wxWidgets which make the
 362 pen list less useful than it once was. Under Windows, scarce resources
 363 are cleaned up internally if they are not being used. Also, a referencing
 364 counting mechanism applied to all GDI objects means that some sharing
 365 of underlying resources is possible. You don't have to keep track of pointers,
 366 working out when it is safe delete a pen, because the referencing counting does
 367 it for you. For example, you can set a pen in a device context, and then
 368 immediately delete the pen you passed, because the pen is `copied'.
 369
 370 So you may find it easier to ignore the pen list, and instead create
 371 and copy pens as you see fit. If your Windows resource meter suggests
 372 your application is using too many resources, you can resort to using
 373 GDI lists to share objects explicitly.
 374
 375 The only compelling use for the pen list is for wxWidgets to keep
 376 track of pens in order to clean them up on exit. It is also kept for
 377 backward compatibility with earlier versions of wxWidgets.
 378
 379 \wxheading{See also}
 380
 381 \helpref{wxPen}{wxpen}
 382
 383 \latexignore{\rtfignore{\wxheading{Members}}}
 384
 385 \membersection{wxPenList::wxPenList}\label{wxpenlistctor}
 386
 387 \func{void}{wxPenList}{\void}
 388
 389 Constructor. The application should not construct its own pen list:
 390 use the object pointer {\bf wxThePenList}.
 391
 392 \membersection{wxPenList::FindOrCreatePen}\label{wxpenlistfindorcreatepen}
 393
 394 \func{wxPen*}{FindOrCreatePen}{\param{const wxColour\& }{colour}, \param{int}{ width}, \param{int}{ style}}
 395
 396 Finds a pen with the specified attributes and returns it, else creates a new pen, adds it
 397 to the pen list, and returns it.
 398
 399 \func{wxPen*}{FindOrCreatePen}{\param{const wxString\& }{colourName}, \param{int}{ width}, \param{int}{ style}}
 400
 401 Finds a pen with the specified attributes and returns it, else creates a new pen, adds it
 402 to the pen list, and returns it.
 403
 404 \wxheading{Parameters}
 405
 406 \docparam{colour}{Colour object.}
 407
 408 \docparam{colourName}{Colour name, which should be in the \helpref{colour database}{wxcolourdatabase}.}
 409
 410 \docparam{width}{Width of pen.}
 411
 412 \docparam{style}{Pen style. See \helpref{wxPen::wxPen}{wxpenctor} for a list of styles.}