1HIKARI(1)                 hikari - Wayland Compositor                HIKARI(1)
2
3
4

NAME

6       hikari - Wayland Compositor
7

SYNTAX

9       hikari [-vh] [-a <executable>] [-c <config>]
10

DESCRIPTION

12       hikari is a stacking Wayland compositor with additional tiling capabil‐
13       ities, it is heavily inspired by the Calm Window manager (cwm(1)).  Its
14       core concepts are views, workspaces, sheets and groups.
15
16       The following options are available:
17
18       -a <executable> Specify autostart executable.
19
20       -c <config> Specify a configuration file.
21
22       -h Show this message and quit.
23
24       -v Show version and quit.
25

CONCEPTS

27   View
28       Views are basically the windows of a Wayland client.  Each view belongs
29       to at most one sheet and can also belong to at most one group.  A  view
30       can be in several states.
31
32hidden
33
34         Hidden  views  are not displayed on the workspace.  Hiding a view re‐
35         moves this view from the workspace.
36
37tiled
38
39         A tiled view is part of a layout.  They can never be floating or  in‐
40         visible.
41
42floating
43
44         Floating views can never become part of a layout.  The floating state
45         is indicated using a tilde in the sheet indicator.
46
47invisible
48
49         When a view is set into invisible state it will not be displayed when
50         switching to the containing sheet and stay hidden until it is explic‐
51         itly requested to be shown.  This can be used to  keep  long  running
52         views  from cluttering the workspace.  An invisible view can never be
53         tiled and are indicated using square brackets in the sheet indicator.
54
55maximized (horizontal, vertical and full)
56
57         Views with such a state can take up the entire horizontal and or ver‐
58         tical space of a workspace.  Tiled views can also be maximized.
59
60borrowed
61
62         Borrowing  happens when a workspace contains a view that view that is
63         not part of the current sheet.  These views are called borrowed views
64         and  are  indicated  by the sheet indicator using the string “x @ y”,
65         where x is the sheet the view is a member of and y is the sheet  that
66         is currently borrowing the view.
67
68public
69
70         Public views are also displayed on the lock screen, in this case they
71         will never accept input.  Views  that  display  sensible  information
72         should  never be marked as public.  The public state is indicated us‐
73         ing an exclamation mark in the sheet indicator.
74
75   Workspace
76       A workspace is the set of views that are currently visible.  Unlike  in
77       most  other Wayland compositors, hikari only has a single workspace for
78       each output and we only manipulate its content  using  actions.   While
79       this  seems  like  a superficial distinction it is important to keep in
80       mind for some actions to make sense.  When switching to  a  sheet  this
81       sheet  becomes the workspace sheet.  On startup a workspace sheet is 1.
82       Views on a workspace are stacked from bottom to  top,  where  the  next
83       view  is  higher up the stack and the previous view is one below.  This
84       order can be changed by raising or lowering views individually via  ac‐
85       tions.   Selecting a view via cycling actions automatically raises this
86       view to the top of the stacking order.
87
88       hikari provides multiple ways to cycle the views on a  workspace.   Cy‐
89       cling is a way to navigate to a view using key bindings.
90
91   Sheet
92       A  sheet  is a collection of views, each view can only be a member of a
93       single sheet.  Switching between sheets will replace the  current  con‐
94       tent  of  the workspace with all the views that are a member of the se‐
95       lected sheet, this sheet will also become the  current  sheet.   hikari
96       has  9 general purpose sheets that correspond to the numbers 1 to 9 and
97       a special purpose sheet 0.  Views that are a member of sheet 0 will al‐
98       ways  be  visible but stacked below the views of the selected sheet.  A
99       sheet that contains views is called inhabited.
100
101       When switching to a different sheet the current current  sheet  becomes
102       the alternate sheet.
103
104   Group
105       Groups  are  a  bit more fine grained than sheets.  Like sheets, groups
106       are a collection of views.  Unlike sheets you can have a arbitrary num‐
107       ber  of  groups  and each group can have an arbitrary name.  Views from
108       one group can be spread among all available sheets.  Some  actions  act
109       on entire groups rather than individual views.
110
111   Layout
112       Each  sheet  can  have at most one layout for tiling views.  Applying a
113       layout to a sheet introduces an additional ordering for views which  is
114       not  altered  by raising or lowering, which can be used to traverse the
115       layout in the expected order.  Each layout can be stored in one of  the
116       layout register a to z.
117
118   View indicators
119       View  indicators  show  information  about  the current view as well as
120       views belonging to the same group.  They outline the border of the cur‐
121       rent  view as well as all view borders belonging to the same group (ob‐
122       scured view borders will shine through the obscuring  view).   The  fo‐
123       cused  view will also display so called indicator bars.  Each bar holds
124       some information, like title, sheet information, group and its mark (if
125       one has been set for the view).
126
127   Marks
128       Marks  can  be  used to “speed dial” views, even if they are on a sheet
129       other than the current sheet (note: such views will become borrowed  in
130       the  process).   Marks are represented by characters from a to z.  When
131       jumping to a mark the view will be brought forward and focused.  If  no
132       view is bound to a mark the user can specify a command that is executed
133       instead.  This can be used to start an application that binds itself to
134       this mark.
135
136   Mode
137       hikari is a modal Wayland compositor and therefore offers several modes
138       for actions like changing a views group, mark or sheet as well a  jump‐
139       ing to marks or grabbing input events and layout selection.
140

