From cb62c8c96dd5cfa9ef6af2dad11470665d4525c6 Mon Sep 17 00:00:00 2001 From: saqimtiaz Date: Mon, 23 Nov 2020 18:07:41 +0100 Subject: [PATCH] Docs for eventcatcher (#5097) --- .../tiddlers/variables/modifier Variable.tid | 4 +- .../tiddlers/widgets/EventCatcherWidget.tid | 78 +++++++++++++++++++ 2 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 editions/tw5.com/tiddlers/widgets/EventCatcherWidget.tid diff --git a/editions/tw5.com/tiddlers/variables/modifier Variable.tid b/editions/tw5.com/tiddlers/variables/modifier Variable.tid index d5db7d702..835b3e7cb 100644 --- a/editions/tw5.com/tiddlers/variables/modifier Variable.tid +++ b/editions/tw5.com/tiddlers/variables/modifier Variable.tid @@ -1,8 +1,10 @@ +created: 20201123120203415 +modified: 20201123120211360 tags: Variables [[Core Variables]] title: modifier Variable type: text/vnd.tiddlywiki -Within the ''action'' string of the DroppableWidget, the ''action'' string of the ButtonWidget and the ''action'' string of the LinkCatcherWidget, the <<.def modifier>> [[variable|Variables]] contains the modifier key(s) held during the drag-process. +Within the ''action'' string of the DroppableWidget, the ''action'' string of the ButtonWidget and the ''action'' string of the LinkCatcherWidget and the EventCatcherWidget, the <<.def modifier>> [[variable|Variables]] contains the modifier key(s) held during the drag-process. The possible keys are ''meta'', ''ctrl'', ''shift'', ''alt'', ''meta'' and ''ctrl'', ''meta'' and ''shift'', ''meta'' and ''alt'', ''ctrl'' and ''shift'', ''alt'' and ''shift'', ''ctrl'' and ''alt'', ''ctrl'' and ''alt'' and ''shift'', ''meta'' and ''alt'' and ''shift'', ''meta'' and ''ctrl'' and ''shift'', ''meta'' and ''ctrl'' and ''alt'', ''meta'' and ''ctrl'' and ''alt'' and ''shift'' The variable contains a string that identifies the keys: diff --git a/editions/tw5.com/tiddlers/widgets/EventCatcherWidget.tid b/editions/tw5.com/tiddlers/widgets/EventCatcherWidget.tid new file mode 100644 index 000000000..dc8e6b0e3 --- /dev/null +++ b/editions/tw5.com/tiddlers/widgets/EventCatcherWidget.tid @@ -0,0 +1,78 @@ +created: 20201123113532200 +modified: 20201123143104394 +tags: Widgets +title: EventCatcherWidget +type: text/vnd.tiddlywiki + +! Introduction + +The event catcher widget traps JavaScript events dispatched within its child content, and allows invoking a series of ActionWidgets in response to the events. + +In order for the events to be trapped they must: + +* be of the type specified as a parameter to the event catcher widget. +* arise within a DOM node matching the selector specified as a parameter to the widget. + +Use of the event catcher widget is useful when using large numbers of other trigger widgets such as the ButtonWidget is causing performance problems. The workflow it enables is akin to what is referred to as "event delegation" in JavaScript parlance. + +//This is an advanced widget intended to be used by those familiar with HTML, CSS and JavaScript.// + +! Content and Attributes + +The content of the `<$eventcatcher>` widget is displayed normally. + +|!Attribute |!Description | +|type |The JavaScript event type to be trapped, for example "click", or "dblclick" | +|selector |A CSS selector. Only events originating inside a DOM node with this selector will be trapped. | +|actions |Action strings to be invoked when a matching event is trapped | +|class |An optional CSS class name to be assigned to the HTML element | +|tag |Optional. The html element the widget creates to capture the events, defaults to:
» `span` when parsed in inline-mode
» `div` when parsed in block-mode | + +! Variables + +The following variables are made available to the actions: + +|!Variables |!Description | +|`dom-*` |All DOM attributes of the node matching the given selector are made available as variables, with the prefix `dom-` | +|`modifier` |The [[modifier Variable]] contains the Modifier Key held during the event (can be "normal", "ctrl", "shift", "alt" or combinations thereof) | +|`event-mousebutton`|The mouse button (if any) used to trigger the event (can be "left", "right" or "middle"). Note that not all event types support the mousebutton property | +|`tv-popup-coords`|A co-ordinate string that can be used with the ActionPopupWidget to trigger a popup at the DOM node matching the selector where the event originated | +|`tv-selectednode-posx`|`x` offset position of the selected DOM node | +|`tv-selectednode-posy`|`y` offset position of the selected DOM node | +|`tv-selectednode-width`|`offsetWidth` of the selected DOM node | +|`tv-selectednode-height`|`offsetHeight` of the selected DOM node | +|`event-fromselected-posx`|`x` position of the event relative to the selected DOM node | +|`event-fromselected-posy`|`y` position of the event relative to the selected DOM node | +|`event-fromcatcher-posx`|`x` position of the event relative to the event catcher DOM node | +|`event-fromcatcher-posy`|`y` position of the event relative to the event catcher DOM node | + +! Example + +This example uses the ActionLogWidget and will log the `data-item-id` attribute of the clicked DOM node to the browser's JavaScript [[console|Web Developer Tools]] + +``` +\define myactions() +<$action-log item=<>/> +\end + +<$eventcatcher type="click" selector=".item" actions=<> tag="div"> + +
+Click events here will be trapped +
+ +
+And here too +
+ +
+Not here +
+ +
+And here +
+ +""" +``` +