xxkb(1)

🌸 xxkb(1) — General Commands Manual 🌸

okay bestie, buckle up, this is the whole xxkb manual and it's a long one, so we're doing this in ✨parts✨. no cap, every single flag stays. let's go 💅

---

💖 NAME 💖

xxkb — switches and indicates a current keyboard layout. that's it, that's the girl. 🦋

---

✨ SYNOPSIS ✨

xxkb

literally just run her. iconic.

---

🎀 DESCRIPTION 🎀

so xxkb shows you the current keyboard layout (an XKB group) and lets you switch it with a mouse click. and she has extras, bestie. she remembers the layout for each application window and changes the keyboard state accordingly when the window gets a focus — like she keeps receipts for every window 📝. she can also place an additional button on a window title bar, and that button is both a switcher and an indicator for that separate window.

if the keyboard map has more than two layouts, xxkb can simplify switching with a two_state mode. in this mode you pick two layouts — one as a base layout and another as an alternative layout — and then she switches the keyboard state between them only. also xxkb supports applications lists, which let you tune her behavior for some separate applications. 🫶

and the best part? xxkb works with any window manager. no exceptions, we love a versatile queen 👑

---

🌈 USAGE 🌈

as an indicator, xxkb shows the current XKB layout using one of four pixmaps and changes the pixmap when you change a layout — either with the keyboard (using the key or the key combination specified in the config file as an XKB group switcher) or with any other application that's able to change the XKB group. she also shows similar pixmaps on each application window title bar, which are indicators for separate windows.

and since the global indicator and the per window indicators duplicate each other, you can hide the global indicator or all per window indicators using configure options. pick your fighter 💅

also you can use xxkb as a layout switcher by clicking a mouse button on the main xxkb window or on one of the per window indicators. in the last case you switch the layout for the chosen application. so satisfying.

🖱️ MouseButton1

the first button acts as a layout switcher. if the two_state mode is active, the button click switches the current layout between two selected layouts (XKB groups). otherwise it selects all possible layouts in cycle. around and around we go 🌀

🖱️ MouseButton3

when the two_state mode is switched on, the third button lets you choose an alternative layout. it selects all possible layouts in cycle, and the layout you stop on becomes the alternative layout. without the two_state mode, this button action is the same as the first button action. twin behavior, honestly 💀

🖱️ MouseButton2

the second (middle) button action depends on the place where you click. the click on the main indicator terminates the xxkb. but the click on one of the per window indicators simply removes the indicator from the title bar and excludes that application from a set of managed applications.

also the second button lets you add an application into one of three lists of the applications which should be ignored (see the Applications lists options below). clicking on the per window indicator while the Control key is pressed adds this application to the wm_class_class list. if the Shift key is pressed, the button click adds the application to the wm_name list. if both keys are pressed, the click adds the application to the wm_class_name list. in all cases the updated lists will be saved in a per user config file ~/.xxkbrc. ✨ auto-save queen ✨

---

⚙️ CONFIGURE OPTIONS ⚙️

xxkb reads all configure options from two files: app-defaults/XXkb and ~/.xxkbrc. two sources, one vibe.

🌸 Common options 🌸

• XXkb.image.path — the directory where xxkb searches pixmap files. her little mood board folder 🎀

🪟 Main window options 🪟

• XXkb.mainwindow.enable — switch on the xxkb main window (yes by default). if a per window button mode is switched on, some users prefer to hide the main window of the xxkb. do you, bestie.
• XXkb.mainwindow.appicon — run xxkb as an animated icon. it is useful for window managers which allow 'to dock' applications. she's moving, she's grooving 💃
• XXkb.mainwindow.in_tray — allow to dock xxkb into a system tray. a value is either true or false.
• XXkb.mainwindow.geometry — the geometry ( WIDTHxHEIGHT{+-}XOFF{+-}YOFF ) of the main window. please read the GEOMETRY SPECIFICATIONS section of X(7) for details. go read it, fr fr.
• XXkb.mainwindow.border.color — color to be used when drawing window border.
• XXkb.mainwindow.border.width — border width in pixels.
• XXkb.mainwindow.image.N — pixmap file names for each indicated group N. if your symbols map has less than four groups, the unused group icons can be omitted. if the file name begins from '/' it means full path for the file. otherwise it means the relative path beginning from the XXkb.image.path value.
• XXkb.mainwindow.label.enable — enable labels to be printed instead of images. group descriptions will be used if not overwritten by XXkb.mainwindow.label.text.N (where N is 1..4, group number) options.
• XXkb.mainwindow.label.text.N — label for the specified group N.
• XXkb.mainwindow.label.background
• XXkb.mainwindow.label.foreground — colors used to draw background and label text respectively.
• XXkb.mainwindow.label.font — font to be used when drawing labels.

🎛️ Operation mode options 🎛️

since xxkb can keep the keyboard state for each application and restore the state when the focus is changed, there's a group of options which controls how xxkb finds the application windows. detective mode: activated 🔍

