QgsHighlight improvements

* Doxygen improvements
* Fix unrequired casting
* Remove unrequired contructor

python/gui/qgshighlight.sip

@@ -13,22 +13,30 @@ class QgsHighlight: QgsMapCanvasItem
 %Docstring
  A class for highlight features on the map.
 
- The QgsHighlight class provides a transparent overlay widget
-for highlighting features on the map.
+ The QgsHighlight class provides a transparent overlay canvas item
+ for highlighting features or geometries on a map canvas.
+
+ \code{.py}
+   color = QColor(Qt.red)
+   highlight = QgsHighlight(mapCanvas, feature, layer)
+   highlight.setColor(color)
+   color.setAlpha(50)
+   highlight.setFillColor(color)
+   highlight.show()
+ \endcode
 %End
 
 %TypeHeaderCode
 #include "qgshighlight.h"
 %End
   public:
 
-
-    QgsHighlight( QgsMapCanvas *mapCanvas, const QgsGeometry &geom, QgsVectorLayer *layer );
+    QgsHighlight( QgsMapCanvas *mapCanvas, const QgsGeometry &geom, QgsMapLayer *layer );
 %Docstring
  Constructor for QgsHighlight
  \param mapCanvas associated map canvas
  \param geom initial geometry of highlight
- \param layer associated vector layer
+ \param layer associated map layer
 %End
 
     QgsHighlight( QgsMapCanvas *mapCanvas, const QgsFeature &feature, QgsVectorLayer *layer );
@@ -49,29 +57,38 @@ for highlighting features on the map.
 
     void setFillColor( const QColor &fillColor );
 %Docstring
- Set polygons fill color.
-.. versionadded:: 2.3
+ Fill color for the highlight.
+ Will be used for polygons and points.
+
+.. versionadded:: 2.4
 %End
 
     void setWidth( int width );
 %Docstring
-Set stroke width. Ignored in feature mode.
+ Set stroke width.
+
+.. note::
+
+   Ignored in feature mode.
 %End
 
     void setBuffer( double buffer );
 %Docstring
  Set line / stroke buffer in millimeters.
-.. versionadded:: 2.3
+
+.. versionadded:: 2.4
 %End
 
     void setMinWidth( double width );
 %Docstring
  Set minimum line / stroke width in millimeters.
-.. versionadded:: 2.3
+
+.. versionadded:: 2.4
 %End
 
-    const QgsMapLayer *layer() const;
+    QgsMapLayer *layer() const;
 %Docstring
+ Return the layer for which this highlight has been created.
  :rtype: QgsMapLayer
 %End
 

src/gui/qgshighlight.cpp

@@ -49,29 +49,15 @@
 QgsHighlight::QgsHighlight( QgsMapCanvas *mapCanvas, const QgsGeometry &geom, QgsMapLayer *layer )
   : QgsMapCanvasItem( mapCanvas )
   , mLayer( layer )
-  , mBuffer( 0 )
-  , mMinWidth( 0 )
-{
-  mGeometry = !geom.isNull() ? new QgsGeometry( geom ) : nullptr;
-  init();
-}
-
-QgsHighlight::QgsHighlight( QgsMapCanvas *mapCanvas, const QgsGeometry &geom, QgsVectorLayer *layer )
-  : QgsMapCanvasItem( mapCanvas )
-  , mLayer( static_cast<QgsMapLayer *>( layer ) )
-  , mBuffer( 0 )
-  , mMinWidth( 0 )
 {
   mGeometry = !geom.isNull() ? new QgsGeometry( geom ) : nullptr;
   init();
 }
 
 QgsHighlight::QgsHighlight( QgsMapCanvas *mapCanvas, const QgsFeature &feature, QgsVectorLayer *layer )
   : QgsMapCanvasItem( mapCanvas )
-  , mLayer( static_cast<QgsMapLayer *>( layer ) )
+  , mLayer( layer )
   , mFeature( feature )
-  , mBuffer( 0 )
-  , mMinWidth( 0 )
 {
   init();
 }

src/gui/qgshighlight.h

@@ -34,8 +34,17 @@ class QgsSymbol;
  * \ingroup gui
  * A class for highlight features on the map.
  *
- * The QgsHighlight class provides a transparent overlay widget
-  for highlighting features on the map.
+ * The QgsHighlight class provides a transparent overlay canvas item
+ * for highlighting features or geometries on a map canvas.
+ *
+ * \code{.py}
+ *   color = QColor(Qt.red)
+ *   highlight = QgsHighlight(mapCanvas, feature, layer)
+ *   highlight.setColor(color)
+ *   color.setAlpha(50)
+ *   highlight.setFillColor(color)
+ *   highlight.show()
+ * \endcode
  */
 class GUI_EXPORT QgsHighlight: public QgsMapCanvasItem
 {
@@ -46,17 +55,8 @@ class GUI_EXPORT QgsHighlight: public QgsMapCanvasItem
      * \param mapCanvas associated map canvas
      * \param geom initial geometry of highlight
      * \param layer associated map layer
-     * \note not available in Python bindings
-     */
-    QgsHighlight( QgsMapCanvas *mapCanvas, const QgsGeometry &geom, QgsMapLayer *layer ) SIP_SKIP;
-
-    /**
-     * Constructor for QgsHighlight
-     * \param mapCanvas associated map canvas
-     * \param geom initial geometry of highlight
-     * \param layer associated vector layer
      */
-    QgsHighlight( QgsMapCanvas *mapCanvas, const QgsGeometry &geom, QgsVectorLayer *layer );
+    QgsHighlight( QgsMapCanvas *mapCanvas, const QgsGeometry &geom, QgsMapLayer *layer );
 
     /**
      * Constructor for highlighting true feature shape using feature attributes
@@ -74,24 +74,38 @@ class GUI_EXPORT QgsHighlight: public QgsMapCanvasItem
     void setColor( const QColor &color );
 
     /**
-     * Set polygons fill color.
-     * \since QGIS 2.3 */
+     * Fill color for the highlight.
+     * Will be used for polygons and points.
+     *
+     * \since QGIS 2.4
+     */
     void setFillColor( const QColor &fillColor );
 
-    //! Set stroke width. Ignored in feature mode.
+    /**
+     * Set stroke width.
+     *
+     * \note Ignored in feature mode.
+     */
     void setWidth( int width );
 
     /**
      * Set line / stroke buffer in millimeters.
-     *  \since QGIS 2.3 */
+     *
+     * \since QGIS 2.4
+     */
     void setBuffer( double buffer ) { mBuffer = buffer; }
 
     /**
      * Set minimum line / stroke width in millimeters.
-     *  \since QGIS 2.3 */
+     *
+     * \since QGIS 2.4
+     */
     void setMinWidth( double width ) { mMinWidth = width; }
 
-    const QgsMapLayer *layer() const { return mLayer; }
+    /**
+     * Return the layer for which this highlight has been created.
+     */
+    QgsMapLayer *layer() const { return mLayer; }
 
     virtual void updatePosition() override;
 
@@ -116,8 +130,8 @@ class GUI_EXPORT QgsHighlight: public QgsMapCanvasItem
     QgsGeometry *mGeometry = nullptr;
     QgsMapLayer *mLayer = nullptr;
     QgsFeature mFeature;
-    double mBuffer; // line / stroke buffer in pixels
-    double mMinWidth; // line / stroke minimum width in pixels
+    double mBuffer = 0; // line / stroke buffer in pixels
+    double mMinWidth = 0; // line / stroke minimum width in pixels
 };
 
 #endif