Raw Extension API Reference

Type: string (property)

Configures the author or developer name of the loaded extension. This must be defined inside your extension's init() function alongside the extension name to register your module's identity.

HPR.authorName = "Plexescor"

Type: string (property)

Configures the custom display name of the loaded extension. Must be set inside your extension's init() function alongside the author name to register your module's identity.

HPR.extensionName = "My Custom HPR Extension"

Returns: uint64 (Unix timestamp in milliseconds)

Returns the current system time as a Unix timestamp in milliseconds. Useful for timestamping events, measuring elapsed durations, or seeding time-series database entries.

local now = HPR.getTime_MS()
print("Current time (ms): " .. now)

Parameters: ms: int (milliseconds) — Returns: nothing

Blocks the calling extension's background thread for the specified number of milliseconds. Since every extension runs on its own isolated OS thread, this only pauses your script — HPR and all other extensions remain fully responsive. Useful for rate-limiting inside a callback or performing a one-shot delayed action without restructuring your tick loop.

HPR.sleep_E(2000) -- pause this extension thread for 2 seconds

Returns: boolean

Returns true if the HPR Slint UI window is currently loaded and active, false otherwise. Use this as a guard before calling HPR.setUiProperty_E or HPR.registerUiCallback in situations where you need an explicit check (e.g. in a tick loop rather than a one-time init() call). Note that both UI functions already silently ignore calls when the UI is not active.

if HPR.isUiActive_E() then
    HPR.setUiProperty_E("statusLabel_S", "Ready")
end

Parameters: (name, matchesEnvironment, initialize, isUsable, getCurrentWindow, getCurrentTitle)

Registers a completely new custom tracking backend dynamically. HPR's backend manager calls the registered functions during startup to inspect compositors and get current window classes/titles. For a detailed guide on using this, please consult the Custom Backend Tutorial.

function init()
    HPR.registerBackend_E(
        "MyCompositor",
        function(env) return env:find("MyCompositor") ~= nil end,
        function() print("Loaded!") end,
        function() return true end,
        function() return "browser" end,
        function() return "Home Page" end
    )
end

Parameters: eventName: string, callback: function — Returns: int (subscription ID)

Subscribes a Lua callback function to a system or custom named event. Whenever the event is emitted, your callback will run. Returns a unique subscription ID integer that must be saved to disconnect later.

local subId = HPR.connect_E("MIDNIGHT_ROLLOVER", function(data)
    print("Day rolled over!")
end)

Parameters: eventName: string, data: table (optional) — Returns: nothing

Broadcasts a named signal to the Event Hub, triggering all active callbacks connected to this event name. You can optionally pass a Lua table/value containing a custom payload structure.

HPR.emit_E("my_custom_alarm", { temp = 82.5, warning = true })

Parameters: eventName: string, subscriptionId: int — Returns: nothing

Unsubscribes a specific listener using its unique subscription ID. Always invoke this inside onExit() to release hooks and prevent memory leaks.

function onExit()
    HPR.disconnect_E("MIDNIGHT_ROLLOVER", subId)
end

Parameters: sql: string, params: table (optional) — Returns: nothing

Executes a write SQL statement (CREATE, INSERT, UPDATE, DELETE) against HPR's SQLite database. The optional second argument is a Lua table of strings bound to ? placeholders in the SQL query, preventing SQL injection. Always use parameterized queries when inserting user-derived data.

-- Create a table
HPR.dbExecute_E([[
    create table if not exists my_data (
        key text unique,
        value text
    );
]])

-- Insert with parameterized values
HPR.dbExecute_E(
    "insert or replace into my_data (key, value) values (?, ?);",
    { "active_app", "firefox" }
)

Parameters: sql: string, params: table (optional) — Returns: table (array of row tables)

Executes a read SQL statement (SELECT) and returns the results as a Lua table. Each element in the returned table is a row, represented as a Lua table with column names as keys.

local rows = HPR.dbQuery_E("select key, value from my_data;")

for i, row in ipairs(rows) do
    print(row.key .. " = " .. row.value)
end

Parameters: none — Returns: string (full absolute file path)

Returns the absolute, resolved filesystem path of the currently loaded historical database. Returns an empty string if HPR is currently in live-tracking mode.

local histPath = HPR.getLoadedHistDbPath_E()
print("Loaded past DB path: " .. histPath)

Parameters: sql: string, params: table (optional) — Returns: table (array of rows)

Executes a read SQL query against the currently active historical database file (set during a "LOAD_DATABASE_SINGULAR" calendar switch). This is a safe, high-level helper that completely abstracts database opening, folder traversal, and closing operations. Blocks for up to 5 seconds waiting for the async historical DB load to complete before running the query.

local rows = HPR.dbQueryHistorical_E("select song_name from spotify_songs;")

Parameters: name: string, value: any — Returns: nothing

Sets a named property on the root Slint UI component. The property name must exactly match an in property defined in app-window.slint. HPR converts the Lua value to a C++ intermediate on the extension thread, then dispatches the Slint update to the main UI thread. Supported types: string, number, boolean, table (array → Slint model, key-value → Slint struct). If the UI is not yet loaded, the call is silently ignored.

-- Set a simple string property
HPR.setUiProperty_E("windowName_S", "firefox")

-- Set an array of structs (each struct maps to a Slint struct)
HPR.setUiProperty_E("spotifySongs_S", {
    { name = "Song A", artist = "Artist 1", duration = "01:23:45", duration_i = 5025000 },
    { name = "Song B", artist = "Artist 2", duration = "00:45:30", duration_i = 2730000 },
})

Parameters: name: string, luaFunction: function — Returns: nothing

Registers a Lua function as a handler for a Slint callback. When the named callback is triggered from the Slint UI (e.g. a button click), HPR invokes your Lua function. The callback name must exactly match a callback defined in the Slint component. If the UI is not yet loaded, the call is silently ignored.

HPR.registerUiCallback("myButtonClicked", function()
    print("Button was clicked in the UI!")
end)

Parameters: ms: int (milliseconds) — Returns: string

Converts a duration in milliseconds to a human-readable "HH:MM:SS" formatted string. Commonly used for displaying tracked time in the UI.

local formatted = HPR.formatTime_HHMMSS_E(5025000)
print(formatted) -- "01:23:45"

Parameters: ms: int (Unix timestamp in ms) — Returns: string

Converts a Unix timestamp in milliseconds to a date string in "DD-MM-YY" format.

Parameters: ms: int (Unix timestamp in ms) — Returns: string

Converts a Unix timestamp in milliseconds to a date string in "MM-YY" format (month and year only).

Parameters: ms: int (Unix timestamp in ms) — Returns: string

Converts a Unix timestamp in milliseconds to a 12-hour time string in "HH:MM:SS AM/PM" format.

Parameters: dateStr: string ("DD-MM-YY") — Returns: int (Unix timestamp in ms)

Parses a "DD-MM-YY" date string and returns the corresponding Unix timestamp in milliseconds. The inverse of convertToDate_DDMMYY_E.

Parameters: dateStr: string ("MM-YY") — Returns: int (Unix timestamp in ms)

Parses a "MM-YY" date string and returns the corresponding Unix timestamp in milliseconds. The inverse of convertToDate_MMYY_E.

Parameters: dateStr: string ("DD-MM-YY") — Returns: string ("MM-YY")

Extracts the month-year portion from a full "DD-MM-YY" date string, returning just "MM-YY". Useful for grouping daily records by month.