1QCanvas(3qt)                                                      QCanvas(3qt)
2
3
4

NAME

6       QCanvas - 2D area that can contain QCanvasItem objects
7

SYNOPSIS

9       #include <qcanvas.h>
10
11       Inherits QObject.
12
13   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
55   Public Slots
56       virtual void advance ()
57       virtual void update ()
58
59   Signals
60       void resized ()
61
62   Protected Members
63       virtual void drawBackground ( QPainter & painter, const QRect & clip )
64       virtual void drawForeground ( QPainter & painter, const QRect & clip )
65

DESCRIPTION

67       The QCanvas class provides a 2D area that can contain QCanvasItem
68       objects.
69
70       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
76       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
81       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
87       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
93       If you created the canvas without passing a width and height to the
94       constructor you must also call resize().
95
96       Although a canvas may appear to be similar to a widget with child
97       widgets, there are several notable differences:
98
99       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
105       It's easy to detect overlapping items (collision detection).
106
107       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
114       Two or more QCanvasView objects can view the same canvas.
115
116       An arbitrary transformation matrix can be set on each QCanvasView which
117       makes it easy to zoom, rotate or shear the viewed canvas.
118
119       Widgets provide a lot more functionality, such as input (QKeyEvent,
120       QMouseEvent etc.) and layout management (QGridLayout etc.).
121
122       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
128       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
135       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
141       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
145       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
155       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
165       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
176       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
183       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
195       The foreground is normally nothing, but if you reimplement
196       drawForeground(), you can draw things in front of all the canvas items.
197
198       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
203       An area can be copied (painted) to a QPainter with drawArea().
204
205       If the canvas is resized it emits the resized() signal.
206
207       The examples/canvas application and the 2D graphics page of the
208       examples/demo application demonstrate many of QCanvas's facilities.
209
210       See also QCanvasView, QCanvasItem, Abstract Widget Classes, Graphics
211       Classes, and Image Processing Classes.
212

MEMBER FUNCTION DOCUMENTATION

QCanvas::QCanvas ( QObject * parent = 0, const char * name = 0 )

215       Create a QCanvas with no size. parent and name are passed to the
216       QObject superclass.
217
218       Warning: You must call resize() at some time after creation to be able
219       to use the canvas.
220

QCanvas::QCanvas ( int w, int h )

222       Constructs a QCanvas that is w pixels wide and h pixels high.
223

QCanvas::QCanvas ( QPixmap p, int h, int v, int tilewidth, int tileheight )

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
229       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
234       <center>.nf
235
236       </center>
237
238       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
244       See also setTiles().
245

QCanvas::~QCanvas () [virtual]

247       Destroys the canvas and all the canvas's canvas items.
248

void QCanvas::advance () [virtual slot]

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
254       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
265       The canvas can be configured to call this function periodically with
266       setAdvancePeriod().
267
268       See also update().
269

QCanvasItemList QCanvas::allItems ()

271       Returns a list of all the items in the canvas.
272

QColor QCanvas::backgroundColor () const

274       Returns the color set by setBackgroundColor(). By default, this is
275       white.
276
277       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
281       See also setBackgroundColor() and backgroundPixmap().
282

QPixmap QCanvas::backgroundPixmap () const

284       Returns the pixmap set by setBackgroundPixmap(). By default, this is a
285       null pixmap.
286
287       See also setBackgroundPixmap() and backgroundColor().
288

int QCanvas::chunkSize () const

290       Returns the chunk size of the canvas.
291
292       See also retune().
293

QCanvasItemList QCanvas::collisions ( const QPoint & p ) const

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

QCanvasItemList QCanvas::collisions ( const QRect & r ) const

300       This is an overloaded member function, provided for convenience. It
301       behaves essentially like the above function.
302
303       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

