You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
589 lines
35 KiB
589 lines
35 KiB
14 years ago
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||
|
|
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/canvas/qcanvas.cpp:435 -->
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||
|
|
<title>QCanvas Class</title>
|
||
|
|
<style type="text/css"><!--
|
||
|
|
fn { margin-left: 1cm; text-indent: -1cm; }
|
||
|
|
a:link { color: #004faf; text-decoration: none }
|
||
|
|
a:visited { color: #672967; text-decoration: none }
|
||
|
|
body { background: #ffffff; color: black; }
|
||
|
|
--></style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
|
||
|
|
<table border="0" cellpadding="0" cellspacing="0" width="100%">
|
||
|
|
<tr bgcolor="#E5E5E5">
|
||
|
|
<td valign=center>
|
||
|
|
<a href="index.html">
|
||
|
|
<font color="#004faf">Home</font></a>
|
||
|
|
| <a href="classes.html">
|
||
|
|
<font color="#004faf">All Classes</font></a>
|
||
|
|
| <a href="mainclasses.html">
|
||
|
|
<font color="#004faf">Main Classes</font></a>
|
||
|
|
| <a href="annotated.html">
|
||
|
|
<font color="#004faf">Annotated</font></a>
|
||
|
|
| <a href="groups.html">
|
||
|
|
<font color="#004faf">Grouped Classes</font></a>
|
||
|
|
| <a href="functions.html">
|
||
|
|
<font color="#004faf">Functions</font></a>
|
||
|
|
</td>
|
||
|
|
<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>
|
||
|
|
|
||
|
|
<p>The QCanvas class provides a 2D area that can contain QCanvasItem objects.
|
||
|
|
<a href="#details">More...</a>
|
||
|
|
<p><tt>#include <<a href="qcanvas-h.html">qcanvas.h</a>></tt>
|
||
|
|
<p>Inherits <a href="qobject.html">QObject</a>.
|
||
|
|
<p><a href="qcanvas-members.html">List of all member functions.</a>
|
||
|
|
<h2>Public Members</h2>
|
||
|
|
<ul>
|
||
|
|
<li class=fn><a href="#QCanvas"><b>QCanvas</b></a> ( QObject * parent = 0, const char * name = 0 )</li>
|
||
|
|
<li class=fn><a href="#QCanvas-2"><b>QCanvas</b></a> ( int w, int h )</li>
|
||
|
|
<li class=fn><a href="#QCanvas-3"><b>QCanvas</b></a> ( QPixmap p, int h, int v, int tilewidth, int tileheight )</li>
|
||
|
|
<li class=fn>virtual <a href="#~QCanvas"><b>~QCanvas</b></a> ()</li>
|
||
|
|
<li class=fn>virtual void <a href="#setTiles"><b>setTiles</b></a> ( QPixmap p, int h, int v, int tilewidth, int tileheight )</li>
|
||
|
|
<li class=fn>virtual void <a href="#setBackgroundPixmap"><b>setBackgroundPixmap</b></a> ( const QPixmap & p )</li>
|
||
|
|
<li class=fn>QPixmap <a href="#backgroundPixmap"><b>backgroundPixmap</b></a> () const</li>
|
||
|
|
<li class=fn>virtual void <a href="#setBackgroundColor"><b>setBackgroundColor</b></a> ( const QColor & c )</li>
|
||
|
|
<li class=fn>QColor <a href="#backgroundColor"><b>backgroundColor</b></a> () const</li>
|
||
|
|
<li class=fn>virtual void <a href="#setTile"><b>setTile</b></a> ( int x, int y, int tilenum )</li>
|
||
|
|
<li class=fn>int <a href="#tile"><b>tile</b></a> ( int x, int y ) const</li>
|
||
|
|
<li class=fn>int <a href="#tilesHorizontally"><b>tilesHorizontally</b></a> () const</li>
|
||
|
|
<li class=fn>int <a href="#tilesVertically"><b>tilesVertically</b></a> () const</li>
|
||
|
|
<li class=fn>int <a href="#tileWidth"><b>tileWidth</b></a> () const</li>
|
||
|
|
<li class=fn>int <a href="#tileHeight"><b>tileHeight</b></a> () const</li>
|
||
|
|
<li class=fn>virtual void <a href="#resize"><b>resize</b></a> ( int w, int h )</li>
|
||
|
|
<li class=fn>int <a href="#width"><b>width</b></a> () const</li>
|
||
|
|
<li class=fn>int <a href="#height"><b>height</b></a> () const</li>
|
||
|
|
<li class=fn>QSize <a href="#size"><b>size</b></a> () const</li>
|
||
|
|
<li class=fn>QRect <a href="#rect"><b>rect</b></a> () const</li>
|
||
|
|
<li class=fn>bool <a href="#onCanvas"><b>onCanvas</b></a> ( int x, int y ) const</li>
|
||
|
|
<li class=fn>bool <a href="#onCanvas-2"><b>onCanvas</b></a> ( const QPoint & p ) const</li>
|
||
|
|
<li class=fn>bool <a href="#validChunk"><b>validChunk</b></a> ( int x, int y ) const</li>
|
||
|
|
<li class=fn>bool <a href="#validChunk-2"><b>validChunk</b></a> ( const QPoint & p ) const</li>
|
||
|
|
<li class=fn>int <a href="#chunkSize"><b>chunkSize</b></a> () const</li>
|
||
|
|
<li class=fn>virtual void <a href="#retune"><b>retune</b></a> ( int chunksze, int mxclusters = 100 )</li>
|
||
|
|
<li class=fn>virtual void <a href="#setAllChanged"><b>setAllChanged</b></a> ()</li>
|
||
|
|
<li class=fn>virtual void <a href="#setChanged"><b>setChanged</b></a> ( const QRect & area )</li>
|
||
|
|
<li class=fn>virtual void <a href="#setUnchanged"><b>setUnchanged</b></a> ( const QRect & area )</li>
|
||
|
|
<li class=fn>QCanvasItemList <a href="#allItems"><b>allItems</b></a> ()</li>
|
||
|
|
<li class=fn>QCanvasItemList <a href="#collisions"><b>collisions</b></a> ( const QPoint & p ) const</li>
|
||
|
|
<li class=fn>QCanvasItemList <a href="#collisions-2"><b>collisions</b></a> ( const QRect & r ) const</li>
|
||
|
|
<li class=fn>QCanvasItemList <a href="#collisions-3"><b>collisions</b></a> ( const QPointArray & chunklist, const QCanvasItem * item, bool exact ) const</li>
|
||
|
|
<li class=fn>void <a href="#drawArea"><b>drawArea</b></a> ( const QRect & clip, QPainter * painter, bool dbuf = FALSE )</li>
|
||
|
|
<li class=fn>virtual void <a href="#setAdvancePeriod"><b>setAdvancePeriod</b></a> ( int ms )</li>
|
||
|
|
<li class=fn>virtual void <a href="#setUpdatePeriod"><b>setUpdatePeriod</b></a> ( int ms )</li>
|
||
|
|
<li class=fn>virtual void <a href="#setDoubleBuffering"><b>setDoubleBuffering</b></a> ( bool y )</li>
|
||
|
|
</ul>
|
||
|
|
<h2>Public Slots</h2>
|
||
|
|
<ul>
|
||
|
|
<li class=fn>virtual void <a href="#advance"><b>advance</b></a> ()</li>
|
||
|
|
<li class=fn>virtual void <a href="#update"><b>update</b></a> ()</li>
|
||
|
|
</ul>
|
||
|
|
<h2>Signals</h2>
|
||
|
|
<ul>
|
||
|
|
<li class=fn>void <a href="#resized"><b>resized</b></a> ()</li>
|
||
|
|
</ul>
|
||
|
|
<h2>Protected Members</h2>
|
||
|
|
<ul>
|
||
|
|
<li class=fn>virtual void <a href="#drawBackground"><b>drawBackground</b></a> ( QPainter & painter, const QRect & clip )</li>
|
||
|
|
<li class=fn>virtual void <a href="#drawForeground"><b>drawForeground</b></a> ( QPainter & painter, const QRect & clip )</li>
|
||
|
|
</ul>
|
||
|
|
<hr><a name="details"></a><h2>Detailed Description</h2>
|
||
|
|
|
||
|
|
|
||
|
|
The QCanvas class provides a 2D area that can contain <a href="qcanvasitem.html">QCanvasItem</a> objects.
|
||
|
|
|
||
|
|
<p>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<p> The QCanvas class manages its 2D graphic area and all the canvas
|
||
|
|
items the area contains. The canvas has no visual appearance of
|
||
|
|
its own. Instead, it is displayed on screen using a <a href="qcanvasview.html">QCanvasView</a>.
|
||
|
|
Multiple QCanvasView widgets may be associated with a canvas to
|
||
|
|
provide multiple views of the same canvas.
|
||
|
|
<p> The canvas is optimized for large numbers of items, particularly
|
||
|
|
where only a small percentage of the items change at any
|
||
|
|
one time. If the entire display changes very frequently, you should
|
||
|
|
consider using your own custom <a href="qscrollview.html">QScrollView</a> subclass.
|
||
|
|
<p> Qt provides a rich
|
||
|
|
set of canvas item classes, e.g. <a href="qcanvasellipse.html">QCanvasEllipse</a>, <a href="qcanvasline.html">QCanvasLine</a>,
|
||
|
|
<a href="qcanvaspolygon.html">QCanvasPolygon</a>, <a href="qcanvaspolygonalitem.html">QCanvasPolygonalItem</a>, <a href="qcanvasrectangle.html">QCanvasRectangle</a>, <a href="qcanvasspline.html">QCanvasSpline</a>,
|
||
|
|
<a href="qcanvassprite.html">QCanvasSprite</a> and <a href="qcanvastext.html">QCanvasText</a>. You can subclass to create your own
|
||
|
|
canvas items; QCanvasPolygonalItem is the most common base class used
|
||
|
|
for this purpose.
|
||
|
|
<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>
|
||
|
|
<a href="#update">update</a>() has been called. The canvas only shows items that are
|
||
|
|
<a href="qcanvasitem.html#setVisible">visible</a>, and then only if
|
||
|
|
<a href="#update">update</a>() is called. (By default the canvas is white and so are
|
||
|
|
canvas items, so if nothing appears try changing colors.)
|
||
|
|
<p> If you created the canvas without passing a width and height to
|
||
|
|
the constructor you must also call <a href="#resize">resize</a>().
|
||
|
|
<p> Although a canvas may appear to be similar to a widget with child
|
||
|
|
widgets, there are several notable differences:
|
||
|
|
<p> <ul>
|
||
|
|
<li> Canvas items are usually much faster to manipulate and redraw than
|
||
|
|
child widgets, with the speed advantage becoming especially great when
|
||
|
|
there are <em>many</em> canvas items and non-rectangular items. In most
|
||
|
|
situations canvas items are also a lot more memory efficient than child
|
||
|
|
widgets.
|
||
|
|
<p> <li> It's easy to detect overlapping items (collision detection).
|
||
|
|
<p> <li> The canvas can be larger than a widget. A million-by-million canvas
|
||
|
|
is perfectly possible. At such a size a widget might be very
|
||
|
|
inefficient, and some window systems might not support it at all,
|
||
|
|
whereas QCanvas scales well. Even with a billion pixels and a million
|
||
|
|
items, finding a particular canvas item, detecting collisions, etc.,
|
||
|
|
is still fast (though the memory consumption may be prohibitive
|
||
|
|
at such extremes).
|
||
|
|
<p> <li> Two or more <a href="qcanvasview.html">QCanvasView</a> objects can view the same canvas.
|
||
|
|
<p> <li> An arbitrary <a href="qwmatrix.html#TransformationMode">transformation matrix</a> can be set on each QCanvasView
|
||
|
|
which makes it easy to zoom, rotate or shear the viewed canvas.
|
||
|
|
<p> <li> Widgets provide a lot more functionality, such as input (<a href="qkeyevent.html">QKeyEvent</a>,
|
||
|
|
<a href="qmouseevent.html">QMouseEvent</a> etc.) and layout management (<a href="qgridlayout.html">QGridLayout</a> etc.).
|
||
|
|
<p> </ul>
|
||
|
|
<p> A canvas consists of a background, a number of canvas items organized by
|
||
|
|
x, y and z coordinates, and a foreground. A canvas item's z coordinate
|
||
|
|
can be treated as a layer number -- canvas items with a higher z
|
||
|
|
coordinate appear in front of canvas items with a lower z coordinate.
|
||
|
|
<p> The background is white by default, but can be set to a different color
|
||
|
|
using <a href="#setBackgroundColor">setBackgroundColor</a>(), or to a repeated pixmap using
|
||
|
|
<a href="#setBackgroundPixmap">setBackgroundPixmap</a>() or to a mosaic of smaller pixmaps using
|
||
|
|
<a href="#setTiles">setTiles</a>(). Individual tiles can be set with <a href="#setTile">setTile</a>(). There
|
||
|
|
are corresponding get functions, e.g. <a href="#backgroundColor">backgroundColor</a>() and
|
||
|
|
<a href="#backgroundPixmap">backgroundPixmap</a>().
|
||
|
|
<p> Note that QCanvas does not inherit from <a href="qwidget.html">QWidget</a>, even though it has some
|
||
|
|
functions which provide the same functionality as those in QWidget. One
|
||
|
|
of these is setBackgroundPixmap(); some others are <a href="#resize">resize</a>(), <a href="#size">size</a>(),
|
||
|
|
<a href="#width">width</a>() and <a href="#height">height</a>(). <a href="qcanvasview.html">QCanvasView</a> is the widget used to display a
|
||
|
|
canvas on the screen.
|
||
|
|
<p> Canvas items are added to a canvas by constructing them and passing the
|
||
|
|
canvas to the canvas item's constructor. An item can be moved to a
|
||
|
|
different canvas using <a href="qcanvasitem.html#setCanvas">QCanvasItem::setCanvas</a>().
|
||
|
|
<p> Canvas items are movable (and in the case of QCanvasSprites, animated)
|
||
|
|
objects that inherit <a href="qcanvasitem.html">QCanvasItem</a>. Each canvas item has a position on the
|
||
|
|
canvas (x, y coordinates) and a height (z coordinate), all of which are
|
||
|
|
held as floating-point numbers. Moving canvas items also have x and y
|
||
|
|
velocities. It's possible for a canvas item to be outside the canvas
|
||
|
|
(for example <a href="qcanvasitem.html#x">QCanvasItem::x</a>() is greater than width()). When a canvas
|
||
|
|
item is off the canvas, <a href="#onCanvas">onCanvas</a>() returns FALSE and the canvas
|
||
|
|
disregards the item. (Canvas items off the canvas do not slow down any
|
||
|
|
of the common operations on the canvas.)
|
||
|
|
<p> Canvas items can be moved with <a href="qcanvasitem.html#move">QCanvasItem::move</a>(). The <a href="#advance">advance</a>()
|
||
|
|
function moves all <a href="qcanvasitem.html#animated">QCanvasItem::animated</a>() canvas items and
|
||
|
|
<a href="#setAdvancePeriod">setAdvancePeriod</a>() makes QCanvas move them automatically on a periodic
|
||
|
|
basis. In the context of the QCanvas classes, to `animate' a canvas item
|
||
|
|
is to set it in motion, i.e. using <a href="qcanvasitem.html#setVelocity">QCanvasItem::setVelocity</a>(). Animation
|
||
|
|
of a canvas item itself, i.e. items which change over time, is enabled
|
||
|
|
by calling <a href="qcanvassprite.html#setFrameAnimation">QCanvasSprite::setFrameAnimation</a>(), or more generally by
|
||
|
|
subclassing and reimplementing <a href="qcanvasitem.html#advance">QCanvasItem::advance</a>(). To detect collisions
|
||
|
|
use one of the <a href="qcanvasitem.html#collisions">QCanvasItem::collisions</a>() functions.
|
||
|
|
<p> The changed parts of the canvas are redrawn (if they are visible in a
|
||
|
|
canvas view) whenever <a href="#update">update</a>() is called. You can either call update()
|
||
|
|
manually after having changed the contents of the canvas, or force
|
||
|
|
periodic updates using <a href="#setUpdatePeriod">setUpdatePeriod</a>(). If you have moving objects on
|
||
|
|
the canvas, you must call <a href="#advance">advance</a>() every time the objects should
|
||
|
|
move one step further. Periodic calls to advance() can be forced using
|
||
|
|
<a href="#setAdvancePeriod">setAdvancePeriod</a>(). The advance() function will call
|
||
|
|
QCanvasItem::advance() on every item that is <a href="qcanvasitem.html#animated">animated</a> and trigger an update of the
|
||
|
|
affected areas afterwards. (A canvas item that is `animated' is simply
|
||
|
|
a canvas item that is in motion.)
|
||
|
|
<p> QCanvas organizes its canvas items into <em>chunks</em>; these are areas on
|
||
|
|
the canvas that are used to speed up most operations. Many operations
|
||
|
|
start by eliminating most chunks (i.e. those which haven't changed)
|
||
|
|
and then process only the canvas items that are in the few interesting
|
||
|
|
(i.e. changed) chunks. A valid chunk, <a href="#validChunk">validChunk</a>(), is one which is on
|
||
|
|
the canvas.
|
||
|
|
<p> The chunk size is a key factor to QCanvas's speed: if there are too many
|
||
|
|
chunks, the speed benefit of grouping canvas items into chunks is
|
||
|
|
reduced. If the chunks are too large, it takes too long to process each
|
||
|
|
one. The QCanvas constructor tries to pick a suitable size, but you
|
||
|
|
can call <a href="#retune">retune</a>() to change it at any time. The <a href="#chunkSize">chunkSize</a>() function
|
||
|
|
returns the current chunk size. The canvas items always make sure
|
||
|
|
they're in the right chunks; all you need to make sure of is that
|
||
|
|
the canvas uses the right chunk size. A good rule of thumb is that
|
||
|
|
the size should be a bit smaller than the average canvas item
|
||
|
|
size. If you have moving objects, the chunk size should be a bit
|
||
|
|
smaller than the average size of the moving items.
|
||
|
|
<p> The foreground is normally nothing, but if you reimplement
|
||
|
|
<a href="#drawForeground">drawForeground</a>(), you can draw things in front of all the canvas
|
||
|
|
items.
|
||
|
|
<p> Areas can be set as changed with <a href="#setChanged">setChanged</a>() and set unchanged with
|
||
|
|
<a href="#setUnchanged">setUnchanged</a>(). The entire canvas can be set as changed with
|
||
|
|
<a href="#setAllChanged">setAllChanged</a>(). A list of all the items on the canvas is returned by
|
||
|
|
<a href="#allItems">allItems</a>().
|
||
|
|
<p> An area can be copied (painted) to a <a href="qpainter.html">QPainter</a> with <a href="#drawArea">drawArea</a>().
|
||
|
|
<p> If the canvas is resized it emits the <a href="#resized">resized</a>() signal.
|
||
|
|
<p> The examples/canvas application and the 2D graphics page of the
|
||
|
|
examples/demo application demonstrate many of QCanvas's facilities.
|
||
|
|
<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>.
|
||
|
|
|
||
|
|
<hr><h2>Member Function Documentation</h2>
|
||
|
|
<h3 class=fn><a name="QCanvas"></a>QCanvas::QCanvas ( <a href="qobject.html">QObject</a> * parent = 0, const char * name = 0 )
|
||
|
|
</h3>
|
||
|
|
Create a QCanvas with no size. <em>parent</em> and <em>name</em> are passed to
|
||
|
|
the <a href="qobject.html">QObject</a> superclass.
|
||
|
|
<p> <b>Warning:</b> You <em>must</em> call <a href="#resize">resize</a>() at some time after creation to
|
||
|
|
be able to use the canvas.
|
||
|
|
|
||
|
|
<h3 class=fn><a name="QCanvas-2"></a>QCanvas::QCanvas ( int w, int h )
|
||
|
|
</h3>
|
||
|
|
Constructs a QCanvas that is <em>w</em> pixels wide and <em>h</em> pixels high.
|
||
|
|
|
||
|
|
<h3 class=fn><a name="QCanvas-3"></a>QCanvas::QCanvas ( <a href="qpixmap.html">QPixmap</a> p, int h, int v, int tilewidth, int tileheight )
|
||
|
|
</h3>
|
||
|
|
Constructs a QCanvas which will 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 taken from pixmap <em>p</em>.
|
||
|
|
<p> The pixmap <em>p</em> is a list of tiles, arranged left to right, (and
|
||
|
|
in the case of pixmaps that have multiple rows of tiles, top to
|
||
|
|
bottom), with tile 0 in the top-left corner, tile 1 next to the
|
||
|
|
right, and so on, e.g.
|
||
|
|
<p> <center><table cellpadding="4" cellspacing="2" border="0">
|
||
|
|
<tr bgcolor="#f0f0f0"> <td valign="top">0 <td valign="top">1 <td valign="top">2 <td valign="top">3
|
||
|
|
<tr bgcolor="#d0d0d0"> <td valign="top">4 <td valign="top">5 <td valign="top">6 <td valign="top">7
|
||
|
|
</table></center>
|
||
|
|
<p> The QCanvas is initially sized to show exactly the given number of
|
||
|
|
tiles horizontally and vertically. If it is resized to be larger,
|
||
|
|
the entire matrix of tiles will be repeated as often as necessary
|
||
|
|
to cover the area. If it is smaller, tiles to the right and bottom
|
||
|
|
will not be visible.
|
||
|
|
<p> <p>See also <a href="#setTiles">setTiles</a>().
|
||
|
|
|
||
|
|
<h3 class=fn><a name="~QCanvas"></a>QCanvas::~QCanvas ()<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Destroys the canvas and all the canvas's canvas items.
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="advance"></a>QCanvas::advance ()<tt> [virtual slot]</tt>
|
||
|
|
</h3>
|
||
|
|
Moves all <a href="qcanvasitem.html#animated">QCanvasItem::animated</a>() canvas items on the canvas and
|
||
|
|
refreshes all changes to all views of the canvas. (An `animated'
|
||
|
|
item is an item that is in motion; see setVelocity().)
|
||
|
|
<p> The advance takes place in two phases. In phase 0, the
|
||
|
|
<a href="qcanvasitem.html#advance">QCanvasItem::advance</a>() function of each QCanvasItem::animated()
|
||
|
|
canvas item is called with paramater 0. Then all these canvas
|
||
|
|
items are called again, with parameter 1. In phase 0, the canvas
|
||
|
|
items should not change position, merely examine other items on
|
||
|
|
the canvas for which special processing is required, such as
|
||
|
|
collisions between items. In phase 1, all canvas items should
|
||
|
|
change positions, ignoring any other items on the canvas. This
|
||
|
|
two-phase approach allows for considerations of "fairness",
|
||
|
|
although no <a href="qcanvasitem.html">QCanvasItem</a> subclasses supplied with Qt do anything
|
||
|
|
interesting in phase 0.
|
||
|
|
<p> The canvas can be configured to call this function periodically
|
||
|
|
with <a href="#setAdvancePeriod">setAdvancePeriod</a>().
|
||
|
|
<p> <p>See also <a href="#update">update</a>().
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qcanvasitemlist.html">QCanvasItemList</a> <a name="allItems"></a>QCanvas::allItems ()
|
||
|
|
</h3>
|
||
|
|
Returns a list of all the items in the canvas.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qcolor.html">QColor</a> <a name="backgroundColor"></a>QCanvas::backgroundColor () const
|
||
|
|
</h3>
|
||
|
|
Returns the color set by <a href="#setBackgroundColor">setBackgroundColor</a>(). By default, this is
|
||
|
|
white.
|
||
|
|
<p> This function is not a reimplementation of
|
||
|
|
<a href="qwidget.html#backgroundColor">QWidget::backgroundColor</a>() (QCanvas is not a subclass of <a href="qwidget.html">QWidget</a>),
|
||
|
|
but all QCanvasViews that are viewing the canvas will set their
|
||
|
|
backgrounds to this color.
|
||
|
|
<p> <p>See also <a href="#setBackgroundColor">setBackgroundColor</a>() and <a href="#backgroundPixmap">backgroundPixmap</a>().
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qpixmap.html">QPixmap</a> <a name="backgroundPixmap"></a>QCanvas::backgroundPixmap () const
|
||
|
|
</h3>
|
||
|
|
Returns the pixmap set by <a href="#setBackgroundPixmap">setBackgroundPixmap</a>(). By default,
|
||
|
|
this is a null pixmap.
|
||
|
|
<p> <p>See also <a href="#setBackgroundPixmap">setBackgroundPixmap</a>() and <a href="#backgroundColor">backgroundColor</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>int <a name="chunkSize"></a>QCanvas::chunkSize () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns the chunk size of the canvas.
|
||
|
|
<p> <p>See also <a href="#retune">retune</a>().
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qcanvasitemlist.html">QCanvasItemList</a> <a name="collisions"></a>QCanvas::collisions ( const <a href="qpoint.html">QPoint</a> & p ) const
|
||
|
|
</h3>
|
||
|
|
Returns a list of canvas items that collide with the point <em>p</em>.
|
||
|
|
The list is ordered by z coordinates, from highest z coordinate
|
||
|
|
(front-most item) to lowest z coordinate (rear-most item).
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qcanvasitemlist.html">QCanvasItemList</a> <a name="collisions-2"></a>QCanvas::collisions ( const <a href="qrect.html">QRect</a> & r ) const
|
||
|
|
</h3>
|
||
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> Returns a list of items which collide with the rectangle <em>r</em>. The
|
||
|
|
list is ordered by z coordinates, from highest z coordinate
|
||
|
|
(front-most item) to lowest z coordinate (rear-most item).
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qcanvasitemlist.html">QCanvasItemList</a> <a name="collisions-3"></a>QCanvas::collisions ( const <a href="qpointarray.html">QPointArray</a> & chunklist, const <a href="qcanvasitem.html">QCanvasItem</a> * item, bool exact ) const
|
||
|
|
</h3>
|
||
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> Returns a list of canvas items which intersect with the chunks
|
||
|
|
listed in <em>chunklist</em>, excluding <em>item</em>. If <em>exact</em> is TRUE,
|
||
|
|
only those which actually <a href="qcanvasitem.html#collidesWith">collide with</a> <em>item</em> are returned; otherwise canvas items
|
||
|
|
are included just for being in the chunks.
|
||
|
|
<p> This is a utility function mainly used to implement the simpler
|
||
|
|
<a href="qcanvasitem.html#collisions">QCanvasItem::collisions</a>() function.
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="drawArea"></a>QCanvas::drawArea ( const <a href="qrect.html">QRect</a> & clip, <a href="qpainter.html">QPainter</a> * painter, bool dbuf = FALSE )
|
||
|
|
</h3>
|
||
|
|
Paints all canvas items that are in the area <em>clip</em> to <em>painter</em>, using double-buffering if <em>dbuf</em> is TRUE.
|
||
|
|
<p> e.g. to print the canvas to a printer:
|
||
|
|
<pre>
|
||
|
|
<a href="qprinter.html">QPrinter</a> pr;
|
||
|
|
if ( pr.<a href="qprinter.html#setup">setup</a>() ) {
|
||
|
|
<a href="qpainter.html">QPainter</a> p(&pr);
|
||
|
|
canvas.drawArea( canvas.rect(), &p );
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
|
||
|
|
<p>Example: <a href="canvas-example.html#x2908">canvas/canvas.cpp</a>.
|
||
|
|
<h3 class=fn>void <a name="drawBackground"></a>QCanvas::drawBackground ( <a href="qpainter.html">QPainter</a> & painter, const <a href="qrect.html">QRect</a> & clip )<tt> [virtual protected]</tt>
|
||
|
|
</h3>
|
||
|
|
This virtual function is called for all updates of the canvas. It
|
||
|
|
renders any background graphics using the painter <em>painter</em>, in
|
||
|
|
the area <em>clip</em>. If the canvas has a background pixmap or a tiled
|
||
|
|
background, that graphic is used, otherwise the canvas is cleared
|
||
|
|
using the background color.
|
||
|
|
<p> If the graphics for an area change, you must explicitly call
|
||
|
|
<a href="#setChanged">setChanged</a>(const <a href="qrect.html">QRect</a>&) for the result to be visible when
|
||
|
|
<a href="#update">update</a>() is next called.
|
||
|
|
<p> <p>See also <a href="#setBackgroundColor">setBackgroundColor</a>(), <a href="#setBackgroundPixmap">setBackgroundPixmap</a>(), and <a href="#setTiles">setTiles</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="drawForeground"></a>QCanvas::drawForeground ( <a href="qpainter.html">QPainter</a> & painter, const <a href="qrect.html">QRect</a> & clip )<tt> [virtual protected]</tt>
|
||
|
|
</h3>
|
||
|
|
This virtual function is called for all updates of the canvas. It
|
||
|
|
renders any foreground graphics using the painter <em>painter</em>, in
|
||
|
|
the area <em>clip</em>.
|
||
|
|
<p> If the graphics for an area change, you must explicitly call
|
||
|
|
<a href="#setChanged">setChanged</a>(const <a href="qrect.html">QRect</a>&) for the result to be visible when
|
||
|
|
<a href="#update">update</a>() is next called.
|
||
|
|
<p> The default is to draw nothing.
|
||
|
|
|
||
|
|
<h3 class=fn>int <a name="height"></a>QCanvas::height () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns the height of the canvas, in pixels.
|
||
|
|
|
||
|
|
<p>Example: <a href="canvas-example.html#x2909">canvas/canvas.cpp</a>.
|
||
|
|
<h3 class=fn>bool <a name="onCanvas"></a>QCanvas::onCanvas ( int x, int y ) const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns TRUE if the pixel position (<em>x</em>, <em>y</em>) is on the canvas;
|
||
|
|
otherwise returns FALSE.
|
||
|
|
<p> <p>See also <a href="#validChunk">validChunk</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>bool <a name="onCanvas-2"></a>QCanvas::onCanvas ( const <a href="qpoint.html">QPoint</a> & p ) const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> Returns TRUE if the pixel position <em>p</em> is on the canvas;
|
||
|
|
otherwise returns FALSE.
|
||
|
|
<p> <p>See also <a href="#validChunk">validChunk</a>().
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qrect.html">QRect</a> <a name="rect"></a>QCanvas::rect () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns a rectangle the size of the canvas.
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="resize"></a>QCanvas::resize ( int w, int h )<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Changes the size of the canvas to have a width of <em>w</em> and a
|
||
|
|
height of <em>h</em>. This is a slow operation.
|
||
|
|
|
||
|
|
<p>Examples: <a href="canvas-example.html#x2910">canvas/canvas.cpp</a> and <a href="canvas-chart-example.html#x2876">chart/chartform.cpp</a>.
|
||
|
|
<h3 class=fn>void <a name="resized"></a>QCanvas::resized ()<tt> [signal]</tt>
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> This signal is emitted whenever the canvas is resized. Each
|
||
|
|
<a href="qcanvasview.html">QCanvasView</a> connects to this signal to keep the scrollview's size
|
||
|
|
correct.
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="retune"></a>QCanvas::retune ( int chunksze, int mxclusters = 100 )<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Change the efficiency tuning parameters to <em>mxclusters</em> clusters,
|
||
|
|
each of size <em>chunksze</em>. This is a slow operation if there are
|
||
|
|
many objects on the canvas.
|
||
|
|
<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
|
||
|
|
the average size of the canvas items. If you choose a chunk size
|
||
|
|
which is too small it will increase the amount of calculation
|
||
|
|
required when drawing since each change will affect many chunks.
|
||
|
|
If you choose a chunk size which is too large the amount of
|
||
|
|
drawing required will increase because for each change, a lot of
|
||
|
|
drawing will be required since there will be many (unchanged)
|
||
|
|
canvas items which are in the same chunk as the changed canvas
|
||
|
|
items.
|
||
|
|
<p> Internally, a canvas uses a low-resolution "chunk matrix" to keep
|
||
|
|
track of all the items in the canvas. A 64x64 chunk matrix is the
|
||
|
|
default for a 1024x1024 pixel canvas, where each chunk collects
|
||
|
|
canvas items in a 16x16 pixel square. This default is also
|
||
|
|
affected by <a href="#setTiles">setTiles</a>(). You can tune this default using this
|
||
|
|
function. For example if you have a very large canvas and want to
|
||
|
|
trade off speed for memory then you might set the chunk size to 32
|
||
|
|
or 64.
|
||
|
|
<p> The <em>mxclusters</em> argument is the number of rectangular groups of
|
||
|
|
chunks that will be separately drawn. If the canvas has a large
|
||
|
|
number of small, dispersed items, this should be about that
|
||
|
|
number. Our testing suggests that a large number of clusters is
|
||
|
|
almost always best.
|
||
|
|
<p>
|
||
|
|
<h3 class=fn>void <a name="setAdvancePeriod"></a>QCanvas::setAdvancePeriod ( int ms )<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Sets the canvas to call <a href="#advance">advance</a>() every <em>ms</em> milliseconds. Any
|
||
|
|
previous setting by <a href="#setAdvancePeriod">setAdvancePeriod</a>() or <a href="#setUpdatePeriod">setUpdatePeriod</a>() is
|
||
|
|
overridden.
|
||
|
|
<p> If <em>ms</em> is less than 0 advancing will be stopped.
|
||
|
|
|
||
|
|
<p>Example: <a href="canvas-example.html#x2962">canvas/main.cpp</a>.
|
||
|
|
<h3 class=fn>void <a name="setAllChanged"></a>QCanvas::setAllChanged ()<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Marks the whole canvas as changed.
|
||
|
|
All views of the canvas will be entirely redrawn when
|
||
|
|
<a href="#update">update</a>() is called next.
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="setBackgroundColor"></a>QCanvas::setBackgroundColor ( const <a href="qcolor.html">QColor</a> & c )<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Sets the solid background to be the color <em>c</em>.
|
||
|
|
<p> <p>See also <a href="#backgroundColor">backgroundColor</a>(), <a href="#setBackgroundPixmap">setBackgroundPixmap</a>(), and <a href="#setTiles">setTiles</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="setBackgroundPixmap"></a>QCanvas::setBackgroundPixmap ( const <a href="qpixmap.html">QPixmap</a> & p )<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Sets the solid background to be the pixmap <em>p</em> repeated as
|
||
|
|
necessary to cover the entire canvas.
|
||
|
|
<p> <p>See also <a href="#backgroundPixmap">backgroundPixmap</a>(), <a href="#setBackgroundColor">setBackgroundColor</a>(), and <a href="#setTiles">setTiles</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="setChanged"></a>QCanvas::setChanged ( const <a href="qrect.html">QRect</a> & area )<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Marks <em>area</em> as changed. This <em>area</em> will be redrawn in all
|
||
|
|
views that are showing it when <a href="#update">update</a>() is called next.
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="setDoubleBuffering"></a>QCanvas::setDoubleBuffering ( bool y )<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
If <em>y</em> is TRUE (the default) double-buffering is switched on;
|
||
|
|
otherwise double-buffering is switched off.
|
||
|
|
<p> Turning off double-buffering causes the redrawn areas to flicker a
|
||
|
|
little and also gives a (usually small) performance improvement.
|
||
|
|
|
||
|
|
<p>Example: <a href="canvas-example.html#x2911">canvas/canvas.cpp</a>.
|
||
|
|
<h3 class=fn>void <a name="setTile"></a>QCanvas::setTile ( int x, int y, int tilenum )<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Sets the tile at (<em>x</em>, <em>y</em>) to use tile number <em>tilenum</em>, which
|
||
|
|
is an index into the tile pixmaps. The canvas will update
|
||
|
|
appropriately when <a href="#update">update</a>() is next called.
|
||
|
|
<p> The images are taken from the pixmap set by <a href="#setTiles">setTiles</a>() and are
|
||
|
|
arranged left to right, (and in the case of pixmaps that have
|
||
|
|
multiple rows of tiles, top to bottom), with tile 0 in the
|
||
|
|
top-left corner, tile 1 next to the right, and so on, e.g.
|
||
|
|
<p> <center><table cellpadding="4" cellspacing="2" border="0">
|
||
|
|
<tr bgcolor="#f0f0f0"> <td valign="top">0 <td valign="top">1 <td valign="top">2 <td valign="top">3
|
||
|
|
<tr bgcolor="#d0d0d0"> <td valign="top">4 <td valign="top">5 <td valign="top">6 <td valign="top">7
|
||
|
|
</table></center>
|
||
|
|
<p> <p>See also <a href="#tile">tile</a>() and <a href="#setTiles">setTiles</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="setTiles"></a>QCanvas::setTiles ( <a href="qpixmap.html">QPixmap</a> p, int h, int v, int tilewidth, int tileheight )<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Sets 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>.
|
||
|
|
<p> The pixmap <em>p</em> is a list of tiles, arranged left to right, (and
|
||
|
|
in the case of pixmaps that have multiple rows of tiles, top to
|
||
|
|
bottom), with tile 0 in the top-left corner, tile 1 next to the
|
||
|
|
right, and so on, e.g.
|
||
|
|
<p> <center><table cellpadding="4" cellspacing="2" border="0">
|
||
|
|
<tr bgcolor="#f0f0f0"> <td valign="top">0 <td valign="top">1 <td valign="top">2 <td valign="top">3
|
||
|
|
<tr bgcolor="#d0d0d0"> <td valign="top">4 <td valign="top">5 <td valign="top">6 <td valign="top">7
|
||
|
|
</table></center>
|
||
|
|
<p> If the canvas is larger than the matrix of tiles, the entire
|
||
|
|
matrix is repeated as necessary to cover the whole canvas. If it
|
||
|
|
is smaller, tiles to the right and bottom are not visible.
|
||
|
|
<p> The width and height of <em>p</em> must be a multiple of <em>tilewidth</em>
|
||
|
|
and <em>tileheight</em>. If they are not the function will do nothing.
|
||
|
|
<p> If you want to unset any tiling set, then just pass in a null
|
||
|
|
pixmap and 0 for <em>h</em>, <em>v</em>, <em>tilewidth</em>, and
|
||
|
|
<em>tileheight</em>.
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="setUnchanged"></a>QCanvas::setUnchanged ( const <a href="qrect.html">QRect</a> & area )<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Marks <em>area</em> as <em>unchanged</em>. The area will <em>not</em> be redrawn in
|
||
|
|
the views for the next <a href="#update">update</a>(), unless it is marked or changed
|
||
|
|
again before the next call to update().
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="setUpdatePeriod"></a>QCanvas::setUpdatePeriod ( int ms )<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Sets the canvas to call <a href="#update">update</a>() every <em>ms</em> milliseconds. Any
|
||
|
|
previous setting by <a href="#setAdvancePeriod">setAdvancePeriod</a>() or <a href="#setUpdatePeriod">setUpdatePeriod</a>() is
|
||
|
|
overridden.
|
||
|
|
<p> If <em>ms</em> is less than 0 automatic updating will be stopped.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qsize.html">QSize</a> <a name="size"></a>QCanvas::size () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns the size of the canvas, in pixels.
|
||
|
|
|
||
|
|
<h3 class=fn>int <a name="tile"></a>QCanvas::tile ( int x, int y ) const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns the tile at position (<em>x</em>, <em>y</em>). Initially, all tiles
|
||
|
|
are 0.
|
||
|
|
<p> The parameters must be within range, i.e.
|
||
|
|
0 < <em>x</em> < <a href="#tilesHorizontally">tilesHorizontally</a>() and
|
||
|
|
0 < <em>y</em> < <a href="#tilesVertically">tilesVertically</a>().
|
||
|
|
<p> <p>See also <a href="#setTile">setTile</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>int <a name="tileHeight"></a>QCanvas::tileHeight () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns the height of each tile.
|
||
|
|
|
||
|
|
<h3 class=fn>int <a name="tileWidth"></a>QCanvas::tileWidth () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns the width of each tile.
|
||
|
|
|
||
|
|
<h3 class=fn>int <a name="tilesHorizontally"></a>QCanvas::tilesHorizontally () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns the number of tiles horizontally.
|
||
|
|
|
||
|
|
<h3 class=fn>int <a name="tilesVertically"></a>QCanvas::tilesVertically () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns the number of tiles vertically.
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="update"></a>QCanvas::update ()<tt> [virtual slot]</tt>
|
||
|
|
</h3>
|
||
|
|
Repaints changed areas in all views of the canvas.
|
||
|
|
<p> <p>See also <a href="#advance">advance</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>bool <a name="validChunk"></a>QCanvas::validChunk ( int x, int y ) const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns TRUE if the chunk position (<em>x</em>, <em>y</em>) is on the canvas;
|
||
|
|
otherwise returns FALSE.
|
||
|
|
<p> <p>See also <a href="#onCanvas">onCanvas</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>bool <a name="validChunk-2"></a>QCanvas::validChunk ( const <a href="qpoint.html">QPoint</a> & p ) const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> Returns TRUE if the chunk position <em>p</em> is on the canvas; otherwise
|
||
|
|
returns FALSE.
|
||
|
|
<p> <p>See also <a href="#onCanvas">onCanvas</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>int <a name="width"></a>QCanvas::width () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns the width of the canvas, in pixels.
|
||
|
|
|
||
|
|
<p>Example: <a href="canvas-example.html#x2912">canvas/canvas.cpp</a>.
|
||
|
|
<!-- eof -->
|
||
|
|
<hr><p>
|
||
|
|
This file is part of the <a href="index.html">Qt toolkit</a>.
|
||
|
|
Copyright © 1995-2007
|
||
|
|
<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
|
||
|
|
<table width=100% cellspacing=0 border=0><tr>
|
||
|
|
<td>Copyright © 2007
|
||
|
|
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
|
||
|
|
<td align=right><div align=right>Qt 3.3.8</div>
|
||
|
|
</table></div></address></body>
|
||
|
|
</html>
|