tiddlywiki 5.1.23 → 5.2.2

package/editions/tw5.com/tiddlers/widgets/EventCatcherWidget.tid

@@ -1,33 +1,41 @@
 created: 20201123113532200
-modified: 20201202200719126
-tags: Widgets
+modified: 20220311154749139
+tags: Widgets TriggeringWidgets
 title: EventCatcherWidget
 type: text/vnd.tiddlywiki
 
 ! Introduction
 
 <<.from-version "5.1.23">>
-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:
+//This is an advanced widget intended for use by those familiar with HTML, CSS and JavaScript handling of DOM events.//
 
-* be of one of the types specified as a parameter to the event catcher widget.
-* arise within a DOM node matching the selector specified as a parameter to the widget.
+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:
 
-//This is an advanced widget intended to be used by those familiar with HTML, CSS and JavaScript.//
+* 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 |
-|events |Space separated list of JavaScript events to be trapped, for example "click" or "click 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. Each event is mapped to an action attribute name of the form `actions-"event"` where `event` represents the type of the event. For example: `actions-click` or `actions-dblclick` |
-|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:<br>» `span` when parsed in inline-mode<br>» `div` when parsed in block-mode |
+|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
 
@@ -36,18 +44,20 @@ 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 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 |
+|`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 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 |
+|`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
 
@@ -62,7 +72,7 @@ This example uses the ActionLogWidget and will log the `data-item-id` attribute
 <$action-log item=<<dom-data-item-id>> event=<<event-type>>/>
 \end
 
-<$eventcatcher events="click contextmenu" selector=".item" actions-click=<<clickactions>> actions-contextmenu=<<contextmenu-actions>> tag="div">
+<$eventcatcher selector=".item" $click=<<clickactions>> $contextmenu=<<contextmenu-actions>> tag="div">
 
 <div class="item" data-item-id="item1">
 Click events here will be trapped
