'\" t
.\"     Title: kakoune
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 11/16/2018
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH KAK_HOOKS 1 "" "" "hooks"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
hooks \- a
.SH "DESCRIPTION"
.sp
Commands can be registered to be executed when certain events arise\&. To register a hook use the following command:
.sp
.if n \{\
.RS 4
.\}
.nf
hook [\-group <group>] <scope> <hook_name> <filtering_regex> <commands>
.fi
.if n \{\
.RE
.\}
.sp
\fBscope\fR can be one of \fBglobal\fR, \fBbuffer\fR or \fBwindow\fR (c\&.f\&. the \fIscopes\fR documentation page)\&.
.sp
\fBcommand\fR is a string containing the commands to execute when the hook is called\&.
.sp
For example to automatically use line numbering with \&.cc files, use the following command:
.sp
.if n \{\
.RS 4
.\}
.nf
hook global WinCreate \&.*\e\&.cc %{ addhl number_lines }
.fi
.if n \{\
.RE
.\}
.sp
if \fBgroup\fR is given, make this hook part of the named group\&. Groups are used for removing hooks with the following command:
.sp
.if n \{\
.RS 4
.\}
.nf
rmhooks <scope> <group>
.fi
.if n \{\
.RE
.\}
.sp
A call to the command above will remove every hooks in \fBscope\fR that are part of the given \fBgroup\fR\&.
.SH "DEFAULT HOOKS"
.PP
\fBNormalIdle\fR
.RS 4
a certain duration has passed since last key was pressed in normal mode
.RE
.PP
\fBNormalBegin\fR
.RS 4
entering normal mode
.RE
.PP
\fBNormalEnd\fR
.RS 4
leaving normal mode
.RE
.PP
\fBNormalKey\fR
.RS 4
a key is received in normal mode, the key is used for filtering
.RE
.PP
\fBInsertIdle\fR
.RS 4
a certain duration has passed since last key was pressed in insert mode
.RE
.PP
\fBInsertBegin\fR
.RS 4
entering insert mode
.RE
.PP
\fBInsertEnd\fR
.RS 4
leaving insert mode
.RE
.PP
\fBInsertKey\fR
.RS 4
a key is received in insert mode, the key is used for filtering
.RE
.PP
\fBInsertChar\fR
.RS 4
a character is received in insert mode, the character is used for filtering
.RE
.PP
\fBInsertMove\fR
.RS 4
the cursor moved (without inserting) in insert mode, the key that triggered the move is used for filtering
.RE
.PP
\fBWinCreate\fR
.RS 4
a window was created, the filtering text is the buffer name
.RE
.PP
\fBWinClose\fR
.RS 4
a window was destroyed, the filtering text is the buffer name
.RE
.PP
\fBWinResize\fR
.RS 4
a window resized, the filtering text is
\fB<line>\&.<column>\fR
.RE
.PP
\fBWinDisplay\fR
.RS 4
a window was bound a client, the filtering text is the buffer name
.RE
.PP
\fBWinSetOption\fR
.RS 4
an option was set in a window context, the filtering text is
\fB<option_name>=<new_value>\fR
.RE
.PP
\fBBufSetOption\fR
.RS 4
an option was set in a buffer context, the filtering text is
\fB<option_name>=<new_value>\fR
.RE
.PP
\fBBufNew\fR
.RS 4
a buffer for a new file has been created, filename is used for filtering
.RE
.PP
\fBBufOpen\fR
.RS 4
a buffer for an existing file has been created, filename is used for filtering
.RE
.PP
\fBBufCreate\fR
.RS 4
a buffer has been created, filename is used for filtering
.RE
.PP
\fBBufWritePre\fR
.RS 4
executed just before a buffer is written, filename is used for filtering
.RE
.PP
\fBBufWritePost\fR
.RS 4
executed just after a buffer is written, filename is used for filtering
.RE
.PP
\fBBufClose\fR
.RS 4
executed when a buffer is deleted, while it is still valid
.RE
.PP
\fBBufOpenFifo\fR
.RS 4
executed when a buffer opens a fifo
.RE
.PP
\fBBufReadFifo\fR
.RS 4
executed after some data has been read from a fifo and inserted in the buffer
.RE
.PP
\fBBufCloseFifo\fR
.RS 4
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
.RE
.PP
\fBRuntimeError\fR
.RS 4
an error was encountered while executing an user command the error message is used for filtering
.RE
.PP
\fBKakBegin\fR
.RS 4
kakoune has started, this hook is called just after reading the user configuration files
.RE
.PP
\fBKakEnd\fR
.RS 4
kakoune is quitting
.RE
.PP
\fBFocusIn\fR
.RS 4
on supported clients, triggered when the client gets focused\&. the filtering text is the client name
.RE
.PP
\fBFocusOut\fR
.RS 4
on supported clients, triggered when the client gets unfocused\&. the filtering text is the client name
.RE
.PP
\fBInsertCompletionShow\fR
.RS 4
Triggered when the insert completion menu gets displayed
.RE
.PP
\fBInsertCompletionHide\fR
.RS 4
Triggered when the insert completion menu gets hidden
.RE
.sp
When not specified, the filtering text is an empty string\&. Note that some hooks will not consider underlying scopes depending on what context they are bound to be run into, e\&.g\&. the BufWritePost hook is a buffer hook, and will not consider the window scope\&.