ListWidget

Widget showing a list of elements.

A widget showing a list of elements. Pass the widget to Script.setWidget() display it on your Home screen.

Be aware that the widget will refresh periodically and the rate at which the widget refreshes is largely determined by the operating system.

Also note that there are memory limitations when running a script in a widget. When using too much memory the widget will crash and not render correctly.

backgroundColor

Background color of the widget.

backgroundColor: Color

backgroundImage

Background image.

backgroundImage: Image

backgroundGradient

Background gradient.

backgroundGradient: LinearGradient

spacing

Spacing between elements.

Specifies the spacing between elements in the widget. You can also use the addSpacer() function on the widget to add spacing between elements. Defaults to 0.

spacing: number

url

URL to open.

The URL will be opened when the widget is tapped. This will override any behavior defined in the configuration of the widget. E.g. if the widget is configured to run the script when interacting with the widget but a URL is set the URL will take precedence.

url: string

refreshAfterDate

Earliest date to refresh the widget.

The property indicates when the widget can be refreshed again. The widget will not be refreshed before the date have been reached. It is not guaranteed that the widget will refresh at exactly the specified date.

The refresh rate of a widget is partly up to iOS/iPadOS. For example, a widget may not refresh if the device is low on battery or the user is rarely looking at the widget.

When the property is null the default refresh interval is used. Defaults to null.

refreshAfterDate: Date

-new ListWidget

Constructs a new list widget.

new ListWidget()

A widget showing a list of elements. Pass the widget to Script.setWidget() to display it on your Home screen.


-addText

Add text to the widget.

addText(text: string): WidgetText

Adds a text element to the widget. Use the properties on the returned element to style the text.

Return value

WidgetText
Text element.


-addDate

Add date to the widget.

addDate(date: Date): WidgetDate

Adds a date element to the widget. Use the properties on the returned element to style the date.

Return value

WidgetDate
Date element.


-addImage

Add image to the widget.

addImage(image: Image): WidgetImage

Adds an image element to the widget. Use the properties on the returned element to style the image.

Return value

WidgetImage
Image element.


-addSpacer

Add spacer.

addSpacer(length: number): WidgetSpacer

Adds a spacer to the widget. This can be used to offset the content vertically in the widget.

Parameters

length
number
Length of the spacer. Pass null to create a spacer with a flexible length.

Return value

WidgetSpacer
Spacer element.


-addStack

Add stack.

addStack(): WidgetStack

Adds a stack to the widget. Stacks layout elements horizontally by default.

Return value

WidgetStack
Stack element.


-setPadding

Set padding.

setPadding(top: number, leading: number, bottom: number, trailing: number)

Sets the padding on each side of the widget.

Parameters

top
number
Padding on the top edge.

leading
number
Padding on the leading edge.

bottom
number
Padding on the bottom edge.

trailing
number
Padding on the trailing edge.


-useDefaultPadding

Use the default padding.

useDefaultPadding()

Configure the widget to use the default padding. Any padding previously defined with setPadding() will be discarded.


-presentSmall

Presents a preview of the widget.

presentSmall(): Promise

The widget is presented in its small size.

Widgets on the Home screen are updated periodically so while working on your widget you may want to preview it in the app.

Return value

Promise
Promsie that is fulfilled when the preview is dismissed.


-presentMedium

Presents a preview of the widget.

presentMedium(): Promise

The widget is presented in its medium size.

Widgets on the Home screen are updated periodically so while working on your widget you may want to preview it in the app.

Return value

Promise
Promsie that is fulfilled when the preview is dismissed.


-presentLarge

Presents a preview of the widget.

presentLarge(): Promise

The widget is presented in its large size.

Widgets on the Home screen are updated periodically so while working on your widget you may want to preview it in the app.

Return value

Promise
Promsie that is fulfilled when the preview is dismissed.