@@ -82,4 +92,3 @@ And here
 
 </$eventcatcher>
 ```
-

package/editions/tw5.com/tiddlers/widgets/FieldManglerWidget.tid

@@ -1,9 +1,9 @@
+caption: fieldmangler
 created: 20131024141900000
-modified: 20150220161229000
-tags: Widgets
+modified: 20211009122821085
+tags: Widgets MessageHandlerWidgets
 title: FieldManglerWidget
 type: text/vnd.tiddlywiki
-caption: fieldmangler
 
 ! Introduction
 

package/editions/tw5.com/tiddlers/widgets/ImageWidget.tid

@@ -1,6 +1,6 @@
 title: ImageWidget
 created: 20140416160234142
-modified: 20140820100234142
+modified: 20220101205921813
 tags: Widgets
 caption: image
 
@@ -22,6 +22,14 @@ Any content of the `<$image>` widget is ignored.
 
 The width and the height can be specified as pixel values (eg "23" or "23px") or percentages (eg "23%"). They are both optional; if not provided the browser will use CSS rules to size the image.
 
+! Image Status Classes
+
+<<from-version "5.2.2">> The following CSS classes are automatically added to the `<img>` element to indicate the status of the image. Note that only one of these classes will be added at the same time.
+
+|''tc-image-loading'' |When the image is being loaded |
+|''tc-image-loaded'' |The image has been loaded successfully |
+|''tc-image-error'' |The image could not be loaded |
+
 ! External Images and the ''_canonical_uri'' field
 
 When used to display tiddler-based images, the image widget operates in two distinct modes:

package/editions/tw5.com/tiddlers/widgets/JSONTiddlerWidget.tid

@@ -0,0 +1,22 @@
+title: JSONTiddlerWidget
+created: 20210630100923398
+modified: 20210630100923398
+tags: Widgets
+caption: jsontiddler
+
+! Introduction
+
+The jsontiddler widget renders the fields of a tiddler to display as a JSON object. The fields of the tiddler can be customised or excluded.
+
+The jsontiddler widget is used in system templates to generate JSON representations of tiddlers for saving.
+
+! Content and Attributes
+
+The content of the `<$jsontiddler>` widget is ignored.
+
+|!Attribute |!Description |
+|tiddler |Optional title of the tiddler from which the fields are to be displayed |
+|exclude |Optional space separated list of fields to be excluded |
+|escapeUnsafeScriptChars |If set to "yes" then the `<` character will be escaped to the equivalent `\u003C` encoding |
+|//{any attributes starting with $}// |Each attribute name (without the leading `$`) specifies a field to be modified with the attribute value providing the value to assign to the field  |
+

package/editions/tw5.com/tiddlers/widgets/Keyboard Codes.tid

@@ -0,0 +1,27 @@
+created: 20210427090945829
+modified: 20210525103712235
+tags: KeyboardWidget
+title: Keyboard Codes
+type: text/vnd.tiddlywiki
+
+This is a list of all the key codes supported by the KeyboardWidget:
+
+<kbd>cancel</kbd>, <kbd>help</kbd>, <kbd>backspace</kbd>, <kbd>tab</kbd>, <kbd>clear</kbd>, <kbd>return</kbd>, <kbd>enter</kbd>, <kbd>pause</kbd>, <kbd>escape</kbd>, <kbd>space</kbd>, 
+<kbd>page_up</kbd>, <kbd>page_down</kbd>, <kbd>end</kbd>, <kbd>home</kbd>, <kbd>left</kbd>, <kbd>up</kbd>, <kbd>right</kbd>, <kbd>down</kbd>, <kbd>printscreen</kbd>, <kbd>insert</kbd>, <kbd>delete</kbd>
+
+<kbd>0</kbd>, <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>, <kbd>4</kbd>, <kbd>5</kbd>, <kbd>6</kbd>, <kbd>7</kbd>, <kbd>8</kbd>, <kbd>9</kbd>
+
+<kbd>a</kbd>, <kbd>b</kbd>, <kbd>c</kbd>, <kbd>d</kbd>, <kbd>e</kbd>, <kbd>f</kbd>, <kbd>g</kbd>, <kbd>h</kbd>, <kbd>i</kbd>, <kbd>j</kbd>, <kbd>k</kbd>, <kbd>l</kbd>, <kbd>m</kbd>, <kbd>n</kbd>, <kbd>o</kbd>, <kbd>p</kbd>, <kbd>q</kbd>, <kbd>r</kbd>, <kbd>s</kbd>, <kbd>t</kbd>, <kbd>u</kbd>, <kbd>v</kbd>, <kbd>w</kbd>, <kbd>x</kbd>, <kbd>y</kbd>, <kbd>z</kbd>
+
+<kbd>numpad0</kbd>, <kbd>numpad1</kbd>, <kbd>numpad2</kbd>, <kbd>numpad3</kbd>, <kbd>numpad4</kbd>, <kbd>numpad5</kbd>, <kbd>numpad6</kbd>, <kbd>numpad7</kbd>, <kbd>numpad8</kbd>, <kbd>numpad9</kbd>
+
+<kbd>multiply</kbd>, <kbd>add</kbd>, <kbd>separator</kbd>, <kbd>subtract</kbd>, <kbd>decimal</kbd>, <kbd>divide</kbd>
+
+<kbd>f1</kbd>,  <kbd>f2</kbd>,  <kbd>f3</kbd>,  <kbd>f4</kbd>,  <kbd>f5</kbd>,  <kbd>f6</kbd>,  <kbd>f7</kbd>,  <kbd>f8</kbd>,  <kbd>f9</kbd>,  <kbd>f10</kbd>, <kbd>f11</kbd>, <kbd>f12</kbd><br/>
+<kbd>f13</kbd>, <kbd>f14</kbd>, <kbd>f15</kbd>, <kbd>f16</kbd>, <kbd>f17</kbd>, <kbd>f18</kbd>, <kbd>f19</kbd>, <kbd>f20</kbd>, <kbd>f21</kbd>, <kbd>f22</kbd>, <kbd>f23</kbd>, <kbd>f24</kbd>
+
+<kbd>firefoxsemicolon</kbd>, <kbd>firefoxequals</kbd>, <kbd>firefoxminus</kbd>
+
+<kbd>semicolon</kbd>, <kbd>equals</kbd>, <kbd>comma</kbd>, <kbd>dash</kbd>, <kbd>period</kbd>, <kbd>slash</kbd>, <kbd>backquote</kbd>, <kbd>openbracket</kbd>, <kbd>backslash</kbd>, <kbd>closebracket</kbd>, <kbd>quote</kbd>
+
+<kbd>shift</kbd>, <kbd>ctrl</kbd>, <kbd>alt</kbd>, <kbd>meta</kbd>

package/editions/tw5.com/tiddlers/widgets/KeyboardWidget.tid

@@ -1,7 +1,7 @@
 caption: keyboard
 created: 20140302192136805
-modified: 20161003114634019
-tags: Widgets
+modified: 20211009121239821
+tags: Widgets TriggeringWidgets
 title: KeyboardWidget
 type: text/vnd.tiddlywiki
 
@@ -14,13 +14,23 @@ The keyboard widget allows ActionWidgets to be triggered by specific key combina
 The content of the `<$keyboard>` widget is rendered normally. The keyboard shortcuts only take effect when the focus is within the contained content.
 
 |!Attribute |!Description |
-|actions |A string containing ActionWidgets to be triggered when the key combination is detected |
+|actions |A string containing ActionWidgets to be triggered when the key combination is detected<br><<.from-version "5.2.0">> The variables: ''event-key'', ''event-code'' and ''modifier'' are available for the actions |
 |message |The title of the [[WidgetMessage|Messages]] to generate |
 |param |The parameter to be passed with the [[WidgetMessage|Messages]] |
 |key |Key string identifying the key(s) to be trapped (see below) |
 |class |A CSS class to be assigned to the generated HTML DIV element |
 |tag|<<.from-version "5.1.14">> The html element the widget creates to capture the keyboard event, defaults to:<br>» `span` when parsed in inline-mode<br>» `div` when parsed in block-mode|
 
+! Variables
+
+<<.from-version "5.2.0">> The following variables are made available to the actions:
+
+|!Variables |!Description |
+|`event-key` |The <<.var event-key>> variable contains the character, if possible. eg: `1`. You can experiment with some settings at: [[Key Codes (Example)]] |
+|`event-code` |The <<.var event-code>> variable contains a character description. eg:  `Digit1` instead of `1`. Or `Space` instead of an empty string ` `, which is hard to see|
+|`event-key-descriptor` |The <<.var event-key-descriptor>> variable is available if the keyboard event captured was configured using a [[keyboard shortcut descriptor|Keyboard Shortcut Descriptor]] of the form `((my-shortcut))` which references a configuration tiddler. |
+|`modifier` |The [[modifier Variable]] contains the Modifier Key held during the event (can be <kbd>normal</kbd>, <kbd>ctrl</kbd>, <kbd>shift</kbd>, <kbd>alt</kbd> or combinations thereof) |
+
 ! Key Strings
 
 Key strings are made up of one or more key specifiers separated by spaces. Each key specifier is zero or more of the modifiers <kbd>alt</kbd>, <kbd>shift</kbd>, <kbd>ctrl</kbd> or <kbd>meta</kbd> followed by the name of a key, all joined with "+" plus or "-" minus symbols. Key names are either the letter or digit printed on the key (eg "a" or "1"), or one of the special keys <kbd>backspace</kbd>, <kbd>tab</kbd>, <kbd>enter</kbd> or <kbd>escape</kbd>.
@@ -43,3 +53,7 @@ shift+escape
 ctrl+enter
 ctrl+shift+alt+A
 ```
