Miscellaneous George functions¶

def undoable(func: T) -> T:
    """Decorator to register actions in the TVPaint undo stack."""

    def wrapper(*args: Any, **kwargs: Any) -> T:
        tv_undo_open_stack()
        res = func(*args, **kwargs)
        tv_undo_close_stack(func.__name__)
        return cast(T, res)

    return cast(T, wrapper)

@contextlib.contextmanager
def undoable_stack() -> Generator[None, None, None]:
    """Context manager that creates an undo stack. Useful to undo a sequence of George actions."""
    tv_undo_open_stack()
    yield
    tv_undo_close_stack()

def tv_warn(msg: str) -> None:
    """Display a warning message."""
    send_cmd("tv_Warn", msg)

def tv_version() -> tuple[str, str, str]:
    """Returns TVPaint version and language info.

    Returns:
        software_name (str): software full name (ex: TVPaint Animation 12.0.0 Pro)
        tvp_version (str): version number (ex: 12.0.0)
        language (str): language (ex: fr, en, etc...)
    """
    cmd_fields: FieldTypes = [
        ("software_name", str),
        ("version", str),
        ("language", str),
    ]
    res = tv_parse_list(send_cmd("tv_Version"), with_fields=cmd_fields)
    software_name, tvp_version, language = res.values()
    return software_name, tvp_version, language

def is_tvp_version_below_12() -> bool:
    """Helper function to check if the connected tvpaint instance version is below v12."""
    _, tvp_version, _ = tv_version()
    return version.parse(tvp_version).major < 12

def min_version_compatible(min_version: str) -> Callable[[T], T]:
    """Decorator to apply on methods.

    Given a minimum version, checks if the current tvpaint version is above the minimum requirement otherwise it
    raises a NotImplemented error

    Args:
        min_version (str): minimum version required to run this version

    Returns:
        the decorated function
    """

    def decorate(func: T) -> T:
        @functools.wraps(func)
        def applicator(*args: Any, **kwargs: Any) -> Any:
            _, tvp_version, _ = tv_version()
            current_version = version.parse(tvp_version)
            min_version_parse = version.parse(min_version)

            if current_version < min_version_parse:
                msg = f"This function is only available in TVPaint version ({min_version}) and above."
                raise NotImplementedError(msg)

            return func(*args, **kwargs)

        return cast(T, applicator)

    return decorate

def deprecated_warning(msg: str) -> Callable[[T], T]:
    """Decorator to apply on methods.

    Prints a deprecation message/warning when decorated function is called

    Args:
        msg (str): deprecation message

    Returns:
        the decorated function
    """

    def decorate(func: T) -> T:
        @functools.wraps(func)
        def applicator(*args: Any, **kwargs: Any) -> Any:
            warnings.warn(msg, DeprecationWarning)
            log.warning(f"DEPRECTED: {msg}")
            return func(*args, **kwargs)

        return cast(T, applicator)

    return decorate

def tv_quit() -> None:
    """Closes the TVPaint instance."""
    send_cmd("tv_Quit")

def tv_host2back() -> None:
    """Minimize the TVPaint window."""
    send_cmd("tv_Host2Back")

def tv_host2front() -> None:
    """Restore the TVPaint window after being minimized."""
    send_cmd("tv_Host2Front")

def tv_menu_hide() -> None:
    """Switch to inlay view and hide all non-docking panels."""
    send_cmd("tv_MenuHide")

def tv_menu_show(menu_element: MenuElement | None = None, *menu_options: Any, current: bool = False) -> None:
    """For the complete documentation, see: https://www.tvpaint.com/doc/tvpaint-animation-11/george-commands#tv_menushow."""
    cmd_args: list[str] = []

    if current:
        cmd_args.append("current")

    if menu_element:
        cmd_args.append(menu_element.value)

    send_cmd("tv_MenuShow", *cmd_args, *menu_options)

def add_some_magic(i_am_a_badass: bool = False, magic_number: int | None = None) -> None:
    """Don't use this function ! It just might change your life forever !"""
    if not i_am_a_badass:
        log.warning("Sorry, you're not enough of a badass for this function !")

    magic_number = magic_number if magic_number is not None else 14
    send_cmd("tv_MagicNumber", magic_number)
    log.info("Totally worth it, right ?! ^^")

def tv_request(msg: str, confirm_text: str = "Yes", cancel_text: str = "No") -> bool:
    """Open a confirmation prompt with a message.

    Args:
        msg: the message to display
        confirm_text: the confirm button text. Defaults to "Yes".
        cancel_text: the cancel button text. Defaults to "No".

    Returns:
        bool: True if clicked on "Yes"
    """
    return bool(int(send_cmd("tv_Request", msg, confirm_text, cancel_text)))

def tv_req_num(value: int, min: int, max: int, title: str = "Enter Value") -> int | None:
    """Open a prompt to request an integer (within a range).

    Args:
        value: the initial value
        min: the minimum value
        max: the maximum value
        title: title of the prompt dialog. Defaults to "Enter Value".

    Returns:
        the value or None if cancelled
    """
    res = send_cmd("tv_ReqNum", value, min, max, title, handle_string=False)
    return None if res.lower() == "cancel" else int(res)

