Add How-To documentation for keyboard shortcuts (#3588)
* add link to "How to" keyboard shortcuts + styles * add "How to create keyboard shortcuts" * Update How to create keyboard shortcuts.tid * Update How to create keyboard shortcuts.tid * Update How to create keyboard shortcuts.tid
This commit is contained in:
BurningTreeC
Jeremy Ruston
parent
62cbbf1db4
commit
b18c85b85c
|
|
@ -0,0 +1,90 @@
|
|||
tags: [[Customise TiddlyWiki]] Learning
|
||||
title: How to create keyboard shortcuts
|
||||
type: text/vnd.tiddlywiki
|
||||
|
||||
<<.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:
|
||||
|
||||
<$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
|
||||
|
||||
!!!!At this point the shortcut is defined but it doesn't trigger any action
|
||||
|
||||
<$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:
|
||||
|
||||
```
|
||||
<$keyboard key="((my-shortcut))" actions="<$action-do-something/>">
|
||||
|
||||
<$edit-text tag="input" tiddler="my-tiddler"/>
|
||||
|
||||
</$keyboard>
|
||||
```
|
||||
<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">
|
||||
|
||||
> The actions for ''global'' keyboard shortcuts are stored in the ''text'' field of tiddlers tagged with <<tag $:/tags/KeyboardShortcut>>
|
||||
|
||||
|
||||
> 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>
|
||||
|
||||
> 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 containing the macro:
|
||||
|
||||
<pre>
|
||||
\import [[$:/core/ui/PageMacros]] [all[shadows+tiddlers]tag[$:/tags/Macro]!has[draft.of]]
|
||||
</pre>
|
||||
|
||||
or even simpler, if the tiddler containing the macro is known and - for example - titled `my-macro-tiddler`:
|
||||
|
||||
<pre>
|
||||
\import [[my-macro-tiddler]]
|
||||
</pre>
|
||||
|
||||
"""/>
|
||||
|
||||
<$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__
|
||||
** <<.wlink ActionNavigateWidget>> (ActionNavigateWidget)
|
||||
* __Messages__<br><ul><$list filter="[tag[navigator-message]]">
|
||||
<li> <$link to={{!!title}}><$view field="title"/></$link></li></$list></ul>
|
||||
|
||||
</$reveal>
|
||||
|
||||
</$vars>
|
||||
|
|
@ -10,20 +10,23 @@ Keyboard shortcuts can either be used with the <<.wlink KeyboardWidget>> Widget
|
|||
|
||||
A shortcut defined through a [[Keyboard Shortcut Tiddler]] makes the shortcut accessible globally""">>
|
||||
|
||||
!!!See [[How to create keyboard shortcuts]] with a detailed explanation for creating your own shortcuts
|
||||
|
||||
Keyboard shortcuts are available for common editing operations within the Text Editor:
|
||||
|
||||
* Confirming changes to the draft tiddler containing the keyboard focus (defaults to <kbd>ctrl-Enter</kbd>)
|
||||
* Abandoning changes to the draft tiddler containing the keyboard focus (defaults to <kbd>escape</kbd>)
|
||||
* Formatting operations from the tiddler editing toolbar (see the tooltips)
|
||||
|
||||
<<.from-version 5.1.18>>: New ''global'' Keyboard shortcuts:
|
||||
<<.from-version 5.1.18>> : New ''global'' Keyboard shortcuts:
|
||||
|
||||
* Creating a new tiddler (defaults to <kbd>alt-N</kbd>)
|
||||
* Creating a new journal (defaults to <kbd>alt-J</kbd>)
|
||||
* Creating a new tiddler (defaults to <kbd>alt-N</kbd> )
|
||||
* Creating a new journal (defaults to <kbd>alt-J</kbd> )
|
||||
* Creating a new image (defaults to <kbd>alt-I</kbd> )
|
||||
|
||||
The current shortcuts can be inspected and customised in the "Keyboard Shortcuts" tab of the [[Control Panel|$:/ControlPanel]] {{$:/core/images/options-button}}.
|
||||
|
||||
!! Special Keys
|
||||
|
||||
; adding tags in the editor
|
||||
: <<.from-version 5.1.14>>: if you hit <kbd>Enter</kbd> in the new tag input, the tag will be added
|
||||
: <<.from-version 5.1.14>> : if you hit <kbd>Enter</kbd> in the new tag input, the tag will be added
|
||||
|
|
|
|||
Loading…
Reference in New Issue