If you want the filer to manage your desktop background then you use the --pinboard option and supply a name for the pinboard, eg:

$ rox --pinboard=MyPinboard

$ rox --pinboard=MyOtherPinboard

$ rox --pinboard=

Panels work just like the pinboard. You can create a panel on any side of the screen by using the options --left, --right, --top and --bottom, depending on which side of the screen the panel should appear on. On some systems, the short (one letter) form of the options must be used. For example, to create a panel along the bottom edge of the screen:

$ rox -b=MyPanel

$ rox --bottom=MyOtherPanel
     $ rox --bottom=

You may have to play around with your window manager a bit to get the pinboard icons and panels to display correctly (eg, without borders and underneath all other windows). In particular, try setting the stacking level / depth to low (or a negative value). Make sure any 'Keep transients above other windows' type options are turned off! In order for the filer to receive mouse clicks on the background (used for the pinboard support) you need a GNOME-compliant window manager. To see if your window manager supports this, try clicking the right mouse button on an unused area of the background. If you get the pinboard menu, all is well.

(require 'gnome)

      # Manage root window (EXPERIMENTAL - normally enabled!)
      GrabRootWindow=1 # 0/1
      # Bitmask of root window button click to use in window manager
      UseRootButtons=3 # [0-255]
      # Desktop mouse-button click to show the menu
      DesktopWinMenuButton=1 # [0-20]
      # Desktop mouse-button click to show the window list
      DesktopWinListButton=2 # [0-5]
      # Desktop mouse-button click to show the window list menu
      DesktopMenuButton=0 # [0-20]

      # ROX-Filer pinboard and panel
      ROX-Filer.icon: folder
      ROX-Panel.layer: Dock
      ROX-Panel.doNotCover: 1
      ROX-Panel.ignoreWinList: 1
      ROX-Panel.ignoreTaskBar: 1
      ROX-Panel.ignoreQuickSwitch: 1
      ROX-Pinboard.layer: Below
      ROX-Pinboard.ignoreWinList: 1
      ROX-Pinboard.ignoreTaskBar: 1
      ROX-Pinboard.ignoreQuickSwitch: 1
      ROX-Filer.layer: Normal

If you run the filer as the `root' user then the filer will display a message at the top of each window to remind you. The root user has permission to access or change any file in the system, so be very careful when using the filer like this. Normally, you should log in as an ordinary user and only change to root when you need to. You can create a simple script which runs the filer as root — something like this:

     #!/bin/sh

     su -m -c "rox $*"

It is sometimes useful to save the current selection for later. You can save the current selection to one of ten numbered groups by pressing Control+<number>. You can restore a saved group by pressing the group number on its own. You can do this from a different directory, or even a different filer window.

Saving is also useful even if there is no selection, since it still saves the current directory.

The groups are saved automatically for next time the filer is loaded.

All of these work in the same way — if you open the menu with some items selected then the operation applies to those items. If you open then menu over an item while there is no selection then that item is temporarily selected.

If you choose one of these while there is no selection at all then the window goes into `target mode'; the operation happens to the next item you click on. Click on the window background, press Escape, or click with the right mouse button to cancel target mode. Target mode is mainly useful with the `Single-click navigation in filer windows' option and keys bound to the various menu entries.

Note that individual applications may add extra menu items to the top of this submenu when you click over them — see Application directories for details.

Note about symlinks: A symbolic link stores the location of another file. Deleting the symlink doesn't affect the other file. Deleting the other file means that the symlink won't work. There are two types of symbolic link — Relative and Absolute. An absolute link stores the path from the root directory to the target file (eg `/home/fred/MyFile' ). A relative path stores the path from the symlink to the target (eg `../fred/MyFile' ). If the target file is never going to move then you want an absolute link, but if the target may move (and the symlink will be moved with it) then you want a relative link.

This menu allows you to select and unselect files in various ways. See the mouse and key bindings section for other ways to select files.

Each entry in this submenu opens a savebox for creating a new file or directory. There are two standard entries; the others are the contents of your `<Choices>/Templates' directory, if it exists.

<html>
 <head>
  <title>My Page</title>
 </head>
 <body>
  The contents.
 </body>
</html>

Note that you cannot set keyboard shortcuts for these user-defined entries at present.

The `Send To' menu provides a quick way to send some files to an application. The filer scans all the `SendTo' directories in your CHOICESPATH and lists the contents on this menu.

To change which applications appear here you should choose the Customise item from the bottom of the menu to create and open your own SendTo directory. Applications can be symlinked into this directory by dragging them in with Control and Shift held down.

Opening the Send To menu via the main menu is rather slow, so it is normally opened by clicking the Menu mouse button over a file while holding the Shift key down.

These menus are both the same, and very simple:

Note that individual applications may add extra menu items to the top of this menu when you click over them — see Application directories for details.

ROX-Filer allows you to run small programs inside the panel — such programs are called applets. To run an applet, drag it onto the panel from a filer window and instead of the applet's icon being shown, the applet will run.

This allows you to type in a path directly. As you type the display is updated to show the item entered visually. The main use is to find a file in a large directory quickly, but you can also use it for navigating between directories, or for selecting a full pathname from somewhere else and pasting it directly into the path-entry box.

If you start entering a name beginning with a `.' then the `Show Hidden' feature is temporarily turned on so that the file can be shown.

Tab completion tries to fill in as many characters for you as it can. For example, if there are two files in a directory called `save-mail-nov-1999' and `save-mail-dec-1999' then typing 'save' and pressing Tab will expand `save' to `save-mail-' and beep to indicate that the match is not complete. If you use tab completion on a directory and it is unique then the filer will automatically change into the directory. This behavior should be familiar to shell users.

This provides a quick way of entering shell commands if you don't want to open an xterm. If you don't know what shell commands are, skip this section!

Just type in the command and press Return to execute it. Up and Down arrows move through previously entered commands. Tab does shell-style completion. Clicking on an item inserts its name into the minibuffer. If some items are selected then they are assigned to the positional parameters $1, $2, etc.

Opening the minibuffer with a selection adds $@ to the end of the command — this expands to all the selected files.

Use this if you want to automatically select all files in the directory which match a condition.

Some actions have options, which appear as option boxes at the bottom of the window. They are:

You can also put shell-style wildcard characters inside the quotes, for example:

'*.html'

'Report.*'

'Draft[1-5]'

'main.[ch]'

Look at the glob(7) manpage if you want to know more about shell wildcards.

If the pattern you enter contains a slash (`/') character then the pattern is matched against the file's full path, otherwise only the leafname is used. That is, '*tmp*' will find `tmp' and `tmpfile' but not `/tmp/file' — '/*tmp*' will find all three.

As well as finding files by their names you can also find them by various other attributes. Note that file is used here to mean anything that can appear in the filesystem — including directories, devices and so on.

You can also use a short form for each test; these are shown in brackets. You can combine multiple tests — `-rw' is the same as `IsReadable and IsWriteable'.

You can combine the above tests in various ways to perform more advanced searches. An expression is actually made up of a list of cases, separated by commas. The filer will try to match each case in turn until one matches or there are no more cases left. For example, to search for files with several possible endings:

'*.gif', '*.htm', '*.html'

IsDir 'lib', IsReg '*.so'

     !(IsDir, IsReg)

     !IsDir !IsReg

     Not isdir and not isreg

     !-d !-f

You can also compare various values using the operators <, <=, =, !=, >, and >= (for less-than, less-than-or-equal-to, equal-to, not-equal-to, greater-than and greater-than-or-equal-to). When comparing times, you may find it helpful to use after and before instead of > and < to make things clearer.

Times are measured as seconds since the Unix Epoch (00:00:00 UTC, January 1, 1970). Sizes are in bytes. When specifying constants to compare these values with you may use various keywords to scale the value:

     mtime after 1 day ago

     size > 10 Mb

     IsReg and nlinks > 1

The second finds files larger than 10 Mb. The last finds regular files with more than one directory entry.

Be careful though — the filer doesn't check the context of the modifiers, so size > 1 day ago is allowed, although it doesn't make much sense! Also, forgetting to use ago or hence will cause odd effects (the time will be measured relative to the Epoch rather than the current time). Finally, don't use = with times — atime = 1 day ago looks for a file accessed exactly 86400 seconds ago...

     '*.old' system(rm '%')

     'src' prune, '*.c'

If file is named `src' then `Prune'. Either way, check if it ends in `.c' and include it in the results if so.

You can choose which language the filer will display messages in from here, or get it to read the LANG environment variable to get the desired language.

If you are using the pinboard features (see the Pinboard support section) then you can choose how the text under each icon is displayed. If you have a fairly uniform background then you may like to choose `No background' , which simply draws the text directly over the desktop background. However, users with more `noisy' backdrops may find such text hard to read; selecting `Rectangular background slab' will draw a solid rectangle behind the text to make it easier to read. When using Gtk+-2.0, this option has no effect.

You may also change the foreground and background colours used for the text by clicking on the colour slabs in the Options window.

If you are using panels (see the Panel support section) then this section lets you choose which icons will have textual labels underneath them. You can have labels on all icons, on no icons, or on all icons except applications.

You can choose to start some operations automatically, without waiting for you to click on Quiet. Select each operation that you want to auto-start here. You can also set the default state for each of the options that appear inside action windows.

The toolbar is described in the Toolbar section.

This box appears when you choose Set Run Action... from the File menu, and is used to set which application is loaded when you click on a file.

For example, let's say you want to set things up so that opening a `.gif' file loads it into the Gimp. First, right-click over a gif image to open the menu and choose Set Run Action... from the File submenu. Then, you have a choice of two methods to set the run action:

This box appears when you choose Set Icon... from the File menu, and is used to set which image to use to represent the file.

It works much like the Set Run Action box described above, except that you may specifiy an icon for one file individually (by name) as well as for all files of a particular type.

The directory icon inside the `Drop an icon here' area allows you to quickly get to a directory from which you are already using one or more icons.

ROX-Filer uses three sub-directories in your Choices directory for filetypes:

`AppInfo.xml' is an XML file with the following structure (any elements may be omitted, and the file itself is optional):

<?xml version="1.0"?>
<AppInfo>
  <Summary>A graphical file manager</Summary>
  <About>
    <Purpose>File manager</Purpose>
    <Version>1.1.3 (07-May-2001)</Version>
    <Authors>Thomas Leonard and others</Authors>
    <License>GNU General Public License</License>
    <Homepage>http://rox.sourceforge.net</Homepage>
  </About>
  <AppMenu>
   <Item label="Enable pinboard" option="-p=Default"/>
   <Item label="Disable pinboard" option="-p="/>
  </AppMenu>
</AppInfo>

ROX-Filer is able to translate many of its messages, provided suitable translation files are provided:

The first time you compile the program you need to do AppRun --compile, but in future you only need to run make in the `src' directory when you change the `.c' and `.h' files. You might want to run make depend too.

When people make small modifications to the sources they will often distribute them as patch files — usually on the mailing list. To apply a patch, go into the `src' directory and run patch with the patch file. Then recompile, like this:

     $ cd ROX-Filer/src
     $ patch < patchfile
     $ ../AppRun --compile

To create a patch you should first get the latest version of the filer from CVS (instructions on using CVS can be found on the web-site). Modify the program as you please. Create the patch using cvs diff from the appropriate directory:

$ cvs diff -u > my_patch

Here's a quick explanation of the autoconf system in case you haven't used it before. See info autoconf for full details.

There's a file called `configure.in' which contains various tests (info autoconf). You run autoconf and it reads through the file and generates a shell script to perform the tests, saving it as `configure' . `configure' is normally distributed with the program because not everyone has autoconf.

You then run `configure' (in fact, let the `AppRun' script do it because it passes it some arguments), which performs all the tests. It reads in `Makefile.in' and `config.h.in' and fills in the missing values with the test results to produce `Makefile' and `config.h' .

You run make, which creates `.o' files from the `.c' files and links to produce `ROX-Filer' .

The `global.h' file lists each major data-structure used in the filer and explains its purpose. This is a good place to start reading if you want to know how the filer works.

In summary, each window has its own FilerWindow structure. This structure has pointers to a Collection (which is the widget which actually displays the files) and to a Directory, which is used to cache the directory contents.

Both Collection and Directory have pointers to (the same) DirItems, each of which corresponds to one filesystem object.

Several FilerWindows may share the same Directory.

While scanning is in progress the Directory keeps a list of the new items it has found (new_items) and the items which have changed in some way (up_items). It periodically notifies the filer window of the changes-so-far by calling all the functions in the users list (use attach() and detach() to add and remove functions to or from the list).