Skip to content

Commit e8b7ca9

Browse files
nyalldawsonnyalldawson
committed
[composer] Small improvements to API docs
1 parent 084fa89 commit e8b7ca9

4 files changed

Lines changed: 126 additions & 46 deletions

File tree

‎python/core/composer/qgsatlascomposition.sip‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -51,11 +51,11 @@ public:
5151
void setHideCoverage( bool hide );
5252

5353
/**Returns whether the atlas map uses a fixed scale
54-
* @deprecated Use QgsComposerMap::atlasFixedScale() instead
54+
* @deprecated since 2.4 Use QgsComposerMap::atlasScalingMode() instead
5555
*/
5656
bool fixedScale() const /Deprecated/;
5757
/**Sets whether the atlas map should use a fixed scale
58-
* @deprecated Use QgsComposerMap::setAtlasFixedScale( bool ) instead
58+
* @deprecated since 2.4 Use QgsComposerMap::setAtlasScalingMode() instead
5959
*/
6060
void setFixedScale( bool fixed ) /Deprecated/;
6161

@@ -131,12 +131,19 @@ public:
131131
int sortKeyAttributeIndex() const /Deprecated/;
132132
void setSortKeyAttributeIndex( int idx ) /Deprecated/;
133133

134-
/** Returns the current list of predefined scales
135-
@returns a vector of doubles representing predefined scales
134+
/**Returns the current list of predefined scales for the atlas. This is used
135+
* for maps which are set to the predefined atlas scaling mode.
136+
* @returns a vector of doubles representing predefined scales
137+
* @see setPredefinedScales
138+
* @see QgsComposerMap::atlasScalingMode
136139
*/
137140
const QVector<double>& predefinedScales() const;
138-
/** Sets the predefined scales
139-
@param scales a vector of doubles representing predefined scales
141+
142+
/**Sets the list of predefined scales for the atlas. This is used
143+
* for maps which are set to the predefined atlas scaling mode.
144+
* @param scales a vector of doubles representing predefined scales
145+
* @see predefinedScales
146+
* @see QgsComposerMap::atlasScalingMode
140147
*/
141148
void setPredefinedScales( const QVector<double>& scales );
142149

‎python/core/composer/qgscomposermap.sip‎

Lines changed: 50 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -75,13 +75,14 @@ class QgsComposerMap : QgsComposerItem
7575
enum AtlasScalingMode
7676
{
7777
Fixed, /*< The current scale of the map is used for each feature of the atlas */
78-
Predefined, /*< A scale is chosen from the predefined scales
78+
Predefined, /*< A scale is chosen from the predefined scales. The smallest scale from
79+
the list of scales where the atlas feature is fully visible is chosen.
7980
@see QgsAtlasComposition::setPredefinedScales.
80-
The smallest scale from the list of scales where the atlas feature
81-
is fully visible is chosen.
82-
*/
81+
@note This mode is only valid for polygon or line atlas coverage layers
82+
*/
8383
Auto /*< The extent is adjusted so that each feature is fully visible.
84-
A margin is applied around the center @see setAtlasMargin */
84+
A margin is applied around the center @see setAtlasMargin
85+
@note This mode is only valid for polygon or line atlas coverage layers*/
8586
};
8687

8788
/** \brief Draw to paint device
@@ -403,32 +404,64 @@ class QgsComposerMap : QgsComposerItem
403404
*/
404405
void sizeChangedByRotation( double& width, double& height ) /Deprecated/;
405406

406-
/** Returns true if the map extent is set to follow the current atlas feature */
407+
/**Returns whether the map extent is set to follow the current atlas feature.
408+
* @returns true if map will follow the current atlas feature.
409+
* @see setAtlasDriven
410+
* @see atlasScalingMode
411+
*/
407412
bool atlasDriven() const;
408-
/** Set to true if the map extents should be set by the current atlas feature */
413+
414+
/**Sets whether the map extent will follow the current atlas feature.
415+
* @param enabled set to true if the map extents should be set by the current atlas feature.
416+
* @see atlasDriven
417+
* @see setAtlasScalingMode
418+
*/
409419
void setAtlasDriven( bool enabled );
410420

411-
/** Returns true if the map uses a fixed scale when in atlas mode
412-
@deprecated since 2.4 Use atlasScalingMode() instead
421+
/**Returns true if the map uses a fixed scale when in atlas mode
422+
* @deprecated since 2.4 Use atlasScalingMode() instead
413423
*/
414424
bool atlasFixedScale() const /Deprecated/;
415-
/** Set to true if the map should use a fixed scale when in atlas mode
416-
@deprecated since 2.4 Use setAtlasScalingMode() instead
425+
426+
/**Set to true if the map should use a fixed scale when in atlas mode
427+
* @deprecated since 2.4 Use setAtlasScalingMode() instead
417428
*/
418429
void setAtlasFixedScale( bool fixed ) /Deprecated/;
419430

