1 <?xml version="1.0" standalone="no"?>
2 <?xml-stylesheet href="to_html.xsl" type="text/xml"?>
3 <!-- vim: set sw=1 sts=1 : -->
4 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
5 "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd">
11 <ulink url="http://rox.sourceforge.net"/>
14 <firstname>Thomas</firstname><surname>Leonard</surname>
16 <address><email>tal197@users.sourceforge.net</email></address>
19 <copyright><year>2002</year><holder>Thomas Leonard</holder></copyright>
21 <title>Conditions</title>
23 This program is free software; you can redistribute it and/or modify
24 it under the terms of the GNU General Public License as published
25 by the Free Software Foundation; either version 2 of the License,
26 or (at your option) any later version.
28 This program is distributed in the hope that it will be useful, but
29 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
30 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
33 You should have received a copy of the GNU General Public License
34 along with this program; if not, write to the Free Software Foundation,
35 Inc., 59 Temple Place, Suite 330, Boston, MA, 02111-1307, USA.
41 <application>ROX-Filer</application> is a graphical file manger for the X
42 Window System. Its user interface is based on the RISC OS filer and it
43 supports similar features such as application directories and drag-and-drop
44 loading and saving of files. The filer can also act as a pinboard, allowing
45 you to pin frequently used files onto the desktop background.
51 <title>Introduction</title>
53 <application>ROX-Filer</application> is a simple and easy to use graphical
54 file manager for X11 — the windowing system used on Unix and Unix-like
55 operating systems. It is also the core component of the ROX Desktop
56 <citation>ROX</citation>. Many of the filer's features were inspired by RISC
57 OS <citation>RISC OS</citation>. `ROX' stands for `RISC OS–On–X'.
61 <title>Features</title>
66 <varlistentry><term>XDND</term>
68 A common drag-and-drop protocol used, for example, by the GNOME
69 desktop<citation>GNOME</citation>. This allows data to be loaded into an
70 application by dragging it from a filer window to a program. The full
71 specification is given in <citation>DND</citation>.
72 </para></listitem></varlistentry>
74 <varlistentry><term>XDS</term>
76 An extension to XDND that allows applications to save data by
77 dragging an icon back to a filer window. The full specification is given in
78 <citation>XDS</citation>.
79 </para></listitem></varlistentry>
81 <varlistentry><term>Choices</term>
83 A simple, but flexible, system for managing user choices. See
84 <citation>Choices</citation> for details.
85 </para></listitem></varlistentry>
87 <varlistentry><term>Application directories</term>
89 Self contained relocatable applications, where installation is as simple as
90 copying it to where you want it and uninstalling it is just a matter of
91 deleting a directory. Described later in this documentation.
92 </para></listitem></varlistentry>
94 <varlistentry><term>Thumbnails</term>
96 The filer can be made to display image files by using the image itself for the
97 icon, instead of a generic `this-is-an-image' icon. Very useful for organising
98 a directory full of photos! See <citation>Thumbs</citation> for details
99 (spec is still in developement).
100 </para></listitem></varlistentry>
109 <chapter id="compiling">
110 <title>Compiling</title>
113 If you've just got hold of the filer by downloading the source archive
114 then you'll need to compile it before you can use it. If you downloaded
115 and installed a binary package, or if <application>ROX-Filer</application>
116 was included with your system, then you can skip this section. If you got
117 here by clicking on the `i' symbol in a filer window, or if typing
118 <command>rox</command> at a shell prompt works, then you don't need to
121 <itemizedlist><title>To compile, you will need the following:</title>
124 Unix or Linux (root access is not required),
128 The X Window system (supplied as standard on all modern systems),
132 GTK+ 1.2.0 or later (libraries and headers) — get the latest version
133 from <citation>GTK+</citation>,
137 A C compiler, such as `gcc' (standard on most systems).
142 All of the above are standard on most modern Linux distributions.
143 To check which version of GTK+ you have installed, run the
144 <command>gtk-config</command> command, like this
145 (<prompt>$</prompt> is the shell prompt):
147 <screen>$ gtk-config --version
149 Due to bugs in earlier versions, GTK+ 1.2.8 is strongly
153 <procedure><title>To compile:</title>
156 The filer needs some shared files to work — icons for the various
157 file types, rules for determining file types and default run actions.
158 These are installed by the `rox-base' package. Install rox-base (from
159 <ulink url="http://rox.sourceforge.net"/> now if you haven't done so already.
163 Change to the directory containing the ROX-Filer subdirectory.
167 Run the <command>install.sh</command> script, like this:
169 <screen>$ ./install.sh</screen>
174 <application>ROX-Filer</application> will perform various checks to find
175 out what kind of system it is being run on and will then compile. If it
176 doesn't work then please e-mail me and complain! Tell me what kind of
177 system you have and what errors were reported. If you manage to fix the
178 problem yourself then please e-mail me the fix.
180 The executable file is stored inside the ROX-Filer directory in a
181 different subdirectory for each platform. Therefore, you can compile
182 the same application on several different types of machine and then
183 run it from any of them using the AppRun script. This is particularly
184 useful in a network environment.
188 Once the filer has compiled you will be asked where you want to install
189 it. If you want to do a system-wide installation as root, you may
190 want to stop here, <command>su</command> to root and rerun the install script.
192 If you don't have the root password then don't worry — just follow
193 the instructions for installing into your home directory.
199 You can now run the filer by running the <command>rox</command> script without
200 any options, like this:
202 <screen>$ rox</screen>
204 A window should appear and display the contents of the current directory.
206 If you installed the script into your home directory then you may
207 need to set your <envar>PATH</envar> environment variable so that the shell can
208 find it. For example, if you installed it into a directory called
209 <filename>bin</filename> in your home directory, use this:
211 <screen>$ PATH=$HOME/bin:$PATH; export PATH</screen>
213 or (if you are using the <citerefentry><refentrytitle>csh</refentrytitle>
214 <manvolnum>1</manvolnum></citerefentry> shell):
216 <screen>$ setenv PATH $HOME/bin:$PATH
223 <chapter id="invoking">
224 <title>Invoking</title>
227 By default, <application>ROX-Filer</application> will start by displaying
228 the current directory. You can get it to display other directories instead
229 by listing them after the command:
231 <screen>$ rox /home /usr /usr/local</screen>
233 You can also use it to open files, like this:
235 <screen>$ rox README</screen>
237 The filer supports various options; use <option>-h</option> for a list.
238 All options have long and short forms (eg <option>-h</option> and
239 <option>--help</option>) — although on some systems you can only use the
242 Note that if the same version of the filer is already running on this
243 machine then, by default, it will be used to open the directories.
244 You can override this (perhaps because the old copy has stopped responding for
245 some reason) using the <option>--new</option> option.
247 For a complete list of command-line options, see <xref linkend="manpage"/>
251 <title><anchor id="run_pin" xreflabel="Pinboard support"/>Pinboard support</title>
254 If you want the filer to manage your desktop background then you use
255 the <option>--pinboard</option> option and supply a name for the pinboard,
258 <screen>$ rox --pinboard=MyPinboard</screen>
260 The pinboard configuration is saved in
261 <filename><Choices>/ROX-Filer/pb_MyPinboard</filename>
262 as soon as you change it in some way (for example, by dropping a file
263 onto the background). You can have as many pinboards as you like and
264 switch between them by running rox again, eg:
266 <screen>$ rox --pinboard=MyOtherPinboard</screen>
268 To turn off the pinboard again, set the name to an empty string:
270 <screen>$ rox --pinboard=</screen>
272 See the <xref linkend="winman"/> if you have trouble getting the icons to
273 display correctly. The pinboard may also be turned on and off by locating
274 <filename>ROX-Filer</filename> in a filer window and choosing `Enable
275 pinboard' or `Disable pinboard' from the menu. </para>
279 <title><anchor id="run_pan" xreflabel="Panel support"/>Panels</title>
282 Panels work just like the pinboard. You can create a panel on any
283 side of the screen by using the options <option>--left</option>, <option>--right,</option>
284 <option>--top</option> and <option>--bottom</option>, depending on which side
285 of the screen the panel should appear on. On some systems, the short
286 (one letter) form of the options must be used. For example, to create
287 a panel along the bottom edge of the screen:
289 <screen>$ rox -b=MyPanel</screen>
291 The panel should be displayed in a window without a title bar. If
292 this does not work then see the <xref linkend="winman"/> for some ideas.
293 You can drag files onto either side of the panel to add them. Panel icons
294 can be repositioned by dragging them with the middle mouse button.
295 Changes to the panel are automatically saved to
296 <filename><Choices>/ROX-Filer/pan_MyPanel</filename>.
297 As with the pinboard, you can switch between panel configurations
298 simply by running rox again with a different panel name. Specify a
299 blank name to remove the panel.
301 <screen>$ rox --bottom=MyOtherPanel
302 $ rox --bottom=</screen>
308 <title id="winman" xreflabel="window manager notes">Window manager notes</title>
311 You may have to play around with your window manager a bit to get
312 the pinboard icons and panels to display correctly (eg, without borders
313 and underneath all other windows). In particular, try setting the
314 stacking level / depth to low (or a negative value). Make sure any
315 'Keep transients above other windows' type options are turned off!
317 In order for the filer to receive mouse clicks on the background (used
318 for the pinboard support) you need a GNOME-compliant window manager.
319 To see if your window manager supports this, try clicking the right
320 mouse button on an unused area of the background. If you get the pinboard
324 <sect2><title>Sawfish / sawmill</title>
326 Sawfish tries to guess whether you are using GNOME at start-up and only
327 provides support if so. You may need to add the line
328 <programlisting>(require 'gnome)</programlisting>
329 to your <filename>.sawfishrc</filename> file (see the sawfish manual
334 <sect2><title>IceWM</title>
337 Paste these configuration settings into
338 <filename>~/.icewm/preferences</filename>:
341 # Manage root window (EXPERIMENTAL - normally enabled!)
342 GrabRootWindow=1 # 0/1
343 # Bitmask of root window button click to use in window manager
344 UseRootButtons=3 # [0-255]
345 # Desktop mouse-button click to show the menu
346 DesktopWinMenuButton=1 # [0-20]
347 # Desktop mouse-button click to show the window list
348 DesktopWinListButton=2 # [0-5]
349 # Desktop mouse-button click to show the window list menu
350 DesktopMenuButton=0 # [0-20]</programlisting>
351 Paste these into <filename>~/.icewm/winoptions</filename>:
354 # ROX-Filer pinboard and panel
355 ROX-Filer.icon: folder
356 ROX-Panel.layer: Dock
357 ROX-Panel.doNotCover: 1
358 ROX-Panel.ignoreWinList: 1
359 ROX-Panel.ignoreTaskBar: 1
360 ROX-Panel.ignoreQuickSwitch: 1
361 ROX-Pinboard.layer: Below
362 ROX-Pinboard.ignoreWinList: 1
363 ROX-Pinboard.ignoreTaskBar: 1
364 ROX-Pinboard.ignoreQuickSwitch: 1
365 ROX-Filer.layer: Normal</programlisting>
366 Restart IceWM and the filer for the new settings to take effect.
371 <sect2><title>Window Maker</title>
373 <step><para>Run the filer using <userinput>rox -p=Default</userinput>.</para></step>
375 Press <keycap>Control</keycap>+<keycap>Escape</keycap>, or
376 [RightButtonDown] on any window's titlebar.
377 Choose <guimenuitem>Attributes...</guimenuitem> from the menu.
381 The Attributes Inspector window appears. From the pulldown menu
382 at the top, choose <guimenuitem>Window Specification</guimenuitem>
387 Press the <guibutton>Select window</guibutton> button.
388 The cursor changes to a double crosshair. Select one of the
389 <application>ROX-Filer</application> pinboard icons. The radio buttons
390 in the <guilabel>Window Specification</guilabel> frame should change
391 their labels to include <userinput>ROX-Pinboard.ROX-Filer</userinput>
392 as the first item. Select that radio button.
396 Choose <guimenuitem>Window Attributes</guimenuitem> from the pulldown
397 menu. In the <guilabel>Attributes</guilabel> frame, choose the
398 features you want the pinboard icons to have; I recommend the
401 <listitem><para>Disable titlebar</para></listitem>
402 <listitem><para>Disable resizebar</para></listitem>
403 <listitem><para>Disable close button</para></listitem>
404 <listitem><para>Disable miniaturize button</para></listitem>
405 <listitem><para>Keep at bottom (sunken)</para></listitem>
406 <listitem><para>Omnipresent</para></listitem>
412 Choose <guimenuitem>Advanced Options</guimenuitem> from the pulldown
413 menu. In the <guilabel>Advanced</guilabel> frame, choose the advanced
414 features you wish; I recommend the following:
417 <listitem><para>Do not show in the window list</para></listitem>
418 <listitem><para>Ignore 'Hide Others'</para></listitem>
419 <listitem><para>Ignore 'Save Session' (possibly)</para></listitem>
424 When you're finished selecting window attributes, press the
425 <guibutton>Save</guibutton> button, and then close the Attributes
426 Inspector window using the <guibutton>X</guibutton> button in the titlebar.
431 <sect2><title>Others</title>
434 If all else fails, try running rox with the <option>-n</option> and
435 <option>-o</option> options; this overrides window manager control of the
436 icons altogether (<option>-n</option> forces the filer to start a new
444 <title>Running as root</title>
447 If you run the filer as the `root' user then the filer will display
448 a message at the top of each window to remind you. The root user has
449 permission to access or change any file in the system, so be very
450 careful when using the filer like this.
452 Normally, you should log in as an ordinary user and only change to
453 root when you need to. You can create a simple script which runs the
454 filer as root — something like this:
459 su -m -c "rox $*"</programlisting>
461 Then, you can get a root filer window by simply running the script
462 and entering the root password. Remember, any file operations you
463 perform and any programs you run from these windows will run as root
466 You may find that the X server won't allow root (or other users) to
467 connect. Reading the manual pages for <command>xauth</command> and
468 <command>xhost</command> may give you some hints, but it varies
469 between systems (which is why this isn't built in to the filer!).
476 <chapter id="keys" xreflabel="mouse and key bindings">
477 <title>Mouse button and key bindings</title>
479 <itemizedlist><title>Quick start:</title>
481 <listitem><para>Click the left
482 <footnote><para>This documentation assumes that button–1 is the left
483 button, button–2 is the middle button and button–3 is the
484 right button. This is not always the case — for example, in a
485 left-handed setup.</para></footnote> mouse button to open files and
486 directories.</para></listitem>
489 Click the right button to get a menu. Click over a file to perform an action on that file.
493 Drag files between windows with the left button to copy them, or with
494 the middle button to get a menu of possible actions (copy, move, link,
501 By default, the mouse button bindings are designed to fit in with X
502 conventions. However, the behaviour is highly configurable — have a play in
503 the Options window if you don't like the normal settings. The normal settings
509 <thead><row><entry>Key or mouse button</entry><entry>Action</entry></row></thead>
513 <row><entry>Left button click</entry><entry>
514 Open the file or directory clicked on. Hold down <keycap>Control</keycap>
515 to select things instead of opening them. Hold down <keycap>Shift</keycap>
516 to look inside applications, treat files as text, follow symlinks or
520 <row><entry>Middle button click</entry><entry>
521 Same as left click, but open a directory in a new window or close the viewer
525 <row><entry>Right button click</entry><entry>
526 Open the main menu. Hold down <keycap>Control</keycap> while clicking to go
527 directly to the Selection submenu. Hold down <keycap>Shift</keycap> to get the
528 <guimenu>Send To</guimenu> menu (see the <xref linkend="SendTo"/> section).
531 <row><entry>Drag an item (left mouse button)</entry><entry>
532 Copy the file(s) to the destination (an application or another filer
533 window). Hold down <keycap>Shift</keycap> to move the file,
534 <keycap>Control</keycap>+<keycap>Shift</keycap> to create
535 a symbolic link, or <keycap>Alt</keycap> to get a menu of possible actions.
538 <row><entry>Drag an item (middle mouse button)</entry><entry>
539 When you let go, display a menu of possible actions.
540 There is an option to make this move the files rather than open the menu.
543 <row><entry>Drag (not over an item)</entry><entry>
544 Select a group of items by dragging a box around them. With the left
545 mouse button, only the files in the box will be selected. If you hold
546 down <keycap>Control</keycap> then the boxed items are added to the selection.
547 If you use the middle button then the boxed items switch between being selected
551 <row><entry>Double-click background</entry><entry>
552 Resize the window to a sensible size.
555 <row><entry><keycap>Backspace</keycap></entry><entry>
556 Change to viewing the parent directory.
559 <row><entry>Cursor keys</entry><entry>
560 Move the cursor around.
564 <keycap>Page Up</keycap>, <keycap>Page Down</keycap></entry><entry>
565 Move the cursor up and down a page at a time.
568 <row><entry><keycap>Home</keycap>, <keycap>End</keycap></entry><entry>
569 Move to the first/last entry in the directory.
572 <row><entry><keycap>Return</keycap></entry><entry>
573 Acts like clicking on the file. You may hold down Shift for other
574 effects, as with clicking.
577 <row><entry><keycap>Spacebar</keycap></entry><entry>
578 Toggles the item under the cursor between being selected and unselected,
579 and moves to the next item.
582 <row><entry><keycap>Tab</keycap>, <keycap>Shift</keycap>+<keycap>Tab</keycap></entry><entry>
583 Moves the cursor to the next/previous selected item.
586 <row><entry>Hold mouse over an item</entry><entry>
587 Shows a tooltip containing a brief description of an application (if
588 available), the target of a symbolic link, and the full name of a file,
589 if it's too long to show in the main window.
592 </tbody></tgroup></informaltable>
595 Other keys can easily be defined by opening the
596 menu, moving the pointer over the item you want to use and pressing
597 a key. The key will appear in the menu and can be used from then on.
598 Key bindings are automatically saved when the filer quits.
603 <chapter id="selection">
604 <title>The selection and file groups</title>
606 When you select items in a <application>ROX-Filer</application> window,
607 the filer takes the <emphasis>primary selection</emphasis>. You can then paste
608 into another window to get the pathnames of the selected files.
612 <title>Example: loading a file into an application that doesn't support
613 drag-and-drop:</title>
615 <step><para>Open the application's Open dialog box.</para></step>
618 <keycap>Control</keycap>-click on the file in
619 <application>ROX-Filer</application> to select it.</para></step>
622 Click the middle button in the filename box in the application to paste the
628 Note that clicking the middle mouse button in the main area of most web-browsers
629 will open the selected file.
631 If you select something else (eg, some text in another program), the selected
632 items in the filer window will be shown shaded (the filer no longer has the
633 primary selection). Clicking on one of the shaded items will cause the
634 filer to regain the primary selection.
637 <sect1><title>Saving and restoring the selection</title>
639 It is sometimes useful to save the current selection for later. You can
640 save the current selection to one of ten numbered groups by pressing
641 <keycap>Control</keycap>+<keycap><number></keycap>.
642 You can restore a saved group by pressing the group number on its own. You
643 can do this from a different directory, or even a different filer window.
645 Saving is also useful even if there is no selection, since it still saves
646 the current directory.
648 <procedure><title>Example: saving a directory and returning to it later:</title>
649 <step><para>You are looking at a directory, and wish to remember it.
650 Press <keycap>Control</keycap>+<keycap>1</keycap>.</para></step>
651 <step><para>Move to another directory, or close the window, etc.</para></step>
652 <step><para>Press <keycap>1</keycap> in any filer window to return
653 to the first directory.</para></step> </procedure>
654 <para>The groups are saved automatically for next time the filer is loaded.
658 <chapter id="toolbar">
659 <title><anchor id="Toolbar" xreflabel="Toolbar"/>The toolbar</title>
662 By default, each window has a toolbar along the top. You can disable
663 this (or make it larger) from the Options window, as well as set which
664 tools appear on the toolbar. Normally, you should click with the left
665 mouse button (1). However, many tools can perform a related function
666 if clicked on with buttons 2 or 3 (middle or right).
669 <informaltable><tgroup cols="3">
674 Mouse button 1</entry><entry>
683 Close the window</entry><entry>
685 </entry></row><row><entry>
686 Up arrow</entry><entry>
687 Change to parent directory</entry><entry>
688 Show parent in a new window <xref linkend="newwin_fn"/>
689 </entry></row><row><entry>
691 Change to home directory</entry><entry>
692 Show home in a new window <xref linkend="newwin_fn"/>
693 </entry></row><row><entry>
694 Looping arrows</entry><entry>
695 Reread the directory contents</entry><entry>
697 </entry></row><row><entry>
698 Magnifying glass</entry><entry>
699 Make icons bigger</entry><entry>
701 </entry></row><row><entry>
703 Hide or show extra details</entry><entry>
705 </entry></row><row><entry>
706 Dot files</entry><entry>
707 Toggle the display of hidden file (those with names starting with a dot)</entry><entry>
709 </entry></row><row><entry>
710 Information</entry><entry>
711 Show <application>ROX-Filer</application>'s help files</entry><entry>
712 Show help files and close window
714 </tbody></tgroup></informaltable>
717 <anchor id="newwin_fn" xreflabel="[1]"/>[1]
718 If the 'New window on button 1' option is turned on
719 then the default is to open a new window — clicking with the other
720 button reuses the same window instead.
724 Dragging files to the Up or Home icons acts just like dragging them
725 into the directory which the button leads to.
727 The toolbar can also show the number of files in the directory, and
728 information about the selection. This can be turned on or off in the
736 <title>The menus</title>
738 By default, you can open a menu by right clicking over a pinboard, panel or
741 In filer windows, you may also press <keycap>\</keycap> to open the menu. As
742 a shortcut, you can open the File submenu directly by holding down the
743 <keycap>Control</keycap> key when opening the menu. Here is a full
744 description of each menu item:
746 <informaltable><tgroup cols="2">
748 <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
751 <row><entry><guimenuitem>Display</guimenuitem></entry><entry>
752 Change the display settings.
755 <row><entry><guimenuitem>File</guimenuitem></entry><entry>
756 Operations on the selected items.
759 <row><entry><guimenuitem>Select</guimenuitem></entry><entry>
760 Control which items are selected.
763 <row><entry><guimenuitem>Options...</guimenuitem></entry><entry>
764 Configure <application>ROX-Filer</application>.
767 <row><entry><guimenuitem>New</guimenuitem></entry><entry>
768 Create a new file or subdirectory inside this directory.
771 <row><entry><guimenuitem>Xterm Here</guimenuitem></entry><entry>
772 Open an xterm with its current directory set to this directory.
775 <row><entry><guimenuitem>Window</guimenuitem></entry><entry>
776 Operations on the window as a whole.
779 </tbody></tgroup></informaltable>
784 <title>The display menu</title>
787 <informaltable><tgroup cols="2">
789 <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
792 <row><entry><guimenuitem>Huge Icons</guimenuitem></entry><entry>
793 Extra large icons (mainly useful with thumbnails, see below).
794 </entry></row><row><entry>
796 <guimenuitem>Large Icons</guimenuitem></entry><entry>
797 Each object in the directory is shown as a large icon with its name
799 </entry></row><row><entry>
801 <guimenuitem>Small Icons</guimenuitem></entry><entry>
802 Items are drawn smaller than usual, allowing you to see more files
804 </entry></row><row><entry>
806 <guimenuitem>Huge, With...</guimenuitem></entry><entry>
807 As for <guimenuitem>Large, With...</guimenuitem>, but with extra large icons.
808 </entry></row><row><entry>
810 <guimenuitem>Large, With...</guimenuitem></entry><entry>
811 <para>Entries are displayed along with some extra details:</para>
814 <listitem><para><guimenuitem>Summary</guimenuitem>
815 shows the file permissions, owner, group, size and modification time.
818 <listitem><para><guimenuitem>Sizes</guimenuitem>
819 shows just the size of each file (not directories).
822 <listitem><para><guimenuitem>Permissions</guimenuitem>
823 shows just the permissions and owner.
826 <listitem><para><guimenuitem>Type</guimenuitem>
827 shows the MIME type of each file.
830 <listitem><para><guimenuitem>Times</guimenuitem>
831 shows the times the file was last accessed, modifed and changed.
832 Reading a file's contents or listing a directory updates the
833 <emphasis>access time</emphasis>; modifying the contents of a file or
834 the list of files in a directory updates the <emphasis>modification
835 time</emphasis>; changing a file's owner or permissions updates the
836 <emphasis>change time</emphasis>.
841 </entry></row><row><entry>
843 <guimenuitem>Small, With...</guimenuitem></entry><entry>
844 As above, but with a smaller icon and all on one line.
845 </entry></row><row><entry>
847 <guimenuitem>Sort by Name</guimenuitem></entry><entry>
848 Items are arranged by name. There is an option to make this case-sensitive.
849 </entry></row><row><entry>
851 <guimenuitem>Sort by Type</guimenuitem></entry><entry>
852 Items are grouped by their types and then sorted by name within the
854 </entry></row><row><entry>
856 <guimenuitem>Sort by Date</guimenuitem></entry><entry>
857 Most recently modified first.
858 </entry></row><row><entry>
860 <guimenuitem>Sort by Size</guimenuitem></entry><entry>
862 </entry></row><row><entry>
864 <guimenuitem>Show Hidden</guimenuitem></entry><entry>
865 If on, files beginning with a dot are shown, otherwise they are hidden.
866 The titlebar shows <guilabel>(All)</guilabel> when this is on.
867 </entry></row><row><entry>
869 <guimenuitem>Show Thumbnails</guimenuitem></entry><entry>
870 When on, the filer tries to load every image file and use that
871 image as the file's icon. Useful if you have a directory full of
872 photos and can't remember which is which!
873 When using Gtk+-2.0 or libpng, the thumbnails are saved in
874 <filename>~/.thumbnails</filename> for quick loading next time.
875 Otherwise, they are lost when the filer quits.
876 While loading thumbnails, a progress bar appears at the bottom of
877 the window. Clicking on the <guibutton>Cancel</guibutton> button
878 beside the bar stops the scan.
879 The titlebar shows <guilabel>(Thumbs)</guilabel> when this is on.
880 </entry></row><row><entry>
882 <guimenuitem>Refresh</guimenuitem></entry><entry>
883 Rereads the contents of the directory and details of all the files
884 in it. Use this if the display becomes out-of-date.
887 </tbody></tgroup></informaltable>
891 <sect2><title><anchor id="Permissions" xreflabel="Permissions"/>
896 The permissions field, when shown, is made up of four groups of three
897 flags. Each flag is displayed as a letter if it is on and a dash (–)
898 if not. The first three characters show the permissions for the owner
899 of the file, the second for other members of the file's group and
900 the third for everyone else. Whichever group applies to the
901 <application>ROX-Filer</application> process itself is shown underlined.
902 The fourth group shows any special flags.
904 The meanings of the characters are:
908 <listitem><para><computeroutput>r</computeroutput> —
909 Permission to read the contents of a file, or the names of files
910 in a directory.</para></listitem>
912 <listitem><para><computeroutput>w</computeroutput> —
913 Permission to alter the contents of a file, or change which names
914 appear in a directory.</para></listitem>
916 <listitem><para><computeroutput>x</computeroutput> —
917 Permission to run the file as a program, or refer to the files
918 listed within the directory.</para></listitem>
920 <listitem><para><computeroutput>U</computeroutput> —
921 This program executes with the <emphasis>effective user ID</emphasis> of its
922 owner rather than the person who ran it.</para></listitem>
924 <listitem><para><computeroutput>G</computeroutput> —
925 This program executes with the <emphasis>effective group ID</emphasis> of its
926 group, regardless of who ran it.</para></listitem>
928 <listitem><para><computeroutput>T</computeroutput> —
929 Entries in this directory can only be altered or removed by the
930 people who own the files even if they have write permission on the
931 directory itself.</para></listitem>
936 <emphasis role="underline">rwx</emphasis>,rwx,r-x/---</programlisting>
937 means that the owner of the file is the same as the effective user of
938 <application>ROX-Filer</application> (basically, you own the file), you and
939 members of the file's group have read, write and execute permission and other
940 people have only read and execute permission. There are no special flags set.
942 The rules which determine which permissions apply may vary slightly between
943 operating systems, but a rough guide is:
947 <listitem><para>If the <emphasis>effective user ID</emphasis> of the
948 process is equal to the file's owner, then the owner permissions apply.
951 <listitem><para>Otherwise, if the <emphasis>effective group ID</emphasis>
952 of the process is equal to the file's group OR the file's group is one
953 of the process's <emphasis>supplemental groups</emphasis> then the
954 group permissions apply.
957 <listitem><para>Otherwise, the `other' permissions apply. The
958 <emphasis>real user ID</emphasis> and <emphasis>real group
959 ID</emphasis> have no effect (except that a process may set its real
960 IDs to its effective IDs).
970 <title>The file menu</title>
972 All of these work in the same way — if you open the menu with some
973 items selected then the operation applies to those items. If you open
974 then menu over an item while there is no selection then that item
975 is temporarily selected.
977 If you choose one of these while there is no selection at all then the
978 window goes into `target mode'; the operation happens to the next item you
979 click on. Click on the window background, press <keycap>Escape</keycap>, or
980 click with the right mouse button to cancel target mode. Target mode is
981 mainly useful with the <guilabel>Single-click navigation in filer
982 windows</guilabel> option and keys bound to the various menu entries.
984 Note that individual applications may add extra menu items to the
985 top of this submenu when you click over them — see
986 <xref linkend="AppDir"/> for details.
988 <informaltable><tgroup cols="2">
989 <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
993 <guimenuitem>Copy...</guimenuitem></entry><entry>
994 Make a copy of this object.
998 <guimenuitem>Rename...</guimenuitem></entry><entry>
999 Change the name used for this object, or move it between directories.
1003 <guimenuitem>Link...</guimenuitem></entry><entry>
1004 Create a symbolic link to this name.
1008 <guimenuitem>Shift Open</guimenuitem></entry><entry>
1009 Opens applications as directories, files as text/plain, mount points by
1010 mounting or unmounting them and symlinks by opening the directory containing
1011 the thing they point to. This is the same effect as clicking with
1012 <keycap>Shift</keycap> held down. The text of the menu entry changes
1013 to show which action will be performed.
1017 <guimenuitem>Help</guimenuitem></entry><entry>
1018 Explain what kind of thing is selected. For applications, display
1023 <guimenuitem>Info</guimenuitem></entry><entry>
1024 Display extra information about this object.
1028 <guimenuitem>Set Run Action...</guimenuitem></entry><entry>
1029 Allows you to set the default program to use when opening files of
1030 this type. See <xref linkend="RunAction"/> section for details.
1034 <guimenuitem>Set Icon...</guimenuitem></entry><entry>
1035 You can give each file or directory its own special icon using this
1036 feature — simply drag a suitable image onto <xref linkend="SetIcon"/>.
1040 <guimenuitem>Open (A)VFS</guimenuitem></entry><entry>
1041 Open the file as if it was a directory — see the
1042 <xref linkend="vfs"/> section.
1046 <guimenuitem>Send To...</guimenuitem></entry><entry>
1047 Opens the `Send To' menu, allowing you to send the selected files
1048 to one of a list of applications. See the
1049 <xref linkend="SendTo"/> section.
1053 <guimenuitem>Delete</guimenuitem></entry><entry>
1054 Remove all the selected entries from the directory. Subdirectories
1055 will have their contents deleted first. Deleting symlinks only removes
1056 the link, not the thing it points to.
1060 <guimenuitem>Disk Usage</guimenuitem></entry><entry>
1061 Count the sizes of all the selected items. Directories also have their
1062 contents counted. Symlinks count themselves, not the things they point
1067 <guimenuitem>Permissions</guimenuitem></entry><entry>
1068 Allows you to change the permissions for the selected files.
1072 <guimenuitem>Find</guimenuitem></entry><entry>
1073 Search for files by specifying various conditions — see the
1074 <xref linkend="Searching"/> section.
1077 </tbody></tgroup></informaltable>
1080 <formalpara><title>Note about symlinks:</title>
1082 A symbolic link stores the <emphasis>location</emphasis>
1083 of another file. Deleting the symlink doesn't affect the other file.
1084 Deleting the other file means that the symlink won't work. There are
1085 two types of symbolic link — Relative and Absolute. An absolute
1086 link stores the path from the root directory to the target file (eg
1087 <filename>/home/fred/MyFile</filename>).
1089 A relative path stores the path from the symlink
1090 to the target (eg <filename>../fred/MyFile</filename>).
1091 If the target file is never going to move then you want an absolute link,
1092 but if the target may move (and the symlink will be moved with it) then
1093 you want a relative link.
1099 <title>The select menu</title>
1101 This menu allows you to select and unselect files in various ways. See the
1102 <xref linkend="keys"/> section for other ways to select files.
1104 <informaltable><tgroup cols="2">
1105 <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
1108 <guimenuitem>Select All</guimenuitem></entry><entry>
1109 Select every item in this window.
1112 <row><entry><guimenuitem>Clear Selection</guimenuitem></entry><entry>
1113 Unselect every item in this window.
1116 <row><entry><guimenuitem>Invert Selection</guimenuitem></entry><entry>
1117 Every selected file becomes unselected, and every unselected file
1122 <guimenuitem>Select If...</guimenuitem></entry><entry>
1123 Select just those files that match the given pattern —
1124 see the <xref linkend="SelectIf"/> section.
1127 </tbody></tgroup></informaltable>
1133 <title>The new menu</title>
1136 Each entry in this submenu opens a savebox for creating a new file or
1137 directory. There are two standard entries; the others are the contents of
1138 your <filename><Choices>/Templates</filename> directory, if it
1142 <informaltable><tgroup cols="2">
1143 <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
1146 Directory</entry><entry>
1147 Create a new directory.
1148 </entry></row><row><entry>
1150 Create a blank file.
1151 </entry></row><row><entry>
1152 <user entries></entry><entry>
1153 Copy a file from your Templates directory.
1155 </tbody></tgroup></informaltable>
1158 To add your own entries, create a new directory called
1159 <filename>~/Choices/Templates</filename>
1160 (if you have the default CHOICESPATH) and put any files you want in
1161 there. Each file in the directory will appear on the menu and the
1162 box that appears will copy it. For example, you could create a blank
1168 <title>My Page</title>
1173 </html></programlisting>
1175 Save this as <filename>index.html</filename> inside the
1176 <filename>Templates</filename> directory and you can easily create new
1177 HTML files. You can also save blank documents from various applications
1178 into here (eg, a blank spreadsheet, a blank letter, etc).
1180 Note that you cannot set keyboard shortcuts for these user-defined
1187 <title>The window menu</title>
1191 <informaltable><tgroup cols="2">
1192 <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
1195 <guimenuitem>Parent, New Window</guimenuitem></entry><entry>
1196 Open a new window displaying this window's parent.
1200 <guimenuitem>Parent, Same Window</guimenuitem></entry><entry>
1201 As above, but reuse this window.
1205 <guimenuitem>New Window</guimenuitem></entry><entry>
1206 Open another window onto this directory.
1210 <guimenuitem>Home Directory</guimenuitem></entry><entry>
1211 Change to your home directory.
1215 <guimenuitem>Resize Window</guimenuitem></entry><entry>
1216 Set the window to a sensible size for its contents.
1220 <guimenuitem>Close Window</guimenuitem></entry><entry>
1225 <guimenuitem>Enter Path...</guimenuitem></entry><entry>
1226 Open the path-entry box (see the the <xref linkend="mini"/> section).
1230 <guimenuitem>Shell Command...</guimenuitem></entry><entry>
1231 Open the shell command box (see the <xref linkend="mini"/> section).
1235 <guimenuitem>Show ROX-Filer Help</guimenuitem></entry><entry>
1236 Same as selecting ROX-Filer and choosing
1237 <guimenuitem>Help</guimenuitem> from the menu.
1240 </tbody></tgroup></informaltable>
1247 <title><anchor id="SendTo" xreflabel="Send To menu"/>The send to menu</title>
1250 The `Send To' menu provides a quick way to send some files to an application.
1251 The filer scans all the <filename>SendTo</filename> directories in your
1252 <envar>CHOICESPATH</envar> and lists the contents on this menu.
1254 To change which applications appear here you should choose the
1255 <guimenuitem>Customise</guimenuitem> item from the bottom
1256 of the menu to create and open your own SendTo directory. Applications can be
1257 symlinked into this directory by dragging them in with <keycap>Control</keycap>
1258 and <keycap>Shift</keycap> held down.
1260 Opening the Send To menu via the main menu is rather slow, so it is
1261 normally opened by clicking the Menu mouse button over a file while
1262 holding the <keycap>Shift</keycap> key down.
1269 <chapter id="icons">
1270 <title>The pinboard and panels</title>
1273 The <xref linkend="run_pin"/> and <xref linkend="run_pan"/> sections explain
1274 how to turn the pinboard and panels on. Once on, you may drop items from filer
1275 windows onto the them to pin them up. Clicking on a pinned item acts just like
1276 clicking on it in a filer window. You can drag pinned icons just like normal
1277 icons and you can right-click on one to see the popup menu.
1279 Drag panel icons with the middle mouse button to move them around.
1280 In previous versions of the filer, pinboard icons were also moved using the
1281 middle mouse button. This may still work (depending on your window manager),
1282 but using the left mouse button is now preferred.
1284 Changes to the pinboard and panel are automatically saved. Clicking on pinned
1285 icons with <keycap>Control</keycap> held down selects and unselects them.
1286 Click on the background to unselect them all.
1288 If the panel has so many icons that they can't all be shown at once
1289 then you can scroll it by dragging the blank area in the middle.
1293 Pinning a file does <emphasis>not</emphasis> copy it, it merely
1294 creates a shortcut to the original file. If you delete the file, then
1295 you've lost it! Removing a pinned file from its pinboard or panel
1296 only removes the link. This is different to most other filers...
1300 <title>The pinboard and panel menus</title>
1303 These menus are both the same, and very simple:
1306 <informaltable><tgroup cols="2">
1307 <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
1311 <guimenuitem>ROX-Filer</guimenuitem></entry><entry>
1312 Show the filer's help, edit the options or open your home directory.
1316 <guimenuitem>File `file'</guimenuitem></entry><entry>
1317 Offers a smaller version of the filer's submenu of the same name.
1321 <guimenuitem>Edit Item</guimenuitem></entry><entry>
1322 Change the name displayed under the icon, or the pathname the item
1327 <guimenuitem>Show Location</guimenuitem></entry><entry>
1328 Open a directory viewer showing where the file is stored.
1332 <guimenuitem>Remove Item(s)</guimenuitem></entry><entry>
1333 Remove the selected items from the pinboard or panel.
1336 </tbody></tgroup></informaltable>
1338 If you are setting up the defaults for multiple users and
1339 you wish to create a `Home' icon that leads to each user's home directory
1340 then you should first create a new icon and then use
1341 <guimenuitem>Edit Icon</guimenuitem> to change the location to
1342 <filename>~</filename> and the name to `Home'.
1344 Note that individual applications may add extra menu items to the
1345 top of this menu when you click over them — see <xref linkend="AppDir"/>
1351 <title>Panel applets</title>
1354 <application>ROX-Filer</application> allows you to run small programs
1355 inside the panel — such programs are called
1356 <emphasis>applets</emphasis>. To run an applet, drag it onto the panel from
1357 a filer window and instead of the applet's icon being shown, the applet
1361 <procedure><title>To create your own applets (programmers only!):</title>
1364 Create a directory for the applet (eg <filename>MyApplet</filename>).
1368 Put an icon called <filename>.DirIcon</filename> inside it (so the directory
1369 appears with an icon).
1373 Make a <filename>Help</filename> directory inside it for when the user chooses
1374 <guimenuitem>Help</guimenuitem> from the menu.
1378 Create an executable file called <filename>AppletRun</filename>. This will be
1379 passed the XID of the panel socket window when the directory is dragged
1380 onto the panel. You can use this to create a GtkPlug widget. An
1381 example applet (written in python) is available at
1382 <ulink url="http://rox.sourceforge.net/applets.php3"/>
1389 <chapter id="virtual">
1391 <anchor id="vfs" xreflabel="Virtual file systems"/>Virtual file systems
1395 Some types of file can be represented as a directory. A typical example
1396 is a zip file, which contains an entire directory structure in compressed
1397 form. It is often useful to be able to open up such a file as if it
1398 was a real directory, and the VFS system allows you to do this.
1400 <itemizedlist><title>To use this feature you must have one or both of the
1404 A system such as AVFS<citation>AVFS</citation> which causes the kernel to
1405 support various Virtual File Systems directly. This is the best option
1406 since all programs will be able to access the contents of the VFS. You
1407 may require root access to install such a system, however, and it is not
1408 available on all platforms.
1412 Support for the Midnight Commander VFS library compiled into
1413 <application>ROX-Filer</application>. This happens automatically when you
1414 compile <application>ROX-Filer</application> if it can find
1415 the VFS library — this means having <filename>libvfs.so</filename>
1416 (or <filename>libvfs.a</filename>) in a system library directory or in the
1417 directory in the environment variable <envar>LD_LIBRARY_PATH</envar>. In
1418 this case, you will be able to view the directory structure and copy
1419 files out of it, but not change it.
1423 When using libvfs, the menu structure is slightly different —
1424 <guimenuitem>Open AVFS</guimenuitem> is replaced by the <guisubmenu>Open
1425 VFS</guisubmenu> submenu. This is simply a short-cut for using the
1426 path-entry box (explained below), so if you want to use a VFS not listed
1427 on the menu you can type in the path directly, eg:
1428 <filename>/home/fred/archive.zip#uzip/</filename>.
1430 Don't forget the final slash!
1432 Use of libvfs is strongly discouraged; use AVFS instead. Recent versions
1433 of the library don't compile properly, and it can't be used on many
1434 systems because it conflicts with large file support.
1443 <chapter id="minibuffer">
1444 <title><anchor id="mini" xreflabel="Minibuffer"/>The mini-buffer</title>
1447 The mini-buffer is a white bar that appears along the bottom of the
1448 window and allows you to enter some text. Press <keycap>Escape</keycap> to
1449 get rid of it again. It behaves in different ways depending on how you
1454 <title>The path-entry box</title>
1457 This allows you to type in a path directly. As you type the display
1458 is updated to show the item entered visually. The main use is to find
1459 a file in a large directory quickly, but you can also use it for navigating
1460 between directories, or for selecting a full pathname from somewhere
1461 else and pasting it directly into the path-entry box.
1464 <informaltable><tgroup cols="2">
1465 <thead><row><entry>Key</entry><entry>Action</entry></row></thead>
1469 <keycap>Return</keycap></entry><entry>
1470 Open the currently selected item.
1474 <keycap>Tab</keycap></entry><entry>
1475 Shell-style tab completion.
1479 <keycap>Up</keycap>, <keycap>Down</keycap></entry><entry>
1480 Select the previous/next matching entry.
1482 </tbody></tgroup></informaltable>
1487 If you start entering a name beginning with a `.' then the `Show Hidden'
1488 feature is temporarily turned on so that the file can be shown.
1492 Tab completion tries to fill in as many characters for you as it can.
1493 For example, if there are two files in a directory called `save-mail-nov-1999'
1494 and `save-mail-dec-1999' then typing 'save' and pressing
1495 <keycap>Tab</keycap> will expand `save' to `save-mail-' and beep to
1496 indicate that the match is not complete. If you use tab completion on a
1497 directory and it is unique then the filer will automatically change into
1498 the directory. This behavior should be familiar to shell users.
1501 <informalexample><para>
1502 Let's say you want to locate the documentation for Wine in the directory
1503 <filename>/usr/doc</filename> (which is usually very large).
1504 Here's how you could do it:
1509 Open the minibuffer by choosing <guimenuitem>Enter Path...</guimenuitem> from the
1510 <guimenu>Window</guimenu> menu.
1511 I usually bind this function to the slash (<keycap>/</keycap>) key.
1515 Press <keycap>CTRL</keycap>+<keycap>U</keycap> to delete the existing contents
1516 — this moves you to the root directory.
1520 Type <userinput>u<Tab>do<Tab>wi<Tab></userinput>.
1521 As you type, the cursor will move to the correct subdirectory.
1522 If it beeps when you press Tab then you need to supply more letters.
1527 </para></informalexample>
1531 <title>The shell command box</title>
1534 This provides a quick way of entering shell commands if you don't
1535 want to open an xterm. If you don't know what shell commands are,
1538 Just type in the command and press <keycap>Return</keycap> to execute it.
1539 <keycap>Up</keycap> and <keycap>Down</keycap> arrows move through previously
1541 <keycap>Tab</keycap> does shell-style completion.
1542 Clicking on an item inserts its name into the minibuffer.
1543 If some items are selected then they are assigned to the positional
1544 parameters <userinput>$1</userinput>, <userinput>$2</userinput>, etc.
1546 Opening the minibuffer with a selection adds <computeroutput>$@</computeroutput>
1547 to the end of the command — this expands to all the selected files.
1550 <informalexample><para>Examples:
1552 <orderedlist><title>To untar a <filename>.tgz</filename> archive:</title>
1555 Open the minibuffer by choosing <guimenuitem>Shell Command...</guimenuitem> from
1556 the <guimenu>Window</guimenu> menu.
1557 I usually bind this to the bang (<keycap>!</keycap>) key.
1561 Type <userinput>tar xzf</userinput> and click on the file.
1562 The leading space is automatically inserted.
1566 Press <keycap>Return</keycap> to execute it.
1571 <orderedlist><title>To print all the selected files:</title>
1574 Open the shell command minibuffer.
1578 Type <userinput>lpr</userinput> at the beginning of the line and press
1579 <keycap>Return</keycap>.
1584 </para></informalexample>
1586 <itemizedlist><title>Notes</title>
1589 Be careful; you will not be asked to confirm! If in doubt, start the
1590 command with <userinput>xmessage</userinput> so that it will be displayed
1591 rather than executed.
1595 <citerefentry><refentrytitle>sh</refentrytitle></citerefentry>
1596 is always used as the name of the shell to run (mainly because
1597 <citerefentry><refentrytitle>bash</refentrytitle></citerefentry> and
1598 <citerefentry><refentrytitle>csh</refentrytitle></citerefentry> treat
1599 positional parameters differently).
1600 However, <envar>PATH</envar> is searched to find it so you can still use
1601 another shell if you want by naming it sh and putting it in your path.
1605 Commands execute in the background, so you can say:
1607 <command>sleep 240; xmessage Time to go!</command>
1614 <title><anchor id="SelectIf" xreflabel="Select If"/>The conditional
1615 selection box</title> <para>
1617 Use this if you want to automatically select all files in the directory
1618 which match a condition.
1620 <orderedlist><title>For example, to select all files larger than 5Mb:</title>
1623 Open the Select If minibuffer.
1627 Type <userinput>Size > 5Mb</userinput> and press <keycap>Return</keycap>.
1632 Just those files over 5 Mb in size will be selected. The expressions
1633 you can enter are in the same form as described in the
1634 <xref linkend="Searching"/> section, except that
1635 <userinput>prune</userinput> has no effect since the contents of
1636 directories are never checked anyway. You can press <keycap>Tab</keycap>
1637 to jump to each selected file in turn.
1643 <chapter id="actions">
1644 <title>Action windows</title>
1646 Action windows are those boxes that appear while you're doing a
1647 Copy/Move/Link/etc operation. The status line at the top of the window shows
1648 the current directory or object that the window is processing. The scrolling
1649 area below is the log area — it shows what has been done, and questions
1650 may be displayed here.
1653 <imagedata align="center" format="PNG" fileref="../Action.png"/>
1655 <textobject><para>Can't display image.</para></textobject>
1658 Below this are four buttons and some options. All windows have the
1659 <guilabel>Quiet</guilabel> option. When this is on the filer will only
1660 confirm some operations (such as deleting a non-writeable file). Otherwise,
1661 all operations are confirmed.
1663 The buttons work as follows:
1667 <varlistentry><term><guibutton>Yes</guibutton></term><listitem><para>
1668 answers yes to the question displayed in the log area.
1669 </para></listitem></varlistentry>
1671 <varlistentry><term><guibutton>No</guibutton></term><listitem><para>
1672 answers no to the question displayed in the log area.
1673 </para></listitem></varlistentry>
1675 <varlistentry><term><guibutton>Abort</guibutton></term><listitem><para>
1676 kills the current operation (if any) and closes the action
1678 </para></listitem></varlistentry>
1680 <varlistentry><term><guibutton>Quiet</guibutton></term><listitem><para>
1681 is a quick way to turn <guilabel>Quiet</guilabel> on and click
1682 <guibutton>Yes</guibutton>.
1683 </para></listitem></varlistentry>
1688 You can control which actions get started automatically (without you
1689 having to click on <guibutton>Quiet</guibutton> at the start) from the
1694 <title>Action window options</title>
1697 Some actions have options, which appear as option boxes at the bottom
1698 of the window. They are:
1703 <guilabel>Force</guilabel> means that the filer won't treat non-writeable
1704 files as special. Normally, it confirms the deletion even if
1705 <guibutton>Quiet</guibutton> is pressed.
1706 Note that you still can't remove files from non-writeable directories because
1707 in that case you really don't have permission.
1711 <guilabel>Brief</guilabel> prevents the filer logging a message every time it
1712 does something. Use this to speed things up if large numbers of messages are
1717 <guilabel>Recurse</guilabel> means that doing something to a directory will
1718 also do the same thing to all its contents, and the contents of any
1719 subdirectories, and so on.
1728 <chapter id="searching">
1729 <title><anchor id="Searching" xreflabel="Searching"/>Searching</title>
1732 The Find feature looks through all the selected files and directories
1733 and any subdirectories (recursively) looking for items that match
1734 a particular expression.
1736 If you know the name of a file then just enter it in the `Expression:'
1737 box, enclosed in single quotes. For example, to find a file called
1738 <filename>log</filename> you would enter <userinput>'log'</userinput>.
1740 Remember to use normal quotes, not double quotes (") or back-quotes (`).
1742 As the filer finds matching files they are added to the results list.
1743 Clicking on an entry in the list opens a viewer showing the file you
1744 clicked on. The filer will use the same window to view other results
1745 (so, if you want the results shown in separate windows you must explicitly
1746 create a new window from the <guimenu>Window</guimenu> menu).
1750 <title>Wildcards</title>
1753 You can also put shell-style wildcard characters inside the quotes,
1758 <member><command>'*.html'</command></member>
1759 <member><command>'Report.*'</command></member>
1760 <member><command>'Draft[1-5]'</command></member>
1761 <member><command>'main.[ch]'</command></member>
1766 <citerefentry><refentrytitle>glob</refentrytitle>
1767 <manvolnum>7</manvolnum></citerefentry>
1768 manpage if you want to know more about shell wildcards.
1770 If the pattern you enter contains a slash (`/') character then the
1771 pattern is matched against the file's full path, otherwise only the
1772 leafname is used. That is, <userinput>'*tmp*'</userinput> will find
1773 <filename>tmp</filename> and <filename>tmpfile</filename> but not
1774 <filename>/tmp/file</filename> — <userinput>'/*tmp*'</userinput> will find
1780 <title>Simple tests</title>
1782 As well as finding files by their names you can also find them by
1783 various other attributes. Note that <emphasis>file</emphasis> is used here to
1784 mean anything that can appear in the filesystem — including directories,
1787 You can also use a short form for each test; these are shown in brackets.
1788 You can combine multiple tests — `<userinput>-rw</userinput>' is
1789 the same as `<userinput>IsReadable and IsWriteable</userinput>'.
1792 <itemizedlist><title>These look at the type of the item being checked:</title>
1795 <userinput>IsReg (-f)</userinput> matches any regular (ie, normal) file.
1799 <userinput>IsLink (-l)</userinput> matches symlinks.
1803 <userinput>IsDir (-d)</userinput> matches directories.
1807 <userinput>IsChar (-c)</userinput> matches character device files.
1811 <userinput>IsBlock (-b)</userinput> matches block device files.
1815 <userinput>IsDev (-D)</userinput> matches block or character device files.
1819 <userinput>IsPipe (-p)</userinput> matches pipes.
1823 <userinput>IsSocket (-S)</userinput> matches sockets.
1828 <itemizedlist><title>These look at the permissions set on the file —
1829 see the <xref linkend="Permissions"/> section.</title>
1832 <userinput>IsSUID (-u)</userinput> matches files which have the Set-UID
1833 bit set.</para></listitem>
1836 <userinput>IsSGID (-g)</userinput> matches files which have the Set-GID
1837 bit set.</para></listitem>
1840 <userinput>IsSticky (-k)</userinput> matches files with the sticky bit
1841 set.</para></listitem>
1844 <userinput>IsReadable (-r)</userinput> matches files which you can read
1845 from.</para></listitem>
1848 <userinput>IsWriteable (-w)</userinput> matches files which you can write to.
1852 <userinput>IsExecutable (-x)</userinput> matches files which you can execute.
1857 <itemizedlist><title>And a couple of other useful ones:</title>
1860 <userinput>IsEmpty (-z)</userinput> finds empty files (ie, those whose
1865 <userinput>IsMine (-o)</userinput> finds files which you own.
1873 <title>Logic operators</title>
1875 You can combine the above tests in various ways to perform more advanced
1877 An expression is actually made up of a list of <emphasis>cases</emphasis>,
1878 separated by commas. The filer will try to match each case in turn
1879 until one matches or there are no more cases left. For example, to
1880 search for files with several possible endings:
1882 <screen>'*.gif', '*.htm', '*.html'</screen>
1884 Further, each of the cases is actually a list of conditions. The case
1885 only matches if all of its conditions are met. So, to find a directory
1886 called <filename>lib</filename> or a regular file ending in
1887 <filename>.so</filename>:
1889 <screen>IsDir 'lib', IsReg '*.so'</screen>
1891 You can negate a condition by putting a <userinput>!</userinput> in front
1892 of it and you can use a sub-expression as a condition by bracketing it,
1900 Not isdir and not isreg
1903 All four do the same thing.
1908 <title>Comparisons</title>
1910 You can also compare various values using the operators
1911 <userinput><</userinput>,
1912 <userinput><=</userinput>,
1913 <userinput>=</userinput>,
1914 <userinput>!=</userinput>,
1915 <userinput>></userinput>, and
1916 <userinput>>=</userinput>
1917 (for less-than, less-than-or-equal-to, equal-to,
1918 not-equal-to, greater-than and greater-than-or-equal-to).
1920 When comparing times, you may find it helpful to use
1921 <userinput>after</userinput> and <userinput>before</userinput> instead of
1922 <userinput>></userinput> and <userinput><</userinput> to make things
1926 <itemizedlist><title>
1927 The following are read from the file being checked and may be used
1928 for the values being compared:
1932 <userinput>atime</userinput> The time that the file was last accessed.
1936 <userinput>ctime</userinput> The time that the file's status was last changed.
1940 <userinput>mtime</userinput> The time that the file's contents were last modified.
1944 <userinput>size</userinput> The size of the file.
1948 <userinput>inode</userinput> The file's inode (index) number.
1952 <userinput>nlinks</userinput> The number of links to this file. That is,
1953 the number of directory entries which refer to this file. Note that
1954 symlinks don't count as references.
1958 <userinput>uid</userinput> The User ID of the file.
1962 <userinput>gid</userinput> The Group ID of the file.
1966 <userinput>blocks</userinput> The number of disk blocks being used by the file.
1972 Times are measured as seconds since the Unix Epoch (00:00:00 UTC,
1973 January 1, 1970). Sizes are in bytes. When specifying constants to
1974 compare these values with you may use various keywords to scale the
1980 <userinput>Byte(s)</userinput> has no effect, but looks better.
1984 <userinput>Kb</userinput> multiplies by 1024, so 2Kb is the same as 2048.
1988 <userinput>Mb</userinput> multiplies by 1024<superscript>2</superscript>,
1993 <userinput>Sec(s)</userinput> has no effect, but looks nice.
1997 <userinput>Min(s)</userinput> multiplies by 60 to get minutes.
2001 <userinput>Hour(s), Day(s), Week(s), Year(s)</userinput> likewise
2002 convert to the relevant unit.
2006 <userinput>Ago</userinput> makes the time in the past relative to when
2011 <userinput>Hence</userinput> makes the time in the future.
2015 <userinput>Now</userinput> is short for <userinput>0 Secs Hence</userinput>.
2020 Some examples should make this all a bit clearer!
2023 mtime after 1 day ago
2027 IsReg and nlinks > 1</screen>
2028 The first finds files modified within the last 24 hours. You could
2029 use <userinput>></userinput> instead of <userinput>after</userinput>,
2030 but it's not so clear what is meant.
2032 The second finds files larger than 10 Mb. The last finds regular files with
2033 more than one directory entry.
2035 Be careful though — the filer doesn't check the context of the
2036 modifiers, so <userinput>size > 1 day ago</userinput> is allowed,
2037 although it doesn't make much sense!
2039 Also, forgetting to use <userinput>ago</userinput> or
2040 <userinput>hence</userinput> will cause odd effects (the time will be
2041 measured relative to the Epoch rather than the current time).
2042 Finally, don't use <userinput>=</userinput> with times —
2043 <userinput>atime = 1 day ago</userinput> looks for a file accessed
2044 <emphasis>exactly</emphasis> 86400 seconds ago...
2050 <title>Specials</title>
2056 <userinput>System(Command)</userinput> executes `Command' on the file.
2057 The test succeeds if the command returns an exit status of zero. A `%'
2058 character in `Command' is replaced by the full path of the file being
2059 checked. <userinput>System</userinput> is a very slow test to perform,
2060 so do it last if possible. For example, if you're looking for a
2061 <filename>.c</filename> file containing the word `main', do:
2063 <screen>'*.c' system(grep -q main "%")</screen>
2064 so that the grep is only performed for files ending in <filename>.c</filename>
2065 (as opposed to only checking that the file ends in <filename>.c</filename> if
2066 it contains the word `main').
2070 <userinput>Prune</userinput> Always fails!
2071 <footnote><para>Note that this is the opposite of the
2072 <citerefentry><refentrytitle>find</refentrytitle><manvolnum>1</manvolnum>
2073 </citerefentry> command.</para></footnote>
2075 However, if it gets evaluated at all then it prevents the filer
2076 from checking inside the current directory. Remember the order in which
2077 the filer checks the expression!
2085 '*.old' system(rm '%')
2087 'src' prune, '*.c'</screen>
2088 The first deletes each file ending in <filename>.old</filename>.
2089 The second looks for <filename>.c</filename> files, but does not bother
2090 checking inside directories called <filename>src</filename>.
2091 The expression is evaluated like this:
2093 If file is named <filename>src</filename> then `Prune'.
2094 Either way, check if it ends in <filename>.c</filename> and include
2095 it in the results if so.
2100 <chapter id="options">
2101 <title>Options</title>
2104 You can configure various aspects of <application>ROX-Filer</application>
2105 from the Options box.
2106 Choose <guimenuitem>Options...</guimenuitem> from a filer window menu to
2109 At the bottom of the window are four buttons:
2114 <guibutton>Save</guibutton>
2115 puts all your choices into effect, and also saves them into
2116 your Choices directory for next time <application>ROX-Filer</application> is
2117 loaded. <application>ROX-Filer</application> will never save any preferences to
2118 disk unless you click on the <guibutton>Save</guibutton> button in the options
2119 window. Exactly where choices are loaded from and saved to is controlled by
2120 the <envar>CHOICESPATH</envar> environment variable — see
2121 <citation>Choices</citation> for details.
2125 <guibutton>OK</guibutton>
2126 puts your choices into effect without writing anything to disk.
2130 <guibutton>Apply</guibutton>
2131 works like <guibutton>OK</guibutton>, but without closing the Options window.
2135 <guibutton>Cancel</guibutton>
2136 closes the options box and forgets any changes you made.
2141 Many of the options in the Options window have tooltips — hold the
2142 mouse pointer over the option to find out what it does.
2147 <title>Translation options</title>
2150 You can choose which language the filer will display messages in from
2151 here, or get it to read the LANG environment variable to get the desired
2158 <title>Display options</title>
2162 <listitem><para><guilabel>Ignore case when sorting</guilabel>
2163 treats upper and lower case letters as
2164 equivalent when sorting. If this is off then <filename>Zoo</filename> comes
2165 before <filename>animal</filename>, for example.
2168 <listitem><para><guilabel>Directories always come first</guilabel> means that
2169 all directories are sorted and displayed at the top, then all the other items
2170 are sorted and displayed below. With this option off, directories are mixed in
2171 with the other files.
2174 <listitem><para><guilabel>Large wrap width</guilabel> sets the maximum width
2175 for a file's name in `Large Icons' display mode before the text will wrap onto
2176 two lines. In `Huge Icons' mode, the wrap width is 50% larger than this value.
2179 <listitem><para><guilabel>Max Small Icons width</guilabel> — in
2180 `Small Icons' mode, any text longer than this is chopped off (a red bar
2181 indicates that some text is not shown). You can hold the mouse over the
2182 truncated name to see the full text.
2185 <listitem><para><guilabel>Inherit options from source window</guilabel>
2186 controls what happens when you open a new window from an existing window
2187 (eg, by clicking the middle button over a directory). If on, the new window
2188 has the same options (icon size, sort order, etc) as the old window. If
2189 off, the new window has the default options.</para></listitem>
2191 <listitem><para><guilabel>Default settings for new windows</guilabel>.
2192 The remaining options provide the default settings for newly opened
2193 windows — they correspond to choosing styles from the
2194 <guimenuitem>Display</guimenuitem> menu.
2202 <title>Pinboard options</title>
2205 If you are using the pinboard features (see the <xref linkend="run_pin"/>
2206 section) then you can choose how the text under each icon is displayed. If
2207 you have a fairly uniform background then you may like to choose <guilabel>No
2208 background</guilabel>, which simply draws the text directly over the desktop
2209 background. However, users with more `noisy' backdrops may find such
2210 text hard to read; selecting <guilabel>Rectangular background slab</guilabel>
2211 will draw a solid rectangle behind the text to make it easier to read.
2212 When using Gtk+-2.0, this option has no effect.
2214 You may also change the foreground and background colours used for
2215 the text by clicking on the colour slabs in the Options window.
2219 <listitem><para> <guilabel>Single-click to open</guilabel>
2220 allows you to open a file or directory just by clicking on it. Hold down
2221 <keycap>Control</keycap> to select things. If this is off, clicking selects
2222 and double-clicking opens.
2225 <listitem><para><guilabel>Keep icons within screen limits</guilabel>
2226 prevents icons from going partly off the side of the screen.
2229 <listitem><para> <guilabel>Icon grid step</guilabel> controls how finely
2230 the icons may be positioned.</para></listitem>
2238 <title>Panel options</title>
2241 If you are using panels (see the <xref linkend="run_pan"/> section)
2242 then this section lets you choose which icons will have textual labels
2244 You can have labels on all icons, on no icons, or on all icons except
2251 <title>Action window options</title>
2254 You can choose to start some operations automatically, without waiting
2255 for you to click on <guibutton>Quiet</guibutton>.
2256 Select each operation that you want to
2257 auto-start here. You can also set the default state for each of the
2258 options that appear inside action windows.
2264 <title>Toolbar options</title>
2266 The toolbar is described in the <xref linkend="Toolbar"/> section.
2268 <listitem><para> <guilabel>Unshade the tools you want:</guilabel> allows
2269 you to set which tools should appear on the toolbar. Click on the
2270 buttons below to shade and unshade them — shaded tools will not be
2271 shown on filer window toolbars.
2274 <listitem><para> <guilabel>Toolbar type</guilabel> allows you to choose
2275 what kind of toolbars you want.
2276 <guimenuitem>None</guimenuitem> means that windows will not have a
2278 <guimenuitem>Normal</guimenuitem> provides a small bar of icons, and
2279 <guimenuitem>Large</guimenuitem> displays larger buttons, with textual labels.
2282 <listitem><para> <guilabel>Show totals of items</guilabel> shows the
2283 number of items displayed in a filer window, as well as the number of
2284 hidden items (if any) on the toolbar. When there's a selection, it
2285 shows the number of selected items and their combined size (excluding
2295 <title>Filer window options</title>
2299 <listitem><para><guilabel>Automatically resize filer windows</guilabel> can be
2300 used to control when windows are automatically resized:
2303 <listitem><para><guilabel>...never</guilabel>
2304 turns off auto-resizing. Windows must be
2308 <listitem><para><guilabel>...when changing the display style</guilabel>
2310 window automatically when you change the icon size or the type of
2311 details to be displayed.
2314 <listitem><para><guilabel>...always</guilabel>
2315 causes the window to resize whenever it
2316 seems useful (that is, when changing to a different directory or when
2317 switching between display styles).
2323 <listitem><para> <guilabel>Window size limit</guilabel> sets the largest size
2324 (as a percentage of the screen size) that the auto-resizer will resize windows
2328 <listitem><para> <guilabel>Unique windows</guilabel> prevents you from having
2329 two windows showing the same directory. Opening a second view onto a directory
2333 <listitem><para> <guilabel>New window on button 1</guilabel> swaps the
2334 actions of the two non-menu buttons when opening directories. This is
2335 provided for people who are used to the RISC OS mouse bindings.
2338 <listitem><para> <guilabel>Single-click navigation in filer windows</guilabel>
2339 means that clicking on a file or directory will open it. If off, clicking on
2340 files selects them instead — you must double click on a file to open it.
2345 The next two options control what happens when you press <keycap>Tab</keycap>
2346 in the path entry minibuffer:
2350 <listitem><para> <guilabel>Beep if Tab-completion fails</guilabel> — beep
2351 if there is no match, or there are several possible completions, each starting
2355 <listitem><para> <guilabel>Beep if there are several matches</guilabel> —
2356 beep if there are several matches, even though some letters were added.
2365 <title>Drag-And-Drop options</title>
2369 <listitem><para><application>ROX-Filer</application> uses the standard
2370 XDND protocol for drag-and-drop. This protocol recommends that URIs
2371 should contain the hostname of the computer that the resource is on so
2372 that the program receiving the data can determine whether it can get the
2373 data directly or whether it must go via the X-server. However, many
2374 older programs (particularly GNOME applications) get confused by the
2375 hostname and fail to load the data correctly. If <guilabel>Don't use
2376 hostnames</guilabel> is on then the hostname part is omitted and
2377 <application>ROX-Filer</application> will work with these applications
2378 BUT you can't drag data to a program running on a different machine.
2381 <listitem><para><guilabel>Allow dragging to icons in filer
2382 windows</guilabel> controls what happens when you drop files onto icons
2383 in filer windows. If on then drops onto directories will save the data
2384 inside the directory, while dropping onto programs will invoke the
2385 program on that data. If off then drops anywhere inside a filer window
2386 act like drops onto the window background — that is, the data will
2387 be saved into the directory being displayed.
2390 <listitem><para><guilabel>Directories spring open</guilabel> controls what
2391 happens when you hold a file over a directory while dragging it. If on,
2392 the directory will `spring open' after a short pause, allowing you to
2393 navigate to any directory during a drag. You can also hold the pointer
2394 over the Home and Up buttons on the toolbar for a similar effect. You
2395 need to have the previous option enabled for this to have any effect on
2396 files displayed in a directory.
2399 <listitem><para><guilabel>Spring delay</guilabel> sets how long, in
2400 thousanths of a second, the filer will wait before spring opening a
2401 directory as described above. If the above option is turned off, then
2405 <listitem><para><guilabel>Dragging files with the middle mouse button...</guilabel>
2406 you can choose whether this displays a menu (like <keycap>Alt</keycap>
2407 dragging) or moves the files (like <keycap>Shift</keycap> dragging).
2416 <title>Menu options</title>
2421 <listitem><para><guilabel>Xterm here program</guilabel> is the command
2422 used when you choose <guimenuitem>Xterm here</guimenuitem> from the
2423 menu. You can replace it with another command such as
2424 <command>gnome-terminal</command>, <command>konsole</command>, or
2425 anything else.</para></listitem>
2427 <listitem><para><guilabel>Size of icons in menus</guilabel> controls the
2428 size of the icons in the <guimenuitem>Send To</guimenuitem> and
2429 <guimenuitem>New</guimenuitem> menus.</para></listitem>
2431 <listitem><para><guilabel>Menu on button 2</guilabel> swaps the actions
2432 of buttons 2 and 3 so that the middle button brings up the menus. This
2433 is provided for people who are used to the RISC OS mouse bindings.
2435 As an alternative to using the options window to put menu on button-2,
2436 some people prefer to use the command <command>xmodmap -e "pointer
2437 = 1 3 2"</command>, which makes the right mouse button button-2 and
2438 the middle one button-3 (this affects all programs, not just
2439 <application>ROX-Filer</application>).
2447 <title>Types</title>
2450 <listitem><para><guilabel>Ignore eXecutable bit for known
2451 extensions</guilabel> means that when a file has a known extension (eg
2452 <filename>.gif</filename>) the executable bit is ignored. This is useful
2453 if you have files on a Windows-type filesystem which are being shown as
2454 executable programs. However, it prevents a file such as
2455 <filename>script.sh</filename> from being treated as a program.
2458 <listitem><para><guilabel>Colour files based on their types</guilabel>.
2459 If on, each file's name is coloured depending on what kind of thing it is
2460 (regular file, directory, executable, etc). You can choose the colours from
2466 The MIME type system used in the filer is described more fully in
2467 <xref linkend="types"/>.
2469 <listitem><para><guibutton>Show name-to-type rules</guibutton>
2470 opens the directories containing the files which tell the filer what
2471 type to give each file.</para></listitem>
2473 <listitem><para><guibutton>Re-read files</guibutton> causes the filer to
2474 reread these files after you've finished changing them.
2482 <chapter id="types">
2483 <title>Filetypes</title>
2486 All files have a MIME type in the form <emphasis>text/plain</emphasis>. Here,
2487 <emphasis>text</emphasis> is the <emphasis>media type</emphasis> and
2488 <emphasis>plain</emphasis> is the <emphasis>sub-type</emphasis>.
2490 <application>ROX-Filer</application> uses a file's name to decide what its MIME
2491 type is, and then uses the MIME type to decide what icon to give it and what
2492 program to use when you open the file.
2496 <title><anchor id="RunAction" xreflabel="the Set Run Action box"/>
2501 This box appears when you choose <guimenuitem>Set Run Action...</guimenuitem>
2502 from the File menu, and is used to set which application is loaded when you click
2505 For example, let's say you want to set things up so that opening a
2506 <filename>.gif</filename> file loads it into the Gimp.
2507 First, right-click over a gif image to open the menu and choose
2508 <guimenuitem>Set Run Action...</guimenuitem> from the
2509 <guimenuitem>File</guimenuitem> submenu.
2510 Then, you have a choice of two methods to set the run action:
2513 <sect2><title>Setting the run action by drag-and-drop</title>
2515 Drag the Gimp (from a filer window, a panel or the pinboard) onto
2516 the area marked <guilabel>Drop a suitable application here</guilabel>.
2517 From now on, clicking on a GIF file will load it into the Gimp.
2521 <sect2><title>Setting the run action by entering a shell command</title>
2523 Type: <userinput>gimp "$1"</userinput>
2524 into the box labelled <guilabel>Enter a shell command</guilabel> and press
2525 <keycap>Return</keycap>. <userinput>$1</userinput>
2526 will be replaced by the name of the file you click on when this command
2527 is used. As before, clicking on any GIF image will now load it into
2532 <sect2><title>Setting the default media-type handlers</title>
2534 Whichever method you use to set the action you have the choice of
2535 setting the run action just for that type, or setting the default
2536 for all files with that media-type which don't already have a specific
2539 Since the Gimp can load many types of image, it makes sense
2540 to select the <guilabel>Set default for all `image/<anything>'</guilabel>
2541 option so you don't have to do it again for image/jpeg files and so on. However,
2542 this only affects types that don't already have a specific action
2543 (ie, those that would have brought up an error box if you tried to
2550 <title><anchor id="SetIcon" xreflabel="the Set Icon box"/>
2555 This box appears when you choose <guimenuitem>Set Icon...</guimenuitem>
2556 from the File menu, and is used to set which image to use to represent
2559 It works much like the Set Run Action box described above, except that
2560 you may specifiy an icon for one file individually (by name) as well as
2561 for all files of a particular type.
2563 The directory icon inside the <guilabel>Drop an icon here</guilabel>
2564 area allows you to quickly get to a directory from which you are already
2565 using one or more icons.
2570 <title>How filetypes are stored</title>
2573 <application>ROX-Filer</application> uses three sub-directories in your Choices
2574 directory for filetypes:
2578 <varlistentry><term><filename>MIME-info</filename></term><listitem><para>
2579 contains files which specify what the MIME types for files
2580 should be, based on their extentions. All the files in all the
2581 <filename>MIME-info</filename> directories are scanned when the filer loads.
2582 <application>ROX-Filer</application> comes with a file containing many such
2583 rules — this is installed into the <filename>MIME-info</filename>
2584 directory by the rox-base package.
2586 Many applications now come with a file called
2587 <filename>something.mime</filename>; copy these files into your
2588 <filename>MIME-info</filename> directory to make
2589 <application>ROX-Filer</application> automatically recognise the new extensions.
2590 ROX-Filer doesn't automatically re-read these files when they change. You can
2591 either restart the filer, or click on the <guibutton>Re-read files</guibutton>
2592 button in the <guilabel>Types</guilabel> section of the Options box.
2593 </para></listitem></varlistentry>
2595 <varlistentry><term><filename>MIME-types</filename></term><listitem><para>
2596 contains symlinks, one for each MIME type, which point
2597 to programs that can handle files of that type. To set what program
2598 is run when you click on the file you should normally use the <guimenuitem>Set
2599 Run Action...</guimenuitem> feature (see the <xref linkend="RunAction"/> section).
2600 However, you can also set the actions manually — for example, to make
2601 opening an HTML file load it into Netscape:
2605 Find the Netscape application and go to <guimenuitem>Link...</guimenuitem>
2610 Enter <userinput>text_html</userinput> as the name for the link and drag the
2611 icon from the Link box into the <filename>MIME-types</filename> directory.
2616 You can also put actual programs in here as well as links if you want
2618 </para></listitem></varlistentry>
2620 <varlistentry><term><filename>MIME-icons</filename></term><listitem><para>
2621 contains the images used to display each type of file.
2622 So the filer will try to display an HTML file using the icon
2623 <filename>MIME-icons/text_html.xpm</filename>.
2624 </para></listitem></varlistentry>
2628 In both <filename>MIME-types</filename> and <filename>MIME-icons</filename>
2629 directories you can also provide default actions/images for each media type.
2630 For example, if <filename>text_html</filename> isn't found then the filer
2631 will try simply using <filename>text</filename>.
2637 <chapter id="appdirs">
2638 <title><anchor id="AppDir" xreflabel="Application directories"/>
2639 Application directories
2642 An application directory is a directory which can be run as an application.
2643 It contains all the resources of an application — source code, binaries,
2644 documentation and so on. Keeping everything in one place make installation
2645 and uninstallation much easier for users. You can also keep multiple
2646 versions of a program by simply having several application directories.
2647 You may move and rename them as you please. Application directories
2648 make programs easier to use and install.
2650 They're more secure too, because you can compile an application as a user and
2651 then simply copy it as root. Since you don't have to run an install script
2652 you are free from the danger of running untrusted code as root. All you have
2653 to watch out for is setuid binaries.
2656 The following files are treated as special by
2657 <application>ROX-Filer</application>:
2662 <filename>AppRun</filename>
2663 is executed when you click on the directory — make sure
2664 it is executable (use the Permissions box)!
2668 <filename>.DirIcon</filename>
2669 is the image used to represent the directory (this works even if
2670 there is no <filename>AppRun</filename>).
2674 <filename>Help</filename>
2675 is the directory to be opened when you choose <guimenuitem>Help</guimenuitem>
2680 <filename>AppInfo.xml</filename>
2681 contains extra information about an application (see below).
2685 <filename>AppIcon.xpm</filename>
2686 is used if <filename>.DirIcon</filename> is missing (for backwards
2692 Have a look at the <filename>ROX-Filer</filename> application directory for a
2697 <note><para>For security reasons, an application directory must have the
2698 same owner as the <filename>AppRun</filename> file inside.</para></note>
2701 <title>The AppInfo file</title>
2704 <filename>AppInfo.xml</filename> is an XML file with the following structure
2705 (any elements may be omitted, and the file itself is optional):
2708 <?xml version="1.0"?>
2710 <Summary>A graphical file manager</Summary>
2712 <Purpose>File manager</Purpose>
2713 <Version>1.1.3 (07-May-2001)</Version>
2714 <Authors>Thomas Leonard and others</Authors>
2715 <License>GNU General Public License</License>
2716 <Homepage>http://rox.sourceforge.net</Homepage>
2719 <Item label="Enable pinboard" option="-p=Default"/>
2720 <Item label="Disable pinboard" option="-p="/>
2722 </AppInfo></screen>
2727 <userinput>Summary</userinput>
2728 is displayed in a tooltip when the mouse is held over the application.
2732 <userinput>About</userinput>
2733 contains a list of fields which are shown in the `File Info'
2734 box for the application (any element names may be used, but the above
2739 <userinput>AppMenu</userinput>
2740 is a list of extra menu items to display for the application.
2741 When one is chosen, <filename>AppRun</filename> is called with
2742 <userinput>option</userinput> as its only argument. You can nest
2743 AppMenus inside other AppMenus.
2753 <title>Internationalisation</title>
2759 <title><anchor id="LANG" xreflabel="Translations"/>
2760 Selecting a translation
2764 <application>ROX-Filer</application> is able to translate many of its messages,
2765 provided suitable translation files are provided:
2768 <listitem><para>Open the Options box from the menu,</para></listitem>
2769 <listitem><para>Select a language from the menu at the top,</para></listitem>
2770 <listitem><para>Click on <guibutton>Save</guibutton> and restart the filer
2771 for the new setting to take full effect.</para></listitem>
2778 <title>Creating a new translation</title>
2782 <listitem><para>Go into the <filename>src</filename> directory and create
2783 the file <filename>messages.pot</filename>:
2787 $ make messages.pot</screen>
2791 <listitem><para>Copy the file into the <filename>po</filename>
2792 subdirectory under <filename>src</filename> as
2793 <filename><name>.po</filename>. Eg, if your
2794 language is referred to as `ml' (`my language'):
2796 <screen>$ cp messages.pot po/ml.po</screen>
2799 <listitem><para>Load the copy into a text editor.</para></listitem>
2801 <listitem><para>Fill in the translations, which are all blank to start with.
2804 <listitem><para>Run the <filename>make-mo</filename> script to create the
2805 binary file which <application>ROX-Filer</application> can use.
2806 You will need the GNU gettext package for this.
2807 If you don't have it then just send me the <filename>.po</filename> file
2808 and I'll convert it for you.
2811 $ cd ROX-Filer/src/po
2813 Created file ../../Messages/ml.gmo OK</screen>
2816 <listitem><para>Edit <filename>ROX-Filer/Options.xml</filename> so that
2817 your language is listed, restart the filer and select it from the Options box
2818 (see the <xref linkend="LANG"/> section).
2821 <listitem><para>Submit the <filename>.po</filename> file to me so that I
2822 can include it in future releases of the filer.
2830 <title>Updating an existing translation</title>
2834 <listitem><para>Go into the directory containing the <filename>.po</filename>
2835 files and run the <filename>update-po</filename> script.
2836 This checks the source code for new and changed strings and updates all
2837 the translation files.
2840 $ cd ROX-Filer/src/po
2841 $ ./update-po</screen>
2844 <listitem><para>Edit the file by hand as before, filling in the new blanks
2845 and updating out-of-date translations.
2846 Look out for <computeroutput>fuzzy</computeroutput> entries where
2847 <command>update-po</command> has made a guess; check it's correct and
2848 remove the <computeroutput>fuzzy</computeroutput> line.
2851 <listitem><para>Run <command>make-mo</command> as before.</para></listitem>
2853 <listitem><para>Submit the updated file to me.</para></listitem>
2857 See the <command>gettext</command> info page for more instructions on creating
2864 <chapter id="hacking">
2865 <title>Hacking</title>
2867 This is a quick start guide for people who want to modify the source
2868 code. If you make useful changes or fix bugs, please send patches
2869 to me or to the mailing list. Tell me which version you're using!
2873 <title>Compiling</title>
2875 The first time you compile the program you need to do <command>AppRun
2876 --compile</command>, but in future you only need to run <command>make</command>
2877 in the <filename>src</filename> directory when you change the
2878 <filename>.c</filename> and <filename>.h</filename> files.
2879 You might want to run <command>make depend</command> too.
2884 <title>Creating and applying patches</title>
2886 When people make small modifications to the sources they will often
2887 distribute them as <emphasis>patch files</emphasis> — usually on the
2890 To apply a patch, go into the <filename>src</filename> directory and run
2891 <command>patch</command> with the patch file. Then recompile, like this:
2895 $ patch < patchfile
2896 $ ../AppRun --compile</screen>
2898 You can remove the patch by simply repeating the above sequence —
2899 <command>patch</command> will detect that the patch is already applied
2900 and offer to remove it.
2902 To create a patch you should first get the latest version of the filer
2903 from CVS (instructions on using CVS can be found on the web-site).
2904 Modify the program as you please. Create the patch using
2905 <command>cvs diff</command> from the appropriate directory:
2907 <screen>$ cvs diff -u > my_patch</screen>
2909 This creates a human– and machine-readable patch file. Submit this
2910 to the mailing list. The are many reasons for posting patches rather
2911 that the modified files:
2914 <listitem><para>They are smaller, and hence shouldn't bounce.
2915 They are also quicker to download for people with slow connections.
2918 <listitem><para>People can see what they're getting into before applying them!
2921 <listitem><para>Patches can (usually) be applied to slightly modified
2922 versions of the sources. This means that people can apply several patches
2923 without each new one overwriting the others.
2932 <title>Autoconf</title>
2934 Here's a quick explanation of the autoconf system in case you haven't
2935 used it before. See <command>info autoconf</command> for full details.
2937 There's a file called <filename>configure.in</filename> which contains
2938 various tests (<command>info autoconf</command>).
2939 You run <command>autoconf</command> and it reads through the file
2940 and generates a shell script to perform the tests, saving it as
2941 <filename>configure</filename>.
2942 <filename>configure</filename> is normally distributed with the program because
2943 not everyone has autoconf.
2945 You then run <filename>configure</filename> (in fact, let the
2946 <filename>AppRun</filename> script do it because
2947 it passes it some arguments), which performs all the tests. It reads
2948 in <filename>Makefile.in</filename> and <filename>config.h.in</filename>
2949 and fills in the missing values with the test results to produce
2950 <filename>Makefile</filename> and <filename>config.h</filename>.
2952 You run <command>make</command>, which creates <filename>.o</filename>
2953 files from the <filename>.c</filename> files and links to produce
2954 <filename>ROX-Filer</filename>.
2958 <sect1><title>Data-structures</title>
2960 The <filename>global.h</filename> file lists each major data-structure used
2961 in the filer and explains its purpose. This is a good place to start reading
2962 if you want to know how the filer works.
2966 In summary, each window has its own <classname>FilerWindow</classname>
2968 This structure has pointers to a <classname>Collection</classname>
2969 (which is the widget which actually displays the files) and to a
2970 <classname>Directory</classname>, which is used to cache the directory
2973 Both <classname>Collection</classname> and
2974 <classname>Directory</classname> have pointers to (the same)
2975 <classname>DirItem</classname>s, each of which corresponds to one filesystem
2978 Several <classname>FilerWindow</classname>s may share the same
2979 <classname>Directory</classname>.
2981 While scanning is in progress the <classname>Directory</classname>
2982 keeps a list of the new items it has found
2983 (<emphasis>new_items</emphasis>) and the items which have changed in some way
2984 (<emphasis>up_items</emphasis>). It periodically notifies the filer window of
2985 the changes-so-far by calling all the functions in the
2986 <emphasis>users</emphasis> list (use <function>attach()</function>
2987 and <function>detach()</function> to add and remove functions to or from
2993 <appendix id="manpage"><title>Manual page</title>
2998 <refentrytitle>ROX</refentrytitle>
2999 <manvolnum>1</manvolnum>
3003 <refname>ROX-Filer</refname>
3004 <refpurpose>a simple graphical file manager</refpurpose>
3009 <command>rox</command>
3010 <arg choice="opt" rep="repeat"><option>OPTION</option></arg>
3011 <arg choice="opt" rep="repeat">FILE</arg>
3015 <refsect1><title>DESCRIPTION</title>
3017 ROX-Filer is a simple and easy to use graphical file manager for X11, the
3018 windowing system used on Unix and Unix-like operating systems.
3020 It is also the core component of the ROX Desktop:
3021 <ulink url="http://rox.sourceforge.net"/>
3023 Invoking <command>rox</command> opens each directory or file listed,
3024 or the current working directory if no arguments are given.
3028 <refsect1><title>COMMAND-LINE OPTIONS</title>
3032 <varlistentry><term><option>-b</option></term><term><option>--bottom=PANEL</option></term>
3033 <listitem><para>open PANEL as a bottom-edge panel.
3034 </para></listitem></varlistentry>
3036 <varlistentry><term><option>-c</option></term><term><option>--client-id=ID</option></term>
3037 <listitem><para>used for session management.
3038 </para></listitem></varlistentry>
3040 <varlistentry><term><option>-d</option></term><term><option>--dir=DIR</option></term>
3041 <listitem><para>open DIR as directory (not as an application, even if it looks like one).
3042 </para></listitem></varlistentry>
3044 <varlistentry><term><option>-D</option></term><term><option>--close=DIR</option></term>
3045 <listitem><para>close DIR and all its subdirectories.
3046 </para></listitem></varlistentry>
3048 <varlistentry><term><option>-h</option></term><term><option>--help</option></term>
3049 <listitem><para>display help about the various options.
3050 </para></listitem></varlistentry>
3052 <varlistentry><term><option>-l</option></term><term><option>--left=PANEL</option></term>
3053 <listitem><para>open PANEL as a left-edge panel.
3054 </para></listitem></varlistentry>
3056 <varlistentry><term><option>-m</option></term><term><option>--mime-type=FILE</option></term>
3057 <listitem><para>print MIME type of FILE and exit.
3058 </para></listitem></varlistentry>
3060 <varlistentry><term><option>-n</option></term><term><option>--new</option></term>
3061 <listitem><para>start a new filer, even if one already seems to be running. This also prevents the filer from forking (running in the background), which is useful for debugging.
3062 </para></listitem></varlistentry>
3064 <varlistentry><term><option>-o</option></term><term><option>--override</option></term>
3065 <listitem><para>override window manager control of panels.
3066 </para></listitem></varlistentry>
3068 <varlistentry><term><option>-p</option></term><term><option>--pinboard=PIN</option></term>
3069 <listitem><para>use pinboard PIN as the pinboard.
3070 </para></listitem></varlistentry>
3072 <varlistentry><term><option>-r</option></term><term><option>--right=PANEL</option></term>
3073 <listitem><para>open PANEL as a right-edge panel.
3074 </para></listitem></varlistentry>
3076 <varlistentry><term><option>-R</option></term><term><option>--RPC</option></term>
3077 <listitem><para>read and invoke SOAP RPC from standard input (see <xref linkend="soap"/>).
3078 </para></listitem></varlistentry>
3080 <varlistentry><term><option>-s</option></term><term><option>--show=FILE</option></term>
3081 <listitem><para>open a directory showing FILE.
3082 </para></listitem></varlistentry>
3084 <varlistentry><term><option>-t</option></term><term><option>--top=PANEL</option></term>
3085 <listitem><para>open PANEL as a top-edge panel.
3086 </para></listitem></varlistentry>
3088 <varlistentry><term><option>-u</option></term><term><option>--user</option></term>
3089 <listitem><para>show user name in each window.
3090 </para></listitem></varlistentry>
3092 <varlistentry><term><option>-v</option></term><term><option>--version</option></term>
3093 <listitem><para>display the version information and exit.
3094 </para></listitem></varlistentry>
3096 <varlistentry><term><option>-x</option></term><term><option>--examine=FILE</option></term>
3097 <listitem><para>FILE has changed; re-examine it.
3098 </para></listitem></varlistentry>
3104 <refsect1><title>NOTES</title>
3106 The main documentation for ROX-Filer is available by choosing
3107 <guimenuitem>Show ROX-Filer Help</guimenuitem> from the
3108 popup menu, or by clicking on the <guibutton>i</guibutton>
3113 <refsect1><title>LICENSE</title>
3114 <para>Copyright (C) 2002 Thomas Leonard.
3116 You may redistribute copies of ROX-Filer under the terms of the GNU General
3121 <refsect1><title>BUGS</title>
3123 Report bugs to <email>tal197@users.sourceforge.net</email>.
3127 <refsect1><title>AUTHORS</title>
3129 ROX-Filer was created by Thomas Leonard, with help from:
3131 <simplelist columns='4'>
3132 <member>Christopher Arndt</member>
3133 <member>Jens Askengren</member>
3134 <member>Liav Asseraf</member>
3135 <member>Wilbert Berendsen</member>
3136 <member>Francesco Bochicchio</member>
3137 <member>Andrzej Borsuk</member>
3138 <member>Richard Boulton</member>
3139 <member>Simon Britnell</member>
3140 <member>Arnaud Calvo</member>
3141 <member>Andrew Clover</member>
3142 <member>Fabien Coutant</member>
3143 <member>Couderc Damien</member>
3144 <member>Andreas Dehmel</member>
3145 <member>Dmitry Elfimov</member>
3146 <member>Mattias Engdegard</member>
3147 <member>Andrew Flegg</member>
3148 <member>Olivier Fourdan</member>
3149 <member>Eric Gillespie</member>
3150 <member>Thierry Godefroy</member>
3151 <member>Alex Holden</member>
3152 <member>Jasper Huijsmans</member>
3153 <member>Bernard Jungen</member>
3154 <member>James Kermode</member>
3155 <member>Jim Knoble</member>
3156 <member>Krzysztof Krzyzaniak</member>
3157 <member>Vincent Ledda</member>
3158 <member>Vincent Lefevre</member>
3159 <member>Victor Liu See-le</member>
3160 <member>Anders Lundmark</member>
3161 <member>Jose Romildo Malaquias</member>
3162 <member>Denis Manente</member>
3163 <member>Andras Mohari</member>
3164 <member>Christiansen Merel</member>
3165 <member>Jimmy Olgeni</member>
3166 <member>Andy Piper</member>
3167 <member>Marcelo Ramos</member>
3168 <member>Michel Alexandre Salim</member>
3169 <member>Chris Sawer</member>
3170 <member>Taras</member>
3171 <member>Simon Truss</member>
3172 <member>Jan Wagemakers</member>
3173 <member>Stephen Watson</member>
3174 <member>Andre Wyrwa</member>
3175 <member>Diego Zamboni</member>
3178 and many others; the <filename>Changes</filename> file contains more
3179 detailed information!
3186 <appendix id="soap"><title>SOAP RPC</title>
3188 <para>When the filer starts you can use command-line options to control its behaviour.
3189 As an alternative to this, the filer allows you to specify an operation with a
3190 <citation>SOAP</citation> RPC format message. In fact, if you use the command-line options,
3191 the filer converts to SOAP RPC internally.
3194 <para>All SOAP RPC messages are passed on standard input, like this:
3197 $ rox --RPC << EOF
3198 <?xml version="1.0"?>
3199 <env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope">
3200 <env:Body xmlns="http://rox.sourceforge.net/SOAP/ROX-Filer">
3202 <Name>Default</Name>
3203 <Side>Bottom</Side>
3206 </env:Envelope>
3209 The following methods are recognised:</para>
3213 <listitem><para><function>Version</function>()
3214 Returns the filer's version.
3217 <listitem><para><function>CloseDir</function>(<parameter>Filename</parameter>)
3218 Close directory <parameter>Filename</parameter> and all its subdirectories.
3221 <listitem><para><function>Examine</function>(<parameter>Filename</parameter>)
3222 <parameter>Filename</parameter> may have changed — check it and
3226 <listitem><para><function>OpenDir</function>(<parameter>Filename</parameter>)
3227 Open a window showing directory <parameter>Filename</parameter>.
3230 <listitem><para><function>Panel</function>(<parameter>Side</parameter>,
3231 [<parameter>Name</parameter>])
3232 Open the panel named <parameter>Name</parameter> on screen side
3233 <parameter>Side</parameter> (<userinput>Top</userinput>|<userinput>Bottom</userinput>|<userinput>Left</userinput>|<userinput>Right</userinput>).
3234 <parameter>Name</parameter> can be a name in Choices (eg,
3235 <userinput>MyPanel</userinput>) or a full pathname.
3236 If not given, the panel on that side is turned off.
3239 <listitem><para><function>Pinboard</function>([<parameter>Name</parameter>])
3240 Display pinboard <parameter>Name</parameter> on the desktop background.
3241 <parameter>Name</parameter> can be a name in Choices (eg,
3242 <userinput>MyPinboard</userinput>) or a full pathname.
3243 If not given, the pinboard is turned off.
3246 <listitem><para><function>Run</function>(<parameter>Filename</parameter>)
3247 Run <parameter>Filename</parameter> as if it was clicked on in the filer.
3250 <listitem><para><function>Show</function>(<parameter>Directory</parameter>,
3251 <parameter>Leafname</parameter>)
3252 Open <parameter>Directory</parameter> and flash the file
3253 <parameter>Leafname</parameter> inside it.
3256 <listitem><para><function>FileType</function>(<parameter>Filename</parameter>)
3257 Returns the MIME-type of <parameter>Filename</parameter> (by writing the
3258 SOAP response to standard output).
3263 The following calls can be used to start new file actions.
3264 <parameter>Quiet</parameter> can be <userinput>true</userinput> if the
3265 operation should start immediately, instead of waiting for the user to
3266 confirm. If <userinput>false</userinput>, the user must always confirm. If
3267 not given, the default setting is used.
3271 <listitem><para><function>Copy</function>(<parameter>From</parameter>,
3272 <parameter>To</parameter>, [<parameter>Leafname</parameter>,
3273 <parameter>Quiet</parameter>])
3274 Copy each file in the array <parameter>From</parameter> to the directory
3275 <parameter>To</parameter>. If <parameter>Leafname</parameter> is given
3276 then <parameter>From</parameter> should contain a single entry only;
3277 <parameter>Leafname </parameter> gives the new leafname.
3280 <listitem><para><function>Move</function>(<parameter>From</parameter>,
3281 <parameter>To</parameter>, [<parameter>Leafname</parameter>,
3282 <parameter>Quiet</parameter>])
3283 Move each file in the array <parameter>From</parameter> to the directory
3284 <parameter>To</parameter>. If <parameter>Leafname</parameter> is given
3285 then <parameter>From</parameter> should contain a single entry only;
3286 <parameter>Leafname</parameter> gives the new leafname.
3289 <listitem><para><function>Link</function>(<parameter>From</parameter>,
3290 <parameter>To</parameter>, [<parameter>Leafname</parameter>])
3291 Symlink each file in the array <parameter>From</parameter> to the
3292 directory <parameter>To</parameter>. If <parameter>Leafname</parameter> is
3293 given then <parameter>From</parameter> should contain a single entry only;
3294 <parameter>Leafname</parameter> gives the new leafname.
3297 <listitem><para><function>Mount</function>(<parameter>MountPoints</parameter>,
3298 [<parameter>OpenDir</parameter>, <parameter>Quiet</parameter>])
3299 Mount each directory in the list <parameter>MountPoints</parameter>. If
3300 <userinput>true</userinput>, <parameter>OpenDir</parameter> causes each
3301 directory to be opened once it is mounted.
3309 <title>References</title>
3312 <abbrev>ROX</abbrev><citetitle>The ROX desktop,
3313 <ulink url="http://rox.sourceforge.net"/></citetitle>
3317 <abbrev>RISC OS</abbrev><citetitle>RISC OS,
3318 <ulink url="http://www.riscos.com"/></citetitle>
3322 <abbrev>GTK+</abbrev><citetitle>GTK+ Toolkit,
3323 <ulink url="http://www.gtk.org"/></citetitle>
3327 <abbrev>GNOME</abbrev><citetitle>The GNOME desktop,
3328 <ulink url="http://www.gnome.org"/></citetitle>
3332 <abbrev>DND</abbrev><citetitle>The Drag and Drop protocol,
3333 <ulink url="http://www.newplanetsoftware.com/xdnd/"/></citetitle>
3337 <abbrev>XDS</abbrev><citetitle>The X Direct Save protocol,
3338 <ulink url="http://www.newplanetsoftware.com/xds/"/></citetitle>
3342 <abbrev>Choices</abbrev><citetitle>The ROX Choices system,
3343 <ulink url="http://rox.sourceforge.net/choices.php3"/></citetitle>
3347 <abbrev>AVFS</abbrev><citetitle>AVFS - A Virtual File System,
3348 <ulink url="http://sourceforge.net/projects/avf/"/></citetitle>
3352 <abbrev>SOAP</abbrev><citetitle>Simple Object Access Protocol (SOAP) 1.2
3353 <ulink url="http://www.w3.org/TR/SOAP/"/></citetitle>
3357 <abbrev>Thumbs</abbrev><citetitle>Thumbnail Managing Standard (Version 0.5)
3358 <ulink url="http://triq.net/~pearl/thumbnail-spec/"/></citetitle>