waimea(1)

NAME

Waimea - an X11 window manager designed for maximum effi

ciency

SYNOPSIS

waimea    [--display=DISPLAYNAME]    [--rcfile=CONFIGFILE]
[--stylefile=STYLEFILE]    [--actionfile=ACTIONFILE]     [--menufile=MENUFILE] [--usage] [--help] [--version]

DESCRIPTION

The design goal for waimea is to create the most efficient

desktop working environment available. To achieve this waimea is

a fast and highly customizable virtual multiple desktop window

manager. It has a very advanced style engine with features like

blackbox style support, pixmap style support and transparent tex

tures. Text can be rendered double buffered using both X core

fonts and Xft fonts. Waimea also includes a fast lightweight

menu system with dynamic menus support. The built in action con

figuration system makes waimea the most configurable window man

ager available. It allows the user to set up waimea to behave as

any other window manager or in new ways never before possible.

OPTIONS

--display DISPLAYNAME

X server to contact

--rcfile CONFIGFILE

Use the alternate CONFIGFILE instead of ~/.waimearc

and /usr/share/waimea/config.

--stylefile STYLEFILE

Use the alternate STYLEFILE instead of

/usr/share/waimea/styles/Default. This overrides styleFile re

source.

--actionfile ACTIONFILE

Use the alternate ACTIONFILE instead of

/usr/share/waimea/actions/action. This overrides actionFile re

source.

--menufile MENUFILE

Use the alternate MENUFILE instead of

/usr/share/waimea/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, waimea looks for a .waimearc resource file

in the users home directory. If file doesn't exist, waimea falls

back to /usr/share/waimea/config, the system wide configuration

file. To force waimea to read a different configuration file use

--rcfile switch. Below is a list of configuration options that

waimea understands.

screenMask: List of screen numbers

Whitespace separated list of screens that waimea

should manage. If you for example want waimea 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/waimea/scripts. scriptDir is used execution of dynam

ic menu scripts.

doubleClickInterval: Integer

Adjust the delay (in milliseconds) between mouse

clicks for waimea to consider it a double click. Default value is

300.

When running waimea 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/waimea/styles/Default.

screen0.menuFile: Filepath

Path to alternate MENUFILE instead of

/usr/share/waimea/menu.

screen0.actionFile: Filepath

Path to alternate ACTIONFILE instead of

/usr/share/waimea/actions/action.

screen0.numberOfDesktops: Integer

This tells waimea 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 waimea to use double buffered text drawing

method. Removes text flickering and requires far less text re

drawing. Faster in most cases. But be aware, then using flat sol

id textures one double buffered text redraw is more expensive

than one single buffered one. Default value is True.

screen0.lazyTransparency: Boolean

Tells waimea to use lazy redrawing of transparent

textures. When enabled waimea only redraws transparent textures

at end of move functions. Default value is False.

screen0.colorsPerChannel: Integer

This tells waimea how many colors to take from the

X server on pseudocolor displays. A channel would be red, green,

or blue. Waimea will allocate this variable ^ 3 colors and make

them always available. Value must be between 2 and 6. When you

run waimea on an 8-bit display, you must set this resource to 4.

Default value is 4.

screen0.cacheMax: Integer

This tells waimea 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 waimea to dither images on none TrueColor

screens. Default value is True.

screen0.virtualSize: IntegerxInteger

Tells waimea what virtual desktop size to use. Ex

ample: 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 waimea what stacking type to use for menus.

Can be one of: AlwaysOnTop, AlwaysAtBottom or Normal. Default

type is Normal.

screen0.transientAbove: Bool

Tells waimea to use special handling of transient

windows. When turned on waimea will always keep transient windows

above and focused relative to the the 'transient for' window.

Default value is True.

Dockappholder Resources

It is possible to have more than one dockappholder run

ning. 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, X offset string of

form: [{+-}<xoffset>{+-}<yoffset>]. See X(7).

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

A whitespace separated list of regular expressions

describing how to order the dockapps in the dockappholder. Dock

apps can be ordered by window name, window class and window ti

tle. 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 win

dows 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 direc

tion is Horizontal, xoffset from geometry resource will be ig

nored and dockappholder will be centered horizontally.

screen0.dock[num].gridSpace: Integer

Number of pixels spacing between dockapps in dock

appholder.

screen0.dock[num].stacking: StackingType

Stacking order for dockappholder {AlwaysOnTop, Al

waysAtBottom}.

screen0.dock[num].inworkspace: Boolean

True if you don't wont dockappholder to alter the

workarea. Maximizied windows will be maximized over the dockap