CONFIGURATION

142       hikari  is  configured  using libucl(3) as a configuration file format.
143       The configuration is located under $XDG_CONFIG_HOME/hikari/hikari.conf.
144       If  this  file is not found hikari is going to try hikari.conf from the
145       install etc directory.
146
147       The default configuration is going to use $TERMINAL  as  your  standard
148       terminal application.
149
150       On startup hikari attempts to execute ~/.config/hikari/autostart to au‐
151       tostart applications.
152
153   Environment Variables
154       hikari supports the use of environment variables in its string  values.
155       Occurrences of ${VARIABLE} or $VARIABLE inside a string will be substi‐
156       tuted with the value of an environment variable named VARIABLE.  If  no
157       such environment variable exists, no substituation takes place.
158
159       You  can use double dollar signs to escape variables: $${VARIABLE} will
160       result in ${VARIABLE}, $$VARIABLE will result in $VARIABLE.
161

ACTIONS

163   General actions
164lock
165
166         Lock hikari and turn off all outputs.  To unlock you  need  to  enter
167         your password and press enter.  Being able to unlock requires hikari-
168         unlocker to be in the PATH and running with setuid(2) root privileges
169         (those  are  required  to  check if the entered password is correct).
170         hikari-unlocker also needs pam.conf(5) to be aware of its  existence,
171         therefore there must be a hikari-unlocker service file in pam.d.
172
173         The  lock  screen  displays all views that are marked as public which
174         allows applications to provide information to the user when the  com‐
175         puter is locked (e.g. a clock).
176
177quit
178
179         Issues  a  quit operation to all views, allowing them to prompt their
180         shutdown dialog if they have any.  Issuing this operation again  dur‐
181         ing shutdown will terminate hikari right away.
182
183reload
184
185         Reload and apply the configuration.
186
187   Group actions
188group-cycle-[next|prev]
189
190         Cycle  to  the next or previous group according to the stacking order
191         by cycling through the top most view of each group.  The next view is
192         further up the stack and the previous view is further down the stack.
193         Reaching each end of the stack just wraps around.  Once a view is se‐
194         lected it will be raised to the top of the stacking order.  Selecting
195         happens by releasing the modifier key.
196
197group-cycle-view-[next|prev|first|last]
198
199         Cycle through all visible views inside of a group.  Once  a  view  is
200         selected it will be raised to the top of the stacking order.  Select‐
201         ing happens by releasing the modifier key.
202
203group-hide
204
205         Hides all visible views of the group of the focused view.
206
207group-lower
208
209         Lowers all visible views of the group of the focused view.
210
211group-only
212
213         Hides all visible views not belonging to the  group  of  the  focused
214         view.
215
216group-raise
217
218         Raises all visible views of the group of the focused view.
219
220   Layout actions
221layout-apply-[a-z]
222
223         Applies the layout in the according register to the current workspace
224         sheet.  If the register happens to be empty this is a no-op.  If  the
225         view  that  currently  has  focus can be tiled and is not borrowed it
226         will get raised to the top of the stack.
227
228layout-cycle-view-[next|prev|first|last]
229
230         Cycle to the next or previous group according to  the  layout  order.
231         Once  a view is selected it will be raised to the top of the stacking
232         order, the layout order will remain unchanged.
233
234layout-exchange-view-[next|prev|main]
235
236         Swaps the focused view with the next, previous or main  view  in  the
237         layout order.
238
239layout-reset
240
241         Resets the geometry of all views in the current layout.
242
243layout-restack-[append|prepend]
244
245         Adds  non-floating sheet views to an existing layout without changing
246         layout order of already tiled views.  If no layout is present the de‐
247         fault layout for the current sheet is applied.
248
249   Mark actions
250mark-show-[a-z]
251
252         Shows  the  view bound to the according mark.  If no view is bound to
253         the mark an optional command for this mark can be executed,  if  none
254         is specified this action is a no-op.
255
256mark-switch-to-[a-z]
257
258         Switches  to the workspace containing the view bound to the according
259         mark.  If no view is bound to the mark an optional command  for  this
260         mark can be executed, if none is specified this action is a no-op.
261
262   Mode actions
263mode-enter-group-assign
264
265         Entering group-assign-mode allows the user to change the group of the
266         currently focused view.  Groups that do no  exist  yet  get  created.
267         Groups that become empty get destroyed.
268
269mode-enter-input-grab
270
271         Redirect  all  input  events directly to the focused view without the
272         compositor interfering.  Focus will not leave this view anymore until
273         the  mode  exits  or the view closes.  To exit this mode, reissue the
274         same key binding that started this mode.
275
276mode-enter-layout
277
278         Layout selection awaits one of the layout registers to  be  selected.
279         Valid  registers range from a to z and 0 to 9.  ESC cancels this mode
280         without selecting a layout.  If the layout  register  happens  to  be
281         empty  this  action is a no-op.  If the view that currently has focus
282         can be tiled and is not borrowed it will get raised to the top of the
283         stack.
284
285mode-enter-mark-assign
286
287         To change the mark of a view enter mark assign mode and select a mark
288         between a and z.  This mode turns the mark indicator bar into an  in‐
289         put  field.  The selection is finalized by pressing Enter or canceled
290         by pressing ESC.  If a mark has already been  taken  the  conflicting
291         window will be indicated.
292
293mode-enter-mark-select
294
295         Mark  selection allows to bring forward a view bound to a mark by se‐
296         lecting that mark.  When entering this mode hikari awaits the name of
297         the  mark to be issued.  If that mark is bound to a view that view is
298         shown, in the case that this view is not  a  member  of  the  current
299         sheet  it  is  considered borrowed.  If no view is bound to this mark
300         and the mark has been configured to execute  a  command  when  empty,
301         this command gets executed.
302
303mode-enter-mark-switch-select
304
305         This action works just like mode-enter-mark-select with the exception
306         that is switches to the workspace of the bound view.  If the mark  is
307         not bound it stays on the same workspace.
308
309mode-enter-move
310
311         Moving  around  views with a pointer device is what this mode is for.
312         Once entered the pointer will jump to the top left corner of the  fo‐
313         cused  view  and start moving the view around with the pointer.  When
314         releasing any key this mode is canceled automatically.
315
316mode-enter-resize
317
318         Resizing around views with a pointer device is what this mode is for.
319         Once  entered the pointer will join to the bottom right corner of the
320         focused view and start resizing the view with the pointer.  When  re‐
321         leasing any key this mode is canceled automatically.
322
323mode-enter-sheet-assign
324
325         Entering this mode lets the user change the sheet of a view by press‐
326         ing the number of the target sheet.  If multiple outputs  are  avail‐
327         able they can be cycled using TAB.
328
329   Sheet actions
330sheet-show-all
331
332         Clears the current workspace and populates it with all views that are
333         a member of its current sheet.   This  includes  invisible  views  as
334         well.
335
336sheet-show-group
337
338         Clears the current workspace and populates it with all views that are
339         a member of its current sheet and the  group  of  the  focused  view.
340         This includes invisible views as well.
341
342sheet-show-invisible
343
344         Clears  the  current  workspace  and  populates it with all invisible
345         views that are a member of its current sheet.
346
347   View actions
348view-cycle-[next|prev]
349
350         Cycle through all visible views.  The next view  is  further  up  the
351         stack and the previous view is further down the stack.  Reaching each
352         end of the stack just wraps around.  Once a view is selected it  will
353         be raised to the top of the stacking order.  Selecting happens by re‐
354         leasing the modifier key.
355
356view-decrease-size-[up|down|left|right]
357
358         Decreases the size of the focused view by the amount of pixels set as
359         step value into the given direction
360
361view-hide
362
363         Hides the focused view.
364
365view-increase-size-[up|down|left|right]
366
367         Increases the size of the focused view by the amount of pixels set as
368         step value into the given direction
369
370view-lower
371
372         Lowers the focused view to the bottom of the stacking order.
373
374view-move-[up|down|left|right]
375
376         Moves the focused view step pixels into the given direction.
377
378view-move-[center[|-left|-right]|[bottom|top]-[left|middle|right]]
379
380         Moves the focused view to the given position on the output.
381
382view-only
383
384         Hides every other view except the focused one.
385
386view-pin-to-sheet-[0-9|alternate|current]
387
388         Pins the focused view to a given sheet.  If the sheet is not current‐
389         ly  a  current  sheet  or sheet 0 the view becomes hidden.  Pinning a
390         view to the current sheet makes sense for borrowed views which  takes
391         this view from its original view and pin it to the current one.
392
393view-quit
394
395         Closes the focused view.
396
397view-raise
398
399         Raises the view to the top of the stacking order.
400
401view-reset-geometry
402
403         Resetting  view  geometry brings a view back to its original size and
404         position.  This means that maximization will be undone and  the  view
405         will  also  be taken out of a layout if it has been a part of one be‐
406         fore.
407
408view-snap-[up|down|left|right]
409
410         Snap the focused view into the specified direction.  Views  can  snap
411         to  the  edge  of the screen as well as to the borders of neighboring
412         views (in this case the gap setting is respected).
413
414view-toggle-floating
415
416         Toggles the floating state of the focused view.  Floating  views  can
417         not  be  part of a layout.  If a view that is already tiled is set to
418         floating state it will be taken out of the layout and reset its geom‐
419         etry.
420
421view-toggle-invisible
422
423         Toggles the invisible state of the focused view.  A view in invisible
424         state is not displayed if a user switches  to  the  sheet  containing
425         this  view.   They need to be shown explicitly, either by using marks
426         or by issuing actions showing views in this state.   Iconified  views
427         can  not be part of a layout.  If a view that is already tiled is set
428         to invisible state it will be taken out of the layout and  reset  its
429         geometry.
430
431view-toggle-maximize-[full|horizontal|vertical]
432
433         Maximizes  the  focused  view  in  the given direction.  Maximization
434         state complement each other so maximizing  a  view  horizontally  and
435         then vertically adds up to a full maximization state and so on.
436
437view-toggle-public
438
439         Toggles  the public state of the focused view.  Public views are also
440         displayed on the lock screen (note: they do not accept any input when
441         the screen is locked though).  These views should only contain infor‐
442         mation that should be displayed when the screen is  locked,  such  as
443         clocks  or  the progress of a long running process, they should never
444         contain sensitive information.  The public state is indicated in  the
445         sheet indicator bar via !.
446
447   VT actions
448vt-switch-to-[1-9]
449
450         Switches to another virtual terminal.
451
452   Workspace actions
453workspace-clear
454
455         Clears the current workspace.
456
457workspace-cycle-[next|prev]
458
459         Cycle  through available workspaces selecting the view that had focus
460         last.  If that view is no longer visible the first view of  the  cur‐
461         rent  sheet of that workspace is selected .  In both cases the cursor
462         gets centered on that view.  If the current sheet is empty this moves
463         the cursor into the center of the target workspace.
464
465workspace-show-all
466
467         Clears  the  current workspace and populates it with all views.  This
468         includes invisible views.
469
470workspace-show-group
471
472         Raises the focused view, clears the current workspace  and  populates
473         it with all views that are a member of the group of the focused view.
474         This includes invisible views.
475
476workspace-show-invisible
477
478         Clears the current workspace and  populates  it  with  all  invisible
479         views that belong to that workspace.
480
481workspace-switch-to-sheet-[0-9|alternate|current]
482
483         Clears the current workspace and populates it with all views that are
484         a member of the specified sheet.  This action also sets  the  current
485         sheet  of  the workspace to this very sheet.  Views that are a member
486         of sheet 0 will also be displayed on the bottom of the  stacking  or‐
487         der.   Switching  to  the  current  sheet will reset the state of the
488         sheet e.g. hiding borrowed views, showing views that have  previously
489         been hidden and hiding views that are in invisible state.
490
491workspace-switch-to-sheet-[next|prev]-inhabited
492
493         Switch  to the next or previous sheet (excluding 00) that contains at
494         least one member.  If none exists is a no-op.  This action also  sets
495         the current sheet of the workspace to this sheet.
496

