source: trunk/doc/html/qcanvas.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 35.3 KB
RevLine 
[190]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/canvas/qcanvas.cpp:435 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QCanvas Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QCanvas Class Reference<br><small>[<a href="canvas.html">canvas module</a>]</small></h1>
33
34<p>The QCanvas class provides a 2D area that can contain QCanvasItem objects.
35<a href="#details">More...</a>
36<p><tt>#include &lt;<a href="qcanvas-h.html">qcanvas.h</a>&gt;</tt>
37<p>Inherits <a href="qobject.html">QObject</a>.
38<p><a href="qcanvas-members.html">List of all member functions.</a>
39<h2>Public Members</h2>
40<ul>
41<li class=fn><a href="#QCanvas"><b>QCanvas</b></a> ( QObject&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )</li>
42<li class=fn><a href="#QCanvas-2"><b>QCanvas</b></a> ( int&nbsp;w, int&nbsp;h )</li>
43<li class=fn><a href="#QCanvas-3"><b>QCanvas</b></a> ( QPixmap&nbsp;p, int&nbsp;h, int&nbsp;v, int&nbsp;tilewidth, int&nbsp;tileheight )</li>
44<li class=fn>virtual <a href="#~QCanvas"><b>~QCanvas</b></a> ()</li>
45<li class=fn>virtual void <a href="#setTiles"><b>setTiles</b></a> ( QPixmap&nbsp;p, int&nbsp;h, int&nbsp;v, int&nbsp;tilewidth, int&nbsp;tileheight )</li>
46<li class=fn>virtual void <a href="#setBackgroundPixmap"><b>setBackgroundPixmap</b></a> ( const&nbsp;QPixmap&nbsp;&amp;&nbsp;p )</li>
47<li class=fn>QPixmap <a href="#backgroundPixmap"><b>backgroundPixmap</b></a> () const</li>
48<li class=fn>virtual void <a href="#setBackgroundColor"><b>setBackgroundColor</b></a> ( const&nbsp;QColor&nbsp;&amp;&nbsp;c )</li>
49<li class=fn>QColor <a href="#backgroundColor"><b>backgroundColor</b></a> () const</li>
50<li class=fn>virtual void <a href="#setTile"><b>setTile</b></a> ( int&nbsp;x, int&nbsp;y, int&nbsp;tilenum )</li>
51<li class=fn>int <a href="#tile"><b>tile</b></a> ( int&nbsp;x, int&nbsp;y ) const</li>
52<li class=fn>int <a href="#tilesHorizontally"><b>tilesHorizontally</b></a> () const</li>
53<li class=fn>int <a href="#tilesVertically"><b>tilesVertically</b></a> () const</li>
54<li class=fn>int <a href="#tileWidth"><b>tileWidth</b></a> () const</li>
55<li class=fn>int <a href="#tileHeight"><b>tileHeight</b></a> () const</li>
56<li class=fn>virtual void <a href="#resize"><b>resize</b></a> ( int&nbsp;w, int&nbsp;h )</li>
57<li class=fn>int <a href="#width"><b>width</b></a> () const</li>
58<li class=fn>int <a href="#height"><b>height</b></a> () const</li>
59<li class=fn>QSize <a href="#size"><b>size</b></a> () const</li>
60<li class=fn>QRect <a href="#rect"><b>rect</b></a> () const</li>
61<li class=fn>bool <a href="#onCanvas"><b>onCanvas</b></a> ( int&nbsp;x, int&nbsp;y ) const</li>
62<li class=fn>bool <a href="#onCanvas-2"><b>onCanvas</b></a> ( const&nbsp;QPoint&nbsp;&amp;&nbsp;p ) const</li>
63<li class=fn>bool <a href="#validChunk"><b>validChunk</b></a> ( int&nbsp;x, int&nbsp;y ) const</li>
64<li class=fn>bool <a href="#validChunk-2"><b>validChunk</b></a> ( const&nbsp;QPoint&nbsp;&amp;&nbsp;p ) const</li>
65<li class=fn>int <a href="#chunkSize"><b>chunkSize</b></a> () const</li>
66<li class=fn>virtual void <a href="#retune"><b>retune</b></a> ( int&nbsp;chunksze, int&nbsp;mxclusters = 100 )</li>
67<li class=fn>virtual void <a href="#setAllChanged"><b>setAllChanged</b></a> ()</li>
68<li class=fn>virtual void <a href="#setChanged"><b>setChanged</b></a> ( const&nbsp;QRect&nbsp;&amp;&nbsp;area )</li>
69<li class=fn>virtual void <a href="#setUnchanged"><b>setUnchanged</b></a> ( const&nbsp;QRect&nbsp;&amp;&nbsp;area )</li>
70<li class=fn>QCanvasItemList <a href="#allItems"><b>allItems</b></a> ()</li>
71<li class=fn>QCanvasItemList <a href="#collisions"><b>collisions</b></a> ( const&nbsp;QPoint&nbsp;&amp;&nbsp;p ) const</li>
72<li class=fn>QCanvasItemList <a href="#collisions-2"><b>collisions</b></a> ( const&nbsp;QRect&nbsp;&amp;&nbsp;r ) const</li>
73<li class=fn>QCanvasItemList <a href="#collisions-3"><b>collisions</b></a> ( const&nbsp;QPointArray&nbsp;&amp;&nbsp;chunklist, const&nbsp;QCanvasItem&nbsp;*&nbsp;item, bool&nbsp;exact ) const</li>
74<li class=fn>void <a href="#drawArea"><b>drawArea</b></a> ( const&nbsp;QRect&nbsp;&amp;&nbsp;clip, QPainter&nbsp;*&nbsp;painter, bool&nbsp;dbuf = FALSE )</li>
75<li class=fn>virtual void <a href="#setAdvancePeriod"><b>setAdvancePeriod</b></a> ( int&nbsp;ms )</li>
76<li class=fn>virtual void <a href="#setUpdatePeriod"><b>setUpdatePeriod</b></a> ( int&nbsp;ms )</li>
77<li class=fn>virtual void <a href="#setDoubleBuffering"><b>setDoubleBuffering</b></a> ( bool&nbsp;y )</li>
78</ul>
79<h2>Public Slots</h2>
80<ul>
81<li class=fn>virtual void <a href="#advance"><b>advance</b></a> ()</li>
82<li class=fn>virtual void <a href="#update"><b>update</b></a> ()</li>
83</ul>
84<h2>Signals</h2>
85<ul>
86<li class=fn>void <a href="#resized"><b>resized</b></a> ()</li>
87</ul>
88<h2>Protected Members</h2>
89<ul>
90<li class=fn>virtual void <a href="#drawBackground"><b>drawBackground</b></a> ( QPainter&nbsp;&amp;&nbsp;painter, const&nbsp;QRect&nbsp;&amp;&nbsp;clip )</li>
91<li class=fn>virtual void <a href="#drawForeground"><b>drawForeground</b></a> ( QPainter&nbsp;&amp;&nbsp;painter, const&nbsp;QRect&nbsp;&amp;&nbsp;clip )</li>
92</ul>
93<hr><a name="details"></a><h2>Detailed Description</h2>
94
95
96The QCanvas class provides a 2D area that can contain <a href="qcanvasitem.html">QCanvasItem</a> objects.
97
98<p>
99
100
101
102
103<p> The QCanvas class manages its 2D graphic area and all the canvas
104items the area contains. The canvas has no visual appearance of
105its own. Instead, it is displayed on screen using a <a href="qcanvasview.html">QCanvasView</a>.
106Multiple QCanvasView widgets may be associated with a canvas to
107provide multiple views of the same canvas.
108<p> The canvas is optimized for large numbers of items, particularly
109where only a small percentage of the items change at any
110one time. If the entire display changes very frequently, you should
111consider using your own custom <a href="qscrollview.html">QScrollView</a> subclass.
112<p> Qt provides a rich
113set of canvas item classes, e.g. <a href="qcanvasellipse.html">QCanvasEllipse</a>, <a href="qcanvasline.html">QCanvasLine</a>,
114<a href="qcanvaspolygon.html">QCanvasPolygon</a>, <a href="qcanvaspolygonalitem.html">QCanvasPolygonalItem</a>, <a href="qcanvasrectangle.html">QCanvasRectangle</a>, <a href="qcanvasspline.html">QCanvasSpline</a>,
115<a href="qcanvassprite.html">QCanvasSprite</a> and <a href="qcanvastext.html">QCanvasText</a>. You can subclass to create your own
116canvas items; QCanvasPolygonalItem is the most common base class used
117for this purpose.
118<p> Items appear on the canvas after their <a href="qcanvasitem.html#show">show()</a> function has been called (or <a href="qcanvasitem.html#setVisible">setVisible(TRUE)</a>), and <em>after</em>
119<a href="#update">update</a>() has been called. The canvas only shows items that are
120<a href="qcanvasitem.html#setVisible">visible</a>, and then only if
121<a href="#update">update</a>() is called. (By default the canvas is white and so are
122canvas items, so if nothing appears try changing colors.)
123<p> If you created the canvas without passing a width and height to
124the constructor you must also call <a href="#resize">resize</a>().
125<p> Although a canvas may appear to be similar to a widget with child
126widgets, there are several notable differences:
127<p> <ul>
128<li> Canvas items are usually much faster to manipulate and redraw than
129child widgets, with the speed advantage becoming especially great when
130there are <em>many</em> canvas items and non-rectangular items. In most
131situations canvas items are also a lot more memory efficient than child
132widgets.
133<p> <li> It's easy to detect overlapping items (collision detection).
134<p> <li> The canvas can be larger than a widget. A million-by-million canvas
135is perfectly possible. At such a size a widget might be very
136inefficient, and some window systems might not support it at all,
137whereas QCanvas scales well. Even with a billion pixels and a million
138items, finding a particular canvas item, detecting collisions, etc.,
139is still fast (though the memory consumption may be prohibitive
140at such extremes).
141<p> <li> Two or more <a href="qcanvasview.html">QCanvasView</a> objects can view the same canvas.
142<p> <li> An arbitrary <a href="qwmatrix.html#TransformationMode">transformation matrix</a> can be set on each QCanvasView
143which makes it easy to zoom, rotate or shear the viewed canvas.
144<p> <li> Widgets provide a lot more functionality, such as input (<a href="qkeyevent.html">QKeyEvent</a>,
145<a href="qmouseevent.html">QMouseEvent</a> etc.) and layout management (<a href="qgridlayout.html">QGridLayout</a> etc.).
146<p> </ul>
147<p> A canvas consists of a background, a number of canvas items organized by
148x, y and z coordinates, and a foreground. A canvas item's z coordinate
149can be treated as a layer number -- canvas items with a higher z
150coordinate appear in front of canvas items with a lower z coordinate.
151<p> The background is white by default, but can be set to a different color
152using <a href="#setBackgroundColor">setBackgroundColor</a>(), or to a repeated pixmap using
153<a href="#setBackgroundPixmap">setBackgroundPixmap</a>() or to a mosaic of smaller pixmaps using
154<a href="#setTiles">setTiles</a>(). Individual tiles can be set with <a href="#setTile">setTile</a>(). There
155are corresponding get functions, e.g. <a href="#backgroundColor">backgroundColor</a>() and
156<a href="#backgroundPixmap">backgroundPixmap</a>().
157<p> Note that QCanvas does not inherit from <a href="qwidget.html">QWidget</a>, even though it has some
158functions which provide the same functionality as those in QWidget. One
159of these is setBackgroundPixmap(); some others are <a href="#resize">resize</a>(), <a href="#size">size</a>(),
160<a href="#width">width</a>() and <a href="#height">height</a>(). <a href="qcanvasview.html">QCanvasView</a> is the widget used to display a
161canvas on the screen.
162<p> Canvas items are added to a canvas by constructing them and passing the
163canvas to the canvas item's constructor. An item can be moved to a
164different canvas using <a href="qcanvasitem.html#setCanvas">QCanvasItem::setCanvas</a>().
165<p> Canvas items are movable (and in the case of QCanvasSprites, animated)
166objects that inherit <a href="qcanvasitem.html">QCanvasItem</a>. Each canvas item has a position on the
167canvas (x, y coordinates) and a height (z coordinate), all of which are
168held as floating-point numbers. Moving canvas items also have x and y
169velocities. It's possible for a canvas item to be outside the canvas
170(for example <a href="qcanvasitem.html#x">QCanvasItem::x</a>() is greater than width()). When a canvas
171item is off the canvas, <a href="#onCanvas">onCanvas</a>() returns FALSE and the canvas
172disregards the item. (Canvas items off the canvas do not slow down any
173of the common operations on the canvas.)
174<p> Canvas items can be moved with <a href="qcanvasitem.html#move">QCanvasItem::move</a>(). The <a href="#advance">advance</a>()
175function moves all <a href="qcanvasitem.html#animated">QCanvasItem::animated</a>() canvas items and
176<a href="#setAdvancePeriod">setAdvancePeriod</a>() makes QCanvas move them automatically on a periodic
177basis. In the context of the QCanvas classes, to `animate' a canvas item
178is to set it in motion, i.e. using <a href="qcanvasitem.html#setVelocity">QCanvasItem::setVelocity</a>(). Animation
179of a canvas item itself, i.e. items which change over time, is enabled
180by calling <a href="qcanvassprite.html#setFrameAnimation">QCanvasSprite::setFrameAnimation</a>(), or more generally by
181subclassing and reimplementing <a href="qcanvasitem.html#advance">QCanvasItem::advance</a>(). To detect collisions
182use one of the <a href="qcanvasitem.html#collisions">QCanvasItem::collisions</a>() functions.
183<p> The changed parts of the canvas are redrawn (if they are visible in a
184canvas view) whenever <a href="#update">update</a>() is called. You can either call update()
185manually after having changed the contents of the canvas, or force
186periodic updates using <a href="#setUpdatePeriod">setUpdatePeriod</a>(). If you have moving objects on
187the canvas, you must call <a href="#advance">advance</a>() every time the objects should
188move one step further. Periodic calls to advance() can be forced using
189<a href="#setAdvancePeriod">setAdvancePeriod</a>(). The advance() function will call
190QCanvasItem::advance() on every item that is <a href="qcanvasitem.html#animated">animated</a> and trigger an update of the
191affected areas afterwards. (A canvas item that is `animated' is simply
192a canvas item that is in motion.)
193<p> QCanvas organizes its canvas items into <em>chunks</em>; these are areas on
194the canvas that are used to speed up most operations. Many operations
195start by eliminating most chunks (i.e. those which haven't changed)
196and then process only the canvas items that are in the few interesting
197(i.e. changed) chunks. A valid chunk, <a href="#validChunk">validChunk</a>(), is one which is on
198the canvas.
199<p> The chunk size is a key factor to QCanvas's speed: if there are too many
200chunks, the speed benefit of grouping canvas items into chunks is
201reduced. If the chunks are too large, it takes too long to process each
202one. The QCanvas constructor tries to pick a suitable size, but you
203can call <a href="#retune">retune</a>() to change it at any time. The <a href="#chunkSize">chunkSize</a>() function
204returns the current chunk size. The canvas items always make sure
205they're in the right chunks; all you need to make sure of is that
206the canvas uses the right chunk size. A good rule of thumb is that
207the size should be a bit smaller than the average canvas item
208size. If you have moving objects, the chunk size should be a bit
209smaller than the average size of the moving items.
210<p> The foreground is normally nothing, but if you reimplement
211<a href="#drawForeground">drawForeground</a>(), you can draw things in front of all the canvas
212items.
213<p> Areas can be set as changed with <a href="#setChanged">setChanged</a>() and set unchanged with
214<a href="#setUnchanged">setUnchanged</a>(). The entire canvas can be set as changed with
215<a href="#setAllChanged">setAllChanged</a>(). A list of all the items on the canvas is returned by
216<a href="#allItems">allItems</a>().
217<p> An area can be copied (painted) to a <a href="qpainter.html">QPainter</a> with <a href="#drawArea">drawArea</a>().
218<p> If the canvas is resized it emits the <a href="#resized">resized</a>() signal.
219<p> The examples/canvas application and the 2D graphics page of the
220examples/demo application demonstrate many of QCanvas's facilities.
221<p> <p>See also <a href="qcanvasview.html">QCanvasView</a>, <a href="qcanvasitem.html">QCanvasItem</a>, <a href="abstractwidgets.html">Abstract Widget Classes</a>, <a href="graphics.html">Graphics Classes</a>, and <a href="images.html">Image Processing Classes</a>.
222
223<hr><h2>Member Function Documentation</h2>
224<h3 class=fn><a name="QCanvas"></a>QCanvas::QCanvas ( <a href="qobject.html">QObject</a>&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )
225</h3>
226Create a QCanvas with no size. <em>parent</em> and <em>name</em> are passed to
227the <a href="qobject.html">QObject</a> superclass.
228<p> <b>Warning:</b> You <em>must</em> call <a href="#resize">resize</a>() at some time after creation to
229be able to use the canvas.
230
231<h3 class=fn><a name="QCanvas-2"></a>QCanvas::QCanvas ( int&nbsp;w, int&nbsp;h )
232</h3>
233Constructs a QCanvas that is <em>w</em> pixels wide and <em>h</em> pixels high.
234
235<h3 class=fn><a name="QCanvas-3"></a>QCanvas::QCanvas ( <a href="qpixmap.html">QPixmap</a>&nbsp;p, int&nbsp;h, int&nbsp;v, int&nbsp;tilewidth, int&nbsp;tileheight )
236</h3>
237Constructs a QCanvas which will be composed of <em>h</em> tiles
238horizontally and <em>v</em> tiles vertically. Each tile will be an image
239<em>tilewidth</em> by <em>tileheight</em> pixels taken from pixmap <em>p</em>.
240<p> The pixmap <em>p</em> is a list of tiles, arranged left to right, (and
241in the case of pixmaps that have multiple rows of tiles, top to
242bottom), with tile 0 in the top-left corner, tile 1 next to the
243right, and so on, e.g.
244<p> <center><table cellpadding="4" cellspacing="2" border="0">
245<tr bgcolor="#f0f0f0"> <td valign="top">0 <td valign="top">1 <td valign="top">2 <td valign="top">3
246<tr bgcolor="#d0d0d0"> <td valign="top">4 <td valign="top">5 <td valign="top">6 <td valign="top">7
247</table></center>
248<p> The QCanvas is initially sized to show exactly the given number of
249tiles horizontally and vertically. If it is resized to be larger,
250the entire matrix of tiles will be repeated as often as necessary
251to cover the area. If it is smaller, tiles to the right and bottom
252will not be visible.
253<p> <p>See also <a href="#setTiles">setTiles</a>().
254
255<h3 class=fn><a name="~QCanvas"></a>QCanvas::~QCanvas ()<tt> [virtual]</tt>
256</h3>
257Destroys the canvas and all the canvas's canvas items.
258
259<h3 class=fn>void <a name="advance"></a>QCanvas::advance ()<tt> [virtual slot]</tt>
260</h3>
261Moves all <a href="qcanvasitem.html#animated">QCanvasItem::animated</a>() canvas items on the canvas and
262refreshes all changes to all views of the canvas. (An `animated'
263item is an item that is in motion; see setVelocity().)
264<p> The advance takes place in two phases. In phase 0, the
265<a href="qcanvasitem.html#advance">QCanvasItem::advance</a>() function of each QCanvasItem::animated()
266canvas item is called with paramater 0. Then all these canvas
267items are called again, with parameter 1. In phase 0, the canvas
268items should not change position, merely examine other items on
269the canvas for which special processing is required, such as
270collisions between items. In phase 1, all canvas items should
271change positions, ignoring any other items on the canvas. This
272two-phase approach allows for considerations of "fairness",
273although no <a href="qcanvasitem.html">QCanvasItem</a> subclasses supplied with Qt do anything
274interesting in phase 0.
275<p> The canvas can be configured to call this function periodically
276with <a href="#setAdvancePeriod">setAdvancePeriod</a>().
277<p> <p>See also <a href="#update">update</a>().
278
279<h3 class=fn><a href="qcanvasitemlist.html">QCanvasItemList</a> <a name="allItems"></a>QCanvas::allItems ()
280</h3>
281Returns a list of all the items in the canvas.
282
283<h3 class=fn><a href="qcolor.html">QColor</a> <a name="backgroundColor"></a>QCanvas::backgroundColor () const
284</h3>
285Returns the color set by <a href="#setBackgroundColor">setBackgroundColor</a>(). By default, this is
286white.
287<p> This function is not a reimplementation of
288<a href="qwidget.html#backgroundColor">QWidget::backgroundColor</a>() (QCanvas is not a subclass of <a href="qwidget.html">QWidget</a>),
289but all QCanvasViews that are viewing the canvas will set their
290backgrounds to this color.
291<p> <p>See also <a href="#setBackgroundColor">setBackgroundColor</a>() and <a href="#backgroundPixmap">backgroundPixmap</a>().
292
293<h3 class=fn><a href="qpixmap.html">QPixmap</a> <a name="backgroundPixmap"></a>QCanvas::backgroundPixmap () const
294</h3>
295Returns the pixmap set by <a href="#setBackgroundPixmap">setBackgroundPixmap</a>(). By default,
296this is a null pixmap.
297<p> <p>See also <a href="#setBackgroundPixmap">setBackgroundPixmap</a>() and <a href="#backgroundColor">backgroundColor</a>().
298
299<h3 class=fn>int <a name="chunkSize"></a>QCanvas::chunkSize () const
300</h3>
301
302<p> Returns the chunk size of the canvas.
303<p> <p>See also <a href="#retune">retune</a>().
304
305<h3 class=fn><a href="qcanvasitemlist.html">QCanvasItemList</a> <a name="collisions"></a>QCanvas::collisions ( const&nbsp;<a href="qpoint.html">QPoint</a>&nbsp;&amp;&nbsp;p ) const
306</h3>
307Returns a list of canvas items that collide with the point <em>p</em>.
308The list is ordered by z coordinates, from highest z coordinate
309(front-most item) to lowest z coordinate (rear-most item).
310
311<h3 class=fn><a href="qcanvasitemlist.html">QCanvasItemList</a> <a name="collisions-2"></a>QCanvas::collisions ( const&nbsp;<a href="qrect.html">QRect</a>&nbsp;&amp;&nbsp;r ) const
312</h3>
313This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
314<p> Returns a list of items which collide with the rectangle <em>r</em>. The
315list is ordered by z coordinates, from highest z coordinate
316(front-most item) to lowest z coordinate (rear-most item).
317
318<h3 class=fn><a href="qcanvasitemlist.html">QCanvasItemList</a> <a name="collisions-3"></a>QCanvas::collisions ( const&nbsp;<a href="qpointarray.html">QPointArray</a>&nbsp;&amp;&nbsp;chunklist, const&nbsp;<a href="qcanvasitem.html">QCanvasItem</a>&nbsp;*&nbsp;item, bool&nbsp;exact ) const
319</h3>
320This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
321<p> Returns a list of canvas items which intersect with the chunks
322listed in <em>chunklist</em>, excluding <em>item</em>. If <em>exact</em> is TRUE,
323only those which actually <a href="qcanvasitem.html#collidesWith">collide with</a> <em>item</em> are returned; otherwise canvas items
324are included just for being in the chunks.
325<p> This is a utility function mainly used to implement the simpler
326<a href="qcanvasitem.html#collisions">QCanvasItem::collisions</a>() function.
327
328<h3 class=fn>void <a name="drawArea"></a>QCanvas::drawArea ( const&nbsp;<a href="qrect.html">QRect</a>&nbsp;&amp;&nbsp;clip, <a href="qpainter.html">QPainter</a>&nbsp;*&nbsp;painter, bool&nbsp;dbuf = FALSE )
329</h3>
330Paints all canvas items that are in the area <em>clip</em> to <em>painter</em>, using double-buffering if <em>dbuf</em> is TRUE.
331<p> e.g. to print the canvas to a printer:
332<pre>
333 <a href="qprinter.html">QPrinter</a> pr;
334 if ( pr.<a href="qprinter.html#setup">setup</a>() ) {
335 <a href="qpainter.html">QPainter</a> p(&amp;pr);
336 canvas.drawArea( canvas.rect(), &amp;p );
337 }
338 </pre>
339
340
341<p>Example: <a href="canvas-example.html#x2908">canvas/canvas.cpp</a>.
342<h3 class=fn>void <a name="drawBackground"></a>QCanvas::drawBackground ( <a href="qpainter.html">QPainter</a>&nbsp;&amp;&nbsp;painter, const&nbsp;<a href="qrect.html">QRect</a>&nbsp;&amp;&nbsp;clip )<tt> [virtual protected]</tt>
343</h3>
344This virtual function is called for all updates of the canvas. It
345renders any background graphics using the painter <em>painter</em>, in
346the area <em>clip</em>. If the canvas has a background pixmap or a tiled
347background, that graphic is used, otherwise the canvas is cleared
348using the background color.
349<p> If the graphics for an area change, you must explicitly call
350<a href="#setChanged">setChanged</a>(const <a href="qrect.html">QRect</a>&) for the result to be visible when
351<a href="#update">update</a>() is next called.
352<p> <p>See also <a href="#setBackgroundColor">setBackgroundColor</a>(), <a href="#setBackgroundPixmap">setBackgroundPixmap</a>(), and <a href="#setTiles">setTiles</a>().
353
354<h3 class=fn>void <a name="drawForeground"></a>QCanvas::drawForeground ( <a href="qpainter.html">QPainter</a>&nbsp;&amp;&nbsp;painter, const&nbsp;<a href="qrect.html">QRect</a>&nbsp;&amp;&nbsp;clip )<tt> [virtual protected]</tt>
355</h3>
356This virtual function is called for all updates of the canvas. It
357renders any foreground graphics using the painter <em>painter</em>, in
358the area <em>clip</em>.
359<p> If the graphics for an area change, you must explicitly call
360<a href="#setChanged">setChanged</a>(const <a href="qrect.html">QRect</a>&) for the result to be visible when
361<a href="#update">update</a>() is next called.
362<p> The default is to draw nothing.
363
364<h3 class=fn>int <a name="height"></a>QCanvas::height () const
365</h3>
366
367<p> Returns the height of the canvas, in pixels.
368
369<p>Example: <a href="canvas-example.html#x2909">canvas/canvas.cpp</a>.
370<h3 class=fn>bool <a name="onCanvas"></a>QCanvas::onCanvas ( int&nbsp;x, int&nbsp;y ) const
371</h3>
372
373<p> Returns TRUE if the pixel position (<em>x</em>, <em>y</em>) is on the canvas;
374otherwise returns FALSE.
375<p> <p>See also <a href="#validChunk">validChunk</a>().
376
377<h3 class=fn>bool <a name="onCanvas-2"></a>QCanvas::onCanvas ( const&nbsp;<a href="qpoint.html">QPoint</a>&nbsp;&amp;&nbsp;p ) const
378</h3>
379
380This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
381<p> Returns TRUE if the pixel position <em>p</em> is on the canvas;
382otherwise returns FALSE.
383<p> <p>See also <a href="#validChunk">validChunk</a>().
384
385<h3 class=fn><a href="qrect.html">QRect</a> <a name="rect"></a>QCanvas::rect () const
386</h3>
387
388<p> Returns a rectangle the size of the canvas.
389
390<h3 class=fn>void <a name="resize"></a>QCanvas::resize ( int&nbsp;w, int&nbsp;h )<tt> [virtual]</tt>
391</h3>
392Changes the size of the canvas to have a width of <em>w</em> and a
393height of <em>h</em>. This is a slow operation.
394
395<p>Examples: <a href="canvas-example.html#x2910">canvas/canvas.cpp</a> and <a href="canvas-chart-example.html#x2876">chart/chartform.cpp</a>.
396<h3 class=fn>void <a name="resized"></a>QCanvas::resized ()<tt> [signal]</tt>
397</h3>
398
399<p> This signal is emitted whenever the canvas is resized. Each
400<a href="qcanvasview.html">QCanvasView</a> connects to this signal to keep the scrollview's size
401correct.
402
403<h3 class=fn>void <a name="retune"></a>QCanvas::retune ( int&nbsp;chunksze, int&nbsp;mxclusters = 100 )<tt> [virtual]</tt>
404</h3>
405Change the efficiency tuning parameters to <em>mxclusters</em> clusters,
406each of size <em>chunksze</em>. This is a slow operation if there are
407many objects on the canvas.
408<p> The canvas is divided into chunks which are rectangular areas <em>chunksze</em> wide by <em>chunksze</em> high. Use a chunk size which is about
409the average size of the canvas items. If you choose a chunk size
410which is too small it will increase the amount of calculation
411required when drawing since each change will affect many chunks.
412If you choose a chunk size which is too large the amount of
413drawing required will increase because for each change, a lot of
414drawing will be required since there will be many (unchanged)
415canvas items which are in the same chunk as the changed canvas
416items.
417<p> Internally, a canvas uses a low-resolution "chunk matrix" to keep
418track of all the items in the canvas. A 64x64 chunk matrix is the
419default for a 1024x1024 pixel canvas, where each chunk collects
420canvas items in a 16x16 pixel square. This default is also
421affected by <a href="#setTiles">setTiles</a>(). You can tune this default using this
422function. For example if you have a very large canvas and want to
423trade off speed for memory then you might set the chunk size to 32
424or 64.
425<p> The <em>mxclusters</em> argument is the number of rectangular groups of
426chunks that will be separately drawn. If the canvas has a large
427number of small, dispersed items, this should be about that
428number. Our testing suggests that a large number of clusters is
429almost always best.
430<p>
431<h3 class=fn>void <a name="setAdvancePeriod"></a>QCanvas::setAdvancePeriod ( int&nbsp;ms )<tt> [virtual]</tt>
432</h3>
433Sets the canvas to call <a href="#advance">advance</a>() every <em>ms</em> milliseconds. Any
434previous setting by <a href="#setAdvancePeriod">setAdvancePeriod</a>() or <a href="#setUpdatePeriod">setUpdatePeriod</a>() is
435overridden.
436<p> If <em>ms</em> is less than 0 advancing will be stopped.
437
438<p>Example: <a href="canvas-example.html#x2962">canvas/main.cpp</a>.
439<h3 class=fn>void <a name="setAllChanged"></a>QCanvas::setAllChanged ()<tt> [virtual]</tt>
440</h3>
441Marks the whole canvas as changed.
442All views of the canvas will be entirely redrawn when
443<a href="#update">update</a>() is called next.
444
445<h3 class=fn>void <a name="setBackgroundColor"></a>QCanvas::setBackgroundColor ( const&nbsp;<a href="qcolor.html">QColor</a>&nbsp;&amp;&nbsp;c )<tt> [virtual]</tt>
446</h3>
447Sets the solid background to be the color <em>c</em>.
448<p> <p>See also <a href="#backgroundColor">backgroundColor</a>(), <a href="#setBackgroundPixmap">setBackgroundPixmap</a>(), and <a href="#setTiles">setTiles</a>().
449
450<h3 class=fn>void <a name="setBackgroundPixmap"></a>QCanvas::setBackgroundPixmap ( const&nbsp;<a href="qpixmap.html">QPixmap</a>&nbsp;&amp;&nbsp;p )<tt> [virtual]</tt>
451</h3>
452Sets the solid background to be the pixmap <em>p</em> repeated as
453necessary to cover the entire canvas.
454<p> <p>See also <a href="#backgroundPixmap">backgroundPixmap</a>(), <a href="#setBackgroundColor">setBackgroundColor</a>(), and <a href="#setTiles">setTiles</a>().
455
456<h3 class=fn>void <a name="setChanged"></a>QCanvas::setChanged ( const&nbsp;<a href="qrect.html">QRect</a>&nbsp;&amp;&nbsp;area )<tt> [virtual]</tt>
457</h3>
458Marks <em>area</em> as changed. This <em>area</em> will be redrawn in all
459views that are showing it when <a href="#update">update</a>() is called next.
460
461<h3 class=fn>void <a name="setDoubleBuffering"></a>QCanvas::setDoubleBuffering ( bool&nbsp;y )<tt> [virtual]</tt>
462</h3>
463If <em>y</em> is TRUE (the default) double-buffering is switched on;
464otherwise double-buffering is switched off.
465<p> Turning off double-buffering causes the redrawn areas to flicker a
466little and also gives a (usually small) performance improvement.
467
468<p>Example: <a href="canvas-example.html#x2911">canvas/canvas.cpp</a>.
469<h3 class=fn>void <a name="setTile"></a>QCanvas::setTile ( int&nbsp;x, int&nbsp;y, int&nbsp;tilenum )<tt> [virtual]</tt>
470</h3>
471Sets the tile at (<em>x</em>, <em>y</em>) to use tile number <em>tilenum</em>, which
472is an index into the tile pixmaps. The canvas will update
473appropriately when <a href="#update">update</a>() is next called.
474<p> The images are taken from the pixmap set by <a href="#setTiles">setTiles</a>() and are
475arranged left to right, (and in the case of pixmaps that have
476multiple rows of tiles, top to bottom), with tile 0 in the
477top-left corner, tile 1 next to the right, and so on, e.g.
478<p> <center><table cellpadding="4" cellspacing="2" border="0">
479<tr bgcolor="#f0f0f0"> <td valign="top">0 <td valign="top">1 <td valign="top">2 <td valign="top">3
480<tr bgcolor="#d0d0d0"> <td valign="top">4 <td valign="top">5 <td valign="top">6 <td valign="top">7
481</table></center>
482<p> <p>See also <a href="#tile">tile</a>() and <a href="#setTiles">setTiles</a>().
483
484<h3 class=fn>void <a name="setTiles"></a>QCanvas::setTiles ( <a href="qpixmap.html">QPixmap</a>&nbsp;p, int&nbsp;h, int&nbsp;v, int&nbsp;tilewidth, int&nbsp;tileheight )<tt> [virtual]</tt>
485</h3>
486Sets the QCanvas to be composed of <em>h</em> tiles horizontally and <em>v</em> tiles vertically. Each tile will be an image <em>tilewidth</em> by <em>tileheight</em> pixels from pixmap <em>p</em>.
487<p> The pixmap <em>p</em> is a list of tiles, arranged left to right, (and
488in the case of pixmaps that have multiple rows of tiles, top to
489bottom), with tile 0 in the top-left corner, tile 1 next to the
490right, and so on, e.g.
491<p> <center><table cellpadding="4" cellspacing="2" border="0">
492<tr bgcolor="#f0f0f0"> <td valign="top">0 <td valign="top">1 <td valign="top">2 <td valign="top">3
493<tr bgcolor="#d0d0d0"> <td valign="top">4 <td valign="top">5 <td valign="top">6 <td valign="top">7
494</table></center>
495<p> If the canvas is larger than the matrix of tiles, the entire
496matrix is repeated as necessary to cover the whole canvas. If it
497is smaller, tiles to the right and bottom are not visible.
498<p> The width and height of <em>p</em> must be a multiple of <em>tilewidth</em>
499and <em>tileheight</em>. If they are not the function will do nothing.
500<p> If you want to unset any tiling set, then just pass in a null
501pixmap and 0 for <em>h</em>, <em>v</em>, <em>tilewidth</em>, and
502<em>tileheight</em>.
503
504<h3 class=fn>void <a name="setUnchanged"></a>QCanvas::setUnchanged ( const&nbsp;<a href="qrect.html">QRect</a>&nbsp;&amp;&nbsp;area )<tt> [virtual]</tt>
505</h3>
506Marks <em>area</em> as <em>unchanged</em>. The area will <em>not</em> be redrawn in
507the views for the next <a href="#update">update</a>(), unless it is marked or changed
508again before the next call to update().
509
510<h3 class=fn>void <a name="setUpdatePeriod"></a>QCanvas::setUpdatePeriod ( int&nbsp;ms )<tt> [virtual]</tt>
511</h3>
512Sets the canvas to call <a href="#update">update</a>() every <em>ms</em> milliseconds. Any
513previous setting by <a href="#setAdvancePeriod">setAdvancePeriod</a>() or <a href="#setUpdatePeriod">setUpdatePeriod</a>() is
514overridden.
515<p> If <em>ms</em> is less than 0 automatic updating will be stopped.
516
517<h3 class=fn><a href="qsize.html">QSize</a> <a name="size"></a>QCanvas::size () const
518</h3>
519
520<p> Returns the size of the canvas, in pixels.
521
522<h3 class=fn>int <a name="tile"></a>QCanvas::tile ( int&nbsp;x, int&nbsp;y ) const
523</h3>
524
525<p> Returns the tile at position (<em>x</em>, <em>y</em>). Initially, all tiles
526are 0.
527<p> The parameters must be within range, i.e.
5280 &lt; <em>x</em> &lt; <a href="#tilesHorizontally">tilesHorizontally</a>() and
5290 &lt; <em>y</em> &lt; <a href="#tilesVertically">tilesVertically</a>().
530<p> <p>See also <a href="#setTile">setTile</a>().
531
532<h3 class=fn>int <a name="tileHeight"></a>QCanvas::tileHeight () const
533</h3>
534
535<p> Returns the height of each tile.
536
537<h3 class=fn>int <a name="tileWidth"></a>QCanvas::tileWidth () const
538</h3>
539
540<p> Returns the width of each tile.
541
542<h3 class=fn>int <a name="tilesHorizontally"></a>QCanvas::tilesHorizontally () const
543</h3>
544
545<p> Returns the number of tiles horizontally.
546
547<h3 class=fn>int <a name="tilesVertically"></a>QCanvas::tilesVertically () const
548</h3>
549
550<p> Returns the number of tiles vertically.
551
552<h3 class=fn>void <a name="update"></a>QCanvas::update ()<tt> [virtual slot]</tt>
553</h3>
554Repaints changed areas in all views of the canvas.
555<p> <p>See also <a href="#advance">advance</a>().
556
557<h3 class=fn>bool <a name="validChunk"></a>QCanvas::validChunk ( int&nbsp;x, int&nbsp;y ) const
558</h3>
559
560<p> Returns TRUE if the chunk position (<em>x</em>, <em>y</em>) is on the canvas;
561otherwise returns FALSE.
562<p> <p>See also <a href="#onCanvas">onCanvas</a>().
563
564<h3 class=fn>bool <a name="validChunk-2"></a>QCanvas::validChunk ( const&nbsp;<a href="qpoint.html">QPoint</a>&nbsp;&amp;&nbsp;p ) const
565</h3>
566
567This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
568<p> Returns TRUE if the chunk position <em>p</em> is on the canvas; otherwise
569returns FALSE.
570<p> <p>See also <a href="#onCanvas">onCanvas</a>().
571
572<h3 class=fn>int <a name="width"></a>QCanvas::width () const
573</h3>
574
575<p> Returns the width of the canvas, in pixels.
576
577<p>Example: <a href="canvas-example.html#x2912">canvas/canvas.cpp</a>.
578<!-- eof -->
579<hr><p>
580This file is part of the <a href="index.html">Qt toolkit</a>.
581Copyright &copy; 1995-2007
582<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
583<table width=100% cellspacing=0 border=0><tr>
584<td>Copyright &copy; 2007
585<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
586<td align=right><div align=right>Qt 3.3.8</div>
587</table></div></address></body>
588</html>
Note: See TracBrowser for help on using the repository browser.