You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
krusader/doc/en/useractions.docbook

645 lines
22 KiB

<sect1 id="useractions">
<!-- **********************************************************************
useractions.docbook
++++++++++++++++++++++++++
(C)opyright : (C) 2000 - 2008
All Rights Reserved Rafi Yanai, Shie Erlich, Frank Schoolmeesters
& the Krusader Krew
e-mail : krusader@users.sourceforge.net
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>
~/.trinity/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>
~/.trinity/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 -&gt;
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, &eg; 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
&lt;first parameter&gt;</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
&lt;first parameter&gt;</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;
"&nbsp;"</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
&lt;first parameter&gt;</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>
&lt;kde-app-data&gt;/krusader/js/</filename>.
&lt;kde-app-data&gt; 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>