Contents

• Public Types
• Public Functions
• Protected Functions
• Detailed Description

Detailed Description

TheQ3CanvasItem class provides an abstract graphic object on aQ3Canvas.

A variety ofQ3CanvasItem 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.Q3CanvasItem is not intended for direct subclassing. It is much easier to subclass one of its subclasses, e.g.Q3CanvasPolygonalItem (the commonest base class),Q3CanvasRectangle,Q3CanvasSprite,Q3CanvasEllipse orQ3CanvasText.

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

Items appear on the canvas after theirshow() function has been called (orsetVisible(true)), andafterupdate() has been called. The canvas only shows items that arevisible, and then only ifupdate() is called. If you created the canvas without passing a width and height to the constructor you'll also need to callresize(). Since the canvas background defaults to white and canvas items default to white, you may need to change colors to see your items.

AQ3CanvasItem object can be moved in thex(),y() andz() dimensions using functions such asmove(),moveBy(),setX(),setY() andsetZ(). A canvas item can be set in motion, `animated', usingsetAnimated() and given a velocity in the x and y directions withsetXVelocity() andsetYVelocity() -- the same effect can be achieved by callingsetVelocity(). Use thecollidesWith() function to see if the canvas item will collide on thenext advance(1) and usecollisions() to see what collisions have occurred.

UseQ3CanvasSprite or your own subclass ofQ3CanvasSprite to create canvas items which are animated, i.e. which change over time.

The size of a canvas item is given byboundingRect(). UseboundingRectAdvanced() to see what the size of the canvas item will beafter the next advance(1) call.

Thertti() function is used for identifying subclasses ofQ3CanvasItem. Thecanvas() function returns a pointer to the canvas which contains the canvas item.

Q3CanvasItem provides theshow() andisVisible() functions like those inQWidget.

Q3CanvasItem also provides thesetEnabled(),setActive() andsetSelected() functions; these functions set the relevant boolean and cause a repaint but the boolean values they set are not used inQ3CanvasItem 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.

Member Type Documentation

enum Q3CanvasItem::RttiValues

This enum is used to name the different types of canvas item.

Member Function Documentation

Q3CanvasItem::Q3CanvasItem(Q3Canvas * canvas)

Constructs aQ3CanvasItem on canvascanvas.

See alsosetCanvas().

[virtual]Q3CanvasItem::~Q3CanvasItem()

Destroys theQ3CanvasItem and removes it from its canvas.

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

The default implementation moves the canvas item, if it isanimated(), by the preset velocity ifphase is 1, and does nothing ifphase is 0.

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 alsoQ3Canvas::advance() andsetVelocity().

bool Q3CanvasItem::animated() const

Returns true if the canvas item is in motion; otherwise returns false.

See alsosetVelocity() andsetAnimated().

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

Returns the bounding rectangle in pixels that the canvas item covers.

See alsoboundingRectAdvanced().

[virtual]QRect Q3CanvasItem::boundingRectAdvanced() const

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

See alsoboundingRect().

Q3Canvas * Q3CanvasItem::canvas() const

Returns the canvas containing the canvas item.

See alsosetCanvas().

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

Returns true if the canvas item will collide with theother itemafter they have moved by their current velocities; otherwise returns false.

See alsocollisions().

Q3CanvasItemList Q3CanvasItem::collisions(bool exact) const

Returns the list of canvas items that this canvas item has collided with.

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 theexact parameter.

Ifexact is true, the canvas items returned have been accurately tested for collision with the canvas item.

Ifexact is false, the canvas items returned arenear the canvas item. You can test the canvas items returned usingcollidesWith() 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 Q3CanvasItems, but often you will need to cast the items to their subclass types. The safe way to do this is to usertti() 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 (seesetVelocity()), then collision testing is done based on where the itemwill 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.

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

This abstract virtual function draws the canvas item usingpainter.

void Q3CanvasItem::hide()

Shorthand forsetVisible(false).

bool Q3CanvasItem::isActive() const

Returns true if theQ3CanvasItem is active; otherwise returns false.

bool Q3CanvasItem::isEnabled() const

Returns true if theQ3CanvasItem is enabled; otherwise returns false.

bool Q3CanvasItem::isSelected() const

Returns true if the canvas item is selected; otherwise returns false.

bool Q3CanvasItem::isVisible() const

Returns true if the canvas item is visible; otherwise returns false.

Note that in this context true doesnot 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 alsosetVisible() andz().

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

Moves the canvas item to the absolute position (x,y).

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

Moves the canvas item relative to its current position by (dx,dy).

[virtual]int Q3CanvasItem::rtti() const

Returns 0 (Q3CanvasItem::Rtti_Item).

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

Overuse of this functionality can damage its extensibility. For example, once you have identified a base class of aQ3CanvasItem found by Q3Canvas::at(), cast it to that type and call meaningful methods rather than acting upon the object based on its rtti value.

For example:

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

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

Sets the active flag of the item toyes. If this changes the item's active state the item will be redrawn whenQ3Canvas::update() is next called.

TheQ3Canvas,Q3CanvasItem and the Qt-suppliedQ3CanvasItem 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 theisActive() value.

See alsoactive().

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

Sets the canvas item to be in motion ify is true, or not ify is false. The speed and direction of the motion is set withsetVelocity(), or withsetXVelocity() andsetYVelocity().

See alsoanimated(),advance(), andQ3Canvas::advance().

[virtual]void Q3CanvasItem::setCanvas(Q3Canvas * c)

Sets theQ3Canvas upon which the canvas item is to be drawn toc.

See alsocanvas().

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

Sets the enabled flag of the item toyes. If this changes the item's enabled state the item will be redrawn whenQ3Canvas::update() is next called.

TheQ3Canvas,Q3CanvasItem and the Qt-suppliedQ3CanvasItem 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 theisEnabled() value.

See alsoenabled().

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

Sets the selected flag of the item toyes. If this changes the item's selected state the item will be redrawn whenQ3Canvas::update() is next called.

TheQ3Canvas,Q3CanvasItem and the Qt-suppliedQ3CanvasItem 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 theisSelected() value.

See alsoselected().

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

Sets the canvas item to be in motion, moving byvx andvy pixels in the horizontal and vertical directions respectively.

See alsoadvance(),setXVelocity(), andsetYVelocity().

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

Makes the canvas item visible ifyes is true, or invisible ifyes is false. The change takes effect whenQ3Canvas::update() is next called.

See alsovisible().

void Q3CanvasItem::setX(double x)

Moves the canvas item so that its x-position isx.

See alsox() andmove().

void Q3CanvasItem::setXVelocity(double vx)

Sets the horizontal component of the canvas item's velocity tovx.

See alsoxVelocity(),setYVelocity(), andsetVelocity().

void Q3CanvasItem::setY(double y)

Moves the canvas item so that its y-position isy.

See alsoy() andmove().

void Q3CanvasItem::setYVelocity(double vy)

Sets the vertical component of the canvas item's velocity tovy.

See alsoyVelocity(),setXVelocity(), andsetVelocity().

void Q3CanvasItem::setZ(double z)

Sets the z index of the canvas item toz. Higher-z items obscure (are in front of) lower-z items.

See alsoz() andmove().

void Q3CanvasItem::show()

Shorthand forsetVisible(true).

[protected]void Q3CanvasItem::update()

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

double Q3CanvasItem::x() const

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

See alsosetX().

double Q3CanvasItem::xVelocity() const

Returns the horizontal velocity component of the canvas item.

See alsosetXVelocity().

double Q3CanvasItem::y() const

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

See alsosetY().

double Q3CanvasItem::yVelocity() const

Returns the vertical velocity component of the canvas item.

See alsosetYVelocity().

double Q3CanvasItem::z() const

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

See alsosetZ().