--- name: "waimea" section: "1" platform: "linux" package: "waimea" version: "0.4.0-7" release: "Debian 4.0 (Etch)" platforms: ["linux"] url: "https://new.carta.tech/waimea" --- # waimea(1) an X11 window manager designed for maximum efficiency ## NAME Waimea - an X11 window manager designed for maximum efficiency ## 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 textures. 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 configuration system makes *waimea* the most configurable window manager 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 resource. - **--actionfile ACTIONFILE** Use the alternate *ACTIONFILE* instead of */usr/share/waimea/actions/action.* This overrides actionFile resource. - **--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 dynamic 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 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 *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. 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 *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 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, X offset string of form: \[{+-}\{+-}\\]. See **[X(7)](/X/7.md).** - **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 *Waimea* enables you to use *blackbox* specialized style files that contain **[X(7)](/X/7.md)** 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 exist 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)](/X/7.md)** 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)](/X/7.md)** 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)](/X/7.md)** for how to write valid XLFD font names.\ e.g.: ``` -adobe-courier-medium-r-normal--10-100-75-75-m-60-iso8859-1 ``` The format for Xft font names is: ``` -:= [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 *waimea* 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 *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 image. 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 appear 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 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 *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. 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 *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 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 *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 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 *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 because *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 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\ 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 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/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 behavior. 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. ACTIONLINE 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 action 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 & ControlMask StartResize : ButtonPress = Button1 & Mod1Mask & !ControlMask ``` 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 second 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 actions for (to define individual actions for a specific window just replace 'window.\*' with n/Regexp/.\*, c/Regexp/.\* or t/Regexp/.\* 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) windows and *window.clientpassive* is the action list for passive (unfocused) windows. All actions for window.client.\* can be prefixed 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 handlebar. **window.leftgrip**\ **window.rightgrip** Windows for the left and right grip in the handlebar. **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 '}' character. 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: \[{+-}\{+-}\\] See **[X(7)](/X/7.md).** The xoffset and yoffset values defines 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: \[{+-}\{+-}\\] See **[X(7)](/X/7.md).** The xoffset and yoffset values defines the new viewport 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 desktop 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 parameter. 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: \[{+-}\{+-}\\] See **[X(7)](/X/7.md).** The xoffset and yoffset values defines the number of pixels to warp the pointer. - **pointerfixedmove(OffsetString)** Warp pointer to a fixed position. MUST have an X offset string as parameter: \[{+-}\{+-}\\] See **[X(7)](/X/7.md).** The xoffset and yoffset values defines the new pointer position. {+-} 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.\* windows: - **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. startopaquemove *action* will move the actual window while you're dragging 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 normal 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 dynamic menu. **shade**\ **unshade**\ **toggleshade** shade *action* will put window in shaded state. unshade *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. unsticky *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 decoration. **decorhandleon**\ **decorhandleoff**\ **decorhandletoggle** Turn on, off or toggle the window handlebar decoration. **decorborderon**\ **decorborderoff**\ **decorbordertoggle** Turn on, off or toggle the window border decoration. **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 display 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 received configure request events. **moveresize(X11 geometry string)**\ **moveresizevirtual(X11 geometry string)** MUST have an X11 geometry string as parameter: \[\{xX}\\]\[{+-}\{+-}\\] See **[X(7)](/X/7.md).** Sets window geometry. moveresize action moves window to a actual screen position. moveresizevirtual action moves window to a virtual screen position. A 'W' character in the OffsetString is replaced 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 Placement 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 desktop 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. startopaquemove *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 containing 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 detail 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 detail 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 \ 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 \ by removing the XK\_ prefix from each name or *anykey.* - **enternotify** Occurs when mouse enters a window. No event details for this event type. - **leavenotify** Occurs when mouse leaves a window. No event details 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 \. A \[checkbox\] tag is basically an \[item\] tag with two states. *Waimea* menu system is compatible with *[blackbox(1)](/blackbox/1.md)* menu system so higher level tags as \[begin\], \[exec\], \[submenu\], \[nop\], \[restart\] and \[exit\] are supported. *[blackbox(1)](/blackbox/1.md)* also support \[styledir\], \[reconfig\] and \[config\] tags, these tags are not supported by *Waimea.* () = menu item title\ "" = action\ {} = command line\ \<\> = sub menu e.g.: ``` [start] (menu) [title] (Menu) [item] (Xterm) {xterm} [sub] (Programs) [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] [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 *waimea* 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\ 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) ``` 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 variable. ## 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 \ The Waimea website: **http://www.waimea.org** ## SEE ALSO [**blackbox**(1)](/blackbox/1.md), [**X**(7)](/X/7.md)