Next Previous Contents

4. AfterStep Configuration

4.1 What's a .steprc, and why do I need it anyway?

In versions of AfterStep prior to version 1.2 (including current versions of AfterStepClassic), all configuration is handled in a single file. This is the .steprc file; it should be in your home directory if you're running any of these versions. These files are generally well-commented, and can be edited easily to change the defaults. The default file from version 1.0 included several major sections:

New versions of AfterStep don't use this file, preferring the GNUstep/Library standard instead. The settings for looks and feels, for instance, have been broken out into separate files, and the configurations of Wharf, Pager, and other modules and applications have been placed in their own files. See below.

4.2 I'm using AfterStep 1.2 or later, and I can't find the .steprc. Why?

AfterStep now uses a directory structure to handle desktop customization.

4.3 OK, so how do I customize non-.steprc versions?

This depends on the version you have.

Versions through 1.4.4 need a full set of directories in each user's home directory. In other words, you need to copy everything in




There were several changes to this directory structure between version 1.4.0 and 1.4.4. A full outline of these changes is beyond the scope of this document, but there are some general remarks on particularly common problems below. For more help configuring 1.4.4, see or

In particular, you should note that the ~/G/L/A/ directories are not compatible between versions 1.4.0 and 1.4.4. You must copy the full {AS install}/G/L/A/ directory (including all sub-directories) into your home directory, even if you are only upgrading from 1.4.0 to 1.4.4.

The ~/GNUstep/Library/AfterStep arrangement is, admittedly, somewhat inefficient, because there are always at least two copies of everything on any system running AfterStep. As of versions post-1.4.5, it is possible to add only those files which you have changed to the directory structure in your home directory; everything else will use the default installation in /usr/share/afterstep or /usr/local/share/afterstep (this location varies among versions; the latter is the default in version 1.5). Nevertheless, there are some subtle differences among the configuration files of each version. If you have upgraded, and you suddenly have problems, your first impulse should be to try renaming your ~/G/L/A/ directory, and starting AfterStep. If the problem disappears, you can reasonably presume that it has something to do with your configuration files. That doesn't mean that the answer will be obvious, but it does mean that you'll know where to start looking.

4.4 I just upgraded versions, and now nothing works.

First, determine whether you have upgraded from a ".steprc version" to a "non-.steprc version". Versions after 1.2 do not (by default) use the .steprc file, so your old customization will not be invoked by default if you have moved from, say, 1.0 to 1.4.5.

If you have changed from 1.4.0 to a later version, you need to remove your old version of the ~/GNUstep/Library/AfterStep directory structure. Version 1.4.4 introduced the "configurable" and "non-configurable" distinction, and so several items have moved. See the previous question.

Subtle changes have been introduced between versions; this is even true between, say, 1.4.4 and In particular, several modules have had their configuration files changed to be in keeping with Wharf style. The practical effect of this is apparently inexplicable problems which develop after an upgrade. If you suddenly have problems after an upgrade, and especially if some modules suddenly do not work, try replacing your configuration with the default configuration. If that works, you can edit the new configuration to reflect your previous customization.

It is also important to note that the syntax for looks and feels changed again in version 1.5. Several of these changes have been as a result of requested features or (more often) improvements in the efficiency or ease of use of the overall program. These changes, of course, entail some frustration; but before you ask, "What happened?" you should always try renaming your ~/GNUstep/Library/AfterStep directory, and re-starting. If this solves the problem, you should try customizing the new version, using your old customization as a model. You are likely to be able to re-use most of your old configuration files as they are.

4.5 How do I change my startmenu?

In versions before 1.2, edit the appropriate section of the .steprc. In later versions, you need to adjust the necessary parts of the ~/GNUstep/Library/AfterStep/start directory structure. The start directory includes sub-directories for every sub-menu. It also has a file corresponding to every entry on a menu. Each file should contain a single line to invoke the desired program. So, if you wanted an entry in your main startmenu which said

xiterm (pixmap)

your ~/G/L/A/start directory would contain a file:

xiterm\ (pixmap)

That file would contain a single line:

xiterm -pixmap [path_to_pixmap.xpm] & 

