ScaleWidget.h

Go to the documentation of this file.

/*  Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.

This file is part of the TerraLib - a Framework for building GIS enabled applications.

TerraLib is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License,
or (at your option) any later version.

TerraLib is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with TerraLib. See COPYING. If not, write to
TerraLib Team at <terralib-team@terralib.org>.
*/

/*!
\file terralib/qt/widgets/canvas/ScaleWidget.h

\brief Contains an implementation of a graphic scale.
*/

#ifndef __TERRALIB_QT_WIDGETS_INTERNAL_SCALEWIDGET_H
#define __TERRALIB_QT_WIDGETS_INTERNAL_SCALEWIDGET_H

//TerraLib
#include "../Config.h"

// Qt
#include <QFrame>

// STL
#include <vector>

// Forward Declarations
class QPixmap;
class QFont;

/*!
\brief Returns icons and the respective names for the types of rulers that can be used to present the graphic scale.
\param[out] icons Generated icons.
\param[out] typesNames Generated names.
\param device The device being used.
\param color The color of the ruler.
*/
void GetScalesIcons(QMap<int, QIcon>& icons, QStringList& typesNames, const QPaintDevice* device, const QColor& color);

namespace te
{
  namespace qt
  {
    namespace widgets
    {
      // Forward declaration
      class MapDisplay;

      /*!
      \class ScaleWidget

      \brief A widget that shows the graphic scale associated with a display.

      The widget shows the graphic scale being used by some display. You can change some attributes for a customized presentation. Divided in sections you can set the following attributes:
      
      <ol>
        <li>The unit to be showed.</li>
        <li>Header:
          <ul>
            <li>Font.</li>
            <li>Color.</li>
            <li>Visibility of the intermediary values.</li>
          </ul>
        </li>
        <li>Ruler:
          <ul>
            <li>Color.</li>
            <li>Units per interval.</li>
            <li>Number of intervals.</li>
            <li>Height in millimeters.</li>
            <li>Type of ruler for presentation pourposes.</li>
          </ul>
        </li>
        <li>Footer:
          <ul>
            <li>Font.</li>
            <li>Color.</li>
            <li>Visibility</li>
          </ul>
        </li>
      </ol>

      The object is divided into three sections: header, ruler and footer. The header shows the values of each interval on the ruler. Ruler is the picture of the ruler itself, 
      and the footer shows the numeric scale showing the scale factor and the unit of measure being used.
      
      \ingroup widgets
      */
      class TEQTWIDGETSEXPORT ScaleWidget : public QFrame
      {
        Q_OBJECT

      public:
        /*!
        \enum ScaleTypes
        \brief Defines the different types of rulers we can use to present the graphical scale.
        */
        enum ScaleTypes
        {
          RULER,                      //!< As a ruler.
          DASHED,                     //!< Alternated rectangles and alternated colors, beginning with a white one.
          DASHED_BEGIN_BLACK,         //!< Alternated rectangles and alternated colors, beginning with a colored one.
          DOUBLE_DASHED,              //!< Alternated rectangles and alternated colors, beginning with a white one, whith two rulers.
          DOUBLE_DASHED_BEGIN_BLACK,  //!< Alternated rectangles and alternated colors, beginning with a colored one, whith two rulers.
          CUSTOM                      //!< Customized.
        };

        /** @name Constructor and destructor methods.
        *  Methods related to instantiation and destruction.
        */
        //@{

        /*!
        \brief Constructor.
        \param parent The display over what the scale will reflect.
        \param interactive Turn on / off interaction mode. If /a true you will can change the scale position on the display.
        */
        ScaleWidget(MapDisplay* parent, const bool& interactive=false);

        /*!
        \brief Destuctor.
        */
        ~ScaleWidget();
        //@}

        /** @name Public methods
        *  Methods to access the internal attributes of the class.
        */
        //@{

        /*!
        \brief Returns the value of the interaction mode.
        \return Value of the interaction mode.
        */
        bool getInteractionHandle() const;

        /*!
        \brief Returns the value of the color of the header.
        \return Value of the color of the header.
        */
        QColor getHeaderColor() const;

        /*!
        \brief Returns the value of the color of the ruler.
        \return Value of the color of the ruler.
        */
        QColor getRulerColor() const;

        /*!
        \brief Returns the value of the color of the footer.
        \return Value of the color of the footer.
        */
        QColor getFooterColor() const;

        /*!
        \brief Returns the value of the font of the header.
        \return Value of the font of the header.
        */
        QFont getHeaderFont() const;

        /*!
        \brief Returns the value of the font of the footer.
        \return Value of the font of the footer.
        */
        QFont getFooterFont() const;

        /*!
        \brief Returns the unit being used to present the graphic scale.
        \return Unit being used to present the graphic scale.
        */
        QString getUnit() const;

        /*!
        \brief Returns the ruler type being used.
        \return Ruler type being used.
        */
        int getScaleType() const;

        /*!
        \brief Returns the visibility of the footer section.
        \return Visibility of the footer section.
        */
        bool getNumericScaleIsVisible() const;

        /*!
        \brief Returns the visibilty of the intermediary values on the header section.
        \return Visibilty of the intermediary values on the header section.
        */
        bool getAllHeaderIsVisible() const;

        /*!
        \brief Returns the number of units used in each gap.
        \return Number of units used in each gap.
        */
        int getUnitsPerGap() const;

        /*!
        \brief Returns the lenght of the ruler in millimeters.
        \return Lenght of the ruler in millimeters.
        */
        int getRulerHeightMM() const;

        /*!
        \brief Returns the number of intervals being used by ruler.
        \return Number of intervals being used by ruler.
        */
        int getNumberOfIntervals() const;

