color_picker

The module containing the ColorPicker widget, as well as some helpers it needs.

To test out the widget, run ptg --color!

ColorPicker

Bases: Container

A simple ColorPicker widget.

This is used to visualize xterm-255 colors. RGB colors are not included here, as it is probably easier to use a web-based picker for those anyways.

Source code in pytermgui/widgets/color_picker.py

class ColorPicker(Container):
    """A simple ColorPicker widget.

    This is used to visualize xterm-255 colors. RGB colors are not
    included here, as it is probably easier to use a web-based picker
    for those anyways.
    """

    size_policy = SizePolicy.STATIC

    def __init__(self, show_output: bool = True, **attrs: Any) -> None:
        """Initializes a ColorPicker.

        Attrs:
            show_output: Decides whether the output Container should be
                added. If not set, the widget will only display the
                PixelMatrix of colors.
        """

        super().__init__(**attrs)
        self.show_output = show_output

        self._matrix = PixelMatrix.from_matrix(_get_xterm_matrix())

        self.width = 72
        self.box = boxes.EMPTY

        self._add_widget(self._matrix, run_get_lines=False)

        self.chosen = Joiner()
        self._output = Container(self.chosen, "", "", "")

        if self.show_output:
            self._add_widget(self._output)

    @property
    def selectables_length(self) -> int:
        """Returns either the button count or 1."""

        return max(super().selectables_length, 1)

    def handle_mouse(self, event: MouseEvent) -> bool:
        """Handles mouse events.

        On hover, the widget will display the currently hovered
        color and some testing text.

        On click, it will add a _FadeInButton for the currently
        hovered color.

        Args:
            event: The event to handle.
        """

        if super().handle_mouse(event):
            return True

        if not self.show_output or not self._matrix.contains(event.position):
            return False

        if event.action is MouseAction.LEFT_CLICK:
            if self._matrix.selected_pixel is None:
                return True

            _, color = self._matrix.selected_pixel
            if len(color) == 0:
                return False

            button = _FadeInButton(f"{color:^5}", width=5)
            button.styles.label = f"@{color}"
            self.chosen.lazy_add(button)

            return True

        return False

    def get_lines(self) -> list[str]:
        """Updates self._output and gets widget lines."""

        if self.show_output and self._matrix.selected_pixel is not None:
            _, color = self._matrix.selected_pixel
            if len(color) == 0:
                return super().get_lines()

            color_obj = str_to_color(color)
            rgb = color_obj.rgb
            hex_ = color_obj.hex
            lines: list[Widget] = [
                Label(f"[@{color} #auto] {color} [/ {color}] {color}"),
                Label(
                    f"[{color} bold]Here[/bold italic] is "
                    + "[/italic underline]some[/underline dim] example[/dim] text"
                ),
                Label(),
                Label(
                    f"RGB: [{';'.join(map(str, rgb))}]"
                    + f"rgb({rgb[0]:>3}, {rgb[1]:>3}, {rgb[2]:>3})"
                ),
                Label(f"HEX: [{hex_}]{hex_}"),
            ]
            self._output.set_widgets(lines + [Label(), self.chosen])

            return super().get_lines()

        return super().get_lines()

selectables_length: int property

Returns either the button count or 1.

__init__(show_output=True, **attrs)

Initializes a ColorPicker.

Attrs

show_output: Decides whether the output Container should be added. If not set, the widget will only display the PixelMatrix of colors.

Source code in pytermgui/widgets/color_picker.py

def __init__(self, show_output: bool = True, **attrs: Any) -> None:
    """Initializes a ColorPicker.

    Attrs:
        show_output: Decides whether the output Container should be
            added. If not set, the widget will only display the
            PixelMatrix of colors.
    """

    super().__init__(**attrs)
    self.show_output = show_output

    self._matrix = PixelMatrix.from_matrix(_get_xterm_matrix())

    self.width = 72
    self.box = boxes.EMPTY

    self._add_widget(self._matrix, run_get_lines=False)

    self.chosen = Joiner()
    self._output = Container(self.chosen, "", "", "")

    if self.show_output:
        self._add_widget(self._output)

get_lines()