+
+! More Info
+
+<<list-links "[tag[KeyboardWidget]]">>

package/editions/tw5.com/tiddlers/widgets/LetWidget.tid

@@ -0,0 +1,57 @@
+title: LetWidget
+created: 20211028115900000
+tags: Widgets
+caption: let
+
+! Introduction
+
+<<.from-version "5.2.1">> The <<.wid let>> widget allows multiple variables to be set in one operation. In some situations it can result in simpler code than using the more flexible <<.wlink SetWidget>> widget. It differs from the <<.wlink VarsWidget>> widget in that variables you're defining may depend on earlier variables defined within the same <<.wid let>>.
+
+! Content and Attributes
+
+The content of the <<.wid let>> widget is the scope for the value assigned to the variable.
+
+|!Attribute |!Description |
+|//{attributes not starting with $}// |Each attribute name specifies a variable name. The attribute value is assigned to the variable |
+
+Attributes are evaluated in the order they are written. Attributes with the same name are allowed. Each time a duplicate attribute is encountered, it will replace the existing value set by the earlier duplicate.
+
+! Examples
+
+Consider a case where you need to set multiple variables, where some depend on the evaluation of others.
+
+Using the <<.wid let>> widget, this situation may be handled in the following way:
+
+```
+\define helloworld() Hello world!
+
+<$let target="MyTiddler" currentTiddler={{{ [<target>prefix[$:/settings/for/]] }}} settings={{!!text}} currentTiddler=<<target>> >
+  The settings for <<currentTiddler>> are: <<settings>>
+</$let>
+```
+
+In contrast, here is the same example using the <<.wid set>> widget:
+
+```
+<$set name="target" value="MyTiddler" >
+<$set name="currentTiddler" value={{{ [<target>prefix[$:/settings/for/]] }}} >
+<$set name="settings" value={{!!text}} >
+<$set name="currentTiddler" value=<<target>> >
+  The settings for <<currentTiddler>> are: <<settings>>
+</$set>
+</$set>
+</$set>
+</$set>
+```
+
+! Remarks
+
+This widget differs from <<.wid vars>> in the following way:
+
+* Each variable's definition will be immediately available to all proceeding variables in the same let widget. This differs from vars, in which definitions which depend on some variable will always look to the widget's outer scope for a value.
+
+This widget differs from <<.wid set>> in the following ways:
+
+* A fallback (also known as "emptyValue") cannot be specified
+* Filters cannot be used to produce a conditional variable assignment
+* Variable names must be literal strings

