/** \ingroup core * A item that forms part of a map composition. */ class QgsComposerItem : QgsComposerObject, QGraphicsRectItem { %TypeHeaderCode #include #include #include #include #include #include #include #include #include #include #include #include #include #include %End %ConvertToSubClassCode // the conversions have to be static, because they're using multiple inheritance // (seen in PyQt4 .sip files for some QGraphicsItem classes) switch (sipCpp->type()) { case QgsComposerItem::ComposerItem: sipType = sipType_QgsComposerItem; *sipCppRet = static_cast(sipCpp); break; case QgsComposerItem::ComposerArrow: sipType = sipType_QgsComposerArrow; *sipCppRet = static_cast(sipCpp); break; case QgsComposerItem::ComposerItemGroup: sipType = sipType_QgsComposerItemGroup; *sipCppRet = static_cast(sipCpp); break; case QgsComposerItem::ComposerLabel: sipType = sipType_QgsComposerLabel; *sipCppRet = static_cast(sipCpp); break; case QgsComposerItem::ComposerLegend: sipType = sipType_QgsComposerLegend; *sipCppRet = static_cast(sipCpp); break; case QgsComposerItem::ComposerMap: sipType = sipType_QgsComposerMap; *sipCppRet = static_cast(sipCpp); break; case QgsComposerItem::ComposerPaper: sipType = sipType_QgsPaperItem; *sipCppRet = static_cast(sipCpp); break; case QgsComposerItem::ComposerPicture: sipType = sipType_QgsComposerPicture; *sipCppRet = static_cast(sipCpp); break; case QgsComposerItem::ComposerScaleBar: sipType = sipType_QgsComposerScaleBar; *sipCppRet = static_cast(sipCpp); break; case QgsComposerItem::ComposerShape: sipType = sipType_QgsComposerShape; *sipCppRet = static_cast(sipCpp); break; case QgsComposerItem::ComposerPolygon: sipType = sipType_QgsComposerPolygon; *sipCppRet = static_cast(sipCpp); break; case QgsComposerItem::ComposerPolyline: sipType = sipType_QgsComposerPolyline; *sipCppRet = static_cast(sipCpp); break; case QgsComposerItem::ComposerFrame: sipType = sipType_QgsComposerFrame; *sipCppRet = static_cast(sipCpp); break; default: sipType = 0; } %End public: enum ItemType { // base class for the items ComposerItem, // derived classes ComposerArrow, ComposerItemGroup, ComposerLabel, ComposerLegend, ComposerMap, ComposerPaper, // QgsPaperItem ComposerPicture, ComposerScaleBar, ComposerShape, ComposerPolygon, ComposerPolyline, ComposerTable, ComposerAttributeTable, ComposerTextTable, ComposerFrame }; /** Describes the action (move or resize in different directon) to be done during mouse move*/ enum MouseMoveAction { MoveItem, ResizeUp, ResizeDown, ResizeLeft, ResizeRight, ResizeLeftUp, ResizeRightUp, ResizeLeftDown, ResizeRightDown, NoAction }; enum ItemPositionMode { UpperLeft, UpperMiddle, UpperRight, MiddleLeft, Middle, MiddleRight, LowerLeft, LowerMiddle, LowerRight }; //note - must sync with QgsMapCanvas::WheelAction. //TODO - QGIS 3.0 move QgsMapCanvas::WheelAction from GUI->CORE and remove this enum /** Modes for zooming item content */ enum ZoomMode { Zoom = 0, /*!< Zoom to center of content */ ZoomRecenter, /*!< Zoom and recenter content to point */ ZoomToPoint, /*!< Zoom while maintaining relative position of point */ NoZoom /*!< No zoom */ }; /** Constructor @param composition parent composition @param manageZValue true if the z-Value of this object should be managed by mComposition*/ QgsComposerItem( QgsComposition *composition /TransferThis/, bool manageZValue = true ); /** Constructor with box position and composer object @param x x coordinate of item @param y y coordinate of item @param width width of item @param height height of item @param composition parent composition @param manageZValue true if the z-Value of this object should be managed by mComposition*/ QgsComposerItem( qreal x, qreal y, qreal width, qreal height, QgsComposition *composition /TransferThis/, bool manageZValue = true ); virtual ~QgsComposerItem(); /** Return correct graphics item type. */ virtual int type() const; /** Returns whether this item has been removed from the composition. Items removed * from the composition are not deleted so that they can be restored via an undo * command. * @returns true if the item has been removed from the composition * @note added in QGIS 2.5 * @see setIsRemoved */ virtual bool isRemoved() const; /** Sets whether this item has been removed from the composition. Items removed * from the composition are not deleted so that they can be restored via an undo * command. * @param removed set to true if the item has been removed from the composition * @note added in QGIS 2.5 * @see isRemoved */ void setIsRemoved( const bool removed ); /** \brief Set selected, selected item should be highlighted */ virtual void setSelected( bool s ); /** \brief Is selected */ virtual bool selected() const; /** Moves item in canvas coordinates*/ void move( double dx, double dy ); /** Move Content of item. Does nothing per default (but implemented in composer map) @param dx move in x-direction (canvas coordinates) @param dy move in y-direction(canvas coordinates)*/ virtual void moveContent( double dx, double dy ); /** Zoom content of item. Does nothing per default (but implemented in composer map) * @param factor zoom factor, where > 1 results in a zoom in and < 1 results in a zoom out * @param point item point for zoom center * @param mode zoom mode * @note added in QGIS 2.5 */ virtual void zoomContent( const double factor, const QPointF point, const ZoomMode mode = QgsComposerItem::Zoom ); /** Gets the page the item is currently on. * @returns page number for item, beginning on page 1 * @see pagePos * @see updatePagePos * @note this method was added in version 2.4 */ int page() const; /** Returns the item's position relative to its current page. * @returns position relative to the page's top left corner. * @see page * @see updatePagePos * @note this method was added in version 2.4 */ QPointF pagePos() const; /** Moves the item so that it retains its relative position on the page * when the paper size changes. * @param newPageWidth new width of the page in mm * @param newPageHeight new height of the page in mm * @see page * @see pagePos * @note this method was added in version 2.4 */ void updatePagePos( double newPageWidth, double newPageHeight ); /** Moves the item to a new position (in canvas coordinates) @param x item position x (mm) @param y item position y (mm) @param itemPoint reference point which coincides with specified position @param page if page > 0, y is interpreted as relative to the origin of the specified page, if page <= 0, y is in absolute canvas coordinates. a page number of 1 corresponds to the first page. */ void setItemPosition( double x, double y, ItemPositionMode itemPoint = UpperLeft, int page = -1 ); /** Sets item position and width / height in one go @param x item position x (mm) @param y item position y (mm) @param width item width (mm) @param height item height (mm) @param itemPoint reference point which coincides with specified position @param posIncludesFrame set to true if the position and size arguments include the item's frame border @param page if page > 0, y is interpreted as relative to the origin of the specified page, if page <= 0, y is in absolute canvas coordinates. a page number of 1 corresponds to the first page. */ void setItemPosition( double x, double y, double width, double height, ItemPositionMode itemPoint = UpperLeft, bool posIncludesFrame = false, int page = -1 ); /** Returns item's last used position mode. @note: This property has no effect on actual's item position, which is always the top-left corner. */ ItemPositionMode lastUsedPositionMode(); /** Sets this items bound in scene coordinates such that 1 item size units corresponds to 1 scene size unit*/ virtual void setSceneRect( const QRectF &rectangle ); /** Writes parameter that are not subclass specific in document. Usually called from writeXML methods of subclasses*/ bool _writeXml( QDomElement &itemElem, QDomDocument &doc ) const; /** Reads parameter that are not subclass specific in document. Usually called from readXML methods of subclasses*/ bool _readXml( const QDomElement &itemElem, const QDomDocument &doc ); /** Whether this item has a frame or not. * @returns true if there is a frame around this item, otherwise false. * @see setFrameEnabled * @see frameStrokeWidth * @see frameJoinStyle * @see frameStrokeColor */ bool hasFrame() const; /** Set whether this item has a frame drawn around it or not. * @param drawFrame draw frame * @see hasFrame * @see setFrameStrokeWidth * @see setFrameJoinStyle * @see setFrameStrokeColor */ virtual void setFrameEnabled( const bool drawFrame ); /** Sets frame stroke color * @param color new color for stroke frame * @note introduced in 2.6 * @see frameStrokeColor * @see setFrameEnabled * @see setFrameJoinStyle * @see setFrameStrokeWidth */ virtual void setFrameStrokeColor( const QColor &color ); /** Returns the frame's stroke color. Only used if hasFrame is true. * @returns frame stroke color * @note introduced in 2.6 * @see hasFrame * @see setFrameStrokeColor * @see frameJoinStyle * @see setFrameStrokeColor */ QColor frameStrokeColor() const; /** Sets frame stroke width * @param strokeWidth new width for stroke frame * @note introduced in 2.2 * @see frameStrokeWidth * @see setFrameEnabled * @see setFrameJoinStyle * @see setFrameStrokeColor */ virtual void setFrameStrokeWidth( const double strokeWidth ); /** Returns the frame's stroke width. Only used if hasFrame is true. * @returns Frame stroke width * @note introduced in 2.3 * @see hasFrame * @see setFrameStrokeWidth * @see frameJoinStyle * @see frameStrokeColor */ double frameStrokeWidth() const; /** Returns the join style used for drawing the item's frame * @returns Join style for outline frame * @note introduced in 2.3 * @see hasFrame * @see setFrameJoinStyle * @see frameStrokeWidth * @see frameStrokeColor */ Qt::PenJoinStyle frameJoinStyle() const; /** Sets join style used when drawing the item's frame * @param style Join style for outline frame * @note introduced in 2.3 * @see setFrameEnabled * @see frameJoinStyle * @see setFrameStrokeWidth * @see setFrameStrokeColor */ void setFrameJoinStyle( const Qt::PenJoinStyle style ); /** Returns the estimated amount the item's frame bleeds outside the item's * actual rectangle. For instance, if the item has a 2mm frame stroke, then * 1mm of this frame is drawn outside the item's rect. In this case the * return value will be 1.0 * @note introduced in 2.2 * @see rectWithFrame */ virtual double estimatedFrameBleed() const; /** Returns the item's rectangular bounds, including any bleed caused by the item's frame. * The bounds are returned in the item's coordinate system (see Qt's QGraphicsItem docs for * more details about QGraphicsItem coordinate systems). The results differ from Qt's rect() * function, as rect() makes no allowances for the portion of outlines which are drawn * outside of the item. * @note introduced in 2.2 * @see estimatedFrameBleed */ virtual QRectF rectWithFrame() const; /** Whether this item has a Background or not. * @returns true if there is a Background around this item, otherwise false. * @see setBackgroundEnabled * @see backgroundColor */ bool hasBackground() const; /** Set whether this item has a Background drawn around it or not. * @param drawBackground draw Background * @returns nothing * @see hasBackground * @see setBackgroundColor */ void setBackgroundEnabled( const bool drawBackground ); /** Gets the background color for this item * @returns background color * @see setBackgroundColor * @see hasBackground */ QColor backgroundColor() const; /** Sets the background color for this item * @param backgroundColor new background color * @returns nothing * @see backgroundColor * @see setBackgroundEnabled */ void setBackgroundColor( const QColor &backgroundColor ); /** Returns the item's composition blending mode. * @returns item blending mode * @see setBlendMode */ QPainter::CompositionMode blendMode() const; /** Sets the item's composition blending mode * @param blendMode blending mode for item * @see blendMode */ void setBlendMode( const QPainter::CompositionMode blendMode ); double itemOpacity() const; void setItemOpacity( const double opacity ); /** Returns whether effects (e.g., blend modes) are enabled for the item * @returns true if effects are enabled * @see setEffectsEnabled * @see transparency * @see blendMode */ bool effectsEnabled() const; /** Sets whether effects (e.g., blend modes) are enabled for the item * @param effectsEnabled set to true to enable effects * @see effectsEnabled * @see setTransparency * @see setBlendMode */ void setEffectsEnabled( const bool effectsEnabled ); /** Composite operations for item groups do nothing per default*/ virtual void addItem( QgsComposerItem *item ); virtual void removeItems(); virtual void beginItemCommand( const QString &text ); /** Starts new composer undo command @param commandText command title @param c context for mergeable commands (unknown for non-mergeable commands*/ void beginCommand( const QString &commandText, QgsComposerMergeCommand::Context c = QgsComposerMergeCommand::Unknown ); virtual void endItemCommand(); /** Finish current command and push it onto the undo stack */ void endCommand(); void cancelCommand(); //functions that encapsulate the workaround for the Qt font bug (that is to scale the font size up and then scale the //painter down by the same factor for drawing /** Locks / unlocks the item position for mouse drags * @param lock set to true to prevent item movement and resizing via the mouse * @see positionLock */ void setPositionLock( const bool lock ); /** Returns whether position lock for mouse drags is enabled * returns true if item is locked for mouse movement and resizing * @see setPositionLock */ bool positionLock() const; /** Returns the current rotation for the composer item. * @returns rotation for composer item * @param valueType controls whether the returned value is the user specified rotation, * or the current evaluated rotation (which may be affected by data driven rotation * settings). * @note this method was added in version 2.1 * @see setItemRotation */ double itemRotation( const QgsComposerObject::PropertyValueType valueType = QgsComposerObject::EvaluatedValue ) const; /** Updates item, with the possibility to do custom update for subclasses*/ virtual void updateItem(); /** Get item's id (which is not necessarly unique) * @returns item id * @see setId */ QString id() const; /** Set item's id (which is not necessarly unique) * @param id new id for item * @see id */ void setId( const QString &id ); /** Get item identification name * @returns unique item identification string * @note there is not setter since one can't manually set the id * @see id * @see setId */ QString uuid() const; /** Get item display name. This is the item's id if set, and if * not, a user-friendly string identifying item type. * @returns display name for item * @see id * @see setId * @note added in version 2.5 */ virtual QString displayName() const; /** Sets visibility for item. * @param visible set to true to show item, false to hide item * @note QGraphicsItem::setVisible should not be called directly * on a QgsComposerItem, as some item types (e.g., groups) need to override * the visibility toggle. * @note added in version 2.5 */ virtual void setVisibility( const bool visible ); /** Returns whether the item should be excluded from composer exports and prints * @param valueType controls whether the returned value is the user specified value, * or the current evaluated value (which may be affected by data driven settings). * @returns true if item should be excluded * @note added in version 2.5 * @see setExcludeFromExports */ bool excludeFromExports( const QgsComposerObject::PropertyValueType valueType = QgsComposerObject::EvaluatedValue ); /** Sets whether the item should be excluded from composer exports and prints * @param exclude set to true to exclude the item from exports * @note added in version 2.5 * @see excludeFromExports */ virtual void setExcludeFromExports( const bool exclude ); /** Returns whether this item is part of a group * @returns true if item is in a group * @note added in version 2.5 * @see setIsGroupMember */ bool isGroupMember() const; /** Sets whether this item is part of a group * @param isGroupMember set to true if item is in a group * @note added in version 2.5 * @see isGroupMember */ void setIsGroupMember( const bool isGroupMember ); virtual int numberExportLayers() const; virtual void setCurrentExportLayer( const int layerIdx = -1 ); virtual QgsExpressionContext createExpressionContext() const; void setUpdatesEnabled( bool enabled ); bool updatesEnabled() const; public slots: /** Sets the item rotation * @param r item rotation in degrees * @param adjustPosition set to true if item should be shifted so that rotation occurs * around item center. If false, rotation occurs around item origin * @note this method was added in version 2.1 * @see itemRotation */ virtual void setItemRotation( const double r, const bool adjustPosition = false ); void repaint(); /** Refreshes a data defined property for the item by reevaluating the property's value * and redrawing the item with this new value. * @param property data defined property to refresh. If property is set to * QgsComposerItem::AllProperties then all data defined properties for the item will be * refreshed. * @param context expression context for evaluating data defined expressions * @note this method was added in version 2.5 */ virtual void refreshDataDefinedProperty( const QgsComposerObject::DataDefinedProperty property = QgsComposerObject::AllProperties, const QgsExpressionContext *context = 0 ); protected: //event handlers virtual void mouseMoveEvent( QGraphicsSceneMouseEvent *event ); virtual void mousePressEvent( QGraphicsSceneMouseEvent *event ); virtual void mouseReleaseEvent( QGraphicsSceneMouseEvent *event ); virtual void hoverMoveEvent( QGraphicsSceneHoverEvent *event ); /** Draws additional graphics on selected items. The base implementation has * no effect. */ virtual void drawSelectionBoxes( QPainter *p ); /** Draw black frame around item*/ virtual void drawFrame( QPainter *p ); /** Draw background*/ virtual void drawBackground( QPainter *p ); /** Returns the current (zoom level dependent) tolerance to decide if mouse position is close enough to the item border for resizing*/ double rectHandlerBorderTolerance() const; /** Returns the zoom factor of the graphics view. * @return the factor or -1 in case of error (e.g. graphic view does not exist) */ double horizontalViewScaleFactor() const; //some utility functions /** Return horizontal align snap item. Creates a new graphics line if 0*/ QGraphicsLineItem *hAlignSnapItem(); void deleteHAlignSnapItem(); /** Return vertical align snap item. Creates a new graphics line if 0*/ QGraphicsLineItem *vAlignSnapItem(); void deleteVAlignSnapItem(); void deleteAlignItems(); /** Evaluates an item's bounding rect to consider data defined position and size of item * and reference point * @param newRect target bounding rect for item * @param resizeOnly set to true if the item is only being resized. If true then * the position of the returned rect will be adjusted to account for the item's * position mode * @param context expression context for evaluating data defined expressions * @returns bounding box rectangle for item after data defined size and position have been * set and position mode has been accounted for * @note added in QGIS 2.5 */ QRectF evalItemRect( const QRectF &newRect, const bool resizeOnly = false, const QgsExpressionContext *context = 0 ); /** Returns whether the item should be drawn in the current context * @returns true if item should be drawn * @note added in QGIS 2.5 */ bool shouldDrawItem() const; signals: /** Is emitted on item rotation change*/ void itemRotationChanged( double newRotation ); /** Emitted if the rectangle changes*/ void sizeChanged(); /** Emitted if the item's frame style changes * @note: this function was introduced in version 2.2 */ void frameChanged(); /** Emitted if the item's lock status changes * @note: this function was introduced in version 2.5 */ void lockChanged(); };