ROX-Filer User Manual http://rox.sourceforge.net

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

The pinboard configuration is saved in `~/.config/rox.sourceforge.net/ROX-Filer/pb_MyPinboard' as soon as you change it in some way (for example, by dropping a file onto the background). You can have as many pinboards as you like and switch between them by running rox again, eg:

$ rox --pinboard=MyOtherPinboard

To turn off the pinboard again, set the name to an empty string:

$ rox --pinboard=

See the window manager notes if you have trouble getting the icons to display correctly. The pinboard may also be turned on and off by locating `ROX-Filer' in a filer window and choosing Enable pinboard or Disable pinboard from the menu.

Panels work just like the pinboard, except that they run along the edge of the screen. To create a panel:

$ rox -b=MyPanel

The panel should be displayed in a window without a title bar. If this does not work then see the window manager notes for some ideas. You can drag files onto either side of the panel to add them. Panel icons can be repositioned by dragging them with the middle mouse button. Changes to the panel are automatically saved to `~/.config/rox.sourceforge.net/ROX-Filer/pan_MyPanel'. As with the pinboard, you can switch between panel configurations simply by running rox again with a different panel name.

$ rox -b=MyOtherPanel

You can set which edge of the screen the panel appears on using the popup menu. You can also set the edge when enabling the panel by using the side instead of -b. Specify a blank name to remove the panel:

$ 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!

(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. If you have sudo installed and set up then you can run the filer like this:

$ sudo rox

Remember, any file operations you perform and any programs you run from these windows will run as root too! Be careful!

You may find that the X server won't allow root (or other users) to connect. Reading the manual pages for xauth and xhost may give you some hints, but it varies between systems (which is why this isn't built in to the filer!).

Note: gnomesu can also be used to run the filer as root, but you'll need to use setsid to run it in a new session group, otherwise gnomesu kills it before it has a chance to open a window. For example:

gnomesu -c 'setsid /usr/local/bin/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 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. There may also be any number of user-defined actions at the top, which depend on the type of file clicked on. You can add programs here by choosing the Customise Menu item. For example, you could make The Gimp appear on the menu for images, and FreeFS appear for mount points.

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 three standard entries; the others are the contents of your `~/.config/rox.sourceforge.net/Templates' directory, if it exists.

To add your own entries, choose Customise Menu and put any files you want in there. Each file in the directory will appear on the menu and the box that appears will copy it. For example, you could create a blank HTML file:

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

Save this as `index.html' inside the `Templates' directory and you can easily create new HTML files. You can also save blank documents from various applications into here (eg, a blank spreadsheet, a blank letter, etc).

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 `$XDG_CONFIG_DIRS/rox.sourceforge.net/SendTo' directories (see [BaseDir]) 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 and choosing Link from the menu.

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.

The bookmarks menu can be used to store a list of frequently used directories. You can also open the menu from the main popup menu (in the Window submenu) and you can use this to bind a shortcut key to it. From the bookmarks menu you can add the currently shown directory to the list, jump to one of the stored directories, or open a dialog letting you edit the list. In the dialog box, you can remove entries, rearrange them (using the arrows or by dragging) and edit the pathnames directly, if required.

The Recently Visited submenu shows the last few directories viewed. Choosing one will switch to that directory. The current directory is shown shaded, since you are already there.

If you are setting up the defaults for multiple users and you wish to create a `Home' icon that leads to each user's home directory then you should first create a new icon and then use Edit Icon to change the location to `~' and the name to `Home'.

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.

When the pinboard is in use, ROX-Filer can be used to display an icon for each iconified (or 'minimised') window. You can turn this on or off from the Options box. Iconified window icons have a semi-transparent background slab effect, and can be dragged around. Clicking on one will expand it back into the window it represents. Some older window managers do not support this, and no icons will be shown.

You can set any image for the backdrop by choosing Backdrop... from the pinboard menu (right-click over the desktop background when the pinboard is turned on).

To set an image, select Centre, Scale, Stretch or Tile to set the style, and then drag an image onto the marked area. To return to a solid colour backdrop (as set in the Options box), click on Clear.

The Wallpaper[Wallpaper] application can be used for more complicated effects, such as choosing a new random image each hour, or rendering an image of the Earth as it is currently lit by the sun.

For programmers...  If you want to create an application to set the backdrop (eg, to choose a random image, or a slideshow) you need to first create an application directory (see Application directories).

When run without arguments, the application should invoke the SetBackdropApp SOAP method (see Appendix C, SOAP RPC). The filer will immediately run the application again, this time with the --backdrop option.

When run with --backdrop, the program should write the style and name of the image file to display to its standard output stream, eg:

tile /tmp/image.png

centre and scale are the other possible styles. The filer will then load this image and display it. The application does not set the backdrop itself, it only tells the filer what to display.

In the case of a random backdrop chooser, the program may then quit immediately. If the application created a temporary image then it should read the line "ok\n" from its standard input before deleting the image.

