API documentation all over

qgis · Nov 20, 2017 · f084fc0 · f084fc0
1 parent 3d2b69e
commit f084fc0
Show file tree

Hide file tree

Showing 19 changed files with 233 additions and 97 deletions.
diff --git a/python/core/qgsaggregatecalculator.sip b/python/core/qgsaggregatecalculator.sip
@@ -28,9 +28,9 @@ class QgsAggregateCalculator
 
     struct AggregateInfo
     {
-      QString function;
-      QString name;
-      QSet<QVariant::Type> supportedTypes;
+      QString function; //!< The expression function
+      QString name; //!< A translated, human readable name
+      QSet<QVariant::Type> supportedTypes; //!< This aggregate function can only be used with these datatypes
     };
 
     enum Aggregate

diff --git a/python/gui/editorwidgets/core/qgssearchwidgetwrapper.sip b/python/gui/editorwidgets/core/qgssearchwidgetwrapper.sip
@@ -60,14 +60,8 @@
 class QgsSearchWidgetWrapper : QgsWidgetWrapper
 {
 %Docstring
- Manages an editor widget
- Widget and wrapper share the same parent
 
- A wrapper controls one attribute editor widget and is able to create a default
- widget or use a pre-existent widget. It is able to set the widget to the value implied
- by a field of a vector layer, or return the value it currently holds. Every time it is changed
- it has to emit a valueChanged signal. If it fails to do so, there is no guarantee that the
- changed status of the widget will be saved.
+ Shows a search widget on a filter form.
 %End
 
 %TypeHeaderCode
@@ -171,22 +165,30 @@ class QgsSearchWidgetWrapper : QgsWidgetWrapper
 
     QString createFieldIdentifier() const;
 %Docstring
+ Get a field name or expression to use as field comparison.
+ If in SearchMode returns a quoted field identifier.
+ If in AggregateSearchMode returns an appropriate aggregate expression.
+
+.. versionadded:: 3.2
  :rtype: str
 %End
 
-
-
     QString aggregate() const;
 %Docstring
+ If in AggregateSearch mode, which aggregate should be used to construct
+ the filter expression. Is a Null String if none.
+
+.. versionadded:: 3.2
  :rtype: str
 %End
-    void setAggregate( const QString &aggregate );
 
-    QgsRelation aggregateRelation() const;
+    void setAggregate( const QString &aggregate );
 %Docstring
- :rtype: QgsRelation
+ If in AggregateSearch mode, which aggregate should be used to construct
+ the filter expression. Is a Null String if none.
+
+.. versionadded:: 3.2
 %End
-    void setAggregateRelation( const QgsRelation &aggregateRelation );
 
   public slots:
 

diff --git a/python/gui/editorwidgets/qgsrelationaggregatesearchwidgetwrapper.sip b/python/gui/editorwidgets/qgsrelationaggregatesearchwidgetwrapper.sip
@@ -13,27 +13,23 @@
 class QgsRelationAggregateSearchWidgetWrapper : QgsSearchWidgetWrapper
 {
 %Docstring
-*************************************************************************
-qgsrelationaggregatesearchwidget.h
------------------------------
-Date                 : Nov 2017
-Copyright            : (C) 2017 Matthias Kuhn
-Email                : matthias@opengis.ch
-**************************************************************************
-                                                                         *
-   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.                                   *
-                                                                         *
-**************************************************************************
+
+ Search widget for the children of a relation.
+ For each attribute of the child, an additional QgsAggregateToolButton will be shown
+ to determine how the values should be aggregated for searching.
+
+.. versionadded:: 3.2
 %End
 
 %TypeHeaderCode
 #include "qgsrelationaggregatesearchwidgetwrapper.h"
 %End
   public:
-    explicit QgsRelationAggregateSearchWidgetWrapper( QgsVectorLayer *vl, QgsRelationWidgetWrapper *wrapper, QWidget *parent /TransferThis/ = 0 );
+
+    explicit QgsRelationAggregateSearchWidgetWrapper( QgsVectorLayer *layer, QgsRelationWidgetWrapper *wrapper, QWidget *parent /TransferThis/ = 0 );
+%Docstring
+ Constructor
+%End
 
     virtual QString expression() const;
 

diff --git a/python/gui/editorwidgets/qgsrelationwidgetwrapper.sip b/python/gui/editorwidgets/qgsrelationwidgetwrapper.sip
@@ -73,6 +73,9 @@ class QgsRelationWidgetWrapper : QgsWidgetWrapper
 
     QgsRelation relation() const;
 %Docstring
+ The relation for which this wrapper is created.
+
+.. versionadded:: 3.2
  :rtype: QgsRelation
 %End
 

diff --git a/python/gui/qgsaggregatetoolbutton.sip b/python/gui/qgsaggregatetoolbutton.sip
@@ -12,50 +12,67 @@
 class QgsAggregateToolButton : QToolButton
 {
 %Docstring
-*************************************************************************
-qgsaggregatetoolbutton.h
---------------------------------------
-Date                 : Nov 2017
-Copyright            : (C) 2017 Matthias Kuhn
-Email                : matthias@opengis.ch
-**************************************************************************
-                                                                         *
-   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.                                   *
-                                                                         *
-**************************************************************************
+
+ Offers a toolbutton to choose between different aggregate functions.
+ Functions are filtered based on the type.
+
+.. versionadded:: 3.2
 %End
 
 %TypeHeaderCode
 #include "qgsaggregatetoolbutton.h"
 %End
   public:
+
     QgsAggregateToolButton();
+%Docstring
+ Constructor
+%End
 
     void setType( QVariant::Type type );
+%Docstring
+ Based on the ``type`` of underlying data, some aggregates will be available or not.
+%End
 
     QVariant::Type type() const;
 %Docstring
+ Based on the ``type`` of underlying data, some aggregates will be available or not.
  :rtype: QVariant.Type
 %End
 
     void setActive( bool active );
+%Docstring
+ When this flag is false, the aggregate will be deactivated. I.e. no aggregate is chosen.
+%End
+
     bool active() const;
 %Docstring
+ When this flag is false, the aggregate will be deactivated. I.e. no aggregate is chosen.
  :rtype: bool
 %End
 
     QString aggregate() const;
 %Docstring
+ The function name of the selected aggregate or a Null String if none is chosen.
  :rtype: str
 %End
+
     void setAggregate( const QString &aggregate );
+%Docstring
+ The function name of the selected aggregate or a Null String if none is chosen.
+%End
 
   signals:
+
     void aggregateChanged();
+%Docstring
+ The function name of the selected aggregate has changed.
+%End
+
     void activeChanged();
+%Docstring
+ A function has been selected or unselected.
+%End
 
 };
 

diff --git a/python/gui/qgsattributeform.sip b/python/gui/qgsattributeform.sip
@@ -126,6 +126,11 @@ class QgsAttributeForm : QWidget
 
     QString aggregateFilter() const;
 %Docstring
+ The aggregate filter is only useful if the form is in AggregateFilter mode.
+ In this case it will return a combined expression according to the chosen filters
+ on all attribute widgets.
+
+.. versionadded:: 3.2
  :rtype: str
 %End
 

diff --git a/python/gui/qgsattributeformrelationeditorwidget.sip b/python/gui/qgsattributeformrelationeditorwidget.sip
@@ -9,30 +9,25 @@
 
 
 
+
 class QgsAttributeFormRelationEditorWidget : QgsAttributeFormWidget
 {
 %Docstring
-*************************************************************************
-qgsattributeformrelationeditorwidget.h
---------------------------------------
-Date                 : Nov 2017
-Copyright            : (C) 2017 Matthias Kuhn
-Email                : matthias@opengis.ch
-**************************************************************************
-                                                                         *
-   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.                                   *
-                                                                         *
-**************************************************************************
+
+ Widget to show for child relations on an attribute form.
+
+.. versionadded:: 3.2
 %End
 
 %TypeHeaderCode
 #include "qgsattributeformrelationeditorwidget.h"
 %End
   public:
+
     explicit QgsAttributeFormRelationEditorWidget( QgsRelationWidgetWrapper *wrapper, QgsAttributeForm *form );
+%Docstring
+ Constructor
+%End
 
     virtual void createSearchWidgetWrappers();
     virtual QString currentFilterExpression() const;

diff --git a/python/gui/qgsattributeformwidget.sip b/python/gui/qgsattributeformwidget.sip
@@ -11,6 +11,13 @@
 
 class QgsAttributeFormWidget : QWidget /Abstract/
 {
+%Docstring
+
+ Base class for all widgets shown on a QgsAttributeForm.
+ Consists of the widget which is visible in edit mode as well as the widget visible in search mode.
+
+.. versionadded:: 3.2
+%End
 
 %TypeHeaderCode
 #include "qgsattributeformwidget.h"
@@ -61,11 +68,13 @@ class QgsAttributeFormWidget : QWidget /Abstract/
 
     QgsVectorLayer *layer();
 %Docstring
+ The layer for which this widget and its form is shown.
  :rtype: QgsVectorLayer
 %End
 
     QgsAttributeForm *form() const;
 %Docstring
+ The form on which this widget is shown.
  :rtype: QgsAttributeForm
 %End
 
@@ -108,15 +117,7 @@ class QgsAttributeFormWidget : QWidget /Abstract/
 
 
 
-    QgsSearchWidgetToolButton *searchWidgetToolButton();
-%Docstring
- Returns a pointer to the search widget tool button in the widget.
-.. note::
 
-   this method is in place for unit testing only, and is not considered
- stable API
- :rtype: QgsSearchWidgetToolButton
-%End
 
 };
 

diff --git a/src/core/qgsaggregatecalculator.h b/src/core/qgsaggregatecalculator.h
@@ -43,11 +43,16 @@ class CORE_EXPORT QgsAggregateCalculator
 {
   public:
 
+    /**
+     * Structured information about the available aggregates.
+     *
+     * \since QGIS 3.0
+     */
     struct AggregateInfo
     {
-      QString function;
-      QString name;
-      QSet<QVariant::Type> supportedTypes;
+      QString function; //!< The expression function
+      QString name; //!< A translated, human readable name
+      QSet<QVariant::Type> supportedTypes; //!< This aggregate function can only be used with these datatypes
     };
 
     /**

diff --git a/src/gui/editorwidgets/core/qgssearchwidgetwrapper.cpp b/src/gui/editorwidgets/core/qgssearchwidgetwrapper.cpp
@@ -119,16 +119,6 @@ void QgsSearchWidgetWrapper::clearExpression()
   mExpression = QStringLiteral( "TRUE" );
 }
 
-QgsRelation QgsSearchWidgetWrapper::aggregateRelation() const
-{
-  return mAggregateRelation;
-}
-
-void QgsSearchWidgetWrapper::setAggregateRelation( const QgsRelation &aggregateRelation )
-{
-  mAggregateRelation = aggregateRelation;
-}
-
 QString QgsSearchWidgetWrapper::aggregate() const
 {
   return mAggregate;

diff --git a/src/gui/editorwidgets/core/qgssearchwidgetwrapper.h b/src/gui/editorwidgets/core/qgssearchwidgetwrapper.h
@@ -79,14 +79,8 @@ class QgsField;
 
 /**
  * \ingroup gui
- * Manages an editor widget
- * Widget and wrapper share the same parent
  *
- * A wrapper controls one attribute editor widget and is able to create a default
- * widget or use a pre-existent widget. It is able to set the widget to the value implied
- * by a field of a vector layer, or return the value it currently holds. Every time it is changed
- * it has to emit a valueChanged signal. If it fails to do so, there is no guarantee that the
- * changed status of the widget will be saved.
+ * Shows a search widget on a filter form.
  */
 class GUI_EXPORT QgsSearchWidgetWrapper : public QgsWidgetWrapper
 {
@@ -188,15 +182,30 @@ class GUI_EXPORT QgsSearchWidgetWrapper : public QgsWidgetWrapper
     // TODO QGIS 3.0 - make pure virtual
     virtual QString createExpression( FilterFlags flags ) const { Q_UNUSED( flags ); return QStringLiteral( "TRUE" ); }
 
+    /**
+     * Get a field name or expression to use as field comparison.
+     * If in SearchMode returns a quoted field identifier.
+     * If in AggregateSearchMode returns an appropriate aggregate expression.
+     *
+     * \since QGIS 3.2
+     */
     QString createFieldIdentifier() const;
 
-
-
+    /**
+     * If in AggregateSearch mode, which aggregate should be used to construct
+     * the filter expression. Is a Null String if none.
+     *
+     * \since QGIS 3.2
+     */
     QString aggregate() const;
-    void setAggregate( const QString &aggregate );
 
-    QgsRelation aggregateRelation() const;
-    void setAggregateRelation( const QgsRelation &aggregateRelation );
+    /**
+     * If in AggregateSearch mode, which aggregate should be used to construct
+     * the filter expression. Is a Null String if none.
+     *
+     * \since QGIS 3.2
+     */
+    void setAggregate( const QString &aggregate );
 
   public slots:
 

diff --git a/src/gui/editorwidgets/qgsrelationaggregatesearchwidgetwrapper.cpp b/src/gui/editorwidgets/qgsrelationaggregatesearchwidgetwrapper.cpp
@@ -17,6 +17,7 @@
 #include "qgsrelationaggregatesearchwidgetwrapper.h"
 #include "qgsattributeform.h"
 #include "qgsrelationwidgetwrapper.h"
+#include "qgslogger.h"
 
 #include <QLabel>
 
@@ -57,5 +58,6 @@ bool QgsRelationAggregateSearchWidgetWrapper::applyDirectly()
 
 void QgsRelationAggregateSearchWidgetWrapper::setExpression( const QString &value )
 {
-
+  Q_UNUSED( value )
+  QgsDebugMsg( "Not supported" );
 }