1HIKARI(1) hikari - Wayland Compositor HIKARI(1)
2
6 hikari - Wayland Compositor
7
9 hikari [-vh] [-a <executable>] [-c <config>]
10
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 The following options are available:
17 -a <executable> Specify autostart executable.
19 -c <config> Specify a configuration file.
21 -h Show this message and quit.
23 -v Show version and quit.
25
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 • hidden
33 Hidden views are not displayed on the workspace. Hiding a view re‐
35 moves this view from the workspace.
36 • tiled
38 A tiled view is part of a layout. They can never be floating or in‐
40 visible.
41 • floating
43 Floating views can never become part of a layout. The floating state
45 is indicated using a tilde in the sheet indicator.
46 • invisible
48 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 • maximized (horizontal, vertical and full)
56 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 • borrowed
61 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 • public
69 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 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 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 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 When switching to a different sheet the current current sheet becomes
102 the alternate sheet.
103 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 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 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 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 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
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 The default configuration is going to use $TERMINAL as your standard
148 terminal application.
149 On startup hikari attempts to execute ~/.config/hikari/autostart to au‐
151 tostart applications.
152 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 You can use double dollar signs to escape variables: $${VARIABLE} will
160 result in ${VARIABLE}, $$VARIABLE will result in $VARIABLE.
161
163 General actions
164 • lock
165 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 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 • quit
178 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 • reload
184 Reload and apply the configuration.
186 Group actions
188 • group-cycle-[next|prev]
189 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 • group-cycle-view-[next|prev|first|last]
198 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 • group-hide
204 Hides all visible views of the group of the focused view.
206 • group-lower
208 Lowers all visible views of the group of the focused view.
210 • group-only
212 Hides all visible views not belonging to the group of the focused
214 view.
215 • group-raise
217 Raises all visible views of the group of the focused view.
219 Layout actions
221 • layout-apply-[a-z]
222 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 • layout-cycle-view-[next|prev|first|last]
229 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 • layout-exchange-view-[next|prev|main]
235 Swaps the focused view with the next, previous or main view in the
237 layout order.
238 • layout-reset
240 Resets the geometry of all views in the current layout.
242 • layout-restack-[append|prepend]
244 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 Mark actions
250 • mark-show-[a-z]
251 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 • mark-switch-to-[a-z]
257 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 Mode actions
263 • mode-enter-group-assign
264 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 • mode-enter-input-grab
270 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 • mode-enter-layout
277 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 • mode-enter-mark-assign
286 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 • mode-enter-mark-select
294 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 • mode-enter-mark-switch-select
304 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 • mode-enter-move
310 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 • mode-enter-resize
317 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 • mode-enter-sheet-assign
324 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 Sheet actions
330 • sheet-show-all
331 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 • sheet-show-group
337 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 • sheet-show-invisible
343 Clears the current workspace and populates it with all invisible
345 views that are a member of its current sheet.
346 View actions
348 • view-cycle-[next|prev]
349 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 • view-decrease-size-[up|down|left|right]
357 Decreases the size of the focused view by the amount of pixels set as
359 step value into the given direction
360 • view-hide
362 Hides the focused view.
364 • view-increase-size-[up|down|left|right]
366 Increases the size of the focused view by the amount of pixels set as
368 step value into the given direction
369 • view-lower
371 Lowers the focused view to the bottom of the stacking order.
373 • view-move-[up|down|left|right]
375 Moves the focused view step pixels into the given direction.
377 • view-move-[center[|-left|-right]|[bottom|top]-[left|middle|right]]
379 Moves the focused view to the given position on the output.
381 • view-only
383 Hides every other view except the focused one.
385 • view-pin-to-sheet-[0-9|alternate|current]
387 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 • view-quit
394 Closes the focused view.
396 • view-raise
398 Raises the view to the top of the stacking order.
400 • view-reset-geometry
402 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 • view-snap-[up|down|left|right]
409 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 • view-toggle-floating
415 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 • view-toggle-invisible
422 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 • view-toggle-maximize-[full|horizontal|vertical]
432 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 • view-toggle-public
438 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 VT actions
448 • vt-switch-to-[1-9]
449 Switches to another virtual terminal.
451 Workspace actions
453 • workspace-clear
454 Clears the current workspace.
456 • workspace-cycle-[next|prev]
458 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 • workspace-show-all
466 Clears the current workspace and populates it with all views. This
468 includes invisible views.
469 • workspace-show-group
471 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 • workspace-show-invisible
477 Clears the current workspace and populates it with all invisible
479 views that belong to that workspace.
480 • workspace-switch-to-sheet-[0-9|alternate|current]
482 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 • workspace-switch-to-sheet-[next|prev]-inhabited
492 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
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 To define an action action-terminal that launches sakura(1) one needs
503 to defined the following.
504 terminal = sakura
506 Now we can bind the newly defined action-terminal to a key combination
508 in the bindings section.
509
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 • L (Logo)
519 • S (Shift)
521 • C (Control)
523 • A (Alt)
525 • 5 (AltGR)
527 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 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 Once a key combination has been identified it can be bound to an ac‐
538 tion.
539 "LS+a" = action1 # symbol binding
541 "LS-38" = action2 # code binding
542 The bindings section can contain 2 subsections keyboard and mouse for
544 keyboard and mouse bindings.
545 Valid values for mouse button names are right, middle, left, side, ex‐
547 tra, forward, back and task.
548 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 "L+t" = {
554 begin = action-push-to-talk-start
555 end = action-push-to-talk-stop
556 }
557
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 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 marks {
570 s = sakura
571 }
572
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 • floating
580 Takes a boolean to specify the view’s floating state on startup. The
582 default value is false.
583 • focus
585 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 • group
591 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 • inherit
597 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 • invisible
607 Takes a boolean to specify the view’s invisible state on startup.
609 The default value is false.
610 • mark
612 Assign a mark to the view. This only takes effect if that mark is
614 not already bound to another view already.
615 • position
617 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 • bottom-left
624 • bottom-middle
626 • bottom-right
628 • center
630 • center-left
632 • center-right
634 • top-left
636 • top-middle
638 • top-right
640 This allows positioning a view relative to the output.
642 • public
644 Takes a boolean to specify the view’s public state on startup. The
646 default value is false.
647 • sheet
649 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 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 systat = {
661 group = monitor
662 sheet = 0
663 position = {
664 x = 1429
665 y = 1077
666 }
667 focus = true
668 inherit = [ group, sheet, { floating = true } ]
670 }
671
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 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 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 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 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 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 {
711 left = ...
712 right = ...
713 }
714 Respectively to split horizontally you have to specify top and bottom.
716 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 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 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 {
732 scale = 0.75
733 top = ...
734 bottom = ...
735 }
736 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 {
746 scale = {
747 min = 0.5
748 max = 0.75
749 }
750 left = single
751 right = stack
752 }
753 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 • empty
760 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 • single
767 Containers using the single layout only consume one view which takes
769 up the entire container.
770 • full
772 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 • stack
778 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 • queue
784 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 • grid
791 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 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 f = full
803 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 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 To define a queue container that contains up to 4 views one would de‐
813 fine it like that:
814 {
816 views = 4
817 layout = queue
818 }
819 Just stating the tiling algorithm is a short-hand for a layout object
821 with where views is set to 256.
822
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 • border
830 Defines the thickness of view borders in pixels.
832 Standard border thickness is set to 1.
834 border = 1
836 • gap
838 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 The standard gap value is 5.
843 gap = 5
845 • font
847 Specifies the font that is used for indicator bars.
849 hikari uses monospace 10 as its default font setting.
851 font = "monospace 10"
853 • step
855 The step value defines how many pixels move and resize operations
857 should cover.
858 The standard step value is 100.
860 step = 100
862 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 • active
871 Indicates view focus.
873 • background
875 Specifies the background color. This will be obscured by a wallpaper
877 • conflict
879 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 • first
886 Signals that the indicated view is the topmost view of a group.
888 • foreground
890 Font color for indicator bars.
892 • grouped
894 Views that belong to the same group are indicated using this color.
896 • inactive
898 Indicates that a view does not have focus.
900 • insert
902 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 • selected
908 This color is used to indicate that a view is selected.
910 These are the default settings for the hikari colorscheme.
912 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
926 The inputs section is used to configure input devices. Device names
927 can be determined using libinput(1).
928 Pointers
930 Pointers can be configured in the pointers subsection. The following
931 options are available.
932 • accel
934 Sets mouse acceleration for the pointer device to a value between -1
936 and 1.
937 • accel-profile
939 Sets mouse acceleration profile for the pointer device to the given
941 mode. Valid values are none, flat and adaptive.
942 • disable-while-typing
944 Enable or disable disable-while-typing if available. This setting
946 expects a boolean value.
947 • middle-emulation
949 Enable or disable middle click emulation if available. This setting
951 expects a boolean value.
952 • natural-scrolling
954 Enable or disable natural-scrolling if available. This setting ex‐
956 pects a boolean value.
957 • scroll-button
959 Configures the pointer scroll button. Valid values are right, mid‐
961 dle, left, side, extra, forward, back and task.
962 • scroll-method
964 Sets the pointers scroll method. Valid values are no-scroll, on-but‐
966 ton-down.
967 • tap
969 Enable or disable tap if available. This setting expects a boolean
971 value.
972 • tap-drag
974 Enable or disable tap-drag if available. This setting expects a
976 boolean value.
977 • tap-drag-lock
979 Enable or disable tap-drag-lock if available. This setting expects a
981 boolean value.
982 Configuring the System mouse input device could look like this.
984 inputs {
986 pointers {
987 "System mouse" = {
988 accel = 1.0
989 scroll-method = on-button-down
990 scroll-button = middle
991 }
992 }
993 }
994 A special name “*” is used to address all pointers. Values defined for
996 this pseudo pointer override unconfigured values for any other pointer.
997 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 To specify rules individually one can use the following options. Refer
1004 to xkeyboard-config(7) for possible settings.
1005 • rules
1007 Specifies the xkb rules. The default value is evdev.
1009 • model
1011 Sets the keyboard model.
1013 • layout
1015 Sets the keyboard layout.
1017 • variant
1019 Sets the keyboard variant.
1021 • options
1023 Sets keyboard options.
1025 Additionally hikari can also configure key repeat using the following
1027 attributes.
1028 • repeat-delay
1030 Takes a positive integer to specify the key repeat delay in millisec‐
1032 onds. The default value is 600.
1033 • repeat-rate
1035 Takes a positive integer to specify the key repeat rate in Hz. The
1037 default value is 25.
1038 Configuring the AT keyboard input device could look like this.
1040 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 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 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 • XKB_DEFAULT_LAYOUT
1063 • XKB_DEFAULT_MODEL
1065 • XKB_DEFAULT_OPTIONS
1067 • XKB_DEFAULT_RULES
1069 To specify a layout set XKB_DEFAULT_LAYOUT to the desired layout. This
1071 needs to happen before starting hikari.
1072 XKB_DEFAULT_LAYOUT "de(nodeadkeys),de"
1074 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 inputs {
1082 switches {
1083 "Control Method Lid Switch" = lock
1084 }
1085 }
1086
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 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 When defining a background object the following attributes are avail‐
1099 able.
1100 • path
1102 This attribute giving the path to the wallpaper image file is manda‐
1104 tory.
1105 • fit
1107 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 Configuring output eDP-1 and WL-1 could look like this.
1113 outputs {
1115 "eDP-1" = {
1116 background = "/path/to/wallpaper"
1117 }
1118 WL-1 = {
1120 background = {
1121 path = "/path/to/wallpaper"
1122 fit = center
1123 }
1124 }
1125 }
1126 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 "eDP-1" = {
1132 position = {
1133 x = 1680
1134 y = 0
1135 }
1136 }
1137 "HDMI-A-1" = {
1139 position = {
1140 x = 0
1141 y = 0
1142 }
1143 }
11442.3.2 HIKARI(1)