add example bindings configuration file with comprehensive description

doc/Makefile.am

@@ -1,4 +1,4 @@
 docdir = $(prefix)/share/doc/$(PACKAGE)
 man_MANS = ncmpcpp.1
-doc_DATA = config keys
+doc_DATA = bindings config
 EXTRA_DIST = $(doc_DATA)

doc/bindings

@@ -0,0 +1,444 @@
+##########################################################
+## this is example bindings configuration file, copy it ##
+## to ~/.ncmpcpp/bindings and set up your preferences   ##
+##########################################################
+##
+##### General rules #####
+##
+## 1) Because each action has runtime checks whether it's
+##    ok to run it, a few actions can be bound to one key.
+##    Actions will be bound in order given in configuration
+##    file. When a key is pressed, first action in order
+##    will test itself whether it's possible to run it. If
+##    test succeeds, action is executed and other actions
+##    bound to this key are ignored. If it doesn't, next
+##    action in order tests itself etc.
+##
+## 2) It's possible to bind more that one action at once
+##    to a key. It can be done using the following syntax:
+##
+##    key_def "key"
+##      action1
+##      action2
+##      ...
+##
+##    This creates chain of actions. When such chain is
+##    executed, each action in chain is run until the end of
+##    chain is reached or one of actions failed to execute
+##    due to its requirements not being met. Note that
+##    execution of chain of actions ALWAYS succeeds, no
+##    matter if one of actions from the chain failed (even
+##    if it was the first one in order and thus nothing
+##    was really executed). Because of that, if you decide
+##    to bind both actions and chains to a single key, make
+##    sure that chain is defined in the end. Otherwise, all
+##    actions bound to the key after chain will never be run.
+##
+## 3) When ncmpcpp starts, bindings configuration file is
+##    parsed and then ncmpcpp provides "missing pieces"
+##    of default keybindings. If you want to disable some
+##    bindings, there is a special action called 'dummy'
+##    for that purpose. Eg. if you want to disable ability
+##    to crop playlists, you need to put the following
+##    into configuration file:
+##
+##    key_def "C"
+##      dummy
+##
+##    After that ncmpcpp will not bind any default action
+##    to this key.
+##
+## 4) To let you write simple macros, the following special
+##    actions are provided:
+##
+##    - push_character "character" - pushes given special
+##      character into input queue, so it will be immediately
+##      picked by ncmpcpp upon next call to readKey function.
+##      Accepted values: mouse, up, down, page_up, page_down,
+##      home, end, space, enter, insert, delete, left, right,
+##      tab, shift_tab, ctrl_a, ctrl_b, ..., ctrl_z, f1, f2,
+##      ..., f12, backspace, backspace_2.
+##
+##    - push_characters "string" - pushes given string into
+##      input queue.
+##
+##    - require_runnable "action" - checks whether given action
+##      is runnable and fails if it isn't. This is especially
+##      useful when mixed with previous two functions. Consider
+##      the following macro definition:
+##
+##      def_key "key"
+##        push_characters "custom_filter"
+##        apply_filter
+##
+##      If apply_filter can't be currently run, we end up with
+##      sequence of characters in input queue which will be
+##      treated just as we typed them. This may lead to unexpected
+##      results (in this case 'c' will most likely clear current
+##      playlist, 'u' will trigger database update, 's' will stop
+##      playback etc.). To prevent such thing from happening, we
+##      need to change above definition to this one:
+##
+##      def_key "key"
+##        require_runnable "apply_filter"
+##        push_characters "custom_filter"
+##        apply_filter
+##
+##      Here, first we test whether apply_filter can be actually run
+##      before we stuff characters into input queue, so if condition
+##      is not met, whole chain is aborted and we're fine.
+##
+## Note: Both 'backspace' and 'backspace_2' are used because some
+##       terminals interpret backspace using keycode of 'backspace'
+##       and some the one of 'backspace_2'. You can get away with
+##       binding once if all your terminal emulators use the same
+##       value.
+##
+## Note: Function def_key accepts non-ascii characters.
+##
+#
+#def_key "mouse"
+#  mouse_event
+#
+#def_key "up"
+#  scroll_up
+#
+#def_key "down"
+#  scroll_down
+#
+#def_key "["
+#  scroll_up_album
+#
+#def_key "]"
+#  scroll_down_album
+#
+#def_key "{"
+#  scroll_up_artist
+#
+#def_key "}"
+#  scroll_down_artist
+#
+#def_key "page_up"
+#  page_up
+#
+#def_key "page_down"
+#  page_down
+#
+#def_key "home"
+#  move_home
+#
+#def_key "end"
+#  move_end
+#
+#def_key "space"
+#  press_space
+#
+#def_key "enter"
+#  press_enter
+#
+#def_key "delete"
+#  delete
+#
+#def_key "right"
+#  next_column
+#
+#def_key "right"
+#  slave_screen
+#
+#def_key "right"
+#  volume_up
+#
+#def_key "+"
+#  volume_up
+#
+#def_key "left"
+#  previous_column
+#
+#def_key "left"
+#  master_screen
+#
+#def_key "left"
+#  volume_down
+#
+#def_key "-"
+#  volume_down
+#
+#def_key "tab"
+#  next_screen
+#
+#def_key "shift_tab"
+#  previous_screen
+#
+#def_key "f1"
+#  show_help
+#
+#def_key "1"
+#  show_playlist
+#
+#def_key "2"
+#  show_browser
+#
+#def_key "3"
+#  show_search_engine
+#
+#def_key "4"
+#  show_media_library
+#
+#def_key "5"
+#  show_playlist_editor
+#
+#def_key "6"
+#  show_tag_editor
+#
+#def_key "7"
+#  show_outputs
+#
+#def_key "8"
+#  show_visualizer
+#
+#def_key "="
+#  show_clock
+#
+#def_key "@"
+#  show_server_info
+#
+#def_key "s"
+#  stop
+#
+#def_key "p"
+#  pause
+#
+#def_key ">"
+#  next
+#
+#def_key "<"
+#  previous
+#
+#def_key "ctrl_h"
+#  jump_to_parent_directory
+#
+#def_key "ctrl_h"
+#  replay_song
+#
+#def_key "backspace"
+#  jump_to_parent_directory
+#
+#def_key "backspace"
+#  replay_song
+#
+#def_key "backspace_2"
+#  jump_to_parent_directory
+#
+#def_key "backspace_2"
+#  replay_song
+#
+#def_key "f"
+#  seek_forward
+#
+#def_key "b"
+#  seek_backward
+#
+#def_key "r"
+#  toggle_repeat
+#
+#def_key "z"
+#  toggle_random
+#
+#def_key "y"
+#  save_tag_changes
+#
+#def_key "y"
+#  start_searching
+#
+#def_key "y"
+#  toggle_single
+#
+#def_key "R"
+#  toggle_consume
+#
+#def_key "Y"
+#  toggle_replay_gain_mode
+#
+#def_key "t"
+#  toggle_add_mode
+#
+#def_key "|"
+#  toggle_mouse
+#
+#def_key "#"
+#  toggle_bitrate_visibility
+#
+#def_key "Z"
+#  shuffle
+#
+#def_key "x"
+#  toggle_crossfade
+#
+#def_key "X"
+#  set_crossfade
+#
+#def_key "u"
+#  update_database
+#
+#def_key "ctrl_v"
+#  sort_playlist
+#
+#def_key "ctrl_r"
+#  reverse_playlist
+#
+#def_key "ctrl_f"
+#  apply_filter
+#
+#def_key "/"
+#  find
+#
+#def_key "/"
+#  find_item_forward
+#
+#def_key "?"
+#  find
+#
+#def_key "?"
+#  find_item_backward
+#
+#def_key "."
+#  next_found_item
+#
+#def_key ","
+#  previous_found_item
+#
+#def_key "w"
+#  toggle_find_mode
+#
+#def_key "e"
+#  edit_song
+#
+#def_key "e"
+#  edit_library_tag
+#
+#def_key "e"
+#  edit_library_album
+#
+#def_key "e"
+#  edit_directory_name
+#
+#def_key "e"
+#  edit_playlist_name
+#
+#def_key "e"
+#  edit_lyrics
+#
+#def_key "i"
+#  show_song_info
+#
+#def_key "I"
+#  show_artist_info
+#
+#def_key "g"
+#  jump_to_position_in_song
+#
+#def_key "l"
+#  show_lyrics
+#
+#def_key "v"
+#  reverse_selection
+#
+#def_key "V"
+#  remove_selection
+#
+#def_key "B"
+#  select_album
+#
+#def_key "a"
+#  add_selected_items
+#
+#def_key "c"
+#  clear_playlist
+#
+#def_key "c"
+#  clear_main_playlist
+#
+#def_key "C"
+#  crop_playlist
+#
+#def_key "C"
+#  crop_main_playlist
+#
+#def_key "m"
+#  move_sort_order_up
+#
+#def_key "m"
+#  move_selected_items_up
+#
+#def_key "n"
+#  move_sort_order_down
+#
+#def_key "n"
+#  move_selected_items_down
+#
+#def_key "M"
+#  move_selected_items_to
+#
+#def_key "A"
+#  add
+#
+#def_key "S"
+#  save_playlist
+#
+#def_key "o"
+#  jump_to_playing_song
+#
+#def_key "G"
+#  jump_to_browser
+#
+#def_key "G"
+#  jump_to_playlist_editor
+#
+#def_key "~"
+#  jump_to_media_library
+#
+#def_key "E"
+#  jump_to_tag_editor
+#
+#def_key "U"
+#  toggle_playing_song_centering
+#
+#def_key "P"
+#  toggle_display_mode
+#
+#def_key "\\"
+#  toggle_interface
+#
+#def_key "!"
+#  toggle_separators_between_albums
+#
+#def_key "L"
+#  toggle_lyrics_fetcher
+#
+#def_key "F"
+#  toggle_fetching_lyrics_in_background
+#
+#def_key "ctrl_l"
+#  toggle_screen_lock
+#
+#def_key "`"
+#  toggle_browser_sort_mode
+#
+#def_key "`"
+#  toggle_library_tag_type
+#
+#def_key "`"
+#  refetch_lyrics
+#
+#def_key "`"
+#  refetch_artist_info
+#
+#def_key "`"
+#  add_random_items
+#
+#def_key "ctrl_p"
+#  set_selected_items_priority
+#
+#def_key "q"
+#  quit
+#