package/editions/tw5.com/tiddlers/widgets/LinkCatcherWidget.tid

@@ -1,7 +1,7 @@
 caption: linkcatcher
 created: 20131024141900000
-modified: 20170707111536556
-tags: Widgets
+modified: 20220226121122574
+tags: Widgets MessageHandlerWidgets TriggeringWidgets
 title: LinkCatcherWidget
 type: text/vnd.tiddlywiki
 
@@ -25,3 +25,4 @@ The content of the `<$linkcatcher>` widget is displayed normally.
 |setTo |Value to be assigned by the `set` attribute |
 |actions |Actions to be performed when a link is caught. Within the action string, the variable "navigateTo" contains the title of the tiddler being navigated. <<.from-version "5.1.23">> the <<.def "modifier">> variable lists the modifier keys that are pressed when the action is invoked. The possible modifiers are ''ctrl'', ''ctrl-alt'', ''ctrl-shift'', ''alt'', ''alt-shift'', ''shift'' and ''ctrl-alt-shift'' |
 
+<<.tip """<<.from-version "5.2.0">> For more complex use cases involving trapping the <<.param tm-navigate>> message consider the MessageCatcherWidget which provides greater flexibility""">>

package/editions/tw5.com/tiddlers/widgets/ListWidget.tid

@@ -1,6 +1,6 @@
 caption: list
 created: 20131024141900000
-modified: 20190608162410684
+modified: 20210416175333981
 tags: Widgets Lists
 title: ListWidget
 type: text/vnd.tiddlywiki
@@ -82,10 +82,43 @@ The action of the list widget depends on the results of the filter combined with
 |template |The title of a template tiddler for transcluding each tiddler in the list. When no template is specified, the body of the ListWidget serves as the item template. With no body, a simple link to the tiddler is returned. |
 |editTemplate |An alternative template to use for [[DraftTiddlers|DraftMechanism]] in edit mode |
 |variable |The name for a [[variable|Variables]] in which the title of each listed tiddler is stored. Defaults to ''currentTiddler'' |
+|counter |<<.from-version "5.2.0">> Optional name for a [[variable|Variables]] in which the 1-based numeric index of each listed tiddler is stored (see below) |
 |emptyMessage |Message to be displayed when the list is empty |
 |storyview |Optional name of module responsible for animating/processing the list |
 |history |The title of the tiddler containing the navigation history |
 
