QCanvasItem Class Reference
[ canvas module ]

The QCanvasItem is an abstract graphic object on a QCanvas. More...

#include <qcanvas.h>

Inherits Qt.

Inherited by QCanvasPolygonalItem, QCanvasSprite and QCanvasText.

List of all member functions.

Public Members

• QCanvasItem ( QCanvas * canvas ) 
• virtual ~QCanvasItem () 
• double x () const
• double y () const
• double z () const
• virtual void moveBy ( double dx, double dy ) 
• void move ( double x, double y ) 
• void setX ( double a ) 
• void setY ( double a ) 
• void setZ ( double a ) 
• bool animated () const
• virtual void setAnimated ( bool y ) 
• virtual void setVelocity ( double vx, double vy ) 
• void setXVelocity ( double vx ) 
• void setYVelocity ( double vy ) 
• double xVelocity () const
• double yVelocity () const
• virtual void advance ( int stage ) 
• virtual bool collidesWith ( const QCanvasItem * ) const
• QCanvasItemList collisions ( bool exact ) const
• virtual void setCanvas ( QCanvas * ) 
• virtual void draw ( QPainter & ) 
• void show () 
• void hide () 
• virtual void setVisible ( bool yes ) 
• bool visible () const
• virtual void setSelected ( bool yes ) 
• bool selected () const
• virtual void setEnabled ( bool yes ) 
• bool enabled () const
• virtual void setActive ( bool yes ) 
• bool active () const
• virtual int rtti () const
• virtual QRect boundingRect () const
• virtual QRect boundingRectAdvanced () const
• QCanvas* canvas () const

Detailed Description

A QCanvasItem object can be moved in the x(), y() and z() dimensions using functions such as move(), moveBy(), setY() and many others. It has a size given by boundingRect(). The item can move or change appearance automatically, using setAnimated() and setVelocity(), and you can get information about whether it collides using collidesWith() and collisions().

Finally, the rtti() function is used for identifying subclasses of QCanvasItem, and the canvas() returns a pointer to the canvas on which the item lives.

An item, by default, has no speed, no size, is not animated and has no velocity.

Note that you cannot easily subclass QCanvasItem yourself - the API is too low-level. Instead, you should subclass QCanvasPolygonalItem, or perhaps QCanvasRectangle or QCanvasSprite.

Member Function Documentation

QCanvasItem::QCanvasItem ( QCanvas * canvas )

Constructs a QCanvasItem on canvas.

See also setCanvas().

QCanvasItem::~QCanvasItem () [virtual]

Destructs the QCanvasItem. It is removed from its canvas.

bool QCanvasItem::active () const

Returns TRUE if the QCanvasItem is active.

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

Advances the animation of the item. The default implementation moves the item by the preset velocity if stage is 1, and does nothing if stage is 0.

Note that if you reimplement this funciton, you may not change the canvas in any way, add other items, or remove items.

See also QCanvas::advance().

bool QCanvasItem::animated () const

Returns TRUE is the item is animated.

See also setVelocity() and setAnimated().

QRect QCanvasItem::boundingRect () const [virtual]

Returns the bounding rectangle of pixels that the item covers.

See also boundingRectAdvanced().

Reimplemented in QCanvasSprite, QCanvasPolygonalItem and QCanvasText.

QRect QCanvasItem::boundingRectAdvanced () const [virtual]

Returns the bounding rectangle of pixels that the item will cover after advance(1) is called.

See also boundingRect().

QCanvas* QCanvasItem::canvas () const

Returns the canvas containing the item.

bool QCanvasItem::collidesWith ( const QCanvasItem * other ) const [virtual]

Returns TRUE if the item will collide with the other item after they have moved by their current velocities.

See also collisions().

Reimplemented in QCanvasText, QCanvasRectangle, QCanvasSprite, QCanvasEllipse and QCanvasPolygonalItem.

QCanvasItemList QCanvasItem::collisions ( bool exact ) const

Returns the list of items that this item collides with.

A collision is generally defined as pixels of one item drawing on the pixels of another item, but not all subclasses are so precise. Also, since pixelwise collision detection can be slow, this function works in either exact or inexact mode, according to the exact parameter.

In exact mode, items returned have been accurately tested to collide with the item.

In inexact mode, the items returned are only near the item and should be tested using collidesWith() if they are interesting collision candidates. By using this, you can ignore some items for which collisions are not interesting.

The returned list is just a list of QCanvasItems, but often you will need to cast the items to more useful types. The safe way to do that is to use rtti() before casting. This provides some of the functionality of standard C++ dynamic cast operation even on compilers where that is not available.