doc/keys

@@ -1,188 +0,0 @@
-#####################################################
-## this is example key configuration file, copy it ##
-## to ~/.ncmpcpp/keys and set up your preferences  ##
-#####################################################
-##
-## Tips:
-## - it's possible to bind maximum two keys to a command
-## - keys can be defined with a character or a decimal value
-## - a command can be disabled by binding it to 0
-##
-## Note: First bind of volume_up/down
-## will be used to switch between columns.
-##
-#
-#key_up = 259 'k'
-#
-#key_down = 258 'j'
-#
-#key_up_album = '['
-#
-#key_down_album = ']'
-#
-#key_up_artist = '{'
-#
-#key_down_artist = '}'
-#
-#key_page_up = 339
-#
-#key_page_down = 338
-#
-#key_home = 262
-#
-#key_end = 360
-#
-#key_space = 32
-#
-#key_enter = 10
-#
-#key_delete = 330 'd'
-#
-#key_volume_up = 261 '+'
-#
-#key_volume_down = 260 '-'
-#
-#key_prev_column = 260
-#
-#key_next_column = 261
-#
-#key_toggle_space_mode = 't'
-#
-#key_toggle_add_mode = 'T'
-#
-#key_toggle_mouse = '|'
-#
-#key_toggle_bitrate_visibility = '#'
-#
-#key_screen_switcher = 9
-#
-#key_backward_screen_switcher = 353
-#
-#key_help = '1' 265
-#
-#key_playlist = '2' 266
-#
-#key_browser = '3' 267
-#
-#key_search_engine = '4' 268
-#
-#key_media_library = '5' 269
-#
-#key_playlist_editor = '6' 270
-#
-#key_tag_editor = '7' 271
-#
-#key_outputs = '8' 272
-#
-#key_music_visualizer = '9' 273
-#
-#key_clock = '0' 274
-#
-#key_server_info = '@'
-#
-#key_stop = 's'
-#
-#key_pause = 'P'
-#
-#key_next = '>'
-#
-#key_prev = '<'
-#
-#key_replay = 263 127
-#
-#key_seek_forward = 'f'
-#
-#key_seek_backward = 'b'
-#
-#key_toggle_repeat = 'r'
-#
-#key_toggle_random = 'z'
-#
-#key_toggle_single = 'y'
-#
-#key_toggle_consume = 'R'
-#
-#key_toggle_replay_gain_mode = 'Y'
-#
-#key_shuffle = 'Z'
-#
-#key_toggle_crossfade = 'x'
-#
-#key_set_crossfade = 'X'
-#
-#key_update_db = 'u'
-#
-#key_sort_playlist = 22
-#
-#key_apply_filter = 6
-#
-#key_clear_filter = 7
-#
-#key_find_forward = '/'
-#
-#key_find_backward = '?'
-#
-#key_next_found_position = '.'
-#
-#key_prev_found_position = ','
-#
-#key_toggle_find_mode = 'w'
-#
-#key_edit_tags = 'e'
-#
-#key_go_to_position = 'g'
-#
-#key_song_info = 'i'
-#
-#key_artist_info = 'I'
-#
-#key_lyrics = 'l'
-#
-#key_reverse_selection = 'v'
-#
-#key_deselect_all = 'V'
-#
-#key_select_album = 'B'
-#
-#key_add_selected_items = 'A'
-#
-#key_clear = 'c'
-#
-#key_crop = 'C'
-#
-#key_move_song_up = 'm'
-#
-#key_move_song_down = 'n'
-#
-#key_move_to = 'M'
-#
-#key_move_before = 0
-#
-#key_move_after = 0
-#
-#key_add = 'a'
-#
-#key_save_playlist = 'S'
-#
-#key_go_to_now_playing = 'o'
-#
-#key_toggle_auto_center = 'U'
-#
-#key_toggle_display_mode = 'p'
-#
-#key_toggle_separators_in_playlist = '!'
-#
-#key_toggle_lyrics_db = 'L'
-#
-#key_toggle_fetching_lyrics_for_current_song_in_background = 'F'
-#
-#key_go_to_containing_directory = 'G'
-#
-#key_go_to_media_library = '~'
-#
-#key_go_to_parent_dir = 263 127
-#
-#key_switch_tag_type_list = '`'
-#
-#key_quit = 'q' 'Q'
-#

src/bindings.cpp

@@ -252,7 +252,7 @@ bool BindingsConfiguration::read(const std::string &file)
 	return result;
 }
 
-void BindingsConfiguration::generateDefault()
+void BindingsConfiguration::generateDefaults()
 {
 	Key k = Key::noOp;
 	if (notBound(k = stringToKey("mouse")))

src/bindings.h

@@ -113,7 +113,7 @@ struct BindingsConfiguration
 	typedef BindingsMap::const_iterator ConstBindingIterator;
 	
 	bool read(const std::string &file);
-	void generateDefault();
+	void generateDefaults();
 	
 	std::pair<BindingIterator, BindingIterator> get(const Key &k) {
 		return m_bindings.equal_range(k);

src/ncmpcpp.cpp

@@ -98,10 +98,9 @@ int main(int argc, char **argv)
 	Config.Read();
 	Config.GenerateColumns();
 	
-	if (!Bindings.read(Config.ncmpcpp_directory + "keys"))
+	if (!Bindings.read(Config.ncmpcpp_directory + "bindings"))
 		return 1;
-	
+	Bindings.generateDefaults();
-	Bindings.generateDefault();
 	
 	if (getenv("MPD_HOST"))
 		Mpd.SetHostname(getenv("MPD_HOST"));