Updates self._output and gets widget lines.

Source code in pytermgui/widgets/color_picker.py

def get_lines(self) -> list[str]:
    """Updates self._output and gets widget lines."""

    if self.show_output and self._matrix.selected_pixel is not None:
        _, color = self._matrix.selected_pixel
        if len(color) == 0:
            return super().get_lines()

        color_obj = str_to_color(color)
        rgb = color_obj.rgb
        hex_ = color_obj.hex
        lines: list[Widget] = [
            Label(f"[@{color} #auto] {color} [/ {color}] {color}"),
            Label(
                f"[{color} bold]Here[/bold italic] is "
                + "[/italic underline]some[/underline dim] example[/dim] text"
            ),
            Label(),
            Label(
                f"RGB: [{';'.join(map(str, rgb))}]"
                + f"rgb({rgb[0]:>3}, {rgb[1]:>3}, {rgb[2]:>3})"
            ),
            Label(f"HEX: [{hex_}]{hex_}"),
        ]
        self._output.set_widgets(lines + [Label(), self.chosen])

        return super().get_lines()

    return super().get_lines()

handle_mouse(event)

Handles mouse events.

On hover, the widget will display the currently hovered color and some testing text.

On click, it will add a _FadeInButton for the currently hovered color.

Parameters:

Name	Type	Description	Default
event	MouseEvent	The event to handle.	required

Source code in pytermgui/widgets/color_picker.py

def handle_mouse(self, event: MouseEvent) -> bool:
    """Handles mouse events.

    On hover, the widget will display the currently hovered
    color and some testing text.

    On click, it will add a _FadeInButton for the currently
    hovered color.

    Args:
        event: The event to handle.
    """

    if super().handle_mouse(event):
        return True

    if not self.show_output or not self._matrix.contains(event.position):
        return False

    if event.action is MouseAction.LEFT_CLICK:
        if self._matrix.selected_pixel is None:
            return True

        _, color = self._matrix.selected_pixel
        if len(color) == 0:
            return False

        button = _FadeInButton(f"{color:^5}", width=5)
        button.styles.label = f"@{color}"
        self.chosen.lazy_add(button)

        return True

    return False

Joiner

Bases: Container

A Container that stacks widgets horizontally, without filling up the available space.

This works slightly differently to Splitter, as that applies padding & custom widths to any Widget it finds. This works much more simply, and only joins their lines together as they come.

Source code in pytermgui/widgets/color_picker.py

class Joiner(Container):
    """A Container that stacks widgets horizontally, without filling up the available space.

    This works slightly differently to Splitter, as that applies padding & custom widths to
    any Widget it finds. This works much more simply, and only joins their lines together as
    they come.
    """

    parent_align = HorizontalAlignment.LEFT

    chars = {"separator": " "}

    def get_lines(self) -> list[str]:
        """Does magic"""

        lines: list[str] = []
        separator = self._get_char("separator")
        assert isinstance(separator, str)

        line = ""
        for widget in self._widgets:
            if len(line) > 0:
                line += separator

            widget.pos = (self.pos[0] + real_length(line), self.pos[1] + len(lines))
            widget_line = widget.get_lines()[0]

            if real_length(line + widget_line) >= self.width:
                lines.append(line)
                widget.pos = self.pos[0], self.pos[1] + len(lines)
                line = widget_line
                continue

            line += widget_line

        lines.append(line)
        self.height = len(lines)
        return lines

get_lines()

Does magic

Source code in pytermgui/widgets/color_picker.py

def get_lines(self) -> list[str]:
    """Does magic"""

    lines: list[str] = []
    separator = self._get_char("separator")
    assert isinstance(separator, str)

    line = ""
    for widget in self._widgets:
        if len(line) > 0:
            line += separator

        widget.pos = (self.pos[0] + real_length(line), self.pos[1] + len(lines))
        widget_line = widget.get_lines()[0]

        if real_length(line + widget_line) >= self.width:
            lines.append(line)
            widget.pos = self.pos[0], self.pos[1] + len(lines)
            line = widget_line
            continue

        line += widget_line

    lines.append(line)
    self.height = len(lines)
    return lines