Useful Things You Can Do with FVWM

FVWM is a window manager used with the
X Window System, which is the standard GUI for UNIX. This article explains a few
useful things you can do with FVWM, including how to take screenshots
conveniently, how to easily change a window's title and how to
reconfigure easily a running FVWM instance.

This article is aimed at fairly knowledgeable UNIX users. A little
programming experience would be helpful, but you probably can manage
without it. No knowledge of X or FVWM is assumed.

The ideas presented in this document were tested with FVWM 2.4.16. They
should work with any FVWM 2 version, however. Scripts presented in this
document are written in Bash; I used the 2.05a.0(1)-release, but they
should work in any version. Finally, I run Debian Linux 3.0. This means
the utilities invoked from the shell scripts are assumed to be the
standard Linux ones or to behave like them.
Taking Screenshots Conveniently
The method I present here allows you to save a screenshot of the
current window by selecting an option from one of FVWM's window menus.
If you use FVWM, it's almost certainly configured to put one or more
buttons on the titlebar of each window. When clicked, one of these buttons--probably
the one in the top left corner--brings up a menu that lists window operations
such as move, resize and so on. We're going to modify this menu to have
two new options, Take screenshot and Take named screenshot. Selecting the former
will cause a screenshot with a unique name to be put in a standard directory.
Selecting the latter will do the same thing, except it will prompt you for a
name for the new image.

You may ask, why is this useful? You may go on to ask, can I not simply
use a standard window-dumping utility, such as xwd, to take my screenshot?
These are good questions, but the method I'm outlining offers several advantages.
First, my method is more convenient than switching to another window and giving a
command to take a screenshot. Second, my method chooses a filename for you,
relieving you of the burden. The filename chosen is unique, ensuring that
screenshots can be ordered according to the time at which they were taken.

The savings in time and trouble may seem minor, but when you need to
take a series of screenshots from a particular window, they add up.
Imagine that you want to explain to a client how to perform a particular
operation. A good way of doing so is to send him a series of screenshots
showing him every step in the sequence. Saving such a series is much
less trouble with the method I'm about to outline.
FVWM Menu Definitions
As mentioned above, we're going to add two new options to an FVWM menu. To
begin, let's look at how FVWM menus are defined. The following code, taken
from a sample configuration file shipped with FVWM 2.4.16, defines an FVWM
menu called Window-Ops2. More precisely, it adds elements to the end of the menu.

  AddToMenu Window-Ops2   "&Move"          Move
  +                       "&Resize"        Resize
  +                       "&Raise"         Raise
  +                       "&Lower"         Lower
  +                       "(De)&Iconify"   Iconify
  +                       "(Un)&Stick"     Stick
  +                       "(Un)&Maximize"  Maximize
  +                       ""               Nop
  +                       "&Delete"        Delete
  +                       "&Close"         Close
  +                       "&Destroy"       Destroy
  +                       "&ScrollBar"     Module FvwmScroll 2 2
  +                       "&Print"         PrintFunction
  +                       "&Print Reverse" PrintReverseFunction

A full description of how to define menus in FVWM is unnecessary for our
purposes, so I'm not going to give one. An outline is necessary,
however. I begin by recapitulating the above command in the following
table, labeling each component:
Command for Adding to Menu DefinitionName of MenuMenu LabelFVWM Code for Menu Action AddToMenu Window-Ops2&MoveMovePlus Sign Menu LabelFVWM Code for Menu Action+ &ResizeResize+ &RaiseRaise+ &LowerLower+ (De)&IconifyIconify+ (Un)&StickStick+ (Un)&MaximizeMaximize+  Nop+ &DeleteDelete+ &CloseClose+ &DestroyDestroy+ &ScrollBarModule+ &PrintPrint Function+ &PrintReverseReverse Print Function
This table shows the structure of the command. The first element is
AddToMenu, an FVWM command. Next comes Window-Ops2, the name of the
menu. After that comes &Move, which defines a menu label; I explain the
function of the ampersand in a minute. Then comes Move, which is an
FVWM command that is executed if the user chooses Move from the menu.
Following this are a number of lines. Each line begins with a plus
sign, which is followed by a label and then an FVWM command, possibly
with arguments. In summary, the essence of the AddToMenu command is to
bind menu labels to actions.

