delegates

_delegates ¶

Custom item delegates for tree/list views.

Classes:

Name	Description
`FXColorLabelDelegate`	A custom delegate to paint items with specific colors and icons based
`FXItemDelegate`	Minimal delegate that enables QIcon mode switching on hover/selection.
`FXThumbnailDelegate`	Custom item delegate for showing thumbnails in tree/list views.

Classes¶

FXColorLabelDelegate ¶

FXColorLabelDelegate(
    colors_icons: Dict[str, Tuple[QColor, QColor, QColor, QIcon, bool]],
    parent: Optional[QWidget] = None,
    margin_left: int = 2,
    margin_top: Optional[int] = None,
    margin_bottom: Optional[int] = None,
)

Bases: FXThemeAware, QStyledItemDelegate


              flowchart TD
              fxgui.fxwidgets._delegates.FXColorLabelDelegate[FXColorLabelDelegate]
              fxgui.fxstyle.FXThemeAware[FXThemeAware]

                              fxgui.fxstyle.FXThemeAware --> fxgui.fxwidgets._delegates.FXColorLabelDelegate
                


              click fxgui.fxwidgets._delegates.FXColorLabelDelegate href "" "fxgui.fxwidgets._delegates.FXColorLabelDelegate"
              click fxgui.fxstyle.FXThemeAware href "" "fxgui.fxstyle.FXThemeAware"

A custom delegate to paint items with specific colors and icons based on their text content.

Note

This delegate automatically refreshes when the theme changes, ensuring that default colors (for items without explicit color mappings) stay in sync with the current theme.

Initializes the delegate with a dictionary of colors and icons.

Parameters:

Name	Type	Description	Default
`colors_icons` ¶	`Dict[str, Tuple[QColor, QColor, QColor, QIcon, bool]]`	A dictionary where keys are text patterns and values are tuples containing background color, border color, text/icon color, icon, and a boolean indicating if the icon should be colored.	required
`parent` ¶	`Optional[QWidget]`	The parent object.	`None`
`margin_left` ¶	`int`	The left margin for the text and icon. Defaults to 2.	`2`
`margin_top` ¶	`Optional[int]`	The top margin for the text and icon. Defaults to `margin_left`.	`None`
`margin_bottom` ¶	`Optional[int]`	The bottom margin for the text and icon. Defaults to `margin_left`.	`None`

Methods:

Name	Description
`paint`	Paints the item with the specified colors and icons.
`sizeHint`	Provides the size hint for the item.

Methods:¶

paint ¶

paint(
    painter: QPainter, option: QStyleOptionViewItem, index: QModelIndex
) -> None

Paints the item with the specified colors and icons.

Parameters:

Name	Type	Description	Default
`painter` ¶	`QPainter`	The painter used to draw the item.	required
`option` ¶	`QStyleOptionViewItem`	The style options for the item.	required
`index` ¶	`QModelIndex`	The model index of the item.	required

sizeHint ¶

sizeHint(option: QStyleOptionViewItem, index: QModelIndex) -> QSize

Provides the size hint for the item.

Parameters:

Name	Type	Description	Default
`option` ¶	`QStyleOptionViewItem`	The style options for the item.	required
`index` ¶	`QModelIndex`	The model index of the item.	required

Returns:

Type	Description
`QSize`	The size hint for the item.

FXItemDelegate ¶

Bases: QStyledItemDelegate


              flowchart TD
              fxgui.fxwidgets._delegates.FXItemDelegate[FXItemDelegate]

              

              click fxgui.fxwidgets._delegates.FXItemDelegate href "" "fxgui.fxwidgets._delegates.FXItemDelegate"

Minimal delegate that enables QIcon mode switching on hover/selection.

Qt's default item view painting only uses QIcon.Selected for selected items. This delegate adds QIcon.Active support for hover states, making icons change color when items are hovered.

This is a drop-in replacement for QStyledItemDelegate with no layout changes. Apply it to any QListView, QTreeView, or QTableView for icon color switching.

