This shows you the differences between two versions of the page.
— |
bindctl [2016/08/23 03:44] (current) |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ======Synopsis:====== | ||
+ | $__bindctl__(FUNCTION <function> <action> [<args]>) \\ | ||
+ | $__bindctl__(SEQUENCE <sequence> <action> [<args]>) \\ | ||
+ | $__bindctl__(MAP [<sequence>] [<action>]) | ||
+ | |||
+ | The bindctl function is a low level interface to the keybinding system. | ||
+ | A //FUNCTION// is a thing that can be run when you press a key. | ||
+ | A //SEQUENCE// is one or more unicode code points ("characters") that you can type sequentially, which cause a //FUNCTION// to be executed when you type them. | ||
+ | A //MAP// is a collection of SEQUENCES that begin with a common sub-sequence. | ||
+ | The client comes with a variety of built-in //FUNCTION//s, and you can create your own. | ||
+ | |||
+ | =====How to work with your own FUNCTION===== | ||
+ | In each case, the first argument is the name of your function ("keybinding") and the second | ||
+ | argument is what you want to do with that keybinding. All operations return 1 for success | ||
+ | and 0 or the empty string for failure, unless they say otherwise. | ||
+ | |||
+ | Create a new keybinding that will run the //statement// when it is invoked. | ||
+ | |||
+ | $bindctl(FUNCTION name CREATE statement) | ||
+ | |||
+ | Destroy a keybinding you created with $bindctl(). You cannot destroy built-in keybindings. | ||
+ | |||
+ | $bindctl(FUNCTION name DESTROY) | ||
+ | |||
+ | Test whether a keybinding exists -- returns 1 for yes, 0 for no. | ||
+ | |||
+ | $bindctl(FUNCTION name EXISTS) | ||
+ | |||
+ | Return the keybinding's action. If you created it with $bindctl(), it will return the statement | ||
+ | you originally provided. If it is a built-in keybinding, it will return something like "Internal <address>" | ||
+ | |||
+ | $bindctl(FUNCTION name GET) | ||
+ | |||
+ | Return the names of all keybindings whose names begin with //string// (ie, command-completion) | ||
+ | |||
+ | $bindctl(FUNCTION string MATCH) | ||
+ | |||
+ | Return the names of all keybindings that match the //pattern// (which can contain wildcards) | ||
+ | |||
+ | $bindctl(FUNCTION pattern PMATCH) | ||
+ | |||
+ | Return the package associated with the keybinding | ||
+ | |||
+ | $bindctl(FUNCTION name GETPACKAGE) | ||
+ | |||
+ | Set the package associated with the keybinding | ||
+ | |||
+ | $bindctl(FUNCTION name SETPACKAGE) | ||
+ | |||
+ | |||
+ | =====How to work with SEQUENCES===== | ||
+ | Bind the sequence "chars" to the given //FUNCTION//. Naturally, the //FUNCTION// must exist before you can bind anything to it. The //args// will be passed into the //FUNCTION// as $*. This is the same operation as /BIND chars function args. Most //function//s don't take an arg. The special //function// "NOTHING" will remove the binding. | ||
+ | |||
+ | $bindctl(SEQUENCE chars SET function args) | ||
+ | |||
+ | Return the //FUNCTION// that is bound to the sequence //chars//. If the chars are not bound to a sequence, it will return the empty string (which means "nothing") | ||
+ | |||
+ | $bindctl(SEQUENCE chars GET) | ||
+ | |||
+ | Set the package associated with the sequence //chars//. | ||
+ | |||
+ | $bindctl(SEQUENCE chars SETPACKAGE) | ||
+ | |||
+ | Get the package associated with the sequence //chars//. | ||
+ | |||
+ | $bindctl(SEQUENCE chars GETPACKAGE) | ||
+ | |||
+ | |||
+ | =====How to work with MAPs==== | ||
+ | Delete all keybindings that begin with //chars//. Be careful! | ||
+ | |||
+ | $bindctl(MAP chars CLEAR) | ||
+ | |||
+ | ======Real Example:====== | ||
+ | Create a keybinding named "GREETINGS" that outputs "Hi there!" | ||
+ | $bindctl(FUNCTION GREETINGS {echo Hi there!}) | ||
+ | |||
+ | Bind Escape-g so it runs your new keybinding | ||
+ | $bindctl(SEQUENCE ^[g GREETINGS) | ||
+ | |||
+ | Stop all this silliness | ||
+ | $bindctl(SEQUENCE ^[g NOTHING) | ||