koreader-mirror/doc/Events.md

Events

Overview

All widgets is a subclass of @{ui.widget.eventlistener}, therefore inherit the @{ui.widget.eventlistener:handleEvent|handleEvent} method. To send an event to a widget, you can simply invoke the handleEvent method like the following:

widget_foo:handleEvent(Event:new("Timeout"))

Builtin events

Reader events

• UpdatePos: emitted by typesetting related modules to notify other modules to recalculate the view based on the new typesetting.

• PosUpdate: emitted by readerrolling module to signal a change in pos.

Event propagation

Most of the UI components is a subclass of @{ui.widget.container.widgetcontainer|WidgetContainer}. A WidgetContainer is an array that stores a list of children widgets.

When @{ui.widget.container.widgetcontainer:handleEvent|WidgetContainer:handleEvent} is called with a new event, it will run roughly the following code:

-- First propagate event to its children
for _, widget in ipairs(self) do
    if widget:handleEvent(event) then
        -- stop propagating when an event handler returns true
        return true
    end
end
-- If not consumed by children, try consume by itself
return self["on"..event.name](self, unpack(event.args))