QCanvasItem

NAME

SYNOPSIS

Inherits Qt.

Inherited by QCanvasSprite, QCanvasPolygonalItem, and QCanvasText.

Public Members

Protected Members

DESCRIPTION

A variety of QCanvasItem subclasses provide immediately usable behaviour. This class is a pure abstract superclass providing the behaviour that is shared among all the concrete canvas item classes. QCanvasItem is not intended for direct subclassing. It is much easier to subclass one of its subclasses, e.g. QCanvasPolygonalItem (the commonest base class), QCanvasRectangle, QCanvasSprite, QCanvasEllipse or QCanvasText.

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 setCanvas().

Items appear on the canvas after their show() function has been called (or setVisible(TRUE)), and after update() has been called. The canvas only shows items that are visible, and then only if update() is called. If you created the canvas without passing a width and height to the constructor you'll also need to call resize(). Since the canvas background defaults to white and canvas items default to white, you may need to change colors to see your items.

A QCanvasItem object can be moved in the x(), y() and z() dimensions using functions such as move(), moveBy(), setX(), setY() and setZ(). A canvas item can be set in motion, `animated', using setAnimated() and given a velocity in the x and y directions with setXVelocity() and setYVelocity() -- the same effect can be achieved by calling setVelocity(). Use the collidesWith() function to see if the canvas item will collide on the next advance(1) and use collisions() to see what collisions have occurred.

Use QCanvasSprite or your own subclass of QCanvasSprite to create canvas items which are animated, i.e. which change over time.

The size of a canvas item is given by boundingRect(). Use boundingRectAdvanced() to see what the size of the canvas item will be after the next advance(1) call.

The rtti() function is used for identifying subclasses of QCanvasItem. The canvas() function returns a pointer to the canvas which contains the canvas item.

QCanvasItem provides the show() and isVisible() functions like those in QWidget.

QCanvasItem also provides the setEnabled(), setActive() and setSelected() functions; these functions set the relevant boolean and cause a repaint but the boolean values they set are not used in QCanvasItem itself. You can make use of these booleans in your subclasses.

By default, canvas items have no velocity, no size, and are not in motion. The subclasses provided in Qt do not change these defaults except where noted.

See also Graphics Classes and Image Processing Classes.  

Member Type Documentation

QCanvasItem::RttiValues

QCanvasItem::Rtti_Item - Canvas item abstract base class

QCanvasItem::Rtti_Ellipse

QCanvasItem::Rtti_Line

QCanvasItem::Rtti_Polygon

QCanvasItem::Rtti_PolygonalItem

QCanvasItem::Rtti_Rectangle

QCanvasItem::Rtti_Spline

QCanvasItem::Rtti_Sprite

QCanvasItem::Rtti_Text

MEMBER FUNCTION DOCUMENTATION

QCanvasItem::QCanvasItem ( QCanvas * canvas )

See also setCanvas().  

QCanvasItem::~QCanvasItem () [virtual]

bool QCanvasItem::active () const

Use isActive() instead.  

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

Note that if you reimplement this function, the reimplementation must not change the canvas in any way, for example it must not add or remove items.

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

Example: canvas/canvas.cpp.

Reimplemented in QCanvasSprite.  

bool QCanvasItem::animated () const

See also setVelocity() and setAnimated().  

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

See also boundingRectAdvanced().

Reimplemented in QCanvasSprite, QCanvasPolygonalItem, and QCanvasText.  

QRect QCanvasItem::boundingRectAdvanced () const [virtual]

See also boundingRect().  

QCanvas * QCanvasItem::canvas () const

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

See also collisions().

Example: canvas/canvas.cpp.  

QCanvasItemList QCanvasItem::collisions ( bool exact ) const

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

If exact is TRUE, the canvas items returned have been accurately tested for collision with the canvas item.

If exact is FALSE, the canvas items returned are near the canvas item. You can test the canvas items returned using collidesWith() if any are interesting collision candidates. By using this approach, you can ignore some canvas items for which collisions are not relevant.

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

Note that a canvas item may be `on' a canvas, e.g. it was created with the canvas as parameter, even though its coordinates place it beyond the edge of the canvas's area. Collision detection only works for canvas items which are wholly or partly within the canvas's area.

