xfiles.1

.Dd August 6, 2024
.Dt XFILES 1
.Os
.Sh NAME
.Nm xfiles ,
.Nm xfilesctl ,
.Nm xfilesthumb
.Nd X11 file manager
.Sh SYNOPSIS
.Nm xfiles
.Op Fl a
.Op Fl N Ar name
.Op Fl X Ar resources
.Op Ar directory
.Nm xfilesctl
.Ar command
.Op Ar file ...
.Nm xfilesthumb
.Ar filepath
.Ar thumbpath
.Sh DESCRIPTION
.Nm xfiles
is a file manager for X11.
.Nm xfiles
uses other programs to perform several tasks,
such as to open a file, generate thumbnails, or run arbitrary commands.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl a
Include directory entries whose name begin with a dot.
.It Fl N Ar name
Specify the
.Ic res_name
member of the
.Xr XClassHint 3
property.
.Ar name
is used to retrieve resources.
If not specified, defaults to
the value of the
.Ev RESOURCES_NAME
environment variable, or (if that variable is not set) to the name of the command
.Nm xfiles
was invoked as (that is, the
.Xr basename 3
of its
.Ic "argv[0]" ) .
.It Fl X Ar resources
Specify additional resources to be added on top of the resources from X's resource database.
If not specified, defaults to the value of the
.Ev RESOURCES_DATA
environment variable, or (if that variable is not set) to the empty string.
.El
.Pp
If no
.Ar directory
is given as argument,
.Nm xfiles
opens at the current directory.
Otherwise, it opens at the given directory.
.Pp
.Nm xfilesctl
is a script called by
.Nm xfiles
to operate on files.
.Nm xfilesctl
should usually not be called manually.
.Nm xfilesctl
gets a
.Ar command
as argument indicating the kind of interaction to perform with the user.
Possible interactions are invoking a menu
or popping up a terminal dialog.
.Pp
.Nm xfiles
source comes with an example
.Nm xfilesctl
script.
But users are encouraged to create their own script satisfying their own needs.
.Pp
The commands passed to it are as follows:
.Bl -tag -width Ds
.It Cm menu
.Nm xfilesctl
is invoked with the
.Cm menu
command when right-clicking a
.Nm xfiles
window.
The selected files are given to
.Nm xfilesctl
as further arguments.
This command is used to pop up a menu (such as
.Xr xmenu 1
or
.Xr pmenu 1 )
containing operations to perform on the selected files
(such as rename them or send them to the trash).
.It Cm drop-ask
.Nm xfilesctl
is invoked with the
.Cm drop-ask
command when dropping files at a
.Nm xfiles
window while no modifier is pressed.
The paths to the dropped files are given to
.Nm xfilesctl
as further arguments.
This command is used to pop up a menu containing operations to perform on the dropped files
(such as copy them to the current directory, move them, or link them).
.It Cm drop-copy
.Nm xfilesctl
is invoked with the
.Cm drop-copy
command when dropping files at a
.Nm xfiles
window while the Control modifier key is pressed.
The paths to the dropped files are given to
.Nm xfilesctl
as further arguments.
This command is used to pop up a terminal dialog window asking whether
to copy the dropped files to the current working directory.
.It Cm drop-move
.Nm xfilesctl
is invoked with the
.Cm drop-move
command when dropping files at a
.Nm xfiles
window while the Shift modifier key is pressed.
The paths to the dropped files are given to
.Nm xfilesctl
as further arguments.
This command is used to pop up a terminal dialog window asking whether
to move the dropped files to the current working directory.
.It Cm drop-link
.Nm xfilesctl
is invoked with the
.Cm drop-link
command when dropping files at a
.Nm xfiles
window while both the Shift and Control modifier keys are pressed.
The paths to the dropped files are given to
.Nm xfilesctl
as further arguments.
This command is used to pop up a terminal dialog window asking whether
to link the dropped files to the current working directory.
.It Cm "^\)" Ns Ar KEY
.Nm xfilesctl
is invoked with a
.Cm "^\)" Ns Ar KEY
command.
.Ar KEY
is the name (as returned by
.Xr XKeysymToString 3 )
of a character key pressed with Control,
a function key (F1~F13), or
an operation key (Delete, BackSpace, etc).
The paths to the selected files are given to
.Nm xfilesctl
as further arguments.
These commands are used to implement user-defined operations
(see
.Sx Extra keys
below for examples).
If the Shift modifier key is also pressed and no file is selected,
the path to the highlighted file is given to
.Nm xfilesctl
instead.
.El
.Pp
.Nm xfilesthumb
is a script called by
.Nm xfiles
to create 64x64 ppm image files called
.Qq thumbnails .
.Nm xfilesthumb
should usually not be called manually.
.Nm xfilesthumb
gets a
.Ar filepath
as argument containing the full path to the file,
and a
.Ar thumbpath
as argument containing the full path to the thumbnail file to be created.
.Pp
.Nm xfiles
source comes with an example
.Nm xfilesthumb
script.
But users are encouraged to create their own script satisfying their own needs.
.Sh USAGE
.Nm xfiles
is controlled mainly with the mouse,
but some actions can also be performed with the keyboard.
.Pp
.Nm xfiles
has five modes of operation.
In each mode, some mouse or keyboard actions are allowed while others are not.
The modes of operation are as follows.
.Bl -tag -width Ds
.It Normal Mode
This is the mode which
.Nm xfiles
starts in.
All actions, except rectangular selection and scroller manipulation,
can be performed while in this mode.
All other modes are accessible from the normal mode.
.It Selection Mode
This mode is entered after dragging the pointer on an empty space with the first button in normal mode.
In this mode, a rectangle can be drawn, in which any file inside it can be selected.
No action other than the rectangular selection can be performed while in this mode.
To exit this mode, release the first mouse button.
.It Scroll Mode
This mode is entered after opening the scroller with the second button in normal mode.
In this mode, the file list can be scrolled up and down by moving the mouse.
No action other than scrolling can be performed while in this mode.
To exit this mode, press the second mouse button
(or release it, if the pointer had not been released nor moved outside the scroller).
.It Dragging Mode
This mode is entered after dragging the pointer on a file with the first button in normal mode.
In this mode, the file icon follows the mouse cursor, indicating that the file can be dropped on another window.
.It Waiting Mode
This mode is entered after
.Nm xfilesctl
is called (such as after pressing the third mouse button or dropping a file).
In this mode,
.Nm xfiles
is waiting for
.Nm xfilesctl
to exit.
No action can be performed while in this mode.
To exit this mode,
.Nm xfilesctl
must return.
.El
.Ss Mouse button 1
The first mouse button (usually the left one) is used for selection and opening.
Selecting one or more files copies their paths into the PRIMARY X selection.
Opening a single file invokes the command specified by the
.Ev OPENER
environment variable with the path to the open file as argument.
The
.Ev OPENER
program is invoked in the directory currently open at
.Nm .
.Bl -bullet -width 2
.It
A single click with no modifier on a file's icon selects it (deselecting any other file).
.It
A double click with no modifier selects and opens it (deselecting any other file).
.It
A single click with a Control modifier does not deselect previously selected files,
but adds the clicked file to the selection list instead.
.It
A single click with a Shift modifier adds to the selection list any file between
the previously selected one and the clicked one.
.It
A dragging motion on no file with no modifier
draws a rectangle selecting anything inside it (deselecting any other file).
.It
A dragging motion on no file with either the Control or Shift modifiers
draws a rectangle adding to the selection list anything inside it.
.It
A dragging motion on a file initiates a drag-and-drop operation with the selected files.
The dragged files can be then dropped on a directory on the current
.Nm xfiles
window, or on another window supporting the XDND protocol.
The dragging motion can be modified by
Control (forcing a copy operation);
Shift (forcing a move operation); or
Control + Shift (forcing a symbolic linking operation);
.El
.Ss Mouse button 2, 4, and 5
The second, fourth and fifth buttons (the middle button click, scroll up and scroll down) are used for scrolling.
No modifier applies to those buttons.
The second button pops up the scroller.
The scroller is a small widget that replaces the scrollbar in
.Nm ;
it can be used either as a scrollbar or as Firefox's autoScroll.
.Bl -bullet -width 2
.It
A press on the second button pops up the scroller.
Moving the pointer up or down scrolls the list of files up or down.
If the button is release while the pointer is outside the scroller, the scroller is closed.
.It
After pressing the second button (as in the previous bullet item),
if it is released while the pointer is inside the scroller, the scroller is not closed.
The scroller handle (a small bar inside the scroller) can be dragged up and down,
scrolling the list of files up or down.
Pressing any button closes the scroller.
.It
Holding the fourth button scrolls the list of files up.
.It
Holding the fifth button scrolls the list of files down.
.El
.Ss Mouse button 3
The third button (usually the right one) is used to pop up a menu with
.Nm xfilesctl .
No modifier applies to that button.
.Bl -bullet -width 2
.It
Pressing the third button while there are one or more files selected invokes
.Nm xfilesctl
with the paths of all the selected files passed as arguments.
.It
Pressing the third button on a file's icon while there's no file selected
selects that file and invokes
.Nm xfilesctl
with its path passed as argument.
.It
Pressing the third button on nothing while there's no file selected invokes
.Nm xfilesctl
with no argument.
.El
.Ss Mouse buttons 8 and 7
The eighth and ninth mouse buttons (previous and next) are used for navigating
through the browsing history.
.Bl -bullet -width 2
.It
Clicking the eighth mouse button goes to the previously open directory.
.It
Clicking the ninth mouse button goes to the next open directory.
.El
.Ss Other mouse buttons
The sixth and seventh mouse buttons (scroll left and scroll right) are not used, since
.Nm xfiles
does not scroll horizontally.
.Ss Default keys.
The following keys (and their number keyboard counterparts) can control
.Nm xfiles
by, for example, scrolling the window, or highlighting or selecting files.
.Bl -tag -width Ds
.It Escape
Deselect everything.
.It Enter/Return
Select and open highlighted file.
.It Menu
Invoke
.Nm xfilesctl
with the
.Cm menu
command on selected files.
.It Space
Select highlighted file.
.It PageUp
Scroll up.
.It PageDown
Scroll down.
.It Home
Highlight and select the first file (deselecting any other file).
If modified by Control, does not deselect previously selected files.
If modified by Shift, does not deselect previously selected files,
and select any file between the first file and the previously highlighted one.
.It End
Highlight and select the last file (deselecting any other file).
If modified by Control, does not deselect previously selected files.
If modified by Shift, does not deselect previously selected files,
and select any file between the last file and the previously highlighted one.
.It Left, Down, Up, Right or h, j, k, l
Highlight and select the file in the given direction (deselecting any other file).
If modified by Control, does not deselect previously selected files.
If modified by Shift, does not deselect previously selected files,
and select any file between the target file and the previously highlighted one.
.It Ctrl + . (Period)
Hide/show hidden files and directories.
.El
.Ss Extra keys
The letter, digit and punctuation keys, when modified by Control,
the function keys (F1~F13),
and a few other keys (like
.Qq "Delete"
and
.Qq "Backspace"
can be used, modified or not by Shift, to invoke
.Nm xfilesctl .
The following keys are handled by default by the
.Nm xfilesctl
script provided with
.Nm xfiles :
.Bl -tag -width Ds
.It Ctrl-G or Ctrl-L
Invoke
.Xr dmenu 1
to act as an URL bar and change the current directory.
.It F5 or Ctrl-R
Refresh the current directory.
.It BackSpace
Go to parent directory.
.It Delete
Pop up a terminal dialog asking whether to send selected files to trash.
.El
.Sh ICONS
.Nm xfiles
can display a custom icon for a file based on a
.Xr glob 3
pattern matching the file.
For example, files matching
.Ic "*.png"
are drawn with the
.Ic image
icon.
.Pp
The list of icons supported by files and the glob patterns associated to them are the following,
in order of precedence of matching.
.Bl -tag -width Ds
.It Ic up_dir
.Qq Ic ".."
.It Ic archive
.Qq Ic "*.zip" , "*.tar" , "*.gz" , "*.bz2" , "*.rar"
.It Ic audio
.Qq Ic "*.mp[23]" , "*.m4a" , "*m3u" , "*.ogg" , "*.opus" , "*.flac"
.It Ic core
.Qq Ic "*.core"
.It Ic image
.Qq Ic "*.xbm" , "*.xpm" , "*.p[bgp]m" , "*.png" , "*.bmp" , "*.gif" , "*.tiff" , "*.jpeg" , "*.jpg" , "*.gif" , "*.svg"
.It Ic info
.Qq Ic "*.[1-9]" , "README" , "README.md" , "COPYING" , "LICENSE" , "COPYRIGHT"
.It Ic makefile
.Qq Ic "[Mm]akefile" , "configure" , "configure"
.It Ic document
.Qq Ic "*.pdf" , "*.epub" , "*.txt" , "*.ps" , "*.eps" , "*.djvu"
.It Ic object
.Qq Ic "*.o" , "*.so" , "*.a"
.It Ic video
.Qq Ic "*.mp4" , "*.webm" , "*.mkv" , "*.mov" , "*.ogv"
.It Ic home_dir
.Qq Ic "~/"
.It Ic dir
.Qq Ic "*"
(for directories).
.It Ic file
.Qq Ic "*"
.El
.Pp
The following icons have no associated glob patterns
(but custom patterns can be installed with the
.Ic fileIcons
X resource).
.Bl -bullet -compact
.It
.Ic executable
.It
.Ic code
.It
.Ic config
.It
.Ic apps_dir
.It
.Ic code_dir
.It
.Ic database_dir
.It
.Ic documents_dir
.It
.Ic downloads_dir
.It
.Ic games_dir
.It
.Ic images_dir
.It
.Ic config_dir
.It
.Ic meme_dir
.It
.Ic mount_dir
.It
.Ic music_dir
.It
.Ic videos_dir
.It
.Ic link_dir
.El
.Sh RESOURCES
.Nm xfiles
understands the following X resources.
They must be prefixed with either the
.Qq Ic "XFiles"
class or the name given with the
.Fl N
command-line option, followed by a period.
.Bl -tag -width Ds
.It Ic activeBackground
Background color for selected entries.
.It Ic activeForeground
Text color for selected entries.
.It Ic background
Background color.
.It Ic faceName
Font for drawing text.
If the value is prefixed with
.Qq Ic "xft:"
(case insensitive), then
.Nm xfiles
uses the Xft library for drawing text;
and fallback fonts can be specified by delimiting the fonts with commas.
If the value is prefixed with
.Qq Ic "x:"
or
.Qq Ic "x11:"
(case insensitive), then
.Nm xfiles
uses the X11 library for drawing text;
if only one font is specified, regular X11 fonts are used;
if two or more fonts are specified (delimited with commas), a
.Ft XFontSet
is used
(but that is not reliable, and depends on the locale,
so it is better to not use more than one X11 font).
.It Ic faceSize
The size, in points, of the font.
This only affects Xft fonts.
.It Ic fileIcons
Sequence of associations between file patterns and icon names.
Each association has the form
.Ic "PATTERN=ICON" .
And associations must be delimited with either newline characters or colon characters.
See
.Sx ICONS
above for a list of supported icons.
.It Ic foreground
Text color.
.It Ic opacity
Background opacity as a floating point number from 0.0 to 1.0.
Note that, for transparency to work, a compositor is required to be running.
.It Ic statusBarEnable, enableStatusBar
Whether a status bar listing information about the highlighted file should be displayed.
The status bar can be enabled
(if this resource is set to
.Ic true )
or disabled
(if set to
.Ic false ) .
Either option can be used (they are synonyms).
.El
.Sh PROPERTIES
.Nm xfiles
sets the following properties on its window:
.Bl -tag -width Ds
.It Ic "_CONTROL_CWD"
Contains the current working directory.
.It Ic "_CONTROL_STATUS"
Contains information about the current highlighted file
(the same information displayed on the status bar, if enabled).
.El
.Pp
.Nm xfiles
reads the following properties on its window:
.Bl -tag -width Ds
.It Ic "_CONTROL_GOTO"
When this property is modified,
.Nm xfiles
tries to change the current directory, if possible.
If this property is set to
.Qq Ic "-" ,
.Nm xfiles
goes to the previous directory in history.
If this property is set to
.Qq Ic "+" ,
.Nm xfiles
goes to the next directory in history.
Otherwise, it goes to the directory whose path is equal to this property's value.
.El
.Sh ENVIRONMENT
The following environment variables affect the execution of
.Nm .
.Bl -tag -width Ds
.It Ev CACHEDIR
Path to a cache directory where the
.Pa thumbnails
directory is created.
.It Ev DISPLAY
The display to start
.Nm xfiles
on.
.It Ev OPENER
Program to be called to open files.
Defaults to
.Xr xdg-open 1 .
.It Ev RESOURCES_NAME
Specify the name used to retrieve resources.
See
.Fl N
above.
.It Ev RESOURCES_DATA
Specify additional resources.
See
.Fl X
above.
.It Ev XDG_CACHE_HOME
Value used when
.Ev CACHEDIR
is not set.
.El
.Pp
The following environment variables are set by
.Nm xfiles
and can affect the execution of the commands run by it.
.Bl -tag -width Ds
.It Ev "WINDOWID"
A string containing the id number, in decimal ASCII characters,
of the X Window created by the current
.Nm xfiles
process.
Note that this string contains the number in decimal notation,
not in hexadecimal (as is usually exchanged by a few X applications).
.El
.Sh SEE ALSO
.Xr dmenu 1 ,
.Xr xmenu 1 ,
.Xr X 7
.Sh CAVEATS
.Nm xfiles
is a work-in-progress.
Some features remain to be implemented.