useractions.docbook

LINUX 下, 以 QT/KDE 写的档案管理员

<sect1 id="useractions">
  <!-- **********************************************************************
                            useractions.docbook
                          ++++++++++++++++++++++++++
 (C)opyright            : (C) 2000 - 2008
  All Rights Reserved     Rafi Yanai, Shie Erlich, Frank Schoolmeesters
                          & the Krusader Krew
  e-mail                : [e-mail]
  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., 59 Temple Place - Suite 330, Boston,    *
* MA 02111-1307, 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>