1 #LyX 1.1 created this file. For more info see http://www.lyx.org/
5 \def \Tab {\thinspace$\langle\hbox{Tab}\rangle$\thinspace}
11 \paperfontsize default
14 \paperpackage widemarginsa4
17 \paperorientation portrait
20 \paragraph_separation indent
22 \quotes_language english
26 \paperpagestyle default
38 large{<http://rox.sourceforge.net>}
43 tal197@users.sourceforge.net
53 ROX-Filer is a graphical file manger for the X Window System.
54 Its user interface is based on the RISC OS filer and it supports similar
55 features such as application directories and drag-and-drop loading and
57 The filer can also act as a pinboard, allowing you to pin frequently used
58 files onto the desktop background.
62 \begin_inset LatexCommand \tableofcontents{}
72 ROX-Filer is a simple and easy to use graphical file manager for X11, the
73 windowing system used on Unix and Unix-like operating systems.
74 It is also the core component of the ROX Desktop
75 \begin_inset LatexCommand \cite{ROX}
85 XDND A common drag-and-drop protocol used, for example, by the GNOME desktop
86 \begin_inset LatexCommand \cite{GNOME}
91 This allows data to be loaded into an application by dragging it from a
92 filer window to a program.
93 The full specification is given in
94 \begin_inset LatexCommand \cite{DND}
101 XDS An extension to XDND that allows applications to save data by dragging
102 an icon back to a filer window.
103 The full specification is given in
104 \begin_inset LatexCommand \cite{XDS}
112 Choices A simple, but flexible, system for managing user choices.
114 \begin_inset LatexCommand \cite{Choices}
121 Application\SpecialChar ~
122 directories Self contained relocatable applications, where installati
123 on is as simple as copying it to where you want it and uninstalling it is
124 just a matter of deleting a directory.
125 Described later in this documentation.
131 This program is free software; you can redistribute it and/or modify it
132 under the terms of the GNU General Public License as published by the Free
133 Software Foundation; either version 2 of the License, or (at your option)
137 This program is distributed in the hope that it will be useful, but WITHOUT
138 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
139 FOR A PARTICULAR PURPOSE.
140 See the GNU General Public License for more details.
143 You should have received a copy of the GNU General Public License along
144 with this program; if not, write to the Free Software Foundation, Inc.,
145 59 Temple Place, Suite 330, Boston, MA, 02111-1307, USA.
154 ROX-Filer is usually supplied in source-only form.
155 To compile and run it, you will require
158 Unix or Linux (root access is not required),
161 The X Window system (supplied as standard on all modern systems),
164 GTK+ 1.2.0 or later (libraries and headers) --- get the latest version from
166 \begin_inset LatexCommand \cite{GTK+}
173 A C compiler (standard on most systems).
176 All of the above are standard on most modern Linux distributions.
177 To check which version of GTK+ you have installed, run the
185 is the shell prompt):
188 $ gtk-config --version
197 Change to the directory containing the ROX-Filer subdirectory.
200 Run the AppRun script with the
208 $ ROX-Filer/AppRun --compile
212 ROX-Filer will perform various checks to find out what kind of system it
213 is being run on and will then compile.
214 If it doesn't work then please e-mail me and complain! Tell me what kind
215 of system you have and what errors were reported.
216 If you manage to fix the problem yourself then please e-mail me the fix.
220 The executables files are stored inside the ROX-Filer directory in a different
221 subdirectory for each platform.
222 Therefore, you can compile the same application on several different types
223 of machine and then run it from any of them using the AppRun script.
224 This is particularly useful in a network environment.
228 The filer needs some shared files to work --- icons for the various file
229 types, rules for determining file types and default run actions.
230 These are installed, along with the filer itself, by the '
234 ' script supplied with the filer.
242 [ enter root password ]
248 If you don't have the root password then don't worry --- skip the '
252 ' step and follow the instructions for installing into your home directory.
257 You can now run the filer by running the AppRun script without any options,
264 A window should appear and display the contents of the current directory.
265 If you opted to install the `rox' script then you can simply do this instead:
271 If you installed the script into your home directory then you may need to
272 set your PATH environment variable so that the shell can find it.
273 For example, if you installed it into a directory called `
277 ' in your home directory, use this:
280 $ PATH=${HOME}/bin:${PATH}; export PATH
283 or (if you are using the
290 $ setenv PATH ${HOME}/bin:${PATH}
299 By default, ROX-Filer will start by displaying the current directory.
300 You can get it to display other directories instead by listing them after
304 $ rox /home /usr /usr/local
307 You can also use it to open files, like this:
313 The filer supports various options, use `
318 All options have long and short forms (eg `
326 ') --- although on some systems you can only use the short versions.
329 Note that if the same version of the filer is already running on this machine
330 then, by default, it will be used to open the directories and the new copy
331 will exit immediately.
332 You can override this (perhaps because the old copy has stopped responding
333 for some reason) using the `
338 \layout Subsubsection
341 \begin_inset LatexCommand \label{run_pin}
348 If you want the filer to manage your desktop background then you use the
353 option and supply a name for the pinboard, eg:
356 $ rox --pinboard=MyPinboard
359 The pinboard configuration is saved in `
361 <Choices>/ROX-Filer/pb_MyPinboard
363 ' as soon as you change it in some way (for example, by dropping a file
364 onto the background).
365 You can have as many pinboards as you like and switch between them by running
369 $ rox --pinboard=MyOtherPinboard
372 To turn off the pinboard again, set the name to an empty string:
379 \begin_inset LatexCommand \ref{winman}
383 if you have trouble getting the icons to display correctly.
384 \layout Subsubsection
389 If you want a directory to be opened as a panel, put
397 before the directory (for `bottom' or `top' panels).
398 If you don't know what a panel is, try it and see!
404 $ ln -s $HOME ~/Panel/Home
410 The panel should be displayed in a window without a title bar.
411 If this does not work then see section
412 \begin_inset LatexCommand \ref{winman}
417 \layout Subsubsection
420 \begin_inset LatexCommand \label{winman}
427 You may have to play around with your window manager a bit to get the pinboard
428 icons and panels to display correctly (eg, without borders and underneath
430 In particular, try setting the stacking level / depth to low (or a negative
432 Make sure any 'Keep transients above other windows' type options are turned
436 If order for the filer to receive mouse clicks on the background (used for
437 the pinboard support) you need a GNOME-compliant window manager.
438 To see if your window manager supports this, try clicking the right mouse
439 button on an unused area of the background.
440 If you get the pinboard menu, all is well.
443 Note for sawfish users: sawfish trys to guess whether you are using GNOME
444 at start-up and only provides support if so.
445 You need to add the line `
453 file (see the sawfish manual for more details).
456 If all else fails, try running rox with the `
460 ' options; this overrides window manager control of the icons altogether.
463 Mouse button and key bindings
470 \begin_float footnote
473 This documentation assumes that button--1 is the left button, button--2
474 is the middle button and button--3 is the right button.
475 This is not always the case --- for example, in a left-handed setup.
477 mouse button to open files and directories.
480 Click the right button to get a menu.
481 Click over a file to perform an action on that file.
484 Drag files between windows to copy (left button) or move (middle button)
494 By default, the mouse button bindings are designed to fit in with X conventions.
495 However, the behaviour is highly configurable --- have a play in the Options
496 window if you don't like the normal settings.
497 The normal settings behave as follows:
575 Open the file or directory clicked on.
579 Hold down Ctrl to select things instead of opening them.
583 Hold down Shift to look inside applications, treat files as text, follow
584 symlinks or mount devices.
588 Same as left click, but open a directory in a new window or close the viewer
594 Hold down Ctrl while clicking to go directly to the Selection submenu.
598 Copy the file(s) to the destination (an application or another filer window).
602 Hold down Shift to move the file, or Ctrl+Shift to create a symbolic link.
606 As above, but always moves rather than copying or symlinking.
608 (middle mouse button)
612 Drag (not over an item)
614 Select a group of items by dragging a box around them.
615 With the left mouse button, only the files
619 in the box will be selected.
620 If you hold down Ctrl then the boxed items are added to the selection.
624 If the other mouse button is used then the boxed items are toggled between
625 selected and unselected.
629 Change to viewing the parent directory.
633 Move the cursor around.
637 Move up and down in steps of ten rows at a time.
641 Move to the first/last entry in the directory.
645 Open the item under the cursor.
646 With Shift held down this acts like choosing 'Shift Open' from the menu.
650 Toggles the item under the cursor between being selected and unselected.
661 Other keys can easily be defined by opening the menu, moving the pointer
662 over the item you want to use and pressing a key.
663 The key will appear in the menu and can be used from then on.
664 Key bindings are automatically saved when the filer quits.
670 While items are selected in a ROX-Filer window the filer has the global
672 You can then paste into another window to get the pathnames of the selected
674 For example, to extract the files from a .tgz archive on a floppy disk into
678 Choose `Xterm here' from the menu in your home directory.
681 Type `tar xzf ' (but don't press Return)
684 Ctrl-click on the .tgz file to select it.
687 Click the middle button in the xterm window to paste the name of the file
691 Press Return in the xterm to execute the command.
695 \begin_inset LatexCommand \label{sec: Toolbar}
702 By default, each window has a toolbar along the top.
703 You can disable this (or make it larger) from the Options window.
704 The four buttons on the toolbar are:
706 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
741 Change to parent directory
743 Show parent in a new window
747 Change to home directory
749 Show home in a new window
753 Reread the directory contents
759 Show ROX-Filer's help files
770 If the toolbar is in Normal mode (ie, not GNOME mode) then you may also
771 use either of the other buttons to perform the `Other action'.
772 If the 'New window on button 1' option is turned on then the `Action' and
773 `Other action' of the first two are swapped.
779 You can open a menu by right clicking
780 \begin_float footnote
783 If the Use `RISC OS mouse bindings' option is on then use the middle button
786 over a panel or filer window.
787 Here is a full description of each choice and what it does:
789 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
819 Select every item in this window.
823 Unselect every item in this window.
831 Create a new directory in this one.
835 Open an xterm with its current directory set to this directory.
836 \layout Subsubsection
840 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
897 Each object in the directory is shown as a large icon with its name below.
901 Items are drawn smaller that usual, allowing you to see more files at once.
911 Entries are displayed along with some extra details:
919 shows the file permissions, owner, group, size and modification time.
927 shows just the size of each file (not directories).
935 displays a bar indicating the size of each file.
936 This is on a log scale.
940 As above, but with a smaller icon and all on one line.
944 Items are arranged by name.
945 There is an option to make this case-sensitive.
949 Items are grouped by their types and then sorted by name within the groups.
953 Most recently modified first.
961 If on, files beginning with a dot are shown, otherwise they are hidden.
965 Rereads the contents of the directory and details of all the files in it.
969 Use this if the display becomes out-of-date.
982 If ROX-Filer was unable to find ImLib
983 \begin_inset LatexCommand \cite{ImLib}
987 when it was compiled then the icons are shown cropped rather than scaled.
988 Get ImLib and recompile if you want it to look nice.
989 \layout Subsubsection
992 \begin_inset LatexCommand \label{sec: Permissions}
999 The permissions display, shown in Full Info mode, is made up of four groups
1001 Each flag is displayed as a letter if it is on and a dash (--) if not.
1002 The first three characters show the permissions for the owner of the file,
1003 the second for other members of the file's group and the third for everyone
1005 Whichever group applies to the ROX-Filer process itself is shown underlined.
1006 The fourth group shows any special flags.
1009 The meanings of the characters are:
1012 r Permission to read the contents of a file, or the names of files in a
1016 w Permission to alter the contents of a file, or change which names appear
1020 x Permission to run the file as a program, or refer to the files listed
1021 within the directory.
1024 U This program executes with the
1028 of its owner rather than the person who ran it.
1031 G This program executes with the
1035 of its group, regardless of who ran it.
1038 T Entries in this directory can only be altered or removed by the people
1039 who own the files even if they have write permission on the directory itself.
1049 ' means that the owner of the file is the same as the effective user of
1050 ROX-Filer (basically, you own the file), you and members of the file's
1051 group have read, write and execute permission and other people have only
1052 read and execute permission.
1053 There are no special flags set.
1056 The rules which determine which permissions apply may vary slightly between
1057 operating systems, but a rough guide is:
1064 of the process is equal to the file's owner, then the owner permissions
1072 of the process is equal to the file's group OR the file's group is one
1077 then the group permissions apply.
1080 Otherwise, the `other' permissions apply.
1089 have no effect (except that a process may set its real IDs to its effective
1091 \layout Subsubsection
1096 All of these work in the same way --- if you open the menu with some items
1097 selected then the operation applies to those items.
1098 If you open then menu over an item while there is no selection then that
1099 item is temporarily selected.
1100 If you choose one of these while there is no selection at all then the
1101 window goes into `target mode'; the operation happens to the next item
1103 Click on the window background, press Escape, or click with the right mouse
1104 button to cancel target mode.
1105 Target mode is mainly useful with the `Single click navigation' option
1106 and keys bound to the various menu entries.
1108 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
1110 19 2 0 0 -1 -1 -1 -1
1177 Make a copy of this object.
1181 Change the name used for this object, or move it between directories.
1185 Create a symbolic link to this name in the same directory.
1189 Opens applications as directories, files as text/plain, mount points
1193 by mounting or unmounting them and symlinks by opening the directory
1197 containing the thing they point to.
1201 This is the same effect as clicking with Shift held down.
1205 Explain what kind of thing is selected.
1206 For applications, display the help files.
1210 Display extra information about this object.
1214 Open the file as if it was a directory --- see section
1215 \begin_inset LatexCommand \ref{sec: vfs}
1223 Mount or unmount each mount point selected.
1227 Remove all the selected entries from the directory.
1231 Subdirectories will have their contents deleted first.
1235 Deleting symlinks only removes the link, not the thing it points to.
1239 Count the sizes of all the selected items.
1240 Directories also have their
1245 Symlinks count themselves, not the things they point to.
1249 Allows you to change the permissions for the selected files.
1253 Search for files by specifying various conditions --- see section
1254 \begin_inset LatexCommand \ref{sec: Searching}
1259 \layout Subsubsection
1263 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
1265 11 2 0 0 -1 -1 -1 -1
1308 Open a new window displaying this window's parent.
1312 As above, but reuse this window.
1316 Open another window onto this directory.
1324 Open the path-entry box (see section
1325 \begin_inset LatexCommand \ref{sec: mini}
1333 Open the shell command box (see section
1334 \begin_inset LatexCommand \ref{sec: mini}
1342 Allows you to set the program to use when double-clicking on a file.
1347 \begin_inset LatexCommand \ref{sec: RunAction}
1355 Select just those files that match the given pattern --- see section
1356 \begin_inset LatexCommand \ref{sec: SelectIf}
1364 Same as selecting ROX-Filer and choosing `Help' from the menu.
1365 \layout Subsubsection
1370 This is just a cut-down version of the window menu.
1371 The only new entry is `Open Panel as Directory', which displays the panel
1372 in a new, non-panel, window.
1373 `Remove Item' is a cut-down version of `Delete'; it only works for symbolic
1374 links and never asks for confirmation.
1375 Since dragging applications and directories to the panel creates symlinks
1376 it is very easy to change the panel contents to suit your needs.
1383 \begin_inset LatexCommand \ref{run_pin}
1387 explains how to turn the pinboard on.
1388 Once on, you may drop icons from filer windows onto the pinboard to pin
1390 Clicking on a pinned file acts just like clicking on it in a filer window.
1391 You can drag pinned icons just like normal icons and you can right-click
1392 on one to see the pinboard's popup menu.
1395 Drag pinned icons with the middle mouse button to move them around (they
1397 Changes to the pinboard are automatically saved.
1400 Clicking on pinned icons with Control held down selects and unselects them.
1401 Click on the desktop background to unselect them all.
1408 Pinning a file to the pinboard does
1412 copy it, it merely creates a shortcut to the original file.
1413 If you delete the file, then you've lost it! Removing a file from the pinboard
1414 only removes the link.
1415 This is different to most other filers...
1419 \begin_inset LatexCommand \label{sec: vfs}
1423 Virtual file systems
1426 Some types of file can be represented as a directory.
1427 A typical example is a zip file, which contains an entire directory structure
1429 It is often useful to be able to open up such a file as if it was a real
1430 directory, and the VFS system allows you to do this.
1433 To use this feature you must have one or both of the following:
1436 A system (such as PODFUK
1437 \begin_inset LatexCommand \cite{PODFUK}
1441 ) which causes the kernel to support various Virtual File Systems directly.
1442 This is the best option since all programs will be able to access the contents
1444 You will require root access to install such a system, however, and it
1445 is not available on all platforms.
1448 Support for the Midnight Commander VFS library compiled into ROX-Filer.
1449 This happens automatically when you compile ROX-Filer if it can find the
1450 VFS library --- this means having
1458 ) in a system library directory or in the directory in the environment variable
1464 In this case, you will be able to view the directory structure and copy
1465 files out of it, but not change it.
1466 Support for this may be added later.
1467 Midnight Commander is part of the GNOME project.
1470 Note that using the `Open VFS' menu is simply a short-cut for using the
1471 path-entry box (explained below), so if you want to use a VFS not listed
1472 on the menu you can type in the path directly, eg:
1477 /home/fred/archive.zip#uzip/
1486 Don't forget the final slash!
1487 \layout Subsubsection
1489 Step by step example of adding VFS support
1492 This assumes that you have the Midnight Commander source in a directory
1494 You might need to replace
1517 If you have the root password then install the library in a system library
1518 directory as normal.
1528 $ cp libvfs.so ~/lib
1531 $ cd ~/Apps/ROX-Filer
1538 file to include this as the
1545 LD_LIBRARY_PATH=${HOME}/lib; export LD_LIBRARY_PATH
1548 This will ensure that ROX-Filer will look for the library in the new
1556 $ ./AppRun --compile
1562 checking for mc_stat in -lvfs...
1566 If you saw that line then it's worked! Well done!
1571 \begin_inset LatexCommand \label{sec: mini}
1578 The mini-buffer is a white bar that appears along the bottom of the window
1579 and allows you to enter some text.
1580 Press Escape to get rid of it again.
1581 It behaves in different ways depending on how you invoked it:
1582 \layout Subsubsection
1587 This allows you to type in a path directly.
1588 As you type the display is updated to show the item entered visually.
1589 The main use is to find a file in a large directory quickly, but you can
1590 also use it for navigating between directories, or for selecting a full
1591 pathname from somewhere else and pasting it directly into the path-entry
1594 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
1618 Open the currently selected item.
1622 Shell-style tab completion.
1626 Select the previous/next matching entry.
1629 If you start entering a name beginning with a `.' then the `Show Hidden'
1630 feature is temporarily turned on so that the file can be shown.
1633 Tab completion tries to fill in as many characters for you as it can.
1634 For example, if there are two files in a directory called `save-mail-nov-1999'
1635 and `save-mail-dec-1999' then typing 'save' and pressing Tab will expand
1636 `save' to `save-mail-' and beep to indicate that the match is not complete.
1637 If you use tab completion on a directory and it is unique then the filer
1638 will automatically change into the directory.
1639 This behavior should be familiar to shell users.
1640 \layout Subsubsection*
1645 Let's say you want to locate the documentation for Wine in the directory
1646 /usr/doc (which is usually very large).
1647 Here's how you could do it:
1650 Open the minibuffer by choosing 'Enter Path' from the Window menu.
1651 I usually bind this function to the slash (`/') key.
1654 Press CTRL-U to delete the existing contents --- this moves you to the root
1677 As you type, the cursor will move to the correct subdirectory.
1678 If it beeps when you press Tab then you need to supply more letters.
1679 \layout Subsubsection
1682 \begin_inset LatexCommand \label{sec: RunAction}
1689 This box appears when you choose `Set Run Action' from the Window menu.
1690 You can now either drag a file onto an application, or you can enter a
1692 In either case, the action is not actually performed but instead becomes
1693 the default action for files of that type.
1696 All files have a MIME type in the form `
1718 Whichever method you use to set the action you will be given the choice
1719 of setting the run action just for that type, or setting the default for
1720 all files with that media-type which don't already have a specific action.
1723 For example, let's say you want to set things up so that double-clicking
1724 on a `.gif' file loads it into the Gimp:
1727 Setting the run action by drag-and-drop
1732 Choose `Set Run Action' from the Window menu and, while the minibuffer is
1733 still open, drag a GIF file from the filer window onto the Gimp's application
1734 directory (probably in another filer window).
1737 Setting the run action by entering a shell command
1746 \begin_inset Quotes erd
1750 \begin_inset Quotes erd
1757 Note that the cursor (the black box) must be on the GIF file when you press
1759 \layout Subsubsection
1761 The shell command box
1764 This provides a quick way of entering shell commands if you don't want to
1766 If you don't know what shell commands are, skip this section!
1769 Just type in the command and press Return to execute it.
1770 Up and Down arrows move through previously entered commands.
1771 Tab does shell-style completion.
1772 Clicking on an item inserts its name into the minibuffer.
1773 If some items are selected then they are assigned to the positional parameters
1783 \layout Subsubsection*
1795 Open the minibuffer by choosing `Shell Command' from the Window menu.
1796 I usually bind this to the bang (`!') key.
1803 ' and click on the file.
1804 The leading space is automatically inserted.
1807 Press Return to execute it.
1810 To print all the selected files:
1813 Open the shell command minibuffer.
1821 \layout Subsubsection*
1826 Be careful; you will not be asked to confirm! If in doubt, start the command
1831 ' so that it will be displayed rather than executed.
1834 The above command won't work if some of the files contain spaces --- use
1846 ' instead to be safe.
1849 `sh' is always used as the name of the shell to run (mainly because bash
1850 and csh treat positional parameters differently).
1851 However, PATH is searched to find it so you can still use another shell
1852 if you want by naming it sh and putting it in your path.
1855 Commands execute in the background, so you can say:
1859 sleep 240; xmessage Time to go!
1861 \layout Subsubsection
1864 \begin_inset LatexCommand \label{sec: SelectIf}
1868 The conditional selection box
1871 Use this if you want to automatically select all files in the directory
1872 which match a condition.
1873 The syntax for the conditions is given in section
1874 \begin_inset LatexCommand \ref{sec: Searching}
1879 For example, to select all files larger than 5Mb:
1882 Open the Select If minibuffer.
1892 Just those files over 5 Mb in size will be selected.
1893 The expressions you can enter are in the same form as described in section
1895 \begin_inset LatexCommand \ref{sec: Searching}
1903 ' has no effect since the contents of directories are never checked anyway.
1909 Action windows are those boxes that appear while you're doing a Copy/Move/Link/e
1911 The status line at the top of the window shows the current directory or
1912 object that the window is processing.
1913 The scrolling area below is the log area --- it shows what has been done
1914 and may display questions here.
1917 At the bottom are four buttons and, sometimes, some options.
1918 The buttons work as follows:
1921 Quiet will do simple operations without asking you to confirm each one.
1922 By turning this on and off during an operation you can use it like a pause
1926 Yes answers yes to the question displayed in the log area.
1929 No answers no to the question displayed in the log area.
1932 Abort kills the current operation (if any) and closes the action window.
1935 You can control which actions get started automatically (without you having
1936 to click on Quiet at the start) from the Options window.
1937 \layout Subsubsection
1939 Action window options
1942 Some actions have options, which appear as option boxes at the bottom of
1947 `Force' means that the filer won't treat non-writeable files as special.
1948 Normally, it confirms the deletion even if Quiet is pressed.
1949 Note that you still can't remove files from non-writeable directories because
1950 in that case you really don't have permission.
1953 `Brief' prevents the filer logging a message every time it does something.
1954 Use this to speed things up if large numbers of messages are being logged.
1957 `Recurse' means that doing something to a directory will also do the same
1958 thing to all its contents, and the contents of any subdirectories, and
1963 \begin_inset LatexCommand \label{sec: Searching}
1970 The Find feature looks through all the selected files and directories and
1971 any subdirectories (recursively) looking for items that match a particular
1975 If you know the name of a file then just enter it in the `Expression:' box,
1976 enclosed in single quotes.
1977 For example, to find a file called `log' you would enter:
1983 Remember to use normal quotes, not double quotes (
1986 \begin_inset Quotes eld
1998 As the filer finds matching files they are added to the results list.
1999 Clicking on an entry in the list opens a viewer showing the file you clicked
2001 The filer will use the same window to view other results (so, if you want
2002 the results shown in separate windows you must explicitly create a new
2003 window from the Window menu).
2004 \layout Subsubsection
2009 You can also put shell-style wildcard characters inside the quotes, for
2029 manpage if you want to know more about shell wildcards.
2032 If the pattern you enter contains a slash ('/') character then the pattern
2033 is matched against the file's full path, otherwise only the leafname is
2039 will find 'tmp' and 'tmpfile' but not '/tmp/file' ---
2043 will find all three.
2044 \layout Subsubsection
2049 As well as finding files by their names you can also find them by various
2051 Note that `file' is used here to mean anything that can appear in the filesyste
2052 m --- including directories, devices and so on.
2063 These look at the type of the item being checked:
2066 IsReg matches any regular (ie, normal) file.
2069 IsLink matches symlinks.
2072 IsDir matches directories.
2075 IsChar matches character device files.
2078 IsBlock matches block device files.
2081 IsDev matches block or character device files.
2084 IsPipe matches pipes.
2087 IsSocket matches sockets.
2090 These look at the permissions set on the file --- see section
2091 \begin_inset LatexCommand \ref{sec: Permissions}
2098 IsSUID matches files which have the Set-UID bit set.
2101 IsSGID matches files which have the Set-GID bit set.
2104 IsSticky matches files with the sticky bit set,
2107 IsReadable matches files which you can read from.
2110 IsWriteable matches files which you can write to.
2113 IsExecutable matches files which you can execute.
2116 And a couple of other useful ones:
2119 IsEmpty finds empty files (ie, those whose length is 0 bytes).
2122 IsMine finds files which you own.
2123 \layout Subsubsection
2128 You can combine the above tests in various ways to perform more advanced
2130 An expression is actually made up of a list of
2134 , separated by commas.
2135 The filer will try to match each case in turn until one matches or there
2136 are no more cases left.
2137 For example, to search for files with several possible endings:
2140 '*.gif', '*.htm', '*.html'
2143 Further, each of the cases is actually a list of conditions.
2144 The case only matches if all of its conditions are met.
2145 So, to find a directory called
2149 or a regular file ending in
2156 IsDir 'lib', IsReg '*.so'
2159 You can negate a condition by putting a
2163 in front of it and you can use a sub-expression as a condition by bracketing
2173 Not isdir and not isreg
2176 All three do the same thing.
2177 \layout Subsubsection
2182 You can also compare various values using the operators
2186 (for less-than, less-than-or-equal-to, equal-to, not-equal-to, greater-than
2187 and greater-than-or-equal-to).
2188 When comparing times, you may find it helpful to use
2204 to make things clearer.
2207 The following are read from the file being checked and may be used for the
2208 values being compared:
2211 atime The time that the file was last accessed.
2214 ctime The time that the file's status was last changed.
2217 mtime The time that the file's contents were last modified.
2220 size The size of the file.
2223 inode The file's inode (index) number
2226 nlinks The number of links to this file (that is, the number of directory
2227 entries which refer to this file.
2228 Note that symlinks don't count as references).
2231 uid The User ID of the file.
2234 gid The Group ID of the file.
2237 blocks The number of disk blocks being used by the file.
2240 Times are measured as seconds since the Unix Epoch (00:00:00 UTC, January
2243 When specifying constants to compare these values with you may use various
2244 keywords to scale the value:
2247 Byte(s) has no effect, but looks better.
2250 Kb multiplies by 1024, so 2Kb is the same as 2048.
2254 \begin_inset Formula \( 1024^{2} \)
2260 Sec(s) has no effect, but looks nice.
2263 Min(s) multiplies by 60 to get minutes.
2266 Hour(s),\SpecialChar ~
2267 Day(s),\SpecialChar ~
2268 Week(s),\SpecialChar ~
2269 Year(s) likewise convert to the relevant unit.
2272 Ago makes the time in the past relative to when the check is done.
2275 Hence makes the time in the future.
2285 Some examples should make this all a bit clearer!
2288 mtime after 1 day ago
2294 IsReg and nlinks > 1
2297 The first finds files modified within the last 24 hours.
2306 but it's not so clear what is meant.
2307 The second finds files larger than 10 Mb and the last finds regular files
2308 with more than one directory entry.
2311 Be careful though --- the filer doesn't check the context of the modifiers,
2316 is allowed, although it doesn't make much sense! Also, forgetting to use
2325 will cause odd effects (the time will be measured relative to the Epoch
2326 rather than the current time).
2327 Finally, don't use = with times ---
2331 looks for a file accessed
2335 86400 seconds ago...
2336 \layout Subsubsection
2341 System(Command) executes `Command' on the file.
2342 The test succeeds if the command returns an exit status of zero.
2343 A `%' character in `Command' is replaced by the full path of the file being
2345 System is a very slow test to perform, so do it last if possible.
2346 For example, if you're looking for a .c file containing the word `main',
2351 '*.c' system(grep -q main
2366 so that the grep is only performed for files ending in .c (as opposed to
2367 only checking that the file ends in .c if it contains the word `main').
2372 \begin_float footnote
2375 Note that this is the opposite of the
2381 However, if it gets evaluated at all then it prevents the filer from checking
2382 inside the current directory.
2383 Remember the order in which the filer checks the expression!
2389 '*.old' system(echo rm %)
2395 The first displays a command to delete each file ending in
2399 ; you can either paste the results into an xterm to execute them or run
2400 the search again without the
2405 It's always a good idea to use
2409 first with dangerous commands! The second looks for
2413 files, but does not bother checking inside directories called
2418 The expression is evaluated like this:
2420 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center
2422 \begin_inset Figure size 216 180
2435 You can configure various aspects of ROX-Filer from the Options box.
2436 Choose `Options...' from a filer window menu to open it.
2440 At the bottom of the window are four buttons:
2443 Save puts all your choices into effect, and also saves them into your Choices
2444 directory for next time ROX-Filer is loaded.
2445 ROX-Filer will never save any preferences to disk unless you click on the
2446 `Save' button in the options window.
2447 Exactly where choices are loaded from and saved to is controlled by the
2452 environment variable --- see
2453 \begin_inset LatexCommand \cite{Choices}
2460 OK puts your choices into effect without writing anything to disk.
2463 Apply works like OK, but without closing the Options window.
2466 Cancel closes the options box and forgets any changes you made.
2467 \layout Subsubsection
2469 Action window options
2472 You can choose to start some operations automatically, without waiting for
2473 you to click on Quiet.
2474 Select each operation that you want to auto-start here.
2475 \layout Subsubsection
2477 Filer window options
2480 `Ignore case when sorting' treats upper and lower case letters as equivalent
2482 If this is off then `Zoo' comes before `animal', for example.
2485 `New window on button 1' swaps the actions of the two non-menu buttons when
2486 opening directories.
2487 This is provided for people who are used to the RISC OS mouse bindings.
2490 `Menu on button 2' swaps the actions of buttons 2 and 3 so that the middle
2491 button brings up the menus.
2492 This is provided for people who are used to the RISC OS mouse bindings.
2495 `Single-click navigation' treats a single click over an item as if it was
2497 This allows you to move around, run applications and open files without
2503 opening it you must hold down CTRL while you click.
2506 `Unique windows' prevents you from having two windows showing the same directory.
2507 Opening a second view onto a directory closes the first.
2510 `Toolbar type for new windows' allows you to choose what kind of toolbar
2511 will be used for future filer windows (the currently open windows are not
2513 None means that new windows will not have a toolbar, Normal provides a
2514 small bar of icons, and GNOME displays larger icons with textual labels
2515 and allows the bar to be detached from the window by dragging it.
2517 \begin_inset LatexCommand \ref{sec: Toolbar}
2524 The last display style and sort type you chose will also be saved as the
2525 defaults for next time.
2526 \layout Subsubsection
2528 Drag-And-Drop options
2531 ROX-Filer uses the standard XDND protocol for drag-and-drop.
2532 This protocol recommends that URIs should contain the hostname of the computer
2533 that the resource is on so that the program receiving the data can determine
2534 whether it can get the data directly or whether it must go via the X-server.
2535 However, many older programs (particularly GNOME applications) get confused
2536 by the hostname and fail to load the data correctly.
2537 If `Don't use hostnames' is on then the hostname part is omitted and ROX-Filer
2538 will work with these applications BUT you can't drag data to a program
2539 running on a different machine.
2542 `Allow dragging to icons in filer windows' controls what happens when you
2543 drop files onto icons in filer windows.
2544 If on then drops onto directories will save the data inside the directory
2545 while dropping onto programs will invoke the program on that data.
2546 If off then drops anywhere inside a filer window act like drops onto the
2547 window background --- that is, the data will be saved into the directory
2549 \layout Subsubsection
2554 The `Xterm here' program is the one used when you choose `Xterm here' from
2556 You can replace it with another program such as `gnome-terminal' if you
2558 In fact, any program will do, but note that you cannot pass any options
2559 to the program at present.
2565 ROX-Filer uses three sub-directories in your Choices directory for filetypes:
2568 MIME-info contains files which specify what the MIME type for a file should
2569 be, based on its extention.
2570 All the files in all the MIME-info directories are scanned when the filer
2572 ROX-Filer comes with many such rules --- these are installed into the MIME-info
2573 directory by the install script.
2577 Many applications now come with a file called `something.mime'; copy these
2578 files into your MIME-info directory to make ROX-Filer automatically recognise
2583 MIME-types contains symlinks, one for each MIME type, which point to programs
2584 that can handle files of that type.
2585 To set what program is run when you click on the file you should normally
2586 use the `Set Run Action' feature (see section
2587 \begin_inset LatexCommand \ref{sec: RunAction}
2592 However, you can also set the actions manually --- for example, to make
2593 opening an HTML file load it into Netscape:
2597 Find the Netscape application and go to `Link...' on the menu.
2600 Enter `text_html' as the name for the link and drag the icon from the Link
2601 box into the MIME-types directory.
2604 You can also put actual programs in here as well as links if you want to.
2608 MIME-icons contains the images used to display each type of file.
2609 So the filer will try to display an HTML file using the icon `MIME-icons/text_h
2613 In both MIME-types and MIME-icons directories you can also provide default
2614 actions/images for each media type.
2615 For example, if `text_html' isn't found then the filer will try simply
2619 Application directories
2622 An application directory is a directory which can be run as an application.
2623 It contains all the resources of an application --- source code, binaries,
2624 documentation and so on.
2625 Keeping everything in one place make installation and uninstallation much
2627 You can also keep multiple versions of a program by simply having several
2628 application directories.
2629 You may move and rename them as you please.
2630 Application directories are easier to use and install and are more secure
2632 \begin_float footnote
2635 Because you can compile an application as a user and then simply copy it
2636 as root rather than having to run an install script you are free from the
2637 danger of running untrusted code as root.
2638 All you have to watch out for is setuid binaries.
2643 To make a directory executable all you need to do is create a executable
2644 file called `AppRun' inside it.
2645 This file is run when the user double-clicks on the application.
2646 You should also provide `AppIcon.xpm' (which will be used as the image for
2647 the application) and `Help' (which is a directory that is opened when the
2648 user asks for help).
2649 Finally (for security reasons), an application directory must have the
2650 same owner as the AppRun file inside.
2651 Have a look at the ROX-Filer application directory for a full example.
2654 Internationalisation
2658 \begin_inset LatexCommand \label{sec: LANG}
2662 Selecting a translation
2665 ROX-Filer is able to translate many of its messages, provided suitable translati
2666 on files are provided.
2667 If you know that your language is supported then simply set the
2671 environment variable to the appropriate code for your country before starting
2675 LANG=fr; export LANG
2681 To see which translations are currently provided, open the ROX-Filer application
2682 directory (hold down Shift and double-click) and look inside the `
2689 Creating a new translation
2696 directory and create the file `
2711 Copy the file into the `
2715 ' subdirectory under
2720 \begin_inset Formula \( \langle \hbox {name}\rangle \hbox {\tt .po} \)
2724 Eg, if your language is referred to as `ml' (`my language'):
2728 $ cp messages.pot po/ml.po
2732 Load the copy into a text editor.
2735 Fill in the translations, which are all blank to start with.
2742 ' script to create the binary file which ROX-Filer can use.
2743 You will need the GNU gettext package for this.
2744 If you don't have it then just send me the
2748 file and I'll convert it for you.
2752 $ cd ROX-Filer/src/po
2758 Created file ../../Messages/ml.gmo OK
2762 Set the LANG variable to `
2766 ' and restart the filer (see section
2767 \begin_inset LatexCommand \ref{sec: LANG}
2778 file to me so that I can include it in future releases of the filer.
2781 Updating an existing translation
2784 Go into the directory containing the
2793 This checks the source code for new and changed strings and updates all
2794 the translation files.
2798 $ cd ROX-Filer/src/po
2805 Edit the file by hand as before, filling in the new blanks and updating
2806 out-of-date translations.
2807 Look out for `fuzzy' entries where
2811 has made a guess; check it's correct and remove the `fuzzy' line.
2821 Submit the updated file to me.
2828 info page for more instructions on creating a translation.
2834 This is a quick start guide for people who want to modify the source code.
2835 If you make useful changes or fix bugs, please send patches to me or to
2837 Tell me which version you're using!
2843 The first time you compile the program you need to do `
2847 ', but in future you only need to run `
2855 ' directory when you change the
2864 You might want to run `
2871 Creating and applying patches
2874 When people make small modifications to the sources they will often distribute
2879 --- usually on the mailing list.
2880 To apply a patch, go into the 'src' directory and run patch with the patch
2882 Then recompile, like this:
2891 $ ../AppRun --compile
2894 You can remove the patch by simply repeating the above sequence --- patch
2895 will detect that the patch is already applied and offer to remove it.
2898 To create a patch you should first get the latest version of the filer from
2899 CVS (instructions on using CVS can be found on the web-site).
2900 Modify the program as you please.
2901 Create the patch using `
2905 ' from the appropriate directory:
2908 $ cvs diff -c > my_patch
2911 This creates a human- and machine-readable patch file.
2912 Submit this to the mailing list.
2913 The are many reasons for posting patches rather that the modified files:
2916 They are smaller, and hence shouldn't bounce.
2917 They are also quicker to download for people with slow connections.
2920 People can see what they're getting into before applying them!
2923 Patches can (usually) be applied to slightly modified versions of the sources.
2924 This means that people can apply several patches without each new one overwriti
2931 Here's a quick explanation of the autoconf system in case you haven't used
2933 See `info autoconf' for full details.
2936 There's a file called 'configure.in' which contains various tests (`info
2938 You run `autoconf' and it reads through the file and generates a shell
2939 script to perform the tests, saving it as `configure'.
2940 `configure' is normally distributed with the program because not everyone
2944 You then run `configure' (in fact, let the `AppRun' script do it because
2945 it passes it some arguments), which performs all the tests.
2946 It reads in `Makefile.in' and `config.h.in' and fills in the missing values
2947 with the test results to produce `Makefile' and `config.h'.
2950 You run `make', which creates .o files from the .c files and links to produce
2957 The diagram below shows some of the major structures found in the filer
2958 along with their most important attributes and methods.
2959 Exactly which attributes have been included is a little hit-and-miss but
2960 it might help you get the overall picture.
2961 If you find it useful, please let me know and I'll try to keep it up-to-date
2962 (or even extend it!).
2965 To summarise, each window (or panel) has its own
2970 This structure has pointers to a
2974 (which is the widget which actually displays the files) and to a
2978 , which is used to cache the directory contents.
2987 have pointers to (the same)
2991 s, each of which corresponds to one filesystem object.
2996 s may share the same
3001 While scanning is in progress the
3005 keeps a list of the new items it has found (
3009 ) and the items which have changed in some way (
3014 It periodically notifies the filer window of the changes-so-far by calling
3015 all the functions in the
3027 to add and remove functions to or from the list).
3029 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center
3031 \begin_inset Figure size 595 606
3039 \layout Bibliography
3046 , <http://rox.sourceforge.net>
3047 \layout Bibliography
3054 , <http://www.gtk.org>
3055 \layout Bibliography
3062 , <http://www.gnome.org>
3063 \layout Bibliography
3068 The Drag and Drop protocol
3070 , <http://www.its.caltech.edu/~jafl/xdnd/>
3071 \layout Bibliography
3076 The X Direct Save protocol
3078 , <http://www.its.caltech.edu/~jafl/xds/>
3079 \layout Bibliography
3084 The ROX Choices system
3086 , <http://rox.sourceforge.net/choices.php3>
3087 \layout Bibliography
3088 \bibitem {enlightenment}
3094 <http://www.enlightenment.org>
3095 \layout Bibliography
3100 POrtable Dodgy Filesystems in Userland (hacK),
3102 <http://atrey.karlin.mff.cuni.cz/~pavel/podfuk/podfuk.html>
3103 \layout Bibliography
3110 , <http://www.gnome.org>