420-
/** Returns the current atlas scaling mode
421-
@returns the current scaling mode
431+
/**Returns the current atlas scaling mode. This controls how the map's extents
432+
* are calculated for the current atlas feature when an atlas composition
433+
* is enabled.
434+
* @returns the current scaling mode
435+
* @note this parameter is only used if atlasDriven() is true
436+
* @see setAtlasScalingMode
437+
* @see atlasDriven
422438
*/
423439
AtlasScalingMode atlasScalingMode();
424-
/** Sets the current atlas scaling mode
425-
@param mode atlas scaling mode to set
440+
441+
/**Sets the current atlas scaling mode. This controls how the map's extents
442+
* are calculated for the current atlas feature when an atlas composition
443+
* is enabled.
444+
* @param mode atlas scaling mode to set
445+
* @note this parameter is only used if atlasDriven() is true
446+
* @see atlasScalingMode
447+
* @see atlasDriven
426448
*/
427449
void setAtlasScalingMode( AtlasScalingMode mode );
428450

429-
/** Returns the margin size (percentage) used when the map is in atlas mode */
451+
/**Returns the margin size (percentage) used when the map is in atlas mode.
452+
* @returns margin size in percentage to leave around the atlas feature's extent
453+
* @note this is only used if atlasScalingMode() is Auto.
454+
* @see atlasScalingMode
455+
* @see setAtlasMargin
456+
*/
430457
double atlasMargin() const;
431-
/** Sets the margin size (percentage) used when the map is in atlas mode */
458+
459+
/**Sets the margin size (percentage) used when the map is in atlas mode.
460+
* @param margin size in percentage to leave around the atlas feature's extent
461+
* @note this is only used if atlasScalingMode() is Auto.
462+
* @see atlasScalingMode
463+
* @see atlasMargin
464+
*/
432465
void setAtlasMargin( double margin );
433466

434467
/** Sets whether updates to the composer map are enabled. */

‎src/core/composer/qgsatlascomposition.h‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -79,12 +79,12 @@ class CORE_EXPORT QgsAtlasComposition : public QObject
7979
void setHideCoverage( bool hide );
8080

8181
/**Returns whether the atlas map uses a fixed scale
82-
* @deprecated Use QgsComposerMap::atlasFixedScale() instead
82+
* @deprecated since 2.4 Use QgsComposerMap::atlasScalingMode() instead
8383
*/
8484
Q_DECL_DEPRECATED bool fixedScale() const;
8585

8686
/**Sets whether the atlas map should use a fixed scale
87-
* @deprecated Use QgsComposerMap::setAtlasFixedScale( bool ) instead
87+
* @deprecated since 2.4 Use QgsComposerMap::setAtlasScalingMode() instead
8888
*/
8989
Q_DECL_DEPRECATED void setFixedScale( bool fixed );
9090

@@ -160,12 +160,19 @@ class CORE_EXPORT QgsAtlasComposition : public QObject
160160
Q_DECL_DEPRECATED int sortKeyAttributeIndex() const;
161161
Q_DECL_DEPRECATED void setSortKeyAttributeIndex( int idx );
162162

163-
/** Returns the current list of predefined scales
164-
@returns a vector of doubles representing predefined scales
163+
/**Returns the current list of predefined scales for the atlas. This is used
164+
* for maps which are set to the predefined atlas scaling mode.
165+
* @returns a vector of doubles representing predefined scales
166+
* @see setPredefinedScales
167+
* @see QgsComposerMap::atlasScalingMode
165168
*/
166169
const QVector<double>& predefinedScales() const { return mPredefinedScales; }
167-
/** Sets the predefined scales
168-
@param scales a vector of doubles representing predefined scales
170+
171+
/**Sets the list of predefined scales for the atlas. This is used
172+
* for maps which are set to the predefined atlas scaling mode.
173+
* @param scales a vector of doubles representing predefined scales
174+
* @see predefinedScales
175+
* @see QgsComposerMap::atlasScalingMode
169176
*/
170177
void setPredefinedScales( const QVector<double>& scales );
171178

‎src/core/composer/qgscomposermap.h‎

