Skip to content

colours

Jump to bottom
Mihaly Konda edited this page Jul 9, 2025 · 3 revisions

colours

version: v1.3.8

A module for adding the standard R colour palette to Qt applications.

function text_colour_threshold() 

def text_colour_threshold() -> int

Returns the threshold which represents the average intensity of colour channels above which the text should be black, while at or below it should be white.


function set_text_colour_threshold() 

def set_text_colour_threshold(new_value: int) -> None

Sets the threshold which represents the average intensity of colour channels above which the text should be black, while at or below it should be white.

Parameters:

  • new_value: The new 8-bit threshold to set.

function icon_file_path() 

def icon_file_path() -> str

Returns the path for the icon file to be used in the dialogs.


function set_icon_file_path() 

def set_icon_file_path(new_path: str = '') -> None

Sets the path for the icon file to be used in the dialogs.

Parameters:

  • new_path: The new path to set for the windows. The default is an empty string, leading to the default icon.

function extended_default() 

def extended_default() -> bool

Returns the flag controlling the default tab of the colour selector.


function set_extended_default() 

def set_extended_default(new_default: bool) -> None

Returns the flag controlling the default tab of the colour selector.

Parameters:

  • new_default: The new flag to set.

function scale_json_to_list() 

def scale_json_to_list(src: str) -> list[QColor]

Takes a path to a JSON scale file, imports then converts it to a list of QColor objects.

Parameters:

  • src: Path to the JSON file containing scale data.

class Colour

A class to represent an RGB colour.

Class variables:

  • name: The name of the colour (read-only).
  • r: The red value of the colour (read-only).
  • g: The green value of the colour (read-only).
  • b: The blue value of the colour (read-only).

def __init__(self, name: str = 'white', r: int = 255, g: int = 255, b: int = 255) -> None

Initializer for the class. By default, it creates a white object.

Parameters:

  • name: The name of the colour. The default value is 'white'.
  • r: The 8-bit red value of the colour. The default value is 255.
  • g: The 8-bit green value of the colour. The default value is 255.
  • b: The 8-bit blue value of the colour. The default value is 255.

def __repr__(self) -> str

Returns the repr of the object.


def __eq__(self, other: Any) -> bool

Performs an equality comparison with another object.

Parameters:

  • other: The other object to which the instance is to be compared.

Returns: The result of a channel-wise comparison between the objects.


def __iter__(self) -> Iterator[int]

Makes the object iterable. (Yields the R, G, B channels in this order.)


def __hash__(self) -> int

Returns a hash created from the name and RGB values of the instance. (So it can be used in a BijectiveDict.)


@cached_property
def as_rgb(self) -> str

Returns a string representation of the colour as [R, G, B].


@cached_property
def as_hex(self) -> str

Returns the hexadecimal representation of the colour as '#RRGGBB'.


def as_qt(self, negative: bool = False) -> QColor

Returns a QColor object with the same RGB values (or its negative).

Parameters:

  • negative: A flag to request the negative of the colour. The default is False.

Returns: A QColor object with the same RGB values as the instance.


def colour_box(self, width: int = 20, height: int = 20) -> QIcon

Returns a colour box as a QIcon with the requested size.

Parameters:

  • width: The requested width of the colour box. The default is 20 pixels.
  • height: The requested height of the colour box. The default is 20 pixels.

Returns: A QIcon of a given size with the colour of the instance.


def text_colour(self) -> Qt.GlobalColor

Returns the (black/white) QColor that's appropriate to write with on the background with the given colour.


class _Colours(metaclass=Singleton) 

def __init__(self) -> None:

Initializer for the class.


def __getattr__(self, name: str) -> Any

Handles an attribute access request.

Parameters:

  • name: The name of the requested attribute.

Returns: A stored colour or an attribute of one of the internal dictionaries.


def __iter__(self) -> Iterator[Colour]

Makes the object iterable.


def __getitem__(self, index: int | Colour | str) -> int | Colour | tuple[Colour, int]

Returns a value from one of the internal dictionaries accessed with '[]' (either of the main or the secondary type).

Parameters:

  • index: The key whose associated value is to be returned.

Returns: A Colour object, its index or a tuple of these, based on the type of the index.


def index(self, name: str) -> int

Returns the index of a given colour in the src.

Parameters:

  • name: The name of the colour to look up.

def colour_at(self, idx: int) -> Colour

Returns the colour at the given numeric index.

Parameters:

  • idx: The numeric index to look up.

def from_qt(self, qc: QColor) -> Colour

