Subtle Window Manager

Options

Following options change behaviour and sizes of the window manager:

Screen

Generally subtle comes with two panels per screen, one on the top and one at the bottom. Each panel can be configured with different panel items and sublets screen wise. The default config uses top panel on the first screen only, it’s up to the user to enable the bottom panel or disable either one or both.

Properties

[*stipple*]    This property adds a stipple pattern to both screen panels.

               Example: stipple "~/stipple.xbm"
               
                        stipple Subtlext::Icon.new("~/stipple.xbm")
                        
[*top*]        This property adds a top panel to the screen.

               Example: top [ :views, :title ]
               
[*bottom*]     This property adds a bottom panel to the screen.

               Example: bottom [ :views, :title ]

*** Following items are available for the panels:

[*:views*]     List of views with buttons

[*:title*]     Title of the current active window

[*:tray*]      Systray icons (Can be used only once)

[*:keychain*]  Display current chain (Can be used only once)

[*:sublets*]   Catch-all for installed sublets

[*:sublet*]    Name of a sublet for direct placement

[*:spacer*]    Variable spacer (free width / count of spacers)

[*:center*]    Enclose items with :center to center them on the panel

[*:separator*] Insert separator

Empty panels are hidden.

Links

Multihead

Panel

Example for a second screen:

screen 2 do
 top    [ :views, :title, :spacer ]
 bottom [ ]
end

Styles

Styles define various properties of styleable items in a CSS-like syntax.

If no background color is given no color will be set. This will ensure a custom background pixmap won’t be overwritten.

Link

[[http://subforge.org/projects/subtle/wiki/Styles][Styles]

Gravities

Gravities are predefined sizes a window can be set to. There are several ways to set a certain gravity, most convenient is to define a gravity via a tag or change them during runtime via grab. Subtler and subtlext can also modify gravities.

A gravity consists of four values which are a percentage value of the screen size. The first two values are x and y starting at the center of the screen and he last two values are the width and height.

Example

Following defines a gravity for a window with 100% width and height:

gravity :example, [ 0, 0, 100, 100 ]

Link

Gravity

Grabs

Grabs are keyboard and mouse actions within subtle, every grab can be assigned either to a key and/or to a mouse button combination. A grab consists of a chain and an action.

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))

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:

Default: Add modifiers to a key and use it for a grab
Example: grab “W-Return”, “urxvt”
1. Chain: Define a list of grabs that need to be pressed in order
  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)

Modifiers

[*A*] = Alt key

[*C*] = Control key

[*M*] = Meta key

[*S*] = Shift key

[*W*] = Super (Windows) key

Action

An action is something that happens when a grab is activated, this can be one of the following:

[*symbol*] Run a subtle action

[*string*] Start a certain program

[*array*]  Cycle through gravities

[*lambda*] Run a Ruby proc

Example

This will create a grab that starts a urxvt when Alt+Enter are pressed:

grab "A-Return", "urxvt"

grab "C-a c",    "urxvt"

Link

Grabs

Tags

Tags are generally used in subtle for placement of windows. This placement is strict, that means that - aside from other tiling window managers - windows must have a matching tag to be on a certain view. This also includes that windows that are started on a certain view will not automatically be placed there.

There are to ways to define a tag:

Simple

The simple way just needs a name and a regular expression to just handle the placement:

Example

tag "terms", "terms"

Extended

Additionally tags can do a lot more then just control the placement - they also have properties than can define and control some aspects of a window like the default gravity or the default screen per view.

Example

tag "terms" do
  match   "xterm|[u]?rxvt"
  gravity :center
end

Default

Whenever a window has no tag it will get the default tag and be placed on the default view. The default view can either be set by the user with adding the default tag to a view by choice or otherwise the first defined view will be chosen automatically.

Properties

[*borderless*] This property enables the borderless mode for tagged clients.

Example: borderless true

Links: http://subforge.org/projects/subtle/wiki/Tagging#Borderless

http://subforge.org/projects/subtle/wiki/Clients#Borderless

[*fixed*] This property enables the fixed mode for tagged clients.

Example: fixed true

Links: http://subforge.org/projects/subtle/wiki/Tagging#Fixed

http://subforge.org/projects/subtle/wiki/Clients#Fixed

[*float*] This property enables the float mode for tagged clients.

Example: float true

Links: http://subforge.org/projects/subtle/wiki/Tagging#Float

http://subforge.org/projects/subtle/wiki/Clients#Float

[*full*] This property enables the fullscreen mode for tagged clients.

Example: full true

Links: http://subforge.org/projects/subtle/wiki/Tagging#Fullscreen

http://subforge.org/projects/subtle/wiki/Clients#Fullscreen

[*geometry*] This property sets a certain geometry as well as floating mode to the tagged client, but only on views that have this tag too. It expects an array with x, y, width and height values whereas width and height must be >0.

Example: geometry [100, 100, 50, 50]

Link: Geometry

[*gravity*] This property sets a certain to gravity to the tagged client, but only on views that have this tag too.

Example: gravity :center

Link: Gravity

[*match*] This property adds matching patterns to a tag, a tag can have more than one. Matching works either via plaintext, regex (see man regex(7)) or window id. Per default tags will only match the WM_NAME and the WM_CLASS portion of a client, this can be changed with following possible values:

[*:name*]      Match the WM_NAME

[*:instance*]  Match the first (instance) part from WM_CLASS

[*:class*]     Match the second (class) part from WM_CLASS

[*:role*]      Match the window role

[*:type*]      Match the window type

Examples: match instance: “urxvt”

match [:role, :class] => "test"

match "[xa]+term"

Link: Match

[*position*] Similar to the geometry property, this property just sets the x/y coordinates of the tagged client, but only on views that have this tag, too. It expects an array with x and y values.

Example: position [ 10, 10 ]

Link: Position

[*resize*] This property enables the float mode for tagged clients.

Example: resize true

Links: Tagging-Resize

Client-Resize

[*stick*] This property enables the float mode for tagged clients.

Example: stick true

Links: Tagging-Stick

Client-Stick

[*type*] This property sets the tagged client to be treated as a specific window type though as the window sets the type itself. Following types are possible:

[*:desktop*] Treat as desktop window (_NET_WM_WINDOW_TYPE_DESKTOP)

Client-Desktop

[*:dock*] Treat as dock window (_NET_WM_WINDOW_TYPE_DOCK)

Link: Client-Dock

[*:toolbar*] Treat as toolbar windows (_NET_WM_WINDOW_TYPE_TOOLBAR)

Link: Client-Toolbar

[*:splash*] Treat as splash window (_NET_WM_WINDOW_TYPE_SPLASH)

Link: Client-Splash

[*:dialog*] Treat as dialog window (_NET_WM_WINDOW_TYPE_DIALOG)

Link: Client-Dialog

Example: type :desktop

Link: Tagging-Type

[*urgent*] This property enables the urgent mode for tagged clients.

Example: stick true

Links: Tagging-Stick

Client-Urgent

[*zaphod*] This property enables the zaphod mode for tagged clients.

Example: zaphod true

Links: Tagging-Zaphod

Client-Zaphod

Link

Tagging

Views

Views are the virtual desktops in subtle, they show all windows that share a tag with them. Windows that have no tag will be visible on the default view which is the view with the default tag or the first defined view when this tag isn’t set.

Like tags views can be defined in two ways:

Simple

The simple way is exactly the same as for tags:

Example

view "terms", "terms"

Extended

The extended way for views is also similar to the tags, but with fewer properties.

Example

view "terms" do
  match "terms"
  icon  "/usr/share/icons/icon.xbm"
end

Properties

[*match*] This property adds a matching pattern to a view. Matching works either via plaintext or regex (see man regex(7)) and applies to names of tags.

Example: match "terms"

[*dynamic*] This property hides unoccupied views, views that display no windows.

Example: dynamic true

[*icon*] This property adds an icon in front of the view name. The icon can either be path to an icon or an instance of Subtlext::Icon.

Example: icon "/usr/share/icons/icon.xbm"

         icon Subtlext::Icon.new("/usr/share/icons/icon.xbm")

[*icon_only*] This property hides the view name from the view buttons, just the icon will be visible.

Example: icon_only true

Link

Tagging

Sublets

Sublets are Ruby scripts that provide data for the panel and can be managed with the sur script that comes with subtle.

Example

sur install clock
sur uninstall clock
sur list

Configuration

All sublets have a set of configuration values that can be changed directly from the config of subtle.

There are three default properties, that can be be changed for every sublet:

[*interval*]    Update interval of the sublet
[*foreground*]  Default foreground color
[*background*]  Default background color

sur can also give a brief overview about properties:

Example

sur config clock

The syntax of the sublet configuration is similar to other configuration options in subtle:

Example

sublet :clock do
   interval      30
   foreground    "#eeeeee"
   background    "#000000"
   format_string "%H:%M:%S"
end

Link

Sublets

Hooks

And finally hooks are a way to bind Ruby scripts to a certain event.

Following hooks exist so far:

[*:client_create*]    Called whenever a window is created
[*:client_configure*] Called whenever a window is configured
[*:client_focus*]     Called whenever a window gets focus
[*:client_kill*]      Called whenever a window is killed

[*:tag_create*]       Called whenever a tag is created
[*:tag_kill*]         Called whenever a tag is killed

[*:view_create*]      Called whenever a view is created
[*:view_configure*]   Called whenever a view is configured
[*:view_jump*]        Called whenever the view is switched
[*:view_kill*]        Called whenever a view is killed

[*:tile*]             Called on whenever tiling would be needed
[*:reload*]           Called on reload
[*:start*]            Called on start
[*:exit*]             Called on exit

Example

This hook will print the name of the window that gets the focus:

on :client_focus do |c|
  puts c.name
end

Link

Hooks

JeremyOttley/subtle

Subtle Window Manager

Options

Screen

Properties

Empty panels are hidden.

Links

Example for a second screen:

Styles

Link

Gravities

Example

Link

Grabs

Finding Keys

Chaining

Mouse buttons

Modifiers

Action

Example

Link

Tags

Simple

Example

Extended

Example

Default

Properties

Link

Views

Simple

Example

Extended

Example

Properties

Link

Sublets

Example

Configuration

Example

Example

Link

Hooks

Example

Link