1QCanvasItem(3qt)                                              QCanvasItem(3qt)
2
3
4

NAME

6       QCanvasItem - Abstract graphic object on a QCanvas
7

SYNOPSIS

9       #include <qcanvas.h>
10
11       Inherits Qt.
12
13       Inherited by QCanvasSprite, QCanvasPolygonalItem, and QCanvasText.
14
15   Public Members
16       QCanvasItem ( QCanvas * canvas )
17       virtual ~QCanvasItem ()
18       double x () const
19       double y () const
20       double z () const
21       virtual void moveBy ( double dx, double dy )
22       void move ( double x, double y )
23       void setX ( double x )
24       void setY ( double y )
25       void setZ ( double z )
26       bool animated () const
27       virtual void setAnimated ( bool y )
28       virtual void setVelocity ( double vx, double vy )
29       void setXVelocity ( double vx )
30       void setYVelocity ( double vy )
31       double xVelocity () const
32       double yVelocity () const
33       virtual void advance ( int phase )
34       virtual bool collidesWith ( const QCanvasItem * other ) const = 0
35       QCanvasItemList collisions ( bool exact ) const
36       virtual void setCanvas ( QCanvas * c )
37       virtual void draw ( QPainter & painter ) = 0
38       void show ()
39       void hide ()
40       virtual void setVisible ( bool yes )
41       bool isVisible () const
42       virtual void setSelected ( bool yes )
43       bool isSelected () const
44       virtual void setEnabled ( bool yes )
45       bool isEnabled () const
46       virtual void setActive ( bool yes )
47       bool isActive () const
48       bool visible () const  (obsolete)
49       bool selected () const  (obsolete)
50       bool enabled () const  (obsolete)
51       bool active () const  (obsolete)
52       enum RttiValues { Rtti_Item = 0, Rtti_Sprite = 1, Rtti_PolygonalItem =
53           2, Rtti_Text = 3, Rtti_Polygon = 4, Rtti_Rectangle = 5,
54           Rtti_Ellipse = 6, Rtti_Line = 7, Rtti_Spline = 8 }
55       virtual int rtti () const
56       virtual QRect boundingRect () const = 0
57       virtual QRect boundingRectAdvanced () const
58       QCanvas * canvas () const
59
60   Protected Members
61       void update ()
62

DESCRIPTION