USER DEFINED ACTIONS

498       Actions  can  also be user defined, this is done in the actions section
499       of the configuration file.  A user defined action consists  of  a  name
500       and a command that should be run when the action has been issued.
501
502       To  define  an action action-terminal that launches sakura(1) one needs
503       to defined the following.
504
505              terminal = sakura
506
507       Now we can bind the newly defined action-terminal to a key  combination
508       in the bindings section.
509

BINDINGS

511       Actions  can  be bound to keys and mouse buttons.  The bindings section
512       in the configuration file is used for this matter.  Keys can be  speci‐
513       fied  by  using  either key symbols or codes.  A key combination starts
514       with a string identifying the modifiers for the bindings.  There are  5
515       valid  modifiers.  A valid modifier string is a combination of the fol‐
516       lowing modifiers.
517
518L (Logo)
519
520S (Shift)
521
522C (Control)
523
524A (Alt)
525
5265 (AltGR)
527
528       If we want to omit the modifier for a key binding we signal this by us‐
529       ing “0” instead of a modifier string.
530
531       Following  the  modifier string a key symbol or code can be stated.  If
532       we are using a key symbol to identify a key combination  we  are  using
533       “+”  followed  by the symbol in the case of a key code we are using “-”
534       followed by the numerical key code.  Key symbols and codes can  be  de‐
535       termined using wev(1).
536
537       Once  a  key  combination has been identified it can be bound to an ac‐
538       tion.
539
540              "LS+a" = action1 # symbol binding
541              "LS-38" = action2 # code binding
542
543       The bindings section can contain 2 subsections keyboard and  mouse  for
544       keyboard and mouse bindings.
545
546       Valid  values for mouse button names are right, middle, left, side, ex‐
547       tra, forward, back and task.
548
549       Bindings can have a dedicated end action that gets triggered whenever a
550       key  is released or additional keys are pressed.  It ensures that a be‐
551       gin action definitely is followed by the end action.
552
553              "L+t"  = {
554                begin = action-push-to-talk-start
555                end = action-push-to-talk-stop
556              }
557

