\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, means pressing ‘|a|’ while holding |Control| and |Shift|. We'll also express mouse clicks this way, with 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 . You should see the titlebar of this window change color. Now, press to launch a terminal. The easiest way to drag the terminal around is to press and hold 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 \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 , 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] 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] Like stack mode, but the titlebars of collapsed clients are hidden. \item[Default] 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 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 to enter default mode. Now we're ready to open another client. Press to launch another terminal. Now, press to move the terminal to a new column to the right of this one. Once it's there, press 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, , , , and , 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 , type . 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 , we'll move windows between them with . 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 and don't function in the floating layer. This is for both historical and logistical reasons. and 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 . 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 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. 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 , 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 . 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 and to cycle through the completions, or you can just press to select the first one. If you want to execute a more complex command, just type it out and press . If you want to recall that command later, use \wimenu's history. Start typing the command you want and then press 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 . 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 . 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 to come back here. Now, press , and 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 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 . 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 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 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.