Cleanup labeling, avoid some duplicate enums, add docs

python/core/qgspallabeling.sip

@@ -91,22 +91,32 @@ class QgsPalLayerSettings
     //! @note added in 2.4
     static QgsPalLayerSettings fromLayer( QgsVectorLayer* layer );
 
+    /** Placement modes which determine how label candidates are generated for a feature.
+     */
     enum Placement
     {
-      AroundPoint, // Point / Polygon
-      OverPoint, // Point / Polygon
-      Line, // Line / Polygon
-      Curved, // Line
-      Horizontal, // Polygon
-      Free // Polygon
+      AroundPoint, /**< Arranges candidates in a circle around a point (or centroid of a polygon). Applies to point or polygon layers only.*/
+      OverPoint, /**  Arranges candidates over a point (or centroid of a polygon), or at a preset offset from the point. Applies to point or polygon layers only.*/
+      Line, /**< Arranges candidates parallel to a generalised line representing the feature or parallel to a polygon's perimeter. Applies to line or polygon layers only. */
+      Curved, /** Arranges candidates following the curvature of a line feature. Applies to line layers only.*/
+      Horizontal, /**< Arranges horizontal candidates scattered throughout a polygon feature. Applies to polygon layers only.*/
+      Free /**< Arranges candidates scattered throughout a polygon feature. Candidates are rotated to respect the polygon's orientation. Applies to polygon layers only.*/
     };
 
+    /** Line placement flags, which control how candidates are generated for a linear feature.
+     */
     enum LinePlacementFlags
     {
-      OnLine,
-      AboveLine,
-      BelowLine,
-      MapOrientation,
+      OnLine, /**< Labels can be placed directly over a line feature.*/
+      AboveLine, /**< Labels can be placed above a line feature. Unless MapOrientation is also specified this mode
+                            respects the direction of the line feature, so a line from right to left labels will have labels
+                            placed placed below the line feature. */
+      BelowLine, /**< Labels can be placed below a line feature. Unless MapOrientation is also specified this mode
+                            respects the direction of the line feature, so a line from right to left labels will have labels
+                            placed placed above the line feature. */
+      MapOrientation, /**< Signifies that the AboveLine and BelowLine flags should respect the map's orientation rather
+                            than the feature's orientation. Eg, AboveLine will always result in label's being placed
+                            above a line, regardless of the line's direction. */
     };
 
     enum QuadrantPosition

src/core/pal/costcalculator.cpp

@@ -69,15 +69,15 @@ namespace pal
         // behaviour depends on obstacle avoid type
         switch ( obstacle->layer()->obstacleType() )
         {
-          case PolygonInterior:
+          case QgsPalLayerSettings::PolygonInterior:
             // n ranges from 0 -> 12
             n = lp->polygonIntersectionCost( obstacle );
             break;
-          case PolygonBoundary:
+          case QgsPalLayerSettings::PolygonBoundary:
             // penalty may need tweaking, given that interior mode ranges up to 12
             n = ( lp->crossesBoundary( obstacle ) ? 6 : 0 );
             break;
-          case PolygonWhole:
+          case QgsPalLayerSettings::PolygonWhole:
             // n is either 0 or 12
             n = ( lp->intersectsWithPolygon( obstacle ) ? 12 : 0 );
             break;
@@ -232,7 +232,7 @@ namespace pal
     if ( feat->feature->getGeosType() == GEOS_POLYGON )
     {
       int arrangement = feat->feature->layer()->arrangement();
-      if ( arrangement == P_FREE || arrangement == P_HORIZ )
+      if ( arrangement == QgsPalLayerSettings::Free || arrangement == QgsPalLayerSettings::Horizontal )
         setPolygonCandidatesCost( stop, feat->lPos, obstacles, bbx, bby );
     }
 

src/core/pal/feature.cpp

@@ -267,7 +267,7 @@ namespace pal
       }
     }
 
