Skip to content

QColorComboBox

A QComboBox for choosing a color from a list. Colors can be given as anything that QColor accepts (names, hex strings, QColors, and so on); currentColor() returns a QColor, and currentColorChanged emits one.

  • With setUserColorsAllowed(True) (or allow_user_colors=True), an "Add Color..." item at the end of the list opens a QColorDialog, and adds the chosen color.
  • setInvalidColorPolicy sets what happens when an invalid color is added: it's ignored (InvalidColorPolicy.Ignore, the default), or it causes a warning (Warn) or an exception (Raise).
QColorComboBox QColorComboBox
from qtpy.QtWidgets import QApplication

from superqt import QColorComboBox

app = QApplication([])

colors = QColorComboBox()
colors.addColors(["red", "green", "blue"])

# show an "Add Color" item that opens a QColorDialog when clicked
colors.setUserColorsAllowed(True)

# emits a QColor when changed
colors.currentColorChanged.connect(print)
colors.show()

app.exec()

QColorComboBox

QColorComboBox(
    parent: QWidget | None = None,
    *,
    allow_user_colors: bool = False,
    add_color_text: str = "Add Color...",
)

A drop down menu for selecting colors.

Parameters:

  • parent (QWidget, default: None ) –

    The parent widget.

  • allow_user_colors (bool, default: False ) –

    Whether to show an "Add Color" item that opens a QColorDialog when clicked. Whether the user can add custom colors by clicking the "Add Color" item. Default is False. Can also be set with setUserColorsAllowed.

  • add_color_text (str, default: 'Add Color...' ) –

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

Subclass of QComboBox

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

Signals

  • currentColorChanged(QColor)

Enums

QColorComboBox.InvalidColorPolicy
Ignore, Warn, Raise

Methods

A drop down menu for selecting colors.

Parameters:

  • parent (QWidget, default: None ) –

    The parent widget.

  • allow_user_colors (bool, default: False ) –

    Whether to show an "Add Color" item that opens a QColorDialog when clicked. Whether the user can add custom colors by clicking the "Add Color" item. Default is False. Can also be set with setUserColorsAllowed.

  • add_color_text (str, default: 'Add Color...' ) –

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

addColor

addColor(color: Any) -> None

Adds the color to the QComboBox.

addColors

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

Adds colors to the QComboBox.

clear

clear() -> None

Clears the QComboBox of all entries (leaves "Add colors" if enabled).

currentColor

currentColor() -> QColor | None

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

currentColorName

currentColorName() -> str | None

Returns the name of the currently selected QColor or black if None.

invalidColorPolicy

invalidColorPolicy() -> InvalidColorPolicy

Returns the policy for handling invalid colors.

itemColor

itemColor(index: int) -> QColor | None

Returns the color of the item at the given index.

setCurrentColor

setCurrentColor(color: Any) -> None

Adds the color to the QComboBox and selects it.

setInvalidColorPolicy

setInvalidColorPolicy(
    policy: InvalidColorPolicy
    | int
    | Literal["Raise", "Ignore", "Warn"],
) -> None

Sets the policy for handling invalid colors.

setUserColorsAllowed

setUserColorsAllowed(allow: bool) -> None

Sets whether the user can add custom colors.

userColorsAllowed

userColorsAllowed() -> bool

Returns whether the user can add custom colors.