Utils.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 QtUtils.h
   
  \brief This file contains utility functions for dealing with Qt controls.
 */

#ifndef __TERRALIB_QTWIDGETS_INTERNAL_UTILS_H
#define __TERRALIB_QTWIDGETS_INTERNAL_UTILS_H

// TerraLib
#include "../../color/RGBAColor.h"
#include "../../geometry/Enums.h"
#include "../../maptools/AbstractLayer.h"
#include "../../maptools/Enums.h"
#include "../../maptools/MapDisplay.h"
#include "Config.h"
#include "Globals.h"

// Qt
#include <QColor>
#include <QModelIndex>
#include <QObject>
#include <QPixmap>
#include <QString>
#include <QHeaderView>

// STL
#include <string>

// Forward declarations
class QAbstractItemModel;
class QAction;
class QActionGroup;
class QClipboard;
class QImage;
class QMenu;
class QMenuBar;
class QTreeWidgetItem;

namespace te
{
  namespace map
  {
    class Canvas;
  }

  namespace qt
  {
    namespace widgets
    {
      class LayerItemView;

      /*!
        \brief It sets the check state for the children of a item.
      */
      TEQTWIDGETSEXPORT void SetChildrenCheckState(QTreeWidgetItem* item, int column, Qt::CheckState state);

      /*!
        \brief It returns the file format as a NULL terminated string.

        \return The file format as a NULL terminated string.
      */
      inline const char* GetFormat(te::map::ImageType t)
      {
        switch(t)
        {
          case te::map::PNG:
            return Globals::sm_pngFmt;

          case te::map::JPEG:
            return Globals::sm_jpegFmt;

          case te::map::GIF:
            return Globals::sm_gifFmt;

          case te::map::BMP:
            return Globals::sm_bmpFmt;

          case te::map::XPM:
            return Globals::sm_xpmFmt;

          case te::map::XBM:
            return Globals::sm_xbmFmt;

          default:
            return Globals::sm_unknownFmt;
        };
      }

      /*!
        \brief It creates a QImage from an RGBA color array.

        \param img    Image - a square matrix of int's where each position corresponds to a RGBA color.
        \param width  The image width.
        \param height The image height.

        \return A pointer to a QImage.

        \note The caller of this method will take the ownership of the returned pointer.
      */
      TEQTWIDGETSEXPORT QImage* GetImage(te::color::RGBAColor** img, int width, int height);

      /*!
        \brief It creates a RGBA color array from a QImage.

        \param img QImage that will be converted.

        \return Image - a square matrix of int's where each position corresponds to a RGBA color.

        \note The caller of this method will take the ownership of the returned pointer.
      */
      TEQTWIDGETSEXPORT te::color::RGBAColor** GetImage(QImage* img);

      /*!
        \brief Finds a menu item in the \a mnu object.

        Use this function to find menus and submenus. There is a sintaxe that is for required sub-menus. Use the names separated by \".\" character,
        e.g to return a menu named \"Layers\" inside another menu named \"Add\" calls this function using "Add.Layers" as the value of the 
        \a mnuText argument.

        \note Pay attention on the translations.

        \param mnuText Name of the QMenu searched.

        \param mnu The menu where the submenu must be searched.

        \return The pointer to the QMenu object or NULL if it do not exists.
      */
      TEQTWIDGETSEXPORT QMenu* FindMenu(const QString& mnuText, QMenu* mnu);

      /*!
        \overload QMenu* findMenu(const QString& mnuText, QMenuBar* bar)

        The difference for the above function is that this will search in all QMenu objects contained in the \a bar.
      */
      TEQTWIDGETSEXPORT QMenu* FindMenu(const QString& mnuText, QMenuBar* bar);

      /*!
        \brief Gets a menu or submenu contained in the \a mnu object.

        This function searches by the menu exactly as the FindMenu function. The difference is that if the menu do not exists,
        this function will create it, in all levels that may be required. Use the syntax described above to the search / create the submenus desired.

        \param mnuText Name of the menu. (This will be used as texts of the menus.)

        \param mnu The menu that will used in search.

        \return A pointer to a QMenu object.
      */
      TEQTWIDGETSEXPORT QMenu* GetMenu(const QString& mnuText, QMenu* mnu);

      /*!
        \overload QMenu* getMenu(const QString& mnuText, QMenuBar* bar)

        The difference for the above function is that it will search in all QMenu objects contained in the \a bar.
      */
      TEQTWIDGETSEXPORT QMenu* GetMenu(const QString& mnuText, QMenuBar* bar);

      /*!
        \brief

        \param
        \param

        \return
      */
      TEQTWIDGETSEXPORT QAction* FindAction(const QString& actText, QMenu* mnu);

      /*!
        \brief

        \param
        \param

        \return
      */
      TEQTWIDGETSEXPORT QAction* FindAction(const QString& actText, QMenuBar* mnuBar);

      /*!
        \brief

        \param
        \param

        \return
      */
      TEQTWIDGETSEXPORT QActionGroup* FindActionGroup(const QString& actGroupText, QMenu* mnu);

