Added basalt.onEvent(event, callback)

Added basalt.removeEvent(eventcallback)
basalt.triggerEvent(event, ...)

Fixed a event is nil error in Container.lua

src/elements/Container.lua

@@ -347,7 +347,7 @@ end
 
 local function convertMousePosition(self, event, ...)
     local args = {...}
-    if event:find("mouse_") then
+    if event and event:find("mouse_") then
         local button, absX, absY = ...
         local xOffset, yOffset = self.get("offsetX"), self.get("offsetY")
         local relX, relY = self:getRelativePosition(absX + xOffset, absY + yOffset)

src/main.lua

@@ -374,4 +374,62 @@ function basalt.getAPI(name)
     return elementManager.getAPI(name)
 end
 
+--- Registers a callback function for a specific event
+--- @shortDescription Registers an event callback
+--- @param eventName string The name of the event to listen for (e.g. "mouse_click", "key", "timer")
+--- @param callback function The callback function to execute when the event occurs
+--- @usage basalt.onEvent("mouse_click", function(button, x, y) basalt.debug("Clicked at", x, y) end)
+function basalt.onEvent(eventName, callback)
+    expect(1, eventName, "string")
+    expect(2, callback, "function")
+
+    if not basalt._events[eventName] then
+        basalt._events[eventName] = {}
+    end
+
+    table.insert(basalt._events[eventName], callback)
+end
+
+--- Removes a callback function for a specific event
+--- @shortDescription Removes an event callback
+--- @param eventName string The name of the event
+--- @param callback function The callback function to remove
+--- @return boolean success Whether the callback was found and removed
+function basalt.removeEvent(eventName, callback)
+    expect(1, eventName, "string")
+    expect(2, callback, "function")
+
+    if not basalt._events[eventName] then
+        return false
+    end
+
+    for i, registeredCallback in ipairs(basalt._events[eventName]) do
+        if registeredCallback == callback then
+            table.remove(basalt._events[eventName], i)
+            return true
+        end
+    end
+
+    return false
+end
+
+--- Triggers a custom event and calls all registered callbacks
+--- @shortDescription Triggers a custom event
+--- @param eventName string The name of the event to trigger
+--- @vararg any Arguments to pass to the event callbacks
+--- @usage basalt.triggerEvent("custom_event", "data1", "data2")
+function basalt.triggerEvent(eventName, ...)
+    expect(1, eventName, "string")
+    
+    if basalt._events[eventName] then
+        for _, callback in ipairs(basalt._events[eventName]) do
+            local ok, err = pcall(callback, ...)
+            if not ok then
+                errorManager.header = "Basalt Event Callback Error"
+                errorManager.error("Error in event callback for '" .. eventName .. "': " .. tostring(err))
+            end
+        end
+    end
+end
+
 return basalt

src/plugins/animation.lua

@@ -270,6 +270,27 @@ function Animation:event(event, timerId)
     end
 end
 
+--- Stops the animation immediately: cancels timers, completes running anim instances and clears the element property
+--- @shortDescription Stops the animation
+function Animation:stop()
+    if self.timer then
+        pcall(os.cancelTimer, self.timer)
+        self.timer = nil
+    end
+
+    for _, seq in ipairs(self.sequences) do
+        for _, anim in ipairs(seq) do
+            pcall(function()
+                if anim and anim.complete then anim:complete() end
+            end)
+        end
+    end
+
+    if self.element and type(self.element.set) == "function" then
+        pcall(function() self.element.set("animation", nil) end)
+    end
+end
+
 Animation.registerAnimation("move", {
     start = function(anim)
         anim.startX = anim.element.get("x")
@@ -519,6 +540,18 @@ function VisualElement.setup(element)
     element.defineEvent(element, "timer")
 end
 
+-- Convenience to stop animations from the element
+function VisualElement.stopAnimation(self)
+    local anim = self.get("animation")
+    if anim and type(anim.stop) == "function" then
+        anim:stop()
+    else
+        -- fallback: clear property
+        self.set("animation", nil)
+    end
+    return self
+end
+
 --- Creates a new Animation Object
 --- @shortDescription Creates a new animation
 --- @return Animation animation The new animation