(you would, of course, adjust the command-line options to reflect your intentions).

By default, the sort order of the start menu is determined at compile time. It is usually sorted alphabetically or chronologically (according to the creation date of the file). This has the disadvantage of forcing a sort order which one might not like. As a result, version 1.5 offers a new (completely-worked-out) way to sort menu items.

In version 1.5, the startmenu can be sorted numerically. Suppose you have three files you want to sort in your startmenu, named "a", "b", and "c". You could sort these in reverse alphabetical order in your startmenu by naming them "0_c", "1_b", and "2_c".

You can specify a startmenu name which is different from the filename, by including that startmenu name in quotes in the file which is associated with the startmenu name. For instance, a file named 8_xitermtransparent would be the 8th file in the startmenu. If the contents of the file were as follows, then it would be named "X terminal ~transparent":

Exec "X terminal ~transparent" exec xiterm -pixmap
~/GNUstep/Library/AfterStep/non-configurable/0_background -sl 500 -vb &
MiniPixmap "mini-app.xpm"

(Note that this command should all be on one line in the actual file!) In this case, the xiterm window comes up with the current background of the first desktop in AfterStep; this simulates a "transparent" xterm. For more on "transparent" xterms, please see the section on as-apps.

The sorting of items in the startmenu always puts directories (which are equivalent to sub-menus) first. Directories, however, are themselves sorted according to the same scheme as are files, except that there is no mechanism for naming a sub-menu something other than the directory name.

From version 1.4.5, you also have to read the new startmenu into your configuration. On the startmenu, under "Desktop" (1.5 or later) or "Quit" (< 1.5), is an option, "update startmenu". Choose this item, and your new startmenu will appear.

People who have Red Hat Linux 5.1 have had another problem with the startmenu updating: all changes are lost after exiting. This is because of the way that Red Hat has modified the startup of AfterStep. The version of AfterStep included in Red Hat 5.1 includes an m4 preprocessing routine which, among other things, re-writes the ~/GNUstep/Library/AfterStep/start directory every time AfterStep starts. As a bit of editorial, I (Andrew) might point out that I don't know what this does, nor why Red Hat used it. I also don't intend to learn. If you can't get Red Hat to explain to you what they did, my suggestion is to remove the RPM, and compile and install the official version. David Mihm (, however, suggests that you can get around the m4 preprocessing this way:

echo "exec afterstep" >~/.xinitrc
echo "exec afterstep" >~/.xsessions
chmod 700 ~/.xsessions

