# wmii

git clone git://oldgit.suckless.org/wmii/

gettingstarted.tex (13908B)

      1 \chapter{Getting Started}
2
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:
11
12 \begin{code}
13   cd
14
15   # Start a PDF viewer with this guide. Use any viewer
16   # you're comfortable with.
17   xpdf wmii.pdf &
18
19   # Launch wmii
20   exec wmii
21
22   # That was easy.
23 \end{code}
24
25 Before you run |xinit|, make sure you know how to switch
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.
35
36 \begin{code}
37   xinit
38 \end{code}
39
40 When you're there, find this page in the new PDF viewer and
41 continue.
42
44
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.
57
58 \subsection{Floating Mode}
59
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.
74
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
83 indicating that it's regained focus.
84
85 \subsection{Managed Mode}
86
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:
90
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}
107
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.
122
124
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.
135
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.
151
153
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.
162
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.
179
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.
187
188 \subsection{Window Focus and Selection}
189
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.
198
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
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}
224
225 \section{Running Programs}
226
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.
238
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.
253
254 \section{Using Views}
255
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:
268
269 \begin{code}
270   echo ‘Hello world!’
271 \end{code}
272
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.
288
289 \section{Learning More}
290
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.
294