Musca Tutorial

First Steps

Note that below we will refer to the Mod4 key on your keyboard. This is usually mapped to the Super_L key in X. On most PC keyboard mappings, Super_L is usually the left Windows key. When we say press Mod4 + <key>, it means first press and hold down Mod4, then press <key>, then release both.

The Default Screen

After starting Musca, you should see a blank screen with a single pixel blue border around it. This is the default single full screen frame.

Note that the screen background is not set by Musca; it will be the default X cross hatch pattern or whatever desktop graphic was placed there by your login manager. In the screenshots here, the X background was made plain white by running:

xsetroot -solid white

If you start an application now, it will fill the entire frame and hence the entire screen. Press Mod4+t and an xterm window should start, filling the frame.

Manually Tile the Screen

Musca's manual tiling means that you decide how you want the screen to be divided up into frames; it will not be done automatically for you. Each frame can only display a single window at any one time. Try dividing the screen horizontally into two frames by pressing Mod4+h. The xterm you opened above should now take up only the left half of the screen, and you should see a new empty frame appear on the right. The left frame should have a blue border indicating it has the keyboard focus, and the right frame should have a grey border indicating it is unfocused.

Press Mod4+Right (the right arrow). The right frame should now have a blue focus border and the left frame a grey unfocused border. The xterm window inside the left frame should also have lost the keyboard focus. Pressing Mod4+Left will move the focus back to the left frame.

Move the focus to the right frame, and press Mod4+t again. A second xterm window will start and fill the right frame. Press Mod4+v and the right frame will divide into two frames stacked vertically, resulting in three frames on the screen. The xterm windows will be displayed in the left and top right frames, while the newest bottom right frame is empty. Press Mod4+Down to move the focus down to the bottom right frame. Press Mod4+Up to move focus back up to the top right frame. You can also move the focus between frames by clicking on them with any mouse button.

Move the focus to the bottom right frame and press Mod4+r. The focused frame will be removed and the remaining frames resized to fill the gap. Now press Mod4+u. The last frame change will be reverted, or undone, recreating the bottom right frame. Finally press Mod4+o. This will cause all frames to be removed and the default single full screen frame to reappear. Using these basic keyboard controls, try creating a few different frame layouts.

Note that it is also possible to split frames into unequal portions, and not just by halves as we've demonstrated here. We'll cover this below.

Move Windows Around

Here are a few basics on handling windows with the keyboard:

Windows can also be selected by name using dmenu. Press Mod4+w and use dmenu as normal to select a window to raise and focus. If the selected window is already visible in a frame, it will be focused in position. If the selected window is not visible in a frame, it will be raised into the currently focused frame.

Start Applications

Reset the screen layout to the default single full screen frame and close any open applications. Now press Mod4+x. A dmenu window will appear at the bottom of the screen and will list every application installed in your $PATH.

Start typing the name of an application you wish to start, for example firefox. As you type, dmenu will reduce the list of options to show only those containing the characters you have input. Once the list is small enough, use the arrow keys to select the correct application. Finally, press the return (or enter) key to start the selected application.

Run Musca Commands

Dmenu is also used for running commands to control Musca. Reset the screen layout to the default single full screen frame and close any open applications. Press Mod4+m and look at the list of Musca commands displayed. Type the characters hs to find the hsplit command, then press the Tab key to select it. This command needs an argument, so enter 70% after it, so it looks like this:

Press return (or enter). Musca will execute the command hsplit 70%, which happens to be an instruction to tile the screen horizontally into two frames (just like the Mod4+h key binding did above), with the first frame being 70% of the screen width and the second frame being the remaining 30% of the screen width.

Use Window Groups

A window group is roughly the same as a virtual desktop in mainstream window managers. We don't call our groups desktops because they have some underlying differences, and also we have ideas for experiementing with some distinctly non-desktop like behavior in future releases.

So, a group consists of:

Press Mod4+g to start dmenu with a list of groups. From here, you can switch to a group by name or number. Execute the Musca command add mickeymouse, replacing mickeymouse with a name of your choosing. You should see your current frames and applications disapear and the default single full screen frame appear in their place. Press Mod4+g again and try switching back and forth between the default and mickeymouse groups.

Some basic Musca commands for working with groups include: