git clone git://oldgit.suckless.org/wmii/
Log | Files | Refs | README | LICENSE

gettingstarted.tex (13908B)

      1 \chapter{Getting Started}
      3 This section will walk you through your first \wmii\ startup.
      4 For your first experience, we recommend running \wmii\ in its
      5 own X session, so you can easily switch back to a more
      6 comfortable environment if you get lost. Though you may start
      7 \wmii\ from a session manager in your day to day use, these
      8 instructions will use |xinit|. To begin with, copy this file
      9 to your home directory, so we can open it in your new X session.
     10 Then setup your |~/.xinitrc| as follows:
     12 \begin{code}
     13   cd
     15   # Start a PDF viewer with this guide. Use any viewer
     16   # you're comfortable with.
     17   xpdf wmii.pdf &
     19   # Launch wmii
     20   exec wmii
     22   # That was easy.
     23 \end{code}
     25 Before you run |xinit|, make sure you know how to switch
     26 between terminals. Depending on your system, your current X
     27 session is probably on terminal 5 or 7. You should be able to
     28 switch between your terminals by pressing
     29 Ctrl-Alt-F$\langle n\rangle$. Assuming that your current X
     30 session is on terminal 7, you should be able to switch between
     31 it and your new session by pressing Ctrl-Alt-F7 and Ctrl-Alt-F8.
     32 Now you should be ready to start \wmii. When you run the
     33 following command, you should be presented with a new X session
     34 running wmii and a PDF viewer showing this document.
     36 \begin{code}
     37   xinit
     38 \end{code}
     40 When you're there, find this page in the new PDF viewer and
     41 continue.
     43 \section{Your First Steps}
     45 If everything went according to plan, you should be viewing this
     46 from a nearly empty \wmii\ session. We're going to be using the
     47 keyboard a lot, so let's start with a convention for key
     48 notation. We'll be using the key modifiers Control, Alt, Shift,
     49 and Meta\footnote{The Windows$^{\mbox{\tiny®}}$ key on most
     50 keyboards. The Penguin key on the more tongue in cheek
     51 varieties.}, which we'll specify as C-, A-, S-, and M-,
     52 respectively. So, <C-S-a> means pressing ‘|a|’ while holding
     53 |Control| and |Shift|.  We'll also express mouse clicks this
     54 way, with <M-Mouse1> signifying a press of the right mouse
     55 button, with the Meta key depressed.  Buttons 4 and 5 are the up
     56 and down scroll wheel directions, respectively.
     58 \subsection{Floating Mode}
     60 Beginning with what's familiar to most users, we'll first explore
     61 floating mode. First, we need to select the floating layer.
     62 Press <M-Space>. You should see the titlebar of this window
     63 change color. Now, press <M-Return> to launch a terminal.
     64 The easiest way to drag the terminal around is to press and hold
     65 <M-Mouse1> over the window and simply drag the window
     66 around. You should be able to drag the window anywhere onscreen
     67 without ever releasing the mouse button. As you drag near the
     68 screen edges, you should notice a snap. If you try to drag the
     69 window fully off-screen, you'll find it constrained so that a
     70 portion always remains visible. Now, release the window and move
     71 the mouse toward one of its corners. Press and hold
     72 <M-Mouse3>\footnote{The right button.}. As you drag the
     73 mouse around, you should see the window resized accordingly.
     75 To move the window without the modifier key, move the pointer
     76 over the layout box to the left of its titlebar. You should see
     77 the cursor change. Now, simply click and drag. To resize it,
     78 move the pointer toward the window's edge until you see the
     79 cursor change, and again, click and drag. Now, to close the
     80 window, move the mouse over the windows titlebar, press and hold
     81 <Mouse3>, select |Delete|, and release it. You should
     82 see this window's titlebar return to its original color,
     83 indicating that it's regained focus.
     85 \subsection{Managed Mode}
     87 Now, for the fun part. We'll start exploring managed mode by
     88 looking at the basics of columns. In the default configuration,
     89 columns have three modes:
     91 \begin{description}
     92   \item[Stack] <M-s> The default mode for new columns. Only one window
     93     is fully visible per column at once. The others only display
     94     their title bars. When new windows are added to the column,
     95     the active window collapses, and the new one takes its
     96     place. Whenever a collapsed client is selected, the active
     97     window is collapsed to take its place.
     98   \item[Max] <M-m> Like stack mode, but the titlebars of collapsed
     99     clients are hidden.
    100   \item[Default] <M-d> Multiple uncollapsed windows may be visible at
    101     once. New windows split the space with the other uncollapsed
    102     windows in their vicinity. Windows may still be collapsed by
    103     shrinking them to the size of their titlebars. At this
    104     point, the behavior of a stack of collapsed and uncollapsed
    105     clients is similar to that of stack mode.
    106 \end{description}
    108 Before we open any new windows in managed mode, we need to
    109 explore the column modes a bit. Column modes are activated with
    110 the key bindings listed above. This column should be in stack
    111 mode now. Watch the right side of the titlebar as you press
    112 <M-m> to enter max mode. You should see an indicator appear.
    113 This tells you the number of hidden windows directly above and
    114 below the current window, and its position in that stack. Press
    115 <M-d> to enter default mode. Now we're ready to open another
    116 client. Press <M-Return> to launch another terminal. Now,
    117 press <M-S-l> to move the terminal to a new column to the
    118 right of this one. Once it's there, press <M-Return> two
    119 more times to launch two more terminals. Now that you have more
    120 than one window in a column, cycle through the three column
    121 modes again until they seem familiar.
    123 \subsection{Keyboard Navigation}
    125 To begin, switch back to default mode. The basic keyboard
    126 navigation keys, <M-h>, <M-j>, <M-k>, and <M-l>,
    127 derive from vi, and represent moving left, down, up, and right
    128 respectively. Try selecting each of the four windows currently
    129 visible on screen. Notice that navigation wraps from one side of
    130 the screen to the other, and from the top to the bottom. Now,
    131 return to the write column, switch to stack mode, and select
    132 each of the three terminals again. Do the same in max mode,
    133 paying careful attention to the indicator to the right of the
    134 titlebar.
    136 Now that you can select windows, you'll want to move them
    137 around. To move a window, just add the Shift key to the
    138 direction keys. So, to move a window left, instead of <M-h>,
    139 type <M-S-h>. Now, experiment with moving windows, just as
    140 you did with navigating them, in each of the three column modes.
    141 Once you're comfortable with that, move a window to the floating
    142 layer. Since we toggled between the floating and managed layers
    143 with <M-Space>, we'll move windows between them with
    144 <M-S-Space>. Try moving some windows back and forth until it
    145 becomes familiar. Now, move several windows to the floating
    146 layer and try switching between them with the keyboard. You'll
    147 notice that <M-h> and <M-l> don't function in the
    148 floating layer. This is for both historical and logistical
    149 reasons. <M-j> and <M-k> cycle through floating windows
    150 in order of their most recent use.
    152 \subsection{Mouse Navigation}
    154 \wmii\ uses the “sloppy focus” model, which is to say, it focuses
    155 windows when the mouse enters them and when you click them. It
    156 focuses windows only when you select them with the keyboard,
    157 click their titlebars, or press click them with <M-Mouse2>.
    158 Collapsed windows may be opened with the mouse by clicking their
    159 titlebars. Moving and resizing floating windows should be
    160 largely familiar, and has already been covered. The same can't
    161 be said for managed windows.
    163 Let's begin working with the mouse in the managed layer. Return
    164 to a layout with this document in a column on the left, and
    165 three terminals in a column to the right. Switch the right
    166 column to default mode. Now, bring the mouse to the top of the
    167 third terminal's titlebar until you see a resize cursor. Click
    168 and drag the titlebar to the very top of the screen. Now, move
    169 the cursor to the top of the second terminal's titlebar and drag
    170 it to the very bottom of the screen. Press <M-d> to restore the
    171 terminals to their original sizes. Now, click and hold the
    172 layout box of the second terminal. Drag it to the middle of the
    173 terminal's window and release. Click and hold the layout box of
    174 the third terminal and drag it to the middle of the first
    175 terminal's window. Finally, drag the first terminal's layout box
    176 to halfway down this window. <M-Mouse1> works to the same
    177 effect as dragging the layout box, but allows you to click
    178 anywhere in the window.
    180 Now that you've seen the basics of moving and dragging windows,
    181 let's move on to columns. Click and drag the border between the
    182 two columns. If that's a difficult target to click, there's a
    183 triangle at the top of the division between the two columns that
    184 you can click and drag as well. If that's still too hard a
    185 target, try using <M-Mouse3>, which works anywhere and provides
    186 much richer functionality.
    188 \subsection{Window Focus and Selection}
    190 For the purposes of keyboard navigation, \wmii\ keeps track of
    191 which window is currently selected, and confers its titlebar a
    192 different color scheme from the other windows. This window is
    193 the basis of relative motion commands, such as “select the
    194 window to the left”, and the target of commands such as “close
    195 this window”. Normally, the selected window is the same as the
    196 focused window, i.e., the window that receives keyboard events.
    197 Some applications, however, present strange corner cases.
    199 \begin{description}
    200   \item[Focused, selected window] This is the normal case of a
    201     window which is both selected and has the keyboard focus.
    202     \titlebar{selected}
    203   \item[Unfocused, unselected window] This is the normal case for an
    204     unselected window which does not have the keyboard focus.
    205     \titlebar{unselected}
    206   \item[Unfocused, selected window] This is the first unusual
    207     case. This is the selected window, for the purposes of
    208     keyboard navigation, but it does not receive keyboard events.
    209     A good example is an onscreen keyboard, which will receive
    210     mouse clicks and translate them to keyboard events, but
    211     won't absorb those keyboard events itself. Other examples
    212     include any window whilst another (such as \wimenu) has
    213     grabbed the keyboard.
    214     \titlebar{unfocused}
    215   \item[Focused, unselected window] This is the second unusual
    216     focus case. The window has the keyboard focus, but for the
    217     purposes of keyboard navigation, it is not considered
    218     selected. In the case of an onscreen keyboard, this is the
    219     window which will receive the generated events. In the case
    220     of a keyboard grab, the will likely be the window holding
    221     the grab.
    222     \titlebar{focused}
    223 \end{description}
    225 \section{Running Programs}
    227 You've already seen the convenient key binding to launch a
    228 terminal, but what about other programs? To get a menu of all of
    229 the executables in your path, type <M-p>. This should replace
    230 the bar at the bottom of the screen with a prompt, followed by a
    231 string of completions. Start typing the name of a program that
    232 you want to open. You can press <Tab> and <S-Tab> to cycle
    233 through the completions, or you can just press <Return> to
    234 select the first one. If you want to execute a more complex
    235 command, just type it out and press <Return>. If you want to
    236 recall that command later, use \wimenu's history. Start typing
    237 the command you want and then press <C-p> until you come to it.
    239 When you're done with a program, you'll probably want an easy
    240 way to close it. The first way is to ask the program to close
    241 itself. Since that can be tedious (and sometimes impossible),
    242 \wmii\ provides other ways. As mentioned, you can right click
    243 the titlebar and select |Delete|. If you're at the keyboard,
    244 you can type <M-S-c>. These two actions cause \wmii\ to ask
    245 nicely that the program exit. In those sticky cases where the
    246 program doesn't respond, \wmii\ will wait 10 seconds before
    247 prompting you to kill the program. If you don't feel like
    248 waiting, you can select |Kill| from the window's titlebar
    249 menu, in which case \wmii\ will forcefully and immediately kill
    250 it. Beware, killing clients is a last resort. In cases where the
    251 same program opens multiple windows, killing one will kill them
    252 all—without warning.
    254 \section{Using Views}
    256 As already noticed, \wmii's concept of virtual workspaces is
    257 somewhat unique, so let's begin exploring it. Open up a terminal
    258 and press <M-S-2>. You should see a new button on the bar at the
    259 bottom of the screen. When you click it, you should see your
    260 original terminal. Press <M-1> to come back here. Now, press
    261 <M-3>, and <M-1> again to return here once more. Notice that the
    262 views were created when needed, and destroyed when no longer
    263 necessary. If you want to select a view with a proper name, use
    264 <M-t> and enter the name. Other than the dynamic creation of
    265 views, this is still similar to the familiar X11 workspace
    266 model. But that's just the beginning of \wmii's model. Open a new
    267 terminal, and type:
    269 \begin{code}
    270   echo ‘Hello world!’
    271 \end{code}
    273 \noindent Now, type <M-S-t>. In the menu that appears, enter
    274 |1+2+3|. Now, visit the views |1|, |2|, and |3|, and you'll see
    275 the client on each. To remove a tag, type <M-S-t> again, and
    276 this time enter |-2|. You'll notice that the client is no longer
    277 on the |2| view. Finally, tag names needn't be discrete,
    278 ordinary strings. They can also be regular expressions. Select
    279 the terminal again, and enter |+/^5/|. Now, switch to the |5|
    280 view.  Now try the |6| view. Finally, type <M-t> and enter |50|
    281 to check the |50| view. Clients tagged with regular expressions
    282 are attached to any matching views when they're created. So,
    283 when you switch to an empty view, or tag a client with a new
    284 tag, any clients with matching regular expressions are
    285 automatically added to it. When all explicitly tagged clients
    286 disappear from the view, and it's no longer visible, clients
    287 held there by regular expressions are automatically removed.
    289 \section{Learning More}
    291 For full tables of the standard key bindings, and descriptions
    292 of the precise semantics of the topics discussed above, you
    293 should refer to \wmii's |man| pages.