wmii/doc/gettingstarted.tex

\chapter{Getting Started}

This section will walk you through your first \wmii\ startup.
For your first experience, we recommend running \wmii\ in its
own X session, so you can easily switch back to a more
comfortable environment if you get lost. Though you may start
\wmii\ from a session manager in your day to day use, these
instructions will use |xinit|. To begin with, copy this file
to your home directory, so we can open it in your new X session.
Then setup your |~/.xinitrc| as follows:

\begin{code}
  cd

  # Start a PDF viewer with this guide. Use any viewer
  # you're comfortable with.
  xpdf wmii.pdf &

  # Launch wmii
  exec wmii

  # That was easy.
\end{code}

Before you run |xinit|, make sure you know how to switch
between terminals. Depending on your system, your current X
session is probably on terminal 5 or 7. You should be able to
switch between your terminals by pressing
Ctrl-Alt-F$\langle n\rangle$. Assuming that your current X
session is on terminal 7, you should be able to switch between
it and your new session by pressing Ctrl-Alt-F7 and Ctrl-Alt-F8.
Now you should be ready to start \wmii. When you run the
following command, you should be presented with a new X session
running wmii and a PDF viewer showing this document.

\begin{code}
  xinit
\end{code}

When you're there, find this page in the new PDF viewer and
continue.

\section{Your First Steps}

If everything went according to plan, you should be viewing this
from a nearly empty \wmii\ session. We're going to be using the
keyboard a lot, so let's start with a convention for key
notation. We'll be using the key modifiers Control, Alt, Shift,
and Meta\footnote{The Windows$^{\mbox{\tiny®}}$ key on most
keyboards. The Penguin key on the more tongue in cheek
varieties.}, which we'll specify as C-, A-, S-, and M-,
respectively. So, <C-S-a> means pressing ‘|a|’ while holding
|Control| and |Shift|.  We'll also express mouse clicks this
way, with <M-Mouse1> signifying a press of the right mouse
button, with the Meta key depressed.  Buttons 4 and 5 are the up
and down scroll wheel directions, respectively.

\subsection{Floating Mode}

Beginning with what's familiar to most users, we'll first explore
floating mode. First, we need to select the floating layer.
Press <M-Space>. You should see the titlebar of this window
change color. Now, press <M-Return> to launch a terminal.
The easiest way to drag the terminal around is to press and hold
<M-Mouse1> over the window and simply drag the window
around. You should be able to drag the window anywhere onscreen
without ever releasing the mouse button. As you drag near the
screen edges, you should notice a snap. If you try to drag the
window fully off-screen, you'll find it constrained so that a
portion always remains visible. Now, release the window and move
the mouse toward one of its corners. Press and hold
<M-Mouse3>\footnote{The right button.}. As you drag the
mouse around, you should see the window resized accordingly.

To move the window without the modifier key, move the pointer
over the layout box to the left of its titlebar. You should see
the cursor change. Now, simply click and drag. To resize it,
move the pointer toward the window's edge until you see the
cursor change, and again, click and drag. Now, to close the
window, move the mouse over the windows titlebar, press and hold
<Mouse3>, select |Delete|, and release it. You should
see this window's titlebar return to its original color,
indicating that it's regained focus.

\subsection{Managed Mode}

Now, for the fun part. We'll start exploring managed mode by
looking at the basics of columns. In the default configuration,
columns have three modes:

\begin{description}
  \item[Stack] <M-s> The default mode for new columns. Only one window
    is fully visible per column at once. The others only display
    their title bars. When new windows are added to the column,
    the active window collapses, and the new one takes its
    place. Whenever a collapsed client is selected, the active
    window is collapsed to take its place.
  \item[Max] <M-m> Like stack mode, but the titlebars of collapsed
    clients are hidden.
  \item[Default] <M-d> Multiple uncollapsed windows may be visible at
    once. New windows split the space with the other uncollapsed
    windows in their vicinity. Windows may still be collapsed by
    shrinking them to the size of their titlebars. At this
    point, the behavior of a stack of collapsed and uncollapsed
    clients is similar to that of stack mode.
