Quantum GIS API Documentation  1.7.4
src/core/qgspallabeling.h
Go to the documentation of this file.
00001 /***************************************************************************
00002   qgspallabeling.h
00003   Smart labeling for vector layers
00004   -------------------
00005          begin                : June 2009
00006          copyright            : (C) Martin Dobias
00007          email                : wonder.sk at gmail.com
00008 
00009  ***************************************************************************
00010  *                                                                         *
00011  *   This program is free software; you can redistribute it and/or modify  *
00012  *   it under the terms of the GNU General Public License as published by  *
00013  *   the Free Software Foundation; either version 2 of the License, or     *
00014  *   (at your option) any later version.                                   *
00015  *                                                                         *
00016  ***************************************************************************/
00017 
00018 //Note: although this file is in the core library, it is not part of the stable API
00019 //and might change at any time!
00020 
00021 #ifndef QGSPALLABELING_H
00022 #define QGSPALLABELING_H
00023 
00024 class QFontMetricsF;
00025 class QPainter;
00026 class QgsGeometry;
00027 class QgsMapRenderer;
00028 class QgsRectangle;
00029 class QgsCoordinateTransform;
00030 class QgsLabelSearchTree;
00031 struct QgsDiagramLayerSettings;
00032 
00033 #include <QString>
00034 #include <QFont>
00035 #include <QColor>
00036 #include <QHash>
00037 #include <QList>
00038 #include <QRectF>
00039 
00040 namespace pal
00041 {
00042   class Pal;
00043   class Layer;
00044   class LabelPosition;
00045 }
00046 
00047 class QgsMapToPixel;
00048 class QgsFeature;
00049 #include "qgspoint.h"
00050 
00051 #include "qgsmaprenderer.h" // definition of QgsLabelingEngineInterface
00052 
00053 class QgsPalGeometry;
00054 class QgsVectorLayer;
00055 
00056 class CORE_EXPORT QgsPalLayerSettings
00057 {
00058   public:
00059     QgsPalLayerSettings();
00060     QgsPalLayerSettings( const QgsPalLayerSettings& s );
00061     ~QgsPalLayerSettings();
00062 
00063     enum Placement
00064     {
00065       AroundPoint, // Point / Polygon
00066       OverPoint, // Point / Polygon
00067       Line, // Line / Polygon
00068       Curved, // Line
00069       Horizontal, // Polygon
00070       Free // Polygon
00071     };
00072 
00073     enum LinePlacementFlags
00074     {
00075       OnLine    = 1,
00076       AboveLine = 2,
00077       BelowLine = 4,
00078       MapOrientation = 8
00079     };
00080 
00081     enum DataDefinedProperties
00082     {
00083       Size = 0,
00084       Bold,
00085       Italic,
00086       Underline,
00087       Color,
00088       Strikeout,
00089       Family,
00090       BufferSize,
00091       BufferColor,
00092       PositionX, //x-coordinate data defined label position
00093       PositionY, //y-coordinate data defined label position
00094       Hali, //horizontal alignment for data defined label position (Left, Center, Right)
00095       Vali, //vertical alignment for data defined label position (Bottom, Base, Half, Cap, Top)
00096       LabelDistance,
00097       Rotation //data defined rotation (only useful in connection with data defined position)
00098     };
00099 
00100     QString fieldName;
00101     Placement placement;
00102     unsigned int placementFlags;
00103     QFont textFont;
00104     QColor textColor;
00105     bool enabled;
00106     int priority; // 0 = low, 10 = high
00107     bool obstacle; // whether it's an obstacle
00108     double dist; // distance from the feature (in mm)
00109     double vectorScaleFactor; //scale factor painter units->pixels
00110     double rasterCompressFactor; //pixel resolution scale factor
00111     int scaleMin, scaleMax; // disabled if both are zero
00112     double bufferSize; //buffer size (in mm)
00113     QColor bufferColor;
00114     bool labelPerPart; // whether to label every feature's part or only the biggest one
00115     bool mergeLines;
00116     bool multiLineLabels; //draw labels on multiple lines if they contain '\n'
00117     double minFeatureSize; // minimum feature size to be labelled (in mm)
00118     // Adds '<' or '>' to the label string pointing to the direction of the line / polygon ring
00119     // Works only if Placement == Line
00120     bool addDirectionSymbol;
00121     bool fontSizeInMapUnits; //true if font size is in map units (otherwise in points)
00122     bool distInMapUnits; //true if distance is in map units (otherwise in mm)
00123 
00124     // called from register feature hook
00125     void calculateLabelSize( const QFontMetricsF* fm, QString text, double& labelX, double& labelY );
00126 
00127     // implementation of register feature hook
00128     void registerFeature( QgsFeature& f, const QgsRenderContext& context );
00129 
00130     void readFromLayer( QgsVectorLayer* layer );
00131     void writeToLayer( QgsVectorLayer* layer );
00132 
00134     void setDataDefinedProperty( DataDefinedProperties p, int attributeIndex );
00136     void removeDataDefinedProperty( DataDefinedProperties p );
00137 
00138     // temporary stuff: set when layer gets prepared
00139     pal::Layer* palLayer;
00140     int fieldIndex;
00141     QFontMetricsF* fontMetrics;
00142     const QgsMapToPixel* xform;
00143     const QgsCoordinateTransform* ct;
00144     QgsPoint ptZero, ptOne;
00145     QList<QgsPalGeometry*> geometries;
00146 
00148     QMap< DataDefinedProperties, int > dataDefinedProperties;
00149 
00154     int sizeToPixel( double size, const QgsRenderContext& c ) const;
00155 
00156   private:
00159     bool checkMinimumSizeMM( const QgsRenderContext& ct, QgsGeometry* geom, double minSize ) const;
00160 };
00161 
00162 class CORE_EXPORT QgsLabelCandidate
00163 {
00164   public:
00165     QgsLabelCandidate( QRectF r, double c ): rect( r ), cost( c ) {}
00166 
00167     QRectF rect;
00168     double cost;
00169 };
00170 
00171 class CORE_EXPORT QgsPalLabeling : public QgsLabelingEngineInterface
00172 {
00173   public:
00174     QgsPalLabeling();
00175     ~QgsPalLabeling();
00176 
00177     QgsPalLayerSettings& layer( const QString& layerName );
00178 
00179     void numCandidatePositions( int& candPoint, int& candLine, int& candPolygon );
00180     void setNumCandidatePositions( int candPoint, int candLine, int candPolygon );
00181 
00182     enum Search { Chain, Popmusic_Tabu, Popmusic_Chain, Popmusic_Tabu_Chain, Falp };
00183 
00184     void setSearchMethod( Search s );
00185     Search searchMethod() const;
00186 
00187     bool isShowingCandidates() const { return mShowingCandidates; }
00188     void setShowingCandidates( bool showing ) { mShowingCandidates = showing; }
00189     const QList<QgsLabelCandidate>& candidates() { return mCandidates; }
00190 
00191     bool isShowingAllLabels() const { return mShowingAllLabels; }
00192     void setShowingAllLabels( bool showing ) { mShowingAllLabels = showing; }
00193 
00194     // implemented methods from labeling engine interface
00195 
00197     virtual void init( QgsMapRenderer* mr );
00199     virtual bool willUseLayer( QgsVectorLayer* layer );
00201     virtual int prepareLayer( QgsVectorLayer* layer, QSet<int>& attrIndices, QgsRenderContext& ctx );
00203     virtual int addDiagramLayer( QgsVectorLayer* layer, QgsDiagramLayerSettings *s );
00205     virtual void registerFeature( QgsVectorLayer* layer, QgsFeature& feat, const QgsRenderContext& context = QgsRenderContext() );
00206     virtual void registerDiagramFeature( QgsVectorLayer* layer, QgsFeature& feat, const QgsRenderContext& context = QgsRenderContext() );
00208     virtual void drawLabeling( QgsRenderContext& context );
00210     virtual void exit();
00212     virtual QList<QgsLabelPosition> labelsAtPosition( const QgsPoint& p );
00213 
00215     virtual QgsLabelingEngineInterface* clone();
00216 
00217     void drawLabelCandidateRect( pal::LabelPosition* lp, QPainter* painter, const QgsMapToPixel* xform );
00219     void drawLabel( pal::LabelPosition* label, QPainter* painter, const QFont& f, const QColor& c, const QgsMapToPixel* xform, double bufferSize = -1, \
00220                     const QColor& bufferColor = QColor( 255, 255, 255 ), bool drawBuffer = false );
00221     static void drawLabelBuffer( QPainter* p, QString text, const QFont& font, double size, QColor color );
00222 
00223   protected:
00224 
00225     void initPal();
00226 
00227   protected:
00228     // hashtable of layer settings, being filled during labeling
00229     QHash<QgsVectorLayer*, QgsPalLayerSettings> mActiveLayers;
00230     // hashtable of active diagram layers
00231     QHash<QgsVectorLayer*, QgsDiagramLayerSettings> mActiveDiagramLayers;
00232     QgsPalLayerSettings mInvalidLayerSettings;
00233 
00234     QgsMapRenderer* mMapRenderer;
00235     int mCandPoint, mCandLine, mCandPolygon;
00236     Search mSearch;
00237 
00238     pal::Pal* mPal;
00239 
00240     // list of candidates from last labeling
00241     QList<QgsLabelCandidate> mCandidates;
00242     bool mShowingCandidates;
00243 
00244     bool mShowingAllLabels; // whether to avoid collisions or not
00245 
00246     QgsLabelSearchTree* mLabelSearchTree;
00247 };
00248 
00249 #endif // QGSPALLABELING_H
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines