addons/keyboardmacros/README.md

0001 Keyboard Macros Plugin
0002 ======================
0003
0004 Introduction
0005 ------------
0006
0007 Record and play keyboard macros (i.e., keyboard action sequences).
0008
0009 Basic usage
0010 -----------
0011
0012 ### To start recording a keyboard macro:
0013
0014 [Tools \> Keyboard Macros \> Record Macro\...]
0015 [`Ctrl+Shift+K`].
0016
0017 The plugin will record every key presses until you end recording.
0018
0019 ### To end recording:
0020
0021 [Tools \> Keyboard Macros \> End Macro Recording]
0022 [`Ctrl+Shift+K`].
0023
0024 The plugin will stop recording key presses and save the sequence as the
0025 current macro.
0026
0027 ### To cancel recording:
0028
0029 [Tools \> Keyboard Macros \> Cancel Macro Recording]
0030 [`Ctrl+Alt+Shift+K`].
0031
0032 The plugin will stop recording key presses but the current macro won\'t
0033 change.
0034
0035 ### To play the current macro:
0036
0037 [Tools \> Keyboard Macros \> Play Macro]
0038 [`Ctrl+Alt+K`].
0039
0040 The plugin will play the current macro.
0041
0042 The `kmplay` command without any arguments will also play the current
0043 macro.
0044
0045 Named macros
0046 ------------
0047
0048 It is possible to save keyboard macros by giving them a name.
0049
0050 Named macros are persistent between Kate\'s sessions, they\'re saved in
0051 the `keyboardmacros.json` file in Kate\'s user data directory (usually
0052 `~/.local/share/kate/`).
0053
0054 ### To save the current macro:
0055
0056 [Tools \> Keyboard Macros \> Save Current Macro]
0057 [`Alt+Shift+K`].
0058
0059 The plugin will prompt you for a name and save the macro under it.
0060
0061 The `kmsave name` command will save the current macro under the name
0062 `name`.
0063
0064 ### To load a saved macro as the current one:
0065
0066 [Tools \> Keyboard Macros \> Load Named Macro\...].
0067
0068 The plugin lists saved macros as items in this submenu, activating an
0069 item will load the corresponding macro as the current one.
0070
0071 The `kmload name` command will load the macro saved under the name
0072 `name` as the current one.
0073
0074 ### To play a saved macro without loading it:
0075
0076 [Tools \> Keyboard Macros \> Play Named Macro\...].
0077
0078 The plugin lists saved macros as items in this submenu, activating an
0079 item will play the corresponding macro without loading it.
0080
0081 Note that each saved macros is an action that is part of the current
0082 action collection so that a custom shortcut can be assigned to it
0083 through the [Settings \> Configure Keyboard Shortcuts\...]
0084 interface.
0085
0086 The `kmplay name` command will play the macro saved under the name
0087 `name` without loading it.
0088
0089 ### To wipe (i.e., delete) a saved macro:
0090
0091 [Tools \> Keyboard Macros \> Wipe Named Macro\...].
0092
0093 The plugin lists saved macros as items in this submenu, activating an
0094 item will wipe (i.e., delete) the corresponding macro.
0095
0096 The `kmwipe name` command will wipe the macro saved under the name
0097 `name`.
0098
0099 ### Tips for commands:
0100
0101 Note that after the `km` prefix, all these commands use a different
0102 letter so you can efficiently call them using tab-completion!
0103
0104 Limitations
0105 -----------
0106
0107 As of now, keyboard macros fail to play properly if some types of GUI
0108 widgets are used: QMenu, QuickOpenLineEdit, or TabSwitcherTreeView, for
0109 example. I\'m not sure why but my first guess would be that these
0110 widgets work in a non-standard way regarding keyboard events.