MARK CONFIGURATION

559       Marks can be used to quickly navigate to views.  They can also  execute
560       commands when they are not currently bound to a view.  This functional‐
561       ity can be used to start an application that can then  take  over  that
562       mark  using auto configuration.  Note that the started application does
563       not automatically take over the mark.
564
565       To specify commands that are issued on unassigned marks one can specify
566       the  commands associated with the mark in the marks section in the con‐
567       figuration file.
568
569              marks {
570                s = sakura
571              }
572

VIEW CONFIGURATION

574       When an application start its views can be automatically configured  by
575       hikari.   Each view has a property called id, in the views section this
576       can be used to specify certain properties you want for that view to ap‐
577       ply.
578
579floating
580
581         Takes a boolean to specify the view’s floating state on startup.  The
582         default value is false.
583
584focus
585
586         Takes a boolean to specify if the view should automatically grab  fo‐
587         cus  when  it  appears  for the first time.  This is useful for views
588         that appear at a specified position.  The default value is false.
589
590group
591
592         Automatically assign this view to a group (if the group does not  ex‐
593         ist  it  is created automatically).  If no group is specified a group
594         name equal to the view id is chosen.
595
596inherit
597
598         Lets the user specify a list of properties which should be  inherited
599         to  child views (e.g. dialogs).  To inherit a property just state the
600         name of the property as a string.   Additionally  use  an  object  to
601         overwrite  specific  values  if  they should differ from the parent’s
602         configuration.  Values that are not explicitly  inherited  resort  to
603         their  default.   If inherit is not specified the child view is going
604         to use the parent’s configuration.
605
606invisible
607
608         Takes a boolean to specify the view’s  invisible  state  on  startup.
609         The default value is false.
610
611mark
612
613         Assign  a  mark  to the view.  This only takes effect if that mark is
614         not already bound to another view already.
615
616position
617
618         Positions a newly created view to the given coordinates.  hikari  al‐
619         lows two ways to define a view position.  One way is to specify abso‐
620         lute position stating the x and y coordinates as a object, the  other
621         one is by stating them as one of the following options:
622
623bottom-left
624
625bottom-middle
626
627bottom-right
628
629center
630
631center-left
632
633center-right
634
635top-left
636
637top-middle
638
639top-right
640
641         This allows positioning a view relative to the output.
642
643public
644
645         Takes  a  boolean to specify the view’s public state on startup.  The
646         default value is false.
647
648sheet
649
650         Takes an integer that references the sheet this view  should  be  as‐
651         signed  to.   If the current sheet is unequal to this sheet or 0 this
652         view automatically is considered to be borrowed.
653
654       To configure views of the systat id to become a  member  of  the  group
655       monitor  and automatically assign them to sheet 0 with a given position
656       and focus grabbing we would do something like this.  Child views inher‐
657       it the group and sheet property while overwriting floating to true, all
658       the other properties are set to their respective default values.
659
660              systat = {
661                group = monitor
662                sheet = 0
663                position = {
664                  x = 1429
665                  y = 1077
666                }
667                focus = true
668
669                inherit = [ group, sheet, { floating = true } ]
670              }
671

