From a47b3b1a5b78fe952f1fc6126b632d707d2a97b5 Mon Sep 17 00:00:00 2001 From: Frans de Jonge Date: Fri, 30 Aug 2019 15:06:30 +0200 Subject: [PATCH] [doc] Add internal documentation references (#5285) Also some minor grammatical fixes. --- doc/Events.md | 8 ++++---- frontend/ui/event.lua | 8 +++++--- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/doc/Events.md b/doc/Events.md index 7f0c284b9..924441a15 100644 --- a/doc/Events.md +++ b/doc/Events.md @@ -3,7 +3,7 @@ Events ## Overview ## -All widgets is a subclass of @{ui.widget.eventlistener}, therefore inherit +All widgets are a subclass of @{ui.widget.eventlistener}, therefore they 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: @@ -45,15 +45,15 @@ return self["on"..event.name](self, unpack(event.args)) ``` ## Event system -Event system is used for widgets to communicate with each others. +The @{ui.event|Event} system is used by widgets to communicate. Each event is an object that has two properties: `args` and `handler`. `handler` is the name of function that will be called on receive. `args` is a table that contains all the arguments needed to be passed to the event handler. When a widget receives a event, it will first check to see if `self[event.handler]` exists. If yes, the `self[event.handler]` function will be called and the return value of the handler will be returned to UIManager. Notice that if you don't want the event propagate after consumed in your handler, your handler must return `true`. Otherwise, the event will be passed to other widgets' handlers until one of the handlers returns `true`. -`WidgetContainer` is a special kind of widget. When it receives an event, it will first propagate the event to all its children. If the event is still not consumed (handler returns `true`), then it will try to handle by itself. +@{ui.widget.container.widgetcontainer|WidgetContainer} is a special kind of widget. When it receives an event, it will first propagate the event to all its children. If the event is still not consumed (i.e., its handler returns `true`), then it will try to handle the event by itself. -When you call `UIManager:show` on an widget, this widget will be added to the top of `UIManager._window_stack`. +When you call @{ui.uimanager.show|UIManager:show} on a widget, this widget will be added to the top of the `UIManager._window_stack`. Events are sent to the first widget in `UIManager._window_stack`. If it is not consumed, then UIManager will try to send it to all active widgets (`widget.is_always_active` equals `true`) in the `_window_stack`. ## Draw Page Code Path diff --git a/frontend/ui/event.lua b/frontend/ui/event.lua index 349fd3f35..d59cb544e 100644 --- a/frontend/ui/event.lua +++ b/frontend/ui/event.lua @@ -1,10 +1,12 @@ --[[-- -Events are messages that are passed through the widget tree +Events are messages that are passed through the widget tree. Events need a "name" attribute as minimal data. -In order to see how event propagation works and how to make +To see how event propagation works and how to make widgets event-aware see the implementation in @{ui.widget.container.widgetcontainer}. + +A detailed guide to events can be found in @{Events.md|the event programmer's guide}. ]] --[[-- @@ -15,7 +17,7 @@ widgets event-aware see the implementation in @{ui.widget.container.widgetcontai local Event = {} --[[-- -Create a new event. +Creates a new event. @string name @tparam[opt] ... arguments for the event