Store
Downloads
Support
SDesk

Swirl Plugin API

The world’s most intuitive browser extension API – Really!

Swirl uses Lua libraries to expose functionality to plugin developers. Here, you’ll find a complete list of libraries and callbacks provided to you when programming Swirl Plugins.

You also have access to all the standard Lua libraries except for io and system.

Libraries

browser

Basic utilities for manipulating tabs and other elements of the browser.

get_current_page_url(): string

Get the URL of the currently displayed webpage.

If the Swirl Tab System is enabled, this will return a link to the webpage displayed by the currently selected tab. Native Swirl menus like the Home Screen, Plugin Loader, or Settings Menu are not considered webpages and this function will return an empty string if the user is on one.

tab_at(url: string, index: number): int

Get the location of the tab with a url matching url.

Returns -1 if no tab is found

If index is greater than 0, this function will not return a tab with an index below index – even if its url matches url.

closest_tab_l(url: string, index: number): int

Get the location of closest tab on the left side of the currently selected tab that has a url matching url.

Returns -1 if no tab is found or index is greater than the number of existing tabs.

If index is greater than 0, this function will not return a tab with an index below index – even if its url matches url.

closest_tab_r(url: string, index: number): int

Get the location of closest tab on the right side of the currently selected tab that has a url matching url.

Returns -1 if no tab is found or index is greater than the number of existing tabs.

If index is greater than 0, this function will not return a tab with an index below index – even if its url matches url.

tab_l(): string

Get the url of the tab directly beside the currently selected tab on its left side.

This function never fails.

tab_r(): string

Get the url of the tab directly beside the currently selected tab on its right side.

This function never fails.

new_tab(): nil

Creates a new tab displaying the start screen.

rm_tab(): nil

Removes the currently selected tab.

new_popup(title: string, description: string, button_text: string, content_offset: number): nil

Create a new popup with the specified metadata.

A popup only has one button. content_offset determines the y-offset of the content inside the popup box (Not the box itself!).

new_dialog(title: string, description: string, cancel_button_text: string, okay_button_text: string, content_offset: number): nil

Create a new dialog with the specified metadata.

A dialog has two buttons. content_offset determines the y-offset of the content inside the dialog box (Not the box itself!).

change_state(state: enum.BrowserState): nil

Change the browser state.

Only affects the currently selected tab. This function will not do anything if state is equal to the current BrowserState.

get_state(): enum.BrowserState

Get the browser state.

This function never returns nil.

engine

Utilities related to manipulating webpages and the underlying browser engine.

load_js(script: string): nil

Inject javascript into the currently displayed webpage.

This function never fails.

load_html(script: string): nil

Inject HTML into the currently displayed webpage.

This function never fails.

set_view_size(width: number, height: number): nil

Set the webpage size.

This does not actually modify the size of the view and only scales the webpage content. This ensures you will never see a native Swirl menu when you aren’t intended to.

change_tab(index: number): nil

Change the currently selected tab to the tab located at index.

This function never fails and can crash Swirl if used incorrectly.

change_url(url: string): nil

Change the currently selected tab’s URL to url.

This function never fails and can crash Swirl if used incorrectly.

go_back(): nil

Go back to the previous URL.

This function never fails.

go_forward(): nil

Go forward to the last URL.

This function never fails.

http_request(url: string, type: enum.XMLHttpRequest, callback: string): nil

Initialize and send a JavaScript XMLHttpRequest object with url being the target url, and type being the type of request.

On completion, the request will try to call a local function matching the name specified in callback with one argument of type string representing the response text from the request.

This function never fails.

new_interceptor(self: engine, id: string, callback: string): nil

Create a new url interceptor and access it later with id. When a new url is loaded, Swirl will try to call a local function matching the name specified in callback with the following arguments: request_url: string, first_party_url: string, initiator_url: string, is_download: boolean.

The url is blocked from being loaded into the browser only if the local function with the name callback returns true.

rm_interceptor(self: engine, id: string): nil

Destroys the first interceptor specified by id.

enum

Enumerations.

BrowserState

  • HOME_MENU_OPEN = 0
  • WEB_PAGE_OPEN = 1
  • SETTINGS_MENU_OPEN = 2
  • PLUGINS_MENU_OPEN = 3