LAYOUTS

673       hikari is not a tiling compositor so naturally some things will  behave
674       a bit differently compared to traditional tiling approaches.  First and
675       foremost, hikari tries to minimize operations that will affect a lot of
676       views  at  the same time e.g. opening a new view will not automatically
677       insert a view into an existing layout and resize  all  of  the  already
678       tiled  views.  To insert a view into an existing layout the user has to
679       issue a tiling action.  This way opening a new view does  not  scramble
680       an existing layout and the user can actively decide when to incorporate
681       a view into a layout.
682
683       A layout is bound to a sheet, each sheet can have at  most  one  layout
684       and  laying  out  a sheet will incorporate all of its views unless they
685       are invisible or floating.  Resetting a layout will reset the  geometry
686       of  all  of the laid out views to its original geometry (also resetting
687       maximization).
688
689       Configuring layouts happens in the layouts section in the configuration
690       file.  Layouts are assigned to layout registers from a to z and special
691       layout registers 0 to 9 which correspond to default layouts for  a  re‐
692       spective  sheet.   A  layout itself is a combination of splits and con‐
693       tainers with tiling algorithms.
694
695       Splits are used to subdivide regions of space and containers  are  used
696       to  consume  views and layout them according to a specific tiling algo‐
697       rithm.
698
699   Splits
700       A layout subdivides the screen space using  splits.   Dividing  up  the
701       screen  space uses a binary space partitioning approach.  One can split
702       a region of space horizontally or vertically into to new regions  which
703       can  contain  either  another  split or a container with a tiling algo‐
704       rithm.
705
706       To split up the screen vertically into two equally  sized  section  one
707       has  to  specify  when the left and right hand side of the split should
708       contain.
709
710              {
711                left = ...
712                right = ...
713              }
714
715       Respectively to split horizontally you have to specify top and bottom.
716
717       Notice that the order in which you specify left, right, top and  bottom
718       is  important, since it defined the orientation of the split.  The side
719       of the split that gets specified first is  the  part  the  gets  filled
720       first when tiling a sheet, it becomes the dominant part of the split.
721
722       Sometimes  splitting  a  region  of  space should not result in equally
723       sized subdivisions and the dominant part of the split should be  scaled
724       up  or  down.  This can be done by specifying the scale attribute which
725       can vary between 0.1 to 0.9, if no scale is specified  this  value  de‐
726       faults to 0.5.
727
728       To  horizontally  split  a region on space where the top portion of the
729       split should take up 75% would be specified like so:
730
731              {
732                scale = 0.75
733                top = ...
734                bottom = ...
735              }
736
737       Additionally to setting a fixed scale value, hikari allows to specify a
738       scale  object with min and max values.  This is called dynamic scaling,
739       and it uses the size of the first view inside the container  to  deter‐
740       mine the size of the entire container.  The min and max values are used
741       to specify possible minimum and maximum scale values for the container.
742       Omitting  the values for min or max sets the former to 0.1 and the lat‐
743       ter to 0.9.
744
745              {
746                scale = {
747                  min = 0.5
748                  max = 0.75
749                }
750                left = single
751                right = stack
752              }
753
754   Containers
755       Containers consume a number of views and arrange them  according  to  a
756       tiling algorithm.  There are 6 different tiling algorithms that you can
757       assign to a container.
758
759empty
760
761         This is one of the simplest  algorithms,  it  does  not  consume  any
762         views.   This is used if a user desired to have a container of a lay‐
763         out to remain empty e.g.  preventing the layout to cover up a portion
764         of the workspace.
765
766single
767
768         Containers  using the single layout only consume one view which takes
769         up the entire container.
770
771full
772
773         Each view inside of a container using this algorithm will take up the
774         entire size of the container.  All of the views are stacked up on top
775         of each other.
776
777stack
778
779         The stack algorithm tries to give every view the  container  consumes
780         an equal amount of vertical space (excess space is given to the first
781         view).  The order in which stacking works is from top to bottom.
782
783queue
784
785         The queue algorithm tries to give every view the  container  consumes
786         an  equal  amount  of  horizontal space (excess space is given to the
787         first view).  The order in which  stacking  works  is  from  left  to
788         right.
789
790grid
791
792         A  grid  tries  to  give  each  view the containers consumes an equal
793         amount of horizontal and vertical space (excess space is given to the
794         first  view,  and therefore first row of the grid).  If the amount of
795         views can not be split up into equal rows and column the last part of
796         the grid will not be filled.
797
798       The  easiest way to define a layout is by simply stating the tiling al‐
799       gorithm.  Binding a fullscreen layout to the layout register f  can  be
800       trivially achieved.
801
802              f = full
803
804       This layout does not subdivide the screen using splits in any way.  The
805       container takes up the entire screen space  (respecting  gap  settings)
806       and uses the full algorithm to arrange the views.
807
808       More complex layouts might demand that the user specifies the number of
809       views that the container may contain up to  a  maximum.   This  can  be
810       achieved by specifying a container object.
811
812       To  define  a queue container that contains up to 4 views one would de‐
813       fine it like that:
814
815              {
816                views = 4
817                layout = queue
818              }
819
820       Just stating the tiling algorithm is a short-hand for a  layout  object
821       with where views is set to 256.
822

UI CONFIGURATION

824       Getting  everything to look right is an important aspect of feeling “at
825       home”.  hikari offers a couple of options to tweak visuals to the users
826       content.   All  of  these configuration options are part of the ui sec‐
827       tion.
828
829border
830
831         Defines the thickness of view borders in pixels.
832
833       Standard border thickness is set to 1.
834
835              border = 1
836
837gap
838
839         A gap is some extra space that is left between  views  when  using  a
840         layout or snapping views.  The value also specifies a pixel value.
841
842       The standard gap value is 5.
843
844              gap = 5
845
846font
847
848         Specifies the font that is used for indicator bars.
849
850       hikari uses monospace 10 as its default font setting.
851
852              font = "monospace 10"
853
854step
855
856         The  step  value  defines  how many pixels move and resize operations
857         should cover.
858
859       The standard step value is 100.
860
861              step = 100
862
863   Colorschemes
864       hikari uses color to indicate different states of views and their indi‐
865       cator  bars.   By specifying a colorscheme section the user can control
866       these colors.  A colorscheme is a number  of  properties  that  can  be
867       changed  individually.  Colors are specified using hexadecimal RGB val‐
868       ues (e.g. 0xE6DB74).
869
870active
871
872         Indicates view focus.
873
874background
875
876         Specifies the background color.  This will be obscured by a wallpaper
877
878conflict
879
880         Conflicts can happen when the user attempts  to  overwrite  something
881         (e.g.   binding  a mark to a view that is already taken up by another
882         view) or does something illegal (e.g. defining a  new  group  with  a
883         leading digit in its name).
884
885first
886
887         Signals that the indicated view is the topmost view of a group.
888
889foreground
890
891         Font color for indicator bars.
892
893grouped
894
895         Views that belong to the same group are indicated using this color.
896
897inactive
898
899         Indicates that a view does not have focus.
900
901insert
902
903         Indicates  indicator  bars  that are in insert mode (e.g. assigning a
904         view to a group) or views that have an input grab  using  mode-enter-
905         input-grab.
906
907selected
908
909         This color is used to indicate that a view is selected.
910
911       These are the default settings for the hikari colorscheme.
912
913              colorscheme {
914                background = 0x282C34
915                foreground = 0x000000
916                selected   = 0xF5E094
917                grouped    = 0xFDAF53
918                first      = 0xB8E673
919                conflict   = 0xED6B32
920                insert     = 0xE3C3FA
921                active     = 0xFFFFFF
922                inactive   = 0x465457
923              }
924