pholder when this is set to true. Default is False.

STYLES

Waimea 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

waimea doesn't use and there are a few new keys that doesn't ex

ist in standard blackbox styles.

To understand how the style mechanism works, you should

have a little knowledge of how X resources work. See X(7) for

this.

Waimea allows you to configure the style of menus and the

windows. Dockappholders uses the same style as the windows.

Here are the different types of values:

Color Is a color name. See X(7) for how to write valid

color names. e.g.: 'green'.

Font XLFD (X core font) or Xft font name. Xft font names

must be followed by [xft] suffix. See X(7) for how to write valid

XLFD font names.

e.g.:

-adobe-courier-medium-r-nor

mal--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 ap

pended to the Xft font name, the complete list of possible prop

erties 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 ac

tually replace the whole name=value part. They're all unique, so

this actually works. Here's a list of all of the enumerated val

ues 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 'char

ter', 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 waimea to draw either a solid color or a gra

diented 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 re

size 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 waimea 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 waimea which type of bevel to use. Bevel1 is

the default bevel. The shading is placed on the edge of the im

age. Bevel2 is an alternative. The shading is placed one pixel

in from the edge of the image.

Instead of a texture description, the option

ParentRelative is also available, which makes the component ap

pear as a part of its parent, totally transparent.

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 interlac

ing color.

A image file must be specified for all pixmap tex

tures. pixmap resources is used for finding the image file. Must

be either a complete file path, a file path relative to waimea

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. Opac

ity 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 with

in any of the borders will be scaled when stretching pixmap.

Here are the keys waimea 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 un

focused 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 la

bel 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 tex

ture can be assigned to each dockappholder. '[ID]' should be re

placed 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 waimea still understands the

above mentioned window.button.* key, but waimea have a much more

advanced configuration system for titlebar buttons. The titlebar

configuration system allows you to have any number of titlebar

buttons and the position and look for each button can be speci

fied.

A titlebar button works just like a checkbox. It has two

states, a 'false' state and a 'true' state. Which state the but

ton 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

waimea 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 be

cause waimea stops reading button configurations when it comes to

missing ID.

window.button[ID].foreground: Boolean

True if you want waimea to draw its standard fore

ground 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 mon

itor for its state. Can be one of these:
MAXIMIZED
SHADED
STICKY
ALWAYSONTOP
ALWAYSATBOTTOM
DECORTITLE
DECORHANDLE
DECORBORDER
DECORALL
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 ti

tlebar button[ID]. [STATE] can be 'false' or 'true'. If button

have more than one state then both 'false' and 'true' state tex

tures should be specified. If button have only one state then on

ly '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/waimea/styles/Default.

You can study or edit this style to grasp how the style mechanism

works.

ACTIONS

Waimea uses special action files for controlling its be

havior. The idea is that you could specify an action for every

useful X event received.

An action file should contain action lists for different

types of windows. An action list looks like this:

WINDOW {

ACTIONLINE,
ACTIONLINE

}

WINDOW is a window that you can create actions for, a list

of windows that you can assign actions for follows below. ACTION

LINE is a string describing the action to be performed and when.

Actions are matched in the same order as the order of the action

lines.

For convenience it's also possible to define lists of ac

tion lines. e.g.:

DEF definedTitleActions {

StartMove : ButtonPress = Button1,
EndMoveResize : ButtonRelease = Button1

}
window.title {

definedTitleActions,
ToggleShade : DoubleClick = Button1

}

In window.title action list 'definedTitleActions' will be

replaced by the action lines defined above.

An action line should start with an action and then a ':'

character followed by an event description.

The event description contains an event type, an optional

event detail and a modifier mask.

Here are two good examples:

StartMove : ButtonPress = Button1 & Mod1Mask & Control

Mask
StartResize : ButtonPress = Button1 & Mod1Mask & !Control

Mask

The first line will create a startmove action that will be

performed when a ButtonPress event is received from Button1 and

at least mod1 modifier and control modifier are active. The sec

ond line will create a startresize action that will be performed

when a ButtonPress event is received from Button1 and at least

mod1 modifier is active and the control modifier is not active.

Waimea also supports delayed actions. A delay is defined

within brackets at the end of the action line. A delay definition

consists of a delay time in milliseconds followed by an optional

delay break event list. The delay break list is a list of events

that if occurring during the delay time will discard the action.

The delay time and the delay break list are separated with a

colon and the events in the delay break list are separated with

pipe signs. e.g.:

Raise : EnterNotify [2000 : LeaveNotify | ButtonPress]

Adds a 2000 milliseconds delay to the Raise action,

