1QCanvasItem(3qt) QCanvasItem(3qt)
2
6 QCanvasItem - Abstract graphic object on a QCanvas
7
9 #include <qcanvas.h>
10 Inherits Qt.
12 Inherited by QCanvasSprite, QCanvasPolygonalItem, and QCanvasText.
14 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 Protected Members
61 void update ()
62
64 The QCanvasItem class provides an abstract graphic object on a QCanvas.
65 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 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 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 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 Use QCanvasSprite or your own subclass of QCanvasSprite to create
96 canvas items which are animated, i.e. which change over time.
97 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 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 QCanvasItem provides the show() and isVisible() functions like those in
107 QWidget.
108 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 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 See also Graphics Classes and Image Processing Classes.
120 Member Type Documentation
123 This enum is used to name the different types of canvas item.
124 QCanvasItem::Rtti_Item - Canvas item abstract base class
126 QCanvasItem::Rtti_Ellipse
128 QCanvasItem::Rtti_Line
130 QCanvasItem::Rtti_Polygon
132 QCanvasItem::Rtti_PolygonalItem
134 QCanvasItem::Rtti_Rectangle
136 QCanvasItem::Rtti_Spline
138 QCanvasItem::Rtti_Sprite
140 QCanvasItem::Rtti_Text
142
145 Constructs a QCanvasItem on canvas canvas.
146 See also setCanvas().
148
150 Destroys the QCanvasItem and removes it from its canvas.
151
153 This function is obsolete. It is provided to keep old source working.
154 We strongly advise against using it in new code.
155 Use isActive() instead.
157
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 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 See also QCanvas::advance() and setVelocity().
167 Example: canvas/canvas.cpp.
169 Reimplemented in QCanvasSprite.
171
173 Returns TRUE if the canvas item is in motion; otherwise returns FALSE.
174 See also setVelocity() and setAnimated().
176
178 Returns the bounding rectangle in pixels that the canvas item covers.
179 See also boundingRectAdvanced().
181 Reimplemented in QCanvasSprite, QCanvasPolygonalItem, and QCanvasText.
183
185 Returns the bounding rectangle of pixels that the canvas item will
186 cover after advance(1) is called.
187 See also boundingRect().
189
191 Returns the canvas containing the canvas item.
192
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 See also collisions().
199 Example: canvas/canvas.cpp.
201
203 Returns the list of canvas items that this canvas item has collided
204 with.
205 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 If exact is TRUE, the canvas items returned have been accurately tested
213 for collision with the canvas item.
214 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 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 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 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
238 This abstract virtual function draws the canvas item using painter.
239 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 Reimplemented in QCanvasSprite, QCanvasPolygonalItem, and QCanvasText.
248
250 This function is obsolete. It is provided to keep old source working.
251 We strongly advise against using it in new code.
252 Use isEnabled() instead.
254
256 Shorthand for setVisible(FALSE).
257
259 Returns TRUE if the QCanvasItem is active; otherwise returns FALSE.
260
262 Returns TRUE if the QCanvasItem is enabled; otherwise returns FALSE.
263
265 Returns TRUE if the canvas item is selected; otherwise returns FALSE.
266
268 Returns TRUE if the canvas item is visible; otherwise returns FALSE.
269 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 See also setVisible() and z().
277
279 Moves the canvas item to the absolute position (x, y).
280 Example: canvas/canvas.cpp.
282
284 Moves the canvas item relative to its current position by (dx, dy).
285 Example: canvas/canvas.cpp.
287
289 Returns 0 (QCanvasItem::Rtti_Item).
290 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 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 For example:
302 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 Example: canvas/canvas.cpp.
314 Reimplemented in QCanvasSprite, QCanvasPolygonalItem, and QCanvasText.
316
318 This function is obsolete. It is provided to keep old source working.
319 We strongly advise against using it in new code.
320 Use isSelected() instead.
322
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 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
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 See also advance() and QCanvas::advance().
339
341 Sets the QCanvas upon which the canvas item is to be drawn to c.
342 See also canvas().
344
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 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
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 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
366 Sets the canvas item to be in motion, moving by vx and vy pixels in the
367 horizontal and vertical directions respectively.
368 See also advance(), setXVelocity(), and setYVelocity().
370
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
376 Moves the canvas item so that its x-position is x.
377 See also x() and move().
379 Example: chart/chartform_canvas.cpp.
381
383 Sets the horizontal component of the canvas item's velocity to vx.
384 See also setYVelocity() and setVelocity().
386
388 Moves the canvas item so that its y-position is y.
389 See also y() and move().
391 Example: chart/chartform_canvas.cpp.
393
395 Sets the vertical component of the canvas item's velocity to vy.
396 See also setXVelocity() and setVelocity().
398
400 Sets the z index of the canvas item to z. Higher-z items obscure (are
401 in front of) lower-z items.
402 See also z() and move().
404 Examples:
406
408 Shorthand for setVisible(TRUE).
409 Examples:
411
413 Call this function to repaint the canvas's changed chunks.
414
416 This function is obsolete. It is provided to keep old source working.
417 We strongly advise against using it in new code.
418 Use isVisible() instead.
420
422 Returns the horizontal position of the canvas item. Note that
423 subclasses often have an origin other than the top-left corner.
424 Example: canvas/canvas.cpp.
426
428 Returns the horizontal velocity component of the canvas item.
429
431 Returns the vertical position of the canvas item. Note that subclasses
432 often have an origin other than the top-left corner.
433 Example: canvas/canvas.cpp.
435
437 Returns the vertical velocity component of the canvas item.
438
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
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
454 Generated automatically from the source code.
455
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 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 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).
470Trolltech AS 2 February 2007 QCanvasItem(3qt)