Project

General

Profile

unexist.dev

subtle

Assorted tidbits and projects

History

Grabs

Grabs are the mouse button/keyboard mappings in subtle and can be used in various combinations, no grab is limited either to button or keyboard only. Generally they are combinations or chains of one or more modifiers and a button/key.

Genereally there are different types of grabs:
  1. Predefined grabs that call a specific actions
  2. Grabs that call a Ruby block
  3. Grabs that exec a program

Finding keys

The best resource for getting the correct key names is /usr/include/X11/keysymdef.h, but to make life easier here are some hints about it:

  • Numbers and letters keep their names, so a is a and 0 is 0
  • Keypad keys need KP_ as prefix, so KP_1 is 1 on the keypad
  • Strip the XK_ from the key names if looked up in /usr/include/X11/keysymdef.h
  • Keys usually have meaningful english names
  • Modifier keys have special meaning (Alt (A), Control (C), Meta (M), Shift (S), Super (W), AltGr (G))

Chaining

Chains are a combination of keys and modifiers to one or a list of keys and can be used in various ways to trigger an action. In subtle, there are two ways to define chains for grabs:

  1. Default: Add modifiers to a key and use it for a grab

    Example: grab "W-Return", "urxvt"

  2. Chain: Define a list of grabs that need to be pressed:

    Example: grab "C-y Return", "urxvt"

Mouse buttons

  • B1 = Button1 (Left mouse button)
  • B2 = Button2 (Middle mouse button)
  • B3 = Button3 (Right mouse button)
  • B4 = Button4 (Mouse wheel up)
  • B5 = Button5 (Mouse wheel down)
  • ...
  • B20 = Button20 (Are you sure that this is a mouse and not a keyboard?)

Modifier keys

  • A = Alt key (Mod1)
  • C = Control key
  • M = Meta key (Mod3)
  • S = Shift key
  • W = Super/Windows key (Mod4)
  • G = AltGr key (Mod5) (since r3004)

Common keys

  • Space
  • Tab
  • Enter / Return
  • F1 - F12
  • Left, Down, Up, Right
  • Next, Prior
  • Page_Up, Page_Down
  • Home, End
  • Insert, Delete
  • Add, Subtract, Multiply, Divide, Equal
  • Decimal
  • Num_Lock
  • Escape

Multimedia keys

The following list shows some typically used keynames for multimedia keys. Per default they are unassigned, see Assigning keynames for more.

  • XF86AudioMute
  • XF86AudioRaiseVolume
  • XF86AudioLowerVolume
  • XF86AudioPlay
  • XF86AudioPrev
  • XF86AudioNext
  • XF86WWW
  • XF86Calculator
  • XF86Mail

The complete list with all keynames can be found in /usr/share/X11/XKeysymDB.

If you use ncmpcpp for your music player needs, you can use your multimedia keys to control playback. Simply copy the below code into your config.

# Multimedia Keys
grab "XF86AudioPlay", "ncmpcpp toggle" 
grab "XF86AudioNext", "ncmpcpp next" 
grab "XF86AudioPrev", "ncmpcpp prev" 
grab "XF86AudioStop", "ncmpcpp stop"

Fn keys

Fn keys found on notebooks other than numpad keys can't be used directly, they need to be defined. See Assigning keynames for more.

Examples

{{hide}}grab "S-B1", :WindowMove
grab "A-space" do |c|
  c.toggle_float
end
grab "W-F1", "xterm -sb"

Assigning keynames

Keys like the multimedia keys are unassigned or even unknown to the xserver and can't be used directly, but xmodmap can be used to assign keynames to these new keycodes. To get the actual keycodes of a key there is showkey, a tool that can't be used in a virtual terminal.

  • Get keycode
kb mode was XLATE

press any key (program terminates 10s after last keypress)...
keycode  28 release
keycode 153 press
keycode 153 release
  • Add to ~/.Xmodmap
keycode 153 = XF86AudioNext

 grab "XF86AudioNext", "mpc next"

Predefined