      /*!
        \brief

        \param
        \param

        \return
      */
      TEQTWIDGETSEXPORT QActionGroup* FindActionGroup(const QString& actText, QMenuBar* mnuBar);

       /*!
        \brief It converts a Qt Color to TerraLib Color.

        \param color The Qt Color that will be converted.
      */
      TEQTWIDGETSEXPORT te::color::RGBAColor Convert2TerraLib(const QColor& color);

      /*!
        \brief It converts a TerraLib Color to Qt Color.

        \param color The TerraLib Color that will be converted.
      */
      TEQTWIDGETSEXPORT QColor Convert2Qt(const te::color::RGBAColor& color);

      /*!
        \brief It configs (i.e. prepares) the given canvas to draw polygons.

        \param canvas The canvas that will be configured. Do not pass NULL!
        \param fillColor The color that will be used to fill the polygons.
        \param contourColor The color that will be used to contour the polygons.
        \param contourWidth The width that will be used to contour the polygons.
      */
      TEQTWIDGETSEXPORT void Config2DrawPolygons(te::map::Canvas* canvas, const QColor& fillColor, const QColor& contourColor, const std::size_t& contourWidth = 1);

      /*!
        \brief It configs (i.e. prepares) the given canvas to draw lines.

        \param canvas The canvas that will be configured. Do not pass NULL!
        \param color The color that will be used to draw the lines.
        \param width The width that will be used to draw the lines.
      */
      TEQTWIDGETSEXPORT void Config2DrawLines(te::map::Canvas* canvas, const QColor& color, const std::size_t& width = 1);

      /*!
        \brief It configs (i.e. prepares) the given canvas to draw points.

        \param canvas The canvas that will be configured. Do not pass NULL!
        \param color The color that will be used to draw the points.
        \param width The width that will be used to draw the points.
      */
      TEQTWIDGETSEXPORT void Config2DrawPoints(te::map::Canvas* canvas, const QColor& color, const std::size_t& width = 1);

       /*!
        \brief It configs (i.e. prepares) the given canvas to draw points.

        \param canvas The canvas that will be configured. Do not pass NULL!
        \param markName The mark name that will be used to draw the points.
        \param size The size that will be used to draw the points.
        \param fillColor The color that will be used to fill the mark.
        \param contourColor The color that will be used to contour the mark.
        \param contourWidth The width that will be used to contour the mark.
      */
      TEQTWIDGETSEXPORT void Config2DrawPoints(te::map::Canvas* canvas, const QString& markName, const std::size_t& size,
                                               const QColor& fillColor, const QColor& contourColor, const std::size_t& contourWidth = 1);

      /*!
        \brief It configs (i.e. prepares) the given canvas to draw a layer selection.

        \param canvas The canvas that will be configured. Do not pass NULL!
        \param selectionColor The color that will be used to draw the selection.
        \param type The geometry type that will be drawn.
      */
      TEQTWIDGETSEXPORT void Config2DrawLayerSelection(te::map::Canvas* canvas, const QColor& selectionColor, const te::gm::GeomType& type);

      /*!
        \brief It creates a pixmap to use as icon (to be used as legend icon).

        \param size         The height and width for the pixmap.
        \param penColor     The color that will be used to set the pen.
        \param brushColor   The color that will be used to set the brush.
        \param contourSize  The countour size.
      */
      TEQTWIDGETSEXPORT QPixmap CreatePixmapIcon(const int& size, const QColor& penColor, const QColor& brushColor, const int& contourSize);

      /*!
        \brief Save last used path in QSettings.

        \param path The path to last used file.

        \param typeFile The type of file opened. Actually we assume three values: "vector", "raster", "database". Any other value may be not used in the system. 

        \note The params are case sensitive. It means that a "Vector" value for the argument \a typeFile is unkowned by application.
      */
      TEQTWIDGETSEXPORT void AddFilePathToSettings(const QString& path, const QString& typeFile);

      /*!
        \brief Returns the value of the last saved file path for the \a typeFile required.

        \param typeFile The type of file opened. Actually we assume three values: "vector", "raster", "database". Any other value may be not used in the system.

        \return The path if encountered or a null QString.
      */
      TEQTWIDGETSEXPORT QString GetFilePathFromSettings(const QString& typeFile);

      /*!
        \brief It converts the given string to an appropriate character encoding.

        \param text      The source string.
        \param encoding  The type of the character encoding of the string to be converted to an appropriate charset.

        \return The converted string.
      */
      TEQTWIDGETSEXPORT QString Convert2Qt(const std::string& text, te::core::EncodingType encoding);
      
      /*!
        \brief Returns a disk raster file selection filter base on current supported formats.

        \param creationSupport Return only those extensions with dataset creation support.

        \return Returns a disk raster file selection filter base on current supported formats.
      */
      TEQTWIDGETSEXPORT QString GetDiskRasterFileSelFilter( const bool creationSupport );

