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

  <info>
   <link type="guide" xref="index#plugins"/>
   <desc>Using the triggers plugin.</desc>
  </info>

  <title><app>Triggers</app></title>

 <section>
  <title>Triggers Plugin</title>
  <p>
    With <app>Triggers</app> you can take a command you would normally
    perform in <app>Kupfer</app>, such as launching an application or
    opening a document, and bind a global key combination to run this
    command. As long as <app>Kupfer</app> is running, any application can
    have the current focus. 
  </p>
  </section>
  <section>
    <title>Basic Usage</title>
    <steps>
     <title>Creating a new trigger</title>
     <item>
      <p>
        Set up a command in <app>Kupfer</app> that you want to run
      </p>
     </item>
     <item>
      <p>
        Press <keyseq><key>Ctrl</key><key>Return</key></keyseq>  to create a
        <em>composed command</em>.
      </p>
     </item>
     <item>
      <p>
        Type <key>Tab</key> and select the action <em>Add Trigger...</em>
        and press <key>Return</key>
      </p>
     </item>
     <item>
      <p>
        Using the window that appears, press modifier keys and a letter or
        number key to set a global shortcut. An example is pressing and
        holding <keyseq><key>Ctrl</key><key>Alt</key></keyseq> and then
        pressing and releasing <key>R</key> to bind
        <keyseq><key>Ctrl</key><key>Alt</key><key>R</key></keyseq>.
      </p>
     </item>
    </steps>
    <steps>
     <title>Removing a trigger</title>
     <item>
      <p>
        Find the source <em>Triggers</em> in <app>Kupfer</app> and
        press <key>→</key> to see its contents.
      </p>
     </item>
     <item>
      <p>
        Find the active trigger in the list and use the action <em>Remove
          Trigger</em>.
      </p>
     </item>
    </steps>
    <p> Since trigger keyboard shortcuts are global, they can be used from
      any application. Select shortcuts with care so that they do
      not conflict with other functions.
    </p>
 </section>
 <section>
   <title>Power User Tips</title>
   <p> <em>Proxy objects</em> such as <em>Selected Text</em>,  <em>Clipboard Text</em>,
     <em>Clipboard File</em>,
     <em>Frontmost Window</em>, <em>Last Command</em> et cetera allow very
     powerful triggers.
   </p>
   <p> The application action <em>Launch</em> is special; if you bind a
     trigger using <em>Launch</em>, it will start the application if it is
     not running, but focus the application when it is already running. By
     contrast, <em>Start Again</em> will start the application if it is
     running or not.
   </p>
 </section>
 <section>
   <title>Example Triggers</title>
   <terms>
     <item>
       <title><em>Text Editor → Launch</em></title>
       <p>
         Start <em>Text Editor</em> or focus its window if it is already
         running.
       </p>
     </item>
     <item>
         <title><em>Selected Text → Search in Wikpedia</em></title>
         <p>Search using the currently selected text.  </p></item>
     <item>
       <title><em>Songs → Search Contents</em></title>
       <p>
         You may even add a trigger to open a specific subcatalog in Kupfer,
         for example Rhythmbox's songs.
       </p>
     </item>
   </terms>
 </section>
  
</page>
