Eric Abrahamsen <e...@ericabrahamsen.net> writes:
> Thanks for all the comments, and I'm glad this seems welcome! I did
> indeed write it in org-mode, because that seemed easiest as a first
> step, but I certainly intend to send a proper texinfo patch when we're
> done. Org will export both to texinfo, and to HTML (for use on the
> wiki). I'll send along the org source as well, for good measure.
>
> I've put some comments on your comments below. I guess I'll give it a
> couple of days to see if anyone else wants to make changes, then send
> along another version.
Okay, here's what I think could be the final version. I rearranged some
things (merged the screens and heads together), and added some stuff.
Right now the only outstanding question is how the frame tree actually works...
Basic Concepts
══════════════
Screens and Heads
─────────────────
A screen is an Xlib concept representing a section of video memory
onto which physical monitors, called “heads”, are mapped. A screen can
be thought of as an abstract rectangle containing all the heads
arranged in a particular layout.
With most modern systems, you’ll only have a single screen no matter
how many heads are connected to your computer. Each head will have its
own frame, and you can move between heads using the normal frame
movement commands.
The layout of the heads within the screen can be specified in one of
two ways: either at startup using your system’s Xorg configuration
files, or on the fly using tools like XRandR or Xinerama. If the
computer is booted with multiple monitors attached, but without
specifying a layout for them, they will all show identical output.
StumpWM will attempt to detect the layout of the heads once at
startup, or any time a RandR command is issued.
In rarer setups you may 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.
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
───────────────
Within a floating group, windows behave more like they do in
traditional window managers: rather than being arranged into frames,
they each have their own box, which can be freely resized and
repositioned, and allowed to overlap. Each window is has a thicker
border at the top. Left click in this border and drag to move the
window, or right click and drag to resize it.
Most of the window-switching commands listed below do not function in
a floating group. You’re restricted to `other’, the `select-window-*’
commands, and `windowlist’.
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 windows side-by-side,
you can “split” this frame in two, either vertically or horizontally.
These frames can be further split, creating nested boxes.
Technically speaking, frames live within a “frame tree”. When you
split a frame, the command actually creates /two/ new frames
side-by-side within the original parent frame. This makes no practical
difference, unless you use the `sibling’ command, which will move to
the other child frame within the parent frame. [Is this paragraph even
correct? I tested it by splitting a head into left-and-right frames,
then splitting each of those frames top-and-bottom. Calling `sibling’
in any of the four frames moved to the top left frame, ie the
“original” one. On the right-hand side, at least, I would have
expected `sibling’ to move between top and bottom.]
Within this frame tree model, all frames either contain other frames,
or windows. The command `fclear’ will hide all a frame’s windows and
show the background.
Windows
───────
Windows are created by programs to display their output. They take the
shape of the frame in which they are created. The windows within a
frame are ordered by how recently that window was focused. Only the
top window in the stack is visible.
System Trays and the Mode Line
──────────────────────────────
Many users choose to sacrifice a little screen real-estate to display
some generally useful information: the current time and date, wireless
network connections, the names of open windows, etc. StumpWM allows
you to display this information in a bar across either the top or the
bottom of the screen. There are two ways to do this: using external
programs called system trays, or using StumpWM’s own mode line.
System trays are a special kind of X window. They advertise to running
programs that they are available for embedding icons or notifications
from those programs. They often also display clickable icons for each
open window. Common tray programs include the GNOME panel or KDE’s
kicker, or simpler programs such as stalonetray. Simply starting one
of these programs is usually enough for StumpWM to detect it, place it
correctly, and allow it to function normally.
The mode line, a concept borrowed from Emacs, is a built-in part of
StumpWM. It is essentially a string of text that can include a variety
of information about your current session, including the names of
current groups and windows. Several contrib modules provide for
different types of information. See The Mode Line (and the contrib
directory) for more.
Manipulating Frames and Windows
═══════════════════════════════
Frames and windows are concepts borrowed from Emacs and the GNU Screen
program, and should be familiar to users of those programs. Others may
find the terms a little confusing. In other window managers, a
“window” usually refers to a bounded box on the screen, showing output
from a single program. StumpWM splits this into two concepts: the
“frame” is the bounded box, the “window” is the visible output of a
program.
One frame can contain many windows. As new windows are created, they
appear at the top of the window-stack of the current frame. This is
also a little different from other tiling window managers, many of
which automatically create new frames for new windows.
Both frames and windows are ordered by when they were last focused. In
the following commands and documentation, the terms “next” and
“previous” refer to this order, and “other” refers to the
most-recently focused object. Calling “other” commands multiple times
will bounce back and forth between the two most recent objects.
By default, StumpWM starts with a single group, called “Default”,
which 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. When a
frame is split, the next-most-recently-focused window is pulled into
the new frame. See the Frames and Windows sections of the manual for a
complete listing of commands.
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) prompt for a direction,
then swap the currently focused window with the top window of the
frame in that direction.
_______________________________________________
Stumpwm-devel mailing list
Stumpwm-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