LeaveNotify and ButtonPress events will discard the action.

Here is the list of all windows that you can create ac

tions for (to define individual actions for a specific window

just replace 'window.*' with n/Regexp/.*, c/Regexp/.* or t/Reg

exp/.* where Regexp is the regular expression to match window

name/class/title):

window.frame

This is the parent window for the client window and

all decoration windows. Use this key if you want to set an action

for the window border.

window.title

This is the parent window for the label and button

windows. You probably want this window to have the same action

list as the label window.

window.label

This is the window that holds the titlebar text.

window.clientactive
window.clientpassive

This is the actual window created by the client.

window.clientactive is the action list for active (focused) win

dows and window.clientpassive is the action list for passive (un

focused) windows. All actions for window.client.* can be pre

fixed with a '*' character to make them pass-through actions

(Events matching pass-through actions will also be sent to the

client window).

window.button[ID]

Titlebar button window, [ID] will match with [ID]

from style file.

window.handle

This is the window for the middle part of the han

dlebar.

window.leftgrip
window.rightgrip

Windows for the left and right grip in the handle

bar.

menu.title
menu.item
menu.sub
menu.checkbox

Menu item windows.

root Root window (background).

westedge
eastedge
northedge
southedge

Transparent windows at the edges of the screen.

Useful for viewport shifting.

Here is the list of actions common for all window types:

{command line}

You can specify a command line to execute instead

of a function. Command line must be within a '{' and a '}' char

