1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: pen.tex 3%% Purpose: wxPen docs 4%% Author: 5%% Modified by: 6%% Created: 7%% RCS-ID: $Id: pen.tex 43567 2006-11-21 09:27:10Z RR $ 8%% Copyright: (c) wxWidgets 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxPen}}\label{wxpen} 13 14A pen is a drawing tool for drawing outlines. It is used for drawing 15lines and painting the outline of rectangles, ellipses, etc. It has a 16colour, 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 29Objects: 30 31{\bf wxNullPen} 32 33Pointers: 34 35{\bf wxRED\_PEN\\ 36wxCYAN\_PEN\\ 37wxGREEN\_PEN\\ 38wxBLACK\_PEN\\ 39wxWHITE\_PEN\\ 40wxTRANSPARENT\_PEN\\ 41wxBLACK\_DASHED\_PEN\\ 42wxGREY\_PEN\\ 43wxMEDIUM\_GREY\_PEN\\ 44wxLIGHT\_GREY\_PEN} 45 46\wxheading{Remarks} 47 48On a monochrome display, wxWidgets shows all non-white pens as black. 49 50Do not initialize objects on the stack before the program commences, 51since other required structures may not have been set up yet. Instead, 52define global pointers to objects and create them in {\it OnInit} or 53when required. 54 55An application may wish to dynamically create pens with different 56characteristics, and there is the consequent danger that a large number 57of duplicate pens will be created. Therefore an application may wish to 58get a pointer to a pen by using the global list of pens {\bf 59wxThePenList}, and calling the member function {\bf FindOrCreatePen}. 60See the entry for \helpref{wxPenList}{wxpenlist}. 61 62This class uses \helpref{reference counting and copy-on-write}{trefcount} 63internally so that assignments between two instances of this class are very 64cheap. You can therefore use actual objects instead of pointers without 65efficiency problems. If an instance of this class is changed it will create 66its own data internally so that other instances, which previously shared the 67data 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 80Default constructor. The pen will be uninitialised, and \helpref{wxPen:IsOk}{wxpenisok} will 81return false. 82 83\func{}{wxPen}{\param{const wxColour\&}{ colour}, \param{int}{ width = $1$}, \param{int}{ style = {\tt wxSOLID}}} 84 85Constructs 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 89Constructs a pen from a colour name, pen width and style. 90 91\func{}{wxPen}{\param{const wxBitmap\&}{ stipple}, \param{int}{ width}} 92 93Constructs a stippled pen from a stipple bitmap and a width. 94 95\func{}{wxPen}{\param{const wxPen\&}{ pen}} 96 97Copy 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 106the 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 133Different versions of Windows and different versions of other platforms 134support {\it very} different subsets of the styles above - there is no 135similarity even between Windows95 and Windows98 - so handle with care. 136 137If the named colour form is used, an appropriate {\bf wxColour} structure 138is 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 157Destructor. 158See \helpref{reference-counted object destruction}{refcountdestruct} for more info. 159 160\wxheading{Remarks} 161 162Although all remaining pens are deleted when the application exits, 163the application should try to clean up all pens itself. This is because 164wxWidgets cannot know if a pointer to the pen object is stored in an 165application data structure, and there is a risk of double deletion. 166 167\membersection{wxPen::GetCap}\label{wxpengetcap} 168 169\constfunc{int}{GetCap}{\void} 170 171Returns 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 182Returns 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 192Gets 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. 194The 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 204Returns 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 215Gets 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 225Returns 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 235Returns 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 245Returns true if the pen is initialised. 246 247\membersection{wxPen::SetCap}\label{wxpensetcap} 248 249\func{void}{SetCap}{\param{int}{ capStyle}} 250 251Sets 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 266The 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 276Associates an array of pointers to dashes (defined as char in X, DWORD under Windows) 277with the pen. The array is not deallocated by wxPen, but neither must it be 278deallocated by the calling application until the pen is deleted or this 279function 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 290Sets 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 301Sets 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 311Set 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 321Sets 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 331Assignment operator, using \helpref{reference counting}{trefcount}. 332 333\membersection{wxPen::operator $==$}\label{wxpenequals} 334 335\func{bool}{operator $==$}{\param{const wxPen\& }{pen}} 336 337Equality operator. 338See \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 344Inequality operator. 345See \helpref{reference-counted object comparison}{refcountequality} for more info. 346 347\section{\class{wxPenList}}\label{wxpenlist} 348 349There is only one instance of this class: {\bf wxThePenList}. Use 350this object to search for a previously created pen of the desired 351type and create it if not already found. In some windowing systems, 352the pen may be a scarce resource, so it can pay to reuse old 353resources if possible. When an application finishes, all pens will 354be deleted and their resources freed, eliminating the possibility of 355`memory leaks'. However, it is best not to rely on this automatic 356cleanup because it can lead to double deletion in some circumstances. 357 358There are two mechanisms in recent versions of wxWidgets which make the 359pen list less useful than it once was. Under Windows, scarce resources 360are cleaned up internally if they are not being used. Also, a referencing 361counting mechanism applied to all GDI objects means that some sharing 362of underlying resources is possible. You don't have to keep track of pointers, 363working out when it is safe delete a pen, because the referencing counting does 364it for you. For example, you can set a pen in a device context, and then 365immediately delete the pen you passed, because the pen is `copied'. 366 367So you may find it easier to ignore the pen list, and instead create 368and copy pens as you see fit. If your Windows resource meter suggests 369your application is using too many resources, you can resort to using 370GDI lists to share objects explicitly. 371 372The only compelling use for the pen list is for wxWidgets to keep 373track of pens in order to clean them up on exit. It is also kept for 374backward 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 386Constructor. The application should not construct its own pen list: 387use 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 393Finds a pen with the specified attributes and returns it, else creates a new pen, adds it 394to the pen list, and returns it. 395 396\func{wxPen*}{FindOrCreatePen}{\param{const wxString\& }{colourName}, \param{int}{ width}, \param{int}{ style}} 397 398Finds a pen with the specified attributes and returns it, else creates a new pen, adds it 399to 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 411