[composer] API docs and python bindings for QgsComposerTableV2 (spons…

…ored

by City of Uster, Switzerland)

python/core/composer/qgscomposerattributetable.sip

@@ -232,8 +232,4 @@ class QgsComposerAttributeTable : QgsComposerTable
      */
     // bool getFeatureAttributes( QList<QgsAttributeMap>& attributeMaps );
 
-
-  signals:
-    /**This signal is emitted if the maximum number of feature changes (interactively)*/
-    void maximumNumberOfFeaturesChanged( int n );
 };

python/core/composer/qgscomposerattributetablemodel.sip

@@ -19,7 +19,7 @@ class QgsComposerAttributeTableColumnModel: QAbstractTableModel
      * @param composerTable QgsComposerAttributeTable the model is attached to
      * @param parent optional parent
      */
-    QgsComposerAttributeTableColumnModel( QgsComposerAttributeTable *composerTable, QObject *parent = 0 );
+    QgsComposerAttributeTableColumnModel( QgsComposerAttributeTable *composerTable, QObject *parent /TransferThis/ = 0 );
     virtual ~QgsComposerAttributeTableColumnModel();
 
     virtual int rowCount( const QModelIndex &parent = QModelIndex() ) const;
@@ -114,7 +114,7 @@ class QgsComposerTableSortColumnsProxyModel : QSortFilterProxyModel
      * @param filterType filter for columns, controls whether sorted or unsorted columns are shown
      * @param parent optional parent
      */
-    QgsComposerTableSortColumnsProxyModel( QgsComposerAttributeTable *composerTable, ColumnFilterType filterType, QObject *parent = 0 );
+    QgsComposerTableSortColumnsProxyModel( QgsComposerAttributeTable *composerTable, ColumnFilterType filterType, QObject *parent /TransferThis/ = 0 );
 
     virtual ~QgsComposerTableSortColumnsProxyModel();
 

python/core/composer/qgscomposerattributetablemodelv2.sip