If the application wishes to show a sequence of images it should still read "ok\n", then wait until it's time to display the next image and then write that filename, and so on.

The filer will indicate that the program should stop running by closing the two streams. The program should clean up and exit at this point. Be sure to catch SIGPIPE when writing to standard output if you need to delete any temporary files.

See the Wallpaper[Wallpaper] application for a complete example application (written in python).

When in thumbnail mode ROX-Filer checks the thumbnail directory (`~/.thumbs/normal') for a thumbnail for each file it scans. If a thumbnail exists it loads it and continues on to the next file.

To generate a thumbnail for a given file of type media/subtype the filer looks for a program `~/.config/rox.sourceforge.net/MIME-thumb/media_subtype', falling back to `~/.config/rox.sourceforge.net/MIME-thumb/media' if one cannot be found (this duplicates how run actions for files are looked up). If neither file can be found and the file is of type image/* then the internal routines are used. If the file is not of type image/* then no thumbnail is generated.

If the generator program is found, is executed with the parameters

thumbnailer /path/to/source/file /path/to/thumbnail pixel_size

Once the child program exits, it attempts to load `/path/to/thumbnail'. If that fails no thumbnail is displayed.

Note that because of the order it does things ROX-Filer will happily use any pre-existing thumbnail even if it has no idea how it was generated.

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.

Just those files over 5 Mb in size will be selected. The expressions you can enter are in the same form as described in the Searching section, except that prune has no effect since the contents of directories are never checked anyway. You can press Tab to jump to each selected file in turn.

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

You can set the defaults for these options from the Options box.

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

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'

Further, each of the cases is actually a list of conditions. The case only matches if all of its conditions are met. So, to find a directory called `lib' or a regular file ending in `.so':

IsDir 'lib', IsReg '*.so'

You can negate a condition by putting a ! in front of it and you can use a sub-expression as a condition by bracketing it, like this:

     !(IsDir, IsReg)

     !IsDir !IsReg

     Not isdir and not isreg

     !-d !-f

All four do the same thing.

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:

Some examples should make this all a bit clearer!

     mtime after 1 day ago

     size > 10 Mb

     IsReg and nlinks > 1

The first finds files modified within the last 24 hours. You could use > instead of after, but it's not so clear what is meant.

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...

Examples:

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

     'src' prune, '*.c'

The first deletes each file ending in `.old'. The second looks for `.c' files, but does not bother checking inside directories called `src'. The expression is evaluated like this:

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

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. When setting the icon for a single file, the filer stores the name of the file and the name of the icon inside your `~/.config/rox.sourceforge.net/MIME-icons' directory. If either moves, the icon won't be displayed.

When setting the icon for a directory, you have the additional option of storing the image inside the directory itself as a hidden file. This means that other users will see the icon too, and you can safely delete the original image after the copy (note that the image is scaled down if needed, and converted to PNG format).

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 two sub-directories in your `~/.config/rox.sourceforge.net' directory for filetypes:

In `MIME-types' you can also provide default actions for each media type. For example, if `text_html' isn't found then the filer will try simply using `text'.

The filer usually works out the type for a file from its name. If this fails, it tries to guess from the file's contents. It is possible to override this guessing by setting an extended attribute on the file with the correct type, using the Set Type... menu item.

To edit the rules used to guess types, open the options box and go to the Types section. There is a button there that will launch the MIME-Editor application. You can also edit the rules manually — see [SharedMIME] for details.

`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 xml:lang="en">A graphical file manager</Summary>
  <Summary xml:lang="de">Ein grafische Datei-Manager</Summary>
  <Summary xml:lang="nl">Een grafisch bestandsbeheerprogramma</Summary>
  <Summary xml:lang="es">Un manejador de archivos gráafico</Summary>
  <About xml:lang="en">
    <Purpose>File manager</Purpose>
    <Version>1.3.5 PREVIEW</Version>
    <Authors>Thomas Leonard and others</Authors>
    <License>GNU General Public License</License>
    <Homepage>http://rox.sourceforge.net</Homepage>
  </About>
  <About xml:lang="es">
    <Purpose>Manejador de Archivos</Purpose>
    <Authors>Thomas Leonard y otros</Authors>
  </About>
  <AppMenu>
    <Item option="-p=Default">
      <Label>Enable pinboard</Label>
      <Label xml:lang="es">Habilitar el pinboard</Label>
    </Item>
    <Item option="-p=">
      <Label>Disable pinboard</Label>
      <Label xml:lang="es">Deshabilitar el pinboard</Label>
    </Item>
  </AppMenu>
</AppInfo>

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

See the gettext info page for more instructions on creating a translation.

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

You can remove the patch by simply repeating the above sequence — patch will detect that the patch is already applied and offer to remove it.

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

This creates a human– and machine-readable patch file. Submit this to the mailing list. The are many reasons for posting patches rather that the modified files:

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.