UI

This page contains a list of classes used by the widgets API to make an UI.

When an UI element with a link attribute in a medium or large widget is pressed, the widget script will be opened in foreground and the link attribute will be passed to this variable. At the beginning of a widget script, you can check if this variable is None. If it’s not, that means an UI element with a link attribute was pressed.

See link, add_row() and set_link()

Return type:str

Widget Configuration

class widgets.Widget

The configuration of a widget, which is a set of different layouts.

extra_large_layout = <widgets.WidgetLayout object>

A WidgetLayout object which UI’s will be used for extra large widgets (only available on iPadOS).

large_layout = <widgets.WidgetLayout object>

A WidgetLayout object which UI’s will be used for large sized widgets.

medium_layout = <widgets.WidgetLayout object>

A WidgetLayout object which UI’s will be used for medium sized widgets.

small_layout = <widgets.WidgetLayout object>

A WidgetLayout object which UI’s will be used for small sized widgets.

class widgets.WidgetLayout

The layout of a widget with all its UI elements. A Widget contains 3 layouts: small, medium and large. A widget layout is composed of rows, each row containing a list of UI elements.

add_row(row: List[widgets.WidgetComponent], background_color: Optional[widgets.Color] = None, corner_radius: float = 0, link: Optional[str] = None)

Adds a row to the widget layout. A row is a list of UI elements on the same horizontal line.

Parameters:
  • row – A list of UI elements.
  • background_color – The background color of the row.
  • corner_radius – The radius to use when drawing rounded corners for the row’s background.
Link:

A string that will be passed to the widget script when the row is tapped. This parameter doesn’t take effect on small widgets.

add_vertical_divider(color: Optional[widgets.Color] = None)

Adds a visual vertical separator.

Parameters:color – The color of the line.
add_vertical_spacer()

Adds a row that takes as much as vertical space as possible.

set_background_color(color: widgets.Color)

Sets the background color of the widget layout.

Parameters:color – A Color object.
set_background_gradient(colors: List[widgets.Color])

Sets the background color of the widget layout to a gradient. The gradient is linear and goes from top to bottom and uses the colors passed as a list.

Parameters:colors – A list of Color objects for the gradient.
set_background_image(image: widgets.Image)

Sets the background image of the widget layout.

Parameters:image – An Image object.

When a widget is tapped, the widget is executed in app and the link attribute is passed to data:~widgets.WidgetComponent.link.

Links on entire widgets take effect on small widgets unlike links on UI elements.

Parameters:link – A string that will be passed to the widget script when the widget is tapped.
class widgets.TimelineProvider

A timeline providers allows a script to provide content to a widget for the future.

Pass a subclass of TimelineProvider to provide_timeline() to provide a timeline of widgets. Calling this function in app will just preview the widget and will not have any effect.

reload_time() → Union[datetime.timedelta, float]

Returns the delay after which the widget should reload and run the script again. The return value is the delay between the last timeline entry and the next reload. The system doesn’t guarantees the widget to be reloaded at an exact time.

Supported return types are float``s representing seconds or a ``datetime.timedelta object.

Return type:Union[datetime.timedelta, float]
timeline() → List[datetime.datetime]

Returns a list of timestamps for which the script has data. Make sure to not provide an exaggerated ammount of dates because the widget can crash due to memory issues.

Return type:List[datetime.datetime]
widget(date: datetime.datetime) → widgets.Widget

Returns a widget for the given timestamp.

Return type:Widget

UI Elements

class widgets.WidgetComponent(background_color: Optional[widgets.Color] = None, corner_radius: float = 0, padding: Union[PADDING, widgets.Padding, None] = None, link: Optional[str] = None)

An abstract class that represents an UI element displayed in a widget.

WidgetComponent attributes can be modified after initialisation, but they can all be set from the initialiser. However, changes made to an WidgetComponent object after being displayed won’t take effect.

background_color

The background color of the element.

Return type:widgets.Color
corner_radius = 0

The radius to use when drawing rounded corners for the view’s background.

Return type:float

A string that will be passed to the widget script when the element is tapped. Set this attribute to make the element tappable.

When an element is tapped, the widget is executed in app and the link attribute is passed to link. The element isn’t tappable if this attribute is set to None.

This attribute doesn’t take effect on small widgets.

Return type:str
padding = 0

If set to True, additional blank space around the view will be added.

See Padding.

Return type:bool
class widgets.Text(text: str, color: Optional[widgets.Color] = None, font: Optional[widgets.Font] = None, background_color: Optional[widgets.Color] = None, corner_radius: float = 0, padding: Union[PADDING, widgets.Padding, None] = None, link: Optional[str] = None)

A widget UI element displaying plain text.

color = None

The foreground color of the text.

Return type:widgets.Color
font = None

The font of the text.

Return type:widgets.Font
text = None

The text displayed on screen.

Return type:str
class widgets.DynamicDate(date: Union[datetime.datetime, datetime.date, datetime.time], style: DATE_STYLE = 0, color: Optional[widgets.Color] = None, font=None, background_color: Optional[widgets.Color] = None, corner_radius: float = 0, padding: Union[PADDING, widgets.Padding, None] = None, link: Optional[str] = None)

A text displaying a date with the correct format.

As widgets are not dynamic and UI elements aren’t modifiable after being displayed, this class can also serve to display timers with a provided date.

Example:

