QCanvasItem(3qt)QCanvasItem(3qt)NAME
QCanvasItem - Abstract graphic object on a QCanvas
SYNOPSIS
#include <qcanvas.h>
Inherits Qt.
Inherited by QCanvasSprite, QCanvasPolygonalItem, and QCanvasText.
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 x )
void setY ( double y )
void setZ ( double z )
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 phase )
virtual bool collidesWith ( const QCanvasItem * other ) const = 0
QCanvasItemList collisions ( bool exact ) const
virtual void setCanvas ( QCanvas * c )
virtual void draw ( QPainter & painter ) = 0
void show ()
void hide ()
virtual void setVisible ( bool yes )
bool isVisible () const
virtual void setSelected ( bool yes )
bool isSelected () const
virtual void setEnabled ( bool yes )
bool isEnabled () const
virtual void setActive ( bool yes )
bool isActive () const
bool visible () const (obsolete)
bool selected () const (obsolete)
bool enabled () const (obsolete)
bool active () const (obsolete)
enum RttiValues { Rtti_Item = 0, Rtti_Sprite = 1, Rtti_PolygonalItem =
2, Rtti_Text = 3, Rtti_Polygon = 4, Rtti_Rectangle = 5,
Rtti_Ellipse = 6, Rtti_Line = 7, Rtti_Spline = 8 }
virtual int rtti () const
virtual QRect boundingRect () const = 0
virtual QRect boundingRectAdvanced () const
QCanvas * canvas () const
Protected Members
void update ()
DESCRIPTION
The QCanvasItem class provides an abstract graphic object on a QCanvas.
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
This enum is used to name the different types of canvas item.
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 DOCUMENTATIONQCanvasItem::QCanvasItem ( QCanvas * canvas )
Constructs a QCanvasItem on canvas canvas.
See also setCanvas().
QCanvasItem::~QCanvasItem () [virtual]
Destroys the QCanvasItem and removes it from its canvas.
bool QCanvasItem::active () const
This function is obsolete. It is provided to keep old source working.
We strongly advise against using it in new code.
Use isActive() instead.
void QCanvasItem::advance ( int phase ) [virtual]
The default implementation moves the canvas item, if it is animated(),
by the preset velocity if phase is 1, and does nothing if phase 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 also QCanvas::advance() and setVelocity().
Example: canvas/canvas.cpp.
Reimplemented in QCanvasSprite.
bool QCanvasItem::animated () const
Returns TRUE if the canvas item is in motion; otherwise returns FALSE.
See also setVelocity() and setAnimated().
QRect QCanvasItem::boundingRect () const [pure virtual]
Returns the bounding rectangle in pixels that the canvas item covers.
See also boundingRectAdvanced().
Reimplemented in QCanvasSprite, QCanvasPolygonalItem, and QCanvasText.
QRect QCanvasItem::boundingRectAdvanced () const [virtual]
Returns the bounding rectangle of pixels that the canvas item will
cover after advance(1) is called.
See also boundingRect().
QCanvas * QCanvasItem::canvas () const
Returns the canvas containing the canvas item.
bool QCanvasItem::collidesWith ( const QCanvasItem * other ) const [pure
virtual]
Returns TRUE if the canvas item will collide with the other item after
they have moved by their current velocities; otherwise returns FALSE.
See also collisions().
Example: canvas/canvas.cpp.
QCanvasItemList QCanvasItem::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 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]
This abstract virtual function draws the canvas item using painter.
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
This function is obsolete. It is provided to keep old source working.
We strongly advise against using it in new code.
Use isEnabled() instead.
void QCanvasItem::hide ()
Shorthand for setVisible(FALSE).
bool QCanvasItem::isActive () const
Returns TRUE if the QCanvasItem is active; otherwise returns FALSE.
bool QCanvasItem::isEnabled () const
Returns TRUE if the QCanvasItem is enabled; otherwise returns FALSE.
bool QCanvasItem::isSelected () const
Returns TRUE if the canvas item is selected; otherwise returns FALSE.
bool QCanvasItem::isVisible () const
Returns TRUE if the canvas item is visible; otherwise returns FALSE.
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 )
Moves the canvas item to the absolute position (x, y).
Example: canvas/canvas.cpp.
void QCanvasItem::moveBy ( double dx, double dy ) [virtual]
Moves the canvas item relative to its current position by (dx, dy).
Example: canvas/canvas.cpp.
int QCanvasItem::rtti () const [virtual]
Returns 0 (QCanvasItem::Rtti_Item).
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
This function is obsolete. It is provided to keep old source working.
We strongly advise against using it in new code.
Use isSelected() instead.
void QCanvasItem::setActive ( bool yes ) [virtual]
Sets the active flag of the item to yes. If this changes the item's
active state the item will be redrawn when QCanvas::update() is next
called.
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]
Sets the canvas item to be in motion if y is TRUE, or not if y is
FALSE. The speed and direction of the motion is set with setVelocity(),
or with setXVelocity() and setYVelocity().
See also advance() and QCanvas::advance().
void QCanvasItem::setCanvas ( QCanvas * c ) [virtual]
Sets the QCanvas upon which the canvas item is to be drawn to c.
See also canvas().
void QCanvasItem::setEnabled ( bool yes ) [virtual]
Sets the enabled flag of the item to yes. If this changes the item's
enabled state the item will be redrawn when QCanvas::update() is next
called.
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]
Sets the selected flag of the item to yes. If this changes the item's
selected state the item will be redrawn when QCanvas::update() is next
called.
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]
Sets the canvas item to be in motion, moving by vx and vy pixels in the
horizontal and vertical directions respectively.
See also advance(), setXVelocity(), and setYVelocity().
void QCanvasItem::setVisible ( bool yes ) [virtual]
Makes the canvas item 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 canvas item so that its x-position is x.
See also x() and move().
Example: chart/chartform_canvas.cpp.
void QCanvasItem::setXVelocity ( double vx )
Sets the horizontal component of the canvas item's velocity to vx.
See also setYVelocity() and setVelocity().
void QCanvasItem::setY ( double y )
Moves the canvas item so that its y-position is y.
See also y() and move().
Example: chart/chartform_canvas.cpp.
void QCanvasItem::setYVelocity ( double vy )
Sets the vertical component of the canvas item's velocity to vy.
See also setXVelocity() and setVelocity().
void QCanvasItem::setZ ( double z )
Sets the z index of the canvas item to z. Higher-z items obscure (are
in front of) lower-z items.
See also z() and move().
Examples:
void QCanvasItem::show ()
Shorthand for setVisible(TRUE).
Examples:
void QCanvasItem::update () [protected]
Call this function to repaint the canvas's changed chunks.
bool QCanvasItem::visible () const
This function is obsolete. It is provided to keep old source working.
We strongly advise against using it in new code.
Use isVisible() instead.
double QCanvasItem::x () const
Returns the horizontal position of the canvas item. Note that
subclasses often have an origin other than the top-left corner.
Example: canvas/canvas.cpp.
double QCanvasItem::xVelocity () const
Returns the horizontal velocity component of the canvas item.
double QCanvasItem::y () const
Returns the vertical position of the canvas item. Note that subclasses
often have an origin other than the top-left corner.
Example: canvas/canvas.cpp.
double QCanvasItem::yVelocity () const
Returns the vertical velocity component of the canvas item.
double QCanvasItem::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 ALSO
http://doc.trolltech.com/qcanvasitem.html
http://www.trolltech.com/faq/tech.html
COPYRIGHT
Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
license file included in the distribution for a complete license
statement.
AUTHOR
Generated automatically from the source code.
BUGS
If you find a bug in Qt, please report it as described in
http://doc.trolltech.com/bughowto.html. Good bug reports help us to
help you. Thank you.
The definitive Qt documentation is provided in HTML format; it is
located at $QTDIR/doc/html and can be read using Qt Assistant or with a
web browser. This man page is provided as a convenience for those users
who prefer man pages, although this format is not officially supported
by Trolltech.
If you find errors in this manual page, please report them to qt-
bugs@trolltech.com. Please include the name of the manual page
(qcanvasitem.3qt) and the Qt version (3.3.8).
Trolltech AS 2 February 2007 QCanvasItem(3qt)
