Expand docs, extra tests

qgis · Jan 14, 2020 · 5a4bd09 · 5a4bd09
1 parent 387787b
commit 5a4bd09
Show file tree

Hide file tree

Showing 9 changed files with 791 additions and 336 deletions.
diff --git a/python/gui/auto_generated/tableeditor/qgstableeditordialog.sip.in b/python/gui/auto_generated/tableeditor/qgstableeditordialog.sip.in
@@ -11,33 +11,45 @@
 class QgsTableEditorDialog : QMainWindow
 {
 %Docstring
-*************************************************************************
-qgstableeditordialog.h
----------------------
-begin                : January 2020
-copyright            : (C) 2020 by Nyall Dawson
-email                : nyall dot dawson at gmail dot com
-**************************************************************************
-
-This program is free software; you can redistribute it and/or modify  *
-it under the terms of the GNU General Public License as published by  *
-the Free Software Foundation; either version 2 of the License, or     *
-(at your option) any later version.                                   *
-
-**************************************************************************
+
+A reusable window for editing simple spreadsheet-style tables.
+
+Table content is retrieved and set using the QgsTableContents class. The editor
+has support for table foreground and background colors, and numeric formats.
+
+.. versionadded:: 3.12
 %End
 
 %TypeHeaderCode
 #include "qgstableeditordialog.h"
 %End
   public:
+
     QgsTableEditorDialog( QWidget *parent = 0 );
-    void setTableData( const QgsTableContents &contents );
-    QgsTableContents tableData() const;
+%Docstring
+Constructor for QgsTableEditorDialog with the specified ``parent`` widget.
+%End
+
+    void setTableContents( const QgsTableContents &contents );
+%Docstring
+Sets the ``contents`` to show in the editor widget.
+
+.. seealso:: :py:func:`tableContents`
+%End
+
+    QgsTableContents tableContents() const;
+%Docstring
+Returns the current contents of the editor widget table.
+
+.. seealso:: :py:func:`setTableContents`
+%End
 
   signals:
 
     void tableChanged();
+%Docstring
+Emitted whenever the table contents are changed.
+%End
 
 };
 

diff --git a/python/gui/auto_generated/tableeditor/qgstableeditorwidget.sip.in b/python/gui/auto_generated/tableeditor/qgstableeditorwidget.sip.in
@@ -10,46 +10,154 @@
 
 class QgsTableEditorWidget : QTableWidget
 {
+%Docstring
+
+A reusable widget for editing simple spreadsheet-style tables.
+
+Table content is retrieved and set using the QgsTableContents class. The editor
+has support for table foreground and background colors, and numeric formats.
+
+.. versionadded:: 3.12
+%End
 
 %TypeHeaderCode
 #include "qgstableeditorwidget.h"
 %End
   public:
 
-    enum Roles
-    {
-      PresetBackgroundColorRole,
+    QgsTableEditorWidget( QWidget *parent /TransferThis/ = 0 );
+%Docstring
+Constructor for QgsTableEditorWidget with the specified ``parent`` widget.
+%End
+    ~QgsTableEditorWidget();
 
-    };
+    void setTableContents( const QgsTableContents &contents );
+%Docstring
+Sets the ``contents`` to show in the editor widget.
 
-    QgsTableEditorWidget( QWidget *parent = 0 );
-    ~QgsTableEditorWidget();
+.. seealso:: :py:func:`tableContents`
+%End
+
+    QgsTableContents tableContents() const;
+%Docstring
+Returns the current contents of the editor widget table.
 
-    void setTableData( const QgsTableContents &contents );
-    QgsTableContents tableData() const;
+.. seealso:: :py:func:`setTableContents`
+%End
 
-    void setCellNumericFormat( QgsNumericFormat *format /Transfer/ );
+    void setSelectionNumericFormat( QgsNumericFormat *format /Transfer/ );
+%Docstring
+Sets the numeric ``format`` to use for the currently selected cells.
 
-    QColor selectedCellForegroundColor();
+Ownership of ``format`` is transferred to the widget.
+%End
 
-    QColor selectedCellBackgroundColor();
+    QColor selectionForegroundColor();
+%Docstring
+Returns the foreground color for the currently selected cells.
+
+If the selected cells have a mix of different foreground colors then an
+invalid color will be returned.
+
+.. seealso:: :py:func:`setSelectionForegroundColor`
+
+.. seealso:: :py:func:`selectionBackgroundColor`
+%End
+
+    QColor selectionBackgroundColor();
+%Docstring
+Returns the background color for the currently selected cells.
+
+If the selected cells have a mix of different background colors then an
+invalid color will be returned.
+
+.. seealso:: :py:func:`setSelectionBackgroundColor`
+
+.. seealso:: :py:func:`selectionForegroundColor`
+%End
 
   public slots:
 
     void insertRowsBelow();
+%Docstring
+Inserts new rows below the current selection.
+
+.. seealso:: :py:func:`insertRowsAbove`
+%End
+
     void insertRowsAbove();
+%Docstring
+Inserts new rows above the current selection.
+
+.. seealso:: :py:func:`insertRowsBelow`
+%End
+
     void insertColumnsBefore();
+%Docstring
+Inserts new columns before the current selection.
+
+.. seealso:: :py:func:`insertColumnsAfter`
+%End
+
     void insertColumnsAfter();
+%Docstring
+Inserts new columns after the current selection.
+
+.. seealso:: :py:func:`insertColumnsBefore`
+%End
+
     void deleteRows();
+%Docstring
+Deletes all rows associated with the current selected cells.
+
+.. seealso:: :py:func:`deleteColumns`
+%End
+
     void deleteColumns();
+%Docstring
+Deletes all columns associated with the current selected cells.
+
+.. seealso:: :py:func:`deleteRows`
+%End
+
+    void expandRowSelection();
+%Docstring
+Expands out the selection to include whole rows associated with the
+current selected cells.
+
+.. seealso:: :py:func:`expandColumnSelection`
+%End
+
+    void expandColumnSelection();
+%Docstring
+Expands out the selection to include whole columns associated with the
+current selected cells.
+
+.. seealso:: :py:func:`expandRowSelection`
+%End
 
-    void selectRows();
-    void selectColumns();
     void clearSelectedCells();
+%Docstring
+Clears the contents of the currently selected cells.
+%End
 
-    void setCellForegroundColor( const QColor &color );
-    void setCellBackgroundColor( const QColor &color );
+    void setSelectionForegroundColor( const QColor &color );
+%Docstring
+Sets the foreground color for the currently selected cells.
+
+.. seealso:: :py:func:`selectionForegroundColor`
+
+.. seealso:: :py:func:`setSelectionBackgroundColor`
+%End
 
+    void setSelectionBackgroundColor( const QColor &color );
+%Docstring
+Sets the background color for the currently selected cells.
+
+.. seealso:: :py:func:`selectionBackgroundColor`
+
+.. seealso:: :py:func:`setSelectionForegroundColor`
+%End
 
   protected:
     virtual void keyPressEvent( QKeyEvent *event );
@@ -58,7 +166,14 @@ class QgsTableEditorWidget : QTableWidget
   signals:
 
     void tableChanged();
+%Docstring
+Emitted whenever the table contents are changed.
+%End
+
     void activeCellChanged();
+%Docstring
+Emitted whenever the active (or selected) cell changes in the widget.
+%End
 
 };
 