\end{description}

Before we open any new windows in managed mode, we need to
explore the column modes a bit. Column modes are activated with
the key bindings listed above. This column should be in stack
mode now. Watch the right side of the titlebar as you press
<M-m> to enter max mode. You should see an indicator appear.
This tells you the number of hidden windows directly above and
below the current window, and its position in that stack. Press
<M-d> to enter default mode. Now we're ready to open another
client. Press <M-Return> to launch another terminal. Now,
press <M-S-l> to move the terminal to a new column to the
right of this one. Once it's there, press <M-Return> two
more times to launch two more terminals. Now that you have more
than one window in a column, cycle through the three column
modes again until they seem familiar.

\subsection{Keyboard Navigation}

To begin, switch back to default mode. The basic keyboard
navigation keys, <M-h>, <M-j>, <M-k>, and <M-l>,
derive from vi, and represent moving left, down, up, and right
respectively. Try selecting each of the four windows currently
visible on screen. Notice that navigation wraps from one side of
the screen to the other, and from the top to the bottom. Now,
return to the write column, switch to stack mode, and select
each of the three terminals again. Do the same in max mode,
paying careful attention to the indicator to the right of the
titlebar.

Now that you can select windows, you'll want to move them
around. To move a window, just add the Shift key to the
direction keys. So, to move a window left, instead of <M-h>,
type <M-S-h>. Now, experiment with moving windows, just as
you did with navigating them, in each of the three column modes.
Once you're comfortable with that, move a window to the floating
layer. Since we toggled between the floating and managed layers
with <M-Space>, we'll move windows between them with
<M-S-Space>. Try moving some windows back and forth until it
becomes familiar. Now, move several windows to the floating
layer and try switching between them with the keyboard. You'll
notice that <M-h> and <M-l> don't function in the
floating layer. This is for both historical and logistical
reasons. <M-j> and <M-k> cycle through floating windows
in order of their most recent use.

\subsection{Mouse Navigation}

\wmii\ uses the “sloppy focus” model, which is to say, it focuses
windows when the mouse enters them and when you click them. It
focuses windows only when you select them with the keyboard,
click their titlebars, or press click them with <M-Mouse2>.
Collapsed windows may be opened with the mouse by clicking their
titlebars. Moving and resizing floating windows should be
largely familiar, and has already been covered. The same can't
be said for managed windows.

Let's begin working with the mouse in the managed layer. Return
to a layout with this document in a column on the left, and
three terminals in a column to the right. Switch the right
column to default mode. Now, bring the mouse to the top of the
third terminal's titlebar until you see a resize cursor. Click
and drag the titlebar to the very top of the screen. Now, move
the cursor to the top of the second terminal's titlebar and drag
it to the very bottom of the screen. Press <M-d> to restore the
terminals to their original sizes. Now, click and hold the
layout box of the second terminal. Drag it to the middle of the
terminal's window and release. Click and hold the layout box of
the third terminal and drag it to the middle of the first
terminal's window. Finally, drag the first terminal's layout box
to halfway down this window. <M-Mouse1> works to the same
effect as dragging the layout box, but allows you to click
anywhere in the window.

Now that you've seen the basics of moving and dragging windows,
let's move on to columns. Click and drag the border between the
two columns. If that's a difficult target to click, there's a
triangle at the top of the division between the two columns that
you can click and drag as well. If that's still too hard a
target, try using <M-Mouse3>, which works anywhere and provides
much richer functionality.

\subsection{Window Focus and Selection}

For the purposes of keyboard navigation, \wmii\ keeps track of
which window is currently selected, and confers its titlebar a
different color scheme from the other windows. This window is
the basis of relative motion commands, such as “select the
window to the left”, and the target of commands such as “close
this window”. Normally, the selected window is the same as the
focused window, i.e., the window that receives keyboard events.
Some applications, however, present strange corner cases.