64       The QCanvasItem class provides an abstract graphic object on a QCanvas.
65
66       A variety of QCanvasItem subclasses provide immediately usable
67       behaviour. This class is a pure abstract superclass providing the
68       behaviour that is shared among all the concrete canvas item classes.
69       QCanvasItem is not intended for direct subclassing. It is much easier
70       to subclass one of its subclasses, e.g. QCanvasPolygonalItem (the
71       commonest base class), QCanvasRectangle, QCanvasSprite, QCanvasEllipse
72       or QCanvasText.
73
74       Canvas items are added to a canvas by constructing them and passing the
75       canvas to the canvas item's constructor. An item can be moved to a
76       different canvas using setCanvas().
77
78       Items appear on the canvas after their show() function has been called
79       (or setVisible(TRUE)), and after update() has been called. The canvas
80       only shows items that are visible, and then only if update() is called.
81       If you created the canvas without passing a width and height to the
82       constructor you'll also need to call resize(). Since the canvas
83       background defaults to white and canvas items default to white, you may
84       need to change colors to see your items.
85
86       A QCanvasItem object can be moved in the x(), y() and z() dimensions
87       using functions such as move(), moveBy(), setX(), setY() and setZ(). A
88       canvas item can be set in motion, `animated', using setAnimated() and
89       given a velocity in the x and y directions with setXVelocity() and
90       setYVelocity() -- the same effect can be achieved by calling
91       setVelocity(). Use the collidesWith() function to see if the canvas
92       item will collide on the next advance(1) and use collisions() to see
93       what collisions have occurred.
94
95       Use QCanvasSprite or your own subclass of QCanvasSprite to create
96       canvas items which are animated, i.e. which change over time.
97
98       The size of a canvas item is given by boundingRect(). Use
99       boundingRectAdvanced() to see what the size of the canvas item will be
100       after the next advance(1) call.
101
102       The rtti() function is used for identifying subclasses of QCanvasItem.
103       The canvas() function returns a pointer to the canvas which contains
104       the canvas item.
105
106       QCanvasItem provides the show() and isVisible() functions like those in
107       QWidget.
108
109       QCanvasItem also provides the setEnabled(), setActive() and
110       setSelected() functions; these functions set the relevant boolean and
111       cause a repaint but the boolean values they set are not used in
112       QCanvasItem itself. You can make use of these booleans in your
113       subclasses.
114
115       By default, canvas items have no velocity, no size, and are not in
116       motion. The subclasses provided in Qt do not change these defaults
117       except where noted.
118
119       See also Graphics Classes and Image Processing Classes.
120
121   Member Type Documentation

QCanvasItem::RttiValues

123       This enum is used to name the different types of canvas item.
124
125       QCanvasItem::Rtti_Item - Canvas item abstract base class
126
127       QCanvasItem::Rtti_Ellipse
128
129       QCanvasItem::Rtti_Line
130
131       QCanvasItem::Rtti_Polygon
132
133       QCanvasItem::Rtti_PolygonalItem
134
135       QCanvasItem::Rtti_Rectangle
136
137       QCanvasItem::Rtti_Spline
138
139       QCanvasItem::Rtti_Sprite
140
141       QCanvasItem::Rtti_Text
142

MEMBER FUNCTION DOCUMENTATION

QCanvasItem::QCanvasItem ( QCanvas * canvas )

145       Constructs a QCanvasItem on canvas canvas.
146
147       See also setCanvas().
148

QCanvasItem::~QCanvasItem () [virtual]

150       Destroys the QCanvasItem and removes it from its canvas.
151

bool QCanvasItem::active () const

153       This function is obsolete. It is provided to keep old source working.
154       We strongly advise against using it in new code.
155
156       Use isActive() instead.
157

void QCanvasItem::advance ( int phase ) [virtual]

159       The default implementation moves the canvas item, if it is animated(),
160       by the preset velocity if phase is 1, and does nothing if phase is 0.
161
162       Note that if you reimplement this function, the reimplementation must
163       not change the canvas in any way, for example it must not add or remove
164       items.
165
166       See also QCanvas::advance() and setVelocity().
167
168       Example: canvas/canvas.cpp.
169
170       Reimplemented in QCanvasSprite.
171

bool QCanvasItem::animated () const

173       Returns TRUE if the canvas item is in motion; otherwise returns FALSE.
174
175       See also setVelocity() and setAnimated().
176

QRect QCanvasItem::boundingRect () const [pure virtual]

178       Returns the bounding rectangle in pixels that the canvas item covers.
179
180       See also boundingRectAdvanced().
181
182       Reimplemented in QCanvasSprite, QCanvasPolygonalItem, and QCanvasText.
183

QRect QCanvasItem::boundingRectAdvanced () const [virtual]

185       Returns the bounding rectangle of pixels that the canvas item will
186       cover after advance(1) is called.
187
188       See also boundingRect().
189

QCanvas * QCanvasItem::canvas () const

191       Returns the canvas containing the canvas item.
192

bool QCanvasItem::collidesWith ( const QCanvasItem * other ) const [pure

194       virtual]
195       Returns TRUE if the canvas item will collide with the other item after
196       they have moved by their current velocities; otherwise returns FALSE.
197
198       See also collisions().
199
200       Example: canvas/canvas.cpp.
201

QCanvasItemList QCanvasItem::collisions ( bool exact ) const

203       Returns the list of canvas items that this canvas item has collided
204       with.
205
206       A collision is generally defined as occurring when the pixels of one
207       item draw on the pixels of another item, but not all subclasses are so
208       precise. Also, since pixel-wise collision detection can be slow, this
209       function works in either exact or inexact mode, according to the exact
210       parameter.
211
212       If exact is TRUE, the canvas items returned have been accurately tested
213       for collision with the canvas item.
214
215       If exact is FALSE, the canvas items returned are near the canvas item.
216       You can test the canvas items returned using collidesWith() if any are
217       interesting collision candidates. By using this approach, you can
218       ignore some canvas items for which collisions are not relevant.
219
220       The returned list is a list of QCanvasItems, but often you will need to
221       cast the items to their subclass types. The safe way to do this is to
222       use rtti() before casting. This provides some of the functionality of
223       the standard C++ dynamic cast operation even on compilers where dynamic
224       casts are not available.
225
226       Note that a canvas item may be `on' a canvas, e.g. it was created with
227       the canvas as parameter, even though its coordinates place it beyond
228       the edge of the canvas's area. Collision detection only works for
229       canvas items which are wholly or partly within the canvas's area.
230
231       Note that if items have a velocity (see setVelocity()), then collision
232       testing is done based on where the item will be when it moves, not its
233       current location. For example, a "ball" item doesn't need to actually
234       embed into a "wall" item before a collision is detected. For items
235       without velocity, plain intersection is used.
236