It has been suggested (by Ian Hay, that the m4 preprocessing was an attempt on Red Hat's part to make the use of AfterStep more friendly to new users: this preprocessing apparently ensures that new apps get added to the start menu after they've been installed. Matteo Lunardi ( has offered a work-around, at least in some versions. In the xinit-1.4.2.noarch.rpm, he edited the file /etc/X11/xinit/Xclients, this way:

if [ -f $HOME/.wm_style ] ; then
    WMSTYLE=Cat $HOME/.wm_style         case "$WMSTYLE" in 
            # we have to start up afterstep
            if [ -x /usr/X11R6/bin/afterstep -a -f
/usr/share/afterstep/wmconfig.conf ] ; then
#               if [ ! -d $HOME/GNUstep/Library/AfterStep ]; then
                     mkdir -p $HOME/GNUstep/Library/AfterStep
                     wmconfig --output=afterstep --directories \
                        /usr/share/afterstep/wmconfig.conf 2>/dev/null
#               fi
                env > "$HOME"/Xrootenv.0
                # if this works, we stop here
                eval "exec /usr/X11R6/bin/afterstep" >
"$HOME"/.AfterStep-errors 2>&1

In this case, the change was to add comment marks ("#") to the "if" lines (not the one where it says, "if this works, we stop here"). Apparently, however, it also works to add the comment marks to the "mkdir" and "wmconfig" lines.

As an alternative, Kai Puolamaki ( suggests that you configure your wmconfig utility to make things work better. This is likely the best way to make these adjustments. Red Hat's wmconfig utility relies on a system-wide directory, /etc/X11/wmconfig, but is adjustable by users through an individual directory, ~/.wmconfig. So, if you wanted a menu item, "Mail", containing both mutt and elm, you would add two files:


The file "mutt" would contain the following:

mutt name "Mutt"
mutt description "Mutt email client"
mutt group Mail
mutt exec "xterm -e mutt &"

The file "elm" would be similar:

elm name "Elm"
elm description "Elm email client"
elm group Mail
elm exec "xterm -e elm &"

More information is available from the wmconfig manpage. Note that there is an additional advantage to this syntax: it ensures that your menu changes are also available if you change window managers.

4.6 Where did the "Decorations" item go in version 1.5?

The "Decorations" menu has been re-named to "Desktop".

4.7 What are "look", "feel", "desktop", etc. files?

In versions that do not use a .steprc, the various elements of the desktop have been separated out, in order that they can each be customized independently. Look files and feel files allow you to customize the desktop in almost an infinite number of ways. Note that any functional changes you make in a look file (like adjusting the number of buttons that appear on a window titlebar) may need to be reflected in a corresponding feel file: the "feel" handles how you interact with windows, while the "look" controls their appearance. This is handy if you want your windows always to respond in more or less the same way, but want them to look differently depending on the task you're performing, the machine you're on, or whatever.

4.8 Can I have differently-sized buttons on the titlebar?

Yes, but not in every version. It is reported that version 1.5 handles differently-sized titlebar buttons with no difficulty. If you want this functionality, please move to version 1.5.

4.9 Fine, but how do I reduce the number of buttons on the titlebar?

This depends upon what version you are using. Version 1.5 allows you simply to change the look file to reflect the buttons you want. Any version before 1.5 requires a change both to the look and to the feel. The trick here is to understand the difference between a look and a feel. A look file simply determines how elements of the screen will appear. It does not determine how the elements will interact: that's what a feel file does. So, if you want to reduce the number of buttons on a titlebar, you need to adjust both the look and feel files. The look file must define the appearance of exactly the number of buttons for which there are functions in the feel file; and each button defined in the feel file must have a reference in the look file.

To see how this works, consider a look file with the following definitions:

# TitleButtons : [1] [3] [5] [7] [9] (title) [0] [8] [6] [4] [2]
TitleButton 1 b1.xpm b1-pressed.xpm
TitleButton 2 b2.xpm b2-pressed.xpm
TitleButton 3 b3.xpm b3-pressed.xpm
TitleButton 4 b4.xpm b4-pressed.xpm
TitleButton 6 b6.xpm b6-pressed.xpm

Now, this defines the appearance of two buttons on the left of each titlebar (TitleButton 1 and TitleButton3), and three buttons on the right of each titlebar (TitleButton 2, TitleButton 4, and TitleButton 6). For each definition, the first XPM mentioned defines the appearance of the button when it is not pressed; the second XPM defines the way the button looks when it is pressed. The numbering of these buttons is hard-coded, so you cannot just number your buttons in any order at all. Follow the "boilerplate" numbering scheme (above the TitleButton pixmap definitions in our example).

In order to make this look function correctly, each titlebar button needs to have its function defined in the feel file. So, the feel file might include something which looks like this (this one is taken from the feel.DEFAULT file in

Mouse 1         1       A       ChangeWindowUp
Mouse 2         1       A       GetHelp
Mouse 3         1       A       ChangeWindowDown
Mouse 1         2       A       Delete
Mouse 2         2       A       Destroy
Mouse 3         2       A       Destroy
Mouse 1         3       A       PopUp "Window"
Mouse 2         3       A       WindowList 2
Mouse 3         3       A       WindowList 2
Mouse 1         4       A       Shade
Mouse 2         4       A       Stick
Mouse 3         4       A       Stick
Mouse 1         6       A       Iconify
Mouse 2         6       A       Maximize
Mouse 3         6       A       Maximize 

The first column defines what action causes the desired behaviour; so, "Mouse 1" means "mouse button one is pressed". The second column defines where the behaviour is to have its desired effect: in our list, we have definitions for all five (TitleButton 1, TitleButton 2, TitleButton 3, TitleButton 4, and TitleButton 6) of the buttons defined in the look file. Notice that each button gets a definition for every mouse button, so there is never an undefined action on any TitleButton. The third column specifies the context for the action. In this case, the context is "Any" (actually any context except in the TitleBar); you can also specify modifications (e.g. by adding "C" for "Control"). The final column specifies the behaviour which attaches to the action. So, in the last row, we define that clicking the third mouse button on the innermost TitleButton on the right-hand side of a window will Maximize that window.

Other functions get defined in the same list in every feel file, so you will have to look carefully to ensure you define everything correctly.

4.10 Why does some key not work as I expect?

There are two possibilities here. One is that you are having problems with your "delete" or "backspace" key. This is a generic X problem, and you should investigate it by reading the relevant documentation for xmodmap. Try issuing "man xmodmap" at the command prompt.

The second possibility is that you have a set of keypresses which work in another X window manager, but which do not work under your recent installation of AfterStep. In that case, you need to edit the "feel" file. Before you go on, go back and read the previous question about mouse bindings. Done that? Good. Now, keybindings work just the same. So, in your feel file, you might have the following keybinding:

Key Left        A       C       Scroll -100 0

This says that if you press "Control" (3d column) and the left cursor key (1st column) while anywhere on the screen, AfterStep will scroll one page to the left. If you want to get the functionality of "Ctrl-left" back, in order to use it in some other X application, then you'll need to remove this keybinding from your feel file.

You can avoid having any keybinding defined by AfterStep by using one of the included feels: feel.ICCCM. Just select it from the Desktop/Feels (v. 1.5) or Decorations/Feels (v. < 1.5) menu under your startmenu.

4.11 Why can't I have my .steprc in version 1.4.x or later?

You can. Use the -f switch to force AfterStep to read from a file. Please notice that not everything will work with your old .steprc file "right out of the box"; but if you like the old version that much, why upgrade anyway?

That said, version 1.5 has worked out almost all the incompatibility issues.

4.12 I'm using Red Hat, and I can't find the configuration files you've mentioned.

Red Hat apparently used to include a look-alike to AfterStep which is actually a hack of fvwm-2. It is not AfterStep, although some Red Hat distributions also contain the real AfterStep. Red Hat has changed the name of their "hacked" version, in order to reduce confusion.

A "real" version of AfterStep is included in Red Hat Linux 5.1. It uses m4 preprocessing for configuration, however, so not all configuration remarks in this document will be useful to Red Hat users. If you want to configure the AfterStep included in Red Hat, you should ask Red Hat how to do it, or read the documentation for m4, or both. There is some discussion of the Red Hat preprocessing under the startmenu section, above.

4.13 What is the database file?

The database file allows you to adjust certain features of the desktop. It allows you to define icons for minimized programs, allows you to force certain programs (like Pager or Wharf, for instance) to stay on top, and other such options. Have a look at the default database file, back it up, and play with some of the settings; it's pretty self-explanatory, but it takes a little fooling to make it work as you want.

Items in the database file follow the "Style" conventions from fvwm and AfterStep. So, each item is listed this way:

Style   "WM_CLASS"      {comma-separated list of options}

You can learn the value of "WM_CLASS" by using the Ident module included with AfterStep. Ethan Fischer ( offers the following account of what the various options do:

In general, these options have both an "on" and an "off" keyword (like 
"Title" and "NoTitle", for instance).  This allows a general style (like 
the "*" style), to be overridden by a later style.  For example:

        Style "*" NoButton 1, BorderWidth 2
        Style "xterm" Button 1, NoHandles

will hide the leftmost button on the titlebar for any window except xterm
windows.  It will turn off resize handles for xterm windows.  It will also
give a 2-pixel border to xterm windows - note that BorderWidth only affects
windows with NoHandles (this is in the manpage), so all other windows will
receive the normal 1-pixel border.

Here's a list of options, along with what they do.  For each group, the 
default is listed first.

Icon {icon.xpm}
  Specifies the icon pixmap, if the app doesn't supply its own.  NoIcon 
  turns this off.

  Give the window a titlebar.  NoTitle removes the window titlebar.

  Display the icon name along with the icon.  NoIconTitle turns this off.

  Give the window resize handles, also called the "lowbar".  NoHandles 
  turns this off.

Button {button}
  Allow a titlebar button to be shown.  It will still not be shown if it 
  is disallowed by Motif WM hints, or there is no pixmap specified for it
  in the look file.  NoButton disallows a button.

  List the window in the window list.  WindowListSkip removes the window
  from the window list.

  Circulating (also called warping or alt-tabbing) will stop at this    
  window.  CirculateSkip prevents circulating to this window.

  Start as a normal window.  StartIconic starts the window as an icon.

  Don't put a window anywhere special in the stacking order.  StaysOnTop
  windows are placed above all other windows except menus.  StaysOnBack 
  windows are placed behind all other windows.

StartsOnDesk {desk}
  Start the window on the current desk.  StartsOnDesk will force the
  window to start on a specific desk.

Color {forecolor} {backcolor}
ForeColor {color}
BackColor {color}
  Change both the foreground (text) color, and the background color for
  this window.  ForeColor changes only the foreground color.  BackColor
  changes only the background color.

  This window will refuse to take the input focus.

Slippery, Sticky
  This window will remain on whatever desk it started on, unless the user
  moves it.  Sticky will cause the window to move to whatever desk is
  currently shown.

BorderWidth {width}
  If NoHandles was also specified, set the border width of this window.
  Note that the border is an X border and not special to AS (unlike the
  titlebar or lowbar).

HandleWidth {width}
  Set the width of the resize handles on the lowbar.

4.14 What is the base.{yourbpp}bpp file?

The "base" files define the path to pixmaps and the like for each bits-per-pixel X ColorDepth setting. The number of colors your X session can use at any one time is limited by the number of bits per pixel that are allowed by your video hardware, and by your X configuration. The file, base.{yourbpp}.bpp, is automatically selected by AfterStep upon startup, according to what your X configuration allows. For more information about ColorDepth, read your X documentation, as well as the section on colormap issues, below.

The base files also define the size and scale of your desktop(s).

4.15 How do I get apps to minimize to a different place?

When an application minimizes, the icon shows up in a predictable place on the desktop. This is the icon box. In versions that use a .steprc, this is defined in the .steprc. In later versions, the icon box is found in the look file. (Naturally, this means that if you change looks, the icon box may move!) You can specify any location you like for the icon box, using standard X geometry.

4.16 I keep losing my icons, or I can't stand having them follow me.

Even though these are opposites, they amount to the same question. Icon behaviour in this case is controlled in the feel. StickyIcons ensures that the icon will follow you from one desktop to another. StubbornIcons iconifies an application to its original place. You can back up your feel, and play with it to see what you can do.

4.17 Suddenly, some windows stay always on top. Why?

With the default, double-clicking (latest versions) or triple-clicking (earlier versions) on a window titlebar toggles a window's always-on-top state. Double/Triple-click again to remove it. If you want to remove this feature, locate the lines in your feel file that look like this (there are several of them):

PutOnTop        "TripleClick"

and comment them out.

It is also possible that you have inadvertently changed your feel. Predictably enough, different feel files define functions differently. So, for instance, one of them may automatically move a window to the top as soon as your pointer is atop that window, while another may require that you click on the titlebar in order to bring a window to the top. You might like to read through the various feel files on your system, in order to get an idea of how they can be customized.

4.18 Can I make or install a "theme" for AfterStep?

There is a new set of scripts available to work through themes. It is still in the early stages of development, but several people have already reported success. The scripts come from Doug Alcorn (, and are available from his page, as well as from the AfterStep FTP site, under /themes.

4.19 I want to do xyz with {some application under X}. How do I do it?

Yes, this is a generic question, because the generic answer is always the same: please read the relevant man pages and README files. That said, there are several applications which are included with AfterStep. Some (not all!) of these are discussed in another section (below, after the Modules section). If you're really perplexed, and you're having a problem peculiar to AfterStep, and you have read every relevant thing (that really means everything!), a question to the regular list would not be out of place.

Next Previous Contents