KAHAKAI

NAME

Kahakai - an X11 window manager with multi-language embedded scripting

SYNOPSIS

kahakai [--display DISPLAYNAME] [--rcfile CONFIGFILE] [--stylefile STYLEFILE] [--menufile MENUFILE] [--usage] [--help] [--version]

DESCRIPTION

Kahakai is a fork of the Waimea window manager, with the goal of allowing as much internal customization as possible. Kahakai uses SWIG to provide wrappers that allow high-level scripting languages to access the internals of the core of the window manager, which is written in C++.

OPTIONS

--display DISPLAYNAME

X server to contact

--rcfile CONFIGFILE

Use the alternate CONFIGFILE instead of ~/.kahakai/config and /usr/share/kahakai/config.

--stylefile STYLEFILE

Use the alternate STYLEFILE instead of /usr/share/kahakai/styles/Default. This overrides styleFile resource.

--menufile MENUFILE

Use the alternate MENUFILE instead of /usr/share/kahakai/menu This overrides menuFile resource.

--usage

Display brief usage message

--help

Show full help message

--version

Output version information and exit

CONFIG FILE

When starting, Kahakai looks for a .kahakai/config resource file in the users home directory. If file doesn't exist, Kahakai falls back to /usr/share/kahakai/config, the system wide configuration file. To force Kahakai to read a different configuration file use --rcfile switch. Below is a list of configuration options that Kahakai understands.

screenMask: List of screen numbers

Whitespace separated list of screens that Kahakai should manage. If you for example want Kahakai to handle only screen .0 and screen .2, then list of screen numbers should be: 0 2

scriptDir: Dirpath

Path to alternate scripts directory instead of /usr/share/kahakai/scripts. scriptDir is used execution of dynamic menu scripts.

doubleClickInterval: Integer

Adjust the delay (in milliseconds) between mouse clicks for Kahakai to consider it a double click. Default value is 300.

When running Kahakai on display with multiple screens the screen0 key in the following configuration options can also be screen1, 2 etc. for any appropriate screen.

screen0.styleFile: Filepath

Path to alternate STYLEFILE instead of /usr/share/kahakai/styles/Default.

screen0.menuFile: Filepath

Path to alternate MENUFILE instead of /usr/share/kahakai/menu.

screen0.numberOfDesktops: Integer

This tells Kahakai how many virtual desktops we should use. Default value is 4.

screen0.desktopNames: List of desktop names

A comma separated list of desktop names.

screen0.doubleBufferedText: Boolean

Tells Kahakai to use double buffered text drawing method. Removes text flickering and requires far less text redrawing. Faster in most cases. But be aware, then using flat solid textures one double buffered text redraw is more expensive than one single buffered one. Default value is True.

screen0.lazyTransparency: Boolean

Tells Kahakai to use lazy redrawing of transparent textures. When enabled, Kahakai only redraws transparent textures at end of move functions. Default value is False.

screen0.colorsPerChannel: Integer

This tells Kahakai how many colors to take from the X server on pseudocolor displays. A channel would be red, green, or blue. Kahakai will allocate this variable ^ 3 colors and make them always available. Value must be between 2 and 6. When you run Kahakai on an 8-bit display, you must set this resource to 4. Default value is 4.

screen0.cacheMax: Integer

This tells Kahakai how much memory (in KB) it may use to store cached pixmaps on the X server. If your machine runs short of memory, you may lower this value. Default value is 200.

screen0.imageDither: Boolean

Tells Kahakai to dither images on none TrueColor screens. Default value is True.

screen0.virtualSize: IntegerxInteger

Tells Kahakai what virtual desktop size to use. Example: 3x3 will set the virtual desktop size to three times screen height in virtual height and three times screen width in virtual width. Default value is 3x3.

screen0.menuStacking: StackingType

Tells Kahakai what stacking type to use for menus. Can be one of: AlwaysOnTop, AlwaysAtBottom or Normal. Default type is Normal.

screen0.transientAbove: Bool

Tells Kahakai to use special handling of transient windows. When turned on Kahakai will always keep transient windows above and focused relative to the the 'transient for' window. Default value is True.