Examples:

>>> from fxgui import fxwidgets
>>> list_widget = QListWidget()
>>> list_widget.setItemDelegate(fxwidgets.FXItemDelegate())

FXThumbnailDelegate ¶

FXThumbnailDelegate(parent: Optional[QWidget] = None)

Bases: FXThemeAware, QStyledItemDelegate


              flowchart TD
              fxgui.fxwidgets._delegates.FXThumbnailDelegate[FXThumbnailDelegate]
              fxgui.fxstyle.FXThemeAware[FXThemeAware]

                              fxgui.fxstyle.FXThemeAware --> fxgui.fxwidgets._delegates.FXThumbnailDelegate
                


              click fxgui.fxwidgets._delegates.FXThumbnailDelegate href "" "fxgui.fxwidgets._delegates.FXThumbnailDelegate"
              click fxgui.fxstyle.FXThemeAware href "" "fxgui.fxstyle.FXThemeAware"

Custom item delegate for showing thumbnails in tree/list views.

This delegate displays items with thumbnails, titles, descriptions, and status indicators. Descriptions may be written in Markdown, which is rendered as plain text. Additionally, it supports custom background colors via Qt.BackgroundRole with rounded corners and borders for visual hierarchy.

Note

Store data in items using the following roles: - Qt.BackgroundRole (QColor/QBrush): Custom background color with rounded corners and border. - Qt.DecorationRole (QIcon): Icon for items without thumbnails. - Qt.UserRole + 1 (bool): Whether to show the thumbnail. - Qt.UserRole + 2 (str): Path to the thumbnail image. - Qt.UserRole + 3 (str): Description text (supports Markdown). - Qt.UserRole + 4 (QColor): Status dot indicator color. - Qt.UserRole + 5 (QColor): Status label background color. - Qt.UserRole + 6 (str): Status label text. - Qt.UserRole + 7 (bool): Whether to show the status dot. - Qt.UserRole + 8 (bool): Whether to show the status label. - Qt.UserRole + 9 (QIcon): Status label icon (displayed before text).

This delegate claims Qt.UserRole + 1 through Qt.UserRole + 12. A view that stamps roles of its own on the same items must derive them from FIRST_FREE_ROLE rather than guess a margin past that range.

Properties

show_thumbnail: Whether to show thumbnails globally. show_status_dot: Whether to show the status dot indicator globally. show_status_label: Whether to show the status label globally.

Note

Global properties and per-item roles work together: - An element is shown only if BOTH global property is True AND per-item role is True (or None/unset). - Setting per-item role to False hides that element for that item.

Note

Column 0 is laid out from both edges. The thumbnail (or the decoration icon) sits at the left, the title and description follow it, and the status label pill and the status dot are anchored to the row's right edge, the pill left of the dot. The text stops short of both of them and of the child count badge in the bottom-right corner, so it never runs underneath any of the three.

Note

Because the indicators are right-anchored, they walk left as the column narrows, and past a point they would reach the thumbnail. apply_minimum_thumbnail_width(view) stops the column there: it keeps column 0 at or above the thumbnail's full span plus whatever indicator space the rows actually show. sizeHint reports the same floor, so a view that sizes to contents already has the room.

Note

When using custom backgrounds (Qt.BackgroundRole), call FXThumbnailDelegate.apply_transparent_selection(view) to disable the native Qt selection/hover highlighting, allowing the delegate's custom highlighting to be visible.

Examples:

