.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "HIKARI" "1" "" "2.2.2" "hikari - Wayland Compositor"
.hy
.SH NAME
.PP
\f[B]hikari\f[R] - Wayland Compositor
.SH SYNTAX
.PP
\f[B]hikari\f[R] [-vh] [-a <executable>] [-c <config>]
.SH DESCRIPTION
.PP
\f[B]hikari\f[R] is a stacking Wayland compositor with additional tiling
capabilities, it is heavily inspired by the Calm Window manager
(cwm(1)).
Its core concepts are views, workspaces, sheets and groups.
.PP
The following options are available:
.PP
-a \f[I]<executable>\f[R] Specify autostart executable.
.PP
-c \f[I]<config>\f[R] Specify a configuration file.
.PP
-h Show this message and quit.
.PP
-v Show version and quit.
.SH CONCEPTS
.SS View
.PP
\f[I]Views\f[R] are basically the windows of a Wayland client.
Each \f[I]view\f[R] belongs to at most one sheet and can also belong to
at most one group.
A \f[I]view\f[R] can be in several states.
.IP \[bu] 2
\f[B]hidden\f[R]
.RS 2
.PP
\f[I]Hidden\f[R] \f[I]views\f[R] are not displayed on the workspace.
Hiding a \f[I]view\f[R] removes this \f[I]view\f[R] from the workspace.
.RE
.IP \[bu] 2
\f[B]tiled\f[R]
.RS 2
.PP
A \f[I]tiled\f[R] \f[I]view\f[R] is part of a layout.
They can never be \f[I]floating\f[R] or \f[I]invisible\f[R].
.RE
.IP \[bu] 2
\f[B]floating\f[R]
.RS 2
.PP
\f[I]Floating\f[R] \f[I]views\f[R] can never become part of a layout.
The floating state is indicated using a tilde in the sheet indicator.
.RE
.IP \[bu] 2
\f[B]invisible\f[R]
.RS 2
.PP
When a \f[I]view\f[R] is set into \f[I]invisible\f[R] state it will not
be displayed when switching to the containing sheet and stay hidden
until it is explicitly requested to be shown.
This can be used to keep long running \f[I]views\f[R] from cluttering
the workspace.
An \f[I]invisible\f[R] \f[I]view\f[R] can never be \f[I]tiled\f[R] and
are indicated using square brackets in the sheet indicator.
.RE
.IP \[bu] 2
\f[B]maximized\f[R] (horizontal, vertical and full)
.RS 2
.PP
Views with such a state can take up the entire horizontal and or
vertical space of a workspace.
\f[I]Tiled\f[R] \f[I]views\f[R] can also be maximized.
.RE
.IP \[bu] 2
\f[B]borrowed\f[R]
.RS 2
.PP
Borrowing happens when a workspace contains a \f[I]view\f[R] that view
that is not part of the \f[B]current sheet\f[R].
These views are called \f[I]borrowed\f[R] views and are indicated by the
sheet indicator using the string \[lq]\f[B]x\f[R] \[at]
\f[B]y\f[R]\[rq], where \f[B]x\f[R] is the sheet the \f[I]view\f[R] is a
member of and \f[B]y\f[R] is the sheet that is currently borrowing the
\f[I]view\f[R].
.RE
.IP \[bu] 2
\f[B]public\f[R]
.RS 2
.PP
\f[I]Public\f[R] views are also displayed on the lock screen, in this
case they will never accept input.
Views that display sensible information should never be marked as
\f[I]public\f[R].
The public state is indicated using an exclamation mark in the sheet
indicator.
.RE
.SS Workspace
.PP
A \f[I]workspace\f[R] is the set of views that are currently visible.
Unlike in most other Wayland compositors, \f[B]hikari\f[R] only has a
single \f[I]workspace\f[R] for each output and we only manipulate its
content using actions.
While this seems like a superficial distinction it is important to keep
in mind for some actions to make sense.
When switching to a sheet this sheet becomes the \f[B]workspace
sheet\f[R].
On startup a \f[I]workspace\f[R] sheet is \f[B]1\f[R].
Views on a \f[I]workspace\f[R] are stacked from bottom to top, where the
next view is higher up the stack and the previous view is one below.
This order can be changed by raising or lowering views individually via
actions.
Selecting a view via cycling actions automatically raises this view to
the top of the stacking order.
.PP
\f[B]hikari\f[R] provides multiple ways to \f[I]cycle\f[R] the views on
a \f[I]workspace\f[R].
Cycling is a way to navigate to a view using key bindings.
.SS Sheet
.PP
A \f[I]sheet\f[R] is a collection of views, each view can only be a
member of a single \f[I]sheet\f[R].
Switching between sheets will replace the current content of the
workspace with all the views that are a member of the selected
\f[I]sheet\f[R], this \f[I]sheet\f[R] will also become the \f[B]current
sheet\f[R].
\f[B]hikari\f[R] has 9 general purpose sheets that correspond to the
numbers \f[B]1\f[R] to \f[B]9\f[R] and a special purpose \f[I]sheet\f[R]
\f[B]0\f[R].
Views that are a member of \f[I]sheet\f[R] \f[B]0\f[R] will always be
visible but stacked below the views of the selected \f[I]sheet\f[R].
A \f[I]sheet\f[R] that contains views is called \f[B]inhabited\f[R].
.PP
When switching to a different sheet the current \f[B]current sheet\f[R]
becomes the \f[B]alternate sheet\f[R].
.SS Group
.PP
\f[I]Groups\f[R] are a bit more fine grained than sheets.
Like sheets, \f[I]groups\f[R] are a collection of views.
Unlike sheets you can have a arbitrary number of \f[I]groups\f[R] and
each \f[I]group\f[R] can have an arbitrary name.
Views from one \f[I]group\f[R] can be spread among all available sheets.
Some actions act on entire \f[I]groups\f[R] rather than individual
views.
.SS Layout
.PP
Each sheet can have at most one \f[I]layout\f[R] for tiling views.
Applying a \f[I]layout\f[R] to a sheet introduces an additional ordering
for views which is not altered by raising or lowering, which can be used
to traverse the \f[I]layout\f[R] in the expected order.
Each \f[I]layout\f[R] can be stored in one of the \f[I]layout\f[R]
register \f[B]a\f[R] to \f[B]z\f[R].
.SS View indicators
.PP
\f[I]View indicators\f[R] show information about the current view as
well as views belonging to the same group.
They outline the border of the current view as well as all view borders
belonging to the same group (obscured view borders will shine through
the obscuring view).
The focused view will also display so called \f[B]indicator bars\f[R].
Each bar holds some information, like title, sheet information, group
and its mark (if one has been set for the view).
.SS Marks
.PP
\f[I]Marks\f[R] can be used to \[lq]speed dial\[rq] views, even if they
are on a sheet other than the \f[B]current sheet\f[R] (note: such views
will become \f[B]borrowed\f[R] in the process).
\f[I]Marks\f[R] are represented by characters from \f[B]a\f[R] to
\f[B]z\f[R].
When jumping to a \f[I]mark\f[R] the view will be brought forward and
focused.
If no view is bound to a \f[I]mark\f[R] the user can specify a command
that is executed instead.
This can be used to start an application that binds itself to this
\f[I]mark\f[R].
.SS Mode
.PP
\f[B]hikari\f[R] is a modal Wayland compositor and therefore offers
several \f[I]modes\f[R] for actions like changing a views group, mark or
sheet as well a jumping to marks or grabbing input events and layout
selection.
.SH CONFIGURATION
.PP
\f[B]hikari\f[R] is configured using libucl(3) as a configuration file
format.
The configuration is located under
\f[I]$XDG_CONFIG_HOME/hikari/hikari.conf\f[R].
If this file is not found \f[B]hikari\f[R] is going to try
\f[I]hikari.conf\f[R] from the install \f[I]etc\f[R] directory.
.PP
The default configuration is going to use \f[B]$TERMINAL\f[R] as your
standard terminal application.
.PP
On startup \f[B]hikari\f[R] attempts to execute
\f[I]\[ti]/.config/hikari/autostart\f[R] to autostart applications.
.SH ACTIONS
.SS General actions
.IP \[bu] 2
\f[B]lock\f[R]
.RS 2
.PP
Lock \f[B]hikari\f[R] and turn off all outputs.
To unlock you need to enter your password and press enter.
Being able to unlock requires \f[I]hikari-unlocker\f[R] to be in the
\f[B]PATH\f[R] and running with setuid(2) root privileges (those are
required to check if the entered password is correct).
\f[I]hikari-unlocker\f[R] also needs pam.conf(5) to be aware of its
existence, therefore there must be a \f[I]hikari-unlocker\f[R] service
file in \f[I]pam.d\f[R].
.PP
The lock screen displays all views that are marked as \f[B]public\f[R]
which allows applications to provide information to the user when the
computer is locked (e.g.\ a clock).
.RE
.IP \[bu] 2
\f[B]quit\f[R]
.RS 2
.PP
Issues a quit operation to all views, allowing them to prompt their
shutdown dialog if they have any.
Issuing this operation again during shutdown will terminate
\f[B]hikari\f[R] right away.
.RE
.IP \[bu] 2
\f[B]reload\f[R]
.RS 2
.PP
Reload and apply the configuration.
.RE
.SS Group actions
.IP \[bu] 2
\f[B]group-cycle-[next|prev]\f[R]
.RS 2
.PP
Cycle to the next or previous group according to the stacking order by
cycling through the top most view of each group.
The \f[I]next\f[R] view is further up the stack and the
\f[I]previous\f[R] view is further down the stack.
Reaching each end of the stack just wraps around.
Once a view is selected it will be raised to the top of the stacking
order.
Selecting happens by releasing the modifier key.
.RE
.IP \[bu] 2
\f[B]group-cycle-view-[next|prev|first|last]\f[R]
.RS 2
.PP
Cycle through all visible views inside of a group.
Once a view is selected it will be raised to the top of the stacking
order.
Selecting happens by releasing the modifier key.
.RE
.IP \[bu] 2
\f[B]group-hide\f[R]
.RS 2
.PP
Hides all visible views of the group of the focused view.
.RE
.IP \[bu] 2
\f[B]group-lower\f[R]
.RS 2
.PP
Lowers all visible views of the group of the focused view.
.RE
.IP \[bu] 2
\f[B]group-only\f[R]
.RS 2
.PP
Hides all visible views not belonging to the group of the focused view.
.RE
.IP \[bu] 2
\f[B]group-raise\f[R]
.RS 2
.PP
Raises all visible views of the group of the focused view.
.RE
.SS Layout actions
.IP \[bu] 2
\f[B]layout-apply-[a-z]\f[R]
.RS 2
.PP
Applies the layout in the according register to the current
\f[B]workspace sheet\f[R].
If the register happens to be empty this is a no-op.
If the view that currently has focus can be tiled and is not borrowed it
will get raised to the top of the stack.
.RE
.IP \[bu] 2
\f[B]layout-cycle-view-[next|prev|first|last]\f[R]
.RS 2
.PP
Cycle to the next or previous group according to the layout order.
Once a view is selected it will be raised to the top of the stacking
order, the layout order will remain unchanged.
.RE
.IP \[bu] 2
\f[B]layout-exchange-view-[next|prev|main]\f[R]
.RS 2
.PP
Swaps the focused view with the next, previous or main view in the
layout order.
.RE
.IP \[bu] 2
\f[B]layout-reset\f[R]
.RS 2
.PP
Resets the geometry of all views in the current layout.
.RE
.IP \[bu] 2
\f[B]layout-restack-[append|prepend]\f[R]
.RS 2
.PP
Adds non-floating sheet views to an existing layout without changing
layout order of already tiled views.
If no layout is present the default layout for the current sheet is
applied.
.RE
.SS Mark actions
.IP \[bu] 2
\f[B]mark-show-[a-z]\f[R]
.RS 2
.PP
Shows the view bound to the according mark.
If no view is bound to the mark an optional command for this mark can be
executed, if none is specified this action is a no-op.
.RE
.IP \[bu] 2
\f[B]mark-switch-to-[a-z]\f[R]
.RS 2
.PP
Switches to the workspace containing the view bound to the according
mark.
If no view is bound to the mark an optional command for this mark can be
executed, if none is specified this action is a no-op.
.RE
.SS Mode actions
.IP \[bu] 2
\f[B]mode-enter-group-assign\f[R]
.RS 2
.PP
Entering \f[I]group-assign-mode\f[R] allows the user to change the group
of the currently focused view.
Groups that do no exist yet get created.
Groups that become empty get destroyed.
.RE
.IP \[bu] 2
\f[B]mode-enter-input-grab\f[R]
.RS 2
.PP
Redirect all input events directly to the focused view without the
compositor interfering.
Focus will not leave this view anymore until the mode exits or the view
closes.
To exit this mode, reissue the same key binding that started this mode.
.RE
.IP \[bu] 2
\f[B]mode-enter-layout\f[R]
.RS 2
.PP
Layout selection awaits one of the layout registers to be selected.
Valid registers range from \f[B]a\f[R] to \f[B]z\f[R] and \f[B]0\f[R] to
\f[B]9\f[R].
\f[I]ESC\f[R] cancels this mode without selecting a layout.
If the layout register happens to be empty this action is a no-op.
If the view that currently has focus can be tiled and is not borrowed it
will get raised to the top of the stack.
.RE
.IP \[bu] 2
\f[B]mode-enter-mark-assign\f[R]
.RS 2
.PP
To change the mark of a view enter mark assign mode and select a mark
between \f[B]a\f[R] and \f[B]z\f[R].
This mode turns the mark indicator bar into an input field.
The selection is finalized by pressing \f[I]Enter\f[R] or canceled by
pressing \f[I]ESC\f[R].
If a mark has already been taken the conflicting window will be
indicated.
.RE
.IP \[bu] 2
\f[B]mode-enter-mark-select\f[R]
.RS 2
.PP
Mark selection allows to bring forward a view bound to a mark by
selecting that mark.
When entering this mode \f[B]hikari\f[R] awaits the name of the mark to
be issued.
If that mark is bound to a view that view is shown, in the case that
this view is not a member of the \f[B]current sheet\f[R] it is
considered \f[B]borrowed\f[R].
If no view is bound to this mark and the mark has been configured to
execute a command when empty, this command gets executed.
.RE
.IP \[bu] 2
\f[B]mode-enter-mark-switch-select\f[R]
.RS 2
.PP
This action works just like \f[B]mode-enter-mark-select\f[R] with the
exception that is switches to the workspace of the bound view.
If the mark is not bound it stays on the same workspace.
.RE
.IP \[bu] 2
\f[B]mode-enter-move\f[R]
.RS 2
.PP
Moving around views with a pointer device is what this mode is for.
Once entered the pointer will jump to the top left corner of the focused
view and start moving the view around with the pointer.
When releasing any key this mode is canceled automatically.
.RE
.IP \[bu] 2
\f[B]mode-enter-resize\f[R]
.RS 2
.PP
Resizing around views with a pointer device is what this mode is for.
Once entered the pointer will join to the bottom right corner of the
focused view and start resizing the view with the pointer.
When releasing any key this mode is canceled automatically.
.RE
.IP \[bu] 2
\f[B]mode-enter-sheet-assign\f[R]
.RS 2
.PP
Entering this mode lets the user change the sheet of a view by pressing
the number of the target sheet.
If multiple outputs are available they can be cycled using
\f[I]TAB\f[R].
.RE
.SS Sheet actions
.IP \[bu] 2
\f[B]sheet-show-all\f[R]
.RS 2
.PP
Clears the current workspace and populates it with all views that are a
member of its current sheet.
This includes \f[B]invisible\f[R] views as well.
.RE
.IP \[bu] 2
\f[B]sheet-show-group\f[R]
.RS 2
.PP
Clears the current workspace and populates it with all views that are a
member of its current sheet and the group of the focused view.
This includes \f[B]invisible\f[R] views as well.
.RE
.IP \[bu] 2
\f[B]sheet-show-invisible\f[R]
.RS 2
.PP
Clears the current workspace and populates it with all
\f[B]invisible\f[R] views that are a member of its current sheet.
.RE
.SS View actions
.IP \[bu] 2
\f[B]view-cycle-[next|prev]\f[R]
.RS 2
.PP
Cycle through all visible views.
The \f[I]next\f[R] view is further up the stack and the
\f[I]previous\f[R] view is further down the stack.
Reaching each end of the stack just wraps around.
Once a view is selected it will be raised to the top of the stacking
order.
Selecting happens by releasing the modifier key.
.RE
.IP \[bu] 2
\f[B]view-decrease-size-[up|down|left|right]\f[R]
.RS 2
.PP
Decreases the size of the focused view by the amount of pixels set as
\f[B]step\f[R] value into the given direction
.RE
.IP \[bu] 2
\f[B]view-hide\f[R]
.RS 2
.PP
Hides the focused view.
.RE
.IP \[bu] 2
\f[B]view-increase-size-[up|down|left|right]\f[R]
.RS 2
.PP
Increases the size of the focused view by the amount of pixels set as
\f[B]step\f[R] value into the given direction
.RE
.IP \[bu] 2
\f[B]view-lower\f[R]
.RS 2
.PP
Lowers the focused view to the bottom of the stacking order.
.RE
.IP \[bu] 2
\f[B]view-move-[up|down|left|right]\f[R]
.RS 2
.PP
Moves the focused view \f[B]step\f[R] pixels into the given direction.
.RE
.IP \[bu] 2
\f[B]view-move-[center[|-left|-right]|[bottom|top]-[left|middle|right]]\f[R]
.RS 2
.PP
Moves the focused view to the given position on the output.
.RE
.IP \[bu] 2
\f[B]view-only\f[R]
.RS 2
.PP
Hides every other view except the focused one.
.RE
.IP \[bu] 2
\f[B]view-pin-to-sheet-[0-9|alternate|current]\f[R]
.RS 2
.PP
Pins the focused view to a given sheet.
If the sheet is not currently a \f[B]current sheet\f[R] or sheet
\f[B]0\f[R] the view becomes hidden.
Pinning a view to the \f[B]current sheet\f[R] makes sense for
\f[B]borrowed views\f[R] which takes this view from its original view
and pin it to the current one.
.RE
.IP \[bu] 2
\f[B]view-quit\f[R]
.RS 2
.PP
Closes the focused view.
.RE
.IP \[bu] 2
\f[B]view-raise\f[R]
.RS 2
.PP
Raises the view to the top of the stacking order.
.RE
.IP \[bu] 2
\f[B]view-reset-geometry\f[R]
.RS 2
.PP
Resetting view geometry brings a view back to its original size and
position.
This means that maximization will be undone and the view will also be
taken out of a layout if it has been a part of one before.
.RE
.IP \[bu] 2
\f[B]view-snap-[up|down|left|right]\f[R]
.RS 2
.PP
Snap the focused view into the specified direction.
Views can snap to the edge of the screen as well as to the borders of
neighboring views (in this case the \f[B]gap\f[R] setting is respected).
.RE
.IP \[bu] 2
\f[B]view-toggle-floating\f[R]
.RS 2
.PP
Toggles the floating state of the focused view.
Floating views can not be part of a layout.
If a view that is already tiled is set to floating state it will be
taken out of the layout and reset its geometry.
.RE
.IP \[bu] 2
\f[B]view-toggle-invisible\f[R]
.RS 2
.PP
Toggles the invisible state of the focused view.
A view in invisible state is not displayed if a user switches to the
sheet containing this view.
They need to be shown explicitly, either by using marks or by issuing
actions showing views in this state.
Iconified views can not be part of a layout.
If a view that is already tiled is set to invisible state it will be
taken out of the layout and reset its geometry.
.RE
.IP \[bu] 2
\f[B]view-toggle-maximize-[full|horizontal|vertical]\f[R]
.RS 2
.PP
Maximizes the focused view in the given direction.
Maximization state complement each other so maximizing a view
horizontally and then vertically adds up to a full maximization state
and so on.
.RE
.IP \[bu] 2
\f[B]view-toggle-public\f[R]
.RS 2
.PP
Toggles the public state of the focused view.
Public views are also displayed on the lock screen (note: they do not
accept any input when the screen is locked though).
These views should only contain information that should be displayed
when the screen is locked, such as clocks or the progress of a long
running process, they should never contain sensitive information.
The public state is indicated in the sheet indicator bar via
\f[B]!\f[R].
.RE
.SS VT actions
.IP \[bu] 2
\f[B]vt-switch-to-[1-9]\f[R]
.RS 2
.PP
Switches to another virtual terminal.
.RE
.SS Workspace actions
.IP \[bu] 2
\f[B]workspace-clear\f[R]
.RS 2
.PP
Clears the current workspace.
.RE
.IP \[bu] 2
\f[B]workspace-cycle-[next|prev]\f[R]
.RS 2
.PP
Cycle through available workspaces selecting the view that had focus
last.
If that view is no longer visible the first view of the \f[B]current
sheet\f[R] of that workspace is selected .
In both cases the cursor gets centered on that view.
If the \f[B]current sheet\f[R] is empty this moves the cursor into the
center of the target workspace.
.RE
.IP \[bu] 2
\f[B]workspace-show-all\f[R]
.RS 2
.PP
Clears the current workspace and populates it with all views.
This includes \f[B]invisible\f[R] views.
.RE
.IP \[bu] 2
\f[B]workspace-show-group\f[R]
.RS 2
.PP
Raises the focused view, clears the current workspace and populates it
with all views that are a member of the group of the focused view.
This includes \f[B]invisible\f[R] views.
.RE
.IP \[bu] 2
\f[B]workspace-show-invisible\f[R]
.RS 2
.PP
Clears the current workspace and populates it with all
\f[B]invisible\f[R] views that belong to that workspace.
.RE
.IP \[bu] 2
\f[B]workspace-switch-to-sheet-[0-9|alternate|current]\f[R]
.RS 2
.PP
Clears the current workspace and populates it with all views that are a
member of the specified sheet.
This action also sets the \f[B]current sheet\f[R] of the workspace to
this very sheet.
Views that are a member of sheet \f[B]0\f[R] will also be displayed on
the bottom of the stacking order.
Switching to the current sheet will reset the state of the sheet
e.g.\ hiding borrowed views, showing views that have previously been
hidden and hiding views that are in invisible state.
.RE
.IP \[bu] 2
\f[B]workspace-switch-to-sheet-[next|prev]-inhabited\f[R]
.RS 2
.PP
Switch to the next or previous sheet (excluding \f[B]00\f[R]) that
contains at least one member.
If none exists is a no-op.
This action also sets the \f[B]current sheet\f[R] of the workspace to
this sheet.
.RE
.SH USER DEFINED ACTIONS
.PP
Actions can also be user defined, this is done in the \f[I]actions\f[R]
section of the configuration file.
A user defined action consists of a name and a command that should be
run when the action has been issued.
.PP
To define an action \f[I]action-terminal\f[R] that launches sakura(1)
one needs to defined the following.
.IP
.nf
\f[C]
terminal = sakura
\f[R]
.fi
.PP
Now we can bind the newly defined \f[I]action-terminal\f[R] to a key
combination in the \f[I]bindings\f[R] section.
.SH BINDINGS
.PP
Actions can be bound to keys and mouse buttons.
The \f[I]bindings\f[R] section in the configuration file is used for
this matter.
Keys can be specified by using either key symbols or codes.
A key combination starts with a string identifying the modifiers for the
bindings.
There are 5 valid modifiers.
A valid modifier string is a combination of the following modifiers.
.IP \[bu] 2
\f[B]L\f[R] (Logo)
.IP \[bu] 2
\f[B]S\f[R] (Shift)
.IP \[bu] 2
\f[B]C\f[R] (Control)
.IP \[bu] 2
\f[B]A\f[R] (Alt)
.IP \[bu] 2
\f[B]5\f[R] (AltGR)
.PP
If we want to omit the modifier for a key binding we signal this by
using \[lq]0\[rq] instead of a modifier string.
.PP
Following the modifier string a key symbol or code can be stated.
If we are using a key symbol to identify a key combination we are using
\[lq]+\[rq] followed by the symbol in the case of a key code we are
using \[lq]-\[rq] followed by the numerical key code.
Key symbols and codes can be determined using wev(1).
.PP
Once a key combination has been identified it can be bound to an action.
.IP
.nf
\f[C]
\[dq]LS+a\[dq] = action1 # symbol binding
\[dq]LS-38\[dq] = action2 # code binding
\f[R]
.fi
.PP
The \f[I]bindings\f[R] section can contain 2 subsections
\f[I]keyboard\f[R] and \f[I]mouse\f[R] for keyboard and mouse bindings.
.PP
Valid values for mouse button names are \f[I]right\f[R],
\f[I]middle\f[R], \f[I]left\f[R], \f[I]side\f[R], \f[I]extra\f[R],
\f[I]forward\f[R], \f[I]back\f[R] and \f[I]task\f[R].
.PP
Bindings can have a dedicated \f[I]end\f[R] action that gets triggered
whenever a key is released or additional keys are pressed.
It ensures that a \f[I]begin\f[R] action definitely is followed by the
\f[I]end\f[R] action.
.IP
.nf
\f[C]
\[dq]L+t\[dq]  = {
  begin = action-push-to-talk-start
  end = action-push-to-talk-stop
}
\f[R]
.fi
.SH MARK CONFIGURATION
.PP
Marks can be used to quickly navigate to views.
They can also execute commands when they are not currently bound to a
view.
This functionality can be used to start an application that can then
take over that mark using auto configuration.
Note that the started application does not automatically take over the
mark.
.PP
To specify commands that are issued on unassigned marks one can specify
the commands associated with the mark in the \f[I]marks\f[R] section in
the configuration file.
.IP
.nf
\f[C]
marks {
  s = sakura
}
\f[R]
.fi
.SH VIEW CONFIGURATION
.PP
When an application start its views can be automatically configured by
\f[B]hikari\f[R].
Each view has a property called \f[I]id\f[R], in the \f[I]views\f[R]
section this can be used to specify certain properties you want for that
view to apply.
.IP \[bu] 2
\f[B]floating\f[R]
.RS 2
.PP
Takes a boolean to specify the view\[cq]s \f[B]floating\f[R] state on
startup.
The default value is \f[I]false\f[R].
.RE
.IP \[bu] 2
\f[B]focus\f[R]
.RS 2
.PP
Takes a boolean to specify if the view should automatically grab focus
when it appears for the first time.
This is useful for views that appear at a specified position.
The default value is \f[I]false\f[R].
.RE
.IP \[bu] 2
\f[B]group\f[R]
.RS 2
.PP
Automatically assign this view to a group (if the group does not exist
it is created automatically).
If no group is specified a group name equal to the view \f[I]id\f[R] is
chosen.
.RE
.IP \[bu] 2
\f[B]inherit\f[R]
.RS 2
.PP
Lets the user specify a list of properties which should be inherited to
child views (e.g.\ dialogs).
To inherit a property just state the name of the property as a string.
Additionally use an object to overwrite specific values if they should
differ from the parent\[cq]s configuration.
Values that are not explicitly inherited resort to their default.
If \f[B]inherit\f[R] is not specified the child view is going to use the
parent\[cq]s configuration.
.RE
.IP \[bu] 2
\f[B]invisible\f[R]
.RS 2
.PP
Takes a boolean to specify the view\[cq]s \f[B]invisible\f[R] state on
startup.
The default value is \f[I]false\f[R].
.RE
.IP \[bu] 2
\f[B]mark\f[R]
.RS 2
.PP
Assign a mark to the view.
This only takes effect if that mark is not already bound to another view
already.
.RE
.IP \[bu] 2
\f[B]position\f[R]
.RS 2
.PP
Positions a newly created view to the given coordinates.
\f[B]hikari\f[R] allows two ways to define a view position.
One way is to specify absolute position stating the \f[B]x\f[R] and
\f[B]y\f[R] coordinates as a object, the other one is by stating them as
one of the following options:
.IP \[bu] 2
\f[I]bottom-left\f[R]
.IP \[bu] 2
\f[I]bottom-middle\f[R]
.IP \[bu] 2
\f[I]bottom-right\f[R]
.IP \[bu] 2
\f[I]center\f[R]
.IP \[bu] 2
\f[I]center-left\f[R]
.IP \[bu] 2
\f[I]center-right\f[R]
.IP \[bu] 2
\f[I]top-left\f[R]
.IP \[bu] 2
\f[I]top-middle\f[R]
.IP \[bu] 2
\f[I]top-right\f[R]
.PP
This allows positioning a view relative to the output.
.RE
.IP \[bu] 2
\f[B]public\f[R]
.RS 2
.PP
Takes a boolean to specify the view\[cq]s \f[B]public\f[R] state on
startup.
The default value is \f[I]false\f[R].
.RE
.IP \[bu] 2
\f[B]sheet\f[R]
.RS 2
.PP
Takes an integer that references the sheet this view should be assigned
to.
If the \f[B]current sheet\f[R] is unequal to this sheet or \f[B]0\f[R]
this view automatically is considered to be \f[B]borrowed\f[R].
.RE
.PP
To configure views of the \f[B]systat\f[R] \f[I]id\f[R] to become a
member of the group \f[I]monitor\f[R] and automatically assign them to
sheet \f[B]0\f[R] with a given position and focus grabbing we would do
something like this.
Child views inherit the \f[B]group\f[R] and \f[B]sheet\f[R] property
while overwriting \f[B]floating\f[R] to \f[I]true\f[R], all the other
properties are set to their respective default values.
.IP
.nf
\f[C]
systat = {
  group = monitor
  sheet = 0
  position = {
    x = 1429
    y = 1077
  }
  focus = true

  inherit = [ group, sheet, { floating = true } ]
}
\f[R]
.fi
.SH LAYOUTS
.PP
\f[B]hikari\f[R] is not a tiling compositor so naturally some things
will behave a bit differently compared to traditional tiling approaches.
First and foremost, \f[B]hikari\f[R] tries to minimize operations that
will affect a lot of views at the same time e.g.\ opening a new view
will not automatically insert a view into an existing layout and resize
all of the already tiled views.
To insert a view into an existing layout the user has to issue a tiling
action.
This way opening a new view does not scramble an existing layout and the
user can actively decide when to incorporate a view into a layout.
.PP
A layout is bound to a sheet, each sheet can have at most one layout and
laying out a sheet will incorporate all of its views unless they are
\f[B]invisible\f[R] or \f[B]floating\f[R].
Resetting a layout will reset the geometry of all of the laid out views
to its original geometry (also resetting maximization).
.PP
Configuring layouts happens in the \f[I]layouts\f[R] section in the
configuration file.
Layouts are assigned to layout registers from \f[B]a\f[R] to \f[B]z\f[R]
and special layout registers \f[B]0\f[R] to \f[B]9\f[R] which correspond
to default layouts for a respective sheet.
A layout itself is a combination of splits and containers with tiling
algorithms.
.PP
Splits are used to subdivide regions of space and containers are used to
consume views and layout them according to a specific tiling algorithm.
.SS Splits
.PP
A layout subdivides the screen space using splits.
Dividing up the screen space uses a binary space partitioning approach.
One can split a region of space horizontally or vertically into to new
regions which can contain either another split or a container with a
tiling algorithm.
.PP
To split up the screen vertically into two equally sized section one has
to specify when the \f[I]left\f[R] and \f[I]right\f[R] hand side of the
split should contain.
.IP
.nf
\f[C]
{
  left = ...
  right = ...
}
\f[R]
.fi
.PP
Respectively to split horizontally you have to specify \f[I]top\f[R] and
\f[I]bottom\f[R].
.PP
Notice that the order in which you specify \f[I]left\f[R],
\f[I]right\f[R], \f[I]top\f[R] and \f[I]bottom\f[R] is important, since
it defined the orientation of the split.
The side of the split that gets specified first is the part the gets
filled first when tiling a sheet, it becomes the dominant part of the
split.
.PP
Sometimes splitting a region of space should not result in equally sized
subdivisions and the dominant part of the split should be scaled up or
down.
This can be done by specifying the \f[I]scale\f[R] attribute which can
vary between \f[B]0.1\f[R] to \f[B]0.9\f[R], if no \f[I]scale\f[R] is
specified this value defaults to \f[B]0.5\f[R].
.PP
To horizontally split a region on space where the top portion of the
split should take up 75% would be specified like so:
.IP
.nf
\f[C]
{
  scale = 0.75
  top = ...
  bottom = ...
}
\f[R]
.fi
.PP
Additionally to setting a fixed \f[I]scale\f[R] value, \f[B]hikari\f[R]
allows to specify a \f[I]scale\f[R] object with \f[I]min\f[R] and
\f[I]max\f[R] values.
This is called dynamic scaling, and it uses the size of the first view
inside the container to determine the size of the entire container.
The \f[I]min\f[R] and \f[I]max\f[R] values are used to specify possible
minimum and maximum scale values for the container.
Omitting the values for \f[I]min\f[R] or \f[I]max\f[R] sets the former
to \f[B]0.1\f[R] and the latter to \f[B]0.9\f[R].
.IP
.nf
\f[C]
{
  scale = {
    min = 0.5
    max = 0.75
  }
  left = single
  right = stack
}
\f[R]
.fi
.SS Containers
.PP
Containers consume a number of views and arrange them according to a
tiling algorithm.
There are 6 different tiling algorithms that you can assign to a
container.
.IP \[bu] 2
\f[B]empty\f[R]
.RS 2
.PP
This is one of the simplest algorithms, it does not consume any views.
This is used if a user desired to have a container of a layout to remain
empty e.g.
preventing the layout to cover up a portion of the workspace.
.RE
.IP \[bu] 2
\f[B]single\f[R]
.RS 2
.PP
Containers using the \f[B]single\f[R] layout only consume one view which
takes up the entire container.
.RE
.IP \[bu] 2
\f[B]full\f[R]
.RS 2
.PP
Each view inside of a container using this algorithm will take up the
entire size of the container.
All of the views are stacked up on top of each other.
.RE
.IP \[bu] 2
\f[B]stack\f[R]
.RS 2
.PP
The \f[B]stack\f[R] algorithm tries to give every view the container
consumes an equal amount of vertical space (excess space is given to the
first view).
The order in which stacking works is from top to bottom.
.RE
.IP \[bu] 2
\f[B]queue\f[R]
.RS 2
.PP
The \f[B]queue\f[R] algorithm tries to give every view the container
consumes an equal amount of horizontal space (excess space is given to
the first view).
The order in which stacking works is from left to right.
.RE
.IP \[bu] 2
\f[B]grid\f[R]
.RS 2
.PP
A grid tries to give each view the containers consumes an equal amount
of horizontal and vertical space (excess space is given to the first
view, and therefore first row of the grid).
If the amount of views can not be split up into equal rows and column
the last part of the grid will not be filled.
.RE
.PP
The easiest way to define a layout is by simply stating the tiling
algorithm.
Binding a fullscreen layout to the layout register \f[B]f\f[R] can be
trivially achieved.
.IP
.nf
\f[C]
f = full
\f[R]
.fi
.PP
This layout does not subdivide the screen using splits in any way.
The container takes up the entire screen space (respecting gap settings)
and uses the \f[B]full\f[R] algorithm to arrange the views.
.PP
More complex layouts might demand that the user specifies the number of
views that the container may contain up to a maximum.
This can be achieved by specifying a container object.
.PP
To define a \f[B]queue\f[R] container that contains up to 4 views one
would define it like that:
.IP
.nf
\f[C]
{
  views = 4
  layout = queue
}
\f[R]
.fi
.PP
Just stating the tiling algorithm is a short-hand for a layout object
with where \f[I]views\f[R] is set to 256.
.SH UI CONFIGURATION
.PP
Getting everything to look right is an important aspect of feeling
\[lq]at home\[rq].
\f[B]hikari\f[R] offers a couple of options to tweak visuals to the
users content.
All of these configuration options are part of the \f[I]ui\f[R] section.
.IP \[bu] 2
\f[B]border\f[R]
.RS 2
.PP
Defines the thickness of view borders in pixels.
.RE
.PP
Standard border thickness is set to \f[B]1\f[R].
.IP
.nf
\f[C]
border = 1
\f[R]
.fi
.IP \[bu] 2
\f[B]gap\f[R]
.RS 2
.PP
A gap is some extra space that is left between views when using a layout
or snapping views.
The value also specifies a pixel value.
.RE
.PP
The standard \f[B]gap\f[R] value is 5.
.IP
.nf
\f[C]
gap = 5
\f[R]
.fi
.IP \[bu] 2
\f[B]font\f[R]
.RS 2
.PP
Specifies the font that is used for indicator bars.
.RE
.PP
\f[B]hikari\f[R] uses \f[I]monospace 10\f[R] as its default font
setting.
.IP
.nf
\f[C]
font = \[dq]monospace 10\[dq]
\f[R]
.fi
.IP \[bu] 2
\f[B]step\f[R]
.RS 2
.PP
The step value defines how many pixels move and resize operations should
cover.
.RE
.PP
The standard \f[B]step\f[R] value is 100.
.IP
.nf
\f[C]
step = 100
\f[R]
.fi
.SS Colorschemes
.PP
\f[B]hikari\f[R] uses color to indicate different states of views and
their indicator bars.
By specifying a \f[I]colorscheme\f[R] section the user can control these
colors.
A colorscheme is a number of properties that can be changed
individually.
Colors are specified using hexadecimal RGB values (e.g.\ 0xE6DB74).
.IP \[bu] 2
\f[B]active\f[R]
.RS 2
.PP
Indicates view focus.
.RE
.IP \[bu] 2
\f[B]background\f[R]
.RS 2
.PP
Specifies the background color.
This will be obscured by a wallpaper
.RE
.IP \[bu] 2
\f[B]conflict\f[R]
.RS 2
.PP
Conflicts can happen when the user attempts to overwrite something (e.g.
binding a mark to a view that is already taken up by another view) or
does something illegal (e.g.\ defining a new group with a leading digit
in its name).
.RE
.IP \[bu] 2
\f[B]first\f[R]
.RS 2
.PP
Signals that the indicated view is the topmost view of a group.
.RE
.IP \[bu] 2
\f[B]foreground\f[R]
.RS 2
.PP
Font color for indicator bars.
.RE
.IP \[bu] 2
\f[B]grouped\f[R]
.RS 2
.PP
Views that belong to the same group are indicated using this color.
.RE
.IP \[bu] 2
\f[B]inactive\f[R]
.RS 2
.PP
Indicates that a view does not have focus.
.RE
.IP \[bu] 2
\f[B]insert\f[R]
.RS 2
.PP
Indicates indicator bars that are in insert mode (e.g.\ assigning a view
to a group) or views that have an input grab using
\f[I]mode-enter-input-grab\f[R].
.RE
.IP \[bu] 2
\f[B]selected\f[R]
.RS 2
.PP
This color is used to indicate that a view is selected.
.RE
.PP
These are the default settings for the \f[B]hikari\f[R] colorscheme.
.IP
.nf
\f[C]
colorscheme {
  background = 0x282C34
  foreground = 0x000000
  selected   = 0xF5E094
  grouped    = 0xFDAF53
  first      = 0xB8E673
  conflict   = 0xED6B32
  insert     = 0xE3C3FA
  active     = 0xFFFFFF
  inactive   = 0x465457
}
\f[R]
.fi
.SH INPUTS
.PP
The \f[I]inputs\f[R] section is used to configure input devices.
Device names can be determined using libinput(1).
.SS Pointers
.PP
Pointers can be configured in the \f[I]pointers\f[R] subsection.
The following options are available.
.IP \[bu] 2
\f[B]accel\f[R]
.RS 2
.PP
Sets mouse acceleration for the pointer device to a value between
\f[B]-1\f[R] and \f[B]1\f[R].
.RE
.IP \[bu] 2
\f[B]disable-while-typing\f[R]
.RS 2
.PP
Enable or disable \f[I]disable-while-typing\f[R] if available.
This setting expects a boolean value.
.RE
.IP \[bu] 2
\f[B]middle-emulation\f[R]
.RS 2
.PP
Enable or disable middle click emulation if available.
This setting expects a boolean value.
.RE
.IP \[bu] 2
\f[B]natural-scrolling\f[R]
.RS 2
.PP
Enable or disable \f[I]natural-scrolling\f[R] if available.
This setting expects a boolean value.
.RE
.IP \[bu] 2
\f[B]scroll-button\f[R]
.RS 2
.PP
Configures the pointer scroll button.
Valid values are \f[I]right\f[R], \f[I]middle\f[R], \f[I]left\f[R],
\f[I]side\f[R], \f[I]extra\f[R], \f[I]forward\f[R], \f[I]back\f[R] and
\f[I]task\f[R].
.RE
.IP \[bu] 2
\f[B]scroll-method\f[R]
.RS 2
.PP
Sets the pointers scroll method.
Valid values are \f[I]no-scroll\f[R], \f[I]on-button-down\f[R].
.RE
.IP \[bu] 2
\f[B]tap\f[R]
.RS 2
.PP
Enable or disable \f[I]tap\f[R] if available.
This setting expects a boolean value.
.RE
.IP \[bu] 2
\f[B]tap-drag\f[R]
.RS 2
.PP
Enable or disable \f[I]tap-drag\f[R] if available.
This setting expects a boolean value.
.RE
.IP \[bu] 2
\f[B]tap-drag-lock\f[R]
.RS 2
.PP
Enable or disable \f[I]tap-drag-lock\f[R] if available.
This setting expects a boolean value.
.RE
.PP
Configuring the \f[I]System mouse\f[R] input device could look like
this.
.IP
.nf
\f[C]
inputs {
  pointers {
    \[dq]System mouse\[dq] = {
      accel = 1.0
      scroll-method = on-button-down
      scroll-button = middle
    }
  }
}
\f[R]
.fi
.PP
A special name \[lq]*\[rq] is used to address all pointers.
Values defined for this pseudo pointer override unconfigured values for
any other pointer.
.SS Keyboards
.PP
\f[C]hikari\f[R] is using \f[C]xkb\f[R] to configure its keyboards via
the \f[I]keyboards\f[R] section.
\f[C]xkb\f[R] rules can be set independently or via a file using the
\f[I]xkb\f[R] attribute.
.PP
To specify rules individually one can use the following options.
Refer to xkeyboard-config(7) for possible settings.
.IP \[bu] 2
\f[B]rules\f[R]
.RS 2
.PP
Specifies the \f[C]xkb\f[R] rules.
The default value is \f[C]evdev\f[R].
.RE
.IP \[bu] 2
\f[B]model\f[R]
.RS 2
.PP
Sets the keyboard model.
.RE
.IP \[bu] 2
\f[B]layout\f[R]
.RS 2
.PP
Sets the keyboard layout.
.RE
.IP \[bu] 2
\f[B]variant\f[R]
.RS 2
.PP
Sets the keyboard variant.
.RE
.IP \[bu] 2
\f[B]options\f[R]
.RS 2
.PP
Sets keyboard options.
.RE
.PP
Additionally \f[B]hikari\f[R] can also configure key repeat using the
following attributes.
.IP \[bu] 2
\f[B]repeat-delay\f[R]
.RS 2
.PP
Takes a positive integer to specify the key repeat delay in
milliseconds.
The default value is 600.
.RE
.IP \[bu] 2
\f[B]repeat-rate\f[R]
.RS 2
.PP
Takes a positive integer to specify the key repeat rate in Hz.
The default value is 25.
.RE
.PP
Configuring the \f[I]AT keyboard\f[R] input device could look like this.
.IP
.nf
\f[C]
inputs {
  keyboards {
    \[dq]*\[dq] = {
      xkb = {
        layout = \[dq]de(nodeadkeys)\[dq]
        options = \[dq]caps:escape\[dq]
      }
      repeat-rate = 25
      repeat-delay = 600
    }
  }
}
\f[R]
.fi
.PP
A special name \[lq]*\[rq] is used to address all keyboards.
Values defined for this pseudo keyboard override unconfigured values for
any other pointer.
.PP
Keyboards can also be configured using \f[I]XKB\f[R] environment
variables.
\f[C]hikari\f[R] will automatically fall back to these settings if a
keyboard is not explicitly configured.
.IP \[bu] 2
\f[B]XKB_DEFAULT_LAYOUT\f[R]
.IP \[bu] 2
\f[B]XKB_DEFAULT_MODEL\f[R]
.IP \[bu] 2
\f[B]XKB_DEFAULT_OPTIONS\f[R]
.IP \[bu] 2
\f[B]XKB_DEFAULT_RULES\f[R]
.PP
To specify a layout set \f[B]XKB_DEFAULT_LAYOUT\f[R] to the desired
layout.
This needs to happen before starting \f[B]hikari\f[R].
.IP
.nf
\f[C]
XKB_DEFAULT_LAYOUT \[dq]de(nodeadkeys),de\[dq]
\f[R]
.fi
.SS Switches
.PP
Switches can be configured in the \f[I]switches\f[R] subsection.
A switch just takes an action and functions like a regular key binding
using the name of the switch as an identifier.
The \f[I]begin\f[R] action is triggered when turning the switch on and
\f[I]end\f[R] is triggered when turning it off.
.IP
.nf
\f[C]
inputs {
  switches {
    \[dq]Control Method Lid Switch\[dq] = lock
  }
}
\f[R]
.fi
.SH OUTPUTS
.PP
The \f[I]outputs\f[R] section allows users to define the background and
position for a output using its name.
A special name \[lq]*\[rq] is used to address all outputs.
Values defined for this pseudo output override unconfigured values for
any other output.
.PP
Backgrounds are configured via the \f[I]background\f[R] attribute which
can be either the path to the background image, or an object which
enables the user to define additional attributes for the background
image.
Background file format has to be \f[I]PNG\f[R].
.PP
When defining a \f[I]background\f[R] object the following attributes are
available.
.IP \[bu] 2
\f[B]path\f[R]
.RS 2
.PP
This attribute giving the \f[I]path\f[R] to the wallpaper image file is
mandatory.
.RE
.IP \[bu] 2
\f[B]fit\f[R]
.RS 2
.PP
Specifies how the wallpaper should be displayed.
Available options are \f[I]center\f[R], \f[I]stretch\f[R] and
\f[I]tile\f[R].
\f[I]stretch\f[R] is the default even when specifying the background
image as a string.
.RE
.PP
Configuring output \f[I]eDP-1\f[R] and \f[I]WL-1\f[R] could look like
this.
.IP
.nf
\f[C]
outputs {
  \[dq]eDP-1\[dq] = {
    background = \[dq]/path/to/wallpaper\[dq]
  }

  WL-1 = {
    background = {
      path = \[dq]/path/to/wallpaper\[dq]
      fit = center
    }
  }
}
\f[R]
.fi
.PP
Output position can be given explicitly using the \f[I]position\f[R]
attribute.
If none is given during startup \f[B]hikari\f[R] will automatically
configure the output.
.IP
.nf
\f[C]
\[dq]eDP-1\[dq] = {
  position = {
    x = 1680
    y = 0
  }
}

\[dq]HDMI-A-1\[dq] = {
  position = {
    x = 0
    y = 0
  }
}
\f[R]
.fi