krusader/doc/en/useractions.docbook

<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>
  ~/.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 -&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>