+!! `counter` attribute
+
+The optional `counter` attribute specifies the name of a variable to hold the 1-based numeric index of the current item in the list.
+
+Two additional variables are also set to indicate the first and last items in the list:
+
+* `<counter-variable-name>-first` is set to `yes` for the first entry in the list, `no` for the others
+* `<counter-variable-name>-last` is set to `yes` for the last entry in the list, `no` for the others
+
+For example:
+
+
+```
+<$list filter="[tag[About]sort[title]]" counter="counter">
+<div>
+<<counter>>: ''<$text text=<<currentTiddler>>/>'' (is first: <<counter-first>>, is last: <<counter-last>>)
+</div>
+</$list>
+```
+
+Displays as:
+
+<<<
+<$list filter="[tag[About]sort[title]]" counter="counter">
+<div>
+<<counter>>: ''<$text text=<<currentTiddler>>/>'' (is first: <<counter-first>>, is last: <<counter-last>>)
+</div>
+</$list>
+<<<
+
+Note that using the `counter` attribute can degrade the performance of the list widget in certain circumstances. In particular, it prevents an optimisation that normally occurs when dynamically adding or removing entries.
+
 !! Edit mode
 
 The `<$list>` widget can optionally render draft tiddlers through a different template to handle editing, see DraftMechanism.

package/editions/tw5.com/tiddlers/widgets/ListopsData.tid

@@ -3,5 +3,6 @@ daysoftheweek: four three Fri Thu Wed Tue Mon
 modified: 20151108041839747
 title: ListopsData
 type: application/x-tiddler-dictionary
+tags: [[Operator Examples]]
 
 DataIndex: 

package/editions/tw5.com/tiddlers/widgets/MacroCallWidget.tid

@@ -1,6 +1,6 @@
 caption: macrocall
 created: 20131024141900000
-modified: 20200928102843275
+modified: 20220122193731433
 tags: Widgets
 title: MacroCallWidget
 type: text/vnd.tiddlywiki
@@ -38,6 +38,8 @@ You can see several examples of the macro call widget within the core:
 * Listing field information: [[$:/snippets/allfields]]
 * Generating `data:` URIs: [[$:/themes/tiddlywiki/starlight/styles.tid]]
 
+See also [[WikiText parser mode: macro examples]]
+
 ! Content and Attributes
 
 The content of the `<$macrocall>` widget is ignored.

package/editions/tw5.com/tiddlers/widgets/MessageCatcherWidget.tid

@@ -0,0 +1,46 @@
+created: 20210309133636211
+modified: 20211222153049771
+tags: Widgets MessageHandlerWidgets TriggeringWidgets
+title: MessageCatcherWidget
+type: text/vnd.tiddlywiki
+
+! Introduction
+
+<<.from-version "5.2.0">>
+
+The message catcher widget traps [[messages|Messages]] dispatched within its child content, and allows invoking a series of ActionWidgets in response to those messages.
+
+! Content and Attributes
+
+The content of the `<$messagecatcher>` widget is displayed normally.
+
+|!Attribute |!Description |
+|//{any attributes starting with $}// |Each attribute name (excluding the $) specifies the name of a message, and the value specifies the action string to be invoked |
+|type |Name of the message be trapped, for example "tm-scroll" or "tm-navigate". The `type` and `actions` attributes can be useful when the type of event needs to be specified via a variable or text reference |
+|actions |Action string to be invoked when a matching message is trapped. Must be used in conjunction with the `type` attribute |
+
+! Variables
+
+The message catcher widget sets the following variables within each action string:
+
+|!Variables |!Description |
+|`event-*` |All string-based properties of the `event` object, with the names prefixed with `event-` |
+|`list-event` |A list of the names of each the string-based properties of the `event` object (the names are not prefixed with `event-`) |
+|`event-paramObject-*` |All string-based properties of the `event.paramObject` object, with the names prefixed with `event-paramObject-` |
+|`list-event-paramObject` |A list of the names of each the string-based properties of the `event.paramObject` object (the names are not prefixed with `event-paramObject-`) |
+|`modifier` |For messages that originated with browser events, the modifier keys that were pressed when the event was fired. The possible modifiers are ''normal'' (no modifiers), ''ctrl'', ''ctrl-alt'', ''ctrl-shift'', ''alt'', ''alt-shift'', ''shift'' and ''ctrl-alt-shift'' |
+
+! Example
+
+<$macrocall $name="wikitext-example-without-html" src="""
+\define actions()
+<$action-log/>
+\end
+
+<$messagecatcher $tm-navigate=<<actions>>>
+
+Click on [[this link]] to fire an action. See the browser JavaScript console for the output
+
+</$messagecatcher>
+"""/>
+