\begin{description}
  \item[Focused, selected window] This is the normal case of a
    window which is both selected and has the keyboard focus.
    \titlebar{selected}
  \item[Unfocused, unselected window] This is the normal case for an
    unselected window which does not have the keyboard focus.
    \titlebar{unselected}
  \item[Unfocused, selected window] This is the first unusual
    case. This is the selected window, for the purposes of
    keyboard navigation, but it does not receive keyboard events.
    A good example is an onscreen keyboard, which will receive
    mouse clicks and translate them to keyboard events, but
    won't absorb those keyboard events itself. Other examples
    include any window whilst another (such as \wimenu) has
    grabbed the keyboard.
    \titlebar{unfocused}
  \item[Focused, unselected window] This is the second unusual
    focus case. The window has the keyboard focus, but for the
    purposes of keyboard navigation, it is not considered
    selected. In the case of an onscreen keyboard, this is the
    window which will receive the generated events. In the case
    of a keyboard grab, the will likely be the window holding
    the grab.
    \titlebar{focused}
\end{description}

\section{Running Programs}

You've already seen the convenient key binding to launch a
terminal, but what about other programs? To get a menu of all of
the executables in your path, type <M-p>. This should replace
the bar at the bottom of the screen with a prompt, followed by a
string of completions. Start typing the name of a program that
you want to open. You can press <Tab> and <S-Tab> to cycle
through the completions, or you can just press <Return> to
select the first one. If you want to execute a more complex
command, just type it out and press <Return>. If you want to
recall that command later, use \wimenu's history. Start typing
the command you want and then press <C-p> until you come to it.

When you're done with a program, you'll probably want an easy
way to close it. The first way is to ask the program to close
itself. Since that can be tedious (and sometimes impossible),
\wmii\ provides other ways. As mentioned, you can right click
the titlebar and select |Delete|. If you're at the keyboard,
you can type <M-S-c>. These two actions cause \wmii\ to ask
nicely that the program exit. In those sticky cases where the
program doesn't respond, \wmii\ will wait 10 seconds before
prompting you to kill the program. If you don't feel like
waiting, you can select |Kill| from the window's titlebar
menu, in which case \wmii\ will forcefully and immediately kill
it. Beware, killing clients is a last resort. In cases where the
same program opens multiple windows, killing one will kill them
all—without warning.

\section{Using Views}

As already noticed, \wmii's concept of virtual workspaces is
somewhat unique, so let's begin exploring it. Open up a terminal
and press <M-S-2>. You should see a new button on the bar at the
bottom of the screen. When you click it, you should see your
original terminal. Press <M-1> to come back here. Now, press
<M-3>, and <M-1> again to return here once more. Notice that the
views were created when needed, and destroyed when no longer
necessary. If you want to select a view with a proper name, use
<M-t> and enter the name. Other than the dynamic creation of
views, this is still similar to the familiar X11 workspace
model. But that's just the beginning of \wmii's model. Open a new
terminal, and type:

\begin{code}
  echo ‘Hello world!’
\end{code}

\noindent Now, type <M-S-t>. In the menu that appears, enter
|1+2+3|. Now, visit the views |1|, |2|, and |3|, and you'll see
the client on each. To remove a tag, type <M-S-t> again, and
this time enter |-2|. You'll notice that the client is no longer
on the |2| view. Finally, tag names needn't be discrete,
ordinary strings. They can also be regular expressions. Select
the terminal again, and enter |+/^5/|. Now, switch to the |5|
view.  Now try the |6| view. Finally, type <M-t> and enter |50|
to check the |50| view. Clients tagged with regular expressions
are attached to any matching views when they're created. So,
when you switch to an empty view, or tag a client with a new
tag, any clients with matching regular expressions are
automatically added to it. When all explicitly tagged clients
disappear from the view, and it's no longer visible, clients
held there by regular expressions are automatically removed.

\section{Learning More}

For full tables of the standard key bindings, and descriptions
of the precise semantics of the topics discussed above, you
should refer to \wmii's |man| pages.