/** \ingroup core
 * A scale bar item that can be added to a map composition.
 */

class QgsComposerScaleBar: QgsComposerItem
{
%TypeHeaderCode
#include "qgscomposerscalebar.h"
%End

  public:

    QgsComposerScaleBar( QgsComposition *composition /TransferThis/ );
    ~QgsComposerScaleBar();

    /** Return correct graphics item type. */
    virtual int type() const;

    /** \brief Reimplementation of QCanvasItem::paint*/
    void paint( QPainter *painter, const QStyleOptionGraphicsItem *itemStyle, QWidget *pWidget );

    //getters and setters
    int numSegments() const;
    void setNumSegments( int nSegments );

    int numSegmentsLeft() const;
    void setNumSegmentsLeft( int nSegmentsLeft );

    double numUnitsPerSegment() const;
    void setNumUnitsPerSegment( double units );

    /** Returns the size mode for scale bar segments.
     * @see setSegmentSizeMode
     * @see minBarWidth
     * @see maxBarWidth
     * @note added in QGIS 2.9
     */
    QgsScaleBarSettings::SegmentSizeMode segmentSizeMode() const;

    /** Sets the size mode for scale bar segments.
     * @param mode size mode
     * @see segmentSizeMode
     * @see setMinBarWidth
     * @see setMaxBarWidth
     * @note added in QGIS 2.9
     */
    void setSegmentSizeMode( QgsScaleBarSettings::SegmentSizeMode mode );

    /** Returns the minimum size (in millimeters) for scale bar segments. This
     * property is only effective if the @link segmentSizeMode @endlink is set
     * to @link SegmentSizeFitWidth @endlink.
     * @see segmentSizeMode
     * @see setMinBarWidth
     * @see maxBarWidth
     * @note added in QGIS 2.9
     */
    double minBarWidth() const;

    /** Sets the minimum size (in millimeters) for scale bar segments. This
     * property is only effective if the @link segmentSizeMode @endlink is set
     * to @link SegmentSizeFitWidth @endlink.
     * @param minWidth minimum width in millimeters
     * @see minBarWidth
     * @see setMaxBarWidth
     * @see setSegmentSizeMode
     * @note added in QGIS 2.9
     */
    void setMinBarWidth( double minWidth );

    /** Returns the maximum size (in millimeters) for scale bar segments. This
     * property is only effective if the @link segmentSizeMode @endlink is set
     * to @link SegmentSizeFitWidth @endlink.
     * @see segmentSizeMode
     * @see setMaxBarWidth
     * @see minBarWidth
     * @note added in QGIS 2.9
     */
    double maxBarWidth() const;

    /** Sets the maximum size (in millimeters) for scale bar segments. This
     * property is only effective if the @link segmentSizeMode @endlink is set
     * to @link SegmentSizeFitWidth @endlink.
     * @param maxWidth maximum width in millimeters
     * @see minBarWidth
     * @see setMaxBarWidth
     * @see setSegmentSizeMode
     * @note added in QGIS 2.9
     */
    void setMaxBarWidth( double maxWidth );

    double numMapUnitsPerScaleBarUnit() const;
    void setNumMapUnitsPerScaleBarUnit( double d );

    QString unitLabeling() const;
    void setUnitLabeling( const QString &label );

    QFont font() const;
    void setFont( const QFont &font );

    /** Returns the color used for drawing text in the scalebar.
     * @returns font color for scalebar.
     * @see setFontColor
     * @see font
     */
    QColor fontColor() const;

    /** Sets the color used for drawing text in the scalebar.
     * @param c font color for scalebar.
     * @see fontColor
     * @see setFont
     */
    void setFontColor( const QColor &c );

    /** Returns the color used for fills in the scalebar.
     * @see setFillColor()
     * @see fillColor2()
     * @note added in QGIS 3.0
     */
    QColor fillColor() const;

    /** Sets the color used for fills in the scalebar.
     * @see fillColor()
     * @see setFillColor2()
     * @note added in QGIS 3.0
     */
    void setFillColor( const QColor &color );

    /** Returns the secondary color used for fills in the scalebar.
     * @see setFillColor2()
     * @see fillColor()
     * @note added in QGIS 3.0
     */
    QColor fillColor2() const;

    /** Sets the secondary color used for fills in the scalebar.
     * @see fillColor2()
     * @see setFillColor2()
     * @note added in QGIS 3.0
     */
    void setFillColor2( const QColor &color );

