pytermgui.enums

This module provides commonly used enumerations for the library. It also has a class implementing Enum-s with default values. All Enums below subclass it, meaning you can use their get_default() methods to get the globally set default value.

To modify defaults, use the defaults dictionary.

  1"""
  2This module provides commonly used enumerations for the library.
  3It also has a class implementing Enum-s with default values. All Enums
  4below subclass it, meaning you can use their `get_default()` methods to get
  5the globally set default value.
  6
  7To modify defaults, use the `defaults` dictionary.
  8"""
  9
 10# This file is an absolute mess to mypy-correctly type.
 11# It is still typed well enough for a human to read, but
 12# I could not make mypy accept it without making the code
 13# horrible to read and edit.
 14#
 15# mypy: ignore-errors
 16
 17from __future__ import annotations
 18
 19from enum import Enum, IntEnum
 20from enum import auto as _auto
 21from typing import Type
 22
 23defaults: dict[IntEnum, Type[IntEnum]] = {}
 24
 25__all__ = [
 26    "SizePolicy",
 27    "CenteringPolicy",
 28    "SizePolicy",
 29    "HorizontalAlignment",
 30    "VerticalAlignment",
 31    "Overflow",
 32]
 33
 34
 35class DefaultEnum(IntEnum):
 36    """An Enum class that can return its default value."""
 37
 38    @classmethod
 39    def get_default(cls) -> IntEnum | None:
 40        """Get default value"""
 41
 42        return defaults.get(cls)
 43
 44
 45class SizePolicy(DefaultEnum):
 46    """Values according to which Widget sizes are assigned."""
 47
 48    FILL = 0
 49    """Inner widget will take up as much width as possible."""
 50
 51    STATIC = 1
 52    """Inner widget will take up an exact amount of width."""
 53
 54    RELATIVE = 2
 55    """Inner widget will take up widget.relative_width * available
 56    space."""
 57
 58
 59class CenteringPolicy(DefaultEnum):
 60    """Policies to center `Container` according to."""
 61
 62    ALL = _auto()
 63    VERTICAL = _auto()
 64    HORIZONTAL = _auto()
 65
 66
 67class HorizontalAlignment(DefaultEnum):
 68    """Policies to align widgets by.
 69
 70    These are applied by the parent object, and are
 71    relative to them."""
 72
 73    LEFT = 0
 74    """Align widget to the left edge."""
 75
 76    CENTER = 1
 77    """Center widget in the available width."""
 78
 79    RIGHT = 2
 80    """Align widget to the right edge."""
 81
 82
 83class VerticalAlignment(DefaultEnum):
 84    """Vertical alignment options for widgets."""
 85
 86    TOP = 0
 87    """Align widgets to the top"""
 88
 89    CENTER = 1
 90    """Align widgets in the center, with equal* padding on the top and bottom.
 91
 92    Note:
 93        When the available height is not divisible by 2, the extra line of padding
 94        is added to the bottom.
 95    """
 96
 97    BOTTOM = 2
 98    """Align widgets to the bottom."""
 99
100
101class Overflow(DefaultEnum):
102    """Overflow policies implemented by Container."""
103
104    HIDE = 0
105    """Stop gathering lines once there is no room left."""
106
107    SCROLL = 1
108    """Allow scrolling when there is too many lines."""
109
110    RESIZE = 2
111    """Resize parent to fit with the new lines.
112
113    Note:
114        When applied to a window, this prevents resizing its height
115        using the bottom border.
116    """
117
118    # TODO: Implement Overflow.AUTO
119    AUTO = 9999
120    """NotImplemented"""
121
122
123class WidgetChange(Enum):
124    """The type of change that happened within a widget."""
125
126    LINES = _auto()
127    """The result of `get_lines` has changed, but size changes didn't happen."""
128
129    SIZE = _auto()
130    """Both WIDTH and HEIGHT has changed."""
131
132    WIDTH = _auto()
133    """The width of the widget changed, possibly involving LINES type changes."""
134
135    HEIGHT = _auto()
136    """The height of the widget changed, possibly involving LINES type changes."""
137
138
139defaults[SizePolicy] = SizePolicy.FILL
140defaults[CenteringPolicy] = CenteringPolicy.ALL
141defaults[HorizontalAlignment] = HorizontalAlignment.CENTER
142defaults[VerticalAlignment] = VerticalAlignment.CENTER
143defaults[Overflow] = Overflow.RESIZE
class SizePolicy(DefaultEnum):
46class SizePolicy(DefaultEnum):
47    """Values according to which Widget sizes are assigned."""
48
49    FILL = 0
50    """Inner widget will take up as much width as possible."""
51
52    STATIC = 1
53    """Inner widget will take up an exact amount of width."""
54
55    RELATIVE = 2
56    """Inner widget will take up widget.relative_width * available
57    space."""

