ROX-Filer User Manual

ROX-Filer User Manual
http://rox.sourceforge.net
Thomas Leonard
Copyright © 2005 Thomas Leonard
Conditions
This program is free software; you can redistribute it and/or modify it under the terms of the GNU
General Public License as published by the Free Software Foundation; either version 2 of the License, or
(at your option) any later version. This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You
should have received a copy of the GNU General Public License along with this program; if not, write to
the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA, 02111-1307, USA.
Abstract
ROX-Filer is a graphical file manger for the X Window System. Its user interface is based on the RISC
OS filer and it supports similar features such as application directories and drag-and-drop loading and
saving of files. The filer can also act as a pinboard, allowing you to pin frequently used files onto the
desktop background.
Table of Contents
1. Introduction
Features
2. Invoking
Pinboard support
Panels
Window manager notes
Sawfish / sawmill
IceWM
Window Maker
Others
Running as root
3. Mouse button and key bindings

4. The selection and file groups
Saving and restoring the selection
5. The toolbar
6. The menus
The display menu
Permissions
rox.sourceforge.net/Manual/Manual/Manual.html 1/38
The file menu
The select menu
The new menu
The window menu
The help menu
The send to menu
Showing different applications for different types
The bookmarks menu
7. The pinboard and panels
The pinboard and panel menus

Panel applets
Iconified windows on the pinboard
The pinboard backdrop image
8. Removable devices
9. File thumbnails
Technical details
10. Virtual file systems

11. The mini-buffer
The path-entry box

The shell command box
The conditional selection box
12. Renaming files in bulk

13. Action windows
Action window options
14. Searching
Wildcards
Simple tests
Logic operators
Comparisons
Specials
15. Options
16. Filetypes
The Set Run Action box
Setting the run action by drag-and-drop

Setting the run action by entering a shell command
Setting the default media-type handlers
The Set Icon box

