interface ¤

def print_at(self, text: str, x: int, y: int, palette: list | tuple) -> int:
    """Wrapper print_at method.

    Parameters:
        text: Text to print.
        x: X axis position / column.
        y: Y axis position / row.
        palette: A length-3 tuple or a list of length-3 tuples representing asciimatics palettes.

    Returns:
        The number of characters actually printed.
    """
    if self.scroll == 0:
        if isinstance(palette, list):
            self.screen.paint(text, x, y, colour_map=palette)
        else:
            self.screen.print_at(text, x, y, *palette)
        written = len(text)
    else:
        text_length = len(text)
        if text_length > self.scroll:
            new_text = text[self.scroll :]
            written = len(new_text)
            if isinstance(palette, list):
                new_palette = palette[self.scroll :]
                self.screen.paint(new_text, x, y, colour_map=new_palette)
            else:
                self.screen.print_at(new_text, x, y, *palette)
            self.scroll = 0
        else:
            self.scroll -= text_length
            written = 0
    return written

def set_scroll(self, scroll: int) -> None:
    """Set the scroll value."""
    self.scroll = scroll

def get_column_at_x(self, x: int) -> int:
    """For an horizontal position X, return the column index."""
    for i, bound in enumerate(self.bounds):
        if bound[0] <= x <= bound[1]:
            return i
    raise ValueError("clicked outside of boundaries")

def get_data(self) -> list[Download]:
    """Return a list of objects."""
    return self.api.get_downloads()

def print_headers(self) -> None:
    """Print the headers (columns names)."""
    self.scroller.set_scroll(self.x_scroll)
    x, y, c = self.x_offset, self.y_offset, 0

    for column_name in self.columns_order:
        column = self.columns[column_name]
        palette = self.palettes["focused_header"] if c == self.sort else self.palettes["header"]

        if column.padding == "100%":
            header_string = f"{column.header}"
            fill_up = " " * max(0, self.width - x - len(header_string))
            written = self.scroller.print_at(header_string, x, y, palette)
            self.scroller.print_at(fill_up, x + written, y, self.palettes["header"])

        else:
            header_string = f"{column.header:{column.padding}} "
            written = self.scroller.print_at(header_string, x, y, palette)

        x += written
        c += 1

def print_rows(self) -> None:
    """Print the rows."""
    y = self.y_offset + 1
    for row in self.rows[self.row_offset : self.row_offset + self.height]:
        self.scroller.set_scroll(self.x_scroll)
        x = self.x_offset

        for i, column_name in enumerate(self.columns_order):
            column = self.columns[column_name]
            padding = f"<{max(0, self.width - x)}" if column.padding == "100%" else column.padding

            if self.focused == y - self.y_offset - 1 + self.row_offset:
                palette = self.palettes["focused_row"]
            else:
                palette = column.get_palette(row[i])
                if isinstance(palette, str):
                    palette = self.palettes[palette]

            field_string = f"{row[i]:{padding}} "
            written = self.scroller.print_at(field_string, x, y, palette)
            x += written

        y += 1

    for i in range(self.height - y):
        self.screen.print_at(" " * self.width, self.x_offset, y + i, *self.palettes["ui"])

def process_event(self, event: KeyboardEvent | MouseEvent) -> None:
    """Process an event.

    For reactivity purpose, this method should not compute expensive stuff, only change the state of the interface,
    changes that will be applied by update_data and update_rows methods.

    Parameters:
        event (KeyboardEvent | MouseEvent): The event to process.
    """
    if isinstance(event, KeyboardEvent):
        self.process_keyboard_event(event)

    elif isinstance(event, MouseEvent):
        self.process_mouse_event(event)