screen0.focusRevertTo: RevertType

Specifies where the input focus reverts to if a window or menu becomes not viewable. RevertType can be one of Root or Window. When set to Root, Kahakai will revert focus to the root window. When set to Window, Kahakai will revert focus to the last focused window that is viewable. Default value is Window.

Dockappholder Resources

It is possible to have more than one dockappholder running. First dockappholder should be named dock0 and the second dock1 and so on. One dockappholder is always running whether you have a dock0 line in your CONFIGFILE or not.

screen0.dock[num].geometry: OffsetString

Define dockappholder position. OffsetString must be an X offset string of form: [{+-}<xoffset>{+-}<yoffset>]

screen0.dock[num].order: Regular Expression List

A whitespace separated list of regular expressions describing how to order the dockapps in the dockappholder. Dockapps can be ordered by window name, window class and window title. For window name use n/Regexp/ , `Regexp' being the POSIX regular expression used for window name matching. For window class use c/Regexp/ , `Regexp' being the POSIX regular expression used for window class matching. For window title use t/Regexp/ , `Regexp' being the POSIX regular expression used for window title matching.

Example:

screen0.dock0.order: n/.*meter$/ c/pager/

This will put dockapp window with name ending with `meter' at the first position in dockappholder and dockapp with classname containing `pager' at second position. All dockapp windows that doesn't match any regular expression will be put in last dockapp at last position.

screen0.dock[num].desktopMask: Desktop number list

A whitespace separated list of desktop numbers. Dockappholder will only appear in desktops specified by this list. To make dockappholder appear in all desktops, replace list with the string `All'. Default is All

screen0.dock[num].direction: Direction

Dockappholder direction {Vertical, Horizontal}

screen0.dock[num].centered: Boolean

True if you want the dockappholder to be centered. If direction is Vertical, yoffset from geometry resource will be ignored and dockappholder will be centered vertically. If direction is Horizontal, xoffset from geometry resource will be ignored and dockappholder will be centered horizontally.

screen0.dock[num].gridSpace: Integer

Number of pixels spacing between dockapps in dockappholder.

screen0.dock[num].stacking: StackingType

Stacking order for dockappholder {AlwaysOnTop, AlwaysAtBottom}.

screen0.dock[num].inworkspace: Boolean

True if you don't wont dockappholder to alter the workarea. Maximizied windows will be maximized over the dockappholder when this is set to true. Default is False.

STYLES

Kahakai enables you to use Blackbox specialized style files that contain X(7) resources to specify colors, textures and fonts, and thus the overall look of your window decorations and menus. However there are a few keys in Blackbox styles that Kahakai doesn't use and there are a few new keys that don't exist in standard Blackbox styles.

Kahakai allows you to configure the style of menus and the windows. Dockappholders use the same style as the windows.

Here are the different types of values:

Color

A valid X resource-style color name, e.g. `green', or `wheat'.

Font

XLFD (X core font) or Xft font name. Xft font names must be followed by [xft] suffix.
e.g.:


-adobe-courier-medium-r-normal--10-100-75-75-m-60-iso8859-1

The format for Xft font names is:


<family>-<size>:<name>=<value> [xft]

An arbitrary set of additional elements can be appended to the Xft font name, the complete list of possible properties is:

Name            Type
---------------------------------
family          String
style           String
slant           Int
weight          Int
size            Double
aspect          Double (only in Xft2)
pixelsize       Double
encoding        String (only in Xft1)
spacing         Int
foundry         String
core            Bool (only in Xft1)
antialias       Bool
xlfd            String (only in Xft1)
file            String
index           Int
rasterizer      String
outline         Bool
scalable        Bool
rgba            Int

(Defaults from resources)

scale           Double
render          Bool (only in Xft1)
minspace        Bool

(Specific to FreeType rasterizer)

charwidth       Int
charheight      Int
matrix          XftMatrix
charset         CharSet (only in Xft2)
lang            String (only in Xft2)

As family and size are both nearly always needed to access a Xft font, they're given a privileged place, but really they're no different than the remaining values. For elements that use an enumerated list of possible values, the values are given names which can be used in place of an integer, or can actually replace the whole name=value part. They're all unique, so this actually works. Here's a list of all of the enumerated values and the associated name:

