pekwm documentation: documentation for version pekwm-0.1.12, last updated April 08, 2010. ; Authors: | ||
---|---|---|
Prev | Next |
Pekwm allows you to remap almost all keyboard and mouse events.
The pekwm Mousebindings go in ~/.pekwm/mouse, and are very simple. They're divided up into two groups: The 'where' and 'event'. Below is an example file:
FrameTitle { ButtonRelease = "1" { Actions = "Raise; Focus; ActivateClient" } ButtonRelease = "2" { Actions = "ActivateClient" } ButtonRelease = "Mod4 3" { Actions = "Close" } ButtonRelease = "3" { Actions = "ShowMenu Window" } ButtonRelease = "4" { Actions = "ActivateClientRel 1" } ButtonRelease = "5" { Actions = "ActivateClientRel -1" } DoubleClick = "2" { Actions = "Toggle Shaded" } DoubleClick = "1" { Actions = "MaxFill True True" } Motion = "1" { Threshold = "4"; Actions = "Move" } Motion = "Mod1 1" { Threshold = "4"; Actions = "Move" } Motion = "Mod4 1" { Threshold = "4"; Actions = "Move" } Motion = "2" { Threshold = "4"; Actions = "GroupingDrag True" } Motion = "Mod1 3" { Actions = "Resize" } Enter = "Any Any" { Actions = "Focus" } } OtherTitle { ButtonRelease = "1" { Actions = "Raise; Focus; ActivateClient" } ButtonRelease = "Mod4 3" { Actions = "Close" } DoubleClick = "2" { Actions = "Toggle Shaded" } DoubleClick = "1" { Actions = "MaxFill True True" } Motion = "1" { Threshold = "4"; Actions = "Move" } Motion = "Mod1 1" { Threshold = "4"; Actions = "Move" } Motion = "Mod4 1" { Threshold = "4"; Actions = "Move" } Motion = "Mod1 3" { Actions = "Resize" } Enter = "Any Any" { Actions = "Focus" } } Border { TopLeft { Enter = "Any Any" { Actions = "Focus" }; ButtonPress = "1" { Actions = "Resize TopLeft" } } Top { Enter = "Any Any" { Actions = "Focus" }; ButtonPress = "1" { Actions = "Move" } } TopRight { Enter = "Any Any" { Actions = "Focus" }; ButtonPress = "1" { Actions = "Resize TopRight" } } Left { Enter = "Any Any" { Actions = "Focus" }; ButtonPress = "1" { Actions = "Resize Left" } } Right { Enter = "Any Any" { Actions = "Focus" }; ButtonPress = "1" { Actions = "Resize Right" } } BottomLeft { Enter = "Any Any" { Actions = "Focus" }; ButtonPress = "1" { Actions = "Resize BottomLeft" } } Bottom { Enter = "Any Any" { Actions = "Focus" }; ButtonPress = "1" { Actions = "Resize Bottom" } } BottomRight { Enter = "Any Any" { Actions = "Focus" }; ButtonPress = "1" { Actions = "Resize BottomRight" } } } ScreenEdge { Down { ButtonRelease = "3" { Actions = "ShowMenu Root" } ButtonRelease = "2" { Actions = "ShowMenu Goto" } } Up { ButtonRelease = "3" { Actions = "ShowMenu Root" } ButtonRelease = "2" { Actions = "ShowMenu Goto" } ButtonRelease = "Mod1 4" { Actions = "GoToWorkspace Right" } ButtonRelease = "Mod1 5" { Actions = "GoToWorkspace Left" } } Left { Enter = "Mod1 Any" { Actions = "GoToWorkspace Left" } ButtonRelease = "3" { Actions = "ShowMenu Root" } ButtonRelease = "1" { Actions = "GoToWorkspace Left" } DoubleClick = "1" { Actions = "GoToWorkspace Left" } ButtonRelease = "2" { Actions = "ShowMenu Goto" } ButtonRelease = "4" { Actions = "GoToWorkspace Right" } ButtonRelease = "5" { Actions = "GoToWorkspace Left" } } Right { Enter = "Mod1 Any" { Actions = "GoToWorkspace Right" } ButtonRelease = "3" { Actions = "ShowMenu Root" } ButtonRelease = "1" { Actions = "GoToWorkspace Right" } DoubleClick = "1" { Actions = "GoToWorkspace Right" } ButtonRelease = "2" { Actions = "ShowMenu Goto" } ButtonRelease = "4" { Actions = "GoToWorkspace Right" } ButtonRelease = "5" { Actions = "GoToWorkspace Left" } } } Client { ButtonPress = "1" { Actions = "Focus" } ButtonRelease = "Mod1 1" { Actions = "Focus; Raise" } ButtonRelease = "Mod4 1" { Actions = "Lower" } Motion = "Mod1 1" { Actions = "Focus; Raise; Move" } Motion = "Mod4 1" { Actions = "Focus; Raise; Move" } Motion = "Mod1 2" { Threshold = "4"; Actions = "GroupingDrag True" } Motion = "Mod1 3" { Actions = "Resize" } Enter = "Any Any" { Actions = "Focus" } } Root { ButtonRelease = "3" { Actions = "ShowMenu Root" } ButtonRelease = "2" { Actions = "ShowMenu Goto" } ButtonRelease = "4" { Actions = "GoToWorkspace Right" } ButtonRelease = "5" { Actions = "GoToWorkspace Left" } ButtonRelease = "1" { Actions = "HideAllMenus" } } Menu { Enter = "Any Any" { Actions = "Focus" } ButtonRelease = "2" { Actions = "Toggle Sticky" } Motion = "1" { Threshold = "10"; Actions = "Move" } ButtonRelease = "3" { Actions = "Close" } } Other { Enter = "Any Any" { Actions = "Focus" } ButtonRelease = "Mod4 3" { Actions = "Close" } Motion = "1" { Actions = "Focus; Raise; Move" } Motion = "Mod1 1" { Actions = "Focus; Raise; Move" } } |
Below are defined the different fields. The actions themselves can be found in the Keys/mouse actions section.
'Where' fields:
On a regular window's Titlebar.
On menu/cmdDialog/etc pekwm's own window's Titlebar.
On the window's borders. See Border Subsection for more information.
On the screen edges. See ScreenEdge Subsection for more information.
Anywhere on the window's interior. It's best to use a keyboard modifier with these.
On the Root window (also called the 'desktop').
On the various menus excluding their titlebars.
On everything else that doesn't have it's own section.
'Event' fields:
A single click
A single click that activates once the button is released
A double click
Clicking, holding, and Dragging.
Defines how to act when mouse pointer enters a place defined by the 'where' field.
Defines how to act when mouse pointer leaves a place defined by the 'where' field.
Defines how to act when a dragged window enters a ScreenEdge. Only works with screen edges.
Definitions work like this:
'Where' { 'Event' = "optional modifiers, like mod1, ctrl, etc and a mouse button" { Actions = "actions and their parameters" } 'Event' = "optional modifiers, like mod1, ctrl, etc and a mouse button" { Actions = "actions and their parameters" } } |
Additional notes.
Modifiers and mouse buttons can be defined as "Any" which is useful for Enter and Leave events. Any also applies as none. Motion events have a threshold argument. This is the number of pixels you must drag your mouse before they begin to work. Multiple actions can be defined for a single user action. Example:
Motion = "1" { Actions = "Move"; Treshold = "3" } ButtonPress = "1" { Actions = "Raise; ActivateClient" } |
The Border subsection in ~/.pekwm/mouse defines the actions to take when handling the window borders.
Border { TopLeft { Enter = "Any Any" { Actions = "Focus" } ButtonPress = "1" { Actions = "Resize TopLeft" } } } |
It's subsections refer to the frame part in question. They are: Top, Bottom, Left, Right, TopLeft, TopRight, BottomLeft, and BottomRight. In these subsections you can define events and actions as usual.
The ScreenEdge subsection in ~/.pekwm/mouse defines the actions to take when an event happens on the specified screenedge.
ScreenEdge { Left { Enter = "Mod1 Any" { Actions = "GoToWorkspace Left" } ButtonPress = "3" { Actions = "ShowMenu Root" } ButtonPress = "1" { Actions = "GoToWorkspace Left" } ButtonPress = "2" { Actions = "ShowMenu Goto" } ButtonPress = "4" { Actions = "GoToWorkspace Right" } ButtonPress = "5" { Actions = "GoToWorkspace Left" } } } |
It has four subsections: Up, Down, Left, and Right, that all refer to the screen edge in question. In these subsections you can give events and actions as usual.
The pekwm keybindings go in ~/.pekwm/keys, and are even more simple than the mouse bindings. Here's the format:
KeyPress = "optional modifiers like mod1, ctrl, etc and the key" { Actions = "action and the parameters for the action, if they are needed" } |
Multiple actions can be given for one keypress. The actions are separated from each other with a semicolon:
Keypress = "Ctrl t" { Actions = "Exec xterm; Set Maximized True True; Close" } |
Here's a small fragment of an example keys file; you can see a full version in ~/.pekwm/keys. As with the mouse, you can see the full list of actions in the Keys/mouse actions section.
Global { # Moving in frames KeyPress = "Mod1 Tab" { Actions = "NextFrame EndRaise" } KeyPress = "Mod1 Shift Tab" { Actions = "PrevFrame EndRaise" } KeyPress = "Mod1 Ctrl Tab" { Actions = "NextFrameMRU EndRaise" } KeyPress = "Mod1 Ctrl Shift Tab" { Actions = "PrevFrameMRU EndRaise" } # Simple window management KeyPress = "Mod4 M" { Actions = "Toggle Maximized True True" } KeyPress = "Mod4 G" { Actions = "Maxfill True True" } KeyPress = "Mod4 F" { Actions = "Toggle FullScreen" } KeyPress = "Mod4 Return" { Actions = "MoveResize" } # Wm actions Chain = "Ctrl Mod1 P" { KeyPress = "Delete" { Actions = "Reload" } KeyPress = "Next" { Actions = "Restart" } KeyPress = "End" { Actions = "Exit" } KeyPress = "Prior" { Actions = "RestartOther twm" } } } MoveResize { KeyPress = "Left" { Actions = "MoveHorizontal -10" } KeyPress = "Right" { Actions = "MoveHorizontal 10" } KeyPress = "Up" { Actions = "MoveVertical -10" } KeyPress = "Down" { Actions = "MoveVertical 10" } Keypress = "Mod4 Left" { Actions = "ResizeHorizontal -10" } Keypress = "Mod4 Right" { Actions = "ResizeHorizontal 10" } Keypress = "Mod4 Up" { Actions = "ResizeVertical -10" } Keypress = "Mod4 Down" { Actions = "ResizeVertical 10" } Keypress = "s" { Actions = "MoveSnap" } Keypress = "Escape" { Actions = "Cancel" } Keypress = "Return" { Actions = "End" } } Menu { KeyPress = "Down" { Actions = "NextItem" } KeyPress = "Up" { Actions = "PrevItem" } KeyPress = "Left" { Actions = "LeaveSubmenu" } KeyPress = "Right" { Actions = "EnterSubmenu" } KeyPress = "Return" { Actions = "Select" } KeyPress = "Escape" { Actions = "Close" } } InputDialog { KeyPress = "BackSpace" { Actions = "Erase" } KeyPress = "Right" { Actions = "CursNext" } KeyPress = "Left" { Actions = "CursPrev" } KeyPress = "Up" { Actions = "HistPrev" } KeyPress = "Down" { Actions = "HistNext" } KeyPress = "Delete" { Actions = "Clear" } KeyPress = "Return" { Actions = "Exec" } KeyPress = "Escape" { Actions = "Close" } KeyPress = "Any Any" { Actions = "Insert" } } |
As you might have noticed, the file consist of four sections. These sections are Global, MoveResize, Menu and InputDialog. The first section, Global, contains all the generic actions.
The MoveResize section has the keybindings that will get used when the MoveResize action is called.
Menu section contains the keys that are used when the ShowMenu action is called. E.g. these are the keys you use to browse thru the menus of pekwm. Note that while ShowMenu is active, the Global keybindings are also listened. If a keybinding is same in both Menu and Global sections, keybindings in Menu section override the global keybinding as long as a menu is active.
Finally, the InputDialog section allow for tuning of what keys are available for line editing when the CmdDialog window that enables the user to enter pekwm actions for running windows is active.
Keys can be identified with their XString name or with their keycode. Both can be found out using the X application xev. If you want to use a keycode, prefix it with #.
Pekwm also supports keychains. Keychain syntax follows the general config syntax and looks like this:
Chain = "modifiers and key" { Chain = "modifiers and key" { KeyPress = "modifiers and key" { Actions = "actions and their parameters" } } Keypress = "modifiers and key" { Actions = "actions and their parameters" } } |
It might seem complicated at start but once you look into it, it is fairly nice and logical. This syntax supports as many nested Chains as you might want.
Now for some examples. Here we have a simple nested chain that lets you press Ctrl+Alt+M, then M, then M, V or H to toggle maximized attribute into Full/Vertical or Horizontal, and a simpler one level chain that brings up the root menu.
Chain = "Ctrl Mod1 A" { Chain = "M" { KeyPress = "M" { Actions = "Toggle Maximized True True" } KeyPress = "V" { Actions = "Toggle Maximized False True" } KeyPress = "H" { Actions = "Toggle Maximized True False" } } } Chain = "Ctrl Mod1 M" { KeyPress = "R" { Actions = "ShowMenu Root" } } |
This next rule is a pure show-off, it lets you type in 'test' and then executes xterm. Note that this will make you unable to type the character 't' to any programs.
Chain = "t" { Chain = "e" { Chain = "s" { Keypress = "t" { Actions = "Exec xterm" } } } } |
Here is the list of all possible actions and attributes. First table shows all toggleable attributes. Toggleable attributes are controlled using the Set, Unset and Toggle actions. Examples below.
Keypress = "Mod4 s" { Actions = "Toggle Shaded" } Keypress = "Mod4 m" { Actions = "Toggle Maximized True True" } Keypress = "Mod4 t" { Actions = "Set Tagged" } Keypress = "Mod4 Shift t" { Actions = "Unset Tagged" } |
Toggleable attributes:
If a frame is maximized. Two parameters, first one decides if the frame is maximized horizontally, the second if it is maximized vertically.
If a frame should be fullscreen. Fullscreen frame takes over the whole desktop ignoring any harbour or struts and becomes decorless.
If a frame should be shaded (so that only the titlebar shows until it's unset or toggled off).
If a frame should be sticky so it appears on every workspace.
If frame should always be on top of other frames.
If a frame should always be below other frames.
If frame should have borders.
If frame should have a titlebar.
If a frame should be iconified.
If a frame should swallow all new clients until unset or toggled off. One parameter, if true new clients open in the background. Defaults to false.
If a frame is marked for later attaching (with AttachMarked).
If a frame should be ignored on specified places, string is one of
menus
focustoggle
snap
When things to be done to this window requested by the client program should be denied, string is one of:
position (don't let the client move the window)
size (don't let the client resize the window)
stacking (don't allow the client to raise or lower the window)
activewindow (don't let client give input focus)
maximizedvert (don't let client maximize a window vertically)
maximizedhorz (don't let client maximize window horizontally)
hidden (don't let client hide window)
fullscreen (don't let client set window fullscreen mode)
above (don't let client place window above other windows)
below (don't let client place window below other windows)
Changes the clients titlebar text to string when set. Unsetting returns the clients title text back to the client specified one.
If set, harbour and anything in it will be hidden from the screen.
If all autogrouping should be in use or not. By default it's set, as in autogrouping is enabled.
Keys/Mouse Actions:
Gives focus to a frame.
Removes focus from a frame.
Makes toggleable attributes set.
Unsets toggleable attributes.
Toggles toggleable attributes.
Acts much like Maximize, but considers other frames while doing it. Instead of filling the whole screen, it only fills to the borders of neighboring frames. Takes two parameters, first one decides if the frame is maxfilled horizontally, the second if it should be maxfilled vertically.
Grows the frame in one of the directions up to the edge of the head. String is one of up, down, left, right.
Closes a client window.
Closes a frame and all client windows in it.
Kills a client window, use if close doesn't work.
Raises a frame above other frames. If bool is true raises a frame and all of the currently active clients child/parent windows above other frames.
Lowers a frame under other frames. If bool is true lowers a frame and all of the currently active clients child/parent windows under other frames.
If the frame this action is used on is not focused, focuses it. If the frame is focused, raises it. If used on a groups titlebar, activates the selected client of the group.
Moves the focus and raises a client inside a frame relative to the currently selected client. Int is 1 to move right, -1 to move left.
Moves the current clients position inside the current frame. Int is 1 to move right, -1 to move left.
Activates a client of a frame.
Mouse-specific
Activates the #th client of a frame. Int is the client number counting from left.
Keygrabber-specific
Resizes a frame. String is one of top, bottom, left, right, topleft, topright, bottomleft, bottomright.
Mouse-specific (parameters frameborder-specific)
Moves a frame.
Mouse-specific
Activates the keyboard move and resize.
Keygrabber-specific
Drags windows in and out of frames, if parameter is true dragged windows go in the background of a frame.
Mouse-specific
Makes a dragged window warp to specified workspace when a it's moved over a screen edge. String is one:
next - send to the next workspace, if on last workspace, wrap to the first one.
prev - send to the previous workspace, if on first workspace, wrap to the last one.
left - send to the previous workspace
right - send to the next workspace
int - integer is a workspace number to send to to
ScreenEdge specific mouse binding
Moves the frame to the specified place on the screen. String is one of TopLeft, TopEdge, TopRight, RightEdge, BottomRight, BottomEdge, BottomLeft, LeftEdge, Center, TopCenterEdge, BottomCenterEdge, LeftCenterEdge, RightCenterEdge.
Keygrabber-specific
Focuses the next frame. String is one of:
alwaysraise - raise windows while toggling them
endraise - raise the selected client
neverraise - do not raise the selected client (unless it's iconified)
Focuses the previous frame. String is:
alwaysraise - raise windows while toggling them
endraise - raise the selected client
neverraise - do not raise the selected client (unless it's iconified)
Focuses the next frame so that the last focused windows will get switched to first. String is:
alwaysraise - raise windows while toggling them
endraise - raise the selected client
neverraise - do not raise the selected client (unless it's iconified)
Focuses the previous frame so that the last focused windows will get switched to first. String is:
alwaysraise - raise windows while toggling them
endraise - raise the selected client
neverraise - do not raise the selected client (unless it's iconified)
Focuses the first window on the direction specified, and optionally raises it. Takes two options, first one is the direction and the second specifies if the focused frame should be raised or not. Bool defaults to True. String is one of up, down, left, right
Attachs all marked clients to the current frame.
Attachs client to the next frame.
Attachs client to the previous frame.
Searches the client list for a client that has a title matching the given regex string.
Shows and focuses a client based on the Client ID given as a parameter.
Detach the current client from its frame.
Sends a frame to the specified workspace. String is one of:
next - send to the next workspace, if on last workspace, wrap to the first one.
prev - send to the previous workspace, if on first workspace, wrap to the last one.
left - send to the previous workspace
right - send to the next workspace
prevv - send to the previous (vertical) workspace, if on last workspace, wrap to the first one.
up - send to the previous (vertical) workspace.
nextv - sed to the next (vertical) workspace, if on last workspace, wrap to the first one.
down -
last - send to workspace you last used before the current
int - integer is a workspace number to send to to
Changes workspaces. String is one of:
left - go to the previous workspace
prev - go to the previous workspace, if on first workspace, wrap to the last one.
right - go to the next workspace
next - go to the next workspace, if on last workspace, wrap to the first one.
prevv -
up -
nextv -
down -
last - go to workspace you last used before the current
int - integer is a workspace number to go to
Executes a program, string is a path to an executable file.
Reloads pekwm configs.
Keygrabber-specific
Restarts pekwm.
Keygrabber-specific
Quits pekwm and starts the program you specify. String is a path to an executable file.
Keygrabber-specific
Exits pekwm.
Shows the command dialog that can be used to input pekwm actions. If it's a window specific action, it affects the window focused when CmdDialog was summoned. If entered action doesn't match any valid pekwm action, pekwm tries to Exec it as a shell command. Takes an optional string as a parameter. This string will then be pre-filled as the initial value of the dialog.
Shows the search dialog that can be used to search for clients and when selected the client will be activated. Takes an optional string as a parameter. This string will then be pre-filled as the initial value of the dialog.
Shows a menu. String is menu type from below list or user defined menu name (see Custom Menus):
root - shows your application menu
icon - shows iconified windows
goto - shows currently active clients
gotoclient - shows all open clients
window - shows a window specific menu
decor - shows possible decorations in the current theme
attachclient - allows to attach clients in current frame
attachframe - allows to attach whole frame in current frame
attachclientinframe - allows attaching current client in any other frame
attachframeinframe - allows attaching current frame in any other frame
Closes all pekwm menus.
Send a key, possibly with modifiers, to the active window.
MoveResize actions:
Moves a frame horizontally. Int is amount of pixels and can be negative.
Moveresize-specific keybinding
Moves a frame vertically. Int is amount of pixels and can be negative.
Moveresize-specific keybinding
Resizes a frame horizontally. Int is amount of pixels and can be negative.
Moveresize-specific keybinding
Resizes a frame vertically. Int is amount of pixels and can be negative.
Moveresize-specific keybinding
Snaps the frame to the closest frames or screenedges.
Moveresize-specific keybinding
Cancels all moveresize actions and keeps the frame how it was before them.
Moveresize-specific keybinding
Acknowledges the moveresize actions and moves/resizes the frame as wished.
Moveresize-specific keybinding
Menu actions:
Goes to next menu item.
Menu-specific keybinding
Goes to previous menu item.
Menu-specific keybinding
Selects the current menu item.
Menu-specific keybinding
Enters a submenu.
Menu-specific keybinding
Leaves a submenu.
Menu-specific keybinding
InputDialog actions:
Allows for the keypress to be inputted to the text field of InputDialog. Usually used to allow any other keys than the ones used for InputDialog.
InputDialog-specific keybinding
Erases the previous character according to the cursor position.
InputDialog-specific keybinding
Clears the whole InputDialog line.
InputDialog-specific keybinding
Erases all characters after the current cursor position.
InputDialog-specific keybinding
Finishes input and executes the the data
Closes an InputDialog.
InputDialog-specific keybinding
Moves InputDialog cursor one characer space to right.
InputDialog-specific keybinding
Moves InputDialog cursor one characer space to left.
InputDialog-specific keybinding
Moves InputDialog cursor to the end of the line.
InputDialog-specific keybinding
Moves InputDialog cursor to the beginning of the line.
InputDialog-specific keybinding
Get next history item previously used in InputDialog.
InputDialog-specific keybinding
Get previous history item previously used in InputDialog.
InputDialog-specific keybinding