Chapter 8. The main config file

Table of Contents
8.1. Basic Config
8.2. Config File Keywords
8.3. Screen Subsections

The main config file is where all the base config stuff goes.

8.1. Basic Config

As previously indicated, the config file follows the rules defined in Common Syntax.

Here's an example ~/.pekwm/config file:

Files {
	Keys = "~/.pekwm/keys"
	Mouse = "~/.pekwm/mouse"
	Menu = "~/.pekwm/menu"
	Start = "~/.pekwm/start"
	AutoProps = "~/.pekwm/autoproperties"
	Theme = "~/.pekwm/themes/default"
	Icons = "~/.pekwm/icons/"
}

MoveResize {
	EdgeAttract = "10"
	EdgeResist = "10"
	WindowAttract = "5"
	WindowResist = "5"
	OpaqueMove = "True"
	OpaqueResize = "False"
}

Screen {
	Workspaces = "4"
	WorkspacesPerRow = "2"
	WorkspaceNames = "Main;Web;E-mail;Music"
	ShowFrameList = "True"
	ShowStatusWindow = "True"
	ShowStatusWindowCenteredOnRoot = "False"
	ShowClientID = "False"
	ShowWorkspaceIndicator = "500"
	FocusNew = "True"
	PlaceNew = "True"

	TrimTitle = "..."
	FullscreenAbove = "True"
	FullscreenDetect = "True"
	HonourRandr = "True"
	HonourAspectRatio = "True"
	EdgeSize = "1 1 1 1"
	EdgeIndent = "False"
	PixmapCacheSize = "20"
	DoubleClickTime = "250"

	Placement {
		Model = "Smart"
		WorkspacePlacements = "Smart;MouseCentered"
		TransientOnParent = "True"
		Smart {
			Row = "False"
			TopToBottom = "True"
			LeftToRight = "True"
			OffsetX = "0"
			OffsetY = "0"
		}
	}

	UniqueNames {
		SetUnique = "True"
		Pre = " #"
		Post = ""
	}
}

Menu {
	DisplayIcons = "True"

	Icons = "DEFAULT" {
		Minimum = "16x16"
		Maximum = "16x16"
	}

	Select = "Motion"
	Enter = "Motion ButtonPress"
	Exec = "ButtonRelease"
}

CmdDialog {
	HistoryUnique = "True"
	HistorySize = "1024"
	HistoryFile = "~/.pekwm/history"
	HistorySaveInterval = "16"
}

Harbour {
	OnTop = "True"
	MaximizeOver = "False"
	Placement = "Right"
	Orientation = "TopToBottom"
	Head = "0"

	DockApp {
		SideMin = "64"
		SideMax = "0"
	}
}

8.2. Config File Keywords

Here's a table showing the different elements that can be used in your config file. Remember that 'boolean' means 'true' or 'false' and that all values should be placed inside quotes.

Config File Elements under the Files-section:

Keys (string)

The location of the keys file, such as ~/.pekwm/keys

Menu (string)

The location of the menu file, such as ~/.pekwm/menu

Start (string)

The location of the start file, such as ~/.pekwm/start

AutoProps (string)

The location of the autoprops file, such as ~/.pekwm/autoproperties

Theme (string)

The location of the Theme directory, such as ~/.pekwm/themes/themename

Icons (string)

The location of the Icons directory, such as ~/.pekwm/icons

Config File Elements under the MoveResize-section:

EdgeAttract (int)

The distance from screen edge required for the window to snap against it in pixels.

EdgeResist (int)

The distance from screen edge required for the window moving to start being resisted in pixels.

WindowAttract (int)

The distance from other clients that a window will snap against them to in pixels.

WindowResist (int)

The distance from other clients that a window movement will start being resisted.

OpaqueMove (boolean)

If true, turns on opaque Moving

OpaqueResize (boolean)

If true, turns on opaque Resizing

Config File Elements under the Screen-section:

Workspaces (int)

Number of workspaces enabled.

WorkspacesPerRow (int)

Number of workspaces on each row. Value < 1 fits all workspaces on a single row.

WorkspaceNames (string)

List of names for workspaces separated by ;.

ShowFrameList (boolean)

Controls whether a list of all available frames on the workspace is displayed during the NextFrame/PrevFrame actions.

ShowStatusWindow (boolean)

Controls whether a size/position info window is shown when moving or resizing windows.

ShowStatusWindowCenteredOnRoot (boolean)

Controls whether a size/position info window is shown centered on the current head or the current window.

ShowClientID (boolean)

Should Client IDs be displayed in window titles.

ShowWorkspaceIndicator (int)

Show WorkspaceIndicator for N milliseconds. If set to < 1, the WorkspaceIndicator is disabled.

WorkspaceIndicatorScale (int)

Changes the size of the WorkspaceIndicator, higher value means smaller size.

WorkspaceIndicatorOpacity (int)

Sets the opacity/transparency of the WorkspaceIndicator. A value of 100 means completely opaque, while 0 stands for completely transparent.

Note that a Composite Manager needs to be running for this feature to take effect.

FocusNew (boolean)

Toggles if new windows should be focused when they pop up.

FocusNewChild (boolean)

Toggles if new transient windows should be focused when they pop up if the window they are transient for is focused.

PlaceNew (boolean)

Toggles if new windows should be placed using the rules found in the Placement subsection, or just opened on the top left corner of your screen.

ReportAllClients (boolean)

Toggles if all clients in a frame or only the active one should be reported and thus displayed in pager applications etc.

TrimTitle (string)

This string contains what pekwm uses to trim down overlong window titles. If it's empty, no trimming down is performed at all.

FullscreenAbove (boolean)

