Quantum GIS API Documentation  1.7.5-Wroclaw
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
qgspallabeling.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgspallabeling.h
3  Smart labeling for vector layers
4  -------------------
5  begin : June 2009
6  copyright : (C) Martin Dobias
7  email : wonder.sk at gmail.com
8 
9  ***************************************************************************
10  * *
11  * This program is free software; you can redistribute it and/or modify *
12  * it under the terms of the GNU General Public License as published by *
13  * the Free Software Foundation; either version 2 of the License, or *
14  * (at your option) any later version. *
15  * *
16  ***************************************************************************/
17 
18 //Note: although this file is in the core library, it is not part of the stable API
19 //and might change at any time!
20 
21 #ifndef QGSPALLABELING_H
22 #define QGSPALLABELING_H
23 
24 class QFontMetricsF;
25 class QPainter;
26 class QgsGeometry;
27 class QgsMapRenderer;
28 class QgsRectangle;
30 class QgsLabelSearchTree;
32 
33 #include <QString>
34 #include <QFont>
35 #include <QColor>
36 #include <QHash>
37 #include <QList>
38 #include <QRectF>
39 
40 namespace pal
41 {
42  class Pal;
43  class Layer;
44  class LabelPosition;
45 }
46 
47 class QgsMapToPixel;
48 class QgsFeature;
49 #include "qgspoint.h"
50 
51 #include "qgsmaprenderer.h" // definition of QgsLabelingEngineInterface
52 
53 class QgsPalGeometry;
54 class QgsVectorLayer;
55 
56 class CORE_EXPORT QgsPalLayerSettings
57 {
58  public:
62 
63  enum Placement
64  {
65  AroundPoint, // Point / Polygon
66  OverPoint, // Point / Polygon
67  Line, // Line / Polygon
68  Curved, // Line
69  Horizontal, // Polygon
70  Free // Polygon
71  };
72 
74  {
75  OnLine = 1,
76  AboveLine = 2,
77  BelowLine = 4,
78  MapOrientation = 8
79  };
80 
82  {
83  Size = 0,
92  PositionX, //x-coordinate data defined label position
93  PositionY, //y-coordinate data defined label position
94  Hali, //horizontal alignment for data defined label position (Left, Center, Right)
95  Vali, //vertical alignment for data defined label position (Bottom, Base, Half, Cap, Top)
97  Rotation //data defined rotation (only useful in connection with data defined position)
98  };
99 
100  QString fieldName;
102  unsigned int placementFlags;
103  QFont textFont;
104  QColor textColor;
105  bool enabled;
106  int priority; // 0 = low, 10 = high
107  bool obstacle; // whether it's an obstacle
108  double dist; // distance from the feature (in mm)
109  double vectorScaleFactor; //scale factor painter units->pixels
110  double rasterCompressFactor; //pixel resolution scale factor
111  int scaleMin, scaleMax; // disabled if both are zero
112  double bufferSize; //buffer size (in mm)
113  QColor bufferColor;
114  bool labelPerPart; // whether to label every feature's part or only the biggest one
116  bool multiLineLabels; //draw labels on multiple lines if they contain '\n'
117  double minFeatureSize; // minimum feature size to be labelled (in mm)
118  // Adds '<' or '>' to the label string pointing to the direction of the line / polygon ring
119  // Works only if Placement == Line
121  bool fontSizeInMapUnits; //true if font size is in map units (otherwise in points)
122  bool distInMapUnits; //true if distance is in map units (otherwise in mm)
123 
124  // called from register feature hook
125  void calculateLabelSize( const QFontMetricsF* fm, QString text, double& labelX, double& labelY );
126 
127  // implementation of register feature hook
128  void registerFeature( QgsFeature& f, const QgsRenderContext& context );
129 
130  void readFromLayer( QgsVectorLayer* layer );
131  void writeToLayer( QgsVectorLayer* layer );
132 
134  void setDataDefinedProperty( DataDefinedProperties p, int attributeIndex );
136  void removeDataDefinedProperty( DataDefinedProperties p );
137 
138  // temporary stuff: set when layer gets prepared
139  pal::Layer* palLayer;
141  QFontMetricsF* fontMetrics;
144  QgsPoint ptZero, ptOne;
145  QList<QgsPalGeometry*> geometries;
146 
148  QMap< DataDefinedProperties, int > dataDefinedProperties;
149 
154  int sizeToPixel( double size, const QgsRenderContext& c ) const;
155 
156  private:
159  bool checkMinimumSizeMM( const QgsRenderContext& ct, QgsGeometry* geom, double minSize ) const;
160 };
161 
162 class CORE_EXPORT QgsLabelCandidate
163 {
164  public:
165  QgsLabelCandidate( QRectF r, double c ): rect( r ), cost( c ) {}
166 
167  QRectF rect;
168  double cost;
169 };
170 
171 class CORE_EXPORT QgsPalLabeling : public QgsLabelingEngineInterface
172 {
173  public:
174  QgsPalLabeling();
175  ~QgsPalLabeling();
176 
177  QgsPalLayerSettings& layer( const QString& layerName );
178 
179  void numCandidatePositions( int& candPoint, int& candLine, int& candPolygon );
180  void setNumCandidatePositions( int candPoint, int candLine, int candPolygon );
181 
182  enum Search { Chain, Popmusic_Tabu, Popmusic_Chain, Popmusic_Tabu_Chain, Falp };
183 
184  void setSearchMethod( Search s );
185  Search searchMethod() const;
186 
187  bool isShowingCandidates() const { return mShowingCandidates; }
188  void setShowingCandidates( bool showing ) { mShowingCandidates = showing; }
189  const QList<QgsLabelCandidate>& candidates() { return mCandidates; }
190 
191  bool isShowingAllLabels() const { return mShowingAllLabels; }
192  void setShowingAllLabels( bool showing ) { mShowingAllLabels = showing; }
193 
194  // implemented methods from labeling engine interface
195 
197  virtual void init( QgsMapRenderer* mr );
199  virtual bool willUseLayer( QgsVectorLayer* layer );
201  virtual int prepareLayer( QgsVectorLayer* layer, QSet<int>& attrIndices, QgsRenderContext& ctx );
203  virtual int addDiagramLayer( QgsVectorLayer* layer, QgsDiagramLayerSettings *s );
205  virtual void registerFeature( QgsVectorLayer* layer, QgsFeature& feat, const QgsRenderContext& context = QgsRenderContext() );
206  virtual void registerDiagramFeature( QgsVectorLayer* layer, QgsFeature& feat, const QgsRenderContext& context = QgsRenderContext() );
208  virtual void drawLabeling( QgsRenderContext& context );
210  virtual void exit();
212  virtual QList<QgsLabelPosition> labelsAtPosition( const QgsPoint& p );
213 
216 
217  void drawLabelCandidateRect( pal::LabelPosition* lp, QPainter* painter, const QgsMapToPixel* xform );
219  void drawLabel( pal::LabelPosition* label, QPainter* painter, const QFont& f, const QColor& c, const QgsMapToPixel* xform, double bufferSize = -1, \
220  const QColor& bufferColor = QColor( 255, 255, 255 ), bool drawBuffer = false );
221  static void drawLabelBuffer( QPainter* p, QString text, const QFont& font, double size, QColor color );
222 
223  protected:
224 
225  void initPal();
226 
227  protected:
228  // hashtable of layer settings, being filled during labeling
229  QHash<QgsVectorLayer*, QgsPalLayerSettings> mActiveLayers;
230  // hashtable of active diagram layers
231  QHash<QgsVectorLayer*, QgsDiagramLayerSettings> mActiveDiagramLayers;
233 
235  int mCandPoint, mCandLine, mCandPolygon;
237 
238  pal::Pal* mPal;
239 
240  // list of candidates from last labeling
241  QList<QgsLabelCandidate> mCandidates;
243 
244  bool mShowingAllLabels; // whether to avoid collisions or not
245 
247 };
248 
249 #endif // QGSPALLABELING_H