SpaceFM Homepage Downloads News Wiki Report Issues User's Manual | SpaceFM User's Manual This document is under construction and incomplete. This manual uses your browser's settings for fonts, font sizes, and colors. TIP: For help within SpaceFM, right-click on a menu item and select Help. Or, highlight the menu item (hover your mouse cursor over it) and press F1. Some dialogs also include a Help button which links to this manual. DISCLAIMER While the authors, copyright holders, and maintainers of this software endeavour to keep all content up to date and valuable, we make no representations or warranties of any kind, express or implied, about the completeness, accuracy, reliability, suitability or availability with respect to the software or the information, communications, products, services, or related graphics for any purpose. Any reliance you place on such content is therefore strictly AT YOUR OWN RISK. Table Of Contents Introduction About History Highlights Installation Downloads Packages Installer Manual Builds Uninstall Invocation Command Line Windows GTK Themes Desktop Manager Daemon Mode Quick Start Frequently Asked Questions GUI Path Bar Devices Introduction List Menu Root Settings How To Enable Kernel Polling Tasks Task Manager Queue Menu Popup Dialog Design Mode Introduction Design Menu Style Command Toolbars Shortcuts MIME Menu Plugins Introduction Install Copy Uninstall Creation And Files Dialog Introduction Invocation Simple Elements List Elements Non-Visible Elements Commands Internal Commands Program Files /home /etc /tmp /usr
Introduction
Contents Introduction About History Highlights Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files | About SpaceFM is a multi-panel tabbed file manager for Linux which is lightweight and has minimal dependencies, yet is capable and very flexible. Design Goals Provide a flexible user interface which rivals the flexibility and capabilities of the Linux command line. Using SpaceFM and making gradual adjustments as you go, you become the designer of your own version of the file manager. Almost every built-in menu and toolbar item can be renamed or hidden from view, bound to any keyboard shortcut, and given a custom icon. You can also add your own custom commands and submenus to any position in most menus. Like word processor macros, custom commands allow you to easily run commonly used programs or automate tasks using SpaceFM's unique integration with the bash scripting language. Provide flexibility in window components, behavior, and appearance. How many panels you want displayed, how they are arranged and sized, what each panel contains, what fonts are used, and how they respond to your actions are largely up to you. SpaceFM can be a single window containing icons of a single folder's contents, or a multi-panel, tabbed arrangement of detailed file lists, devices, bookmarks, and folder trees. Keep the user interface as simple and clean as possible. Although SpaceFM's UI has been redesigned, it is still inspired by the simplicity and clarity of PCManFM's UI. Provide an automated, programmable device manager which monitors what devices are added to and removed from your system, and allows you to define what action is performed automatically on various events and media types. Perform-as-root functions allow you to easily check filesystems, change volume labels, and format/backup/restore device partitions using a variety of pre-configured methods or your own. Mounting can be performed by udevil (a mount program developed specifically for SpaceFM), pmount, udisks v1/v2, or any program you specify. Provide a Task Manager which controls the optional appearance of pop-up dialogs, and handles queuing of tasks. Running tasks are organized in the Task Manager, freeing you to continue working in any folder or panel. Custom commands can also be run as tasks in the Task Manager, allowing you to monitor their progress and errors. Optional output dialogs monitor stdout/stderr output of built-in and custom commands, with error detection and popup control, or you can run your custom commands in a terminal or as an independent process. Provide a plugin capability which extends the base capabilities. Plugins can be copied into most menus as custom commands, or can be installed as root for added protection and multi-user access. In addition, any custom command you create can easily be saved as a plugin and shared with other users. Provide a common interface to multiple su and graphical su programs, terminals, and editors. You simply select which utilities you want to use for these functions, and SpaceFM's Task Manager handles the details of running your commands as other users, in a terminal, etc. Provide extensive system maintenance capabilities. Perform-as-root functions allow you to edit, copy, move, and delete files and folders as root, change permissions, and create links. SpaceFM can also be run as root for full system maintenance needs. Remain largely independent of particular distributions, desktop environments, and libraries. Written entirely in C, SpaceFM uses GTK2 for its GUI and allows you to customize many GUI elements without modifying your GTK theme, or it can be run with no theme. By default, it relies only on stock GTK icons. SpaceFM has its own built-in virtual filesystem (VFS) code which uses core C filesystem functions for speed and reliability, and has no dependence on gvfs, etc. It includes built-in support for inotify-capable kernels (most are), meaning there are no dependencies on file alteration monitors (fam, gamin, gvfs, etc). (For rare kernels without inotify support, SpaceFM can easily be built with deprecated fam/gamin support.) SpaceFM uses udev for device detection and information, with no dependency on udisks. (SpaceFM can also be built with deprecated HAL support instead of libudev.)
Contents Introduction About History Highlights Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files | History SpaceFM was developed from a fork of the legacy PCManFM file manager. When PCManFM reached version 0.5.2 (aka 'the legacy version'), the original author (Hon Jen Yee) abandoned it for a major rewrite which made later versions (the 0.9.x series) dependent on gvfs and other components. At about this same time, PCManFM-Mod was created as a minor fork of the legacy version which added features, addressed numerous bugs, and kept the legacy version alive for those who prefered it for its light dependencies, HAL support, and added features. PCManFM-Mod was then used as a base for developing SpaceFM, which included a major redesign of the user interface, multiple panel support, a new device manager, inotify support, and removed dependencies on fam/gamin and HAL. Much of the internal VFS which had been developed and debugged in legacy PCManFM and PCManFM-Mod was retained and extended, providing SpaceFM with a reliable VFS to build upon. Due to the extensive changes in many parts of the project, SpaceFM was released with its new name as an alpha test version in January 2012. Beginning with version 0.7.5 in April 2012, SpaceFM replaced udisks with direct udev support for device detection and information. For non-root user mounting and unmounting, SpaceFM will use whatever you have installed: udevil (a mount program developed specifically for SpaceFM), pmount, udisks v1/v2, or any program you specify.
Contents Introduction About History Highlights Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files | Highlights Lightweight - Written in C with GTK2 stability, inotify kernel and libudev support Responsive - Built-in vfs runs fast with low resource usage (no gvfs, etc) Flexible - Can appear very simple or very complex depending on configuration Multiple Windows - A single instance opens multiple windows Multiple Panels - Each window contains up to four independently configured and interactive browser panels plus a Task Manager pane Tabbed - Each browser panel supports multiple folder tabs Side Panes - Any browser panel can show Devices, Bookmarks, and Directory Tree side panes Desktop Manager - Includes a built-in, lightweight DM mode with custom commands - works great with Openbox Device Manager - Built-in libudev support for manual and automatic device management, plus easily format, backup and restore partitions and MBRs Conveniently mount network URLs (nfs:// ftp:// smb:// ssh://) and ISO files (requires udevil) Task Manager - Control or eliminate popup dialogs with multi-tasking abilities - no waiting to move on to your next task MIME - Manages MIME file types and default actions Custom Menus and Toolbars - Its unique Design Mode allows you to quickly change any menu or toolbar item name, shortcut key, or icon, and insert your own commands or submenus anywhere SpaceFM Dialog - easily create, use, and control custom dialogs Plugins - Install, copy, and export custom commands as plugins Bash Integration - Built-in bash scripting support for custom commands, with file manager data exported as bash variables Output Control - Monitor the stdout/stderr output of built-in and custom commands, with error detection and popup control, or run commands in a terminal Fonts & Icons - Easily configure custom fonts and icons in each panel or pane for a unique look Styles - Show files as icons or in lists with selectable columns Find-As-You-Type - File list allows you to quickly locate a file with a case-insensitive substring search of filenames - just type a few letters File Search - Flexibly search for file names, sizes, content, etc. with no daemons System Management - Safely perform quick commands as root or run a root instance File Management - Extensive move, copy, link, drag-n-drop, and clipboard control Archives - Single-click, in-program archive creation and extraction, or use external apps Daemon Mode - Run in the background to automount devices and autorun apps, and quickly open browser windows Alternate Builds - deprecated support for hal (replaces libudev) and fam/gamin (replaces inotify)
Installation
Contents Introduction Installation Downloads Packages Installer Manual Builds Uninstall Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files | Downloads SpaceFM is distributed from SourceForge and Github. Packages are also available for some distros, and SpaceFM is available in some distro repositories. For others, there is a self-extracting installer, as well as several manual build methods available. You can also check the homepage, latest news and report issues. The SpaceFM Wiki contains user-contributed plugins, help, and information. Everyone is encouraged to contribute to the wiki. All distributed files are signed for your protection. Before using downloaded files, it is recommended that you authenticate your download using the spacefm-x.x.x.SHA256.asc file for the current version and these instructions. NOTE: Enabling kernel polling is recommended after installing SpaceFM.
Contents Introduction Installation Downloads Packages Installer Manual Builds Uninstall Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files | Packages
Distro | Packages & Repositories*
--- | ---
antiX | antiX-12 base and full includes spacefm
Arch Linux | Arch Linux's [community] repository includes spacefm (i686 & amd64), and the spacefm-git AUR package provides the 'next' branch as a work in progress.
Debian-based | deb packages are available in Downloads (to save a file, click on its filename and click 'View Raw'), and are also available in the author's PPA. These convenience deb packages contain the source code and will build and install SpaceFM automatically on most Debian-based distros. $TMPDIR (usually /tmp) must NOT be mounted noexec. Or easily build your own deb package from source using the instructions in the README file.
Foresight | Foresight Lxde uses SpaceFM as its default file manager; Foresight includes spacefm in its repositories
Gentoo | Gentoo's portage tree includes spacefm
openSUSE | openSUSE 12.1 repo (add the following repo to Yast software manager): http://download.opensuse.org/repositories/home:/mournblade:/spacefm/openSUSE_12.1 openSUSE Tumbleweed repo: http://download.opensuse.org/repositories/home:/mournblade:/spacefm/openSUSE_Tumbleweed/ rpm package downloads are also available for a one-click install. Feedback on openSUSE builds can be sent via the SpaceFM OBS project.
Parted Magic | Parted Magic includes SpaceFM with udevil as its default file manager
PCLinuxOS | spacefm test packages available (see forum)
Sabayon | Includes spacefm in its repositories
Slackware | SlackBuilds.org includes spacefm
SliTaz | Includes spacefm in its repositories
SystemRescueCD | SpaceFM is included by default in SystemRescueCD live distro
Ubuntu | See Debian
VectorLinux | spacefm test packages available
Other | A self-extracting installer is available, or use one of the manual build methods
* For the most up to date table, please visit the SpaceFM Homepage
Contents Introduction Installation Downloads Packages Installer Manual Builds Uninstall Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files | Installer If a package is not yet available for your distribution, SpaceFM is easily installed using its self-extracting installer available in Downloads (to save a file, click on its filename and click 'View Raw'). The installer extracts, builds, and installs automatically. To use the installer, first install required build dependencies (below are Debian package names - packages names in your distribution's repository may vary but should be similar): autotools-dev bash build-essential dbus desktop-file-utils libc6 libcairo2 libdbus-1-3 libglib2.0-0 libgtk2.0-0 (>=2.18) libgtk2.0-bin libpango1.0-0 libx11-6 shared-mime-info intltool pkg-config libgtk2.0-dev libglib2.0-dev fakeroot libdbus-1-dev libudev0 (>=143) libudev-dev Also Recommended: udevil|pmount|udisks, eject, lsof, wget, ktsuss|gksu, libstartup-notification0, libstartup-notification0-dev IF building with HAL support (device manager functions are very limited), you also need: hal libhal-dev libhal-storage-dev libdbus-glib-1-dev libhal-storage1 libhal1 libdbus-glib-1-2 With HAL, you do NOT need: libudev0 libudev-dev IF disabling inotify support, you also need fam or gamin: fam|gamin libfam0|libgamin0 libfam-dev|libgamin-dev Next, run the installer in a terminal like this (substitute the correct version for "x.x.x"):
        bash spacefm-x.x.x-installer.sh
Or, to see the help for alternate build options, run:
        bash spacefm-x.x.x-installer.sh --help
If build dependencies are missing, examine the errors, install required dependencies, and run the installer again. To upgrade to the latest version, just download the latest installer and run it. NOTE: Enabling kernel polling is recommended after installing SpaceFM.
Contents Introduction Installation Downloads Packages Installer Manual Builds Uninstall Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files | Manual Builds For easy-to-follow manual build instructions, please see the README file. Sections there include: BUILD - build SpaceFM from source BUILD DEBUG - build SpaceFM with debug symbols for reporting crashes with a gdb backtrace BUILD NEXT - build the 'next' branch of SpaceFM. This version is a work in progress which eventually becomes the next release version. BUILD GTK3 - The git gtk3 branch of SpaceFM is available for alpha testing. Please see the gtk3 README for details. CREATE DEB PACKAGE - easily create a deb binary package file of SpaceFM for almost any Debian-based distro
Contents Introduction Installation Downloads Packages Installer Manual Builds Uninstall Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files | Uninstall If you installed SpaceFM from a package, use your package manager to remove it. Otherwise, if you installed via the self-extracting installer or a manual build, you can remove SpaceFM (including plugins) with these commands, all run as root: (these commands assume you installed with the default `--prefix=/usr/local` - adjust as needed)
        rm /usr/local/bin/spacefm /usr/local/bin/spacefm-auth
        rm -r /usr/local/share/spacefm
        rm /usr/local/share/pixmaps/spacefm.png
        rm /usr/local/share/pixmaps/spacefm-*.png
        rm /usr/local/share/icons/hicolor/*/apps/spacefm.png
        rm /usr/local/share/icons/hicolor/*/apps/spacefm-*.png
        rm /usr/local/share/icons/Faenza/apps/48/spacefm.png
        rm /usr/local/share/icons/Faenza/apps/48/spacefm-*.png
        rm /usr/local/share/locale/*/LC_MESSAGES/spacefm.mo
        rm /usr/local/share/applications/spacefm*.desktop
        rm /usr/local/share/mime/packages/spacefm-mime.xml
        update-mime-database /usr/local/share/mime > /dev/null
        update-desktop-database -q
        gtk-update-icon-cache -q -t -f /usr/local/share/icons/hicolor
Invocation
Contents Introduction Installation Invocation Command Line Windows GTK Themes Desktop Manager Daemon Mode Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files | Command Line To see SpaceFM's command line usage run `spacefm --help`
    Usage:
      spacefm [OPTION...] [DIR | FILE | URL]...

    Help Options:
      -h, --help                   Show help options
      --help-all                   Show all help options
      --help-gtk                   Show GTK+ Options

    Application Options:
      -t, --new-tab                Open folders in new tab of last window (default)
      -r, --reuse-tab              Open folder in current tab of last used window
      -n, --no-saved-tabs          Don't load saved tabs
      -w, --new-window             Open folders in new window
      -p, --panel=P                Open folders in panel 'P' (1-4)
      --desktop                    Launch desktop manager daemon
      --desktop-pref               Show desktop settings
      --show-pref=N                Show Preferences ('N' is the Pref tab number)
      -d, --daemon-mode            Run as a daemon
      -c, --config-dir=DIR         Use DIR as configuration directory
      -f, --find-files             Show File Search
      --set-wallpaper              Set desktop wallpaper to FILE
      -g, --dialog                 Show a custom dialog (See -g help)
      --profile=PROFILE            No function - for compatibility only
      --no-desktop                 No function - for compatibility only
      --display=DISPLAY            X display to use
Normally, your session file and other user files are saved in ~/.config/spacefm/ To make SpaceFM read and save your files in another folder (~/.config/spacefm-alt in this example), stop ALL instances of SpaceFM and run:
        # first stop all instances:
        killall spacefm

        # then:
        spacefm --config-dir ~/.config/spacefm-alt
IMPORTANT: The config directory path may not contain spaces or other special characters - keep it simple. Also, if /etc/xdg/spacefm exists, its contents will be copied to the config directory if it doesn't exist at startup.
Contents Introduction Installation Invocation Command Line Windows GTK Themes Desktop Manager Daemon Mode Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files | Windows To open an initial SpaceFM window, run 'spacefm' with or without a folder specification:
        spacefm

        # or to open a folder:
        spacefm /home

        # or to open several folders in tabs:
        spacefm /home /usr/bin

        # or to not open saved tabs:
        spacefm -n
To open an additional folder in a new tab of the last used window:
        spacefm /etc
To open a folder in the current tab of the last used window:
        spacefm -r /etc
To simply bring the SpaceFM window to the top of other windows:
        spacefm -r
To open a second window:
        spacefm -w

        # or to open a specified folder in a second window:
        spacefm -w /boot

        # or to open a second window without loading saved tabs:
        spacefm -wn
To open a File Search window:
        spacefm --find-files
SpaceFM maintains a socket for each user/display combination, so when you open multiple windows using the same user and display, all windows are run from a single instance of SpaceFM. Unless a daemon or the desktop manager is running, SpaceFM will exit when all windows are closed. When a window is closed, the current folder tabs are saved to your session file if option File|Save Tabs is checked. The next time you run SpaceFM, these folder tabs will be re-opened in addition to opening tabs for any folders you specify on the command line (unless you specify -n on the command line). To specify a specific panel in which to open a folder:
        # open a folder in panel 2:
        spacefm --panel=2 /usr/bin
To simply show and focus panel 2 in the last used window:
        spacefm --panel=2
As a more advanced example, consider wanting to open multiple SpaceFM windows, each containing different folder tabs in each panel, using a single command. For this, use a script like this to start SpaceFM:
        #!/bin/bash

        # open new window with two tabs in panel 1
        spacefm -wn --panel=1 /etc /usr &
        sleep 0.2
        # add two tabs to panel 2
        spacefm -rn --panel=2 /bin /lib
        sleep 0.2
        # open second window with two tabs in panel 1
        spacefm -wn --panel=1 /boot /media
        sleep 0.2
        # add two tabs to panel 2 of second window
        spacefm -rn --panel=2 /sbin /var
The sleep commands give time for the socket to be created and the newly created window to become the last used window. A shorter sleep time of 0.1 may also work on your system. Opening Files If you specify a file rather than a folder on the command line, SpaceFM will open the file using the default MIME application for this file type, but will not open a SpaceFM window:
        # open a file:
        spacefm /etc/fstab
Contents Introduction Installation Invocation Command Line Windows GTK Themes Desktop Manager Daemon Mode Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files | GTK Themes Because multiple panels in SpaceFM use many GUI elements, the GTK2 theme you're using may have a significant impact on performance. Some themes are 'heavier' than others. For example, the Clearlooks theme has been observed to be very slow with SpaceFM, while the Raleigh theme is quite fast. It is possible to use a specific theme just for SpaceFM, overriding your default theme. For example, to use the Raleigh theme (if installed), run SpaceFM like this:
        GTK2_RC_FILES=/usr/share/themes/Raleigh/gtk-2.0/gtkrc spacefm
You can also test SpaceFM's speed with no theme, which should be faster than any theme:
        GTK2_RC_FILES="" spacefm
To specify a theme within a desktop file, copy SpaceFM's desktop file to your home folder:
        mkdir -p ~/.local/share/applications
        cp /usr/local/share/applications/spacefm.desktop ~/.local/share/applications/
        # OR
        cp /usr/share/applications/spacefm.desktop ~/.local/share/applications/
Then open ~/.local/share/applications/spacefm.desktop in your editor and set the Exec= line using env. For example: Exec=env GTK2_RC_FILES=/usr/share/themes/Raleigh/gtk-2.0/gtkrc spacefm More information on using GTK themes
Contents Introduction Installation Invocation Command Line Windows GTK Themes Desktop Manager Daemon Mode Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files | Desktop Manager SpaceFM includes a lightweight desktop manager to manage desktop icons and show wallpaper. This works well with Openbox, for example, which doesn't include a desktop manager. To start a desktop manager daemon, first terminate any other software which is managing your desktop, then run:
        spacefm --desktop
You can also run `spacefm --desktop` from your login script. For example, if you're using Openbox, add this line to ~/.config/openbox/autostart.sh:
        ( spacefm --desktop ) &
While managing the desktop, SpaceFM's volume monitor will also be running, meaning that if configured to do so, it will automount devices. To set the wallpaper from the command line, run a command like:
        spacefm --set-wallpaper /home/user/wallpaper.jpg
To open the desktop preferences window from the command line run:
        spacefm --desktop-pref
To stop management of the desktop prematurely (before logoff), send spacefm a quit signal:
        killall spacefm
Contents Introduction Installation Invocation Command Line Windows GTK Themes Desktop Manager Daemon Mode Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files | Daemon Mode If you want SpaceFM always running in the background, ready to quickly open windows and automount volumes, but don't want it to manage the desktop, start a daemon instance of SpaceFM:
        spacefm -d
No window will open in this case, but an instance will be started if not already running, and it will continue running for the duration of your X login session. You can also start the daemon from your login script. For example, if using Openbox, add this line to ~/.config/openbox/autostart.sh:
        (sleep 2 && spacefm -d) &
One particular use for daemon mode is to make sure leftover folders in /media are removed. SpaceFM can unmount removable devices on exit to prevent folders remaining in /media at shutdown (if you check option Settings|Auto-Mount|Unmount On Exit). If running as a normal instance, this means devices will be unmounted whenever you close the last SpaceFM window. When running as a daemon (or as a desktop manager daemon), devices won't be unmounted until you logoff. To stop a daemon mode instance, send SpaceFM a quit signal:
        killall spacefm
Quick Start
Contents Introduction Installation Invocation Quick Start Frequently Asked Questions GUI Devices Tasks Design Mode Plugins Dialog Program Files | Frequently Asked Questions How do I see help for a menu item? How do I set or change key shortcuts and icons? How to I set or change the key to go Up a directory? Right-click on the file list, right-click on menu item Go|Up, and select Key. How do I customize the toolbars? I hid the toolbar - how do I restore it? How do I create a custom menu command? Use Design Mode to add a New custom menu item. How do I move a custom command to another menu or menu position? How do I copy a plugin to another menu? How do I create a new tab in the current folder? Right-click on any tab and select Tab Here (you can assign any key shortcut to this item using Design Mode). How do I make archives (tar.gz etc) open with an application? Right-click on any archive file and select Open|Archive Default|Open With App. Why aren't all my thumbnails displayed? View|Preferences|Max Pic Size To Thumbnail may limit what pics are thumbnailed.
GUI
Contents Introduction Installation Invocation Quick Start GUI Path Bar Devices Tasks Design Mode Plugins Dialog Program Files | Path Bar SpaceFM's Path Bar (address bar) is located above the file list between the Left and Right toolbars. At it's simplest, the Path Bar allows you to see the current folder's path, and you can enter a new path and press Enter to change to another folder. TIP: To place the cursor in the Path Bar, you can use Go|Focus|Path Bar, accessed from the right-click menu of the file list. By default, this is assigned to key shortcut Ctrl+L. In addition to displaying and accepting a folder path, SpaceFM's Path Bar has additional methods and uses as detailed below. File Path The path to a file may be entered or pasted in the Path Bar. When you press Enter, SpaceFM will change to the directory containing the file and will select the file in the file list. Tab Completion As you're entering a directory path in the Path Bar, tab completion will be active. For example, if you enter "/us", a drop down box will appear listing /usr (and any other directories that may begin with "/us" on your system). If there is only one match, you can press Tab to complete the entry automatically ("/us" will be completed to "/usr"). If multiple possibilities are listed, press Down Arrow to select the desired completion and press Enter (or select it using the mouse). Breadcrumbs The Breadcrumbs feature allows you to Ctrl+Click on a portion of the path in the Path Bar to change to that level directory. For example, if this path is currently in the Path Bar:
        /usr/share/spacefm/plugins
and you Ctrl+Click on the name 'share', SpaceFM will change to directory /usr/share. This provides a convenient way to go up to a specific directory. Protocol URL Any entry in the Path Bar which looks like a protocol, such as ftp://mirrors.kernel.org/, will be opened with the Protocol Handler. By default, SpaceFM uses udevil as the handler, unless a custom Protocol Handler has been configured. If udevil recognizes the protocol, it will be mounted and SpaceFM will automatically open the mount point directory (in most cases). If the Devices List has option Settings|Show|Mounted Networks checked, the new network filesystem will be listed. Information like username, password, port, etc may also be included in the URL - see URL protocols and formats handled by udevil. TIP: You can right-click on a mounted network in the Devices List and select Bookmark to bookmark the URL for future use. Protocol Handler If you would like to use a custom handler for URLs within SpaceFM, right-click on the Path Bar and select Protocol Handler. In the dialog, enter the command to be used to open or handle URLs. No substitution variables are accepted - the URL is passed as the first argument to your command. Your handler command may be a script which intelligently opens URLs using programs you specify in the script (see example below), or it can be a single command such as 'udevil mount' (the default if the handler command is left blank). Note that any Path Bar entry which looks like a protocol URL will be passed to your command, so this feature can be used to create custom protocols or to support ones not recognized by udevil. For example, if your handler knows what to do with the URL myproto://something-here, then you will be able to enter this URL in SpaceFM's Path Bar to take a custom action. Your handler doesn't necessarily have to mount anything - it can take any action on the URL passed to it. SpaceFM runs the handler as a synchronous task and will popup an error dialog on non-zero exit status. When the task finishes, SpaceFM will check to see if the URL is now mounted, and if it is, will open the mount point directory. (Note that SpaceFM may not detect or recognize all mounted protocols. You can also have your handler open the mount point directory after a successful mount by having it run `spacefm DIR`) Bookmarked protocol URLs are also opened by the Protocol Handler. When unmounting a network using Remove or Unmount in the Devices Menu, the configured Unmount Command is run. If you want to be able to unmount custom or unusual protocols via the Devices List, you can set the Unmount Command to a script which handles your protocols. (It must also handle normal device unmounts for normal operation.) Example Protocol Handler Script Below is an example protocol handler script. For example, you might save this script as a text file named 'myhandler', then install it as 'protocol-handler' (installing your script improves security):
        sudo install myhandler /usr/local/bin/protocol-handler
Finally, set Protocol Handler to 'protocol-handler'.
    #!/bin/bash
    # Example Protocol Handler script to open URLs entered in SpaceFM's Path Bar

    # Set prefered terminal
    terminal=xterm

    # Get just the protocol, eg "smb" from "smb://..."
    protocol="${1%%:*}"

    # Open the URL using the appropriate program
    case "$protocol" in
        "" )
            echo "Invalid URL" 2>&1
            exit 1
            ;;
        myproto )
            # open custom protocol 'myproto' with myproto-handler
            myproto-handler "$1"
            ;;
        ssh )
            # instead of udevil, mount ssh by running sshfs as the current user

            # First, create a mountpoint
            mount_point=`mktemp -d ~/ssh-mount-XXXX`
            if [ $? -ne 0 ]; then
                echo "Unable to create mount point" 2>&1
                exit 1
            fi

            # Get just the hostname to pass to sshfs
            # See http://www.tldp.org/LDP/abs/html/refcards.html#AEN22587
            hostname="${1#*:}"
            while [ "${hostname:0:1}" == "/" ]; do
                hostname="${hostname#/}"
            done
            hostname="${hostname%:*}"
            hostname="${hostname%/*}"

            # Run sshfs in a terminal to mount hostname to mount point
            $terminal -e "sshfs $hostname: $mount_point; echo; echo Press Enter; read"

    	# Attempt to remove mount point in case of mount error
    	rmdir "$mount_point" 2>/dev/null
            ;;
        * )
            # For any other protocols, use udevil
            udevil mount "$1"
            ;;
    esac
Now when you enter a URL in the Path Bar, it will be mounted using the above script. Command Line In addition, a bash command line can be entered in the Path Bar. This is a convenient way to run a command without having to manually open a terminal. One or more command prefixes are required to tell SpaceFM how to run your command:
Prefix | Result
--- | ---
$ | run as task
& | run and forget
+ | run in terminal
! | run as root
A Path Bar entry is interpreted as a command only if at least one of the above prefixes preceeds the command. A space after the prefix(es) is optional. For example, enter in the Path Bar:
        $ ls
When you press Enter, ls will be run for the current directory, and a dialog will open showing the output. When using prefix '$', the command is run as a task (it will be listed in the Task Manager if it takes longer than a half second to run), and an popup dialog will open only if the command produces output or an error. In addition, the substitution variables defined in Command|Line, and the bash script variables described in Command|Script may also be used in Path Bar command lines. For example, to open a dialog showing the path of the current directory:
        $ echo Current Directory: %d
Or to run umount in a terminal (+) as root (!) passing it the currently selected device (%v):
        +! umount %v
When a plus sign (+) prefix is included, the command is run in a terminal, not as a task. When an exclamation point (!) prefix is included, the command is run as root. If the ampersand (&) prefix is included, the command is run and forgotten (no error or output will be shown). This is useful for starting an application. For example:
        & firefox
For a reminder of prefixes and substitution variables, enter a lone dollar sign ($) in the Path Bar and press Enter. Or press F1 while the Path Bar has focus to open this manual. SpaceFM also keeps a command history, similar to terminals. Enter a lone dollar sign ($) or other command prefix in the Path Bar and press the Up/Down Arrow keys repeatedly to access the history of commands. Select By Pattern If a percent sign (%) prefix is entered in the Path Bar, SpaceFM treats the rest of the text as a file selection pattern. This function is equivalent to right-clicking on the file list and selecting Edit|Select By Pattern. For example, enter in the Path Bar:
        % *.avi
When you press Enter, all filenames in the file list ending in ".avi" will be selected, and all other files will be unselected. If your pattern contains any uppercase characters, the matching will be case sensitive. For additional wildcard characters and pattern specifics, see IEEE Pattern Matching Notation. Font The font used in the Path Bar can be customized (this is a per panel setting). Right-click on the Path Bar and select Font. More To Come Additional functions are planned for SpaceFM's Path Bar - check this manual for updates or see SpaceFM News for recent changes.
Devices
Contents Introduction Installation Invocation Quick Start GUI Devices Introduction List Menu Root Settings How To Enable Kernel Polling Tasks Design Mode Plugins Dialog Program Files | Introduction SpaceFM includes a programmable udev-based device manager which lists device volumes, allows you to mount and unmount devices, and detects changes, insertions, and removals. On events, SpaceFM can auto-mount and auto-open devices, and run commands you specify. In addition, perform-as-root commands allow you to mount and unmount as root; change volume labels; and check, format, erase, backup, and restore partitions. Like most parts of SpaceFM, the behavior and appearance of the device manager is customizable. Whenever SpaceFM is running, whether a window is visible or not, a volume monitor is running to monitor device events and take actions. The volume monitor requires the udevd daemon to be running for device event detection, and enabling kernel polling is recommended. SpaceFM mounts and unmounts devices using whatever you have installed for this purpose: udevil (a mount program developed specifically for SpaceFM), pmount, the udisks command line tool (v1 or v2), or any program you specify. You can run the same command lines that SpaceFM uses in a terminal to troubleshoot behavior, or create your own custom commands to manipulate devices. NOTE: If you choose to use udisks with SpaceFM, note that SpaceFM does not configure udisks. It merely runs the udisks command line tool to mount and unmount devices (unless you install udevil, pmount or specify another program). If you receive the common 'Not Authorized' or other similar errors from udisks when mounting, or you are prompted for a password, this indicates that udisks (and policykit, etc.) are not properly installed or configured. This must be corrected in your system configuration, not in SpaceFM. Deprecated HAL support can also be used in SpaceFM (alternate build required). However, SpaceFM's HAL device manager is far less capable than the udev-based version. It can only be used to manually mount and unmount devices. Thus the udev-based version is recommended, and this manual deals exclusively with the udev-based device manager. To have the device manager always running, responding to events even while no SpaceFM windows are open, run SpaceFM as a daemon or desktop manager. When testing the device manager, it may be useful to run the initial instance of SpaceFM in a terminal, so that you can see additional diagnostic output as it's running. Just open a terminal window and run `spacefm`.
Contents Introduction Installation Invocation Quick Start GUI Devices Introduction List Menu Root Settings How To Enable Kernel Polling Tasks Design Mode Plugins Dialog Program Files | List Each panel or tab in SpaceFM can display a Devices list to show devices and permit configuration of the underlying volume monitor. A Devices list is your interface to the volume monitor's information and actions. Even if multiple Devices lists are displayed or multiple SpaceFM windows are open, only one volume monitor will be running. To show or hide a Devices list in each panel, right-click on the file list and check or uncheck option View|Devices. You can also show or hide the list using the 'Devices' toggle tool item on a toolbar. The Devices list will display only removable and optical devices. If your Devices list is empty, this means there are no removable or optical devices with media, the udevd daemon is not installed or is not working properly on your system, or you may need to enable kernel polling for media detection. To show or hide additional devices, use the Show submenu described below.
Contents Introduction Installation Invocation Quick Start GUI Devices Introduction List Menu Root Settings How To Enable Kernel Polling Tasks Design Mode Plugins Dialog Program Files | Menu To access the Devices menu, right-click on the Devices list. By right-clicking directly on a listed device, more options will be available. Like most menus in SpaceFM, to see the help for any menu item, hover your mouse cursor over the menu item and press F1. Alternatively, right-click on the menu item and select Help in the Design Menu. The Devices context menu includes: Remove The Remove item is used to remove a device and eject media. When you click Remove, first a sync is performed to ensure all data has been commited. If the sync takes longer than about one half second, the Task Manager will auto-show and will list the Remove command as running. Do not remove a device until the Task Manager shows this command has finished, or data may not be properly written, which can cause extensive data loss. Next, if the volume is mounted, it will be unmounted, and if the device is ejectable, it will be ejected. If the device is removable, it is safe to remove it once the Remove command has completed without errors, and any lights on the device indicate activity has stopped. (Even after the sync and unmount has finished, it may take a second or two for the device to stop flashing. If the device has no activity indicator, it is best to wait 5 seconds before removing it.) If you click Remove and nothing seems to happen, this also indicates the device is ready to be removed. When a device is removed or unmounted, any tabs showing directories on the device may be automatically closed. Middle-clicking on a device in the Devices list is equivalent to right-clicking the device and selecting Remove. Thus to quickly remove a device, just middle-click on it. Reload Reload is used to unmount, eject if necessary, and reload a device's media tray in one step, and can also be used to close an already open media tray. The Reload item is similar to Remove - the device will be synced, unmounted, and if possible, ejected. After this, if ejected the tray will be closed. The device will not be mounted unless auto-mount is set. Unmount Unmount will simply run an unmount command on the selected device. By default, udevil, pumount, or the udisks command line tool will be used, unless another program is specified in Settings|Unmount Command. No sync is performed. If the command takes longer than about one half second, the Task Manager will auto-show and the Unmount command will be listed until finished. Sync Sync merely runs a sync command to commit all data to all devices. If the command takes longer than about one half second, the Task Manager will auto-show and the Sync command will be listed until finished. It is valuable to sync before removing or unmounting devices. If you use the Remove or Reload menu items, a sync is performed automatically. Open Selecting Open will cause the selected device to be mounted if it is not already mounted, and then the mount point directory of the device will be opened in the current tab. If an error occurs, the error will be shown. If the command takes longer than about one half second, the Task Manager will auto-show and the Open command will be listed until finished. You can also open a device by simply left-clicking on it. The behavior of a left-click will vary depending on options New Tab and Single Click. To mount, SpaceFM runs a mount command on the selected device. By default, udevil, pmount, or the udisks command line tool will be used, unless another program is specified in Settings|Mount Command. The mount point will be determined automatically by the mount program, usually an automatically created subfolder in /media or /run/media/$USER. If it was automatically created, this subfolder will be automatically removed when the device is unmounted. If the device has an entry in /etc/fstab, that mount point may be used instead, and its mount directory will not be removed when unmounted. The device will be mounted using SpaceFM's Mount Options. If the device has an fstab entry, options specified there may take precedence, depending on your mount program, which may also automatically add or change some mount options. pmount does not support conventional mount options, so when using pmount as the mount command, options set in Mount Options will be ignored. Instead, you can include pmount's command line options in the Mount Command. Tab Tab works similarly to open, except that the device's mount point directory will be opened in a new tab, instead of reusing the current tab. This is also the default behavior of a left-click on a device if option New Tab is checked. Again, a left-click will not display an error, while selecting Tab will. Mount Mount will simply run a mount command on the selected device. By default, udevil, pmount, or the udisks command line tool will be used, unless another program is specified in Settings|Mount Command. The mount point will be determined automatically by the mount program, usually an automatically created subfolder in /media or /run/media/$USER. If the command takes longer than about one half second, the Task Manager will auto-show and the Mount command will be listed until finished. The device will be mounted using SpaceFM's Mount Options. If the device has an fstab entry, options specified there may take precedence. The mount program may also automatically add or change some mount options. pmount does not support conventional mount options, so when using pmount as the mount command, options set in Mount Options will be ignored. Instead, you can include pmount's command line options in the Mount Command. Re/mount The Re/mount item is used to mount or remount a device using specific mount options. A dialog will open asking you for the mount options to be used. If mounted, the device will first be unmounted. Then the device will be mounted using the specified options. Because most mount programs cannot perform a true remount, the device will be unmounted and mounted. Re/mount accepts extended mount options, as detailed in Mount Options. pmount does not support conventional mount options, so when using pmount as the mount command, options set here will be ignored. Instead, you can include pmount's command line options in the Mount Command. Bookmark The Bookmark item will only be shown if the selected device is a mounted network. This item allows you to create a bookmark which will automatically mount the network. Note: Any custom commands you add directly after the Bookmark menu item will also only appear if the selected device is a mounted network, providing an automatic context. Root The Root submenu allows you to perform actions on a device as root. Dialog messages should be read carefully when using any command in the Root submenu, because actions performed as root can affect any aspect of your system. SpaceFM will explain what is about to happen and will let you examine the final command line before it is executed. For details, see the Root section below. Settings The Settings submenu allows you to (globally) configure the appearance of the Devices list, controlling what devices are listed, how they are listed, what icons are used, etc., and also allows you to set the volume monitor to run commands on various events, such as device insertions, etc. For details, see the Settings section below. Properties The Properties item will gather and show information about the currently selected device. If mounted, any mtab lines related to the device will be shown in DEVICE, showing you how and where the device is mounted. USAGE will show information about the filesystem on the device. If the device has any related lines in the /etc/fstab file, these will be listed in FSTAB. These may include lines which are disabled (# comments). In the INFO section, the device's UUID will be listed if known, as well as detailed information from udev on the device's properties. The PROCESSES section, shown for mounted devices, uses lsof to display any processes which are using the device. Sometimes when unmounting a device, you will receive an error that the device is in use. You can check this processes list to see what is holding the device open. Custom Commands As with most menus, it is also possible to add your own custom commands to the Devices menu. This allows you to add commands which can take actions based on the currently selected device in one or more panels. There are several provided bash variables which your commands can use to get information about the currently selected device:
        "$fm_device"              selected device (eg /dev/sr0)  ( same as %v )
        "$fm_device_udi"          device ID
        "$fm_device_mount_point"  device mount point if mounted (eg /media/dvd) (%m)
        "$fm_device_label"        device volume label            ( same as %l )
        "$fm_device_fstype"       device fs_type (eg vfat)
        "$fm_device_size"         device volume size in bytes
        "$fm_device_display_name" device display name
        "$fm_device_icon"         icon currently shown for this device
        $fm_device_is_mounted     device is mounted (0=no or 1=yes)
        $fm_device_is_optical     device is an optical drive (0 or 1)
        $fm_device_is_table       a partition table (usually a whole device)
        $fm_device_is_floppy      device is a floppy drive (0 or 1)
        $fm_device_is_removable   device appears to be removable (0 or 1)
        $fm_device_is_audiocd     optical device contains an audio CD (0 or 1)
        $fm_device_is_dvd         optical device contains a DVD (0 or 1)
        $fm_device_is_blank       device contains blank media (0 or 1)
        $fm_device_is_mountable   device APPEARS to be mountable (0 or 1)
        $fm_device_nopolicy       policy_noauto set (no automount) (0 or 1)

        "$fm_panel3_device"       panel 3 selected device (eg /dev/sdd1)
        "$fm_panel3_device_udi"   panel 3 device ID
        ...                       (all these are the same as above for each panel)
For example, to add a custom command which shows the size of the currently selected device in bytes, use this command line:
        echo "$fm_device_size"
Contents Introduction Installation Invocation Quick Start GUI Devices Introduction List Menu Root Settings How To Enable Kernel Polling Tasks Design Mode Plugins Dialog Program Files | Root The Root submenu allows you to perform actions on a device as root. When performing commands as root, SpaceFM will use your configured Terminal SU or Graphical SU program to run the command. When most items on this menu are selected, a dialog will open showing you the exact command to be run, and allowing you to edit it. If SpaceFM knows how to perform the function on the selected device type, a default command will already be present. In order to edit the default command, you must first depress the Edit button. To restore the command to its default, depress Edit and then press Default. Most items accept the substitution variable %v in their command, which is used to insert the device file (eg /dev/sda2). Some commands accept additional substitution variables. These will be displayed in the dialog's instructions. When performing commands which result in data loss, such as format, the exact command line to be run will be displayed in the terminal after you enter the root password. You will need to type the word 'yes' and press Enter to execute the command. The following functions are included: Unmount By default, SpaceFM will use udisks to unmount as root, but you can change this to any command in the dialog, such as umount, udevil, or pumount. Only the substitution variable %v may be used in this command to insert the currently selected device file (eg /dev/sda2). If you want any mount options added, you must specify them in the command dialog. Mount Mount works similarly to Unmount, except that the selected device is mounted as root. Label Label is used to change the volume label of a device. First, a dialog will open asking you to enter the volume label. The device's current volume label, if any, will be entered as default. To unset a volume label, leave the entry blank. Next the command used to change the volume label on this filesystem type will be shown. If SpaceFM doesn't know how to change the volume label for this type, the command will be blank and you will have to supply your own. This dialog remembers the change label command used for each filesystem type. When you click OK, your Graphical SU program will be used to run the command (no terminal will open). IMPORTANT: SpaceFM will display a warning in both dialogs if the device is currently mounted. Although some filesystem types permit it, it is generally good practice to unmount a volume before changing its label. Check Check runs a filesystem check on the device, using fsck by default. The command dialog remembers the check command used for each filesystem type. Check may only be used on unmounted filesystems. Format The Format submenu allows you to format or simply erase a device or partition. Although Format will work on an entire device, it is up to you to decide what device or device partition you want to format. The submenu contains common filesystem types to choose from. To format, select the type and review or edit the command in the dialog. This dialog remembers the format command used for each filesystem type. When you click OK, the command will be run in a terminal. After entering the root password, you will be shown the exact command to be run, and you must type the word 'yes' and press Enter to execute it. The format submenu also contain 'zero' and 'urandom'. If selected, the device will be overwritten with zeroes or random values to completely erase it. As with filesystem formats, you can edit the particular command used. Edit with care! To test out the format function without actually formatting anything, try using format on a DVD drive, or an empty drive. The entire procedure will be the same - you will merely receive an error when the command is finally executed. This will allow you to safely review how SpaceFM conducts a format. Just be sure you know which device is the DVD or empty drive! Backup|FSArchiver The Backup submenu allows you to perform a backup of a selected device or MBR. There are several supported backup types. FSArchiver (website) is a modern program which creates an archive of a filesystem. It is similar to tar, except that the archive includes checksums, can be restored if corrupted, and includes additional information. One disadvantage to using FSArchiver is that unlike Partimage, the on disk locations of files will change when restored. For most files this won't matter, but in the case of grub's stage files, moving them can cause the grub boot process to no longer work. Thus if you restore a volume containing grub's files using an FSArchiver archive, you will then need to reinstall grub to the MBR (so that it knows accurately where it's files are - these locations are stored in the MBR's boot code). An advantage to FSArchiver is that it supports more filesystem types than Partimage, including ext4 and btrfs, and several compression methods. Other advantages include file exclusion, multi-thread compression, and encryption. The data may also be restored to any partition large enough to hold it, regardless of the original partition's size. FSArchiver is also currently maintained, while Partimage is no longer actively developed. There are additional differences between Partimage and FSArchiver - see their websites for details. By default, FSArchiver will backup unmounted volumes and volumes mounted read-only. To backup a volume which is mounted read-write, you must add --allow-rw-mounted to the command. This may create inconsistencies in the backup. Run `man fsarchiver` for details. To create an FSArchiver backup, right-click on a device and select Root|Backup|FSArchiver. A file save dialog will open asking you to select a filename and location. Keep in mind that the archive size may be 50% or more of the total data saved in the filesystem. Choose a save location with ample space. Next a command dialog will show you the FSArchiver command to be used, and allow you to edit it. When you click OK, the command will be run immediately in a terminal. Backup|Partimage Although older than FSArchiver, Partimage (website) is still a valuable if simpler backup tool. One advantage to Partimage is that the backup preserves the on disk locations of files, which means there is no grub MBR breakage. However, Partimage does have some limitations when compared to FSArchiver: Partimage cannot be used to backup ext4 or btrfs filesystems. Partimage cannot be used to backup mounted filesystems. Partimage can only restore to a partition which is the same size or larger than the original partition, regardless of the actual amount of data in the archive. Archives have no internal checksums, so it is not possible to detect corruption (unless you manually create an MD5 sum and check it yourself, etc.) There is no built-in ability to encrypt an archive. There are additional differences between Partimage and FSArchiver - see their websites for details. To create a Partimage backup, right-click on an unmounted device and select Root|Backup|Partimage. A file save dialog will open asking you to select a filename and location. Keep in mind that the archive size may be 50% or more of the total data saved in the filesystem. Choose a save location with ample space. Note that Partimage will add a '.000' volume extension to the name you select. Next a command dialog will show you the Partimage command to be used, and allow you to edit it. By default, the command will break the archive into archive volumes 4G in size. This can be adjusted by carefully editing the command. When you click OK, the command will be run immediately in a terminal. Backup|MBR SpaceFM can also create a backup of a device's Master Boot Record (MBR). This is a small backup (512 bytes) which contains the entire MBR. (What Is The MBR?) After selecting Root|Backup|MBR, a file save dialog will open asking you to select a filename and location. This is a very small backup file. When you click OK, a terminal will open and the command will be executed immediately. (It is not possible to edit the MBR backup command.) Restore|From File To restore the contents of a device, partition, or MBR using a backup archive file, right-click on the target partition and select Root|Restore|From File. A choose file dialog will open for you to choose a backup file. This may be any backup file created by SpaceFM, including an FSArchiver, Partimage, or MBR archive file. (If the file was not created by SpaceFM but uses one of these formats, it may be possible to use the file if the file is named appropriately.) Next a dialog will show the restoration command to be used, and allow you to edit it. When you click OK, a terminal will open prompting you for the root password. Once entered, the exact command to be run will be shown. You will need to type the word 'yes' and press Enter to execute it. IMPORTANT: Restoring data to a partition overwrites any existing filesystem. After restoring from an FSArchiver backup, if the filesystem contains grub's files, you may need to reinstall grub to the MBR to restore normal boot behavior. (Reinstalling grub is not handled by SpaceFM, and is outside the scope of this manual, but you can create a custom command to do so.) When restoring an MBR, only the first 448 bytes of the MBR are restored. This portion contains the boot code. The remaining portion of the MBR contains the primary partition table. This portion is NOT restored (it is generally not useful to do so, and in the case of an out of date backup, could cause extreme data loss). However, the MBR backup file created by SpaceFM does contain the full 512 byte MBR, so if you do want to restore the entire MBR, consult appropriate instructions such as these. To practice restoring a file without making real changes, consider restoring to a DVD or empty drive as the target. This will allow you to see the entire process, except that the final command will fail when executed. Just be sure you know which device is your DVD or empty drive! Restore|File Info To examine the summary information in a backup file, select Root|Restore|File Info and select the backup file. Restore|File Info makes no changes to the backup file or any device - it only displays information about the backup file. It may need to run as root to do so. Edit fstab Edit fstab is a convenience function which simply opens the /etc/fstab file as root using root's editor (configured in View|Preferences|Advanced).
Contents Introduction Installation Invocation Quick Start GUI Devices Introduction List Menu Root Settings How To Enable Kernel Polling Tasks Design Mode Plugins Dialog Program Files | Settings The Settings submenu is your interface for controlling the appearance and behavior of the Devices list and volume monitor. Options include: Show|Internal Drives By default, the Devices list will only show removable and optical drives, while hiding internal system drives. If option Show|Internal Drives is checked, internal system drives will also be shown in the Devices list. For the root user, option Show|Internal Drives is checked by default. Internal drives are often treated differently by mount programs. You may not be able to mount or unmount them as a normal (non-root) user without making changes to /etc/fstab or to the mount program's configuration. Note that some external esata drives report themselves as internal, so they may not be shown unless Show|Internal Drives is checked. Another solution with these drives is to enter an exception for them in Show|Volumes. Show|Empty Drives By default, the Devices list will only show drives which contain media, and will hide empty drives. If option Show|Empty Drives is checked, drives not containing media will also be shown. Properties can still be obtained on empty drives, and you can use Remove or Reload to open or close the tray. NOTE: For proper detection of media, enabling kernel polling may be required. Show|Partition Tables By default, the Devices list will not show devices which contain partition tables, such as a whole device file (eg /dev/sda) which contains the primary partition table in its MBR, or a partition (eg /dev/sda4) which contains the extended partition table. Normally you will not work with these device files so it is not useful to show them. If you do want them shown, check option Show|Partition Tables. If the device is internal, option Show|Internal Drives is also required. IMPORTANT: For some purposes, a whole device file, such as /dev/sda, designates not just the primary partition table, but also the entire device including partitions (/dev/sda1, /dev/sda2, etc.) Thus if you format /dev/sda, for example, you will overwrite all partitions on the entire device. However, in some cases a device uses no partitions, and the entire device has been formatted with a single filesystem. In this case, the Devices list does not consider the whole device file a partition table, so option Show|Partition Tables will have no effect on it being shown. The size displayed for a whole device file (eg /dev/sda) will generally be the size of the entire device (including all partitions), regardless of whether it contains a partition table or a filesystem. Specifically, SpaceFM considers a device to be a partition table if its udev properties include a 'partition table:' line, or the device is a partition of type 0x05 (extended partition). Show|Mounted Networks By default, the Devices list will show recognized mounted network filesystems (eg nfs, cifs, etc). This enables you to click on the network to open it's mount point directory, or right-click on it to use the Unmount and Bookmark menu items. If you do not want mounted networks listed, uncheck option Show|Mounted Networks. Show|Mounted Files By default, the Devices list will show files mounted to loop devices. For example, if you right-click on an ISO file and select Open|Mount ISO, SpaceFM will use udevil to attach the ISO file to a loop device and mount it, so you can browse its contents. You can then click on this device in the Devices list to open it's mount point directory, or right-click on it to use Remove or Unmount. If you do not want mounted files listed, uncheck option Show|Mounted Files. Show|Ignore Hide Policy Some devices may have their udev property UDISKS_PRESENTATION_HIDE set to 1. This is a hint to software that the device should be hidden. By default, SpaceFM will honor these hints and hide such devices. To ignore such hints, check option Show|Ignore Hide Policy. The hide policy of a device can be seen by selecting Properties for the device and observing the value of 'presentation hide:' in the INFO section. To ignore UDISKS_PRESENTATION_HIDE for a specific device, use Show|Volumes. Show|Volumes The Show|Volumes dialog allows you to specify display exceptions for some devices. When deciding whether to show or hide a device in the Devices list, SpaceFM will first consult the Show|Volumes list. If the device is present, it will be shown or hidden based on its entry in this list. All other show or hide settings will be ignored for this device. One example use for Show|Volumes is to show an external esata drive which is erroneously identified by udev as internal. Even if option Show|Internal Drives is unchecked, the drive will be shown if listed in Show|Volumes. Show|Volumes opens a dialog which allows you to specify device files, volume labels, or device IDs in a space-separated list. There must be a space between entries and a plus or minus sign directly before each item. This list is case-sensitive. For example, to force showing device /dev/sdd1, include: +/dev/sdd1 Or, to force hiding of /dev/sdd1, include: -/dev/sdd1 The '/dev/' portion of the device file MUST be included. Devices can also be identified by volume label. For example, to always hide a device with volume label "Label With Space" use: -Label With Space DO NOT use quotes to enclose the label, even if it contains spaces. Finally, a device's ID may be used: +ata-OCZ-part4 For example, this list in Show|Volumes: +/dev/sdd1 -Label With Space +ata-OCZ-part4 would cause /dev/sdd1 and the OCZ device to be shown, and the volume with label "Label With Space" to be hidden. Show|Display Name Display Name opens a dialog which allows you to edit the display name format used for the Devices list. This controls how device names are displayed. In addition to separator characters of your choice, the following substitution variables may be used:
%v | device filename (eg sdd1)
%s | total size (eg 800G)
%t | fstype (eg ext4)
%l | volume label (eg Label or [no media])
%m | mount point if mounted, or ---
%i | device ID
A device in the list is guaranteed to have a unique, non-blank device filename - no two will be alike. The other values may be duplicated or empty in some cases. After you click OK, the display names of the currently shown devices will be updated. The list is sorted alphabetically, ignoring spaces. Auto Mount|Mount Optical The Auto Mount submenu allows you to control the auto-mounting behavior of the volume monitor. This determines what happens when a new device or new medium is inserted, whether a new tab is opened, and the auto-unmount behavior. IMPORTANT: If you have multiple auto-mount solutions installed and running, this can create confusing behavior. For example, if you use devmon, then when using SpaceFM's auto-mount features, it is best to disable devmon. If option Mount Optical is checked, optical devices such as CD/DVD drives will be automatically mounted when media is inserted, and at SpaceFM startup. TIP: For additional information on what the volume monitor is doing, try running SpaceFM in a terminal. Information on devices being auto-mounted will be printed to the terminal, and error messages generated by your command may be seen there as well. Auto Mount|Mount Removable If option Mount Removable is checked, the device will be automatically mounted whenever a removable device is inserted, and at SpaceFM startup. Auto Mount|Ignore No Policy Some devices may have their udev property UDISKS_PRESENTATION_NOPOLICY set to 1. This is a hint to software that the device should not be automatically mounted. By default, SpaceFM will honor these hints and not auto-mount such devices. To ignore such hints, check option Show|Ignore No Policy. The policy of a device can be seen by selecting Properties for the device and observing the value of 'presentation nopolicy:' in the INFO section. To ignore UDISKS_PRESENTATION_NOPOLICY for a specific device, use Mount|Volumes. Auto Mount|Mount Volumes The Mount Volumes list works similarly to the Show|Volumes list, except that it determines what devices will or will not be auto-mounted (and auto-unmounted, if option Unmount On Exit is checked). When deciding whether to auto-mount a device, SpaceFM will first consult the Mount Volumes list. If the device is present, it will or will not be auto-mounted based on its entry in this list. All other auto-mount settings will be ignored for this device. Mount Volumes opens a dialog which allows you to specify device files, volume labels, or device IDs in a space-separated list. There must be a space between entries and a plus or minus sign directly before each item. This list is case-sensitive. For example, to force auto-mounting of device /dev/sdc1, include: +/dev/sdc1 Or, to inhibit auto-mounting of /dev/sdc1, include: -/dev/sdc1 The '/dev/' portion of the device file MUST be included. Devices can also be identified by volume label. For example, to inhibit auto-mounting of a device with volume label "Label With Space" use: -Label With Space DO NOT use quotes to enclose the label, even if it contains spaces. Finally, a device's ID may be used: +ata-OCZ-part4 For example, this list in Mount Volumes: +/dev/sdc1 -Label With Space +ata-OCZ-part4 would cause /dev/sdc1 and the OCZ device to be auto-mounted, and the volume with label "Label With Space" to not be auto-mounted. Auto Mount|Open Tab If option Open Tab is checked, when a device is auto-mounted by SpaceFM, a new tab will be opened for the mount point directory of the device. If unchecked, the mount point directory will not be automatically opened. Note that the Open Tab option only affects what happens after a device is auto-mounted by SpaceFM. It has no effect on devices mounted by other means, nor does it apply to devices mounted by user action within SpaceFM. Auto Mount|Unmount On Exit If option Unmount On Exit is checked, any device which would normally be auto-mounted by SpaceFM (based on auto-mount settings) will be unmounted when SpaceFM exits. Exit occurs when the last SpaceFM window is closed, unless a daemon or desktop manager daemon is running, in which case it occurs when you logoff. If there is no fstab entry for a device, your mount program may create a subfolder for the device mount point in /media or /run/media/$USER. If you or SpaceFM unmounts the device, this subfolder will be removed. However, if you logoff without unmounting the device, the subfolder may be left behind. In order to avoid these subfolders accumulating in /media, SpaceFM can unmount devices on exit. If you don't check option Unmount On Exit, you may need to unmount devices in some other way before logging off to avoid these /media subfolders accumulating. Auto Run|On Mount Auto Run|On Mount opens a dialog which allows you to set a command line to be run when a removable drive or optical data disc is auto-mounted by SpaceFM. This command can be as simple as a program name to be run, or can be a one line bash script. The following substitution variables may be used in the command line:
%v | device (eg /dev/sda1)
%l | device volume label
%m | device mount point (eg /media/disk)
Note: When the command is run, %v, %l, and %m refer to the device being added or removed, not the device which is currently selected in the Devices list. For this command to be run, the device must be auto-mounted by SpaceFM. It will not be run for devices mounted by other means, or for devices mounted by user action within SpaceFM. The command will not be run for devices which are auto-mounted at SpaceFM's initial startup. Thus Auto Run affects devices you add after SpaceFM is running. For additional information on what the volume monitor is doing, try running SpaceFM in a terminal. Information on devices being auto-mounted will be printed to the terminal, and error messages generated by your command may be seen there as well. For example, to automatically add a mounted volume to traydevice, set the On Mount command line to:
        traydevice %v
Another example: To have notify-send alert you of new drive mounts:
        notify-send --icon=block-device --urgency=low "Volume %l has been mounted"
Auto Run|On Audio CD Similar to Auto Run|On Mount, Auto Run|On Audio CD opens a dialog which allows you to set a command line to be run when an audio CD is inserted in a qualified optical device. The command will be run only if: a) option Mount Optical is checked, AND b) the device qualifies for auto-mounting based on Mount Volumes (ie it is not inhibited). The command will not be run for media which is already inserted during SpaceFM's initial startup. Thus Auto Run|On Audio CD affects media you insert after SpaceFM is running. For example, to set an audio CD to automatically start playing in the vlc media player, set the On Audio CD command line to:
        vlc --verbose=-1 cdda://%v
Auto Run|On Video DVD Similar to Auto Run|On Audio CD, Auto Run|On Video DVD opens a dialog which allows you to set a command line to be run when a video DVD is inserted in a qualified optical device. The command will be run only if: a) the device is auto-mounted by SpaceFM, AND b) the device contains a video DVD. The command will not be run for devices which are auto-mounted at SpaceFM's initial startup, nor will it be run for devices mounted by other means, nor for devices mounted by user action within SpaceFM. For example, to set a video DVD to automatically start in the vlc media player, set the On Video DVD command line to:
        vlc --verbose=-1 dvd://%v
Auto Run|On Insert Auto Run|On Insert opens a dialog which allows you to set a command line to be run when any device is inserted. This allows you to connect your command to the insertion (device added) event. Auto-mount settings have no impact on this function. Note that when inserting a single drive, your command may be run several times - once for each device file added. For example, if you insert device /dev/sdd which contains one partition /dev/sdd1, your command will be run once with %v=/dev/sdd and once with %v=/dev/sdd1. It is up to your command or script to discard events for unwanted devices or partitions. A script can run one of these commands to get current information on a device's status:
        udevil info /dev/sdX
        udisks --show-info /dev/sdX
        udisksctl info -b /dev/sdX
Auto Run|On Unmount Auto Run|On Unmount opens a dialog which allows you to set a command line to be run when any device is unmounted by any means. Auto-mount settings have no impact on this function. For example, to automatically remove the drive from traydevice, set the On Unmount command line to:
        pkill -f "traydevice %v"
Auto Run|On Remove Auto Run|On Remove opens a dialog which allows you to set a command line to be run when any device is removed. This allows you to connect your command to the removal event. The device must be removed. Ejection of media will not cause this command to be run. Auto-mount settings have no impact on this function. Note that when removing a single drive, your command may be run several times - once for each device file removed. For example, if you remove device /dev/sdd which contains one partition /dev/sdd1, your command will be run once with %v=/dev/sdd and once with %v=/dev/sdd1. It is up to your command or script to discard events for unwanted devices or partitions. Note that when the command is run, %v equals the device file which has been removed, not the device file which is selected in the Devices list. Mount Options Mount Options opens a dialog which allows you to set default mount options to be used for all mounts, including auto-mounts. In addition to regular options, you can also specify options to be added or removed for a specific filesystem type by using the form OPTION+FSTYPE or OPTION-FSTYPE. For example, this set of options: nosuid, sync+vfat, sync+ntfs, noatime, noatime-ext4 will add nosuid and noatime for all filesystem types, add sync for vfat and ntfs only, and remove noatime for ext4. Note that some options, such as nosuid, may be added by your mount program even if you don't include them. Options specified in fstab may take precedence. pmount does not support conventional mount options, so when using pmount as the mount command, options set here will be ignored. Instead, you can include pmount's command line options in the Mount Command. Mount Command Mount Command opens a dialog which allows you to enter a custom mount command. This command will be used for all manual and automatic mounts. The command accepts two substitution variables, %v and %o, which are replaced with the device file (eg /dev/sda5) and the volume specific mount options when the command is run. Except for pmount's command line options, mount options should NOT be entered here - enter them in Mount Options instead. If the Mount Command dialog is left empty, SpaceFM will automatically determine which mount program to use. Currently it will use udevil, pmount, or the udisks v2 or v1 command line tool (/usr/bin/udisksctl or /usr/bin/udisks). Unmount Command Unmount Command opens a dialog which allows you to enter a custom unmount command. This command will be used for all manual and automatic unmounting. The command accepts one substitution variable, %v, which is replaced with the device file (eg /dev/sda5) when the command is run. If the Unmount Command dialog is left empty, SpaceFM will automatically determine which unmount program to use. Currently it will use udevil, pumount, or the udisks v2 or v1 command line tool (/usr/bin/udisksctl or /usr/bin/udisks). Single Click If option Single Click is checked, the Devices list operates in single-click mode: a single left-click on a device will open it. If unchecked, a single-click will only select a device, and a double-click is required to open it. New Tab If option New Tab is checked, when a device is opened with a single or double click (depending on option Single Click), the mount point directory will be opened in a new tab in the current panel. If unchecked, the mount point directory will be opened in the current tab. Icon The Icon submenu allows you to set custom icons to be displayed at the left of devices in the Devices list. For example, to change the icon used for an internal, mounted drive, click Icon|Internal Mounted and enter the desired icon name. By default, SpaceFM reuses a limited number of icons so that only stock GTK icons are required. If you would like the device icons to better reflect the changing state of devices, it is valuable to customize these icons. Font Font opens a font selection dialog which allows you to select the font to be used for the Devices list. Select a font family, style, and size and click OK, or click Default to use your GTK theme's font.
Contents Introduction Installation Invocation Quick Start GUI Devices Introduction List Menu Root Settings How To Enable Kernel Polling Tasks Design Mode Plugins Dialog Program Files | How To Enable Kernel Polling When using SpaceFM without udisks, and without the udisks-daemon running, you may need to enable kernel polling for device media changes to be detected. For example, if you insert a CD and SpaceFM still says 'no media', this is a symptom that kernel polling is not enabled. Kernel polling is a new feature of the Linux kernel and udev, so most distros don't yet have it enabled. Even if you are using udisks, enabling kernel polling is recommended to eliminate the need for udisks to do userspace polling. Kernel polling also corrects a common issue where the eject button on a drive won't respond with the newer udev when udisks is not used. To use kernel polling, your Linux kernel needs to be 2.6.38 or newer, and udev must be version 173 or newer. You can deterime if kernel polling is enabled by running these commands:
        cat /sys/module/block/parameters/events_dfl_poll_msecs
        cat /sys/block/sr0/events_poll_msecs
If you get 0 or -1 from those commands, then it's probably disabled. To enable kernel polling temporarily, enable common polling for the block module:
        sudo bash -c 'echo 2000 > /sys/module/block/parameters/events_dfl_poll_msecs'
Any number between 2000 and 5000 (milliseconds) should be reasonable - the higher 5000 means poll every 5 seconds, which is less overhead but a little slower. OR you can enable polling just for a single device like this (/dev/sr0 in this example):
        sudo bash -c 'echo 2000 > /sys/block/sr0/events_poll_msecs'
The change should be immediate - media will be detected and the eject button on the drive should work normally again. However, the above changes will be lost when you reboot. To make polling permanent (survives a reboot), add one of the above commands to your /etc/rc.local file (anywhere before the 'exit' line in that file), like this (without the sudo):
        echo 2000 > /sys/module/block/parameters/events_dfl_poll_msecs
OR you can pass this option to the kernel boot command line in grub: block.events_dfl_poll_msecs=2000 References: linuxfromscratch.org/msg15714.html uam-can-now-mount-cds-and-dvds bugs.archlinux.org
Tasks
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Task Manager Queue Menu Popup Dialog Design Mode Plugins Dialog Program Files | Task Manager Each SpaceFM window includes a single Task Manager which centrally manages the tasks of all panels in the window. The Task Manager is designed to eliminate annoying popup dialogs which interfere with user multi-tasking, and allows you to continue working while large files are being copied, etc. The Task Manager lists running tasks, automatically manages the task queue, allows you to stop, pause, queue, or resume tasks manually, and opens popup dialogs. Like most parts of SpaceFM, the Task Manager can also be customized with your own commands to control or interact with running tasks. A task is a job initiated by the user, such as copying a file. Tasks come in two varieties: internal and exec. SpaceFM's internal functions handle tasks such as a copying, moving, and deleting files, while an exec task runs an executable or script, either initiated from within SpaceFM's functions or from a custom command. The output of exec tasks is also collected and shown in the popup dialog's output monitor. exec tasks include custom commands as well as external commands run by SpaceFM, such as running udevil to unmount a device. The Task Manager is located at the bottom of the SpaceFM window, below all panels. It has two display modes: Show and Auto-Hide. If option View|Tasks|Show Manager is selected, the Task Manager is always visible, even when no tasks are running. Or, if option View|Tasks|Auto-Hide Manager is selected (the default), the Task Manager will become visible when tasks are running, and will be automatically hidden from view when the last task completes. The size of the Task Manager may be adjusted by dragging the pane separator above it. When a task is initiated in any panel and runs for longer than about one half second, it will be listed in the Task Manager, and the Task Manager will be shown if in Auto-Hide mode. If a task finishes in less than about one half second, the task will not be listed. New tasks are added to the end of the task list. When a task completes (successfully or with errors), it is immediately removed from the list. Task Manager columns provide information on each task, and each column can be hidden or moved, allowing you to control what information is shown. A single left-click on a task in the list, anywhere except in the Status column, will open a popup dialog showing the task's stats, a progress bar, and an output monitor. For internal tasks (copy, move, etc), the output monitor is used to show errors. For exec tasks, the output monitor shows the combined stdout and stderr output of the command as its produced. A single left-click on the Status of a task, or a middle-click anywhere on a listed task will change its state (running, queued, or paused). Click repeatedly to achieve the desired state. A right-click on a task shows the Task Manager's menu, which allows you to stop, pause, queue, and resume tasks, and also contains options for the Task Manager. (These same options may also be accessed via the main menu bar's View|Tasks submenu.)
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Task Manager Queue Menu Popup Dialog Design Mode Plugins Dialog Program Files | Queue Each task listed in the Task Manager may be in one of three states: running, paused, or queued. A running task is currently executing - files are being copied, or an executable is running, etc. A paused task has been halted. For internal tasks such as copy and move, the task thread is halted until you resume the task. For exec tasks (eg a custom command running an executable, or SpaceFM running udevil to unmount a device), the process has been sent a SIGSTOP signal as described in Pause. A queued task is also halted. The only difference is that the Task Manager will automatically resume running a queued task when other tasks complete, whereas a paused task will never resume automatically. A task's state (running, paused, or queued) can be changed by the user, and in some cases may be changed automatically. Simply, the queue is used to prevent all tasks from running simultaneously, which can impact performance. For example, copying two sets of files to the same drive simultaneously is often slower than first copying one set, then the other (due to drive seeking and other issues). Thus it may be desirable to queue the second task, so it will remain halted until the first task is completed. If option View|Tasks|Queue|Queue New Tasks is checked (the default), new tasks are automatically queued when initiated, rather than run immediately. SpaceFM will automatically determine when to resume the queued tasks, depending on option View|Tasks|Queue|Smart Queue. Or, you can always manually Resume, Pause or Stop a task to remove it from the queue.
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Task Manager Queue Menu Popup Dialog Design Mode Plugins Dialog Program Files | Menu The Task Manager's context menu allows you to control tasks and set Task Manager options. The menu is opened by right-clicking on the list. The options found on this menu are also available in the main menu bar's View|Tasks submenu (convenient if the Task Manager is hidden). The context menu contains the following items: Stop Stop is used to stop the selected task. If the task is internal (such as copying files), SpaceFM will terminate the task thread, and the task will be removed from the Task Manager. If the task is an exec task (eg a custom command running an executable, or SpaceFM running udevil to unmount a device), the process, and all its child processes, are sent a SIGTERM signal. This will usually cause the processes to terminate, but not always. So SpaceFM will also send a SIGKILL signal to all the processes several seconds later. An exec task will not be removed from the Task Manager until its process terminates. This means that if a process is hung and cannot be stopped with SIGKILL, selecting Stop may have no effect. If the command was run as another user, such as root, selecting Stop will cause a prompt for the user's password (or root's password depending on your configured su program) to open. This password is required to send the SIGTERM and SIGKILL signals to the process running as another user. (You can see the exact commands being issued by running SpaceFM from a terminal and observing its stdout output.) Paused and queued tasks may also be stopped. You can also stop a task by clicking the Stop button in the task's popup dialog. Pause Pause temporarily halts a task, putting it into a paused state. It will remain in the paused state until you Resume, Queue or Stop it, and will never be automatically resumed or queued while paused. If the task is internal (such as copying files), SpaceFM will suspend the task thread. Any files currently being read or written will remain open as long as the task is paused. If the task is an exec task, the process, and all its child processes, are sent a SIGSTOP signal. This is similar to pressing Ctrl+S in a terminal while a command is running; it will often cause the process to temporarily halt execution. In some cases, a process will not halt on a SIGSTOP signal, but the Task Manager will still list it as being in a 'paused' state until you Resume the task. If the command was run as another user, such as root, selecting Pause will cause a prompt for the user's password (or root's password depending on your configured su program) to open. This password is required to send the SIGSTOP signal to the process running as another user. (You can see the exact commands being issued by running SpaceFM from a terminal and observing its stdout output.) If you change the menu icon for Pause, the new icon will also be used as the 'paused' icon in the task list. You can also pause a task by clicking the Pause button in the task's popup dialog, left-clicking on the Status of a task in the Task Manager list, or by middle-clicking on a task in the list. Queue Selecting Queue will change the selected task's state to queued. In this state, the task is halted, but will resume automatically when other tasks complete. Note that selecting Queue on a running task may seem to have no effect. This is because the task may be queued, but then may automatically be removed from the queue and resumed by the Task Manager. There is no way to force a task to stay in the queue (but you can Pause it). If you change the menu icon for Queue, the new icon will also be used as the 'queued' icon in the task list. You can also queue a task by clicking the Queue button in the task's popup dialog, left-clicking on the Status of a task in the Task Manager list, or by middle-clicking on a task in the list. Resume Resume starts the selected task, changing its state to running. If it was in the queue it will be removed from the queue and resumed, regardless of how it conflicts with other running tasks. If the task is an exec task, the process, and all its child processes, are sent a SIGCONT signal. This is similar to pressing Ctrl+Q in a terminal after a command has been halted with Ctrl+S. If the original SIGSTOP halted the execution, SIGCONT should resume it. If SIGSTOP did not halt execution, SIGCONT will generally have no effect, except that the Task Manager will now list the task as 'running'. If the command was run as another user, such as root, selecting Resume will cause a prompt for the user's password (or root's password depending on your configured su program) to open. This password is required to send the SIGCONT signal to the process running as another user. (You can see the exact commands being issued by running SpaceFM from a terminal and observing its stdout output.) You can also resume a task by clicking the Resume button in the task's popup dialog, left-clicking on the Status of a task in the Task Manager list, or by middle-clicking on a task in the list. Tasks may also be resumed automatically by the Task Manager if they are queued. All Tasks The All Tasks submenu is used to place all listed tasks into the selected state. The Stop, Pause, Queue, and Resume menu items in this submenu have the same effect as detailed above, except that all tasks are affected. Selecting All Tasks|Queue will place all tasks in the 'queued' state momentarily, but note that one or more of the tasks may then be automatically removed from the queue and resumed. Show Manager The Task Manager has two display modes: Show and Auto-Hide. If option Show Manager is selected, the Task Manager is always visible, even when no tasks are running. The size of the Task Manager may be adjusted by dragging the pane separator above it. This option is also available via the main menu bar's View|Tasks submenu. You may also associate a key shortcut with it. Auto-Hide Manager If option Auto-Hide Manager is selected (the default), the Task Manager will become visible at the bottom of the window when any tasks are running, and will be hidden when the last task completes. This is a window space-saving feature. Although there is no option to hide the Task Manager while tasks are listed, you can effectively hide it if desired by dragging the pane separator to the very bottom of the window. However, if you do so you should enable option View|Tasks|Popups|Popup All Tasks, so that you are aware that tasks are running. This combination of a zero-height Task Manager and Popup All Tasks makes SpaceFM behave like a conventional file manager, showing a popup dialog when performing a task, rather than showing a list of tasks. You can also enable option View|Tasks|Popups|Stay On Top if desired. Columns The Columns submenu is used to select which columns are visible in the Task Manager, and to select a font for the Task Manager. Each column provides information about the listed tasks. The following columns are available:
Column | Information
--- | ---
Count | The number of items processed thus far
Folder | Directory containing current item
Item | Filename of current item, or command name
To | The task's destination directory, eg where files are being copied to
Progress | A progress bar with percentage label
Total | The task's processed and total sizes
Started | Time task was started
Elapsed | Elapsed running time of task
Current Speed | The current speed of the task (based on previous 2 second interval)
Current Remain | Estimated time remaining based on Current Speed
Average Speed | The average speed of the task
Average Remain | Estimated time remaining based on Average Speed
The current item refers to the file currently being processed in the task (copied, etc). For exec tasks, the Item column shows the name of the command in parentheses. The Status column, which shows the task icon, current state (queued or paused) and task action (copying, moving, etc.), is not included in the Columns submenu because its visibility not optional. The Reorder menu item shows a reminder: "To change the order of the columns, drag the column header to the desired location." The Font menu item allows you to set a font for the Task Manager's list columns. Narrow fonts work well. Note: The Columns submenu, and other Task Manager options, can also be found in the main menu bar's View|Tasks submenu. Popups|Popup All Tasks The Popups submenu is used to configure the Task Manager's behavior for opening popup dialogs. If option Popup All Tasks is checked, a popup dialog will automatically open for any task which runs for longer than about one half second. If the task finishes successfully, the popup will automatically close. If errors occur, it will remain open for you to view the error messages. If option Popup All Tasks is unchecked, a popup dialog will open for an internal task only if an error occurs. For custom commands, the popup behavior will depend on the command's popup settings. Note that if Popup All Tasks is checked, this overrides the command's popup settings. Popup All Tasks makes SpaceFM behave like a conventional file manager with regard to progress dialogs. If the option is enabled, it is also feasible to effectively hide the Task Manager by dragging the pane separator to the very bottom of the window when unneeded. You will still be aware of tasks running due to the popups. Option Stay On Top also works well with this approach. Popups|Stay On Top If option Stay On Top is checked, any task's popup dialog, whether opened automatically or manually, will stay on top of the SpaceFM window. However, you can still click on visible portions of the main window. If unchecked, popup dialogs may be placed beneath the main window. Popups|Detailed Stats Detailed Stats affects how task stats are displayed in the 'Progress:' line of popup dialogs (seen in internal task dialogs only). If unchecked, a brief stats line is shown. For example: Progress: 204 M / 350 M (26 M/s) :05 remaining In the above example, 204 MB of 350 MB has been processed at an average speed of 26 MB/s. The estimated time remaining until the task finishes is 5 seconds. If option Detailed Stats is checked, more detailed stats are shown. For example: Progress: #1 (204 M / 350 M) [:08] @cur 31 M/s (:06) @avg 26 M/s (:05) The additional stats include the item count (#1), the elapsed running time of the task (8 seconds), the current speed of the task (31 M/s), and the estimated time remaining at the current speed (6 seconds). The current speed is measured based on the speed over the previous two second interval, whereas the average speed is based on the entire time the task has been running. The current speed is a more accurate measure of what is happening right now, and will fluctuate more, while the average speed is a better measure of the overall performance. The time remaining estimate based on the current speed shows how long the task will continue if it continues at the current speed. The time remaining estimate based on the average speed tends to be a more accurate estimate in general. The information shown in the 'Progress:' line will match the information shown in the corresponding Task Manager columns. Popups|Overwrite Option If Overwrite Option is checked, the popup dialogs for internal tasks will show a drop-down list which displays and allows you to change the overwrite mode of the task. The list is not shown for exec tasks. For more information see Popup Dialog. Popups|Error Option If Error Option is checked, the popup dialogs for internal tasks will show a drop-down list which displays and allows you to change the error handling mode of the task. The list is not shown for exec tasks. For more information see Popup Dialog. Popups|Font The Font menu item allows you to set a font to be used in the output monitor of popup dialogs. For example, you might choose a fixed width font to make the monitor look more like a terminal. This font may also be set by right-clicking on the output monitor of any task's popup dialog and selecting Font from the context menu. The dialog font you select will be used for new dialogs only; currently open dialogs will not be affected. (You can close a dialog and re-open it to see the change.) Errors The Errors submenu contains a set of radio options which control how errors in internal tasks (such as copy and move) are handled by default. (These options have no effect on exec tasks such as custom commands.) If option Stop If First is selected (the default), the task will be stopped by the Task Manager if an error occurs AND that error is encountered before the task has successfully processed one file. If an error occurs on later files in the task, the Task Manager will open a popup dialog to show the error, but subsequent actions in the task will continue to run. For example, if there are more files to be copied, SpaceFM will attempt to copy them despite any errors on previous files. Stop If First is provided as a convenience option. Usually if the first action of a task fails, the rest of the task will fail as well, so it might as well be stopped rather than producing a long list of errors for every file in the task. If option Stop On Any is instead selected, the Task Manager will stop if any error is encountered in the task, regardless of whether the error occurs on the first or later actions. If option Continue is selected, the Task Manager will never stop an internal task due to errors. It will present the popup dialog on each error, and will list the errors in the output monitor, but subsequent actions in the task will continue. For example, if a set of files is being copied, and only one file in the middle produces a copy error, all the other files will still be copied. The popup dialog will show the error(s) for the file(s) which failed. Continue is especially useful when copying large sets of files. If the task stops on errors, you might start the task and leave the computer, only to return to find that only a few files were copied before a single error stopped the entire task. If the task continues on errors, you'll return to find all the files copied except those with errors. You can then correct the problem files without having to restart and wait for the entire task again. You can also change the error mode on a per task basis if View|Tasks|Popups|Error Option is checked. Queue|Queue New Tasks If option Queue New Tasks is checked (the default), new internal tasks are queued instead of being run immediately. (exec tasks such as custom commands are never queued automatically.) The Task Manager will then automatically resume the task when other tasks finish. When you start new tasks while other tasks are still running, Queue New Tasks improves performance by not running all the tasks simultaneously (though some tasks may be run concurrently, depending on option Smart Queue). If unchecked, new tasks are always run immediately, even if other tasks are already running, and the Task Manager will never automatically queue any task. Regardless of how Queue New Tasks is set, you can always manually Queue, Pause or Resume any task. Queue|Smart Queue The Smart Queue option determines under what conditions the Task Manager will remove a task from the queue and resume it. If UNchecked, the queue is simple - only one internal task is run at a time, and other tasks are queued. (exec tasks such as custom commands are always run regardless of option Smart Queue.) When a task finishes, the next task is removed from the queue and resumed. If you always want SpaceFM to only do one file operation at time, uncheck option Smart Queue. However, this may be less efficient. If option Smart Queue is checked (the default), the Task Manager is more sophisticated in its handling of the queue to improve both performance and convenience. In general, tasks will not be run concurrently, but the following exceptions may be made if Smart Queue is checked: Different Disks Exception If two or more tasks involve files on mutually exclusive disks (parent devices), the Task Manager will run them concurrently. To determine what devices a task involves, SpaceFM makes a list of all devices (and their parent devices, if the device is a partition) holding every file in the task, as well as the device of the destination directory, if applicable. If any devices in this list are the same as the devices in another task's devices list, the two tasks conflict and will not be run concurrently. Note that if the files of two tasks are located on different partitions on the same disk, they will conflict, and only one of the tasks will run. Note that all of the devices of the task are examined when a queue decision is made, not just the device of the file currently in use by the task. The reason for this exception is that if two tasks involve mutually exclusive disks, there is usually much less of a performance loss by running them together. On the other hand, if two tasks share files on the same disk, running them together may cause excessive drive seeking as different files are concurrently read and written. Thus no exception is made for such tasks, and only one is resumed at a time. Size Exceptions Often while copying a set of large files, you may want to perform a quick operation on a set of small files. Because the latter task is brief, it is reasonably efficient to allow it to run concurrently. This way you don't have to wait for the longer task to finish before your quick task is run. When a task involves copying or moving a set of files less than 10 MB in total size, an exception is made which allows the task to run immediately, even if other tasks are running on the same devices. An exception is also made when a task involves deleting a set of files less than 5 GB in total size. This allows small tasks to run immediately. Functional Exceptions Internal tasks involving creating links, and changing file permissions or ownership are typically very fast as little data is written to disk. Thus an exception is always made for these task types - they are run immediately. Also note that you can always manually Queue, Pause or Resume any task, regardless of the Task Manager's queue settings. For example, if you want a task to run immediately even though the Task Manager made no exception for it, you can Resume it yourself. HAL NOTE:: If you are using a copy of SpaceFM built with configure option --enable-hal, or a HAL-based SpaceFM package, option Smart Queue will be unavailable. Queue|Pause On Error If option Pause On Error is checked, when an error occurs in any running task, all queued tasks will be paused. Tasks which are already running will not be paused. The task in which the error occurs may continue running as well, depending on its error mode. The paused tasks will not resume until you manually resume them. Pause On Error is something of a paranoia setting - it ensures that if an error occurs, later tasks (which may depend on files in the task with errors) are suspended until you can examine the problem. Custom Commands As with most menus, it is also possible to add your own custom commands to the Task Manager's context menu. This allows you to add commands which can control or interact with running tasks, particularly running custom commands. There are several provided bash variables which your commands can use to get information about the currently selected task:
        "fm_task_type"            currently SELECTED task type (eg 'run','copy')
        "fm_task_name"            selected task name (custom menu item name)
        "fm_task_pwd"             selected task working directory ( same as %t )
        "fm_task_pid"             selected task pid               ( same as %p )
        "fm_task_command"         selected task command
Note that the PID of the task refers to the initial process started by SpaceFM. The actual process you want to control may be a child of this PID. For example, to add a custom command which opens the working directory of the currently selected task, use this command line:
        spacefm "$fm_task_pwd"
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Task Manager Queue Menu Popup Dialog Design Mode Plugins Dialog Program Files | Popup Dialog A single left-click on a task listed in the Task Manager will open a popup dialog showing stats, a progress bar, and an output monitor. Popup dialogs may also be automatically shown when errors occur, if option View|Tasks|Popups|Popup All Tasks is checked, or based on a custom command's popup settings. For internal tasks, the popup dialog will show the task's job ("Copy", etc), the current file being processed, the destination directory, brief or detailed stats, the status of the task ("Paused", etc), a progress bar, an output monitor used to show the details of any errors which have occured, and overwrite and error mode controls. If View|Tasks|Popups|Overwrite Option is checked and the task is internal, the popup dialog will show a drop-down list which displays and allows you to change the overwrite mode of the task (what happens when a file being copied already exists): Ask (prompt to rename, overwrite, or skip each file), Overwrite All (overwrite all files), Skip All (never overwrite files), or Auto Rename (assign a unique filename). Clicking the Overwrite All, Skip All, or Auto Rename All button in an overwrite query dialog will also change the overwrite mode. Note that the overwrite mode you set only applies to future file conflicts in the current task. If View|Tasks|Popups|Error Option is checked and the task is internal, the popup dialog will show a drop-down list which displays and allows you to change the error mode of the task: Stop If Error First, Stop On Any Error, or Continue. When the task first starts, the error mode will match the default set in View|Tasks|Errors. If you then change the error mode, it will apply to the current task only. For exec tasks, the popup dialog will show the title of the command being run, the task's status, a pulsing progress bar, and an output monitor showing any output from the command. The output monitor is designed to display text output to be used for monitoring the output of commands as they run, or to display a final result. However, the output monitor is not a terminal and does not allow you to enter input. If your command requires interaction, you will need to enable Run In Terminal instead. To close the dialog, press the Close button or close the window. You can always re-open the dialog by clicking on the task in the Task Manager. To permanently stop a task, click the Stop button. This is equivalent to selecting Stop in the Task Manager menu. The third button in the dialog will change depending on the state of the task. If the task is running, the button will be a Pause button; if the task is paused, the button will become a Queue button; and if the task is queued, the button will become a Resume button. Pressing this button is equivalent to selecting Pause, Queue, or Resume in the Task Manager's context menu.
Design Mode
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Introduction Design Menu Style Command Toolbars Shortcuts MIME Menu Plugins Dialog Program Files | Introduction SpaceFM's Design Mode allows you to change the name, shortcut key and icon of menu and toolbar items; access help for the menu item's function; set menu items to be disabled or hidden based on your rules; add, copy, and move your own custom commands to any position in most menus; and save your custom commands as plugins. All of this is controlled from the Design Menu. To open the Design Menu, simply right-click on a menu item. The Design Menu is available for most menu items, but is not available in the Bookmarks menu. Alternatively, to open the Design Menu using a shortcut key, press F2 while the menu item is highlighted. To open the Design Menu for a submenu, first close the submenu (by clicking on it), then right-click on the submenu name. Or, press F2 while the submenu is highlighted. Although you cannot right-click directly on toolbar items, Design Mode can be used to customize toolbars via their config menus, as detailed in the Toolbars section. While Design Mode works in almost all menus, a good place to practice is the Tools menu, which is reserved for your custom commands. When working with Design Mode, it is important to distinguish between two types of menu items: built-in and custom. Built-in items, such as Rename on the file list context menu, are part of the SpaceFM program, whereas custom items are custom commands you have added. Design Mode can be used on both types of items, but in different ways. For example, custom commands can be removed, while built-in items cannot (although they can be hidden). You will note that some of the Design Menu's functions will be disabled or enabled depending on the type of menu item. Custom commands in SpaceFM are like word processor macros - they allow you to automate tasks. You might create a quick custom command just for today's use, and delete it when you're done, while other commands may become a regular part of your file manager use. The Design Menu allows you to quickly create, move, copy, and remove custom commands. You don't need to be a programmer to use them - just a little knowledge of the command line gets you started.
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Introduction Design Menu Style Command Toolbars Shortcuts MIME Menu Plugins Dialog Program Files | Design Menu When you right-click on a menu item, or press F2 while the menu item is highlighted, you will be presented with a menu which gives you extensive control over how the item is displayed and performs. TIP: For help with a menu item in the Design Menu itself, highlight the Design Menu item and press F1. Show The Show item will only be visible in the Design Menu when it is opened from a toolbar config menu. Checking the Show option will show this item in the toolbar, and unchecking it will remove it from the toolbar. When a toolbar item is shown, an asterisk will appear next to it's name in the toolbar config menu. Name The Name item allows you to change a menu item's name as it appears in the menu. Precede a character with an underscore (_) to underline that character as a shortcut key if desired. You can change the name of both built-in and custom menu items. You cannot change the name of plugins in the Plugins menu. Key The Key item allows you to bind any shortcut key to the current menu item, and to change or unset an existing shortcut key. When you select Key, a dialog will open asking you to press your key combination (for example Ctrl+G), and the keycode will be displayed. If the key combination is already in use, you will be told what function the key is currently assigned to and be given the option to replace the current assignment. Once you have pressed the desired key combination, click the Set button. Or, to unset the current key assignment, leaving no key assigned to this menu item, click the Unset button. The Key option can be used on built-in and custom commands, but cannot be used on a submenu. After you have set a key combination, when you reopen the menu the new key shortcut will be displayed in the menu. You can also change the key for a menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item and press Ctrl+K, or use the mouse shortcut Ctrl + Middle-Click. Icon The Icon item allows you to set or change an icon for a menu item. A dialog will allow you to enter an icon name such as 'folder', a stock item name such as 'GTK_STOCK_OPEN' or 'gtk-open', or an absolute path to an icon file. For best results, use an icon name or stock name so that the icon can be automatically sized. When using an absolute path, the icon may not be sized correctly. Due to various issues, not all icons may work. If an icon fails to load, you will see a broken icon image instead. If successful, the icon will appear in the menu next to the menu item. To remove an icon, simply clear the text box where the icon name is entered and click OK. (For plugins, clearing the box will show the default icon for the plugin, if any.) To browse the available icons on your system, open /usr/share/icons/. When you enter an icon name, GTK will search there for an appropriate icon, and will also search ~/.icons/ and ~/.local/share/icons/. You can also change the icon for a menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item and press Ctrl+I, or use the mouse shortcut Shift + Middle-Click. Style If a menu item is a custom command, the Style submenu allows you to change the type of the menu item (Normal, Checkbox, Confirmation, or Input), and change the dialog message. For all menu items (built-in and custom), it also allows you to set context rules which determine when and how this menu item will appear. See the Style section below for details. Command Only available for custom menu items, the Command submenu allows you to set and change the custom command which is run when the menu item is selected, allows you to browse the files associated with the command or plugin, and provides options for how your command is run. See the Command section below for details. Help Help opens contextual help for a menu item. For built-in commands, the SpaceFM user's manual will be opened in your browser. If no help is currently available, Help will be disabled. [Note: Because the user's manual is still incomplete, not all menu items will have help available.] Your browser may be customized in Help|Options|Browser, and a custom location for the user's manual can be set in Help|Options|Manual Location. For custom commands, including plugins, Help will open the plain text README file for the command in your text editor. If no README file exists for a custom command, selecting Help will create one for you to edit. This file may also be named 'README.mkd' or 'README.txt'. You can also open help for a menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item and press F1, or use the mouse shortcut Alt + Middle-Click. F1 may also be used from within the Design Menu itself to show help for a Design Menu item. Cut The next items on the Design Menu, including Cut, Copy, and Paste, allow you to move and copy custom menu items. Menu items are cut, copied, and pasted in a similar way to how you cut, copy, and paste files or text, except that instead of the main clipboard, the design clipboard is used. Cut cuts the current menu item onto the design clipboard. This will not affect the contents of your main (text & files) clipboard. You will not observe any change in the menu after cutting an item - until you paste it. You cannot cut built-in menu items, only custom ones. You can cut and copy submenus, which copies all the items within the submenu recursively. You can also cut a menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item and press Ctrl+X, or use the mouse shortcut Alt + Left-or-Right-Click. Copy Similarly, Copy copies the current menu item onto the design clipboard. Again, you will not observe any immediate change to the menu after copying an item. You cannot copy built-in menu items, only custom ones. You can also copy a menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item and press Ctrl+C, or use the mouse shortcut Ctrl + Left-or-Right-Click. Paste If you previously cut or copied a menu item onto the design clipboard, the Paste item in the Design Menu will be enabled for use. Determine where in what menu you want to paste the item, right-click on an existing item to open the Design Menu, and select Paste. The menu item will be copied or moved from it's original menu location and will be placed after the item you clicked on. For example, to move a custom command called 'Test' from the Tools menu to the file list's context menu: Open the Tools menu and right-click on 'Test' to open the Design Menu. Select Cut. Now right-click on the file list and right-click on a menu item, such as 'Rename'. Select Paste in the Design Menu. Right-click again on the file list and you will see your 'Test' command has been moved from the Tools menu and has been placed immediately after the 'Rename' item. When copying a custom command, note that everything contained in the command is copied, including script, extra files you added to the command or data directories, settings, etc. You can also copy plugins from the Plugins menu (although you cannot cut them). When a plugin, which is root-installed and -protected, is copied, the copy is no longer protected by root. The copy is now a custom command which you can alter in any way. Copying a plugin provides a means of changing and customizing it. It can also then be exported and reinstalled as a plugin. See the Plugins section for details. Paste, Cut, and Copy can also be used on the separators between menu items. To move a command to directly after a separator, copy the command to the Design Menu, right-click on a separator, and select Paste. You can also cut, copy, and paste the separators themselves, providing they are not built-in. You can also paste a menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item and press Ctrl+V, or use the mouse shortcut Shift + Left-or-Right-Click. Remove Remove is used to remove any custom command or separator. It cannot be used on built-in commands or separators. When used on a plugin, Remove will uninstall the plugin (root password required). Unless you have unchecked option View|Preferences|Interface|Confirm delete/remove, you will be presented with a confirmation dialog before the item is removed. IMPORTANT: When a custom command is removed, all files and settings are deleted, including any extra files you added to the command directory, any files stored in the command's data directory, and the command script. When a plugin is uninstalled using Remove, the plugin is removed for all users, and all settings, files and plugin-data for the plugin are deleted. WHEN REMOVING A SUBMENU, all commands and submenus contained within it are deleted as described above. Note that a submenu in SpaceFM can never be empty. As a result, if you remove the last item from a submenu, a new command will automatically be added to it. You can also remove a menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item and press the Delete key, or use the mouse shortcut Ctrl + Shift + Middle-Click. Export The Export item, which is only available for custom commands, will open a save dialog, allowing you to save the custom command into a plugin file. This is how plugins are created for SpaceFM - you create a custom command, then simply export it. Once your command has been exported to a plugin file, the file can then be used to import the command back into either the Plugins menu or another menu, or can be shared with other users of SpaceFM. Exporting also provides a mechanism for backing up custom commands - the plugin file acts as a backup copy of your command which can always be imported into any SpaceFM session. When using export on a plugin, a new plugin file is created - generally this creates a copy of the original plugin (unless you modified the installed plugin files as root). You can also export a group of custom commands into one plugin file by exporting a custom submenu, which means the plugin file will contain all commands and submenus contained in the submenu. This provides way to share multiple related plugins in a single plugin file. For more information on plugins, please see the Plugins section. New The New item creates a new custom command, which will be inserted after the current menu item. This works similarly to Paste, except that instead of copying or moving a command, you're creating a new one. You will be prompted for a menu name for the command, followed by a prompt for a command line. If you just want to create the command and set the command line later, you can leave this blank and click OK. The command line accepts anything you would normally enter in a bash command line, and may include variables. It can be as simple as a program's name you want to run when this menu item is selected, or as complex as a one-line bash script. For more information, please see the Command section. For example, right-click on a menu item and select New. Enter 'Current Time' for the menu name. For the command line, enter:
        date
When you click the new menu item, a dialog will open showing you the current date and time. You can also add a new menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item where you want to insert the new item, and press the Insert key, or use the mouse shortcut Ctrl + Shift + Left-or-Right-Click. Submenu The Submenu item adds a new submenu into the menu after the current menu item. You will be prompted for the new submenu's name. Because a submenu in SpaceFM can never be empty, a new command named "New Command" will automatically be added to the new submenu. Separator The Separator item adds a new separator line into the menu after the current menu item. Design Mode works on separators too - right-click on a separator to open its Design Menu, which allows you to remove it, change it's context rules, or paste items after it.
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Introduction Design Menu Style Command Toolbars Shortcuts MIME Menu Plugins Dialog Program Files | Style The Style submenu of the Design Menu allows you to control a menu item's appearance. For custom commands, you can choose whether the item acts as a normal menu item, a checkbox, a confirmation dialog, or an input dialog. For built-in as well as custom commands, the Style menu also contains the context rules which determine if and how a menu item is displayed based on the file browser's context. Normal If your command's style is set to Normal, it will be displayed as a normal menu item, with an optional icon to the left, and a key shortcut to the right. When clicked, your custom command will be run immediately. Normal is the default style for new commands. Checkbox If your command's style is set to Checkbox, it will be displayed as a checkbox menu item with a checkbox to the left, and a key shortcut to the right. No icon will be displayed. The checkbox will contain or not contain a checkmark. Each time the user clicks the menu item, the checkbox will be toggled (if checked it will uncheck; if unchecked it will check), just like the checkbox menu items you are accustomed to. After the checkbox is toggled, your custom command will be run. Your custom command can read the value of the checkbox using the variable $fm_value. This will equal 1 if checked, or 0 if unchecked. This allows your command to take different actions depending on the state of the checkbox. For example, add a new custom menu item called 'Checker'. Then open the Design Menu for the new item and select Style|Checkbox. Open the Design Menu again and select Command|Line. Enter or paste this command line into the Edit Command Line dialog:
        if [ $fm_value -eq 1 ]; then echo "Box is checked"; else echo "Box is unchecked"; fi
Now when you click your menu item, you will be told if the box is checked or unchecked - each time you click the item, it will change. Confirmation If your command's style is set to Confirmation, it will be displayed as a normal menu item with an optional icon to the left, and a key shortcut to the right. When the item is clicked, the user will be presented with a confirmation dialog with OK and Cancel buttons. If the user the clicks OK, your custom command will then be run. If the user clicks Cancel, the command will not be run. There is also a Help button in this dialog which opens the README file for this command. To set or change the message which appears in the dialog, set Message. To show a dialog while your script is running, or to create custom dialogs, see SpaceFM Dialog. Input If your command's style is set to Input, it will be displayed as a normal menu item with an optional icon to the left, and a key shortcut to the right. When the item is clicked, the user will be prompted to enter text. If the user the clicks OK, your custom command will then be run. If the user clicks Cancel, the command will not be run. There is also a Help button in this dialog which opens the README file for this command. Your custom command can read the text entered by the user using the variable "$fm_value". The last text entered in the box will be remembered and will be the default entry next time the item is clicked. For example, add a new custom menu item called 'Your Name'. Then open the Design Menu for the new item and select Style|Input. A dialog will open asking you for the message to be displayed for the user. Enter 'Please enter your name:' into this dialog and click OK. Now open the Design Menu again and select Command|Line. Enter or paste this command line into the Edit Command Line dialog:
        echo "Your name is $fm_value."
When you click the menu item, you will be asked for your name, and if you click OK, told your name. To set or change the message which appears in the dialog, set Message. To show a dialog while your script is running, or to create custom dialogs, see SpaceFM Dialog. NOTE: When exporting a command, the last value entered in the input dialog will be exported with the plugin, even if Input is no longer the selected style. Before distributing a plugin, be sure to open or extract the archive and examine all files in your text editor to be clear on what data you are sharing. Message The Message item will be enabled only if the style is set to Confirmation or Input. This is the same dialog you saw when you first selected Style|Confirmation or Style|Input - it allows you to change the message seen by the user when the item is clicked. Although all the text must be on one line, you can create linebreaks in the displayed dialog text by inserting \n for a linefeed. Or to insert a tab, use \t. No other format characters should be used in this dialog. For example:
        Please enter your value:\n\nA value is required.
Context The context dialog allows you to set rules which determine when and how a menu item appears in the menu. Context rules can be set for both built-in and custom items, including plugins and separators. Context cannot be set for toolbar items. Context refers to the state of the entire file browser window when the menu is shown. For example, the MIME type of the currently selected file is one subject of the context. Another context subject is the filename of the selected file. Another is any device that is currently selected in the Devices list. There are many subjects which can be used in context rules. By default, the top line of the context dialog reads "Show item if context matches any rule:", and is followed by an empty rule box. When the rule box is empty, the item will always be shown regardless of context. Rather than using an arcane syntax, context rules are composed using words and phrases, which make the rules readable sentences. To compose a new rule, use the Edit Rule box. There are many context subjects available in the drop-down list, but "MIME Type" and "Filename" are the most useful for most purposes. As an initial example, we will add a rule which shows the current menu item when the selected file is an audio file. Note that when determining the context, only the type and name of the first selected file is considered. If multiple files are selected, this can be determined, but the type of each selected file cannot be individually tested. Set the rule subject to 'MIME Type'. The box to the right of the subject allows you to choose a verb, or a relationship between the subject and its value. For this example, set the verb to 'begins with'. The box below the subject and verb will contain the value to be used as a test. You can enter custom text in this box or click the arrow at the right to select a common value from the drop-down list. Each subject chosen will have a different list of common values. In this example, choose 'audio/' from the drop-down list. Below the value box containing 'audio/' is a 'Value:' label, which may or may not show a value. This label shows the subject's value in the current context. When you opened the Design Menu, the file browser had a context - perhaps some files or a device were selected, the browser was in a particular directory, etc. For example, if a file is selected and the subject is 'MIME Type', then the file's MIME type will currently appear next to 'Value:'. If no file is selected, then 'Value:' will show nothing. (Tip: You can quickly copy a value into the value box by double-clicking it.) Now the words in the Edit Rule box should read 'MIME Type... begins with... audio/'. To add this rule to the rule box above, click the Add button. 'MIME Type begins with audio/' will be added to the list of rules. For this rule to be satisfied, the MIME type of the first selected file must begin with the text "audio/". Thus a file of type "audio/mpeg" (an MP3 file), or of type "audio/x-wav" (a WAV file) would match this rule, but a file of type "video/x-msvideo" (an AVI video file) would not. (You can see the MIME type of any file by right-clicking on it in the file list and selecting Properties|Info.) In this way, our rule will only match the context if the first selected file is an audio file. The context dialog will let you know the result of the current set of rules. Below the rules box to the right, you will see "Current: Show" or "Current: Hide", depending on the current context. If the first selected file is an audio file, it will read "Current: Show", meaning that with the current context, this menu item will be shown in the menu. If instead it reads "Current: Hide", then the menu item will be hidden from view for the current context - it will not appear in the menu. The top line of the context dialog is also now enabled. For example, we can change 'Show item if context matches any rule:' to 'Enable item if context matches any rule:'. If the action is to 'Show', its opposite is to hide. If the action is to 'Enable', then its opposite to disable. Thus if we change the top line to read 'Enable item if context matches any rule:', then the menu item will be enabled or disabled depending on context, but will never be completely hidden from view in the menu. Or, to reverse the logic, action can be set to 'Hide' or 'Disable' when any rule is matched. The 'matches any rules:' box can also be changed so that it requires all rules to be matched instead of just one. This is like putting an AND between the rules, instead of OR. Or you can reverse the matching logic by choosing one of the 'doesn't match' options. For this example, set the top line to read 'Enable item if context matches any rule:'. We now have a context rule set which reads 'Enable item if context matches any rule: MIME Type begins with audio/'. Click OK to accept this rule set. Then select an audio file in the file browser's file list. Open the menu where your item appears, and it will be enabled for use. Next select another kind of file, such as a text or video file. Open the menu again, and the menu item will be disabled. In order to open the Design Menu again for this menu item, you must first select an audio file (you cannot open the Design Menu on a disabled menu item). Or you can set Ignore Context (see below). The context dialog includes a few more features for editing rules. To remove a rule, click the rule, then click the Remove button. If all rules are removed and you click OK, the item will be shown regardless of context. To change a rule in the list, click the rule, then edit the rule using the Edit Rule box. When the rule is how you want it to appear, click the Apply button to update the rule in the list. The best way to learn to use the context rules is to practice with a file selected. In this way you can use the 'Value:' and 'Current:' labels to see context values and observe the result of changing the rules. Some context subjects are boolean - they will equal 'true' or 'false' (these words must be in english even if the rest of the rule is translated). For example, the rule subject 'Multiple Selected' will always equal 'true' or 'false', depending on whether more than one file is selected in the file list of the current panel. Thus if your custom command is designed to work with only one selected file, you might set a context rule to disable it if the user has selected multiple files. Other context subjects, such as 'Panel Count', contain a number, and you can test whether they are equal to, less than, or greater than a value. For example, the rule 'Panel Count is greater than 1' will only match if the user has multiple panels shown. As a more advanced use, it's also possible to use || (or) or && (and) in the test value to provide a list of possibilities (use || or &&, but not both in the same rule). For example, this rule: MIME Type begins with audio/ || video/ causes two tests to be performed. If the MIME Type begins with 'audio/' OR the MIME Type begins with 'video/', then the rule matches. Likewise, the rule: Device Properties contains dvd && blank also causes two tests to be performed. If the Device Properties value (which provides information about the currently selected device) contains the word 'dvd', AND it contains the word 'blank', then the rule matches. This context rule would tell you if the currently selected device contains a blank DVD. It is important to note that built-in menu items sometimes have a built-in context, which is evaluated before any rules you add. For example, the file list's Paste menu item is disabled if the clipboard is empty. No rule you add will cause it to be enabled in this case, although you can still add a rule to hide it. Impossible Context Note that it IS possible to set an impossible context for an item - a set of rules which will never match. In this case the item will never be shown. This can be used to permanently hide an item you don't use. This can also happen accidently, which is one reason why Ignore Context is provided. For example, the rule Directory equals "" will never match (Directory is always set). You can also open the context dialog for a menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item and press F3, or use the mouse shortcut Ctrl + Alt + Middle-Click. Ignore Context The 'Ignore Context (global)' item in the Style submenu, if checked, causes all context rules to be ignored, and all menu items shown. This is a global setting - it disables context rules in all windows of the current instance. If you need to change the context of an item you have disabled or hidden, you can either create the appropriate context so that the item is shown and enabled, or you can open the Design Menu for any other item and check 'Ignore Context (global)'. This will allow you to then access the Design Menu of the item and change its context. When you are finished, you can uncheck 'Ignore Context (global)'. Note that Ignore Context does not affect the built-in context of built-in items - for example, even with Ignore Context checked, the file list's Paste menu item will still be disabled if the clipboard is empty.
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Introduction Design Menu Style Command Toolbars Shortcuts MIME Menu Plugins Dialog Program Files | Command The Command submenu of the Design Menu gives you substantial control over the type of custom command you're using and how it is run, lets you quickly edit your command, and also lets you browse files associated with the command. Edit & Edit As Root The Edit items allow you to edit the current command. Edit will perform differently depending on the type of command (see types below). If your command is a command line, a dialog will open which will allow you to edit the command line. If a command script is used, Edit will open the script in your configured editor. Edit As Root, if shown, works similarly, except that the script will be opened by root in root's editor. Finally, if the command is type custom, Edit will either open a file dialog allowing you to select the custom executable binary, or if the target is a text file (usually a script), it will be opened in your editor. Edit works a little differently with plugins. If the plugin is command type line, you are permitted to edit the command line of the plugin. However, note that your changes will be lost when you exit SpaceFM - the plugin will revert to its saved command line when SpaceFM restarts. Likewise, if the plugin uses command type custom, you can temporarily change the executable used, but the change will not be saved. When making a temporary change to a plugin, only the current user is affected by the change. If the plugin is a script, Edit will open the script in your editor. To actually make changes to an installed plugin's script, you must use Edit As Root. You can edit a menu item's command using a design mode shortcut instead of the Design Menu. Highlight the menu item and press F4, or use the mouse shortcut Middle-Click. Copy Copy in the Command submenu is a convenience item used to copy the current command to the main (files & text) clipboard. For a command line, Copy will copy the command line to the clipboard. For a command script or custom command, the path of the script or executable will be copied to the clipboard. Browse The browse submenu allows you to quickly open folders associated with a command. This can be used to browse a plugin's files as a security check before running the plugin. When designing more complex scripts, Browse can be used to help manage associated files. Browse|Files Each command has several folders where associated files are stored. Browse|Files opens the 'command directory' ("$fm_cmd_dir"). The command directory contains the command script if any, as well as other files you may have added for use by the command. For a custom menu item, the command directory will be something like: ~/.config/spacefm/scripts/cstm_00000000/ Or for a plugin: /usr/share/spacefm/plugins/PLUGIN-FILENAME/cstm_00000000/ (/usr/local may also be used depending on install location) While you may modify files in the command directory when creating and maintaining your command, the command script should not modify this directory while the command is running. The reason is that if you later install the command as a plugin, it will probably no longer have write access to this directory. When exporting a command, all files in the command directory are included in the plugin file. There are several special files: 'exec.sh' is the command script, if any. 'icon' is a custom icon file for the command or plugin - it will automatically be shown if no icon is set. You can also include a 'readme' file in this directory which describes your command or plugin. All files in the command directory are deleted when the command or plugin is removed! Browse|Data Commands also have an associated data directory ("$fm_cmd_data"), which may or may not exist. The data directory is used to store persistent settings or data used by the command or plugin. The data directory for both custom menu items and plugins will be something like: ~/.config/spacefm/plugin-data/cstm_00000000/ This directory is created on demand, so if you plan to use it in a script, first make sure it exists:
        mkdir -p "$fm_cmd_data"
SpaceFM does not automatically store any files in this directory - it is entirely up to you or the plugin creator how it is used. To see what persistent data a plugin is storing in your home folder, browse Data. All files in the data directory are deleted when the command or plugin is removed! Browse|Plugin The Plugin browse item will only be enabled when in the Design Menu of a plugin. It takes you to the top level of a plugin's directories, so you can browse all its files (except its data directory, which is stored in the user's home folder). The plugin directory will be something like: /usr/share/spacefm/plugins/PLUGIN-FILENAME/ (/usr/local may also be used depending on install location) Plugins may contain multiple commands (a submenu plugin), so this directory may have several command directories within it, but will at least contain one command directory as well as a 'plugin' file which defines the contents of the plugin. If the plugin is a command line, the command line will be listed in the 'plugin' file. Review the contents of this file, but it should NOT be edited. Before using a plugin obtained from another user, browse Plugin to make sure you understand what each command does. Keep in mind that plugins can do anything on your system which the current user is permitted to do. The plugin directory contained a mirror copy of the contents of the plugin archive file (eg Example.spacefm-plugin.tar.gz) when the plugin was installed. Its contents will not change unless the directory contents are modified by the root user. Line Any one of the Line, Script, or Custom options may be selected. This determines the type of command. By default, new commands will have Line set. When Line is selected, the command is executed as a single command line. To edit the command line, right-click on the menu item and select Command|Edit. The command line may contain a program name to be run or any single-line command which you would normally enter at a bash command prompt. When run, your command line is inserted into a temporary bash script, so you can do anything in this line which is valid in bash. In addition, you may use the following substitution variables in your command line:
%F | selected files
%f | first selected file
%N | selected filenames
%n | first selected filename
%d | current directory
%v | selected device (eg /dev/sda1)
%m | device mount point (eg /media/dvd)
%l | device label
%b | selected bookmark
%t | selected task directory
%p | task pid
%a | menu item value
For example, to calculate the MD5 sum of all selected filenames, use this command line:
        md5sum %N
Before your command is run, the substitution variables will be replaced with their current values. Do NOT place quotes around substitution variables - they will be quoted automatically when required. Bash variables, described below in Script, can also be used in command lines (bash variables SHOULD in general be "double quoted"). To experiment with variables, use the echo command to simply print their values. For example, the following command line will print the current directory:
        echo %d
Command lines can also contain single-line bash scripts containing multiple commands. For example, this command line will print the currect directory and the first selected file path:
        echo "Current directory:" %d ; echo "First file:" %f
This command line will print the current time, once per second, for ten seconds, then stop:
        while (( x < 10 )); do date; sleep 1; (( x++ )); done
Environment variables can also be included. For example, to run claws-mail using a custom DISPLAY variable:
        DISPLAY=:1 claws-mail
NOTE: When exporting a command, the value of the command line will be exported with the plugin even if Line is no longer the selected command type. Before distributing a plugin, be sure to open or extract the archive and examine all files in your text editor to be clear on what data you are sharing. Script Sometimes a single line isn't enough to do what you want, so SpaceFM provides a convenient way to use a full script with a command. Select Command|Script, and a bash script will be generated and opened in your configured editor. You can simply add your commands to this script and save it. There is no need to organize your scripts, because you can always use Command|Edit from the Design Menu to access the script of any custom command. At its simplest, a command script is simply a list of commands that could be entered in a terminal. The script executes each command in sequence, allowing you to automate common command-line tasks. You can also use tests and loops in scripts to make them more capable. For more information on writing scripts, see the Bash Scripting Guide. Command scripts can also evolve into small, full-featured applications using SpaceFM Dialog to show custom dialogs from within the script. The substitution variables used above in command lines may NOT be used in a command script. Instead, bash variables are preloaded for your use. When you select Command|Script, a default bash script is generated as shown below:
    #!/bin/bash
    $fm_import    # import file manager variables (scroll down for info)
    #
    # Enter your commands here:     ( then save this file )

    exit $?
    # Example variables available for use: (imported by $fm_import)
    # These variables represent the state of the file manager when command is run.
    # These variables can also be used in command lines and in the Path Bar.

    # "${fm_files[@]}"          selected files              ( same as %F )
    # "$fm_file"                first selected file         ( same as %f )
    # "${fm_files[2]}"          third selected file

    # "${fm_filenames[@]}"      selected filenames          ( same as %N )
    # "$fm_filename"            first selected filename     ( same as %n )

    # "$fm_pwd"                 current directory           ( same as %d )
    # "${fm_pwd_tab[4]}"        current directory of tab 4
    # $fm_panel                 current panel number (1-4)
    # $fm_tab                   current tab number

    # "${fm_panel3_files[@]}"   selected files in panel 3
    # "${fm_pwd_panel[3]}"      current directory in panel 3
    # "${fm_pwd_panel3_tab[2]}" current directory in panel 3 tab 2
    # ${fm_tab_panel[3]}        current tab number in panel 3

    # "${fm_desktop_files[@]}"  selected files on desktop (when run from desktop)
    # "$fm_desktop_pwd"         desktop directory (eg '/home/user/Desktop')

    # "$fm_device"              selected device (eg /dev/sr0)  ( same as %v )
    # "$fm_device_udi"          device ID
    # "$fm_device_mount_point"  device mount point if mounted (eg /media/dvd) (%m)
    # "$fm_device_label"        device volume label            ( same as %l )
    # "$fm_device_fstype"       device fs_type (eg vfat)
    # "$fm_device_size"         device volume size in bytes
    # "$fm_device_display_name" device display name
    # "$fm_device_icon"         icon currently shown for this device
    # $fm_device_is_mounted     device is mounted (0=no or 1=yes)
    # $fm_device_is_optical     device is an optical drive (0 or 1)
    # $fm_device_is_table       a partition table (usually a whole device)
    # $fm_device_is_floppy      device is a floppy drive (0 or 1)
    # $fm_device_is_removable   device appears to be removable (0 or 1)
    # $fm_device_is_audiocd     optical device contains an audio CD (0 or 1)
    # $fm_device_is_dvd         optical device contains a DVD (0 or 1)
    # $fm_device_is_blank       device contains blank media (0 or 1)
    # $fm_device_is_mountable   device APPEARS to be mountable (0 or 1)
    # $fm_device_nopolicy       policy_noauto set (no automount) (0 or 1)

    # "$fm_panel3_device"       panel 3 selected device (eg /dev/sdd1)
    # "$fm_panel3_device_udi"   panel 3 device ID
    # ...                       (all these are the same as above for each panel)

    # "fm_bookmark"             selected bookmark directory     ( same as %b )
    # "fm_panel3_bookmark"      panel 3 selected bookmark directory

    # "fm_task_type"            currently SELECTED task type (eg 'run','copy')
    # "fm_task_name"            selected task name (custom menu item name)
    # "fm_task_pwd"             selected task working directory ( same as %t )
    # "fm_task_pid"             selected task pid               ( same as %p )
    # "fm_task_command"         selected task command

    # "$fm_command"             current command
    # "$fm_value"               menu item value             ( same as %a )
    # "$fm_user"                original user who ran this command
    # "$fm_cmd_name"            menu name of current command
    # "$fm_cmd_dir"             command files directory (for read only)
    # "$fm_cmd_data"            command data directory (must create)
    #                                 To create:   mkdir -p "$fm_cmd_data"
    # "$fm_plugin_dir"          top plugin directory
    # tmp="$(fm_new_tmp)"       makes new temp directory (destroy when done)
    #                                 To destroy:  rm -rf "$tmp"

    # $fm_import                command to import above variables (this
    #                           variable is exported so you can use it in any
    #                           script run from this script)

    # Script Example 1:

    #   # show MD5 sums of selected files
    #   md5sum "${fm_files[@]}"

    # Script Example 2:

    #   # Show a confirmation dialog using SpaceFM Dialog:
    #   # Use QUOTED eval to read variables output by SpaceFM Dialog:
    #   eval "`spacefm -g --label "Are you sure?" --button yes --button no`"
    #   if [[ "$dialog_pressed" == "button1" ]]; then
    #       echo "User pressed Yes - take some action"
    #   else
    #       echo "User did NOT press Yes - abort"
    #   fi

    # Script Example 3:

    #   # Build list of filenames in panel 4:
    #   i=0
    #   for f in "${fm_panel4_files[@]}"; do
    #       panel4_names[$i]="$(basename "$f")"
    #       (( i++ ))
    #   done
    #   echo "${panel4_names[@]}"

    # Script Example 4:

    #   # Copy selected files to panel 2
    #      # make sure panel 2 is visible ?
    #      # and files are selected ?
    #      # and current panel isn't 2 ?
    #   if [ "${fm_pwd_panel[2]}" != "" ] \
    #               && [ "${fm_files[0]}" != "" ] \
    #               && [ "$fm_panel" != 2 ]; then
    #       cp "${fm_files[@]}" "${fm_pwd_panel[2]}"
    #   else
    #       echo "Can't copy to panel 2"
    #       exit 1    # shows error if 'Popup Error' enabled
    #   fi
Or, if you would like to use another script as your default, save it as ~/.config/spacefm/scripts/default-script. It is recommended that you include the example variables shown above at the end of your default script. For example, to calculate the MD5 sum of all selected filenames using a command script, you would use this line in the script:
        md5sum "${fm_filenames[@]}"
Script Directories If your script requires additional files to work, they should be placed in the command directory. You can refer to this directory in your script as "$fm_cmd_dir". Files in this directory should not be modified by the script. If your script needs to save changing, persistent data to the user's home folder (to keep track of user preferences, for example), the data directory should be used ("$fm_cmd_data"). Because this directory may not already exist, always run this command before using it:
        mkdir -p "$fm_cmd_data"
If your script needs a temporary directory to work in, you can create one automatically using this convenience function:
        tmp="$(fm_new_tmp)"
Your new, empty temporary directory will be created, and its path will be placed in $tmp by the above command. Before the end of your script, be sure to clean up by destroying the temporary directory:
        rm -rf "$tmp"
When you export a command, the command script and any files in the command directory are included in the plugin file. When you remove a command, all of these files AND the data directory are deleted! Custom In addition to Line and Script, a command's type may also be set to Custom. This will allow you to select any executable file (including a script) or desktop file to be run by this command. When using Custom, you cannot directly modify the command line used to run the program or script. When the Custom target is an executable, no filenames are passed to the program, so integration with the file browser is limited. If the Custom target is a desktop file, and the Exec line of the file contains substitution variables %f, %F, %d, or %D, these will be used to pass selected files or the current directory to the program as command line arguments. One use for Custom is to maintain an external script associated with a command, rather than the script provided by Command|Script. This way you can still use the Edit or Edit As Root items to edit the associated script, even though it is stored outside of your SpaceFM config folder. (Tip: When using an external script, be sure to include the line "$fm_import" at the top of your script, just below the "#!/bin/bash" line, if you want to use the provided bash variables.) NOTE: When exporting a command, the value of the custom target will be exported with the plugin even if Custom is no longer the selected command type. Before distributing a plugin, be sure to open or extract the archive and examine all files in your text editor to be clear on what data you are sharing. Run In Terminal Regardless of what type a custom command is (line, script, or custom), there are various ways it can be run when clicked. If your command is a command-line program which produces much output, or you need to be able to interact with it (enter input, etc), check the Run In Terminal option in the Command submenu. Each time your command is run, a terminal will be opened and the command will be run within it. The terminal program used is configured globally in View|Preferences|Advanced|Terminal. When you check the Run In Terminal option, the Run As Task option will be unchecked automatically as a convenience. (If you do want both Run In Terminal and Run As Task, you can then check Run As Task as well. However, normally it is not useful to run the terminal window as a task, as nothing will be shown in the output monitor.) Keep Terminal Enabled by default when using Run In Terminal, Keep Terminal will cause the terminal to stay open even after the command or program has finished. This is useful for programs which produce some output then exit. Without Keep Terminal, the terminal window would close before you had a chance to read the output. When Keep Terminal is enabled, after the command finishes you will be presented with a message like:
      [ Finished ]  Press Enter to close or s + Enter for a shell:
To close the window, simply press Enter. If you want to enter an interactive bash shell, press s then Enter. When finished with the shell, type 'exit'. With other programs or commands, it is not useful for the terminal to be held open after the command has finished. For these commands, uncheck Keep Terminal. Run As User Run As User opens a dialog which allows you to enter a username. When the command is run, your configured terminal or graphical su program will be used to run the command as this username, instead of as the current SpaceFM user. Depending on the su program used, you will be prompted to enter either the user's password or root's password. To run a command as root, "root" may be entered as the Run As User username. However, running commands as root in this way is generally NOT recommended. Because the command line or script is generally saved with normal user permissions, as well as the SpaceFM session file which contains settings for the command, you are running a command which is not protected by root, as root. This means that any intrusion into your normal user account could lead to this command's contents being modified. You may then run this command as root not realizing it has been modified, which may compromise your system security at the root level. To run commands more safely as root, consider exporting the command and installing it as a plugin. Plugins enjoy root protection from modification, so when they are run as root, you have more assurance that they have not been tampered with. Another option is to run SpaceFM itself as root when needed (select File|Root Window). In this way, all commands and settings are stored in root's home (/root/.config/spacefm), and are protected by root. Yet running SpaceFM as root puts much power at your fingertips - accidentally deleting a file or folder may render your system unusable! When run as root, everything you do in the file browser is done as root, including opening applications. At the very least, be sure to have an up-to-date system backup if running SpaceFM as root. It is up to you to evaluate this option for your purposes. When running a custom command as another non-root user, depending on the permissions of your SpaceFM config and scripts directories, this user may not have permission to access the command directory, including the command script. To avoid this limitation, you can use a command line, or use a script which is in a mutually accessible directory. To run a command as the current user, simply leave the Run As User dialog box empty and click OK. Run As Task Run As Task, which is enabled by default for new commands, changes several aspects of how your command is run. If Run As Task is UNchecked, the command is run asynchronously - it is run and forgotten by SpaceFM. This is useful for running a program such as Firefox, for example. SpaceFM doesn't need to wait for Firefox to finish or monitor its output - it can be run and forgotten. For commands which simply start applications or produce no output, you may want to uncheck Run As Task. If Run As Task is checked, then the command is run synchronously - as a child process of SpaceFM. SpaceFM's Task Manager will monitor the task, and if the task runs for longer than about one half second, the Task Manager will auto-show and the task will be listed. When the task finishes, it will be removed from the list. This can be used to monitor a task and to know when it has completed. In addition, any output from the task (stdout and stderr), will be collected in an output monitor. To raise this monitor, click on the task in the Task Manager. (The output monitor can also be set to raise automatically on certain events - see Popup options below for details.) SpaceFM's output monitor is designed to display text output to be used for monitoring the output of commands as they run, or to display a final result. However, the output monitor is not a terminal and does not allow you to enter input. If your command requires interaction, you will need to use Run In Terminal instead. To stop a task prematurely, raise the output monitor and click the Stop button, or right-click on the task in the Task Manager and select Stop. When SpaceFM stops a task, it sends the process and all its child processes a SIGTERM signal, followed several seconds later by SIGKILL signals. If the process was run as another user, you will be prompted to enter the user's password (or root's password) again to stop the task. When the Run In Terminal option is checked, the Run As Task option will be unchecked automatically as a convenience. Although not normally useful, it is possible to use these options together (just check Run As Task again after checking Run In Terminal). When both are checked, the terminal window itself is run as a task, the output monitor will generally be empty, and errors may not be detected. Mostly this is useful only for monitoring when the command has finished (when the terminal window closes, it will be removed from the Task Manager). Popup Task The Popup Task/Error/Output and Scroll options are only enabled if Run As Task is checked. If Popup Task is checked, the popup dialog for the task will be raised as soon as the task is added to the Task Manager, even if no output has occured. The output monitor will not be shown if the task completes in less than about one half second. Use Popup Task if you want a popup anytime the task runs for more than a moment. When the task finishes, the popup will remain, allowing you to review any output. You can also close the monitor prematurely while the task is still running by clicking the Close button - the task will continue running in the Task Manager. Note that the global Task Manager setting Popup All Tasks, if checked, takes predecence - the task will popup even if the command's Popup Task option is unchecked. By default, Popup Task is unchecked in new commands. Popup Error If Popup Error is checked and the exit status of your command is not zero, a popup dialog will be raised to show the error. Popup Error only has an effect at the moment the command finishes. If unchecked, the exit status is ignored. Popup Error provides a convenient way to get feedback on the success of your command. When the command finishes successfully it will simply be removed from the Task Manager. However, if an error occurs then the popup will be raised. Even if your command does not produce a usuable exit status, you can terminate your command line or script with a non-zero exit status to trigger the error popup. For example:
        if [ ! -e file.output ]; then exit 1; fi
(If the file 'file.output' does not exist, then exit with exit status 1, triggering an error popup if Popup Error is checked.) To see another example, scroll to the end of a command script:
        # Script Example 3:

        # Copy selected files to panel 2
          # make sure panel 2 is visible ?
          # and files are selected ?
          # and current panel isn't 2 ?
        if [ "${fm_pwd_panel[2]}" != "" ] \
                    && [ "${fm_files[0]}" != "" ] \
                    && [ "$fm_panel" != 2 ]; then
            cp "${fm_files[@]}" "${fm_pwd_panel[2]}"
        else
            echo "Can't copy to panel 2"
            exit 1    # shows error if 'Popup Error' enabled
        fi
By default, Popup Error is checked in new commands. Popup Output If Popup Output is checked, a popup dialog will be shown the first time the command produces output (even if the task runs so quickly that it is not shown in the Task Manager). Popup Output can be used to alert you when your task has produced output. By default, it is checked in new commands. Scroll The Scroll option, which is checked by default for new commands, determines the auto-scroll behavior of the output monitor. If checked, the monitor will automatically scroll down to the end of the output (unless the user has moved the scrollbar up from the bottom position). If unchecked, the output will not automatically scroll to the end. With some commands, it's useful to read the output from the top and scroll down manually. For example, if you right-click on a device in the Devices list and select Properties, you will see a non-auto-scrolling output monitor - the cursor stays at the very beginning of the output so you can read it. With other commands, you're most interested in the end of the output, so you want the output monitor to behave like a terminal and scroll to the end as new output is added. For example, errors usually appear at the end, so if you want to know why the command stopped prematurely, you're most interested in the end of the output. When you want the output monitor to behave like a terminal in this regard, check Scroll. Even if Scroll is checked, you can always manually move the scrollbar up to inhibit auto-scrolling.
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Introduction Design Menu Style Command Toolbars Shortcuts MIME Menu Plugins Dialog Program Files | Toolbars SpaceFM includes two primary toolbars: the main Toolbar (which is divided into a Left Toolbar, Path Bar, and Right Toolbar) and a Side Toolbar. To show or hide the Toolbar or Side Toolbar, right-click on the file list and check or uncheck View|Toolbar or View|Side Toolbar. Toolbars can also be customized using Design Mode. Although you cannot right-click directly on a toolbar, each toolbar has a config menu for the purpose of customization. Making changes to a toolbar's config menu will automatically change the items in the toolbar. To access a toolbar's config menu, click the leftmost icon on the toolbar (at the far left of the panel). The 'Left Toolbar' config menu is used to customize the toolbar to the left of the Path Bar, and 'Right Toolbar' is used to customize the toolbar to the right. The 'Side Toolbar' menu configures the Side Toolbar. In these menus, Design Mode works as always - use right-click or F2 to open the Design Menu for any highlighted item. But there are a few differences in these menus. Toolbar config menus show all available tool items, with an asterisk (*) next to the name of currently shown items, and no asterisk next to the name of hidden items. When opening the Design Menu on a toolbar config menu item, the topmost item will be Show. If checked, the tool item will be shown in the toolbar. If unchecked, the tool item will be hidden. You can add custom commands to these menus (and thus to the toolbars), but you cannot add submenus. There are two special built-in submenus in each toolbar config menu: Back Menu and Forward Menu. If shown, these will display not only a back/forward icon, but also a drop-down list showing path history for the current browser tab. Commands can also be pasted to and copied from the toolbar config menus.
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Introduction Design Menu Style Command Toolbars Shortcuts MIME Menu Plugins Dialog Program Files | Shortcuts In addition to right-clicking on a menu item and using the Design Menu, design mode keyboard and mouse shortcuts are also available. These shortcuts are NOT required - all you really need to know is 'right-click opens the Design Menu'. To use these shortcuts, highlight the menu item (hover your mouse cursor over it, or use the keyboard arrows to highlight the menu item), then use the key or mouse combo shown below. These shortcuts are only available for use when a menu is open.
Design Mode Shortcuts
Action | Key Combo | Mouse Combo
--- | --- | ---
Design Menu | F2 | Right
Cut | Ctrl + X | Alt + Left-or-Right
Copy | Ctrl + C | Ctrl + Left-or-Right
Paste | Ctrl + V | Shift + Left-or-Right
New | Insert | Ctrl + Shift + Left-or-Right
Edit Command | F4 or Ctrl + E | Middle
Help | F1 | Alt + Middle
Set Key | Ctrl + K | Ctrl + Middle
Set Icon | Ctrl + I | Shift + Middle
Remove | Delete | Ctrl + Shift + Middle
Context | F3 | Ctrl + Alt + Middle
These shortcuts will also work after the Design Menu has been shown. The F1 keyboard shortcut is special in that it can also be used to show help on items in the Design Menu itself. Highlight a Design Menu item (such as Export) and press F1. If the shortcut action is not available for the current menu item (for example, performing Remove on a built-in command), the Design Menu will be opened instead. NOTE: Some window managers may be configured to use some of these mouse combos for other purposes. For these to work within SpaceFM, you may need to disable them in your window manager.
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Introduction Design Menu Style Command Toolbars Shortcuts MIME Menu Plugins Dialog Program Files | MIME Menu When you right-click on a file in the file list, the Open submenu shows applications associated with the (first selected) file's MIME type (eg text/plain). If you right-click on one of these listed applications, or press F2 while the menu item is highlighted, you will be presented with a menu which allows you to configure MIME associations and definitions for this file type. TIP: For help with a menu item in the MIME menu itself, highlight the MIME menu item and press F1. IMPORTANT: Changes made with this menu may affect any programs on your system which use the MIME database, not just SpaceFM. However, some programs use other means for determining file types, or some combination of several methods, so not all MIME changes made in SpaceFM will be reflected in all programs. For more elaborate MIME adjustments, consider using a dedicated MIME editor. How MIME Works SpaceFM uses freedesktop.org's shared-mime-info database exclusively to determine file types, display file type names, determine and adjust associated applications, and determine and adjust the default application for a type. It helps to know some basics about how MIME works so you can better control how your system handles file types. MIME knows what applications are installed on your system by examining .desktop files. When an application is installed, it will usually install one or more .desktop files for itself to /usr/share/applications or /usr/local/share/applications. These .desktop files determine the display name of the application (which may differ from the executable's name), translated display names, the command used to execute the application, an icon for the application, what MIME file types the application can open, and other specifics. If you would like to change anything in an application's .desktop file, the correct way to do so is to copy the desktop file to ~/.local/share/applications in your home folder, and make changes in the copy. (Changes made directly in /usr/share/applications may be lost when the software is upgraded.) You can also add your own custom .desktop files to run programs or scripts. When MIME looks for a desktop file, first it looks in ~/.local/share/applications, then in /usr/local/share/applications, and then in /usr/share/applications, using the first copy it finds. Thus copies in your home folder always take precedence, and will not be modified when software is upgraded. Anytime .desktop files are created or changed, the MIME desktop database needs to be updated. A user's database can be updated by the user running:
        update-desktop-database ~/.local/share/applications
This command examines all the desktop files and will create files named 'mimeinfo.cache' which contain all the relevant information for fast access. The mimeinfo.cache files should never be edited directly. To determine what applications are associated with a given MIME type (what applications can be used to open files of that type), SpaceFM and many other programs will build a list of applications by examining the mimeinfo.cache files in ~/.local/share/applications, /usr/local/share/applications, and /usr/share/applications. Sometimes a distro, admin, or user may want to associate additional applications with a MIME type, or remove unwanted associations. Information about added and removed associations are placed in mimeapps.list files located in the applications directories. ~/.local/share/applications/mimeapps.list in the user's home folder takes precedence. Distros and admins may also use files named 'defaults.list' to associate applications, although modification of these files by the user is now deprecated - change mimeapps.list instead. (SpaceFM versions >0.7.7 will use mimeapps.list first if present, and will only modify mimeapps.list.) The first application listed for a given MIME type in these files, for which a corresponding .desktop file can be found, is considered the 'default application' for this MIME type. For example, when you click on a file in SpaceFM, the default application is used to open the file (with some exceptions). To define MIME types, xml files are used. These may determine a file type using a filename glob (eg *.txt), or may base determination on a file's contents. freedesktop supplies basic definitions, and additional ones may be added in /usr/share/mime/packages. Any definitions placed in Overrides.xml will override other definitions. Users can add xml files to add custom MIME types or to change existing definitions. These are usually placed in ~/.local/share/mime/packages. After adding or changing these files, run:
        update-mime-database ~/.local/share/mime
Or to update the system-wide database:
        sudo update-mime-database
At startup, SpaceFM reads and caches these xml files to know how to recognize all the file types on your system. Because they are cached, you may need to restart SpaceFM after changing MIME type definitions. SpaceFM's MIME menu makes it easy to find and edit all the files needed to customize your MIME database, and in some cases will create and edit the files for you. One example is the 'Choose...' menu item on the file list context menu's Open submenu, which lets you choose or set a default application for a MIME type. Choosing an application will cause SpaceFM to edit your mimeapps.list file, setting the application as the default. For other adjustments, see the MIME menu items below. Set As Default Selecting Set As Default will set the selected application as the default application for the selected file's MIME type. In SpaceFM this will move the application to the top of the Open submenu. Specifically, SpaceFM will edit your ~/.local/share/applications/mimeapps.list file, adding the application's .desktop file to the beginning of the list for the given MIME type in [Added Associations], and will remove it from [Removed Associations] if present. Remove Selecting Remove will remove the selected application's association with the selected file's MIME type for the current user. It will no longer appear in the Open submenu for this file type. Specifically, SpaceFM will edit your ~/.local/share/applications/mimeapps.list file, removing the application's .desktop file for the given MIME type in [Added Associations], and will add it to [Removed Associations] for the given MIME type. To restore an association that you have removed, use Add... NOTE: When compiling the list of applications to appear in the Open submenu for a text file, SpaceFM will include applications associated with the MIME type (eg text/html) and applications associated with text/plain. If you select Remove on an application, it will be removed as an associated application for the MIME type (eg text/html), but will NOT be removed as an associated application for text/plain (unless the MIME type is text/plain). Thus using Remove may not remove the application from the Open submenu for this type, unless you also remove it from text/plain. Text files are the only files with this behavior. Add... Selecting Add... will open the same dialog as the 'Choose...' item on the Open submenu, allowing you to select an application or enter a command to be associated with this MIME type. The application won't be made the default unless you check option 'Set as default' in the dialog. The application or command will then appear as an associated application in the Open submenu for this MIME type. Specifically, SpaceFM will edit your ~/.local/share/applications/mimeapps.list file, adding the application's .desktop file to the list for the given MIME type in [Added Associations], and will remove it from [Removed Associations] if present. If you entered a command instead of choosing an application from the list, a custom desktop file will be created for your command in ~/.local/share/applications/. application.desktop The next item on the MIME menu will be the name of the .desktop file for the selected application (eg spacefm.desktop). Selecting this item will open the copy of the desktop file located in ~/.local/share/applications/ using your text editor, allowing you to customize the .desktop file. For example, you can change the application's name (how it appears in the menu), the icon as it appears in the menu, or the command run when the application is selected. Edit the file and save it. If "(*copy)" appears next to the .desktop filename on the menu, this means that no copy of the desktop file currently exists in ~/.local/share/applications/. If you select it, SpaceFM will automatically copy the desktop file from /usr/share/applications/ to ~/.local/share/applications/, and will then open the copy in your text editor. The copy in ~/.local/share/applications/ always takes precedence over other locations. mimeapps.list Selecting mimeapps.list will simply open ~/.local/share/applications/mimeapps.list in your text editor, allowing you to examine added and removed associations, and edit them. If you edit this file, be careful to use its default formatting. While SpaceFM doesn't mind spaces in the lists, other programs may not be so forgiving. Any changes you make to this file will immediately take effect. applications/ Selecting applications/ will open the ~/.local/share/applications/ folder in a new tab. This folder contains your user copies of .desktop files as well as your mimeapps.list file. (See How MIME Works above.) mime-type.xml The next item on the MIME menu will be the name of an xml file which can be used to redefine this MIME type (eg text-plain.xml) for the current user. Selecting this item will open the file located in ~/.local/share/mime/packages/ using your text editor, allowing you to customize the MIME type definition. For example, you can change what filename extensions (globs) are used, or change the name of the file type as it appears in the Type column of the file list. Edit the file and save it. You may then need to run 'update-mime-database ~/.local/share/mime' and/or restart SpaceFM for the changes to take effect. (SpaceFM will run update-mime-database for you if you opened the file using this menu item.) If "(*new)" appears next to the xml filename on the menu, this means that the xml file doesn't currently exist in ~/.local/share/mime/packages/. If you select it, SpaceFM will automatically create the xml file using the definition in /usr/share/mime as a template (if present), and will then open the new xml file in your text editor. The copy in ~/.local/share/mime/packages/ always takes precedence over other locations. You can also use this menu item simply to see the MIME type of the selected file. For example, if the name of this menu item is "application-zip.xml", then you know the MIME type is "application/zip". mime/packages/ Selecting mime/packages/ will open the ~/.local/share/mime/packages/ folder in a new tab. This folder contains your custom xml files used to redefine MIME types (see mime-type.xml above). After adding, editing, or removing files from this folder, you may then need to run 'update-mime-database ~/.local/share/mime' and/or restart SpaceFM for the changes to take effect. usr/ The usr/ submenu gives you access to files and folders in /usr/share/applications/ and /usr/share/mime/packages/ (or in some cases, /usr/local/share/...). For example, to see the original .desktop file for an application, select the .desktop file in the usr/ submenu. It will be opened in your editor, but can only be edited by root. (Normally it is useless to edit this copy, as a software upgrade may overwrite it.) Likewise, to see the system-wide MIME type definition for the current MIME type, select the xml file in the /usr submenu. The Overrides.xml file, if present, will be opened as root to allow you to edit it. This is one place where you can define system-wide changes to MIME types. (Or you can copy your custom xml files to /usr/share/mime/packages/). When making changes here you must run 'sudo update-mime-database' and restart SpaceFM.
Plugins
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Introduction Install Copy Uninstall Creation And Files Dialog Program Files | Introduction Like any plugin, a SpaceFM plugin extends the features of the file manager. What's different about SpaceFM plugins is how readily they're created. Any custom command can be turned into a plugin simply by exporting it to a plugin file. SpaceFM plugins use an open format which can include additional files, and can also store persistent data between sessions. SpaceFM plugins can do anything a bash script can do - which means just about anything. Eventually, some plugins will be included with SpaceFM. Additionally, user-contributed plugins can be shared and obtained in the SpaceFM Wiki. It is your responsibility to evaluate the safety and applicability to your purposes of all plugins.
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Introduction Install Copy Uninstall Creation And Files Dialog Program Files | Install When a plugin is installed, it is added to the Plugins menu where it gains root protection (it cannot be modified by normal users) and becomes accessible to all users of SpaceFM on your system. Installing a plugin helps protect the plugin's contents from tampering, but it also limits what you can change. To install a plugin using a plugin file, use Plugins|Install|File. You will be prompted to choose a file, and you will need to enter the root password for installation. You can also install a plugin directly from a URL using Plugins|Install|URL (be sure to examine their contents before running commands within the plugin). wget is required when installing from URL (this program is already installed on most Linux distributions). Remember that installing a plugin as root does NOT mean it is run as root. The files for the plugin are merely copied to /usr/?local?/share/spacefm/plugins as root. Installed plugins are available via the Plugins menu. SpaceFM will allow you to set a key shortcut for a plugin, change its icon, and change Run In Terminal and Run As Task options for the plugin. You cannot change the type (line, script, custom) of a plugin, and unless you do so as root, you cannot edit the command script. You can temporarily edit the command line or custom target of a plugin, but your changes will not be saved - they will be valid only for the current session by the current user. To see the help file for a plugin command, use Help on the Design Menu, or highlight the menu item and press F1. When you make Design Mode changes to a plugin, you are not actually altering the plugin itself. SpaceFM creates a skin for the plugin which holds your custom key shortcut, icon, etc. Thus these changes made to a plugin by one user will not be seen by other users on the system. This skin is retained in the SpaceFM session file until the plugin is removed. If you want to make deeper changes to a plugin, you can copy it using Copy on the Design Menu, and Paste the copy into another menu. The copy will be exactly like the plugin, except that its files will no longer be owned by root. Thus you can make any changes to a copied plugin, just as with any custom command. You can also export the copy, then install it as a plugin again, either with a new name, or overwriting the old plugin. You can also export an installed plugin. Unless you made changes to the plugin directory as root, the exported plugin file will essentially be a copy of the original plugin file. NOTE: Plugins created with SpaceFM versions 0.7.0 and later may not work correctly with prior versions due to changes in the file structure of plugins and commands.
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Introduction Install Copy Uninstall Creation And Files Dialog Program Files | Copy Instead of installing a plugin, you can import it into any SpaceFM menu which supports design mode. When imported in this way, the plugin loses root protection and becomes a normal custom command. To do so, use Plugins|Copy|File to import a plugin file, or Plugins|Copy|URL to import directly from URL. No root password is required. The plugin will be copied to the design clipboard. You may then use Paste on the Design Menu to paste the command into any location in any supported menu. As with any commands, you cannot paste the command into the Bookmarks menu, as well as some parts of the Plugins menu and Open context menu. If option Plugins|Copy|Verbose is checked, after the plugin has been copied to the design clipboard, you'll see a message reminding you what to do next. IMPORTANT: Due to a problem in SpaceFM versions 0.7.2 and prior, copying an installed plugin to another menu may not copy all required plugin files. To avoid this problem, run the following command (this only needs to be done one time, and only when using SpaceFM <= 0.7.2):
        mkdir -p ~/.config/spacefm/scripts
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Introduction Install Copy Uninstall Creation And Files Dialog Program Files | Uninstall To uninstall a plugin, use Remove on the Design Menu. You will be prompted for the root password, and all files and settings associated with the plugin will be removed. If the installed plugin is a submenu plugin, you can only remove the top submenu of the plugin. You cannot remove individual items from within it.
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Introduction Install Copy Uninstall Creation And Files Dialog Program Files | Creation And Files The best way to create a plugin, whether for your own use or for others, is to create a custom command. Develop the command to work the way you want, and set any Design Mode options for how the command is best run. When you're ready to create the plugin, simply use Export on the Design Menu to save the command to a plugin file. A plugin may also contain multiple related commands and submenus of commands. To create such a plugin, simply export a submenu. Exporting commands as plugins also provides a way to back up commands. By exporting it to a plugin file, your custom command becomes portable and self-contained - you can always use the plugin file to import it back into any SpaceFM session, either as a normal custom command, or as an installed plugin. Plugin File The SpaceFM plugin file uses a simple and open format. The plugin file is simply a tar.gz archive. This allows you to open any plugin file and examine its contents using your text editor. With the possible exception of any extra files included within the plugin, all files are plain text files. When creating plugins, try to honor this design by using open, accessible text file formats. A plugin file, such as Example.spacefm-plugin.tar.gz, contains a single file named 'plugin' which SpaceFM uses to define the contents of the plugin. This file is plain text and can be viewed in your editor, but should NOT be edited. In addition, plugin files contain one or more command directories, one for each command in the plugin. Plugins may be a single command, or they may be a single submenu which contains an unlimited number of commands and submenus. Thus a set of commands with related functions can be distributed as a single submenu plugin. (To create a submenu plugin, simply export a submenu.) TIP: If you have a larger plugin, you can manually convert it to tar.xz format and SpaceFM will accept it (only tar.gz or tar.xz). Extra Files Additional files required by your plugin can be added to the command directory, accessed in the Design Menu via Command|Browse|Files. When the command is exported, these files will be included in the plugin file. The command script (exec.sh) is located in the command directory. Files in the command directory should be considered read-only (once your plugin is installed, your script will probably not have permission to modify them). You may also add a file named 'icon'. SpaceFM will automatically display this icon for the plugin if no other icon is set in the Design Menu. Small icons work best, as your icon may not be resized. If you don't want to include a custom 'icon' file, you can also simply set a standard icon for the command using the Design Menu. Users can also override your default icon in this way. Keep in mind that the user may be using a different icon theme than you are, so try to stick with common icon names. Using an absolute path for the icon is not recommended. In addition, adding a README file to the command directory is recommended. This file will be created automatically if you select Help from the Design Menu. This file explains what your plugin does, how to use it, and may include an email address, website, license terms, etc. If multiple commands in your plugin need to access shared files, it is possible to place them in the top level of the plugin file, the plugin directory. SpaceFM won't do this for you automatically when exporting a command, but you can add them using an archive application after the plugin file has been created. Or, if your plugin is already installed and you added files to its plugin directory, these files WILL be included in the plugin file when the plugin is exported again. Your scripts can access this directory using "$fm_plugin_dir". To browse it, use Command|Browse|Plugin from the Design Menu. One limitation to using this directory is that if a user copies commands from within your plugin submenu to another menu, the files in the plugin directory will NOT be included. Thus, it may be better to include all of a command's required files in its command directory instead. In this way, each command is complete when copied elsewhere. Data Files If necessary, your plugin can maintain changing, persistent data files in the user's home folder to store user preferences and other changing data. Your script should store these files only in the data directory ("$fm_cmd_data", accessed via Command|Browse|Data). Data files are NOT included when the command or plugin is exported, and they are deleted when the command or plugin is removed. Each command or plugin has its own data directory. If you need to populate the data directory with initial files, consider making your script copy them from the command directory when it is first run. Because it is located in the user's home folder, you should always document what files you are storing in the data directory. Most plugins do not require any data files. Remember that the data directory may not exist, so make sure your script always creates it before attempting to use it. Place this command in the initial part of your script:
        mkdir -p "$fm_cmd_data"
Before distributing a plugin, be sure to open or extract the archive and examine all files in your text editor to be clear on what data you are sharing. For example, some entries may be included in the plugin file even if they are currently disabled in the command.
Dialog
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Introduction Invocation Simple Elements List Elements Non-Visible Elements Commands Internal Commands Program Files | Introduction SpaceFM Dialog is a built-in feature of SpaceFM which allows you to easily create and control custom GTK dialogs. Typically such dialogs are shown from scripts to gather information from the user. SpaceFM Dialog allows scripts to easily use much of the power of GTK - a dialog can be as simple as a single message prompt or as complex as a mini-app with lists, editors, and other widgets. Dialog elements can have associated commands which are run when the user takes an action (such as pressing a button ), and internal commands can be used to modify the dialog elements while the dialog is running. When SpaceFM Dialog exits, it writes variables to stdout which can be evaluated directly in bash, or easily parsed in other languages. Although SpaceFM Dialog is relatively easy to use, this portion of the manual assumes you have a basic understanding of command lines and scripts. If you don't, try some of the examples and also consult the Bash Scripting Guide for reference. All of the example commands in this section can be pasted as-is into your terminal for a demonstration.
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Introduction Invocation Simple Elements List Elements Non-Visible Elements Commands Internal Commands Program Files | Invocation SpaceFM Dialog runs as a separate instance, whether other instances of SpaceFM are running or not. This means you can use SpaceFM Dialog from within custom command scripts in SpaceFM, or in other scripts which run independently. Help Reference To see SpaceFM Dialog's help reference, run:
    $ spacefm -g help
    SpaceFM Dialog creates a custom GTK dialog based on the GUI elements you
    specify on the command line, features run-time internal/external commands which
    can modify elements, and outputs evaluatable/parsable results.
    Usage:
        spacefm --dialog|-g {ELEMENT [OPTIONS] [ARGUMENTS...]} ...
    Example:
        spacefm -g --label "A message" --button ok

    ELEMENT:       OPTIONS & ARGUMENTS:
    --------       --------------------
    --title        TEXT|@FILE
                   Set window title
    --window-icon  ICON|@FILE
                   Set window icon
    --label        LABEL|@FILE
                   Add a text label
    --button       LABEL[:ICON]|STOCK|@FILE [COMMAND...]
                   Add STOCK dialog button, or LABEL button with ICON
    --free-button  LABEL[:ICON]|STOCK|@FILE [COMMAND...]
                   Add STOCK button, or LABEL button with ICON anywhere
    --input        [--select START[:END]] [TEXT|@FILE [COMMAND...]]
                   Add a text entry
    --input-large  [--select START[:END]] [TEXT|@FILE [COMMAND...]]
                   Add a large text entry
    --password     [TEXT|@FILE [COMMAND...]]
                   Add a password entry
    --viewer       [--scroll] FILE|PIPE
                   Add a file or pipe viewer
    --editor       [FILE [SAVEFILE]]
                   Add multi-line text editor
    --check        LABEL [VALUE|@FILE [COMMAND...]]
                   Add a checkbox option
    --radio        LABEL [VALUE|@FILE [COMMAND...]]
                   Add a radio option
    --icon         ICON|@FILE [COMMAND...]
                   Add an icon
    --image        FILE|@FILE [COMMAND...]
                   Add an image
    --progress     [VALUE|pulse|@FILE]
                   Add a progress bar
    --hsep         ( no arguments )
                   Add a horizontal line separator
    --vsep         ( no arguments )
                   Add a vertical line separator
    --timeout      [DELAY|@FILE]
                   Automatically close window after DELAY seconds
    --drop         {TEXT... --}|@FILE [DEFAULT|+N|@FILE [COMMAND...]]
                   Add a drop-down list.  COMMAND run when clicked.
    --combo        {TEXT... --}|@FILE [DEFAULT|+N|@FILE [COMMAND...]]
                   Add a combo list.  COMMAND run when Enter pressed.
    --list         {[^HEAD[:TYPE]] [--colwidth=W] TEXT... --}|@FILE [COMMAND...]]
                   Add a list box.  COMMAND run when double-clicked.
    --mlist        {[^HEAD[:TYPE]] [--colwidth=W] TEXT... --}|@FILE [COMMAND...]]
                   Add a list box with multiple selections
    --chooser      [CHOOSER-OPTIONS] [DIR|FILE|@FILE [COMMAND...]]
                   Options: [--save] [--dir] [--multi] [--filter F[:F...]]
    --prefix       NAME|@FILE
                   Set base variable name  (Default: "dialog")
    --window-size  "WIDTHxHEIGHT [PAD]"|@FILE
                   Set minimum width, height, padding (-1 = don't change)
    --hbox         [--compact] [PAD|@FILE]
                   Add following widgets to a horizontal box
    --vbox         [--compact] [PAD|@FILE]
                   Add following widgets to a vertical box
    --close-box
                   Close the current box of widgets
    --keypress     KEYCODE MODIFIER COMMAND...
                   Run COMMAND when a key combination is pressed
    --command      FILE|PIPE [COMMAND...]
                   Read commands from FILE or PIPE.  COMMAND for init.

    The following arguments may be used as shown above:
        STOCK    One of: ok cancel close open yes no apply delete edit save stop
        ICON     An icon name, eg:  gtk-open
        @FILE    A text file from which to read a value.  In some cases this file
                 is monitored, so writing a new value to the file will update the
                 element.  In other cases, the file specifies an initial value.
        SAVEFILE An editor's contents are saved to this file if specified.
        COMMAND  An internal command or executable followed by arguments. Separate
                 multiple commands with a -- argument.  eg: echo '#1' -- echo '#2'
                 The following substitutions may be used in COMMANDs:
                     %n           Name of the current element
                     %v           Value of the current element
                     %NAME        Value of element named NAME (eg: %input1)
                     %(command)   stdout from a command
                     %%           %
        LABEL    The following escape sequences in LABEL are unescaped:
                     \n   newline
                     \t   tab
                     \"   "
                     \\   \
                 In --label elements only, if the first character in LABEL is a
                 tilde (~), pango markup may be used.  For example:
                     --label '~This is plain. <b>This is bold.</b>'

    In addition to the OPTIONS listed above, a --font option may be used with most
    element types to change the element's font and font size.  For example:
        --input --font "Times New Roman 16" "Default Text"

    INTERNAL COMMANDS:
        noop       ( any arguments )
                   No operation - does nothing but evaluate arguments
        close      ( no arguments )
                   Close the dialog
        press      BUTTON-NAME
                   Press button named BUTTON-NAME
        set        NAME VALUE
                   Set element NAME to VALUE
        select     NAME [VALUE]
                   Select item VALUE (or first/all) in element NAME
        unselect   NAME [VALUE]
                   Unselect item VALUE (or all) in element NAME
        focus      NAME [REVERSE]
                   Focus element NAME
        hide       NAME [REVERSE]
                   Hide element NAME
        show       NAME [REVERSE]
                   Show element NAME if previously hidden
        disable    NAME [REVERSE]
                   Disable element NAME
        enable     NAME [REVERSE]
                   Enable element NAME if previously disabled
        source     FILE
                   Save files and write source output to FILE
Usage The command line accepts any number of elements:
        spacefm -g ELEMENT [OPTIONS] [ARGUMENTS] \
    	       ELEMENT [OPTIONS] [ARGUMENTS] \
    	       ELEMENT [OPTIONS] [ARGUMENTS] \
    	       ...
where each ELEMENT has its own options and arguments. An element represents one piece of the dialog. It may be a widget, such as a label or button, or it may be an invisible element which controls how the dialog looks or behaves. For example, to show a dialog with a message label and an OK button, run this command:
        spacefm -g --label "This is a message." \
    	       --button ok
Note: The forward slash (\) at the end of a line tells the terminal that the command is continued on the next line. You can select both lines above, copy them, and paste them into a terminal to run the above example; it is not necessary to copy and paste each line individually. In this manual, SpaceFM Dialog commands are always shown with at most one element on each line for clarity. These multi-line commands can also be pasted directly into scripts. Evaluating The Output When the above command is run, a message dialog will be shown. When the OK button is pressed, the dialog will close and the following output will be written to the terminal:
        #!/bin/bash
        # SpaceFM Dialog source output - execute this output to set variables
        # Example:  eval "`spacefm --dialog --label "Message" --button ok`"

        dialog_label1='This is a message.'
        dialog_pressed='button1'
        dialog_pressed_index='0'
        dialog_pressed_label='ok'
        dialog_button1='ok'
        dialog_windowsize='450x100'
The above source output, written to stdout, is produced by the dialog to allow you to easily use element values in your script. (To get this output while the dialog is still running, use source.) If using bash or another compatible shell, you can automatically evaluate this output to set the variables. For example, you can run:
        eval "`spacefm -g --label "This is a message." \
    	              --button ok`"
Using this method, you will no longer see the output in the terminal when the dialog closes. Instead, the output is fed into eval, which reads the variable values. A command enclosed in backticks (`), not to be confused with apostrophes ('), evaluates to a string containing the stdout output of the command. This output is then double-quoted (") and passed to eval, which interprets it (sets the variables). (Be sure to double-quote the backticks as shown above or some data may be lost!) After running the above command, we can see the value is set:
        echo "$dialog_pressed"
        button1
If you would like the output to also be written in the terminal, you can use the following method instead:
        out="`spacefm -g --label "This is a message." \
        	             --button ok`"
        eval "$out"   # read
        echo "$out"   # display
The above commands place spacefm's output into the variable 'out', then pass that value to eval to set the variables, then echo writes the output to the terminal for you to see. Yet another method is to write the output to a file, then source the file. For example:
        spacefm -g --label "This is a message." \
    	       --button ok > /tmp/outputfile
        source /tmp/outputfile  # read
        cat /tmp/outputfile     # display
        rm /tmp/outputfile      # cleanup
In general, anytime you need to use the dialog's variables in your script, you will want to use one of the above methods to evaluate the dialog's output. Or, if your shell doesn't support eval, you can parse the output manually.
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Introduction Invocation Simple Elements List Elements Non-Visible Elements Commands Internal Commands Program Files | Simple Elements Elements tell SpaceFM Dialog how to build your dialog. Each element is similar to a command line - it includes an element followed by arguments. When SpaceFM Dialog sees a new element on the command line, it knows the arguments for the previous element have ended. Most visible elements (widgets) are stacked vertically in the dialog (in a vbox), while buttons are packed horizontally at the bottom of the dialog: ELEMENT1 ELEMENT2 ELEMENT3 BUTTON1 BUTTON2 The following elements may be used to create dialogs: --title Usage: `--title TEXT|@FILE` The --title element sets the title of the dialog window ("SpaceFM Dialog" is the default title if no --title element is used). For example:
        spacefm -g --title "A Window Title"
--title also accepts a file instead of a string. For example:
        echo "A Window Title" > /tmp/dialog-title
        spacefm -g --title @/tmp/dialog-title
The "at" sign (@) indicates that a file path is being specified, and that SpaceFM Dialog should read the value from the first line of the file /tmp/dialog-title. The file is also watched for changes. This method allows you to later change the window title. As the dialog is running, in another terminal run:
        echo "Another Window Title" > /tmp/dialog-title
and the dialog window's title will change to reflect the new value. Thus using @FILE is one method which allows you to dynamically change the dialog as its running (commands being another method). In commands, the value of a title element (%title1) is the title's TEXT. Also note that even if no --title element has been added to the dialog, you can later use the set command to set 'title' (no numeric suffix). --window-icon Usage: `--window-icon ICON|@FILE` The --window-icon element sets the dialog window's icon ("spacefm-48-pyramid-blue" is the default icon if no --window-icon element is used). For example:
        spacefm -g --window-icon gtk-open
--window-icon also accepts a file instead of a string. For example:
        echo "gtk-open" > /tmp/dialog-wicon
        spacefm -g --window-icon @/tmp/dialog-wicon
The icon name will be read from the first line of the file /tmp/dialog-wicon. The file is also watched for changes, allowing you to later change the window icon. As the dialog is running, in another terminal run:
        echo "gtk-save" > /tmp/dialog-wicon
and the dialog window's icon will change to reflect the new value. In commands, the value of a window-icon (%windowicon1) is the icon name (ICON). Also note that even if no --window-icon element has been added to the dialog, you can later use the set command to set 'windowicon' (no numeric suffix). See also: --window-size --label Usage: `--label LABEL|@FILE` The --label element adds a GTK label widget to the dialog, which is used to display one or more lines of text, such as a message for the user or a label for an input box. For example:
        spacefm -g --label "The process is complete."
--label also accepts a file instead of a string. For example:
        echo "The process is complete." > /tmp/dialog-label
        spacefm -g --label @/tmp/dialog-label
The label's text will be read from the file /tmp/dialog-label (which may contain multiple lines). The file is also watched for changes, allowing you to later change the label's text. As the dialog is running, in another terminal run:
        echo "Another processs is complete." > /tmp/dialog-label
and the text in the dialog window will change to reflect the new value in the file. As with most elements, you can add multiple --label elements to a dialog. Some escape sequences are unescaped when LABEL is read:
\n | newline
\t | tab
\" | "
\\ | \
For example, to create a label with two lines:
        spacefm -g --label "This is line 1.\nThis is line 2."
Note that you can also set a label to multiple lines by specifying a @FILE which contains multiple lines, in which case \n is not needed (but may be used in files too). Labels can also include Pango markup text, which can be used to italicize, bold, and otherwise stylize portions of text. The --label element (only) recognizes the prefix character tilde (~) to indicate that your text is Pango markup. For example:
        spacefm -g --label "~This is plain.  <b>This is bold.</b>"
Like most elements, --label also accepts a --font option to change the font and font size of the text:
        spacefm -g --label --font "Times New Roman 16" "The process is complete."
Note that the --font option must come directly after the --label element. In general it is best to use the default font unless your script is only intended for your own use. In commands, the value of a label (eg %label1) is the text of the label. --button Usage: `--button LABEL[:ICON]|STOCK|@FILE [COMMAND...]` The --button element adds a button to the dialog. All buttons are packed horizontally at the bottom of the dialog, in the order in which they are added (to add a button in the upper part of the dialog, use a --free-button instead). Most dialogs should include at least an "OK" button. The easiest way to add a complete button is to use a STOCK name, which may be any one of: ok cancel close open yes no apply delete edit save stop (in lowercase) For example, to add a stock OK button:
        spacefm -g --button ok
The button will include the stock gtk-ok icon on it (taken from your icon theme), and an "OK" label. If you don't want to use a stock button, you can include a custom button label instead:
        spacefm -g --button _Update
The underscore (_), which is optional, indicates that 'U' is to be shown as the shortcut key for this button (Alt-U). Also note that a button label may contain multiple lines if desired. You can also add an icon to your button using a colon:
        spacefm -g --button _Update:gtk-apply
--button also accepts a file instead of a string. For example:
        echo "_Update:gtk-apply" > /tmp/dialog-button
        spacefm -g --button @/tmp/dialog-button
The button's label and icon will be read from the first line of the file /tmp/dialog-button. The file is also watched for changes, allowing you to later change the button's appearance. As the dialog is running, in another terminal run:
        echo "close" > /tmp/dialog-button
and the button in the dialog window will change to reflect the new value in the file. When the user presses a button, the dialog window will close if no COMMAND has been associated with the button. The output will include several variables to allow your script to determine what button was pressed. For example:
        dialog_pressed='button1'
        dialog_pressed_index='0'
        dialog_pressed_label='_Update:gtk-apply'
The first, "$dialog_pressed", contains the name of the button which was pressed to close the window, in this case "button1" (the first button added). "$dialog_pressed_index" contains the index of the button. Buttons are indexed left to right, starting from 0, so the first button you add has index 0, the second index 1, etc. Finally, "$dialog_pressed_label" contains the "LABEL[:ICON]" used to create the button. Thus your script can evaluate what button was pressed and take an action, as shown in the example script below:
        #!/bin/bash
        # This script shows a Yes/No dialog
        # Use QUOTED eval to read variables output by SpaceFM Dialog:
        eval "`spacefm -g --label "Are you sure?" --button yes --button no`"
        if [[ "$dialog_pressed" == "button1" ]]; then
            echo "User pressed Yes - take some action"
        else
            echo "User did NOT press Yes - abort"
        fi
Note: If the window is closed by the user pressing the X in the top-right corner, or by pressing Alt-F4, "$dialog_pressed" will be empty (no button was pressed) and "$dialog_pressed_index" will be -2. If a command is added to a button, then the dialog will not necessarily close when the button is pressed. Instead, the COMMAND(s) will be run. The value of a button (eg %v, %button1, etc) is the "LABEL[:ICON]" used to create the button. The following example creates a dialog with a label and a button. When the button is pressed, the label is set to the current date.
        spacefm -g --label \
    	       --button 'Get Date' set label1 '%(date)'
--free-button Usage: `--free-button LABEL[:ICON]|STOCK|@FILE [COMMAND...]` A --free-button element is similar to a --button, except that it is packed into the top area of the dialog like any other widget, instead of being placed in the horizontal row of buttons at the bottom. Like a --button, if the user presses a --free-button that has no COMMAND, the dialog window will be closed. The value of "$dialog_pressed_index" will always be -1 for a --free-button. --input Usage: `--input [--select START[:END]] [TEXT|@FILE [COMMAND...]]` An --input element adds a GTK entry widget to the dialog, which allows the user to enter text in a single-line box. This can be as simple as:
       spacefm -g --input
If you would like the box to already have default text in it when the dialog is first shown, add your text on the command line:
       spacefm -g --input "Some default text"
--input also accepts a file instead of a string. For example:
        echo "Some default text" > /tmp/dialog-input
        spacefm -g --input @/tmp/dialog-input
The input's default text will be read from the first line of the file. The file is also watched for changes, allowing you to later change the input's contents. As the dialog is running, in another terminal run:
        echo "Some other text" > /tmp/dialog-input
and the text in the input box will change to reflect the value in the file. Also, when the dialog is closed, the text in the input will be saved to the file. This method can be used to have the dialog remember the last text entered. The next time the dialog is run, assuming the file hasn't been deleted, the input will show the text from the previous dialog. A portion of the text may be selected when the dialog first opens using the --select option. By default, all of the text is selected. If you only want to select a portion, use a command like:
       spacefm -g --input --select 3:6 "Some default text"
Note that the --select option must come directly after the --input element. The first number (START) is the first character to select, and the second number (:END), if included, is the last. So "--select 3:6" will select characters 3 thru 6. Note that counting starts from zero: the first chracter has index 0, the second 1, etc. If END is negative or omitted, text will be selected from START through the end of the text. --input also accepts a --font option to change the font and font size of the text:
        spacefm -g --input --font "Times New Roman 16" "Some default text"
When the user presses Enter in an input box, one of several things may happen. If no COMMAND is associated with the input, then the right-most button at the bottom of the dialog will be automatically pressed. If the dialog has no buttons, nothing will happen. Or, if a command is added to the input, the COMMAND(s) will be run and no button will be automatically pressed. The value of an input (eg %v, %input1, etc) is the text in the box when the command is run. In SpaceFM Dialog's output, the value of an input can be read from, for example, "$dialog_input1". The following example creates a dialog with an input and a label. When Enter is pressed in the input box, the text of the input is copied to the label.
        spacefm -g --label "Enter some text and press Enter:" \
                   --input "" set label2 %v \
    	       --label \
    	       --button close
--input-large Usage: `--input-large [--select START[:END]] [TEXT|@FILE [COMMAND...]]` An --input-large element works identically to an --input, except that the text box is larger. It still contains a single line of text, but the text may be wrapped to several display lines. Such boxes are useful for editing long lines, such as a file path. --password Usage: `--password [TEXT|@FILE [COMMAND...]]` A --password element, used to enter a password, is similar to an --input, except that the text is hidden. Also, the options --select and --font have no effect on a --password element. --viewer Usage: `--viewer [--scroll] FILE|PIPE` A --viewer element adds a read-only multi-line text box to the dialog, and may be used to view the contents of a file or the data written to a pipe. By writing text to a temporary file, a viewer can also be used to show the user larger amounts of text which won't fit in a --label. A vertical scroll bar will automatically appear when the text exceeds the size of the box. To view the static or changing contents of a regular file:
        spacefm -g --viewer /etc/fstab
Anytime the contents of the file changes, the viewer will be updated. If you always want the viewer to scroll to the end of the file (except when the user pulls the scroll handle up), include the --scroll option:
        spacefm -g --viewer --scroll /etc/fstab
A --viewer may also be used to monitor data written to a pipe. This can be used to show the user changing information. For example:
        # First, create a pipe:
        mkfifo /tmp/dialog-pipe
        # Next, monitor the pipe:
        spacefm -g --viewer /tmp/dialog-pipe
When you write text to the pipe, it will be added to the viewer box. For example, while the dialog is running, in another terminal run:
        echo "some text to a pipe" > /tmp/dialog-pipe
Or:
        # Press Ctrl-C to cancel:
        while (( 1 )); do date > /tmp/dialog-pipe; sleep 1; done
In commands, the value of a viewer (eg %viewer1) is the path of the file being viewed. To change the file being viewed, use set (eg 'set viewer1 /etc/mtab'). The following example creates a dialog with a file chooser and a viewer. When the user double-clicks a text file in the chooser, the file's contents are displayed.
        spacefm -g --label "Double-click a file to view:" \
                   --chooser --filter text/plain . set viewer1 %v \
                   --viewer \
    	       --button close
--editor Usage: `--editor [FILE [SAVEFILE]]` Similar to a --viewer, an --editor element adds a multi-line text box to the dialog. Unlike a viewer, the user is able to edit the text in the box. To create an empty editor:
        spacefm -g --editor
Or, to load a text file into the editor:
        spacefm -g --editor /etc/fstab
When the dialog is closed, the contents of the editor are lost unless a SAVEFILE is also specified:
        spacefm -g --editor /etc/fstab /tmp/fstab-edited
When the above dialog is closed, the contents of the editor will be automatically saved to /tmp/fstab-edited. Your script can then use this file to replace the original if the user pressed the appropriate button, etc. Note: It is possible to set FILE and SAVEFILE to the same path, in which case the original file will automatically be overwritten when the dialog is closed, regardless of what button is pressed! In commands, the value of an editor (eg %editor1) is the path of the file last loaded. To load a file into the editor, use set (eg 'set editor1 /etc/mtab'). Also note that the contents of the editor are also saved to SAVEFILE whenever the internal command source is run. The following example creates a dialog with a file chooser and an editor. When the user double-clicks a text file in the chooser, the file's contents are displayed in the editor. If the user clicks the Save button, the editor's contents are saved to a temporary file (they are also saved when the dialog closes).
        spacefm -g --label "Double-click a file to edit a copy:" \
                   --chooser --filter text/plain . set editor1 %v \
                   --editor "" /tmp/dialog-copy \
    	       --label \
    	       --button save source /dev/null -- \
    	                     set label2 "Copy saved to /tmp/dialog-copy" \
    	       --button close
--check Usage: `--check LABEL [VALUE|@FILE [COMMAND...]]` A --check element adds a checkbox and associated label to the dialog, allowing the user to check or uncheck the option. The value of the checkbox can be read from a variable when the dialog closes, or it can be used by internal commands while the dialog is running. For example:
        spacefm -g --check "Option One"
By default, the checkbox will not have a check in it. To set a default value for the checkbox, specify "false" or "0" (unchecked), or "true" or "1" (checked). For example:
        spacefm -g --check "Option One" 1
--check also accepts a file instead of a string for the VALUE (but not for the LABEL). For example:
        echo 1 > /tmp/dialog-check
        spacefm -g --check "Option One" @/tmp/dialog-check
The checkbox's default value will be read from the first line of the file. The file is also watched for changes, allowing you to later change the state of the checkbox. As the dialog is running, in another terminal run:
        echo 0 > /tmp/dialog-check
and the checkbox state will change to reflect the value in the file. Also, when the dialog is closed, the state of the checkbox will be saved to the file. This method can be used to have the dialog remember the state. The next time the dialog is run, assuming the file hasn't been deleted, the checkbox will have the same state as when the previous dialog was closed. If a command is included, the COMMAND(s) will be run whenever the checkbox changes state, either due to the user clicking it, its @FILE value changing, or its value being set with an internal command. (The command is NOT run when the state is set to a default VALUE during dialog creation.) In commands, the value of a --check element (eg %check1) will equal 1 or 0, reflecting whether the box is checked or not. If internal command set is used on a --check and the value is not "0", "false", "1", or "true", the check's LABEL is set to the value (eg "set check1 "A new option label"), instead of the state being changed. In SpaceFM Dialog's output, the value of a check can be read from, for example, "$dialog_check1". The following example creates a dialog with a check and a label. If the checkbox is checked, the label is shown, otherwise it is hidden.
        spacefm -g --check "Show text" 1 show label1 %v \
                   --label "Some text"
The check's value in the above command works as a reversal in the show command - if %v is "0" then label1 is hidden, otherwise it is shown. --radio Usage: `--radio LABEL [VALUE|@FILE [COMMAND...]]` A --radio element is similar to a --check, adding a radio button and associated label to the dialog, allowing the user to select or unselect the option. However, only one of a set of radio buttons may be selected at a given time - selecting one will unselect the others in the set. To add a --radio element:
        spacefm -g --radio "Apples"
By default, the first --radio element of a set will be selected. To select another --radio element, include a default VALUE, specifying "false" or "0" (unselected), or "true" or "1" (selected). For example:
        spacefm -g --radio "Apples" 1
Remember that only one --radio can be selected, so the last --radio element you add with a 1 VALUE will be selected. Consecutive --radio elements are part of the same set, until a visible non-radio element is added. For example, these elements will be part of a set:
        spacefm -g --radio "Apples"    \
    	       --radio "Oranges" 1 \
    	       --radio "Pears"
In the above example, Oranges will be selected by default. As with --check elements, a @FILE may be substituted for VALUE, causing SpaceFM Dialog to read the value from the first line of the file. The state will be updated if the file is changed. The value will also be written to the file when the dialog closes. To have a dialog remember the selection of a radio set, you must specify a different file for each element. For example:
        spacefm -g --radio "Apples"  @/tmp/dialog-radio1 \
    	       --radio "Oranges" @/tmp/dialog-radio2 \
    	       --radio "Pears"	 @/tmp/dialog-radio3
The files do not need to be created (they will be created automatically), unless you want to select an option other than the first. If you run the above command multiple times, you will note that your selection is remembered from the previously closed dialog. If a command is included, the COMMAND(s) will be run whenever the radio button is selected (but not when it is unselected), either due to the user clicking it, its @FILE value changing, or its value being set with an internal command. (The command is NOT run when the state is set to a default VALUE during dialog creation.) In commands, the value of a --radio element (eg %radio1) will equal 1 or 0. If internal command set is used on a --radio and the value is not "0", "false", "1", or "true", the radio's LABEL is set to the value (eg "set radio1 "A new option label"), instead of the state being changed. In SpaceFM Dialog's output, the value of each --radio in a set can be read from, for example, "$dialog_radio1", "$dialog_radio2", etc. --icon Usage: `--icon ICON|@FILE [COMMAND...]` An --icon element packs a dialog-sized icon into the dialog. ICON specifies an icon name (not a path - to use a path use --image instead). The icon is selected using your current icon theme. For example:
        spacefm -g --icon gtk-open
--icon also accepts a file instead of a string. For example:
        echo "gtk-open" > /tmp/dialog-icon
        spacefm -g --icon @/tmp/dialog-icon
In this case, the icon name is read from the first line of the file /tmp/dialog-icon. This file is also watched, so when its contents change, the icon will change. As the dialog is running, in another terminal run:
        echo "gtk-close" > /tmp/dialog-icon
and the icon will change to reflect the value in the file. If a command is included, the COMMAND(s) will be run whenever the icon is clicked. For example:
        spacefm -g --icon gtk-open echo '# %n clicked %v'
When you run the above command and click the icon in the dialog, a message will be written to the terminal showing what mouse button was pressed and the location of the click. Both values are in the element's value (%v). Note that the location is relative to the upper-left corner of the event box holding the icon, not necessarily the corner of the icon itself (pack the icon into a compact --vbox for the latter). In commands, the value of an --icon element (eg %icon1) when referenced from another element will equal the icon name, while the current --icon element's value (%v) will equal the mouse button and click location. If internal command set is used on an --icon, the icon name is changed. --image Usage: `--image FILE|@FILE [COMMAND...]` An --image element packs an image into the dialog. If FILE isn't found or can't be loaded, the resulting image will display a 'broken image' icon. If the file contains an animation, the image will contain an animation. Not all image formats are supported. For example:
        spacefm -g --image ~/example-image.jpg
--image also accepts a file instead of a string. For example:
        echo "~/example-image.jpg" > /tmp/dialog-image
        spacefm -g --image @/tmp/dialog-image
In this case, the image FILE path is read from the first line of the file /tmp/dialog-image. This file is also watched, so when its contents change, the image will change. As the dialog is running, in another terminal run:
        echo "~/another-image.jpg" > /tmp/dialog-image
and the image will change to reflect the value in the file. Images are not resized. They are displayed at their full size, so only small images can be comfortably packed into a dialog. [Resizing options may be added soon - check this manual for updates.] If a command is included, the COMMAND(s) will be run whenever the image is clicked. For example:
        spacefm -g --image ~/example-image.jpg echo '# %n clicked %v'
When you run the above command and click the image in the dialog, a message will be written to the terminal showing what mouse button was pressed and the location of the click. Both values are in the element's value (%v). Note that the location is relative to the upper-left corner of the event box holding the image, not necessarily the corner of the image itself (pack the image into a compact --vbox for the latter). In commands, the value of an --image element (eg %image1) when referenced from another element will equal the image FILE path, while the current --image element's value (%v) will equal the mouse button and click location. If internal command set is used on an --image, the image path is changed. --progress Usage: `--progress [VALUE|pulse|@FILE]` A --progress element adds a progress bar to the dialog. For example:
        spacefm -g --progress
By default, the progress bar will pulse automatically. You can also specify an initial VALUE (0-100 or 'pulse'). To update the progress bar, it is most convenient to specify @FILE so the progress bar's value is read from FILE. For example:
        spacefm -g --progress @/tmp/dialog-progress
The file is watched for changes. To later update the value of the progress bar:
        echo 50 > /tmp/dialog-progress
Or, the progress bar will advance one pulse step each time you run:
        echo pulse > /tmp/dialog-progress
In commands, the value of a --progress element can be set using the internal set command (eg 'set progress1 35' or 'set progress1 pulse'). --hsep Usage: `--hsep` An --hsep element adds a horizontal line separator to the dialog. The line will extend the full width of whatever box the widget is packed into. --vsep Usage: `--vsep` A --vsep element adds a vertical line separator to the dialog. The line will extend to the full height of whatever box the widget is packed into. --timeout Usage: `--timeout [DELAY|@FILE]` A --timeout element adds a Pause button to the dialog, which causes the dialog window to close automatically after DELAY seconds, unless the Pause button has been pressed. In commands, the timeout value can be changed while the dialog is running with 'set timeout1 VALUE'. In SpaceFM Dialog's output, if the window closes due to the timeout, "$dialog_pressed" will equal "timeout1", and "$dialog_pressed_index" will equal -3. (The timeout button is not indexed with the other buttons.)
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Introduction Invocation Simple Elements List Elements Non-Visible Elements Commands Internal Commands Program Files | List Elements --drop Usage: `--drop {TEXT... --}|@FILE [DEFAULT|+N|@FILE [COMMAND...]]` A --drop element adds a drop-down list to the dialog, allowing the user to select a single option or item in the list. The contents of the list can be passed to SpaceFM Dialog as arguments on the command line or as a file. To pass the list on the command line:
        spacefm -g --drop "Item One" "Item Two" "Item Three" --
Especially if there are any arguments following the list, be sure to end the list with a '--' argument as shown above. By default, the list will have no item selected. To select a default item, add it to the command line after '--':
        spacefm -g --drop "Item One" "Item Two" "Item Three" -- "Item Two"
Or, pass the index of the default item with a plus sign (+) (indexing starts counting from zero):
        spacefm -g --drop "Item One" "Item Two" "Item Three" -- +1
To instead read the list from the lines of a text file:
        # First, create a text file containing multiple lines of text:
        echo -e "Item One\nItem Two\nItem Three" > /tmp/dialog-drop
        # Tell spacefm to load the drop list from a file:
        spacefm -g --drop @/tmp/dialog-drop
To specify a default item, add the default item value or index number. For example:
        spacefm -g --drop @/tmp/dialog-drop +1
The file /tmp/dialog-drop in the above example will be watched. When its contents change, the list contents will be updated to reflect the new list in the file. The default value, as an item value or a +N index, may also be read from the contents of a file:
        echo "Item Two" > /tmp/dialog-dropdef
        spacefm -g --drop @/tmp/dialog-drop @/tmp/dialog-dropdef
The file /tmp/dialog-dropdef in the above example will NOT be watched - changing its contents while the dialog is running will have no effect. However, when the dialog closes, the currently selected item in the list will be written to the file. This will cause the dialog to remember the selected value between sessions. If you run the above spacefm command multiple times, you will note that your selection is remembered from the previously closed dialog. If a command is included, the COMMAND(s) will be run whenever the list selection changes. (The command is NOT run when the default item is set during dialog creation.) To include a COMMAND, be sure to include a DEFAULT value on the command line, or "" for no default. In commands, the value of a --drop element (eg %drop1) will equal the currently selected item in the list. If internal command set is used on a --drop element, the command will set a new file to read the list from. Or, if the set value is not a file, will select an item in the list. The internal select command can also be used to select an item in the list. In SpaceFM Dialog's output, the selected item of a --drop element can be read from, for example, "$dialog_drop1", and its index from "$dialog_drop1_index". (An index of -1 indicates no item is selected.) --combo Usage: `--combo {TEXT... --}|@FILE [DEFAULT|+N|@FILE [COMMAND...]]` A --combo element is similar to a --drop element, except that it adds a text entry box, so the user can either select an item from the list, or enter custom text. The list is created the same way as a --drop list, either with arguments on the command line, or reading the list from a file. However, the DEFAULT value will be set in the text entry box even if it isn't in the list. When the user presses Enter in the text entry box, one of several things may happen. If no COMMAND is associated with the input, then the right-most button at the bottom of the dialog will be automatically pressed. If the dialog has no buttons, nothing will happen. Or, if a command is included, the COMMAND(s) will be run when the user presses Enter in the text entry box, and no button will be automatically pressed. To include a COMMAND, be sure to include a DEFAULT value on the command line, or "" for no default. In commands, the value of a --combo element (eg %combo1) will equal the text in the entry box. If internal command set is used on a --combo element, the command will set a new file to read the list from. Or, if the set value is not a file, will set the text in the entry box. The internal select command can also be used to set the text in the box, and the unselect command will clear the text. In SpaceFM Dialog's output, the entry box text of a --combo element can be read from, for example, "$dialog_combo1", and its index from "$dialog_combo1_index". The index will be set only if the user selects an item from the list, otherwise it will be -1 (even if the text in the entry box equals an item in the list). --list Usage: `--list {[^HEAD[:TYPE]] [--colwidth=W] TEXT... --}|@FILE [COMMAND...]]` A --list element adds a list box to the dialog, which includes a scroll bar when the list is long, and allows the user to select a single item or no item in the list. The list is created similarly to a --drop or --combo list, either with arguments on the command line, or reading the list from a file. However, no default item may be selected on the command line, and several additional, optional components may be added. To create a simple list:
        spacefm -g --list "Item One" "Item Two" "Item Three" --
Or, in a script, you can create an array and populate the list from the array. For example:
        #!/bin/bash
        # This script creates a list from an array

        alist=( "Item One" "Item Two" "Item Three" )
        eval "`spacefm -g --list "${alist[@]}" -- --button ok`"
        if (( dialog_list1_index != -1 )); then
            echo "Item selected: $dialog_list1"
            echo "Index selected: $dialog_list1_index = ${alist[dialog_list1_index]}"
        else
            echo "No item selected."
        fi
The above method has the advantage that the list indices match your array indices. Or, create a text file and read the list from it:
        # First, create a text file containing multiple lines of text:
        echo -e "Item One\nItem Two\nItem Three" > /tmp/dialog-list
        # Tell spacefm to load the list from a file:
        spacefm -g --list @/tmp/dialog-list
The file /tmp/dialog-list in the above example will be watched. When its contents change, the list contents will be updated to reflect the new list in the file. Lists can also contain multiple columns. Column headers are used to both set the column header label, and to define when a new column begins. A column header is an argument that begins with a caret (^). For example:
        spacefm -g --list ^Letter A B C ^Number 1 2 3 --
The above command will create a list with three rows and two columns, where "Letter" and "Number" are column headers. By adding column headers, the list also becomes sortable - the user can click on a column header to sort by that column (and click again for a descending vs. ascending sort). You can also set a column width if desired. Include a --colwidth=WIDTH option anywhere after the start of a column. (Columns have a minimum width of 50.) For example:
        spacefm -g --list ^Letter A B C ^Number --colwidth=200 1 2 3 --
Usually it's easier to create a multi-column list using a file. For example, create a text file with these contents:
    ^Letter
    A
    B
    C
    ^Number
    --colwidth=200
    1
    2
    3
Save the above text to a file named '/tmp/dialog-list'. Note that the --colwidth option must be placed on a line by itself in a file. Then load the file:
    	 spacefm -g --list @/tmp/dialog-list
It's also possible to set a data type for a column. Data types include 'string' (the default type if none is specified), 'int' (integer), 'double' (a double-precision floating point number), and 'progress' (a progress bar with values ranging 0-100). Different data types will be displayed and sorted differently. To define a data type for a column, include it in the column header after a colon. For example, edit the '/tmp/dialog-list' so it contains this list with three columns:
    ^Job
    A
    B
    C
    ^Number:int
    1
    2
    3
    ^Complete:progress
    35
    75
    90
In the above example, the "Job" column is type 'string', the "Number" column contains integers, and the "Complete" column will show progress bars. Once again, show the list:
    	 spacefm -g --list @/tmp/dialog-list
Note: If you want a column header to end with a colon (eg "Number:"), and you want to define a data type, use two colons (eg "Number::int"). If a command is included, the COMMAND(s) will be run when the user double-clicks an item in the list. If no COMMAND is included, double-clicking an item in the list will automatically press the right-most dialog button, if present. In commands, the value of a --list element (eg %list1) will equal the currently selected item (first column data, or hidden column - see below). If internal command set is used on a --list element, the command will set a new file to read the list from. The internal select command will select an item in the list, and the unselect command will unselect any selection. In SpaceFM Dialog's output, the selected item can be read from, for example, "$dialog_list1", and its index from "$dialog_list1_index" (-1 if nothing is selected). It's also possible to set a hidden data column to be used for return values. Rather than returning the first column data of the selected item, the hidden column data will be returned. To set a hidden column, name the first column header "HIDE" (uppercase) (with optional data type :TYPE). For example:
    ^HIDE
    return1
    return2
    return3
    ^Job
    A
    B
    C
    ^Number:int
    1
    2
    3
    ^Complete:progress
    35
    75
    90
The above list still has only three visible columns. The values in the "HIDE" column will be returned in the dialog's output, and in commands. For example, save the above list as '/tmp/dialog-list' and run:
    	 spacefm -g --list @/tmp/dialog-list echo '# %n = %v'
When you double-click an item in the list, the return value will be printed to the terminal (eg "# list1 = return2"). --mlist Usage: `--mlist {[^HEAD[:TYPE]] [--colwidth=W] TEXT... --}|@FILE [COMMAND...]]` An --mlist element behaves like a --list except that multiple items may be selected. (To select more than one item, hold down Ctrl and click, or hold down Ctrl and press arrows keys and Space to select.) In SpaceFM Dialog's output, the --mlist element variable (eg "$dialog_mlist1") is set to an array containing all selected items, and the index variable (eg $dialog_mlist1_index) is set to an array containing the indices of all selected items. For example:
    #!/bin/bash
    # This script creates an mlist from an array

    alist=( Aaa Bbb Ccc Ddd Eee Fff Ggg Hhh )
    eval "`spacefm -g --mlist "${alist[@]}" -- --button ok`"
    if [[ "${dialog_mlist1[0]}" != "" ]]; then
        echo "Selected items:"
        for item in "${dialog_mlist1[@]}"; do
    	echo "    $item"
        done
    else
        echo "No item selected."
    fi
In commands, the --mlist element's value (eg %v, %mlist1) is set to a list of quoted values (eg 'Aaa' 'Bcc' 'Ccc') which can be passed to an executable's command line. --chooser Usage: `--chooser [CHOOSER-OPTIONS] [DIR|FILE|@FILE [COMMAND...]]` Chooser Options: `[--save] [--dir] [--multi] [--filter F[:F...]]` A --chooser element adds a GTK file chooser to the dialog, which includes a file list, recent places list, and other widgets as a group, allowing the user to select or enter the name of a file or directory. Filters can be added to control what types of files are displayed. To allow the user to select a file which already exists:
         spacefm -g --chooser
If no path is specified, the chooser will open in "Recently Used". You can add a directory to the command line to make the chooser open in a default directory, or add a file path to select a file by default. For example:
         spacefm -g --chooser /etc/fstab
The default file or directory can also be read from a file. For example:
        echo "/etc/fstab" > /tmp/dialog-chooser
        spacefm -g --chooser @/tmp/dialog-chooser
In the above example, the file '/tmp/dialog-chooser' will be watched. When its contents change, the chooser will change directory and/or select a file to reflect the new value on the first line of the file. When the dialog closes, the current directory of the chooser will be written to the file. Thus the next time the dialog opens, it will open to the same directory. To allow the user to select multiple files, add the --multi option (all options must precede any arguments):
         spacefm -g --chooser --multi /etc
To allow the user to select a directory which already exists:
         spacefm -g --chooser --dir
To allow the user to select multiple directories:
         spacefm -g --chooser --dir --multi
To allow the user to select an existing file, or enter a filename that doesn't exist (to save a file, for example):
         spacefm -g --chooser --save
To allow the user to select an existing directory, or enter a directory name that doesn't exist (to create a directory, for example):
         spacefm -g --chooser --dir --save
Note that it is up to your script to determine if a file already exists before overwriting it, or to prompt the user for overwrite confirmation. Filters can be added to control what types of files are displayed. The F value in a filter can be a MIME type (eg "text/plain" or "video/*") or a filename pattern (eg *.txt). For example, to allow the user to choose only files with MIME type "text/plain":
         spacefm -g --chooser --filter text/plain
Or to allow the user to select only files ending in ".avi":
         spacefm -g --chooser --filter '*.avi'
Multiple filters can be added. The user will be able to select the desired filter from a drop-down list in the chooser. For example:
         spacefm -g --chooser --filter '*.avi' --filter video/x-matroska
A single filter can include multiple types or patterns separated by a colon. For example:
         spacefm -g --chooser --filter '*.avi:*.mpg:video/*'
More than one --chooser element can be added to a dialog. If a command is included, the COMMAND(s) will be run when the user double-clicks a file in the list. In commands, the value of a --chooser element (eg %v, %chooser1) will equal the currently selected file or files. If internal command set is used on a chooser, the command will change directory (and/or select a file). The select and unselect commands can be used to select and unselect files. In SpaceFM Dialog's output, the selected file(s) can be read from, for example, "$dialog_chooser1", and the current directory from "$dialog_chooser1_dir". Note that in some cases, such as when the chooser is in "Recently Used", "$dialog_chooser1_dir" will be null. Also, if the --multi option is used, "$dialog_chooser1" will be an array containing the selected paths.
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Introduction Invocation Simple Elements List Elements Non-Visible Elements Commands Internal Commands Program Files | Non-Visible Elements The following elements control how the dialog appears or behaves, and how other elements are packed into the dialog, but don't add a visible widget to the dialog: --prefix Usage: `--prefix NAME|@FILE` --prefix is a non-visible element which sets the base variable name that SpaceFM Dialog will use when writing output. By default, the base name is "dialog" (eg "$dialog_pressed"). In some cases you may want to use another name, especially if your script uses multiple dialogs. For example:
        spacefm -g --prefix var
In this case, the output will use variables such as "$var_pressed" instead. As with many elements, --prefix also accepts a file instead of a string, and will read the value from the first line of the file. For example:
        echo "var" > /tmp/dialog-prefix
        spacefm -g --prefix @/tmp/dialog-prefix
The "at" sign (@) indicates that a file path is being specified, and that SpaceFM Dialog should read the value from the first line of the file /tmp/dialog-prefix. The file is not watched or modified, but its value is not read until output is produced. --window-size Usage: `--window-size "WIDTHxHEIGHT [PAD]"|@FILE` The --window-size element sets a minimum WIDTH and/or HEIGHT for the dialog window. This element is used to make the window larger by default. If WIDTH or HEIGHT is negative, that dimension's minimum remains unchanged. For example, to make the minimum window size 800x600:
        spacefm -g --window-size 800x600
Note that depending on the other elements added, the window may grow larger than the minimum size specified. Also, window managers are capable of overriding the default size request. Or, to only set a minimum width of 800, leaving the height at the default:
        spacefm -g --window-size 800x-1
A padding amount can also be included.. This sets the amount of empty space around widgets (0-20 is a reasonable range of values for PAD, 4 is the default). For example:
        spacefm -g --window-size "800x600 10"
IMPORTANT: The --window-size element must come before other elements on the command line for the padding value to have an effect. The minimum window size and padding can also be read from a file:
        spacefm -g --window-size @/tmp/dialog-wsize
When the file is changed, the window will be resized to the specified size. As the dialog is running, in another terminal run:
        echo 500x500 > /tmp/dialog-wsize
and the window will be resized. (Note that the padding will not change once the dialog is running.) Also, when the dialog closes, the window size (and padding if specified) are written to the file. Thus when the dialog is next run, it will be at least whatever size the user last resized the window to. In commands, you can resize the window by using the internal set command on 'windowsize' (eg 'set windowsize 800x600'), even if you have not added a --window-size element. In SpaceFM Dialog's output, you can always read the window's last size (and padding if specified) from "$dialog_windowsize" (no numeric suffix), even if you have not added a --window-size element. To get the current size while the window is running, use the source command. See also: --title and --window-icon --hbox Usage: `--hbox [--compact] [PAD|@FILE]` The --hbox and --vbox elements allow to you create more sophisticated-looking dialogs. Instead of all elements being stacked vertically in the dialog, one after another, boxes also allow you to arrange elements horizontally in rows. You can also pack boxes within boxes. For example, a vertical box of small elements might be packed into a horizontal box of other elements. Boxes are invisible containers that hold elements - you can't actually see the box itself, only its affect on the elements within it. They come in two varieties: a vbox (vertical box) arranges its child elements in a vertical stack, while an hbox (horizontal box) arranges its child elements in a row. When you add an element to a dialog, it is packed into the current box of the dialog. The current box refers to whatever box was last added to the dialog. Or, if no boxes have been added, the current box is the default vbox of the dialog. Thus if you add no box elements, all elements are arranged vertically in a dialog. An --hbox element packs a new hbox into the current box. The hbox then becomes the new current box. Any widgets you add after the --hbox element will be packed into it, and thus arranged in a row. For example:
        spacefm -g --hbox \
                   --free-button "Button1" \
                   --free-button "Button2" \
                   --free-button "Button3"
In the above command, the initial --hbox element is packed into the default vbox of the dialog. Then, the buttons are packed into the hbox, and are thus arranged in a row. When you are done adding elements to the hbox, you can close the box if you have other elements to add. When the box is closed, the current box becomes the previous box, in this case the default vbox of the dialog again. So any elements added after the box closure will again be stacked vertically in the dialog. For example:
        spacefm -g --hbox \
    	       --free-button "Button1" \
    	       --free-button "Button2" \
    	       --free-button "Button3" \
    	       --close-box \
                   --free-button "Button4" \
                   --free-button "Button5"
You will notice that if you resize the above window, the row of buttons expand vertically. For some elements (like a --list or a --viewer) this is desirable, since the elements expand to fill the window. For other elements, such as buttons, you don't normally want this expansion. By default, an hbox will expand vertically consuming available window space, giving the extra space to its children, who in turn expand. If you don't want the hbox to consume extra vertical space in the window, include the --compact option:
        spacefm -g --hbox --compact \
    	       --free-button "Button1" \
    	       --free-button "Button2" \
    	       --free-button "Button3" \
    	       --close-box \
                   --free-button "Button4" \
                   --free-button "Button5"
The --compact option tells the box not to expand in the other dimension. For an hbox, --compact will affect the vertical dimension (height), and for a vbox, --compact will affect the horizontal dimension (width). With --compact, the box will not consume extra window space beyond what its children require as a minimum, so the children will in turn not expand. The extra space in the window will be divided among other boxes (if they can expand), or will remain empty (as in the above example). Also, whether children expand in the same dimension (horizontally in an hbox or vertically in a vbox) depends on the type of elements in the box. The box itself will expand in the same dimension, but its children may not (as seen in the above example). Note: A box with no children in it will take no space - it is effectively hidden. Finally, a PAD value may also be added to an hbox, which adds padding (empty space) between the children. For example:
        spacefm -g --hbox 30 \
    	       --free-button "Button1" \
    	       --free-button "Button2" \
    	       --free-button "Button3"
If an --hbox is hidden, all of its children become invisible. --vbox Usage: `--vbox [--compact] [PAD|@FILE]` For a general discussion of boxes, see --hbox. A --vbox element works similarly to an --hbox, except that the child elements in the box are stacked vertically rather than horizontally. The default box in a dialog is a vbox, so elements are added in a vertical stack. Adding a --vbox element to the dialog's default vbox will have no apparent effect. Thus these two commands create the same dialog:
        spacefm -g --free-button "Button1" \
                   --free-button "Button2" \
                   --free-button "Button3"

        # Produces the same dialog as:

        spacefm -g --vbox \
                   --free-button "Button1" \
                   --free-button "Button2" \
                   --free-button "Button3"
To see the effects of a vbox, we need to pack it into an hbox containing other elements:
        spacefm -g --hbox \
                   --list AAA BBB CCC \
    	       --vbox \
    	       --check "Option Alpha" \
    	       --check "Option Beta" \
    	       --check "Option Gamma"
In the above example, an hbox is first packed in the dialog. This hbox contains two elements: a list and a vbox. Since its an hbox, those elements are arranged side-by-side, in a row - the list and the vbox will be next to each other. Finally, three check options are packed into the vbox. Since its a vbox, they are stacked vertically. If we wanted to add another element below all of that, in the original default vbox of the dialog, we would first need to close the boxes we added:
        spacefm -g --hbox \
                   --list AAA BBB CCC \
    	       --vbox \
    	       --check "Option Alpha" \
    	       --check "Option Beta" \
    	       --check "Option Gamma" \
    	       --close-box \
    	       --close-box \
    	       --drop item
A --close-box always closes the current box. In the above example, the first --close-box closes the vbox, and the second closes the hbox. (You cannot close the default vbox of the dialog, so an additional --close-box would be ignored.) As with an --hbox, a --compact option can be added to a --vbox to prevent it from expanding in the other dimension - horizontally. In our example this will compact the check options to the right side of the window, giving the list more horizontal space in the window:
        spacefm -g --hbox \
                   --list AAA BBB CCC \
    	       --vbox --compact \
    	       --check "Option Alpha" \
    	       --check "Option Beta" \
    	       --check "Option Gamma" \
    	       --close-box \
    	       --close-box \
    	       --drop item
Finally, as with an --hbox, a PAD value may be added to a --vbox to add empty space between its children:
        spacefm -g --hbox \
                   --list AAA BBB CCC \
    	       --vbox --compact 30 \
    	       --check "Option Alpha" \
    	       --check "Option Beta" \
    	       --check "Option Gamma" \
    	       --close-box \
    	       --close-box \
    	       --drop item
If a --vbox is hidden, all of its children become invisible. --close-box Usage: `--close-box` A --close-box element closes the current box of the dialog, as demonstrated in --hbox and --vbox. Elements after the --close-box will be added to the previous current box of the dialog. --keypress Usage: `--keypress KEYCODE MODIFIER COMMAND...` A --keypress element associates a key combination with a COMMAND while the dialog is running. Pressing the key combination will run the COMMAND(s), which as always may be internal, external, or a mixture of both. For example, to associate Ctrl+K with a command that prints a value to the terminal and updates a label:
        spacefm -g --label "Press Ctrl+K" \
                   --keypress 0x6b 0x4 echo '# %n %v' -- \
                                       set label1 "You pressed Ctrl+K"
In the above example, "0x6b" is the KEYCODE for the 'k' key, and "0x4" is the MODIFIER for Ctrl. When Ctrl+K is pressed, "# keypress1 0x6b 0x4" is written to the terminal. Keycodes and modifiers may be obtained using SpaceFM's Design Mode Key setting. Right-click on a menu item in SpaceFM and select Key. Press the desired key combination to see the keycode and modifier, then click Cancel. Multiple --keypress elements can be added to a dialog. In commands, the value of a --keypress element (eg %v, %keypress1) will equal the keycode and modifier. --command Usage: `--command FILE|PIPE [COMMAND...]` A --command element causes SpaceFM Dialog to monitor a regular file or a pipe for internal commands. For example, to monitor a regular file:
        spacefm -g --command /tmp/dialog-cmd
No command will be read from the file during dialog creation even if it contains one. When you write a command to the first line of the file while the dialog is running, it will be run as an internal command. In another terminal run:
        echo "set title A Window Title" > /tmp/dialog-cmd
Note that separate quotes should NOT be used around the third argument, even if it contains spaces. Or, to monitor a pipe:
        # First create the pipe:
        mkfifo /tmp/dialog-cmdpipe
        spacefm -g --command /tmp/dialog-cmdpipe
Then in another terminal, write text to the pipe:
        echo "set windowsize 500x500" > /tmp/dialog-cmdpipe
Multiple --command elements may be added if desired. This can help prevent race conditions when submitting commands rapidly, etc. You can use a command file or pipe from your script to get data from a running dialog by submitting a 'source' command (eg 'source /tmp/dialog-source'). Then in your script, parse the source file:
        source /tmp/dialog-source
Note that you may or may not need to add a small delay (eg sleep 0.1) for the source file to be written in response to your command, before reading the file. COMMAND, if included, specifies initialization commands for the dialog. COMMAND(s) associated with a --command element are run only once, just after the dialog is created. These are used to initialize the dialog, such as disabling or hiding some elements. (FILE|PIPE may be "" if you want to include an initialization COMMAND but don't want to watch a command file.)
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Introduction Invocation Simple Elements List Elements Non-Visible Elements Commands Internal Commands Program Files | Commands One or more commands may be associated with a SpaceFM Dialog element if the element accepts COMMAND on its command line. Most commands are run when the element is activated - a user clicks a button, double-clicks an item in a list, presses Enter in a text box, etc. Commands may be internal (used to internally change aspects of the dialog while it's running) or external (an executable to be run). SpaceFM Dialog recognizes its internal commands by name; any commands which are not internal are run as external. The COMMAND argument may represent a single command followed by its command arguments, or multiple commands each with arguments. A "--" argument is used to separate multiple commands. Both internal and external may be mixed. For example:
        spacefm -g --label "Press Button" \
    	       --button "Button" set label1 "Button was pressed" -- \
    				 echo '# Button %n was pressed'
The --button element above includes two commands with arguments, separated by a "--" argument. The first command (set label1 "Button was pressed") is an internal command. The second command (echo '# Button was pressed') is an external command. When the button is pressed, both commands are run - the first changes the label internally, and the second runs the echo executable to write text to the terminal. Although commands are run in the order presented, note that external commands are run asynchronously. SpaceFM Dialog runs and forgets the command, and doesn't wait for it to finish. This means later commands may run before an earlier command has finished. (To run an external command synchronously, run it inside an internal noop command's %(command) substitution.) Substitution Variables Before SpaceFM Dialog runs a command, internal or external, it replaces some variables anywhere in the command or arguments with current values. The following substitution variables are replaced:
%n | Name of the current element
%v | Value of the current element
%NAME | Value of element named NAME (eg: %input1)
%(command) | stdout from an external command
%% | %
%n In the above button example, %n would equal "button1", the name of the element. Elements are named automatically as they are added. These are the same names used in the variables in SpaceFM Dialog's output. %v The value of the current element, or "my value" from the element's perspective, is substituted for %v. This is equivalent to referring to the element's own value by name (eg %button1 in the above example). %NAME %NAME is used to get the value of any other element in the dialog. For example, the text in the first --input element of a dialog is always "%input1". If element NAME does not exist, %NAME has value "". Note that the value read from an element may differ from the value used to set an element. For example, using set on a --list element sets the file path for the list. But "%list1" will contain the selected items in the list. %(command) %(command) executes an external command line synchronously, and is substituted with the stdout output of the command. For example:
        spacefm -g --label \
    	       --button 'Get Date' set label1 '%(date +%%D)'
Generally, you will need to quote the '%(command)' argument as shown above when running spacefm, or the shell will misinterpret the parentheses. The command line "date +%D" (remember %% is changed to %) is run, and the output is substituted. IMPORTANT: Because the %(command) command line is run synchronously, SpaceFM Dialog will wait until it finishes. While it's waiting, the dialog GUI and other functions will be suspended. If the command takes an appreciable amount of time, you will notice the GUI lags or hangs. Thus fast commands work best. Also, if you want to run an external command synchronously, you can run it inside an internal command with %(command). The noop command, which does nothing except evaluate arguments, is good for this, eg noop '%(command)'. In this case, the stdout output will be discarded, but the command will be run synchronously. Note that a small bash script can be run directly inside a %(command) substitution by using bash -c. For example:
    spacefm -g --check Option 0                                                      \
    		   set label1 '%( bash -c "echo -n Option is\ ;                  \
    				  (( %v )) && echo checked || echo unchecked" )' \
    	   --label "Option is unchecked"
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Introduction Invocation Simple Elements List Elements Non-Visible Elements Commands Internal Commands Program Files | Internal Commands Internal commands are run internally by the dialog to change elements while the dialog is running. They can be included as part of an element's COMMAND arguments, or submitted from an external process using a --command element. The following internal commands may be used: noop Usage: noop The noop (no operation) command simply does nothing, but its arguments, if any, are evaluated. One use for a noop command is to prevent a dialog closing when a button or other element is activated. Buttons will automatically close the dialog when pressed if no COMMAND is included. Other elements, such as lists and inputs, will press the right-most dialog button to close the dialog when they are activated if no COMMAND is included. To prevent this behavior, you can set COMMAND to noop. For example:
        spacefm -g --button ok noop
Another use for the noop command is to evaluate arguments. This can be used to run an external command synchronously as detailed in %(command) substitution. For example:
        spacefm -g --button ok noop '%(myscript)' -- close
In the above example, when the OK button is pressed, first 'myscript' will be run synchronously (an imaginary script which does something critical before closure). SpaceFM Dialog will wait for it to finish. Then and only then, the 'close' command will close the dialog. close Usage: close The close command simply closes the dialog window, as if the user clicked the X in the top-right corner or used Alt+F4. $dialog_pressed_index will equal -2. press Usage: press BUTTON-NAME The press command presses a button in the dialog, just as if the user clicked it. It is passed the name of the button to press. For example:
        spacefm -g --icon gtk-ok press button1 \
    	       --button ok
When the above command is run and the icon is clicked, the OK button will be pressed, closing the dialog ($dialog_pressed = button1). Other elements, if no COMMAND is included, will press the right-most dialog button when activated. The press command can also be used to press another button instead. set Usage: set NAME VALUE The set command sets a new VALUE for the element named NAME. What effect this has will depend on the type of element. For most elements, set will change what they are displaying or their state. For details on how a particular element handles set, see the element's documentation. For example:
        spacefm -g --label "Press Button" \
    	       --button "Button" set label1 "Button was pressed"
select Usage: select NAME [VALUE] The select command is used to select an item in any kind of list, or if no VALUE is supplied, all items are selected if possible. select can also be used to select a filename in a --chooser, or set the text in a --combo. For example:
        spacefm -g --list AAA BBB CCC \
                   --button "Select CCC" select list1 CCC \
    	       --button ok
unselect Usage: unselect NAME [VALUE] The unselect command is used to unselect an item in any kind of list, or if no VALUE is supplied, all items are unselected. unselect can also be used to unselect a filename in a --chooser, or clear the text in a --combo. For example:
        spacefm -g --mlist AAA BBB CCC \
    	       --command "" select mlist1 \
                   --button "Unselect All" unselect mlist1 \
    	       --button ok
focus Usage: focus NAME [REVERSE] The focus command gives the element NAME the focus in the dialog. The focused element receives keyboard input. REVERSE, if supplied and equal to "", "0", or "false", causes the focus command to do nothing. This can be used with the value from a --check element, for example, to make the focus command conditional. hide Usage: hide NAME [REVERSE] The hide command makes the element named NAME invisible. A hidden element takes no space, so other elements may shift position or size in response to an element being hidden. hide can be used to hide or show dialog elements conditionally in a certain mode or use of the dialog. REVERSE, if supplied and equal to "", "0", or "false", causes the hide command to have the reversed effect (it becomes a show command). This can be used with the value from a --check element, for example, to make the hide command conditional. show Usage: show NAME [REVERSE] The show command makes the element named NAME visible. All elements are visible by default, so a show command only has an effect if an element was previously hidden with hide (or a reversed show). REVERSE, if supplied and equal to "", "0", or "false", causes the show command to have the reversed effect (it becomes a hide command). This can be used with the value from a --check element, for example, to make the show command conditional. For example:
        spacefm -g --check "Show text" 1 show label1 %v \
                   --label "Some text"
disable Usage: disable NAME [REVERSE] The disable command sets the element named NAME insensitive (grayed). A disabled element cannot be clicked or used by the user. REVERSE, if supplied and equal to "", "0", or "false", causes the disable command to have the reversed effect (it becomes an enable command). This can be used with the value from a --check element, for example, to make the disable command conditional. enable Usage: enable NAME [REVERSE] The enable command sets the element named NAME sensitive (not grayed). All elements are enabled by default, so an enable command only has an effect if an element was previously disabled with disable (or a reversed enable). REVERSE, if supplied and equal to "", "0", or "false", causes the enable command to have the reversed effect (it becomes a disable command). This can be used with the value from a --check element, for example, to make the enable command conditional. For example (you can't click OK unless you select a function):
        spacefm -g --label "Select a function and click OK:"           \
                   --drop "Function A" "Function B" "Function C" -- "" \
    	              enable button1 %v                            \
    	       --button ok                                         \
    	       --command "" disable button1
In the above example, the drop's %v equals "", reversing the enable, unless a function is selected. The --command element is used to initialize the dialog by disabling button1 when the dialog is first created. source Usage: source FILE When a dialog closes, it saves some @FILE values, and it writes output to stdout containing variables for use in a script. The source command is used to trigger this output to be written to a file while the dialog is still running. The file can then be used as a source file in bash or a similar script, providing the script with the current state of the dialog elements. The source command also saves @FILEs for some elements, such as --input, which are normally only saved when the dialog closes. It also saves the contents of an --editor element to SAVEFILE. If FILE is omitted or equals "", the output is written to stderr by the dialog process (useful for debuging). To run source with no output use 'source /dev/null'.
Program Files
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files /home /etc /tmp /usr | /home Your entire SpaceFM configuration, including settings and custom commands, is stored in the config directory: ~/.config/spacefm/ (unless you use `--config-dir` on the command line to specify another location). If the config directory doesn't exist, and /etc/xdg/spacefm/ does exist, the contents of /etc/xdg/spacefm/ will be copied to the new config directory on startup. Files in ~/.config/spacefm/ include: session Holds most user settings and customizations. This file is plain text so you can review its contents, but it should NOT be edited. SpaceFM saves the current session anytime you make a change to the configuration (at most once every 15 seconds or so). If SpaceFM can't find a session file at startup, it will use session-last or session-prior instead. If all session, session-last, and session-prior files are deleted, SpaceFM will be restored to factory default settings. session-last & session-prior These are the session files from your last and prior-to-last runs of SpaceFM. If you encounter a configuration problem or loss of settings when starting or using SpaceFM, be sure to make a backup copy of these files before running SpaceFM again. To revert to an older session, stop all instances of SpaceFM and rename the older session file 'session'. session.tmp For stability, when SpaceFM saves your session file, it first saves it as 'session.tmp'. If successful, it then renames it 'session', overwriting the old session file. Usually you won't find a session.tmp file because it is quickly written and renamed. bookmarks Contains your folder bookmarks. Currently, this file is in the same format as GTK's bookmarks (~/.gtk-bookmarks). To copy your GTK bookmarks into SpaceFM (replacing any SpaceFM bookmarks you have added) use:
        cp ~/.gtk-bookmarks ~/.config/spacefm/bookmarks
plugin-data/ Contains the data directories for custom commands and plugins, if any. If commands need to store persistent user data, this is where they store it. It is should generally be safe to remove files from this folder, but your commands may lose their settings. scripts/ Contains the command directories for custom commands you have added to SpaceFM's menus or toolbars, if any. Because SpaceFM is highly configurable, you may have much time and effort invested in your SpaceFM config folder, so it's a good idea to keep an up-to-date backup! scripts/default-script This file, if you create it, is used as your default command script rather than the automatically generated one. When you create a new custom command and set its type to Command|Script, ~/.config/spacefm/scripts/default-script will be copied to the command directory as exec.sh. ~/.local/share/applications/ This folder contains desktop files which define applications available on your system, and the defaults.list file specifies default applications for given MIME types. SpaceFM checks this directory to determine what application to use to open files, will modify the mimeapps.list file when you change the default application for a MIME type, and may create custom desktop files when needed. The system-wide /usr/share/applications/ folder is used similarly, though settings in the local folder take precedence. You can copy desktop files from /usr/share/applications/ to ~/.local/share/applications/ in order to modify them on a per-user basis, and also add your own custom desktop files.
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files /home /etc /tmp /usr | /etc The first time you click OK in the View|Preferences dialog, and anytime you change your terminal or root editor in that dialog, SpaceFM will ask to save some settings as root to /etc/spacefm/ Although optional, this is recommended to help secure your use of SpaceFM's perform-as-root commands. Also, anytime you run a perform-as-root command, such as to format a partition, these settings may be updated. Without these settings saved as root, your system security may be more easily compromised. The following files may be found in /etc/spacefm: USERNAME-as-root For each USERNAME who runs SpaceFM, you may find this file which contains the user's prefered root editor, terminal, and other perform-as-root settings. This file should NOT be edited. spacefm.conf This file is designed to be edited by the administrative user. Currently, the only setting in this file is tmp_dir, which specifies what temporary directory SpaceFM should use. If unset, it defaults to /tmp. If this file is not present and you want to specify a different temporary directory (/dev/shm in this example), create the file /etc/spacefm.conf as root and add this line: tmp_dir=/dev/shm Be sure to use a temporary directory which is root-owned/protected and user-writable (see /tmp's permissions). /dev/shm is usually a good choice too. The temporary directory may not contain spaces or other special characters - keep it simple. Because SpaceFM may run commands as other users (including root), the temporary directory must be accessible to all users. /etc/xdg/spacefm/ This folder, if it exists, is used to create a default configuration for new SpaceFM users. If no config directory exists for the current user when spacefm is first started, the contents of /etc/xdg/spacefm/ will be copied to the new config directory (be sure to kill all running instances of spacefm before testing this). This allows a distro or system admin to set a default SpaceFM configuration for new users. To do so, simply configure SpaceFM as you want it to appear and work by default, then copy the contents of the config directory to /etc/xdg/spacefm/ as root. Be sure to set all files in /etc/xdg/spacefm/ to be readable by all users:
        chmod -R ugo+rX /etc/xdg/spacefm
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files /home /etc /tmp /usr | /tmp SpaceFM writes small files to the temporary directory (which can be changed in spacefm.conf). These include: .spacefm-socketDISPLAY-USERNAME A socket which SpaceFM uses to open additional windows and other functions, removing the need to start additional instances of the entire program. DISPLAY is the current display of the user (eg :0) and USERNAME the username. Generally, this file will be removed when the current instance of SpaceFM exits. spacefm.tmp/ This folder, shared by all users, contains temporary files used for running a command as another user, including root. Once a root command is run, this folder will be owned by root. spacefm-USERNAME-RANDOM.tmp/ This folder contains temporary files used by USERNAME running SpaceFM. It is owned by the user and will be deleted on exit. Other users can access this folder, but usually not the files within it, unless a command is being run as another user. spacefm*.tmp/ID-tmp.sh A temporary bash script used to execute a command run in SpaceFM, which will be deleted when the command completes. ID will be an eight digit hexadecimal number. This script creates a suitable bash environment for the command being run, including import of file manager variables for use in commands. While the command is running, you can import the file manager variables from this script into another script using:
        $fm_import
        # OR
        source ID-tmp.sh
spacefm*.tmp/ID/ A folder used to store temporary data, usually plugin data which has been copied via Plugins|Copy, where ID is an eight digit hexadecimal number.
Contents Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Dialog Program Files /home /etc /tmp /usr | /usr The parent folder (--prefix=) for files listed below may be '/usr' or '/usr/local' depending on how you installed SpaceFM. With the exception of plugins installed by the user, all files stored in /usr are created only when SpaceFM is installed, and are not changed by SpaceFM. These include: bin/spacefm The SpaceFM executable file. bin/spacefm-auth This script is used internally by spacefm to authenticate temporary scripts run as another user (using /usr/bin/sha256sum). This file should not be modified or run directly. This file was added to SpaceFM version 0.7.2 to simplify the command line for su programs, which often handle special characters poorly and have inconsistent command line usage. If spacefm-auth or /usr/bin/sha256sum are missing, SpaceFM will operate in a less secure mode. share/doc/spacefm/spacefm-manual-en.html A local copy of this manual you're reading (also may be in share/spacefm/, or in your distro's standard html docs folder). This copy is accessed when using context-sensitive help within SpaceFM. If available, a version for your language will automatically be used. To use a different manual location within SpaceFM, set your preference in Help|Options|Manual Location. share/spacefm/plugins/ A folder containing plugins installed by the user. Plugin files should NOT be copied directly to this folder. Instead, use Plugins|Install to install them, or Design Mode to remove them. However, if you make a package for your plugin, you can instruct the package manager to install the correct uncompressed files to this folder, allowing users to install your plugin via their package manager. share/spacefm/included/ Plugins included in a standard SpaceFM installation. This folder should NOT be modified. share/spacefm/ui/ A folder containing glade files for some of SpaceFM's dialogs. share/pixmaps/spacefm.png & share/pixmaps/spacefm-root.png The window icons for the normal user mode and root mode of SpaceFM. Use of these icons can be avoided by changing View|Window Icon. Note: If configure option --disable-pixmaps is used during installation, these icons will be located in share/icons/hicolor/48x48/apps/, share/icons/hicolor/128x128/apps/, and share/icons/Faenza/apps/48/ instead. share/pixmaps/spacefm-[48|128]-[cube|pyramid|folder]-[blue|green|red].png Alternate SpaceFM icons. share/locale/*/LC_MESSAGES/spacefm.mo Language files used by SpaceFM, where '*' is a locale. share/applications/ This folder contains desktop files which define applications available on your system, and the defaults.list file specifies default applications for given MIME types. SpaceFM checks both ~/.local/share/applications/ and /usr/share/applications/ to determine what application to use to open files. Settings in the local folder take precedence. You can copy desktop files from /usr/share/applications/ to ~/.local/share/applications/ in order to modify them on a per-user basis, and also add your own custom desktop files. share/applications/spacefm.desktop A desktop file which opens a SpaceFM window. share/applications/spacefm-find.desktop A desktop file which open a SpaceFM File Search window. share/applications/spacefm-folder-handler.desktop A desktop file which uses SpaceFM to open a folder share/mime/packages/spacefm-mime.xml Additional MIME types provided by libmimetype, adding globs for some missing but frequently seen file types.

This document is under construction and incomplete.

Copyright (C) 2012

DISCLAIMER: While the authors, copyright holders, and maintainers of this software endeavour to keep all content up to date and valuable, we make no representations or warranties of any kind, express or implied, about the completeness, accuracy, reliability, suitability or availability with respect to the software or the information, communications, products, services, or related graphics for any purpose. Any reliance you place on such content is therefore strictly AT YOUR OWN RISK.

Updated 2012-10-25 (SpaceFM version 0.8.2)