Class: QgsDirectoryItem

A browser item for directories: contains subdirectories and layers.

Class Hierarchy

Inheritance diagram of qgis.core.QgsDirectoryItem

Base classes

QgsDataCollectionItem

A browser item for collections of data.

QgsDataItem

Base class for all items in the model.

QObject

Methods

dirPath

Returns the full path to the directory the item represents.

directoryChanged

iconColor

Returns the directory's icon color.

isMonitored

Returns True if the directory is currently being monitored for changes and the item auto-refreshed when these occur.

monitoring

Returns the monitoring setting for this directory item.

setIconColor

Sets the directory's icon color.

setMonitoring

Sets the monitoring setting for this directory.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsDirectoryItem. See the FAQ for more details.

paramWidget

Static Methods

hiddenPath

Check if the given path is hidden from the browser model

monitoringForPath

Returns the monitoring setting for a directory path.

pathShouldByMonitoredByDefault

Returns True if a directory path should be monitored by default.

setCustomColor

Sets a custom icon color to use for the items for the corresponding directory path.

class qgis.core.QgsDirectoryItem[source]

Bases: QgsDataCollectionItem

__init__(parent: QgsDataItem | None, name: str | None, path: str | None)

Constructor for QgsDirectoryItem, with the specified parent item.

The name argument specifies the text to show in the model for the item. This is usually the directory name, but in certain cases may differ for special directories (e.g. “Home”). If a non-directory-name text is used, it should be a translated string when appropriate.

The path argument specifies the directory path in the file system (e.g. “/home/gsherman/stuff”). A valid directory path must be specified.

Parameters:
  • parent (Optional[QgsDataItem])

  • name (Optional[str])

  • path (Optional[str])

__init__(parent: QgsDataItem | None, name: str | None, dirPath: str | None, path: str | None, providerKey: str | None = '')

Constructor for QgsDirectoryItem, with the specified parent item.

The name argument specifies the text to show in the model for the item. This is usually the directory name, but in certain cases may differ for special directories (e.g. “Home”). If a non-directory-name text is used, it should be a translated string when appropriate.

The dirPath argument specifies the directory path in the file system (e.g. “/home/gsherman/stuff”). A valid directory path must be specified.

The path argument gives the item path in the browser tree. The path string can take any form, but is usually the same as dirPath or dirPath with a prefix, e.g. “favorites:/home/gsherman/Downloads”). QgsDirectoryItem items pointing to different dirPaths should always use a different item path.

The optional providerKey string can be used to specify the key for the QgsDataItemProvider that created this item.

Parameters:
  • parent (Optional[QgsDataItem])

  • name (Optional[str])

  • dirPath (Optional[str])

  • path (Optional[str])

  • providerKey (Optional[str] = '')

dirPath(self) str[source]

Returns the full path to the directory the item represents.

Return type:

str

directoryChanged(self)[source]
static hiddenPath(path: str | None) bool[source]

Check if the given path is hidden from the browser model

Parameters:

path (Optional[str])

Return type:

bool

iconColor(self) QColor[source]

Returns the directory’s icon color.

An invalid color will be returned if the default icon color is used.

See also

setIconColor()

Added in version 3.20.

Return type:

QColor

isMonitored(self) bool[source]

Returns True if the directory is currently being monitored for changes and the item auto-refreshed when these occur.

Added in version 3.20.

Return type:

bool

monitoring(self) Qgis.BrowserDirectoryMonitoring[source]

Returns the monitoring setting for this directory item.

See also

setMonitoring()

Added in version 3.20.

Return type:

Qgis.BrowserDirectoryMonitoring

static monitoringForPath(path: str | None) Qgis.BrowserDirectoryMonitoring[source]

Returns the monitoring setting for a directory path.

This method returns the monitoring setting for path only. If no explicit monitoring setting is in place for the path then Qgis.BrowserDirectoryMonitoring.Default is returned.

This method does not consider the monitoring setting of parent directories.

Added in version 3.20.

Parameters:

path (Optional[str])

Return type:

Qgis.BrowserDirectoryMonitoring

virtual paramWidget(self) QWidget | None[source]

Deprecated since version 3.20.

Return type:

Optional[QWidget]

static pathShouldByMonitoredByDefault(path: str | None) bool[source]

Returns True if a directory path should be monitored by default.

In the absence of any other settings this will dictate whether the directory is monitored. This method does not consider an explicit monitoring setting set for the path, which can be determined by calling monitoringForPath().

All parent directories will be checked to determine whether they have monitoring manually enabled or disabled. As soon as a parent directory is found which has monitoring manually enabled or disabled then the corresponding value will be returned.

If no explicit setting is in place for a parent directory, then a check will be made to determine whether the path resides on a known slow drive. If so, monitoring is disabled by default and False will be returned. Otherwise paths are monitored by default and the function will return True.

See also

isMonitored()

See also

setMonitoring()

Added in version 3.20.

Parameters:

path (Optional[str])

Return type:

bool

static setCustomColor(directory: str | None, color: QColor | Qt.GlobalColor)[source]

Sets a custom icon color to use for the items for the corresponding directory path.

If color is an invalid color then the default icon color will be used.

Added in version 3.20.

Parameters:
  • directory (Optional[str])

  • color (Union[QColor, Qt.GlobalColor])

setIconColor(self, color: QColor | Qt.GlobalColor)[source]

Sets the directory’s icon color.

Setting an invalid color will cause the default icon color to be used.

This is a transient property, and will not permanently alter the directory’s colors in future QGIS sessions. Use setCustomColor() to permanently set the directory’s color.

See also

iconColor()

Added in version 3.20.

Parameters:

color (Union[QColor, Qt.GlobalColor])

setMonitoring(self, monitoring: Qgis.BrowserDirectoryMonitoring)[source]

Sets the monitoring setting for this directory.

This is a persistent setting, which is saved in QSettings.

See also

monitoring()

Added in version 3.20.

Parameters:

monitoring (Qgis.BrowserDirectoryMonitoring)