QCanvasItem(3qt)

📦 version 3.3.8b, in fedora 43, fedora 44

💖 QCanvasItem 💖

ok so welcome to the QCanvasItem(3qt) page bestie, sit down, grab a strawberry 🍓, we're learning about the abstract graphic object on a QCanvas and it's gonna be iconic, no cap.

✨ NAME ✨

QCanvasItem — the abstract graphic object on a QCanvas. yes she's abstract, she's the blueprint, she's the moment. 💅

✨ 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. she's abstract, she's a vibe, she's the mother of all canvas items 💖

ok so a whole little family of QCanvasItem subclasses gives you behaviour you can use immediately, out of the box, no assembly required. But this class itself? She's a pure abstract superclass — she only provides the behaviour that all the concrete canvas item classes share. Do not try to subclass QCanvasItem directly, bestie. That's not the move. It is so much easier to subclass one of her subclasses, like QCanvasPolygonalItem (the commonest base class, she's the people's princess 👑), QCanvasRectangle, QCanvasSprite, QCanvasEllipse or QCanvasText.

Canvas items get added to a canvas by constructing them and handing the canvas over to the canvas item's constructor. And if you ever want to move an item to a totally different canvas? setCanvas() — done. slay.

Items show up on the canvas after their show() function has been called (or setVisible(TRUE)), and after update() has been called. Read that again. The canvas only shows items that are visible, and then only if update() is called. Both. Not one. Both. 😤 And if you created the canvas without passing a width and height to the constructor, you'll also need to call resize(). Oh and also — the canvas background defaults to white and canvas items default to white, so like... you may need to change colors to actually see your items. white on white is giving invisible, bestie 🙈

A QCanvasItem object can be moved around in the x(), y() and z() dimensions using functions such as move(), moveBy(), setX(), setY() and setZ(). You can also set a canvas item in motion — make it animated — using setAnimated(), and give it a velocity in the x and y directions with setXVelocity() and setYVelocity(). And plot twist: the exact 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. that's her whole thing.

The size of a canvas item is given by boundingRect(). And use boundingRectAdvanced() to see what the size of the canvas item will be after the next advance(1) call. future-predicting queen 🔮

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. (yes, same energy, different class.)

QCanvasItem also provides the setEnabled(), setActive() and setSelected() functions. These functions set the relevant boolean and cause a repaint — but heads up: the boolean values they set are not used in QCanvasItem itself. You can make use of these booleans in your subclasses. they're just little vibes you can pick up if you want 🎀

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 DOCUMENTATION ✨

QCanvasItem::QCanvasItem ( QCanvas * canvas )

Constructs a QCanvasItem on canvas canvas.

See also setCanvas().

QCanvasItem::~QCanvasItem () [virtual]

Destroys the QCanvasItem and removes it from its canvas. she said goodbye and she took herself off the canvas, that's closure 💜

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. fr fr, upgrade.

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. it's giving "who's your mother" but for canvases 🌸

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. lazy-girl efficiency, we love her 💅

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. check before you cast, bestie, it's called informed consent 😌

⚠️ 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. she predicts the future, she's psychic, that's the whole plot 🔮💥

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). leave it how you found it, that's basic roommate etiquette 😤

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). that's it. that's the function. short queen. ✨

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. so many conditions, so much nuance, she's complicated and we respect that 💜

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 rtti () const [virtual] — hands you back 0, which is QCanvasItem::Rtti_Item. 💫

🌸 int QCanvasItem::rtti () const [virtual] 🌸

Okay so this one returns 0 and that value has a whole name, it's QCanvasItem::Rtti_Item. That's the base vibe. ✨

Here's the thing though — you're supposed to make your own derived classes return their own little values for rtti(), so you can actually tell apart the objects that QCanvas::at() throws at you. And listen: use values greater than 1000 to leave room for extensions to this class, bestie. Don't be greedy with the low numbers. 💅

Also real talk — overuse of this functionality can damage its extensibility. Like, the move is: once you've identified a base class of a QCanvasItem found by QCanvas::at(), cast it to that type and call actual meaningful methods. Don't just sit there acting upon the object based on its rtti value forever. That's not the serve you think it is. 😭

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. That's it, that's the whole thing. Old code gets a pass, new code does not. ✨

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

Sets the active flag of the item to yes. If this actually changes the item's active state, the item will get redrawn the next time QCanvas::update() is called. 🦋

And here's the tea: the QCanvas, QCanvasItem and the Qt-supplied QCanvasItem subclasses do not make use of this value. Like, at all. The setActive() function is supplied because so many applications need it, but it is entirely up to you how you use the isActive() value. It's giving "here's a flag, do whatever with it". 🙈

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

Sets the canvas item to be in motion if y is TRUE, or not in motion if y is FALSE. The speed and direction of the motion gets 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. Moving your whole item to a new canvas, iconic. 💫

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. 🌸

Same disclaimer as before, no cap: the QCanvas, QCanvasItem and the Qt-supplied QCanvasItem subclasses do not make use of this value. setEnabled() is supplied because many applications need it, but how you use the isEnabled() value is 100% on you. 🫶

✨ 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. 💅

And yes, same energy: 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. Main character energy, your call. 👑

🔥 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. Zoom zoom. 🦋

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 — so don't be surprised when it doesn't pop off instantly. ⭐

💜 void QCanvasItem::setX ( double x ) 💜

Moves the canvas item so that its x-position is x. Simple, clean, no notes. ✨

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. Vertical bestie moment. 💫

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. And remember the golden rule: higher-z items obscure (are in front of) lower-z items. Front of the line = bigger z. Periodt. 👑

See also z() and move().

Examples:

🎀 void QCanvasItem::show () 🎀

Shorthand for setVisible(TRUE). That's the whole function, and honestly? We love a one-liner. 💅

Examples:

🧚 void QCanvasItem::update () [protected] 🧚

Call this function to repaint the canvas's changed chunks. It's protected, so it's a "family only" kind of function, iykyk. 🌸

💜 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, so don't just assume top-left and get shocked later. 🙈

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. ⚠️ Same heads-up as before: 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. Stacking order, but make it cute. 💅

👀 SEE ALSO 👀

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. (Not me writing it by hand, bestie — the machine did that part. ✨)

🌸 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 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). That's the info they need, don't leave it out! 💌

And that's a wrap on QCanvasItem(3qt), bestie!! 🎉 This one's brought to you by Trolltech AS, dated 2 February 2007, and it is genuinely, truly the end of the page. Go draw something iconic. 💅✨👑

📦 where this page comes from