home/doc/manpages/hooks.asciidoc

KAKOUNE(1)
==========

NAME
----
hooks - a

Description
-----------

Commands can be registered to be executed when certain events arise. To
register a hook use the following command:

----------------------------------------------------------------------
hook [-group <group>] <scope> <hook_name> <filtering_regex> <commands>
----------------------------------------------------------------------

*scope* can be one of *global*, *buffer* or *window* (c.f. the
'scopes' documentation page).

*command* is a string containing the commands to execute when the hook
is called.

For example to automatically use line numbering with .cc files, use the
following command:

----------------------------------------------------
hook global WinCreate .*\.cc %{ addhl number_lines }
----------------------------------------------------

if *group* is given, make this hook part of the named group. Groups are used
for removing hooks with the following command:

-----------------------
rmhooks <scope> <group>
-----------------------

A call to the command above will remove every hooks in *scope* that are part
of the given *group*.

Default hooks
-------------
*NormalIdle*::
	a certain duration has passed since last key was pressed in normal mode

*NormalBegin*::
	entering normal mode

*NormalEnd*::
	leaving normal mode

*NormalKey*::
	a key is received in normal mode, the key is used for filtering

*InsertIdle*::
	a certain duration has passed since last key was pressed in insert mode

*InsertBegin*::
	entering insert mode

*InsertEnd*::
	leaving insert mode

*InsertKey*::
	a key is received in insert mode, the key is used for filtering

*InsertChar*::
	a character is received in insert mode, the character is used for
	filtering

*InsertMove*::
	the cursor moved (without inserting) in insert mode, the key that
	triggered the move is used for filtering

*WinCreate*::
	a window was created, the filtering text is the buffer name

*WinClose*::
	a window was destroyed, the filtering text is the buffer name

*WinResize*::
	a window resized, the filtering text is *<line>.<column>*

*WinDisplay*::
	a window was bound a client, the filtering text is the buffer name

*WinSetOption*::
	an option was set in a window context, the filtering text is
	*<option_name>=<new_value>*

*BufSetOption*::
	an option was set in a buffer context, the filtering text is
	*<option_name>=<new_value>*

*BufNew*::
	a buffer for a new file has been created, filename is used for
	filtering

*BufOpen*::
	a buffer for an existing file has been created, filename is used
	for filtering

*BufCreate*::
	a buffer has been created, filename is used for filtering

*BufWritePre*::
	executed just before a buffer is written, filename is used for
	filtering

*BufWritePost*::
	executed just after a buffer is written, filename is used for filtering

*BufClose*::
	executed when a buffer is deleted, while it is still valid

*BufOpenFifo*::
	executed when a buffer opens a fifo

*BufReadFifo*::
	executed after some data has been red from a fifo and inserted in
	the buffer

*BufCloseFifo*::
	executed when a fifo buffer closes its fifo file descriptor either
	because the buffer is being deleted,
	or because the writing end has been closed

*RuntimeError*::
	an error was encountered while executing an user command the error
	message is used for filtering

*KakBegin*::
	kakoune has started, this hook is called just after reading the user
	configuration files

*KakEnd*::
	kakoune is quitting

*FocusIn*::
	on supported clients, triggered when the client gets focused. the
	filtering text is the client name

*FocusOut*::
	on supported clients, triggered when the client gets unfocused. the
	filtering text is the client name

*InsertCompletionShow*::
	Triggered when the insert completion menu gets displayed.

*InsertCompletionHide*::
	Triggered when the insert completion menu gets hidden.

When not specified, the filtering text is an empty string.