Following options change behaviour and sizes of the window manager:
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.
[*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 separatorEmpty panels are hidden.
screen 2 do
top [ :views, :title, :spacer ]
bottom [ ]
endStyles 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.
[[http://subforge.org/projects/subtle/wiki/Styles][Styles]
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.
Following defines a gravity for a window with 100% width and height:
gravity :example, [ 0, 0, 100, 100 ]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.
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))
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”
- Chain: Define a list of grabs that need to be pressed in order
Example: grab “C-y Return”, “urxvt”
- Chain: Define a list of grabs that need to be pressed in order
[*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)[*A*] = Alt key
[*C*] = Control key
[*M*] = Meta key
[*S*] = Shift key
[*W*] = Super (Windows) keyAn 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 procThis will create a grab that starts a urxvt when Alt+Enter are pressed:
grab "A-Return", "urxvt"
grab "C-a c", "urxvt"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:
The simple way just needs a name and a regular expression to just handle the placement:
tag "terms", "terms"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.
tag "terms" do
match "xterm|[u]?rxvt"
gravity :center
endWhenever 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.
[*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 typeExamples: 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
[*stick*] This property enables the float mode for tagged clients.
Example: stick true
Links: Tagging-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
[*zaphod*] This property enables the zaphod mode for tagged clients.
Example: zaphod true
Links: Tagging-Zaphod
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:
The simple way is exactly the same as for tags:
view "terms", "terms"The extended way for views is also similar to the tags, but with fewer properties.
view "terms" do
match "terms"
icon "/usr/share/icons/icon.xbm"
end[*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 trueSublets are Ruby scripts that provide data for the panel and can be managed with the sur script that comes with subtle.
sur install clock
sur uninstall clock
sur listAll 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 colorsur can also give a brief overview about properties:
sur config clockThe syntax of the sublet configuration is similar to other configuration options in subtle:
sublet :clock do
interval 30
foreground "#eeeeee"
background "#000000"
format_string "%H:%M:%S"
endAnd 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 exitThis hook will print the name of the window that gets the focus:
on :client_focus do |c|
puts c.name
end