QuickStart Guide

First, what is HPR's Event Hub?

Under the hood, HPR is a beautifully multi-threaded beast. It runs several independent systems all at the same time on separate background threads: the window tracker, the database writer, the daily midnight rollover scheduler, and your custom Lua extensions. The Event Hub is HPR's internal messaging backbone that lets all these isolated systems talk to each other by broadcasting signals.

Think of the Event Hub like a cork bulletin board in the middle of HPR's headquarters. Any system can walk up and pin a message to it. Any extension that is subscribed to that specific message type gets notified instantly the exact millisecond it is pinned—no periodic checking required! Instead of your extension constantly asking "hey, did the window change yet?" every single second, HPR's window tracker itself walks up and taps your extension on the shoulder the instant a change occurs.

Polling (onTick) vs. Event-Driven (connect_E)

The onTick polling approach we built in Step 3 works fine, but let's be honest: it is kind of dumb. Your extension has to wake up every few hundred milliseconds, run code to check the state, and go back to sleep—even if you've been working in the exact same text editor window for three hours straight! That is a waste of clock cycles.

Event-driven programming is way smarter. Your callback function only wakes up and executes when something actually happens in the real world. For window tracking in particular, events are the correct tool because users do not switch windows on a fixed, predictable schedule.

How connect_E works (and your subscription receipt)

To tune in, we call HPR.connect_E(). This function takes two arguments: the name of the event string we want to listen to, and a callback function to run when the event occurs.

Crucially, HPR.connect_E() returns a subscription ID integer. Think of this ID as your claim receipt. It is the only way HPR knows how to identify your listener, and it is the only way you can cancel that subscription later. Because of this, you should always save this ID in a variable at the very top of your script so that your entire file has access to it.

HPR's Automatic RAII Connection Tracking

When HPR runs your extension, it spins up an isolated Lua virtual machine. While this VM is alive, your callback function exists in memory, and HPR's C++ event registry holds a reference to that Lua function.

To prevent classic use-after-free bugs and segmentation faults (segfaults) upon extension shutdown, HPR's C++ manager features an elegant, automatic RAII lifecycle tracking architecture. The core engine dynamically registers and monitors every Event Hub subscription established by your extension.

When your extension is stopped, disabled, or reloaded, HPR automatically and cleanly disconnects all active subscriptions from the C++ event loop before the Lua VM is destroyed. Manual cleanup via HPR.disconnect_E() is completely optional but still a great practice to keep your code organized!

What does WINDOW_CHANGED actually pass to us?

When the WINDOW_CHANGED event fires, the Event Hub passes a table with detailed window information directly to your callback function's argument. Specifically, this table contains two highly useful string properties: data.fromWindow (the class name of the window you just left) and data.toWindow (the class name of the window you just focused, e.g. "chrome", "code", or "spotify"). This makes writing complex, event-driven window transitions effortless!

HPR.authorName = "DevFriend"
HPR.extensionName = "EventMaster"

local changeSubId = nil

function init()
    print("Starting EventMaster...")
    
    -- Listen to a REAL built-in event when focus changes.
    -- data will be a table containing fromWindow and toWindow strings
    changeSubId = HPR.connect_E("WINDOW_CHANGED", function(data)
        print("[Event] Active application class switched to: " .. data.toWindow)
    end)
    
    return 3000 -- Run onTick every 3 seconds
end

function onTick(delta)
    print("[Tick] Tick delta: " .. delta .. "ms")
end

function onExit()
    print("Shutting down cleanly...")
    
    -- Optional/Best Practice: Unregister event hook (HPR automatically disconnects on exit)
    if changeSubId then
        HPR.disconnect_E("WINDOW_CHANGED", changeSubId)
    end
end

-- Subscribed, but no ID saved to disconnect early
function init()
    HPR.connect_E("WINDOW_CHANGED", callback)
end

local subId = nil

function init()
    subId = HPR.connect_E("WINDOW_CHANGED", callback)
end

function onExit()
    -- Explicit cleanup is still a great practice!
    if subId then
        HPR.disconnect_E("WINDOW_CHANGED", subId)
    end
end

-- Saves at global root (extensions/settings.csv)
local data = HPR.readCsv_E("settings.csv")

-- Dynamically resolve paths relative to your folder
local myDir = HPR.getExtensionDir_E()
local data = HPR.readCsv_E(myDir .. "settings.csv")

-- Fails or times out on IPv6 loopback resolution
local body, status = HPR.httpGet_E(
    "localhost:5600", 
    "/api/0/buckets", 
    false
)

-- Bypasses DNS lookup and hits IPv4 directly
local body, status = HPR.httpGet_E(
    "127.0.0.1:5600", 
    "/api/0/buckets", 
    false
)