I've been meaning to do this for a while: when I started using stump I
was pretty confused about some of the basic concepts and behaviors (it
was also my first tiling WM), and I thought the manual could use a
little bit more handholding. I've written a manual addition including
what I would have liked to have known in the beginning, and am posting
it here for comments (there are also direct questions in brackets). I
envision this going in the info manual, in the "Introduction" section,
after "Basic Usage", with both "Basic Concepts" and "Manipulating Frames
and Windows" being separate top-level sections.
I haven't posted this as an actual patch because I thought it would be
easier to incorporate comments/additions/corrections in plain text. If
people agree this is useful and we hash out a final version, I can do
the patch then. Or it can go on the wiki, or whatever! Hope this is
helpful.
E
━━━━━━━━━━━━━━━━━━━━━━━━
STUMPWM INFO ADDITIONS
━━━━━━━━━━━━━━━━━━━━━━━━
Basic Concepts
══════════════
Screens
───────
A screen is an Xlib concept representing a section of video memory
onto which physical monitors (or “heads”) are mapped. Imagine your
computer’s video output as an abstract rectangle into which all the
heads are arranged. The actual location of the heads in this rectangle
is determined not by StumpWM, but by another X-related program such as
Xrandr. [how does stump arrange them if they’re already plugged in
when X starts? simple cloning, right? are there other commonly-used
programs for specifying the location of heads within a screen?]
What this means in practical terms depends on whether you’re using
Xinerama or not.
If you are, you’ll only ever have a single screen no matter how many
monitors are connected to your computer. Each monitor, or head, will
have its own frame, and you can move between heads using the normal
frame movement commands.
If you’re not using Xinerama, you’ll have multiple screens, with one
head per screen. That means that you’ll move between heads using
screen movement commands (`snext’, `sprev’, and `sother’) rather than
frame movement commands.
Heads
─────
A head represents a physical monitor connected to the computer. As
mentioned above, how this plays out depends on whether you’re using
Xinerama.
Groups
──────
A group is usually referred to as a “desktop” or “workspace” in other
window managers. StumpWM starts with a single group, called “Default”.
Each group has its own configuration of frames and windows that is
separate from and independent of other groups. You can’t have
different groups display in different monitors: when you switch
groups, all monitors switch to that group.
Each group contains an ordered list of frames.
Floating Groups
───────────────
[I don’t know enough about what floating groups are or how they work]
Frames
──────
Frames are the boxes within which windows are displayed. StumpWM
starts with a single frame per head, meaning that each monitor shows a
single window, full screen. If you want to see two or more windows
side-by-side, you can “split” this frame.
Frames live within a “frame tree”. As you split frames, each new frame
becomes a child of the frame it was split from. Practically speaking,
this makes no difference, unless you use the `sibling’ command, which
will move to the frame from which the current frame was created. [in
which case, it should probably be called the `parent’ command, no?]
Each frame has its own ordered list of windows, only one of which is
visible at time.
Windows
───────
Windows are created by programs to display their output. Each window
can only belong to a single frame.
Trays and the Mode Line
───────────────────────
[what is a tray? how does the mode line relate to frames? mention the
new stumptray.lisp in contrib?]
Manipulating Frames and Windows
═══════════════════════════════
By default, StumpWM starts with a single group, called “Default”, that
contains one full-screen frame per head. You can split individual
frames horizontally or vertically using the `hsplit’ and `vsplit’
commands, bound to “C-t S” and “C-t s” by default. See the Frames and
Windows sections of the manual for a complete listing of commands.
Both frames and windows exist in ordered lists. In the following
commands, the terms “next” and “previous” refer to relative positions
in these lists.
Moving Between Frames
─────────────────────
Once you have multiple frames, you can move between them in various
ways:
• `fnext’ (“C-t o” or “C-t TAB”) jumps to the next frame in the
current group’s frame list.
• `fother’ (“C-t M-TAB”) jumps to the last frame that had focus.
• `fselect’ (“C-t f”) displays numbers on each visible frame: hit a
number key to move to that frame.
• `move-focus’ (“C-t <arrow key>”) focus the frame in the direction of
the arrow key pressed.
• `sibling’ (unbound by default) focus the frame from which the
current frame was split.
Manipulating Windows
────────────────────
Some commands change which window is currently focused, some move
windows between frames, and some may do both at once.
There are two general ways to move focus between windows: either
between windows belonging to the current frame, or between all windows
within the current group. Within a single frame:
• `next-in-frame’ (“C-t C-M-n”) focus the next window in the current
frame’s list of windows.
• `prev-in-frame’ (“C-t C-M-p”) focus the previous window in the
current frame’s list of windows.
• `other-in-frame’ (“C-t M-t”) focus the most recently focused window
in the current frame’s list of windows.
• `frame-windowlist’ (unbound by default) display a menu of windows in
the currently-focused frame, and allow the user to choose one.
Alternately, the command `frame-windows’ will simply display the
list of window names, with no menu choice available.
Within the current group, the following commands will go straight to
the specified window. They will never move a window from its original
frame, and so may result in focus switching frames.
• `next’ (“C-t M-n”) focus the next window in the current group.
• `prev’ (“C-t M-p”) focus the previous window in the current group.
• `other’ or `other-window’ (unbound by default) focus the most
recently focused window in the current group.
• `next-urgent’ (“C-t C-u”) focus the next window that has marked
itself “urgent”.
• `select’ or `select-window’ (“C-t '”) prompt for the title of a
window and focus it. Works with partial completion of the title.
• `select-window-by-name’ (unbound by default) prompt for the title of
a window and focus it. Requires the window title to be entered
exactly.
• `select-window-by-number’ (“C-t <number>”) choose a window by
number.
• `windowlist’ (“C-t "") display a menu of windows in the
currently-focused group, and allow the user to choose one.
The following commands always keep the current frame focused. If the
selected window is not in the current frame, it will be pulled there
from wherever it is (hence the “pull” naming scheme).
• `pull’ or `pull-window-by-number’ (“C-t C-<number>”) pull the
numbered window into the current frame.
• `pull-hidden-next’ (“C-t n” or “C-t SPC”) pull the next currently
undisplayed window in the window list into the current frame.
• `pull-hidden-previous’ (“C-t p”) pull the previous currently
undisplayed window in the window list into the current frame.
• `pull-hidden-other’ (“C-t C-t”) pull the most recently focused,
currently undisplayed window into the current frame.
The following commands move the current window from one frame to
another, bringing focus with them.
• `move-window’ (“C-t M-<arrow>”) move the currently focused window in
the direction indicated by the arrow key.
• `exchange-direction’ (unbound by default) swap the currently focused
window with the top window of the frame in the direction indicated.
_______________________________________________
Stumpwm-devel mailing list
Stumpwm-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