-    if ( mLF->layer()->arrangement() == P_POINT )
+    if ( mLF->layer()->arrangement() == QgsPalLayerSettings::AroundPoint )
     {
       //if in "around point" placement mode, then we use the label distance to determine
       //the label's offset
@@ -604,7 +604,7 @@ namespace pal
 #ifdef _DEBUG_FULL_
       std::cout << "  Create new label" << std::endl;
 #endif
-      if ( mLF->layer()->arrangement() == P_LINE )
+      if ( mLF->layer()->arrangement() == QgsPalLayerSettings::Line )
       {
         // find out whether the line direction for this candidate is from right to left
         bool isRightToLeft = ( alpha > M_PI / 2 || alpha <= -M_PI / 2 );
@@ -630,7 +630,7 @@ namespace pal
             positions.append( new LabelPosition( i, bx - yrm*cos( beta ) / 2, by - yrm*sin( beta ) / 2, xrm, yrm, alpha, cost, this, isRightToLeft ) ); // Line
         }
       }
-      else if ( mLF->layer()->arrangement() == P_HORIZ )
+      else if ( mLF->layer()->arrangement() == QgsPalLayerSettings::Horizontal )
       {
         positions.append( new LabelPosition( i, bx - xrm / 2, by - yrm / 2, xrm, yrm, 0, cost, this ) ); // Line
       }
@@ -1087,7 +1087,7 @@ namespace pal
             continue;
           }
 