@@ -0,0 +1,164 @@
+/**A model for displaying columns shown in a QgsComposerAttributeTableV2*/
+class QgsComposerAttributeTableColumnModelV2: QAbstractTableModel
+{
+%TypeHeaderCode
+#include <qgscomposerattributetablemodelv2.h>
+%End
+
+  public:
+
+    /*! Controls whether a row/column is shifted up or down
+     */
+    enum ShiftDirection
+    {
+      ShiftUp, /*!< shift the row/column up */
+      ShiftDown /*!< shift the row/column down */
+    };
+
+    /**Constructor for QgsComposerAttributeTableColumnModel.
+    /**Constructor for QgsComposerAttributeTableColumnModel.
+     * @param composerTable QgsComposerAttributeTable the model is attached to
+     * @param parent optional parent
+     */
+    QgsComposerAttributeTableColumnModelV2( QgsComposerAttributeTableV2 *composerTable, QObject *parent /TransferThis/ = 0 );
+    virtual ~QgsComposerAttributeTableColumnModelV2();
+
+    virtual int rowCount( const QModelIndex &parent = QModelIndex() ) const;
+    int columnCount( const QModelIndex &parent = QModelIndex() ) const;
+    virtual QVariant data( const QModelIndex &index, int role ) const;
+    QVariant headerData( int section, Qt::Orientation orientation, int role = Qt::DisplayRole ) const;
+    virtual bool setData( const QModelIndex &index, const QVariant &value, int role = Qt::EditRole );
+    Qt::ItemFlags flags( const QModelIndex &index ) const;
+    bool removeRows( int row, int count, const QModelIndex &parent = QModelIndex() );
+    bool insertRows( int row, int count, const QModelIndex &parent = QModelIndex() );
+    QModelIndex index( int row, int column, const QModelIndex &parent ) const;
+    QModelIndex parent( const QModelIndex &child ) const;
+
+    /**Moves the specified row up or down in the model. Used for rearranging the attribute tables
+     * columns.
+     * @returns true if the move is allowed
+     * @param row row in model representing attribute table column to move
+     * @param direction direction to move the attribute table column
+     * @note added in 2.3
+     */
+    bool moveRow( int row , ShiftDirection direction );
+
+    /**Resets the attribute table's columns to match the source layer's fields. Remove all existing
+     * attribute table columns and column customisations.
+     * @note added in 2.3
+     */
+    void resetToLayer();
+
+    /**Returns the QgsComposerTableColumn corresponding to an index in the model.
+     * @returns QgsComposerTableColumn for specified index
+     * @param index a QModelIndex
+     * @note added in 2.3
+     * @see indexFromColumn
+     */
+    QgsComposerTableColumn* columnFromIndex( const QModelIndex & index ) const;
+
+    /**Returns a QModelIndex corresponding to a QgsComposerTableColumn in the model.
+     * @returns QModelIndex for specified QgsComposerTableColumn
+     * @param column a QgsComposerTableColumn
+     * @note added in 2.3
+     * @see columnFromIndex
+     */
+    QModelIndex indexFromColumn( QgsComposerTableColumn *column );
+
+    /**Sets a specified column as a sorted column in the QgsComposerAttributeTable. The column will be
+     * added to the end of the sort rank list, ie it will take the next largest available sort rank.
+     * @param column a QgsComposerTableColumn
+     * @param order sort order for column
+     * @note added in 2.3
+     * @see removeColumnFromSort
+     * @see moveColumnInSortRank
+     */
+    void setColumnAsSorted( QgsComposerTableColumn *column, Qt::SortOrder order );
+
+    /**Sets a specified column as an unsorted column in the QgsComposerAttributeTable. The column will be
+     * removed from the sort rank list.
+     * @param column a QgsComposerTableColumn
+     * @note added in 2.3
+     * @see setColumnAsSorted
+     */
+    void setColumnAsUnsorted( QgsComposerTableColumn * column );
+
+    /**Moves a column up or down in the sort rank for the QgsComposerAttributeTable.
+     * @param column a QgsComposerTableColumn
+     * @param direction direction to move the column in the sort rank list
+     * @note added in 2.3
+     * @see setColumnAsSorted
+     */
+    bool moveColumnInSortRank( QgsComposerTableColumn * column, ShiftDirection direction );
+
+};
+
+/**Allows for filtering QgsComposerAttributeTable columns by columns which are sorted or unsorted*/
+class QgsComposerTableSortColumnsProxyModelV2 : QSortFilterProxyModel
+{
+%TypeHeaderCode
+#include <qgscomposerattributetablemodelv2.h>
+%End
+
+  public:
+
+    /*! Controls whether the proxy model shows sorted or unsorted columns
+     */
+    enum ColumnFilterType
+    {
+      ShowSortedColumns, /*!< show only sorted columns */
+      ShowUnsortedColumns/*!< show only unsorted columns */
+    };
+
+    /**Constructor for QgsComposerTableSortColumnsProxyModel.
+     * @param composerTable QgsComposerAttributeTable the model is attached to
+     * @param filterType filter for columns, controls whether sorted or unsorted columns are shown
+     * @param parent optional parent
+     */
+    QgsComposerTableSortColumnsProxyModelV2( QgsComposerAttributeTableV2 *composerTable, ColumnFilterType filterType, QObject *parent /TransferThis/ = 0 );
+
+    virtual ~QgsComposerTableSortColumnsProxyModelV2();
+
+    bool lessThan( const QModelIndex &left, const QModelIndex &right ) const;
+    int columnCount( const QModelIndex &parent = QModelIndex() ) const;
+    virtual QVariant data( const QModelIndex &index, int role ) const;
+    QVariant headerData( int section, Qt::Orientation orientation, int role = Qt::DisplayRole ) const;
+    Qt::ItemFlags flags( const QModelIndex &index ) const;
+    virtual bool setData( const QModelIndex &index, const QVariant &value, int role = Qt::EditRole );
+
+    /**Returns the QgsComposerTableColumn corresponding to a row in the proxy model.
+     * @returns QgsComposerTableColumn for specified row
+     * @param row a row number
+     * @note added in 2.3
+     * @see columnFromIndex
+     */
+    QgsComposerTableColumn* columnFromRow( int row );
+
+    /**Returns the QgsComposerTableColumn corresponding to an index in the proxy model.
+     * @returns QgsComposerTableColumn for specified index
+     * @param index a QModelIndex
+     * @note added in 2.3
+     * @see columnFromRow
+     * @see columnFromSourceIndex
+     */
+    QgsComposerTableColumn* columnFromIndex( const QModelIndex & index ) const;
+
+    /**Returns the QgsComposerTableColumn corresponding to an index from the source
+     * QgsComposerAttributeTableColumnModel model.
+     * @returns QgsComposerTableColumn for specified index from QgsComposerAttributeTableColumnModel
+     * @param sourceIndex a QModelIndex
+     * @note added in 2.3
+     * @see columnFromRow
+     * @see columnFromIndex
+     */
+    QgsComposerTableColumn* columnFromSourceIndex( const QModelIndex& sourceIndex ) const;
+
+    /**Invalidates the current filter used by the proxy model
+     * @note added in 2.3
+     */
+    void resetFilter();
+
+  protected:
+    bool filterAcceptsRow( int source_row, const QModelIndex & source_parent ) const;
+
+};

