kopia lustrzana https://github.com/miklobit/TiddlyWiki5
Reformatting "How to create keyboard shortcuts" (#3633)
BurningTreeC
Jeremy Ruston
rodzic
f6b1e27281
commit
a7cdb94957
|
|
@ -2,89 +2,104 @@ tags: [[Customise TiddlyWiki]] Learning
|
|||
title: How to create keyboard shortcuts
|
||||
type: text/vnd.tiddlywiki
|
||||
|
||||
<br>
|
||||
<<.tip """We distinguish keyboard shortcuts that work within <$macrocall $name=".tag" _="input"/> fields or <$macrocall $name=".tag" _="textareas"/> which are handled by the <$macrocall $name=".wlink" to="KeyboardWidget"/> widget and keyboard shortcuts that work globally - which means that only the page needs to have focus in order for them to be accessible - handled by a mechanism that starts to work when a wiki is loaded""">>
|
||||
|
||||
!!!!There's an underlying configuration mechanism that is the same for both shortcut-types:
|
||||
|
||||
!! The configuration mechanism is the same for both shortcut-types
|
||||
|
||||
<$vars tv-show-missing-links="no">
|
||||
|
||||
* (`A`) - A tiddler with the <<.def prefix>> ''$:/config/ShortcutInfo/'' + a ''unique suffix'', like `my-shortcut` makes the new shortcut appear in the $:/ControlPanel within the [[Keyboard Shortcuts Tab|$:/core/ui/ControlPanel/KeyboardShortcuts]]. An optional description can be added within its text field
|
||||
** In the [[Keyboard Shortcuts Tab|$:/core/ui/ControlPanel/KeyboardShortcuts]] it's possible to create the ''key combination'' that should trigger the shortcut
|
||||
*** Look for the ''unique suffix'' (A) and click the <$button class="tc-btn-invisible">{{$:/core/images/edit-button}}<$action-sendmessage $message="tm-notify" $param="$:/core/images/edit-button"/></$button> button to open a popup that detects ''key combinations'' and shows the detected combination in its input field
|
||||
*** Press ''add shortcut'' if you're happy with the assigned key-combination
|
||||
**** (`B`) Depending on the platform you choose the configuration mechanism creates a tiddler with a specific nomenclature:
|
||||
***** $:/config/shortcuts/ + the ''unique suffix'' for shortcuts that will work on all platforms (operating systems)
|
||||
***** $:/config/shortcuts-(mac/not-mac/windows/not-windows/linux/not-linux)/ + the ''unique suffix'' for shortcuts that will work on the chosen platform only or that will not work on the excluded platform
|
||||
***** <$reveal state="$:/state/how-to/kb-shortcuts/platform-examples" type="nomatch" text="show"><$button class="tc-btn-invisible" set="$:/state/how-to/kb-shortcuts/platform-examples" setTo="show">Show examples</$button></$reveal><$reveal state="$:/state/how-to/kb-shortcuts/platform-examples" type="match" text="show"><$button class="tc-btn-invisible" set="$:/state/how-to/kb-shortcuts/platform-examples" setTo="hide">Hide examples</$button></$reveal><br><$reveal state="$:/state/how-to/kb-shortcuts/platform-examples" type="match" text="show" animate="yes" retain="yes">''$:/config/shortcuts/''`my-shortcut`<br>''$:/config/shortcuts-mac/''`my-shortcut`<br>''$:/config/shortcuts-windows/''`my-shortcut`<br>''$:/config/shortcuts-linux/''`my-shortcut`<br>''$:/config/shortcuts-not-mac/''`my-shortcut`<br>''$:/config/shortcuts-not-windows/''`my-shortcut`<br>''$:/config/shortcuts-not-linux/''`my-shortcut`<br></$reveal>
|
||||
***** Note that you don't have to create those platform-specific tiddlers manually if you simply create the ''ShortcutInfo'' tiddler (`A`) and configure the shortcut in the ~ControlPanel
|
||||
A tiddler with the <<.def prefix>> `$:/config/ShortcutInfo/` and a ''unique suffix'' appended, like `my-shortcut`, makes the new shortcut appear in the $:/ControlPanel within the [[Keyboard Shortcuts Tab|$:/core/ui/ControlPanel/KeyboardShortcuts]]. An optional description can be added within its text field
|
||||
|
||||
!!!!At this point the shortcut is defined but it doesn't trigger any action
|
||||
In the [[Keyboard Shortcuts Tab|$:/core/ui/ControlPanel/KeyboardShortcuts]] 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 class="tc-btn-invisible">{{$:/core/images/edit-button}}<$action-sendmessage $message="tm-notify" $param="$:/core/images/edit-button"/></$button> 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`
|
||||
|
||||
<<.tip """Note that you don't have to create those platform-specific tiddlers manually if you simply create the ''ShortcutInfo'' tiddler as mentioned above and configure the shortcut in the ~ControlPanel""">>
|
||||
|
||||
<$reveal type="nomatch" text="show" state="$:/state/how-to/kb-shortcuts/keyboard-widget">
|
||||
<$button class="tc-btn-invisible" set="$:/state/how-to/kb-shortcuts/keyboard-widget" setTo="show">''Show'' "How to create the shortcut-actions for <<.tag input>> and <<.tag textarea>> fields"</$button>
|
||||
</$reveal>
|
||||
<$reveal type="match" text="show" state="$:/state/how-to/kb-shortcuts/keyboard-widget">
|
||||
<$button class="tc-btn-invisible" set="$:/state/how-to/kb-shortcuts/keyboard-widget" setTo="hide">''Hide'' "How to create the shortcut-actions for <<.tag input>> and <<.tag textarea>> fields"</$button>
|
||||
</$reveal>
|
||||
<br>
|
||||
<$reveal type="match" text="show" animate="yes" retain="yes" state="$:/state/how-to/kb-shortcuts/keyboard-widget">
|
||||
|
||||
> A <<.wlink "KeyboardWidget">> widget detects the key combinations pressed in an <<.tag input>> or <<.tag textarea>> field within its scope. The <<.wlink "KeyboardWidget">> widget needs to ''surround'' the <<.tag input>> or <<.tag textarea>> field:
|
||||
!! At this point the shortcut is defined and its ''actions'' can be configured
|
||||
|
||||
!! Using the [[Keyboard Widget|KeyboardWidget]]
|
||||
|
||||
> A <<.wlink "KeyboardWidget">> widget detects the key combinations pressed within an <<.tag input>> or <<.tag textarea>> field within its scope. The <<.wlink "KeyboardWidget">> widget needs to "embrace" the <<.tag input>> or <<.tag textarea>> field and its <<.attr key>> attribute either points to a configuration tiddler using the [[Key Descriptor]] Syntax or explicitely contains the key
|
||||
|
||||
```
|
||||
<$keyboard key="((my-shortcut))" actions="<$action-do-something/>">
|
||||
<$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 <<.wlink KeyboardWidget>> widget will invoke the actions defined in its <<.attr actions>> attribute when it detects the key-combination defined in its <<.attr key>> attribute being pressed in any <<.tag input>> or <<.tag textarea>> field within its scope
|
||||
|
||||
<br>
|
||||
|
||||
> The `((my-shortcut))` syntax with the `((` and `))` embracing the ''unique suffix'' defined in (`A`) makes the <<.wlink "KeyboardWidget">> widget look up for all existing configuration tiddlers (`B`) and assigns the correct key-combination for your platform/operating system to the actions defined with the <<.attr actions>> attribute
|
||||
|
||||
> At this point, the <<.wlink KeyboardWidget>> widget will invoke the actions defined in its <<.attr actions>> attribute when it detects the key-combination defined for `my-shortcut` in any <<.tag input>> or <<.tag textarea>> field within its scope
|
||||
|
||||
</$reveal>
|
||||
|
||||
<$reveal type="nomatch" text="show" state="$:/state/how-to/kb-shortcuts/global-actions">
|
||||
<$button class="tc-btn-invisible" set="$:/state/how-to/kb-shortcuts/global-actions" setTo="show">''Show'' "How to create the shortcut-actions for `global` keyboard shortcuts"</$button>
|
||||
</$reveal>
|
||||
<$reveal type="match" text="show" state="$:/state/how-to/kb-shortcuts/global-actions">
|
||||
<$button class="tc-btn-invisible" set="$:/state/how-to/kb-shortcuts/global-actions" setTo="hide">''Hide'' "How to create the shortcut-actions for `global` keyboard shortcuts"</$button>
|
||||
</$reveal>
|
||||
<br>
|
||||
<$reveal type="match" text="show" animate="yes" retain="yes" state="$:/state/how-to/kb-shortcuts/global-actions">
|
||||
!! Using global Keyboard Shortcuts
|
||||
|
||||
> The actions for ''global'' keyboard shortcuts are stored in the ''text'' field of tiddlers tagged with <<tag $:/tags/KeyboardShortcut>>
|
||||
|
||||
> The ''key field'' connects an action-tiddler with the corresponding shortcut through the `((my-shortcut))` syntax, called [[Keyboard Shortcut Descriptor]]
|
||||
|
||||
> The ''key field'' connects this action-tiddler with the corresponding shortcut through the `((my-shortcut))` syntax, called [[Keyboard Shortcut Descriptor]]
|
||||
|
||||
:<h3> Syntax: `((` + ''unique suffix'' (`A`) + `))` </h3>
|
||||
:<h3> Syntax: `((` + `a chosen suffix` + `))` </h3>
|
||||
|
||||
> If the tiddler has the tag <<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
|
||||
|
||||
<$macrocall $name=".tip" _="""''Macros'' defined ''outside'' our keyboard-shortcut tiddlers (through a tiddler tagged <<tag-pill $:/tags/Macro>>) don't work out-of-the-box when triggered with a global keyboard shortcut, but there's a simple workaround using the [[import pragma|Pragma]], adding the following line ''on top'' of your keyboard-shortcut tiddler:
|
||||
<br>
|
||||
<$macrocall $name=".tip" _="""''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|Pragma]] can be used for that"""/>
|
||||
|
||||
<pre>
|
||||
\import [[$:/core/ui/PageMacros]] [all[shadows+tiddlers]tag[$:/tags/Macro]!has[draft.of]]
|
||||
</pre>
|
||||
|
||||
or even simpler, if the tiddler that contains the macro definition is known and - for example - titled `my-macro-tiddler`:
|
||||
If the tiddler that contains the macro definition is known and - for example - titled `my-macro-tiddler`
|
||||
|
||||
<pre>
|
||||
\import [[my-macro-tiddler]]
|
||||
</pre>
|
||||
|
||||
"""/>
|
||||
<br>
|
||||
<$macrocall $name=".tip" _="""Some actions require a <<.wlink NavigatorWidget>> widget at the top of our action tiddler. That is necessary for following list of widgets and messages in order to work if used within global keyboard shortcuts. See the following list"""/>
|
||||
|
||||
<$macrocall $name=".tip" _="""Some actions require that we add a <<.wlink NavigatorWidget>> widget at the top of our action tiddler. That is necessary for following list of widgets and messages in order ''to work with global keyboard shortcuts'':"""/>
|
||||
!!! Widgets
|
||||
|
||||
* __Widgets__
|
||||
** <<.wlink ActionNavigateWidget>> (ActionNavigateWidget)
|
||||
* __Messages__<br><ul><$list filter="[tag[navigator-message]]">
|
||||
<li> <$link to={{!!title}}><$view field="title"/></$link></li></$list></ul>
|
||||
<<.wlink ActionNavigateWidget>> (ActionNavigateWidget)
|
||||
|
||||
</$reveal>
|
||||
!!! Messages
|
||||
|
||||
<$list filter="[tag[navigator-message]]">
|
||||
<$link to={{!!title}}><$view field="title"/></$link><br>
|
||||
</$list>
|
||||
|
||||
</$vars>
|
||||
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue