Docs + cleanups for color ramp dialogs

doc/api_break.dox

@@ -300,6 +300,7 @@ variant instead.</li>
 <ul>
 <li>The dialog no longer edits a color ramp in place. Instead, a copy of the ramp is edited
 and the new ramp can be retrieved after executing the dialog by calling ramp().</li>
+<li>Some internal methods which were previously public or protected were made private.</li>
 </ul>
 
 \subsection qgis_api_break_3_0_QgsComposerLabel QgsComposerLabel
@@ -401,6 +402,7 @@ be returned in place of a null pointer.</li>
 <ul>
 <li>The dialog no longer edits a color ramp in place. Instead, a copy of the ramp is edited
 and the new ramp can be retrieved after executing the dialog by calling ramp().</li>
+<li>Some internal methods which were previously public or protected were made private.</li>
 </ul>
 
 \subsection qgis_api_break_3_0_QgsCptCitySelectionItem QgsCptCitySelectionItem
@@ -578,6 +580,7 @@ a QgsGeometry value rather than a pointer.</li>
 <ul>
 <li>The dialog no longer edits a color ramp in place. Instead, a copy of the ramp is edited
 and the new ramp can be retrieved after executing the dialog by calling ramp().</li>
+<li>Some internal methods which were previously public or protected were made private.</li>
 </ul>
 
 \subsection qgis_api_break_3_0_QgsGraphBuilderInterface QgsGraphBuilderInterface
@@ -630,6 +633,7 @@ plugins calling this method will need to be updated.</li>
 <ul>
 <li>The dialog no longer edits a color ramp in place. Instead, a copy of the ramp is edited
 and the new ramp can be retrieved after executing the dialog by calling ramp().</li>
+<li>Some internal methods which were previously public or protected were made private.</li>
 </ul>
 
 \subsection qgis_api_break_3_0_QgsMapCanvas QgsMapCanvas

python/gui/qgscolorbrewercolorrampdialog.sip

@@ -1,21 +1,36 @@
+/** \ingroup gui
+ * \class QgsColorBrewerColorRampDialog
+ * A dialog which allows users to modify the properties of a QgsColorBrewerColorRamp.
+ * \note added in QGIS 3.0
+ */
+
 class QgsColorBrewerColorRampDialog : QDialog
 {
 %TypeHeaderCode
 #include <qgscolorbrewercolorrampdialog.h>
 %End
 
   public:
+
+    /** Constructor for QgsColorBrewerColorRampDialog.
+     * @param ramp initial ramp to show in dialog
+     * @param parent parent widget
+     */
     QgsColorBrewerColorRampDialog( const QgsColorBrewerColorRamp& ramp, QWidget* parent /TransferThis/ = nullptr );
 
+    /** Returns a color ramp representing the current settings from the dialog.
+     * @see setRamp()
+     */
     QgsColorBrewerColorRamp ramp() const;
 
-  public slots:
-    void setSchemeName();
-    void setColors();
-
-    void populateVariants();
+    /** Sets the color ramp to show in the dialog.
+     * @param ramp color ramp
+     * @see ramp()
+     */
+    void setRamp( const QgsColorBrewerColorRamp& ramp );
 
-  protected:
+  signals:
 
-    void updatePreview();
+    //! Emitted when the dialog settings change
+    void changed();
 };

python/gui/qgsgradientcolorrampdialog.sip

@@ -1,22 +1,50 @@
+/** \ingroup gui
+ * \class QgsGradientColorRampDialog
+ * A dialog which allows users to modify the properties of a QgsGradientColorRamp.
+ * \note added in QGIS 3.0
+ */
+
 class QgsGradientColorRampDialog : QDialog
 {
 %TypeHeaderCode
 #include <qgsgradientcolorrampdialog.h>
 %End
 
   public:
+
+    /** Constructor for QgsGradientColorRampDialog.
+     * @param ramp initial ramp to show in dialog
+     * @param parent parent widget
+     */
     QgsGradientColorRampDialog( const QgsGradientColorRamp& ramp, QWidget* parent /TransferThis/ = nullptr );
     ~QgsGradientColorRampDialog();
 
+    /** Returns a color ramp representing the current settings from the dialog.
+     * @see setRamp()
+     */
     QgsGradientColorRamp ramp() const;
 
+    /** Sets the color ramp to show in the dialog.
+     * @param ramp color ramp
+     * @see ramp()
+     */
+    void setRamp( const QgsGradientColorRamp& ramp );
+
+  signals:
+
+    //! Emitted when the dialog settings change
+    void changed();
+
   public slots:
+
+    /** Sets the start color for the gradient ramp.
+     * @see setColor2()
+     */
     void setColor1( const QColor& color );
-    void setColor2( const QColor& color );
 
-  protected slots:
-    void on_cboType_currentIndexChanged( int index );
-    void on_btnInformation_pressed();
+    /** Sets the end color for the gradient ramp.
+     * @see setColor1()
+     */
+    void setColor2( const QColor& color );
 
-  protected:
 };