import widgets as wd
from datetime import datetime, timedelta

# A 1 hour timer
one_hour = datetime.now() + timedelta(hours=1)
timer = wd.DynamicDate(one_hour, style=wd.DATE_STYLE_TIMER)

# Formatted date
today = datetime.today()
date_text = wd.DynamicDate(today)
color = None

The foreground color of the text.

Return type:widgets.Color
date = None

The date used to create the text.

Valid value types:

  • datetime.datetime: A specific date and time.
  • datetime.date: A date without specifying time. The current time will be used.
  • datetime.time: A time without specifying date. The current date will be used.
Return type:Union[datetime.datetime, datetime.date, datetime.time]
font = None

The font of the text.

Return type:widgets.Font
style = 0

The date style determines how the date should be used to create text.

See Date Style

Return type:DATE_STYLE_DATE
class widgets.SystemSymbol(symbol_name: str, color: Optional[widgets.Color] = None, font_size: Optional[float] = None, background_color: Optional[widgets.Color] = None, corner_radius: float = 0, padding: Union[PADDING, widgets.Padding, None] = None, link: Optional[str] = None)

An UI element displaying a system symbol (SF Symbol).

Valid symbol names are declared in the sf_symbols module.

color = None

The foreground color of the symbol.

Return type:widgets.Color
font_size = None

The size in pixels of the symbol.

Return type:float
symbol_name = None

The SF Symbol name.

Return type:str
class widgets.Image(image: Optional[PIL.Image.Image] = None, url: Optional[str] = None, fill: bool = False, background_color: Optional[widgets.Color] = None, corner_radius: float = 0, padding: Union[PADDING, widgets.Padding, None] = None, link: Optional[str] = None)

An UI element displaying an image.

fill = False

If set to True, the image will fill its container. Otherwise, the image will conserve its own aspect ratio.

Return type:bool
image = None

A Pillow image to be displayed.

Return type:PIL.Image
class widgets.Spacer

An invisible UI element taking as much as horizontal space as it can.

Label – < Spacer> – Label

Data Types

class widgets.Padding(top: float = 0, bottom: float = 0, left: float = 0, right: float = 0)

Padding with custom values. Use constants for using the system defined padding.

bottom = None

Bottom padding

left = None

Left padding

right = None

Right padding

top = None

Top padding

class widgets.Color(py_color)

A Color object represents a color to be displayed on screen.

Example:

import pyto_ui as ui

# RGB
black = ui.Color.rgb(0, 0, 0, 1)

# White
white = ui.Color.white(1, 1)

# Dynamic
background = ui.Color.dynamic(light=white, dark=black)

For pre-defined colors, see Color constants.

alpha() → float

Returns the alpha value of the color.

Return type:float
blue() → float

Returns the blue value of the color.

Return type:float
classmethod dynamic(light: widgets.Color, dark: widgets.Color) → widgets.Color

Initializes and returns a color that dynamically changes in dark or light mode.

Parameters:
  • lightColor object to be displayed in light mode.
  • darkColor object to be displayed in dark mode.
Return type:

widgets.Color

green() → float

Returns the green value of the color.

Return type:float
red() → float

Returns the red value of the color.

Return type:float
classmethod rgb(red: float, green: float, blue, alpha: float = 1) → widgets.Color

Initializes a color from RGB values.

All values should be located between 0 and 1, not between 0 and 255.

Parameters:
  • red – The red value.
  • green – The geen value.
  • blue – The blue value.
  • alpha – The opacity value.
Return type:

widgets.Color

classmethod white(white: float, alpha: float) → widgets.Color

Initializes and returns a color from white value.

All values should be located between 0 and 1, not between 0 and 255.

Parameters:
  • white – The grayscale value.
  • alpha – The opacity value.
Return type:

widgets.Color

class widgets.Font(name: str, size: float)

A Font object represents a font (with name and size) to be used on labels, buttons, text views etc.

classmethod bold_system_font_of_size(size: float) → widgets.Font

Returns the font object used for standard interface items that are rendered in boldface type in the specified size

Parameters:size – The size (in points) for the font. This value must be greater than 0.0.
Return type:pyto_ui.Font
classmethod font_names_for_family_name(name: str) → List[str]

Returns an array of font names available in a particular font family.

Parameters:name – The name of the font family. Use the font_family_names() function to get an array of the available font family names on the system.
Return type:List[str]
classmethod font_with_style(style: ui_constants.FONT_TEXT_STYLE) → widgets.Font

Returns an instance of the system font for the specified text style and scaled appropriately for the user’s selected content size category.

Parameters:style – The text style for which to return a font. See Font Text Style constants for possible values.
Return type:pyto_ui.Font
classmethod italic_system_font_of_size(size: float) → widgets.Font

Returns the font object used for standard interface items that are rendered in italic type in the specified size.

Parameters:size – The size (in points) for the font. This value must be greater than 0.0.
Return type:pyto_ui.Font
classmethod system_font_of_size(size: float) → widgets.Font

Returns the font object used for standard interface items in the specified size.

Parameters:size – The size (in points) to which the font is scaled. This value must be greater than 0.0.
Return type:pyto_ui.Font
with_size(size: float) → widgets.Font

Returns a font object that is the same as the receiver but which has the specified size instead.

Parameters:size – The desired size (in points) of the new font object. This value must be greater than 0.0.
Return type:pyto_ui.Font