manual/include/keyboard-shortcuts.html

<p>
	The <kbd class="window">Keyboard Shortcuts</kbd> dialog allows easily
	redefining existing keyboard shortcuts to operations and creating new ones.
</p>

<figure>
  <img style="width:50%;" src="/images/keyboard-shortcuts-window.png" alt="Keyboard Shortcuts">
  <figcaption>
    Keyboard Shortcuts
  </figcaption>
</figure>

<p class="note">
	A thematic list of the default keyboard shortcuts in Ardour can be 
	found in the <a href="@@default-shortcuts">Appendix</a>, but the 
	<kbd>Print Bindings (to your web browser)</kbd> button show an 
	up-to-date list of the current keyboard bindings, with 
	customization, nicely laid out by theme and alphabetical. 
</p>

<h2>Contexts and Subcontexts</h2>

<p>
	The important concept to understand here is that the same shortcut can be
	used for different operations in different contexts. E.g. in the
	<dfn>Editor</dfn> context, the <kbd>T</kbd> key switches
	on the <dfn>Stretch</dfn> mode to time-stretch clips on the canvas. However,
	in the MIDI Step Entry context, <kbd>T</kbd> inserts
	an F-sharp note. The contexts are represented by tabs in this dialog, e.g.
	Editor, MIDI, Recorder, etc.
</p>

<p>
	Inside every tab, features are grouped into <dfn>subcontexts</dfn> that can
	be expanded or collapsed by clicking the triangular-shaped button to the
	left of the name of each subcontext. E.g. the 'Snap' subcontext lists all
	snapping units, while the 'Region' subcontext lists all actions accessible
	via the right-click menu.
</p>

<p>
	The <dfn>Search</dfn> function at the bottom of the dialog works within
	the currently selected context/tab only. If a search returned zero results,
	switching to a different context is a viable solution to locating the action
	of interest.
</p>

<h2>Setting New Shortcuts</h2>

<p>
	Once an action of interest is located in the list, all it takes to set
	a keybinding to it is selecting the action in the list, then pressing
	the sequence of keys. The newly defined keybinding will immediately show up
	in the <dfn>Shortcut</dfn> column.
</p>

<h2>Redefining Existing Shortcuts</h2>

<p>
	An existing shortcut to an action can easily be replaced with a different
	one by selecting the action and pressing a new sequence of keys. The newly
	defined keybinding will immediately show up in the <dfn>Shortcut</dfn>
	column.
</p>

<h2>Handling Collisions</h2>

<p>
	Once a keybinding is assigned to an action, that keybinding is considered
	taken. Attempting to assign that same keybinding to a different action will
	result in a collision. Ardour will notify the user that the keybinding is
	already taken (and by what action) and will ask to either reconsider or
	force-set the keybinding to a new action.
</p>

<figure>
  <img style="width:50%;" src="/images/keyboard-shortcuts-collision.png" alt="A keyboard shortcut collision">
  <figcaption>
    A keyboard shortcut collision
  </figcaption>
</figure>

<p>
	Force-setting the keybinding of choice to a new action will remove
	the keybinding from the action it was previously assigned to. A new
	keybinding then can be assigned to that action.
</p>

<h2>Removing Existing Shortcuts</h2>

<p>
	In some cases it is desirable to remove a shortcuts entirely. Selecting an
	action of interest, then pressing the
	<kbd>Remove shortcut</kbd> button at the bottom of the dialog
	will do just that. The keybinding will immediately disappear from the
	<dfn>Shortcut</dfn> column.
</p>

<h2>Reverting to Factory Settings</h2>

<p>
	If applied customizations to default keyboard shortcuts didn't work out,
	it's possible to revert to "factory settings". Clicking
	<kbd>Reset Bindings to Defaults</kbd> will remove all
	customizations and bring back default keybindings. Important: Ardour will not
	ask for a confirmation!
</p>