Skip to content

Commit df412ec

Browse files
mhugentmhugent
committedFeb 12, 2013
Merge pull request #427 from matthias-kuhn/rubberband-doc
Documentation update for QgsRubberband
·
ltr-3_40archive/master_2
2 parents 8e11e5f + 42dad85 commit df412ec

File tree

2 files changed

+121
-52
lines changed

2 files changed

+121
-52
lines changed
 

‎src/gui/qgsrubberband.cpp

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ void QgsRubberBand::reset( bool isPolygon )
111111
/*!
112112
Add a point to the shape being created.
113113
*/
114-
void QgsRubberBand::addPoint( const QgsPoint & p, bool do_update /* = true */, int geometryIndex )
114+
void QgsRubberBand::addPoint( const QgsPoint & p, bool doUpdate /* = true */, int geometryIndex )
115115
{
116116
if ( geometryIndex < 0 )
117117
{
@@ -139,7 +139,7 @@ void QgsRubberBand::addPoint( const QgsPoint & p, bool do_update /* = true */, i
139139
}
140140

141141

142-
if ( do_update )
142+
if ( doUpdate )
143143
{
144144
updateRect();
145145
update();

‎src/gui/qgsrubberband.h

Lines changed: 119 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ class QPaintEvent;
2727

2828
/** \ingroup gui
2929
* A class for drawing transient features (e.g. digitising lines) on the map.
30+
* It may be used
3031
*/
3132
class GUI_EXPORT QgsRubberBand: public QgsMapCanvasItem
3233
{
@@ -36,109 +37,175 @@ class GUI_EXPORT QgsRubberBand: public QgsMapCanvasItem
3637
* Added in 1.9 */
3738
enum IconType
3839
{
40+
/**
41+
* No icon is used
42+
*/
3943
ICON_NONE,
44+
/**
45+
* A cross is used to highlight points (+)
46+
*/
4047
ICON_CROSS,
48+
/**
49+
* A cross is used to highlight points (x)
50+
*/
4151
ICON_X,
52+
/**
53+
* A box is used to highlight points (□)
54+
*/
4255
ICON_BOX,
56+
/**
57+
* A circle is used to highlight points (○)
58+
*/
4359
ICON_CIRCLE
4460
};
4561

4662
/**
4763
* Creates a new RubberBand.
48-
* @param mapCanvas The map canvas to draw onto. It's CRS will be used map points onto screen coordinates.
49-
* @param geometryType Defines how the data should be drawn onto the screen. (Use QGis::Line, QGis::Polygon or QGis::Point)
50-
* Added in 1.9.
64+
* @param mapCanvas The map canvas to draw onto. It's CRS will be used map points onto screen coordinates.
65+
* @param geometryType Defines how the data should be drawn onto the screen. (Use QGis::Line, QGis::Polygon or QGis::Point)
66+
* @note Added in 1.9.
5167
*/
5268
QgsRubberBand( QgsMapCanvas* mapCanvas, QGis::GeometryType geometryType = QGis::Line );
5369
/**
5470
* Creates a new RubberBand.
55-
* @deprecated
56-
* @param mapCanvas The map canvas to draw onto. It's CRS will be used map points onto screen coordinates.
57-
* @param isPolygon true: draw as (multi-)polygon, false draw as (multi-)linestring
71+
* @deprecated Use the constructor which takes QGis::GeometryType as second argument instead
72+
* @param mapCanvas The map canvas to draw onto. It's CRS will be used map points onto screen coordinates.
73+
* @param isPolygon true: draw as (multi-)polygon, false draw as (multi-)linestring
5874
*/
5975
QgsRubberBand( QgsMapCanvas* mapCanvas, bool isPolygon );
6076
~QgsRubberBand();
6177

62-
/** Set the color for the rubberband */
78+
/**
79+
* Set the color for the rubberband
80+
* @param color The color used to render this rubberband
81+
*/
6382
void setColor( const QColor & color );
6483

65-
/** Set the width of the line. Outline width for polygon. */
84+
/**
85+
* Set the width of the line. Outline width for polygon.
86+
* @param width The width for any lines painted for this rubberband
87+
*/
6688
void setWidth( int width );
6789

68-
/** Set the icon type to highlight point geometries.
69-
* Added in 1.9 */
90+
/**
91+
* Set the icon type to highlight point geometries.
92+
* @param icon The icon to visualize point geometries
93+
* @note Added in 1.9
94+
*/
7095
void setIcon( IconType icon );
7196

72-
/** Set the size of the point icons
73-
* Added in 1.9 */
97+
/**
98+
* Set the size of the point icons
99+
* @note Added in 1.9
100+
*/
74101
void setIconSize( int iconSize );
75102

76103
/**
77104
* Clears all the geometries in this rubberband.
78105
* Sets the representation type according to geometryType.
79-
* @param geometryType Defines how the data should be drawn onto the screen. (Use QGis::Line, QGis::Polygon or QGis::Point)
80-
* Added in 1.9.
106+
* @param geometryType Defines how the data should be drawn onto the screen. (Use QGis::Line, QGis::Polygon or QGis::Point)
107+
* @note Added in 1.9.
81108
*/
82109
void reset( QGis::GeometryType geometryType = QGis::Line );
110+
83111
/**
84-
* @deprecated
112+
* @deprecated Use the reset method which takes QGis::GeometryType as second argument instead
85113
* Clears all the geometries in this rubberband.
86114
* Sets the representation type according to isPolygon.
87-
* @param isPolygon true: draw as (multi-)polygon, false draw as (multi-)linestring
115+
* @param isPolygon true: draw as (multi-)polygon, false draw as (multi-)linestring
88116
*/
89117
void reset( bool isPolygon );
90118

91-
//! Add point to rubberband and update canvas
92-
//! If adding more points consider using update=false for better performance
93-
//! geometryIndex is the index of the feature part (in case of multipart geometries)
94-
void addPoint( const QgsPoint & p, bool update = true, int geometryIndex = 0 );
119+
/**
120+
* Add a vertex to the rubberband and update canvas.
121+
* The rendering of the vertex depends on the current GeometryType and icon.
122+
* If adding more points consider using update=false for better performance
123+
* @param p The vertex/point to add
124+
* @param doUpdate Should the map canvas be updated immediately?
125+
* @param geometryIndex The index of the feature part (in case of multipart geometries)
126+
*/
127+
void addPoint( const QgsPoint & p, bool doUpdate = true, int geometryIndex = 0 );
95128

96-
//!Removes the last point. Most useful in connection with undo operations
129+
/**
130+
* Removes the last point. Most useful in connection with undo operations
131+
*/
97132
void removeLastPoint( int geometryIndex = 0 );
98133

134+
/**
135+
* Moves the rubber band point specified by index. Note that if the rubber band is
136+
* not used to track the last mouse position, the first point of the rubber band has two vertices
137+
*/
99138
void movePoint( const QgsPoint & p, int geometryIndex = 0 );
100-
/**Moves the rubber band point specified by index. Note that if the rubber band is
101-
not used to track the last mouse position, the first point of the rubber band has two vertices*/
139+
140+
/**
141+
* Moves the rubber band point specified by index. Note that if the rubber band is
142+
* not used to track the last mouse position, the first point of the rubber band has two vertices
143+
*/
102144
void movePoint( int index, const QgsPoint& p, int geometryIndex = 0 );
103145

104-
/**Sets this rubber band to the geometry of an existing feature.
105-
This is useful for feature highlighting.
106-
In contrast to addGeometry, this method does also change the geometry type of the rubberband.
107-
@param geom the geometry object
108-
@param layer the layer containing the feature, used for coord transformation to map
109-
crs. In case of 0 pointer, the coordinates are not going to be transformed.
110-
*/
146+
/**
147+
* Sets this rubber band to the geometry of an existing feature.
148+
* This is useful for feature highlighting.
149+
* In contrast to {@link addGeometry}, this method does also change the geometry type of the rubberband.
150+
* @param geom the geometry object
151+
* @param layer the layer containing the feature, used for coord transformation to map
152+
* crs. In case of 0 pointer, the coordinates are not going to be transformed.
153+
*/
111154
void setToGeometry( QgsGeometry* geom, QgsVectorLayer* layer );
112155

113-
/**Sets this rubber band to a map canvas rectangle
114-
@param rect rectangle in canvas coordinates
115-
@note added in version 1.7*/
156+
/**
157+
* Sets this rubber band to a map canvas rectangle
158+
* @param rect rectangle in canvas coordinates
159+
* @note added in version 1.7
160+
*/
116161
void setToCanvasRectangle( const QRect& rect );
117162

118-
/**Add the geometry of an existing feature to a rubberband
119-
This is useful for multi feature highlighting.
120-
@param geom the geometry object
121-
@param layer the layer containing the feature, used for coord transformation to map
122-
crs. In case of 0 pointer, the coordinates are not going to be transformed.
123-
@note added in 1.5
124-
*/
163+
/**
164+
* Add the geometry of an existing feature to a rubberband
165+
* This is useful for multi feature highlighting.
166+
* As of 2.0, this method does not change the GeometryType any more. You need to set the GeometryType
167+
* of the rubberband explicitly by calling {@link reset} or {@link setToGeometry} with appropriate arguments.
168+
* {@link setToGeometry} is also to be preferred for backwards-compatibility.
169+
*
170+
* @param geom the geometry object. Will be treated as a collection of vertices.
171+
* @param layer the layer containing the feature, used for coord transformation to map
172+
* crs. In case of 0 pointer, the coordinates are not going to be transformed.
173+
* @note added in 1.5
174+
*/
125175
void addGeometry( QgsGeometry* geom, QgsVectorLayer* layer );
126176

127-
/**Adds translation to original coordinates (all in map coordinates)*/
177+
/**
178+
* Adds translation to original coordinates (all in map coordinates)
179+
* @param dx x translation
180+
* @param dy y translation
181+
*/
128182
void setTranslationOffset( double dx, double dy );
129183

130-
/**Returns number of geometries
131-
* added in 1.5 */
184+
/**
185+
* Returns number of geometries
186+
* @return number of geometries
187+
* @note added in 1.5
188+
*/
132189
int size() const;
133190

134-
/**Returns count of vertices in all lists of mPoint*/
191+
/**
192+
* Returns count of vertices in all lists of mPoint
193+
* @return The total number of vertices
194+
*/
135195
int numberOfVertices() const;
136196

137-
/**Return vertex*/
197+
/**
198+
* Return vertex
199+
* @param i The geometry index
200+
* @param j The vertex index within geometry i
201+
*/
138202
const QgsPoint *getPoint( int i, int j = 0 ) const;
139203

140-
/**Returns the rubberband as a Geometry.
141-
* added in 1.6 */
204+
/**
205+
* Returns the rubberband as a Geometry.
206+
* @return A geometry object which reflects the current state of the rubberband.
207+
* @note Added in 1.6
208+
*/
142209
QgsGeometry* asGeometry();
143210

144211
protected:
@@ -155,14 +222,16 @@ class GUI_EXPORT QgsRubberBand: public QgsMapCanvasItem
155222
int mWidth;
156223

157224
/** The size of the icon for points.
158-
* Added in 1.9 */
225+
* @note Added in 1.9 */
159226
int mIconSize;
160227

161228
/** Icon to be shown.
162-
* Added in 1.9 */
229+
* @note Added in 1.9 */
163230
IconType mIconType ;
164231

165-
/**Nested lists used for multitypes*/
232+
/**
233+
* Nested lists used for multitypes
234+
*/
166235
QList< QList <QgsPoint> > mPoints;
167236
QGis::GeometryType mGeometryType;
168237
double mTranslationOffsetX;

0 commit comments

Comments
 (0)
Please sign in to comment.