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

  <info>
   <link type="guide" xref="index#usage"/>
   <desc>Complete keyboard shortcuts reference.</desc>
  </info>

  <title>Command Keys and Accelerator Keys</title>

  <section>
    <title>Keyboard Interface</title>
  <p>
    In command mode, the following keystrokes have special meanings: 
  </p>
  <table>
    <tr>
      <td><p><key>↓</key> or <key>Space</key></p></td>
      <td><p> Go to the next match </p></td>
    </tr>
    <tr>
      <td><p>
        <key>↑</key> or <keyseq><key>Shift</key><key>Space</key></keyseq>
      </p></td>
     <td><p> Go to the previous match </p></td>
    </tr>
    <tr>
      <td><p> <key>→</key> or <key>/</key>  </p></td>
     <td><p> Descend into an object with content </p></td>
    </tr>
    <tr>
      <td><p> <key>Backspace</key></p></td>
     <td><p> Erase a character from the query. If the
       query is empty, go up a level 
   </p></td>
    </tr>
    <tr>
      <td><p> <key>.</key></p></td>
     <td><p> Activate free-text mode </p></td>
    </tr>
    <tr>
      <td><p> <key>,</key></p></td>
     <td><p> Put selected object on the stack ("Comma Trick") </p></td>
    </tr>
   </table>
  <p>
    Quick access keys:
  </p>
  <table>
    <tr>
      <td><p>
          <key>=</key>
        </p></td>
        <td><p> Activate free-text mode with =
          prefix (for <link xref="plugin-calculator" />)
      </p></td>
    </tr>
    <tr>
      <td><p>
          <key>/</key>
        </p></td>
        <td><p> Activate free-text mode (when nothing is selected) with
            <code>/</code> prefix (to input a rooted path) 
        </p></td>
    </tr>
   </table>
  <p>
    Additionally:
  </p>
  <list>
    <item><p><key>Return</key> activates the current selection: the command is executed.
    </p></item>
    <item><p><key>Escape</key> clears the current selection.</p></item>
    <item><p><key>Tab</key> switches between the object and the action pane. </p></item>
  </list>
  <p>
    The meaning of the keys <key>Space</key>, <key>.</key>, <key>,</key>,
    <key>/</key> and <key>=</key> can not be changed, but you can deactivate
    their special meaning with the checkbox <app>Use single keystroke
    commands</app> in <app>Kupfer Preferences</app>.
  </p>
  </section>

  <section>
    <title>Kupfer's Keyboard Shortcuts</title>
    <p>
      These keyboard shortcuts are used in <app>Kupfer</app>'s interface.
      They have the following meanings and default shortcuts (some
      have no default).
    </p>
  <table>
    <tr>
      <td><p><keyseq><key>Alt</key><key>A</key></keyseq></p></td>
      <td><p> Alternate activate </p></td>
    </tr>
    <tr>
      <td><p><keyseq><key>Ctrl</key><key>.</key></keyseq></p></td>
      <td><p> Toggle text mode </p></td>
    </tr>
    <tr>
      <td><p><keyseq><key>Ctrl</key><key>,</key></keyseq></p></td>
      <td><p> The comma trick </p></td>
    </tr>
    <tr>
      <td><p><keyseq><key>Ctrl</key><key>;</key></keyseq></p></td>
      <td><p> Show preferences window </p></td>
    </tr>
    <tr>
      <td><p><keyseq><key>Ctrl</key><key>R</key></keyseq></p></td>
      <td><p> Reset all </p></td>
    </tr>
    <tr>
      <td><p><keyseq><key>Ctrl</key><key>Return</key></keyseq></p></td>
      <td><p> Compose command </p></td>
    </tr>
    <tr>
      <td><p></p></td>
      <td><p> Switch to 1st pane </p></td>
    </tr>
    <tr>
      <td><p></p></td>
      <td><p> Switch to 2st pane </p></td>
    </tr>
    <tr>
      <td><p></p></td>
      <td><p> Switch to 3st pane </p></td>
    </tr>
    <tr>
      <td><p><keyseq><key>Ctrl</key><key>Q</key></keyseq></p></td>
      <td><p> Select 'Quit' </p></td>
    </tr>
    <tr>
      <td><p></p></td>
      <td><p> Select 'Clipboard File' </p></td>
    </tr>
    <tr>
      <td><p></p></td>
      <td><p> Select 'Clipboard Text' </p></td>
    </tr>
    <tr>
      <td><p></p></td>
      <td><p> Select 'Selected File' </p></td>
    </tr>
    <tr>
      <td><p><keyseq><key>Ctrl</key><key>G</key></keyseq></p></td>
      <td><p> Select 'Selected Text' </p></td>
    </tr>
    <tr>
      <td><p><keyseq><key>F1</key></keyseq></p></td>
      <td><p> Show Help </p></td>
    </tr>

   </table>
   <steps>
     <title>How to configure a keyboard shortcut</title>
     <item>
      <p>
        Open <app>Kupfer Preferences</app> and go to the
        <em>Keyboard</em> tab.
      </p>
     </item>
     <item>
      <p>
        Double-click the shorcut's row under <em>Browser Keyboard
          Shortcuts</em>.
      </p>
     </item>
     <item>
      <p>
        Using the window that appears, press modifier keys and a letter or
        number key to set a shortcut. An example is pressing and holding
        <key>Ctrl</key> and then pressing and releasing <key>T</key> to bind
        <keyseq><key>Ctrl</key><key>T</key></keyseq>.
      </p>
     </item>
    </steps>
  </section>

  <section>
    <title>Action Accelerators</title>
    <p>
      Action acclerators are a quick way to select or run a certain action
      on an object.
      All action accelerators use the same modifier key, which is <key>Ctrl</key>
      by default.
    </p>
    <p>
      An action's accelerator is a key that is pressed together with the
      modifier to directly run the action on the currently selected object
      (in the case of actions that need an indirect object, the third pane
      will be focused instead).
    </p>
   <steps>
     <title>How to configure an action accelerator</title>
     <item>
      <p>
        Open <app>Kupfer</app> and find an object that allows the action
        you are configuring. Switch to the action pane with <key>Tab</key>.
      </p>
     </item>
     <item>
      <p>
        Find the action to configure an accelerator for in the action pane.
      </p>
     </item>
     <item>
      <p>
        Click the kupfer context menu in the window and select the option
        <em>Assign Accelerator to “(Action)”</em>
      </p>
     </item>
     <item>
      <p>
        Press and release a single key (with or without the action
        accelerator’s modifier) in the window that pops up.
        <key>Escape</key> cancels the configuration, and
        <key>Backspace</key> unsets the accelerator key for the action.
      </p>
     </item>
    </steps>
    <note>
      <p>Regular keyboard shortcuts in <app>Kupfer</app> take precedence over
        action accelerator keys. If multiple simultaneously eligible actions
        have the same accelerator key, the highest ranked one will be
        activated.
      </p>
    </note>
  </section>

  <section>
    <title>Global Keyboard Shortcuts</title>
    <p>
      <app>Kupfer</app> always listens to global shortcuts, even if it is not
      currently in the foreground.
    </p>
    <p>
      They have the following meanings and default shortcuts:
    </p>
  <table>
    <tr>
      <td><p><keyseq><key>Ctrl</key><key>Space</key></keyseq></p></td>
      <td><p> Show/hide <app>Kupfer</app></p></td>
    </tr>
    <tr>
      <td><p>(not configured by default)</p></td>
      <td><p> Show <app>Kupfer</app> with 'Selection' object focused</p></td>
    </tr>
  </table>
    <steps>
     <title>How to configure a global keyboard shortcut</title>
     <item>
      <p>
        Open <app>Kupfer Preferences</app> and go to the
        <em>Keyboard</em> tab.
      </p>
     </item>
     <item>
      <p>
        Double-click the shorcut's row under <em>Global Keyboard
          Shortcuts</em>.
      </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 <key>Super</key> and then pressing and releasing
        <key>Space</key> to bind
        <keyseq><key>Super</key><key>Space</key></keyseq>.
      </p>
     </item>
    </steps>
    <p>
      Since these 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>Triggers</title>
    <p>
      The plugin <em>Triggers</em> allows to activate actions with
      global keyboard shortcuts. Trigger shortcuts do not appear in
      <app>Kupfer Preferences</app>.
    </p>

    <p>
      See <link xref="plugin-triggers"/> for more information.
    </p>
  </section>

</page>
