UI element utilities

zpui_lib.ui.utils.fit_image_to_screen(image, o, resampling='BOX', fill_color='black')

Fits a given image to fit on any sized screen whilst maintaining the aspect ratio. Any remaining space is filled with borders. The resized image is returned as image.

Args:

• image: A PIL image to be resized.

• o: output device object. Used to find the width and height of the screen.

• resampling="BOX" (PIL.Image.BOX): PIL resampling algorithm to be used during resizing. You can supply a string (to avoid importing PIL), or supply an algorithm enum variable (i.e. Image.BOX) directly. See https://pillow.readthedocs.io/en/stable/handbook/concepts.html#concept-filters .

zpui_lib.ui.utils.fit_image_to_dims(image, width, height, resampling=4, fill_color='black')

Fits a given image to fit on any sized screen whilst maintaining the aspect ratio. Any remaining space is filled with borders. The resized image is returned as image.

Args:

• image: A PIL image to be resized.

• width: target width.

• height: target height.

• resampling=PIL.Image.BOX: PIL resampling algorithm to be used during resizing. See https://pillow.readthedocs.io/en/stable/handbook/concepts.html#concept-filters .

zpui_lib.ui.utils.clamp(value, _min, _max)

Returns a value clamped between two bounds (inclusive)

>>> clamp(17, 0, 100)
17
>>> clamp(-89, 0, 100)
0
>>> clamp(65635, 0, 100)
100

zpui_lib.ui.utils.clamp_list_index(value, _list)

Returns a list index clamped to the bounds of the list. Useful to prevent iterating out of bounds, repeats the bounds values.

>>> astronauts = ['Collins', 'Armstrong', 'Aldrin']
>>> astronauts[clamp_list_index(0, astronauts)]
'Collins'
>>> astronauts[clamp_list_index(2, astronauts)]
'Aldrin'
>>> astronauts[clamp_list_index(9000, astronauts)]
'Aldrin'
>>> astronauts[clamp_list_index(-666, astronauts)]
'Collins'

zpui_lib.ui.utils.modulo_list_index(value, _list)

Returns an always valid list index. Repeats the list circularly.

>>> robots=['R2D2', 'C3PO', 'HAL9000']
>>> robots[modulo_list_index(0, robots)]
'R2D2'
>>> robots[modulo_list_index(3, robots)]
'R2D2'
>>> [robots[modulo_list_index(i, robots)] for i in range(10)]
['R2D2', 'C3PO', 'HAL9000', 'R2D2', 'C3PO', 'HAL9000', 'R2D2', 'C3PO', 'HAL9000', 'R2D2']

zpui_lib.ui.utils.check_value_lock(func)

A safety check wrapper so that there’s no race conditions between functions that are able to change position/value

zpui_lib.ui.utils.to_be_foreground(func)

A safety check wrapper so that certain functions can’t possibly be called if UI element is not the one active

zpui_lib.ui.funcs.format_for_screen(data, screen_width, break_words=False, linebreak=None)

zpui_lib.ui.funcs.replace_filter_ascii(text, replace_characters={'ö': 'o'})

Replaces non-ASCII characters with their ASCII equivalents if available, removes them otherwise. You can add new replacement characters using the add_character_replacement function. The output of this function is ASCII printable characters.

This function is mostly useful because the default PIL font doesn’t have many Unicode characters (in fact, it’s doubtful it has any). So, if you’re going to display strings with Unicode characters, you’ll want to use this function to filter your text before displaying.

zpui_lib.ui.funcs.add_character_replacement(character, replacement)

In case a Unicode character isn’t replaced in the way you want it replaced, use this function to add a special case.

zpui_lib.ui.funcs.format_values_into_text_grid(values, o)