Toggles restacking of windows when going to and from fullscreen mode. Windows are restacked to the top of all windows when going to fullscreen and to the top of their layer when being restored from fullscreen.

FullscreenDetect (boolean)

Toggles detection of broken fullscreen requests setting clients to fullscreen mode when requesting to be the size of the screen. Default true.

HonourRandr (boolean)

Toggles reading of XRANDR information, this can be disabled if the display driver gives both Xinerama and Randr information and only of the two is correct. Default true.

HonourAspectRatio (boolean)

Toggles if pekwm respects the aspect ratio of clients (XSizeHints). Default true.

EdgeSize (int) (int) (int) (int)

How many pixels from the edge of the screen should screen edges be. Parameters correspond to the following edges: top bottom left right. A value of 0 disables edges.

EdgeIndent (boolean)

Toggles if the screen edge should be reserved space.

PixmapCacheSize (int)

Determines how many unused pixmaps are stored on the image cache for future use.

DoubleClicktime (int)

Time, in milliseconds, between clicks to be counted as a doubleclick.

Config File Elements under the Placement-subsection of the Screen-section:

TransientOnParent (bool)

Set to true if you want the transient windows to be mappend on their "parent" window (tiling layouters might ignore this option).

Model (string)

  • Smart - Tries to place windows where no other window is present

  • MouseCentered - Places the center of the window underneath the current mouse pointer position

  • MouseTopLeft - Places the top-left corner of the window under the pointer

  • MouseNotUnder - Places windows on screen corners avoiding the current mouse cursor position.

  • CenteredOnParent - Places transient windows at center of their parent window.

WorkspacePlacements (string)

List of placement models for the workspaces separated by ;. For an explanation of the allowed options see "Model" above.

Config File Elements under the Smart-subsection of the Placement-subsection:

Row (boolean)

Whether to use row or column placement, if true, uses row.

TopToBottom (boolean)

If false, the window is placed starting from the bottom.

LeftToRight (boolean)

If false, the window is placed starting from the right.

OffsetX (int)

Pixels to leave between new and old windows and screen edges. When 0, no space is reserved.

OffsetY (int)

Pixels to leave between new and old windows and screen edges. When 0, no space is reserved.

Config File Elements under the UniqueNames-subsection of the Screen-section:

SetUnique (boolean)

Decides if the feature is used or not. False or True.

Pre (string)

String to place before the unique client number.

Post (string)

String to place after the unique client number.

Config File Elements under the CmdDialog-section:

HistoryUnique (boolean)

If true, identical items in the history will only appear once where the most recently used is the first item. Default true.

HistorySize (integer)

Number of entries in the history that should be kept track of. Default 1024.

HistoryFile (string)

Path to history file where history is persisted between session. Default ~/.pekwm/history

HistorySaveInterval (int)

Defines how often the history file should be saved counting each time the CmdDialog finish a command. Default 16.

Config File Elements under the Menu-section:

DisplayIcons (boolean)

Defines wheter menus should render their icons. Default true.

FocusOpacity (int)

Sets the opacity/transparency for focused Menus. A value of 100 means completely opaque, while 0 stands for completely transparent.

UnfocusOpacity (int)

Sets the opacity/transparency for unfocused Menus.

Icons = "MENU"

Minimum (width x height)

Defines minimum size of icons, if 0x0 no check is done. Default 16x16.

Maximum (width x height)

Defines maximum size of icons, if 0x0 no check is done. Default 16x16.

Select (list of strings)

Decides on what mouse events to select a menu entry. List is space separated and can include "ButtonPress, ButtonRelease, DoubleClick, Motion, MotionPressed"

Enter (list of strings)

Decides on what mouse events to enter a submenu. List is space separated and can include "ButtonPress, ButtonRelease, DoubleClick, Motion, MotionPressed"

Exec (list of strings)

Decides on what mouse events to execute an entry. List is space separated anc can include "ButtonPress, ButtonRelease, DoubleClick, Motion, MotionPressed"

Config File Elements under the Harbour-section:

Placement (string)

Which edge to place the harbour on. One of Right, Left, Top, or Bottom.

Orientation (string)

From what to which direction the harbour expands. One of TopToBottom, BottomToTop, RightToLeft, LeftToRight.

OnTop (boolean)

Whether or not the harbour is "always on top"

MaximizeOver (boolean)

Controls whether maximized clients will cover the harbour (true), or if they will stop at the edge of the harbour (false).

Head (int)

When RandR or Xinerama is on, decides on what head the harbour resides on. Integer is the head number.

Opacity (int)

Sets the opacity/transparency for the harbour. A value of 100 means completely opaque, while 0 stands for completely transparent.

Config File Elements under the DockApp-subsection of the Harbour-section:

SideMin (int)

Controls the minimum size of dockapp clients. If a dockapp client is smaller than the minimum, it gets resized up to the SideMin value. Integer is a number of pixels.

SideMax (int)

Controls the maximum size of dockapp clients. If a dockapp client is larger than the maximum, it gets resized down to the SideMax value. Integer is a number of pixels.

8.3. Screen Subsections

There are two subsections in the screen section - Placement and UniqueNames. Placement can optionally have its own subsection. Sounds hard? It's not! It's really quite simple.

We'll start off with Placement. Placement has two options: Model, and a 'Smart' subsection. Model is very simple, it's simply a list of keywords that describes how to place new windows, such as "Smart MouseCentered". Secondly, there's a Smart section, which describes how pekwm computes where to place a new window in smart mode.

The second subsection, UniqueNames, lets you configure how pekwm should handle similar client names. Pekwm can add unique number identifiers to clients that have the same title so that instead of "terminal" and "terminal", you would end up with something like "terminal" and "terminal [2]".