QgsDataItem class

Base class for all items in the model.

Reference

Parent/children hierarchy is not based on QObject.

Derived classes

class QgsDataCollectionItem: A Collection: logical collection of layers or subcollections, e.g.
class QgsErrorItem: Data item that can be used to report problems (e.g.
class QgsLayerItem: Item that represents a layer that can be opened with one of the providers.
class QgsProjectItem: Data item that can be used to represent QGIS projects.

Public types

enum Capability { NoCapabilities = 0, SetCrs = 1 << 0, Fertile = 1 << 1, Fast = 1 << 2, Collapse = 1 << 3, Rename = 1 << 4, Delete = 1 << 5 }
enum State { NotPopulated, Populating, Populated }
enum Type { Collection, Directory, Layer, Error, Favorites, Project, Custom }

Public static functions

static auto pathComponent(const QString& component) -> QString: Create path component replacing path separators.

Constructors, destructors, conversion operators

QgsDataItem(QgsDataItem::Type type, QgsDataItem* parent, const QString& name, const QString& path): Create new data item.

Public functions

auto acceptDrop() -> bool virtual: Returns whether the item accepts drag and dropped layers - e.g.
auto actions(QWidget* parent) -> QList<QAction*> virtual: Returns the list of actions available for this item.
void addChildItem(QgsDataItem* child, bool refresh = false) virtual: Inserts a new child item.
auto capabilities2() const -> Capabilities virtual: Returns the capabilities for the data item.
auto createChildren() -> QVector<QgsDataItem*> virtual: Create children.
void deleteChildItem(QgsDataItem* child) virtual: Removes and deletes a child item, emitting relevant signals to the model.
auto equal(const QgsDataItem* other) -> bool virtual: Returns true if this item is equal to another item (by testing item type and path).
auto handleDoubleClick() -> bool virtual: Called when a user double clicks on the item.
auto handleDrop(const QMimeData*, Qt::DropAction) -> bool virtual: Attempts to process the mime data dropped on this item.
auto hasDragEnabled() const -> bool virtual: Returns true if the item may be dragged.
auto menus(QWidget* parent) -> QList<QMenu*> virtual: Returns the list of menus available for this item.
auto mimeUri() const -> QgsMimeDataUtils::Uri virtual: Returns mime URI for the data item.
void moveToThread(QThread* targetThread): Move object and all its descendants to thread.
auto name() const -> QString: Returns the name of the item (the displayed text for the item).
auto parent() const -> QgsDataItem*: Gets item parent.
auto removeChildItem(QgsDataItem* child) -> QgsDataItem* virtual: Removes a child item and returns it without deleting it.
auto rename(const QString& name) -> bool virtual: Sets a new name for the item, and returns true if the item was successfully renamed.
void setCapabilities(Capabilities capabilities) virtual: Sets the capabilities for the data item.
auto setCrs(const QgsCoordinateReferenceSystem& crs) -> bool virtual: Writes the selected crs into data source.
void setName(const QString& name): Sets the name of the item (the displayed text for the item).
void setParent(QgsDataItem* parent): Set item parent and connect / disconnect parent to / from item signals.
void setSortKey(const QVariant& key): Sets a custom sorting key for the item.
void setState(State state) virtual: Set item state.
auto sortKey() const -> QVariant virtual: Returns the sorting key for the item.
auto state() const -> State

Signals

void connectionsChanged(): Emitted when the provider's connections of the child items have changed This signal is normally forwarded to the app in order to refresh the connection item in the provider dialogs and to refresh the connection items in the other open browsers.

Public slots

void deleteLater() virtual: Safely delete the item:
void depopulate() virtual: Remove children recursively and set as not populated. This is used when refreshing collapsed items.
void refreshConnections() virtual: Refresh connections: update GUI and emit signal.

Protected functions

auto deferredDelete() -> bool: The item is scheduled to be deleted.
void refresh(const QVector<QgsDataItem*>& children) virtual: Refresh the items from a specified list of child items.

Protected slots

void updateIcon(): Will request a repaint of this icon.

Protected variables

QVariant mSortKey: Custom sort key. If invalid, name() will be used for sorting instead.

Enum documentation

enum QgsDataItem::Capability

Enumerators
NoCapabilities
SetCrs	Can set CRS on layer or group of layers.
Fertile	Can create children. Even items without this capability may have children, but cannot create them, it means that children are created by item ancestors.
Fast	CreateChildren() is fast enough to be run in main thread when refreshing items, most root items (wms,wfs,wcs,postgres...) are considered fast because they are reading data only from QgsSettings.
Collapse	The collapse/expand status for this items children should be ignored in order to avoid undesired network connections (wms etc.)
Rename	Item can be renamed.
Delete	Item can be deleted.

enum QgsDataItem::State

Enumerators
NotPopulated	Children not yet created.
Populating	Creating children in separate thread (populating or refreshing)
Populated	Children created.

enum QgsDataItem::Type

Enumerators
Collection
Directory
Layer
Error
Favorites	Represents a favorite item.
Project	Represents a QGIS project.
Custom	Custom item type.

Function documentation

bool QgsDataItem::acceptDrop() virtual

Returns whether the item accepts drag and dropped layers - e.g.

for importing a dataset to a provider. Subclasses should override this and handleDrop() to accept dropped layers.

QList<QAction> QgsDataItem::actions(QWidget parent) virtual

Returns the list of actions available for this item.

This is usually used for the popup menu on right-clicking the item. Subclasses should override this to provide actions.

Subclasses should ensure that ownership of created actions is correctly handled by parenting them to the specified parent widget.

void QgsDataItem::addChildItem(QgsDataItem* child, bool refresh = false) virtual

Inserts a new child item.

Parameters
child	child item to insert. Ownership is transferred, and item parent will be set and relevant connections made.
refresh	- set to true to refresh populated item, emitting relevant signals to the model

The child will be inserted at a position using an alphabetical order based on mName.

Capabilities QgsDataItem::capabilities2() const virtual

Returns the capabilities for the data item.

QVector<QgsDataItem*> QgsDataItem::createChildren() virtual

Create children.

Children are not expected to have parent set. This method MUST BE THREAD SAFE.

void QgsDataItem::deleteChildItem(QgsDataItem* child) virtual

Removes and deletes a child item, emitting relevant signals to the model.

Parameters
child	child to remove. Item must exist as a current child.

bool QgsDataItem::handleDoubleClick() virtual

Called when a user double clicks on the item.

Subclasses should return true if they have implemented a double-click handler and do not want the default double-click behavior for items.

bool QgsDataItem::handleDrop(const QMimeData*, Qt::DropAction) virtual

Attempts to process the mime data dropped on this item.

Subclasses must override this and acceptDrop() if they accept dropped layers.

bool QgsDataItem::hasDragEnabled() const virtual

Returns true if the item may be dragged.

Default implementation returns false. A draggable item has to implement mimeUri() that will be used to pass data.

QList<QMenu> QgsDataItem::menus(QWidget parent) virtual

Returns the list of menus available for this item.

Parameters
parent	a parent widget of the menu
Returns	list of menus

This is usually used for the popup menu on right-clicking the item. Subclasses should override this to provide actions. Subclasses should ensure that ownership of created menus is correctly handled by parenting them to the specified parent widget.

QgsMimeDataUtils::Uri QgsDataItem::mimeUri() const virtual

Returns mime URI for the data item.

Items that return valid URI will be returned in mime data when dragging a selection from browser model.

QString QgsDataItem::name() const

Returns the name of the item (the displayed text for the item).

QgsDataItem* QgsDataItem::parent() const

Gets item parent.

QgsDataItem maintains its own items hierarchy, it does not use QObject hierarchy.

QgsDataItem* QgsDataItem::removeChildItem(QgsDataItem* child) virtual

Removes a child item and returns it without deleting it.

Parameters
child	child to remove
Returns	pointer to the removed item or null if no such item was found

Emits relevant signals to model as required.

bool QgsDataItem::rename(const QString& name) virtual

Sets a new name for the item, and returns true if the item was successfully renamed.

Items which implement this method should return the QgsDataItem::Rename capability.

The default implementation does nothing.

void QgsDataItem::setCapabilities(Capabilities capabilities) virtual

Sets the capabilities for the data item.

bool QgsDataItem::setCrs(const QgsCoordinateReferenceSystem& crs) virtual

Writes the selected crs into data source.

The original data source will be modified when calling this method.

void QgsDataItem::setName(const QString& name)

Sets the name of the item (the displayed text for the item).

void QgsDataItem::setParent(QgsDataItem* parent)

Set item parent and connect / disconnect parent to / from item signals.

It does not add itself to parents children (mChildren)

void QgsDataItem::setSortKey(const QVariant& key)

Sets a custom sorting key for the item.

void QgsDataItem::setState(State state) virtual

Set item state.

Parameters
state

It also take care about starting/stopping loading icon animation.

QVariant QgsDataItem::sortKey() const virtual

Returns the sorting key for the item.

By default name() is returned, but setSortKey() can be used to set a custom sort key for the item.

Alternatively subclasses can override this method to return a custom sort key.

State QgsDataItem::state() const

void QgsDataItem::deleteLater() virtual public slot

Safely delete the item:

disconnects parent
unsets parent (but does not remove itself)
deletes all its descendants recursively
waits until Populating state (createChildren() in thread) finished without blocking main thread
calls QObject::deleteLater()

bool QgsDataItem::deferredDelete() protected

The item is scheduled to be deleted.

E.g. if deleteLater() is called when item is in Populating state (createChildren() running in another thread), the deferredDelete() returns true and item will be deleted once Populating finished. Items with slow reateChildren() (for example network or database based) may check during createChildren() if deferredDelete() returns true and return from createChildren() immediately because result will be useless.

void QgsDataItem::updateIcon() protected slot

Will request a repaint of this icon.