python/gui/qgslimitedrandomcolorrampdialog.sip

@@ -1,24 +1,53 @@
+/** \ingroup gui
+ * \class QgsLimitedRandomColorRampDialog
+ * A dialog which allows users to modify the properties of a QgsLimitedRandomColorRamp.
+ * \note added in QGIS 3.0
+ */
+
 class QgsLimitedRandomColorRampDialog : QDialog
 {
 %TypeHeaderCode
 #include <qgslimitedrandomcolorrampdialog.h>
 %End
 
   public:
+
+    /** Constructor for QgsLimitedRandomColorRampDialog.
+     * @param ramp initial ramp to show in dialog
+     * @param parent parent widget
+     */
     QgsLimitedRandomColorRampDialog( const QgsLimitedRandomColorRamp& ramp, QWidget* parent /TransferThis/ = nullptr );
 
+    /** Returns a color ramp representing the current settings from the dialog.
+     * @see setRamp()
+     */
     QgsLimitedRandomColorRamp ramp() const;
 
+    /** Sets the color ramp to show in the dialog.
+     * @param ramp color ramp
+     * @see ramp()
+     */
+    void setRamp( const QgsLimitedRandomColorRamp& ramp );
+
+  signals:
+
+    //! Emitted when the dialog settings change
+    void changed();
+
   public slots:
+
+    //! Sets the number of colors to create in the ramp
     void setCount( int val );
+    //! Sets the minimum hue for colors in the ramp
     void setHue1( int val );
+    //! Sets the maximum hue for colors in the ramp
     void setHue2( int val );
+    //! Sets the minimum saturation for colors in the ramp
     void setSat1( int val );
+    //! Sets the maximum saturation for colors in the ramp
     void setSat2( int val );
+    //! Sets the minimum value for colors in the ramp
     void setVal1( int val );
+    //! Sets the maximum value for colors in the ramp
     void setVal2( int val );
-
-  protected:
-
-    void updatePreview();
 };

python/gui/symbology-ng/qgscptcitycolorrampdialog.sip

@@ -1,3 +1,8 @@
+/** \ingroup gui
+ * \class QgsCptCityColorRampDialog
+ * A dialog which allows users to modify the properties of a QgsCptCityColorRamp.
+ * \note added in QGIS 3.0
+ */
 class QgsCptCityColorRampDialog : QDialog
 {
 %TypeHeaderCode
@@ -6,40 +11,36 @@ class QgsCptCityColorRampDialog : QDialog
 
   public:
 
+    /** Constructor for QgsCptCityColorRampDialog.
+     * @param ramp initial ramp to show in dialog
+     * @param parent parent widget
+     */
     QgsCptCityColorRampDialog( const QgsCptCityColorRamp& ramp, QWidget* parent /TransferThis/ = nullptr );
     ~QgsCptCityColorRampDialog();
 
+    /** Returns a color ramp representing the current settings from the dialog.
+     * @see setRamp()
+     */
     QgsCptCityColorRamp ramp() const;
 
+    /** Sets the color ramp to show in the dialog.
+     * @param ramp color ramp
+     * @see ramp()
+     */
+    void setRamp( const QgsCptCityColorRamp& ramp );
 
+    /** Returns the name of the ramp currently selected in the dialog.
+     */
     QString selectedName() const;
 
+    /** Returns true if the ramp should be converted to a QgsGradientColorRamp.
+     */
     bool saveAsGradientRamp() const;
 
-  public slots:
-    void populateVariants();
-
-    void on_mTreeView_clicked( const QModelIndex & );
-    void on_mListWidget_itemClicked( QListWidgetItem * item );
-    void on_mListWidget_itemSelectionChanged();
-    void on_tabBar_currentChanged( int index );
-    void on_pbtnLicenseDetails_pressed();
-    void on_cboVariantName_currentIndexChanged( int index );
-    void onFinished();
-    void on_buttonBox_helpRequested();
-    /* void refresh(); */
-
-  protected:
-
-    void updatePreview( bool clear = false );
-    void clearCopyingInfo();
-    void updateCopyingInfo( const QMap< QString, QString >& copyingMap );
-    void updateTreeView( QgsCptCityDataItem *item, bool resetRamp = true );
-    void updateListWidget( QgsCptCityDataItem *item );
     bool eventFilter( QObject *obj, QEvent *event );
 
-    /* void refreshModel( const QModelIndex& index ); */
-    bool updateRamp();
-    void showAll();
-    void setTreeModel( QgsCptCityBrowserModel* model );
+  signals:
+
+    //! Emitted when the dialog settings change
+    void changed();
 };

src/gui/qgscolorbrewercolorrampdialog.cpp

