Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
[composer] Clean up code, move some methods to QgsComposerUtils, cons…
…t correctness, tests, doc improvements
  • Loading branch information
nyalldawson committed Jul 16, 2014
1 parent 0c7ce60 commit e2d57d9
Show file tree
Hide file tree
Showing 18 changed files with 1,045 additions and 491 deletions.
150 changes: 106 additions & 44 deletions python/core/composer/qgscomposeritem.sip
Expand Up @@ -225,58 +225,69 @@ class QgsComposerItem : QgsComposerObject, QGraphicsRectItem
/**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.
/**Whether this item has a frame or not.
* @returns true if there is a frame around this item, otherwise false.
* @note introduced since 1.8
* @see hasFrame
* @see setFrameEnabled
* @see frameOutlineWidth
* @see frameJoinStyle
*/
bool hasFrame() const;

/** Set whether this item has a frame drawn around it or not.
/**Set whether this item has a frame drawn around it or not.
* @param drawFrame draw frame
* @returns nothing
* @note introduced in 1.8
* @see hasFrame
* @see setFrameOutlineWidth
* @see setFrameJoinStyle
*/
void setFrameEnabled( bool drawFrame );
void setFrameEnabled( const bool drawFrame );

/** Sets frame outline width
/**Sets frame outline width
* @param outlineWidth new width for outline frame
* @returns nothing
* @note introduced in 2.2
* @see frameOutlineWidth
* @see setFrameEnabled
* @see setFrameJoinStyle
*/
virtual void setFrameOutlineWidth( double outlineWidth );
virtual void setFrameOutlineWidth( const double outlineWidth );

/** Returns the frame's outline width. Only used if hasFrame is true.
/**Returns the frame's outline width. Only used if hasFrame is true.
* @returns Frame outline width
* @note introduced in 2.3
* @see hasFrame
* @see setFrameOutlineWidth
* @see frameJoinStyle
*/
double frameOutlineWidth() const;

/** Returns the join style used for drawing the item's frame
/**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 frameOutlineWidth
*/
Qt::PenJoinStyle frameJoinStyle() const;
/** Sets join style used when drawing the item's frame

/**Sets join style used when drawing the item's frame
* @param style Join style for outline frame
* @returns nothing
* @note introduced in 2.3
* @see setFrameEnabled
* @see frameJoinStyle
* @see setFrameOutlineWidth
*/
void setFrameJoinStyle( Qt::PenJoinStyle style );
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 outline, then
* 1mm of this frame is drawn outside the item's rect. In this case the
* return value will be 1.0
/**Returns the estimated amount the item's frame bleeds outside the item's
* actual rectangle. For instance, if the item has a 2mm frame outline, 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;

Expand All @@ -290,53 +301,81 @@ class QgsComposerItem : QgsComposerObject, QGraphicsRectItem
*/
virtual QRectF rectWithFrame() const;

/** Whether this item has a Background or not.
/**Whether this item has a Background or not.
* @returns true if there is a Background around this item, otherwise false.
* @note introduced since 2.0
* @see hasBackground
* @see setBackgroundEnabled
* @see backgroundColor
*/
bool hasBackground() const;

/** Set whether this item has a Background drawn around it or not.
/**Set whether this item has a Background drawn around it or not.
* @param drawBackground draw Background
* @returns nothing
* @note introduced in 2.0
* @see hasBackground
* @see setBackgroundColor
*/
void setBackgroundEnabled( bool drawBackground );
void setBackgroundEnabled( const bool drawBackground );

/** Gets the background color for this item
/**Gets the background color for this item
* @returns background color
* @note introduced in 2.0
* @see setBackgroundColor
* @see hasBackground
*/
QColor backgroundColor() const;

/** Sets the background color for this item
/**Sets the background color for this item
* @param backgroundColor new background color
* @returns nothing
* @note introduced in 2.0
* @see backgroundColor
* @see setBackgroundEnabled
*/
void setBackgroundColor( const QColor& backgroundColor );

/** Returns the item's composition blending mode */
/**Returns the item's composition blending mode.
* @returns item blending mode
* @see setBlendMode
*/
QPainter::CompositionMode blendMode() const;

/** Sets the item's composition blending mode*/
void setBlendMode( QPainter::CompositionMode blendMode );
/**Sets the item's composition blending mode
* @param blendMode blending mode for item
* @see blendMode
*/
void setBlendMode( const QPainter::CompositionMode blendMode );

/** Returns the item's transparency */
/**Returns the item's transparency
* @returns transparency as integer between 0 (transparent) and 255 (opaque)
* @see setTransparency
*/
int transparency() const;
/** Sets the item's transparency */
void setTransparency( int transparency );

/** Returns true if effects (eg blend modes) are enabled for the item
/**Sets the item's transparency
* @param transparency integer between 0 (transparent) and 255 (opaque)
* @see transparency
*/
void setTransparency( const int transparency );

/**Returns whether effects (eg blend modes) are enabled for the item
* @returns true if effects are enabled
* @note introduced in 2.0
* @see setEffectsEnabled
* @see transparency
* @see blendMode
*/
bool effectsEnabled() const;
/** Sets whether effects (eg blend modes) are enabled for the item

/**Sets whether effects (eg blend modes) are enabled for the item
* @param effectsEnabled set to true to enable effects
* @note introduced in 2.0
* @see effectsEnabled
* @see setTransparency
* @see setBlendMode
*/
void setEffectsEnabled( bool effectsEnabled );
void setEffectsEnabled( const bool effectsEnabled );