QCanvasItemList QCanvas::collisions ( const QPointArray & chunklist, const

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
312       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
317       This is a utility function mainly used to implement the simpler
318       QCanvasItem::collisions() function.
319

void QCanvas::drawArea ( const QRect & clip, QPainter * painter, bool dbuf =

321       FALSE )
322       Paints all canvas items that are in the area clip to painter, using
323       double-buffering if dbuf is TRUE.
324
325       e.g. to print the canvas to a printer:
326
327           QPrinter pr;
328           if ( pr.setup() ) {
329               QPainter p(&pr);
330               canvas.drawArea( canvas.rect(), &p );
331           }
332
333       Example: canvas/canvas.cpp.
334

void QCanvas::drawBackground ( QPainter & painter, const QRect & clip )

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
343       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
347       See also setBackgroundColor(), setBackgroundPixmap(), and setTiles().
348

void QCanvas::drawForeground ( QPainter & painter, const QRect & clip )

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
355       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
359       The default is to draw nothing.
360

int QCanvas::height () const

362       Returns the height of the canvas, in pixels.
363
364       Example: canvas/canvas.cpp.
365

bool QCanvas::onCanvas ( int x, int y ) const

367       Returns TRUE if the pixel position (x, y) is on the canvas; otherwise
368       returns FALSE.
369
370       See also validChunk().
371

bool QCanvas::onCanvas ( const QPoint & p ) const

373       This is an overloaded member function, provided for convenience. It
374       behaves essentially like the above function.
375
376       Returns TRUE if the pixel position p is on the canvas; otherwise
377       returns FALSE.
378
379       See also validChunk().
380

QRect QCanvas::rect () const

382       Returns a rectangle the size of the canvas.
383

void QCanvas::resize ( int w, int h ) [virtual]

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
388       Examples:
389

void QCanvas::resized () [signal]

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

void QCanvas::retune ( int chunksze, int mxclusters = 100 ) [virtual]

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
399       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
409       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
417       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

void QCanvas::setAdvancePeriod ( int ms ) [virtual]

423       Sets the canvas to call advance() every ms milliseconds. Any previous
424       setting by setAdvancePeriod() or setUpdatePeriod() is overridden.
425
426       If ms is less than 0 advancing will be stopped.
427
428       Example: canvas/main.cpp.
429

void QCanvas::setAllChanged () [virtual]

431       Marks the whole canvas as changed. All views of the canvas will be
432       entirely redrawn when update() is called next.
433

void QCanvas::setBackgroundColor ( const QColor & c ) [virtual]

435       Sets the solid background to be the color c.
436
437       See also backgroundColor(), setBackgroundPixmap(), and setTiles().
438

void QCanvas::setBackgroundPixmap ( const QPixmap & p ) [virtual]

440       Sets the solid background to be the pixmap p repeated as necessary to
441       cover the entire canvas.
442
443       See also backgroundPixmap(), setBackgroundColor(), and setTiles().
444

void QCanvas::setChanged ( const QRect & area ) [virtual]

446       Marks area as changed. This area will be redrawn in all views that are
447       showing it when update() is called next.
448

void QCanvas::setDoubleBuffering ( bool y ) [virtual]

450       If y is TRUE (the default) double-buffering is switched on; otherwise
451       double-buffering is switched off.
452
453       Turning off double-buffering causes the redrawn areas to flicker a
454       little and also gives a (usually small) performance improvement.
455
456       Example: canvas/canvas.cpp.
457

void QCanvas::setTile ( int x, int y, int tilenum ) [virtual]

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
463       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
468       <center>.nf
469
470       </center>
471
472       See also tile() and setTiles().
473

void QCanvas::setTiles ( QPixmap p, int h, int v, int tilewidth, int

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
480       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
485       <center>.nf
486
487       </center>
488
489       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
493       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
496       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

void QCanvas::setUnchanged ( const QRect & area ) [virtual]

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

void QCanvas::setUpdatePeriod ( int ms ) [virtual]

505       Sets the canvas to call update() every ms milliseconds. Any previous
506       setting by setAdvancePeriod() or setUpdatePeriod() is overridden.
507
508       If ms is less than 0 automatic updating will be stopped.
509

QSize QCanvas::size () const

511       Returns the size of the canvas, in pixels.
512

int QCanvas::tile ( int x, int y ) const

514       Returns the tile at position (x, y). Initially, all tiles are 0.
515
516       The parameters must be within range, i.e. 0 < x < tilesHorizontally()
517       and 0 < y < tilesVertically().
518
519       See also setTile().
520

int QCanvas::tileHeight () const

522       Returns the height of each tile.
523

int QCanvas::tileWidth () const

525       Returns the width of each tile.
526

int QCanvas::tilesHorizontally () const

528       Returns the number of tiles horizontally.
529

int QCanvas::tilesVertically () const

531       Returns the number of tiles vertically.
532

void QCanvas::update () [virtual slot]

534       Repaints changed areas in all views of the canvas.
535
536       See also advance().
537

bool QCanvas::validChunk ( int x, int y ) const

539       Returns TRUE if the chunk position (x, y) is on the canvas; otherwise
540       returns FALSE.
541
542       See also onCanvas().
543

bool QCanvas::validChunk ( const QPoint & p ) const

545       This is an overloaded member function, provided for convenience. It
546       behaves essentially like the above function.
547
548       Returns TRUE if the chunk position p is on the canvas; otherwise
549       returns FALSE.
550
551       See also onCanvas().
552

int QCanvas::width () const

554       Returns the width of the canvas, in pixels.
555
556       Example: canvas/canvas.cpp.
557
558

SEE ALSO

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

AUTHOR

569       Generated automatically from the source code.
570

BUGS

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
576       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
582       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).
585
586
587
588Trolltech AS                    2 February 2007                   QCanvas(3qt)
Impressum