1QCanvas(3qt) QCanvas(3qt)
2
6 QCanvas - 2D area that can contain QCanvasItem objects
7
9 #include <qcanvas.h>
10 Inherits QObject.
12 Public Members
14 QCanvas ( QObject * parent = 0, const char * name = 0 )
15 QCanvas ( int w, int h )
16 QCanvas ( QPixmap p, int h, int v, int tilewidth, int tileheight )
17 virtual ~QCanvas ()
18 virtual void setTiles ( QPixmap p, int h, int v, int tilewidth, int
19 tileheight )
20 virtual void setBackgroundPixmap ( const QPixmap & p )
21 QPixmap backgroundPixmap () const
22 virtual void setBackgroundColor ( const QColor & c )
23 QColor backgroundColor () const
24 virtual void setTile ( int x, int y, int tilenum )
25 int tile ( int x, int y ) const
26 int tilesHorizontally () const
27 int tilesVertically () const
28 int tileWidth () const
29 int tileHeight () const
30 virtual void resize ( int w, int h )
31 int width () const
32 int height () const
33 QSize size () const
34 QRect rect () const
35 bool onCanvas ( int x, int y ) const
36 bool onCanvas ( const QPoint & p ) const
37 bool validChunk ( int x, int y ) const
38 bool validChunk ( const QPoint & p ) const
39 int chunkSize () const
40 virtual void retune ( int chunksze, int mxclusters = 100 )
41 virtual void setAllChanged ()
42 virtual void setChanged ( const QRect & area )
43 virtual void setUnchanged ( const QRect & area )
44 QCanvasItemList allItems ()
45 QCanvasItemList collisions ( const QPoint & p ) const
46 QCanvasItemList collisions ( const QRect & r ) const
47 QCanvasItemList collisions ( const QPointArray & chunklist, const
48 QCanvasItem * item, bool exact ) const
49 void drawArea ( const QRect & clip, QPainter * painter, bool dbuf =
50 FALSE )
51 virtual void setAdvancePeriod ( int ms )
52 virtual void setUpdatePeriod ( int ms )
53 virtual void setDoubleBuffering ( bool y )
54 Public Slots
56 virtual void advance ()
57 virtual void update ()
58 Signals
60 void resized ()
61 Protected Members
63 virtual void drawBackground ( QPainter & painter, const QRect & clip )
64 virtual void drawForeground ( QPainter & painter, const QRect & clip )
65
67 The QCanvas class provides a 2D area that can contain QCanvasItem
68 objects.
69 The QCanvas class manages its 2D graphic area and all the canvas items
71 the area contains. The canvas has no visual appearance of its own.
72 Instead, it is displayed on screen using a QCanvasView. Multiple
73 QCanvasView widgets may be associated with a canvas to provide multiple
74 views of the same canvas.
75 The canvas is optimized for large numbers of items, particularly where
77 only a small percentage of the items change at any one time. If the
78 entire display changes very frequently, you should consider using your
79 own custom QScrollView subclass.
80 Qt provides a rich set of canvas item classes, e.g. QCanvasEllipse,
82 QCanvasLine, QCanvasPolygon, QCanvasPolygonalItem, QCanvasRectangle,
83 QCanvasSpline, QCanvasSprite and QCanvasText. You can subclass to
84 create your own canvas items; QCanvasPolygonalItem is the most common
85 base class used for this purpose.
86 Items appear on the canvas after their show() function has been called
88 (or setVisible(TRUE)), and after update() has been called. The canvas
89 only shows items that are visible, and then only if update() is called.
90 (By default the canvas is white and so are canvas items, so if nothing
91 appears try changing colors.)
92 If you created the canvas without passing a width and height to the
94 constructor you must also call resize().
95 Although a canvas may appear to be similar to a widget with child
97 widgets, there are several notable differences:
98 Canvas items are usually much faster to manipulate and redraw than
100 child widgets, with the speed advantage becoming especially great when
101 there are many canvas items and non-rectangular items. In most
102 situations canvas items are also a lot more memory efficient than child
103 widgets.
104 It's easy to detect overlapping items (collision detection).
106 The canvas can be larger than a widget. A million-by-million canvas is
108 perfectly possible. At such a size a widget might be very inefficient,
109 and some window systems might not support it at all, whereas QCanvas
110 scales well. Even with a billion pixels and a million items, finding a
111 particular canvas item, detecting collisions, etc., is still fast
112 (though the memory consumption may be prohibitive at such extremes).
113 Two or more QCanvasView objects can view the same canvas.
115 An arbitrary transformation matrix can be set on each QCanvasView which
117 makes it easy to zoom, rotate or shear the viewed canvas.
118 Widgets provide a lot more functionality, such as input (QKeyEvent,
120 QMouseEvent etc.) and layout management (QGridLayout etc.).
121 A canvas consists of a background, a number of canvas items organized
123 by x, y and z coordinates, and a foreground. A canvas item's z
124 coordinate can be treated as a layer number -- canvas items with a
125 higher z coordinate appear in front of canvas items with a lower z
126 coordinate.
127 The background is white by default, but can be set to a different color
129 using setBackgroundColor(), or to a repeated pixmap using
130 setBackgroundPixmap() or to a mosaic of smaller pixmaps using
131 setTiles(). Individual tiles can be set with setTile(). There are
132 corresponding get functions, e.g. backgroundColor() and
133 backgroundPixmap().
134 Note that QCanvas does not inherit from QWidget, even though it has
136 some functions which provide the same functionality as those in
137 QWidget. One of these is setBackgroundPixmap(); some others are
138 resize(), size(), width() and height(). QCanvasView is the widget used
139 to display a canvas on the screen.
140 Canvas items are added to a canvas by constructing them and passing the
142 canvas to the canvas item's constructor. An item can be moved to a
143 different canvas using QCanvasItem::setCanvas().
144 Canvas items are movable (and in the case of QCanvasSprites, animated)
146 objects that inherit QCanvasItem. Each canvas item has a position on
147 the canvas (x, y coordinates) and a height (z coordinate), all of which
148 are held as floating-point numbers. Moving canvas items also have x and
149 y velocities. It's possible for a canvas item to be outside the canvas
150 (for example QCanvasItem::x() is greater than width()). When a canvas
151 item is off the canvas, onCanvas() returns FALSE and the canvas
152 disregards the item. (Canvas items off the canvas do not slow down any
153 of the common operations on the canvas.)
154 Canvas items can be moved with QCanvasItem::move(). The advance()
156 function moves all QCanvasItem::animated() canvas items and
157 setAdvancePeriod() makes QCanvas move them automatically on a periodic
158 basis. In the context of the QCanvas classes, to `animate' a canvas
159 item is to set it in motion, i.e. using QCanvasItem::setVelocity().
160 Animation of a canvas item itself, i.e. items which change over time,
161 is enabled by calling QCanvasSprite::setFrameAnimation(), or more
162 generally by subclassing and reimplementing QCanvasItem::advance(). To
163 detect collisions use one of the QCanvasItem::collisions() functions.
164 The changed parts of the canvas are redrawn (if they are visible in a
166 canvas view) whenever update() is called. You can either call update()
167 manually after having changed the contents of the canvas, or force
168 periodic updates using setUpdatePeriod(). If you have moving objects on
169 the canvas, you must call advance() every time the objects should move
170 one step further. Periodic calls to advance() can be forced using
171 setAdvancePeriod(). The advance() function will call
172 QCanvasItem::advance() on every item that is animated and trigger an
173 update of the affected areas afterwards. (A canvas item that is
174 `animated' is simply a canvas item that is in motion.)
175 QCanvas organizes its canvas items into chunks; these are areas on the
177 canvas that are used to speed up most operations. Many operations start
178 by eliminating most chunks (i.e. those which haven't changed) and then
179 process only the canvas items that are in the few interesting (i.e.
180 changed) chunks. A valid chunk, validChunk(), is one which is on the
181 canvas.
182 The chunk size is a key factor to QCanvas's speed: if there are too
184 many chunks, the speed benefit of grouping canvas items into chunks is
185 reduced. If the chunks are too large, it takes too long to process each
186 one. The QCanvas constructor tries to pick a suitable size, but you can
187 call retune() to change it at any time. The chunkSize() function
188 returns the current chunk size. The canvas items always make sure
189 they're in the right chunks; all you need to make sure of is that the
190 canvas uses the right chunk size. A good rule of thumb is that the size
191 should be a bit smaller than the average canvas item size. If you have
192 moving objects, the chunk size should be a bit smaller than the average
193 size of the moving items.
194 The foreground is normally nothing, but if you reimplement
196 drawForeground(), you can draw things in front of all the canvas items.
197 Areas can be set as changed with setChanged() and set unchanged with
199 setUnchanged(). The entire canvas can be set as changed with
200 setAllChanged(). A list of all the items on the canvas is returned by
201 allItems().
202 An area can be copied (painted) to a QPainter with drawArea().
204 If the canvas is resized it emits the resized() signal.
206 The examples/canvas application and the 2D graphics page of the
208 examples/demo application demonstrate many of QCanvas's facilities.
209 See also QCanvasView, QCanvasItem, Abstract Widget Classes, Graphics
211 Classes, and Image Processing Classes.
212
215 Create a QCanvas with no size. parent and name are passed to the
216 QObject superclass.
217 Warning: You must call resize() at some time after creation to be able
219 to use the canvas.
220
222 Constructs a QCanvas that is w pixels wide and h pixels high.
223
225 Constructs a QCanvas which will be composed of h tiles horizontally and
226 v tiles vertically. Each tile will be an image tilewidth by tileheight
227 pixels taken from pixmap p.
228 The pixmap p is a list of tiles, arranged left to right, (and in the
230 case of pixmaps that have multiple rows of tiles, top to bottom), with
231 tile 0 in the top-left corner, tile 1 next to the right, and so on,
232 e.g.
233 <center>.nf
235 </center>
237 The QCanvas is initially sized to show exactly the given number of
239 tiles horizontally and vertically. If it is resized to be larger, the
240 entire matrix of tiles will be repeated as often as necessary to cover
241 the area. If it is smaller, tiles to the right and bottom will not be
242 visible.
243 See also setTiles().
245
247 Destroys the canvas and all the canvas's canvas items.
248
250 Moves all QCanvasItem::animated() canvas items on the canvas and
251 refreshes all changes to all views of the canvas. (An `animated' item
252 is an item that is in motion; see setVelocity().)
253 The advance takes place in two phases. In phase 0, the
255 QCanvasItem::advance() function of each QCanvasItem::animated() canvas
256 item is called with paramater 0. Then all these canvas items are called
257 again, with parameter 1. In phase 0, the canvas items should not change
258 position, merely examine other items on the canvas for which special
259 processing is required, such as collisions between items. In phase 1,
260 all canvas items should change positions, ignoring any other items on
261 the canvas. This two-phase approach allows for considerations of
262 "fairness", although no QCanvasItem subclasses supplied with Qt do
263 anything interesting in phase 0.
264 The canvas can be configured to call this function periodically with
266 setAdvancePeriod().
267 See also update().
269
271 Returns a list of all the items in the canvas.
272
274 Returns the color set by setBackgroundColor(). By default, this is
275 white.
276 This function is not a reimplementation of QWidget::backgroundColor()
278 (QCanvas is not a subclass of QWidget), but all QCanvasViews that are
279 viewing the canvas will set their backgrounds to this color.
280 See also setBackgroundColor() and backgroundPixmap().
282
284 Returns the pixmap set by setBackgroundPixmap(). By default, this is a
285 null pixmap.
286 See also setBackgroundPixmap() and backgroundColor().
288
290 Returns the chunk size of the canvas.
291 See also retune().
293
295 Returns a list of canvas items that collide with the point p. The list
296 is ordered by z coordinates, from highest z coordinate (front-most
297 item) to lowest z coordinate (rear-most item).
298
300 This is an overloaded member function, provided for convenience. It
301 behaves essentially like the above function.
302 Returns a list of items which collide with the rectangle r. The list is
304 ordered by z coordinates, from highest z coordinate (front-most item)
305 to lowest z coordinate (rear-most item).
306
308 QCanvasItem * item, bool exact ) const
309 This is an overloaded member function, provided for convenience. It
310 behaves essentially like the above function.
311 Returns a list of canvas items which intersect with the chunks listed
313 in chunklist, excluding item. If exact is TRUE, only those which
314 actually collide with item are returned; otherwise canvas items are
315 included just for being in the chunks.
316 This is a utility function mainly used to implement the simpler
318 QCanvasItem::collisions() function.
319
321 FALSE )
322 Paints all canvas items that are in the area clip to painter, using
323 double-buffering if dbuf is TRUE.
324 e.g. to print the canvas to a printer:
326 QPrinter pr;
328 if ( pr.setup() ) {
329 QPainter p(&pr);
330 canvas.drawArea( canvas.rect(), &p );
331 }
332 Example: canvas/canvas.cpp.
334
336 [virtual protected]
337 This virtual function is called for all updates of the canvas. It
338 renders any background graphics using the painter painter, in the area
339 clip. If the canvas has a background pixmap or a tiled background, that
340 graphic is used, otherwise the canvas is cleared using the background
341 color.
342 If the graphics for an area change, you must explicitly call
344 setChanged(const QRect&) for the result to be visible when update() is
345 next called.
346 See also setBackgroundColor(), setBackgroundPixmap(), and setTiles().
348
350 [virtual protected]
351 This virtual function is called for all updates of the canvas. It
352 renders any foreground graphics using the painter painter, in the area
353 clip.
354 If the graphics for an area change, you must explicitly call
356 setChanged(const QRect&) for the result to be visible when update() is
357 next called.
358 The default is to draw nothing.
360
362 Returns the height of the canvas, in pixels.
363 Example: canvas/canvas.cpp.
365
367 Returns TRUE if the pixel position (x, y) is on the canvas; otherwise
368 returns FALSE.
369 See also validChunk().
371
373 This is an overloaded member function, provided for convenience. It
374 behaves essentially like the above function.
375 Returns TRUE if the pixel position p is on the canvas; otherwise
377 returns FALSE.
378 See also validChunk().
380
382 Returns a rectangle the size of the canvas.
383
385 Changes the size of the canvas to have a width of w and a height of h.
386 This is a slow operation.
387 Examples:
389
391 This signal is emitted whenever the canvas is resized. Each QCanvasView
392 connects to this signal to keep the scrollview's size correct.
393
395 Change the efficiency tuning parameters to mxclusters clusters, each of
396 size chunksze. This is a slow operation if there are many objects on
397 the canvas.
398 The canvas is divided into chunks which are rectangular areas chunksze
400 wide by chunksze high. Use a chunk size which is about the average size
401 of the canvas items. If you choose a chunk size which is too small it
402 will increase the amount of calculation required when drawing since
403 each change will affect many chunks. If you choose a chunk size which
404 is too large the amount of drawing required will increase because for
405 each change, a lot of drawing will be required since there will be many
406 (unchanged) canvas items which are in the same chunk as the changed
407 canvas items.
408 Internally, a canvas uses a low-resolution "chunk matrix" to keep track
410 of all the items in the canvas. A 64x64 chunk matrix is the default for
411 a 1024x1024 pixel canvas, where each chunk collects canvas items in a
412 16x16 pixel square. This default is also affected by setTiles(). You
413 can tune this default using this function. For example if you have a
414 very large canvas and want to trade off speed for memory then you might
415 set the chunk size to 32 or 64.
416 The mxclusters argument is the number of rectangular groups of chunks
418 that will be separately drawn. If the canvas has a large number of
419 small, dispersed items, this should be about that number. Our testing
420 suggests that a large number of clusters is almost always best.
421
423 Sets the canvas to call advance() every ms milliseconds. Any previous
424 setting by setAdvancePeriod() or setUpdatePeriod() is overridden.
425 If ms is less than 0 advancing will be stopped.
427 Example: canvas/main.cpp.
429
431 Marks the whole canvas as changed. All views of the canvas will be
432 entirely redrawn when update() is called next.
433
435 Sets the solid background to be the color c.
436 See also backgroundColor(), setBackgroundPixmap(), and setTiles().
438
440 Sets the solid background to be the pixmap p repeated as necessary to
441 cover the entire canvas.
442 See also backgroundPixmap(), setBackgroundColor(), and setTiles().
444
446 Marks area as changed. This area will be redrawn in all views that are
447 showing it when update() is called next.
448
450 If y is TRUE (the default) double-buffering is switched on; otherwise
451 double-buffering is switched off.
452 Turning off double-buffering causes the redrawn areas to flicker a
454 little and also gives a (usually small) performance improvement.
455 Example: canvas/canvas.cpp.
457
459 Sets the tile at (x, y) to use tile number tilenum, which is an index
460 into the tile pixmaps. The canvas will update appropriately when
461 update() is next called.
462 The images are taken from the pixmap set by setTiles() and are arranged
464 left to right, (and in the case of pixmaps that have multiple rows of
465 tiles, top to bottom), with tile 0 in the top-left corner, tile 1 next
466 to the right, and so on, e.g.
467 <center>.nf
469 </center>
471 See also tile() and setTiles().
473
475 tileheight ) [virtual]
476 Sets the QCanvas to be composed of h tiles horizontally and v tiles
477 vertically. Each tile will be an image tilewidth by tileheight pixels
478 from pixmap p.
479 The pixmap p is a list of tiles, arranged left to right, (and in the
481 case of pixmaps that have multiple rows of tiles, top to bottom), with
482 tile 0 in the top-left corner, tile 1 next to the right, and so on,
483 e.g.
484 <center>.nf
486 </center>
488 If the canvas is larger than the matrix of tiles, the entire matrix is
490 repeated as necessary to cover the whole canvas. If it is smaller,
491 tiles to the right and bottom are not visible.
492 The width and height of p must be a multiple of tilewidth and
494 tileheight. If they are not the function will do nothing.
495 If you want to unset any tiling set, then just pass in a null pixmap
497 and 0 for h, v, tilewidth, and tileheight.
498
500 Marks area as unchanged. The area will not be redrawn in the views for
501 the next update(), unless it is marked or changed again before the next
502 call to update().
503
505 Sets the canvas to call update() every ms milliseconds. Any previous
506 setting by setAdvancePeriod() or setUpdatePeriod() is overridden.
507 If ms is less than 0 automatic updating will be stopped.
509
511 Returns the size of the canvas, in pixels.
512
514 Returns the tile at position (x, y). Initially, all tiles are 0.
515 The parameters must be within range, i.e. 0 < x < tilesHorizontally()
517 and 0 < y < tilesVertically().
518 See also setTile().
520
522 Returns the height of each tile.
523
525 Returns the width of each tile.
526
528 Returns the number of tiles horizontally.
529
531 Returns the number of tiles vertically.
532
534 Repaints changed areas in all views of the canvas.
535 See also advance().
537
539 Returns TRUE if the chunk position (x, y) is on the canvas; otherwise
540 returns FALSE.
541 See also onCanvas().
543
545 This is an overloaded member function, provided for convenience. It
546 behaves essentially like the above function.
547 Returns TRUE if the chunk position p is on the canvas; otherwise
549 returns FALSE.
550 See also onCanvas().
552
554 Returns the width of the canvas, in pixels.
555 Example: canvas/canvas.cpp.
557
560 http://doc.trolltech.com/qcanvas.html
561 http://www.trolltech.com/faq/tech.html
562
564 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
565 license file included in the distribution for a complete license
566 statement.
567
569 Generated automatically from the source code.
570
572 If you find a bug in Qt, please report it as described in
573 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
574 help you. Thank you.
575 The definitive Qt documentation is provided in HTML format; it is
577 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
578 web browser. This man page is provided as a convenience for those users
579 who prefer man pages, although this format is not officially supported
580 by Trolltech.
581 If you find errors in this manual page, please report them to qt-
583 bugs@trolltech.com. Please include the name of the manual page
584 (qcanvas.3qt) and the Qt version (3.3.8).
585Trolltech AS 2 February 2007 QCanvas(3qt)