--- layout: default title: User Guide - Configuration ---

## Chapter 4

# Configuring Window Maker

## 4.1 The Defaults System

WindowMaker uses a defaults database for storing various information, like configurations and other data that must be kept between sessions (like the list of applications of a saved session). The defaults database is stored as property lists in the $(HOME)/GNUstep/Defaults directory. Each file in the $(HOME)/GNUstep/Defaults directory contains data that belongs to a specific domain.
Any application can use the defaults database to store its information. Generally an application will have one or more domains that belong to it.

### 4.1.1 Property list File Format

The syntax of the property list is simple, but, if you need to change it manually you must take care not to leave any syntax errors.
The EBNF for the property list is the following:

### Description of the syntax of a property list in the Bacchus Naur Form (BNF)

<object> | ::= | <string> | <data> | <array> | <dictionary>
<string> | ::= | text with non-alphanumeric characters | alphanumeric text
<array> | ::= | `(' [ <object> { `,' <object> }* ] `)'
<dictionary> | ::= | `{' [ <keyval_pair> { `,' <keyval_pair> }* ] `}'
<keyval_pair> | ::= | <string> `=' <object> `;'

### Example property list file

     {
            "*" = {
                    Icon = "defaultAppIcon.xpm";
            };
            "xterm.XTerm" = {
                    Icon = "xterm.xpm";
            };
            xconsole = {
                    Omnipresent = YES;
                    NoTitlebar = YES;
                    KeepOnTop = NO;
            };
     }

The property list above is a dictionary with 3 dictionaries inside. The first is keyed by ``*'', the second by ``XTerm.xterm'' and the last by ``xconsole''.
Note that all strings that have non-alphabetic or numeric characters (like a dot ``.'' or the asterisk ``*'' are enclosed by double quotes. Strings with only alphanumeric characters may or may not be enclosed in double quotes, as they will not make any difference.
Here is another example:

    {
            FTitleBack = ( hgradient, gray, "#112233" );
    }

The property list in the example above contains an array with 3 elements with a key named ``FTitleBack''.
Except for cases like file names and paths, all value strings are case insensitive, i.e.: YES = Yes = yes = yEs

### 4.1.2 Value Types

Here is a description of some of the types of values that an option might have:

Type | Value
--- | ---
boolean | YES or NO
integer | any integer number, usually limited by a range that will be indicated
positive integer | any integer number greater than or equal to zero (0)
speed | UltraFast, Fast, Medium, Slow, or VerySlow
mouse button | Left, Middle, Right, Button1, Button2, Button3, Button4, or Button5

### 4.1.3 Preferences

General preference options are stored in the WindowMaker domain; i.e. the $(HOME)/GNUstep/Defaults/WindowMaker file.
Changes in preference options will automatically affect the current WindowMaker session, without a restart. Some options, however, require a restart of WindowMaker before they take effect. Such options are marked with a * .
Note that values marked as Default are values that are assumed if the option is not specified, instead of factory default values that are set in the preference file.

Option | Value | Description
--- | --- | ---
PixmapPath | list of directories separated by ":" (default: depends on the system) | A list of directories where pixmaps can be found. The pixmaps for things like icons, are searched in these paths in order of appearance.
*NoDithering | boolean (default: NO) | Disable internal dithering of images. Not recommended for displays with less than 8 bits per pixel.
*ColormapSize | integer number > 1 (default: 4) | Number of colors for each of the red, green and blue components to be used for the dithering colormap. This value must be greater than 1 and smaller than 6 for 8bpp displays. It only makes sense on PseudoColor displays. This option has not effect on TrueColor displays. Larger values result in better appearance, but leaves less colors for other applications.
*ModifierKey | modifier key name (default: Mod1) | The key to use as the modifier being referred as Meta in this manual, like Meta dragging a window to move it. Valid values are Alt, Meta, Super, Hyper, Mod1, Mod2, Mod3, Mod4, Mod5.
UseSaveUnders | boolean (default: NO) | Use saveunders in WindowMaker windows. This can improve performance but increases memory usage. It also can cause problems with refreshing in some applications.
DisableClip | boolean (default: NO) | Will remove the application Clip from the workspace.
DisableDock | boolean (default: NO) | Will remove the application Dock from the workspace
Superfluous | boolean (default: NO) | Enable extra animations and other cosmetic things that might increase peak memory and CPU usage.
SaveSessionOnExit | boolean (default: NO) | Automatically save the state of the session when exiting WindowMaker.
*IconSize | integer > 4 (default: 64) | The size of application icons and miniwindows.
OpaqueMove | boolean (default: NO) | Whether the whole window should be moved while dragging it, or, if only it's frame should be dragged.
FocusMode | Manual or CickToFocus, Auto or FocusFollowsMouse, SemiAuto or Sloppy (default: ClickToFocus) | The mode of input focus setting. Refer to section 2.2.1, Focusing a Window
IgnoreFocusClick | boolean (default: NO) | Whether the mouse click use to focus a window should be ignore or treated normally.
AutoFocus | boolean (default: NO) | Whether newly created windows should receive input focus. Do not confuse with FocusMode=Auto.
RaiseDelay | integer number (default: 0) | How many tenths of a second to wait before raising a window in Auto or Semi-Auto focus mode. 0 disables this feature.
DoubleClickTime | integer number (default: 250) | If two mouse clicks occur in this interval of time, it will be considered a double click.
ColorMapMode | Manual or ClickToFocus, Auto or FocusFollowsMouse (default: auto) | The mode of colormap setting. In Manual or ClickToFocus mode, the colormap is set to the one belonging to the current focused window. In Auto or FocusFollowsMouse mode, the colormap is set to the one belonging to the window under the pointer.
CirculateRaise | boolean (default: NO) | Whether the window should be raised when circulating. (focus the next or previous window through the keyboard)
OnTopTransients | boolean (default: NO) | Whether transient windows should always be placed over their owners
WindowPlacement | auto, cascade, manual, or random (default: cascade) | Sets placement mode for new windows. Auto places the window automatically in the first open space found in the workspace. Cascade places the window in incrementing positions starting from the the top-left corner of the workspace. Manual allows you to place the window interactively with the mouse. Random paces the window randomly in the workspace.
WindowPlaceOrigin | (X,Y) where X and Y are integer numbers (default: (0,0)) | Sets the offset, from the top-left corner of the screen, to place windows. In non-manual WindowPlacement modes windows will not be placed above or to the left of this point.
AutoArrangeIcons | boolean (default: NO) | Whether icons should be automatically arranged
ResizeDisplay | center, corner, floating, or line (default: corner) | Selects the type or position of the box that shows the window size when a window is being resized. center places the box in the center of the workspace, corner places it in the top-left corner of the workspace, floating places it in the center of the window being resized and line draws the current window size over the workspace, like in a technical drawing.
MoveDisplay | center, corner or floating (default: corner) | Selects the type or position of the box that shows the window position when a window is being moved. The value meanings are the same as for the ResizeDisplay option.
AlignSubmenus | boolean (default: NO) | Whether submenus should be aligned vertically with their parent menus.
WrapMenus | boolean (default: NO) | Whether submenus should be placed to the right of their parent menus when they don't fit the screen. Note that menus placed off the screen can be scrolled.
ScrollableMenus | boolean (default: NO) | Whether menus that are not fully inside the screen should automatically scroll when the pointer is over them and near the border of the screen.
MenuScrollSpeed | speed (default: medium) | The scrolling speed of menus.
DontLinkWorkspaces | boolean (default: NO) | Do not automatically switch to the next or previous workspace when a window is dragged to the edge of the screen.
NoWindowUnderDock | boolean (default: NO) | When maximizing windows, limit their sizes so that they will not be covered by the dock.
NoWindowOverIcons | boolean (default: NO) | When maximizing windows, limit their sizes so that they will cover miniwindows and application icons.
StickyIcons | boolean (default: NO) | Whether miniwindows should be present in all workspaces.
CycleWorkspaces | boolean (default: NO) | Set to YES if you want windows that are dragged past the last workspace to be moved to the first workspace, and vice-versa.
AdvanceToNewWorkspace | boolean (default: NO) | Whether windows dragged past the last workspace should create a new workspace.
DisableAnimations | boolean (default: NO) | Whether animations, like the one done during minimization, should be disabled.
IconSlideSpeed | speed (default: medium) | The speed of icons when they are being slid across the workspace.
ShadeSpeed | speed (default: medium) | The speed of the shading animation.
DisableSound | boolean (default: NO) | Whether sound support in WindowMaker should be disabled
*DisableWSMouseActions | boolean (default: NO) | Whether actions in the workspace triggered by mouse-clicks should be disabled. This allows the use of file and desktop managers that place icons on the root window (such as KDE).
SelectWindowMouseButton | mouse button (default: left) | The mouse button that activates selection of multiple windows in the workspace.
WindowListMouseButton | mouse button (default: middle) | The mouse button that opens the window list menu in the workspace.
ApplicationMenuMouseButton | mouse button (default: right) | The mouse button that opens the applications menu in the workspace.

### Appearance Options

Fonts are specified in the X Logical Font Description format. You can cut and paste these names from programs like xfontsel.
Colors are specified as color names in the standard X format. This can be any color name shown by the showrgb program (like black, white or gray) or a color value in the #rrggbb format, where rr, gg and bb is the intensity of the color component (like #ff0000 for pure red or #000080 for medium blue). Note that color names in the #rrggbb format must be enclosed with double quotes.
Textures are specified as an array, where the first element specifies the texture type followed by a variable number of arguments.
Valid texture types are:

(solid, color) | the texture is a simple solid color.
(dgradient, color1, color2) | the texture is a diagonal gradient rendered from the top-left corner to the bottom-right corner. The first argument (color1) is the color for the top-left corner and the second (color2) is for the bottom-right corner.
(hgradient, color1, color2) | the texture is a horizontal gradient rendered from the left edge to the right edge. The first argument (color1) is the color for the left edge and the second (color2) is for the right edge.
(vgradient, color1, color2) | the texture is a vertical gradient rendered from the top edge to the bottom edge. The first argument (color1) is the color for the top edge and the second (color2) is for the bottom edge.
(mdgradient, color1, color2,...,colorn) | this is equivalent to drgadient, but you can specify more than two colors
(mhgradient, color1, color2,...,colorn) | this is equivalent to hrgadient, but you can specify more than two colors
(mvgradient, color1, color2,...,colorn) | this is equivalent to vrgadient, but you can specify more than two colors

Examples:

| (solid, gray)
| (dgradient, gray80, gray20)
| (hgradient, gray80, gray20)
| (vgradient, gray80, gray20)

Option | Value | Description
--- | --- | ---
*NewStyle | boolean (default: NO) | Selects between N*XTSTEP style buttons in the titlebar and a newer style of buttons.
WidgetColor | (solid, color) where color is a color name (default: (solid, grey)) | Chooses the color to be used in titlebar buttons if NewStyle=No;
WorkspaceBack | a texture or none (default: none) | Default texture for the workspace background. Note the dgradient and mdgradient textures can take a lot of time to be rendered.
IconBack | texture (default: (solid, grey)) | Texture for the background of icons and miniwindows.
FTitleBack | texture (default: (solid, black)) | Texture for the focused window titlebar.
PTitleBack | texture (default: (solid, "#616161")) | Texture for the titlebar of the parent window of the currently focused transient window
UTitleBack | texture (default: (solid, gray)) | Texture for unfocused window titlebars.
MenuTitleBack | texture (default: (solid, black)) | Texture for menu titlebars.
MenuTextBack | texture (default: (solid, gray)) | Texture for menu items
FTitleColor | color (default: white) | The color of the text in the focused window titlebar.
PTitleColor | color (default: white) | Color for the text in the titlebar of the parent window of the currently focused transient.
UTitleColor | color (default: black) | The color for the text in the titlebar of unfocused windows.
MenuTitleColor | color (default: white) | Color for the text in menu titlebars
MenuTextColor | color (default: black) | Color for the text in menu items
HighlightColor | color (default: white) | Color for the highlighted item in menus.
HighlightTextColor | color (default: black) | Color for the highlighted item text in menus.
MenuDisabledColor | color (default: "#616161") | Color for the text of disabled menu items.
ClipTitleColor | color (default: black) | Color for the text in the clip.
CClipTitleColor | color (default: "#454045") | Color for the text in the collapsed clip.
WindowTitleFont | font (default: Helvetica bold 12) | Font for the text in window titlebars.
MenuTitleFont | font (default: Helvetica bold 12) | Font for the text in menu titlebars)
MenuTextFont | font (default: Helvetica medium 12) | Font for the text in menu items
IconTitleFont | font (default: Helvetica medium 8) | Font for the text in miniwindow titlebars.
ClipTitleFont | font (default: Helvetica bold 10) | Font for the text in the clip.
Displayfont | font (default: Helvetica medium 12) | Font for the text information in windows, like the size of windows during resize.
TitleJustify | center, left, or right (default: center) | Justification of the text in window titlebars.