Value           Element
---------------------------------
light           weight
medium          weight
demibold        weight
bold            weight
black           weight

roman           slant
italic          slant
oblique         slant

proportional    spacing
mono            spacing
charcell        spacing

rgb             rgba
bgr             rgba
vrgb            rgba
vbgr            rgba

Some example Xft font names:


times-12 [xft]

12 point times


times,charter-12:bold [xft]

12 point, preferring 'times', but accepting 'charter', bold.


times-12:bold:slant=italic,oblique [xft]

12 point times bold, either italic or oblique


times-12:rgba=vbgr [xft]

12 point times, optimized for display on an LCD screen with sub-pixel elements arranged vertically with blue on the top and red on the bottom.


times:pixelsize=100 [xft]

100 pixel times -- pixel size overrides any point size

Xft opacity level

Xft font opacity level. Integer value from 0 to 100, where 0 is the default non translucent opacity level and and 100 makes it a fully transparent font.

Font justification

Is one of left, right or center. e.g.: 'left'.

Texture descriptions

Texture descriptions are specified directly to the key that they should apply to, e.g.:


window.label:  Raised Gradient Diagonal Bevel1

A texture description consists of up to five fields, which are as follows:


Flat / Raised / Sunken

gives the component either a flat, raised or sunken appearance.


Gradient / Solid / Pixmap

tells Kahakai to draw either a solid color or a gradiented texture.

Horizontal / Vertical / Diagonal / Crossdiagonal / Pipecross / Elliptic / Rectangle / Pyramid

Select one of these texture types. They only work when also Gradient is specified!

Tiled / Scaled / Stretched

Select one of these resizing methods. They only work when also Pixmap is specified!. Tiled resizing does not resize the image just tiles it, fastest method. Scaled resizing performs a normal scaling of image, all parts of the image are scaled equally. Stretched resizing only scales the middle part of the image, all borders are preserved.


Interlaced

tells Kahakai to interlace the texture (darken every other line). This option is most commonly used with gradiented textures, but it also works in solid textures.


Bevel1 / Bevel2

tells Kahakai which type of bevel to use. Bevel1 is the default bevel. The shading is placed on the edge of the image. Bevel2 is an alternative. The shading is placed one pixel in from the edge of the image.

Instead of a texture description, also the option ParentRelative is available, which makes the component appear as a part of its parent, totally transparant.

All gradiented textures are composed of two color values: the color and colorTo resources. When Interlaced is used in Solid mode, the colorTo resource is used to find the interlacing color.

A image file must be specified for all pixmap textures. pixmap resources is used for finding the image file. Must be either a complete file path, a file path relative to Kahakai start directory or an image file in the same directory as the style file.

Texture opacity level

Texture opacity level. Integer value from 0 to 100, where 0 is the default non translucent opacity level and and 100 makes it a fully transparent texture. This requires that the program setting the background image has support for setting _XROOTPMAP_ID property on root window. Esetroot does this. Opacity works for all types of textures even pixmaps.

Pixmap stretching borders

Borders used for pixmap stretching. Format is:

{ LEFT, RIGHT, TOP, BOTTOM }

LEFT being the width of left border, RIGHT being the width of right border, TOP being the height of top border and BOTTOM being the height of bottom border. Only graphics not within any of the borders will be scaled when stretching pixmap.

Here are the keys Kahakai understands together with the value they should contain.

Window Keys
Controls the look of the window decorations. The '*' in the window keys can be one of: title, label, handle, button or grip.

window.*.focus: Texture description
window.*.focus.opacity: Texture opacity level
window.*.focus.color: Color
window.*.focus.colorTo: Color
window.*.focus.pixmap: Pixmap
window.*.focus.border: Border

: Texture type, opacity level, colors and pixmap used for focused window textures.

window.*.unfocus: Texture description
window.*.unfocus.opacity: Texture opacity level
window.*.unfocus.color: Color
window.*.unfocus.colorTo: Color
window.*.unfocus.pixmap: Pixmap
window.*.unfocus.border: Border