package/editions/tw5.com/tiddlers/widgets/MessageHandlerWidgets.tid

@@ -0,0 +1,13 @@
+created: 20211031174746965
+modified: 20211113163856255
+tags: Widgets
+title: MessageHandlerWidgets
+type: text/vnd.tiddlywiki
+
+Message handler widgets are those widgets which can react to one or more [[widget messages|Messages]].
+
+<<.tip "Widget messages are similar to low-level DOM events, except they are higher-level and specific to TiddlyWiki. To handle DOM events see the EventCatcherWidget">>
+
+The following message handler widgets are provided:
+
+<<list-links "[tag[MessageHandlerWidgets]]">>

package/editions/tw5.com/tiddlers/widgets/NavigatorWidget.tid

@@ -1,7 +1,7 @@
 caption: navigator
 created: 20131024141900000
-modified: 20170629074415261
-tags: Widgets
+modified: 20211127023932158
+tags: Widgets MessageHandlerWidgets
 title: NavigatorWidget
 type: text/vnd.tiddlywiki
 
@@ -39,3 +39,6 @@ The following [[Variables]] are assigned by the navigator widget:
 * <<.vlink tv-story-list>>, giving the name of the tiddler containing the story list
 * <<.vlink tv-history-list>>, giving the name of the tiddler containing the history list
 
+! Examples
+
+See [[Creating SubStories]].

package/editions/tw5.com/tiddlers/widgets/QualifyWidget.tid

@@ -0,0 +1,39 @@
+caption: vars
+created: 20220125160004463
+modified: 20220125163041347
+tags: Widgets
+title: QualifyWidget
+
+! Introduction
+
+The <<.wid qualify>> widget sets a variable
+to a unique string that encodes its position within the widget tree, as identified by the stack of transcluded tiddlers that lead to that position.
+
+Internally, it is implemented using the transclusion variable.
+
+! Content and Attributes
+
+The content of the <<.wid qualify>> widget is the scope for the value assigned to the <<.var name>> variable.
+
+|!Attribute |!Description |
+|//title// |The prefix for the string, normally a tiddler title |
+|//name// |The name of the variable to be set to the unique string |
+
+! Examples
+
+The two examples below are identical, but produce different results because the second one has been transcluded from [[another tiddler|$:/editions/tw5.com/widget-examples/qualify-transcluded]].
+
+Each example shows the result of calling <<.var qualify>> and then the value of the <<.vlink transclusion>> variable.
+<$macrocall $name=".example" n="1"
+eg="""<$qualify title="BaseTiddler" name="iamnotanumber">
+<ul>
+<li><code><<iamnotanumber>></code></li>
+<li><code><<transclusion>></code></li>
+</ul>
+</$qualify>
+"""/>
+{{$:/editions/tw5.com/widget-examples/qualify-transcluded}}
+
+! Remarks
+
+In most cases it will be simpler to use the [[qualify Macro]].

package/editions/tw5.com/tiddlers/widgets/RadioWidget Example.tid

@@ -1,5 +1,5 @@
 created: 20201130181015815
-modified: 20201130183426619
+modified: 20210307102027763
 tags: RadioWidget
 title: RadioWidget Example
 type: text/vnd.tiddlywiki
@@ -14,19 +14,22 @@ type: text/vnd.tiddlywiki
 
 !! Using Actions
 
-If you select an option, the value is written to $:/temp/test/value and the ''id'' field of tiddler: $:/temp/test will be updated. 
+When you select an option below the following acitons will occur:
 