How filetypes are stored
How the filer determines a file's type
17. Application directories
The AppInfo file
18. Internationalisation
Selecting a translation
Creating a new translation
Updating an existing translation
19. Hacking
Compiling
Creating and applying patches
Autoconf
Data-structures
A. Compiling
B. Manual page
ROX - a simple graphical file manager
C. SOAP RPC
References
Chapter 1. Introduction
Table of Contents
Features
ROX-Filer is a simple and easy to use graphical file manager for X11 — the windowing system used on
Unix and Unix-like operating systems. It is also the core component of the ROX Desktop [ROX]. Many
of the filer's features were inspired by RISC OS [RISC OS]. `ROX' stands for `RISC OS–On–X'.
Features
XDND
A common drag-and-drop protocol used, for example, by the GNOME desktop[GNOME]. This
allows data to be loaded into an application by dragging it from a filer window to a program. The
full specification is given in [DND].
XDS
An extension to XDND that allows applications to save data by dragging an icon back to a filer
window. The full specification is given in [XDS].
Basedir spec
A simple, but flexible, system for managing user choices. By default, choices are saved under
`~/.config'. However, you can change this by setting the XDG_CONFIG_HOME environment variable.
See [BaseDir] for details.
Application directories
Self contained relocatable applications, where installation is as simple as copying it to where you
want it and uninstalling it is just a matter of deleting a directory. Described later in this
documentation.
Thumbnails
The filer can be made to display image files by using the image itself for the icon, instead of a
generic `this-is-an-image' icon. Very useful for organising a directory full of photos! See [Thumbs]
for details.
Shared MIME Info Database
In the past, each desktop had its own database of rules for determining the type of files. The Shared
MIME Info Database[SharedMIME] unifies these into a single system shared by all desktops.
Icon Themes
Collections of file icons, called themes, can be installed (eg, to `~/.icons'). You can switch
between themes in the Options box. Once other desktops support this fully, themes will be sharable
between desktops. See [IconTheme] for details.
DNotify support (Linux only)
If used with a recent Linux kernel (2.4.x series), the filer will notice changes to directories
automatically. On other systems, directories will update when the pointer is moved over them.
Chapter 2. Invoking
Table of Contents
Pinboard support
Panels
Sawfish / sawmill
IceWM
Window Maker
Others
Running as root
You should be able to start the filer by simply running the rox command, by typing it at a shell prompt or
otherwise. If the filer isn't installed yet, consult Appendix A, Compiling.
By default, ROX-Filer will start by displaying the current directory. You can get it to display other
directories instead by listing them after the command:
$ rox /home /usr /usr/local
You can also use it to open files, like this:
$ rox README
The filer supports various options; use -h for a list. All options have long and short forms (eg -h and --
help) — although on some systems you can only use the short versions.
Note that if the same version of the filer is already running on this machine then, by default, it will be
used to open the directories.
For a complete list of command-line options, see Appendix B, Manual page
Pinboard support
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
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!
Sawfish / sawmill
Sawfish tries to guess whether you are using GNOME at start-up and only provides support if so. You
may need to add the line
(require 'gnome)
to your `.sawfishrc' file (see the sawfish manual for more details).
IceWM
Paste these configuration settings into `~/.icewm/preferences':
# 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]
Paste these into `~/.icewm/winoptions':
# 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
Restart IceWM and the filer for the new settings to take effect.
Window Maker
1. Run the filer using rox -p=Default.
2. Press Control+Escape, or [RightButtonDown] on any window's titlebar. Choose Attributes... from

the menu.
3. The Attributes Inspector window appears. From the pulldown menu at the top, choose
Window Specification (the top item).
4. Press the Select window button. The cursor changes to a double crosshair. Select one of the ROX-
Filer pinboard icons. The radio buttons in the Window Specification frame should change their
labels to include ROX-Pinboard.ROX-Filer as the first item. Select that radio button.
5. Choose Window Attributes from the pulldown menu. In the Attributes frame, choose the features
you want the pinboard icons to have; I recommend the following:
Disable titlebar
Disable resizebar
Disable close button
Disable miniaturize button
Keep at bottom (sunken)
Omnipresent
6. Choose Advanced Options from the pulldown menu. In the Advanced frame, choose the advanced
features you wish; I recommend the following:
Do not show in the window list
Ignore 'Hide Others'
Ignore 'Save Session' (possibly)
7. When you're finished selecting window attributes, press the Save button, and then close the
Attributes Inspector window using the X button in the titlebar.
Others
If all else fails, try the Compatibility section of the Options window.
Running as root
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 /'
Chapter 3. Mouse button and key bindings

Quick start:
Click the left [1] mouse button to open files and directories.
Click the right button to get a menu. Click over a file to perform an action on that file.
Drag files between windows with the left button to copy, move or link them (choose from a menu).
Linking creates a shortcut to the original file.
By default, the mouse button bindings are designed to fit in with X conventions. However, the behaviour
is highly configurable — have a play in the Options window if you don't like the normal settings. The
normal settings behave as follows:
Key or
mouse Action
button
Open the file or directory clicked on. Hold down Control to select things instead of
Left button
opening them. Hold down Shift to look inside applications, treat files as text, follow
click
symlinks, or get more control over mount points (see Removable devices).
Middle Same as left click, but open a directory in a new window or close the viewer when opening
button click a file.
Right Open the main menu. Hold down Control while clicking to go directly to the Selection
button click submenu. Hold down Shift to get the Send To menu (see the Send To menu section).
Drag an Show a menu of possible actions. There is an option to disable this menu, in which case this
item (left gesture will copy the file(s) to the destination (an application or another filer window).
mouse Hold down Shift to move the file, Control+Shift to create a symbolic link, or Alt to get the
button) menu of possible actions.
Drag an
item
When you let go, display a menu of possible actions. There is an option to make this move
(middle
the files rather than open the menu.
mouse
button)
Select a group of items by dragging a box around them. With the left mouse button, only
Drag (not
the files in the box will be selected. If you hold down Control then the boxed items are
over an
added to the selection. If you use the middle button then the boxed items switch between
item)
being selected and unselected.
Double-
click Resize the window to a sensible size (this can be turned off from the Options window).
background
Backspace Change to viewing the parent directory.
Cursor keys Move the cursor around.
Page Up,
Move the cursor up and down a page at a time.
Page Down
Home, End Move to the first/last entry in the directory.
Acts like clicking on the file. You may hold down Shift for other effects, as with clicking.
Return Holding down Alt works like clicking with the middle button; directories open in a new
window and opening files closes the directory at the same time.
Toggles the item under the cursor between being selected and unselected, and moves to the
Spacebar
next item.
Tab,
Moves the cursor to the next/previous selected item.
Shift+Tab
Hold
Shows a tooltip containing a brief description of an application (if available), the target of a
mouse over
symbolic link, and the full name of a file, if it's too long to show in the main window.
an item
If you have user-defineable key-bindings enabled, then other keys can easily be set by opening the menu,
moving the pointer over the item you want to use and pressing a key. The key will appear in the menu
and can be used from then on. Key bindings are automatically saved when the filer quits. You can use an
XSettings manager, such as ROX-Session, to turn this feature on for all Gtk+-2.0 applications.
[1] This
documentation assumes that button–1 is the left button, button–2 is the middle button and
button–3 is the right button. This is not always the case — for example, in a left-handed setup.
Chapter 4. The selection and file groups

Table of Contents
When you select items in a ROX-Filer window, the filer takes the primary selection. You can then paste
into another window to get the pathnames of the selected files.
Procedure 4.1. Example: loading a file into an application that doesn't support drag-and-drop:
1. Open the application's Open dialog box.
2. Control-click on the file in ROX-Filer to select it.
3. Click the middle button in the filename box in the application to paste the name in.
Note that clicking the middle mouse button in the main area of most web-browsers will open the selected
file.
If you select something else (eg, some text in another program), the selected items in the filer window
will be shown shaded (the filer no longer has the primary selection). Clicking on one of the shaded items
will cause the filer to regain the primary selection.

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.
Procedure 4.2. Example: saving a directory and returning to it later:
1. You are looking at a directory, and wish to remember it. Press Control+1.
2. Move to another directory, or close the window, etc.
3. Press 1 in any filer window to return to the first directory.
The groups are saved automatically for next time the filer is loaded.
Chapter 5. The toolbar

By default, each window has a toolbar along the top. You can disable this (or make it larger) from the
Options window, as well as set which tools appear on the toolbar. Normally, you should click with the
left mouse button (1). However, many tools can perform a related function if clicked on with buttons 2 or
3 (middle or right).
Icon Mouse button 1 Other button
Cross Close the window Open a new window
Show parent in a new window
Up arrow Change to parent directory
[1]
House Change to home directory Show home in a new window [1]
Jump to point Open the Bookmarks menu Edit the bookmarks
Looping arrows Reread the directory contents Open a new window
Magnifying
Select a larger icon size. Select a smaller icon size.
glass (+)
Magnifying
Set Automatic sizing mode and resize the window. -
glass (fit)
List Hide or show extra details Same
Step backward through the sort
A..Z Step forward through the different sort types.
types.
Toggle the display of hidden files (those with names Toggle display of thumbnails for
Eye
starting with a dot) image files.
List with
Select All. Invert Selection.
selections
Life-belt Show ROX-Filer's help files Open manual directly
[1] If the 'New window on button 1' option is turned on then the default is to open a new window —
clicking with the other button reuses the same window instead.
Dragging files to the Up or Home icons acts just like dragging them into the directory which the button
leads to. Dragging to the Bookmarks button will add the directory as a bookmark.
The toolbar can also show the number of files in the directory, and information about the selection. This
can be turned on or off in the Options box.
Chapter 6. The menus

Table of Contents
The display menu
Permissions
The file menu

The select menu
The new menu
The window menu
The help menu
The send to menu
The bookmarks menu
By default, you can open a menu by right clicking over a pinboard, panel or filer window. In filer
windows, you may also press \ to open the menu. As a shortcut, you can open the File submenu directly
by holding down the Control key when opening the menu. Here is a full description of each menu item:
Entry Action
Entry Action
Display Change the display settings.
File Operations on the selected items.
Select Control which items are selected.
Options... Configure ROX-Filer.
New Create a new file or subdirectory inside this directory.
Window Operations on the window as a whole.
Help Information about the filer.
The display menu

Entry Action
Icons View Files are displayed as rows of icons.
Files are displayed as rows of icons with additional details (chosen from the
Icons, With...
submenu). To see fuller information about each file use the List View instead.
Show files in a list along with their details. Click on a column heading to sort
List View
by that column.
Bigger Icons Increase the size of the icons. Turns off Automatic mode.
Smaller Icons Reduce the size of the icons. Turns off Automatic mode.
Automatic Select a sensbile icon size automatically now and when changing directory, etc.
Set the sort mode. In List View you can also set the sort type by clicking on the
Sort by XXX
column headings.
Reversed Sort in reverse order (newest to oldest, largest to smallest, etc).
If on, files beginning with a dot are shown, otherwise they are hidden. The
Show Hidden
titlebar shows (All) when this is on.
Restrict the display to only show files with names matching the given pattern.
Filter Files...
The titlebar shows (Glob (pattern)) when this is on.
When on, the filer tries to load every image file and use that image as the file's
Show Thumbnails icon. Useful if you have a directory full of photos and can't remember which is
which! See the Thumbnails section for details.
Rereads the contents of the directory and details of all the files in it. Use this if
Refresh
the display becomes out-of-date.
Remember the display settings just for this directory. Each time you open the
Save Display Settings...
directory, the saved settings will be used.
Permissions
The permissions field, when shown, is made up of four groups of three flags. Each flag is displayed as a
letter if it is on and a dash (–) if not. The first three characters show the permissions for the owner of the
file, the second for other members of the file's group and the third for everyone else. Whichever group
applies to the ROX-Filer process itself is shown underlined. The fourth group shows any special flags.
The meanings of the characters are:
r — Permission to read the contents of a file, or the names of files in a directory.
w — Permission to alter the contents of a file, or change which names appear in a directory.
x — Permission to run the file as a program, or refer to the files listed within the directory.
U — This program executes with the effective user ID of its owner rather than the person who ran
it.
G — This program executes with the effective group ID of its group, regardless of who ran it.
T — Entries in this directory can only be altered or removed by the people who own the files even
if they have write permission on the directory itself.
For example,
rwx,rwx,r-x/---
means that the owner of the file is the same as the effective user of ROX-Filer (basically, you own the
file), you and members of the file's group have read, write and execute permission and other people have
only read and execute permission. There are no special flags set. The rules which determine which
permissions apply may vary slightly between operating systems, but a rough guide is:
If the effective user ID of the process is equal to the file's owner, then the owner permissions apply.
Otherwise, if the effective group ID of the process is equal to the file's group OR the file's group is
one of the process's supplemental groups then the group permissions apply.
Otherwise, the òther' permissions apply. The real user ID and real group ID have no effect (except
that a process may set its real IDs to its effective IDs).
The file menu

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.
Entry Action
Copy... Make a copy of this object.
Change the name used for this object, or move it between directories. If multiple files
Rename...
are selected, this opens The Bulk Rename window.
Link... Create a symbolic link to this name.
Remove all the selected entries from the directory. Subdirectories will have their
Delete contents deleted first. Deleting symlinks only removes the link, not the thing it points
to.
Opens applications as directories, files as text/plain, and symlinks by opening the
directory containing the thing they point to. It also has interesting effects on mount
Shift Open
points (see Removable devices). This is the same effect as clicking with Shift held
down. The text of the menu entry changes to show which action will be performed.
Opens the `Send To' menu, allowing you to send the selected files to one of a list of
Send To...
applications. See the Send To menu section.
Allows you to set the default program to use when opening files of this type. See the
Set Run Action...
Set Run Action box section for details.
Entry Action
You can give each file or directory its own special icon using this feature — simply
Set Icon...
drag a suitable image onto the Set Icon box.
Display extra information about this object. You can also change the access
Properties permissions from here (Permissions below allows you to change many files at once),
and change the target to which a symlink points.
Count the sizes of all the selected items. Directories also have their contents counted.
Count
Symlinks count themselves, not the things they point to.
Set the MIME type for a file. This only works on filesystems with extended attribute
Set Type...
support. For older filesystems, you will have to rename a file to change its type.
Allows you to change the permissions for the selected files. If only one file is to be
Permissions
changed, you can use Properties instead for a simpler interface.
Find Search for files by specifying various conditions — see the Searching section.
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.
The select menu

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.
Entry Action
Select All Select every item in this window.
Clear Selection Unselect every item in this window.
Invert Selection Every selected file becomes unselected, and every unselected file becomes selected.
Select just those files that match the given name pattern. This isn't as flexible as
Select If... (see below), but it is quicker to use. Files also highlight as you type with
Select by Name...
this option. The default key binding is ., so you can type .png to select all `.png'
files, for example.
Select If... Select just those files that match the given pattern — see the Select If section.
The new menu

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.
Entry Action
Directory Create a new directory.
File Create a blank file.
Customise Menu Open the `Templates' directory so that you can add extra items to the menu.
<user entries> Copy a file from your Templates directory.
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 ìndex.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 window menu

Entry Action
Parent, New Window Open a new window displaying this window's parent.
Parent, Same Window As above, but reuse this window.
New Window Open another window onto this directory.
Home Directory Change to your home directory.
Show Bookmarks Open the bookmarks menu (see Bookmarks menu).
Converts the path shown in the window's titlebar to its canonical form. For
example, if `/home/fred/link' is a symlink pointing to `/usr/share/doc/'
Follow Symbolic Links then clicking on the symlink will take you to that directory and going ùp' will
take you back to `/home/fred'. If you'd used Follow Symbolic Links, you
would have ended up in `/usr/share' instead.
Resize Window Set the window to a sensible size for its contents.
Close Window Close this window.
Enter Path... Open the path-entry box (see the the Minibuffer section).
Shell Command... Open the shell command box (see the Minibuffer section).
Xterm Here Open an xterm with its current directory set to this directory.
Open an xterm with its current directory set to this directory, and close the filer
Switch to xterm
window at the same time.
The help menu

Entry Action
Display information about the file. This is the same as locating ROX-Filer itself in a
About ROX-Filer...
filer window and selecting Properties from the file menu.
Show Help Files Same as selecting ROX-Filer and choosing Help from the file menu.
Opens the HTML manual for your language, or the English version if there is no
Manual
translation.
The send to menu

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.

You may want to set things up so that, for example, the Gimp is only shown when an image is selected.
To do this, create a hidden directory inside `SendTo' called `.image', or whatever type you want to use.
You can use either the complete type (eg `.image_png') or just the media type. Use Properties over a file
to find out its MIME type.
Entries in these hidden directories are shown only for files of the appropriate type. If multiple files are
selected, the `.group' directory is used instead.
The bookmarks menu

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.
Chapter 7. The pinboard and panels

Table of Contents

Panel applets
The Pinboard support and Panel support sections explain how to turn the pinboard and panels on. Once
on, you may drop items from filer windows onto the them to pin them up. Clicking on a pinned item acts
just like clicking on it in a filer window. You can drag pinned icons just like normal icons and you can
right-click on one to see the popup menu.
Drag panel icons with the middle mouse button to move them around. In previous versions of the filer,
pinboard icons were also moved using the middle mouse button, but this is no longer supported (as the
middle button is reserved for the window manager's use).
You can assign keyboard shortcuts to pinboard and panel icons. These can be used to open directories,
files or applications quickly, even if another window has the focus.
Changes to the pinboard and panel are automatically saved. Clicking on pinned icons with Control held
down selects and unselects them. Click on the background to unselect them all.
Important
Pinning a file does not copy it, it merely creates a shortcut to the original file. If you delete
the file, then you've lost it! Removing a pinned file from its pinboard or panel only
removes the link. This is different to most other filers...

Entry Action
ROX-Filer Show the filer's help, edit the options or open your home directory.
File `file' Offers a smaller version of the filer's submenu of the same name.
Change the name displayed under the icon, or the pathname the item points to. You can
Edit Item also set a keyboard shortcut for the icon here, and lock it against accidental deletion.
For programs, you can specify extra arguments to be passed in.
Show Location Open a directory viewer showing where the file is stored.
Remove Item(s) Remove the selected items from the pinboard or panel.
Backdrop... Set the desktop backdrop image (see below). Only available from the pinboard menu.
Set the edge of the screen on which the panel is displayed. Only available from the
Panel Options...
panel menu.
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.
Panel applets
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.
Procedure 7.1. To create your own applets (programmers only!):
1. Create a directory for the applet (eg `MyApplet').
2. Use the Set Icon... feature to create an icon called `.DirIcon' inside it (so the directory appears
with an icon).
3. Make a `Help' directory inside it for when the user chooses Help from the menu.
4. Create an executable file called ÀppletRun'. This will be passed the XID of the panel socket
window when the directory is dragged onto the panel. You can use this to create a GtkPlug widget.
A tutorial is available at http://rox.sourceforge.net/phpwiki/index.php/Tutorials/Applets

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).
Chapter 8. Removable devices

Using removable devices, such as floppy disks and CDROMs under ROX-Filer is quite simple. However,
it is important to understand about mounting and unmounting devices.
Mounting a device causes its contents to appear in the filesystem. On a typical setup, the directory
`/floppy' is an empty directory on the hard disk. The floppy device is then mounted onto this directory,
causing its contents to appear inside. For example, a file called `Letter' on the floppy disk will appear as
`/floppy/Letter'.
Devices must be unmounted before the disk is removed. Unmounting causes the system to write any
buffered data to the disk. If you remove a disk without unmounting it, it will probably be corrupted. CD
and Zip drives often lock the tray while the device is mounted so you can't remove it accidentally.
So that you don't have to specify which device should be mounted at which point in the filesystem every
time you want to use a disk, a preset list is usually found in the file `/etc/fstab'. ROX-Filer shows
mount points (such as `/floppy') which are listed here but not mounted with transparent grey circles
overlayed on their icons.
Clicking on one of these mount points will mount the device for you. The circle turns green to indicate
that the device is now mounted. Do not remove the device while the circle is lit! You can unmount the
device by clicking while holding down Shift on the `/floppy' directory icon.
You can also unmount a device by closing its directory window (eg, closing the view of `/floppy') and
choosing Unmount when prompted. The filer will only offer to unmount devices this way if they were
mounted by the filer in the first place.
If you want to open a directory without mounting anything (eg, if you want to see the contents of
`/floppy' on the hard disk), you can click on the unmounted mount point with Shift held down. This isn't
usually useful, as these directories are typically empty.
Chapter 9. File thumbnails

Table of Contents
Technical details
When thumbnailing is turned on, the filer tries to load every image file and use that image as the file's
icon. Useful if you have a directory full of photos and can't remember which is which! You can turn it on
for a single directory by choosing Show Thumbnails from the Display menu. You can set it as the default
from the Options box. The titlebar shows (Thumbs) when thumbnailing is on.
The thumbnails are saved in `~/.thumbnails' for quick loading next time. While loading thumbnails, a
progress bar appears at the bottom of the window. Clicking on the Cancel button beside the bar stops the
scan. It is also possible to thumbnail other types of file, such as videos (eg, by showing the first frame),
with a suitable helper program.
Technical details
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.
Chapter 10. Virtual file systems

Some types of file can be represented as a directory. A typical example is a zip file, which contains an
entire directory structure in compressed form. It is often useful to be able to open up such a file as if it
was a real directory, and the VFS system allows you to do this.
To use this feature you must have a system such as AVFS[AVFS] installed, which causes the kernel to
support various Virtual File Systems directly.
There are various ways to use AVFS. This example shows how to use it on a Linux 2.6 system with
FUSE. You will need a kernel with FUSE support and the 'libfuse-dev' header files package installed.
Procedure 10.1. Installing AVFS on Linux 2.6
1. Get AVFS from CVS (the current July 2005 release is too old).
2. Compile AVFS (sh autogen.sh; ./configure; make).
3. Go into the àvfs/fuse' subdirectory and run ./compile.sh.
4. Create a mount point: mkdir ~/.avfs-mount.
5. Run AVFS: ./avfsd ~/.avfs-mount.
6. To configure ROX-Filer to open directories using AVFS, set the run action (Set Run Action...) for
zip files (and other archive types) to:
rox ~/.avfs-mount/"$1#"
Note that all of the above steps should be done as a user, not as root. You may need to be in some special
group to use FUSE (check the group of `/usr/bin/fusermount').
If you don't want to make AVFS the default action for these files, you could instead create a script
containing the above and add it to the File menu, using Customise Menu....
Chapter 11. The mini-buffer

Table of Contents
The path-entry box

The mini-buffer is a white bar that appears along the bottom of the window and allows you to enter some
text. Press Escape to get rid of it again. It behaves in different ways depending on how you invoked it:
The path-entry box

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.
Key Action
Return Open the currently selected item.
Tab Shell-style tab completion.
Key Action
Up, Down Select the previous/next matching entry.
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.
Let's say you want to locate the documentation for Wine in the directory `/usr/share/doc' (which is
usually very large). Here's how you could do it:
1. Open the minibuffer by choosing Enter Path... from the Window menu, or by pressing the slash (/)
key.
2. Press CTRL+A to select the existing contents.
3. Type u<Tab>sh<Tab>do<Tab>wi<Tab>. As you type, the cursor will move to the correct
subdirectory. If it beeps when you press Tab then you need to supply more letters, or press Return.

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.
Examples:
To untar a `.tgz' archive:
1. Open the minibuffer by choosing Shell Command... from the Window menu. I usually bind this to
the bang (!) key.
2. Type tar xzf and click on the file. The leading space is automatically inserted.
3. Press Return to execute it.
To print all the selected files:
1. Open the shell command minibuffer.
2. Type lpr at the beginning of the line and press Return.
Notes
Be careful; you will not be asked to confirm! If in doubt, start the command with xmessage so that
it will be displayed rather than executed.
sh is always used as the name of the shell to run (mainly because bash and csh treat positional
parameters differently). However, PATH is searched to find it so you can still use another shell if
you want by naming it sh and putting it in your path.
Commands execute in the background, so you can say: sleep 240; xmessage Time to go!

Use this if you want to automatically select all files in the directory which match a condition.
For example, to select all files larger than 5Mb:
1. Open the Select If minibuffer (bound to ? by dafault).
2. Type Size > 5Mb and press Return.
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.
Chapter 12. Renaming files in bulk

If you have a large number of files to rename, it is tedious to rename them one by one. Instead, select all
the files and choose Rename... from the menu to open the bulk rename window.
The window shows a table with two columns. The Old name column shows the current name of each
selected file, and the New name column shows the new name, which is initially the same.
There are two ways to change the new names. You can edit the names in the table directly, or you can use
the search and replace feature at the top of the window. This takes a regular expression to search for, and
some text to replace matches with. For example, if you had a lot of files with names ending in `.htm' and
you wanted to change them to use `.html', you would enter \.htm$ in the Replace: field and .html in the
With: field. When you click Apply , the table is updated to show the proposed new names (but no actual
renaming is done yet).
Having checked that the new names look OK, click on the Rename button to actually perform the
rename operation.
Chapter 13. Action windows

Table of Contents
Action windows are those boxes that appear while you're doing a Copy/Move/Link/etc operation. The
status line at the top of the window shows the current directory or object that the window is processing.
The scrolling area below is the log area — it shows what has been done, and questions may be displayed
here.
Below this are four buttons and some options. All windows have the Quiet option. When this is on the
filer will only confirm some operations (such as deleting a non-writeable file). Otherwise, all operations
are confirmed.
The buttons work as follows:
Yes
answers yes to the question displayed in the log area.
No
answers no to the question displayed in the log area.
Cancel
kills the current operation (if any) and closes the action window.
Quiet
is a quick way to turn Quiet on and click Yes .
You can control which actions get started automatically (without you having to click on Quiet at the
start) from the Options window.

Some actions have options, which appear as option boxes at the bottom of the window. They are:
Force means that the filer won't treat non-writeable files as special. Normally, it confirms the
deletion even if Quiet is pressed. Note that you still can't remove files from non-writeable
directories because in that case you really don't have permission.
Brief prevents the filer logging a message every time it does something. Use this to speed things up
if large numbers of messages are being logged.
Recurse means that doing something to a directory will also do the same thing to all its contents,
and the contents of any subdirectories, and so on.
Newer will automatically copy a file over an existing one if the file is newer than the one it
replaces (later modification time).
You can set the defaults for these options from the Options box.
Chapter 14. Searching

Table of Contents
Wildcards
Simple tests
Logic operators
Comparisons
Specials
The Find feature looks through all the selected files and directories and any subdirectories (recursively)
looking for items that match a particular expression.
Choose Find from the File submenu to search all the selected objects. If you want to select all the files
within a single directory which meet certain criteria, use Select -> Select If... instead.
If you know the name of a file then just enter it in the Èxpression:' box, enclosed in single quotes. For
example, to find a file called `log' you would enter 'log'. Remember to use normal quotes, not double
quotes (") or back-quotes (`).
As the filer finds matching files they are added to the results list. Double-clicking on an entry in the list
opens a viewer showing that file. The filer will use the same window to view other results (so, if you
want the results shown in separate windows you must explicitly create a new window from the Window
menu).
Wildcards
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.
Simple tests
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 ÌsReadable and IsWriteable'.
These look at the type of the item being checked:
IsReg (-f) matches any regular (ie, normal) file.
IsLink (-l) matches symlinks.
IsDir (-d) matches directories.
IsChar (-c) matches character device files.
IsBlock (-b) matches block device files.
IsDev (-D) matches block or character device files.
IsPipe (-p) matches pipes.
IsSocket (-S) matches sockets.
IsDoor (-O) matches door objects (Solaris).
These look at the permissions set on the file — see the Permissions section.
IsSUID (-u) matches files which have the Set-UID bit set.
IsSGID (-g) matches files which have the Set-GID bit set.
IsSticky (-k) matches files with the sticky bit set.
IsReadable (-r) matches files which you can read from.
IsWriteable (-w) matches files which you can write to.

IsExecutable (-x) matches files which you can execute.
And a couple of other useful ones:
IsEmpty (-z) finds empty files (ie, those whose length is 0 bytes).
IsMine (-o) finds files which you own.
Logic operators
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.
Comparisons
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.
The following are read from the file being checked and may be used for the values being compared:
atime The time that the file was last accessed.
ctime The time that the file's status was last changed.
mtime The time that the file's contents were last modified.
size The size of the file.
inode The file's inode (index) number.
nlinks The number of links to this file. That is, the number of directory entries which refer to this
file. Note that symlinks don't count as references.
uid The User ID of the file.
gid The Group ID of the file.
blocks The number of disk blocks being used by the file.
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:
Byte(s) has no effect, but looks better.
Kb multiplies by 1024, so 2Kb is the same as 2048.
Mb multiplies by 10242, ie 1024 Kb.
Sec(s) has no effect, but looks nice.
Min(s) multiplies by 60 to get minutes.
Hour(s), Day(s), Week(s), Year(s) likewise convert to the relevant unit.
Ago makes the time in the past relative to when the check is done.
Hence makes the time in the future.
Now is short for 0 Secs Hence.
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...
Specials
System(Command) executes `Command' on the file. The test succeeds if the command returns an
exit status of zero. A `%' character in `Command' is replaced by the full path of the file being
checked. System is a very slow test to perform, so do it last if possible. For example, if you're
looking for a `.c' file containing the word `main', do:
'*.c' system(grep -q main "%")
so that the grep is only performed for files ending in `.c' (as opposed to only checking that the file
ends in `.c' if it contains the word `main').
Prune Always fails! [2] However, if it gets evaluated at all then it prevents the filer from checking
inside the current directory. Remember the order in which the filer checks the expression!
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.
[2] Note that this is the opposite of the find(1) command.
Chapter 15. Options

You can configure various aspects of ROX-Filer from the Options box. Choose Options... from a filer
window menu to open it. The list on the left of the window lists the various sections — click on one to
see its options. At the bottom of the window are two buttons:
OK saves the current choices into your `~/.config/rox.sourceforge.net/ROX-Filer' directory

for next time ROX-Filer is loaded, if anything changed. Exactly where choices are loaded from and
saved to is controlled by the XDG_CONFIG_HOME environment variable — see [BaseDir] for details.
Changes made in the Options box take effect instantly, so you don't need to click on OK just to try
them out.
Revert Restores all choices to how they were when the options box was opened. This button is
shown shaded if you haven't made any changes. The Options window is not closed when this is
used.
The options in the Options window have tooltips explaining the use of each option — hold the mouse
pointer over an option to find out what it does.
Chapter 16. Filetypes

Table of Contents

The Set Icon box

All files have a MIME type in the form text/plain. Here, text is the media type and plain is the sub-type.
ROX-Filer uses a file's name to decide what its MIME type is, and then uses the MIME type to decide
what icon to give it and what program to use when you open the file.

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:

Drag the Gimp (from a filer window, a panel or the pinboard) onto the area marked Drop a suitable
application here. From now on, clicking on a GIF file will load it into the Gimp.
Type: gimp "$@" into the box labelled Enter a shell command and press Return. $@ will be replaced by
the name of the file you click on when this command is used. As before, clicking on any GIF image will
now load it into the Gimp.
Whichever method you use to set the action you have the choice of setting the run action just for that
type, or setting the default for all files with that media-type which don't already have a specific action.
Since the Gimp can load many types of image, it makes sense to select the Set default for all
ìmage/<anything>' option so you don't have to do it again for image/jpeg files and so on. However, this
only affects types that don't already have a specific action (ie, those that would have brought up an error
box if you tried to open them).
The Set Icon box

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:
`MIME-types'
contains symlinks, one for each MIME type, which point to programs that can handle files of that
type. To set what program is run when you click on the file you should normally use the
Set Run Action... feature (see the the Set Run Action box section). However, you can also set the
actions manually — for example, to make opening an HTML file load it into Netscape:
1. Find the Netscape application and go to Link... on the menu.
2. Enter text_html as the name for the link and drag the icon from the Link box into the
`MIME-types' directory.
You can also put actual programs in here as well as links if you want to.
`MIME-icons'
contains the images used to display each type of file. So the filer will try to display an HTML file
using the icon `MIME-icons/text_html.png'. If no icon is set here, the filer will use the currently
selected icon theme (as set in the options box); see [IconTheme] for details.
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.
Chapter 17. Application directories

Table of Contents
The AppInfo file
An application directory is a directory which can be run as an application. It contains all the resources of
an application — source code, binaries, documentation and so on. Keeping everything in one place make
installation and uninstallation much easier for users. You can also keep multiple versions of a program by
simply having several application directories. You may move and rename them as you please.
Application directories make programs easier to use and install.
They're more secure too, because you can compile an application as a user and then simply copy it as
root. Since you don't have to run an install script you are free from the danger of running untrusted code
as root. All you have to watch out for is setuid binaries.
The following files are treated as special by ROX-Filer:
ÀppRun' is executed when you click on the directory — make sure it is executable (use the
Permissions box)!
`.DirIcon' is the image used to represent the directory (this works even if there is no ÀppRun').
`Help' is the directory to be opened when you choose Help from the File menu.
ÀppInfo.xml' contains extra information about an application (see below).
ÀppIcon.xpm' is used if `.DirIcon' is missing (for backwards compatibility; not to be used

anymore).
Have a look at the `ROX-Filer' application directory for a full example.
Note
For security reasons, an application directory must have the same owner as the ÀppRun'
file inside.
The AppInfo file

ÀppInfo.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>
Summary is displayed in a tooltip when the mouse is held over the application.
About contains a list of fields which are shown in the `File Info' box for the application (any
element names may be used, but the above are suggested).
AppMenu is a list of extra menu items to display for the application. When one is chosen, ÀppRun'
is called with option as its only argument. You can nest AppMenus inside other AppMenus to
create submenus, provided they have <Label> elements. Item elements can also have icon
attributes, which name an icon in the current icon theme for the menu item.
Chapter 18. Internationalisation
Table of Contents
ROX-Filer is able to translate many of its messages, provided suitable translation files are provided:
1. Open the Options box from the menu,
2. Select a language from the list,
3. Click on OK and restart the filer for the new setting to take full effect.

1. Go into the `src/po' directory and create the file `src/messages.pot':
$ cd ROX-Filer/src/po
$ ./update-po
2. Copy the file into the `src/po' directory as `<name>.po'. Eg, if your language is referred to as `ml'
(`my language'):
$ cp ../messages.pot ml.po
3. Load the copy into a text editor.
4. Fill in the translations, which are all blank to start with.
5. Run the `make-mo' script to create the binary file which ROX-Filer can use. You will need the GNU
gettext package for this.
$ ./make-mo ml
Created file ../../Messages/ml.gmo OK
6. Edit `ROX-Filer/Options.xml' so that your language is listed, restart the filer and select it from
the Options box (see the Translations section).
7. Submit the `.po' file to the ROX patch tracker so that we can include it in future releases of the
filer.

1. Go into the directory containing the `.po' files and run the ùpdate-po' script. This checks the
source code for new and changed strings and updates all the translation files.
$ ./update-po
2. Edit the file by hand as before, filling in the new blanks and updating out-of-date translations.
Look out for fuzzy entries where update-po has made a guess; check it's correct and remove the
fuzzy line.
3. Run make-mo as before.
4. Submit the updated file to us.
See the gettext info page for more instructions on creating a translation.
Chapter 19. Hacking

Table of Contents
Compiling
Autoconf
Data-structures
This is a quick start guide for people who want to modify the source code. If you make useful changes or
fix bugs, please send patches to me or to the mailing list. Tell me which version you're using!
Compiling
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:
They are smaller, and hence shouldn't bounce. They are also quicker to download for people with
slow connections.
People can see what they're getting into before applying them!
Patches can (usually) be applied to slightly modified versions of the sources. This means that
people can apply several patches without each new one overwriting the others.
Autoconf
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 ÀppRun' 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'.
Data-structures
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.
Appendix A. Compiling
If you've just got hold of the filer by downloading the source archive then you'll need to compile it before
you can use it. If you downloaded and installed a binary package, or if ROX-Filer was included with
your system, then you can skip this section. If you got here by clicking on the lifebelt symbol in a filer
window, or if typing rox at a shell prompt works, then you don't need to compile.
To compile, you will need the following:
Unix or Linux (root access is not required),
The X Window system (supplied as standard on all modern systems),
GTK+ 2.4.0 or later (libraries and headers) — get the latest version from [GTK+],
LibXML 2.0.0 or later (libraries and headers) — get the latest version from [libxml],
A C compiler, such as `gcc' (standard on most systems).
All of the above are standard on most modern Linux distributions. To check which version of GTK+ you
have installed, run the pkg-config command, like this ($ is the shell prompt):
$ pkg-config --modversion gtk+-2.0

2.6.8
Procedure A.1. To compile:

1. The filer now uses the Shared MIME Database[SharedMIME] to work out the types of files. You
need to install this before the filer will work properly (ROX-Filer will warn you if it's not installed
when you run it).
2. Change to the directory containing the ROX-Filer subdirectory.
3. Run the install.sh script, like this:
$ ./install.sh
4. ROX-Filer will perform various checks to find out what kind of system it is being run on and will
then compile. If it doesn't work then please e-mail me and complain! Tell me what kind of system
you have and what errors were reported. If you manage to fix the problem yourself then please e-
mail me the fix.
5. Once the filer has compiled you will be asked where you want to install it. If you want to do a
system-wide installation as root, you may want to stop here, su to root and rerun the install script.
If you don't have the root password then don't worry — just follow the instructions for installing
into your home directory.
You can now run the filer by running the rox script without any options, like this:
$ rox
A window should appear and display the contents of the current directory. If you installed the script into
your home directory then you may need to set your PATH environment variable so that the shell can find
it. For example, if you installed it into a directory called `bin' in your home directory, use this:
$ PATH=$HOME/bin:$PATH; export PATH
or (if you are using the csh(1) shell):
$ setenv PATH $HOME/bin:$PATH

$ rehash
Appendix B. Manual page

Table of Contents
ROX - a simple graphical file manager
Name
ROX-Filer — a simple graphical file manager
Synopsis
rox [OPTION...] [FILE...]
DESCRIPTION
ROX-Filer is a simple and easy to use graphical file manager for X11, the windowing system used on
Unix and Unix-like operating systems.
It is also the core component of the ROX Desktop: http://rox.sourceforge.net
Invoking rox opens each directory or file listed, or the current working directory if no arguments are
given.
COMMAND-LINE OPTIONS
-b, --border=PANEL
open PANEL.
-B, --bottom=PANEL
open PANEL as a bottom-edge panel.
-c, --client-id=ID
used for session management.
-d, --dir=DIR
open DIR as directory (not as an application, even if it looks like one).
-D, --close=DIR
close DIR and all its subdirectories.
-h, --help
display help about the various options.
-l, --left=PANEL
open PANEL as a left-edge panel.
-m, --mime-type=FILE
print MIME type of FILE and exit.
-n, --new
start a new filer, even if one already seems to be running. This also prevents the filer from forking
(running in the background). This option is mainly useful for debugging.
-p, --pinboard=PIN
use pinboard PIN as the pinboard.
-r, --right=PANEL
open PANEL as a right-edge panel.
-R, --RPC
read and invoke SOAP RPC from standard input (see Appendix C, SOAP RPC).
-s, --show=FILE
open a directory showing FILE.
-S, --rox-session
run under ROX-Session, open the default panel and pinboard (implies --new).
-t, --top=PANEL
open PANEL as a top-edge panel.
-u, --user
show user name in each window.
-v, --version
display the version information and exit.
-x, --examine=FILE
FILE has changed; re-examine it.
NOTES
The main documentation for ROX-Filer is available by choosing Show Help Files from the popup menu,
or by clicking on the right-most toolbar icon.
LICENSE
Copyright (C) 2004 Thomas Leonard.
You may redistribute copies of ROX-Filer under the terms of the GNU General Public License.
BUGS
Please report bugs to the developer mailing list: http://rox.sourceforge.net/contact.html.
AUTHORS
ROX-Filer was created by Thomas Leonard, with help from:
Michael Adams Thierry Godefroy Christiansen Merel

Christopher Arndt Olli Helenius Jimmy Olgeni
Jens Askengren Alex Holden Richard Olsson
Liav Asseraf Jasper Huijsmans Matthew O'Phinney
Wilbert Berendsen Sigve Indregard Daniele Peri
Francesco Bochicchio Bernard Jungen Andy Piper
Yuri Bongiorno Marcin Juszkiewicz Marcelo Ramos
Andrzej Borsuk James Kermode Michel Alexandre Salim
Richard Boulton Jim Knoble Adam Sampson
Simon Britnell Krzysztof Krzyzaniak Chris Sawer
Arnaud Calvo Aaron Kurtz Christian Storgaard
Babyfai Cheung Vincent Ledda Taras
Andrew Clover Vincent Lefevre Simon Truss
Fabien Coutant Victor Liu See-le Hirosi Utumi
Couderc Damien Alexey Lubimov Jan Wagemakers
Andreas Dehmel Krzysztof Luks Keith Warno
Micah Dowty Marcus Lundblad Götz Waschk
Dmitry Elfimov Anders Lundmark Stephen Watson
Mattias Engdegard Jose Romildo Malaquias Andre Wyrwa
Andrew Flegg Denis Manente Geoff Youngs
Olivier Fourdan Brendan McCarthy Diego Zamboni
Eric Gillespie Andras Mohari
and many others; the `Changes' file contains more detailed information!
Appendix C. SOAP RPC

When the filer starts you can use command-line options to control its behaviour. As an alternative to this,
the filer allows you to specify an operation with a [SOAP] RPC format message. In fact, if you use the
command-line options, the filer converts to SOAP RPC internally.
All SOAP RPC messages are passed on standard input, like this:
$ rox --RPC << EOF

<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope">
<env:Body xmlns="http://rox.sourceforge.net/SOAP/ROX-Filer">
<Panel>
<Name>Default</Name>
<Side>Bottom</Side>
</Panel>
</env:Body>
</env:Envelope>
EOF
The following methods are recognised:
Version() Returns the filer's version.
CloseDir(Filename) Close directory Filename and all its subdirectories.
Examine(Filename) Filename may have changed — check it and update the display.
OpenDir(Filename, [Style, Details, Sort, Class, ID, Hidden, Filter]) Open a window showing
directory Filename. Style is one of Large, Small, Huge or Automatic. Details is one of None,
ListView, Size, Type, Times or Permissions. Sort is one of Name, Type, Date, Size, Owner or
Group. If any of these three option parameters are missing, the default is used. Class can be used to
set the WM_CLASS property on the new window. You can use this to get your window manager to
treat the window specially. ID is a string used to identify the opened window. If a window with this
ID already exists, it is changed to the given directory. Otherwise, a new window is created and
given this ID. If used from a program, ensure the IDs you generate are unique, for example by
including your process name, PID and a timestamp in the ID. Hidden if true means that hidden
files (those that start with a dot character) are shown, or not shown if false. If ommitted then the
configured setting is used. Filter can be used to filter files shown by their name. For example using
a filter of *.c means that only files ending in .c are shown.
Panel([Side, Name]) Open the panel named Name on screen side Side (Top|Bottom|Left|Right).
Name can be a name in `~/.config/rox.sourceforge.net/ROX-Filer' (eg, MyPanel) or a full
pathname. If not given, the panel on that side is turned off.
PanelAdd(Side, Path, [Label, After, Shortcut, Args]) Add Path to the panel on side Side, with label
Label. If After is true the icon goes on the right/bottom side of the panel, otherwise on the left/top
side. If Shortcut is given it is the keyboard shortcut to trigger this item. If Args is given it is the
argument string to append to the item when run if it is a program.
PanelRemove(Side, [Path, Label]) Remove an item from the panel on side Side. If Path or Label
is not given then any path or label will match. At least one must be specified. If more than one item
matches, only one is removed.
Pinboard([Name]) Display pinboard Name on the desktop background. Name can be a name in
`~/.config/rox.sourceforge.net/ROX-Filer' (eg, MyPinboard) or a full pathname. If not given,
the pinboard is turned off.
PinboardAdd(Path, X, Y, [Label, Shortcut, Args]) Add Path to the pinboard at position (X, Y),
giving it the (optional) label Label. If Shortcut is given it is the keyboard shortcut to trigger this
item. If Args is given it is the argument string to append to the item when run if it is a program.
PinboardRemove(Path, [Label]) Remove Path from the pinboard. If Label is given then this must
match the label of the item. If more than one item matches, only one is removed.
SetBackdropApp(App) Make App (an application directory) the new handler for the current
pinboard's backdrop. The ÀppInfo.xml' file inside App must contain the CanSetBackdrop
element, eg:
<AppInfo>
<ROX:CanSetBackdrop xmlns:ROX="http://rox.sourceforge.net/SOAP/ROX-Filer"/>
</AppInfo>
The application will be run with the --backdrop option as it's only argument after invoking this
method, and whenever the pinboard is reloaded. DO NOT use this method if invoked with --
backdrop or you will get stuck in an infinite loop! See Backdrop applications for a guide to writing
backdrop applications.
SetBackdrop(Filename, Style) Set the backdrop image to a given file. If you want to regenerate
the image next time the user logs in, or you want to change it automatically from time to time, use
SetBackdropApp above instead.
Run(Filename) Run Filename as if it was clicked on in the filer.
Show(Directory, Leafname) Open Directory and flash the file Leafname inside it.
FileType(Filename) Returns the MIME-type of Filename (by writing the SOAP response to
standard output).
SetIcon(Path, Icon) Set the icon to use for the given path. This is equivalent to using the Set Icon...
menu item.
UnsetIcon(Path) Clear the icon to use for the given path.
The following calls can be used to start new file actions. Quiet can be true if the operation should start
immediately, instead of waiting for the user to confirm. If false, the user must always confirm. If not
given, the default setting is used.
Copy(From, To, [Leafname, Quiet]) Copy each file in the array From to the directory To. If
Leafname is given then From should contain a single entry only; Leafname gives the new
leafname.
Move(From, To, [Leafname, Quiet]) Move each file in the array From to the directory To. If
Leafname is given then From should contain a single entry only; Leafname gives the new
leafname.
Link(From, To, [Leafname]) Symlink each file in the array From to the directory To. If Leafname
is given then From should contain a single entry only; Leafname gives the new leafname.
Mount(MountPoints, [OpenDir, Quiet]) Mount each directory in the list MountPoints. If true,
OpenDir causes each directory to be opened once it is mounted.
Unmount(MountPoints, [Quiet]) Unmount each directory in the list MountPoints.
References
[ROX] The ROX desktop, http://rox.sourceforge.net
[RISC OS] RISC OS, http://www.riscos.com
[GTK+] GTK+ Toolkit, http://www.gtk.org
[libxml] The XML C library for Gnome http://www.xmlsoft.org
[GNOME] The GNOME desktop, http://www.gnome.org
[DND] The Drag and Drop protocol, http://www.newplanetsoftware.com/xdnd/
[XDS] The X Direct Save protocol, http://www.newplanetsoftware.com/xds/
[BaseDir] The freedesktop.org base directory system, http://www.freedesktop.org/wiki/Standards_2fbasedir_2dspec
[AVFS] AVFS - A Virtual File System, http://sourceforge.net/projects/avf/
[SOAP] Simple Object Access Protocol (SOAP) 1.2 http://www.w3.org/TR/SOAP/
[Thumbs] Thumbnail Managing Standard (Version 0.5) http://triq.net/~jens/thumbnail-spec/
[Wallpaper] Wallpaper backdrop control application http://rox.sourceforge.net/phpwiki/index.php/Wallpaper
[SharedMIME] Shared MIME-info Database (Version 0.16)

http://www.freedesktop.org/wiki/Standards_2fshared_2dmime_2dinfo_2dspec
[IconTheme] The freedesktop.org Icon Theme specification

http://www.freedesktop.org/wiki/Standards_2ficon_2dtheme_2dspec

ROX-Filer User Manual

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ROX-Filer User Manual

Uploaded by

Copyright:

Available Formats

ROX-Filer User Manual

Copyright © 2005 Thomas Leonard

3. Mouse button and key bindings

Saving and restoring the selection

The display menu

Showing different applications for different types

The bookmarks menu

7. The pinboard and panels

The pinboard and panel menus

10. Virtual file systems

The path-entry box

12. Renaming files in bulk

Action window options

The Set Run Action box

Setting the run action by drag-and-drop

The Set Icon box

17. Application directories

The AppInfo file

ROX - a simple graphical file manager

Shared MIME Info Database

DNotify support (Linux only)

$ rox /home /usr /usr/local

You can also use it to open files, like this:

For a complete list of command-line options, see Appendix B, Manual page

The pinboard configuration is saved in `~/.config/rox.sourceforge.net/ROX-Filer/pb_MyPinboard'

Window manager notes

# Manage root window (EXPERIMENTAL - normally enabled!)

Paste these into `~/.icewm/winoptions':

# ROX-Filer pinboard and panel

1. Run the filer using rox -p=Default.

2. Press Control+Escape, or [RightButtonDown] on any window's titlebar. Choose Attributes... from

Disable miniaturize button

Keep at bottom (sunken)

Do not show in the window list

Ignore 'Hide Others'

Ignore 'Save Session' (possibly)

gnomesu -c 'setsid /usr/local/bin/rox /'

Chapter 3. Mouse button and key bindings

Chapter 4. The selection and file groups

Saving and restoring the selection

1. Open the application's Open dialog box.

2. Control-click on the file in ROX-Filer to select it.

Saving and restoring the selection

Procedure 4.2. Example: saving a directory and returning to it later:

2. Move to another directory, or close the window, etc.

3. Press 1 in any filer window to return to the first directory.

Chapter 5. The toolbar

Chapter 6. The menus

The display menu

The file menu

Showing different applications for different types

The bookmarks menu

The display menu

The meanings of the characters are:

r — Permission to read the contents of a file, or the names of files in a directory.

The file menu

The select menu

The new menu

The window menu

The help menu

The send to menu

Showing different applications for different types

The bookmarks menu

Chapter 7. The pinboard and panels

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