This page is part of a static HTML representation of the TiddlyWiki at https://tiddlywiki.com/

How to create keyboard shortcuts

Customise TiddlyWiki Learning


TiddlyWiki distinguishes two types of keyboard shortcuts. Those that are limited to work within input fields or textareas which are handled by the $keyboard widget and keyboard shortcuts that work globally - which means that only the page needs to have focus in order for them to be accessible. The latter are handled by a mechanism that starts to work when a wiki is loaded

The configuration mechanism is the same for both shortcut-types

A tiddler with the prefix $:/config/ShortcutInfo/ and a unique suffix appended, like my-shortcut, makes the new shortcut appear in the $:/ControlPanel within the Keyboard Shortcuts Tab. An optional description can be added within its text field

In the Keyboard Shortcuts Tab the key combination that should trigger the shortcut can be configured:

Look for the unique suffix defined for the new shortcut and click the button to open a popup that detects key combinations and shows the detected combination in its input field
The add shortcut assigns the key-combination to the shortcut

Depending on the chosen platform the configuration mechanism creates a tiddler with a specific nomenclature

$:/config/shortcuts/ + the shortcut suffix for shortcuts that will work on all platforms (operating systems)
$:/config/shortcuts-(mac/not-mac/windows/not-windows/linux/not-linux)/ + the shortcut suffix for shortcuts that will work on the chosen platform only or that will not work on the excluded platform

Examples

  • $:/config/shortcuts/my-shortcut
  • $:/config/shortcuts-mac/my-shortcut
  • $:/config/shortcuts-windows/my-shortcut
  • $:/config/shortcuts-linux/my-shortcut
  • $:/config/shortcuts-not-mac/my-shortcut
  • $:/config/shortcuts-not-windows/my-shortcut
  • $:/config/shortcuts-not-linux/my-shortcut

Note that those platform-specific tiddlers don't have to be created manually if the ShortcutInfo tiddler as mentioned above is created first and and the shortcut is configured in the ControlPanel


At this point the shortcut is defined and its actions can be configured

Using the Keyboard Widget

A $keyboard widget detects the key combinations pressed within an input or textarea field within its scope. The $keyboard widget needs to "embrace" the input or textarea field and its key attribute either points to a configuration tiddler using the Key Descriptor Syntax or explicitely contains the key
<$keyboard key="((my-shortcut))" actions='<$action-setfield $tiddler="my-tiddler" $field="my-field" $value="my-value"/>'>

<$edit-text tag="input" tiddler="my-tiddler"/>

</$keyboard>
<$keyboard key="alt-shift-M" actions='<$action-setfield $tiddler="my-tiddler" $field="my-field" $value="my-value"/>'>

<$edit-text tag="input" tiddler="my-tiddler"/>

</$keyboard>
If actions are defined , the $keyboard widget will invoke the actions defined in its actions attribute when it detects the key-combination defined in its key attribute being pressed in any input or textarea field within its scope

Using global Keyboard Shortcuts

The actions for global keyboard shortcuts are stored in the text field of tiddlers tagged with $:/tags/KeyboardShortcut
The key field connects an action-tiddler with the corresponding shortcut through the ((my-shortcut)) syntax, called Keyboard Shortcut Descriptor

Syntax: (( + a chosen suffix + ))

If the tiddler has the tag $:/tags/KeyboardShortcut , the field key with the Keyboard Shortcut Descriptor as its value and some actions in its text field, the actions will be triggered when the mechanism detects the configured key-combination


Macros defined outside a global keyboard-shortcut (through a tiddler tagged $:/tags/Macro) need to be imported in order to be accessible. The import pragma can be used for that

\import $:/core/ui/PageMacros [all[shadows+tiddlers]tag[$:/tags/Macro]!has[draft.of]]

If the tiddler that contains the macro definition is known and - for example - titled my-macro-tiddler

\import my-macro-tiddler


Some actions require to be wrapped within a $navigator widget. That is necessary for the following list of widgets and messages in order to work if used within global keyboard shortcuts

Widgets

$action-navigate (ActionNavigateWidget)

Messages

WidgetMessage: tm-cancel-tiddler
WidgetMessage: tm-close-all-tiddlers
WidgetMessage: tm-close-other-tiddlers
WidgetMessage: tm-close-tiddler
WidgetMessage: tm-delete-tiddler
WidgetMessage: tm-edit-tiddler
WidgetMessage: tm-import-tiddlers
WidgetMessage: tm-new-tiddler
WidgetMessage: tm-perform-import
WidgetMessage: tm-rename-tiddler
WidgetMessage: tm-save-tiddler