Attributes to know about

All widgets share a set of attributes that can be used to make things look the way you want. Here is a quick overview on them.

Note

This API will likely be reformed in the future to be properly controllable through YAML config files. The underlying attributes will remain the same, but the way to access/modify them will be improved.

Applicable to all

Parent align

This attribute can be used to tell a widget's parent to align it left, right or center.

Possible values:

• HorizontalAlignment.LEFT or 0: Aligns to the left side.
• HorizontalAlignment.CENTER or 1: Aligns to the center.
• HorizontalAlignment.RIGHT or 2: Aligns to the right.

Default: HorizontalAlignment.CENTER

PythonOutput

from pytermgui import Container, Label, pretty

container = Container(
    Label("This is the left", parent_align=0),
    Label("This is the center", parent_align=1),
    Label("This is the right", parent_align=2),
)

for line in container.get_lines():
    print(line)

Size policy

Widget width adjustments are handled through a system of policies. The basics are:

• SizePolicy.FILL: The widget will take up the entire width provided by its parent.
• SizePolicy.STATIC: The widget will remain at a certain width, and its parent will never try to resize it.
• SizePolicy.RELATIVE: The widget will take up a certain percentage of its parent's width, denoted by a floating point value between 0 and 1.

While you can set these manually, it's easier for the both of us if you use the helper properties instead:

Default: SizePolicy.FILL

Warning

SizePolicy.STATIC can cause various issues if the parent widget doesn't have enough width available. If using it, make sure to make sure that the parent will never be smaller than the given widget!

PythonOutput

from pytermgui import Container, SizePolicy, pretty

container = Container(
    Container("I fill the space"),
    Container("I take up 70%", relative_width=0.7),
    Container("I take up exactly\n31 characters", static_width=31),
)


for line in container.get_lines():
    print(line)

Applicable to Container

Box

The container border and corner characters can be set to a few presets, which are defined in the boxes module.

Setting the box attribute to either a Box instance or an upper-cased box name will set both the border and corner characters to those defined by the box.

Default: SINGLE for Container, DOUBLE for Window.

PythonOutput

from pytermgui import Container, boxes, pretty

container = Container(box="EMPTY")

for name in [name for name in dir(boxes) if name.isupper()]:
    box = getattr(boxes, name)

    container += Container(
        f"[primary]{name}",
        box=box,
    )

for line in container.get_lines():
    print(line)

Applicable to Window

Note

Container's attributes also apply to Window.

Title

Windows can display text on the top-left corner of their borders.

Warning

You can only use markup in titles if the given window's corner_style parses TIM. This will always be the case with string-based shorthand styles, but may not be for custom callables. See the styling section for more info!

Default: ""

PythonOutput

from pytermgui import Window


window = Window("This is my test window")
window.set_title("[surface+2]Welcome to the docs!")