Git commit 7f1a0f13705fabecc8f700ee703036945a6e2963 by Christoph Cullmann, on behalf of Pablo Rauzy. Committed on 14/08/2022 at 14:20. Pushed by cullmann into branch 'master'.
adding Keyboard Macros Plugin to Kate's documentation M +120 -0 doc/kate/plugins.docbook https://invent.kde.org/utilities/kate/commit/7f1a0f13705fabecc8f700ee703036945a6e2963 diff --git a/doc/kate/plugins.docbook b/doc/kate/plugins.docbook index b4fb29caf..80862feec 100644 --- a/doc/kate/plugins.docbook +++ b/doc/kate/plugins.docbook @@ -101,6 +101,10 @@ Search and replace in documents, folders, or projects</para> <para><link linkend="kate-application-plugin-snippets">Snippets tool view</link> - Tool view embedding the snippets management</para> </listitem> <listitem> +<para><link linkend="kate-application-plugin-keyboardmacros">Keyboard Macros</link> +- Record and play keyboard macros (i.e., keyboard action sequences)</para> +</listitem> +<listitem> <para><link linkend="kate-application-plugin-sql">SQL Plugin</link> - Execute query on SQL databases</para> </listitem> @@ -3504,6 +3508,122 @@ writing much of this section.</para> </sect1> +<sect1 id="kate-application-plugin-keyboardmacros"> +<sect1info> +<authorgroup> +<author>&Pablo.Rauzy; &Pablo.Rauzy.mail;</author> +</authorgroup> +</sect1info> +<title>Keyboard Macros Plugin</title> + +<sect2 id="keyboardmacros-intro"> +<title>Introduction</title> +<para>Record and play keyboard macros (i.e., keyboard action sequences).</para> +</sect2> + +<sect2 id="keyboardmacros-basicusage"> +<title>Basic usage</title> + +<sect3 id="keyboardmacros-basicusage-record"> +<title>To start recording a keyboard macro:</title> +<para> +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Keyboard Macros</guimenuitem><guimenuitem>Record Macro...</guimenuitem></menuchoice> +(<keycombo action="simul">&Ctrl;&Shift;<keycap>K</keycap></keycombo>). +</para> +<para>The plugin will record every key presses until you end recording.</para> +</sect3> + +<sect3 id="keyboardmacros-basicusage-record-end"> +<title>To end recording:</title> +<para> +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Keyboard Macros</guimenuitem><guimenuitem>End Macro Recording</guimenuitem></menuchoice> +(<keycombo action="simul">&Ctrl;&Shift;<keycap>K</keycap></keycombo>). +</para> +<para>The plugin will stop recording key presses and save the key presses sequences as the current macro.</para> +</sect3> + +<sect3 id="keyboardmacros-basicusage-record-cancel"> +<title>To cancel recording:</title> +<para> +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Keyboard Macros</guimenuitem><guimenuitem>Cancel Macro Recording</guimenuitem></menuchoice> +(<keycombo action="simul">&Ctrl;&Alt;&Shift;<keycap>K</keycap></keycombo>). +</para> +<para>The plugin will stop recording key presses but the current macro won't change.</para> +</sect3> + +<sect3 id="keyboardmacros-basicusage-play"> +<title>To play the current macro:</title> +<para> +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Keyboard Macros</guimenuitem><guimenuitem>Play Macro</guimenuitem></menuchoice> +(<keycombo action="simul">&Ctrl;&Alt;<keycap>K</keycap></keycombo>). +</para> +<para>The plugin will play the current macro.</para> +<para>The <userinput>kmplay</userinput> command without any arguments will also play the current macro.</para> +</sect3> + +</sect2> + +<sect2 id="keyboardmacros-namedmacros"> +<title>Named macros</title> + +<para>It is possible to save keyboard macros by giving them a name.</para> +<para>Named macros are persistent between Kate's sessions, they're saved in the <filename>keyboardmacros.json</filename> file in Kate's user data directory (usually <filename>~/.local/share/kate/</filename>).</para> + +<sect3 id="keyboardmacros-namedmacros-save"> +<title>To save the current macro:</title> +<para> +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Keyboard Macros</guimenuitem><guimenuitem>Save Current Macro</guimenuitem></menuchoice> +(<keycombo action="simul">&Alt;&Shift;<keycap>K</keycap></keycombo>). +</para> +<para>The plugin will prompt you for a name and save the macro under it.</para> +<para>The <userinput>kmsave <replaceable>name</replaceable></userinput> command will save the current macro under the name <replaceable>name</replaceable>.</para> +</sect3> + +<sect3 id="keyboardmacros-namedmacros-load"> +<title>To load a saved macro as the current one:</title> +<para> +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Keyboard Macros</guimenuitem><guimenuitem>Load Named Macro...</guimenuitem></menuchoice>. +</para> +<para>The plugin lists saved macros as items in this submenu, activating an item will load the corresponding macro as the current one.</para> +<para>The <userinput>kmload <replaceable>name</replaceable></userinput> command will load the macro saved under the name <replaceable>name</replaceable> as the current one.</para> +</sect3> + +<sect3 id="keyboardmacros-namedmacros-play"> +<title>To play a saved macro without loading it:</title> +<para> +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Keyboard Macros</guimenuitem><guimenuitem>Play Named Macro...</guimenuitem></menuchoice>. +</para> +<para>The plugin lists saved macros as items in this submenu, activating an item will play the corresponding macro without loading it.</para> +<para>Note that each saved macros is an action that is part of the current action collection so that a custom shortcut can be assigned to it through the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Keyboard Shortcuts...</guimenuitem></menuchoice> interface.</para> +<para>The <userinput>kmplay <replaceable>name</replaceable></userinput> command will play the macro saved under the name <replaceable>name</replaceable> without loading it.</para> +</sect3> + +<sect3 id="keyboardmacros-namedmacros-wipe"> +<title>To wipe (e.g., delete) a saved macro:</title> +<para> +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Keyboard Macros</guimenuitem><guimenuitem>Wipe Named Macro...</guimenuitem></menuchoice>. +</para> +<para>The plugin lists saved macros as items in this submenu, activating an item will wipe (i.e., delete) the corresponding macro.</para> +<para>The <userinput>kmwipe <replaceable>name</replaceable></userinput> command will wipe the macro saved under the name <replaceable>name</replaceable>.</para> +</sect3> + +<sect3 id="keyboardmacros-namedmacros-command-tips"> +<title>Tips for commands:</title> +<para>Note that after the <userinput>km</userinput> prefix, all these commands use a different letter so you can efficiently call them using tab-completion!</para> +</sect3> + +</sect2> + +<sect2 id="keyboardmacros-limitations"> +<title>Limitations</title> + +<para>As of now, keyboard macros fail to play properly if some types of GUI widgets are used: QMenu, QuickOpenLineEdit, or TabSwitcherTreeView, for example. +I'm not sure why but my first guess would be that these widgets work in a non-standard way regarding keyboard events.</para> + +</sect2> + +</sect1> + <sect1 id="kate-application-plugin-sql"> <sect1info>