    /** Returns the color used for lines in the scalebar.
     * @see setLineColor()
     * @note added in QGIS 3.0
     */
    QColor lineColor() const;

    /** Sets the color used for lines in the scalebar.
     * @see lineColor()
     * @note added in QGIS 3.0
     */
    void setLineColor( const QColor &color );

    /** Returns the line width in millimeters for lines in the scalebar.
     * @see setLineWidth()
     * @note added in QGIS 3.0
     */
    double lineWidth() const;

    /** Sets the line width in millimeters for lines in the scalebar.
     * @see lineWidth()
     * @note added in QGIS 3.0
     */
    void setLineWidth( double width );

    /** Returns the pen used for drawing the scalebar.
     * @returns QPen used for drawing the scalebar outlines.
     * @see setPen
     * @see brush
     */
    QPen pen() const;

    /** Returns the primary brush for the scalebar.
     * @returns QBrush used for filling the scalebar
     * @see setBrush
     * @see brush2
     * @see pen
     */
    QBrush brush() const;

    /** Returns the secondary brush for the scalebar. This is used for alternating color style scalebars, such
     * as single and double box styles.
     * @returns QBrush used for secondary color areas
     * @see setBrush2
     * @see brush
     */
    QBrush brush2() const;

    double height() const;
    void setHeight( double h );

    void setComposerMap( QgsComposerMap *map );
    QgsComposerMap *composerMap();

    double labelBarSpace() const;
    void setLabelBarSpace( double space );

    double boxContentSpace() const;
    void setBoxContentSpace( double space );

    /** Left / Middle/ Right */
    QgsScaleBarSettings::Alignment alignment() const;

    void setAlignment( QgsScaleBarSettings::Alignment a );

    QgsUnitTypes::DistanceUnit units() const;

    void setUnits( QgsUnitTypes::DistanceUnit u );

    /** Returns the join style used for drawing lines in the scalebar
     * @returns Join style for lines
     * @note introduced in 2.3
     * @see setLineJoinStyle
     */
    Qt::PenJoinStyle lineJoinStyle() const;
    /** Sets join style used when drawing the lines in the scalebar
     * @param style Join style for lines
     * @returns nothing
     * @note introduced in 2.3
     * @see lineJoinStyle
     */
    void setLineJoinStyle( Qt::PenJoinStyle style );

    /** Returns the cap style used for drawing lines in the scalebar
     * @returns Cap style for lines
     * @note introduced in 2.3
     * @see setLineCapStyle
     */
    Qt::PenCapStyle lineCapStyle() const;
    /** Sets cap style used when drawing the lines in the scalebar
     * @param style Cap style for lines
     * @returns nothing
     * @note introduced in 2.3
     * @see lineCapStyle
     */
    void setLineCapStyle( Qt::PenCapStyle style );

    /** Apply default settings*/
    void applyDefaultSettings();
    /** Apply default size (scale bar 1/5 of map item width) */
    void applyDefaultSize( QgsUnitTypes::DistanceUnit u = QgsUnitTypes::DistanceMeters );

    /** Sets style by name
     @param styleName (untranslated) style name. Possibilities are: 'Single Box', 'Double Box', 'Line Ticks Middle', 'Line Ticks Down', 'Line Ticks Up', 'Numeric'*/
    void setStyle( const QString &styleName );

    /** Returns style name*/
    QString style() const;

    /** Sets box size suitable to content*/
    void adjustBoxSize();

    /** Adjusts box size and calls QgsComposerItem::update()*/
    void update();

    /** Stores state in Dom element
     * @param elem is Dom element corresponding to 'Composer' tag
     * @param doc Dom document
     */
    bool writeXml( QDomElement &elem, QDomDocument &doc ) const;

    /** Sets state from Dom document
     * @param itemElem is Dom node corresponding to item tag
     * @param doc is Dom document
     */
    bool readXml( const QDomElement &itemElem, const QDomDocument &doc );

    /** Moves scalebar position to the left / right depending on alignment and change in item width*/
    void correctXPositionAlignment( double width, double widthAfter );

    //overridden to apply minimum size
    void setSceneRect( const QRectF &rectangle );

  public slots:
    void updateSegmentSize();
    /** Sets mCompositionMap to 0 if the map is deleted*/
    void invalidateCurrentMap();
    virtual void refreshDataDefinedProperty( const QgsComposerObject::DataDefinedProperty property = QgsComposerObject::AllProperties, const QgsExpressionContext *context = 0 );

};