Site Tools


bindctl

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

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)
  
bindctl.txt ยท Last modified: 2016/08/23 03:44 (external edit)