/**Composite operations for item groups do nothing per default*/
virtual void addItem( QgsComposerItem* item );
Expand Down Expand Up @@ -391,18 +430,26 @@ class QgsComposerItem : QgsComposerObject, QGraphicsRectItem
*/
double fontHeightMillimeters( const QFont& font ) const;

/**Calculates font to from point size to pixel size*/
double pixelFontSize( double pointSize ) const;
/**Calculates font size in mm from a font point size
* @deprecated use QgsComposerUtils::mmFontSize instead
*/
double pixelFontSize( double pointSize ) const /Deprecated/;

/**Returns a font where size is in pixel and font size is upscaled with FONT_WORKAROUND_SCALE*/
QFont scaledFontPixelSize( const QFont& font ) const;

/**Locks / unlocks the item position for mouse drags
@note this method was added in version 1.2*/
void setPositionLock( bool lock );
* @param lock set to true to prevent item movement and resizing via the mouse
* @note this method was added in version 1.2
* @see positionLock
*/
void setPositionLock( const bool lock );

/**Returns position lock for mouse drags (true means locked)
@note this method was added in version 1.2*/
/**Returns whether position lock for mouse drags is enabled
* returns true if item is locked for mouse movement and resizing
* @note this method was added in version 1.2
* @see setPositionLock
*/
bool positionLock() const;

/**Returns the current rotation for the composer item.
Expand All @@ -411,8 +458,9 @@ class QgsComposerItem : QgsComposerObject, QGraphicsRectItem
* 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( QgsComposerObject::PropertyValueType valueType = QgsComposerObject::EvaluatedValue ) const;
double itemRotation( const QgsComposerObject::PropertyValueType valueType = QgsComposerObject::EvaluatedValue ) const;

/**Returns the rotation for the composer item
* @deprecated Use itemRotation()
Expand All @@ -424,16 +472,26 @@ class QgsComposerItem : QgsComposerObject, QGraphicsRectItem
virtual void updateItem();

/**Get item's id (which is not necessarly unique)
@note this method was added in version 1.7*/
* @returns item id
* @note this method was added in version 1.7
* @see setId
*/
QString id() const;

/**Set item's id (which is not necessarly unique)
@note this method was added in version 1.7*/
* @param id new id for item
* @note this method was added in version 1.7
* @see id
*/
void setId( const QString& id );

/**Get item identification name
@note this method was added in version 2.0
@note there is not setter since one can't manually set the id*/
* @returns unique item identification string
* @note this method was added in version 2.0
* @note there is not setter since one can't manually set the id
* @see id
* @see setId
*/
QString uuid() const;

/**Returns whether this item is part of a group
Expand All @@ -448,20 +506,22 @@ class QgsComposerItem : QgsComposerObject, QGraphicsRectItem
* @note added in version 2.5
* @see isGroupMember
*/
void setIsGroupMember( bool isGroupMember );
void setIsGroupMember( const bool isGroupMember );

/**Get the number of layers that this item requires for exporting as layers
* @returns 0 if this item is to be placed on the same layer as the previous item,
* 1 if it should be placed on its own layer, and >1 if it requires multiple export layers
* @note this method was added in version 2.4
* @see setCurrentExportLayer
*/
int numberExportLayers() const;

/**Sets the current layer to draw for exporting
* @param layerIdx can be set to -1 to draw all item layers, and must be less than numberExportLayers()
* @note this method was added in version 2.4
* @see numberExportLayers
*/
void setCurrentExportLayer( int layerIdx = -1 );
void setCurrentExportLayer( const int layerIdx = -1 );

public slots:
/**Sets the item rotation
Expand All @@ -474,8 +534,9 @@ class QgsComposerItem : QgsComposerObject, QGraphicsRectItem
* @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( double r, bool adjustPosition = false );
virtual void setItemRotation( const double r, const bool adjustPosition = false );

void repaint();

Expand All @@ -486,7 +547,8 @@ class QgsComposerItem : QgsComposerObject, QGraphicsRectItem
* refreshed.
* @note this method was added in version 2.5
*/
virtual void refreshDataDefinedProperty( QgsComposerObject::DataDefinedProperty property = QgsComposerObject::AllProperties );
virtual void refreshDataDefinedProperty( const QgsComposerObject::DataDefinedProperty property = QgsComposerObject::AllProperties );


protected:

Expand Down
4 changes: 2 additions & 2 deletions python/core/composer/qgscomposermap.sip
Expand Up @@ -319,7 +319,7 @@ class QgsComposerMap : QgsComposerItem
void updateBoundingRect();

/* reimplement setFrameOutlineWidth, so that updateBoundingRect() is called after setting the frame width */
virtual void setFrameOutlineWidth( double outlineWidth );
virtual void setFrameOutlineWidth( const double outlineWidth );

/**Sets length of the cros segments (if grid style is cross)
@note this function was added in version 1.4*/
Expand Down Expand Up @@ -513,5 +513,5 @@ class QgsComposerMap : QgsComposerItem

void overviewExtentChanged();

virtual void refreshDataDefinedProperty( QgsComposerObject::DataDefinedProperty property = QgsComposerObject::AllProperties );
virtual void refreshDataDefinedProperty( const QgsComposerObject::DataDefinedProperty property = QgsComposerObject::AllProperties );
};
10 changes: 10 additions & 0 deletions python/core/composer/qgscomposerobject.sip
Expand Up @@ -93,6 +93,16 @@ class QgsComposerObject : QObject
/**Triggers a redraw for the item*/
virtual 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.
* @note this method was added in version 2.5
*/
virtual void refreshDataDefinedProperty( const DataDefinedProperty property = AllProperties );


protected:

/**Evaluate a data defined property and return the calculated value
Expand Down

0 comments on commit e2d57d9

Please sign in to comment.