Values according to which Widget sizes are assigned.

FILL = <SizePolicy.FILL: 0>

Inner widget will take up as much width as possible.

STATIC = <SizePolicy.STATIC: 1>

Inner widget will take up an exact amount of width.

RELATIVE = <SizePolicy.RELATIVE: 2>

Inner widget will take up widget.relative_width * available space.

Inherited Members
DefaultEnum
get_default
enum.Enum
name
value
builtins.int
conjugate
bit_length
bit_count
to_bytes
from_bytes
as_integer_ratio
real
imag
numerator
denominator
class CenteringPolicy(DefaultEnum):
60class CenteringPolicy(DefaultEnum):
61    """Policies to center `Container` according to."""
62
63    ALL = _auto()
64    VERTICAL = _auto()
65    HORIZONTAL = _auto()

Policies to center Container according to.

ALL = <CenteringPolicy.ALL: 1>
VERTICAL = <CenteringPolicy.VERTICAL: 2>
HORIZONTAL = <CenteringPolicy.HORIZONTAL: 3>
Inherited Members
DefaultEnum
get_default
enum.Enum
name
value
builtins.int
conjugate
bit_length
bit_count
to_bytes
from_bytes
as_integer_ratio
real
imag
numerator
denominator
class HorizontalAlignment(DefaultEnum):
68class HorizontalAlignment(DefaultEnum):
69    """Policies to align widgets by.
70
71    These are applied by the parent object, and are
72    relative to them."""
73
74    LEFT = 0
75    """Align widget to the left edge."""
76
77    CENTER = 1
78    """Center widget in the available width."""
79
80    RIGHT = 2
81    """Align widget to the right edge."""

Policies to align widgets by.

These are applied by the parent object, and are relative to them.

Align widget to the left edge.

Center widget in the available width.

Align widget to the right edge.

Inherited Members
DefaultEnum
get_default
enum.Enum
name
value
builtins.int
conjugate
bit_length
bit_count
to_bytes
from_bytes
as_integer_ratio
real
imag
numerator
denominator
class VerticalAlignment(DefaultEnum):
84class VerticalAlignment(DefaultEnum):
85    """Vertical alignment options for widgets."""
86
87    TOP = 0
88    """Align widgets to the top"""
89
90    CENTER = 1
91    """Align widgets in the center, with equal* padding on the top and bottom.
92
93    Note:
94        When the available height is not divisible by 2, the extra line of padding
95        is added to the bottom.
96    """
97
98    BOTTOM = 2
99    """Align widgets to the bottom."""

Vertical alignment options for widgets.

Align widgets to the top

CENTER = <VerticalAlignment.CENTER: 1>

Align widgets in the center, with equal* padding on the top and bottom.

Note

When the available height is not divisible by 2, the extra line of padding is added to the bottom.

BOTTOM = <VerticalAlignment.BOTTOM: 2>

Align widgets to the bottom.

Inherited Members
DefaultEnum
get_default
enum.Enum
name
value
builtins.int
conjugate
bit_length
bit_count
to_bytes
from_bytes
as_integer_ratio
real
imag
numerator
denominator
class Overflow(DefaultEnum):
102class Overflow(DefaultEnum):
103    """Overflow policies implemented by Container."""
104
105    HIDE = 0
106    """Stop gathering lines once there is no room left."""
107
108    SCROLL = 1
109    """Allow scrolling when there is too many lines."""
110
111    RESIZE = 2
112    """Resize parent to fit with the new lines.
113
114    Note:
115        When applied to a window, this prevents resizing its height
116        using the bottom border.
117    """
118
119    # TODO: Implement Overflow.AUTO
120    AUTO = 9999
121    """NotImplemented"""

Overflow policies implemented by Container.

HIDE = <Overflow.HIDE: 0>

Stop gathering lines once there is no room left.

SCROLL = <Overflow.SCROLL: 1>

Allow scrolling when there is too many lines.

RESIZE = <Overflow.RESIZE: 2>

Resize parent to fit with the new lines.

Note

When applied to a window, this prevents resizing its height using the bottom border.

AUTO = <Overflow.AUTO: 9999>

NotImplemented

Inherited Members
DefaultEnum
get_default
enum.Enum
name
value
builtins.int
conjugate
bit_length
bit_count
to_bytes
from_bytes
as_integer_ratio
real
imag
numerator
denominator