        /*!
        \brief Changes the current position of the widget, centralizing it in the display.
        */
        void updateScalePosition();

        /*!
        \brief Sets the unit using SRID.
        \param SRID The display SRID.
        */
        void setUnit(const int& SRID);
        //@}

      public slots:

      /** @name Public slots.
      *  Methods to update the internal attributes of the class, using the signal-slot mechanism of QT.
      */
      //@{

      /*!
        \brief Enable / disable the interaction mode.

        If enabled the user can change the scale position on the MapDisplay.

        \param state True for enabling of the interaction mode, false to disable it.
        */
        void setInteractionHandle(const bool& state);

        /*!
        \brief Updates the scale values.

        This method must be called when the visualized area changes on the display, to the ScaleWidget be adjusted to the new visualized area. 
        */
        void updateScaleFactor();

        /*!
        \brief Changes the color of the header.
        \param color The new color to be used.
        */
        void setHeaderColor(const QColor& color);

        /*!
        \brief Changes the color of the ruler.
        \param color The new color to be used.
        */
        void setRulerColor(const QColor& color);

        /*!
        \brief Changes the color of the footer.
        \param color The new color to be used.
        */
        void setFooterColor(const QColor& color);

        /*!
        \brief Changes the color of the background.

        The initial background color is set to transparent.

        \param color The new color to be used.
        */
        void setBackgroundColor(const QColor& color);

        /*!
        \brief Changes the font of the header.
        \param font The new font to be used.
        */
        void setHeaderFont(const QFont& font);

        /*!
        \brief Changes the font of the footer.
        \param font The new font to be used.
        */
        void setFooterFont(const QFont& font);

        /*!
        \brief Sets the unit of measure to be used by the graphic scale.

        Available units of measure:

        <ul>
          <li>Meters.</li>
          <li>Kilometers.</li>
          <li>Feet.</li>
          <li>Degrees.</li>
        </ul>

        \param unit The new unit of measure to be used.
        */
        void setUnit(const QString& unit);

        /*!
        \brief Sets the type of ruler to be presented.

        See the definition of \a ScaleTypes enumeration to see details.

        \param type The new type of ruler to be presented.
        */
        void setScaleType(const int& type);

        /*!
        \brief Enable / disable the visibility of the footer or the \a numeric \a scale.
        \param visible The new visibility of the footer section.
        */
        void setNumericScaleVisble(const bool& visible);

        /*!
        \brief Enable / disable intermediary values of the header.

        The first and last elements are alaways visible. But the intermediary values can be hidden / showed.

        \param visible \a True if the intermediary values must be showed and \a false otherwise.
        */
        void setAllHeaderVisible(const bool& visible);

        /*!
        \brief Changes the number of units to used per interval.

        \ An unit is a value greater then measure corresponding to 1cm that is a better value to be presented. For example, if the display shows a data in a scale 1 : 2924mt, in the ruler
        we should use intervals of 3000mt, then each unit represents 3000mts.

        \param units Number of units to be used in each interval.
        */
        void setUnitsPerGap(const int& units);

        /*!
        \brief Updates the heightness of the ruler.
        \param hMM The new height of the ruler in millimeters.
        \note The \a hMM parameter must be a value of a measure in millimeters.
        */
        void setRulerHeightMM(const int& hMM);

        /*!
        \brief Updates the number of intervals of the ruler.
        \param v Number of intervals of the ruler.
        */
        void setNumberOfIntervals(const int& v);
        //@}

      signals:

        /** @name Signals
        *  Signals emmited by the widget.
        */
        //@{

        /*!
         * Signal emmited when the widget is about to be closed.
         */
        void aboutToBeclosed();
        //@}

      protected:

        /** @name Protected methods
        *  Methods used internally by the object.
        */
        //@{

        /*!
        \brief Recalculates and redraw the graphic scale based on the values of its internal attributes.
        */
        void redoWidget();

        /*!
        \brief Reimplementation of the QFrame method. 
        \param event The event generated.
        */
        void paintEvent(QPaintEvent* event);

        /*!
         * \brief Reimplementation of the QFrame method.
         *
         * \param event The event generated.
         */
        void closeEvent(QCloseEvent *event);
        //@}

        QPixmap* m_bckGround;             //!< Background pixmap.
        QFont m_footerFont;               //!< Font of the footer section.
        bool m_showNumericScale;          //!< Flag for enabling / disabling visibility of the footer section.
        double m_factor;                  //!< Factor of scaling being used. 
        QString m_unit;                   //!< Unit of measure being used.
        std::vector<double> m_intervals;  //!< Values of the intervals in millimeters.
        std::vector<double> m_values;     //!< Values of the intervals in the selected unit of measure.
        int m_numberOfIntervals;          //!< Number of intervals of the ruler.
        ScaleTypes m_type;                //!< Type of the ruler to be presented.
        QColor m_rulerColor;              //!< Color of the ruler section.
        QColor m_bckGrd;                  //!< Background color.
        bool m_interactionEnabled;        //!< Flag for enabling / disabling the interactive mode.
        MapDisplay* m_display;            //!< Pointer to the display where to present the widget.
        QColor m_headerColor;             //!< Color of the header section.
        QFont m_headerFont;               //!< Font of the header section.
        bool m_headerAllVisible;          //!< Flag do enabling / disabling of the intermediary values of the header.
        int m_unitsPerGap;                //!< Number of units to be used by each interval.
        QColor m_footerColor;             //!< Color of the footer section.
        int m_rulerHeightMM;              //!< Height of the ruler in millimeters.
      };
    }
  }
}

#endif //__TERRALIB_QT_WIDGETS_INTERNAL_SCALEWIDGET_H