INPUTS

926       The  inputs  section  is used to configure input devices.  Device names
927       can be determined using libinput(1).
928
929   Pointers
930       Pointers can be configured in the pointers subsection.   The  following
931       options are available.
932
933accel
934
935         Sets  mouse acceleration for the pointer device to a value between -1
936         and 1.
937
938accel-profile
939
940         Sets mouse acceleration profile for the pointer device to  the  given
941         mode.  Valid values are none, flat and adaptive.
942
943disable-while-typing
944
945         Enable  or  disable  disable-while-typing if available.  This setting
946         expects a boolean value.
947
948middle-emulation
949
950         Enable or disable middle click emulation if available.  This  setting
951         expects a boolean value.
952
953natural-scrolling
954
955         Enable  or  disable natural-scrolling if available.  This setting ex‐
956         pects a boolean value.
957
958scroll-button
959
960         Configures the pointer scroll button.  Valid values are  right,  mid‐
961         dle, left, side, extra, forward, back and task.
962
963scroll-method
964
965         Sets the pointers scroll method.  Valid values are no-scroll, on-but‐
966         ton-down.
967
968tap
969
970         Enable or disable tap if available.  This setting expects  a  boolean
971         value.
972
973tap-drag
974
975         Enable  or  disable  tap-drag  if  available.  This setting expects a
976         boolean value.
977
978tap-drag-lock
979
980         Enable or disable tap-drag-lock if available.  This setting expects a
981         boolean value.
982
983       Configuring the System mouse input device could look like this.
984
985              inputs {
986                pointers {
987                  "System mouse" = {
988                    accel = 1.0
989                    scroll-method = on-button-down
990                    scroll-button = middle
991                  }
992                }
993              }
994
995       A special name “*” is used to address all pointers.  Values defined for
996       this pseudo pointer override unconfigured values for any other pointer.
997
998   Keyboards
999       hikari is using xkb to configure its keyboards via the  keyboards  sec‐
1000       tion.   xkb  rules can be set independently or via a file using the xkb
1001       attribute.
1002
1003       To specify rules individually one can use the following options.  Refer
1004       to xkeyboard-config(7) for possible settings.
1005
1006rules
1007
1008         Specifies the xkb rules.  The default value is evdev.
1009
1010model
1011
1012         Sets the keyboard model.
1013
1014layout
1015
1016         Sets the keyboard layout.
1017
1018variant
1019
1020         Sets the keyboard variant.
1021
1022options
1023
1024         Sets keyboard options.
1025
1026       Additionally  hikari  can also configure key repeat using the following
1027       attributes.
1028
1029repeat-delay
1030
1031         Takes a positive integer to specify the key repeat delay in millisec‐
1032         onds.  The default value is 600.
1033
1034repeat-rate
1035
1036         Takes  a  positive integer to specify the key repeat rate in Hz.  The
1037         default value is 25.
1038
1039       Configuring the AT keyboard input device could look like this.
1040
1041              inputs {
1042                keyboards {
1043                  "*" = {
1044                    xkb = {
1045                      layout = "de(nodeadkeys)"
1046                      options = "caps:escape"
1047                    }
1048                    repeat-rate = 25
1049                    repeat-delay = 600
1050                  }
1051                }
1052              }
1053
1054       A special name “*” is used to address all  keyboards.   Values  defined
1055       for  this  pseudo  keyboard  override unconfigured values for any other
1056       pointer.
1057
1058       Keyboards can also  be  configured  using  XKB  environment  variables.
1059       hikari  will automatically fall back to these settings if a keyboard is
1060       not explicitly configured.
1061
1062XKB_DEFAULT_LAYOUT
1063
1064XKB_DEFAULT_MODEL
1065
1066XKB_DEFAULT_OPTIONS
1067
1068XKB_DEFAULT_RULES
1069
1070       To specify a layout set XKB_DEFAULT_LAYOUT to the desired layout.  This
1071       needs to happen before starting hikari.
1072
1073              XKB_DEFAULT_LAYOUT "de(nodeadkeys),de"
1074
1075   Switches
1076       Switches  can  be configured in the switches subsection.  A switch just
1077       takes an action and functions like a regular key binding using the name
1078       of  the  switch  as  an identifier.  The begin action is triggered when
1079       turning the switch on and end is triggered when turning it off.
1080
1081              inputs {
1082                switches {
1083                  "Control Method Lid Switch" = lock
1084                }
1085              }
1086