def tv_req_angle(value: float, min: float, max: float, title: str = "Enter Value") -> float | None:
    """Open a prompt to request an angle (in degree).

    Args:
        value: the initial value
        min: the minimum value
        max: the maximum value
        title: title of the prompt. Defaults to "Enter Value".

    Returns:
        the value or None if cancelled
    """
    res = send_cmd("tv_ReqAngle", value, min, max, title, handle_string=False)
    return None if res.lower() == "cancel" else float(res)

def tv_req_float(value: float, min: float, max: float, title: str = "Enter value") -> float | None:
    """Open a prompt to request a float.

    Args:
        value: the initial value
        min: the minimum value
        max: the maximum value
        title: title of the prompt. Defaults to "Enter Value".

    Returns:
        the value or None if cancelled
    """
    res = send_cmd("tv_ReqFloat", value, min, max, title, handle_string=False)
    return None if res.lower() == "cancel" else float(res)

def tv_req_string(title: str, text: str) -> str | None:
    """Open a prompt to request a string.

    Args:
        title: title of the requester. Defaults to "Enter Value".
        text: the initial value

    Returns:
        the value or None if cancelled
    """
    cmd_args = ["|".join([title, text])]
    if "\n" in text:
        cmd_args.insert(0, "multiline")
    res = send_cmd("tv_ReqString", *cmd_args, handle_string=False)
    return None if res.lower() == "cancel" else res

def tv_list_request(entries: list[Entry]) -> tuple[int, str]:
    """Open a prompt to request a selection in a list.

    Args:
        entries: the list of entries (either a single entry or sub entries)

    Returns:
        the position, the entry
    """
    entries_str = "|".join(map(_entry_to_str, entries))
    res = send_cmd("tv_ListRequest", entries_str, error_values=["-1 Cancel"])
    res_obj = tv_parse_list(
        res,
        with_fields=[
            ("index", int),
            ("entry", str),
        ],
    )
    index, entry = tuple(res_obj.values())
    return int(index), entry

def tv_req_file(
    mode: FileMode,
    title: str = "",
    working_dir: Path | str | None = None,
    default_name: str | None = None,
    extension_filter: str | None = None,
) -> Path | None:
    """Open a prompt to request a file.

    Args:
        mode: save or load
        title: the title of the request
        working_dir: the default folder to go. Defaults to None.
        default_name: the default name. Defaults to None.
        extension_filter: display the files with this extension. Defaults to None.

    Returns:
        the choosen path or None if cancelled
    """
    cmd_args = [
        title,
        Path(working_dir).as_posix() if working_dir else None,
        default_name,
        extension_filter,
    ]

    arg_str = "|".join([v if v is not None else "" for v in cmd_args])
    res = send_cmd("tv_ReqFile", f"{mode.value} {arg_str}", handle_string=False)

    return None if res.lower() == "cancel" else Path(res)

def tv_undo() -> None:
    """Do an undo."""
    send_cmd("tv_Undo")

def tv_update_undo() -> None:
    """Copies the contents of the current image in the current layer into the buffer undo memory.

    None of the draw commands described in this section updates this buffer memory.
    If you click on the Undo button after executing a George program, everything that the program has drawn in your image will be deleted.
    With this function you can update the undo buffer memory whenever you wish (for example at the beginning of the program).
    """
    send_cmd("tv_UpdateUndo")

def tv_undo_open_stack() -> None:
    """Open an 'undo' stack.

    Surround a piece of code with tv_undoopenstack ... tv_undoclosestack, then multiple undo will be added to this stack, and closing this stack will undo everything inside.
    (To be sure the script returns to the expected result use tv_updateundo before tv_undoopenstack)
    """
    send_cmd("tv_UndoOpenStack")

def tv_undo_close_stack(name: str = "") -> None:
    """Close an 'undo' stack (See tv_undo_open_stack)."""
    send_cmd("tv_UndoCloseStack", name)

def tv_save_mode_get() -> tuple[SaveFormat, list[str]]:
    """Get the saving alpha mode."""
    res = send_cmd("tv_SaveMode")
    res_split = res.split()
    save_format = tv_cast_to_type(res_split.pop(0), SaveFormat)
    return save_format, res_split

def tv_save_mode_set(save_format: SaveFormat, *format_options: str | int | float) -> None:
    """Set the saving alpha mode."""
    send_cmd("tv_SaveMode", save_format.value, *format_options)

def tv_alpha_load_mode_get() -> AlphaMode:
    """Set the loading alpha mode."""
    res = send_cmd("tv_AlphaLoadMode")
    return tv_cast_to_type(res, AlphaMode)

def tv_alpha_load_mode_set(mode: AlphaMode) -> None:
    """Get the loading alpha mode."""
    send_cmd("tv_AlphaLoadMode", mode.value)

def tv_alpha_save_mode_get() -> AlphaSaveMode:
    """Get the saving alpha mode."""
    res = send_cmd("tv_AlphaSaveMode")
    return tv_cast_to_type(res, AlphaSaveMode)