-A notification showing the ''actionValue'' will be shown.
+* the value is written to $:/temp/test/value
+* the ''id'' field of tiddler: $:/temp/test will be updated
+* a notification showing the ''actionValue'' will be shown
 
 <$tiddler tiddler="$:/temp/test">
-	<$radio field="id" value="a" actions=<<radioActions>> > Option a </$radio>|
-	<$radio field="id" value="b" actions=<<radioActions>> > Option b </$radio>|
-	<$radio field="id" value="c" actions=<<radioActions>> > Option c </$radio>|
+
+<$radio field="id" value="a" actions=<<radioActions>> > Option a </$radio>
+
+<$radio field="id" value="b" actions=<<radioActions>> > Option b </$radio>
+
+<$radio field="id" value="c" actions=<<radioActions>> > Option c </$radio>
+
 </$tiddler>
 
----
+The wikitext of this example is shown below:
 
-<details>
-    <summary>Show the code [[RadioWidget Example]]</summary>
-    <pre><code><$view mode=text&><pre><code>
-</details>
+<$codeblock code={{RadioWidget Example!!text}}/>

package/editions/tw5.com/tiddlers/widgets/RadioWidget.tid

@@ -1,7 +1,7 @@
 caption: radio
 created: 20131212195353929
-modified: 20201130184330254
-tags: Widgets
+modified: 20211009121654734
+tags: Widgets TriggeringWidgets
 title: RadioWidget
 type: text/vnd.tiddlywiki
 
@@ -15,13 +15,13 @@ The content of the `<$radio>` widget is displayed within an HTML `<label>` eleme
 
 |!Attribute |!Description |
 |tiddler |Title of the tiddler to manipulate (defaults to the [[current tiddler|Current Tiddler]]) |
-|field |The field of the //tiddler// bound to the radio button|
-|index|<<.from-version "5.1.14">> The index of the //tiddler// being [[DataTiddler|DataTiddlers]] bound to the radio button<<.tip "takes precedence over //field//">>|
-|value |The value for the //field// or //index// of the //tiddler//|
-|class |The CSS classes assigned to the label around the radio button<$macrocall $name=".tip" _="""<<.from-version "5.1.14">> `tc-radio` is always applied by default, as well as `tc-radio-selected` when selected"""/>|
-|actions|<<.from-version "5.1.23">> Optional, A string containing ActionWidgets to be triggered when the value changes. <br>The variable: ''actionValue'' is available for the actions.  |
-|disabled|<<.from-version "5.1.23">> Optional, disables the radio input if set to "yes". Defaults to "no"|
-
+|field |The field of the //tiddler// bound to the radio button |
+|index|<<.from-version "5.1.14">> The index of the //tiddler// being [[DataTiddler|DataTiddlers]] bound to the radio button (takes precedence over //field//) |
+|default |<<.from-version "5.2.0">> The default value to be used for matching if the tiddler, field or index are missing |
+|value |The value for the //field// or //index// of the //tiddler// |
+|class |The CSS classes assigned to the label around the radio button <<.from-version "5.1.14">> `tc-radio` is always applied by default, as well as `tc-radio-selected` when selected |
+|actions|<<.from-version "5.1.23">> Optional string containing ActionWidgets to be triggered when the value changes. <br>The variable: ''actionValue'' is available for the actions  |
+|disabled|<<.from-version "5.1.23">> Optional. Set to "yes" to disable the radio input. Defaults to "no" |
 
 !! Field Mode
 

package/editions/tw5.com/tiddlers/widgets/RangeWidget Example.tid

@@ -1,5 +1,5 @@
 created: 20201130191618831
-modified: 20201130194441670
+modified: 20210307102027763
 tags: RangeWidget
 title: RangeWidget Example
 type: text/vnd.tiddlywiki
@@ -48,7 +48,6 @@ type: text/vnd.tiddlywiki
 
 ---
 
-<details>
-    <summary>Show the code [[RangeWidget Example]]</summary>
-    <pre><code><$view mode=text&><pre><code>
-</details>
+The wikitext of this example is shown below:
+
+<$codeblock code={{RangeWidget Example!!text}}/>