python/core/composer/qgscomposerattributetablev2.sip

@@ -0,0 +1,180 @@
+/**Helper class for sorting tables, takes into account sorting column and ascending / descending*/
+class QgsComposerAttributeTableCompareV2
+{
+%TypeHeaderCode
+#include <qgscomposerattributetablev2.h>
+%End
+
+  public:
+
+    QgsComposerAttributeTableCompareV2();
+
+    bool operator()( const QgsComposerTableRow& m1, const QgsComposerTableRow& m2 );
+
+    /**Sets column number to sort by
+     * @param col column number for sorting
+     */
+    void setSortColumn( int col );
+
+    /**Sets sort order for column sorting
+     * @param asc set to true to sort in ascending order, false to sort in descending order
+     */
+    void setAscending( bool asc );
+
+};
+
+/**A table that displays attributes from a vector layer*/
+class QgsComposerAttributeTableV2 : QgsComposerTableV2
+{
+%TypeHeaderCode
+#include <qgscomposerattributetablev2.h>
+%End
+
+  public:
+
+    QgsComposerAttributeTableV2( QgsComposition* composition, bool createUndoCommands );
+    ~QgsComposerAttributeTableV2();
+
+    /**Writes properties specific to attribute tables
+     * @param elem an existing QDomElement in which to store the attribute table's properties.
+     * @param doc QDomDocument for the destination xml.
+     * @see readXML
+     */
+    virtual bool writeXML( QDomElement& elem, QDomDocument & doc, bool ignoreFrames = false ) const;
+
+    /**Reads the properties specific to an attribute table from xml.
+     * @param itemElem a QDomElement holding the attribute table's desired properties.
+     * @param doc QDomDocument for the source xml.
+     * @see writeXML
+     */
+    virtual bool readXML( const QDomElement& itemElem, const QDomDocument& doc, bool ignoreFrames = false );
+
+    virtual void addFrame( QgsComposerFrame* frame, bool recalcFrameSizes = true );
+
+    /**Sets the vector layer from which to display feature attributes
+     * @param layer Vector layer for attribute table
+     * @see vectorLayer
+     */
+    void setVectorLayer( QgsVectorLayer* layer );
+
+    /**Returns the vector layer the attribute table is currently using
+     * @returns attribute table's current vector layer
+     * @see setVectorLayer
+     */
+    QgsVectorLayer* vectorLayer() const;
+
+    /**Resets the attribute table's columns to match the vector layer's fields
+     * @see setVectorLayer
+     */
+    void resetColumns();
+
+    /**Sets the composer map to use to limit the extent of features shown in the
+     * attribute table. This setting only has an effect if setDisplayOnlyVisibleFeatures is
+     * set to true. Changing the composer map forces the table to refetch features from its
+     * vector layer, and may result in the table changing size to accommodate the new displayed
+     * feature attributes.
+     * @param map QgsComposerMap which drives the extents of the table's features
+     * @see composerMap
+     * @see setDisplayOnlyVisibleFeatures
+     */
+    void setComposerMap( const QgsComposerMap* map );
+
+    /**Returns the composer map whose extents are controlling the features shown in the
+     * table. The extents of the map are only used if displayOnlyVisibleFeatures() is true.
+     * @returns composer map controlling the attribute table
+     * @see setComposerMap
+     * @see displayOnlyVisibleFeatures
+     */
+    const QgsComposerMap* composerMap() const;
+
+    /**Sets the maximum number of features shown by the table. Changing this setting may result
+     * in the attribute table changing its size to accommodate the new number of rows, and requires
+     * the table to refetch features from its vector layer.
+     * @param features maximum number of features to show in the table
+     * @see maximumNumberOfFeatures
+     */
+    void setMaximumNumberOfFeatures( int features );
+
+    /**Returns the maximum number of features to be shown by the table.
+     * @returns maximum number of features
+     * @see setMaximumNumberOfFeatures
+     */
+    int maximumNumberOfFeatures() const;
+
+    /**Sets attribute table to only show features which are visible in a composer map item. Changing
+     * this setting forces the table to refetch features from its vector layer, and may result in
+     * the table changing size to accommodate the new displayed feature attributes.
+     * @param visibleOnly set to true to show only visible features
+     * @see displayOnlyVisibleFeatures
+     * @see setComposerMap
+     */
+    void setDisplayOnlyVisibleFeatures( bool visibleOnly );
+
+    /**Returns true if the table is set to show only features visible on a corresponding
+     * composer map item.
+     * @returns true if table only shows visible features
+     * @see composerMap
+     * @see setDisplayOnlyVisibleFeatures
+     */
+    bool displayOnlyVisibleFeatures() const;
+
+    /**Returns true if a feature filter is active on the attribute table
+     * @returns bool state of the feature filter
+     * @see setFilterFeatures
+     * @see featureFilter
+     */
+    bool filterFeatures() const;
+
+    /**Sets whether the feature filter is active for the attribute table. Changing
+     * this setting forces the table to refetch features from its vector layer, and may result in
+     * the table changing size to accommodate the new displayed feature attributes.
+     * @param filter Set to true to enable the feature filter
+     * @see filterFeatures
+     * @see setFeatureFilter
+     */
+    void setFilterFeatures( bool filter );
+
+    /**Returns the current expression used to filter features for the table. The filter is only
+     * active if filterFeatures() is true.
+     * @returns feature filter expression
+     * @see setFeatureFilter
+     * @see filterFeatures
+     */
+    QString featureFilter() const;
+
+    /**Sets the expression used for filtering features in the table. The filter is only
+     * active if filterFeatures() is set to true. Changing this setting forces the table
+     * to refetch features from its vector layer, and may result in
+     * the table changing size to accommodate the new displayed feature attributes.
+     * @param expression filter to use for selecting which features to display in the table
+     * @see featureFilter
+     * @see setFilterFeatures
+     */
+    void setFeatureFilter( const QString& expression );
+
+    /**Sets the attributes to display in the table.
+     * @param attr QSet of integer values refering to the attributes from the vector layer to show.
+     * Set to an empty QSet to show all feature attributes.
+     * @param refresh set to true to force the table to refetch features from its vector layer
+     * and immediately update the display of the table. This may result in the table changing size
+     * to accommodate the new displayed feature attributes.
+     * @see displayAttributes
+     */
+    void setDisplayAttributes( const QSet<int>& attr, bool refresh = true );
+
+    /**Returns the attributes used to sort the table's features.
+     * @returns a QList of integer/bool pairs, where the integer refers to the attribute index and
+     * the bool to the sort order for the attribute. If true the attribute is sorted ascending,
+     * if false, the attribute is sorted in descending order.
+     * @note not available in python bindings
+     */
+    //QList<QPair<int, bool> > sortAttributes() const;
+
+    /**Queries the attribute table's vector layer for attributes to show in the table.
+     * @param attributeMaps list of QgsAttributeMaps where the fetched feature attributes will be stored
+     * @returns true if attributes were successfully fetched
+     * @note not available in python bindings
+     */
+    bool getTableContents( QgsComposerTableContents &contents );
+
+};