XMLHttpRequest

  • GET = 0
  • POST = 1
  • PATCH = 2
  • DELETE = 3

SwirlHostSystem

  • MACOS = 0
  • SDESK = 1
registry

Functions for accessing the Swirl Plugin Registry – which allows your plugin to store persistent data securely.

exists(self: registry, key: string): boolean

Returns true if a registry entry by the name of key exists – otherwise this function returns false.

set(self: registry, key: string, data: string): nil

Sets the data stored in the registry entry by the name of key to data.

This function never fails.

get(self: registry, key: string): string

Returns the data stored in the registry entry by the name of key if it exists.

graphics

Graphics utilities.

draw_frame(self: graphics, id: string, x: number, y: number, z: number, width: number, height: number): nil

Draw a frame with the specified metadata.

Access later with id.

draw_button(self: graphics, id: string, text: string, x: number, y: number, z: number, width: number, height: number): nil

Draw a Swirl-styled button with the specified metadata.

Access later with id.

draw_native_button(self: graphics, id: string, text: string, x: number, y: number, z: number, width: number, height: number): nil

Draw a Swirl-styled button with the specified metadata.

Access later with id.

destroy_frame(self: graphics, id: string): nil

Destroys the first frame specified by id.

destroy_button(self: graphics, id: string): nil

Destroys the first Swirl-styled button specified by id.

destroy_native_button(self: graphics, id: string): nil

Destroys the first button specified by id.

change_frame_visibility(self: graphics, id: string, visible: boolean): nil

Changes the first frame specified by id to be either visible or invisible depending on the value of visible.

change_button_visibility(self: graphics, id: string, visible: boolean): nil

Changes the first Swirl-styled button specified by id to be either visible or invisible depending on the value of visible.

change_native_button_visibility(self: graphics, id: string, visible: boolean): nil

Changes the first button specified by id to be either visible or invisible depending on the value of visible.

change_frame_opacity(self: graphics, opacity: number): nil

Changes the opacity (0.0 – 1.0) of the first frame specified by id to opacity.

change_button_opacity(self: graphics, opacity: number): nil

Changes the opacity (0.0 – 1.0) of the first Swirl-styled button specified by id to opacity.

change_native_button_opacity(self: graphics, opacity: number): nil

Changes the opacity (0.0 – 1.0) of the first button specified by id to opacity.

adjust_frame(self: graphics, id: string, x: number, y: number, z: number, width: number, height: number): nil

Adjust the metadata of the first frame specified by id.

adjust_button(self: graphics, id: string, text: string, x: number, y: number, z: number, width: number, height: number): nil

Adjust the metadata of the first Swirl-styled button specified by id.

adjust_native_button(self: graphics, id: string, text: string, x: number, y: number, z: number, width: number, height: number): nil

Adjust the metadata of the first button specified by id.

system

OS information utilities.

datetime(): number

This function returns the number of seconds since the start of the year 1970 in UTC.

trans(text: string): string

Uses the Qt Linguist tool to translate text to the language used by the computer running Swirl. This function returns the translated text as a string.

systemname(): enum.SwirlHostSystem

This function returns enum.SwirlHostSystem.SDESK if the Swirl browser is running on SDesk Linux, or enum.SwirlHostSystem.MACOS if the Swirl browser is running on macOS.

hostname(): string

This function returns the host name of the computer running Swirl.

Callbacks

These are functions that you manually define in your code and are called by the Swirl browser automatically.

onStart()

onUpdate(elapsed: number)

onCloseRequested()

onCustomPopupStarted()

onCustomPopupStopped()

onCustomPopupFinished()

onCustomDialogStarted()

onCustomDialogStopped()

onCustomDialogFinished()

onDisable(first_time: boolean)

onDelete()

onEnable(first_time: boolean)

onFrameDrawn()

onWentBack()

onWentForward()

onNativeButtonHovered(id: string)

onNativeButtonClicked(id: string)

onNativeButtonDrawn(id: string)

onBookmarkAdded(url: string)

onBookmarkRemoved(url: string)

onDownloadRequested(file_name: string)

onContextMenuRequested()

onNewWindowRequested(url: string)

onNewTabRequested(url: string)

onNewBackgroundTabRequested(url: string)