diff --git a/src/app/layout/qgslayoutmanualtablewidget.cpp b/src/app/layout/qgslayoutmanualtablewidget.cpp
@@ -172,13 +172,13 @@ void QgsLayoutManualTableWidget::setTableContents()
     mEditorDialog = new QgsTableEditorDialog( this );
     connect( this, &QWidget::destroyed, mEditorDialog, &QMainWindow::close );
 
-    mEditorDialog->setTableData( mTable->tableContents() );
+    mEditorDialog->setTableContents( mTable->tableContents() );
     connect( mEditorDialog, &QgsTableEditorDialog::tableChanged, this, [ = ]
     {
       if ( mTable )
       {
         mTable->beginCommand( tr( "Change Table Contents" ) );
-        mTable->setTableContents( mEditorDialog->tableData() );
+        mTable->setTableContents( mEditorDialog->tableContents() );
         mTable->endCommand();
       }
     } );

diff --git a/src/gui/tableeditor/qgstableeditordialog.cpp b/src/gui/tableeditor/qgstableeditordialog.cpp
@@ -60,7 +60,7 @@ QgsTableEditorDialog::QgsTableEditorDialog( QWidget *parent )
   cc.setBackgroundColor( QColor( 255, 255, 255 ) );
   cc.setForegroundColor( QColor( 255, 0, 255 ) );
   c.last() << cc << QgsTableCell( "test4" );