Note that if items have a velocity (see setVelocity()), then collision testing is done based on where the item will be when it moves, not its current location. For example, a "ball" item doesn't need to actually embed into a "wall" item before a collision is detected. For items without velocity, plain intersection is used.  

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

Warning: When you reimplement this function, make sure that you leave the painter in the same state as you found it. For example, if you start by calling QPainter::translate(50, 50), end your code by calling QPainter::translate(-50, -50). Be also aware that the painter might already have some transformations set (i.e., don't call QPainter::resetXForm() when you're done).

Reimplemented in QCanvasSprite, QCanvasPolygonalItem, and QCanvasText.  

bool QCanvasItem::enabled () const

Use isEnabled() instead.  

void QCanvasItem::hide ()

bool QCanvasItem::isActive () const

bool QCanvasItem::isEnabled () const

bool QCanvasItem::isSelected () const

bool QCanvasItem::isVisible () const

Note that in this context TRUE does not mean that the canvas item is currently in a view, merely that if a view is showing the area where the canvas item is positioned, and the item is not obscured by items with higher z values, and the view is not obscured by overlaying windows, it would be visible.

See also setVisible() and z().  

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

Example: canvas/canvas.cpp.  

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

Example: canvas/canvas.cpp.  

int QCanvasItem::rtti () const [virtual]

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

Overuse of this functionality can damage it's 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, e.g. with QCanvasItem::collisions().


        ...


        if (item->rtti() == MySprite::RTTI ) {


            MySprite* s = (MySprite*)item;


            if (s->isDamagable()) s->loseHitPoints(1000);


            if (s->isHot()) myself->loseHitPoints(1000);


            ...


        }

Example: canvas/canvas.cpp.

Reimplemented in QCanvasSprite, QCanvasPolygonalItem, and QCanvasText.  

bool QCanvasItem::selected () const

Use isSelected() instead.  

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

The QCanvas, QCanvasItem and the Qt-supplied QCanvasItem subclasses do not make use of this value. The setActive() function is supplied because many applications need it, but it is up to you how you use the isActive() value.  

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

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

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

See also canvas().  

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

The QCanvas, QCanvasItem and the Qt-supplied QCanvasItem subclasses do not make use of this value. The setEnabled() function is supplied because many applications need it, but it is up to you how you use the isEnabled() value.  

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

The QCanvas, QCanvasItem and the Qt-supplied QCanvasItem subclasses do not make use of this value. The setSelected() function is supplied because many applications need it, but it is up to you how you use the isSelected() value.  

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

See also advance(), setXVelocity(), and setYVelocity().  

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

void QCanvasItem::setX ( double x )

See also x() and move().

Example: chart/chartform_canvas.cpp.  

void QCanvasItem::setXVelocity ( double vx )

See also setYVelocity() and setVelocity().  

void QCanvasItem::setY ( double y )

See also y() and move().

Example: chart/chartform_canvas.cpp.  

void QCanvasItem::setYVelocity ( double vy )

See also setXVelocity() and setVelocity().  

void QCanvasItem::setZ ( double z )

See also z() and move().

Examples:  

void QCanvasItem::show ()

Examples:  

void QCanvasItem::update () [protected]

bool QCanvasItem::visible () const

Use isVisible() instead.  

double QCanvasItem::x () const

Example: canvas/canvas.cpp.  

double QCanvasItem::xVelocity () const

double QCanvasItem::y () const

Example: canvas/canvas.cpp.  

double QCanvasItem::yVelocity () const

double QCanvasItem::z () const

SEE ALSO

COPYRIGHT

AUTHOR

BUGS