Now, about those ampersands: they're used in labels to define hotkeys.
FVWM looks at the character after the ampersand to find out what the
hotkey is. For example, a label of &Move defines M as a hotkey. If
the user presses the M key after bringing up the menu, this is
equivalent to clicking on the Move option.
Adding Our Own Action to the Menu
Suppose we want a simple way of saving a screenshot of the current window, so that
when we select the correct option from a menu, a screenshot is saved to
the file /tmp/screenshot. We can achieve this by adding the following line
to the end of the AddToMenu command listed above:

  + "Take screenshot" Exec xwd -id $w -out /tmp/screenshot

Let's examine how this works. As already explained, the first two elements
of the line are a plus sign and a label. Then comes the FVWM command,
which in this case is:

  Exec xwd -id $w -out /tmp/screenshot

The command name is Exec, which allows one to execute an external
command. Its arguments are the external command, followed by the
external command's arguments. In this case, the external command is
xwd,
and the arguments passed to it by FVWM are -id $w -out
/tmp/screenshot.

The notation $w in these arguments needs some explanation. It's a
special FVWM variable that stands for the window ID of the current
window. When FVWM runs the above xwd command, it replaces the argument
$w with the relevant window ID.

What is a window ID? The X Window System needs a way of identifying
and referring to windows. It does so by assigning each window a unique
number, known as the window ID.

For our purposes, you don't need to understand xwd's other arguments
just yet. For now, all you need to know is that the command given above
causes xwd to put a screenshot of the current window in the file
/tmp/screenshot.

At this point, you may be asking, FVWM has many menus; how do I
identify the one I need to modify? The answer is the correct one
probably is the one called Window-Ops2, but it all depends on whoever
packaged and configured FVWM for you. The best way to find the correct
menu is to search your FVWM config file for a menu that uses all or
most of the following functions: Move, Resize, Raise, Lower, Iconify, Close.
If you find such a menu, it's almost certainly the right one.
Running Our Window-Dumping Program
We've completed the preliminaries and now are ready to start looking
at the promised solution. It involves a program I call savescreenshot.
To have FVWM run it to take a screenshot, we add the following line to
the appropriate AddToMenu command:

  + "Take screens&hot" Exec savescreenshot $w
  + "Take &named screenshot" Exec savescreenshot -n $w

You need to make sure savescreenshot can be found by searching
the PATH that was defined when FVWM was invoked. If it can't, you can
use an absolute pathname for savescreenshot. Also, notice that the
above labels make H and N into hotkeys.
xwd, xwud and Conversion Programs
To actually take the screenshot, savescreenshot relies on xwd. Although
several screenshot utilities exist, I chose xwd because it comes packaged
with X. xwd's basic usage is as follows:

xwd [-id window_ID] [-out output_file]

where window_ID and output_file should be replaced by the actual names of the window ID and output
file, respectively.

The -out option, as the summary above suggests, directs xwd's output to
the specified output file; if you don't supply it, xwd writes to its
standard output. The -id option tells xwd to use the window with the
specified window ID. If you don't supply it, xwd changes the mouse
pointer's shape to indicate that it wants you to click in a window to
select it. When you've done so, it takes a screenshot of that window.

xwd uses its own special image format. This format doesn't use
compression, so output files often are quite large. You usually
want to convert the output file to a format such as PNG; I'll cover this
in a minute.

To view xwd's output files, you can use xwud, which also comes packaged
with X. You can specify an input file with the -in option. The
command xwud -in browser-window would display
the screenshot stored in the file browser-window.

To convert files in xwd format, you can use convert from the
ImageMagick suite.
The following commands convert an image to various common formats and
should be self-explanatory:

  convert browser-window browser-window.png
  convert browser-window browser-window.jpg

If you want to use the
netpbm tools,
the following two commands correspond to the two commands above:

  xwdtopnm < browser-window | pnmtopng > browser-window.png
  xwdtopnm < browser-window | pnmtojpeg > browser-window.jpg