def run(self) -> bool:
    """The main drawing loop."""
    try:
        # outer loop to support screen resize
        while True:
            with ManagedScreen() as screen:
                logger.debug(f"Created new screen {screen}")
                self.set_screen(screen)
                self.frame = 0
                # break (and re-enter) when screen has been resized
                while not screen.has_resized():
                    # keep previous sort in memory to know if we have to re-sort the rows
                    # once all events are processed (to avoid useless/redundant sort passes)
                    previous_sort = (self.sort, self.reverse)

                    # we only refresh when explicitly asked for
                    self.refresh = False

                    # process all events before refreshing screen,
                    # otherwise the reactivity is slowed down a lot with fast inputs
                    event = screen.get_event()
                    logger.debug(f"Got event {event}")
                    while event:
                        # avoid crashing the interface if exceptions occur while processing an event
                        try:
                            self.process_event(event)
                        except Exit:
                            logger.debug("Received exit command")
                            return True
                        except Exception as error:  # noqa: BLE001
                            # TODO: display error in status bar
                            logger.exception(error)
                        event = screen.get_event()
                        logger.debug(f"Got event {event}")

                    # time to update data and rows
                    if self.frame == 0:
                        logger.debug("Tick! Updating data and rows")
                        self.update_data()
                        self.update_rows()
                        self.refresh = True

                    # time to refresh the screen
                    if self.refresh:
                        logger.debug("Refresh! Printing text")
                        # sort if needed, unless it was just done at frame 0 when updating
                        if (self.sort, self.reverse) != previous_sort and self.frame != 0:
                            self.sort_data()
                            self.update_rows()

                        # actual printing and screen refresh
                        for print_function in self.state_mapping[self.state]["print_functions"]:
                            print_function()
                        screen.refresh()

                    # sleep and increment frame
                    time.sleep(self.sleep)
                    self.frame = (self.frame + 1) % self.frames
                logger.debug("Screen has resized")
                self.post_resize()
    except Exception as error:  # noqa: BLE001
        logger.exception(error)
        return False

def set_screen(self, screen: Screen) -> None:
    """Set the screen object, its scroller wrapper, width, height, and columns bounds."""
    self.screen = screen
    self.height, self.width = screen.dimensions
    self.scroller = HorizontalScroll(screen)
    self.bounds = []
    for column_name in self.columns_order:
        column = self.columns[column_name]
        if column.padding == "100%":  # last column
            self.bounds.append((self.bounds[-1][1] + 1, self.width))
        else:
            padding = int(column.padding.lstrip("<>=^"))
            if not self.bounds:
                self.bounds = [(0, padding)]
            else:
                self.bounds.append((self.bounds[-1][1] + 1, self.bounds[-1][1] + 1 + padding))

def sort_data(self) -> None:
    """Sort data according to interface state."""
    sort_function = self.columns[self.columns_order[self.sort]].get_sort
    self.data = sorted(self.data, key=sort_function, reverse=self.reverse)

def update_data(self) -> None:
    """Set the interface data and rows contents."""
    try:
        self.data = self.get_data()
        self.sort_data()
    except requests.exceptions.Timeout:
        logger.debug("Request timeout")

def update_rows(self) -> None:
    """Update rows contents according to data and interface state."""
    text_getters = [self.columns[c].get_text for c in self.columns_order]
    n_columns = len(self.columns_order)
    self.rows = [tuple(text_getters[i](item) for i in range(n_columns)) for item in self.data]
    if self.follow:
        self.focused = self.data.index(self.follow)

@staticmethod
def name(value: str) -> str | list[tuple[int, int, int]]:
    """Return the palette for a NAME cell."""
    if value.startswith("[METADATA]"):
        return (
            [(Screen.COLOUR_GREEN, Screen.A_UNDERLINE, Screen.COLOUR_BLACK)] * 10
            + [Interface.palettes["metadata"]] * (len(value.strip()) - 10)
            + [Interface.palettes["row"]]
        )
    return "name"

@staticmethod
def status(value: str) -> str:
    """Return the palette for a STATUS cell."""
    return "status_" + value