Returns an existing colour or an unnamed custom one.

Parameters:

  • qc: The Qt colour based on which the search is to be conducted.

dataclass _ColourBoxData

Data for an individual colour box in the drawer widget.

Parameters:

  • row: The row in which to draw the colour box.
  • column: The column in which to draw the colour box.
  • colour: The colour of the colour box. The default is None, resulting in white.

def __post_init__(self) -> None

Adds the default white colour.


dataclass _ColourScaleData

Metadata and colour list of a colour scale.

def import_from_json(self, path: str) -> None

Import a JSON file and parse its data.

Parameters:

  • path: The source path of the JSON file.

def export_to_json(self, path: str) -> None

Exports contents as a JSON file to the requested destination.

Parameters:

  • path: The destination path of the JSON file.

class _ColourBoxDrawer(QWidget)

A selector widget showing all the colours as a grid of colour boxes.

Signals:

  • colourSelected: A signal carrying the index of the selected colour.

def __init__(self, default_colour: Colour) -> None

Initializer for the class.

Parameters:

  • default_colour: The default colour the combobox icon should be set to.

@property
def selection(self) -> Colour

Returns the currently selected or the default colour.


@selection.setter
def selection(self, new_selection: _ColourBoxData) -> None

Sets a new selection (made by an external sender).

Parameters:

  • new_selection: The new selection to set.

def mousePressEvent(self, event: QMouseEvent) -> None

Handles colour selection graphically and by emitting a signal.

Parameters:

  • event: The mouse event that triggered the method.

def keyPressEvent(self, event: QKeyEvent) -> None

Handles colour selection graphically and by emitting a signal. (Makes it possible to navigate the extended colour selector using the arrow keys.)

Parameters:

  • event: The mouse event that triggered the method.

def paintEvent(self, event: QPaintEvent) -> None

Prints the colour boxes and the selection rectangle.

Parameters:

  • event: The paint event that triggered the method.

class _ColourSelectorMixin

Mixin class for the colour selector.

Signals:

  • colourChanged: A signal carrying the button ID and the new colour.

def __init__(self, button_id: int = 0, default_colour: Colour = Colour(), widget_theme: ThemeParameters = None) -> None

Initializer for the class.

Parameters:

  • button_id: An ID for the button to which the instance corresponds. The default is 0.
  • default_colour: The default colour the combobox icon should be set to. The default is white.
  • widget_theme: The theme used for the selector. The default is None, for when the theme module is not found.

def _setup_ui(self) -> None

Sets up the user interface: GUI objects and layouts.


def _setup_connections(self) -> None

Sets up the connections of the GUI objects.


@property
def theme(self) -> ThemeParameters

Returns the parameters of the theme set for this object.


@theme.setter
def theme(self, new_theme: ThemeParameters) -> None

Sets a new set of parameters defining a theme to this object.

Parameters:

  • new_theme: The new theme to set for the widget.

def _slot_tab_changed(self, index: int) -> None

Handles tab changes.

Parameters:

  • index: The index of the new tab.

def _slot_filter(self) -> None

Filters the colour list based on the text in line edit.


def _slot_update_selection(self, index: int) -> None

Updates the data of the currently selected colour.

Parameters:

  • index: The index of the new colour from a combobox or a selector dialog.

def _slot_apply(self) -> None

Emits the ID of the set colour to the caller, then closes the window.


def _slot_cancel(self) -> None

Closes the window without emitting a signal.


class ColourSelector(_ColourSelectorMixin, QDialog)

A colour selector dialog.

def __init__(self, button_id: int = 0, default_colour: Colour = Colour(), widget_theme: ThemeParameters = None) -> None

Initializer for the class.

Parameters:

  • button_id: An ID for the button to which the instance corresponds. The default is 0.
  • default_colour: The default colour the combobox icon should be set to. The default is white.
  • widget_theme: The theme used for the selector. The default is None, for when the theme module is not found.

class ColourSelectorDW(_ColourSelectorMixin, QDockWidget)

A colour selector dock widget.

def __init__(self, button_id: int = 0, default_colour: Colour = Colour(), widget_theme: ThemeParameters = None) -> None

Initializer for the class.

Parameters:

  • button_id: An ID for the button to which the instance corresponds. The default is 0.
  • default_colour: The default colour the combobox icon should be set to. The default is white.
  • widget_theme: The theme used for the selector. The default is None, for when the theme module is not found.

class _ColourScale(QWidget)

A widget that draws a 500px vertical/horizontal colour scale.