Converting Made Easy
I have a script called convert-xwd that makes the process of converting a slew of
XWD files much easier. If you supply arguments, it assumes they're
the names of XWD files and converts them to PNG format. If you
supply no arguments, it finds all of the XWD files in the current
directory and converts them. After successfully converting an XWD file
to PNG, it deletes the XWD file. Here's the script:

  #!/bin/bash

  main() {
    if [ $# = 0 ]
    then
      do_files *
    else
      do_files "$@"
    fi
  }

  do_files() {
    local file

    for file in "$@"
    do
      if file "$file" | fgrep -q ": XWD X-Windows Dump image data,"
      then
	echo "Doing $file"
	convert "$file" "$file.png" && rm "$file"
      fi
    done
  }

  main "$@"

I've given two sample invocations of savescreenshot. Now it's time
to explain what they do. As the accompanying labels suggest,
when run with no arguments, savescreenshot simply saves a screenshot,
and when passed the -n option, it saves and names a screenshot.

savescreenshot uses two directories, $HOME/.screenshots/t and
$HOME/.screenshots/n. If they don't exist, it creates them. In the first
directory, savescreenshot saves a screenshot whose name has the form of
NNN-HHMM.SS. NNN is a three-digit number representing the number of the
day in the year, HH is a two-digit number representing the hour, MM is a
two-digit number for the minute and SS is a two-digit number for the second.

The second directory, $HOME/.screenshots/n, is left untouched unless the -n option was given.
If it was, savescreenshot pops up a window to ask the user what name the
screenshot should have. After the user has answered, savescreenshot
creates a symbolic link, using the name entered in the popup window, in
$HOME/.screenshots/n pointing to the screenshot in $HOME/.screenshots/t.

The user needs to know when the screenshot has been taken so that he
can continue interacting with the window he's dumped. xwd beeps
when it's finished, but in case you have the bell disabled, as I do,
savescreenshot also makes the screen flash red when xwd has completed.

Here's the savescreenshot program. I don't believe it needs much
comment. One thing to note, however, is it handles prompting the
user for a name by invoking itself again with a private option.

Another interesting feature is the savescreenshot program attempts
to delay the screenshot a little if it believes the window may be
slow to update. This can happen with windows whose contents are
fetched over a network. Examples of applications that create such
windows are remote administration programs such as VNC and rdesktop.

  #!/bin/bash

  main() {
    dir=~/.screenshots
    timedir=$dir/t
    namedir=$dir/n

    test -e "$timedir" || mkdir -p "$timedir"
    test -e "$namedir" || mkdir -p "$namedir"

    menu_linger_time=.1

    # we wait this amount of time to allow for the menu obscuring the
    # window to disappear.

    prompt_for_name=false

    timestamp=`date +%j-%H%M.%S`

    case "$1" in
      -n)
	prompt_for_name=true
	shift
      ;;
      -p)
	timestamp=$2
	read -p "Please supply name for screenshot: " name
	ln -s "../t/$timestamp" "$namedir/$name" 
	exit
    esac

    window_id=$1

    sleep $menu_linger_time

    sleep `get_delay_for_update $window_id`

    xwd -id "$window_id" -out "$timedir/$timestamp"

    xrefresh -solid red
    # this is to inform the user that xwd has finished.

    sleep .5
    xrefresh -solid red

    # just in case the user blinked and missed the first flash.

    if $prompt_for_name
    then
      title="Please supply name..."
      x rxvt -T "$title" -n "$title" -e "$0" -p "$timestamp"
    fi
  }

  # this function estimates how long it will take the application to repaint
  # the part of the window uncovered when the FVWM menu obscuring it disappears.
  # most applications repaint almost instantaneously, but some applications which
  # need to fetch data over a network in order to repaint take a little time.
  # 
  # this method isn't failsafe, because the window's title may have been 
  # manually changed.

  get_delay_for_update() {
    local window_id=$1

    case "`window_title "$window_id"`" in
      TightVNC:\ *)
	echo 2
      ;;
      rdesktop\ *)
	echo 1
      ;;
      *)
	echo 0
    esac
  }

  window_title() {
    local window_id=$1

    xwininfo -id "$window_id" | perl -ne 'if(/"(.*)"\s*$/) { print $1; exit }'
  }

  main "$@"

