Skip to content

QColormapComboBox

A QComboBox for choosing a colormap from a list. Each item shows the colormap, and currentColormap() returns a cmap.Colormap.

Requires cmap

Colormaps come from the cmap library, which you can install with the cmap extra:

pip install "superqt[cmap]"

Colormaps can be added in any of the forms that cmap accepts: the name of a colormap in its catalog, a sequence of colors (which are interpolated), a cmap.Colormap, and others.

  • Typing in the combo box filters the colormaps (turn this off with setFilterable(False)).
  • With setUserAdditionsAllowed(True) (or allow_user_colormaps=True), an "Add Colormap..." item at the end of the list opens a dialog for choosing any colormap in the cmap catalog.
  • Right-clicking an item in the list shows a menu for removing it.

Example

QColormapComboBox QColormapComboBox
from cmap import Colormap
from qtpy.QtWidgets import QApplication

from superqt import QColormapComboBox

app = QApplication([])

# (allow_user_colormaps adds an "Add Colormap..." item, to choose from the catalog)
cmap_combo = QColormapComboBox(allow_user_colormaps=True)
# see note above about colormap-like objects
# as names from the cmap catalog
cmap_combo.addColormaps(["viridis", "plasma", "magma", "gray"])
# as a sequence of colors, linearly interpolated
cmap_combo.addColormap(("#0f0", "slateblue", "#F3A003A0"))
# as a `cmap.Colormap` instance with custom name:
cmap_combo.addColormap(Colormap(("green", "white", "orange"), name="MyMap"))

cmap_combo.show()
app.exec()

Customizing the appearance

By default, the colormap fills about a third of the combo box, next to its name, and all of the width of the items in the list. Both can be changed.

To make the colormap fill the whole width of the combo box:

cmap_combo.lineEdit().setFractionalColormapWidth(1)

(The line edit is a QColormapLineEdit.)

To make the colormaps in the list fill a third of their width:

from superqt.cmap import QColormapItemDelegate

delegate = QColormapItemDelegate(fractional_colormap_width=0.33)
cmap_combo.setItemDelegate(delegate)

QColormapComboBox

QColormapComboBox(
    parent: QWidget | None = None,
    *,
    allow_user_colormaps: bool = False,
    add_colormap_text: str = "Add Colormap...",
    filterable: bool = True,
)

A drop down menu for selecting colormaps.

Parameters:

  • parent (QWidget, default: None ) –

    The parent widget.

  • allow_user_colormaps (bool, default: False ) –

    Whether the user can add custom colormaps by clicking the "Add Colormap..." item. Default is False. Can also be set with setUserAdditionsAllowed.

  • add_colormap_text (str, default: 'Add Colormap...' ) –

    The text to display for the "Add Colormap..." item. Default is "Add Colormap...".

  • filterable (bool, default: True ) –

    Whether the user can filter colormaps by typing in the line edit. Default is True. Can also be set with setFilterable.

Subclass of QComboBox

QColormapComboBox inherits all of QComboBox's methods, signals, and properties. Only those that superqt adds or changes are listed here.

Signals

  • currentColormapChanged(Colormap)

Methods

A drop down menu for selecting colormaps.

Parameters:

  • parent (QWidget, default: None ) –

    The parent widget.

  • allow_user_colormaps (bool, default: False ) –

    Whether the user can add custom colormaps by clicking the "Add Colormap..." item. Default is False. Can also be set with setUserAdditionsAllowed.

  • add_colormap_text (str, default: 'Add Colormap...' ) –

    The text to display for the "Add Colormap..." item. Default is "Add Colormap...".

  • filterable (bool, default: True ) –

    Whether the user can filter colormaps by typing in the line edit. Default is True. Can also be set with setFilterable.

addColormap

addColormap(cmap: ColorStopsLike) -> None

Adds the colormap to the QComboBox.

addColormaps

addColormaps(colors: Sequence[Any]) -> None

Adds colors to the QComboBox.

clear

clear() -> None

currentColormap

currentColormap() -> Colormap | None

Returns the currently selected Colormap or None if not yet selected.

isFilterable

isFilterable() -> bool

Returns whether the user can filter the list of colormaps.

itemColormap

itemColormap(index: int) -> Colormap | None

Returns the color of the item at the given index.

setCurrentColormap

setCurrentColormap(color: Any) -> None

Adds the color to the QComboBox and selects it.

setFilterable

setFilterable(filterable: bool) -> None

Set whether the user can enter/filter colormaps by typing in the line edit.

If enabled, the user can select the text in the line edit and type to filter the list of colormaps. The completer will show a list of matching colormaps as the user types. If disabled, the user can only select from the combo box dropdown.

setUserAdditionsAllowed

setUserAdditionsAllowed(allow: bool) -> None

Sets whether the user can add custom colors.

If enabled, an "Add Colormap..." item will be added to the end of the list. When clicked, a dialog will be shown to allow the user to select a colormap from the cmap catalog.

userAdditionsAllowed

userAdditionsAllowed() -> bool

Returns whether the user can add custom colors.