1 ##############################################################
2 ## This is the example bindings file. Copy it to ##
3 ## ~/.ncmpcpp/bindings or $XDG_CONFIG_HOME/ncmpcpp/bindings ##
4 ## and set up your preferences ##
5 ##############################################################
7 ##### General rules #####
9 ## 1) Because each action has runtime checks whether it's
10 ## ok to run it, a few actions can be bound to one key.
11 ## Actions will be bound in order given in configuration
12 ## file. When a key is pressed, first action in order
13 ## will test itself whether it's possible to run it. If
14 ## test succeeds, action is executed and other actions
15 ## bound to this key are ignored. If it doesn't, next
16 ## action in order tests itself etc.
18 ## 2) It's possible to bind more that one action at once
19 ## to a key. It can be done using the following syntax:
26 ## This creates a chain of actions. When such chain is
27 ## executed, each action in chain is run until the end of
28 ## chain is reached or one of its actions fails to execute
29 ## due to its requirements not being met. If multiple actions
30 ## and/or chains are bound to the same key, they will be
31 ## consecutively run until one of them gets fully executed.
33 ## 3) When ncmpcpp starts, bindings configuration file is
34 ## parsed and then ncmpcpp provides "missing pieces"
35 ## of default keybindings. If you want to disable some
36 ## bindings, there is a special action called 'dummy'
37 ## for that purpose. Eg. if you want to disable ability
38 ## to crop playlists, you need to put the following
39 ## into configuration file:
44 ## After that ncmpcpp will not bind any default action
47 ## 4) To let you write simple macros, the following special
48 ## actions are provided:
50 ## - push_character "character" - pushes given special
51 ## character into input queue, so it will be immediately
52 ## picked by ncmpcpp upon next call to readKey function.
53 ## Accepted values: mouse, up, down, page_up, page_down,
54 ## home, end, space, enter, insert, delete, left, right,
55 ## tab, ctrl-a, ctrl-b, ..., ctrl-z, ctrl-[, ctrl-\\,
56 ## ctrl-], ctrl-^, ctrl-_, f1, f2, ..., f12, backspace.
57 ## In addition, most of these names can be prefixed with
58 ## alt-/ctrl-/shift- to be recognized with the appropriate
61 ## - push_characters "string" - pushes given string into
64 ## - require_runnable "action" - checks whether given action
65 ## is runnable and fails if it isn't. This is especially
66 ## useful when mixed with previous two functions. Consider
67 ## the following macro definition:
70 ## push_characters "custom_filter"
73 ## If apply_filter can't be currently run, we end up with
74 ## sequence of characters in input queue which will be
75 ## treated just as we typed them. This may lead to unexpected
76 ## results (in this case 'c' will most likely clear current
77 ## playlist, 'u' will trigger database update, 's' will stop
78 ## playback etc.). To prevent such thing from happening, we
79 ## need to change above definition to this one:
82 ## require_runnable "apply_filter"
83 ## push_characters "custom_filter"
86 ## Here, first we test whether apply_filter can be actually run
87 ## before we stuff characters into input queue, so if condition
88 ## is not met, whole chain is aborted and we're fine.
90 ## - require_screen "screen" - checks whether given screen is
91 ## currently active. accepted values: browser, clock, help,
92 ## media_library, outputs, playlist, playlist_editor,
93 ## search_engine, tag_editor, visualizer, last_fm, lyrics,
94 ## selected_items_adder, server_info, song_info,
95 ## sort_playlist_dialog, tiny_tag_editor.
97 ## - run_external_command "command" - runs given command using
100 ## 5) In addition to binding to a key, you can also bind actions
101 ## or chains of actions to a command. If it comes to commands,
102 ## syntax is very similar to defining keys. Here goes example
103 ## definition of a command:
105 ## def_command "quit" [deferred]
109 ## If you execute the above command (which can be done by
110 ## invoking action execute_command, typing 'quit' and pressing
111 ## enter), ncmpcpp will stop the player and then quit. Note the
112 ## presence of word 'deferred' enclosed in square brackets. It
113 ## tells ncmpcpp to wait for confirmation (ie. pressing enter)
114 ## after you typed quit. Instead of 'deferred', 'immediate'
115 ## could be used. Then ncmpcpp will not wait for confirmation
116 ## (enter) and will execute the command the moment it sees it.
118 ## Note: while command chains are executed, internal environment
119 ## update (which includes current window refresh and mpd status
120 ## update) is not performed for performance reasons. However, it
121 ## may be desirable to do so in some situration. Therefore it's
122 ## possible to invoke by hand by performing 'update enviroment'
125 ## Note: There is a difference between:
139 ## First one binds two single actions to the same key whilst
140 ## second one defines a chain of actions. The behavior of
141 ## these two is different and is described in (1) and (2).
143 ## Note: Function def_key accepts non-ascii characters.
145 ##### List of unbound actions #####
147 ## The following actions are not bound to any key/command:
166 #def_key "shift-down"
210 # add_item_to_playlist
213 # toggle_lyrics_update_on_song_change
216 # toggle_visualization_type
219 delete_playlist_items
225 delete_stored_playlist
276 # reset_search_engine
282 # toggle_media_library_columns_mode
285 # show_playlist_editor
315 # jump_to_parent_directory
321 # jump_to_parent_directory
351 # toggle_replay_gain_mode
360 # toggle_bitrate_visibility
378 # toggle_browser_sort_mode
381 # toggle_media_library_sort_mode
408 # previous_found_item
423 # edit_directory_name
438 # jump_to_position_in_song
462 # clear_main_playlist
474 # move_selected_items_up
477 # move_sort_order_down
480 # move_selected_items_down
483 # move_selected_items_to
492 # jump_to_playing_song
498 # jump_to_playlist_editor
501 # jump_to_media_library
507 # toggle_playing_song_centering
510 # toggle_display_mode
516 # toggle_separators_between_albums
519 # toggle_lyrics_fetcher
522 # fetch_lyrics_in_background
525 # toggle_fetching_lyrics_in_background
531 # toggle_library_tag_type
540 # set_selected_items_priority
