| 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.} |