mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-11-20 00:34:50 +00:00
3918e59cc1
* Fix popup location for tables This commit introduces the `popupAbsCoords` option to the $button widget and implements an absolut coordinate format. Coordinates for popups are stored in the format `(x,y,w,h)`. These coordinates are relative to the offset parent of the element that defines the popup. This commits adds a second format `@(x,y,w,h)`. Coordinates specified in this format a relative to the pages root element. The `popupAbsCoords` option of the $button widget enables the use of this coordinates. * Unify the declaration of the RegEx for parsing the popup-position The regular expression was declared in three locations with the same content. This commit supplies a new function `parseCoordinates` in `popup.js`. This function returns the parsed coordinates and understands the classic/absolute coordinates. This function is used in `reveal.js` and `action-popup.js` to parse the coordinates. * Add documentation for coordinate systems * Consolidate creating coordinate strings The Popup object now contains a `buildCoordinates` method that can be used to build coordinate strings. It takes an "enum" for the coordinate- system to use. This makes everything easily extensible and prevents the use of magic values. * Add tests for `parseCoordinates` and `buildCoordinates` * Add `tv-popup-abs-coords` to `collectDOMVariables` This will make the absolute coordinates available for the `DraggableWidget` and the `EventCatcherWidget`. * Add documentation for the `tv-popup-abs-coords` ... to the `DraggableWidget` and the `EventCatcherWidget`. * Fix crash when generating a static version of the TW The Popup class is not initialized in `startup.js` if `$tw.browser` is not true. After having consolidated the facilities for parsing coordinate strings into `popup.js` this breaks because the static build needs to parse coordinate stings even if no Popup module is initialized. This commit solves this problem by making `readPopupState`, `parseCoordinates` and `buildCoordinates` static methods of `popup.js`. It also adds a comment to these functions to show that these can be called safely even if the Popup-Class is not initialized.
98 lines
6.1 KiB
Plaintext
98 lines
6.1 KiB
Plaintext
created: 20201123113532200
|
||
modified: 20221012194222875
|
||
tags: Widgets TriggeringWidgets
|
||
title: EventCatcherWidget
|
||
type: text/vnd.tiddlywiki
|
||
|
||
! Introduction
|
||
|
||
<<.from-version "5.1.23">>
|
||
|
||
//This is an advanced widget intended for use by those familiar with HTML, CSS and JavaScript handling of DOM events.//
|
||
|
||
The event catcher widget traps DOM-initiated Javascript events dispatched within its child content, and allows invoking a series of ActionWidgets in response to those events.
|
||
|
||
In order for the events to be trapped:
|
||
|
||
* The event must be of one of the events specified in the event catcher widget's `events` attribute
|
||
* The event must target a DOM node with an ancestor that matches the widget's `selector` attribute
|
||
* <<.from-version "5.2.2">> Optionally, the DOM node targetted by the event must also match the widgets `matchSelector` attribute
|
||
* The event must support event bubbling
|
||
|
||
Use of the event catcher widget is beneficial 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.
|
||
|
||
! Content and Attributes
|
||
|
||
The content of the `<$eventcatcher>` widget is displayed normally.
|
||
|
||
|!Attribute |!Description |
|
||
|selector |A CSS selector. Only events originating inside a DOM node with this selector will be trapped |
|
||
|matchSelector |<<.from-version "5.2.2">> An optional CSS selector. Only events targetting DOM nodes matching this selector will be trapped |
|
||
|//{any attributes starting with $}// |<<.from-version "5.2.0">> Each attribute name (excluding the $) specifies the name of an event, and the value specifies the action string to be invoked. For example: `$click=<<clickActions>>` |
|
||
|tag |Optional. The HTML element the widget creates to capture the events, defaults to:<br>» `span` when parsed in inline-mode<br>» `div` when parsed in block-mode |
|
||
|class |Optional. A CSS class name (or names) to be assigned to the widget HTML element |
|
||
|stopPropagation |<<.from-version "5.2.0">> Optional. Set to "always" to always stop event propagation even if there are no corresponding actions to invoke, "never" to never stop event propagation, or the default value "onaction" with which event propagation is only stopped if there are corresponding actions that are invoked. |
|
||
|events |//(deprecated – see below)// Space separated list of JavaScript events to be trapped, for example "click" or "click dblclick" |
|
||
|actions-* |//(deprecated – see below)// Action strings to be invoked when a matching event is trapped. Each event is mapped to an action attribute name of the form <code>actions-<em>event</em></code> where <code><em>event</em></code> represents the type of the event. For example: `actions-click` or `actions-dblclick` |
|
||
|
||
<<.from-version "5.2.0">> Note that the attributes `events` and `actions-*` are no longer needed. Instead you can use attributes starting with $ where the attribute name (excluding the $) specifies the name of the event and the value specifies the action string to be invoked. If any attributes with the prefix $ are present then the `types` attribute is ignored.
|
||
|
||
! 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 |
|
||
|`event-type` |The type property of the JavaScript event |
|
||
|`event-detail-*` |Any properties in the detail attribute of the event are made available with the prefix `event-detail-` |
|
||
|`tv-popup-coords` |A relative 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 (see [[Coordinate Systems]] for more information) |
|
||
|`tv-popup-abs-coords` |<<.from-version "5.2.4">> An absolute 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 (see [[Coordinate Systems]] for more information) |
|
||
|`tv-widgetnode-width` |<<.from-version "5.2.3">> `offsetWidth` of the DOM node created by the eventcatcher widget |
|
||
|`tv-widgetnode-height` |<<.from-version "5.2.3">> `offsetHeight` of the DOM node created by the eventcatcher widget |
|
||
|`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 |
|
||
|`event-fromviewport-posx` |<<.from-version "5.2.0">> `x` position of the event relative to the viewport |
|
||
|`event-fromviewport-posy` |<<.from-version "5.2.0">> `y` position of the event relative to the viewport |
|
||
|
||
! 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 clickactions()
|
||
<$action-log item=<<dom-data-item-id>> event=<<event-type>>/>
|
||
\end
|
||
|
||
\define contextmenu-actions()
|
||
<$action-log item=<<dom-data-item-id>> event=<<event-type>>/>
|
||
\end
|
||
|
||
<$eventcatcher selector=".item" $click=<<clickactions>> $contextmenu=<<contextmenu-actions>> tag="div">
|
||
|
||
<div class="item" data-item-id="item1">
|
||
Click events here will be trapped
|
||
</div>
|
||
|
||
<div class="item" data-item-id="item2">
|
||
And here too
|
||
</div>
|
||
|
||
<div data-item-id="item3">
|
||
Not here
|
||
</div>
|
||
|
||
<div class="item" data-item-id="item4">
|
||
And here
|
||
</div>
|
||
|
||
</$eventcatcher>
|
||
```
|