• XXkb.controls.add_when_start — if this mode is switched on (default), xxkb at start time tries to find all application already run.
• XXkb.controls.add_when_create — in this mode xxkb gets a new application window at time when the application creates it. it is the base mode but I can't guaranty it works with all window managers. ⚠️ (yes, the typo is canon, we keep it, no cap)
• XXkb.controls.add_when_change — in this mode xxkb doesn't catch the windows at their creation but adds windows to the managed windows list if the keyboard state changes when the window is focused. it's an additional mode (not recommended) and may be useful only if the add_when_create mode for some reason doesn't work.
• XXkb.controls.focusout — it makes xxkb reset the keyboard group when the focus leaves the window. the mode makes sense with the add_when_change mode only.
• XXkb.controls.button_delete — this mode (switched on by default) allows user to remove the per window button using a mouse middle button click. although xxkb tries to ignore the windows where the keyboard layout switching doesn't make sense, such windows can still appear. or there are windows where an user for some reason doesn't want to have the button. relatable honestly.
• XXkb.controls.button_delete_and_forget — this mode in addition to previous one makes xxkb forget the window which button is deleted. it means xxkb will not remember the keyboard state changes in this window and restore this state when the window will be focused. she's letting go of the past 🦋
• XXkb.controls.two_state — switching between two chosen keyboard layouts only. if the XKB symbols map has more than two groups and not all of them are needed for each application, xxkb allows to skip unneeded layouts at the layout switching. you can select one group as a base group and another one as an alternative group and then switch between these two groups only. the base group is common for all applications (usually it contains ASCII) but the alternative group can be chosen for each application window separately. in this mode a mouse right button allows to select the alternative group and a mouse left button as well as the key which configured as the layout switcher change the current state between two selected layouts only. this mode uses two additional config options:
  • XXkb.group.base — the base group (integer 1..4).
  • XXkb.group.alt — the default alternative group (integer 1..4).

🔘 The application window button options 🔘

all these options make sense if the XXkb.button.enable is switched on. (read that twice, bestie 💅)

• XXkb.button.enable — if turned on, xxkb adds an additional button to a title bar of each managed window which is the indicator and the layout switcher for that particular window. these buttons are not usual window manager buttons but windows (with a pixmap) owned by the xxkb itself. it means that in some cases a user needs to tune the button size and the position for the button to look like a window manager decoration element. cosplay but make it functional ✨
• XXkb.button.geometry — the button geometry ( WIDTHxHEIGHT{+-}XOFF{+-}YOFF ).
• XXkb.button.image.N — the pixmap file names (the same as for the XXkb.mainwindow.image.* options).
• XXkb.button.label.enable
• XXkb.button.label.text.N
• XXkb.button.label.background
• XXkb.button.label.foreground
• XXkb.button.label.font
• XXkb.button.border.color
• XXkb.button.border.width — see description of their main window counterparts. 👀

🔔 Bell options 🔔

• XXkb.bell.enable — enables the keyboard bell when the layout changes. ding! 🔔
• XXkb.bell.percent — an argument value for the XBell call.

📋 Applications lists options 📋

xxkb allows to specify lists of applications that requires some special actions. the applications can be specified using their WM_CLASS or WM_NAME properties.

a common form of such option is

XXkb.app_list.property.action: an applications list

the action here can be one of ignore, start_alt or alt_groupn. the ignore action means that the xxkb must ignore the windows of those applications and doesn't add them to the managed windows set. the start_alt action means that the xxkb must set the keyboard state to the alternative layout when the application starts. and the alt_group1, alt_group2, alt_group3 or alt_group4 actions allow to specify the alternative layout for some applications if this layout should be different from the common alternative layout specified in the XXkb.group.alt option.

the property can be one of wm_class_class, wm_class_name or wm_name. the xxkb can identify an application using its window properties WM_CLASS or WM_NAME. the WM_CLASS property actually consists of two parts — a res_class and a res_name. thus the property field specifies what property or part of property should be considered for the application identification.

by default all these lists are empty. a not empty list is a sequence of words separated by space/tab. the xxkb accepts an asterisk as a part of word. long lists can be continued to the next line using a backslash as the last char in the line.

for example:

XXkb.app_list.wm_name.ignore: Fvwm* *clock .br

                              Xman

• XXkb.ignore.reverse — this option changes a meaning of the Xxkb.*.ignore list. if the option switched on, the ignore list becomes the list of windows which should be managed but all other should be ignored. plot twist 🌀 (and yes, the lowercase x in Xxkb.*.ignore is exactly how the original says it, we keep it fr fr)

---

and that's it for part one, bestie... but hold up, there's more coming 💖

🌟 AUTHOR 🌟

okay so the entire legend behind this whole thing? it's giving Ivan Pascal 👑💖. that's the name on the door, bestie — he's the one who made xxkb a thing. no cap. go say thank u if u ever bump into him fr fr 🫶✨

---

and that's the whole page, bestie!! u just read the xxkb manual top to bottom and ur officially That Girl who knows her keyboard layout switcher 💅🌸

this page is from the XXKB manual, dated 24 Jun 2002 📅✨ — so yeah, it's an elder icon, but iconic is iconic, and it's been holding it down since way back 💜🦋

mwah 💋 go switch some layouts, u got this 🎀