![]() |
Home · Overviews · Examples |
The QGraphicsScene class provides a surface for managing a large number of 2D graphical items. More...
Inherits QObject.
The QGraphicsScene class provides a surface for managing a large number of 2D graphical items.
The class serves as a container for QGraphicsItems. It is used together with QGraphicsView for visualizing graphical items, such as lines, rectangles, text, or even custom items, on a 2D surface. QGraphicsScene is part of The Graphics View Framework.
QGraphicsScene also provides functionality that lets you efficiently determine both the location of items, and for determining what items are visible within an arbitrary area on the scene. With the QGraphicsView widget, you can either visualize the whole scene, or zoom in and view only parts of the scene.
Example:
QGraphicsScene scene; scene.addText("Hello, world!"); QGraphicsView view(&scene); view.show();
Note that QGraphicsScene has no visual appearance of its own; it only manages the items. You need to create a QGraphicsView widget to visualize the scene.
To add items to a scene, you start off by constructing a QGraphicsScene object. Then, you have two options: either add your existing QGraphicsItem objects by calling addItem, or you can call one of the convenience functions addEllipse, addLine, addPath, addPixmap, addPolygon, addRect, or addText, which all return a pointer to the newly added item. The dimensions of the items added with these functions are relative to the item's coordinate system, and the items position is initialized to (0, 0) in the scene.
You can then visualize the scene using QGraphicsView. When the scene changes, (e.g., when an item moves or is transformed) QGraphicsScene emits the changed signal. To remove an item, call removeItem.
QGraphicsScene uses an indexing algorithm to manage the location of items efficiently. By default, a BSP (Binary Space Partitioning) tree is used; an algorithm suitable for large scenes where most items remain static (i.e., do not move around). You can choose to disable this index by calling setItemIndexMethod. For more information about the available indexing algorithms, see the itemIndexMethod property.
The scene's bounding rect is set by calling setSceneRect. Items can be placed at any position on the scene, and the size of the scene is by default unlimited. The scene rect is used only for internal bookkeeping, maintaining the scene's item index. If the scene rect is unset, QGraphicsScene will use the bounding area of all items, as returned by itemsBoundingRect, as the scene rect. However, itemsBoundingRect is a relatively time consuming function, as it operates by collecting positional information for every item on the scene. Because of this, you should always set the scene rect when operating on large scenes.
One of QGraphicsScene's greatest strengths is its ability to efficiently determine the location of items. Even with millions of items on the scene, the items functions can determine the location of an item within few milliseconds. There are several overloads to items: one that finds items at a certain position, one that finds items inside or intersecting with a polygon or a rectangle, and more. The list of returned items is sorted by stacking order, with the topmost item being the first item in the list. For convenience, there is also an itemAt function that returns the topmost item at a given position.
QGraphicsScene maintains selection information for the scene. To select items, call setSelectionArea, and to clear the current selection, call clearSelection. Call selectedItems to get the list of all selected items.
Another responsibility that QGraphicsScene has, is to propagate events from QGraphicsView. To send an event to a scene, you construct an event that inherits QEvent, and then send it using, for example, QApplication::sendEvent(). event is responsible for dispatching the event to the individual items. Some common events are handled by convenience event handlers. For example, key press events are handled by keyPressEvent, and mouse press events are handled by mousePressEvent.
Key events are delivered to the focus item. To set the focus item, you can either call setFocusItem, passing an item that accepts focus, or the item itself can call QGraphicsItem::setFocus(). Call focusItem to get the current focus item. For compatibility with widgets, the scene also maintains its own focus information. By default, the scene does not have focus, and all key events are discarded. If setFocus is called, or if an item on the scene gains focus, the scene automatically gains focus. If the scene has focus, hasFocus will return true, and key events will be forwarded to the focus item, if any. If the scene loses focus, (i.e., someone calls clearFocus,) while an item has focus, the scene will maintain its item focus information, and once the scene regains focus, it will make sure the last focus item regains focus.
For mouse-over effects, QGraphicsScene dispatches hover events. If an item accepts hover events (see QGraphicsItem::acceptsHoverEvents()), it will receive a GraphicsSceneHoverEnter event when the mouse enters its area. As the mouse continues moving inside the item's area, QGraphicsScene will send it GraphicsSceneHoverMove events. When the mouse leaves the item's area, the item will receive a GraphicsSceneHoverLeave event.
All mouse events are delivered to the current mouse grabber item. An item becomes the scene's mouse grabber if it accepts mouse events (see QGraphicsItem::acceptedMouseButtons()) and it receives a mouse press. It stays the mouse grabber until it receives a mouse release when no other mouse buttons are pressed. You can call mouseGrabberItem to determine what item is currently grabbing the mouse.
See also QGraphicsItem and QGraphicsView.
Copyright © 2008 Trolltech | Trademarks | Qt Jambi 4.3.5_01 |