>>> from fxgui import fxwidgets
>>> from qtpy.QtWidgets import QTreeWidget, QTreeWidgetItem
>>> from qtpy.QtCore import Qt
>>> from qtpy.QtGui import QColor
>>>
>>> tree = QTreeWidget()
>>> delegate = fxwidgets.FXThumbnailDelegate()
>>> delegate.show_thumbnail = True
>>> delegate.show_status_dot = True
>>> delegate.show_status_label = True
>>> tree.setItemDelegate(delegate)
>>>
>>> item = QTreeWidgetItem(tree, ["My Item"])
>>> item.setData(0, fxwidgets.FXThumbnailDelegate.THUMBNAIL_VISIBLE_ROLE, True)
>>> item.setData(0, fxwidgets.FXThumbnailDelegate.THUMBNAIL_PATH_ROLE, "/path/to/image.png")
>>> item.setData(0, fxwidgets.FXThumbnailDelegate.DESCRIPTION_ROLE, "**Bold** description")
>>> item.setData(0, fxwidgets.FXThumbnailDelegate.STATUS_DOT_COLOR_ROLE, QColor("green"))
>>> # Hide status dot for this specific item
>>> item.setData(0, fxwidgets.FXThumbnailDelegate.STATUS_DOT_VISIBLE_ROLE, False)
>>> # Custom background color with rounded corners and border
>>> item.setBackground(0, QColor("#252424"))

Initialize the thumbnail delegate.

Parameters:

Name	Type	Description	Default
`parent` ¶	`Optional[QWidget]`	The parent widget.	`None`

Methods:

Name	Description
`apply_minimum_thumbnail_width`	Keep one column from shrinking below what its content needs.
`apply_transparent_selection`	Apply transparent selection stylesheet to a tree view widget.
`markdown_to_plain_text`	Convert Markdown text to plain text by removing formatting.
`paint`	Paint the item with custom background, border, and hover/selection.
`sizeHint`	Return the size hint for the item at the given index.

Attributes:

Name	Type	Description
`show_child_count`	`bool`	Whether child count badges are shown.
`show_starred`	`bool`	Whether starred indicators are shown.
`show_status_dot`	`bool`	Whether the status dot is shown.
`show_status_label`	`bool`	Whether the status label is shown.
`show_thumbnail`	`bool`	Whether thumbnails are shown globally.

Attributes¶

show_child_count `property` `writable` ¶

show_child_count: bool

Whether child count badges are shown.

show_starred `property` `writable` ¶

show_starred: bool

Whether starred indicators are shown.

show_status_dot `property` `writable` ¶

show_status_dot: bool

Whether the status dot is shown.

show_status_label `property` `writable` ¶

show_status_label: bool

Whether the status label is shown.

show_thumbnail `property` `writable` ¶

show_thumbnail: bool

Whether thumbnails are shown globally.

Individual items can override via THUMBNAIL_VISIBLE_ROLE.

Methods:¶

apply_minimum_thumbnail_width `classmethod` ¶

apply_minimum_thumbnail_width(view: QWidget, column: int = 0) -> None

Keep one column from shrinking below what its content needs.

The status label pill and the status dot are anchored to the row's right edge, so they walk left as the column narrows and would end up on the thumbnail. This installs a floor on the given column: the thumbnail's full span plus the space the rows' indicators occupy plus the gap between the two. Dragging the section narrower than that snaps it back to the floor.

A view opts in: the delegate cannot install this itself, since it is handed a rect and never sees the header. sizeHint already reports the same floor, which covers resizeColumnToContents and ResizeToContents, but a size hint does not stop a person dragging a section by hand. QHeaderView.setMinimumSectionSize cannot serve either: it applies to every section, so the wide floor column 0 needs would also be forced on the narrow columns beside it.

The floor is measured from the model each time a resize would breach it, walking the rows that are laid out (expanded branches only), so it follows the widest pill the view currently shows.

Parameters:

Name	Type	Description	Default
`view` ¶	`QWidget`	The tree view whose header should be constrained.	required
`column` ¶	`int`	The column to constrain. Defaults to 0.	`0`

Examples:

>>> from fxgui import fxwidgets
>>> from qtpy.QtWidgets import QTreeWidget
>>> tree = QTreeWidget()
>>> tree.setItemDelegate(fxwidgets.FXThumbnailDelegate())
>>> fxwidgets.FXThumbnailDelegate.apply_minimum_thumbnail_width(
...     tree
... )