@@ -51,14 +51,16 @@ QgsColorBrewerColorRampDialog::QgsColorBrewerColorRampDialog( const QgsColorBrew
     cboSchemeName->addItem( icon, schemeName );
   }
 
-  cboSchemeName->setCurrentIndex( cboSchemeName->findText( mRamp.schemeName() ) );
-  populateVariants();
-  cboColors->setCurrentIndex( cboColors->findText( QString::number( mRamp.colors() ) ) );
-
+  updateUi();
   connect( cboSchemeName, SIGNAL( currentIndexChanged( int ) ), this, SLOT( setSchemeName() ) );
   connect( cboColors, SIGNAL( currentIndexChanged( int ) ), this, SLOT( setColors() ) );
+}
 
-  updatePreview();
+void QgsColorBrewerColorRampDialog::setRamp( const QgsColorBrewerColorRamp& ramp )
+{
+  mRamp = ramp;
+  updateUi();
+  emit changed();
 }
 
 void QgsColorBrewerColorRampDialog::populateVariants()
@@ -89,18 +91,28 @@ void QgsColorBrewerColorRampDialog::updatePreview()
   lblPreview->setPixmap( QgsSymbolLayerUtils::colorRampPreviewPixmap( &mRamp, size ) );
 }
 
+void QgsColorBrewerColorRampDialog::updateUi()
+{
+  whileBlocking( cboSchemeName )->setCurrentIndex( cboSchemeName->findText( mRamp.schemeName() ) );
+  populateVariants();
+  whileBlocking( cboColors )->setCurrentIndex( cboColors->findText( QString::number( mRamp.colors() ) ) );
+  updatePreview();
+}
+
 void QgsColorBrewerColorRampDialog::setSchemeName()
 {
   // populate list of variants
   populateVariants();
 
   mRamp.setSchemeName( cboSchemeName->currentText() );
   updatePreview();
+  emit changed();
 }
 
 void QgsColorBrewerColorRampDialog::setColors()
 {
   int num = cboColors->currentText().toInt();
   mRamp.setColors( num );
   updatePreview();
+  emit changed();
 }

src/gui/qgscolorbrewercolorrampdialog.h

@@ -25,25 +25,47 @@ class QgsColorBrewerColorRamp;
 
 /** \ingroup gui
  * \class QgsColorBrewerColorRampDialog
+ * A dialog which allows users to modify the properties of a QgsColorBrewerColorRamp.
+ * \note added in QGIS 3.0
  */
 class GUI_EXPORT QgsColorBrewerColorRampDialog : public QDialog, private Ui::QgsColorBrewerColorRampDialogBase
 {
     Q_OBJECT
+    Q_PROPERTY( QgsColorBrewerColorRamp ramp READ ramp WRITE setRamp )
 
   public:
+
+    /** Constructor for QgsColorBrewerColorRampDialog.
+     * @param ramp initial ramp to show in dialog
+     * @param parent parent widget
+     */
     QgsColorBrewerColorRampDialog( const QgsColorBrewerColorRamp& ramp, QWidget* parent = nullptr );
 
+    /** Returns a color ramp representing the current settings from the dialog.
+     * @see setRamp()
+     */
     QgsColorBrewerColorRamp ramp() const { return mRamp; }
 
-  public slots:
+    /** Sets the color ramp to show in the dialog.
+     * @param ramp color ramp
+     * @see ramp()
+     */
+    void setRamp( const QgsColorBrewerColorRamp& ramp );
+
+  signals:
+
+    //! Emitted when the dialog settings change
+    void changed();
+
+  private slots:
     void setSchemeName();
     void setColors();
-
     void populateVariants();
 
-  protected:
+  private:
 
     void updatePreview();
+    void updateUi();
 
     QgsColorBrewerColorRamp mRamp;
 };

src/gui/qgsgradientcolorrampdialog.cpp

@@ -155,6 +155,17 @@ QgsGradientColorRampDialog::~QgsGradientColorRampDialog()
 
 }
 
+void QgsGradientColorRampDialog::setRamp( const QgsGradientColorRamp& ramp )
+{
+  mRamp = ramp;
+
+  updateColorButtons();
+  updateStopEditor();
+  updatePlot();
+
+  emit changed();
+}
+
 void QgsGradientColorRampDialog::on_cboType_currentIndexChanged( int index )
 {
   if (( index == 0 && mRamp.isDiscrete() ) ||
@@ -164,6 +175,8 @@ void QgsGradientColorRampDialog::on_cboType_currentIndexChanged( int index )
   updateColorButtons();
   updateStopEditor();
   updatePlot();
+
+  emit changed();
 }
 
 void QgsGradientColorRampDialog::on_btnInformation_pressed()
@@ -541,6 +554,8 @@ void QgsGradientColorRampDialog::updateRampFromStopEditor()
 
   updateColorButtons();
   updatePlot();
+
+  emit changed();
 }
 
 void QgsGradientColorRampDialog::setColor1( const QColor& color )