: Texture type, opacity level and colors used for unfocused window textures.

window.label.focus.textColor: Color
window.label.focus.textColor.opacity: Xft opacity level
window.label.focus.textShadowColor: Color
window.label.focus.textShadowColor.opacity: Xft opacity level

: Color and opacity level used for focused window label font.

window.label.focus.textShadowXOffset: Integer
window.label.focus.textShadowYOffset: Integer

: X and Y shadow offset for focused window label. If neither XOffset or YOffset are specified or both are zero no shadow will be rendered.

window.label.unfocus.textColor: Color
window.label.unfocus.textColor.opacity: Xft opacity level
window.label.unfocus.textShadowColor: Color
window.label.unfocus.textShadowColor.opacity: Xft opacity level

: Color and opacity level used for unfocused window label font.

window.label.unfocus.textShadowXOffset: Integer
window.label.unfocus.textShadowYOffset: Integer

: X and Y shadow offset for unfocused window label. If neither XOffset or YOffset are specified or both are zero no shadow will be rendered.

window.button.focus.picColor: Color: Color used for focused window button symbols.

window.button.unfocus.picColor: Color: Color used for unfocused window button symbols.

window.button.pressed.picColor: Color: Color used for pressed button symbols.

window.justify: Font justification: Font justification for window labels.

window.font: Font: Font for window titles.

borderWidth: Integer: Integer value for window border width.

borderColor: Color: Color of window border.

outlineColor: Color: Color of window outline used for non-opaque moving and resizing.

window.title.height: Integer

Integer value for forced titlebar height. If key isn't defined the title height is set by the height of the font.

Menu Keys
Controls the look of the menus. The '*' in the menu keys can be one of: title, frame or hilite.

menu.*: Texture description
menu.*.opacity: Texture opacity level
menu.*.color: Color
menu.*.colorTo: Color
menu.*.pixmap: Pixmap
menu.*.border: Border

: Texture type, opacity level and colors used for menu textures.

menu.*.textColor: Color
menu.*.textColor.opacity: Xft opacity level
menu.*.textShadowColor: Color
menu.*.textShadowColor.opacity: Xft opacity level

: Color and opacity level used for menu fonts.

menu.*.textShadowXOffset: Integer
menu.*.textShadowYOffset: Integer

: X and Y shadow offset for menu item. If neither XOffset or YOffset are specified or both are zero no shadow will be rendered.

menu.*.justify: Font justification: Font justification for menu items.

menu.*.font: Font: Font for menu items.

menu.bullet.look: String or 'char': String or character code used for menu bullets.

menu.checkbox.true.look: String or 'char': String or character code used for true checkboxes.

menu.checkbox.false.look: String or 'char': String or character code used for false checkboxes.

menu.borderWidth: Integer: Integer value for menu border width.

menu.item.height: Integer: Integer value for forced menu frame item height. If key isn't defined the frame menu item height is set by the height of the font.

menu.title.height: Integer

Integer value for forced menu title item height. If key isn't defined the frame menu title height is set by the height of the font.

Dockappholder Keys
Controls the look of the dockappholders. A different texture can be assigned to each dockappholder. '[ID]' should be replaced by a dockappholder ID number. A dockappholder ID is >=0 and depends on the dockappholder configuration in the rc-file.

dockappholder.dock[ID].frame: Texture description
dockappholder.dock[ID].frame.opacity: Opacity level
dockappholder.dock[ID].frame.color: Color
dockappholder.dock[ID].frame.colorTo: Color
dockappholder.dock[ID].frame.pixmap: Pixmap
dockappholder.dock[ID].frame.border: Border

: Texture type, opacity level and colors used for dockappholder 'dock[ID]'s frame texture.

dockappholder.dock[ID].borderWidth: Integer: Border width used for dockappholder 'dock[ID]'s border.

dockappholder.dock[ID].borderColor: Color

Border color used for dockappholder 'dock[ID]'s border.

Button Keys
Controls the look of the titlebar buttons. For backwards compatibility with blackbox styles Kahakai still understands the above mentioned window.button.* key, but Kahakai have a much more advanced configuration system for titlebar buttons. The Kahakai titlebar configuration system allows you to have any number of titlebar buttons and the position and look for each button can be specified.