Subtle

SubtleReload

Reload config and sublets.

Example:

grab "W-C-r", :SubtleReload

SubtleRestart

Restart subtle without exiting Xorg.

Example:

grab "W-C-S-r", :SubtleRestart

SubtleQuit

Quit subtle and exit Xorg session.

Example:

grab "W-C-q", :SubtleQuit

Views

ViewJump

Move pointer either to screen showing numbered view (multihead) or open numbered view on current screen.

  • ViewJump1
  • ViewJump2
  • ...
  • ViewJumpN

Example:

grab "W-S-1", :ViewJump1

ViewSwitch

Set current view to numbered view and swap view with screen currently showing it. (multihead)

  • ViewSwitch1
  • ViewSwitch2
  • ...
  • ViewSwitchN

Example:

grab "W-1", :ViewSwitch

ViewNext

Select next view.

Example:

grab "KP_Add", :ViewNext

ViewPrev

Select previous view.

Example:

grab "KP_Subtract", :ViewPrev

Screens

ScreenJump

Move pointer to the numbered screen.

  • ScreenJump1
  • ScreenJump2
  • ..
  • ScreenJumpN

Example:

grab "W-A-1", :ScreenJump1

Windows

Window grabs manipulate/toggle various modes of client windows.

WindowMove

Move window either by mouse movement while holding the mouse button or via arrow/cursor keys. The move mode can be exited either with releasing the mouse button or pressing return.

Example:

grab "W-B1", :WindowMove

WindowMoveUp

WindowMoveRight

WindowMoveDown

WindowMoveLeft

Move window to selected direction pixel steps defined by the :step option.

Example:

grab "W-Up",    :WindowMoveUp
grab "W-Right", :WindowMoveUp
grab "W-Down",  :WindowMoveUp
grab "W-Left",  :WindowMoveUp

WindowResize

Resize window either by mouse movement while holding the mouse button or via arrow/cursor keys. The resize mode can be exited either with releasing the mouse button or pressing return.

Example:

grab "W-B3", :WindowResize

WindowResizeUp

WindowResizeRight

WindowResizeDown

WindowResizeLeft

Resize window in selected direction pixel steps defined by the :step option.

Example:

grab "W-Up",    :WindowResizeUp
grab "W-Right", :WindowResizeUp
grab "W-Down",  :WindowResizeUp
grab "W-Left",  :WindowResizeUp

WindowFloat

Toggle floating mode of window. Floating windows have no gravity and float above the other windows.

Example:

grab "W-f", :WindowFloat

WindowFull

Toggle [[Clients|Fullscreen|fullscreen]] mode of window.

Example:

grab "W-space", :WindowFull

WindowStick

Toggle sticky mode of window zo appear on all screens.

Example:

grab "W-s", :WindowStick

WindowZaphod

Toggle zaphod mode of window to span across all screens.

Example:

grab "W-s", :WindowStick

h4. WindowRaise

Move window to top of window stacking list.

Example:

grab "W-r", :WindowRaise

WindowLower

Move window to bottom of window stacking list.

Example:

grab "W-l", :WindowLower

WindowUp

WindowDown

WindowRight

WindowLeft

Select window of given direction of of current window.

Example:

grab "W-Up",    :WindowUp
grab "W-Right", :WindowRight
grab "W-Down",  :WindowDown
grab "W-Left",  :WindowLeft

WindowKill

Kill current window.

Example:

grab "W-k", :WindowKill

Gravities

Gravity grabs change the gravity of the selected client on the current view, they are basically a list of gravities and are toggled.

Example:

grab "W-KP_7", [ :top_left, :top_left66, :top_left33 ]

Blocks

Grabs can also call a Ruby block (aka lambda/proc), the arity of the block is either a client window or none. Inside of the blocks the whole API of subtlext can be used, the extension will be loaded ondemand.

Example:

{{hide}}grab "S-F2" do |c| 
  puts c.name
end

Exec

Invoke a shell and exec a program.

Example:

grab "W-Return", "urxvt"