def __init__(self, colours: list[Colour] = None, steps: int = 0, horizontal: bool = False) -> None

Initializer for the class.

Parameters:

  • colours: The list of colours on which the scale is based. The default is None, resulting in a blank colour scale.
  • steps: The number of steps of colours between two set colours. The default is 0, corresponding to an empty colour list.
  • horizontal: A flag marking whether the scale is horizontal. The default is False (vertical scale).

def update_scale(self, colours: list[Colour], steps: int) -> None

Sets new controls to update the scale.

Parameters:

  • colours: The list of colours on which the scale is based.
  • steps: The number of steps of colours between two set colours.

@classmethod
def _segment_calculator(cls, colours: tuple[Colour], steps: int) -> list[QColor]

Calculates the colours of a segment of the scale, which is between two set colours.

Parameters:

  • colours: A pair of colours at the edges of the segment.
  • steps: The number of steps of colours between two set colours.

Returns: A list of QColor objects representing the colours of the scale.


def _to_8_bit(value: int) -> int

Coerces a value to be between 0 and 255 and returns it as an integer. (Nested function inside _segment_calculator().)


def paintEvent(self, event: QPaintEvent) -> None

Draws the requested scale.

Parameters:

  • event: The paint event that triggered the method.

class _ColourScaleCreatorMixin

A custom colour scale creator.

Signals:

  • colourScaleChanged: A signal carrying the list of colours of the new scale.

def __init__(self, colours: list[Colour] = None, horizontal: bool = False, widget_theme: ThemeParameters = None, parent: QMainWindow = None) -> None

Initializer for the class.

Parameters:

  • colours: The list of colours to set for the scale. The default is None, resulting in a default white scale.
  • horizontal: A flag marking whether a vertical (default) or horizontal scale should be used in the dialog.
  • widget_theme: The theme used for the selector. The default is None, for when the theme module is not found.
  • parent: The parent window to which the dock widget belongs. The default is None, for the dialog.

def _setup_ui(self) -> None

Sets up the user interface: GUI objects and layouts.


def _setup_connections(self) -> None

Sets up the connections of the GUI objects.


@property
def theme(self) -> ThemeParameters:

Returns the parameters of the theme set for this object.


@theme.setter
def theme(self, new_theme: ThemeParameters) -> None

Sets a new set of parameters defining a theme to this object.


def _slot_update_total_steps(self) -> None

Updates the label showing the total number of colour steps.


def _slot_add_colour(self) -> None

Adds a colour to the list widget and updates the label accordingly.


def catch_signal(button_id, colour) -> None

Catches the signal carrying the newly set colour. (Nested function inside _slot_add_colour().)

Parameters:

  • button_id: The caller button's ID, unused here.
  • colour: The colour to add to the list.

def _slot_remove_colour(self) -> None

Removes the selected colour from the list widget.


def _slot_update_scale(self) -> None

Sends the set colours to the scale widget for it to get updated.


def _slot_import_scale(self) -> None

Import a JSON file containing scale data.


def _slot_export_scale(self) -> None

Export the metadata and colour list of the scale to a JSON file.


def _slot_apply(self) -> None

Emits the calculated scale colours, then closes the window.


def _slot_cancel(self) -> None

Closes the window without emitting a signal.


class ColourScaleCreator(_ColourScaleCreatorMixin, QDialog)

A colour selector dialog.

def __init__(self, colours: list[Colour] = None, horizontal: bool = False, widget_theme: ThemeParameters = None) -> None

Initializer for the class.

Parameters:

  • colours: The list of colours to set for the scale. The default is None, resulting in a default white scale.
  • horizontal: A flag marking whether a vertical (default) or horizontal scale should be used in the dialog.
  • widget_theme: The theme used for the selector. The default is None, for when the theme module is not found.

class ColourScaleCreatorDW(_ColourScaleCreatorMixin, QDockWidget)

A colour selector dock widget.

def __init__(self, parent: QMainWindow, colours: list[Colour] = None, horizontal: bool = False, widget_theme: ThemeParameters = None) -> None

Initializer for the class.

Parameters:

  • parent: The parent window to which the dock widget belongs.
  • colours: The list of colours to set for the scale. The default is None, resulting in a default white scale.
  • horizontal: A flag marking whether a vertical (default) or horizontal scale should be used in the dialog.
  • widget_theme: The theme used for the selector. The default is None, for when the theme module is not found.

API reference

Base/technical modules:

Other modules

Clone this wiki locally