      TEQTWIDGETSEXPORT void GetDiskRasterFileSelFilter(std::vector<std::string>& filterVec);

      /*!
        \brief Returns a disk vector file selection filter base on current supported formats.

        \param creationSupport Return only those extensions with dataset creation support.

        \return Returns a disk vector file selection filter base on current supported formats.
      */
      TEQTWIDGETSEXPORT QString GetDiskVectorFileSelFilter();

      TEQTWIDGETSEXPORT void GetDiskVectorFileSelFilter(std::vector<std::string>& filterVec);

      TEQTWIDGETSEXPORT std::list<te::map::AbstractLayerPtr> GetSelectedLayersOnly(te::qt::widgets::LayerItemView* view, const bool getFolder = false);
      
      TEQTWIDGETSEXPORT void GetValidLayers(QAbstractItemModel* model, const QModelIndex& parent, std::vector<te::map::AbstractLayerPtr>& layers);

      TEQTWIDGETSEXPORT void GetValidLayers(QAbstractItemModel* model, const QModelIndex& parent, std::list<te::map::AbstractLayerPtr>& layers);

      TEQTWIDGETSEXPORT void GetChangedAndVisibleLayers(const QModelIndexList& idxs, std::list<te::map::AbstractLayerPtr>& layers);


      /*!
        \brief Verify if the SRID from informed Layers are valids to execute the operation.

        \param firstSRID    The SRID from the first layer.
        \param secondSRID   The SRID from the second layer.
        \param msg          Fiils this parameter in case of invalid SRIDs.

        return Resturns a bool value. If false, it fills the message parameter.
      */
      TEQTWIDGETSEXPORT bool isValidSRIDs(const int& firstSRID, const int& secondSRID, std::string& msg);

      /*!
       * \brief Returns the size in pixels.
       *
       * \param device Dots per inch.
       *
       * \param mm Measure in millimeters.
       *
       * \param printer True if the drawing is on a printer.
       *
       * \return (\a mm * Physical dpi ) / 25,4mm (inch)
       */
      TEQTWIDGETSEXPORT int MillimetersToPixels(const QPaintDevice* device, const double& mm, const bool& printer);

      /*!
       * \brief Returns a transparent pixmap of size \a s.
       *
       * \param s Size in pixels.
       *
       * \param c Background color.
       *
       * \return A transparent pixmap of size \a s.
       */
      TEQTWIDGETSEXPORT QPixmap* GetCleanImage(const QSize& s, const QColor& c);

       /*!
       \brief Returns the user data location path.

       \return Returns the user data location path.
     */
      TEQTWIDGETSEXPORT QString GetUserDataLocation();

      /** @name DMS Functions
        *  Utilities functions section for DMS treatment.
        */
      //@{

      QString ConvertDecimalToDegree(const double& value, int precision);

      /*!
       * \brief Returns the value as a formatted string.
       *
       * \param d Degrees.
       *
       * \param m Minutes.
       *
       * \param s Seconds.
       *
       * \return A string formatted as a degrees-minutes-seconds value.
       */
      TEQTWIDGETSEXPORT QString GetDMSAsString(const int& d, const int& m, const int& s);

      /*!
       * \brief Transforms a degree-minute-second value into a decimal-degree value.
       *
       * \param d Degrees.
       *
       * \param m Minutes.
       *
       * \param s Seconds.
       *
       * \return The decimal-degree value.
       */
      TEQTWIDGETSEXPORT double DMS2DD(const int& d, const int& m, const int& s);

      /*!
       * \brief Transforms a decimal-degree value in a degree-minute-second formatted string.
       *
       * \param value Value in decimal-degrees.
       *
       * \return The degree-minute-second representing the given \a value.
       */
      TEQTWIDGETSEXPORT QString DD2DMS(const double& value);

      /*!
       * \brief Format coord precision value to show value.
       *
       * \param value Value in current srid.
       *
       * \return The string value with right precision.
       */
      TEQTWIDGETSEXPORT QString FormatCoord(const double& value, te::map::MapDisplay* display);

      /*!
       * \brief Returns the QClipboard object
       *
       * \return Returns the QClipboard object
       */
      TEQTWIDGETSEXPORT QClipboard* GetClipboard();

      /*!
       * \brief Returns the QClipboard object
       *
       * \return Returns the QClipboard object
       */
      TEQTWIDGETSEXPORT void SetHeaderViewResizeMode(QHeaderView* header, QHeaderView::ResizeMode mode);

      //@}

      /*!
       * \brief Converts a std::string to a QString
       *
       * \return The converted QString
       */
      TEQTWIDGETSEXPORT QString Convert2QString(const std::string& stdString);

      /*!
       * \brief Converts a QString to a std::string
       *
       * \return The converted std::string
       */
      TEQTWIDGETSEXPORT std::string Convert2StdString(const QString& qString);



    } // end namespace widgets
  }   // end namespace qt
}     // end namespace te

#endif  // __TERRALIB_QTWIDGETS_INTERNAL_UTILS_H