acter. All special characters need to be escaped (with a `´) to

protect them from expansion. Special characters are:
( ) { } < > [ ] " $

focus Set input focus to the event window.

viewportleft
viewportright
viewportup
viewportdown

Moves viewport one screen width and warps the

pointer one screen width in the opposite direction.

viewportrelativemove(OffsetString)

Moves viewport relative to its current position.

MUST have an X offset string as parameter: [{+-}<xoff

set>{+-}<yoffset>] See X(7). The xoffset and yoffset values de

fines the number of pixels to move the viewport. A 'W' character

in the OffsetString is replaced with screenwidth. A 'H' character

in the OffsetString is replace with screenheight.

viewportfixedmove(OffsetString)

Moves viewport to a fixed position. MUST have an X

offset string as parameter: [{+-}<xoffset>{+-}<yoffset>] See

X(7).

position. {+-} signs defines viewport gravity. A 'W' character
in the OffsetString is replaced with screenwidth. A 'H' character
in the OffsetString is replace with screenheight.
startviewportmove

Moves viewport after mouse motion events, kind of

the same way as you move windows. Must be ended with

endmoveresize action.

taskswitcher

Maps windowlist menu at the middle of the screen.

This menu is very useful for switching between windows.

nexttask

Sets focus to the window that was focused longest

time ago.

previoustask

Sets focus to the window that was focused before

the currently focused window.

gotodesktop(Desktop number)

Sets current desktop to desktop specified by desk

top number parameter.

nextdesktop

Sets current desktop to desktop with number one

higher than current desktop. Current desktop is set to desktop 0

if no desktop with higher number than current desktop exists.

previousdesktop

Sets current desktop to desktop with number one

lower than current desktop. Current desktop is set to desktop

with highest number if no desktop with lower number than current

desktop exists.

exit Shutdowns waimea.

restart[(command line)]

Shutdowns waimea and executes command line parame

ter. If no command line parameter was given this action executes

the same command line as waimea was started with.

pointerrelativewarp(OffsetString)

Warps pointer relative to its current position.

MUST have an X offset string as parameter: [{+-}<xoff

set>{+-}<yoffset>] See X(7). The xoffset and yoffset values de

fines the number of pixels to warp the pointer.

pointerfixedmove(OffsetString)

Warp pointer to a fixed position. MUST have an X

offset string as parameter: [{+-}<xoffset>{+-}<yoffset>] See

X(7).

sition. {+-} signs defines pointer gravity.
nop Does nothing. But will when used as non-pass

through action on client window grab the event from the client.

Here is the list of additional actions for window.* win

dows:

raise Raise window to top of display stack.

raisefocus

Raise window to top of display stack and focus it.

lower Lower window to bottom of display stack.

startmove
startopaquemove

Move window by dragging the mouse. startmove action

will display a window outline while dragging the mouse and first

move the actual window when you're finished dragging. star

topaquemove action will move the actual window while you're drag

ging the mouse. Both must be ended with endmoveresize action.

startresizeright
startresizeleft
startopaqueresizeright
startopaqueresizeleft

Resize window by dragging the mouse. Actions not

containing 'opaque' will display a window outline while dragging

the mouse and first move the actual window when you're finished

dragging. Actions ending with 'opaque' will resize the actual

window while you're dragging the mouse. All four must be ended

with endmoveresize action.

endmoveresize

Ends a move or resize process.

close Sends a delete message to the client window. A nor

mal running X window should accept this event and destroy itself.

kill Tells the the X server to remove the window from

the screen through killing the process that created it.

closekill

Checks if the window will accept a delete message.

If it will, then we send a delete message to the client window

otherwise we tell the X server to kill the client that created

it.

menumap(menu_name)
menuremap(menu_name)
menuunmap(menu_name)
menumapfocused(menu_name) menuremapfocused(menu_name) menuunmapfocused(menu_name)

Map, remap or unmap a menu. Mapping a menu that is

already mapped will do nothing. Remapping a menu that is already

mapped will move the mapped menu to the new mapping position.

Actions ending with 'focused' will set input focus to the first

focusable menu item in the menu when being mapped. A menu must

be given as parameter to all these actions. Menu can be a dynam

ic menu.

shade
unshade
toggleshade

shade action will put window in shaded state. un

shade action will restore window from shaded to normal state.

toggleshade action will toggle between shaded and normal state.

In shaded state only the titlebar for the window is shown.

maximize
unmaximize
togglemaximize

maximize action will put window in maximized state.

unmaximize action will restore window from maximized to normal

state. togglemaximize action will toggle between maximized and

normal state. In maximized state the window will have maximum

allowed size fitted in screen.

sticky
unsticky
togglesticky

sticky action will put window in sticky state. un

sticky action will restore window from sticky to normal state.

togglesticky action will toggle between sticky and normal state.

In sticky state the window will stick to its position whatever

the viewport is.

decortitleon
decortitleoff
decortitletoggle

Turn on, off or toggle the window titlebar decora

tion.

decorhandleon
decorhandleoff
decorhandletoggle

Turn on, off or toggle the window handlebar decora

tion.

decorborderon
decorborderoff
decorbordertoggle

Turn on, off or toggle the window border decora

tion.

decorallon
decoralloff

Turn on or off all window decorations.

alwaysontopon
alwaysontopoff
alwaysontoptoggle

Turn on, off or toggle if window should be always

on top. Always on top windows are always at the top of the dis

play stack.

alwaysatbottomon
alwaysatbottomoff
alwaysatbottomtoggle

Turn on, off or toggle if window should be always

at bottom. Always at bottom windows are always at the bottom of

the display stack.

acceptconfigrequeston
acceptconfigrequestoff
acceptconfigrequesttoggle

Turn on, off or toggle if window should handle re

ceived configure request events.

moveresize(X11 geometry string) moveresizevirtual(X11 geometry string)

MUST have an X11 geometry string as parameter:

[<width>{xX}<height>][{+-}<xoffset>{+-}<yoffset>] See X(7). Sets

window geometry. moveresize action moves window to a actual

screen position. moveresizevirtual action moves window to a vir

tual screen position. A 'W' character in the OffsetString is re

placed with screenwidth. A 'H' character in the OffsetString is

replace with screenheight.

movetopointer

Moves center of window to mouse pointer position.

movetosmartplace

Moves window to position calculated by Smart Place

ment algorithm.

desktopmask(Desktop number list)

Sets desktop mask for window. Parameter should be a

whitespace separated list of desktop numbers. Window will only

appear in desktops specified by this list. To make window appear

in all desktops, replace list with the string `All'.

joindesktop(Desktop number)

Makes window a member of desktop specified by desk

top number parameter.

partdesktop(Desktop number)

Makes window not a member of desktop specified by

desktop number parameter.

partcurrentdesktop

Makes window not a member of current desktop.

joinalldesktops

Makes window a member of all desktops.

partalldesktopsexceptcurrent

Makes window not a member of all desktops except

the current desktop.

partcurrentjoindesktop(Desktop number)

Makes window not a member of current desktop and

instead makes it a member of desktop specified by desktop number

parameter.

Here is the list of additional actions for menu.* windows:

raise Raise menu to top of display stack.

lower Lower menu to bottom of display stack.

startmove
startopaquemove

Move menu by dragging the mouse. startmove action

will display a menu outline while dragging the mouse and first

move the actual menu when you're finished dragging. startopaque

move action will move the actual menu while you're dragging the

mouse. Both must be ended with endmoveresize action.

endmoveresize

Ends a move or resize process.

mapsub
mapsubonly
remapsub
mapsubfocused
mapsubfocusedonly
remapsubfocused
unmap
unmapfocused

Map, remap or unmap menu items submenu. If menu

item doesn't have a submenu, nothing is done. Mapping a submenu

that is already mapped will do nothing. Remapping a submenu that

is already mapped will move the mapped submenu to the new mapping

position. Actions ending with 'focused' will set input focus to

the first focusable window in the submenu when being mapped.

Actions ending with 'only' will unmap all other submenus before

mapping submenu.

unmapsubs

Unmaps the submenutree of the menu that contains

the menu item. Only linked menus are part of the submenutree and

will be unmapped by this action.

unmaptree

Unmaps the complete menutree that the menu contain

ing the menu item is part of. Only linked menus are part of the

menutree and will be unmapped by this action.

func Calls function linked to menu item. If menu item

doesn't have a linked function, nothing is done.

exec Executes command line linked to menu item. If menu

item doesn't have a linked command line, nothing is done.

unlink unlinks menu containing the menu item from its menu

tree.

Here is the list of additional actions for root, *edge

windows:

menumap(menu_name)
menuremap(menu_name)
menuunmap(menu_name)
menumapfocused(menu_name) menuremapfocused(menu_name) menuunmapfocused(menu_name)

Map, remap or unmap a menu. Mapping a menu that is

already mapped will do nothing. Remapping a menu that is already

mapped will move the mapped menu to the new mapping position.

Actions ending with 'focused' will set input focus to the first

focusable menu item in the menu when being mapped. A menu must

be given as parameter to all these actions.

Here is the list of event types that can be linked to an

action:

buttonpress

Occurs when a mouse button is pressed. Event de

tail for this event can be one of button1, button2, button3,

button4, button5, button6, button7 or anybutton.

buttonrelease

Occurs when a mouse button is released. Event de

tail for this event can be one of button1, button2, button3,

button4, button5, button6, button7 or anybutton.

doubleclick

Occurs when a mouse button is pressed two times

within time of the double click interval. Event detail for this

event can be one of button1, button2, button3, button4, button5,

button6, button7 or anybutton.

keypress

Occurs when a key is pressed. Event detail for

this event should be standard KeySym name obtained from

<X11/keysymdef.h> by removing the XK_ prefix from each name or

anykey.

keyrelease

Occurs when a key is released. Event detail for

this event should be standard KeySym name obtained from

<X11/keysymdef.h> by removing the XK_ prefix from each name or

anykey.

enternotify

Occurs when mouse enters a window. No event de

tails for this event type.

leavenotify

Occurs when mouse leaves a window. No event de

tails for this event type.

maprequest

Occurs when a window requests to be mapped. No

event details for this event type.

Here is the list of event modifiers that can used in the

modifier mask:

shiftmask
lockmask
controlmask
mod[1-5]mask
button[1-5]mask
moveresizemask
Any KeySym that is assigned to a modifier

Default action file is /usr/share/waimea/actions/action.

You can study or edit this action file to grasp how the action

system works.

MENUS

All menus used in the action file 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.

Waimea 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 support

[styledir], [reconfig] and [config] tags, these tags are not sup

ported by Waimea.

() = 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 in

clude 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: 0

Will be expanded to:

[item] (win name: windowname)

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

" "0 Window class name
"ost name for window owner
"" PID of window owner

If some window info isn't known for a window, the charac

ter 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
SHADED
STICKY
ALWAYSONTOP
ALWAYSATBOTTOM
DECORTITLE
DECORHANDLE
DECORBORDER
DECORALL

Taskswitcher
Predefined menu named "__windowlist__" can be used in menu

file and action file to access the taskswitcher menu.

Dynamic menus
Waimea 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/waimea/menu. You can

study or edit this menu file to grasp how the menu system works.

ENVIRONMENT

HOME Waimea uses this variable to find its .waimearc

file.

DISPLAY

When no other display was given on the command

line, waimea will start on the display specified by this vari

able.

FILES

~/.waimearc

User configuration file. See CONFIG FILE section

for further details.

/usr/share/waimea/config

The system wide configuration file. See CONFIG FILE

section for further details.

/usr/share/waimea/style/Default

The system wide style file. See STYLES section for

further details.

/usr/share/waimea/actions/action

The system wide action file. See ACTIONS section

for further details.

/usr/share/waimea/menu

The system wide menu file. See MENUS section for

further details.

BUGS

Bug reports, patches and suggestions are much appreciated,

send them to the author.

AUTHOR

David Reveman <david@waimea.org>

The Waimea website: http://www.waimea.org

SEE ALSO

blackbox(1), X(7)

0.4.0 Nov 06 2002

WAIMEA(1)