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
194 Due to bugs in earlier versions, GTK+ 1.2.8 is strongly recommended.
206 Change to the directory containing the ROX-Filer subdirectory.
209 Run the AppRun script with the
217 $ ROX-Filer/AppRun --compile
221 ROX-Filer will perform various checks to find out what kind of system it
222 is being run on and will then compile.
223 If it doesn't work then please e-mail me and complain! Tell me what kind
224 of system you have and what errors were reported.
225 If you manage to fix the problem yourself then please e-mail me the fix.
229 The executables files are stored inside the ROX-Filer directory in a different
230 subdirectory for each platform.
231 Therefore, you can compile the same application on several different types
232 of machine and then run it from any of them using the AppRun script.
233 This is particularly useful in a network environment.
237 The filer needs some shared files to work --- icons for the various file
238 types, rules for determining file types and default run actions.
239 These are installed, along with the filer itself, by the '
243 ' script supplied with the filer.
251 [ enter root password ]
257 If you don't have the root password then don't worry --- skip the '
261 ' step and follow the instructions for installing into your home directory.
266 You can now run the filer by running the AppRun script without any options,
273 A window should appear and display the contents of the current directory.
274 If you opted to install the `rox' script then you can simply do this instead:
280 If you installed the script into your home directory then you may need to
281 set your PATH environment variable so that the shell can find it.
282 For example, if you installed it into a directory called `
286 ' in your home directory, use this:
289 $ PATH=${HOME}/bin:${PATH}; export PATH
292 or (if you are using the
299 $ setenv PATH ${HOME}/bin:${PATH}
308 By default, ROX-Filer will start by displaying the current directory.
309 You can get it to display other directories instead by listing them after
313 $ rox /home /usr /usr/local
316 You can also use it to open files, like this:
322 The filer supports various options, use `
327 All options have long and short forms (eg `
335 ') --- although on some systems you can only use the short versions.
338 Note that if the same version of the filer is already running on this machine
339 then, by default, it will be used to open the directories and the new copy
340 will exit immediately.
341 You can override this (perhaps because the old copy has stopped responding
342 for some reason) using the `
347 \layout Subsubsection
350 \begin_inset LatexCommand \label{run_pin}
357 If you want the filer to manage your desktop background then you use the
362 option and supply a name for the pinboard, eg:
365 $ rox --pinboard=MyPinboard
368 The pinboard configuration is saved in `
370 <Choices>/ROX-Filer/pb_MyPinboard
372 ' as soon as you change it in some way (for example, by dropping a file
373 onto the background).
374 You can have as many pinboards as you like and switch between them by running
378 $ rox --pinboard=MyOtherPinboard
381 To turn off the pinboard again, set the name to an empty string:
388 \begin_inset LatexCommand \ref{winman}
392 if you have trouble getting the icons to display correctly.
393 \layout Subsubsection
396 \begin_inset LatexCommand \label{run_pan}
403 Panels work just like the pinboard.
404 You can create a panel on any side of the screen by using the options
420 , depending on which side of the screen the panel should appear on.
421 On some systems, the short (one letter) form of the options must be used.
422 For example, to create a panel along the bottom edge of the screen:
428 The panel should be displayed in a window without a title bar.
429 If this does not work then see section
430 \begin_inset LatexCommand \ref{winman}
435 You can drag files onto either side of the panel to add them.
436 Icons can be repositioned by dragging them with the middle mouse button.
437 Changes to the panel are automatically saved to '
439 <Choices>/ROX-Filer/pan_MyPanel
442 As with the pinboard, you can switch between panel configurations simply
443 by running rox again with a different panel name.
444 Specify a blank name to remove the panel.
447 $ rox --bottom=MyOtherPanel
451 \layout Subsubsection
454 \begin_inset LatexCommand \label{winman}
461 You may have to play around with your window manager a bit to get the pinboard
462 icons and panels to display correctly (eg, without borders and underneath
464 In particular, try setting the stacking level / depth to low (or a negative
466 Make sure any 'Keep transients above other windows' type options are turned
470 In order for the filer to receive mouse clicks on the background (used for
471 the pinboard support) you need a GNOME-compliant window manager.
472 To see if your window manager supports this, try clicking the right mouse
473 button on an unused area of the background.
474 If you get the pinboard menu, all is well.
477 Note for sawfish users: sawfish trys to guess whether you are using GNOME
478 at start-up and only provides support if so.
479 You need to add the line `
487 file (see the sawfish manual for more details).
490 If all else fails, try running rox with the `
494 ' options; this overrides window manager control of the icons altogether.
495 \layout Subsubsection
504 ' option to rox then the filer will display a message at the top of each
505 window saying which user the filer is running as.
506 This also disables the normal warning box you get when you try to run the
508 The idea here is that you create a simple script which runs the filer as
509 root --- something like:
518 Then, you can get a root filer window by simply running the script and entering
520 Remember, any file operations you perform and any programs you run from
521 these windows will run as root too! Be careful!
524 You may find that the X server won't allow root (or other users) to connect.
525 Reading the manual pages for `
533 ' may give you some hints, but it varies between systems (which is why this
534 isn't built in to the filer!).
537 Mouse button and key bindings
544 \begin_float footnote
547 This documentation assumes that button--1 is the left button, button--2
548 is the middle button and button--3 is the right button.
549 This is not always the case --- for example, in a left-handed setup.
551 mouse button to open files and directories.
554 Click the right button to get a menu.
555 Click over a file to perform an action on that file.
558 Drag files between windows to copy (left button) or move (middle button)
568 By default, the mouse button bindings are designed to fit in with X conventions.
569 However, the behaviour is highly configurable --- have a play in the Options
570 window if you don't like the normal settings.
571 The normal settings behave as follows:
652 Open the file or directory clicked on.
656 Hold down Ctrl to select things instead of opening them.
660 Hold down Shift to look inside applications, treat files as text, follow
661 symlinks or mount devices.
665 Same as left click, but open a directory in a new window or close the viewer
671 Hold down Ctrl while clicking to go directly to the Selection submenu.
675 Copy the file(s) to the destination (an application or another filer window).
679 Hold down Shift to move the file, or Ctrl+Shift to create a symbolic link.
683 As above, but always moves rather than copying or symlinking.
685 (middle mouse button)
689 Drag (not over an item)
691 Select a group of items by dragging a box around them.
692 With the left mouse button, only the files
696 in the box will be selected.
697 If you hold down Ctrl then the boxed items are added to the selection.
701 If the other mouse button is used then the boxed items are toggled between
702 selected and unselected.
706 Change to viewing the parent directory.
710 Move the cursor around.
714 Move up and down in steps of ten rows at a time.
718 Move to the first/last entry in the directory.
722 Open the item under the cursor.
723 With Shift held down this acts like choosing 'Shift Open' from the menu.
727 Toggles the item under the cursor between being selected and unselected.
731 Moves the cursor to the next/previous selected item.
742 Other keys can easily be defined by opening the menu, moving the pointer
743 over the item you want to use and pressing a key.
744 The key will appear in the menu and can be used from then on.
745 Key bindings are automatically saved when the filer quits.
751 While items are selected in a ROX-Filer window the filer has the global
753 You can then paste into another window to get the pathnames of the selected
755 For example, to extract the files from a .tgz archive on a floppy disk into
759 Choose `Xterm here' from the menu in your home directory.
762 Type `tar xzf ' (but don't press Return)
765 Ctrl-click on the .tgz file to select it.
768 Click the middle button in the xterm window to paste the name of the file
772 Press Return in the xterm to execute the command.
776 \begin_inset LatexCommand \label{sec: Toolbar}
783 By default, each window has a toolbar along the top.
784 You can disable this (or make it larger) from the Options window.
785 The four buttons on the toolbar are:
787 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
822 Change to parent directory
824 Show parent in a new window
828 Change to home directory
830 Show home in a new window
834 Reread the directory contents
840 Show ROX-Filer's help files
851 You may also use either of the other buttons to perform the `Other action'.
852 If the 'New window on button 1' option is turned on then the `Action' and
853 `Other action' of the first two are swapped.
856 Dragging files to the Up or Home icons acts just like dragging them into
857 the directory which the button leads to.
863 You can open a menu by right clicking
864 \begin_float footnote
867 If the Use `RISC OS mouse bindings' option is on then use the middle button
870 over a panel or filer window.
871 Here is a full description of each choice and what it does:
873 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
903 Select every item in this window.
907 Unselect every item in this window.
915 Create a new directory in this one.
919 Open an xterm with its current directory set to this directory.
920 \layout Subsubsection
924 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
981 Each object in the directory is shown as a large icon with its name below.
985 Items are drawn smaller than usual, allowing you to see more files at once.
995 Entries are displayed along with some extra details:
1003 shows the file permissions, owner, group, size and modification time.
1011 shows just the size of each file (not directories).
1019 displays a bar indicating the size of each file.
1020 This is on a log scale.
1024 As above, but with a smaller icon and all on one line.
1028 Items are arranged by name.
1029 There is an option to make this case-sensitive.
1033 Items are grouped by their types and then sorted by name within the groups.
1037 Most recently modified first.
1045 If on, files beginning with a dot are shown, otherwise they are hidden.
1049 Rereads the contents of the directory and details of all the files in it.
1053 Use this if the display becomes out-of-date.
1066 If ROX-Filer was unable to find ImLib
1067 \begin_inset LatexCommand \cite{ImLib}
1071 when it was compiled then the icons are shown cropped rather than scaled.
1072 Get ImLib and recompile if you want it to look nice.
1073 \layout Subsubsection
1076 \begin_inset LatexCommand \label{sec: Permissions}
1083 The permissions display, shown in Full Info mode, is made up of four groups
1085 Each flag is displayed as a letter if it is on and a dash (--) if not.
1086 The first three characters show the permissions for the owner of the file,
1087 the second for other members of the file's group and the third for everyone
1089 Whichever group applies to the ROX-Filer process itself is shown underlined.
1090 The fourth group shows any special flags.
1093 The meanings of the characters are:
1096 r Permission to read the contents of a file, or the names of files in a
1100 w Permission to alter the contents of a file, or change which names appear
1104 x Permission to run the file as a program, or refer to the files listed
1105 within the directory.
1108 U This program executes with the
1112 of its owner rather than the person who ran it.
1115 G This program executes with the
1119 of its group, regardless of who ran it.
1122 T Entries in this directory can only be altered or removed by the people
1123 who own the files even if they have write permission on the directory itself.
1133 ' means that the owner of the file is the same as the effective user of
1134 ROX-Filer (basically, you own the file), you and members of the file's
1135 group have read, write and execute permission and other people have only
1136 read and execute permission.
1137 There are no special flags set.
1140 The rules which determine which permissions apply may vary slightly between
1141 operating systems, but a rough guide is:
1148 of the process is equal to the file's owner, then the owner permissions
1156 of the process is equal to the file's group OR the file's group is one
1161 then the group permissions apply.
1164 Otherwise, the `other' permissions apply.
1173 have no effect (except that a process may set its real IDs to its effective
1175 \layout Subsubsection
1180 All of these work in the same way --- if you open the menu with some items
1181 selected then the operation applies to those items.
1182 If you open then menu over an item while there is no selection then that
1183 item is temporarily selected.
1184 If you choose one of these while there is no selection at all then the
1185 window goes into `target mode'; the operation happens to the next item
1187 Click on the window background, press Escape, or click with the right mouse
1188 button to cancel target mode.
1189 Target mode is mainly useful with the `Single click navigation' option
1190 and keys bound to the various menu entries.
1192 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
1194 21 2 0 0 -1 -1 -1 -1
1267 Make a copy of this object.
1271 Change the name used for this object, or move it between directories.
1275 Create a symbolic link to this name.
1279 Opens applications as directories, files as text/plain, mount points
1283 by mounting or unmounting them and symlinks by opening the directory
1287 containing the thing they point to.
1291 This is the same effect as clicking with Shift held down.
1295 Explain what kind of thing is selected.
1296 For applications, display the help files.
1300 Display extra information about this object.
1304 Allows you to set the default program to use when opening files of this
1310 \begin_inset LatexCommand \ref{sec: RunAction}
1318 Open the file as if it was a directory --- see section
1319 \begin_inset LatexCommand \ref{sec: vfs}
1327 Mount or unmount each mount point selected.
1331 Remove all the selected entries from the directory.
1335 Subdirectories will have their contents deleted first.
1339 Deleting symlinks only removes the link, not the thing it points to.
1343 Count the sizes of all the selected items.
1344 Directories also have their
1349 Symlinks count themselves, not the things they point to.
1353 Allows you to change the permissions for the selected files.
1357 Search for files by specifying various conditions --- see section
1358 \begin_inset LatexCommand \ref{sec: Searching}
1363 \layout Subsubsection
1367 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
1369 11 2 0 0 -1 -1 -1 -1
1412 Open a new window displaying this window's parent.
1416 As above, but reuse this window.
1420 Open another window onto this directory.
1428 Open the path-entry box (see section
1429 \begin_inset LatexCommand \ref{sec: mini}
1437 Open the shell command box (see section
1438 \begin_inset LatexCommand \ref{sec: mini}
1454 Select just those files that match the given pattern --- see section
1455 \begin_inset LatexCommand \ref{sec: SelectIf}
1463 Same as selecting ROX-Filer and choosing `Help' from the menu.
1466 The pinboard and panels
1470 \begin_inset LatexCommand \ref{run_pin}
1475 \begin_inset LatexCommand \ref{run_pan}
1479 explain how to turn the pinboard and panels on.
1480 Once on, you may drop icons from filer windows onto the them to pin them
1482 Clicking on a pinned file acts just like clicking on it in a filer window.
1483 You can drag pinned icons just like normal icons and you can right-click
1484 on one to see the popup menu.
1487 Drag pinned icons with the middle mouse button to move them around (they
1488 snap to a grid on the pinboard).
1489 Changes to the pinboard and panel layouts are automatically saved.
1490 Clicking on pinned icons with Control held down selects and unselects them.
1491 Click on the background to unselect them all.
1494 If the panel has so many icons that they can't all be shown at once then
1495 you can scroll it by dragging the blank area in the middle.
1506 copy it, it merely creates a shortcut to the original file.
1507 If you delete the file, then you've lost it! Removing a pinned file from
1508 its pinboard or panel only removes the link.
1509 This is different to most other filers...
1510 \layout Subsubsection
1512 The panel and pinboard menus
1515 These menus are both the same, and very simple:
1517 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
1547 Open the directory containing ROX-Filer's documentation.
1549 ROX-Filer Options...
1551 Show the configuration options for ROX-Filer.
1555 Show your home directory.
1559 Show the documentation for the selected application.
1563 Remove the selected items from the panel.
1567 \begin_inset LatexCommand \label{sec: vfs}
1571 Virtual file systems
1574 Some types of file can be represented as a directory.
1575 A typical example is a zip file, which contains an entire directory structure
1577 It is often useful to be able to open up such a file as if it was a real
1578 directory, and the VFS system allows you to do this.
1581 To use this feature you must have one or both of the following:
1584 A system (such as PODFUK
1585 \begin_inset LatexCommand \cite{PODFUK}
1589 ) which causes the kernel to support various Virtual File Systems directly.
1590 This is the best option since all programs will be able to access the contents
1592 You will require root access to install such a system, however, and it
1593 is not available on all platforms.
1596 Support for the Midnight Commander VFS library compiled into ROX-Filer.
1597 This happens automatically when you compile ROX-Filer if it can find the
1598 VFS library --- this means having
1606 ) in a system library directory or in the directory in the environment variable
1612 In this case, you will be able to view the directory structure and copy
1613 files out of it, but not change it.
1614 Support for this may be added later.
1615 Midnight Commander is part of the GNOME project.
1618 Note that using the `Open VFS' menu is simply a short-cut for using the
1619 path-entry box (explained below), so if you want to use a VFS not listed
1620 on the menu you can type in the path directly, eg:
1625 /home/fred/archive.zip#uzip/
1634 Don't forget the final slash!
1635 \layout Subsubsection
1637 Step by step example of adding VFS support
1640 This assumes that you have the Midnight Commander source in a directory
1642 You might need to replace
1665 If you have the root password then install the library in a system library
1666 directory as normal.
1676 $ cp libvfs.so ~/lib
1679 $ cd ~/Apps/ROX-Filer
1686 file to include this as the
1693 LD_LIBRARY_PATH=${HOME}/lib; export LD_LIBRARY_PATH
1696 This will ensure that ROX-Filer will look for the library in the new
1704 $ ./AppRun --compile
1710 checking for mc_stat in -lvfs...
1714 If you saw that line then it's worked! Well done!
1719 \begin_inset LatexCommand \label{sec: mini}
1726 The mini-buffer is a white bar that appears along the bottom of the window
1727 and allows you to enter some text.
1728 Press Escape to get rid of it again.
1729 It behaves in different ways depending on how you invoked it:
1730 \layout Subsubsection
1735 This allows you to type in a path directly.
1736 As you type the display is updated to show the item entered visually.
1737 The main use is to find a file in a large directory quickly, but you can
1738 also use it for navigating between directories, or for selecting a full
1739 pathname from somewhere else and pasting it directly into the path-entry
1742 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
1766 Open the currently selected item.
1770 Shell-style tab completion.
1774 Select the previous/next matching entry.
1777 If you start entering a name beginning with a `.' then the `Show Hidden'
1778 feature is temporarily turned on so that the file can be shown.
1781 Tab completion tries to fill in as many characters for you as it can.
1782 For example, if there are two files in a directory called `save-mail-nov-1999'
1783 and `save-mail-dec-1999' then typing 'save' and pressing Tab will expand
1784 `save' to `save-mail-' and beep to indicate that the match is not complete.
1785 If you use tab completion on a directory and it is unique then the filer
1786 will automatically change into the directory.
1787 This behavior should be familiar to shell users.
1788 \layout Subsubsection*
1793 Let's say you want to locate the documentation for Wine in the directory
1794 /usr/doc (which is usually very large).
1795 Here's how you could do it:
1798 Open the minibuffer by choosing 'Enter Path' from the Window menu.
1799 I usually bind this function to the slash (`/') key.
1802 Press CTRL-U to delete the existing contents --- this moves you to the root
1825 As you type, the cursor will move to the correct subdirectory.
1826 If it beeps when you press Tab then you need to supply more letters.
1827 \layout Subsubsection
1829 The shell command box
1832 This provides a quick way of entering shell commands if you don't want to
1834 If you don't know what shell commands are, skip this section!
1837 Just type in the command and press Return to execute it.
1838 Up and Down arrows move through previously entered commands.
1839 Tab does shell-style completion.
1840 Clicking on an item inserts its name into the minibuffer.
1841 If some items are selected then they are assigned to the positional parameters
1851 \layout Subsubsection*
1863 Open the minibuffer by choosing `Shell Command' from the Window menu.
1864 I usually bind this to the bang (`!') key.
1871 ' and click on the file.
1872 The leading space is automatically inserted.
1875 Press Return to execute it.
1878 To print all the selected files:
1881 Open the shell command minibuffer.
1889 \layout Subsubsection*
1894 Be careful; you will not be asked to confirm! If in doubt, start the command
1899 ' so that it will be displayed rather than executed.
1902 The above command won't work if some of the files contain spaces --- use
1914 ' instead to be safe.
1917 `sh' is always used as the name of the shell to run (mainly because bash
1918 and csh treat positional parameters differently).
1919 However, PATH is searched to find it so you can still use another shell
1920 if you want by naming it sh and putting it in your path.
1923 Commands execute in the background, so you can say:
1927 sleep 240; xmessage Time to go!
1929 \layout Subsubsection
1932 \begin_inset LatexCommand \label{sec: SelectIf}
1936 The conditional selection box
1939 Use this if you want to automatically select all files in the directory
1940 which match a condition.
1941 The syntax for the conditions is given in section
1942 \begin_inset LatexCommand \ref{sec: Searching}
1947 For example, to select all files larger than 5Mb:
1950 Open the Select If minibuffer.
1960 Just those files over 5 Mb in size will be selected.
1961 The expressions you can enter are in the same form as described in section
1963 \begin_inset LatexCommand \ref{sec: Searching}
1971 ' has no effect since the contents of directories are never checked anyway.
1977 Action windows are those boxes that appear while you're doing a Copy/Move/Link/e
1979 The status line at the top of the window shows the current directory or
1980 object that the window is processing.
1981 The scrolling area below is the log area --- it shows what has been done
1982 and may display questions here.
1985 At the bottom are four buttons and, sometimes, some options.
1986 The buttons work as follows:
1989 Quiet will do simple operations without asking you to confirm each one.
1990 By turning this on and off during an operation you can use it like a pause
1994 Yes answers yes to the question displayed in the log area.
1997 No answers no to the question displayed in the log area.
2000 Abort kills the current operation (if any) and closes the action window.
2003 You can control which actions get started automatically (without you having
2004 to click on Quiet at the start) from the Options window.
2005 \layout Subsubsection
2007 Action window options
2010 Some actions have options, which appear as option boxes at the bottom of
2015 `Force' means that the filer won't treat non-writeable files as special.
2016 Normally, it confirms the deletion even if Quiet is pressed.
2017 Note that you still can't remove files from non-writeable directories because
2018 in that case you really don't have permission.
2021 `Brief' prevents the filer logging a message every time it does something.
2022 Use this to speed things up if large numbers of messages are being logged.
2025 `Recurse' means that doing something to a directory will also do the same
2026 thing to all its contents, and the contents of any subdirectories, and
2031 \begin_inset LatexCommand \label{sec: Searching}
2038 The Find feature looks through all the selected files and directories and
2039 any subdirectories (recursively) looking for items that match a particular
2043 If you know the name of a file then just enter it in the `Expression:' box,
2044 enclosed in single quotes.
2045 For example, to find a file called `log' you would enter:
2051 Remember to use normal quotes, not double quotes (
2054 \begin_inset Quotes eld
2066 As the filer finds matching files they are added to the results list.
2067 Clicking on an entry in the list opens a viewer showing the file you clicked
2069 The filer will use the same window to view other results (so, if you want
2070 the results shown in separate windows you must explicitly create a new
2071 window from the Window menu).
2072 \layout Subsubsection
2077 You can also put shell-style wildcard characters inside the quotes, for
2097 manpage if you want to know more about shell wildcards.
2100 If the pattern you enter contains a slash ('/') character then the pattern
2101 is matched against the file's full path, otherwise only the leafname is
2107 will find 'tmp' and 'tmpfile' but not '/tmp/file' ---
2111 will find all three.
2112 \layout Subsubsection
2117 As well as finding files by their names you can also find them by various
2119 Note that `file' is used here to mean anything that can appear in the filesyste
2120 m --- including directories, devices and so on.
2131 These look at the type of the item being checked:
2134 IsReg matches any regular (ie, normal) file.
2137 IsLink matches symlinks.
2140 IsDir matches directories.
2143 IsChar matches character device files.
2146 IsBlock matches block device files.
2149 IsDev matches block or character device files.
2152 IsPipe matches pipes.
2155 IsSocket matches sockets.
2158 These look at the permissions set on the file --- see section
2159 \begin_inset LatexCommand \ref{sec: Permissions}
2166 IsSUID matches files which have the Set-UID bit set.
2169 IsSGID matches files which have the Set-GID bit set.
2172 IsSticky matches files with the sticky bit set,
2175 IsReadable matches files which you can read from.
2178 IsWriteable matches files which you can write to.
2181 IsExecutable matches files which you can execute.
2184 And a couple of other useful ones:
2187 IsEmpty finds empty files (ie, those whose length is 0 bytes).
2190 IsMine finds files which you own.
2191 \layout Subsubsection
2196 You can combine the above tests in various ways to perform more advanced
2198 An expression is actually made up of a list of
2202 , separated by commas.
2203 The filer will try to match each case in turn until one matches or there
2204 are no more cases left.
2205 For example, to search for files with several possible endings:
2208 '*.gif', '*.htm', '*.html'
2211 Further, each of the cases is actually a list of conditions.
2212 The case only matches if all of its conditions are met.
2213 So, to find a directory called
2217 or a regular file ending in
2224 IsDir 'lib', IsReg '*.so'
2227 You can negate a condition by putting a
2231 in front of it and you can use a sub-expression as a condition by bracketing
2241 Not isdir and not isreg
2244 All three do the same thing.
2245 \layout Subsubsection
2250 You can also compare various values using the operators
2254 (for less-than, less-than-or-equal-to, equal-to, not-equal-to, greater-than
2255 and greater-than-or-equal-to).
2256 When comparing times, you may find it helpful to use
2272 to make things clearer.
2275 The following are read from the file being checked and may be used for the
2276 values being compared:
2279 atime The time that the file was last accessed.
2282 ctime The time that the file's status was last changed.
2285 mtime The time that the file's contents were last modified.
2288 size The size of the file.
2291 inode The file's inode (index) number.
2294 nlinks The number of links to this file.
2295 That is, the number of directory entries which refer to this file.
2296 Note that symlinks don't count as references.
2299 uid The User ID of the file.
2302 gid The Group ID of the file.
2305 blocks The number of disk blocks being used by the file.
2308 Times are measured as seconds since the Unix Epoch (00:00:00 UTC, January
2311 When specifying constants to compare these values with you may use various
2312 keywords to scale the value:
2315 Byte(s) has no effect, but looks better.
2318 Kb multiplies by 1024, so 2Kb is the same as 2048.
2322 \begin_inset Formula \( 1024^{2} \)
2328 Sec(s) has no effect, but looks nice.
2331 Min(s) multiplies by 60 to get minutes.
2334 Hour(s),\SpecialChar ~
2335 Day(s),\SpecialChar ~
2336 Week(s),\SpecialChar ~
2337 Year(s) likewise convert to the relevant unit.
2340 Ago makes the time in the past relative to when the check is done.
2343 Hence makes the time in the future.
2353 Some examples should make this all a bit clearer!
2356 mtime after 1 day ago
2362 IsReg and nlinks > 1
2365 The first finds files modified within the last 24 hours.
2374 but it's not so clear what is meant.
2375 The second finds files larger than 10 Mb and the last finds regular files
2376 with more than one directory entry.
2379 Be careful though --- the filer doesn't check the context of the modifiers,
2384 is allowed, although it doesn't make much sense! Also, forgetting to use
2393 will cause odd effects (the time will be measured relative to the Epoch
2394 rather than the current time).
2395 Finally, don't use = with times ---
2399 looks for a file accessed
2403 86400 seconds ago...
2404 \layout Subsubsection
2409 System(Command) executes `Command' on the file.
2410 The test succeeds if the command returns an exit status of zero.
2411 A `%' character in `Command' is replaced by the full path of the file being
2413 System is a very slow test to perform, so do it last if possible.
2414 For example, if you're looking for a .c file containing the word `main',
2419 '*.c' system(grep -q main
2434 so that the grep is only performed for files ending in .c (as opposed to
2435 only checking that the file ends in .c if it contains the word `main').
2440 \begin_float footnote
2443 Note that this is the opposite of the
2449 However, if it gets evaluated at all then it prevents the filer from checking
2450 inside the current directory.
2451 Remember the order in which the filer checks the expression!
2457 '*.old' system(echo rm %)
2463 The first displays a command to delete each file ending in
2467 ; you can either paste the results into an xterm to execute them or run
2468 the search again without the
2473 It's always a good idea to use
2477 first with dangerous commands! The second looks for
2481 files, but does not bother checking inside directories called
2486 The expression is evaluated like this:
2488 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center
2490 \begin_inset Figure size 216 180
2503 You can configure various aspects of ROX-Filer from the Options box.
2504 Choose `Options...' from a filer window menu to open it.
2508 At the bottom of the window are four buttons:
2511 Save puts all your choices into effect, and also saves them into your Choices
2512 directory for next time ROX-Filer is loaded.
2513 ROX-Filer will never save any preferences to disk unless you click on the
2514 `Save' button in the options window.
2515 Exactly where choices are loaded from and saved to is controlled by the
2520 environment variable --- see
2521 \begin_inset LatexCommand \cite{Choices}
2528 OK puts your choices into effect without writing anything to disk.
2531 Apply works like OK, but without closing the Options window.
2534 Cancel closes the options box and forgets any changes you made.
2537 Many of the options in the Options window have tooltips --- hold the mouse
2538 pointer over the option to find out what it does.
2539 \layout Subsubsection
2544 If you are using the pinboard features (see section
2545 \begin_inset LatexCommand \ref{run_pin}
2549 ) then you can choose how the text under each icon is displayed.
2550 If you have a fairly uniform background then you may like to choose `No
2551 background', which simply draws the text directly over the desktop background.
2552 However, users with more `noisy' backdrops may find such text hard to read;
2553 selecting `Rectangular background slab' will draw a solid rectangle behind
2554 the text to make it easier to read.
2557 You may also change the foreground and background colours used for the text
2558 by clicking on the colour slabs in the Options window.
2559 \layout Subsubsection
2561 Action window options
2564 You can choose to start some operations automatically, without waiting for
2565 you to click on Quiet.
2566 Select each operation that you want to auto-start here.
2567 \layout Subsubsection
2572 `Ignore case when sorting' treats upper and lower case letters as equivalent
2574 If this is off then `Zoo' comes before `animal', for example.
2577 `Max Large Icons width' sets the maximum width for a file's name in `Large
2578 Icons' display mode.
2579 Text wider than this will be truncated (a small red vertical bar indicates
2580 when text has been truncated).
2583 `Max Small Icons width' --- as above, but applies when the display is in
2584 `Small Icons' display mode.
2587 The last display style and sort type you chose will also be saved as the
2588 defaults for next time if you click on Save.
2589 \layout Subsubsection
2594 `Toolbar type for new windows' allows you to choose what kind of toolbar
2595 will be used for future filer windows (the currently open windows are not
2601 means that new windows will not have a toolbar,
2605 provides a small bar of icons, and
2609 displays larger icons with textual labels.
2611 \begin_inset LatexCommand \ref{sec: Toolbar}
2616 \layout Subsubsection
2618 Filer window options
2621 `Unique windows' prevents you from having two windows showing the same directory.
2622 Opening a second view onto a directory closes the first.
2625 `Initial window height' determines how large newly opened filer windows
2627 The height is given as the number of rows at Large Icons size.
2628 \layout Subsubsection
2630 Drag-And-Drop options
2633 ROX-Filer uses the standard XDND protocol for drag-and-drop.
2634 This protocol recommends that URIs should contain the hostname of the computer
2635 that the resource is on so that the program receiving the data can determine
2636 whether it can get the data directly or whether it must go via the X-server.
2637 However, many older programs (particularly GNOME applications) get confused
2638 by the hostname and fail to load the data correctly.
2639 If `Don't use hostnames' is on then the hostname part is omitted and ROX-Filer
2640 will work with these applications BUT you can't drag data to a program
2641 running on a different machine.
2644 `Allow dragging to icons in filer windows' controls what happens when you
2645 drop files onto icons in filer windows.
2646 If on then drops onto directories will save the data inside the directory,
2647 while dropping onto programs will invoke the program on that data.
2648 If off then drops anywhere inside a filer window act like drops onto the
2649 window background --- that is, the data will be saved into the directory
2653 `Directories spring open' controls what happens when you hold a file over
2654 a directory in a filer window or on the pinboard.
2655 If on, the directory will `spring open' after a short pause, allowing you
2656 to navigate to any directory during a drag.
2657 You can also hold the pointer over the Home and Up buttons on the toolbar
2658 for a similar effect.
2659 You need to have the previous option enabled for this to have any effect
2660 on files displayed in a directory.
2663 `Spring delay' sets how long, in thousanths of a second, the filer will
2664 wait before spring opening a directory as described above.
2665 If the above option is turned off, then this has no effect.
2666 \layout Subsubsection
2671 The `Xterm here' program is the one used when you choose `Xterm here' from
2673 You can replace it with another program such as `gnome-terminal' or `konsole'
2675 In fact, any program will do, but note that you cannot pass any options
2676 to the program at present.
2677 \layout Subsubsection
2682 `New window on button 1' swaps the actions of the two non-menu buttons when
2683 opening directories.
2684 This is provided for people who are used to the RISC OS mouse bindings.
2687 `Menu on button 2' swaps the actions of buttons 2 and 3 so that the middle
2688 button brings up the menus.
2689 This is provided for people who are used to the RISC OS mouse bindings.
2692 `Single-click navigation' treats a single click over an item as if it was
2694 This allows you to move around, run applications and open files without
2700 opening it you must hold down CTRL while you click.
2706 All files have a MIME type in the form `
2728 ROX-Filer uses a file's name to decide what its MIME type is, and then
2729 uses the MIME type to decide what icon to give it and what program to use
2730 when you open the file.
2734 \begin_inset LatexCommand \label{sec: RunAction}
2741 This box appears when you choose `Set Run Action...' from the File menu, and
2742 is used to set which application is loaded when you click on a file.
2745 For example, let's say you want to set things up so that opening a `.gif'
2746 file loads it into the Gimp.
2747 First, right-click over a gif image to open the menu and choose `Set Run
2748 Action...' from the File submenu.
2749 Then, you have a choice of two methods to set the run action:
2750 \layout Subsubsection*
2752 Setting the run action by drag-and-drop
2755 Drag the Gimp (from a filer window, a panel or the pinboard) onto the area
2756 marked `Drop a suitable application here'.
2757 From now on, clicking on a GIF file will load it into the Gimp.
2758 \layout Subsubsection*
2760 Setting the run action by entering a shell command
2767 \begin_inset Quotes eld
2771 \begin_inset Quotes erd
2777 into the box labelled `Enter a shell command' and press Return.
2782 ' will be replaced by the name of the file you click on when this command
2784 As before, clicking on any GIF image will now load it into the Gimp.
2785 \layout Subsubsection
2787 Setting the default media-type handlers
2792 Whichever method you use to set the action you have the choice of setting
2793 the run action just for that type, or setting the default for all files
2794 with that media-type which don't already have a specific action.
2795 Since the Gimp can load many types of image, it makes sense to select the
2796 `Set default for all `image/<anything>'' option so you don't have to do
2797 it again for image/jpeg files and so on.
2798 However, this only affects types that don't already have a specific action
2799 (ie, those that would have brought up an error box if you tried to open
2803 How filetypes are stored
2806 ROX-Filer uses three sub-directories in your Choices directory for filetypes:
2809 MIME-info contains files which specify what the MIME type for a file should
2810 be, based on its extention.
2811 All the files in all the MIME-info directories are scanned when the filer
2813 ROX-Filer comes with many such rules --- these are installed into the MIME-info
2814 directory by the install script.
2818 Many applications now come with a file called `something.mime'; copy these
2819 files into your MIME-info directory to make ROX-Filer automatically recognise
2824 MIME-types contains symlinks, one for each MIME type, which point to programs
2825 that can handle files of that type.
2826 To set what program is run when you click on the file you should normally
2827 use the `Set Run Action' feature (see section
2828 \begin_inset LatexCommand \ref{sec: RunAction}
2833 However, you can also set the actions manually --- for example, to make
2834 opening an HTML file load it into Netscape:
2838 Find the Netscape application and go to `Link...' on the menu.
2841 Enter `text_html' as the name for the link and drag the icon from the Link
2842 box into the MIME-types directory.
2845 You can also put actual programs in here as well as links if you want to.
2849 MIME-icons contains the images used to display each type of file.
2850 So the filer will try to display an HTML file using the icon `MIME-icons/text_h
2854 In both MIME-types and MIME-icons directories you can also provide default
2855 actions/images for each media type.
2856 For example, if `text_html' isn't found then the filer will try simply
2860 Application directories
2863 An application directory is a directory which can be run as an application.
2864 It contains all the resources of an application --- source code, binaries,
2865 documentation and so on.
2866 Keeping everything in one place make installation and uninstallation much
2868 You can also keep multiple versions of a program by simply having several
2869 application directories.
2870 You may move and rename them as you please.
2871 Application directories are easier to use and install and are more secure
2873 \begin_float footnote
2876 Because you can compile an application as a user and then simply copy it
2877 as root rather than having to run an install script you are free from the
2878 danger of running untrusted code as root.
2879 All you have to watch out for is setuid binaries.
2884 To make a directory executable all you need to do is create a executable
2885 file called `AppRun' inside it.
2886 This file is run when the user double-clicks on the application.
2887 You should also provide `AppIcon.xpm' (which will be used as the image for
2888 the application) and `Help' (which is a directory that is opened when the
2889 user asks for help).
2890 Finally (for security reasons), an application directory must have the
2891 same owner as the AppRun file inside.
2892 Have a look at the ROX-Filer application directory for a full example.
2895 Internationalisation
2899 \begin_inset LatexCommand \label{sec: LANG}
2903 Selecting a translation
2906 ROX-Filer is able to translate many of its messages, provided suitable translati
2907 on files are provided.
2908 If you know that your language is supported then simply set the
2912 environment variable to the appropriate code for your country before starting
2916 LANG=fr; export LANG
2922 To see which translations are currently provided, open the ROX-Filer application
2923 directory (hold down Shift and double-click) and look inside the `
2930 Creating a new translation
2937 directory and create the file `
2952 Copy the file into the `
2956 ' subdirectory under
2961 \begin_inset Formula \( \langle \hbox {name}\rangle \hbox {\tt .po} \)
2965 Eg, if your language is referred to as `ml' (`my language'):
2969 $ cp messages.pot po/ml.po
2973 Load the copy into a text editor.
2976 Fill in the translations, which are all blank to start with.
2983 ' script to create the binary file which ROX-Filer can use.
2984 You will need the GNU gettext package for this.
2985 If you don't have it then just send me the
2989 file and I'll convert it for you.
2993 $ cd ROX-Filer/src/po
2999 Created file ../../Messages/ml.gmo OK
3003 Set the LANG variable to `
3007 ' and restart the filer (see section
3008 \begin_inset LatexCommand \ref{sec: LANG}
3019 file to me so that I can include it in future releases of the filer.
3022 Updating an existing translation
3025 Go into the directory containing the
3034 This checks the source code for new and changed strings and updates all
3035 the translation files.
3039 $ cd ROX-Filer/src/po
3046 Edit the file by hand as before, filling in the new blanks and updating
3047 out-of-date translations.
3048 Look out for `fuzzy' entries where
3052 has made a guess; check it's correct and remove the `fuzzy' line.
3062 Submit the updated file to me.
3069 info page for more instructions on creating a translation.
3075 This is a quick start guide for people who want to modify the source code.
3076 If you make useful changes or fix bugs, please send patches to me or to
3078 Tell me which version you're using!
3084 The first time you compile the program you need to do `
3088 ', but in future you only need to run `
3096 ' directory when you change the
3105 You might want to run `
3112 Creating and applying patches
3115 When people make small modifications to the sources they will often distribute
3120 --- usually on the mailing list.
3121 To apply a patch, go into the 'src' directory and run patch with the patch
3123 Then recompile, like this:
3132 $ ../AppRun --compile
3135 You can remove the patch by simply repeating the above sequence --- patch
3136 will detect that the patch is already applied and offer to remove it.
3139 To create a patch you should first get the latest version of the filer from
3140 CVS (instructions on using CVS can be found on the web-site).
3141 Modify the program as you please.
3142 Create the patch using `
3146 ' from the appropriate directory:
3149 $ cvs diff -c > my_patch
3152 This creates a human- and machine-readable patch file.
3153 Submit this to the mailing list.
3154 The are many reasons for posting patches rather that the modified files:
3157 They are smaller, and hence shouldn't bounce.
3158 They are also quicker to download for people with slow connections.
3161 People can see what they're getting into before applying them!
3164 Patches can (usually) be applied to slightly modified versions of the sources.
3165 This means that people can apply several patches without each new one overwriti
3172 Here's a quick explanation of the autoconf system in case you haven't used
3174 See `info autoconf' for full details.
3177 There's a file called 'configure.in' which contains various tests (`info
3179 You run `autoconf' and it reads through the file and generates a shell
3180 script to perform the tests, saving it as `configure'.
3181 `configure' is normally distributed with the program because not everyone
3185 You then run `configure' (in fact, let the `AppRun' script do it because
3186 it passes it some arguments), which performs all the tests.
3187 It reads in `Makefile.in' and `config.h.in' and fills in the missing values
3188 with the test results to produce `Makefile' and `config.h'.
3191 You run `make', which creates .o files from the .c files and links to produce
3198 The diagram below shows some of the major structures found in the filer
3199 and the relationships between them.
3201 \added_space_top 0.3cm \added_space_bottom 0.3cm \align center
3203 \begin_inset Figure size 595 314
3213 To summarise, each window (or panel) has its own
3218 This structure has pointers to a
3222 (which is the widget which actually displays the files) and to a
3226 , which is used to cache the directory contents.
3235 have pointers to (the same)
3239 s, each of which corresponds to one filesystem object.
3244 s may share the same
3249 While scanning is in progress the
3253 keeps a list of the new items it has found (
3257 ) and the items which have changed in some way (
3262 It periodically notifies the filer window of the changes-so-far by calling
3263 all the functions in the
3275 to add and remove functions to or from the list).
3276 \layout Bibliography
3283 , <http://rox.sourceforge.net>
3284 \layout Bibliography
3291 , <http://www.gtk.org>
3292 \layout Bibliography
3299 , <http://www.gnome.org>
3300 \layout Bibliography
3305 The Drag and Drop protocol
3307 , <http://www.its.caltech.edu/~jafl/xdnd/>
3308 \layout Bibliography
3313 The X Direct Save protocol
3315 , <http://www.its.caltech.edu/~jafl/xds/>
3316 \layout Bibliography
3321 The ROX Choices system
3323 , <http://rox.sourceforge.net/choices.php3>
3324 \layout Bibliography
3325 \bibitem {enlightenment}
3331 <http://www.enlightenment.org>
3332 \layout Bibliography
3337 POrtable Dodgy Filesystems in Userland (hacK),
3339 <http://atrey.karlin.mff.cuni.cz/~pavel/podfuk/podfuk.html>
3340 \layout Bibliography
3347 , <http://www.gnome.org>