Introduction to Xen HTML

Widget Locations

To load widgets into Xen HTML, it is recommended to place those that are intended for the Lockscreen into:


The file LockBackground.html will be then be used to load your widget. This is to ensure backwards compatibility with both GroovyLock and LockHTML.

For the Homescreen, Xen HTML will load widgets from:


The HTML file loaded from here will be Wallpaper.html, again, to maintain backwards compatibility with SBHTML.

Both of these folders will be created on installation by Xen HTML if they do not currently exist.


When building widgets to run in Xen HTML, you now have the option to include a new file named WidgetInfo.plist in your widget. Including this file allows you to specify additional metadata to be loaded, and furthermore allows you to use Options.plist (as per iWidgets) as user-facing settings. Please note that the usage of Options.plist is optional.

Example widget using WidgetInfo.plist: download here.

General WidgetInfo.plist Keys

A number of keys can be set in WidgetInfo.plist, with more to be added over time:


Configures whether the widget's size should be set to the display's bounds, or to the size key.



Configures the size of the widget, and is typically used in conjunction with isFullscreen.



Configures whether to use Options.plist in this widget.



Configures whether the widget can scroll vertically when in use, such as how a typical webpage functions.


Options.plist Keys

Since utilising WidgetInfo.plist allows for usage of Options.plist, this will also be documented here.

Example Options.plist: download here.

To add a new settings option in Options.plist, you will want to create a new dictionary item:


There a few options that can be specified to complete a setting, with one being optional. These are placed inside the new dictionary item:


Configures what type the setting is.


Available options:

switch - specifies that the setting is a simple true/false toggle

edit - allows the user to enter any text or number for this variable

select - allows the user to select a number of possible settings from a list


This setting is the name of the variable used in your code.



This setting is the variable's formatted name as dislayed to the user when configuring settings.

<string>Some Variable</string>


The default value for this settings option.

If using switch as the type:


If using edit as the type:




If using select as the type:

<string>Options Title</string>

Where the value is equal to the <key> in the dictionary supplied in options (see below).


This provides the list of available options the user can pick from when using the select type. The other two types don't need this key.

  <key>First Title</key>
  <key>Second Title</key>

For each line in the dictionary provided to this key, the <key> is what is displayed to the user in Settings, and the following line is the variable in your code it corresponds to.

Make sure to check on an iWidget how this works if you're unsure.


Xen HTML allows for placing an image named Screenshot.png in your widget's root folder. This is displayed to the user when they are scrolling through the list of widgets available on their devices in Settings. For example, its location in the filesystem will be as follows:

- <widget_name>
-- LockBackground.html
-- Screenshot.png

This image can be any size, but will be scaled to a height of 80pts (e.g., 160px on a @2x device) with the aspect ratio being preserved.