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.
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.
enum
Enumerations.
BrowserState
- HOME_MENU_OPEN = 0
- WEB_PAGE_OPEN = 1
- SETTINGS_MENU_OPEN = 2
- PLUGINS_MENU_OPEN = 3
graphics
Graphics utilities.
draw_frame(id: string, x: number, y: number, width: number, height: number): nil
Draw a frame with the specified metadata.
Access later with id.
draw_button(id: string, text: string, x: number, y: number, width: number, height: number): nil
Draw a Swirl-styled button with the specified metadata.
Access later with id.
draw_native_button(id: string, text: string, x: number, y: number, width: number, height: number): nil
Draw a Swirl-styled button with the specified metadata.
Access later with id.
destroy_frame(id: string): nil
Destroys the first frame specified by id.
destroy_button(id: string): nil
Destroys the first Swirl-styled button specified by id.
destroy_native_button(id: string): nil
Destroys the first button specified by id.
change_frame_visibility(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(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(id: string, visible: boolean): nil
Changes the first button specified by id to be either visible or invisible depending on the value of visible.
Callbacks
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)