Warning, /utilities/krusader/doc/handbook/useractions.docbook is written in an unsupported language. File is not indexed.
0001 <!--
0002 SPDX-FileCopyrightText: 2000-2003 Shie Erlich <erlich@users.sourceforge.net>
0003 SPDX-FileCopyrightText: 2000-2003 Rafi Yanai <yanai@users.sourceforge.net>
0004 SPDX-FileCopyrightText: 2004-2010 Frank Schoolmeesters <codeknight@users.sourceforge.net>
0005 SPDX-FileCopyrightText: 2000-2022 Krusader Krew <https://krusader.org>
0006 -->
0007 <sect1 id="useractions">
0008 <title>UserActions</title>
0009 <indexterm>
0010 <primary>UserActions</primary>
0011 </indexterm>
0012 <!-- Thanks to Jonas Bar -->
0013 <para>With ActionMan you can set up, configure and manage
0014 UserActions. Some general settings are configured with
0015 <link linkend="konfig-useractions">Konfigurator</link>. With
0016 UserActions you can perform actions on files in the panel or to
0017 access &krusader; internal functions with parameters
0018 directly using placeholders. The actions integrate seamlessly
0019 into &plasma; action system, which means that the
0020 standard Edit Toolbar and Edit Shortcut dialogs will show
0021 UserActions, too. The UserActions are stored in
0022 <filename>
0023 ~/.local/share/krusader/useractions.xml</filename> or <filename>krusader/useraction.xml</filename> in the folder which can be determined using the <userinput>qtpaths --paths GenericDataLocation</userinput> command.
0024 Several
0025 <link linkend="useraction-xml">examples</link> are included in the
0026 documentation. UserActions can be edited / added / imported /
0027 exported by using ActionMan. The default UserActions are stored
0028 in
0029 <filename>
0030 /usr/share/krusader/useraction-examples.xml</filename>.
0031 UserActions can appear nearly everywhere where <quote>normal</quote> KActions
0032 can be placed. The actions can even be placed in the menu bar, but for that the
0033 <filename>krusaderui.rc</filename> file must be edited. A few
0034 examples:</para>
0035 <itemizedlist>
0036 <listitem>
0037 <para>
0038 <link linkend="useractions-menu">Useractions Menu</link>
0039 </para>
0040 </listitem>
0041 <listitem>
0042 <para><link linkend="useractions">User Menu</link></para>
0043 </listitem>
0044 <listitem>
0045 <para><link linkend="actions_toolbar">Actions Toolbar</link></para>
0046 </listitem>
0047 <listitem>
0048 <para>right click menus</para>
0049 </listitem>
0050 <listitem>
0051 <para>&etc;</para>
0052 </listitem>
0053 </itemizedlist>
0054 <para>&krusader;'s UserActions tool is very
0055 powerful and customizable if you are familiar with writing
0056 UserActions in general.</para>
0057 <tip>
0058 <para>Several UserActions are provided by default. Please
0059 <link linkend="help_krusader">upload your favorite
0060 UserActions</link> so that they become available for the
0061 &krusader; community. Thanks!<!-- We provide also an
0062 <ulink url="https://krusader.org/phpBB/viewforum.php?f=11">UserActions Forum</ulink>.--></para>
0063 </tip>
0064 <figure id="screenshot-actionman" float="1">
0065 <title>ActionMan</title>
0066 <mediaobject>
0067 <imageobject>
0068 <imagedata fileref="actionman.png"></imagedata>
0069 </imageobject>
0070 <textobject>
0071 <phrase>ActionMan</phrase>
0072 </textobject>
0073 </mediaobject>
0074 </figure>
0075 <para>Basically, UserActions are a method to call external
0076 programs with variable parameters. For example, you could have a
0077 UserAction with the following
0078 <command>xmms
0079 <option>--enqueue %aList("Selected")%</option></command> to
0080 enqueue all selected items of the active panel to the current
0081 instance of xmms. Additionally, there is limited access to
0082 &krusader; internal functions requiring parameters.
0083 For example,
0084 <command>%aPanelSize("80")%</command> will set the width of the
0085 active panel to 80% of the &krusader; mainwindow.
0086 Since the parameter of placeholders can contain other
0087 placeholders, few scripts are possible.
0088 </para>
0089 <para>
0090 <emphasis role="bold">Managing UserActions</emphasis>
0091 </para>
0092 <para>Open Konfigurator and choose <menuchoice><guimenu>User Actions</guimenu>
0093 <guimenuitem>Start ActionMan</guimenuitem></menuchoice>, in which you can add, edit, remove, import and export
0094 UserActions.</para>
0095 <itemizedlist>
0096 <listitem>
0097 <para>
0098 <guimenuitem>Add Action</guimenuitem>: If you add an new
0099 action, you get an empty input mask where you can enter all
0100 the properties you desire. The action will be added as soon
0101 as you press
0102 <guimenuitem>Apply</guimenuitem>. Afterwards, the name is shown
0103 in the list on the left.</para>
0104 </listitem>
0105 <listitem>
0106 <para>To edit a UserAction: Select the UserAction on the
0107 left. Then choose it if you want to edit its properties. The
0108 changes will only take effect when you press
0109 <guimenuitem>Apply</guimenuitem>.</para>
0110 </listitem>
0111 <listitem>
0112 <para>
0113 <guimenuitem>To remove a UserAction</guimenuitem>: Select the
0114 UserAction on the left and click the <inlinemediaobject>
0115 <imageobject> <imagedata fileref="Icon-edit-delete.png"
0116 format="PNG"/> </imageobject> </inlinemediaobject>button.</para>
0117 </listitem>
0118 <listitem>
0119 <para>
0120 <guimenuitem>To import a UserAction</guimenuitem>: If you
0121 import some actions, they will be automatically added to your
0122 list. If there are name conflicts (the names have to be
0123 unique because these are the ID for &plasma; action
0124 system), you are asked to resolve them. For this, the list on
0125 the left will only show the actions where conflicts exist.
0126 You can now give them new names or remove them.</para>
0127 </listitem>
0128 <listitem>
0129 <para>
0130 <guimenuitem>Export Action</guimenuitem>: If you export a
0131 UserAction you have to give a filename in which to store it.
0132 If it does not exist, it will be created. If the file already
0133 contains UserActions, the action you are exporting will be
0134 added to that file.</para>
0135 </listitem>
0136 </itemizedlist>
0137 <para>All actions you have defined are now shown in the
0138 user menu and in &plasma; dialogs for changing shortcuts
0139 and managing the toolbar. In addition, all actions available for
0140 the current item will also show up in the right click
0141 menu.</para>
0142 <para>
0143 <emphasis role="bold">Basic Properties</emphasis>
0144 </para>
0145 <para>
0146 <guimenuitem>Identifier</guimenuitem>, <guimenuitem>Title</guimenuitem>
0147 and <guimenuitem>Command line</guimenuitem> are always required, all the other properties
0148 are optional.</para>
0149 <itemizedlist>
0150 <listitem>
0151 <para>
0152 <guimenuitem>Identifier</guimenuitem>: A unique name of
0153 the UserAction, used to identify it for &plasma;
0154 action system.</para>
0155 </listitem>
0156 <listitem>
0157 <para>
0158 <guimenuitem>Icon button</guimenuitem>: The icon for your
0159 UserAction.</para>
0160 </listitem>
0161 <listitem>
0162 <para>
0163 <guimenuitem>Category</guimenuitem>: Categories are used for a
0164 better overview. They appear as submenu items in
0165 the <guimenuitem>Useractions</guimenuitem> menu.</para>
0166 </listitem>
0167 <listitem>
0168 <para>
0169 <guimenuitem>Title</guimenuitem>: The title displayed in
0170 the menus or dialogs.</para>
0171 </listitem>
0172 <listitem>
0173 <para>
0174 <guimenuitem>Tooltip</guimenuitem>: A tooltip for your
0175 UserAction, ⪚ displayed in the toolbar on
0176 mouseover.</para>
0177 </listitem>
0178 <listitem>
0179 <para>
0180 <guimenuitem>Description</guimenuitem>: A description of
0181 what the UserAction does. This is also displayed as
0182 <guimenuitem>What's This</guimenuitem> if you
0183 <keycombo action="simul">&Shift;
0184 <keycap>F1</keycap></keycombo> click on your
0185 UserAction.</para>
0186 </listitem>
0187 <listitem>
0188 <para>
0189 <guimenuitem>Command</guimenuitem>: The command which
0190 will be executed. You can add placeholder using a &GUI; with
0191 the <guibutton>add</guibutton> button.</para>
0192 </listitem>
0193 <listitem>
0194 <para>
0195 <guimenuitem>Workdir</guimenuitem>: The working folder
0196 for the command which will be executed.</para>
0197 </listitem>
0198 <listitem>
0199 <para>
0200 <guimenuitem>Execution mode</guimenuitem>:</para>
0201 <itemizedlist>
0202 <listitem>
0203 <para>
0204 <guimenuitem>Normal</guimenuitem>: Normal execution
0205 mode.</para>
0206 </listitem>
0207 <listitem>
0208 <para>
0209 <guimenuitem>Run in terminal</guimenuitem>: Runs the
0210 command in the terminal.</para>
0211 </listitem>
0212 <listitem>
0213 <para>
0214 <guimenuitem>Run in embedded terminal emulator</guimenuitem>: Runs the
0215 command in the embedded terminal.</para>
0216 </listitem>
0217 <listitem>
0218 <para>
0219 <guimenuitem>Collect output</guimenuitem>: Collects the
0220 output of the executed program in a &GUI;
0221 window.</para>
0222 </listitem>
0223 <listitem>
0224 <para>
0225 <guimenuitem>Separate standard error</guimenuitem>:
0226 When <quote>Collect output</quote> is used the stdout and stderr are
0227 separately collected.</para>
0228 </listitem>
0229 </itemizedlist>
0230 </listitem>
0231 <listitem>
0232 <para>
0233 <guimenuitem>Command accepts</guimenuitem>:</para>
0234 <itemizedlist>
0235 <listitem>
0236 <para>
0237 <guimenuitem>Local files only (no &URL;s)</guimenuitem>: Tells
0238 the placeholder it should return local addresses.</para>
0239 </listitem>
0240 <listitem>
0241 <para>
0242 <guimenuitem>&URL;s (remote and local)</guimenuitem>:
0243 Tells the placeholder it should return
0244 &URL;s.</para>
0245 </listitem>
0246 </itemizedlist>
0247 </listitem>
0248 <!-- Not yet implemented, but will be after 1.50 stable is released
0249 <listitem><para><guimenuitem>On multiple selection</guimenuitem>: </para>
0250 <itemizedlist>
0251 <listitem><para><guimenuitem>Separate call for each file</guimenuitem>: executes the command for each selected file.
0252 </para></listitem>
0253 </itemizedlist>
0254 </listitem> -->
0255 <listitem>
0256 <para>
0257 <guimenuitem>Default shortcut</guimenuitem>: Configures a default
0258 shortcut for the UserAction.</para>
0259 </listitem>
0260 <listitem>
0261 <para>
0262 <guimenuitem>Enabled</guimenuitem>: if checked, the useraction is shown in the <link linkend="useractions">User Menu</link>,
0263 otherwise the useraction will be hidden.</para>
0264 </listitem>
0265 </itemizedlist>
0266 <para>
0267 <emphasis role="bold">Command-line syntax</emphasis>
0268 </para>
0269 <para>Basically, everything you type in the command line will get
0270 executed (if you type <quote>ls -l</quote>, <quote>ls -l</quote> gets executed). You have
0271 the possibility to get a character string from
0272 &krusader; which represents the current state of the
0273 panel. This is done using placeholders. A placeholder begins with
0274 a percent-sign ('%') and is followed by a panel indicator ('a'
0275 for the active, 'o' for the other, 'l' for the left and 'r' for
0276 the right panel. If the placeholder does not need a panel to
0277 operate on, you have to indicate this by an underscore ('_')).
0278 Then comes the name of the placeholder (see the list below),
0279 which may get some parameters enclosed in quotes. Finally, again
0280 the percent sign.</para>
0281 <para>This sounds very complicated, so let's make an example:
0282 '%aList("Selected")%' is replaced by a list of all selected items
0283 in the active panel. So a command like 'xmms --enqueue
0284 %aList("All", " ", "", "*.mp3")%' will execute xmms with a list
0285 of all .mp3s in the current panel, separated by a single
0286 blank.</para>
0287 <para>Currently, these placeholders are implemented:</para>
0288 <itemizedlist>
0289 <listitem>
0290 <para>
0291 <userinput>Path</userinput> - replaced by the panels
0292 path</para>
0293 <orderedlist>
0294 <listitem>
0295 <para>Parameter (optional):
0296 Automatic escape spaces. Default:
0297 yes</para>
0298 </listitem>
0299 </orderedlist>
0300 </listitem>
0301 <listitem>
0302 <para>
0303 <userinput>Count</userinput> - replaced by the number of
0304 <first parameter></para>
0305 <orderedlist>
0306 <listitem>
0307 <para>Parameter: Which items;
0308 either <quote>All</quote>, <quote>Selected</quote>, <quote>Files</quote> or <quote>Dirs</quote></para>
0309 </listitem>
0310 </orderedlist>
0311 </listitem>
0312 <listitem>
0313 <para>
0314 <userinput>Filter</userinput> - replaced by the panel's filter
0315 mask</para>
0316 </listitem>
0317 <listitem>
0318 <para>
0319 <userinput>Current</userinput> - replaced by the current
0320 item</para>
0321 <orderedlist>
0322 <listitem>
0323 <para>Parameter (optional): Omit the
0324 current path. Default: no</para>
0325 </listitem>
0326 <listitem>
0327 <para>Parameter (optional):
0328 Automatic escape spaces. Default:
0329 yes</para>
0330 </listitem>
0331 </orderedlist>
0332 </listitem>
0333 <listitem>
0334 <para>
0335 <userinput>List</userinput> - replaced by a list of all
0336 <first parameter></para>
0337 <orderedlist>
0338 <listitem>
0339 <para>Parameter: Which items;
0340 either <quote>All</quote>, <quote>Selected</quote>, <quote>Files</quote> or <quote>Dirs</quote></para>
0341 </listitem>
0342 <listitem>
0343 <para>Parameter (optional):
0344 Separator between the items.
0345 Default:
0346 <quote> </quote></para>
0347 </listitem>
0348 <listitem>
0349 <para>Parameter (optional): Omit the
0350 current path. Default: no</para>
0351 </listitem>
0352 <listitem>
0353 <para>Parameter (optional):
0354 Filtermask (for all but <quote>Selected</quote>).
0355 Default: *</para>
0356 </listitem>
0357 <listitem>
0358 <para>Parameter (optional):
0359 Automatic escape spaces. Default:
0360 yes</para>
0361 </listitem>
0362 </orderedlist>
0363 </listitem>
0364 <listitem>
0365 <para>
0366 <userinput>Select</userinput> - manipulates the selection in a
0367 panel</para>
0368 <orderedlist>
0369 <listitem>
0370 <para>Parameter: Filtermask</para>
0371 </listitem>
0372 <listitem>
0373 <para>Parameter (optional):
0374 manipulate in which way; either <quote>Set</quote>, <quote>Add</quote> or <quote>Remove</quote>.
0375 Default: <quote>Set</quote></para>
0376 </listitem>
0377 </orderedlist>
0378 </listitem>
0379 <listitem>
0380 <para>
0381 <userinput>Goto</userinput> - changes the panels' path to
0382 <first parameter></para>
0383 <orderedlist>
0384 <listitem>
0385 <para>Parameter: A relative or
0386 absolute path, or an &URL;</para>
0387 </listitem>
0388 <listitem>
0389 <para>Parameter (optional): Open the
0390 location in a new tab. Default:
0391 no</para>
0392 </listitem>
0393 </orderedlist>
0394 </listitem>
0395 <listitem>
0396 <para>
0397 <userinput>Ask</userinput> - asks the user for some text and
0398 is replaced by the answer</para>
0399 <orderedlist>
0400 <listitem>
0401 <para>Parameter: The
0402 Question</para>
0403 </listitem>
0404 <listitem>
0405 <para>Parameter (optional): A
0406 default answer</para>
0407 </listitem>
0408 <listitem>
0409 <para>Parameter (optional): A
0410 caption for the question box</para>
0411 </listitem>
0412 </orderedlist>
0413 </listitem>
0414 <listitem>
0415 <para>
0416 <userinput>Clipboard</userinput> - manipulates the
0417 clipboard</para>
0418 <orderedlist>
0419 <listitem>
0420 <para>Parameter: The text that
0421 should go to the clipboard (you may want to use
0422 <quote>%aCurrent%</quote> here)</para>
0423 </listitem>
0424 <listitem>
0425 <para>Parameter (optional): Append
0426 the text to the current content of the clipboard with
0427 this separator</para>
0428 </listitem>
0429 </orderedlist>
0430 </listitem>
0431 <listitem>
0432 <para>
0433 <userinput>Copy</userinput> - copies a file, useful for quick,
0434 local backups</para>
0435 <orderedlist>
0436 <listitem>
0437 <para>Parameter: What should be
0438 copied</para>
0439 </listitem>
0440 <listitem>
0441 <para>Parameter: Where it should
0442 be copied</para>
0443 </listitem>
0444 </orderedlist>
0445 </listitem>
0446 <listitem>
0447 <para>
0448 <userinput>Sync</userinput> - opens the Synchronizer with a
0449 given profile</para>
0450 <orderedlist>
0451 <listitem>
0452 <para>Parameter: A profile for the
0453 Synchronizer</para>
0454 </listitem>
0455 </orderedlist>
0456 </listitem>
0457 <listitem>
0458 <para>
0459 <userinput>NewSearch</userinput> - opens the search windows
0460 with a given profile</para>
0461 <orderedlist>
0462 <listitem>
0463 <para>Parameter: A profile for the
0464 search module</para>
0465 </listitem>
0466 </orderedlist>
0467 </listitem>
0468 <listitem>
0469 <para>
0470 <userinput>Profile</userinput> - loads a given panel
0471 profile</para>
0472 <orderedlist>
0473 <listitem>
0474 <para>Parameter: A panel
0475 profile</para>
0476 </listitem>
0477 </orderedlist>
0478 </listitem>
0479 <listitem>
0480 <para>
0481 <userinput>Each</userinput> - splits the commandline into a
0482 list. These commands are executed one after another.</para>
0483 <orderedlist>
0484 <listitem>
0485 <para>Parameter: A list item (all,
0486 all files, all dirs, all selected).</para>
0487 </listitem>
0488 </orderedlist>
0489 </listitem>
0490 <listitem>
0491 <para>
0492 <userinput>Move</userinput> - move from source to
0493 destination.</para>
0494 <orderedlist>
0495 <listitem>
0496 <para>Parameter: A source</para>
0497 </listitem>
0498 <listitem>
0499 <para>Parameter: A
0500 destination</para>
0501 </listitem>
0502 </orderedlist>
0503 </listitem>
0504 <listitem>
0505 <para>
0506 <userinput>PanelSize</userinput> - change the ratio between
0507 the two panels.</para>
0508 <orderedlist>
0509 <listitem>
0510 <para>Parameter (optional): A
0511 integer value, ⪚, 80 makes the active panel use 80% of
0512 &krusader;'s width (height in vertical mode),
0513 omitting the parameter means 50%.</para>
0514 </listitem>
0515 </orderedlist>
0516 </listitem>
0517 <listitem>
0518 <para>
0519 <userinput>Ask</userinput> - cancel the execution.</para>
0520 <orderedlist>
0521 <listitem>
0522 <para>Parameter (optional): A string
0523 for the cancel question.</para>
0524 </listitem>
0525 </orderedlist>
0526 </listitem>
0527 <listitem>
0528 <para>
0529 <userinput>ListFile</userinput> - is replaced by path/file name
0530 of a temporary file containing a list of items</para>
0531 <orderedlist>
0532 <listitem>
0533 <para>Parameter:
0534 path/filename</para>
0535 </listitem>
0536 </orderedlist>
0537 </listitem>
0538 <listitem>
0539 <para>
0540 <userinput>ColSort</userinput> - set the sorting on a column
0541 of a specific panel.</para>
0542 <orderedlist>
0543 <listitem>
0544 <para>Parameter: Column: Either
0545 <quote>Name</quote>, <quote>Ext</quote>, <quote>Type</quote>, <quote>Size</quote>, <quote>Modified</quote>, <quote>Perms</quote>,
0546 <quote>rwx</quote>, <quote>Owner</quote> and <quote>Group</quote></para>
0547 </listitem>
0548 <listitem>
0549 <para>Parameter: Sort sequence:
0550 Either <quote>Toggle</quote>, <quote>Asc</quote>, <quote>Desc</quote></para>
0551 </listitem>
0552 </orderedlist>
0553 </listitem>
0554 <listitem>
0555 <para>
0556 <userinput>View</userinput> - set the view mode.</para>
0557 <orderedlist>
0558 <listitem>
0559 <para>Parameter: View mode: Either
0560 <quote>generic</quote>, <quote>text</quote>, <quote>hex</quote></para>
0561 </listitem>
0562 <listitem>
0563 <para>Parameter: Window Mode:
0564 Either <quote>tab</quote>, <quote>window</quote></para>
0565 </listitem>
0566 </orderedlist>
0567 </listitem>
0568 </itemizedlist>
0569 <para>A &GUI;-based helper for placeholder adding is
0570 provided. Spaces in Path, Current and List are by default,
0571 automatically escaped. There is one more important thing to know:
0572 All placeholders that interact with &krusader;
0573 internal functions are called at expand time (meaning directly
0574 when the placeholders are replaced). External programs are
0575 called at execution time (meaning after all placeholders are
0576 replaced).</para>
0577 <para>
0578 <emphasis role="bold">Advanced Properties</emphasis>
0579 </para>
0580 <para>Here you can configure where your command should be visible
0581 (for the right click menu). In addition, it is possible to change
0582 the command executed and confirm it separately. You can also set
0583 a user under which the command should be executed.</para>
0584 <itemizedlist>
0585 <listitem>
0586 <para>Configures if the action is valid for a Protocol, Path,
0587 &MIME; type or File name.</para>
0588 </listitem>
0589 <listitem>
0590 <para>Tweaking the command line before being executed.</para>
0591 </listitem>
0592 <listitem>
0593 <para>Set a different user for the execution (this has no
0594 effect in &krusader; internal functions)</para>
0595 </listitem>
0596 </itemizedlist>
0597 </sect1>