apply_transparent_selection `staticmethod` ¶

apply_transparent_selection(view: QWidget) -> None

Apply transparent selection stylesheet to a tree view widget.

This method disables the default Qt selection/hover backgrounds by applying a comprehensive stylesheet directly to the widget. The delegate handles all selection and hover highlighting itself.

Call this on QTreeView/QTreeWidget instances that use custom backgrounds with FXThumbnailDelegate.

Parameters:

Name	Type	Description	Default
`view` ¶	`QWidget`	The tree view widget to apply transparent selection to.	required

markdown_to_plain_text `staticmethod` ¶

markdown_to_plain_text(text: str) -> str

Convert Markdown text to plain text by removing formatting.

Parameters:

Name	Type	Description	Default
`text` ¶	`str`	Markdown-formatted text.	required

Returns:

Type	Description
`str`	Plain text with Markdown formatting removed.

paint ¶

paint(
    painter: QPainter, option: QStyleOptionViewItem, index: QModelIndex
) -> None

Paint the item with custom background, border, and hover/selection.

This method handles all painting consistently across all items and columns, ensuring hover and selection highlighting looks the same everywhere. It supports custom background colors via Qt.BackgroundRole with rounded corners and borders.

Parameters:

Name	Type	Description	Default
`painter` ¶	`QPainter`	The painter to use for drawing.	required
`option` ¶	`QStyleOptionViewItem`	The style options for the item.	required
`index` ¶	`QModelIndex`	The model index of the item.	required

sizeHint ¶

sizeHint(option: QStyleOptionViewItem, index: QModelIndex) -> QSize

Return the size hint for the item at the given index.

Parameters:

Name	Type	Description	Default
`option` ¶	`QStyleOptionViewItem`	The style options for the item.	required
`index` ¶	`QModelIndex`	The model index of the item.	required

Returns:

Type	Description
`QSize`	The size hint for the item.

delegates

_delegates ¶

Classes¶

FXColorLabelDelegate ¶

`colors_icons` ¶

`parent` ¶

`margin_left` ¶

`margin_top` ¶

`margin_bottom` ¶

Methods:¶

paint ¶

sizeHint ¶

FXItemDelegate ¶

FXThumbnailDelegate ¶

`parent` ¶

Attributes¶

show_child_count `property` `writable` ¶

show_starred `property` `writable` ¶

show_status_dot `property` `writable` ¶

show_status_label `property` `writable` ¶

show_thumbnail `property` `writable` ¶

Methods:¶

apply_minimum_thumbnail_width `classmethod` ¶

apply_transparent_selection `staticmethod` ¶

markdown_to_plain_text `staticmethod` ¶

paint ¶

sizeHint ¶

delegates

_delegates ¶

Classes¶

FXColorLabelDelegate ¶

colors_icons ¶

parent ¶

margin_left ¶

margin_top ¶

margin_bottom ¶

Methods:¶

paint ¶

sizeHint ¶

FXItemDelegate ¶

FXThumbnailDelegate ¶

parent ¶

Attributes¶

show_child_count property writable ¶

show_starred property writable ¶

show_status_dot property writable ¶

show_status_label property writable ¶

show_thumbnail property writable ¶

Methods:¶

apply_minimum_thumbnail_width classmethod ¶

apply_transparent_selection staticmethod ¶

markdown_to_plain_text staticmethod ¶

paint ¶

sizeHint ¶

`colors_icons` ¶

`parent` ¶

`margin_left` ¶

`margin_top` ¶

`margin_bottom` ¶

`parent` ¶

show_child_count `property` `writable` ¶

show_starred `property` `writable` ¶

show_status_dot `property` `writable` ¶

show_status_label `property` `writable` ¶

show_thumbnail `property` `writable` ¶

apply_minimum_thumbnail_width `classmethod` ¶

apply_transparent_selection `staticmethod` ¶

markdown_to_plain_text `staticmethod` ¶