Class: QgsOptionsDialogBase

A base dialog for options and properties dialogs that offers vertical tabs.

It handles saving/restoring of geometry, splitter and current tab states, switching vertical tabs between icon/text to icon-only modes (splitter collapsed to left), and connecting QDialogButtonBox’s accepted/rejected signals to dialog’s accept/reject slots

To use:

  • Start with copy of qgsoptionsdialog_template.ui and build options/properties dialog.

  • In source file for dialog, inherit this class instead of QDialog, then in constructor: … setupUi( this ); // set up .ui file objects initOptionsBase( False ); // set up this class to use .ui objects, optionally restoring base ui … restoreOptionsBaseUi(); // restore the base ui with initOptionsBase or use this later on

Class Hierarchy

Inheritance diagram of qgis.gui.QgsOptionsDialogBase

Base classes

QDialog

QWidget

QObject

QPaintDevice

Subclasses

QgsLayerPropertiesDialog

Base class for “layer properties” dialogs, containing common utilities for handling functionality in these dialogs.

Methods

addPage

Adds a new page to the dialog pages.

iconOnly

Determine if the options list is in icon only mode

initOptionsBase

Set up the base ui connections for vertical tabs.

insertPage

Inserts a new page into the dialog pages.

registerTextSearchWidgets

register widgets in the dialog to search for text in it it is automatically called if a line edit has "mSearchLineEdit" as object name.

resizeAlltabs

Resizes all tabs when the dialog is resized

restoreLastPage

Refocus the active tab from the last time the dialog was shown.

restoreOptionsBaseUi

Restore the base ui.

searchText

searchText searches for a text in all the pages of the stacked widget and highlight the results

setCurrentPage

Sets the dialog page (by object name) to show.

setSettings

warnAboutMissingObjects

Virtual Methods

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

optionsStackedWidget_CurrentChanged

Select relevant tab on current page change

optionsStackedWidget_WidgetRemoved

Remove tab and unregister widgets on page remove

updateOptionsListVerticalTabs

Update tabs on the splitter move

updateWindowTitle

class qgis.gui.QgsOptionsDialogBase[source]

Bases: QDialog

__init__(settingsKey: str | None, parent: QWidget | None = None, fl: Qt.WindowFlags | Qt.WindowType = Qt.WindowFlags(), settings: QgsSettings | None = None)

Constructor

Parameters:
  • settingsKey (Optional[str]) – QgsSettings subgroup key for saving/restore ui states, e.g. “ProjectProperties”.

  • parent (Optional[QWidget] = None) – parent object (owner)

  • fl (Union[Qt.WindowFlags, Qt.WindowType] = Qt.WindowFlags()) – widget flags

  • settings (Optional[QgsSettings] = None) – custom QgsSettings pointer

addPage(self, title: str | None, tooltip: str | None, icon: QIcon, widget: QWidget | None, path: Iterable[str | None] = [], key: str | None = '')[source]

Adds a new page to the dialog pages.

The title, tooltip and icon arguments dictate the page list item title, tooltip and icon respectively.

The page content is specified via the widget argument. Ownership of widget is transferred to the dialog.

Since QGIS 3.22, the optional path argument can be used to set the path of the item’s entry in the tree view (for dialogs which show a tree view of options pages only).

Since QGIS 3.32, the optional key argument can be used to set an untranslated key that path can refer to in following calls. Default to title.

See also

insertPage()

Added in version 3.14.

Parameters:
  • title (Optional[str])

  • tooltip (Optional[str])

  • icon (QIcon)

  • widget (Optional[QWidget])

  • path (Iterable[Optional[str]] = [])

  • key (Optional[str] = '')

iconOnly(self) bool[source]

Determine if the options list is in icon only mode

Return type:

bool

initOptionsBase(self, restoreUi: bool = True, title: str | None = '')[source]

Set up the base ui connections for vertical tabs.

Parameters:
  • restoreUi (bool = True) – Whether to restore the base ui at this time.

  • title (Optional[str] = '') – the window title

insertPage(self, title: str | None, tooltip: str | None, icon: QIcon, widget: QWidget | None, before: str | None, path: Iterable[str | None] = [], key: str | None = '')[source]

Inserts a new page into the dialog pages.

The title, tooltip and icon arguments dictate the page list item title, tooltip and icon respectively.

The page content is specified via the widget argument. Ownership of widget is transferred to the dialog.

The before argument specifies the object name of an existing page. The new page will be inserted directly before the matching page.

Since QGIS 3.22, the optional path argument can be used to set the path of the item’s entry in the tree view (for dialogs which show a tree view of options pages only).

Since QGIS 3.32, the optional key argument can be used to set an untranslated key that path can refer to in following calls. Default to title.

See also

addPage()

Added in version 3.14.

Parameters:
  • title (Optional[str])

  • tooltip (Optional[str])

  • icon (QIcon)

  • widget (Optional[QWidget])

  • before (Optional[str])

  • path (Iterable[Optional[str]] = [])

  • key (Optional[str] = '')

virtual optionsStackedWidget_CurrentChanged(self, index: int)[source]

Select relevant tab on current page change

Parameters:

index (int)

virtual optionsStackedWidget_WidgetRemoved(self, index: int)[source]

Remove tab and unregister widgets on page remove

Parameters:

index (int)

registerTextSearchWidgets(self)[source]

register widgets in the dialog to search for text in it it is automatically called if a line edit has “mSearchLineEdit” as object name.

resizeAlltabs(self, index: int)[source]

Resizes all tabs when the dialog is resized

Parameters:

index (int) – current tab index

Added in version 3.10.

restoreLastPage(self)[source]

Refocus the active tab from the last time the dialog was shown.

Added in version 3.14.

restoreOptionsBaseUi(self, title: str | None = '')[source]

Restore the base ui. Sometimes useful to do at end of subclass’s constructor.

Parameters:

title (Optional[str] = '') – the window title (it does not need to be defined if previously given to initOptionsBase();

searchText(self, text: str | None)[source]

searchText searches for a text in all the pages of the stacked widget and highlight the results

Parameters:

text (Optional[str]) – the text to search

setCurrentPage(self, page: str | None)[source]

Sets the dialog page (by object name) to show.

Added in version 3.14.

Parameters:

page (Optional[str])

setSettings(self, settings: QgsSettings | None)[source]
Parameters:

settings (Optional[QgsSettings])

virtual updateOptionsListVerticalTabs(self)[source]

Update tabs on the splitter move

virtual updateWindowTitle(self)[source]
warnAboutMissingObjects(self)[source]