### Keyboard Bindings

Keyboard shortcut specifications are in the form:

            [<modifier key names> + ] <key name>

Where modifier key names specify an optional modifier key, like Meta or Shift. Any number of modifier keys might be specified. The key name is the actual key that will trigger the action bound to the option.
Examples:

[F10] | Means the F10 key.
Meta+TAB | Means the TAB key with the Meta modifier key pressed at the same time.
Meta+Shift+TAB | Means the TAB key with the Meta and Shift modifier keys pressed at the same time.

Key names can be found at /usr/X11R6/include/X11/keysymdef.h The XK_ prefixes must be ignored (if key name is XK_Return use Return).

Option | Default Value | Description
--- | --- | ---
RootMenuKey | None | Opens the root window menu at the current position of the mouse pointer.
WindowListKey | None | Opens the window list menu menu at the current position of the mouse pointer.
WindowMenuKey | None | Opens the window commands menu for the currently focused window.
MiniaturizeKey | None | Miniaturizes the currently focused window.
HideKey | None | Hides the currently active application.
CloseKey | None | Closes the current focused window
MaximizeKey | None | Maxmizes the currently focused window.
VMaximizeKey | None | Vertically Maximizes the currently focused window.
RaiseKey | Meta+Up | Raises the currently focused window.
LowerKey | Meta+Down | Lowers the currently focused window.
RaiseLowerKey | None | Raises the window under the pointer, or lowers it if it is already raised.
ShadeKey | None | Shades the currently focused window.
SelectKey | None | Selects current focused window.
FocusNextKey | None | Switch focus to next window.
FocusPrevKey | None | Switch focus to previous window.
NextWorkspaceKey | None | Switches to next workspace.
PrevWorkspaceKey | None | Switches to previous workspace.
NextWorkspaceLayerKey | None | Switches to the next group of 10 workspaces.
PrevWorkspaceLayerKey | None | Switches to the previous group of 10 workspaces.
Workspace1Key | None | Switches to workspace 1.
Workspace2Key | None | Switches to workspace 2, creating it if it does not exist.
Workspace3Key | None | Switches to workspace 3, creating it if it does not exist.
Workspace4Key | None | Switches to workspace 4, creating it if it does not exist.
Workspace5Key | None | Switches to workspace 5, creating it if it does not exist.
Workspace6Key | None | Switches to workspace 6, creating it if it does not exist.
Workspace7Key | None | Switches to workspace 7, creating it if it does not exist.
Workspace8Key | None | Switches to workspace 8, creating it if it does not exist.
Workspace9Key | None | Switches to workspace 9, creating it if it does not exist.
Workspace10Key | None | Switches to workspace 10, creating it if it does not exist.
ClipLowerKey | None | Lowers the clip.
ClipLowerKey | None | Lowers the clip.
ClipRaiseLowerKEy | None | Raises the clip, or lowers it if it is already raised.

