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