Lines changed: 50 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -109,13 +109,14 @@ class CORE_EXPORT QgsComposerMap : public QgsComposerItem
109109
enum AtlasScalingMode
110110
{
111111
Fixed, /*< The current scale of the map is used for each feature of the atlas */
112-
Predefined, /*< A scale is chosen from the predefined scales
112+
Predefined, /*< A scale is chosen from the predefined scales. The smallest scale from
113+
the list of scales where the atlas feature is fully visible is chosen.
113114
@see QgsAtlasComposition::setPredefinedScales.
114-
The smallest scale from the list of scales where the atlas feature
115-
is fully visible is chosen.
116-
*/
115+
@note This mode is only valid for polygon or line atlas coverage layers
116+
*/
117117
Auto /*< The extent is adjusted so that each feature is fully visible.
118-
A margin is applied around the center @see setAtlasMargin */
118+
A margin is applied around the center @see setAtlasMargin
119+
@note This mode is only valid for polygon or line atlas coverage layers*/
119120
};
120121

121122
/** \brief Draw to paint device
@@ -439,32 +440,64 @@ class CORE_EXPORT QgsComposerMap : public QgsComposerItem
439440
*/
440441
Q_DECL_DEPRECATED void sizeChangedByRotation( double& width, double& height );
441442

442-
/** Returns true if the map extent is set to follow the current atlas feature */
443+
/**Returns whether the map extent is set to follow the current atlas feature.
444+
* @returns true if map will follow the current atlas feature.
445+
* @see setAtlasDriven
446+
* @see atlasScalingMode
447+
*/
443448
bool atlasDriven() const { return mAtlasDriven; }
444-
/** Set to true if the map extents should be set by the current atlas feature */
449+
450+
/**Sets whether the map extent will follow the current atlas feature.
451+
* @param enabled set to true if the map extents should be set by the current atlas feature.
452+
* @see atlasDriven
453+
* @see setAtlasScalingMode
454+
*/
445455
void setAtlasDriven( bool enabled ) { mAtlasDriven = enabled; }
446456

447-
/** Returns true if the map uses a fixed scale when in atlas mode
448-
@deprecated since 2.4 Use atlasScalingMode() instead
457+
/**Returns true if the map uses a fixed scale when in atlas mode
458+
* @deprecated since 2.4 Use atlasScalingMode() instead
449459
*/
450460
Q_DECL_DEPRECATED bool atlasFixedScale() const;
451-
/** Set to true if the map should use a fixed scale when in atlas mode
452-
@deprecated since 2.4 Use setAtlasScalingMode() instead
461+
462+
/**Set to true if the map should use a fixed scale when in atlas mode
463+
* @deprecated since 2.4 Use setAtlasScalingMode() instead
453464
*/
454465
Q_DECL_DEPRECATED void setAtlasFixedScale( bool fixed );
455466

456-
/** Returns the current atlas scaling mode
457-
@returns the current scaling mode
467+
/**Returns the current atlas scaling mode. This controls how the map's extents
468+
* are calculated for the current atlas feature when an atlas composition
469+
* is enabled.
470+
* @returns the current scaling mode
471+
* @note this parameter is only used if atlasDriven() is true
472+
* @see setAtlasScalingMode
473+
* @see atlasDriven
458474
*/
459475
AtlasScalingMode atlasScalingMode() const { return mAtlasScalingMode; }
460-
/** Sets the current atlas scaling mode
461-
@param mode atlas scaling mode to set
476+
477+
/**Sets the current atlas scaling mode. This controls how the map's extents
478+
* are calculated for the current atlas feature when an atlas composition
479+
* is enabled.
480+
* @param mode atlas scaling mode to set
481+
* @note this parameter is only used if atlasDriven() is true
482+
* @see atlasScalingMode
483+
* @see atlasDriven
462484
*/
463485
void setAtlasScalingMode( AtlasScalingMode mode ) { mAtlasScalingMode = mode; }
464486

465-
/** Returns the margin size (percentage) used when the map is in atlas mode */
487+
/**Returns the margin size (percentage) used when the map is in atlas mode.
488+
* @returns margin size in percentage to leave around the atlas feature's extent
489+
* @note this is only used if atlasScalingMode() is Auto.
490+
* @see atlasScalingMode
491+
* @see setAtlasMargin
492+
*/
466493
double atlasMargin() const { return mAtlasMargin; }
467-
/** Sets the margin size (percentage) used when the map is in atlas mode */
494+
495+
/**Sets the margin size (percentage) used when the map is in atlas mode.
496+
* @param margin size in percentage to leave around the atlas feature's extent
497+
* @note this is only used if atlasScalingMode() is Auto.
498+
* @see atlasScalingMode
499+
* @see atlasMargin
500+
*/
468501
void setAtlasMargin( double margin ) { mAtlasMargin = margin; }
469502

470503
/** Sets whether updates to the composer map are enabled. */

0 commit comments

Comments
 (0)