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.
Defaults to a solid color in widgets placed on the Home Screen and a transparent color placed on the Lock Screen.
backgroundColor: Color
backgroundImage¶
Background image.
backgroundImage: Image
backgroundGradient¶
Background gradient.
backgroundGradient: LinearGradient
addAccessoryWidgetBackground¶
Whether to use an accessory widget background.
Enable to add an adaptive background that provides a standard appearance based on the widget's environment. Defaults to false.
This is only available starting from iOS 16.
addAccessoryWidgetBackground: bool
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
Promise 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
Promise 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
Promise that is fulfilled when the preview is dismissed.
-presentExtraLarge¶
Presents a preview of the widget.
presentExtraLarge(): Promise
The widget is presented in its extra 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.
The extra large widget is available on iPads running iOS 15 and newer.
Return value¶
Promise
Promise that is fulfilled when the preview is dismissed.
-presentAccessoryInline¶
Presents a preview of the widget.
presentAccessoryInline(): Promise
The widget is presented in its accessory inline size that suitable to be displayed above the clock on the Lock Screen.
The preview is an estimated representation of the widget and is not accurate. Widgets placed on the Lock Screen change appearance based on the wallpaper and tint color of the Lock Screen, and as such, they cannot be previewed accurately in Scriptable.
Widgets on the Lock Screen are updated periodically so while working on your widget you may want to preview it in the app.
The accessory inline widget is available on iPhones running iOS 16 and newer and can display a single image and a single text. Any additional elements will be filtered away during presentation.
Return value¶
Promise
Promise that is fulfilled when the preview is dismissed.
-presentAccessoryCircular¶
Presents a preview of the widget.
presentAccessoryCircular(): Promise
The widget is presented in its circular accessory size that suitable to be displayed above the clock on the Lock Screen.
The preview is an estimated representation of the widget and is not accurate. Widgets placed on the Lock Screen change appearance based on the wallpaper and tint color of the Lock Screen, and as such, they cannot be previewed accurately in Scriptable.
Widgets on the Lock Screen are updated periodically so while working on your widget you may want to preview it in the app.
The circular accessory widget is available on iPhones running iOS 16 and newer.
Return value¶
Promise
Promise that is fulfilled when the preview is dismissed.
-presentAccessoryRectangular¶
Presents a preview of the widget.
presentAccessoryRectangular(): Promise
The widget is presented in its rectangular accessory size that suitable to be displayed above the clock on the Lock Screen.
The preview is an estimated representation of the widget and is not accurate. Widgets placed on the Lock Screen change appearance based on the wallpaper and tint color of the Lock Screen, and as such, they cannot be previewed accurately in Scriptable.
Widgets on the Lock Screen are updated periodically so while working on your widget you may want to preview it in the app.
The rectangular accessory widget is available on iPhones running iOS 16 and newer.
Return value¶
Promise
Promise that is fulfilled when the preview is dismissed.