### 4.1.4 Window Attributes

Window attributes are stored in the $(HOME)/GNUstep/Defaults/WMWindowAttributes file.
The contents of this file is a dictionary of attribute dictionaries keyed by window names. Like this:

    {
            "*" = {
                    Icon = "defaultAppIcon.xpm";
            };
            "xterm.XTerm" = {
                    Icon = "xterm.xpm";
            };
            xconsole = {
                    Omnipresent = YES;
                    NoTitlebar = YES;
                    KeepOnTop = NO;
            };
    }

Window names are in the form1:
<window instance name>.<window class name>
OR
<window instance name>
OR
<window class name>
Placing an asterisk as the window name means that the values set for that key are to be used as default values for all windows. So, since xconsole does not specify an Icon attribute, it will use the default value, which in the above example is defaultAppIcon.xpm.

1 You can get the values for these information by running the xprop utility on the desired window. When you do that, it will show the following line, among other things:
WM_CLASS(STRING) = "xterm", "XTerm"
The first string (xterm) is the window instance name and the second (XTerm) the window class name.}

### Options:

The default is NO for all options

Option | Value | Description
--- | --- | ---
Icon | pixmap file name | Assigns a pixmap image to be used as the icon for that window.
NoTitleBar | boolean | Disables the titlebar in the window.
NoResizeBar | boolean | Disables the resizebar in the window.
NoMiniaturizeButton | boolean | Remove the miniaturize button.
NoCloseButton | boolean | Remove the close button.
NoHideOthers | boolean | Do not hide the window, or the application to which the window belongs when a Hide Others command is issued.
NoMouseBindings | boolean | Do not grab mouse buttons in that window. This means that actions like a Meta-click on the window will be caught by the application instead of WindowMaker.
NoKeyBindings | boolean | Do not grab keys in that window. This means that keystrokes that would normally be intercepted by WindowMaker (because they are bound to some action), like Meta+Up, will be passed to the application.
NoAppIcon | boolean | Do not create application icon for the window. This is useful for some applications that incorrectly get more than one application icon.
KeepOnTop | boolean | Always keep the window over other normal windows.
Omnipresent | boolean | Make the window be present in all workspaces, AKA sticky window.
SkipWindowList | boolean | Do not list the window in the window list menu.
KeepInsideScreen | boolean | Always keep the window inside the visible are of the screen.
Unfocusable | boolean | Do not let the window be focused.
StartWorkspace | Workspace number or name | Make the window always be initially shown in the indicated workspace.

### 4.1.5 Applications Menu

The applications menu (AKA: Root Menu) can be defined in one of two distinct ways:

- In the form of an array in property list format, in $(HOME)/GNUstep/Defaults/WMRootMenu
- In the form of a text file, whose location is present in $(HOME)/GNUstep/Defaults/WMRootMenu