Copyright © 2002 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
Table of Contents
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'.
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].
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].
A simple, but flexible, system for managing user choices. See [Choices] for details.
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.
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 (spec is still in developement).
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.
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 `i' 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.0.1 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.0.5
Procedure 2.1. To compile:
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).
Change to the directory containing the ROX-Filer subdirectory.
Run the install.sh script, like this:
$ ./install.sh
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.
The executable file is stored inside the ROX-Filer directory in a different subdirectory for each platform. Therefore, you can compile the same application on several different types of machine and then run it from any of them using the `AppRun' script. This is particularly useful in a network environment.
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
Table of Contents
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. You can override this (perhaps because the old copy has stopped responding for some reason) using the --new option.
For a complete list of command-line options, see Appendix A
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 `<Choices>/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. You can create a panel on any side of the screen by using the options --left, --right, --top and --bottom, depending on which side of the screen the panel should appear on. On some systems, the short (one letter) form of the options must be used. For example, to create a panel along the bottom edge of the screen:
$ rox -b=MyPanel
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 `<Choices>/ROX-Filer/pan_MyPanel'. As with the pinboard, you can switch between panel configurations simply by running rox again with a different panel name. Specify a blank name to remove the panel.
$ rox --bottom=MyOtherPanel $ rox --bottom=
You may have to play around with your window manager a bit to get the pinboard icons and panels to display correctly (eg, without borders and underneath all other windows). In particular, try setting the stacking level / depth to low (or a negative value). Make sure any 'Keep transients above other windows' type options are turned off!
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).
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.
Run the filer using rox -p=Default.
Press Control+Escape, or [RightButtonDown] on any window's titlebar. Choose from the menu.
The Attributes Inspector window appears. From the pulldown menu at the top, choose
(the top item).Press the Window Specification' frame should change their labels to include ROX-Pinboard.ROX-Filer as the first item. Select that radio button.
button. The cursor changes to a double crosshair. Select one of the ROX-Filer pinboard icons. The radio buttons in the `Choose Attributes' frame, choose the features you want the pinboard icons to have; I recommend the following:
from the pulldown menu. In the `Disable titlebar
Disable resizebar
Disable close button
Disable miniaturize button
Keep at bottom (sunken)
Omnipresent
Choose Advanced' frame, choose the advanced features you wish; I recommend the following:
from the pulldown menu. In the `Do not show in the window list
Ignore 'Hide Others'
Ignore 'Save Session' (possibly)
When you're finished selecting window attributes, press the
button, and then close the Attributes Inspector window using the button in the titlebar.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!).
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 them, or with the middle button to get a menu of possible actions (copy, move, link, etc).
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 button | Action |
---|---|
Left button click | Open the file or directory clicked on. Hold down Control to select things instead of opening them. Hold down Shift to look inside applications, treat files as text, follow symlinks or mount devices. |
Middle button click | Same as left click, but open a directory in a new window or close the viewer when opening a file. |
Right button click | Open the main menu. Hold down Control while clicking to go directly to the Selection submenu. Hold down Shift to get the Send To menu (see the Send To menu section). |
Drag an item (left mouse button) | Copy the file(s) to the destination (an application or another filer window). Hold down Shift to move the file, Control+Shift to create a symbolic link, or Alt to get a menu of possible actions. |
Drag an item (middle mouse button) | When you let go, display a menu of possible actions. There is an option to make this move the files rather than open the menu. |
Drag (not over an item) | Select a group of items by dragging a box around them. With the left mouse button, only the files in the box will be selected. If you hold down Control then the boxed items are added to the selection. If you use the middle button then the boxed items switch between being selected and unselected. |
Double-click background | Resize the window to a sensible size. |
Backspace | Change to viewing the parent directory. |
Cursor keys | Move the cursor around. |
Page Up, Page Down | Move the cursor up and down a page at a time. |
Home, End | Move to the first/last entry in the directory. |
Return | Acts like clicking on the file. You may hold down Shift for other effects, as with clicking. 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. |
Spacebar | Toggles the item under the cursor between being selected and unselected, and moves to the next item. |
Tab, Shift+Tab | Moves the cursor to the next/previous selected item. |
Hold mouse over an item | Shows a tooltip containing a brief description of an application (if available), the target of a symbolic link, and the full name of a file, if it's too long to show in the main window. |
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.
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 5.1. Example: loading a file into an application that doesn't support drag-and-drop:
Open the application's Open dialog box.
Control-click on the file in ROX-Filer to select it.
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 5.2. Example: saving a directory and returning to it later:
You are looking at a directory, and wish to remember it. Press Control+1.
Move to another directory, or close the window, etc.
Press 1 in any filer window to return to the first directory.
The groups are saved automatically for next time the filer is loaded.
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 |
Up arrow | Change to parent directory | Show parent in a new window [1] |
House | Change to home directory | Show home in a new window [1] |
Looping arrows | Reread the directory contents | Open a new window |
Magnifying glass | Make icons bigger | Make icons smaller |
List | Hide or show extra details | Same |
Crossed out text | Toggle the display of hidden file (those with names starting with a dot) | Same |
Life-belt | Show ROX-Filer's help files | Show help files and close window |
[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. 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.
Table of Contents
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 |
---|---|
Change the display settings. | |
Operations on the selected items. | |
Control which items are selected. | |
Configure ROX-Filer. | |
Create a new file or subdirectory inside this directory. | |
Operations on the window as a whole. | |
Information about the filer. |
Entry | Action |
---|---|
Extra large icons (mainly useful with thumbnails, see below). | |
Each object in the directory is shown as a large icon with its name below. | |
Items are drawn smaller than usual, allowing you to see more files at once. | |
As for | , but with extra large icons.|
Entries are displayed along with some extra details:
| |
As above, but with a smaller icon and all on one line. | |
Items are arranged by name. The default sort mode is case-insensitive and deals with numbers sensibly. There is an option to use straight ASCII sorting. | |
Items are grouped by their types and then sorted by name within the groups. | |
Most recently modified first. | |
Largest first. | |
If on, files beginning with a dot are shown, otherwise they are hidden. The titlebar shows `(All)' when this is on. | |
When 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! 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 (Thumbs)' when this is on. | button beside the bar stops the scan. The titlebar shows `|
Rereads the contents of the directory and details of all the files in it. Use this if the display becomes out-of-date. |
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 `other' 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).
All of these work in the same way — if you open the menu with some items selected then the operation applies to those items. If you open then menu over an item while there is no selection then that item is temporarily selected.
If you choose one of these while there is no selection at all then the window goes into `target mode'; the operation happens to the next item you click on. Click on the window background, press Escape, or click with the right mouse button to cancel target mode. Target mode is mainly useful with the `Single-click navigation in filer windows' option and keys bound to the various menu entries.
Note that individual applications may add extra menu items to the top of this submenu when you click over them — see Application directories for details.
Entry | Action |
---|---|
Make a copy of this object. | |
Change the name used for this object, or move it between directories. | |
Create a symbolic link to this name. | |
Remove all the selected entries from the directory. Subdirectories will have their contents deleted first. Deleting symlinks only removes the link, not the thing it points to. | |
Explain what kind of thing is selected. For applications, display the help files. | |
Opens applications as directories, files as text/plain, mount points by mounting or unmounting them and symlinks by opening the directory containing the thing they point to. 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. | |
Open the file as if it was a directory — see the Virtual file systems section. | |
Opens the `Send To' menu, allowing you to send the selected files to one of a list of 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 box section for details. | |
You can give each file or directory its own special icon using this feature — simply drag a suitable image onto the Set Icon box. | |
Display extra information about this object. | |
Count the sizes of all the selected items. Directories also have their contents counted. Symlinks count themselves, not the things they point to. | |
Allows you to change the permissions for the selected files. | |
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.
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 every item in this window. | |
Unselect every item in this window. | |
Every selected file becomes unselected, and every unselected file becomes selected. | |
Select just those files that match the given pattern — see the Select If section. |
Each entry in this submenu opens a savebox for creating a new file or directory. There are two standard entries; the others are the contents of your `<Choices>/Templates' directory, if it exists.
Entry | Action |
---|---|
Directory | Create a new directory. |
File | Create a blank file. |
<user entries> | Copy a file from your Templates directory. |
To add your own entries, create a new directory called `~/Choices/Templates' (if you have the default CHOICESPATH) 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.
Entry | Action |
---|---|
Open a new window displaying this window's parent. | |
As above, but reuse this window. | |
Open another window onto this directory. | |
Change to your home directory. | |
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/' then clicking on the symlink will take you to that directory and going `up' will take you back to `/home/fred'. If you'd used | , you would have ended up in `/usr/share' instead.|
Set the window to a sensible size for its contents. | |
Close this window. | |
Open the path-entry box (see the the Minibuffer section). | |
Open the shell command box (see the Minibuffer section). | |
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 window at the same time. | |
Same as selecting ROX-Filer and choosing | from the menu.
Entry | Action |
---|---|
Display information about the file. This is the same as locating ROX-Filer itself in a filer window and selecting | from the file menu.|
Same as selecting ROX-Filer and choosing | from the file menu.|
Opens the HTML manual for your language, or the English version if there is no translation. |
The `Send To' menu provides a quick way to send some files to an application. The filer scans all the `SendTo' directories in your CHOICESPATH and lists the contents on this menu.
To change which applications appear here you should choose the Control and Shift held down.
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 withOpening 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
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.
Table of Contents
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.
If the panel has so many icons that they can't all be shown at once then you can scroll it by dragging the blank area in the middle.
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 |
---|---|
Show the filer's help, edit the options or open your home directory. | |
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 also set a keyboard shortcut for the icon here. | |
Open a directory viewer showing where the file is stored. | |
Remove the selected items from the pinboard or panel. | |
Set the desktop backdrop image (see below). Only available from the pinboard 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
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.
Procedure 8.1. To create your own applets (programmers only!):
Create a directory for the applet (eg `MyApplet').
Use the
feature to create an icon called `.DirIcon' inside it (so the directory appears with an icon).Make a `Help' directory inside it for when the user chooses
from the menu.Create an executable file called `AppletRun'. 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. An example applet (written in python) is available at http://rox.sourceforge.net/applets.php3
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 highlight when you move the mouse over them 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
from the pinboard menu (right-click over the desktop background when the pinboard is turned on).To set an image, select `Centred', `Scaled' or `Tiled' 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 .
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 B). 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.
This example program will display an image of the Earth on the backdrop, updating it once a minute. Note the three places we check for the filer closing its connection with us: when sending the image, when waiting for acknowledgement, and while sleeping. This file should be saved as `AppRun' inside your new application directory. To set the backdrop, run the application (eg, by clicking on it).
#!/usr/bin/env python import sys, os if len(sys.argv) == 1: # Become the backdrop application app = os.path.abspath(os.path.dirname(sys.argv[0])) cin = os.popen('rox -R', 'w') cin.write("""<?xml version="1.0"?> <env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope"> <env:Body xmlns="http://rox.sourceforge.net/SOAP/ROX-Filer"> <SetBackdropApp><App>""" + app + """</App></SetBackdropApp> </env:Body> </env:Envelope> """) sys.exit(0) elif len(sys.argv) != 2 or sys.argv[1] != '--backdrop': sys.stderr.write("Usage: %s [--backdrop]\n" % sys.argv[0]) sys.exit(1) # If we get here, we've been run by the filer. # Generate a sequence of images, sending them to the filer one by one. import tempfile, time, signal from select import select time_between_updates = 60 while 1: # Write image to a temporary file path = tempfile.mktemp('.ppm') child = os.fork() if child == 0: fd = os.open(path, os.O_CREAT | os.O_WRONLY | os.O_TRUNC, 0600) os.dup2(fd, 1) os.execvp("xearth", ["xearth", "-ppm"]) os._exit(1) pid, status = os.waitpid(child, 0) if status: break # xearth didn't work # Send message to filer quit = 0 try: print "centre " + path sys.stdout.flush() if sys.stdin.readline() != 'ok\n': quit = 1 # filer closed connection except: quit = 1 # filer closed connection # Delete temporary file os.unlink(path) if quit: break # Wait until the next image is due, or the filer tells us to quit ready = select([sys.stdin], [], [], time_between_updates)[0] if ready: # filer closed connection while we were waiting break
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.
Table of Contents
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:
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. |
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:
Open the minibuffer by choosing /) key.
from the Window menu, or by pressing the slash (Press CTRL+A to select the existing contents.
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:
Open the minibuffer by choosing !) key.
from the Window menu. I usually bind this to the bang (Type tar xzf and click on the file. The leading space is automatically inserted.
Press Return to execute it.
To print all the selected files:
Open the shell command minibuffer.
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:
Open the Select If minibuffer.
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.
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:
answers yes to the question displayed in the log area.
answers no to the question displayed in the log area.
kills the current operation (if any) and closes the action window.
is a quick way to turn `Quiet' on and click .
You can control which actions get started automatically (without you having to click on
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 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.
Table of Contents
The Find feature looks through all the selected files and directories and any subdirectories (recursively) looking for items that match a particular expression.
Choose
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 -> instead.If you know the name of a file then just enter it in the `Expression:' 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).
You can also put shell-style wildcard characters inside the quotes, for example:
'*.html' |
'Report.*' |
'Draft[1-5]' |
'main.[ch]' |
Look at the glob(7) manpage if you want to know more about shell wildcards.
If the pattern you enter contains a slash (`/') character then the pattern is matched against the file's full path, otherwise only the leafname is used. That is, '*tmp*' will find `tmp' and `tmpfile' but not `/tmp/file' — '/*tmp*' will find all three.
As well as finding files by their names you can also find them by various other attributes. Note that file is used here to mean anything that can appear in the filesystem — including directories, devices and so on.
You can also use a short form for each test; these are shown in brackets. You can combine multiple tests — `-rw' is the same as `IsReadable and IsWriteable'.
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.
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.
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.
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...
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.
Table of Contents
You can configure various aspects of ROX-Filer from the Options box. Choose
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:Choices] for details. Changes made in the Options box take effect instantly, so you don't need to click on just to try them out.
saves the current choices into your Choices directory for next time ROX-Filer is loaded, if anything changed. Exactly where choices are loaded from and saved to is controlled by the CHOICESPATH environment variable — see [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.
Many of the options in the Options window have tooltips — hold the mouse pointer over the option to find out what it does.
You can choose which language the filer will display messages in from here, or get it to read the LANG environment variable to get the desired language.
`Automatically resize filer windows' can be used to control when windows are automatically resized:
`Never automatically resize' turns off auto-resizing. Windows must be resized manually.
`Resize when changing the display style' will resize the window automatically when you change the icon size or the type of details to be displayed.
`Always resize' causes the window to resize whenever it seems useful (that is, when changing to a different directory or when switching between display styles).
`Largest window size' sets the largest size (as a percentage of the screen size) that the auto-resizer will resize windows to.
`Change from Large icons to Small automatically' allows the filer to choose the size when changing directory. The switching threshold is set using the number entry below.
`Short titlebar flags' abbreviates the All, Thumbs and Scanning titlebar indicators to single letters.
`Unique windows' prevents you from having two windows showing the same directory. Opening a second view onto a directory simply reshows the first one.
`New window on button 1' swaps the actions of the two non-menu buttons when opening directories. This is provided for people who are used to the RISC OS mouse bindings.
`Single-click navigation in filer windows' means that clicking on a file or directory will open it. If off, clicking on files selects them instead — you must double click on a file to open it.
`Intelligent sorting' treats upper and lower case letters as equivalent when sorting, ignores punctuation, and sorts numbers numerically. If this is off then `Zoo' comes before `animal', for example.
`Directories always come first' means that all directories are sorted and displayed at the top, then all the other items are sorted and displayed below. With this option off, directories are mixed in with the other files.
`Large wrap width' sets the maximum width for a file's name in `Large Icons' display mode before the text will wrap onto two lines. In `Huge Icons' mode, the wrap width is 50% larger than this value.
`Max Small Icons width' — in `Small Icons' mode, any text longer than this is chopped off (a red bar indicates that some text is not shown). You can hold the mouse over the truncated name to see the full text.
`Default settings for new windows' — these options provide the default settings for newly opened windows. They correspond to choosing styles from the menu. If `Inherit options from source window' is on then opening a new window from an existing window (eg, by clicking the middle button over a directory) gives the new window the same options (icon size, sort order, etc) as the old window. If off, the new window has the default settings chosen here.
The toolbar is described in the Toolbar section.
`Unshade the tools you want:' allows you to set which tools should appear on the toolbar. Click on the buttons below to shade and unshade them — shaded tools will not be shown on filer window toolbars.
`Toolbar type' allows you to choose what kind of toolbars you want. means that windows will not have a toolbar, provides a small bar of icons, displays larger buttons, with textual labels below, and displays wider buttons, with textual labels next to the icons.
`Show totals of items' shows the number of items displayed in a filer window, as well as the number of hidden items (if any) on the toolbar. When there's a selection, it shows the number of selected items and their combined size (excluding directories).
These two options control what happens when you press Tab in the path entry minibuffer:
`Beep if Tab-completion fails' — beep if there is no match, or there are several possible completions, each starting differently.
`Beep if there are several matches' — beep if there are several matches, even though some letters were added.
See the Pinboard support section for instructions on enabling the pinboard.
`Colours' sets the colours used for the text under the icons, and the background colour (if no background image is set).
`Use custom font' can be used to set a different font for pinboard icons. If unset, the global default font, as set by your session manager (eg ROX-Session) is used.
`Single-click to open' allows you to open a file or directory just by clicking on it. Hold down Control to select things. If this is off, clicking selects and double-clicking opens.
`Keep icons within screen limits' prevents icons from going partly off the side of the screen.
`Icon grid step' controls how finely the icons may be positioned.
`Iconified windows' controls how the filer deals with iconified (or 'minimised') windows. If `Show iconified windows' is on then the filer shows an icon on the pinboard for each iconified window. The other two options let you choose the method of placing the icons. See Iconified windows for details.
If you are using panels (see the Panel support section) then this section lets you choose which icons will have textual labels underneath them. You can have labels on all icons, on no icons, or on all icons except applications.
You can choose to start some operations automatically, without waiting for you to click on
. Select each operation that you want to auto-start here. You can also set the default state for each of the options that appear inside action windows.
`Allow dragging to icons in filer windows' controls what happens when you drop files onto icons in filer windows. If on then drops onto directories will save the data inside the directory, while dropping onto programs will invoke the program on that data. If off then drops anywhere inside a filer window act like drops onto the window background — that is, the data will be saved into the directory being displayed.
`Directories spring open' controls what happens when you hold a file over a directory while dragging it. If on, the directory will `spring open' after a short pause, allowing you to navigate to any directory during a drag. You can also hold the pointer over the Home and Up buttons on the toolbar for a similar effect. You need to have the previous option enabled for this to have any effect on files displayed in a directory.
`Spring delay' sets how long, in thousanths of a second, the filer will wait before spring opening a directory as described above. If the above option is turned off, then this has no effect.
`Dragging files with the middle mouse button' you can choose whether this displays a menu (like Alt dragging) or moves the files (like Shift dragging).
`Menu on button 2' swaps the actions of buttons 2 and 3 so that the middle button brings up the menus. This is provided for people who are used to the RISC OS mouse bindings.
As an alternative to using the options window to put menu on button-2, some people prefer to use the command xmodmap -e "pointer = 1 3 2", which makes the right mouse button button-2 and the middle one button-3 (this affects all programs, not just ROX-Filer).
`Size of icons in menus' controls the size of the icons in the and menus.
`Xterm here program' is the command used when you choose from the menu. You can replace it with another command such as gnome-terminal, konsole, or anything else.
`Ignore eXecutable bit for known extensions' means that when a file has a known extension (eg `.gif') the executable bit is ignored. This is useful if you have files on a Windows-type filesystem which are being shown as executable programs. However, it prevents a file such as `script.sh' from being treated as a program.
The MIME type system used in the filer is described more fully in Chapter 14.
opens the directories containing the files which tell the filer what type to give each file.
Make sure you run the `update-mime-database' command after editing the files, and click on the Refresh toolbar button to make the filer read the new settings.
`Override window manager control of the pinboard and panels' may need to be turned on to stop older window managers from trying to display the pinboard and panels in a normal window, or from raising them when clicked and from doing other odd things.
`Pass all backdrop mouse clicks to window manager' may be needed if your window manager has important functions on these buttons. Normally, clicking button-3 will display the filer's pinboard menu, and button-1 dragging allows you to select multiple icons.
ROX-Filer uses the standard XDND protocol for drag-and-drop. This protocol recommends that URIs should contain the hostname of the computer that the resource is on so that the program receiving the data can determine whether it can get the data directly or whether it must go via the X-server. However, many older programs (particularly GNOME applications) get confused by the hostname and fail to load the data correctly. If `Don't use hostnames' is on then the hostname part is omitted and ROX-Filer will work with these applications BUT you can't drag data to a program running on a different machine.
Table of Contents
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
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
from the 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 `image/<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).
This box appears when you choose
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 Choices 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 Choices directory for filetypes:
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 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:
feature (see theFind the Netscape application and go to
on the menu.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.
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'.
In both `MIME-types' and `MIME-icons' directories you can also provide default actions/images for each media type. For example, if `text_html' isn't found then the filer will try simply using `text'.
The filer works out the type for a file from its name. The rules come from various `globs' files — see [SharedMIME] for details.
Table of Contents
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:
`AppRun' 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 `AppRun').
`Help' is the directory to be opened when you choose
from the File menu.`AppInfo.xml' contains extra information about an application (see below).
`AppIcon.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.
For security reasons, an application directory must have the same owner as the `AppRun' file inside.
`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="sp">Un manejador de archivos gráafico</Summary> <About xml:lang="en"> <Purpose>File manager</Purpose> <Version>1.3.3 (25-Jul-2002)</Version> <Authors>Thomas Leonard and others</Authors> <License>GNU General Public License</License> <Homepage>http://rox.sourceforge.net</Homepage> </About> <AppMenu> <Item option="-p=Default"> <Label>Enable pinboard</Label> <Label xml:lang="hu">Pinboard engedélyezése</Label> <Label xml:lang="sp">Habilitar el pinboard</Label> </Item> <Item option="-p="> <Label>Disable pinboard</Label> <Label xml:lang="hu">Pinboard tiltása</Label> <Label xml:lang="sp">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, `AppRun' is called with option as its only argument. You can nest AppMenus inside other AppMenus.
Table of Contents
ROX-Filer is able to translate many of its messages, provided suitable translation files are provided:
Open the Options box from the menu,
Select a language from the menu at the top,
Click on
and restart the filer for the new setting to take full effect.
Go into the `src' directory and create the file `messages.pot':
$ cd ROX-Filer/src $ make messages.pot
Copy the file into the `po' subdirectory under `src' as `<name>.po'. Eg, if your language is referred to as `ml' (`my language'):
$ cp messages.pot po/ml.po
Load the copy into a text editor.
Fill in the translations, which are all blank to start with.
Run the `make-mo' script to create the binary file which ROX-Filer can use. You will need the GNU gettext package for this. If you don't have it then just send me the `.po' file and I'll convert it for you.
$ cd ROX-Filer/src/po $ ./make-mo ml Created file ../../Messages/ml.gmo OK
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).
Submit the `.po' file to me so that I can include it in future releases of the filer.
Go into the directory containing the `.po' files and run the `update-po' script. This checks the source code for new and changed strings and updates all the translation files.
$ cd ROX-Filer/src/po $ ./update-po
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.
Run make-mo as before.
Submit the updated file to me.
See the gettext info page for more instructions on creating a translation.
Table of Contents
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!
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.
Here's a quick explanation of the autoconf system in case you haven't used it before. See info autoconf for full details.
There's a file called `configure.in' which contains various tests (info autoconf). You run autoconf and it reads through the file and generates a shell script to perform the tests, saving it as `configure'. `configure' is normally distributed with the program because not everyone has autoconf.
You then run `configure' (in fact, let the `AppRun' script do it because it passes it some arguments), which performs all the tests. It reads in `Makefile.in' and `config.h.in' and fills in the missing values with the test results to produce `Makefile' and `config.h'.
You run make, which creates `.o' files from the `.c' files and links to produce `ROX-Filer'.
The `global.h' file lists each major data-structure used in the filer and explains its purpose. This is a good place to start reading if you want to know how the filer works.
In summary, each window has its own FilerWindow structure. This structure has pointers to a Collection (which is the widget which actually displays the files) and to a Directory, which is used to cache the directory contents.
Both Collection and Directory have pointers to (the same) DirItems, each of which corresponds to one filesystem object.
Several FilerWindows may share the same Directory.
While scanning is in progress the Directory keeps a list of the new items it has found (new_items) and the items which have changed in some way (up_items). It periodically notifies the filer window of the changes-so-far by calling all the functions in the users list (use attach() and detach() to add and remove functions to or from the list).
Table of Contents
ROX-Filer — a simple graphical file manager
rox [OPTION...] [FILE...]
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.
open PANEL as a bottom-edge panel.
used for session management.
open DIR as directory (not as an application, even if it looks like one).
close DIR and all its subdirectories.
display help about the various options.
open PANEL as a left-edge panel.
print MIME type of FILE and exit.
start a new filer, even if one already seems to be running. This also prevents the filer from forking (running in the background), which is useful for debugging.
override window manager control of panels.
use pinboard PIN as the pinboard.
open PANEL as a right-edge panel.
read and invoke SOAP RPC from standard input (see Appendix B).
open a directory showing FILE.
open PANEL as a top-edge panel.
show user name in each window.
display the version information and exit.
FILE has changed; re-examine it.
The main documentation for ROX-Filer is available by choosing
from the popup menu, or by clicking on the right-most toolbar icon.Copyright (C) 2002 Thomas Leonard.
You may redistribute copies of ROX-Filer under the terms of the GNU General Public License.
Report bugs to <tal197@users.sourceforge.net>.
ROX-Filer was created by Thomas Leonard, with help from:
Michael Adams | Olivier Fourdan | Brendan McCarthy |
Christopher Arndt | Eric Gillespie | Andras Mohari |
Jens Askengren | Thierry Godefroy | Christiansen Merel |
Liav Asseraf | Olli Helenius | Jimmy Olgeni |
Wilbert Berendsen | Alex Holden | Daniele Peri |
Francesco Bochicchio | Jasper Huijsmans | Andy Piper |
Andrzej Borsuk | Bernard Jungen | Marcelo Ramos |
Richard Boulton | Marcin Juszkiewicz | Michel Alexandre Salim |
Simon Britnell | James Kermode | Chris Sawer |
Arnaud Calvo | Jim Knoble | Christian Storgaard |
Babyfai Cheung | Krzysztof Krzyzaniak | Taras |
Andrew Clover | Aaron Kurtz | Simon Truss |
Fabien Coutant | Vincent Ledda | Jan Wagemakers |
Couderc Damien | Vincent Lefevre | Stephen Watson |
Andreas Dehmel | Victor Liu See-le | Andre Wyrwa |
Micah Dowty | Krzysztof Luks | Geoff Youngs |
Dmitry Elfimov | Anders Lundmark | Diego Zamboni |
Mattias Engdegard | Jose Romildo Malaquias | |
Andrew Flegg | Denis Manente |
and many others; the `Changes' file contains more detailed information!
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 <?xml version="1.0"?> <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]) Open a window showing directory Filename. Style is one of Large, Small or Huge. Details is one of None, Summary, Size, Type, Times or Permissions. Sort is one of Name, Type, Date or Size. 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.
Panel(Side, [Name]) Open the panel named Name on screen side Side (Top|Bottom|Left|Right). Name can be a name in Choices (eg, MyPanel) or a full pathname. If not given, the panel on that side is turned off.
PanelAdd(Side, Path, [Label, After]) 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.
Pinboard([Name]) Display pinboard Name on the desktop background. Name can be a name in Choices (eg, MyPinboard) or a full pathname. If not given, the pinboard is turned off.
PinboardAdd(Path, X, Y, [Label]) Add Path to the pinboard at position (X, Y), giving it the label Label.
SetBackdropApp(App) Make App (an application directory) the new handler for the current pinboard's backdrop. The `AppInfo.xml' file inside App must contain the CanSetBackdrop element, eg:
<?xml version="1.0"?> <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.
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).
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.
[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/
[Choices] The ROX Choices system, http://rox.sourceforge.net/choices.php3
[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/~pearl/thumbnail-spec/
[SharedMIME] Shared MIME-info Database (Version 0.8) http://www.freedesktop.org/standards/shared-mime-info.html