Hacking

The following information is for people who are interested in subtle's internals and/or like to play around and extend subtle. If you have problems with a certain client or discover an odd behaviour, feel free to add to the blamelist.

RDoc documentation

The latest rdoc documention can either be found here or be generated from the source tree:

rake rdoc

Unit testing

Testing a window manager is a difficult task, currently the unit tests consist of a bunch of riot contexts and a script to run Xvfb.

Requirements:
  1. riot
  2. Xvfb
  3. xterm

Run tests:

cd test
ruby ./xserver.rb &
ruby ./test.rb

...

68 passes, 0 failures, 0 errors in 18.540124 seconds

Loglevel

subtle uses a loglevel system to distinguish between messages and to be able to turn certain messages off. The level can be set with the -l or --level= options, multiple values are comma separated without any whitespace.

subtle -l ruby,subtlext
subtle --level=ruby,subtlext

Default levels:

Name Messages
warnings Warning messages
sublet Sublet warnings
error Error messages
deprecated Deprecation warnings

Debugging levels:

Name Messages
events Information about handled events
ruby Ruby debugging messages
xerror X11 error messages
subtle Subsystem messages of subtle
debug General debugging messages

EWMH/ICCCM specifications

Here are all EWMH/NetWM properties listed, that are supported by subtle and subtlext.

Default

_NET_NUMBER_OF_DESKTOPS

Get the number of views.

top

_NET_DESKTOP_NAMES

Get a list of all view names.

top

_NET_CURRENT_DESKTOP

Change or get current desktop

Root property

Get current desktop

Client message

Set current desktop

1 data.l[0] = <View id>
2 data.l[1] = <Timestamp>
3 data.l[2] = <Screen id>[1]
4 data.l[3] = 0
5 data.l[4] = 0

1 subtle extension (Use -1 to for current screen of view)

top

_NET_ACTIVE_WINDOW

Root property

Get current1 active window

1 subtle returns the five recent active windows

Client message

Set current active window

1 data.l[0] = <Window id>
2 data.l[1] = 0
3 data.l[2] = 0
4 data.l[3] = 0
5 data.l[4] = 0

top

_NET_RESTACK_WINDOW

Change stacking of window

1 data.l[0] = <Ignored>
2 data.l[1] = <Client id>
3 data.l[2] = <Detail>
4 data.l[3] = 0
5 data.l[4] = 0

Detail: 0 = Above (raise), 1 = Below (lower)

top

_NET_MOVERESIZE_WINDOW

Resize window

1 data.l[0] = <Ignored>
2 data.l[1] = <x>
3 data.l[2] = <y>
4 data.l[3] = <width>
5 data.l[4] = <height>

Move/resize a window.

top

_NET_CLOSE_WINDOW

Close client window

1 data.l[0] = <Timestamp>
2 data.l[1] = <Ignored>
3 data.l[2] = 0
4 data.l[3] = 0
5 data.l[4] = 0

Ask subtle to close a window.

top

WM State

Normally there are three types of actions: remove (0), add (1) and toggle (2), but we always toggle the states independent of the supplied action. The second property will be ignored.

_NET_WM_STATE_FULLSCREEN

Toggle client fullscreen

1 data.l[0] = <Action>
2 data.l[1] = _NET_WM_STATE_FULLSCREEN
3 data.l[2] = <Ignored>
4 data.l[3] = 0
5 data.l[4] = 0

Set fullscreen state of a window.

top

_NET_WM_STATE_ABOVE

Toggle client float

1 data.l[0] = <Action>
2 data.l[1] = _NET_WM_STATE_ABOVE
3 data.l[2] = <Ignored>
4 data.l[3] = 0
5 data.l[4] = 0

Set floating state of a window.

top

_NET_WM_STATE_STICKY

Toggle client urgent

1 data.l[0] = <Action>
2 data.l[1] = _NET_WM_STATE_STICKY
3 data.l[2] = <Ignored>
4 data.l[3] = 0
5 data.l[4] = 0

Set sticky mode of a window.

top

_NET_WM_STATE_DEMANDS_ATTENTION

Toggle client urgent

1 data.l[0] = <Action>
2 data.l[1] = _NET_WM_STATE_DEMANDS_ATTENTION
3 data.l[2] = <Ignored>
4 data.l[3] = 0
5 data.l[4] = 0

Set urgency of a window.

top

Tray

MANAGER

Inform clients about a new selection manager.

top

_NET_SYSTEM_TRAY_OPCODE

Used for communication between embedder and client.

top

_NET_SYSTEM_TRAY_MESSAGE_DATA

Used for communication between embedder and client.

top

_NET_SYSTEM_TRAY_S

Screen tray selection.

top

_XEMBED

_XEMBED_INFO

XEmbed protocol info.

top

XEMBED_EMBEDDED_NOTIFY

Notification to start embedding cycle.

top

XEMBED_WINDOW_ACTIVATE

NormalState for embedded clients.

top

XEMBED_WINDOW_DEACTIVATE

WithdrawnState for embedded clients.

top

XEMBED_REQUEST_FOCUS

Notification of the client for embedder to pass focus.

top

XEMBED_FOCUS_IN

Notification when client can take focus.

top

XEMBED_FOCUS_OUT

Notification when client lost focus.

top

Subtle extension

SUBTLE_CLIENT_TAGS

Set the tags of a client.

1 data.l[0] = <Client id>
2 data.l[1] = <Tag bitmask>
3 data.l[2] = 0
4 data.l[3] = 0
5 data.l[4] = 0

top

SUBTLE_CLIENT_GRAVITY

Set client gravity

1 data.l[0] = <Client id>
2 data.l[1] = <Gravity id>
3 data.l[2] = 0
4 data.l[3] = 0
5 data.l[4] = 0

top

SUBTLE_CLIENT_FLAGS

Set client flags

1 data.l[0] = <Client id>
2 data.l[1] = <Flags>
3 data.l[2] = 0
4 data.l[3] = 0
5 data.l[4] = 0

The bits in flags have the following meaning:

Bit Description
0 Fullscreen
1 Floating
2 Sticky
3 Resize
4 Urgent
5 Zaphod
6 Fixed
7 Center
8 Borderless

top

SUBTLE_GRAVITY_NEW

Create a new gravity mode

1 data.b[0-20] = <Gravity x>x<Gravity y>+<Gravity width>+<Gravity height>#<Gravity name>

top

SUBTLE_GRAVITY_LIST

Get a gravity mode list

top

SUBTLE_GRAVITY_KILL

Kill a gravity

1 data.l[0] = <Gravity id>
2 data.l[1] = 0
3 data.l[2] = 0
4 data.l[3] = 0
5 data.l[4] = 0

top

SUBTLE_TAG_NEW

Create a new tag

1 data.b[0-20] = <Tag name>

top

SUBTLE_TAG_LIST

Get a tag list

top

SUBTLE_TAG_KILL

Kill a tag

1 data.l[0] = <Tag id>
2 data.l[1] = 0
3 data.l[2] = 0
4 data.l[3] = 0
5 data.l[4] = 0

top

SUBTLE_VIEW_NEW

Create a new view

1 data.b[0-20] = <View name>

top

SUBTLE_VIEW_TAGS

Root property

Get a list of all tags.

Client message

Set tags of views.

1 data.l[0] = <View id>
2 data.l[1] = <Tag mask>
3 data.l[2] = 0
4 data.l[3] = 0
5 data.l[4] = 0

SUBTLE_VIEW_ICONS

Get a list of all view icons.

SUBTLE_VIEW_KILL

Kill a view

1 data.l[0] = <View id>
2 data.l[1] = 0
3 data.l[2] = 0
4 data.l[3] = 0
5 data.l[4] = 0

top

SUBTLE_SUBLET_UPDATE

Force update of a sublet

1 data.l[0] = <Sublet id>
2 data.l[1] = 0
3 data.l[2] = 0
4 data.l[3] = 0
5 data.l[4] = 0

top

SUBTLE_SUBLET_DATA

Set data field of sublet

1 data.l[0] = <Sublet id>

After receiving of this client message, subtle checkes the SUBTLE_DATA property on the root display and copies the data.

top

SUBTLE_SUBLET_LIST

Get sublet list

top

SUBTLE_SUBLET_KILL

Kill a sublet

1 data.l[0] = <Sublet id>
2 data.l[1] = 0
3 data.l[2] = 0
4 data.l[3] = 0
5 data.l[4] = 0

top

SUBTLE_SCREEN_VIEWS

List of views in screen order that are visible.

top

SUBTLE_VISIBLE_TAGS

Bitfield of all visible tags on all screens.

top

SUBTLE_VISIBLE_VIEWS

Bitfield of all visible views on all screens.

top

SUBTLE_RELOAD

Force reload of config and sublets.

1 data.l[0] = 0
2 data.l[1] = 0
3 data.l[2] = 0
4 data.l[3] = 0
5 data.l[4] = 0

top

SUBTLE_RESTART

Force full restart.

1 data.l[0] = 0
2 data.l[1] = 0
3 data.l[2] = 0
4 data.l[3] = 0
5 data.l[4] = 0

top

SUBTLE_QUIT

Force quit.

1 data.l[0] = 0
2 data.l[1] = 0
3 data.l[2] = 0
4 data.l[3] = 0
5 data.l[4] = 0

top

SUBTLE_COLORS

Get a color list.

SUBTLE_DATA

Property to exchange data.

top