1 .\" Automatically generated by Pandoc 2.9.2.1

     2 .\"

     3 .TH "HIKARI" "1" "" "2.2.2" "hikari - Wayland Compositor"

     4 .hy

     5 .SH NAME

     6 .PP

     7 \f[B]hikari\f[R] - Wayland Compositor

     8 .SH SYNTAX

     9 .PP

    10 \f[B]hikari\f[R] [-vh] [-a <executable>] [-c <config>]

    11 .SH DESCRIPTION

    12 .PP

    13 \f[B]hikari\f[R] is a stacking Wayland compositor with additional tiling

    14 capabilities, it is heavily inspired by the Calm Window manager

    15 (cwm(1)).

    16 Its core concepts are views, workspaces, sheets and groups.

    17 .PP

    18 The following options are available:

    19 .PP

    20 -a \f[I]<executable>\f[R] Specify autostart executable.

    21 .PP

    22 -c \f[I]<config>\f[R] Specify a configuration file.

    23 .PP

    24 -h Show this message and quit.

    25 .PP

    26 -v Show version and quit.

    27 .SH CONCEPTS

    28 .SS View

    29 .PP

    30 \f[I]Views\f[R] are basically the windows of a Wayland client.

    31 Each \f[I]view\f[R] belongs to at most one sheet and can also belong to

    32 at most one group.

    33 A \f[I]view\f[R] can be in several states.

    34 .IP \[bu] 2

    35 \f[B]hidden\f[R]

    36 .RS 2

    37 .PP

    38 \f[I]Hidden\f[R] \f[I]views\f[R] are not displayed on the workspace.

    39 Hiding a \f[I]view\f[R] removes this \f[I]view\f[R] from the workspace.

    40 .RE

    41 .IP \[bu] 2

    42 \f[B]tiled\f[R]

    43 .RS 2

    44 .PP

    45 A \f[I]tiled\f[R] \f[I]view\f[R] is part of a layout.

    46 They can never be \f[I]floating\f[R] or \f[I]invisible\f[R].

    47 .RE

    48 .IP \[bu] 2

    49 \f[B]floating\f[R]

    50 .RS 2

    51 .PP

    52 \f[I]Floating\f[R] \f[I]views\f[R] can never become part of a layout.

    53 The floating state is indicated using a tilde in the sheet indicator.

    54 .RE

    55 .IP \[bu] 2

    56 \f[B]invisible\f[R]

    57 .RS 2

    58 .PP

    59 When a \f[I]view\f[R] is set into \f[I]invisible\f[R] state it will not

    60 be displayed when switching to the containing sheet and stay hidden

    61 until it is explicitly requested to be shown.

    62 This can be used to keep long running \f[I]views\f[R] from cluttering

    63 the workspace.

    64 An \f[I]invisible\f[R] \f[I]view\f[R] can never be \f[I]tiled\f[R] and

    65 are indicated using square brackets in the sheet indicator.

    66 .RE

    67 .IP \[bu] 2

    68 \f[B]maximized\f[R] (horizontal, vertical and full)

    69 .RS 2

    70 .PP

    71 Views with such a state can take up the entire horizontal and or

    72 vertical space of a workspace.

    73 \f[I]Tiled\f[R] \f[I]views\f[R] can also be maximized.

    74 .RE

    75 .IP \[bu] 2

    76 \f[B]borrowed\f[R]

    77 .RS 2

    78 .PP

    79 Borrowing happens when a workspace contains a \f[I]view\f[R] that view

    80 that is not part of the \f[B]current sheet\f[R].

    81 These views are called \f[I]borrowed\f[R] views and are indicated by the

    82 sheet indicator using the string \[lq]\f[B]x\f[R] \[at]

    83 \f[B]y\f[R]\[rq], where \f[B]x\f[R] is the sheet the \f[I]view\f[R] is a

    84 member of and \f[B]y\f[R] is the sheet that is currently borrowing the

    85 \f[I]view\f[R].

    86 .RE

    87 .IP \[bu] 2

    88 \f[B]public\f[R]

    89 .RS 2

    90 .PP

    91 \f[I]Public\f[R] views are also displayed on the lock screen, in this

    92 case they will never accept input.

    93 Views that display sensible information should never be marked as

    94 \f[I]public\f[R].

    95 The public state is indicated using an exclamation mark in the sheet

    96 indicator.

    97 .RE

    98 .SS Workspace

    99 .PP

   100 A \f[I]workspace\f[R] is the set of views that are currently visible.

   101 Unlike in most other Wayland compositors, \f[B]hikari\f[R] only has a

   102 single \f[I]workspace\f[R] for each output and we only manipulate its

   103 content using actions.

   104 While this seems like a superficial distinction it is important to keep

   105 in mind for some actions to make sense.

   106 When switching to a sheet this sheet becomes the \f[B]workspace

   107 sheet\f[R].

   108 On startup a \f[I]workspace\f[R] sheet is \f[B]1\f[R].

   109 Views on a \f[I]workspace\f[R] are stacked from bottom to top, where the

   110 next view is higher up the stack and the previous view is one below.

   111 This order can be changed by raising or lowering views individually via

   112 actions.

   113 Selecting a view via cycling actions automatically raises this view to

   114 the top of the stacking order.

   115 .PP

   116 \f[B]hikari\f[R] provides multiple ways to \f[I]cycle\f[R] the views on

   117 a \f[I]workspace\f[R].

   118 Cycling is a way to navigate to a view using key bindings.

   119 .SS Sheet

   120 .PP

   121 A \f[I]sheet\f[R] is a collection of views, each view can only be a

   122 member of a single \f[I]sheet\f[R].

   123 Switching between sheets will replace the current content of the

   124 workspace with all the views that are a member of the selected

   125 \f[I]sheet\f[R], this \f[I]sheet\f[R] will also become the \f[B]current

   126 sheet\f[R].

   127 \f[B]hikari\f[R] has 9 general purpose sheets that correspond to the

   128 numbers \f[B]1\f[R] to \f[B]9\f[R] and a special purpose \f[I]sheet\f[R]

   129 \f[B]0\f[R].

   130 Views that are a member of \f[I]sheet\f[R] \f[B]0\f[R] will always be

   131 visible but stacked below the views of the selected \f[I]sheet\f[R].

   132 A \f[I]sheet\f[R] that contains views is called \f[B]inhabited\f[R].

   133 .PP

   134 When switching to a different sheet the current \f[B]current sheet\f[R]

   135 becomes the \f[B]alternate sheet\f[R].

   136 .SS Group

   137 .PP

   138 \f[I]Groups\f[R] are a bit more fine grained than sheets.

   139 Like sheets, \f[I]groups\f[R] are a collection of views.

   140 Unlike sheets you can have a arbitrary number of \f[I]groups\f[R] and

   141 each \f[I]group\f[R] can have an arbitrary name.

   142 Views from one \f[I]group\f[R] can be spread among all available sheets.

   143 Some actions act on entire \f[I]groups\f[R] rather than individual

   144 views.

   145 .SS Layout

   146 .PP

   147 Each sheet can have at most one \f[I]layout\f[R] for tiling views.

   148 Applying a \f[I]layout\f[R] to a sheet introduces an additional ordering

   149 for views which is not altered by raising or lowering, which can be used

   150 to traverse the \f[I]layout\f[R] in the expected order.

   151 Each \f[I]layout\f[R] can be stored in one of the \f[I]layout\f[R]

   152 register \f[B]a\f[R] to \f[B]z\f[R].

   153 .SS View indicators

   154 .PP

   155 \f[I]View indicators\f[R] show information about the current view as

   156 well as views belonging to the same group.

   157 They outline the border of the current view as well as all view borders

   158 belonging to the same group (obscured view borders will shine through

   159 the obscuring view).

   160 The focused view will also display so called \f[B]indicator bars\f[R].

   161 Each bar holds some information, like title, sheet information, group

   162 and its mark (if one has been set for the view).

   163 .SS Marks

   164 .PP

   165 \f[I]Marks\f[R] can be used to \[lq]speed dial\[rq] views, even if they

   166 are on a sheet other than the \f[B]current sheet\f[R] (note: such views

   167 will become \f[B]borrowed\f[R] in the process).

   168 \f[I]Marks\f[R] are represented by characters from \f[B]a\f[R] to

   169 \f[B]z\f[R].

   170 When jumping to a \f[I]mark\f[R] the view will be brought forward and

   171 focused.

   172 If no view is bound to a \f[I]mark\f[R] the user can specify a command

   173 that is executed instead.

   174 This can be used to start an application that binds itself to this

   175 \f[I]mark\f[R].

   176 .SS Mode

   177 .PP

   178 \f[B]hikari\f[R] is a modal Wayland compositor and therefore offers

   179 several \f[I]modes\f[R] for actions like changing a views group, mark or

   180 sheet as well a jumping to marks or grabbing input events and layout

   181 selection.

   182 .SH CONFIGURATION

   183 .PP

   184 \f[B]hikari\f[R] is configured using libucl(3) as a configuration file

   185 format.

   186 The configuration is located under

   187 \f[I]$XDG_CONFIG_HOME/hikari/hikari.conf\f[R].

   188 If this file is not found \f[B]hikari\f[R] is going to try

   189 \f[I]hikari.conf\f[R] from the install \f[I]etc\f[R] directory.

   190 .PP

   191 The default configuration is going to use \f[B]$TERMINAL\f[R] as your

   192 standard terminal application.

   193 .PP

   194 On startup \f[B]hikari\f[R] attempts to execute

   195 \f[I]\[ti]/.config/hikari/autostart\f[R] to autostart applications.

   196 .SH ACTIONS

   197 .SS General actions

   198 .IP \[bu] 2

   199 \f[B]lock\f[R]

   200 .RS 2

   201 .PP

   202 Lock \f[B]hikari\f[R] and turn off all outputs.

   203 To unlock you need to enter your password and press enter.

   204 Being able to unlock requires \f[I]hikari-unlocker\f[R] to be in the

   205 \f[B]PATH\f[R] and running with setuid(2) root privileges (those are

   206 required to check if the entered password is correct).

   207 \f[I]hikari-unlocker\f[R] also needs pam.conf(5) to be aware of its

   208 existence, therefore there must be a \f[I]hikari-unlocker\f[R] service

   209 file in \f[I]pam.d\f[R].

   210 .PP

   211 The lock screen displays all views that are marked as \f[B]public\f[R]

   212 which allows applications to provide information to the user when the

   213 computer is locked (e.g.\ a clock).

   214 .RE

   215 .IP \[bu] 2

   216 \f[B]quit\f[R]

   217 .RS 2

   218 .PP

   219 Issues a quit operation to all views, allowing them to prompt their

   220 shutdown dialog if they have any.

   221 Issuing this operation again during shutdown will terminate

   222 \f[B]hikari\f[R] right away.

   223 .RE

   224 .IP \[bu] 2

   225 \f[B]reload\f[R]

   226 .RS 2

   227 .PP

   228 Reload and apply the configuration.

   229 .RE

   230 .SS Group actions

   231 .IP \[bu] 2

   232 \f[B]group-cycle-[next|prev]\f[R]

   233 .RS 2

   234 .PP

   235 Cycle to the next or previous group according to the stacking order by

   236 cycling through the top most view of each group.

   237 The \f[I]next\f[R] view is further up the stack and the

   238 \f[I]previous\f[R] view is further down the stack.

   239 Reaching each end of the stack just wraps around.

   240 Once a view is selected it will be raised to the top of the stacking

   241 order.

   242 Selecting happens by releasing the modifier key.

   243 .RE

   244 .IP \[bu] 2

   245 \f[B]group-cycle-view-[next|prev|first|last]\f[R]

   246 .RS 2

   247 .PP

   248 Cycle through all visible views inside of a group.

   249 Once a view is selected it will be raised to the top of the stacking

   250 order.

   251 Selecting happens by releasing the modifier key.

   252 .RE

   253 .IP \[bu] 2

   254 \f[B]group-hide\f[R]

   255 .RS 2

   256 .PP

   257 Hides all visible views of the group of the focused view.

   258 .RE

   259 .IP \[bu] 2

   260 \f[B]group-lower\f[R]

   261 .RS 2

   262 .PP

   263 Lowers all visible views of the group of the focused view.

   264 .RE

   265 .IP \[bu] 2

   266 \f[B]group-only\f[R]

   267 .RS 2

   268 .PP

   269 Hides all visible views not belonging to the group of the focused view.

   270 .RE

   271 .IP \[bu] 2

   272 \f[B]group-raise\f[R]

   273 .RS 2

   274 .PP

   275 Raises all visible views of the group of the focused view.

   276 .RE

   277 .SS Layout actions

   278 .IP \[bu] 2

   279 \f[B]layout-apply-[a-z]\f[R]

   280 .RS 2

   281 .PP

   282 Applies the layout in the according register to the current

   283 \f[B]workspace sheet\f[R].

   284 If the register happens to be empty this is a no-op.

   285 If the view that currently has focus can be tiled and is not borrowed it

   286 will get raised to the top of the stack.

   287 .RE

   288 .IP \[bu] 2

   289 \f[B]layout-cycle-view-[next|prev|first|last]\f[R]

   290 .RS 2

   291 .PP

   292 Cycle to the next or previous group according to the layout order.

   293 Once a view is selected it will be raised to the top of the stacking

   294 order, the layout order will remain unchanged.

   295 .RE

   296 .IP \[bu] 2

   297 \f[B]layout-exchange-view-[next|prev|main]\f[R]

   298 .RS 2

   299 .PP

   300 Swaps the focused view with the next, previous or main view in the

   301 layout order.

   302 .RE

   303 .IP \[bu] 2

   304 \f[B]layout-reset\f[R]

   305 .RS 2

   306 .PP

   307 Resets the geometry of all views in the current layout.

   308 .RE

   309 .IP \[bu] 2

   310 \f[B]layout-restack-[append|prepend]\f[R]

   311 .RS 2

   312 .PP

   313 Adds non-floating sheet views to an existing layout without changing

   314 layout order of already tiled views.

   315 If no layout is present the default layout for the current sheet is

   316 applied.

   317 .RE

   318 .SS Mark actions

   319 .IP \[bu] 2

   320 \f[B]mark-show-[a-z]\f[R]

   321 .RS 2

   322 .PP

   323 Shows the view bound to the according mark.

   324 If no view is bound to the mark an optional command for this mark can be

   325 executed, if none is specified this action is a no-op.

   326 .RE

   327 .IP \[bu] 2

   328 \f[B]mark-switch-to-[a-z]\f[R]

   329 .RS 2

   330 .PP

   331 Switches to the workspace containing the view bound to the according

   332 mark.

   333 If no view is bound to the mark an optional command for this mark can be

   334 executed, if none is specified this action is a no-op.

   335 .RE

   336 .SS Mode actions

   337 .IP \[bu] 2

   338 \f[B]mode-enter-group-assign\f[R]

   339 .RS 2

   340 .PP

   341 Entering \f[I]group-assign-mode\f[R] allows the user to change the group

   342 of the currently focused view.

   343 Groups that do no exist yet get created.

   344 Groups that become empty get destroyed.

   345 .RE

   346 .IP \[bu] 2

   347 \f[B]mode-enter-input-grab\f[R]

   348 .RS 2

   349 .PP

   350 Redirect all input events directly to the focused view without the

   351 compositor interfering.

   352 Focus will not leave this view anymore until the mode exits or the view

   353 closes.

   354 To exit this mode, reissue the same key binding that started this mode.

   355 .RE

   356 .IP \[bu] 2

   357 \f[B]mode-enter-layout\f[R]

   358 .RS 2

   359 .PP

   360 Layout selection awaits one of the layout registers to be selected.

   361 Valid registers range from \f[B]a\f[R] to \f[B]z\f[R] and \f[B]0\f[R] to

   362 \f[B]9\f[R].

   363 \f[I]ESC\f[R] cancels this mode without selecting a layout.

   364 If the layout register happens to be empty this action is a no-op.

   365 If the view that currently has focus can be tiled and is not borrowed it

   366 will get raised to the top of the stack.

   367 .RE

   368 .IP \[bu] 2

   369 \f[B]mode-enter-mark-assign\f[R]

   370 .RS 2

   371 .PP

   372 To change the mark of a view enter mark assign mode and select a mark

   373 between \f[B]a\f[R] and \f[B]z\f[R].

   374 This mode turns the mark indicator bar into an input field.

   375 The selection is finalized by pressing \f[I]Enter\f[R] or canceled by

   376 pressing \f[I]ESC\f[R].

   377 If a mark has already been taken the conflicting window will be

   378 indicated.

   379 .RE

   380 .IP \[bu] 2

   381 \f[B]mode-enter-mark-select\f[R]

   382 .RS 2

   383 .PP

   384 Mark selection allows to bring forward a view bound to a mark by

   385 selecting that mark.

   386 When entering this mode \f[B]hikari\f[R] awaits the name of the mark to

   387 be issued.

   388 If that mark is bound to a view that view is shown, in the case that

   389 this view is not a member of the \f[B]current sheet\f[R] it is

   390 considered \f[B]borrowed\f[R].

   391 If no view is bound to this mark and the mark has been configured to

   392 execute a command when empty, this command gets executed.

   393 .RE

   394 .IP \[bu] 2

   395 \f[B]mode-enter-mark-switch-select\f[R]

   396 .RS 2

   397 .PP

   398 This action works just like \f[B]mode-enter-mark-select\f[R] with the

   399 exception that is switches to the workspace of the bound view.

   400 If the mark is not bound it stays on the same workspace.

   401 .RE

   402 .IP \[bu] 2

   403 \f[B]mode-enter-move\f[R]

   404 .RS 2

   405 .PP

   406 Moving around views with a pointer device is what this mode is for.

   407 Once entered the pointer will jump to the top left corner of the focused

   408 view and start moving the view around with the pointer.

   409 When releasing any key this mode is canceled automatically.

   410 .RE

   411 .IP \[bu] 2

   412 \f[B]mode-enter-resize\f[R]

   413 .RS 2

   414 .PP

   415 Resizing around views with a pointer device is what this mode is for.

   416 Once entered the pointer will join to the bottom right corner of the

   417 focused view and start resizing the view with the pointer.

   418 When releasing any key this mode is canceled automatically.

   419 .RE

   420 .IP \[bu] 2

   421 \f[B]mode-enter-sheet-assign\f[R]

   422 .RS 2

   423 .PP

   424 Entering this mode lets the user change the sheet of a view by pressing

   425 the number of the target sheet.

   426 If multiple outputs are available they can be cycled using

   427 \f[I]TAB\f[R].

   428 .RE

   429 .SS Sheet actions

   430 .IP \[bu] 2

   431 \f[B]sheet-show-all\f[R]

   432 .RS 2

   433 .PP

   434 Clears the current workspace and populates it with all views that are a

   435 member of its current sheet.

   436 This includes \f[B]invisible\f[R] views as well.

   437 .RE

   438 .IP \[bu] 2

   439 \f[B]sheet-show-group\f[R]

   440 .RS 2

   441 .PP

   442 Clears the current workspace and populates it with all views that are a

   443 member of its current sheet and the group of the focused view.

   444 This includes \f[B]invisible\f[R] views as well.

   445 .RE

   446 .IP \[bu] 2

   447 \f[B]sheet-show-invisible\f[R]

   448 .RS 2

   449 .PP

   450 Clears the current workspace and populates it with all

   451 \f[B]invisible\f[R] views that are a member of its current sheet.

   452 .RE

   453 .SS View actions

   454 .IP \[bu] 2

   455 \f[B]view-cycle-[next|prev]\f[R]

   456 .RS 2

   457 .PP

   458 Cycle through all visible views.

   459 The \f[I]next\f[R] view is further up the stack and the

   460 \f[I]previous\f[R] view is further down the stack.

   461 Reaching each end of the stack just wraps around.

   462 Once a view is selected it will be raised to the top of the stacking

   463 order.

   464 Selecting happens by releasing the modifier key.

   465 .RE

   466 .IP \[bu] 2

   467 \f[B]view-decrease-size-[up|down|left|right]\f[R]

   468 .RS 2

   469 .PP

   470 Decreases the size of the focused view by the amount of pixels set as

   471 \f[B]step\f[R] value into the given direction

   472 .RE

   473 .IP \[bu] 2

   474 \f[B]view-hide\f[R]

   475 .RS 2

   476 .PP

   477 Hides the focused view.

   478 .RE

   479 .IP \[bu] 2

   480 \f[B]view-increase-size-[up|down|left|right]\f[R]

   481 .RS 2

   482 .PP

   483 Increases the size of the focused view by the amount of pixels set as

   484 \f[B]step\f[R] value into the given direction

   485 .RE

   486 .IP \[bu] 2

   487 \f[B]view-lower\f[R]

   488 .RS 2

   489 .PP

   490 Lowers the focused view to the bottom of the stacking order.

   491 .RE

   492 .IP \[bu] 2

   493 \f[B]view-move-[up|down|left|right]\f[R]

   494 .RS 2

   495 .PP

   496 Moves the focused view \f[B]step\f[R] pixels into the given direction.

   497 .RE

   498 .IP \[bu] 2

   499 \f[B]view-move-[center[|-left|-right]|[bottom|top]-[left|middle|right]]\f[R]

   500 .RS 2

   501 .PP

   502 Moves the focused view to the given position on the output.

   503 .RE

   504 .IP \[bu] 2

   505 \f[B]view-only\f[R]

   506 .RS 2

   507 .PP

   508 Hides every other view except the focused one.

   509 .RE

   510 .IP \[bu] 2

   511 \f[B]view-pin-to-sheet-[0-9|alternate|current]\f[R]

   512 .RS 2

   513 .PP

   514 Pins the focused view to a given sheet.

   515 If the sheet is not currently a \f[B]current sheet\f[R] or sheet

   516 \f[B]0\f[R] the view becomes hidden.

   517 Pinning a view to the \f[B]current sheet\f[R] makes sense for

   518 \f[B]borrowed views\f[R] which takes this view from its original view

   519 and pin it to the current one.

   520 .RE

   521 .IP \[bu] 2

   522 \f[B]view-quit\f[R]

   523 .RS 2

   524 .PP

   525 Closes the focused view.

   526 .RE

   527 .IP \[bu] 2

   528 \f[B]view-raise\f[R]

   529 .RS 2

   530 .PP

   531 Raises the view to the top of the stacking order.

   532 .RE

   533 .IP \[bu] 2

   534 \f[B]view-reset-geometry\f[R]

   535 .RS 2

   536 .PP

   537 Resetting view geometry brings a view back to its original size and

   538 position.

   539 This means that maximization will be undone and the view will also be

   540 taken out of a layout if it has been a part of one before.

   541 .RE

   542 .IP \[bu] 2

   543 \f[B]view-snap-[up|down|left|right]\f[R]

   544 .RS 2

   545 .PP

   546 Snap the focused view into the specified direction.

   547 Views can snap to the edge of the screen as well as to the borders of

   548 neighboring views (in this case the \f[B]gap\f[R] setting is respected).

   549 .RE

   550 .IP \[bu] 2

   551 \f[B]view-toggle-floating\f[R]

   552 .RS 2

   553 .PP

   554 Toggles the floating state of the focused view.

   555 Floating views can not be part of a layout.

   556 If a view that is already tiled is set to floating state it will be

   557 taken out of the layout and reset its geometry.

   558 .RE

   559 .IP \[bu] 2

   560 \f[B]view-toggle-invisible\f[R]

   561 .RS 2

   562 .PP

   563 Toggles the invisible state of the focused view.

   564 A view in invisible state is not displayed if a user switches to the

   565 sheet containing this view.

   566 They need to be shown explicitly, either by using marks or by issuing

   567 actions showing views in this state.

   568 Iconified views can not be part of a layout.

   569 If a view that is already tiled is set to invisible state it will be

   570 taken out of the layout and reset its geometry.

   571 .RE

   572 .IP \[bu] 2

   573 \f[B]view-toggle-maximize-[full|horizontal|vertical]\f[R]

   574 .RS 2

   575 .PP

   576 Maximizes the focused view in the given direction.

   577 Maximization state complement each other so maximizing a view

   578 horizontally and then vertically adds up to a full maximization state

   579 and so on.

   580 .RE

   581 .IP \[bu] 2

   582 \f[B]view-toggle-public\f[R]

   583 .RS 2

   584 .PP

   585 Toggles the public state of the focused view.

   586 Public views are also displayed on the lock screen (note: they do not

   587 accept any input when the screen is locked though).

   588 These views should only contain information that should be displayed

   589 when the screen is locked, such as clocks or the progress of a long

   590 running process, they should never contain sensitive information.

   591 The public state is indicated in the sheet indicator bar via

   592 \f[B]!\f[R].

   593 .RE

   594 .SS VT actions

   595 .IP \[bu] 2

   596 \f[B]vt-switch-to-[1-9]\f[R]

   597 .RS 2

   598 .PP

   599 Switches to another virtual terminal.

   600 .RE

   601 .SS Workspace actions

   602 .IP \[bu] 2

   603 \f[B]workspace-clear\f[R]

   604 .RS 2

   605 .PP

   606 Clears the current workspace.

   607 .RE

   608 .IP \[bu] 2

   609 \f[B]workspace-cycle-[next|prev]\f[R]

   610 .RS 2

   611 .PP

   612 Cycle through available workspaces selecting the view that had focus

   613 last.

   614 If that view is no longer visible the first view of the \f[B]current

   615 sheet\f[R] of that workspace is selected .

   616 In both cases the cursor gets centered on that view.

   617 If the \f[B]current sheet\f[R] is empty this moves the cursor into the

   618 center of the target workspace.

   619 .RE

   620 .IP \[bu] 2

   621 \f[B]workspace-show-all\f[R]

   622 .RS 2

   623 .PP

   624 Clears the current workspace and populates it with all views.

   625 This includes \f[B]invisible\f[R] views.

   626 .RE

   627 .IP \[bu] 2

   628 \f[B]workspace-show-group\f[R]

   629 .RS 2

   630 .PP

   631 Raises the focused view, clears the current workspace and populates it

   632 with all views that are a member of the group of the focused view.

   633 This includes \f[B]invisible\f[R] views.

   634 .RE

   635 .IP \[bu] 2

   636 \f[B]workspace-show-invisible\f[R]

   637 .RS 2

   638 .PP

   639 Clears the current workspace and populates it with all

   640 \f[B]invisible\f[R] views that belong to that workspace.

   641 .RE

   642 .IP \[bu] 2

   643 \f[B]workspace-switch-to-sheet-[0-9|alternate|current]\f[R]

   644 .RS 2

   645 .PP

   646 Clears the current workspace and populates it with all views that are a

   647 member of the specified sheet.

   648 This action also sets the \f[B]current sheet\f[R] of the workspace to

   649 this very sheet.

   650 Views that are a member of sheet \f[B]0\f[R] will also be displayed on

   651 the bottom of the stacking order.

   652 Switching to the current sheet will reset the state of the sheet

   653 e.g.\ hiding borrowed views, showing views that have previously been

   654 hidden and hiding views that are in invisible state.

   655 .RE

   656 .IP \[bu] 2

   657 \f[B]workspace-switch-to-sheet-[next|prev]-inhabited\f[R]

   658 .RS 2

   659 .PP

   660 Switch to the next or previous sheet (excluding \f[B]00\f[R]) that

   661 contains at least one member.

   662 If none exists is a no-op.

   663 This action also sets the \f[B]current sheet\f[R] of the workspace to

   664 this sheet.

   665 .RE

   666 .SH USER DEFINED ACTIONS

   667 .PP

   668 Actions can also be user defined, this is done in the \f[I]actions\f[R]

   669 section of the configuration file.

   670 A user defined action consists of a name and a command that should be

   671 run when the action has been issued.

   672 .PP

   673 To define an action \f[I]action-terminal\f[R] that launches sakura(1)

   674 one needs to defined the following.

   675 .IP

   676 .nf

   677 \f[C]

   678 terminal = sakura

   679 \f[R]

   680 .fi

   681 .PP

   682 Now we can bind the newly defined \f[I]action-terminal\f[R] to a key

   683 combination in the \f[I]bindings\f[R] section.

   684 .SH BINDINGS

   685 .PP

   686 Actions can be bound to keys and mouse buttons.

   687 The \f[I]bindings\f[R] section in the configuration file is used for

   688 this matter.

   689 Keys can be specified by using either key symbols or codes.

   690 A key combination starts with a string identifying the modifiers for the

   691 bindings.

   692 There are 5 valid modifiers.

   693 A valid modifier string is a combination of the following modifiers.

   694 .IP \[bu] 2

   695 \f[B]L\f[R] (Logo)

   696 .IP \[bu] 2

   697 \f[B]S\f[R] (Shift)

   698 .IP \[bu] 2

   699 \f[B]C\f[R] (Control)

   700 .IP \[bu] 2

   701 \f[B]A\f[R] (Alt)

   702 .IP \[bu] 2

   703 \f[B]5\f[R] (AltGR)

   704 .PP

   705 If we want to omit the modifier for a key binding we signal this by

   706 using \[lq]0\[rq] instead of a modifier string.

   707 .PP

   708 Following the modifier string a key symbol or code can be stated.

   709 If we are using a key symbol to identify a key combination we are using

   710 \[lq]+\[rq] followed by the symbol in the case of a key code we are

   711 using \[lq]-\[rq] followed by the numerical key code.

   712 Key symbols and codes can be determined using wev(1).

   713 .PP

   714 Once a key combination has been identified it can be bound to an action.

   715 .IP

   716 .nf

   717 \f[C]

   718 \[dq]LS+a\[dq] = action1 # symbol binding

   719 \[dq]LS-38\[dq] = action2 # code binding

   720 \f[R]

   721 .fi

   722 .PP

   723 The \f[I]bindings\f[R] section can contain 2 subsections

   724 \f[I]keyboard\f[R] and \f[I]mouse\f[R] for keyboard and mouse bindings.

   725 .PP

   726 Valid values for mouse button names are \f[I]right\f[R],

   727 \f[I]middle\f[R], \f[I]left\f[R], \f[I]side\f[R], \f[I]extra\f[R],

   728 \f[I]forward\f[R], \f[I]back\f[R] and \f[I]task\f[R].

   729 .PP

   730 Bindings can have a dedicated \f[I]end\f[R] action that gets triggered

   731 whenever a key is released or additional keys are pressed.

   732 It ensures that a \f[I]begin\f[R] action definitely is followed by the

   733 \f[I]end\f[R] action.

   734 .IP

   735 .nf

   736 \f[C]

   737 \[dq]L+t\[dq]  = {

   738   begin = action-push-to-talk-start

   739   end = action-push-to-talk-stop

   740 }

   741 \f[R]

   742 .fi

   743 .SH MARK CONFIGURATION

   744 .PP

   745 Marks can be used to quickly navigate to views.

   746 They can also execute commands when they are not currently bound to a

   747 view.

   748 This functionality can be used to start an application that can then

   749 take over that mark using auto configuration.

   750 Note that the started application does not automatically take over the

   751 mark.

   752 .PP

   753 To specify commands that are issued on unassigned marks one can specify

   754 the commands associated with the mark in the \f[I]marks\f[R] section in

   755 the configuration file.

   756 .IP

   757 .nf

   758 \f[C]

   759 marks {

   760   s = sakura

   761 }

   762 \f[R]

   763 .fi

   764 .SH VIEW CONFIGURATION

   765 .PP

   766 When an application start its views can be automatically configured by

   767 \f[B]hikari\f[R].

   768 Each view has a property called \f[I]id\f[R], in the \f[I]views\f[R]

   769 section this can be used to specify certain properties you want for that

   770 view to apply.

   771 .IP \[bu] 2

   772 \f[B]floating\f[R]

   773 .RS 2

   774 .PP

   775 Takes a boolean to specify the view\[cq]s \f[B]floating\f[R] state on

   776 startup.

   777 The default value is \f[I]false\f[R].

   778 .RE

   779 .IP \[bu] 2

   780 \f[B]focus\f[R]

   781 .RS 2

   782 .PP

   783 Takes a boolean to specify if the view should automatically grab focus

   784 when it appears for the first time.

   785 This is useful for views that appear at a specified position.

   786 The default value is \f[I]false\f[R].

   787 .RE

   788 .IP \[bu] 2

   789 \f[B]group\f[R]

   790 .RS 2

   791 .PP

   792 Automatically assign this view to a group (if the group does not exist

   793 it is created automatically).

   794 If no group is specified a group name equal to the view \f[I]id\f[R] is

   795 chosen.

   796 .RE

   797 .IP \[bu] 2

   798 \f[B]inherit\f[R]

   799 .RS 2

   800 .PP

   801 Lets the user specify a list of properties which should be inherited to

   802 child views (e.g.\ dialogs).

   803 To inherit a property just state the name of the property as a string.

   804 Additionally use an object to overwrite specific values if they should

   805 differ from the parent\[cq]s configuration.

   806 Values that are not explicitly inherited resort to their default.

   807 If \f[B]inherit\f[R] is not specified the child view is going to use the

   808 parent\[cq]s configuration.

   809 .RE

   810 .IP \[bu] 2

   811 \f[B]invisible\f[R]

   812 .RS 2

   813 .PP

   814 Takes a boolean to specify the view\[cq]s \f[B]invisible\f[R] state on

   815 startup.

   816 The default value is \f[I]false\f[R].

   817 .RE

   818 .IP \[bu] 2

   819 \f[B]mark\f[R]

   820 .RS 2

   821 .PP

   822 Assign a mark to the view.

   823 This only takes effect if that mark is not already bound to another view

   824 already.

   825 .RE

   826 .IP \[bu] 2

   827 \f[B]position\f[R]

   828 .RS 2

   829 .PP

   830 Positions a newly created view to the given coordinates.

   831 \f[B]hikari\f[R] allows two ways to define a view position.

   832 One way is to specify absolute position stating the \f[B]x\f[R] and

   833 \f[B]y\f[R] coordinates as a object, the other one is by stating them as

   834 one of the following options:

   835 .IP \[bu] 2

   836 \f[I]bottom-left\f[R]

   837 .IP \[bu] 2

   838 \f[I]bottom-middle\f[R]

   839 .IP \[bu] 2

   840 \f[I]bottom-right\f[R]

   841 .IP \[bu] 2

   842 \f[I]center\f[R]

   843 .IP \[bu] 2

   844 \f[I]center-left\f[R]

   845 .IP \[bu] 2

   846 \f[I]center-right\f[R]

   847 .IP \[bu] 2

   848 \f[I]top-left\f[R]

   849 .IP \[bu] 2

   850 \f[I]top-middle\f[R]

   851 .IP \[bu] 2

   852 \f[I]top-right\f[R]

   853 .PP

   854 This allows positioning a view relative to the output.

   855 .RE

   856 .IP \[bu] 2

   857 \f[B]public\f[R]

   858 .RS 2

   859 .PP

   860 Takes a boolean to specify the view\[cq]s \f[B]public\f[R] state on

   861 startup.

   862 The default value is \f[I]false\f[R].

   863 .RE

   864 .IP \[bu] 2

   865 \f[B]sheet\f[R]

   866 .RS 2

   867 .PP

   868 Takes an integer that references the sheet this view should be assigned

   869 to.

   870 If the \f[B]current sheet\f[R] is unequal to this sheet or \f[B]0\f[R]

   871 this view automatically is considered to be \f[B]borrowed\f[R].

   872 .RE

   873 .PP

   874 To configure views of the \f[B]systat\f[R] \f[I]id\f[R] to become a

   875 member of the group \f[I]monitor\f[R] and automatically assign them to

   876 sheet \f[B]0\f[R] with a given position and focus grabbing we would do

   877 something like this.

   878 Child views inherit the \f[B]group\f[R] and \f[B]sheet\f[R] property

   879 while overwriting \f[B]floating\f[R] to \f[I]true\f[R], all the other

   880 properties are set to their respective default values.

   881 .IP

   882 .nf

   883 \f[C]

   884 systat = {

   885   group = monitor

   886   sheet = 0

   887   position = {

   888     x = 1429

   889     y = 1077

   890   }

   891   focus = true

   892 

   893   inherit = [ group, sheet, { floating = true } ]

   894 }

   895 \f[R]

   896 .fi

   897 .SH LAYOUTS

   898 .PP

   899 \f[B]hikari\f[R] is not a tiling compositor so naturally some things

   900 will behave a bit differently compared to traditional tiling approaches.

   901 First and foremost, \f[B]hikari\f[R] tries to minimize operations that

   902 will affect a lot of views at the same time e.g.\ opening a new view

   903 will not automatically insert a view into an existing layout and resize

   904 all of the already tiled views.

   905 To insert a view into an existing layout the user has to issue a tiling

   906 action.

   907 This way opening a new view does not scramble an existing layout and the

   908 user can actively decide when to incorporate a view into a layout.

   909 .PP

   910 A layout is bound to a sheet, each sheet can have at most one layout and

   911 laying out a sheet will incorporate all of its views unless they are

   912 \f[B]invisible\f[R] or \f[B]floating\f[R].

   913 Resetting a layout will reset the geometry of all of the laid out views

   914 to its original geometry (also resetting maximization).

   915 .PP

   916 Configuring layouts happens in the \f[I]layouts\f[R] section in the

   917 configuration file.

   918 Layouts are assigned to layout registers from \f[B]a\f[R] to \f[B]z\f[R]

   919 and special layout registers \f[B]0\f[R] to \f[B]9\f[R] which correspond

   920 to default layouts for a respective sheet.

   921 A layout itself is a combination of splits and containers with tiling

   922 algorithms.

   923 .PP

   924 Splits are used to subdivide regions of space and containers are used to

   925 consume views and layout them according to a specific tiling algorithm.

   926 .SS Splits

   927 .PP

   928 A layout subdivides the screen space using splits.

   929 Dividing up the screen space uses a binary space partitioning approach.

   930 One can split a region of space horizontally or vertically into to new

   931 regions which can contain either another split or a container with a

   932 tiling algorithm.

   933 .PP

   934 To split up the screen vertically into two equally sized section one has

   935 to specify when the \f[I]left\f[R] and \f[I]right\f[R] hand side of the

   936 split should contain.

   937 .IP

   938 .nf

   939 \f[C]

   940 {

   941   left = ...

   942   right = ...

   943 }

   944 \f[R]

   945 .fi

   946 .PP

   947 Respectively to split horizontally you have to specify \f[I]top\f[R] and

   948 \f[I]bottom\f[R].

   949 .PP

   950 Notice that the order in which you specify \f[I]left\f[R],

   951 \f[I]right\f[R], \f[I]top\f[R] and \f[I]bottom\f[R] is important, since

   952 it defined the orientation of the split.

   953 The side of the split that gets specified first is the part the gets

   954 filled first when tiling a sheet, it becomes the dominant part of the

   955 split.

   956 .PP

   957 Sometimes splitting a region of space should not result in equally sized

   958 subdivisions and the dominant part of the split should be scaled up or

   959 down.

   960 This can be done by specifying the \f[I]scale\f[R] attribute which can

   961 vary between \f[B]0.1\f[R] to \f[B]0.9\f[R], if no \f[I]scale\f[R] is

   962 specified this value defaults to \f[B]0.5\f[R].

   963 .PP

   964 To horizontally split a region on space where the top portion of the

   965 split should take up 75% would be specified like so:

   966 .IP

   967 .nf

   968 \f[C]

   969 {

   970   scale = 0.75

   971   top = ...

   972   bottom = ...

   973 }

   974 \f[R]

   975 .fi

   976 .PP

   977 Additionally to setting a fixed \f[I]scale\f[R] value, \f[B]hikari\f[R]

   978 allows to specify a \f[I]scale\f[R] object with \f[I]min\f[R] and

   979 \f[I]max\f[R] values.

   980 This is called dynamic scaling, and it uses the size of the first view

   981 inside the container to determine the size of the entire container.

   982 The \f[I]min\f[R] and \f[I]max\f[R] values are used to specify possible

   983 minimum and maximum scale values for the container.

   984 Omitting the values for \f[I]min\f[R] or \f[I]max\f[R] sets the former

   985 to \f[B]0.1\f[R] and the latter to \f[B]0.9\f[R].

   986 .IP

   987 .nf

   988 \f[C]

   989 {

   990   scale = {

   991     min = 0.5

   992     max = 0.75

   993   }

   994   left = single

   995   right = stack

   996 }

   997 \f[R]

   998 .fi

   999 .SS Containers

  1000 .PP

  1001 Containers consume a number of views and arrange them according to a

  1002 tiling algorithm.

  1003 There are 6 different tiling algorithms that you can assign to a

  1004 container.

  1005 .IP \[bu] 2

  1006 \f[B]empty\f[R]

  1007 .RS 2

  1008 .PP

  1009 This is one of the simplest algorithms, it does not consume any views.

  1010 This is used if a user desired to have a container of a layout to remain

  1011 empty e.g.

  1012 preventing the layout to cover up a portion of the workspace.

  1013 .RE

  1014 .IP \[bu] 2

  1015 \f[B]single\f[R]

  1016 .RS 2

  1017 .PP

  1018 Containers using the \f[B]single\f[R] layout only consume one view which

  1019 takes up the entire container.

  1020 .RE

  1021 .IP \[bu] 2

  1022 \f[B]full\f[R]

  1023 .RS 2

  1024 .PP

  1025 Each view inside of a container using this algorithm will take up the

  1026 entire size of the container.

  1027 All of the views are stacked up on top of each other.

  1028 .RE

  1029 .IP \[bu] 2

  1030 \f[B]stack\f[R]

  1031 .RS 2

  1032 .PP

  1033 The \f[B]stack\f[R] algorithm tries to give every view the container

  1034 consumes an equal amount of vertical space (excess space is given to the

  1035 first view).

  1036 The order in which stacking works is from top to bottom.

  1037 .RE

  1038 .IP \[bu] 2

  1039 \f[B]queue\f[R]

  1040 .RS 2

  1041 .PP

  1042 The \f[B]queue\f[R] algorithm tries to give every view the container

  1043 consumes an equal amount of horizontal space (excess space is given to

  1044 the first view).

  1045 The order in which stacking works is from left to right.

  1046 .RE

  1047 .IP \[bu] 2

  1048 \f[B]grid\f[R]

  1049 .RS 2

  1050 .PP

  1051 A grid tries to give each view the containers consumes an equal amount

  1052 of horizontal and vertical space (excess space is given to the first

  1053 view, and therefore first row of the grid).

  1054 If the amount of views can not be split up into equal rows and column

  1055 the last part of the grid will not be filled.

  1056 .RE

  1057 .PP

  1058 The easiest way to define a layout is by simply stating the tiling

  1059 algorithm.

  1060 Binding a fullscreen layout to the layout register \f[B]f\f[R] can be

  1061 trivially achieved.

  1062 .IP

  1063 .nf

  1064 \f[C]

  1065 f = full

  1066 \f[R]

  1067 .fi

  1068 .PP

  1069 This layout does not subdivide the screen using splits in any way.

  1070 The container takes up the entire screen space (respecting gap settings)

  1071 and uses the \f[B]full\f[R] algorithm to arrange the views.

  1072 .PP

  1073 More complex layouts might demand that the user specifies the number of

  1074 views that the container may contain up to a maximum.

  1075 This can be achieved by specifying a container object.

  1076 .PP

  1077 To define a \f[B]queue\f[R] container that contains up to 4 views one

  1078 would define it like that:

  1079 .IP

  1080 .nf

  1081 \f[C]

  1082 {

  1083   views = 4

  1084   layout = queue

  1085 }

  1086 \f[R]

  1087 .fi

  1088 .PP

  1089 Just stating the tiling algorithm is a short-hand for a layout object

  1090 with where \f[I]views\f[R] is set to 256.

  1091 .SH UI CONFIGURATION

  1092 .PP

  1093 Getting everything to look right is an important aspect of feeling

  1094 \[lq]at home\[rq].

  1095 \f[B]hikari\f[R] offers a couple of options to tweak visuals to the

  1096 users content.

  1097 All of these configuration options are part of the \f[I]ui\f[R] section.

  1098 .IP \[bu] 2

  1099 \f[B]border\f[R]

  1100 .RS 2

  1101 .PP

  1102 Defines the thickness of view borders in pixels.

  1103 .RE

  1104 .PP

  1105 Standard border thickness is set to \f[B]1\f[R].

  1106 .IP

  1107 .nf

  1108 \f[C]

  1109 border = 1

  1110 \f[R]

  1111 .fi

  1112 .IP \[bu] 2

  1113 \f[B]gap\f[R]

  1114 .RS 2

  1115 .PP

  1116 A gap is some extra space that is left between views when using a layout

  1117 or snapping views.

  1118 The value also specifies a pixel value.

  1119 .RE

  1120 .PP

  1121 The standard \f[B]gap\f[R] value is 5.

  1122 .IP

  1123 .nf

  1124 \f[C]

  1125 gap = 5

  1126 \f[R]

  1127 .fi

  1128 .IP \[bu] 2

  1129 \f[B]font\f[R]

  1130 .RS 2

  1131 .PP

  1132 Specifies the font that is used for indicator bars.

  1133 .RE

  1134 .PP

  1135 \f[B]hikari\f[R] uses \f[I]monospace 10\f[R] as its default font