Quantum GIS API Documentation  1.8
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 
00050 #include "qgspoint.h"
00051 #include "qgsmaprenderer.h" // definition of QgsLabelingEngineInterface
00052 #include "qgsexpression.h"
00053 
00054 class QgsPalGeometry;
00055 class QgsVectorLayer;
00056 
00057 class CORE_EXPORT QgsPalLayerSettings
00058 {
00059   public:
00060     QgsPalLayerSettings();
00061     QgsPalLayerSettings( const QgsPalLayerSettings& s );
00062     ~QgsPalLayerSettings();
00063 
00064     enum Placement
00065     {
00066       AroundPoint, // Point / Polygon
00067       OverPoint, // Point / Polygon
00068       Line, // Line / Polygon
00069       Curved, // Line
00070       Horizontal, // Polygon
00071       Free // Polygon
00072     };
00073 
00074     enum LinePlacementFlags
00075     {
00076       OnLine    = 1,
00077       AboveLine = 2,
00078       BelowLine = 4,
00079       MapOrientation = 8
00080     };
00081 
00082     enum DataDefinedProperties
00083     {
00084       Size = 0,
00085       Bold,
00086       Italic,
00087       Underline,
00088       Color,
00089       Strikeout,
00090       Family,
00091       BufferSize,
00092       BufferColor,
00093       PositionX, //x-coordinate data defined label position
00094       PositionY, //y-coordinate data defined label position
00095       Hali, //horizontal alignment for data defined label position (Left, Center, Right)
00096       Vali, //vertical alignment for data defined label position (Bottom, Base, Half, Cap, Top)
00097       LabelDistance,
00098       Rotation //data defined rotation (only useful in connection with data defined position)
00099     };
00100 
00101     QString fieldName;
00102 
00105     bool isExpression;
00106 
00109     QgsExpression* getLabelExpression();
00110 
00111     Placement placement;
00112     unsigned int placementFlags;
00113     QFont textFont;
00114     QColor textColor;
00115     bool enabled;
00116     int priority; // 0 = low, 10 = high
00117     bool obstacle; // whether it's an obstacle
00118     double dist; // distance from the feature (in mm)
00119     double vectorScaleFactor; //scale factor painter units->pixels
00120     double rasterCompressFactor; //pixel resolution scale factor
00121     int scaleMin, scaleMax; // disabled if both are zero
00122     double bufferSize; //buffer size (in mm)
00123     QColor bufferColor;
00124     bool formatNumbers;
00125     int decimals;
00126     bool plusSign;
00127     bool labelPerPart; // whether to label every feature's part or only the biggest one
00128     bool mergeLines;
00129     double minFeatureSize; // minimum feature size to be labelled (in mm)
00130     // Adds '<' or '>' to the label string pointing to the direction of the line / polygon ring
00131     // Works only if Placement == Line
00132     bool addDirectionSymbol;
00133     bool fontSizeInMapUnits; //true if font size is in map units (otherwise in points)
00134     bool distInMapUnits; //true if distance is in map units (otherwise in mm)
00135     QString wrapChar;
00136     // called from register feature hook
00137     void calculateLabelSize( const QFontMetricsF* fm, QString text, double& labelX, double& labelY );
00138 
00139     // implementation of register feature hook
00140     void registerFeature( QgsVectorLayer* layer, QgsFeature& f, const QgsRenderContext& context );
00141 
00142     void readFromLayer( QgsVectorLayer* layer );
00143     void writeToLayer( QgsVectorLayer* layer );
00144 
00146     void setDataDefinedProperty( DataDefinedProperties p, int attributeIndex );
00148     void removeDataDefinedProperty( DataDefinedProperties p );
00149 
00150     // temporary stuff: set when layer gets prepared
00151     pal::Layer* palLayer;
00152     int fieldIndex;
00153     QFontMetricsF* fontMetrics;
00154     const QgsMapToPixel* xform;
00155     const QgsCoordinateTransform* ct;
00156     QgsPoint ptZero, ptOne;
00157     QList<QgsPalGeometry*> geometries;
00158     QgsGeometry* extentGeom;
00159 
00161     QMap< DataDefinedProperties, int > dataDefinedProperties;
00162 
00167     int sizeToPixel( double size, const QgsRenderContext& c ) const;
00168 
00169   private:
00172     bool checkMinimumSizeMM( const QgsRenderContext& ct, QgsGeometry* geom, double minSize ) const;
00173     QgsExpression* expression;
00174 };
00175 
00176 class CORE_EXPORT QgsLabelCandidate
00177 {
00178   public:
00179     QgsLabelCandidate( QRectF r, double c ): rect( r ), cost( c ) {}
00180 
00181     QRectF rect;
00182     double cost;
00183 };
00184 
00185 class CORE_EXPORT QgsPalLabeling : public QgsLabelingEngineInterface
00186 {
00187   public:
00188     QgsPalLabeling();
00189     ~QgsPalLabeling();
00190 
00191     QgsPalLayerSettings& layer( const QString& layerName );
00192 
00193     void numCandidatePositions( int& candPoint, int& candLine, int& candPolygon );
00194     void setNumCandidatePositions( int candPoint, int candLine, int candPolygon );
00195 
00196     enum Search { Chain, Popmusic_Tabu, Popmusic_Chain, Popmusic_Tabu_Chain, Falp };
00197 
00198     void setSearchMethod( Search s );
00199     Search searchMethod() const;
00200 
00201     bool isShowingCandidates() const { return mShowingCandidates; }
00202     void setShowingCandidates( bool showing ) { mShowingCandidates = showing; }
00203     const QList<QgsLabelCandidate>& candidates() { return mCandidates; }
00204 
00205     bool isShowingAllLabels() const { return mShowingAllLabels; }
00206     void setShowingAllLabels( bool showing ) { mShowingAllLabels = showing; }
00207 
00208     // implemented methods from labeling engine interface
00209 
00211     virtual void init( QgsMapRenderer* mr );
00213     virtual bool willUseLayer( QgsVectorLayer* layer );
00215     virtual int prepareLayer( QgsVectorLayer* layer, QSet<int>& attrIndices, QgsRenderContext& ctx );
00217     virtual int addDiagramLayer( QgsVectorLayer* layer, QgsDiagramLayerSettings *s );
00219     virtual void registerFeature( QgsVectorLayer* layer, QgsFeature& feat, const QgsRenderContext& context = QgsRenderContext() );
00220     virtual void registerDiagramFeature( QgsVectorLayer* layer, QgsFeature& feat, const QgsRenderContext& context = QgsRenderContext() );
00222     virtual void drawLabeling( QgsRenderContext& context );
00224     virtual void exit();
00226     virtual QList<QgsLabelPosition> labelsAtPosition( const QgsPoint& p );
00227 
00229     virtual QgsLabelingEngineInterface* clone();
00230 
00231     void drawLabelCandidateRect( pal::LabelPosition* lp, QPainter* painter, const QgsMapToPixel* xform );
00233     void drawLabel( pal::LabelPosition* label, QPainter* painter, const QFont& f, const QColor& c, const QgsMapToPixel* xform, double bufferSize = -1,
00234                     const QColor& bufferColor = QColor( 255, 255, 255 ), bool drawBuffer = false );
00235     static void drawLabelBuffer( QPainter* p, QString text, const QFont& font, double size, QColor color );
00236 
00237   protected:
00238 
00239     void initPal();
00240 
00241   protected:
00242     // hashtable of layer settings, being filled during labeling
00243     QHash<QgsVectorLayer*, QgsPalLayerSettings> mActiveLayers;
00244     // hashtable of active diagram layers
00245     QHash<QgsVectorLayer*, QgsDiagramLayerSettings> mActiveDiagramLayers;
00246     QgsPalLayerSettings mInvalidLayerSettings;
00247 
00248     QgsMapRenderer* mMapRenderer;
00249     int mCandPoint, mCandLine, mCandPolygon;
00250     Search mSearch;
00251 
00252     pal::Pal* mPal;
00253 
00254     // list of candidates from last labeling
00255     QList<QgsLabelCandidate> mCandidates;
00256     bool mShowingCandidates;
00257 
00258     bool mShowingAllLabels; // whether to avoid collisions or not
00259 
00260     QgsLabelSearchTree* mLabelSearchTree;
00261 };
00262 
00263 #endif // QGSPALLABELING_H
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines