commit 4b91716720161902e3235c67c7813983d114d56e
parent a193d2ab4a6f8559dd7f706b09365d75fd40ac22
Author: phillbush <phillbush@cock.li>
Date: Sun, 26 Sep 2021 21:12:53 -0300
improve manual; fix shodc state
Diffstat:
| M | shod.1 | | | 272 | +++++++++++++++++++++++++++++++++++++++++++++++++++++-------------------------- |
| M | shodc.c | | | 5 | +++++ |
2 files changed, 189 insertions(+), 88 deletions(-)
diff --git a/shod.1 b/shod.1
@@ -1,7 +1,7 @@
.TH SHOD 1
.SH NAME
.B shod, shodc
-\- mouse-based window manager
+\- mouse-focused window manager
.SH SYNOPSIS
.B shod
.RB [ \-f
@@ -63,9 +63,6 @@ and by responding to client messages
a controller called
.IR shodc (1)
to control shod).
-To understand how
-.B shod
-organizes the desktop, see the DESKTOP section below.
.PP
The options are as follows:
.TP
@@ -405,14 +402,33 @@ One of the desktops of a monitor is the focused desktop for that monitor.
.PP
Most client windows are displayed in containers;
but some windows are special and are displayed in different ways.
-A new client window is mapped inside a new container that floats in the focused desktop of the focused monitor.
-This new container is placed in a empty area of the screen or in an area with few windows over it.
-.SS Containers
-Containers are floating windows with borders (four edges and four corners).
+.SH CONTAINERS
+Containers are floating windows where the windows of clients are mapped in.
A container contains client\-windows organized in columns, rows, and tabs;
-each client\-window can also contain dialog windows associated to it.
-Containers are divided into columns.
-A container can be made maximized, fullscreen, minimized, sticky, and/or above/below.
+each client\-window can also contain dialog windows associated with it.
+A new client\-window is mapped inside a new container that floats in the focused desktop of the focused monitor.
+This new container is placed in a empty area of the screen or in an area with few windows over it.
+.SS Components of a container
+.PP
+The components of a container are listed below.
+.TP
+Border
+Around each container lies its border, that is used to resize and move the container.
+Borders are always visible, except when the container is fullscreen
+(in which case the border is hidden until the container loses its fullscreen state).
+A border is composed of eight handles: four edges and four corners.
+The mouse cursor changes when hovering a handle; there is one cursor for each handle.
+Dragging a handle with the mouse button 1 (the left mouse button) resizes the container to the direction of that handle.
+Dragging a handle with the mouse button 3 (the right mouse button) moves the container.
+.TP
+Divisors
+When a container has more than one column, a column divisor appears to separate those columns.
+Dragging a column divisor with the mouse button 1 (the left mouse button)
+resizes the columns it divides.
+When a column has more than one row, a row divisor appears to separate those rows.
+Dragging a row divisor with the mouse button 1 (the left mouse button)
+resizes the rows it divides.
+When a column has a maximized row, row divisors are hidden.
.TP
Columns
A container can have one or more columns.
@@ -420,7 +436,8 @@ Columns split a conteiner horizontally, and each container appears next to the o
Columns are divided into rows.
A column can have either no maximized row, in which case all rows are visible;
or can have a single maximized row, in which case only that row is visible.
-The process of maximizing a row is called restacking.
+The process of maximizing a row or unmaximizing it is called restacking.
+Restacking is controlled with the left title bar button.
.TP
Rows
A column can have one or more rows.
@@ -433,10 +450,29 @@ and the right button (used to close the active tab of the row).
The title bar is always visible, even when the content of the row is hidden by another
maximized row.
.TP
+Title-bar
+Title-bar is a region of the container where the tabs of the client\-windows are placed and
+the left and right title-bar buttons appear.
+There is one title bar for each row.
+.TP
+Left title-bar button
+The left title-bar button is used to control its row and container.
+Clicking on the left title-bar button with the mouse button 1 (the left mouse button)
+restacks the column by maximizing its row (and minimizing the other rows in the same column)
+or by returning the rows to their usual size.
+Dragging the left title-bar button with the mouse button 3 (the right mouse button)
+moves the row through the column or to other columns.
+.TP
Tabs
A row can have one or more tabs.
Tabs split a column in the Z axis, and each tab appears above the other.
A tab contain a client\-window and all the dialogs associated to that client\-window.
+A tab contains the current title of the client\-window and is placed on the title bar of a row.
+Dragging a tab with the mouse button 1 (the left mouse button) moves the container.
+Dragging a tab with the mouse button 3 (the right mouse button) dettach the tab from the container.
+A dettached tab, while being dragged, can be reattached in other container (or the same container)
+in the title bar of a row (and be part of that row), on a row divisor (and create a new row),
+or on a column divisor (and create a new column).
.TP
Client\-window.
A client\-window is the actual window where the actual content of the client
@@ -450,38 +486,136 @@ A dialog appears above the client window, and is centered on it.
.PP
The following illustration is an example of a container with several client\-windows in it.
This container contains two columns: one column in the left and another in the right.
-The column in the left contain three rows, the top row is maximized and visible, while
-the two rows on the bottom (one one of them with two tabs) are hidden.
+The column in the left contain three rows, the top row is maximized and visible
+(and has a dialog above it), while
+the two rows on the bottom (one of them with two tabs) are hidden.
The column in the right contain two rows:
the top row with a single tab, and the bottom row with two tabs.
-Each tab contains a client\-window;
-one of the client\-windows has a dialog floating above it.
+The border handles and divisors are represented by double line.
+The title-bar buttons are represented by two squares around the title-bars.
.IP
.EX
-┌─┬─────────────────────────┬─┬─┬─────────────────────────┬─┐
-├─┴─────────────────────────┴─┼─┴─────────────────────────┴─┤
-│ │ │
-│ │ │
-│ │ │
-│ │ │
-│ ┌─────────────────────────┐ │ │
-│ │ │ │ │
-│ │ │ │ │
-│ │ │ │ │
-│ │ │ ├─┬────────────┬────────────┬─┤
-│ │ │ ├─┴────────────┴────────────┴─┤
-│ │ │ │ │
-│ └─────────────────────────┘ │ │
-│ │ │
-│ │ │
-│ │ │
-│ │ │
-├─┬─────────────────────────┬─┤ │
-├─┼────────────┬────────────┼─┤ │
-└─┴────────────┴────────────┴─┴─────────────────────────────┘
+╔═╤═════════════════════════╤═╦═╤═════════════════════════╤═╗
+╟─┴─────────────────────────┴─╫─┴─────────────────────────┴─╢
+║ ║ ║
+║ ║ ║
+║ ║ ║
+║ ║ ║
+║ ╔═════════════════════════╗ ║ ║
+║ ║ ║ ║ ║
+║ ║ ║ ║ ║
+║ ║ ║ ║ ║
+║ ║ ║ ╠═╤════════════╤════════════╤═╣
+║ ║ ║ ╟─┴────────────┴────────────┴─╢
+║ ║ ║ ║ ║
+║ ╚═════════════════════════╝ ║ ║
+║ ║ ║
+║ ║ ║
+║ ║ ║
+║ ║ ║
+╟─┬─────────────────────────┬─╢ ║
+╟─┼────────────┬────────────┼─╢ ║
+╚═╧════════════╧════════════╧═╩═════════════════════════════╝
.EE
+.SS Focus history
+.PP
+When a client\-window is focused it gets keyboard input.
+A focused client\-window continues to get keyboard input until it is closed,
+its container is hidden, or another client\-window is explicitly selected to be focused.
+Only one client\-window can be focused at a time.
+Each container has a client\-window, called the selected client\-window
+that is focused when the focus goes to that container.
+.PP
+The container of the focused client\-window is called the focused container
+and is decorated with a visually distinct decoration (blue in the default theme);
+while other containers have either the common decoration (gray in the default theme),
+or have the urgent decoration (red in the default theme).
+.PP
+.B shod
+maintains a list of focused containers called the focus history. The
+focused container is the first container in the focus history. When a
+client\-window gains focus, its container is moved to the beginning of
+the focus history. When a focused client\-window loses focus, the focus
+goes to another client\-window in the same container, or (if there's no
+other client\-window in that container) to the selected client\-window
+of the next container in the focus history that is visible and in the
+same desktop or monitor, or (if there's no other container to focus), no
+window gets the focus.
+.PP
+A container can be focused with the mouse.
+The mouse buttons set with the
+.B \-f
+command-line option are used to focus a container when clicking on it.
+If no mouse button is specified, the focus follows the mouse pointer.
+.SS Stacking order
+Containers are stacked one above the other in the virtual Z axis.
+The position of the container in this Z axis can be changed by a operation called raising.
+.PP
+The list of containers in this Z axis, from the one in the bottom to the topmost,
+is called the stacking order.
+The stacking order is organized in four layers.
+When a container in is raised, it moves to the top of the other
+containers in the same layer.
+.TP
+The bottom layer
+At the bottom of the stacking order, lays the containers with the
+bottom state set. They appear below any other container.
+.TP
+The normal layer
+Above the containers in the bottom layer, lays the containers that have
+not set any of the states that change the stacking order (that is, the
+below, above or fullscreen states).
+.TP
+The above layer
+Above the containers in the normal layer, lays the container with the
+above state set.
+.TP
+The fullscreen layer
+Above the containers in the above layer, lays the container with the
+fullscreen state set. They appear above any other container.
+.PP
+A container can have either the above state or the below state set, but not both.
+When a container has the fullscreen state set and either the above or the below state also set,
+the fullscreen state has priority (so the container belongs to the fullscreen layer).
+.PP
+A container can be raised with the mouse.
+The mouse buttons set with the
+.B \-r
+command-line option are used to raise a container to the top of its layer when clicking on it.
+.SS Moving and Resizing
+.PP
+A container can be moved by various methods, which are listed below.
+When a container is moved from one monitor to another, that
+container moves from the desktop it is in to the focused desktop of the monitor it is moved to.
+Container moving can only be performed if the container is not fullscreen
+and not maximized.
+.IP \(bu 2
+By pressing the modifier key (set with the
+.B \-m
+command-line option) and dragging any part of a container with the mouse button 1
+(the left mouse button).
+.IP \(bu 2
+By dragging the container border with the mouse button 3 (the right mouse button),
+without pressing any modifier.
+.IP \(bu 2
+By dragging a tab with the mouse button 1 (the left mouse button),
+without pressing any modifier.
.PP
-Each container can or not have each one of the following states:
+A container can be resized by various methods, which are listed below.
+Container resizing can only be performed if the container is not fullscreen
+and not maximized.
+.IP \(bu 2
+By pressing the modifier key (set with the
+.B \-m
+command-line option) and dragging any part of a container with the mouse button 3
+(the right mouse button).
+.IP \(bu 2
+By dragging the container border with the mouse button 1 (the left mouse button),
+without pressing any modifier.
+.SS Container states
+.PP
+Each container can or not have each one of the following states.
+By default, a container has no state.
.TP
Maximized
Maximized containers occupies the entire space on the monitor available for windows.
@@ -504,7 +638,7 @@ and they appear on the screen no matter which desktop is focused on that monitor
.TP
Above or below.
A container can be raised above or lowered below other containers.
-.SS Prompt
+.SH PROMPT
A window of type
.B _NET_WM_WINDOW_TYPE_PROMPT
(called prompt window)
@@ -517,7 +651,7 @@ only used by
.B shod
does not change the size of the prompt window.
However, shod changes its position.
-.SS Desktop windows
+.SH DESKTOP WINDOWS
Windows of type
.B _NET_WM_WINDOW_TYPE_DESKTOP
(called desktop windows)
@@ -532,7 +666,7 @@ and windows that manage desktop icons.
.PP
.B shod
does not change the size nor the position of desktop windows.
-.SS Notifications
+.SH NOTIFICATIONS
Windows of type
.B _NET_WM_WINDOW_TYPE_NOTIFICATION
(called notifications)
@@ -551,55 +685,10 @@ command-line option.
.PP
.B shod
can change the size and the position of notification windows.
-.SS Dropdown windows
+.SH DROPDOWN WINDOWS
TODO
-.SS Docked windows
+.SH DOCKED WINDOWS
TODO
-.SH USAGE
-The main method for managing containers and windows is the mouse.
-.PP
-The mouse buttons set with the
-.B \-f
-command-line option are used to focus a container when clicking on it.
-If no mouse button is specified, the focus follows the mouse pointer.
-.PP
-The mouse buttons set with the
-.B \-r
-command-line option are used to raise a container when clicking on it.
-.PP
-The modifier set with the
-.B \-m
-command-line option is the modifier key.
-Pressing the modifier key and dragging a container with the mouse button 1
-(the left mouse button) will move that container.
-Pressing the modifier key and dragging a container with the mouse button 3
-(the right mouse button) will resize that container.
-.PP
-Resizing a container can also be performed by dragging the container border with the mouse button 1,
-without pressing any modifier.
-Moving a container can also be performed by dragging the container border with the mouse button 3,
-without pressing any modifier.
-Moving a container can also be performed by dragging a tab with the mouse button 1,
-without pressing any modifier.
-.PP
-A window can be detached from its container by dragging it by the tab with the mouse button 3.
-A detached window, while being dragged this way,
-can be attached as a new tab into another container by dropping it next to an existing tab;
-or can be attached into a new row or column on another container by dropping it on a column or row division.
-.PP
-Each row has two buttons on its title bar.
-Clicking with the mouse button 1 on the left title bar button can be used to maximize the row on the column
-while minimizing all the other rows (this operation is called "restacking").
-Clicking with the mouse button 3 on the left title bar button can be used to drag and drop the row around the container.
-Clicking with the mouse button 1 on the right title bar button closes the window on the focused tab, and
-if it was the last window on the container, deletes the container.
-.PP
-The divisions between columns and rows can be dragged with the mouse button 1 (the left mouse button)
-to rearrange the size of columns and rows.
-.PP
-When a container is moved from one monitor to another,
-that container moves from the desktop it is in to the focused desktop
-of the monitor it is moved to.
.SH ENVIRONMENT
The following environment variables affect the execution of
.B shod
@@ -609,9 +698,11 @@ The display to start
.B shod
on.
.SH SEE ALSO
+.IR X (1),
.IR xprompt (1),
.IR xnotify (1)
.SH BUGS
+.PP
.IR XSizeHints (3)
are ignored.
Size hints make no sense in a tiled and tabbed window manager.
@@ -621,3 +712,8 @@ When the size of a container depends on the size of other windows (as in the til
or when a set of windows must have the same size (as in a tabbed situation),
it makes no sense to constrain the size of a container based on the size hints of a single window,
because the relation from windows to containers is no more one-to-one.
+.PP
+Different from other window managers,
+in
+.BR shod ,
+shaped client\-windows are not shapped.
diff --git a/shodc.c b/shodc.c
@@ -724,12 +724,15 @@ state(int argc, char *argv[])
break;
case 'a':
state1 = atoms[_NET_WM_STATE_ABOVE];
+ state2 = None;
break;
case 'b':
state1 = atoms[_NET_WM_STATE_BELOW];
+ state2 = None;
break;
case 'f':
state1 = atoms[_NET_WM_STATE_FULLSCREEN];
+ state2 = None;
break;
case 'M':
state1 = atoms[_NET_WM_STATE_MAXIMIZED_VERT];
@@ -737,9 +740,11 @@ state(int argc, char *argv[])
break;
case 'm':
state1 = atoms[_NET_WM_STATE_HIDDEN];
+ state2 = None;
break;
case 's':
state1 = atoms[_NET_WM_STATE_STICKY];
+ state2 = None;
break;
default:
usage();