-          if ( mLF->layer()->arrangement() == P_HORIZ && mLF->layer()->fitInPolygonOnly() )
+          if ( mLF->layer()->arrangement() == QgsPalLayerSettings::Horizontal && mLF->layer()->fitInPolygonOnly() )
           {
             //check width/height of bbox is sufficient for label
             if ( box->length < labelWidth || box->width < labelHeight )
@@ -1106,7 +1106,7 @@ namespace pal
 #endif
 
           bool enoughPlace = false;
-          if ( mLF->layer()->arrangement() == P_FREE )
+          if ( mLF->layer()->arrangement() == QgsPalLayerSettings::Free )
           {
             enoughPlace = true;
             px = ( box->x[0] + box->x[2] ) / 2 - labelWidth;
@@ -1134,7 +1134,7 @@ namespace pal
 
           } // arrangement== FREE ?
 
-          if ( mLF->layer()->arrangement() == P_HORIZ || enoughPlace )
+          if ( mLF->layer()->arrangement() == QgsPalLayerSettings::Horizontal || enoughPlace )
           {
             alpha = 0.0; // HORIZ
           }
@@ -1280,13 +1280,13 @@ namespace pal
       switch ( type )
       {
         case GEOS_POINT:
-          if ( mLF->layer()->arrangement() == P_POINT_OVER || mLF->hasFixedQuadrant() )
+          if ( mLF->layer()->arrangement() == QgsPalLayerSettings::OverPoint || mLF->hasFixedQuadrant() )
             setPositionOverPoint( x[0], y[0], lPos, angle );
           else
             setPositionForPoint( x[0], y[0], lPos, angle );
           break;
         case GEOS_LINESTRING:
-          if ( mLF->layer()->arrangement() == P_CURVED )
+          if ( mLF->layer()->arrangement() == QgsPalLayerSettings::Curved )
             setPositionForLineCurved( lPos, mapShape );
           else
             setPositionForLine( lPos, mapShape );
@@ -1295,16 +1295,16 @@ namespace pal
         case GEOS_POLYGON:
           switch ( mLF->layer()->arrangement() )
           {
-            case P_POINT:
-            case P_POINT_OVER:
+            case QgsPalLayerSettings::AroundPoint:
+            case QgsPalLayerSettings::OverPoint:
               double cx, cy;
               mapShape->getCentroid( cx, cy, mLF->layer()->centroidInside() );
-              if ( mLF->layer()->arrangement() == P_POINT_OVER )
+              if ( mLF->layer()->arrangement() == QgsPalLayerSettings::OverPoint )
                 setPositionOverPoint( cx, cy, lPos, angle, mapShape );
               else
                 setPositionForPoint( cx, cy, lPos, angle, mapShape );
               break;
-            case P_LINE:
+            case QgsPalLayerSettings::Line:
               setPositionForLine( lPos, mapShape );
               break;
             default:

src/core/pal/labelposition.cpp

@@ -101,7 +101,7 @@ namespace pal
     y[3] = y1 + dy2;
 
     // upside down ? (curved labels are always correct)
-    if ( feature->layer()->arrangement() != P_CURVED &&
+    if ( feature->layer()->arrangement() != QgsPalLayerSettings::Curved &&
          this->alpha > M_PI / 2 && this->alpha <= 3*M_PI / 2 )
     {
       bool uprightLabel = false;

src/core/pal/layer.cpp

@@ -43,11 +43,11 @@
 namespace pal
 {
 
-  Layer::Layer( QgsAbstractLabelProvider* provider, const QString& name, Arrangement arrangement, double defaultPriority, bool active, bool toLabel, Pal *pal, bool displayAll )
+  Layer::Layer( QgsAbstractLabelProvider* provider, const QString& name, QgsPalLayerSettings::Placement arrangement, double defaultPriority, bool active, bool toLabel, Pal *pal, bool displayAll )
       : mProvider( provider )
       , mName( name )
       , pal( pal )
-      , mObstacleType( PolygonInterior )
+      , mObstacleType( QgsPalLayerSettings::PolygonInterior )
       , mActive( active )
       , mLabelLayer( toLabel )
       , mDisplayAll( displayAll )

src/core/pal/layer.h

@@ -89,13 +89,13 @@ namespace pal
       /** Returns the layer's arrangement policy.
        * @see setArrangement
        */
-      Arrangement arrangement() const { return mArrangement; }
+      QgsPalLayerSettings::Placement arrangement() const { return mArrangement; }
 
       /** Sets the layer's arrangement policy.
        * @param arrangement arrangement policy
        * @see arrangement
        */
-      void setArrangement( Arrangement arrangement ) { mArrangement = arrangement; }
+      void setArrangement( QgsPalLayerSettings::Placement arrangement ) { mArrangement = arrangement; }
 
       /** Returns the layer's arrangement flags.
        * @see setArrangementFlags
@@ -142,14 +142,14 @@ namespace pal
        * act as obstacles for labels.
        * @see setObstacleType
        */
-      ObstacleType obstacleType() const { return mObstacleType; }
+      QgsPalLayerSettings::ObstacleType obstacleType() const { return mObstacleType; }
 
       /** Sets the obstacle type, which controls how features within the layer
        * act as obstacles for labels.
        * @param obstacleType new obstacle type
        * @see obstacleType
        */
-      void setObstacleType( ObstacleType obstacleType ) { mObstacleType = obstacleType; }
+      void setObstacleType( QgsPalLayerSettings::ObstacleType obstacleType ) { mObstacleType = obstacleType; }
 
       /** Sets the layer's priority.
        * @param priority layer priority, between 0 and 1. 0 corresponds to highest priority,
@@ -262,15 +262,15 @@ namespace pal
 
       double mDefaultPriority;
 
-      ObstacleType mObstacleType;
+      QgsPalLayerSettings::ObstacleType mObstacleType;
       bool mActive;
       bool mLabelLayer;
       bool mDisplayAll;
       bool mCentroidInside;
       bool mFitInPolygon;
 
       /** Optional flags used for some placement methods */
-      Arrangement mArrangement;
+      QgsPalLayerSettings::Placement mArrangement;
       LineArrangementFlags mArrangementFlags;
       LabelMode mMode;
       bool mMergeLines;
@@ -304,7 +304,7 @@ namespace pal
        * @param displayAll if true, all features will be labelled even though overlaps occur
        *
        */
-      Layer( QgsAbstractLabelProvider* provider, const QString& name, Arrangement arrangement, double defaultPriority, bool active, bool toLabel, Pal *pal, bool displayAll = false );
+      Layer( QgsAbstractLabelProvider* provider, const QString& name, QgsPalLayerSettings::Placement arrangement, double defaultPriority, bool active, bool toLabel, Pal *pal, bool displayAll = false );
 
       /** Add newly created feature part into r tree and to the list */
       void addFeaturePart( FeaturePart* fpart, const QString &labelText = QString() );

src/core/pal/pal.cpp

@@ -116,7 +116,7 @@ namespace pal
     //finishGEOS();
   }
 
-  Layer* Pal::addLayer( QgsAbstractLabelProvider* provider, const QString& layerName, Arrangement arrangement, double defaultPriority, bool active, bool toLabel, bool displayAll )
+  Layer* Pal::addLayer( QgsAbstractLabelProvider* provider, const QString& layerName, QgsPalLayerSettings::Placement arrangement, double defaultPriority, bool active, bool toLabel, bool displayAll )
   {
     mMutex.lock();
 

src/core/pal/pal.h

@@ -31,6 +31,7 @@
 #define PAL_H
 
 #include "qgsgeometry.h"
+#include "qgspallabeling.h"
 #include <QList>
 #include <iostream>
 #include <ctime>
@@ -62,20 +63,6 @@ namespace pal
     FALP = 4 /** only initial solution */
   };
 
-  /** The way to arrange labels against spatial entities
-   *
-   * image html arrangement.png "Arrangement modes" width=7cm
-   * */
-  enum Arrangement
-  {
-    P_POINT = 0, /**< arranges candidates around a point (centroid for polygon)*/
-    P_POINT_OVER, /** arranges candidates over a point (centroid for polygon)*/
-    P_LINE, /**< Only for lines and polygons, arranges candidates over the line or the polygon perimeter */
-    P_CURVED, /** Only for lines, labels along the line */
-    P_HORIZ, /**< Only for polygon, arranges candidates horizontaly */
-    P_FREE /**< Only for polygon, arranges candidates with respect of polygon orientation */
-  };
-
   /** Enumeration line arrangement flags. Flags can be combined. */
   enum LineArrangementFlag
   {
@@ -86,13 +73,6 @@ namespace pal
   };
   Q_DECLARE_FLAGS( LineArrangementFlags, LineArrangementFlag )
 
-  enum ObstacleType
-  {
-    PolygonInterior,
-    PolygonBoundary,
-    PolygonWhole
-  };
-
   /**
    *  \brief Main Pal labelling class
    *
@@ -134,7 +114,7 @@ namespace pal
        *
        * @todo add symbolUnit
        */
-      Layer* addLayer( QgsAbstractLabelProvider* provider, const QString& layerName, Arrangement arrangement, double defaultPriority, bool active, bool toLabel, bool displayAll = false );
+      Layer* addLayer( QgsAbstractLabelProvider* provider, const QString& layerName, QgsPalLayerSettings::Placement arrangement, double defaultPriority, bool active, bool toLabel, bool displayAll = false );
 
       /**
        * \brief remove a layer

src/core/qgslabelingenginev2.cpp

@@ -68,39 +68,12 @@ void QgsLabelingEngineV2::removeProvider( QgsAbstractLabelProvider* provider )
 
 void QgsLabelingEngineV2::processProvider( QgsAbstractLabelProvider* provider, QgsRenderContext& context, pal::Pal& p )
 {
-  // how to place the labels
-  pal::Arrangement arrangement;
-  switch ( provider->placement() )
-  {
-    case QgsPalLayerSettings::AroundPoint:
-      arrangement = pal::P_POINT;
-      break;
-    case QgsPalLayerSettings::OverPoint:
-      arrangement = pal::P_POINT_OVER;
-      break;
-    case QgsPalLayerSettings::Line:
-      arrangement = pal::P_LINE;
-      break;
-    case QgsPalLayerSettings::Curved:
-      arrangement = pal::P_CURVED;
-      break;
-    case QgsPalLayerSettings::Horizontal:
-      arrangement = pal::P_HORIZ;
-      break;
-    case QgsPalLayerSettings::Free:
-      arrangement = pal::P_FREE;
-      break;
-    default:
-      Q_ASSERT( "unsupported placement" && 0 );
-      return;
-  }
-
   QgsAbstractLabelProvider::Flags flags = provider->flags();
 
   // create the pal layer
   pal::Layer* l = p.addLayer( provider,
                               provider->name(),
-                              arrangement,
+                              provider->placement(),
                               provider->priority(),
                               true,
                               flags.testFlag( QgsAbstractLabelProvider::DrawLabels ),
@@ -116,18 +89,7 @@ void QgsLabelingEngineV2::processProvider( QgsAbstractLabelProvider* provider, Q
   l->setMergeConnectedLines( flags.testFlag( QgsAbstractLabelProvider::MergeConnectedLines ) );
 
   // set obstacle type
-  switch ( provider->obstacleType() )
-  {
-    case QgsPalLayerSettings::PolygonInterior:
-      l->setObstacleType( pal::PolygonInterior );
-      break;
-    case QgsPalLayerSettings::PolygonBoundary:
-      l->setObstacleType( pal::PolygonBoundary );
-      break;
-    case QgsPalLayerSettings::PolygonWhole:
-      l->setObstacleType( pal::PolygonWhole );
-      break;
-  }
+  l->setObstacleType( provider->obstacleType() );
 
   // set whether location of centroid must be inside of polygons
   l->setCentroidInside( flags.testFlag( QgsAbstractLabelProvider::CentroidMustBeInside ) );