void QCanvasItem::draw ( QPainter & painter ) [pure virtual]

238       This abstract virtual function draws the canvas item using painter.
239
240       Warning: When you reimplement this function, make sure that you leave
241       the painter in the same state as you found it. For example, if you
242       start by calling QPainter::translate(50, 50), end your code by calling
243       QPainter::translate(-50, -50). Be also aware that the painter might
244       already have some transformations set (i.e., don't call
245       QPainter::resetXForm() when you're done).
246
247       Reimplemented in QCanvasSprite, QCanvasPolygonalItem, and QCanvasText.
248

bool QCanvasItem::enabled () const

250       This function is obsolete. It is provided to keep old source working.
251       We strongly advise against using it in new code.
252
253       Use isEnabled() instead.
254

void QCanvasItem::hide ()

256       Shorthand for setVisible(FALSE).
257

bool QCanvasItem::isActive () const

259       Returns TRUE if the QCanvasItem is active; otherwise returns FALSE.
260

bool QCanvasItem::isEnabled () const

262       Returns TRUE if the QCanvasItem is enabled; otherwise returns FALSE.
263

bool QCanvasItem::isSelected () const

265       Returns TRUE if the canvas item is selected; otherwise returns FALSE.
266

bool QCanvasItem::isVisible () const

268       Returns TRUE if the canvas item is visible; otherwise returns FALSE.
269
270       Note that in this context TRUE does not mean that the canvas item is
271       currently in a view, merely that if a view is showing the area where
272       the canvas item is positioned, and the item is not obscured by items
273       with higher z values, and the view is not obscured by overlaying
274       windows, it would be visible.
275
276       See also setVisible() and z().
277

void QCanvasItem::move ( double x, double y )

279       Moves the canvas item to the absolute position (x, y).
280
281       Example: canvas/canvas.cpp.
282

void QCanvasItem::moveBy ( double dx, double dy ) [virtual]

284       Moves the canvas item relative to its current position by (dx, dy).
285
286       Example: canvas/canvas.cpp.
287

int QCanvasItem::rtti () const [virtual]

289       Returns 0 (QCanvasItem::Rtti_Item).
290
291       Make your derived classes return their own values for rtti(), so that
292       you can distinguish between objects returned by QCanvas::at(). You
293       should use values greater than 1000 to allow for extensions to this
294       class.
295
296       Overuse of this functionality can damage it's extensibility. For
297       example, once you have identified a base class of a QCanvasItem found
298       by QCanvas::at(), cast it to that type and call meaningful methods
299       rather than acting upon the object based on its rtti value.
300
301       For example:
302
303               QCanvasItem* item;
304               // Find an item, e.g. with QCanvasItem::collisions().
305               ...
306               if (item->rtti() == MySprite::RTTI ) {
307                   MySprite* s = (MySprite*)item;
308                   if (s->isDamagable()) s->loseHitPoints(1000);
309                   if (s->isHot()) myself->loseHitPoints(1000);
310                   ...
311               }
312
313       Example: canvas/canvas.cpp.
314
315       Reimplemented in QCanvasSprite, QCanvasPolygonalItem, and QCanvasText.
316

bool QCanvasItem::selected () const

318       This function is obsolete. It is provided to keep old source working.
319       We strongly advise against using it in new code.
320
321       Use isSelected() instead.
322

void QCanvasItem::setActive ( bool yes ) [virtual]

324       Sets the active flag of the item to yes. If this changes the item's
325       active state the item will be redrawn when QCanvas::update() is next
326       called.
327
328       The QCanvas, QCanvasItem and the Qt-supplied QCanvasItem subclasses do
329       not make use of this value. The setActive() function is supplied
330       because many applications need it, but it is up to you how you use the
331       isActive() value.
332

void QCanvasItem::setAnimated ( bool y ) [virtual]

334       Sets the canvas item to be in motion if y is TRUE, or not if y is
335       FALSE. The speed and direction of the motion is set with setVelocity(),
336       or with setXVelocity() and setYVelocity().
337
338       See also advance() and QCanvas::advance().
339

void QCanvasItem::setCanvas ( QCanvas * c ) [virtual]

341       Sets the QCanvas upon which the canvas item is to be drawn to c.
342
343       See also canvas().
344

void QCanvasItem::setEnabled ( bool yes ) [virtual]

346       Sets the enabled flag of the item to yes. If this changes the item's
347       enabled state the item will be redrawn when QCanvas::update() is next
348       called.
349
350       The QCanvas, QCanvasItem and the Qt-supplied QCanvasItem subclasses do
351       not make use of this value. The setEnabled() function is supplied
352       because many applications need it, but it is up to you how you use the
353       isEnabled() value.
354

void QCanvasItem::setSelected ( bool yes ) [virtual]

356       Sets the selected flag of the item to yes. If this changes the item's
357       selected state the item will be redrawn when QCanvas::update() is next
358       called.
359
360       The QCanvas, QCanvasItem and the Qt-supplied QCanvasItem subclasses do
361       not make use of this value. The setSelected() function is supplied
362       because many applications need it, but it is up to you how you use the
363       isSelected() value.
364

void QCanvasItem::setVelocity ( double vx, double vy ) [virtual]

366       Sets the canvas item to be in motion, moving by vx and vy pixels in the
367       horizontal and vertical directions respectively.
368
369       See also advance(), setXVelocity(), and setYVelocity().
370

void QCanvasItem::setVisible ( bool yes ) [virtual]

372       Makes the canvas item visible if yes is TRUE, or invisible if yes is
373       FALSE. The change takes effect when QCanvas::update() is next called.
374

void QCanvasItem::setX ( double x )

376       Moves the canvas item so that its x-position is x.
377
378       See also x() and move().
379
380       Example: chart/chartform_canvas.cpp.
381

void QCanvasItem::setXVelocity ( double vx )

383       Sets the horizontal component of the canvas item's velocity to vx.
384
385       See also setYVelocity() and setVelocity().
386

void QCanvasItem::setY ( double y )

388       Moves the canvas item so that its y-position is y.
389
390       See also y() and move().
391
392       Example: chart/chartform_canvas.cpp.
393

void QCanvasItem::setYVelocity ( double vy )

395       Sets the vertical component of the canvas item's velocity to vy.
396
397       See also setXVelocity() and setVelocity().
398

void QCanvasItem::setZ ( double z )

400       Sets the z index of the canvas item to z. Higher-z items obscure (are
401       in front of) lower-z items.
402
403       See also z() and move().
404
405       Examples:
406

void QCanvasItem::show ()

408       Shorthand for setVisible(TRUE).
409
410       Examples:
411

void QCanvasItem::update () [protected]

413       Call this function to repaint the canvas's changed chunks.
414

bool QCanvasItem::visible () const

416       This function is obsolete. It is provided to keep old source working.
417       We strongly advise against using it in new code.
418
419       Use isVisible() instead.
420

double QCanvasItem::x () const

422       Returns the horizontal position of the canvas item. Note that
423       subclasses often have an origin other than the top-left corner.
424
425       Example: canvas/canvas.cpp.
426

double QCanvasItem::xVelocity () const

428       Returns the horizontal velocity component of the canvas item.
429

double QCanvasItem::y () const

431       Returns the vertical position of the canvas item. Note that subclasses
432       often have an origin other than the top-left corner.
433
434       Example: canvas/canvas.cpp.
435

double QCanvasItem::yVelocity () const

437       Returns the vertical velocity component of the canvas item.
438

double QCanvasItem::z () const

440       Returns the z index of the canvas item, which is used for visual order:
441       higher-z items obscure (are in front of) lower-z items.
442
443

SEE ALSO

445       http://doc.trolltech.com/qcanvasitem.html
446       http://www.trolltech.com/faq/tech.html
447
449       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
450       license file included in the distribution for a complete license
451       statement.
452

AUTHOR

454       Generated automatically from the source code.
455

BUGS

457       If you find a bug in Qt, please report it as described in
458       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
459       help you. Thank you.
460
461       The definitive Qt documentation is provided in HTML format; it is
462       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
463       web browser. This man page is provided as a convenience for those users
464       who prefer man pages, although this format is not officially supported
465       by Trolltech.
466
467       If you find errors in this manual page, please report them to qt-
468       bugs@trolltech.com.  Please include the name of the manual page
469       (qcanvasitem.3qt) and the Qt version (3.3.8).
470
471
472
473Trolltech AS                    2 February 2007               QCanvasItem(3qt)
Impressum