Introduction

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.

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.

In order for the events to be trapped:

• The event must be of one of the events specified in the event catcher widget's attributes
• The event must target a DOM node with an ancestor that matches the widget's selector attribute
• Introduced in v5.2.2 Optionally, the DOM node targeted by the event must also match the widget's matchSelector attribute
• The event must support event bubbling
• New in v5.4.0 The widget must be enabled (enabled="yes")
• New in v5.4.0 Pointer events may continue to be trapped outside the widget DOM boundaries if pointer capture is enabled

Content and Attributes

The content of the <$eventcatcher> widget is displayed normally.

New in v5.4.0 The attributes events and actions-* have been removed as they 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.

Pointer Capture

New in v5.4.0 The pointerCapture attribute enables native Pointer Events support using setPointerCapture(). This allows pointer interactions to continue to be tracked even if the pointer moves outside the widget’s DOM nodes or the browser viewport.

This is particularly useful for drag-and-drop interfaces, sliders, drawing tools, and other pointer-driven interactions.

Values

• no (default)

Pointer capture is not used. Pointer events are only received while the pointer remains within the widget’s DOM nodes.

• yes

Pointer capture is enabled whenever a pointerdown event occurs. All pointer event handlers specified on the widget remain active for the lifetime of the widget.

• dynamic

Pointer capture is enabled only for the duration of an active pointer interaction. Event handlers for pointerup, pointercancel, and optionally pointermove are attached only while pointer capture is active and are removed when the interaction ends. This mode minimizes active event listeners and is recommended for performance-sensitive use cases.

Notes

• Pointer capture only applies to pointer events such as pointerdown, pointermove, pointerup, and pointercancel
• Pointer capture does not affect mouse or touch events
• Pointer capture is automatically released on pointerup or pointercancel

Enabling and Disabling the Widget

New in v5.4.0 The enabled attribute allows the event catcher widget to be temporarily disabled without removing it from the DOM.

When enabled="no":

• All event listeners are removed
• No actions are invoked
• The widget’s DOM node and child content remain unchanged

Variables

The following variables are made available to the actions:

Example

This example illustrates how to work with click and right click events:

\procedure card-click-actions()  
<$action-setfield $tiddler="$:/temp/selected-card" text=<<dom-data-card-id>>/>  
\end  
  
\procedure card-context-actions()  
<$action-setfield $tiddler="$:/temp/context-menu"   
  text=`Showing context menu for card: {{!!card}}`
  card=<<dom-data-card-id>>
  x=<<event-fromviewport-posx>>  
  y=<<event-fromviewport-posy>>/>  
\end  
  
<$eventcatcher   
  selector=".gallery-card"   
  $click=<<card-click-actions>>   
  $contextmenu=<<card-context-actions>>  
  class="card-gallery">  
  
<div class="gallery-card" data-card-id="card1" style="border: 1px solid #ccc; padding: 10px; margin: 5px; cursor: pointer;">  
  <h3>1: Mountain Landscape</h3>  
  <p>Click to select, right-click for options</p>  
</div>  
  
<div class="gallery-card" data-card-id="card2" style="border: 1px solid #ccc; padding: 10px; margin: 5px; cursor: pointer;">  
  <h3>2: Ocean View</h3>  
  <p>Click to select, right-click for options</p>  
</div>  
  
<div class="gallery-card" data-card-id="card3" style="border: 1px solid #ccc; padding: 10px; margin: 5px; cursor: pointer;">  
  <h3>3: City Skyline</h3>  
  <p>Click to select, right-click for options</p>  
</div>  
  
</$eventcatcher>  
  
<!-- Display selected card info -->  
<$reveal type="nomatch" state="$:/temp/selected-card" text="">  
<div style="background: #f0f0f0; padding: 10px; margin-top: 10px;">  
  <strong>Selected:</strong> {{$:/temp/selected-card}}  
</div>  
</$reveal>  
  
<!-- Display context menu info -->  
<$reveal type="nomatch" state="$:/temp/context-menu" text="">  
<div style="background: #ffe0e0; padding: 10px; margin-top: 10px;">  
  {{$:/temp/context-menu}}  
</div>  
</$reveal>