A titlebar button works just like a checkbox. It has two states, a 'false' state and a 'true' state. Which state the button is in depends on a variable and the look of each of these states can be specified. The '[ID]' must be a number >= 0. For Kahakai to read button configuration with an ID of 2, there must be a configuration with an ID of 0 and an ID of 1, this is because Kahakai stops reading button configurations when it comes to missing ID.

window.button[ID].foreground: Boolean: True if you want Kahakai to draw its standard foreground graphics on the button. Graphics drawn depends on the buttons state configuration.

window.button[ID].state: Checkbox State

This specifies what variable the button should monitor for its state. Can be one of these:
MAXIMIZED
MINIMIZED
SHADED
STICKY
ALWAYSONTOP
ALWAYSATBOTTOM
DECORTITLE
DECORHANDLE
DECORBORDER
DECORALL
FULLSCREEN
CLOSE
None

When set to None, titlebar button will only have one state (false state). Default is None.

window.button[ID].autoplace: Autoplace Type: This specifies the autoplace type for the button. Can be one of Left, Right or False. Left will automatically place the button on the left side of the titlebar so that it doesn't cover any other button and Right will automatically place the button on the right side. No automatic placement will be used when set to False. Default is False.

window.button[ID].position: Offset: X coordinate for button. If offset is positive, then the left side of the titlebar will be used as X coordinate zero. If offset is negative, then the right side of the titlebar will be used as X coordinate zero. 'position' resource will be ignored if not 'autoplace' resource is set to False.

window.button[ID].[STATE].focus: Texture description
window.button[ID].[STATE].focus.opacity: Opacity level
window.button[ID].[STATE].focus.color: Color
window.button[ID].[STATE].focus.colorTo: Color
window.button[ID].[STATE].focus.pixmap: Pixmap
window.button[ID].[STATE].focus.border: Border
window.button[ID].[STATE].unfocus: Texture description
window.button[ID].[STATE].unfocus.opacity: Opacity level
window.button[ID].[STATE].unfocus.color: Color
window.button[ID].[STATE].unfocus.colorTo: Color
window.button[ID].[STATE].focus.border: Border
window.button[ID].[STATE].unfocus.pixmap: Pixmap
window.button[ID].[STATE].pressed: Texture description
window.button[ID].[STATE].pressed.opacity: Opacity level
window.button[ID].[STATE].pressed.color: Color
window.button[ID].[STATE].pressed.colorTo: Color
window.button[ID].[STATE].pressed.pixmap: Pixmap
window.button[ID].[STATE].pressed.border: Border

: Texture type, opacity level and colors used for titlebar button[ID]. [STATE] can be 'false' or 'true'. If button have more than one state then both 'false' and 'true' state textures should be specified. If button have only one state then only 'false' state needs to be specified.

rootCommand: Command line: This command is executed whenever this style is loaded. Typically it sets the root window to a nice picture.

Default style file is /usr/share/kahakai/styles/Default. You can study or edit this style to grasp how the style mechanism works.

MENUS

All menus must be defined in the menu file.

A menu definition starts with a [start] tag and ends with an [end] tag. Between the [start] and the [end] tag a number of [item], [title], [sub] and [checkbox] tags should be placed. The looks and action lists are the only things separating the first three menu item types. All three of these tags could be followed by a (string), "string", {string} and <string>. A [checkbox] tag is basically an [item] tag with two states.

Kahakai menu system is compatible with blackbox(1) menu system, so higher level tags as [begin], [exec], [submenu], [nop], [restart] and [exit] are supported. blackbox(1) also supports [styledir], [reconfig] and [config] tags, these tags are not used by Kahakai.

() = menu item title
"" = action
{} = command line
<> = sub menu

e.g.:


[start]   (menu)
  [title] (Menu)
  [item]  (Xterm)    {xterm}
  [sub]   (Programs) <progs>
  [item]  (Restart)  "restart"
  [item]  (Exit)     "exit"
[end]

It is possible to start defining a new menu within another menu. e.g.:


