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