diff options
Diffstat (limited to 'doc/en/useractions.docbook')
| -rw-r--r-- | doc/en/useractions.docbook | 644 |
1 files changed, 644 insertions, 0 deletions
diff --git a/doc/en/useractions.docbook b/doc/en/useractions.docbook new file mode 100644 index 0000000..2c3b5fd --- /dev/null +++ b/doc/en/useractions.docbook @@ -0,0 +1,644 @@ +<sect1 id="useractions"> + <!-- ********************************************************************** + useractions.docbook + ++++++++++++++++++++++++++ + (C)opyright : (C) 2000 - 2008 + All Rights Reserved Rafi Yanai, Shie Erlich, Frank Schoolmeesters + & the Krusader Krew + e-mail : [email protected] + web site : http://www.krusader.org + description : a Krusader Documentation File + +*************************************************************************** +* Permission is granted to copy, distribute and/or modify this * +* document under the terms of the GNU Free Documentation License, * +* Version 1.1 or any later version published by the Free Software * +* Foundation; with no Invariant Sections, no Front-Cover Texts and * +* no Back-Cover Texts. A copy of the license is available on the * +* GNU site http://www.gnu.org/licenses/fdl.html or by writing to: * +* Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, * +* MA 02110-1301, USA. * +*********************************************************************** --> + <title>UserActions</title> + <indexterm> + <primary>UserActions</primary> + </indexterm> + <!-- Thanks to Jonas Bar --> + <para>With ActionMan you can set up, configure and manage + UserActions. Some general settings are configured with + <link linkend="konfig-useractions">Konfigurator</link>. With + UserActions you can perform actions on files in the panel or to + access &krusader; internal functions with parameters + directly using placeholders. The actions integrate seamlessly + into &kde;'s action system, which means that the + standard Edit Toolbar and Edit Shortcut dialogs will show + UserActions, too. The UserActions are stored in + <filename> + ~/.kde/share/apps/krusader/useraction.xml</filename> (the file + structure is documentated in doxygen headers of UserActionXML). + Several + <link linkend="useraction-xml">examples</link> are included in the + documentation. UserActions can be edited / added / imported / + exported by using ActionMan. The default UserActions are stored + in + <filename> + ~/.kde/share/apps/krusader/useraction-examples.xml</filename>. + UserActions can appear nearly everywhere where "normal" KActions + can be placed. The actions integrate seamlessly into + &kde; action system, which means that the standard + Edit Toolbar and Edit Shortcut dialogs will show UserActions, + too. They can even be placed in the menu bar, but for that the + <filename>krusaderui.rc</filename> file must be edited. A few + examples: + <itemizedlist> + <listitem> + <para> + <link linkend="useractions-menu">Useractions Menu</link> + </para> + </listitem> + <listitem> + <para>&usermenu-lnk;</para> + </listitem> + <listitem> + <para>&actions-toolbar-lnk;</para> + </listitem> + <listitem> + <para>right click menus</para> + </listitem> + <listitem> + <para>&etc;</para> + </listitem> + </itemizedlist>&krusader;'s UserActions tool is very + powerful and customizable if you are familiar with writing + UserActions in general.</para> + <tip> + <para>Several UserActions are provided by default. Please + <link linkend="help_krusader">upload your favorite + UserActions</link> so that they become available for the + &krusader; community. Thanks! We provide also an + &useractionsforum-url;.</para> + </tip> + <figure id="screenshot-actionman" float="1"> + <title>ActionMan</title> + <mediaobject> + <imageobject> + <imagedata fileref="actionman.png"></imagedata> + </imageobject> + <textobject> + <phrase>ActionMan</phrase> + </textobject> + </mediaobject> + </figure> + <para>Basically, UserActions are a method to call external + programs with variable parameters. For example, you could have a + UserAction with the following + <command>xmms + <option>--enqueue %aList("Selected")%</option></command> to + enqueue all selected items of the active panel to the current + instance of xmms. Additionally, there is limited access to + &krusader; internal functions requiring parameters. + For example, + <command>%aPanelSize("80")%</command> will set the width of the + active panel to 80% of the &krusader; mainwindow. + Since the parameter of placeholders can contain other + placeholders, few scripts are possible. However, scripting can be + done with the &javascript-console-lnk;.</para> + <para> + <emphasis role="bold">Managing UserActions</emphasis> + </para> + <para>Open Konfigurator and choose "UserActions -> + ActionMan", in which you can add, edit, remove, import and export + UserActions. + <itemizedlist> + <listitem> + <para> + <guimenuitem>Add Action</guimenuitem>: If you add an new + action, you get an empty input mask where you can enter all + the properties you desire. The action will be added as soon + as you press + <guimenuitem>Ok</guimenuitem>. Afterwards, the name is shown + in the list on the left.</para> + </listitem> + <listitem> + <para>To edit a UserAction: Select the UserAction on the + left. Then choose it if you want to edit its properties. The + changes will only take effect when you press + <guimenuitem>OK</guimenuitem>.</para> + </listitem> + <listitem> + <para> + <guimenuitem>To remove a UserAction</guimenuitem>: Select the + UserAction on the left and click the remove button.</para> + </listitem> + <listitem> + <para> + <guimenuitem>To import a UserAction</guimenuitem>: If you + import some actions, they will be automatically added to your + list. If there are name conflicts (the names have to be + unique because these are the ID for &kde;'s action + system), you are asked to resolve them. For this, the list on + the left will only show the actions where conflicts exist. + You can now give them new names or remove them.</para> + </listitem> + <listitem> + <para> + <guimenuitem>Export Action</guimenuitem>: If you export a + UserAction you have to give a filename in which to store it. + If it does not exist, it will be created. If the file already + contains UserActions, the action you are exporting will be + added to that file.</para> + </listitem> + </itemizedlist>All actions you have defined are now shown in the + user menu and in &kde; dialogs for changing shortcuts + and managing the toolbar. In addition, all actions available for + the current item will also show up in the right click + menu.</para> + <para> + <emphasis role="bold"> + <guimenuitem>Basic Properties</guimenuitem> + </emphasis> + </para> + <para> + <guimenuitem>"Distinct Name", "Title" and "Command + line"</guimenuitem>are always required, all the other properties + are optional. + <itemizedlist> + <listitem> + <para> + <guimenuitem>"Distinct Name"</guimenuitem>: A unique name of + the UserAction, used to identify it for &kde;'s + action system.</para> + </listitem> + <listitem> + <para> + <guimenuitem>"Icon button"</guimenuitem>: The icon for your + UserAction.</para> + </listitem> + <listitem> + <para> + <guimenuitem>"Category"</guimenuitem>: Adds a category for a + better overview. NOTE: This property is not used yet. It is + planned to be used, but has not implemented yet.</para> + </listitem> + <listitem> + <para> + <guimenuitem>"Title"</guimenuitem>: The title displayed in + the menus or dialogs.</para> + </listitem> + <listitem> + <para> + <guimenuitem>"Tooltip"</guimenuitem>: A tooltip for your + UserAction, ⪚ displayed in the toolbar on + mouseover.</para> + </listitem> + <listitem> + <para> + <guimenuitem>"Description"</guimenuitem>: A description of + what the UserAction does. This is also displayed as + <guimenuitem>"What's This"</guimenuitem> if you + <keycombo action="simul">&Shift; + <keycap>F1</keycap></keycombo> click on your + UserAction.</para> + </listitem> + <listitem> + <para> + <guimenuitem>"Use Tooltip checkbox"</guimenuitem>: Uses the + tooltip as description.</para> + </listitem> + <listitem> + <para> + <guimenuitem>"Command line"</guimenuitem>: The command which + will be executed. You can add placeholder using a GUI with + the + <guibutton>add</guibutton> button.</para> + </listitem> + <listitem> + <para> + <guimenuitem>"Startpath"</guimenuitem>: The working directory + for the command which will be executed.</para> + </listitem> + <listitem> + <para> + <guimenuitem>"Execution mode"</guimenuitem>:</para> + <itemizedlist> + <listitem> + <para> + <guimenuitem>"Normal"</guimenuitem>: Normal execution + mode.</para> + </listitem> + <listitem> + <para> + <guimenuitem>"Run in terminal"</guimenuitem>: Runs the + command in the terminal.</para> + </listitem> + <listitem> + <para> + <guimenuitem>"Collect output"</guimenuitem>: Collects the + output of the executed program in a &GUI; + window.</para> + </listitem> + <listitem> + <para> + <guimenuitem>"Separate standard error"</guimenuitem>: + When "Collect output" is used the stdout and stderr are + separately collected.</para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + <guimenuitem>"Command accepts"</guimenuitem>:</para> + <itemizedlist> + <listitem> + <para> + <guimenuitem>"Local files (no URLs)"</guimenuitem>: Tells + the placeholder it should return local addresses.</para> + </listitem> + <listitem> + <para> + <guimenuitem>"URLs (local and remote)"</guimenuitem>: + Tells the placeholder it should return + &URL;s.</para> + </listitem> + </itemizedlist> + </listitem> + <!-- Not yet implemented, but will be after 1.50 stable is released + <listitem><para><guimenuitem>"On multiple selection"</guimenuitem>: </para> + <itemizedlist> + <listitem><para><guimenuitem>"separate call for each file"</guimenuitem>: executes the command for each selected file. + </para></listitem> + </itemizedlist> + </listitem> --> + <listitem> + <para> + <guimenuitem>"Shortcut button"</guimenuitem>: Configures a + shortcut for the UserAction.</para> + </listitem> + </itemizedlist></para> + <para> + <emphasis role="bold">Command-line syntax:</emphasis> + </para> + <para>Basically, everything you type in the command line will get + executed (if you type "ls -l", "ls -l" gets executed). You have + the possiblity to get a character string from + &krusader; which represents the current state of the + panel. This is done using placeholders. A placeholder begins with + a percent-sign ('%') and is followed by a panel indicator ('a' + for the active, 'o' for the other, 'l' for the left and 'r' for + the right panel. If the placeholder doesn't need a panel to + operate on, you have to indicate this by an underscore ('_')). + Then comes the name of the placeholder (see the list below), + which may get some parameters enclosed in quotes. Finally, again + the percent sign.</para> + <para>This sounds very complicated, so let's make an example: + '%aList("Selected")%' is replaced by a list of all selected items + in the active panel. So a command like 'xmms --enqueue + %aList("All", " ", "", "*.mp3")%' will execute xmms with a list + of all .mp3s in the current panel, separated by a single + blank.</para> + <para>Currently, these placeholders are implemented: + <itemizedlist> + <listitem> + <para> + <userinput>Path</userinput> - replaced by the panels + path</para> + <orderedlist> + <listitem> + <para>&useraction-optional-parameter; + Automatic escape spaces. &useraction-default; + yes</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>Count</userinput> - replaced by the number of + <first parameter></para> + <orderedlist> + <listitem> + <para>&useraction-parameter; Which items; + either "All", "Selected", "Files" or "Dirs"</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>Filter</userinput> - replaced by the panel's filter + mask</para> + </listitem> + <listitem> + <para> + <userinput>Current</userinput> - replaced by the current + item</para> + <orderedlist> + <listitem> + <para>&useraction-optional-parameter; Omit the + current path. &useraction-default; no</para> + </listitem> + <listitem> + <para>&useraction-optional-parameter; + Automatic escape spaces. &useraction-default; + yes</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>List</userinput> - replaced by a list of all + <first parameter></para> + <orderedlist> + <listitem> + <para>&useraction-parameter; Which items; + either "All", "Selected", "Files" or "Dirs"</para> + </listitem> + <listitem> + <para>&useraction-optional-parameter; + Separator between the items. + &useraction-default; + " "</para> + </listitem> + <listitem> + <para>&useraction-optional-parameter; Omit the + current path. &useraction-default; no</para> + </listitem> + <listitem> + <para>&useraction-optional-parameter; + Filtermask (for all but "Selected"). + &useraction-default; *</para> + </listitem> + <listitem> + <para>&useraction-optional-parameter; + Automatic escape spaces. &useraction-default; + yes</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>Select</userinput> - manipulates the selection in a + panel</para> + <orderedlist> + <listitem> + <para>&useraction-parameter; Filtermask</para> + </listitem> + <listitem> + <para>&useraction-optional-parameter; + manipulate in which way; either "Set", "Add" or "Remove". + &useraction-default; "Set"</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>Goto</userinput> - changes the panels' path to + <first parameter></para> + <orderedlist> + <listitem> + <para>&useraction-parameter; A relative or + absolute path, or an URL</para> + </listitem> + <listitem> + <para>&useraction-optional-parameter; Open the + location in a new tab. &useraction-default; + no</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>Ask</userinput> - asks the user for some text and + is replaced by the answer</para> + <orderedlist> + <listitem> + <para>&useraction-parameter; The + Question</para> + </listitem> + <listitem> + <para>&useraction-optional-parameter; A + default answer</para> + </listitem> + <listitem> + <para>&useraction-optional-parameter; A + caption for the question box</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>Clipboard</userinput> - manipulates the + clipboard</para> + <orderedlist> + <listitem> + <para>&useraction-parameter; The text that + should go to the clipboard (you may want to use + "%aCurrent%" here)</para> + </listitem> + <listitem> + <para>&useraction-optional-parameter; Append + the text to the current content of the clipboard with + this separator</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>Copy</userinput> - copies a file, useful for quick, + local backups</para> + <orderedlist> + <listitem> + <para>&useraction-parameter; What should be + copied</para> + </listitem> + <listitem> + <para>&useraction-parameter; Where it should + be copied</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>Sync</userinput> - opens the Synchronizer with a + given profile</para> + <orderedlist> + <listitem> + <para>&useraction-parameter; A profile for the + Synchronizer</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>NewSearch</userinput> - opens the search windows + with a given profile</para> + <orderedlist> + <listitem> + <para>&useraction-parameter; A profile for the + search module</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>Profile</userinput> - loads a given panel + profile</para> + <orderedlist> + <listitem> + <para>&useraction-parameter; A panel + profile</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>Each</userinput> - splits the commandline into a + list. These commands are executed one after another.</para> + <orderedlist> + <listitem> + <para>&useraction-parameter; A list item (all, + all files, all dirs, all selected).</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>Move</userinput> - move from source to + destination.</para> + <orderedlist> + <listitem> + <para>&useraction-parameter; A source</para> + </listitem> + <listitem> + <para>&useraction-parameter; A + destination</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>PanelSize</userinput> - change the ratio between + the two panels.</para> + <orderedlist> + <listitem> + <para>&useraction-optional-parameter; A + integer value, e.g., 80 makes the active panel use 80% of + &krusader;'s width (height in vertical mode), + omitting the parameter means 50%.</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>Ask</userinput> - cancel the execution.</para> + <orderedlist> + <listitem> + <para>&useraction-optional-parameter; A string + for the cancel question.</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>Script</userinput> - executes an external + <link linkend="javascript_console"> + Javascript</link> file.</para> + <para>NOTE: This is still experimental and the interface may + change, feedback is always welcome.</para> + <orderedlist> + <listitem> + <para>&useraction-parameter; path to the + external foo.js file, absolute path or relative to + <filename> + <kde-app-data>/krusader/js/</filename>. + <kde-app-data> is + <filename>$(kde-config + --localprefix)/share/apps/</filename> or + <filename>$(kde-config --prefix)/share/apps/</filename>, + for those who don't know where to copy the + scripts/extensions. If all the needed files (normally + <filename>.js</filename> and maybe + <filename>.ui</filename>) are in one of these dirs it's + sufficient to give the file name only as 1. + parameter.</para> + </listitem> + <listitem> + <para>&useraction-optional-parameter; a list + of variables which should be set, like "return=cmd; + a=lalala; b='%_Ask(..)'" so that the placeholder is + replaced be the content of the variable cmd and the other + two have already these values when the script + starts.</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>ListFile</userinput> - is replaced by path/file name + of a temporary file containing a list of items</para> + <orderedlist> + <listitem> + <para>&useraction-parameter; + path/filename</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>ColSort</userinput> - set the sorting on a column + of a specific panel.</para> + <orderedlist> + <listitem> + <para>&useraction-parameter; Column: Either + "Name", "Ext", "Type", "Size", "Modified", "Perms", + "rwx", "Owner" and "Group"</para> + </listitem> + <listitem> + <para>&useraction-parameter; Sort sequence: + Either "Toggle", "Asc", "Desc"</para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> + <userinput>View</userinput> - set the view mode.</para> + <orderedlist> + <listitem> + <para>&useraction-parameter; View mode: Either + "generic", "text", "hex"</para> + </listitem> + <listitem> + <para>&useraction-parameter; Window Mode: + Either "tab", "window"</para> + </listitem> + </orderedlist> + </listitem> + </itemizedlist>A GUI-based helper for placeholder adding is + provided. Spaces In Path, Current and List are by default, + automatically escaped. There is one more important thing to know: + All placeholders that interact with &krusader; + internal functions are called at expand time (meaning directly + when the placeholders are replaced). External programs are + called at execution time (meaning after all placeholders are + replaced).</para> + <para> + <emphasis role="bold"> + <guimenuitem>Advanced Properties</guimenuitem> + </emphasis> + </para> + <para>Here you can configure where your command should be visible + (for the right click menu) In addition, it is possible to change + the command executed and confirm it separately. You can also set + a user under which the command should be executed. + <itemizedlist> + <listitem> + <para>Configures if the action is valid for a Protocol, Path, + Mime type or File name.</para> + </listitem> + <listitem> + <para>Tweaking the command line before being executed.</para> + </listitem> + <listitem> + <para>Set a different user for the execution (this has no + effect in &krusader; internal functions)</para> + </listitem> + </itemizedlist></para> +</sect1> |