[start]    (menu)
  [start]  (menu2)
    [item] (not smart)    {rm -rf ~}
    [end]
  [sub]    <menu2>
[end]

[include] tags can be used anywhere in a menu file to include the contains of another file. e.g.:


[include] (/home/user/.waimea/rootmenu)

Environment Variables And Window Info Expansion
Menu item titles include filenames and submenu references can contain environment variables. e.g.:

[item] (Logout $USER) "exit"

$USER will be replaced with USER environment variable.

Menu mapped by event occurring on a window.* window can contain special window info character sequences. These character sequences are expanded with the current window info when menu is mapped. e.g.:


[item] (win name: \n)

Will be expanded to:


[item] (win name: windowname)

Where windowname is the actual class name of the window.
These are the character sequences that Kahakai recognizes:


"\c" Window class
"\n" Window class name
"\h" Host name for window owner
"\p" PID of window owner

If some window info isn't known for a window, the character sequence used for expanding this info will be replaced with an empty string.

All special characters need to be escaped (with a `\') to protect them from expansion. Special characters are:

( ) { } < > [ ] " $

Checkboxes
A checkbox item is a item that have two states and a flag decides which state the item is in. e.g.:


[checkbox=STICKY] @FALSE (Sticky) "sticky" @TRUE (Sticky) "unsticky"

Flag to decide which mode to be in for this checkbox is STICKY (the sticky flag for a window). If STICKY flag is 'False' the checkbox item will be in mode defined by menu string after @FALSE and if STICKY flag is 'True' the checkbox item will be in mode defined by the menu string after @TRUE.

Here is the list of flags that can be used with checkbox items:
MAXIMIZED
MINIMIZED
SHADED
STICKY
ALWAYSONTOP
ALWAYSATBOTTOM
DECORTITLE
DECORHANDLE
DECORBORDER
FULLSCREEN

Taskswitcher
Predefined menu named "__windowlist__" can be used in menu file and scripts to access the taskswitcher menu.

Window merging
Predefined menus named "__mergelist__", "__mergelist_vertically__" and "__mergelist_horizontally__" can be used in menu file and scripts to access window merging menus.

Dynamic menus
Kahakai supports dynamic menus. A Dynamic menu is a menu that is generated when mapped. Compared to a normal static menu that must be fully defined in the MENUFILE the definition of a dynamic menu only consists of a command line. The command line is executed when the menu is to be mapped and the standard output from the command is parsed in the same way as the MENUFILE to generate the dynamic menu. Every time the menu is remapped the command line is executed and a new menu is generated. A dynamic menu is defined as a submenu link in the MENUFILE or as a menu_name parameter to one of the menumap actions. A dynamic menu definition must start with a '!' character and be followed by a command line. e.g.:


[sub] (Styles) <!styledir.pl>

Creates a submenu item with title 'Styles' and the submenu for the item is dynamic menu created by execution of styledir.pl script. Dynamic menus can contain definitions of other dynamic menus.

Default menu file is /usr/share/kahakai/menu. You can study or edit this menu file to grasp how the menu system works.

ENVIRONMENT

HOME

Kahakai uses this variable to find its .kahakai directory.

DISPLAY

When no other display was given on the command line, Kahakai will start on the display specified by this variable.

FILES

~/.kahakai/config: User configuration file. See CONFIG FILE section for further details.
/usr/share/kahakai/config: The system wide configuration file. See CONFIG FILE section for further details.
/usr/share/kahakai/style/Default.style: The system wide style file. See STYLES section for further details.
/usr/share/kahakai/menu: The system wide menu file. See MENUS section for further details.

BUGS

This man page is itself somewhat of a bug, because it is not very accurate or thorough. Kahakai development is taking place very rapidly and documentation will not have a chance to catch up for a while. Resources such as the Kahakai irc channel ( irc.freenode.net #kahakai ) and the wiki ( http://kahakai.sf.net/wiki/ ) are your best bet.

Bug reports, patches, suggestions, and insults are welcomed and appreciated, please file them in the appropriate area on http://sf.net/kahakai

The Kahakai website: http://kahakai.sf.net