OUTPUTS

1088       The outputs section allows users to define the background and  position
1089       for a output using its name.  A special name “*” is used to address all
1090       outputs.  Values defined for this pseudo output  override  unconfigured
1091       values for any other output.
1092
1093       Backgrounds  are  configured  via the background attribute which can be
1094       either the path to the background image, or an object which enables the
1095       user  to  define additional attributes for the background image.  Back‐
1096       ground file format has to be PNG.
1097
1098       When defining a background object the following attributes  are  avail‐
1099       able.
1100
1101path
1102
1103         This  attribute giving the path to the wallpaper image file is manda‐
1104         tory.
1105
1106fit
1107
1108         Specifies how the wallpaper should be displayed.   Available  options
1109         are center, stretch and tile.  stretch is the default even when spec‐
1110         ifying the background image as a string.
1111
1112       Configuring output eDP-1 and WL-1 could look like this.
1113
1114              outputs {
1115                "eDP-1" = {
1116                  background = "/path/to/wallpaper"
1117                }
1118
1119                WL-1 = {
1120                  background = {
1121                    path = "/path/to/wallpaper"
1122                    fit = center
1123                  }
1124                }
1125              }
1126
1127       Output position can be given explicitly using the  position  attribute.
1128       If none is given during startup hikari will automatically configure the
1129       output.
1130
1131              "eDP-1" = {
1132                position = {
1133                  x = 1680
1134                  y = 0
1135                }
1136              }
1137
1138              "HDMI-A-1" = {
1139                position = {
1140                  x = 0
1141                  y = 0
1142                }
1143              }
1144
1145
1146
11472.3.3                                                                HIKARI(1)
Impressum