-  mTableWidget->setTableData( c );
+  mTableWidget->setTableContents( c );
 
   connect( mTableWidget, &QgsTableEditorWidget::tableChanged, this, [ = ]
   {
@@ -82,17 +82,17 @@ QgsTableEditorDialog::QgsTableEditorDialog( QWidget *parent )
 
   mPropertiesDock->setFeatures( QDockWidget::NoDockWidgetFeatures );
 
-  connect( mFormattingWidget, &QgsTableEditorFormattingWidget::foregroundColorChanged, mTableWidget, &QgsTableEditorWidget::setCellForegroundColor );
-  connect( mFormattingWidget, &QgsTableEditorFormattingWidget::backgroundColorChanged, mTableWidget, &QgsTableEditorWidget::setCellBackgroundColor );
+  connect( mFormattingWidget, &QgsTableEditorFormattingWidget::foregroundColorChanged, mTableWidget, &QgsTableEditorWidget::setSelectionForegroundColor );
+  connect( mFormattingWidget, &QgsTableEditorFormattingWidget::backgroundColorChanged, mTableWidget, &QgsTableEditorWidget::setSelectionBackgroundColor );
   connect( mFormattingWidget, &QgsTableEditorFormattingWidget::numberFormatChanged, this, [ = ]
   {
-    mTableWidget->setCellNumericFormat( mFormattingWidget->numericFormat() );
+    mTableWidget->setSelectionNumericFormat( mFormattingWidget->numericFormat() );
   } );
 
   connect( mTableWidget, &QgsTableEditorWidget::activeCellChanged, this, [ = ]
   {
-    mFormattingWidget->setForegroundColor( mTableWidget->selectedCellForegroundColor() );
-    mFormattingWidget->setBackgroundColor( mTableWidget->selectedCellBackgroundColor() );
+    mFormattingWidget->setForegroundColor( mTableWidget->selectionForegroundColor() );
+    mFormattingWidget->setBackgroundColor( mTableWidget->selectionBackgroundColor() );
   } );
 
   addDockWidget( Qt::RightDockWidgetArea, mPropertiesDock );
@@ -104,22 +104,22 @@ QgsTableEditorDialog::QgsTableEditorDialog( QWidget *parent )
   connect( mActionInsertColumnsAfter, &QAction::triggered, mTableWidget, &QgsTableEditorWidget::insertColumnsAfter );
   connect( mActionDeleteRows, &QAction::triggered, mTableWidget, &QgsTableEditorWidget::deleteRows );
   connect( mActionDeleteColumns, &QAction::triggered, mTableWidget, &QgsTableEditorWidget::deleteColumns );
-  connect( mActionSelectRow, &QAction::triggered, mTableWidget, &QgsTableEditorWidget::selectRows );
-  connect( mActionSelectColumn, &QAction::triggered, mTableWidget, &QgsTableEditorWidget::selectColumns );
+  connect( mActionSelectRow, &QAction::triggered, mTableWidget, &QgsTableEditorWidget::expandRowSelection );
+  connect( mActionSelectColumn, &QAction::triggered, mTableWidget, &QgsTableEditorWidget::expandColumnSelection );
   connect( mActionSelectAll, &QAction::triggered, mTableWidget, &QgsTableEditorWidget::selectAll );
   connect( mActionClear, &QAction::triggered, mTableWidget, &QgsTableEditorWidget::clearSelectedCells );
 }
 
-void QgsTableEditorDialog::setTableData( const QgsTableContents &contents )
+void QgsTableEditorDialog::setTableContents( const QgsTableContents &contents )
 {
   mBlockSignals = true;
-  mTableWidget->setTableData( contents );
+  mTableWidget->setTableContents( contents );
   mBlockSignals = false;
 }
 
-QgsTableContents QgsTableEditorDialog::tableData() const
+QgsTableContents QgsTableEditorDialog::tableContents() const
 {
-  return mTableWidget->tableData();
+  return mTableWidget->tableContents();
 }
 
 #include "qgstableeditordialog.h"
diff --git a/src/gui/tableeditor/qgstableeditordialog.h b/src/gui/tableeditor/qgstableeditordialog.h
@@ -26,26 +26,54 @@ class QgsDockWidget;
 class QgsPanelWidgetStack;
 class QgsTableEditorFormattingWidget;
 
+/**
+ * \ingroup gui
+ * \class QgsTableEditorDialog
+ *
+ * A reusable window for editing simple spreadsheet-style tables.
+ *
+ * Table content is retrieved and set using the QgsTableContents class. The editor
+ * has support for table foreground and background colors, and numeric formats.
+ *
+ * \since QGIS 3.12
+ */
 class GUI_EXPORT QgsTableEditorDialog : public QMainWindow, private Ui::QgsTableEditorBase
 {
     Q_OBJECT
   public:
+
+    /**
+     * Constructor for QgsTableEditorDialog with the specified \a parent widget.
+     */
     QgsTableEditorDialog( QWidget *parent = nullptr );
-    void setTableData( const QgsTableContents &contents );
-    QgsTableContents tableData() const;
+
+    /**
+     * Sets the \a contents to show in the editor widget.
+     *
+     * \see tableContents()
+     */
+    void setTableContents( const QgsTableContents &contents );
+
+    /**
+     * Returns the current contents of the editor widget table.
+     *
+     * \see setTableContents()
+     */
+    QgsTableContents tableContents() const;
 
   signals:
 
+    /**
+     * Emitted whenever the table contents are changed.
+     */
     void tableChanged();
 
   private:
     QgsTableEditorWidget *mTableWidget = nullptr;
-
     QgsMessageBar *mMessageBar = nullptr;
     QgsDockWidget *mPropertiesDock = nullptr;
     QgsPanelWidgetStack *mPropertiesStack = nullptr;
     QgsTableEditorFormattingWidget *mFormattingWidget = nullptr;
-
     bool mBlockSignals = false;
 };