Repository navigation
API
Returns whether this is an HTML5 build.
local supported = browser_io.is_supported()boolean
true on HTML5 builds and false on other build targets.
This does not test an individual browser API. Use the can_*() functions for feature detection.
Returns whether the current browser context exposes clipboard text writing.
local supported = browser_io.can_copy()The implementation requires:
- a secure browser context
navigator.clipboardnavigator.clipboard.writeText
A returned value of true means the operation can be attempted. Browser security policy can still reject the request.
Returns whether the current browser context exposes clipboard text reading.
local supported = browser_io.can_paste()The implementation requires:
- a secure browser context
navigator.clipboardnavigator.clipboard.readText
A returned value of true does not guarantee permission to read the clipboard.
Returns whether the browser exposes the APIs required by open_file().
local supported = browser_io.can_open_file()The current implementation checks for DOM element creation and FileReader.
Returns whether the browser exposes the APIs required by save_file().
local supported = browser_io.can_save_file()The current implementation checks for:
BlobURL.createObjectURL- an
<a>element with download support
Returns whether the browser exposes drag/drop and file-reading APIs.
local supported = browser_io.can_drop_files()This is an API capability check only. It does not guarantee that an external file-drag workflow is practical on a touch-only device.
Copies UTF-8 text to the system clipboard.
local request_id = browser_io.copy(text, callback)text
: Lua string containing the text to copy.
callback
: Function called as:
callback(self, result)On success:
{
success = true,
cancelled = false,
operation = "copy"
}On failure:
{
success = false,
cancelled = false,
operation = "copy",
error = "..."
}A numeric request ID.
local function copy_callback(self, result)
if result.success then
pprint("data copied")
else
pprint("Clipboard copy failed: "..result.error)
end
end
function copy(data)
browser_io.copy(data, copy_callback)
end
Reads UTF-8 text from the system clipboard.
local request_id = browser_io.paste(callback)callback
: Function called as:
callback(self, result){
success = true,
cancelled = false,
operation = "paste",
data = "...",
size = 123
}size is the byte length of the Lua string.
An empty successful paste returns:
data = ""
size = 0A numeric request ID.
local function paste_callback(self, result)
if result.success then
print("PASTED:", result.data)
else
pprint("Clipboard paste failed")
end
end
function paste()
browser_io.paste(paste_callback)
endOpens a browser file picker and reads one selected file into a Lua string.
browser_io.open_file(nil, callback)
browser_io.open_file(options, callback)callback
: Function called as:
callback(self, result){
accept = ".ohm",
max_size = 16384
}Optional HTML-style accept filter.
The JavaScript bridge supports:
- file extensions such as
.txt - exact MIME types such as
application/json - wildcard MIME types such as
image/* - comma-separated combinations
Example:
accept = ".txt,.json,application/json"The default is an empty string, which does not restrict file type.
The selected file is checked against the accept rules by the extension after selection as well as being supplied to the browser file input.
Maximum file size in bytes.
Default:
16 MiB
A supplied numeric value is used only when greater than zero.
{
success = true,
cancelled = false,
operation = "open_file",
name = "level.ohm",
data = "...",
size = 2048
}The file data is binary-safe.
A zero-byte file returns:
data = ""
size = 0If the browser reports that the file picker was cancelled:
result.cancelled == trueA numeric request ID.
local function open_callback(self, result)
if result.success then
print("data:", result.data)
else
pprint("Open failed:", result.error)
end
end
function open_file()
browser_io.open_file( {accept = ".ohm", max_size = 16 * 1024}, open_callback)
endCreates a browser download from a Lua string.
browser_io.save_file(filename, data, nil, callback)
browser_io.save_file(filename, data, options, callback)filename
: Suggested download filename.
data
: Lua string containing the file bytes. Binary data is supported.
options
: Optional table.
callback
: Function called as:
callback(self, result){
mime_type = "text/plain;charset=utf-8"
}Default MIME type:
application/octet-stream
{
success = true,
cancelled = false,
operation = "save_file"
}A successful result means the extension created the Blob, triggered the browser download link, and handed the operation to the browser. The extension cannot confirm that the user eventually saved the file to disk.
A numeric request ID.
local function save_callback(self, result)
if result.success then
print("success")
else
pprint("failed")
end
end
function save_file()
local text = "hello world!"
browser_io.save_file("hello.txt",text,{mime_type = "text/plain;charset=utf-8"},save_callback)
endRegisters a persistent drag-and-drop file listener.
The listener is installed on the browser window in capture mode so that handled file drops can suppress the browser's normal navigation behaviour.
browser_io.set_drop_listener(nil, callback)
browser_io.set_drop_listener(options, callback)callback
: Function called as:
callback(self, result)The options are the same as open_file():
{
accept = ".txt",
max_size = 16384
}Default max_size is 16 MiB.
{
success = true,
cancelled = false,
operation = "drop_file",
name = "level.ohm",
data = "...",
size = 2048
}Only the first file in a drop operation is processed.
The listener remains active after a callback and can receive additional drop events.
Calling set_drop_listener() again replaces the previous Lua listener.
true when enabled on HTML5.
Returns false on unsupported build targets.
local function drop_callback(self, result)
if result.success then
print("success",result.data)
else
pprint("failed: "..result.error)
end
end
function drop_listener()
browser_io.set_drop_listener({accept = ".ohm",max_size = 16384}, drop_callback)
endRemoves the persistent drag-and-drop listener and releases its Lua callback.
browser_io.cancel_drop_listener()It is good practice to call this from final() when leaving a screen that enabled drag and drop:
function final(self)
browser_io.cancel_drop_listener()
endNo value is returned.