<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="moreusage">

  <info>
   <link type="guide" xref="index#usage"/>
   <desc>More advanced usage information.</desc>
  </info>

  <title>Using <app>Kupfer</app> in Depth</title>

 <section>
  <title>Adding Applications and Scripts</title>
  <p>
   <app>Kupfer</app> will show all applications that are configured visible
   in your menu editor.
 </p>
 <p>
   If you want to add an application manually, you can create a new
   <code>.desktop</code> file and place it in one of the standard directories
   for applications, for example <file>~/.local/share/applications</file>,
   where <app>Kupfer</app> will find it. 
  </p>
  <p>
   If you have a collection of scripts that you want to call from
   <app>Kupfer</app>, you can add the scripts folder as a catalog directory
   to <app>Kupfer</app> in the preferences. Scripts that you add to
   <app>Kupfer</app>'s catalog this way can be run directly or in the
   terminal as long as they are executable.
  </p>
  <p>
    You can also save command-lines by using the action <em>Add to
      Favorites</em>.
  </p>
 </section>

  <section>
    <title>Opening Files and Folders</title>
    <p>
      Using the action <em>Open</em>, files and folders are opened in their
      preferred application. The application associations can be changed,
      see <link xref="plugin-applications"/>.
    </p>
  </section>

  <section>
    <title>Show Hidden Files</title>
    <p>
      Use <keyseq><key>Alt</key><key>→</key></keyseq> instead of just
      <key>→</key> when descending into a directory to list hidden files too.
    </p>
  </section>

 <section>
   <title>The <em>Comma Trick</em></title>
    <p> The comma trick allows the user to use actions on many objects at
       the same time.
    </p>

    <p>Simply press comma <key>,</key> when an object is selected. The object
      is put on a "stack", and you can find yet another file or object, press
      comma to put it on the stack. When you subsequently invoke an action, the
      action is carried out on all of the objects at the same time.
    </p>

    <p>Some actions are only "multiplied" when used with many objects, other
      are smarter than that:</p>
    <list>
      <item><p> Selecting many files and using the Create Archive action, all
          files will be packed into the same archive.</p></item>
      <item><p>If you select multiple contacts and use a Send Email action, it
          creates one email directed at all the contacts.</p></item>
      <item><p>If you select multiple subcatalogs (For example Firefox
          Bookmarks and Epiphany Bookmarks) and use Search Contents.., you get
          a subcatalog search restricted to the objects of those two catalogs!
          You can even bind a trigger to this command(!) 
      </p></item>
    </list>
    <p>The comma trick is 
      <link href="http://www.43folders.com/2005/06/13/quicksilver-the-comma-trick">
        directly taken from Quicksilver</link>
      (the example given in the external article should work identically in
      Kupfer).
    </p>
  </section>

 <section>
  <title>Grab Current Selection</title>
  <p> To use the current selected text, from any application, with
    <app>Kupfer</app>, you can configure a global keyboard shortcut for the
    action <em>Show with Selection</em> in <app>Kupfer Preferences</app>.
  </p>
  <p>
   If configured, pressing the global keyboard shortcut
   will summon <app>Kupfer</app> with the current selection as the focused
   object.
  </p>
  <p>See <link xref="keyboard"/></p>
 </section>
  
 <section>
  <title>Command-line Connection</title>
  <p>
    The command <cmd>kupfer</cmd> on the command-line will focus
    <app>Kupfer</app> if it's already running, otherwise it will start it.
  </p>
  <p>
    The command <cmd>kupfer</cmd> can be used to send files or text from
    the command-line to <app>Kupfer</app>.

    For example, if you are using the shell in a directory where you have 
    a file called "report.pdf", you can focus this file in <app>Kupfer</app> by 
    running <cmd>kupfer report.pdf</cmd>. 
  </p>
  <p>
    You can also send text if you pipe the output of a command into
    <cmd>kupfer</cmd>.
  </p>
 </section>
  
 <section>
  <title>Managing Context and Current Selection</title>
  <p>
    If you find the object you want to use, then invoke an action, 
    <app>Kupfer</app> goes away to perform the action (for example start a program 
    or play a song). When you come back to <app>Kupfer</app>, it will still keep the 
    same object and action selected. Some actions make sense to be 
    repeated (like skipping to the next song) and it can be useful to 
    perform different actions on the same object.
  </p>
  <p>
    However, you always have the top level catalog reachable when you 
    "come back" to <app>Kupfer</app> -- say you went into the subcatalog "Albums" 
    to browse your albums only; you select an album to play, and play it. 
    You come back with the album selected -- but your next search will still 
    go over the top level catalog, not just albums.
  </p>
  <p>
    How to come back into the subcatalog you were in? You do that by simply 
    browsing, not searching the first thing you do when you focus <app>Kupfer</app> again. 
    A quick way is to press down-arrow or space to open the browse window; 
    think of it as saying "I want to stay in this subfolder". With the browse 
    window open, your next query will search the current subcatalog. 
  </p>
  <p>
    This way you can work both ways -- you can quickly drill down into folders 
    to find a file, and when you come back for the next action with <app>Kupfer</app> you 
    can either summon any normal toplevel object (just start typing), or stay 
    around where you were, deep in that folder (press space, then type a query).
  </p>
 </section>

  <section>
    <title>Saving Commands as Files</title>
    <p>You can use keyboard shortcut for <em>Compose Command</em> (by
      default it is <keyseq><key>Ctrl</key><key>Return</key></keyseq>) to
      create a command object out of the currently focused command in
      Kupfer.  This object can be saved as a runnable file if you use the
      <em>Save As...</em> action.  The resulting file will can be executed
      when opened from the file manager (it requires that Kupfer is already
      running).
    </p>
  </section>
  <section>
    <title>Ignoring Accents</title>
    <p>
      You can find an object by an unaccented version of its name (this is
      more or less only implemented for latin-based alphabets).  For example
      an item named <em>Suð í</em> can be matched with <em>sud i</em>
      because the accent is removed and the ð transliterated to d.
    </p>
  </section>

</page>