Making screenshots is a good thing to know how to do, but sometimes
you want to capture continuous video.
Here's
a link to an interesting article on Newsforge that describes how
to do this task.
Changing a Window Title
Your FVWM undoubtedly is configured to put a titlebar at the top of every
window. To be entirely accurate here, I should have said nearly
every window. Some applications, such as xbiff, create
small persistent windows, and putting a titlebar on them would clutter the
screen needlessly. These titles also are used by window-listing
facilities, such as FVWM's WindowList command or its FvwmWinList module.

Below I present a program that easily changes the title on a window. It
is invoked by opening the window operations menu--the same one we
modified in the previous section--choosing the Change title option and
entering the new title when prompted, whereupon the window's title
is changed.

I often find that I have many windows open at one time. They obscure one
another, of course, so the only way to manage them and bring up the
one I want when I need it is to use some window-listing facility.

In order for me to be able to find the window I want in the list,
windows need to have informative titles. Applications don't always
choose informative titles for their windows, however. Furthermore, sometimes
the functions of windows change over time, making the initial title
inappropriate. Other times, I start several instances of one
application, and they all use the same title, making it impossible to
distinguish between them.

I've covered modifying FVWM menu definitions in an earlier section (see FVWM
Menu Definitions), so I won't go over it again. Instead, below is the
line you need to add to the relevant menu definition in order to be able
to change the title:

+   "Change &title" Exec set-new-title $w

As before, if set-new-title isn't in the PATH, you have to use an
absolute pathname.

Here's the program, called set-new-title. It relies on
xwit, which is the
utility that actually changes the title.

  #!/bin/bash

  set -u

  main() {
    window_id=$1

    title=`xwininfo -id "$window_id" | perl -ne 'print $1 if /"(.*)"\s*$/'`

    if ! tempfile=`mktemp` 
    then
      echo "Cannot create temporary file" 1>&2
      exit 1
    fi

    echo "$title" > "$tempfile"

    popup_window_title="Choose new title in editor, then save and exit..."

    rxvt -T "$popup_window_title" -n "$popup_window_title" \
      -e "${EDITOR:-vi}" "$tempfile"

    newtitle=`head -c 1000 "$tempfile"`

    xwit -id "$window_id" -name "$newtitle"
  }

  main "$@"

Reconfiguring a Running FVWM Instance
Sometimes one wants to temporarily reconfigure FVWM, perhaps to test the
effect of some configuration command. One way to do this is to modify
the config file and then restart FVWM. You probably will find, depending,
of course, on how your FVWM is configured, that if you click on the root
window, you get a menu containing the option Restart FVWM. This is a little
tedious, however. Maneuvering the mouse to the root window, clicking on it
and choosing the option to restart FVWM takes time, particularly if the
root window is completely obscured by windows. And the restart of FVWM
takes a significant fraction of a second. There's a better and faster
way--the program FvwmCommand, which comes packaged with FVWM.

FvwmCommand can perform a number of functions. We're only interested in
one function, however: sending commands to FVWM. Sending commands is a
simple task: one simply runs FvwmCommand
command_to_send. For example, the command to restart FVWM is called
Restart, so to restart FVWM, one only need give the command FvwmCommand
Restart at the shell prompt.

In order for FvwmCommand to work, it needs to talk to FVWM. It
doesn't do so directly, however; instead, it does so through an
intermediary, called FvwmCommandS. FvwmCommandS is an FVWM module, which is
a program started by FVWM that communicates with it by means of a special protocol.

The best way to get FVWM to start FvwmCommandS is to put a command to
this effect in FVWM's config file. The command to use is Module, and it
takes as its argument the name of the module to start. So in this case,
the full command is Module FvwmCommandS. Once you've put
this command into the FVWM config file and restarted FVWM, you should find that
FvwmCommand works for you.
Resources
"Basic FVWM
Configuration"

"A Toolbox for the
X User"

Ronan McGoran is a UNIX system administrator. His home page can be found
here.