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>
102 <varlistentry><term>Shared MIME Info Database</term>
104 In the past, each desktop had its own database of rules for determining the
105 type of files. The Shared MIME Info Database<citation>SharedMIME</citation>
106 unifies these into a single system shared by all desktops.
107 </para></listitem></varlistentry>
116 <chapter id="compiling">
117 <title>Compiling</title>
120 If you've just got hold of the filer by downloading the source archive
121 then you'll need to compile it before you can use it. If you downloaded
122 and installed a binary package, or if <application>ROX-Filer</application>
123 was included with your system, then you can skip this section. If you got
124 here by clicking on the lifebelt symbol in a filer window, or if typing
125 <command>rox</command> at a shell prompt works, then you don't need to
128 <itemizedlist><title>To compile, you will need the following:</title>
131 Unix or Linux (root access is not required),
135 The X Window system (supplied as standard on all modern systems),
139 GTK+ 2.0.1 or later (libraries and headers) — get the latest version
140 from <citation>GTK+</citation>,
144 LibXML 2.0.0 or later (libraries and headers) — get the latest
145 version from <citation>libxml</citation>,
149 A C compiler, such as `gcc' (standard on most systems).
154 All of the above are standard on most modern Linux distributions.
155 To check which version of GTK+ you have installed, run the
156 <command>pkg-config</command> command, like this
157 (<prompt>$</prompt> is the shell prompt):
159 <screen>$ pkg-config --modversion gtk+-2.0
163 <procedure><title>To compile:</title>
166 The filer now uses the Shared MIME Database<citation>SharedMIME</citation>
167 to work out the types of files. You need to install this before the
168 filer will work properly (ROX-Filer will warn you if it's not installed
173 Change to the directory containing the ROX-Filer subdirectory.
177 Run the <command>install.sh</command> script, like this:
179 <screen>$ ./install.sh</screen>
184 <application>ROX-Filer</application> will perform various checks to find
185 out what kind of system it is being run on and will then compile. If it
186 doesn't work then please e-mail me and complain! Tell me what kind of
187 system you have and what errors were reported. If you manage to fix the
188 problem yourself then please e-mail me the fix.
190 The executable file is stored inside the ROX-Filer directory in a
191 different subdirectory for each platform. Therefore, you can compile
192 the same application on several different types of machine and then
193 run it from any of them using the <filename>AppRun</filename> script.
194 This is particularly useful in a network environment.
198 Once the filer has compiled you will be asked where you want to install
199 it. If you want to do a system-wide installation as root, you may
200 want to stop here, <command>su</command> to root and rerun the install
203 If you don't have the root password then don't worry — just follow
204 the instructions for installing into your home directory.
209 You can now run the filer by running the <command>rox</command> script
210 without any options, like this:
212 <screen>$ rox</screen>
214 A window should appear and display the contents of the current directory.
216 If you installed the script into your home directory then you may
217 need to set your <envar>PATH</envar> environment variable so that the shell can
218 find it. For example, if you installed it into a directory called
219 <filename>bin</filename> in your home directory, use this:
221 <screen>$ PATH=$HOME/bin:$PATH; export PATH</screen>
223 or (if you are using the <citerefentry><refentrytitle>csh</refentrytitle>
224 <manvolnum>1</manvolnum></citerefentry> shell):
226 <screen>$ setenv PATH $HOME/bin:$PATH
233 <chapter id="invoking">
234 <title>Invoking</title>
237 By default, <application>ROX-Filer</application> will start by displaying
238 the current directory. You can get it to display other directories instead
239 by listing them after the command:
241 <screen>$ rox /home /usr /usr/local</screen>
243 You can also use it to open files, like this:
245 <screen>$ rox README</screen>
247 The filer supports various options; use <option>-h</option> for a list.
248 All options have long and short forms (eg <option>-h</option> and
249 <option>--help</option>) — although on some systems you can only use the
252 Note that if the same version of the filer is already running on this
253 machine then, by default, it will be used to open the directories.
255 For a complete list of command-line options, see <xref linkend="manpage"/>
259 <title><anchor id="run_pin" xreflabel="Pinboard support"/>Pinboard support</title>
262 If you want the filer to manage your desktop background then you use
263 the <option>--pinboard</option> option and supply a name for the pinboard,
266 <screen>$ rox --pinboard=MyPinboard</screen>
268 The pinboard configuration is saved in
269 <filename><Choices>/ROX-Filer/pb_MyPinboard</filename>
270 as soon as you change it in some way (for example, by dropping a file
271 onto the background). You can have as many pinboards as you like and
272 switch between them by running rox again, eg:
274 <screen>$ rox --pinboard=MyOtherPinboard</screen>
276 To turn off the pinboard again, set the name to an empty string:
278 <screen>$ rox --pinboard=</screen>
280 See the <xref linkend="winman"/> if you have trouble getting the icons to
281 display correctly. The pinboard may also be turned on and off by locating
282 <filename>ROX-Filer</filename> in a filer window and choosing `Enable
283 pinboard' or `Disable pinboard' from the menu. </para>
287 <title><anchor id="run_pan" xreflabel="Panel support"/>Panels</title>
290 Panels work just like the pinboard. You can create a panel on any
291 side of the screen by using the options <option>--left</option>, <option>--right,</option>
292 <option>--top</option> and <option>--bottom</option>, depending on which side
293 of the screen the panel should appear on. On some systems, the short
294 (one letter) form of the options must be used. For example, to create
295 a panel along the bottom edge of the screen:
297 <screen>$ rox -b=MyPanel</screen>
299 The panel should be displayed in a window without a title bar. If
300 this does not work then see the <xref linkend="winman"/> for some ideas.
301 You can drag files onto either side of the panel to add them. Panel icons
302 can be repositioned by dragging them with the middle mouse button.
303 Changes to the panel are automatically saved to
304 <filename><Choices>/ROX-Filer/pan_MyPanel</filename>.
305 As with the pinboard, you can switch between panel configurations
306 simply by running rox again with a different panel name. Specify a
307 blank name to remove the panel.
309 <screen>$ rox --bottom=MyOtherPanel
310 $ rox --bottom=</screen>
315 <title><anchor id="winman" xreflabel="window manager notes"/>Window manager notes</title>
317 You may have to play around with your window manager a bit to get
318 the pinboard icons and panels to display correctly (eg, without borders
319 and underneath all other windows). In particular, try setting the
320 stacking level / depth to low (or a negative value). Make sure any
321 'Keep transients above other windows' type options are turned off!
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>
433 If all else fails, try the Compatibility section of the Options window.
439 <title>Running as root</title>
442 If you run the filer as the `root' user then the filer will display
443 a message at the top of each window to remind you. The root user has
444 permission to access or change any file in the system, so be very
445 careful when using the filer like this.
447 Normally, you should log in as an ordinary user and only change to
448 root when you need to. If you have <command>sudo</command> installed
449 and set up then you can run the filer like this:
451 <screen>$ sudo rox</screen>
453 Remember, any file operations you perform and any programs you run from
454 these windows will run as root too! Be careful!
456 You may find that the X server won't allow root (or other users) to
457 connect. Reading the manual pages for <command>xauth</command> and
458 <command>xhost</command> may give you some hints, but it varies
459 between systems (which is why this isn't built in to the filer!).
466 <chapter id="keys" xreflabel="mouse and key bindings">
467 <title>Mouse button and key bindings</title>
469 <itemizedlist><title>Quick start:</title>
471 <listitem><para>Click the left
472 <footnote><para>This documentation assumes that button–1 is the left
473 button, button–2 is the middle button and button–3 is the
474 right button. This is not always the case — for example, in a
475 left-handed setup.</para></footnote> mouse button to open files and
476 directories.</para></listitem>
479 Click the right button to get a menu. Click over a file to perform an action on that file.
483 Drag files between windows with the left button to copy them, or with
484 the middle button to get a menu of possible actions (copy, move, link,
491 By default, the mouse button bindings are designed to fit in with X
492 conventions. However, the behaviour is highly configurable — have a play in
493 the Options window if you don't like the normal settings. The normal settings
499 <thead><row><entry>Key or mouse button</entry><entry>Action</entry></row></thead>
503 <row><entry>Left button click</entry><entry>
504 Open the file or directory clicked on. Hold down <keycap>Control</keycap>
505 to select things instead of opening them. Hold down <keycap>Shift</keycap>
506 to look inside applications, treat files as text, follow symlinks, or
507 get more control over mount points (see <xref linkend="media"/>).
510 <row><entry>Middle button click</entry><entry>
511 Same as left click, but open a directory in a new window or close the viewer
515 <row><entry>Right button click</entry><entry>
516 Open the main menu. Hold down <keycap>Control</keycap> while clicking to go
517 directly to the Selection submenu. Hold down <keycap>Shift</keycap> to get the
518 <guimenu>Send To</guimenu> menu (see the <xref linkend="SendTo"/> section).
521 <row><entry>Drag an item (left mouse button)</entry><entry>
522 Copy the file(s) to the destination (an application or another filer
523 window). Hold down <keycap>Shift</keycap> to move the file,
524 <keycap>Control</keycap>+<keycap>Shift</keycap> to create
525 a symbolic link, or <keycap>Alt</keycap> to get a menu of possible actions.
528 <row><entry>Drag an item (middle mouse button)</entry><entry>
529 When you let go, display a menu of possible actions.
530 There is an option to make this move the files rather than open the menu.
533 <row><entry>Drag (not over an item)</entry><entry>
534 Select a group of items by dragging a box around them. With the left
535 mouse button, only the files in the box will be selected. If you hold
536 down <keycap>Control</keycap> then the boxed items are added to the selection.
537 If you use the middle button then the boxed items switch between being selected
541 <row><entry>Double-click background</entry><entry>
542 Resize the window to a sensible size.
545 <row><entry><keycap>Backspace</keycap></entry><entry>
546 Change to viewing the parent directory.
549 <row><entry>Cursor keys</entry><entry>
550 Move the cursor around.
554 <keycap>Page Up</keycap>, <keycap>Page Down</keycap></entry><entry>
555 Move the cursor up and down a page at a time.
558 <row><entry><keycap>Home</keycap>, <keycap>End</keycap></entry><entry>
559 Move to the first/last entry in the directory.
562 <row><entry><keycap>Return</keycap></entry><entry>
563 Acts like clicking on the file. You may hold down Shift for other
564 effects, as with clicking. Holding down Alt works like clicking with
565 the middle button; directories open in a new window and opening files
566 closes the directory at the same time.
569 <row><entry><keycap>Spacebar</keycap></entry><entry>
570 Toggles the item under the cursor between being selected and unselected,
571 and moves to the next item.
574 <row><entry><keycap>Tab</keycap>, <keycap>Shift</keycap>+<keycap>Tab</keycap></entry><entry>
575 Moves the cursor to the next/previous selected item.
578 <row><entry>Hold mouse over an item</entry><entry>
579 Shows a tooltip containing a brief description of an application (if
580 available), the target of a symbolic link, and the full name of a file,
581 if it's too long to show in the main window.
584 </tbody></tgroup></informaltable>
587 If you have user-defineable key-bindings enabled, then other keys can easily
588 be set by opening the menu, moving the pointer over the item you want to use
589 and pressing a key. The key will appear in the menu and can be used from
590 then on. Key bindings are automatically saved when the filer quits.
591 You can use an XSettings manager, such as ROX-Session, to turn this feature
592 on for all Gtk+-2.0 applications.
596 <chapter id="selection">
597 <title>The selection and file groups</title>
599 When you select items in a <application>ROX-Filer</application> window,
600 the filer takes the <emphasis>primary selection</emphasis>. You can then paste
601 into another window to get the pathnames of the selected files.
605 <title>Example: loading a file into an application that doesn't support
606 drag-and-drop:</title>
608 <step><para>Open the application's Open dialog box.</para></step>
611 <keycap>Control</keycap>-click on the file in
612 <application>ROX-Filer</application> to select it.</para></step>
615 Click the middle button in the filename box in the application to paste the
621 Note that clicking the middle mouse button in the main area of most web-browsers
622 will open the selected file.
624 If you select something else (eg, some text in another program), the selected
625 items in the filer window will be shown shaded (the filer no longer has the
626 primary selection). Clicking on one of the shaded items will cause the
627 filer to regain the primary selection.
630 <sect1><title>Saving and restoring the selection</title>
632 It is sometimes useful to save the current selection for later. You can
633 save the current selection to one of ten numbered groups by pressing
634 <keycap>Control</keycap>+<keycap><number></keycap>.
635 You can restore a saved group by pressing the group number on its own. You
636 can do this from a different directory, or even a different filer window.
638 Saving is also useful even if there is no selection, since it still saves
639 the current directory.
641 <procedure><title>Example: saving a directory and returning to it later:</title>
642 <step><para>You are looking at a directory, and wish to remember it.
643 Press <keycap>Control</keycap>+<keycap>1</keycap>.</para></step>
644 <step><para>Move to another directory, or close the window, etc.</para></step>
645 <step><para>Press <keycap>1</keycap> in any filer window to return
646 to the first directory.</para></step> </procedure>
647 <para>The groups are saved automatically for next time the filer is loaded.
651 <chapter id="toolbar">
652 <title><anchor id="Toolbar" xreflabel="Toolbar"/>The toolbar</title>
655 By default, each window has a toolbar along the top. You can disable
656 this (or make it larger) from the Options window, as well as set which
657 tools appear on the toolbar. Normally, you should click with the left
658 mouse button (1). However, many tools can perform a related function
659 if clicked on with buttons 2 or 3 (middle or right).
662 <informaltable><tgroup cols="3">
667 Mouse button 1</entry><entry>
676 Close the window</entry><entry>
678 </entry></row><row><entry>
679 Up arrow</entry><entry>
680 Change to parent directory</entry><entry>
681 Show parent in a new window <xref linkend="newwin_fn"/>
682 </entry></row><row><entry>
684 Change to home directory</entry><entry>
685 Show home in a new window <xref linkend="newwin_fn"/>
686 </entry></row><row><entry>
687 Jump to point</entry><entry>
688 Open the <xref linkend="bookmarks"/>
691 </entry></row><row><entry>
692 Looping arrows</entry><entry>
693 Reread the directory contents</entry><entry>
695 </entry></row><row><entry>
696 Magnifying glass</entry><entry>
697 Make icons bigger</entry><entry>
699 </entry></row><row><entry>
701 Hide or show extra details</entry><entry>
703 </entry></row><row><entry>
704 Crossed out text</entry><entry>
705 Toggle the display of hidden file (those with names starting with a dot)</entry><entry>
707 </entry></row><row><entry>
708 Life-belt</entry><entry>
709 Show <application>ROX-Filer</application>'s help files</entry><entry>
712 </tbody></tgroup></informaltable>
715 <anchor id="newwin_fn" xreflabel="[1]"/>[1]
716 If the 'New window on button 1' option is turned on
717 then the default is to open a new window — clicking with the other
718 button reuses the same window instead.
722 Dragging files to the Up or Home icons acts just like dragging them
723 into the directory which the button leads to.
725 The toolbar can also show the number of files in the directory, and
726 information about the selection. This can be turned on or off in the
734 <title>The menus</title>
736 By default, you can open a menu by right clicking over a pinboard, panel or
739 In filer windows, you may also press <keycap>\</keycap> to open the menu. As
740 a shortcut, you can open the File submenu directly by holding down the
741 <keycap>Control</keycap> key when opening the menu. Here is a full
742 description of each menu item:
744 <informaltable><tgroup cols="2">
746 <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
749 <row><entry><guimenuitem>Display</guimenuitem></entry><entry>
750 Change the display settings.
753 <row><entry><guimenuitem>File</guimenuitem></entry><entry>
754 Operations on the selected items.
757 <row><entry><guimenuitem>Select</guimenuitem></entry><entry>
758 Control which items are selected.
761 <row><entry><guimenuitem>Options...</guimenuitem></entry><entry>
762 Configure <application>ROX-Filer</application>.
765 <row><entry><guimenuitem>New</guimenuitem></entry><entry>
766 Create a new file or subdirectory inside this directory.
769 <row><entry><guimenuitem>Window</guimenuitem></entry><entry>
770 Operations on the window as a whole.
773 <row><entry><guimenuitem>Help</guimenuitem></entry><entry>
774 Information about the filer.
777 </tbody></tgroup></informaltable>
782 <title>The display menu</title>
785 <informaltable><tgroup cols="2">
787 <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
790 <row><entry><guimenuitem>Huge Icons</guimenuitem></entry><entry>
791 Extra large icons (mainly useful with thumbnails, see below).
792 </entry></row><row><entry>
794 <guimenuitem>Large Icons</guimenuitem></entry><entry>
795 Each object in the directory is shown as a large icon with its name
797 </entry></row><row><entry>
799 <guimenuitem>Small Icons</guimenuitem></entry><entry>
800 Items are drawn smaller than usual, allowing you to see more files
802 </entry></row><row><entry>
804 <guimenuitem>Huge, With...</guimenuitem></entry><entry>
805 As for <guimenuitem>Large, With...</guimenuitem>, but with extra large icons.
806 </entry></row><row><entry>
808 <guimenuitem>Large, With...</guimenuitem></entry><entry>
809 <para>Entries are displayed along with some extra details:</para>
812 <listitem><para><guimenuitem>Summary</guimenuitem>
813 shows the file permissions, owner, group, size and modification time.
816 <listitem><para><guimenuitem>Sizes</guimenuitem>
817 shows just the size of each file (not directories).
820 <listitem><para><guimenuitem>Permissions</guimenuitem>
821 shows just the permissions and owner.
824 <listitem><para><guimenuitem>Type</guimenuitem>
825 shows the MIME type of each file.
828 <listitem><para><guimenuitem>Times</guimenuitem>
829 shows the times the file was last accessed, modifed and changed.
830 Reading a file's contents or listing a directory updates the
831 <emphasis>access time</emphasis>; modifying the contents of a file or
832 the list of files in a directory updates the <emphasis>modification
833 time</emphasis>; changing a file's owner or permissions updates the
834 <emphasis>change time</emphasis>.
839 </entry></row><row><entry>
841 <guimenuitem>Small, With...</guimenuitem></entry><entry>
842 As above, but with a smaller icon and all on one line.
843 </entry></row><row><entry>
845 <guimenuitem>Sort by Name</guimenuitem></entry><entry>
846 Items are arranged by name. The default sort mode is case-insensitive
847 and deals with numbers sensibly.
848 </entry></row><row><entry>
850 <guimenuitem>Sort by Type</guimenuitem></entry><entry>
851 Items are grouped by their types and then sorted by name within the
853 </entry></row><row><entry>
855 <guimenuitem>Sort by Date</guimenuitem></entry><entry>
856 Most recently modified first.
857 </entry></row><row><entry>
859 <guimenuitem>Sort by Size</guimenuitem></entry><entry>
861 </entry></row><row><entry>
863 <guimenuitem>Show Hidden</guimenuitem></entry><entry>
864 If on, files beginning with a dot are shown, otherwise they are hidden.
865 The titlebar shows <guilabel>(All)</guilabel> when this is on.
866 </entry></row><row><entry>
868 <guimenuitem>Show Thumbnails</guimenuitem></entry><entry>
869 When on, the filer tries to load every image file and use that
870 image as the file's icon. Useful if you have a directory full of
871 photos and can't remember which is which!
872 The thumbnails are saved in <filename>~/.thumbnails</filename> for
873 quick loading next time.
874 While loading thumbnails, a progress bar appears at the bottom of
875 the window. Clicking on the <guibutton>Cancel</guibutton> button
876 beside the bar stops the scan.
877 The titlebar shows <guilabel>(Thumbs)</guilabel> when this is on.
878 </entry></row><row><entry>
880 <guimenuitem>Refresh</guimenuitem></entry><entry>
881 Rereads the contents of the directory and details of all the files
882 in it. Use this if the display becomes out-of-date.
885 </tbody></tgroup></informaltable>
889 <sect2><title><anchor id="Permissions" xreflabel="Permissions"/>
894 The permissions field, when shown, is made up of four groups of three
895 flags. Each flag is displayed as a letter if it is on and a dash (–)
896 if not. The first three characters show the permissions for the owner
897 of the file, the second for other members of the file's group and
898 the third for everyone else. Whichever group applies to the
899 <application>ROX-Filer</application> process itself is shown underlined.
900 The fourth group shows any special flags.
902 The meanings of the characters are:
906 <listitem><para><computeroutput>r</computeroutput> —
907 Permission to read the contents of a file, or the names of files
908 in a directory.</para></listitem>
910 <listitem><para><computeroutput>w</computeroutput> —
911 Permission to alter the contents of a file, or change which names
912 appear in a directory.</para></listitem>
914 <listitem><para><computeroutput>x</computeroutput> —
915 Permission to run the file as a program, or refer to the files
916 listed within the directory.</para></listitem>
918 <listitem><para><computeroutput>U</computeroutput> —
919 This program executes with the <emphasis>effective user ID</emphasis> of its
920 owner rather than the person who ran it.</para></listitem>
922 <listitem><para><computeroutput>G</computeroutput> —
923 This program executes with the <emphasis>effective group ID</emphasis> of its
924 group, regardless of who ran it.</para></listitem>
926 <listitem><para><computeroutput>T</computeroutput> —
927 Entries in this directory can only be altered or removed by the
928 people who own the files even if they have write permission on the
929 directory itself.</para></listitem>
934 <emphasis role="underline">rwx</emphasis>,rwx,r-x/---</programlisting>
935 means that the owner of the file is the same as the effective user of
936 <application>ROX-Filer</application> (basically, you own the file), you and
937 members of the file's group have read, write and execute permission and other
938 people have only read and execute permission. There are no special flags set.
940 The rules which determine which permissions apply may vary slightly between
941 operating systems, but a rough guide is:
945 <listitem><para>If the <emphasis>effective user ID</emphasis> of the
946 process is equal to the file's owner, then the owner permissions apply.
949 <listitem><para>Otherwise, if the <emphasis>effective group ID</emphasis>
950 of the process is equal to the file's group OR the file's group is one
951 of the process's <emphasis>supplemental groups</emphasis> then the
952 group permissions apply.
955 <listitem><para>Otherwise, the `other' permissions apply. The
956 <emphasis>real user ID</emphasis> and <emphasis>real group
957 ID</emphasis> have no effect (except that a process may set its real
958 IDs to its effective IDs).
968 <title>The file menu</title>
970 All of these work in the same way — if you open the menu with some
971 items selected then the operation applies to those items. If you open
972 then menu over an item while there is no selection then that item
973 is temporarily selected.
975 If you choose one of these while there is no selection at all then the
976 window goes into `target mode'; the operation happens to the next item you
977 click on. Click on the window background, press <keycap>Escape</keycap>, or
978 click with the right mouse button to cancel target mode. Target mode is
979 mainly useful with the <guilabel>Single-click navigation in filer
980 windows</guilabel> option and keys bound to the various menu entries.
982 Note that individual applications may add extra menu items to the
983 top of this submenu when you click over them — see
984 <xref linkend="AppDir"/> for details.
986 <informaltable><tgroup cols="2">
987 <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
991 <guimenuitem>Copy...</guimenuitem></entry><entry>
992 Make a copy of this object.
996 <guimenuitem>Rename...</guimenuitem></entry><entry>
997 Change the name used for this object, or move it between directories.
1001 <guimenuitem>Link...</guimenuitem></entry><entry>
1002 Create a symbolic link to this name.
1006 <guimenuitem>Delete</guimenuitem></entry><entry>
1007 Remove all the selected entries from the directory. Subdirectories
1008 will have their contents deleted first. Deleting symlinks only removes
1009 the link, not the thing it points to.
1013 <guimenuitem>Help</guimenuitem></entry><entry>
1014 Explain what kind of thing is selected. For applications, display
1019 <guimenuitem>Shift Open</guimenuitem></entry><entry>
1020 Opens applications as directories, files as text/plain, and
1021 symlinks by opening the directory containing the thing they point to.
1022 It also has interesting effects on mount points (see <xref linkend="media"/>).
1023 This is the same effect as clicking with <keycap>Shift</keycap> held
1024 down. The text of the menu entry changes to show which action will be
1029 <guimenuitem>Open AVFS</guimenuitem></entry><entry>
1030 Open the file as if it was a directory — see the
1031 <xref linkend="vfs"/> section.
1035 <guimenuitem>Send To...</guimenuitem></entry><entry>
1036 Opens the `Send To' menu, allowing you to send the selected files
1037 to one of a list of applications. See the
1038 <xref linkend="SendTo"/> section.
1042 <guimenuitem>Set Run Action...</guimenuitem></entry><entry>
1043 Allows you to set the default program to use when opening files of
1044 this type. See <xref linkend="RunAction"/> section for details.
1048 <guimenuitem>Set Icon...</guimenuitem></entry><entry>
1049 You can give each file or directory its own special icon using this
1050 feature — simply drag a suitable image onto <xref linkend="SetIcon"/>.
1054 <guimenuitem>Info</guimenuitem></entry><entry>
1055 Display extra information about this object.
1059 <guimenuitem>Count</guimenuitem></entry><entry>
1060 Count the sizes of all the selected items. Directories also have their
1061 contents counted. Symlinks count themselves, not the things they point
1066 <guimenuitem>Permissions</guimenuitem></entry><entry>
1067 Allows you to change the permissions for the selected files.
1071 <guimenuitem>Find</guimenuitem></entry><entry>
1072 Search for files by specifying various conditions — see the
1073 <xref linkend="Searching"/> section.
1076 </tbody></tgroup></informaltable>
1079 <formalpara><title>Note about symlinks:</title>
1081 A symbolic link stores the <emphasis>location</emphasis>
1082 of another file. Deleting the symlink doesn't affect the other file.
1083 Deleting the other file means that the symlink won't work. There are
1084 two types of symbolic link — Relative and Absolute. An absolute
1085 link stores the path from the root directory to the target file (eg
1086 <filename>/home/fred/MyFile</filename>).
1088 A relative path stores the path from the symlink
1089 to the target (eg <filename>../fred/MyFile</filename>).
1090 If the target file is never going to move then you want an absolute link,
1091 but if the target may move (and the symlink will be moved with it) then
1092 you want a relative link.
1098 <title>The select menu</title>
1100 This menu allows you to select and unselect files in various ways. See the
1101 <xref linkend="keys"/> section for other ways to select files.
1103 <informaltable><tgroup cols="2">
1104 <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
1107 <guimenuitem>Select All</guimenuitem></entry><entry>
1108 Select every item in this window.
1111 <row><entry><guimenuitem>Clear Selection</guimenuitem></entry><entry>
1112 Unselect every item in this window.
1115 <row><entry><guimenuitem>Invert Selection</guimenuitem></entry><entry>
1116 Every selected file becomes unselected, and every unselected file
1121 <guimenuitem>Select If...</guimenuitem></entry><entry>
1122 Select just those files that match the given pattern —
1123 see the <xref linkend="SelectIf"/> section.
1126 </tbody></tgroup></informaltable>
1132 <title>The new menu</title>
1135 Each entry in this submenu opens a savebox for creating a new file or
1136 directory. There are two standard entries; the others are the contents of
1137 your <filename><Choices>/Templates</filename> directory, if it
1141 <informaltable><tgroup cols="2">
1142 <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
1145 Directory</entry><entry>
1146 Create a new directory.
1147 </entry></row><row><entry>
1149 Create a blank file.
1150 </entry></row><row><entry>
1151 <user entries></entry><entry>
1152 Copy a file from your Templates directory.
1154 </tbody></tgroup></informaltable>
1157 To add your own entries, create a new directory called
1158 <filename>~/Choices/Templates</filename>
1159 (if you have the default <envar>CHOICESPATH</envar>) and put any files you
1160 want in there. Each file in the directory will appear on the menu and the
1161 box that appears will copy it. For example, you could create a blank
1167 <title>My Page</title>
1172 </html></programlisting>
1174 Save this as <filename>index.html</filename> inside the
1175 <filename>Templates</filename> directory and you can easily create new
1176 HTML files. You can also save blank documents from various applications
1177 into here (eg, a blank spreadsheet, a blank letter, etc).
1179 Note that you cannot set keyboard shortcuts for these user-defined
1186 <title>The window menu</title>
1190 <informaltable><tgroup cols="2">
1191 <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
1194 <guimenuitem>Parent, New Window</guimenuitem></entry><entry>
1195 Open a new window displaying this window's parent.
1199 <guimenuitem>Parent, Same Window</guimenuitem></entry><entry>
1200 As above, but reuse this window.
1204 <guimenuitem>New Window</guimenuitem></entry><entry>
1205 Open another window onto this directory.
1209 <guimenuitem>Home Directory</guimenuitem></entry><entry>
1210 Change to your home directory.
1214 <guimenuitem>Show Bookmarks</guimenuitem></entry><entry>
1215 Open the bookmarks menu (see <xref linkend="bookmarks"/>).
1219 <guimenuitem>Follow Symbolic Links</guimenuitem></entry><entry>
1220 Converts the path shown in the window's titlebar to its canonical form.
1221 For example, if <filename>/home/fred/link</filename> is a symlink
1222 pointing to <filename>/usr/share/doc/</filename> then clicking on the symlink
1223 will take you to that directory and going `up' will take you back to
1224 <filename>/home/fred</filename>.
1225 If you'd used <guimenuitem>Follow Symbolic Links</guimenuitem>, you would
1226 have ended up in <filename>/usr/share</filename> instead.
1230 <guimenuitem>Resize Window</guimenuitem></entry><entry>
1231 Set the window to a sensible size for its contents.
1235 <guimenuitem>Close Window</guimenuitem></entry><entry>
1240 <guimenuitem>Enter Path...</guimenuitem></entry><entry>
1241 Open the path-entry box (see the the <xref linkend="mini"/> section).
1245 <guimenuitem>Shell Command...</guimenuitem></entry><entry>
1246 Open the shell command box (see the <xref linkend="mini"/> section).
1249 <row><entry><guimenuitem>Xterm Here</guimenuitem></entry><entry>
1250 Open an xterm with its current directory set to this directory.
1253 <row><entry><guimenuitem>Switch to xterm</guimenuitem></entry><entry>
1254 Open an xterm with its current directory set to this directory, and close the
1255 filer window at the same time.
1259 <guimenuitem>Show ROX-Filer Help</guimenuitem></entry><entry>
1260 Same as selecting ROX-Filer and choosing
1261 <guimenuitem>Help</guimenuitem> from the menu.
1264 </tbody></tgroup></informaltable>
1271 <title>The help menu</title>
1274 <informaltable><tgroup cols="2">
1275 <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
1278 <guimenuitem>About ROX-Filer...</guimenuitem></entry><entry>
1279 Display information about the file. This is the same as locating ROX-Filer
1280 itself in a filer window and selecting <guimenuitem>Info</guimenuitem> from
1285 <guimenuitem>Show Help Files</guimenuitem></entry><entry>
1286 Same as selecting ROX-Filer and choosing
1287 <guimenuitem>Help</guimenuitem> from the file menu.
1291 <guimenuitem>Manual</guimenuitem></entry><entry>
1292 Opens the HTML manual for your language, or the English version if there
1296 </tbody></tgroup></informaltable>
1302 <title><anchor id="SendTo" xreflabel="Send To menu"/>The send to menu</title>
1305 The `Send To' menu provides a quick way to send some files to an application.
1306 The filer scans all the <filename>SendTo</filename> directories in your
1307 <envar>CHOICESPATH</envar> and lists the contents on this menu.
1309 To change which applications appear here you should choose the
1310 <guimenuitem>Customise</guimenuitem> item from the bottom
1311 of the menu to create and open your own <filename>SendTo</filename>
1312 directory. Applications can be symlinked into this directory by dragging
1313 them in with <keycap>Control</keycap> and <keycap>Shift</keycap> held down.
1315 Opening the Send To menu via the main menu is rather slow, so it is
1316 normally opened by clicking the Menu mouse button over a file while
1317 holding the <keycap>Shift</keycap> key down.
1320 <title>Showing different applications for different types</title>
1322 You may want to set things up so that, for example, the Gimp is
1323 only shown when an image is selected. To do this, create a
1324 hidden directory inside <filename>SendTo</filename> called
1325 <filename>.image</filename>, or whatever type you want to use.
1326 You can use either the complete type (eg <filename>.image_png</filename>)
1327 or just the media type. Use <guimenuitem>Info</guimenuitem> over a file to
1328 find out its MIME type.
1331 Entries in these hidden directories are shown only for files of
1332 the appropriate type. If multiple files are selected, the
1333 <filename>.group</filename> directory is used instead.
1339 <title><anchor id="bookmarks" xreflabel="Bookmarks menu"/>The bookmarks menu</title>
1341 The bookmarks menu can be used to store a list of frequently used directories.
1342 You can also open the menu from the main popup menu (in the <guimenuitem>Window</guimenuitem> submenu)
1343 and you can use this to bind a shortcut key to it. From the bookmarks menu
1344 you can add the currently shown directory to the list, jump to one of the
1345 stored directories, or open a dialog letting you edit the list. In the dialog
1346 box, you can remove entries, rearrange them (using the arrows or by
1347 dragging) and edit the pathnames directly, if required.
1353 <chapter id="icons">
1354 <title>The pinboard and panels</title>
1357 The <xref linkend="run_pin"/> and <xref linkend="run_pan"/> sections explain
1358 how to turn the pinboard and panels on. Once on, you may drop items from filer
1359 windows onto the them to pin them up. Clicking on a pinned item acts just like
1360 clicking on it in a filer window. You can drag pinned icons just like normal
1361 icons and you can right-click on one to see the popup menu.
1363 Drag panel icons with the middle mouse button to move them around.
1364 In previous versions of the filer, pinboard icons were also moved using the
1365 middle mouse button, but this is no longer supported (as the middle button
1366 is reserved for the window manager's use).
1368 You can assign keyboard shortcuts to pinboard and panel icons. These can be
1369 used to open directories, files or applications quickly, even if another
1370 window has the focus.
1372 Changes to the pinboard and panel are automatically saved. Clicking on pinned
1373 icons with <keycap>Control</keycap> held down selects and unselects them.
1374 Click on the background to unselect them all.
1376 If the panel has so many icons that they can't all be shown at once
1377 then you can scroll it by dragging the blank area in the middle.
1381 Pinning a file does <emphasis>not</emphasis> copy it, it merely
1382 creates a shortcut to the original file. If you delete the file, then
1383 you've lost it! Removing a pinned file from its pinboard or panel
1384 only removes the link. This is different to most other filers...
1388 <title>The pinboard and panel menus</title>
1391 <informaltable><tgroup cols="2">
1392 <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
1396 <guimenuitem>ROX-Filer</guimenuitem></entry><entry>
1397 Show the filer's help, edit the options or open your home directory.
1401 <guimenuitem>File `file'</guimenuitem></entry><entry>
1402 Offers a smaller version of the filer's submenu of the same name.
1406 <guimenuitem>Edit Item</guimenuitem></entry><entry>
1407 Change the name displayed under the icon, or the pathname the item
1408 points to. You can also set a keyboard shortcut for the icon here.
1412 <guimenuitem>Show Location</guimenuitem></entry><entry>
1413 Open a directory viewer showing where the file is stored.
1417 <guimenuitem>Remove Item(s)</guimenuitem></entry><entry>
1418 Remove the selected items from the pinboard or panel.
1422 <guimenuitem>Backdrop...</guimenuitem></entry><entry>
1423 Set the desktop backdrop image (see below). Only available from
1427 </tbody></tgroup></informaltable>
1430 If you are setting up the defaults for multiple users and
1431 you wish to create a `Home' icon that leads to each user's home directory
1432 then you should first create a new icon and then use
1433 <guimenuitem>Edit Icon</guimenuitem> to change the location to
1434 <filename>~</filename> and the name to `Home'.
1436 Note that individual applications may add extra menu items to the
1437 top of this menu when you click over them — see <xref linkend="AppDir"/>
1443 <title>Panel applets</title>
1446 <application>ROX-Filer</application> allows you to run small programs
1447 inside the panel — such programs are called
1448 <emphasis>applets</emphasis>. To run an applet, drag it onto the panel from
1449 a filer window and instead of the applet's icon being shown, the applet
1453 <procedure><title>To create your own applets (programmers only!):</title>
1456 Create a directory for the applet (eg <filename>MyApplet</filename>).
1460 Use the <guimenuitem>Set Icon...</guimenuitem> feature to create an icon
1461 called <filename>.DirIcon</filename> inside it (so the directory appears
1466 Make a <filename>Help</filename> directory inside it for when the user
1467 chooses <guimenuitem>Help</guimenuitem> from the menu.
1471 Create an executable file called <filename>AppletRun</filename>. This will be
1472 passed the XID of the panel socket window when the directory is dragged
1473 onto the panel. You can use this to create a GtkPlug widget. An
1474 example applet (written in python) is available at
1475 <ulink url="http://rox.sourceforge.net/applets.php3"/>
1482 <title><anchor id="iconify" xreflabel="Iconified windows"/>Iconified windows on the pinboard</title>
1484 When the pinboard is in use, ROX-Filer can be used to display an icon for each iconified
1485 (or 'minimised') window. You can turn this on or off from the Options box. Iconified window icons
1486 highlight when you move the mouse over them and can be dragged around.
1487 Clicking on one will expand it back into the window it represents. Some older window managers do not
1488 support this, and no icons will be shown.
1493 <title><anchor id="backdropapp" xreflabel="Backdrop applications"/>The pinboard backdrop image</title>
1495 You can set any image for the backdrop by choosing <guimenuitem>Backdrop...</guimenuitem>
1496 from the pinboard menu (right-click over the desktop background when the pinboard is turned on).
1499 To set an image, select <guilabel>Centred</guilabel>, <guilabel>Scaled</guilabel> or
1500 <guilabel>Tiled</guilabel> to set the style, and then drag an image onto the marked area.
1501 To return to a solid colour backdrop (as set in the Options box), click on
1502 <guibutton>Clear</guibutton>.
1504 The Wallpaper<citation>Wallpaper</citation> application can be used for more complicated
1505 effects, such as choosing a new random image each hour, or rendering an image of the Earth
1506 as it is currently lit by the sun.
1508 <formalpara><title>For programmers...</title>
1510 If you want to create an application to set the backdrop (eg, to choose a
1511 random image, or a slideshow) you need to first create an application directory
1512 (see <xref linkend="AppDir"/>).
1515 When run without arguments, the application should invoke the
1516 <function>SetBackdropApp</function> SOAP method (see <xref
1517 linkend="soap"/>). The filer will immediately run the application again,
1518 this time with the <option>--backdrop</option> option.
1520 When run with <option>--backdrop</option>, the program should write the style and name of
1521 the image file to display to its standard output stream, eg:
1522 <screen>tile /tmp/image.png</screen>
1523 <userinput>centre</userinput> and <userinput>scale</userinput> are the other possible
1524 styles. The filer will then load this image and display it. The application does not
1525 set the backdrop itself, it only tells the filer what to display.
1527 In the case of a random backdrop chooser, the program may then quit immediately. If
1528 the application created a temporary image then it should read the line "ok\n" from its
1529 standard input before deleting the image.
1531 If the application wishes to show a sequence of images it should still read "ok\n",
1532 then wait until it's time to display the next image and then write that filename, and
1535 The filer will indicate that the program should stop running by closing the two
1536 streams. The program should clean up and exit at this point. Be sure to catch
1537 SIGPIPE when writing to standard output if you need to delete any temporary files.
1539 See the Wallpaper<citation>Wallpaper</citation> application for a complete example application
1540 (written in python).
1547 <anchor id="media" xreflabel="Removable devices"/>Removable devices
1550 Using removable devices, such as floppy disks and CDROMs under ROX-Filer is quite
1551 simple. However, it is important to understand about <emphasis>mounting</emphasis> and
1552 <emphasis>unmounting</emphasis> devices.
1555 Mounting a device causes its contents to appear in the filesystem. On a typical setup,
1556 the directory <filename>/floppy</filename> is an empty directory on the hard disk.
1557 The floppy device is then mounted onto this directory, causing its contents to appear
1558 inside. For example, a file called <filename>Letter</filename> on the floppy disk will
1559 appear as <filename>/floppy/Letter</filename>.
1562 Devices must be unmounted before the disk is removed. Unmounting causes the system to
1563 write any buffered data to the disk. If you remove a disk without unmounting
1564 it, it will probably be corrupted. CD and Zip drives often lock the tray while the
1565 device is mounted so you can't remove it accidentally.
1568 So that you don't have to specify which device should be mounted at which point in the
1569 filesystem every time you want to use a disk, a preset list is usually found in the
1570 file <filename>/etc/fstab</filename>. ROX-Filer shows mount points (such as
1571 <filename>/floppy</filename>) which are listed here but not mounted with transparent
1572 grey circles overlayed on their icons.
1575 Clicking on one of these mount points will mount the device for you. The circle turns
1576 green to indicate that the device is now mounted. Do <emphasis>not</emphasis> remove
1577 the device while the circle is lit! You can unmount the device by clicking
1578 while holding down <keycap>Shift</keycap> on the <filename>/floppy</filename>
1582 You can also unmount a device by closing its directory window (eg, closing
1583 the view of <filename>/floppy</filename>) and choosing Unmount when prompted. The
1584 filer will only offer to unmount devices this way if they were mounted by
1585 the filer in the first place.
1588 If you want to open a directory without mounting anything (eg, if you want to
1589 see the contents of <filename>/floppy</filename> on the hard disk), you can
1590 click on the unmounted mount point with <keycap>Shift</keycap> held down.
1591 This isn't usually useful, as these directories are typically empty.
1595 <chapter id="virtual">
1597 <anchor id="vfs" xreflabel="Virtual file systems"/>Virtual file systems
1600 Some types of file can be represented as a directory. A typical example
1601 is a zip file, which contains an entire directory structure in compressed
1602 form. It is often useful to be able to open up such a file as if it
1603 was a real directory, and the VFS system allows you to do this.
1605 To use this feature you must have a system such as
1606 AVFS<citation>AVFS</citation> installed, which causes the kernel to support
1607 various Virtual File Systems directly.
1612 <chapter id="minibuffer">
1613 <title><anchor id="mini" xreflabel="Minibuffer"/>The mini-buffer</title>
1616 The mini-buffer is a white bar that appears along the bottom of the
1617 window and allows you to enter some text. Press <keycap>Escape</keycap> to
1618 get rid of it again. It behaves in different ways depending on how you
1623 <title>The path-entry box</title>
1626 This allows you to type in a path directly. As you type the display
1627 is updated to show the item entered visually. The main use is to find
1628 a file in a large directory quickly, but you can also use it for navigating
1629 between directories, or for selecting a full pathname from somewhere
1630 else and pasting it directly into the path-entry box.
1633 <informaltable><tgroup cols="2">
1634 <thead><row><entry>Key</entry><entry>Action</entry></row></thead>
1638 <keycap>Return</keycap></entry><entry>
1639 Open the currently selected item.
1643 <keycap>Tab</keycap></entry><entry>
1644 Shell-style tab completion.
1648 <keycap>Up</keycap>, <keycap>Down</keycap></entry><entry>
1649 Select the previous/next matching entry.
1651 </tbody></tgroup></informaltable>
1656 If you start entering a name beginning with a `.' then the `Show Hidden'
1657 feature is temporarily turned on so that the file can be shown.
1661 Tab completion tries to fill in as many characters for you as it can.
1662 For example, if there are two files in a directory called
1663 <filename>save-mail-nov-1999</filename> and
1664 <filename>save-mail-dec-1999</filename> then typing
1665 <userinput>save</userinput> and pressing <keycap>Tab</keycap> will expand
1666 <userinput>save</userinput> to <userinput>save-mail-</userinput> and beep
1667 to indicate that the match is not complete. If you use tab completion on a
1668 directory and it is unique then the filer will automatically change into
1669 the directory. This behavior should be familiar to shell users.
1672 <informalexample><para>
1673 Let's say you want to locate the documentation for Wine in the directory
1674 <filename>/usr/share/doc</filename> (which is usually very large).
1675 Here's how you could do it:
1680 Open the minibuffer by choosing <guimenuitem>Enter
1681 Path...</guimenuitem> from the <guimenu>Window</guimenu> menu, or
1682 by pressing the slash (<keycap>/</keycap>) key.
1686 Press <keycap>CTRL</keycap>+<keycap>A</keycap> to select the existing
1692 <userinput>u<Tab>sh<Tab>do<Tab>wi<Tab></userinput>.
1693 As you type, the cursor will move to the correct subdirectory.
1694 If it beeps when you press <keycap>Tab</keycap> then you need to supply
1695 more letters, or press <keycap>Return</keycap>.
1700 </para></informalexample>
1704 <title>The shell command box</title>
1707 This provides a quick way of entering shell commands if you don't
1708 want to open an xterm. If you don't know what shell commands are,
1711 Just type in the command and press <keycap>Return</keycap> to execute it.
1712 <keycap>Up</keycap> and <keycap>Down</keycap> arrows move through previously
1714 <keycap>Tab</keycap> does shell-style completion.
1715 Clicking on an item inserts its name into the minibuffer.
1716 If some items are selected then they are assigned to the positional
1717 parameters <userinput>$1</userinput>, <userinput>$2</userinput>, etc.
1719 Opening the minibuffer with a selection adds <computeroutput>"$@"</computeroutput>
1720 to the end of the command — this expands to all the selected files.
1723 <informalexample><para>Examples:
1725 <orderedlist><title>To untar a <filename>.tgz</filename> archive:</title>
1728 Open the minibuffer by choosing <guimenuitem>Shell Command...</guimenuitem> from
1729 the <guimenu>Window</guimenu> menu.
1730 I usually bind this to the bang (<keycap>!</keycap>) key.
1734 Type <userinput>tar xzf</userinput> and click on the file.
1735 The leading space is automatically inserted.
1739 Press <keycap>Return</keycap> to execute it.
1744 <orderedlist><title>To print all the selected files:</title>
1747 Open the shell command minibuffer.
1751 Type <userinput>lpr</userinput> at the beginning of the line and press
1752 <keycap>Return</keycap>.
1757 </para></informalexample>
1759 <itemizedlist><title>Notes</title>
1762 Be careful; you will not be asked to confirm! If in doubt, start the
1763 command with <userinput>xmessage</userinput> so that it will be displayed
1764 rather than executed.
1768 <citerefentry><refentrytitle>sh</refentrytitle></citerefentry>
1769 is always used as the name of the shell to run (mainly because
1770 <citerefentry><refentrytitle>bash</refentrytitle></citerefentry> and
1771 <citerefentry><refentrytitle>csh</refentrytitle></citerefentry> treat
1772 positional parameters differently).
1773 However, <envar>PATH</envar> is searched to find it so you can still use
1774 another shell if you want by naming it sh and putting it in your path.
1778 Commands execute in the background, so you can say:
1780 <command>sleep 240; xmessage Time to go!</command>
1787 <title><anchor id="SelectIf" xreflabel="Select If"/>The conditional
1788 selection box</title> <para>
1790 Use this if you want to automatically select all files in the directory
1791 which match a condition.
1793 <orderedlist><title>For example, to select all files larger than 5Mb:</title>
1796 Open the Select If minibuffer.
1800 Type <userinput>Size > 5Mb</userinput> and press <keycap>Return</keycap>.
1805 Just those files over 5 Mb in size will be selected. The expressions
1806 you can enter are in the same form as described in the
1807 <xref linkend="Searching"/> section, except that
1808 <userinput>prune</userinput> has no effect since the contents of
1809 directories are never checked anyway. You can press <keycap>Tab</keycap>
1810 to jump to each selected file in turn.
1816 <chapter id="actions">
1817 <title>Action windows</title>
1819 Action windows are those boxes that appear while you're doing a
1820 Copy/Move/Link/etc operation. The status line at the top of the window shows
1821 the current directory or object that the window is processing. The scrolling
1822 area below is the log area — it shows what has been done, and questions
1823 may be displayed here.
1826 <imagedata align="center" format="PNG" fileref="../Action.png"/>
1830 Below this are four buttons and some options. All windows have the
1831 <guilabel>Quiet</guilabel> option. When this is on the filer will only
1832 confirm some operations (such as deleting a non-writeable file). Otherwise,
1833 all operations are confirmed.
1835 The buttons work as follows:
1839 <varlistentry><term><guibutton>Yes</guibutton></term><listitem><para>
1840 answers yes to the question displayed in the log area.
1841 </para></listitem></varlistentry>
1843 <varlistentry><term><guibutton>No</guibutton></term><listitem><para>
1844 answers no to the question displayed in the log area.
1845 </para></listitem></varlistentry>
1847 <varlistentry><term><guibutton>Cancel</guibutton></term><listitem><para>
1848 kills the current operation (if any) and closes the action
1850 </para></listitem></varlistentry>
1852 <varlistentry><term><guibutton>Quiet</guibutton></term><listitem><para>
1853 is a quick way to turn <guilabel>Quiet</guilabel> on and click
1854 <guibutton>Yes</guibutton>.
1855 </para></listitem></varlistentry>
1860 You can control which actions get started automatically (without you
1861 having to click on <guibutton>Quiet</guibutton> at the start) from the
1866 <title>Action window options</title>
1869 Some actions have options, which appear as option boxes at the bottom
1870 of the window. They are:
1875 <guilabel>Force</guilabel> means that the filer won't treat non-writeable
1876 files as special. Normally, it confirms the deletion even if
1877 <guibutton>Quiet</guibutton> is pressed.
1878 Note that you still can't remove files from non-writeable directories because
1879 in that case you really don't have permission.
1883 <guilabel>Brief</guilabel> prevents the filer logging a message every time it
1884 does something. Use this to speed things up if large numbers of messages are
1889 <guilabel>Recurse</guilabel> means that doing something to a directory will
1890 also do the same thing to all its contents, and the contents of any
1891 subdirectories, and so on.
1895 <guilabel>Newer</guilabel> will automatically copy a file over an existing one
1896 if the file is newer than the one it replaces (later modification time).
1902 You can set the defaults for these options from the Options box.
1907 <chapter id="searching">
1908 <title><anchor id="Searching" xreflabel="Searching"/>Searching</title>
1910 The Find feature looks through all the selected files and directories
1911 and any subdirectories (recursively) looking for items that match
1912 a particular expression.
1914 Choose <guimenuitem>Find</guimenuitem> from the <guimenu>File</guimenu>
1915 submenu to search all the selected objects. If you want to select all the
1916 files within a single directory which meet certain criteria, use
1917 <guimenuitem>Select</guimenuitem> -> <guimenuitem>Select If...</guimenuitem>
1920 If you know the name of a file then just enter it in the `Expression:'
1921 box, enclosed in single quotes. For example, to find a file called
1922 <filename>log</filename> you would enter <userinput>'log'</userinput>.
1924 Remember to use normal quotes, not double quotes (") or back-quotes (`).
1926 As the filer finds matching files they are added to the results list.
1927 Double-clicking on an entry in the list opens a viewer showing that file.
1928 The filer will use the same window to view other results (so, if you want
1929 the results shown in separate windows you must explicitly create a new
1930 window from the <guimenu>Window</guimenu> menu).
1934 <title>Wildcards</title>
1937 You can also put shell-style wildcard characters inside the quotes,
1942 <member><command>'*.html'</command></member>
1943 <member><command>'Report.*'</command></member>
1944 <member><command>'Draft[1-5]'</command></member>
1945 <member><command>'main.[ch]'</command></member>
1950 <citerefentry><refentrytitle>glob</refentrytitle>
1951 <manvolnum>7</manvolnum></citerefentry>
1952 manpage if you want to know more about shell wildcards.
1954 If the pattern you enter contains a slash (`/') character then the
1955 pattern is matched against the file's full path, otherwise only the
1956 leafname is used. That is, <userinput>'*tmp*'</userinput> will find
1957 <filename>tmp</filename> and <filename>tmpfile</filename> but not
1958 <filename>/tmp/file</filename> — <userinput>'/*tmp*'</userinput> will find
1964 <title>Simple tests</title>
1966 As well as finding files by their names you can also find them by
1967 various other attributes. Note that <emphasis>file</emphasis> is used here to
1968 mean anything that can appear in the filesystem — including directories,
1971 You can also use a short form for each test; these are shown in brackets.
1972 You can combine multiple tests — `<userinput>-rw</userinput>' is
1973 the same as `<userinput>IsReadable and IsWriteable</userinput>'.
1976 <itemizedlist><title>These look at the type of the item being checked:</title>
1979 <userinput>IsReg (-f)</userinput> matches any regular (ie, normal) file.
1983 <userinput>IsLink (-l)</userinput> matches symlinks.
1987 <userinput>IsDir (-d)</userinput> matches directories.
1991 <userinput>IsChar (-c)</userinput> matches character device files.
1995 <userinput>IsBlock (-b)</userinput> matches block device files.
1999 <userinput>IsDev (-D)</userinput> matches block or character device files.
2003 <userinput>IsPipe (-p)</userinput> matches pipes.
2007 <userinput>IsSocket (-S)</userinput> matches sockets.
2012 <itemizedlist><title>These look at the permissions set on the file —
2013 see the <xref linkend="Permissions"/> section.</title>
2016 <userinput>IsSUID (-u)</userinput> matches files which have the Set-UID
2017 bit set.</para></listitem>
2020 <userinput>IsSGID (-g)</userinput> matches files which have the Set-GID
2021 bit set.</para></listitem>
2024 <userinput>IsSticky (-k)</userinput> matches files with the sticky bit
2025 set.</para></listitem>
2028 <userinput>IsReadable (-r)</userinput> matches files which you can read
2029 from.</para></listitem>
2032 <userinput>IsWriteable (-w)</userinput> matches files which you can write to.
2036 <userinput>IsExecutable (-x)</userinput> matches files which you can execute.
2041 <itemizedlist><title>And a couple of other useful ones:</title>
2044 <userinput>IsEmpty (-z)</userinput> finds empty files (ie, those whose
2049 <userinput>IsMine (-o)</userinput> finds files which you own.
2057 <title>Logic operators</title>
2059 You can combine the above tests in various ways to perform more advanced
2061 An expression is actually made up of a list of <emphasis>cases</emphasis>,
2062 separated by commas. The filer will try to match each case in turn
2063 until one matches or there are no more cases left. For example, to
2064 search for files with several possible endings:
2066 <screen>'*.gif', '*.htm', '*.html'</screen>
2068 Further, each of the cases is actually a list of conditions. The case
2069 only matches if all of its conditions are met. So, to find a directory
2070 called <filename>lib</filename> or a regular file ending in
2071 <filename>.so</filename>:
2073 <screen>IsDir 'lib', IsReg '*.so'</screen>
2075 You can negate a condition by putting a <userinput>!</userinput> in front
2076 of it and you can use a sub-expression as a condition by bracketing it,
2084 Not isdir and not isreg
2087 All four do the same thing.
2092 <title>Comparisons</title>
2094 You can also compare various values using the operators
2095 <userinput><</userinput>,
2096 <userinput><=</userinput>,
2097 <userinput>=</userinput>,
2098 <userinput>!=</userinput>,
2099 <userinput>></userinput>, and
2100 <userinput>>=</userinput>
2101 (for less-than, less-than-or-equal-to, equal-to,
2102 not-equal-to, greater-than and greater-than-or-equal-to).
2104 When comparing times, you may find it helpful to use
2105 <userinput>after</userinput> and <userinput>before</userinput> instead of
2106 <userinput>></userinput> and <userinput><</userinput> to make things
2110 <itemizedlist><title>
2111 The following are read from the file being checked and may be used
2112 for the values being compared:
2116 <userinput>atime</userinput> The time that the file was last accessed.
2120 <userinput>ctime</userinput> The time that the file's status was last changed.
2124 <userinput>mtime</userinput> The time that the file's contents were last modified.
2128 <userinput>size</userinput> The size of the file.
2132 <userinput>inode</userinput> The file's inode (index) number.
2136 <userinput>nlinks</userinput> The number of links to this file. That is,
2137 the number of directory entries which refer to this file. Note that
2138 symlinks don't count as references.
2142 <userinput>uid</userinput> The User ID of the file.
2146 <userinput>gid</userinput> The Group ID of the file.
2150 <userinput>blocks</userinput> The number of disk blocks being used by the file.
2156 Times are measured as seconds since the Unix Epoch (00:00:00 UTC,
2157 January 1, 1970). Sizes are in bytes. When specifying constants to
2158 compare these values with you may use various keywords to scale the
2164 <userinput>Byte(s)</userinput> has no effect, but looks better.
2168 <userinput>Kb</userinput> multiplies by 1024, so 2Kb is the same as 2048.
2172 <userinput>Mb</userinput> multiplies by 1024<superscript>2</superscript>,
2177 <userinput>Sec(s)</userinput> has no effect, but looks nice.
2181 <userinput>Min(s)</userinput> multiplies by 60 to get minutes.
2185 <userinput>Hour(s), Day(s), Week(s), Year(s)</userinput> likewise
2186 convert to the relevant unit.
2190 <userinput>Ago</userinput> makes the time in the past relative to when
2195 <userinput>Hence</userinput> makes the time in the future.
2199 <userinput>Now</userinput> is short for <userinput>0 Secs Hence</userinput>.
2204 Some examples should make this all a bit clearer!
2207 mtime after 1 day ago
2211 IsReg and nlinks > 1</screen>
2212 The first finds files modified within the last 24 hours. You could
2213 use <userinput>></userinput> instead of <userinput>after</userinput>,
2214 but it's not so clear what is meant.
2216 The second finds files larger than 10 Mb. The last finds regular files with
2217 more than one directory entry.
2219 Be careful though — the filer doesn't check the context of the
2220 modifiers, so <userinput>size > 1 day ago</userinput> is allowed,
2221 although it doesn't make much sense!
2223 Also, forgetting to use <userinput>ago</userinput> or
2224 <userinput>hence</userinput> will cause odd effects (the time will be
2225 measured relative to the Epoch rather than the current time).
2226 Finally, don't use <userinput>=</userinput> with times —
2227 <userinput>atime = 1 day ago</userinput> looks for a file accessed
2228 <emphasis>exactly</emphasis> 86400 seconds ago...
2234 <title>Specials</title>
2240 <userinput>System(Command)</userinput> executes `Command' on the file.
2241 The test succeeds if the command returns an exit status of zero. A `%'
2242 character in `Command' is replaced by the full path of the file being
2243 checked. <userinput>System</userinput> is a very slow test to perform,
2244 so do it last if possible. For example, if you're looking for a
2245 <filename>.c</filename> file containing the word `main', do:
2247 <screen>'*.c' system(grep -q main "%")</screen>
2248 so that the grep is only performed for files ending in <filename>.c</filename>
2249 (as opposed to only checking that the file ends in <filename>.c</filename> if
2250 it contains the word `main').
2254 <userinput>Prune</userinput> Always fails!
2255 <footnote><para>Note that this is the opposite of the
2256 <citerefentry><refentrytitle>find</refentrytitle><manvolnum>1</manvolnum>
2257 </citerefentry> command.</para></footnote>
2259 However, if it gets evaluated at all then it prevents the filer
2260 from checking inside the current directory. Remember the order in which
2261 the filer checks the expression!
2269 '*.old' system(rm '%')
2271 'src' prune, '*.c'</screen>
2272 The first deletes each file ending in <filename>.old</filename>.
2273 The second looks for <filename>.c</filename> files, but does not bother
2274 checking inside directories called <filename>src</filename>.
2275 The expression is evaluated like this:
2277 If file is named <filename>src</filename> then `Prune'.
2278 Either way, check if it ends in <filename>.c</filename> and include
2279 it in the results if so.
2284 <chapter id="options">
2285 <title>Options</title>
2288 You can configure various aspects of <application>ROX-Filer</application>
2289 from the Options box.
2290 Choose <guimenuitem>Options...</guimenuitem> from a filer window menu to
2291 open it. The list on the left of the window lists the various sections —
2292 click on one to see its options.
2294 At the bottom of the window are two buttons:
2299 <guibutton>OK</guibutton>
2300 saves the current choices into your Choices directory for next time
2301 <application>ROX-Filer</application> is loaded, if anything changed.
2302 Exactly where choices are loaded from and saved to is controlled by the
2303 <envar>CHOICESPATH</envar> environment variable — see
2304 <citation>Choices</citation> for details.
2305 Changes made in the Options box take effect instantly, so you don't need to
2306 click on <guibutton>OK</guibutton> just to try them out.
2310 <guibutton>Revert</guibutton>
2311 Restores all choices to how they were when the options box was opened.
2312 This button is shown shaded if you haven't made any changes.
2313 The Options window is not closed when this is used.
2318 Many of the options in the Options window have tooltips — hold the
2319 mouse pointer over the option to find out what it does.
2324 <title>Translation options</title>
2327 You can choose which language the filer will display messages in from
2328 here, or get it to read the LANG environment variable to get the desired
2335 <title>Filer window options</title>
2339 <listitem><para><guilabel>Automatically resize filer windows</guilabel> can be
2340 used to control when windows are automatically resized:
2343 <listitem><para><guilabel>Never automatically resize</guilabel>
2344 turns off auto-resizing. Windows must be resized manually.
2347 <listitem><para><guilabel>Resize when changing the display style</guilabel>
2348 will resize the window automatically when you change the icon size or
2349 the type of details to be displayed.
2352 <listitem><para><guilabel>Always resize</guilabel>
2353 causes the window to resize whenever it seems useful (that is, when
2354 changing to a different directory or when switching between display
2361 <listitem><para> <guilabel>Largest window size</guilabel> sets the largest size
2362 (as a percentage of the screen size) that the auto-resizer will resize windows
2366 <listitem><para> <guilabel>Change from Large icons to Small automatically</guilabel>
2367 allows the filer to choose the size when changing directory. The
2368 switching threshold is set using the number entry below.
2371 <listitem><para> <guilabel>Short titlebar flags</guilabel> abbreviates
2372 the All, Thumbs and Scanning titlebar indicators to single letters.
2375 <listitem><para> <guilabel>Unique windows</guilabel> prevents you from having
2376 two windows showing the same directory. Opening a second view onto a directory
2377 simply reshows the first one.
2380 <listitem><para> <guilabel>New window on button 1</guilabel> swaps the
2381 actions of the two non-menu buttons when opening directories. This is
2382 provided for people who are used to the RISC OS mouse bindings.
2385 <listitem><para> <guilabel>Single-click navigation in filer windows</guilabel>
2386 means that clicking on a file or directory will open it. If off, clicking on
2387 files selects them instead — you must double click on a file to open it.
2394 <title>Display options</title>
2399 <listitem><para><guilabel>Directories always come first</guilabel> means that
2400 all directories are sorted and displayed at the top, then all the other items
2401 are sorted and displayed below. With this option off, directories are mixed in
2402 with the other files.
2405 <listitem><para><guilabel>Large wrap width</guilabel> sets the maximum width
2406 for a file's name in `Large Icons' display mode before the text will wrap onto
2407 two lines. In `Huge Icons' mode, the wrap width is 50% larger than this value.
2410 <listitem><para><guilabel>Max Small Icons width</guilabel> — in
2411 `Small Icons' mode, any text longer than this is chopped off (a red bar
2412 indicates that some text is not shown). You can hold the mouse over the
2413 truncated name to see the full text.
2416 <listitem><para><guilabel>Default settings for new windows</guilabel> —
2417 these options provide the default settings for newly opened
2418 windows. They correspond to choosing styles from the
2419 <guimenuitem>Display</guimenuitem> menu.
2420 If <guilabel>Inherit options from source window</guilabel>
2421 is on then opening a new window from an existing window
2422 (eg, by clicking the middle button over a directory) gives the new window
2423 the same options (icon size, sort order, etc) as the old window. If
2424 off, the new window has the default settings chosen here.
2431 <sect2><title>Toolbar options</title>
2433 The toolbar is described in the <xref linkend="Toolbar"/> section.
2435 <listitem><para> <guilabel>Unshade the tools you want:</guilabel> allows
2436 you to set which tools should appear on the toolbar. Click on the
2437 buttons below to shade and unshade them — shaded tools will not be
2438 shown on filer window toolbars.
2441 <listitem><para> <guilabel>Toolbar type</guilabel> allows you to choose
2442 what kind of toolbars you want.
2443 <guimenuitem>None</guimenuitem> means that windows will not have a
2445 <guimenuitem>Icons only</guimenuitem> provides a small bar of icons,
2446 <guimenuitem>Text under icons</guimenuitem> displays larger buttons,
2447 with textual labels below, and
2448 <guimenuitem>Text beside icons</guimenuitem> displays wider buttons,
2449 with textual labels next to the icons.
2452 <listitem><para> <guilabel>Show totals of items</guilabel> shows the
2453 number of items displayed in a filer window, as well as the number of
2454 hidden items (if any) on the toolbar. When there's a selection, it
2455 shows the number of selected items and their combined size (excluding
2464 <sect2><title>Minibuffers</title>
2466 These two options control what happens when you press <keycap>Tab</keycap>
2467 in the path entry minibuffer:
2471 <listitem><para> <guilabel>Beep if Tab-completion fails</guilabel> — beep
2472 if there is no match, or there are several possible completions, each starting
2476 <listitem><para> <guilabel>Beep if there are several matches</guilabel> —
2477 beep if there are several matches, even though some letters were added.
2486 <title>Pinboard options</title>
2488 See the <xref linkend="run_pin"/> section for instructions on enabling the
2493 <listitem><para><guilabel>Colours</guilabel>
2494 sets the colours used for the text under the icons, and the background colour
2495 (if no background image is set). You can also choose to give the text a
2496 shadow, which can help with some backgrounds.
2499 <listitem><para><guilabel>Use custom font</guilabel> can be used to set a
2500 different font for pinboard icons. If unset, the global default font, as set
2501 by your session manager (eg ROX-Session) is used.
2504 <listitem><para><guilabel>Single-click to open</guilabel>
2505 allows you to open a file or directory just by clicking on it. Hold down
2506 <keycap>Control</keycap> to select things. If this is off, clicking selects
2507 and double-clicking opens.
2510 <listitem><para><guilabel>Keep icons within screen limits</guilabel>
2511 prevents icons from going partly off the side of the screen.
2514 <listitem><para> <guilabel>Icon grid step</guilabel> controls how finely
2515 the icons may be positioned.
2518 <listitem><para> <guilabel>Iconified windows</guilabel> controls how the
2519 filer deals with iconified (or 'minimised') windows. If
2520 <guilabel>Show iconified windows</guilabel> is on then the filer shows
2521 an icon on the pinboard for each iconified window. The other two options
2522 let you choose the method of placing the icons. See <xref linkend="iconify"/>
2532 <title>Panel options</title>
2535 If you are using panels (see the <xref linkend="run_pan"/> section)
2536 then this section lets you choose which icons will have textual labels
2538 You can have labels on all icons, on no icons, or on all icons except
2545 <title>Action window options</title>
2548 You can choose to start some operations automatically, without waiting
2549 for you to click on <guibutton>Quiet</guibutton>.
2550 Select each operation that you want to auto-start here. You can also set
2551 the default state for each of the options that appear inside action
2558 <title>Drag-And-Drop options</title>
2562 <listitem><para><guilabel>Allow dragging to icons in filer
2563 windows</guilabel> controls what happens when you drop files onto icons
2564 in filer windows. If on then drops onto directories will save the data
2565 inside the directory, while dropping onto programs will invoke the
2566 program on that data. If off then drops anywhere inside a filer window
2567 act like drops onto the window background — that is, the data will
2568 be saved into the directory being displayed.
2571 <listitem><para><guilabel>Directories spring open</guilabel> controls what
2572 happens when you hold a file over a directory while dragging it. If on,
2573 the directory will `spring open' after a short pause, allowing you to
2574 navigate to any directory during a drag. You can also hold the pointer
2575 over the Home and Up buttons on the toolbar for a similar effect. You
2576 need to have the previous option enabled for this to have any effect on
2577 files displayed in a directory.
2580 <listitem><para><guilabel>Spring delay</guilabel> sets how long, in
2581 thousanths of a second, the filer will wait before spring opening a
2582 directory as described above. If the above option is turned off, then
2586 <listitem><para><guilabel>Dragging files with the middle mouse button</guilabel>
2587 you can choose whether this displays a menu (like <keycap>Alt</keycap>
2588 dragging) or moves the files (like <keycap>Shift</keycap> dragging).
2597 <title>Menu options</title>
2602 <listitem><para><guilabel>Menu on button 2</guilabel> swaps the actions
2603 of buttons 2 and 3 so that the middle button brings up the menus. This
2604 is provided for people who are used to the RISC OS mouse bindings.
2606 As an alternative to using the options window to put menu on button-2,
2607 some people prefer to use the command <command>xmodmap -e "pointer
2608 = 1 3 2"</command>, which makes the right mouse button button-2 and
2609 the middle one button-3 (this affects all programs, not just
2610 <application>ROX-Filer</application>).
2613 <listitem><para><guilabel>Size of icons in menus</guilabel> controls the
2614 size of the icons in the <guimenuitem>Send To</guimenuitem> and
2615 <guimenuitem>New</guimenuitem> menus.</para></listitem>
2617 <listitem><para><guilabel>Xterm here program</guilabel> is the command
2618 used when you choose <guimenuitem>Xterm here</guimenuitem> from the
2619 menu. You can replace it with another command such as
2620 <command>gnome-terminal</command>, <command>konsole</command>, or
2621 anything else.</para></listitem>
2628 <title>Types</title>
2630 <guilabel>Ignore eXecutable bit for known extensions</guilabel> means that
2631 when a file has a known extension (eg <filename>.gif</filename>) the
2632 executable bit is ignored. This is useful if you have files on a
2633 Windows-type filesystem which are being shown as executable programs.
2634 However, it prevents a file such as <filename>script.sh</filename> from
2635 being treated as a program.
2637 The MIME type system used in the filer is described more fully in
2638 <xref linkend="types"/>.
2640 <listitem><para><guibutton>Show name-to-type rules</guibutton>
2641 opens the directories containing the files which tell the filer what
2642 type to give each file.</para></listitem>
2644 Make sure you run the `update-mime-database' command after editing the files,
2645 and click on the Refresh toolbar button to make the filer read the new
2649 <sect2><title>Colours</title>
2651 <guilabel>Colour files based on their types</guilabel>. If on, each
2652 file's name is coloured depending on what kind of thing it is (regular
2653 file, directory, executable, etc). You can choose the colours from the
2660 <sect1><title>Compatibility</title>
2663 <listitem><para><guilabel>Override window manager control of the pinboard
2664 and panels</guilabel> may need to be turned on to stop older window managers from
2665 trying to display the pinboard and panels in a normal window, or from raising them
2666 when clicked and from doing other odd things.
2668 <listitem><para><guilabel>Pass all backdrop mouse clicks to window manager</guilabel>
2669 may be needed if your window manager has important functions on these buttons.
2670 Normally, clicking button-3 will display the filer's pinboard menu, and
2671 button-1 dragging allows you to select multiple icons.
2673 <listitem><para><application>ROX-Filer</application> uses the standard
2674 XDND protocol for drag-and-drop. This protocol recommends that URIs
2675 should contain the hostname of the computer that the resource is on so
2676 that the program receiving the data can determine whether it can get the
2677 data directly or whether it must go via the X-server. However, many
2678 older programs (particularly GNOME applications) get confused by the
2679 hostname and fail to load the data correctly. If <guilabel>Don't use
2680 hostnames</guilabel> is on then the hostname part is omitted and
2681 <application>ROX-Filer</application> will work with these applications
2682 BUT you can't drag data to a program running on a different machine.
2690 <chapter id="types">
2691 <title>Filetypes</title>
2694 All files have a MIME type in the form <emphasis>text/plain</emphasis>. Here,
2695 <emphasis>text</emphasis> is the <emphasis>media type</emphasis> and
2696 <emphasis>plain</emphasis> is the <emphasis>sub-type</emphasis>.
2698 <application>ROX-Filer</application> uses a file's name to decide what its MIME
2699 type is, and then uses the MIME type to decide what icon to give it and what
2700 program to use when you open the file.
2704 <title><anchor id="RunAction" xreflabel="the Set Run Action box"/>
2709 This box appears when you choose <guimenuitem>Set Run Action...</guimenuitem>
2710 from the File menu, and is used to set which application is loaded when you click
2713 For example, let's say you want to set things up so that opening a
2714 <filename>.gif</filename> file loads it into the Gimp.
2715 First, right-click over a gif image to open the menu and choose
2716 <guimenuitem>Set Run Action...</guimenuitem> from the
2717 <guimenuitem>File</guimenuitem> submenu.
2718 Then, you have a choice of two methods to set the run action:
2721 <sect2><title>Setting the run action by drag-and-drop</title>
2723 Drag the Gimp (from a filer window, a panel or the pinboard) onto
2724 the area marked <guilabel>Drop a suitable application here</guilabel>.
2725 From now on, clicking on a GIF file will load it into the Gimp.
2729 <sect2><title>Setting the run action by entering a shell command</title>
2731 Type: <userinput>gimp "$@"</userinput>
2732 into the box labelled <guilabel>Enter a shell command</guilabel> and press
2733 <keycap>Return</keycap>. <userinput>$@</userinput>
2734 will be replaced by the name of the file you click on when this command
2735 is used. As before, clicking on any GIF image will now load it into
2740 <sect2><title>Setting the default media-type handlers</title>
2742 Whichever method you use to set the action you have the choice of
2743 setting the run action just for that type, or setting the default
2744 for all files with that media-type which don't already have a specific
2747 Since the Gimp can load many types of image, it makes sense
2748 to select the <guilabel>Set default for all `image/<anything>'</guilabel>
2749 option so you don't have to do it again for image/jpeg files and so on. However,
2750 this only affects types that don't already have a specific action
2751 (ie, those that would have brought up an error box if you tried to
2758 <title><anchor id="SetIcon" xreflabel="the Set Icon box"/>
2763 This box appears when you choose <guimenuitem>Set Icon...</guimenuitem>
2764 from the File menu, and is used to set which image to use to represent
2767 It works much like the Set Run Action box described above, except that
2768 you may specifiy an icon for one file individually (by name) as well as
2769 for all files of a particular type. When setting the icon for a single
2770 file, the filer stores the name of the file and the name of the icon inside
2771 your Choices directory. If either moves, the icon won't be displayed.
2773 When setting the icon for a directory, you have the additional option of
2774 storing the image inside the directory itself as a hidden file. This means
2775 that other users will see the icon too, and you can safely delete the original
2776 image after the copy (note that the image is scaled down if needed, and converted
2779 The directory icon inside the <guilabel>Drop an icon here</guilabel>
2780 area allows you to quickly get to a directory from which you are already
2781 using one or more icons.
2786 <title>How filetypes are stored</title>
2789 <application>ROX-Filer</application> uses two sub-directories in your Choices
2790 directory for filetypes:
2794 <varlistentry><term><filename>MIME-types</filename></term><listitem><para>
2795 contains symlinks, one for each MIME type, which point
2796 to programs that can handle files of that type. To set what program
2797 is run when you click on the file you should normally use the <guimenuitem>Set
2798 Run Action...</guimenuitem> feature (see the <xref linkend="RunAction"/> section).
2799 However, you can also set the actions manually — for example, to make
2800 opening an HTML file load it into Netscape:
2804 Find the Netscape application and go to <guimenuitem>Link...</guimenuitem>
2809 Enter <userinput>text_html</userinput> as the name for the link and drag the
2810 icon from the Link box into the <filename>MIME-types</filename> directory.
2815 You can also put actual programs in here as well as links if you want
2817 </para></listitem></varlistentry>
2819 <varlistentry><term><filename>MIME-icons</filename></term><listitem><para>
2820 contains the images used to display each type of file.
2821 So the filer will try to display an HTML file using the icon
2822 <filename>MIME-icons/text_html.png</filename>.
2823 </para></listitem></varlistentry>
2827 In both <filename>MIME-types</filename> and <filename>MIME-icons</filename>
2828 directories you can also provide default actions/images for each media type.
2829 For example, if <filename>text_html</filename> isn't found then the filer
2830 will try simply using <filename>text</filename>.
2834 The filer works out the type for a file from its name. The rules come from
2835 various <filename>globs</filename> files — see
2836 <citation>SharedMIME</citation> for details.</para>
2840 <chapter id="appdirs">
2841 <title><anchor id="AppDir" xreflabel="Application directories"/>
2842 Application directories
2845 An application directory is a directory which can be run as an application.
2846 It contains all the resources of an application — source code, binaries,
2847 documentation and so on. Keeping everything in one place make installation
2848 and uninstallation much easier for users. You can also keep multiple
2849 versions of a program by simply having several application directories.
2850 You may move and rename them as you please. Application directories
2851 make programs easier to use and install.
2853 They're more secure too, because you can compile an application as a user and
2854 then simply copy it as root. Since you don't have to run an install script
2855 you are free from the danger of running untrusted code as root. All you have
2856 to watch out for is setuid binaries.
2859 The following files are treated as special by
2860 <application>ROX-Filer</application>:
2865 <filename>AppRun</filename>
2866 is executed when you click on the directory — make sure
2867 it is executable (use the Permissions box)!
2871 <filename>.DirIcon</filename>
2872 is the image used to represent the directory (this works even if
2873 there is no <filename>AppRun</filename>).
2877 <filename>Help</filename>
2878 is the directory to be opened when you choose <guimenuitem>Help</guimenuitem>
2883 <filename>AppInfo.xml</filename>
2884 contains extra information about an application (see below).
2888 <filename>AppIcon.xpm</filename>
2889 is used if <filename>.DirIcon</filename> is missing (for backwards
2890 compatibility; not to be used anymore).
2895 Have a look at the <filename>ROX-Filer</filename> application directory for a
2900 <note><para>For security reasons, an application directory must have the
2901 same owner as the <filename>AppRun</filename> file inside.</para></note>
2904 <title>The AppInfo file</title>
2907 <filename>AppInfo.xml</filename> is an XML file with the following structure
2908 (any elements may be omitted, and the file itself is optional):
2911 <?xml version="1.0"?>
2913 <Summary xml:lang="en">A graphical file manager</Summary>
2914 <Summary xml:lang="de">Ein grafische Datei-Manager</Summary>
2915 <Summary xml:lang="nl">Een grafisch bestandsbeheerprogramma</Summary>
2916 <Summary xml:lang="es">Un manejador de archivos gráafico</Summary>
2917 <About xml:lang="en">
2918 <Purpose>File manager</Purpose>
2919 <Version>1.3.5 PREVIEW</Version>
2920 <Authors>Thomas Leonard and others</Authors>
2921 <License>GNU General Public License</License>
2922 <Homepage>http://rox.sourceforge.net</Homepage>
2924 <About xml:lang="es">
2925 <Purpose>Manejador de Archivos</Purpose>
2926 <Authors>Thomas Leonard y otros</Authors>
2929 <Item option="-p=Default">
2930 <Label>Enable pinboard</Label>
2931 <Label xml:lang="es">Habilitar el pinboard</Label>
2933 <Item option="-p=">
2934 <Label>Disable pinboard</Label>
2935 <Label xml:lang="es">Deshabilitar el pinboard</Label>
2944 <userinput>Summary</userinput>
2945 is displayed in a tooltip when the mouse is held over the application.
2949 <userinput>About</userinput>
2950 contains a list of fields which are shown in the `File Info'
2951 box for the application (any element names may be used, but the above
2956 <userinput>AppMenu</userinput>
2957 is a list of extra menu items to display for the application.
2958 When one is chosen, <filename>AppRun</filename> is called with
2959 <userinput>option</userinput> as its only argument. You can nest
2960 AppMenus inside other AppMenus.
2970 <title>Internationalisation</title>
2976 <title><anchor id="LANG" xreflabel="Translations"/>
2977 Selecting a translation
2981 <application>ROX-Filer</application> is able to translate many of its messages,
2982 provided suitable translation files are provided:
2985 <listitem><para>Open the Options box from the menu,</para></listitem>
2986 <listitem><para>Select a language from the menu at the top,</para></listitem>
2987 <listitem><para>Click on <guibutton>Save</guibutton> and restart the filer
2988 for the new setting to take full effect.</para></listitem>
2995 <title>Creating a new translation</title>
2999 <listitem><para>Go into the <filename>src</filename> directory and create
3000 the file <filename>messages.pot</filename>:
3004 $ make messages.pot</screen>
3008 <listitem><para>Copy the file into the <filename>po</filename>
3009 subdirectory under <filename>src</filename> as
3010 <filename><name>.po</filename>. Eg, if your
3011 language is referred to as `ml' (`my language'):
3013 <screen>$ cp messages.pot po/ml.po</screen>
3016 <listitem><para>Load the copy into a text editor.</para></listitem>
3018 <listitem><para>Fill in the translations, which are all blank to start with.
3021 <listitem><para>Run the <filename>make-mo</filename> script to create the
3022 binary file which <application>ROX-Filer</application> can use.
3023 You will need the GNU gettext package for this.
3024 If you don't have it then just send me the <filename>.po</filename> file
3025 and I'll convert it for you.
3028 $ cd ROX-Filer/src/po
3030 Created file ../../Messages/ml.gmo OK</screen>
3033 <listitem><para>Edit <filename>ROX-Filer/Options.xml</filename> so that
3034 your language is listed, restart the filer and select it from the Options box
3035 (see the <xref linkend="LANG"/> section).
3038 <listitem><para>Submit the <filename>.po</filename> file to me so that I
3039 can include it in future releases of the filer.
3047 <title>Updating an existing translation</title>
3051 <listitem><para>Go into the directory containing the <filename>.po</filename>
3052 files and run the <filename>update-po</filename> script.
3053 This checks the source code for new and changed strings and updates all
3054 the translation files.
3057 $ cd ROX-Filer/src/po
3058 $ ./update-po</screen>
3061 <listitem><para>Edit the file by hand as before, filling in the new blanks
3062 and updating out-of-date translations.
3063 Look out for <computeroutput>fuzzy</computeroutput> entries where
3064 <command>update-po</command> has made a guess; check it's correct and
3065 remove the <computeroutput>fuzzy</computeroutput> line.
3068 <listitem><para>Run <command>make-mo</command> as before.</para></listitem>
3070 <listitem><para>Submit the updated file to me.</para></listitem>
3074 See the <command>gettext</command> info page for more instructions on creating
3081 <chapter id="hacking">
3082 <title>Hacking</title>
3084 This is a quick start guide for people who want to modify the source
3085 code. If you make useful changes or fix bugs, please send patches
3086 to me or to the mailing list. Tell me which version you're using!
3090 <title>Compiling</title>
3092 The first time you compile the program you need to do <command>AppRun
3093 --compile</command>, but in future you only need to run <command>make</command>
3094 in the <filename>src</filename> directory when you change the
3095 <filename>.c</filename> and <filename>.h</filename> files.
3096 You might want to run <command>make depend</command> too.
3101 <title>Creating and applying patches</title>
3103 When people make small modifications to the sources they will often
3104 distribute them as <emphasis>patch files</emphasis> — usually on the
3107 To apply a patch, go into the <filename>src</filename> directory and run
3108 <command>patch</command> with the patch file. Then recompile, like this:
3112 $ patch < patchfile
3113 $ ../AppRun --compile</screen>
3115 You can remove the patch by simply repeating the above sequence —
3116 <command>patch</command> will detect that the patch is already applied
3117 and offer to remove it.
3119 To create a patch you should first get the latest version of the filer
3120 from CVS (instructions on using CVS can be found on the web-site).
3121 Modify the program as you please. Create the patch using
3122 <command>cvs diff</command> from the appropriate directory:
3124 <screen>$ cvs diff -u > my_patch</screen>
3126 This creates a human– and machine-readable patch file. Submit this
3127 to the mailing list. The are many reasons for posting patches rather
3128 that the modified files:
3131 <listitem><para>They are smaller, and hence shouldn't bounce.
3132 They are also quicker to download for people with slow connections.
3135 <listitem><para>People can see what they're getting into before applying them!
3138 <listitem><para>Patches can (usually) be applied to slightly modified
3139 versions of the sources. This means that people can apply several patches
3140 without each new one overwriting the others.
3149 <title>Autoconf</title>
3151 Here's a quick explanation of the autoconf system in case you haven't
3152 used it before. See <command>info autoconf</command> for full details.
3154 There's a file called <filename>configure.in</filename> which contains
3155 various tests (<command>info autoconf</command>).
3156 You run <command>autoconf</command> and it reads through the file
3157 and generates a shell script to perform the tests, saving it as
3158 <filename>configure</filename>.
3159 <filename>configure</filename> is normally distributed with the program because
3160 not everyone has autoconf.
3162 You then run <filename>configure</filename> (in fact, let the
3163 <filename>AppRun</filename> script do it because
3164 it passes it some arguments), which performs all the tests. It reads
3165 in <filename>Makefile.in</filename> and <filename>config.h.in</filename>
3166 and fills in the missing values with the test results to produce
3167 <filename>Makefile</filename> and <filename>config.h</filename>.
3169 You run <command>make</command>, which creates <filename>.o</filename>
3170 files from the <filename>.c</filename> files and links to produce
3171 <filename>ROX-Filer</filename>.
3175 <sect1><title>Data-structures</title>
3177 The <filename>global.h</filename> file lists each major data-structure used
3178 in the filer and explains its purpose. This is a good place to start reading
3179 if you want to know how the filer works.
3184 <appendix id="manpage"><title>Manual page</title>
3189 <refentrytitle>ROX</refentrytitle>
3190 <manvolnum>1</manvolnum>
3194 <refname>ROX-Filer</refname>
3195 <refpurpose>a simple graphical file manager</refpurpose>
3200 <command>rox</command>
3201 <arg choice="opt" rep="repeat"><option>OPTION</option></arg>
3202 <arg choice="opt" rep="repeat">FILE</arg>
3206 <refsect1><title>DESCRIPTION</title>
3208 ROX-Filer is a simple and easy to use graphical file manager for X11, the
3209 windowing system used on Unix and Unix-like operating systems.
3211 It is also the core component of the ROX Desktop:
3212 <ulink url="http://rox.sourceforge.net"/>
3214 Invoking <command>rox</command> opens each directory or file listed,
3215 or the current working directory if no arguments are given.
3219 <refsect1><title>COMMAND-LINE OPTIONS</title>
3223 <varlistentry><term><option>-b</option></term><term><option>--bottom=PANEL</option></term>
3224 <listitem><para>open PANEL as a bottom-edge panel.
3225 </para></listitem></varlistentry>
3227 <varlistentry><term><option>-c</option></term><term><option>--client-id=ID</option></term>
3228 <listitem><para>used for session management.
3229 </para></listitem></varlistentry>
3231 <varlistentry><term><option>-d</option></term><term><option>--dir=DIR</option></term>
3232 <listitem><para>open DIR as directory (not as an application, even if it looks like one).
3233 </para></listitem></varlistentry>
3235 <varlistentry><term><option>-D</option></term><term><option>--close=DIR</option></term>
3236 <listitem><para>close DIR and all its subdirectories.
3237 </para></listitem></varlistentry>
3239 <varlistentry><term><option>-h</option></term><term><option>--help</option></term>
3240 <listitem><para>display help about the various options.
3241 </para></listitem></varlistentry>
3243 <varlistentry><term><option>-l</option></term><term><option>--left=PANEL</option></term>
3244 <listitem><para>open PANEL as a left-edge panel.
3245 </para></listitem></varlistentry>
3247 <varlistentry><term><option>-m</option></term><term><option>--mime-type=FILE</option></term>
3248 <listitem><para>print MIME type of FILE and exit.
3249 </para></listitem></varlistentry>
3251 <varlistentry><term><option>-n</option></term><term><option>--new</option></term>
3252 <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). This option is only useful for debugging.
3253 </para></listitem></varlistentry>
3255 <varlistentry><term><option>-o</option></term><term><option>--override</option></term>
3256 <listitem><para>override window manager control of panels.
3257 </para></listitem></varlistentry>
3259 <varlistentry><term><option>-p</option></term><term><option>--pinboard=PIN</option></term>
3260 <listitem><para>use pinboard PIN as the pinboard.
3261 </para></listitem></varlistentry>
3263 <varlistentry><term><option>-r</option></term><term><option>--right=PANEL</option></term>
3264 <listitem><para>open PANEL as a right-edge panel.
3265 </para></listitem></varlistentry>
3267 <varlistentry><term><option>-R</option></term><term><option>--RPC</option></term>
3268 <listitem><para>read and invoke SOAP RPC from standard input (see <xref linkend="soap"/>).
3269 </para></listitem></varlistentry>
3271 <varlistentry><term><option>-s</option></term><term><option>--show=FILE</option></term>
3272 <listitem><para>open a directory showing FILE.
3273 </para></listitem></varlistentry>
3275 <varlistentry><term><option>-t</option></term><term><option>--top=PANEL</option></term>
3276 <listitem><para>open PANEL as a top-edge panel.
3277 </para></listitem></varlistentry>
3279 <varlistentry><term><option>-u</option></term><term><option>--user</option></term>
3280 <listitem><para>show user name in each window.
3281 </para></listitem></varlistentry>
3283 <varlistentry><term><option>-v</option></term><term><option>--version</option></term>
3284 <listitem><para>display the version information and exit.
3285 </para></listitem></varlistentry>
3287 <varlistentry><term><option>-x</option></term><term><option>--examine=FILE</option></term>
3288 <listitem><para>FILE has changed; re-examine it.
3289 </para></listitem></varlistentry>
3295 <refsect1><title>NOTES</title>
3297 The main documentation for ROX-Filer is available by choosing
3298 <guimenuitem>Show Help Files</guimenuitem> from the
3299 popup menu, or by clicking on the right-most toolbar icon.
3303 <refsect1><title>LICENSE</title>
3304 <para>Copyright (C) 2002 Thomas Leonard.
3306 You may redistribute copies of ROX-Filer under the terms of the GNU General
3311 <refsect1><title>BUGS</title>
3313 Report bugs to <email>tal197@users.sourceforge.net</email>.
3317 <refsect1><title>AUTHORS</title>
3319 ROX-Filer was created by Thomas Leonard, with help from:
3321 <simplelist columns='3'>
3322 <member>Michael Adams</member>
3323 <member>Christopher Arndt</member>
3324 <member>Jens Askengren</member>
3325 <member>Liav Asseraf</member>
3326 <member>Wilbert Berendsen</member>
3327 <member>Francesco Bochicchio</member>
3328 <member>Andrzej Borsuk</member>
3329 <member>Richard Boulton</member>
3330 <member>Simon Britnell</member>
3331 <member>Arnaud Calvo</member>
3332 <member>Babyfai Cheung</member>
3333 <member>Andrew Clover</member>
3334 <member>Fabien Coutant</member>
3335 <member>Couderc Damien</member>
3336 <member>Andreas Dehmel</member>
3337 <member>Micah Dowty</member>
3338 <member>Dmitry Elfimov</member>
3339 <member>Mattias Engdegard</member>
3340 <member>Andrew Flegg</member>
3341 <member>Olivier Fourdan</member>
3342 <member>Eric Gillespie</member>
3343 <member>Thierry Godefroy</member>
3344 <member>Olli Helenius</member>
3345 <member>Alex Holden</member>
3346 <member>Jasper Huijsmans</member>
3347 <member>Sigve Indregard</member>
3348 <member>Bernard Jungen</member>
3349 <member>Marcin Juszkiewicz</member>
3350 <member>James Kermode</member>
3351 <member>Jim Knoble</member>
3352 <member>Krzysztof Krzyzaniak</member>
3353 <member>Aaron Kurtz</member>
3354 <member>Vincent Ledda</member>
3355 <member>Vincent Lefevre</member>
3356 <member>Victor Liu See-le</member>
3357 <member>Krzysztof Luks</member>
3358 <member>Marcus Lundblad</member>
3359 <member>Anders Lundmark</member>
3360 <member>Jose Romildo Malaquias</member>
3361 <member>Denis Manente</member>
3362 <member>Brendan McCarthy</member>
3363 <member>Andras Mohari</member>
3364 <member>Christiansen Merel</member>
3365 <member>Jimmy Olgeni</member>
3366 <member>Richard Olsson</member>
3367 <member>Daniele Peri</member>
3368 <member>Andy Piper</member>
3369 <member>Marcelo Ramos</member>
3370 <member>Michel Alexandre Salim</member>
3371 <member>Chris Sawer</member>
3372 <member>Christian Storgaard</member>
3373 <member>Taras</member>
3374 <member>Simon Truss</member>
3375 <member>Jan Wagemakers</member>
3376 <member>Stephen Watson</member>
3377 <member>Andre Wyrwa</member>
3378 <member>Geoff Youngs</member>
3379 <member>Diego Zamboni</member>
3382 and many others; the <filename>Changes</filename> file contains more
3383 detailed information!
3390 <appendix id="soap"><title>SOAP RPC</title>
3392 <para>When the filer starts you can use command-line options to control its behaviour.
3393 As an alternative to this, the filer allows you to specify an operation with a
3394 <citation>SOAP</citation> RPC format message. In fact, if you use the command-line options,
3395 the filer converts to SOAP RPC internally.
3398 <para>All SOAP RPC messages are passed on standard input, like this:
3401 $ rox --RPC << EOF
3402 <?xml version="1.0"?>
3403 <env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope">
3404 <env:Body xmlns="http://rox.sourceforge.net/SOAP/ROX-Filer">
3406 <Name>Default</Name>
3407 <Side>Bottom</Side>
3410 </env:Envelope>
3413 The following methods are recognised:</para>
3417 <listitem><para><function>Version</function>()
3418 Returns the filer's version.
3421 <listitem><para><function>CloseDir</function>(<parameter>Filename</parameter>)
3422 Close directory <parameter>Filename</parameter> and all its subdirectories.
3425 <listitem><para><function>Examine</function>(<parameter>Filename</parameter>)
3426 <parameter>Filename</parameter> may have changed — check it and
3430 <listitem><para><function>OpenDir</function>(<parameter>Filename</parameter>,
3431 [<parameter>Style</parameter>, <parameter>Details</parameter>, <parameter>Sort</parameter>,
3432 <parameter>Class</parameter>])
3433 Open a window showing directory <parameter>Filename</parameter>.
3434 <parameter>Style</parameter> is one of <userinput>Large</userinput>, <userinput>Small</userinput>, <userinput>Huge</userinput>
3435 or <userinput>Automatic</userinput>.
3436 <parameter>Details</parameter> is one of <userinput>None</userinput>, <userinput>ListView</userinput>, <userinput>Size</userinput>, <userinput>Type</userinput>, <userinput>Times</userinput> or <userinput>Permissions</userinput>.
3437 <parameter>Sort</parameter> is one of <userinput>Name</userinput>, <userinput>Type</userinput>, <userinput>Date</userinput> or <userinput>Size</userinput>.
3438 If any of these three option parameters are missing, the default is used.
3439 <parameter>Class</parameter> can be used to set the WM_CLASS property on the new window. You can
3440 use this to get your window manager to treat the window specially.
3443 <listitem><para><function>Panel</function>(<parameter>Side</parameter>,
3444 [<parameter>Name</parameter>])
3445 Open the panel named <parameter>Name</parameter> on screen side
3446 <parameter>Side</parameter> (<userinput>Top</userinput>|<userinput>Bottom</userinput>|<userinput>Left</userinput>|<userinput>Right</userinput>).
3447 <parameter>Name</parameter> can be a name in Choices (eg,
3448 <userinput>MyPanel</userinput>) or a full pathname.
3449 If not given, the panel on that side is turned off.
3452 <listitem><para><function>PanelAdd</function>(<parameter>Side</parameter>,
3453 <parameter>Path</parameter>, [<parameter>Label</parameter>,
3454 <parameter>After</parameter>])
3455 Add <parameter>Path</parameter> to the panel on side <parameter>Side</parameter>,
3456 with label <parameter>Label</parameter>. If <parameter>After</parameter> is
3457 <userinput>true</userinput> the icon goes on the right/bottom side of the panel,
3458 otherwise on the left/top side.
3461 <listitem><para><function>Pinboard</function>([<parameter>Name</parameter>])
3462 Display pinboard <parameter>Name</parameter> on the desktop background.
3463 <parameter>Name</parameter> can be a name in Choices (eg,
3464 <userinput>MyPinboard</userinput>) or a full pathname.
3465 If not given, the pinboard is turned off.
3468 <listitem><para><function>PinboardAdd</function>(<parameter>Path</parameter>,
3469 <parameter>X</parameter>, <parameter>Y</parameter>, [<parameter>Label</parameter>])
3470 Add <parameter>Path</parameter> to the pinboard at position
3471 (<parameter>X</parameter>, <parameter>Y</parameter>), giving it the label
3472 <parameter>Label</parameter>.
3475 <listitem><para><function>SetBackdropApp</function>(<parameter>App</parameter>)
3476 Make <parameter>App</parameter> (an application directory) the new handler
3477 for the current pinboard's backdrop.
3478 The <filename>AppInfo.xml</filename> file inside <parameter>App</parameter>
3479 must contain the CanSetBackdrop element, eg:
3481 <?xml version="1.0"?>
3483 <ROX:CanSetBackdrop xmlns:ROX="http://rox.sourceforge.net/SOAP/ROX-Filer"/>
3484 </AppInfo></programlisting>
3485 The application will be run with the <option>--backdrop</option> option
3486 as it's only argument after invoking this method, and whenever the pinboard is
3487 reloaded. DO NOT use this method if invoked with <option>--backdrop</option> or
3488 you will get stuck in an infinite loop!
3489 See <xref linkend="backdropapp"/> for a guide to writing backdrop applications.
3492 <listitem><para><function>Run</function>(<parameter>Filename</parameter>)
3493 Run <parameter>Filename</parameter> as if it was clicked on in the filer.
3496 <listitem><para><function>Show</function>(<parameter>Directory</parameter>,
3497 <parameter>Leafname</parameter>)
3498 Open <parameter>Directory</parameter> and flash the file
3499 <parameter>Leafname</parameter> inside it.
3502 <listitem><para><function>FileType</function>(<parameter>Filename</parameter>)
3503 Returns the MIME-type of <parameter>Filename</parameter> (by writing the
3504 SOAP response to standard output).
3509 The following calls can be used to start new file actions.
3510 <parameter>Quiet</parameter> can be <userinput>true</userinput> if the
3511 operation should start immediately, instead of waiting for the user to
3512 confirm. If <userinput>false</userinput>, the user must always confirm. If
3513 not given, the default setting is used.
3517 <listitem><para><function>Copy</function>(<parameter>From</parameter>,
3518 <parameter>To</parameter>, [<parameter>Leafname</parameter>,
3519 <parameter>Quiet</parameter>])
3520 Copy each file in the array <parameter>From</parameter> to the directory
3521 <parameter>To</parameter>. If <parameter>Leafname</parameter> is given
3522 then <parameter>From</parameter> should contain a single entry only;
3523 <parameter>Leafname </parameter> gives the new leafname.
3526 <listitem><para><function>Move</function>(<parameter>From</parameter>,
3527 <parameter>To</parameter>, [<parameter>Leafname</parameter>,
3528 <parameter>Quiet</parameter>])
3529 Move each file in the array <parameter>From</parameter> to the directory
3530 <parameter>To</parameter>. If <parameter>Leafname</parameter> is given
3531 then <parameter>From</parameter> should contain a single entry only;
3532 <parameter>Leafname</parameter> gives the new leafname.
3535 <listitem><para><function>Link</function>(<parameter>From</parameter>,
3536 <parameter>To</parameter>, [<parameter>Leafname</parameter>])
3537 Symlink each file in the array <parameter>From</parameter> to the
3538 directory <parameter>To</parameter>. If <parameter>Leafname</parameter> is
3539 given then <parameter>From</parameter> should contain a single entry only;
3540 <parameter>Leafname</parameter> gives the new leafname.
3543 <listitem><para><function>Mount</function>(<parameter>MountPoints</parameter>,
3544 [<parameter>OpenDir</parameter>, <parameter>Quiet</parameter>])
3545 Mount each directory in the list <parameter>MountPoints</parameter>. If
3546 <userinput>true</userinput>, <parameter>OpenDir</parameter> causes each
3547 directory to be opened once it is mounted.
3555 <title>References</title>
3558 <abbrev>ROX</abbrev><citetitle>The ROX desktop,
3559 <ulink url="http://rox.sourceforge.net"/></citetitle>
3563 <abbrev>RISC OS</abbrev><citetitle>RISC OS,
3564 <ulink url="http://www.riscos.com"/></citetitle>
3568 <abbrev>GTK+</abbrev><citetitle>GTK+ Toolkit,
3569 <ulink url="http://www.gtk.org"/></citetitle>
3573 <abbrev>libxml</abbrev><citetitle>The XML C library for Gnome
3574 <ulink url="http://www.xmlsoft.org"/></citetitle>
3578 <abbrev>GNOME</abbrev><citetitle>The GNOME desktop,
3579 <ulink url="http://www.gnome.org"/></citetitle>
3583 <abbrev>DND</abbrev><citetitle>The Drag and Drop protocol,
3584 <ulink url="http://www.newplanetsoftware.com/xdnd/"/></citetitle>
3588 <abbrev>XDS</abbrev><citetitle>The X Direct Save protocol,
3589 <ulink url="http://www.newplanetsoftware.com/xds/"/></citetitle>
3593 <abbrev>Choices</abbrev><citetitle>The ROX Choices system,
3594 <ulink url="http://rox.sourceforge.net/choices.php3"/></citetitle>
3598 <abbrev>AVFS</abbrev><citetitle>AVFS - A Virtual File System,
3599 <ulink url="http://sourceforge.net/projects/avf/"/></citetitle>
3603 <abbrev>SOAP</abbrev><citetitle>Simple Object Access Protocol (SOAP) 1.2
3604 <ulink url="http://www.w3.org/TR/SOAP/"/></citetitle>
3608 <abbrev>Thumbs</abbrev><citetitle>Thumbnail Managing Standard (Version 0.5)
3609 <ulink url="http://triq.net/~pearl/thumbnail-spec/"/></citetitle>
3613 <abbrev>Wallpaper</abbrev><citetitle>Wallpaper backdrop control application
3614 <ulink url="http://rox.sf.net/wallpaper.php3"/></citetitle>
3618 <abbrev>SharedMIME</abbrev><citetitle>Shared MIME-info Database (Version 0.8)
3619 <ulink url="http://www.freedesktop.org/standards/shared-mime-info.html"/></citetitle>