widgets

Home Screen Widgets

Since iOS / iPadOS 14, multiple widgets from the same app can be displayed in the home screen. That changed the way widgets work. Before iOS 14, widgets were dynamic which means that a script’s output could be displayed at real time and views were interactive. However, that changed. Now widgets are not really interactive. The UI cannot be changed after being presented. That means a widget now provides a static UI multiple times a day.

Individual UI elements can open the script in foreground except on the small layout, where only the whole widget can be pressed.

Scripts can determine when a widget will be reloaded, for example each hour. While the UI is not interactive, UI elements can open the script in foreground to do a certain task. So coding some kind of launcher is possible.

Warning

This library requires iOS 14+

API Reference

The type of the None singleton.

Types of widgets

There are two types of widgets:

Run Script: A script running in background to update the widget content automatically. The scripts run with a limited amount of memory and cannot execute subprocesses.

In App: A script executed manually in foreground that will provide an UI for a widget. The scripts can do everything a script running in foreground can. This is very powerful with Shortcuts automations or with request_background_fetch().

Getting Started

As an example, we will code a widget that shows the current date and week day.

Firstly, we will import the required libraries:

import widgets as wg
from datetime import datetime, timedelta

We will start by defining the text foreground color and the background color for the widget’s UI.

BACKGROUND = wg.Color.rgb(255/255, 250/255, 227/255)
FOREGROUND = wg.Color.rgb(75/255, 72/255, 55/255)

Then we’ll declare a function that returns the weekday of a ‘datetime’ object as a string.

def weekday(date):
    day = date.weekday()
    if day == 0:
        return "Monday"
    elif day == 1:
        return "Tuesday"
    elif day == 2:
        return "Wednesday"
    elif day == 3:
        return "Thursday"
    elif day == 4:
        return "Friday"
    elif day == 5:
        return "Saturday"
    elif day == 6:
        return "Sunday"

To provide the widgets, we need to declare a subclass of TimelineProvider.

class DateProvider(wg.TimelineProvider):

Two methods must be implemented: timeline() and widget().

Let’s start by timeline(). This method returns a list of dates for which the script has data. As we are creating a calendar widget, we need to update it everyday at midnight. We will cache the next 30 days.

def timeline(self):
    today = datetime.today()
    today = datetime.combine(today, datetime.min.time())

    dates = []
    for i in range(30):
        date = today + timedelta(days=i)
        dates.append(date)

    return dates

The method above returns the next 30 days dates at midnight. Then we need to provide a widget for each date.

We will code the UI. Each widget has 3 layouts: small, medium and large. So we need to provide a different layout for each size. A layout is composed of rows, each row containing horizontally aligned UI elements. The small layout is a small square, the medium layout is a rectangle and the large one is a big square.

A Widget instance has 3 properties that can be used to modify the layout of each widget size. small_layout, medium_layout, large_layout

The Widget object must be returned from the widget(). The date parameter is a datetime object corresponding to the date when the widget will be displayed. For this example, we will use the medium layout only.

def widget(self, date):
    widget = wg.Widget()
    layout = widget.medium_layout

Firstly, we will create a Text showing the week day corresponding to the given date.

day = wg.Text(
    text=weekday(date),
    font=wg.Font("AmericanTypewriter-Bold", 50),
    color=FOREGROUND)

To show the current formatted date, we can use DynamicDate:

date_text = wg.DynamicDate(
    date=date,
    font=wg.Font("AmericanTypewriter", 18),
    color=FOREGROUND,
    padding=wg.Padding.ALL)

Then we place the the week day at center and the date at the bottom. add_vertical_layout() adds an invisible space that takes as much as vertical space as it can. The set_link() method sets a parameter that will be passed to the script when the widget is pressed, the link property can be set for individual UI elements.

See UI Elements for a list of UI elements and their documentation.

layout.add_vertical_spacer()
layout.add_row([day])
layout.add_row([date_text])
layout.set_background_color(BACKGROUND)
layout.set_link(date.ctime())

return widget

Call the provide_timeline() function to show the widget:

wg.provide_timeline(DateProvider())

And we can check for the link variable to use the passed parameter.

if wg.link is not None:
    print(wg.link)
else:
    wg.provide_timeline(DateProvider())

The script looks like that:

import widgets as wg
from datetime import datetime, timedelta

BACKGROUND = wg.Color.rgb(255/255, 250/255, 227/255)
FOREGROUND = wg.Color.rgb(75/255, 72/255, 55/255)

def weekday(date):
    day = date.weekday()
    if day == 0:
        return "Monday"
    elif day == 1:
        return "Tuesday"
    elif day == 2:
        return "Wednesday"
    elif day == 3:
        return "Thursday"
    elif day == 4:
        return "Friday"
    elif day == 5:
        return "Saturday"
    elif day == 6:
        return "Sunday"

class DateProvider(wg.TimelineProvider):

    def timeline(self):
        today = datetime.today()
        today = datetime.combine(today, datetime.min.time())

        dates = []
        for i in range(30):
            date = today + timedelta(days=i)
            dates.append(date)

        return dates

    def widget(self, date):
        widget = wg.Widget()
        layout = widget.medium_layout

        day = wg.Text(
            text=weekday(date),
            font=wg.Font("AmericanTypewriter-Bold", 50),
            color=FOREGROUND)

        date_text = wg.DynamicDate(
            date=date,
            font=wg.Font("AmericanTypewriter", 18),
            color=FOREGROUND,
            padding=wg.Padding.ALL)

        layout.add_vertical_spacer()
        layout.add_row([day])
        layout.add_row([date_text])
        layout.set_background_color(BACKGROUND)
        layout.set_link(date.ctime())

        return widget

if wg.link is not None:
    print(wg.link)
else:
    wg.provide_timeline(DateProvider())

After running the script, it will be selectable in the “Run Script” widget.

If your widget doesn’t have any data for the future, instead of providing a timeline you can provide a single widget and request a refresh after a certain delay. See show_widget() and schedule_next_reload().

import widgets as wg
from datetime import timedelta

widget = wg.Widget()

...

wg.schedule_next_reload(timedelta(hours=1))
wg.show_widget(widget)