Note that while a QCanvasItem may be `on' a QCanvas even if it's coordinates place it far off the edge of the area of the QCanvas, collision detection only works for parts of an item that are within the area of the canvas.

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

This abstract virtual function draws the item using painter.

Reimplemented in QCanvasPolygonalItem and QCanvasSprite.

bool QCanvasItem::enabled () const

Returns TRUE if the QCanvasItem is enabled.

void QCanvasItem::hide ()

Shorthand for setVisible(FALSE).

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

Moves the item to (x, y) by calling the moveBy() virtual function.

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

Moves the item from its current position by the given amounts.

Reimplemented in QCanvasText and QCanvasPolygon.

int QCanvasItem::rtti () const [virtual]

Returns 0.

Although often frowned upon by purists, Run Time Type Identification is very useful in this case, as it allows a QCanvas to be an efficient indexed storage mechanism.

Make your derived classes return their own values for rtti(), and you can distinguish between objects returned by QCanvas::at(). You should use values greater than 1000 preferably a large random number, to allow for extensions to this class.

However, it is important not to overuse this facility, as it damages extensibility. For example, once you have identified a base class of a QCanvasItem found by QCanvas::at(), cast it to that type and call meaningful methods rather than acting upon the object based on its rtti value.

For example:

    QCanvasItem* item;
    // Find an item, eg. with QCanvasItem::collisions().
    ...
    if (item->rtti() == MySprite::rtti()) {
        MySprite* s = (MySprite*)item;
        if (s->isDamagable()) s->loseHitPoints(1000);
        if (s->isHot()) myself->loseHitPoints(1000);
        ...
    }

Reimplemented in QCanvasRectangle, QCanvasEllipse, QCanvasLine, QCanvasPolygonalItem and QCanvasPolygon.

bool QCanvasItem::selected () const

Returns TRUE if the QCanvasItem is selected.

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

Sets the active flag of the item to yes and causes it to be redrawn when QCanvas::update() is next called.

The behavior of QCanvas, QCanvasItem or the built-in QCanvasItem subclasses is not affected by this value. setActive() is supplied because many applications need it, but it is up to the application to define its exact meaning.

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

Sets the item to be animated if y is TRUE, or not if y is FALSE.

See also advance() and QCanvas::advance().

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

Sets the QCanvas upon which the QCanvasItem is to be drawn to c.

See also canvas().

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

Sets the enabled flag of the item to yes and causes it to be redrawn when QCanvas::update() is next called.

The behavior of QCanvas, QCanvasItem or the built-in QCanvasItem subclasses is not affected by this value. setEnabled() is supplied because many applications need it, but it is up to the application to define its exact meaning.

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

Sets the selected flag of the item to yes and causes it to be redrawn when QCanvas::update() is next called.

The behavior of QCanvas, QCanvasItem or the built-in QCanvasItem subclasses is not affected by this value. setSelected() is supplied because many applications need it, but it is up to the application to define its exact meaning.

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

Sets the item to be animated and moving by dx and dy pixels in the horizontal and vertical directions respectively.

See also advance().

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

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

void QCanvasItem::setX ( double x )

Moves the item so that its X-position is x.

See also x() and move().

void QCanvasItem::setXVelocity ( double vx )

Sets the horizontal component of the item's velocity to vx.

void QCanvasItem::setY ( double y )

Moves the item so that its Y-position is y.

See also y() and move().

void QCanvasItem::setYVelocity ( double vy )

Sets the vertical component of the item's velocity to vy.

void QCanvasItem::setZ ( double z )

Sets the height of the item to z. Higher-z items obscure lower-z ones.

See also z() and move().

void QCanvasItem::show ()

Shorthand for setVisible(TRUE).

bool QCanvasItem::visible () const

Returns TRUE if the QCanvasItem is visible. This does not mean the QCanvasItem is currently in a view, merely that if a view is showing the area where the QCanvasItem is, and the item is not obscured by items at a higher z, and the view is not obscured by overlying windows, it would be visible.

See also setVisible() and z().

double QCanvasItem::x () const

Returns the horizontal position of the item. Note that subclasses often have an origin other than the top-left corner.

double QCanvasItem::xVelocity () const

Returns the horizontal component of the velocity of the item.

double QCanvasItem::y () const

Returns the vertical position of the item. Note that subclasses often have an origin other than the top-left corner.

double QCanvasItem::yVelocity () const

Returns the vertical component of the velocity of the item.

double QCanvasItem::z () const

Returns the z height of the item, which is used for visual order: higher-z items obscure lower-z ones.

Search the documentation, FAQ, qt-interest archive and more (uses www.trolltech.com):

This file is part of the Qt toolkit, copyright © 1995-2005 Trolltech, all rights reserved.