TIP: Within the zzzFM program, you can right-click on a menu item and select Help to access context-specific 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 sections within this manual.

-=-
While reading this (long) User Manual, you can press Ctrl+F key to search within the page.

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.

The zzzFM source code and localization (.po) files are available for inspection / download here:
https://gitlab.com/skidoo/zzzfm/

zzzFM is derived from the SpaceFM v1.0.6 codebase (which had been unmaintained since 2018)
https://github.com/IgnorantGuru/spacefm
SpaceFM had been previously distributed as "PCManFM-Mod", derived from the PCManFM file manager

license: GPL3+
see: /usr/share/common-licenses/LGPL-3     /usr/share/zzzfm/COPYING-LGPL     /usr/share/zzzfm/COPYING

zzzFM is a multi-panel tabbed file manager (and, optionally, a desktop manager) for Linux. It has a built-in VFS, a udev -based device manager, a customizable menu system, and bash shell integration.

Flexible ~~ its GUI can appear very simple or very complex depending on configuration

zzzFM's GUI aims to be simple and uncluttered, while still providing extensive capabilities for power users and flexibility in customizing window components, behavior, and appearance.
‣ Each window may contain up to four independently configured, interactive file browser panels *

‣ Each panel supports multiple folder directory tabs

‣ Optional side panes in each panel can show Devices, Bookmarks, and a Directory Tree

‣ How many panels you want displayed, how they are arranged and sized, what each panel contains, and what fonts and icons are used is largely up to you. zzzFM can be displayed as a window showing the contents of a single directory, or as a multi-panel, tabbed arrangement of detailed file lists, devices, bookmarks, and folder directory trees.

‣ Extensive file management features to move, copy, link, plus configurable drag-n-drop and unique clipboard functions

‣ Find-As-You-Type search to quickly locate a file with a case-sensitive/insensitive search of filenames - just type a few letters, or use a wildcard pattern *

‣ System management features to safely perform convenient commands as root: edit, copy, move, and delete files and folders directories as root, change permissions, and create links, or run a root instance

‣ In-program archive creation and extraction (or use an external app)

‣ File search - flexibly search system-wide for file names, sizes, content, etc. with no daemon required

‣ Extended Rename dialog enables not only renaming, but moving, copying, and creating links, with optional root priviledges, and enables creation of new files and folders directories from templates *

‣ Roomy dialogs for easy editing and viewing of long filenames, paths, and commands

‣ Extended Path Bar uses tab completion and enables entry of full bash commands with substitution *

‣ Powerfully manage how files are opened *

‣ Sort options enable a natural sort and a case sensitive sort. FoldersDirectories within the file list may be placed before or after files, or mixed with files, and hidden files may be placed before or after regular files.

‣ Custom date display format; binary or SI decimal file sizes and copy speeds

‣ Easily customize window titles and program icon

zzzFM's unique extensible GUI rivals the flexibility and capabilities of the Linux command line. Using zzzFM 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, and can be assigned to any keyboard shortcut *

‣ Add your own custom menu items and submenus to any position in most menus. Like word processor macros, custom menu items enable you to easily run commonly used programs or automate tasks using zzzFM's unique integration with the bash scripting language, with file manager data exported as ready-to-use bash variables *

‣ The Bookmarks menu and side pane can contain not only bookmarks, but submenus, custom commands to be run, and applications. *

‣ With the built-in zzzFM Dialog tool - a zenity-like tool but with much greater power - easily create, use, and control custom dialogs or mini-apps. *

‣ Make your custom commands respond to window events and manipulate the GUI directly using socket commands *.

‣ Monitor the stdout/stderr output of custom commands in a dialog, with error detection and popup control, or automatically run commands in a terminal or as an independent process. *

‣ Written entirely in C - super fast with low resource usage

‣ Independent of particular distributions and desktop environments

‣ Builds easily on almost all Linux systems

‣ Builds with any version of GTK+ ranging from 2.18 to 3.x

‣ Built-in virtual filesystem (VFS) code uses core C kernel functions for speed and reliability, with no dependence on gvfs, etc.

‣ Interfaces directly with udev (or eudev) for device support, with no dependency on udisks

‣ Built-in support for inotify-capable linux kernels (>=2.6.13); no dependencies on file alteration monitors (fam, gamin, gvfs).

‣ Rather than opening a popup dialog and making you wait while a copy or other task runs, zzzFM's Task Manager lists all the tasks running in the current window (including copy speed and other statistics), freeing you to continue working *

‣ Popup dialogs are shown when errors occur, or can be configured to be shown for all tasks *

‣ To optimize performance, zzzFM's task queue smartly pauses some tasks which involve devices already in use, or you can manually pause, queue, resume or stop any task *

‣ Includes extended overwrite, auto-rename, and error handling options *

‣ Single-click mounting and unmounting of devices *

‣ Optional automatic mounting and opening of devices on insert *

‣ Programmable event-based manager runs any commands or apps you specify on device or media insertion, mount, and removal *

‣ customizable root functions to format, backup and restore partitions and MBRs, check filesystems, and change volume labels *

‣ Custom format of display names for devices *, and hide or show any device *

‣ Built-in udev (or eudev) support - can be used with udevil, pmount, udisks, or your custom mount solution *

‣ When used without udisks, there is no need for policykit, consolekit, devicekit, gvfs, and other troublesome components susceptible to frequent breakage and misconfiguration

‣ Add custom Device and Protocol handlers, and mount options based on fstype or device *

Based on LXDE's former desktop manager, zzzFM can conveniently manage the icons and wallpaper on your desktop, and supports a transparent background. Works great with Openbox and other WMs, and can be extended with custom menu items. *

Run zzzFM in the background as a daemon to auto-mount and auto-open devices, and quickly open file browser windows on demand. *

Conveniently mount network URLs (nfs:// ftp:// smb:// ssh://) and ISO files using the highly configurable udevil (debian package name "udevil"). Or, configure a custom protocol handler to mount networks using any external tools you choose, plus create custom protocols of your own. * NOTE: Network share support in zzzFM is ad hoc by design. This means there few built-in functions pertaining to networks, and zzzFM does not make network connections itself. Network discovery and other functions are handled via your custom commands.

To see zzzFM's command line usage, run zzzfm --help

Usage:
  zzzfm [OPTION...] [DIR | FILE | URL | DEVICE]...

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

Application Options:
  -t, --new-tab                Open a new tab (default)
  -r, --reuse-tab              Open directory in current tab of last used window
  -n, --no-saved-tabs          Don't load saved tabs
  -w, --new-window             Open directory in new window
  -p, --panel=P                Open directories 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)
  -s, --socket-cmd             Send a socket command (See -s help)
  --profile=PROFILE            No function - for compatibility only
  --no-desktop                 No function - for compatibility only
  --version                    Show version information
  --display=DISPLAY            X display to use

Normally, your session file and other user files are saved in ~/.config/zzzfm/ To make zzzfm read and save your files in another folder directory (~/.config/zzzfm-alt in this example), stop ALL instances of zzzFM and run:

    # first stop all instances:
    killall zzzfm

    # then:
    zzzfm --config-dir ~/.config/zzzfm-alt

IMPORTANT: The config directory path must not contain spaces or other special characters. Also, if /etc/xdg/zzzfm/ exists, its contents will used to pre-populate the user's config directory (if such doesn't already exist) during first-run startup.

To open an initial zzzFM window, run 'zzzfm' with or without a specifying a folder directory :

    zzzfm

    # or to open a specific directory:
    zzzfm /home

    # or to open several directories, displayed as multiple tabs:
    zzzfm /home /usr/bin

    # or to not open saved tabs:
    zzzfm -n

To open an additional directory in a new tab of the last used zzzFM window on the current workspace:

    zzzfm /etc

To open a directory in the current tab of the last used zzzFM window on the current workspace:

    zzzfm -r /etc

To simply bring the zzzFM window to the top of other windows:

    zzzfm -r

To open a second window:

    zzzfm -w

    # or to open a specified directory in a second window:
    zzzfm -w /boot

    # or to open a second window without loading saved tabs:
    zzzfm -wn

To open a File Search window:

    zzzfm --find-files

zzzFM maintains a socket for each user/display combination, so that when you open multiple windows using the same user and display, all windows are run from a single instance of zzzFM. Unless a daemon or the desktop manager is running, zzzFM will exit when all windows are closed.

When a window is closed, the current directory tabs are saved to your session file if option File|Save Tabs is checked. The next time you run zzzFM, these directory tabs will be re-opened in addition to opening tabs for any directories you specify on the command line (unless you specify -n on the command line).

To specify a specific panel in which to open a directory:

    # open a directory in panel 2:
    zzzfm --panel=2 /usr/bin

To simply show and focus panel 2 in the last used window:

    zzzfm --panel=2

As a more advanced example, consider wanting to open multiple zzzFM windows, each containing different directory tabs in each panel, using a single command. For this, use a script like this to start zzzFM:

    #!/bin/bash

    # open new window with two tabs in panel 1
    zzzfm -wn --panel=1 /etc /usr &
    sleep 0.2
    # add two tabs to panel 2
    zzzfm -rn --panel=2 /bin /lib
    sleep 0.2
    # open second window with two tabs in panel 1
    zzzfm -wn --panel=1 /boot /media
    sleep 0.2
    # add two tabs to panel 2 of second window
    zzzfm -rn --panel=2 /sbin /var

If you specify a file (rather than a directory) on the command line, zzzFM will open the file using the default MIME application for this file type (File Handlers are not used), but will not open a zzzFM window:

    # open a file:
    zzzfm /etc/fstab

    zzzfm ftp://ftp.us.debian.org/debian/

    zzzfm /dev/sdd1

The GTK theme you're using may have a significant impact on zzzFM's performance, and a non-working theme may create dysfunctional behavior. Because multiple panels in zzzFM use many GUI elements, some themes cause zzzFM to run more slowly. For example, the Clearlooks GTK2 theme has been observed to be very slow with zzzFM, while the Raleigh theme is quite fast.

zzzFM may be built to use GTK v2 or v3.
To see if your installed copy of zzzFM is using GTK2 or GTK3 themes, run zzzfm --version

tip: If packagename is "zzzfm", your installed copy is intended for use with GTK2 themes. If the installed packagename is "zzzfm-gtk3", your copy will use GTK3 themes ~~ identical functionality / features, but the comparatively large GTK3 library files incur a higher RAM usage (aka "larger memory footprint").

GTK 2
When using GTK2, it is possible to use a specific theme just for zzzFM, overriding your default theme. For example, to use the Raleigh theme (if installed), launch zzzFM like this:

    GTK2_RC_FILES=/usr/share/themes/Raleigh/gtk-2.0/gtkrc zzzfm

or, if you prefer a compact layout, (install the "murrine-themes" debian package and) launch:

    GTK2_RC_FILES=/usr/share/themes/NOX/gtk-2.0 zzzfm

You can also test zzzFM's speed with no theme, which should be faster than any theme:

    GTK2_RC_FILES="" zzzfm

                Q. Hmm, no theme ~= uses less RAM?
                A. Not really (YMMV, but in my testing the memory [and speed] difference was negligible.)

To specify a GTK2 theme within a desktop file, copy zzzFM's desktop file to your home directory:

    mkdir -p ~/.local/share/applications
    cp /usr/share/applications/zzzfm.desktop ~/.local/share/applications/
    # OR
    cp /usr/local/share/applications/zzzfm.desktop ~/.local/share/applications/

Exec=env GTK2_RC_FILES=/usr/share/themes/Raleigh/gtk-2.0/gtkrc zzzfm

GTK 3
When using GTK3, theme choice becomes especially important because themes are often broken with every minor GTK3 release, and a theme not made specifically for your current version of GTK3 can cause memory leaks, GUI glitches, and other severe problems visible in zzzFM. To determine if your theme is the cause of problems, launch zzzFM from commandline (using a terminal emulator) to see any warnings, and also compare behavior with Adwaita (GNOME theme).

zzzFM includes a lightweight desktop manager to manage desktop icons and show wallpaper (or a transparent background). zzzFM's DM 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:

    zzzfm --desktop

You can also run zzzfm --desktop from your login script. For example, if you're using Openbox, add this line to ~/.config/openbox/autostart.sh:

    ( zzzfm --desktop ) &

While managing the desktop, zzzFM'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:

    zzzfm --set-wallpaper /home/user/wallpaper.jpg

To open the desktop preferences window from the command line run:

    zzzfm --desktop-pref

To stop management of the desktop prematurely (before logoff), send zzzfm a quit signal:

    killall zzzfm

If you want zzzFM 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 zzzFM:

    zzzfm -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 && zzzfm -d) &

One particular use for daemon mode is to make sure leftover directories in /media are removed. zzzFM can unmount removable devices on exit to prevent directories 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 zzzFM 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 zzzFM a quit signal:

    killall zzzfm

Frequently Asked Questions

Package: zzzfm                v---  (provides the zzzfm localization files)
Depends: ${misc:Depends}, zzzfm-common,  desktop-file-utils, shared-mime-info, e2fsprogs
Recommends: udisks2
Suggests: udevil, eject, lsof, wget, gksu, sshfs, dbus, fuseiso, curlftpfs, jmtpfs, gphotofs, ifuse

    What's the best way for Conky to play nicely with zzzFM?
    I'm using it with pseudo-transparency and it displays the "root" background, but unfortunately
    zzzFM's desktop must be a window above this and consequently on a refresh Conky seems to disappear completely.
    If I kill zzzFM, Conky reappears. I think I had this problem when I tried the Rox desktop too.

    You can use settings like the following to make conky an actual window
    (undecorated, and will not show up in the taskbar):
          own_window yes
          own_window_transparent yes
         #own_window_argb_visual false
         #own_window_argb_value 0
          own_window_type normal
          own_window_hints undecorated,below,sticky,skip_taskbar,skip_pager

    This will cause it the conky to cover up any desktop icons it overlaps,
    and may not work with all window managers. If you have two conkys that overlap each other
    you may need a method to control which window is on top of the other at all times.
    In Fluxbox this can be accomplished by specifying
          own_window_title
    within the ~/fluxbox/apps file
    (assign each conky a different window title to differentiate them)

zzzFM includes up to four file manager panels in each window. Each panel represents a complete file manager, including tabbed directory contents and optionally shown side panes, toolbars, path bar, and status bar. Each panel can be hidden or shown via the View menu, or via the Panel Bar located to the right of the main menu bar.

If shown, panels 1 and 2 are next to each other in the top half of the window, and panels 3 and 4 are in the bottom half. This enables horizontally arranged panels, vertically arranged panels, and combinations of both.

NOTE: zzzFM's main menu bar (File, View, etc.) is mostly used for program-wide settings and functions. Most adjustments for an individual panel's appearance can be made by right-clicking on the file list and selecting the View context menu (also available in the main View menu). This View menu will enable you to set which side panes and toolbars are visible in a panel, add and remove file list columns, set the list style and font, set the sort method, etc.

Panel Memory

The best way to use zzzFM's memory for panel configurations is to select the panels you want visible, then arrange each panel as you want it to appear. Hide or show side panes and adjust their sizes, choose file list columns and adjust their widths, choose which toolbars are visible, etc. Each time you select a different combination of panels, you may need to do some further configuration until zzzFM gets to know all the combinations you use and how you like them arranged.

How It Works

Many settings in each panel are specific to that panel. For example, a different font can be set for the file list or other panes in each panel. Also, each panel may have a different view style (Detailed, Compact, or Icons), different file list columns visible, different side panes visible, etc.

Some panel settings use a four-state memory, and these settings may be different depending on the panel's relationship to other panels in the window. The four states are:

• panel is shown by itself in the window
  
• panel has a horizonal neighboring panel
  
• panel has a vertical neighboring panel
  
• panel has both horizontal and vertical neighboring panels
  

The four-state memory of each panel enables zzzFM to remember how you configured each panel in combination with other panels. This makes it easier to show and hide panels on the fly without having to readjust columns, side panes, etc. zzzFM will remember the selected columns (visibility), column widths, side pane visibility and sizes, and toolbar visibility for each state of each panel.

For more advanced users, note that socket commands can be used to adjust panel configurations from a command or script. When set as event handlers, adjustments can be made automatically when GUI or other events occur, such as showing/hiding a panel or changing window size.

Maximized & Fullscreen

If you maximize the zzzFM window, any changes to column widths are not remembered (in any panel or in the task manager). This means that you can change column widths while maximized, and when you return to an unmaximized window state, your columns widths will revert to their original sizes.

However, if you exit zzzFM while the window is maximized, your column widths will be saved. When you restart zzzFM it will open maximized, and any changes to column widths thereafter will be remembered while maximized (unless you unmaximize and maximize again).

In fullscreen mode, neither changes to column widths nor to side pane heights are remembered. When you return to non-fullscreen mode, these will revert to their original sizes.

Focus Highlighting
zzzFM is designed so that for most purposes, it is not necessary to know which panel has the focus. By right-clicking in a panel, the context menu shown will be specific to that panel. (Window level commands and settings are available via the main menu bar.)

However, sometimes it is necessary to know which panel has focus, such as when using keyboard shortcuts on selected files, or using a custom command in the main menus. For this purpose, zzzFM provides an icon at the right of each panel's status bar. This icon will be enabled for the panel which has focus.

If you would like a more prominent reminder, it is possible to set custom highlight colors for the focused panel's status bar text and background. To set highlight colors, right-click on the status bar of the panel and select Highlight Text or Highlight Bar. Each panel may use different highlight colors, or the same.

zzzFM's Path Bar (location bar) is located in each panel above the file list in the panel's main toolbar. At its simplest, the Path Bar enables you to see path of the currently viewed directory, and you can enter a new path and press Enter to change to another directory.

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 directory path, zzzFM's Path Bar has additional methods and uses as detailed below.

Editing Keys
When the cursor is in the Path Bar, the following editing key combinations can be used:

Key Combo	Result
Shift+Backspace	Clear the entry
Ctrl+Backspace	Backspace to the previous separator
Ctrl+Left	Jump to previous separator
Ctrl+Right	Jump to next separator
Tab	Complete entry

When the Path Bar has focus, it will steal the following keypresses (even if they are set as key shortcuts): visible characters without a modifier key, Enter, Home, Shift+Home, End, Shift+End, Delete, Tab, Backspace, Left, Shift+Left, Right, Shift+Right.

Auto Seek
By default, the Path Bar will auto seek, which means that as you type in the Path Bar, the current directory will change automatically, and any partial filename typed will select the first matching directory or file found in the file list. You can turn off auto seek by right-clicking on the Path Bar and unchecking option Auto Seek. In this case, you will need to press the Enter key to change to the directory entered.

To locate files within the current directory, use Find-As_You-Type Search or Actions|Select By Pattern.

Completion
As you're entering a directory path in the Path Bar, 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). You can press Tab to complete the entry automatically ("/us" will be completed to "/usr/", or as much as possible if there are multiple matches). 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 enables you to Ctrl+Click on a portion of the path in the Path Bar to trim the path back. This will also immediately change to the new path. For example, if the path is currently /usr/share/applications and you Ctrl+Click on the name 'share', the path will change to /usr/share. This provides a convenient way to go up to a specific directory.

Middle-Click Auto Seek
A middle-click in the Path Bar will replace the contents of the Path Bar with the contents of the primary clipboard, and will seek to the location. The primary clipboard is set simply by selecting text in any application. For example, if you select the text "/etc/fstab" in your editor, then middle click in zzzFM's path bar, the directory will change to /etc and the 'fstab' file will be selected. If you don't want to replace the contents of the Path Bar, and merely want to insert the primary clipboard text (the usual behavior of middle-click), hold down a modifier key while you click, such as Ctrl or Shift.

File Path or Device
The path to a file may be entered or pasted in the Path Bar. When you press Enter, zzzFM will change to the directory containing the file and will select the file in the file list.

Also, a device file (eg /dev/sdd1) may be entered in the path bar. The device will be mounted if needed, and the mount point directory of the device will be opened.

Protocol URL
Any entry in the Path Bar which looks like a protocol, such as ftp://mirrors.kernel.org/, will be opened with the associated protocol handler. If a fileystem is mounted, zzzFM will usually open the mount point directory automatically. If the Devices List has option Settings|Show|Mounted Networks checked, the filesystem may be listed.

Regardless of the protocol, most of zzzFM's default protocol handlers accept URLs in the format:

    PROTOCOL://USERNAME:PASSWORD@HOST:PORT/SHARE

WARNING: Including a password in the URL is a very unsafe mode of use, as your password is included in the command line and may be written to temporary and/or system files by zzzFM or mount helpers. See documentation specific to the filesystem for other authentication methods offered, or enter your password when prompted.

Some parts of the above URL format may be omitted. Examples include:

    ftp://mirrors.kernel.org
    smb://user:pass@10.0.0.1:50/docs
    ssh://user@sys.domain
    mtp://

    NFSHOST:/SHARE
    //SAMBAHOST/SHARE

In addition, custom protocol handlers may be added which accept URLs in the above formats, or in any format you prefer.

URLs may also be opened via the main menu bar's File|Open URL item, which is equivalent to entering them in the Path Bar, or on the command line.

TIP: You can sometimes right-click on a mounted network in the Devices List and select Bookmark to bookmark the URL for future use. Or, right-click on the Path Bar containing a URL and select New Bookmark. Or, edit an existing bookmark to contain a URL target.

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 zzzFM 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

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

    +! 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

Command History
zzzFM also keeps a command history. As you enter a command, any commands previously entered will be shown in a popup. Use Up/Down Arrow keys to select a previous command and press Enter, or click it.

Select By Pattern
If a percent sign (%) prefix is entered in the Path Bar, zzzFM treats the rest of the text as a file selection pattern. This function is equivalent to right-clicking on the file list and selecting Actions|Select By Pattern. For example, enter in the Path Bar:

    % *.avi

See also: Find-As-You-Type Search.

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.

When the file list has focus (click on the file list), pressing an alphanumeric key will open the Find-As-You-Type search box in the lower right corner of the file list, enabling you to quickly jump to a file. Press down or up arrow, or scroll wheel up/down, to go to the next or previous matched filename.

In addition, Find-As-You-Type Search supports the following modes:

• Pattern Mode: If the search key contains at least one asterisk (*) or question mark (?), a glob substring search is used. (An asterisk is automatically added before and after your key before testing.) For pattern usage see IEEE Pattern Matching Notation.
  
  
• Non-Pattern Mode: If your key does not contain an asterisk (*) or question mark (?), a normal substring search is performed, with the following new special characters recognized:
  
  
  • If the search key begins with a caret (^), or the search key is less than three characters, the search will match names beginning with your key.
  • If the search key is longer than two characters and doesn't begin with a caret (^), a case insensitive substring search is conducted (this means if you type any part of a filename, the cursor will select the first filename which contains that string of characters.)
  • If your key ends with a dollar sign ($), the search will match names ending with your key.
  • You can use both a caret and dollar sign to constrain both. (Other regex characters and wildcards are not supported in this mode.)
  
  
• Anytime you use an uppercase letter anywhere in your search key, the search mode becomes case sensitive.
  
  
• Regardless of mode, you can press down or up arrow, or scroll wheel down/up, to go to the next or previous matched filename.
  
  

zzzFM's Rename Dialog, accessed by right-clicking on a file and selecting Rename, does much more than rename files. It can move, copy, or create a link to the selected file or directory. It can also copy the target of a selected link, or create a new link to the target. By checking As Root, the function will be performed as the root user.

The Option button enables you to add and remove fields from the dialog. The selected fields, which are extra-large for easy editing of long filenames, show different parts of the selected path, such as the name and extension, full filename, parent, or path. As you edit the file's path, you will be advised if the entered path already exists. If you use a path which doesn't exist, zzzFM will create the necessary parents automatically. The Confirm Create option determines if you will be prompted before parents are created.

The Browse button enables you to browse for a filename, parent, or path, and insert it into the dialog.

TIPS: To select all the text in an entry, click the entry's label (eg 'Filename:'), press the Alt key shortcut, or use Tab. To quickly copy an entry's text to the clipboard, double- or middle-click on the entry's label (eg 'Filename:'). Multiple files can be selected in the file browser to rename a batch of files.

The New File/Folder Dialog is opened by right-clicking on the file list and selecting New|File, Folder, or Link. This dialog works similarly to the Rename Dialog, enabling you to create files and directories in other paths, create as root, create relative links (eg a link to ../filename.txt), and create new files and directories using templates.

zzzFM looks in $XDG_TEMPLATES_DIR/, ~/Templates/, or ~/.templates/ to find template files. Templates are simply empty or partially filled files (of any type) used to create new files, so instead of an empty file you get a copy of the template file. You can place any files or links to files in your Templates directory. SubfoldersSubdirectories within the templates directory can also be used to create new directories pre-filled with a set of files, or to organize templates.

After you have finished entering the path for your new file or directory, you can press Create to create it, or the '& Open' button to create and open the file or directory in one step.

zzzFM's main Bookmarks menu works like most other menus - you can right-click in the menu to add custom menu items, and to cut, copy, and paste items to other menus. Custom menu items may be bookmarks which open destination directories, but they may, instead, run commands or applications. This means that items in zzzFM's bookmarks can run socket commands to open specified directory locations in specific panels, change view settings, run external programs, and perform other automated tasks.

Bookmarks Side Pane

Items added to the Bookmarks menu may be shown in the Bookmarks side pane of each panel. To show the Bookmarks pane, select Show Bookmarks from the main Bookmarks menu, or right-click on a file and select View|Bookmarks.

Right-click in the Bookmarks pane and enter the Settings submenu to adjust behavior. The Single Click option determines if a single- or double-click is required to open an item. New Tab, if checked, will open bookmarks in a new tab. Bookmark Icon and Submenu Icon are used to set the default icons used in the list, and individual item icons can also be configured via their Properties. The Font setting adjusts the font and font size used in the Bookmarks side pane.

Finally, the Follow Dir option will cause the Bookmarks pane to follow the current directory. If a bookmark matches the current directory, it will be highlighted. If the matching bookmark is in a submenu, the submenu will be opened.

Follow Dir is a per-panel setting. For example, you can turn it on in the Bookmarks pane of Panel 1, and turn it off in Panel 2. When Follow Dir is off, the bookmark selection will not change automatically.

Tips:

• If you don't want zzzFM to select a bookmark via Follow Dir, prefix the bookmark's target with a semicolon (;). Also note that zzzFM's bookmarks can target multiple directories, URLs, and devices. Only the first target is used by the Follow Dir function.
  
  
• To reorder items in the Bookmarks pane, drag them. Note that drag-n-drop in this pane currently only enables items to be reordered, not moved to other locations. To move an item to a submenu, or to another zzzFM menu or toolbar, you must use Cut and Paste.
  
  
• The Open item in the context menu of the Bookmarks pane (seen by right-clicking in the pane) will obey the reverse of the New Tab setting. For example, if New Tab is enabled, choosing Open will not open a new tab. Opening a bookmark by clicking on it with the middle mouse button also reverses New Tab behavior.
  
  
• The Open item and the Settings submenu of the context menu of the Bookmarks pane can have custom items added after them or within Settings using Design Mode. Click once on the Settings submenu to close it, then right-click on it for the design menu, or right-click on the Open item, or on one of the items within the Settings submenu.
  
  
• Selecting Copy on any item of type Bookmark (in any menu or in the side pane) will also copy the bookmark target to the text and primary clipboards (in addition to copying the menu item to the design clipboard for pasting into another menu or toolbar).

Adding A Bookmark

To add a new bookmark targeting the current directory, select New Bookmark from the Bookmarks menu (a key shortcut may also be assigned to this item - right-click on it to set one), or right-click in the Bookmarks pane or menu and select New|Bookmark (which will ask you to select a directory target).

To bookmark a single selected file or directory, or otherwise the current directory, right-click on the file list and select New|Bookmark.

To bookmark a mounted URL, in some cases you can right-click on the URL in the Devices List and select Bookmark. Or, a URL or file/dir path in the Path Bar may be bookmarked by right-clicking on the Path Bar and selecting New Bookmark.

To view or adjust the properties of a bookmark, right-click on it and select Properties.

Note: The Properties dialog of all custom menu items includes a Context tab which determines when and how menu items are displayed based on the file browser's current context. Note that Context settings do not affect display of bookmarks in the Bookmarks side pane, which always shows all bookmarks. The Context settings WILL affect how items are shown in the main Bookmarks menu.

zzzFM includes a programmable udev-based device manager which lists device volumes, enables you to mount and unmount devices, and detects changes, insertions, and removals. On events, zzzFM can auto-mount and auto-open devices, and run commands you specify. In addition, perform-as-root commands enable you to mount and unmount as root; change volume labels; and check, format, erase, backup, and restore partitions. Like most parts of zzzFM, the behavior and appearance of the device manager is customizable.

Whenever zzzFM 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.

zzzFM mounts and unmounts devices using customizable Device Handlers which can use udevil, pmount, the udisks command line tool (v1 or v2), or any program you specify. To troubleshoot behavior, you can run the same command lines in a terminal that zzzFM uses, or create your own custom handlers or menu items to manipulate devices.

NOTE: If you choose to use udisks with zzzFM, note that zzzFM 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 zzzFM. Installing udevil is the quickest way to solve such problems.

To have the device manager always running, responding to events even while no zzzFM windows are open, run zzzFM as a daemon or desktop manager.

When testing the device manager, it may be useful to run the initial instance of zzzFM in a terminal so that you can see additional diagnostic output as it's running. Just open a terminal window and run zzzfm.

Each panel or tab in zzzFM can display a Devices list to show devices and permit configuration of the underlying volume monitor. A Devices list is one interface to the volume monitor's information and actions. Even if multiple Devices lists are displayed or multiple zzzFM 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. To show or hide additional devices, use the Show submenu.

You can mount and open a device in the Devices list by simply left-clicking on it. The behavior of a left-click will vary depending on options New Tab and Single Click.

Right-click on a device to show the Devices context menu.

Middle-clicking on a device is equivalent to right-clicking on the device and selecting Remove / Eject. Thus to quickly remove a device, just middle-click on it.

Similar to the Devices List, zzzFM's main menu bar and the desktop menu include Devices menus which list currently shown devices. Click on a device to mount and open it, or right-click on a device for additional options. Right-clicking on a device in these menus or in the Devices List shows the context menu described below. As in the Devices List, you can also middle-click on a device in the menu to 'Remove / Eject'.

Like most menus in zzzFM, 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: (not all items may be shown)

Remove / Eject
The 'Remove / Eject' item is used to remove a device and eject media. When you click 'Remove / Eject', first a full sync is performed to ensure all data has been commited to all disks. 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 data loss. (If using 'Remove / Eject' from the Devices menu on the desktop, a popup dialog will show removal progress.) Note that if all other filesystems don't sync immediately, this may prolong the Remove command. In that case, you can use Unmount instead, which only does a filesystem-specific sync.

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 / Eject' 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 due to hardware caches. If the device has no activity indicator, it is best to wait 5 seconds before removing it.)

If you click 'Remove / Eject' 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 / Eject'. Thus to quickly remove a device, just middle-click on it.

NOTE: zzzFM does NOT disable or power-down usb ports or spin down disks when removing a device, it merely performs a sync to ensure data is written. Usually this is sufficient to prevent data loss. If powering down is required for your device, you must add a custom command to the Devices menu, or add the applicable command or option to the unmount handler.

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 / Eject - 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. The unmount command from the appropriate Device Handler will be run ~~ by default, udevil, pumount, or the udisks command line tool will be used. No general sync is performed (but a filesystem-specific sync is performed by umount). 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. Do not remove a device until the Task Manager shows this command has finished, or data may not be properly written, which can cause data loss. (If using 'Unmount' from the Devices menu on the desktop, a popup dialog will show removal progress.) (Even after the unmount has finished, it may take a second or two for the device to stop flashing due to hardware caches. If the device has no activity indicator, it is best to wait 5 seconds before removing it.) (skidoo sez: the previous statement was inherited from spaceFM docs. I would suggest waiting 20 seconds, or longer, if you are unsure of the device status.)

Sync
Sync merely runs a sync command to commit all data to all disks. 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.

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, zzzFM runs the mount command from the appropriate Device Handler for the selected device. By default, udevil, pmount, or the udisks command line tool will be used. The mount point will be determined automatically by the mount program or handler, usually an automatically created subdirectory in /media or /run/media/$USER. If it was automatically created, this subdirectory 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 generally be mounted using zzzFM'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 device handler. Open In 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. The mount command from the appropriate Device Handler will be run - by default, udevil, pumount, or the udisks command line tool will be used. The mount point will be determined automatically by the mount program or handler, usually an automatically created subdirectory 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 generally be mounted using zzzFM'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 device handler.

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 device handler.

Bookmark
The Bookmark item will only be shown if the selected device is a mounted network. This item enables you to create a bookmark which will automatically mount the network. Some mounted networks are not recognized. To create a URL bookmark manually, enter the URL in the Path Bar, right-click in the Path Bar, and select New Bookmark.

Note: Any custom menu items you add directly after the Bookmark menu item in the Devices menu will also only appear if the selected device is a mounted network, providing an automatic context.

Root
The Root submenu enables 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. zzzFM 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 enables 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 enables 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 Menus
As with most menus, it is also possible to add your own custom menu items and submenus to the Devices menu. This enables 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)

    echo "$fm_device_size"

The Root submenu enables you to perform actions on a device as root. When performing commands as root, zzzFM 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 enabling you to edit it. If zzzFM 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, zzzFM will use udevil (if udevil is installed on your system) to unmount as root, but you can change this to any unmount command, such as a udisks, pumount, or umount command. Only the substitution variable %v may be used in this command to insert the currently selected device file (eg /dev/sda2).

Mount
Mount works similarly to Unmount, except that the selected device is mounted as root. If you want any mount options added, you must specify them in the dialog.

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 zzzFM 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: zzzFM 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 enables 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 enable you to safely review how zzzFM conducts a format. Just be sure you know which device is the DVD or empty drive!

Backup|FSArchiver
The Backup submenu enables you to perform a backup of a selected device or MBR. There are several supported backup types.

2021 note by skidoo: This inherited documentation section was probably drafted 2015 or earlier.
The specific reference to FSArchiver remains to serve as an example here, not an endorsement.

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 enable 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.
•     ^~~~ in 2021, these statements may now be outdated / inaccurate ~~~v

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 enable 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
zzzFM 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 zzzFM, including an FSArchiver, Partimage, or MBR archive file. (If the file was not created by zzzFM 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 enable 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 zzzFM, 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 zzzFM 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 enable 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).

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.

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, zzzFM 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 Other
By default, the Devices list will show files mounted to loop devices, and other non-block devices, such as mounted fuse filesystems. For example, if you right-click on an ISO file and select Open|Mount ISO, the ISO file will be mounted 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 and non-block device filesystems listed, uncheck option Show|Mounted Other.

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, zzzFM 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 enables you to specify display exceptions for some devices. When deciding whether to show or hide a device in the Devices list, zzzFM 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 enables 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 enables 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:

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 enables 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 zzzFM'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 zzzFM startup.

TIP: For additional information on what the volume monitor is doing, try running zzzFM 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 zzzFM 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, zzzFM 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, zzzFM 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 enables 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|Mount Dirs
This dialog enables you to enter a single directory where zzzFM should automatically create mount point directories for fuse and similar filesystems (%a in handler commands). This directory must be user-writable (do NOT use /media); if it doesn't already exist, it will be created (including parents). For best results with all handlers, avoid spaces and other special characters. If left blank, ~/.cache/zzzfm/ (or $XDG_CACHE_HOME/zzzfm/) is used.

The following variables are recognized and will be replaced with their current value: $USER $UID $HOME $XDG_RUNTIME_DIR $XDG_CACHE_HOME

Note that some handlers or mount programs may not obey this setting. It will only be used by handlers which use %a in their mount or open commands.

Anytime a device, protocol or file handler uses %a to automatically create a mount point, the specified directory will be used as the parent. This applies to both manual and automatic mounts.

Note that empty subdirectories will be routinely and automatically removed from the specified directory.

Auto Mount|Open Tab
If option Open Tab is checked, when a device is auto-mounted by zzzFM, 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 zzzFM. It has no effect on devices mounted by other means, nor does it apply to devices mounted by user action within zzzFM.

Auto Mount|Unmount On Exit
If option Unmount On Exit is checked, any device which would normally be auto-mounted by zzzFM (based on auto-mount settings) will be unmounted when zzzFM exits. Exit occurs when the last zzzFM window is closed, unless a daemon or desktop manager daemon is running. Note that if zzzFM is killed with SIGKILL (such as when you logout of your X session), the automatic unmount will NOT occur. (To unmount all devices before or just after X logoff, consider running devmon --unmount-all (devmon is distributed with udevil).

When mounting a device, if there is no fstab entry for the device, your mount program may create a subdirectory for the device mount point in /media or /run/media/$USER. If you or zzzFM unmounts the device, this subdirectory will be removed. However, if you logoff without unmounting the device, the subdirectory may be left behind. In order to avoid these subdirectories accumulating in /media, zzzFM 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 subdirectories accumulating.

Auto Run|On Mount
Auto Run|On Mount opens a dialog which enables you to set a command line to be run when a removable drive or optical data disc is auto-mounted by zzzFM. 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:

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 zzzFM. It will not be run for devices mounted by other means, or for devices mounted by user action within zzzFM.

The command will not be run for devices which are auto-mounted at zzzFM's initial startup. Thus Auto Run affects devices you add after zzzFM is running.

For additional information on what the volume monitor is doing, try running zzzFM 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 enables 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 zzzFM's initial startup. Thus Auto Run|On Audio CD affects media you insert after zzzFM 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 enables 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 zzzFM, AND b) the device contains a video DVD.

The command will not be run for devices which are auto-mounted at zzzFM's initial startup, nor will it be run for devices mounted by other means, nor for devices mounted by user action within zzzFM.

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 enables you to set a command line to be run when any device is inserted. This enables 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

For greater control, an event handler may be set for event evt_device.

Auto Run|On Unmount
Auto Run|On Unmount opens a dialog which enables 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"

For greater control, an event handler may be set for event evt_device.

Auto Run|On Remove
Auto Run|On Remove opens a dialog which enables you to set a command line to be run when any device is removed. This enables 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.

For greater control, an event handler may be set for event evt_device.

Device Handlers
Opens the Device Handlers configuration dialog.

Protocol Handlers
Opens the Protocol Handlers configuration dialog.

Mount Options
Mount Options opens a dialog which enables you to set default mount options. These options may be used in Device Handlers via the substitution variable %o, and are used by the default mount command 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 only handlers which use the %o substitution variable will use options specified here. They will not apply to mounts performed by other handlers.

Note that some options, such as nosuid or noatime, may be added by your mount program even if you don't include them. For example, if using udevil, you may need to also change the default options in /etc/udevil/udevil.conf. Also, options specified in /etc/fstab may take precedence over options specified 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 appropriate Device Handler.

Change Detection
Change Detection opens a dialog which enables you to enter a comma- or space-separated list of filesystems which should NOT be monitored for changes to files. This setting only affects non-block devices (such as nfs or fuse), and is usually used to prevent zzzFM becoming unresponsive with network filesystems.

When zzzFM opens a directory in a tab, normally it will detect changes, for example if you edit or change the properties or sizes of files in the directory. Because zzzFM works directly with the kernel for file information, and because some network filesystems become temporarily unresponsive when busy, this can cause zzzFM to become temporarily unresponsive to mouse clicks, etc.

To prevent this, the device's filesystem can be listed in the Change Detection Blacklist. In this case, zzzFM will not detect changes to files, load thumbnails, or load subdirectory sizes, and you will need to manually refresh the file list view to see file changes. To do so, right-click on the file list and select View|Refresh, or press F5.

Note that even if the filesystem is listed in Change Detection, new files created in the directory, or files which are renamed or deleted, will be detected and read.

An alternative approach to blacklisting filesystems is to close the tab containing the filesystem while a copy is in progress to that directory.

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 enables 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, zzzFM 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 enables 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.

Each zzzFM 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 enables you to continue working while large files are being copied, etc. The Task Manager lists running tasks, automatically manages the task queue, enables you to stop, pause, queue, or resume tasks manually, and opens popup dialogs. Like most parts of zzzFM, 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. Internal tasks handle built-in functions such as a copying, moving, and deleting files, while an exec task runs an executable or script, either initiated from within zzzFM's built-in functions (such as running udevil to unmount a device) or from a custom command. The output of exec tasks is also collected and shown in the popup dialog's output monitor.

The Task Manager is located at the bottom of the zzzFM window, below all panels. It has two display modes: Show and Auto-Hide. If option View|Task Manager|Show Manager is selected, the Task Manager is always visible, even when no tasks are running. Or, if option View|Task Manager|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, enabling 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 enables 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|Task Manager submenu.)

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 zzzFM 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|Task Manager|Queue|Queue New Tasks is checked (the default), new tasks are automatically queued when initiated, rather than run immediately. zzzFM will automatically determine when to resume the queued tasks, depending on option View|Task Manager|Queue|Smart Queue. Or, you can always manually Resume, Pause or Stop a task to remove it from the queue.

The Task Manager's context menu enables 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|Task Manager 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), zzzFM 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 zzzFM 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 zzzFM 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 AsRoot, selecting Stop will cause a prompt for your 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 AsRoot. (You can see the exact commands being issued by running zzzFM 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), zzzFM 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 AsRoot, selecting Pause will cause a prompt for your 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 AsRoot. (You can see the exact commands being issued by running zzzFM 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 AsRoot, selecting Resume will cause a prompt for your 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 AsRoot. (You can see the exact commands being issued by running zzzFM 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.

Show Output
The Show Output menu item will only appear if a custom popup handler has been set for the selected task. Show Output will raise the normal popup dialog for the task, showing any stdout/stderr output. This is particularly useful for debugging.

Note that any custom menu items added directly after Show Output will also only appear for tasks with a custom popup handler.

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|Task Manager 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|Task Manager|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 zzzFM 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|Task Manager|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:

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 enables 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|Task Manager 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 zzzFM 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 zzzFM window. However, you can still click on visible portions of the main window. Changing this setting has no effect on dialogs which are already open.

If unchecked, popup dialogs may be placed beneath the main window.

Popups|Above Others
If option Above Others is checked, any task's popup dialog will be kept above all other windows when initially shown. Note that some window managers do not support keeping windows above others, and your window manager settings may override this behavior.

Popups|All Workspaces
If option All Workspaces is checked, any task's popup dialog will appear on all workspaces/desktops (will be set as sticky) when initially shown. Note that some window managers do not support sticking windows, and your window manager settings may override this behavior.

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

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 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 enables 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 enables 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 enables 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 Error 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, zzzFM will attempt to copy them despite any errors on previous files.

Stop If Error 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 Error 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|Task Manager|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 zzzFM to do only one file operation at a 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, zzzFM 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 permit 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 100 MB in total size, an exception is made which permits 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 10 GB in total size. This permits 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.

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 Menus
As with most menus, it is also possible to add your own custom menu items and submenus to the Task Manager's context menu using Design Mode. This enables you to add commands which can control or interact with running tasks.

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

For example, to add a custom command which opens the working directory of the currently selected task, use this command line:

    zzzfm "$fm_task_pwd"

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|Task Manager|Popups|Popup All Tasks is checked, or based on a custom command's popup settings. The popup dialog's relationship to other windows may be controlled with options View|Task Manager|Popups|Stay On Top, Above Others, and All Workspaces.

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 occurred, and overwrite and error mode controls.

If View|Task Manager|Popups|Overwrite Option is checked and the task is internal, the popup dialog will show a drop-down list which displays and enables 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|Task Manager|Popups|Error Option is checked and the task is internal, the popup dialog will show a drop-down list which displays and enables 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|Task Manager|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 permit you to enter input. If your command requires interaction, you will need to enable Run In Terminal instead. Custom commands can also set a custom popup handler to replace the normal popup dialog.

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.

zzzFM's Design Mode enables you to change the name, shortcut key and icon of menu, toolbar and bookmark items; access help for an item; and set menu items to be disabled or hidden based on your context rules. You may add custom commands, applications, bookmarks, and submenus to any position in menus and toolbars. Custom items can be cut/copied/pasted from/to bookmarks, toolbars, and menus. All of this is controlled from the Design Menu.

To open the Design Menu, simply right-click on a menu item, bookmark, or toolbar item. The Design Menu is available for most menus in zzzFM, including in the right-click menu of the desktop.

To open the Design Menu using a shortcut key, press F2 while a 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.

While Design Mode works in almost all menus, a good place to practice is the Tools menu, which is reserved for your custom menu items.

When working with Design Mode, it is important to distinguish between two types of items: built-in and custom. Built-in items, such as Rename on the file list context menu, are part of the zzzFM program, whereas custom items are items you have added. Design Mode can be used on both types of items, but in different ways. For example, custom items can be removed, while built-in menu 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 item.

Custom items in zzzFM are like word processor macros - they enable you to automate tasks. You might create a quick custom item just for today's use and delete it when you're done, while other items may become a regular part of your file manager use.

Custom items come in several varieties: a Bookmark (which opens a directory, group of directories, URLs, or mounts a device), an Application (which starts an application or runs an executable), a Command (which runs a command line or script), a Separator (a line separating items in a menu or toolbar), and a Submenu (a menu containing more custom items).

When you right-click on a menu item, bookmark, or toolbar item, or press F2 while a 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.

Cut
The next items on the Design Menu, including Cut, Copy, and Paste, enable you to move and copy custom items. 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 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 items (except on the toolbar), 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 item onto the design clipboard. Again, you will not observe any immediate change to the menu after copying an item, until you paste it. You cannot copy built-in items (except on the toolbar), only custom ones.

Note: When copying an item of type Bookmark, the bookmark target will also be copied to the text and primary clipboards.

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 an item onto the design clipboard, it can be pasted into a menu, toolbar or the Booksmarks list. Determine where you want to paste the item, right-click on an existing item to open the Design Menu, and select Paste. The item will be copied or moved from its original location and will be placed after the item you clicked on.

For example, to move a custom menu item named '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 item, note that everything contained in the item is copied, including any command script, extra files you added to the command or data directories, settings, etc.

Paste, Cut, and Copy can also be used on the separators between items. To move a custom item to directly after a separator, copy the item 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 item. It cannot be used on built-in items, except in a toolbar.

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 item 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 REMOVING A SUBMENU, all commands and submenus contained within it are deleted as described above.

Note that a submenu in zzzFM can never be empty. As a result, if you remove the last item from a submenu, a new custom item named "New Command" or a default bookmark 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.

New|Bookmark
The New submenu of the Design Menu enables you to add a new custom item of a particular type: Bookmark, Application, Command, Submenu, or Separator.

New|Bookmark adds a new custom item of type Bookmark after the current item. You will be prompted to select a single target directory, and the Bookmark item will be added. To make further changes to your Bookmark item, right-click on it and select Properties. A Bookmark item's target may be a single directory to be opened when you activate the item, or it can be a semicolon-separated list of target directories, URLs, or devices.

Bookmarks in zzzFM may be placed into any menu or toolbar, not just the Bookmarks menu.

New|Application
New|Application adds a new custom item of type Application after the current item. Initially, you will be prompted to select an application from a list of applications installed on your system, and the Application item will be added. To make further changes to your Application item, right-click on it and select Properties. An Application item's target may be a .desktop file or an executable file, as detailed in Item Properties.

New|Command
New|Command adds a new custom item of type Command after the current item. You will be prompted to enter a name for the new command. Next, the Item Properties dialog will open to the Command page, enabling you to enter your command line(s) to be run, or to edit a command script.

The command line accepts anything you would normally enter in a bash command line. It can be as simple as a program's name you want to run when this menu item is selected, or may include multiple lines and variables. For more information, please see the Command page.

For example, right-click on a menu item and select New|Command. Enter 'Current Time' for the item name. For the command line, enter:

    date

And click OK. When you click the new 'Current Time' menu item, a dialog will open showing you the current date and time.

You can also add a new Command menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item where you want to insert the new Command item, and press the Insert key, or use the mouse shortcut Ctrl + Shift + Left-or-Right-Click.

New|Submenu
New|Submenu adds a new submenu into the menu or toolbar after the current item. You will be prompted for the new submenu's name. Because a submenu in zzzFM can never be empty, a new Command item named "New Command" or a default bookmark will automatically be added to the new submenu.

New|Separator
New|Separator adds a new separator line into the menu or toolbar after the current item. Design Mode works on separators too - right-click on a separator to open its Design Menu, which enables you to remove it, change its context rules, or paste items after it.

Add
The Add submenu will only appear in the Design Menu when it is opened by right-clicking on a toolbar item. This menu enables you to add built-in items to the toolbar. These items have preset functions, but you can change their name, shortcut key, and icon. Once added, they can be cut, copied and pasted (within toolbars only).

Tooltips
The Tooltips checkbox item will only be visible in the Design Menu when it is opened by right-clicking on a toolbar item. Checking the Tooltips option will cause tooltips to be shown when the mouse hovers over a toolbar item (the item's name is shown). This setting is global (for all toolbars).

Help
Help opens contextual help for an item. For built-in items, the zzzFM user's manual will be opened in your web browser. If no help is currently available, Help will be disabled. [Note: Because the user's manual is still incomplete, not all items will have specific help available.]

You may specify a preferred web browser via Help|Options|Browser. Also, a custom location for the user's manual can be set in Help|Options|Manual Location.

For custom items, Help will open the plain text README file for the item in your text editor. If no README file exists for a custom menu item, selecting Help will create one for you to edit. This file may also be named either '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.

Key Shortcut
Key Shortcut opens a dialog which enables you to bind any shortcut key to the current item, and to change or unset an existing shortcut key. When you select Key Shortcut, 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 Shortcut option can be used on built-in and custom items, 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.

TIP: To use only the keyboard in the Set Key dialog, press a key combination and then press Enter to click the Set button. Or, to click Unset, press the Escape key twice. To cancel, simply close the dialog (usually Alt-F4).

NOTE: Due to zzzFM's literal use of keycodes, turning Caps Lock on or changing your keyboard layout may cause some key shortcuts to not respond. For example, pressing Ctrl+C with Caps Lock on will not activate 'Copy' because the 'C' key returns a different code than with Caps Lock off. Also note that some keycodes for non-Latin keyboard layouts are converted to their approximate Latin equivalent. If such a conversion is made, the original keycode will be shown in square brackets.

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.

Edit Command
Appearing only for custom items of type Command where the command is set to a command line, Edit Command opens the Item Properties dialog to the Command page.

You can also edit an item's command line using a design mode shortcut instead of the Design Menu. Highlight the menu item and press F4 or Ctrl+E, or use the mouse shortcut Middle-Click.

Edit Script
Appearing only for custom items of type Command where the command is set to a script, Edit Script opens the command script in your configured editor.

You can also edit an item's script using a design mode shortcut instead of the Design Menu. Highlight the menu item and press F4 or Ctrl+E, or use the mouse shortcut Middle-Click.

Properties
Properties opens the Item Properties dialog for the current item, enabling you to change properties for the item as detailed in Item Properties below.

You can also open Item Properties 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.

The Item Properties dialog enables you to view and change the properties of built-in or custom menu and toolbar items. To open the dialog, right-click on a menu item, toolbar item, or bookmark and select Properties, or highlight a menu item and press F3.

Type
The Menu/Toolbar Item tab of the Item Properties dialog provides basic settings for the item.

The Type drop-down list shows the current type of the item: Built-In Command, Bookmark, Application, Command, Submenu, or Separator. If the type is Bookmark, Application or Command, you can change the type by selecting another type from the list.

An item's type determines what properties you can view and change, and how the item appears and behaves.

Name
The Name entry enables you to change an item's name as it appears in the menu, and is used as the tooltip for toolbar items. Precede a character with an underscore (_) to underline that character as a shortcut key (mnemonic) if desired (or use \_ to escape a literal underscore in the name). You can change the name of both built-in and custom items.

Note: In GTK >= 3.10, you must press the Alt key to see the mnemonics underlined.

For items of type Bookmark, the Name entry may be left empty, in which case the target of the Bookmark will be displayed as the item name.

For items of type Application, the Name entry may also be left empty, in which case the application's name (derived from the .desktop file's Name= key), or the executable's name will be displayed as the item name.

Key
The Key button shows the current key shortcut set for this item, if any. Clicking the button will open the Set Key dialog which enables you to set a key shortcut. Clicking the button is equivalent to selecting Key Shortcut directly from the Design Menu.

You can also change the key for an 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 entry enables you to set or change an icon for an item. 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, and will also be used in the task list when a command is run.

To remove an icon, simply clear the text box where the icon name is entered and click OK.

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/.

For items of type Bookmark, if no icon is specified, the default icon is used, set by right-clicking on the Bookmarks side pane and selecting Settings|Bookmark Icon.

For items of type Application, if no icon is specified, the application's icon (derived from the .desktop file's Icon= key) will be displayed as the item icon.

You can also change the icon for an item using a design mode shortcut instead of the Item Properties dialog. Highlight the menu item and press Ctrl+I, or use the mouse shortcut Shift + Middle-Click.

Target
The Target(s) entry and associated Browse button will only appear if an item is of type Bookmark or Application. This entry enables you to control what is opened when the item is activated.

Bookmark Targets
For Bookmark items, the Targets list may contain a single directory to be opened, or may contain a semicolon-separated list of directories, URLs, and/or devices. For example:

    /etc; /usr/bin; ftp://mirrors.kernel.org; /dev/sr0

When the Targets list contains a single directory or URL, whether it is opened in a new tab or in the current tab is determined by the New Tab setting for bookmarks, found by right-clicking on the Bookmarks side pane and selecting Settings. If the Targets list contains multiple paths or URLs, each is opened in a new tab.

Finally, the Targets list for a Bookmark may contain the path to a file, in which case the directory containing the file will be opened, and the file will be selected in the file list. For example:

    /etc/fstab

    ;/etc

Application Target
For Application items, the Target entry may contain the name of a .desktop file (zzzfm.desktop), the full path of a .desktop file, the name of an executable file (binary or script, eg zzzfm), or the full path of an executable file (/usr/bin/zzzfm).

When specifying an executable file, note that selected filenames will NOT be passed to the executable when it is run. (To do so, use a menu item of type Command.) When specifying a .desktop file, what is passed to the command is determined by the substitution variables in the Exec= key of the .desktop file.

When specifying a .desktop file, it is generally recommended to leave the Name and Icon fields empty so the .desktop file's values are used automatically.

Clicking the Browse button will enable you to select an application from a list of applications installed on your system.

Context
The Context page of the Item Properties dialog enables 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, and or separators. Context cannot be set for toolbar items (except items in custom toolbar submenus), and context will not apply to items when they are shown in the Bookmarks side pane.

Context refers to the state of the entire file browser window or desktop when a 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.

You 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.

Composing Rules
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 generally the most useful.

The box to the right of the subject enables you to choose a verb, or a relationship between the subject and its value. In the case of "matches" or "doesn't match", wildcards may be used (eg "Filename matches *.jpg"). If the test pattern contains any uppercase characters, the test is case-sensitive. For additional wildcard characters and pattern specifics, see IEEE Pattern Matching Notation.

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. Each subject chosen will have a different list of common values.

Below the value box 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 file browser was in a particular directory, etc. For example, if a file is selected when you open the properties dialog, and the subject is set to 'MIME Type', then the selected file's MIME type will 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.)

The context dialog will let you know the result of the current set of rules given the current context. Below the rules box to the right, you will see a 'Current:' label. For example if it reads "Current: Show", then for the current context and set of rules, 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.

An Example Set Of Rules
As an 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.

For this example, set the rule subject to 'MIME Type' and set the verb (the box to the right of subject) to 'begins with'. Below these, choose 'audio/' from the drop-down list of common values.

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 example, our rule will only match the context if the first selected file is an audio file.

Now 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 temporarily check option Ignore Context (see below) to access all menu items.

Additional Features
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 menu item 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 match if the currently selected device contained a blank DVD.

Automatic Context
It is important to note that built-in menu items sometimes have an automatic 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.

Custom menu items added directly after the Default menu item in the file list's Open context menu have an automatic pre-context ~~ they only appear if the MIME type of the first selected file matches the MIME type when the custom item was added. This provides an easy way to add an item with an automatic context based on MIME type, and may also be used to setup a file handler (see below).

Custom menu items added directly after Show Output in the Task Manager's context menu will also only appear for tasks with a custom popup handler.

Also, custom submenus which are empty due to all of their children being hidden based on context are hidden automatically.

Note: Custom menu items when shown in the Bookmarks side pane will not respond to Context rules, and will always be shown.

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 or disable an item you don't use. This can also happen accidently, which is one reason why Ignore Context (see below) is provided. For example, the rule Directory equals "" will never match (because Directory is always set).

Use As Handler For
Visible only for Command or Application items, the 'If enabled, use as handler for' drop-down list on the Context page is used to set this item as a default handler. For example, if set to "files", and you open one or more files, if this item is shown and enabled based on its context rules, then this item will be run, rather than the default MIME application. This option is used to define a file handler for specific file types (or based on any context rules).

If set to 'files', note that no files are passed to a command on the command line. You must use variables in your command line or script to pass files to it. If the menu item is of type Application, what is passed will depend on the Exec= line of the application's .desktop file.

If set to 'devices', clicking on a device in the Devices list will cause the item to be run rather than the applicable device handler. Variables %v, "$fm_device", or other variables may be used in your command.

If more than one item is set as a handler and each is enabled, multiple items will be run each time files or devices are opened.

As noted above, custom menu items added directly after the Open|Default menu item have an automatic pre-context - they only appear if the MIME file type of the first selected file matches the MIME type when the custom item was added. This provides an easy way to set a custom handler for a given MIME type. Simply select a file of the desired type, right-click on it and add your custom item directly after the Open|Default menu item. Next, select option 'use as handler for files'. Your custom item will be used to open files when the MIME type matches. Or, you can set additional context rules to determine when your handler is used.

'Use as handler for' currently has no effect on files or devices opened from the zzzFM desktop.

Ignore Context (see below) has no effect on the handler being context-enabled - its context will be tested even if global option Ignore Context is checked.

Ignore Context
The 'Ignore Context / Show All (global setting)' option, if checked, causes all context rules to be ignored, and all menu items shown regardless of context. 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 select the appropriate file to create a context where the item is shown and enabled, or you can open the Item Properties dialog for any other item and check option 'Ignore Context'. This will enable you to then access the Design Menu of all items and change their context rules. When you are finished, you can uncheck option 'Ignore Context'.

Note that Ignore Context does not affect the automatic context of built-in items - for example, even with Ignore Context checked, the file list's Paste menu item will always be disabled if the clipboard is empty.

Command
Shown only for menu items of type Command, the Command page of the Item Properties dialog enables you to set command line(s) to be run by this menu item, or edit a command script, depending on which radio button is selected: Command Line or Script.

Command Line
When Command Line is selected, the command is executed as one or more bash command lines. At its simplest, the command line may simply be the name of a program to run, but any valid bash line may be used, as the command lines are inserted into a temporary bash script when run.

You may use the following substitution variables in command lines:

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, may 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 may also contain bash scripts containing multiple commands. For example, 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 in a command line:

    DISPLAY=:1 claws-mail

Open In Editor
The Open In Editor button will examine the first part of the command line. If the first part is a text file (a script), it will be opened in your editor.

Command Script
When Script is selected on the Command page, a default bash script will be created for the command. Similar to command lines, bash commands may be entered in the script, or open it in your editor and save it. There is no need to organize your scripts, because you can always use Properties from the Design Menu to access the script of any Command menu item.

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, enabling 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 zzzFM Dialog to show custom dialogs from within the script, and socket commands to manipulate elements of the zzzFM window. Your script can also replace the default task popup dialog by setting a custom popup handler.

The substitution variables used above in command lines may NOT be used in a command script. Instead, bash variables are preloaded for your use (these variables may be used in command lines or a script).

When you select Script, a default bash script is generated as shown below:

__________________________________________________________

#!/bin/bash
### import zzzfm variables
### To see a list of all available variables, refer to
###    file:///usr/share/doc/zzzfm/zzzfm-manual-en.html#exvar
$fm_import
###
###
### Enter your commands here, below:     ( then save this file )




exit $?
__________________________________________________________




zzzfm variables available for use within custom scripts:
These are imported by the  $fm_import  line atop your custom scripts.
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

      Below, notice that variables which will be replaced by a string value
      are shown here enclosed within quotationmark characters. They should be
      similarly quoted when used within your scripts.  Variables which will only
      produce a numeric runtime value (or no whitespace characters, at least)
      are shown here unquoted.

      Bash Scripting Guide:  http://www.tldp.org/LDP/abs/html/index.html


"${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_task_id"                 selected task id
"fm_task_window"             selected task window id

"$fm_command"                current command
"$fm_value"                  menu item value             ( same as %a )
"$fm_user"                   original user who ran this command
"$fm_my_task"                current task's id  (see 'zzzfm -s help')
"$fm_my_window"              current task's window id
"$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"
tmp="$(fm_new_tmp)"          makes new temp directory  (destroy when done)
                                   To destroy:  rm -rf "$tmp"
fm_edit "FILE"               open FILE in user's configured editor

$fm_import        command to import above variables
                  This variable is exported to the runtime bash shell; you can also
                  use it in any script run from (sourced by) your custom command script.

______________________________________________


Script Example 1:
Note: a result idendical to this example No.1 could be achieved
via a NON-scripted custom command, ala: md5sum %F

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



Script Example 2:

  ### Show a confirmation dialog using zzzFM Dialog:
  ### Use QUOTED eval to read variables output by zzzFM Dialog:
  eval "`zzzfm -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[@]}"

[[[ TODO: run the sample script and paste the output here, inline, within the docs ]]]


Script Example 4:

  ### Copy selected files to panel 2
  ###   ensure panel 2 is visible
  ###   and files are selected
  ###   and current panel is not 2
  if [ "${fm_pwd_panel[2]}" != "" ] \
              && [ "${fm_files[0]}" != "" ] \
              && [ "$fm_panel" != 2 ]; then
      cp "${fm_files[@]}" "${fm_pwd_panel[2]}"
  else
      echo "Cannot copy to panel 2"
      exit 1    ###  shows error if [Popup Error] enabled
  fi


Script Example 5:

  ### Keep current time in task manager list Item column
  ###    ~~ refer to the #sockets section of this UserManual ~~

  while (( 1 )); do
      sleep 0.7
      zzzfm -s set-task $fm_my_task item "$(date)"
  done

______________________________________________

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 directory (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"

Open In Editor & Root Editor
The Open In Editor button will save and open the command script in your editor. Simply edit the script and save it in your editor. The Root Editor button, if shown, can be used to open a root-owned script in root's editor.

You can also open the command script in your editor directly from the Design Menu with Edit Script or using a design mode shortcut instead of the Design Menu. Highlight the menu item and press F4 or Ctrl+E, or use the mouse shortcut Middle-Click.

Run Options
Shown only for items of type Command, the Options page of the Item Properties dialog enables you to set additional options which determine how your command behaves. The Run Options section determines how zzzFM will run your command when the item is activated.

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 zzzFM. This is useful for running a program such as Firefox, for example. zzzFM 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 zzzFM. zzzFM'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. (When a command is run from the desktop menu, no Task Manager is shown for the task, but a popup may be shown automatically.)

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.)

zzzFM'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 permit 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 zzzFM 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 AsRoot, you will be prompted to enter your 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). Note that some terminal emulators cannot be run as a task by zzzFM because the emulator does not start a new instance.

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 occurred. 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, enabling 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. (However, unlike Popup Task, Popup All Tasks will not cause the popup to remain when the command has finished, unless an error occurs.)

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

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). Note that if you close the popup dialog while the command is still running, further output will NOT reopen it, but you can open it again by clicking on the task.

Popup Output can be used to alert you when your task has produced output. By default, it is checked in new commands.

Scroll Output
The Scroll Output 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 Output.

Even if Scroll Output is checked, you can always manually move the scrollbar up to inhibit auto-scrolling.

Run In Terminal
If your command is a command-line program which produces much output, or you need to be able to interact with it (eg enter a password), check the Run In Terminal option on the Options page.

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. If you do so, normally nothing will be shown in the output monitor.

Note that gnome-terminal, konsole, lxterminal, and urxvtc (and possibly other terminal emulator programs) lack a --disable-server or similar option to force a new instance to be started for each terminal window. This means that these terminals cannot generally be used successfully with a combination of both the Run In Terminal and Run As Task options, unless no other terminal window is open when the command is run. Thus use of these terminals may prevent zzzFM working correctly in some cases. For example, if a handler mounts a protocol in a terminal, the mount point may not be automatically opened when the mount command finishes. If you really want to use these terminals, you can, but you should note that not all functions may work as expected.

Keep Terminal Open
Enabled by default when using Run In Terminal, Keep Terminal Open will cause the terminal to stay open even after the command or program has finished. This is useful for programs which produce some output and then exit. Without Keep Terminal Open, the terminal window would close before you had a chance to read the output.

When Keep Terminal Open 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 Open.

Run As Root
when the command is run, your configured terminal or graphical su program will be used to run the command with elevated privileges (AsRoot), instead of as the current zzzFM user. Depending on the su program used, you will be prompted to enter either your 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, you are running a command which is not protected by root, as root. This may compromise your system security at the root level.

Another option is to run zzzFM itself as root when needed (select File|Root Window). In this way, all commands and settings are stored in root's home (/root/.config/zzzfm), and are protected by root. (sic)(skidoo sez: that statement may, OR MAY NOT, be true. You should test on your system to confirm the result.) Running zzzFM as root puts much power at your fingertips - accidentally deleting a file or directory 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 zzzFM as root. It is your responsibility to evaluate this option for your purposes.

When running a custom command as another non-root user, depending on the permissions of your zzzFM 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 field empty.

Style
The Style section of the Options page of the Item Properties dialog enables you to choose whether the item acts as a normal menu item, a checkbox, a confirmation dialog, or an input dialog.

Normal
If your menu item'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, or as a toolbar item. When clicked, your command will be run immediately. Normal is the default style for new commands.

Checkbox
If your menu item'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 command will be run.

On the toolbar, a Checkbox style item will appear as an icon, and clicking it will show the button depressed. In the Bookmarks list, an icon will be shown when a Checkbox style item is checked, and no icon will be shown when it is unchecked.

Your command can read the value of the checkbox using the variable $fm_value (or %a in command lines). This will equal 1 if checked, or 0 if unchecked. This enables your command to take different actions depending on the state of the checkbox.

For example, add a new Command menu item called 'Checker'. Then open the Properties dialog for the new item and select style Checkbox. Enter or paste this command line on the Command page:

    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 clicks OK, your 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 your message in the Confirmation/Input Message entry on the Options page.

Alternatively, to show a dialog while your script is running, or to easily create custom dialogs, see zzzFM 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 clicks OK, your 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 (or %a in command lines). 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 menu item called 'Your Name'. Then open the Properties dialog for the new item and select style Input. Enter 'Please enter your name:' as the message. Enter or paste this command line on the Command page:

    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.

Alternatively, to show a dialog while your script is running, or to easily create custom dialogs, see zzzFM Dialog.

Open In File Browser
The 'Open In File Browser' drop-down list is located at the bottom of the Options page of the Item Properties dialog. Each Command item has several directories where associated files are stored, and Open In File Browser enables you to conveniently open these directories. Simply select a directory and it will be opened. When designing more complex scripts, this facility can be used to help manage associated files.

Command Dir $fm_cmd_dir
Opens the command directory ($fm_cmd_dir). The command directory contains the command script if any (exec.sh), as well as other files you may have added for use by the command. The command directory's path will typically be:
    ~/.config/zzzfm/scripts/cstm_00000000/

While you may modify files in the command directory when creating and maintaining your command, the command script should not modify files in this directory while the command is running.

All files in the command directory are deleted when the item is removed!

Data Dir $fm_cmd_data
Command items may 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. The data directory's path will typically be:
    ~/.config/zzzfm/mydat/cstm_00000000/

This directory must be created on demand, so if you plan to use it in a script, first make sure it exists:

    mkdir -p "$fm_cmd_data"

zzzFM does not automatically store any files in this directory - it is entirely up to you how it is used. Note: All files in the item's data directory will be automatically deleted if the item is removed.

zzzFM includes two toolbars in each panel: the main Toolbar above the file list, and a Side Toolbar shown above the side panes. To show or hide the Toolbar or Side Toolbar in a given panel, right-click on the file list and check or uncheck View|Toolbar or View|Side Toolbar.

Toolbars can be customized using Design Mode by right-clicking on a toolbar item. You can also middle-click on a toolbar item to open its Item Properties dialog or script. Each panel's toolbars are configured independently of other panels.

In addition to adding or pasting the usual custom items in a toolbar, you can also use the Add submenu of the Design Menu to add built-in tool items. These items have preset functions, but you can change their name and icon. Once added, they can be cut, copied and pasted within toolbars only. There are also two built-in submenus in the Add submenu: Back History and Forward History. If shown, these will display not only a back/forward button, but also a menu button which opens a drop-down list showing path history for the current browser tab.

When adding or pasting a custom submenu into a toolbar, it will also be displayed as a button with a smaller menu button next to it. The large button will have the icon (and tooltip) of the first item in the submenu , and clicking this button will activate that first item. To use other items in the submenu, click the smaller menu button. Design Mode can also be used within this menu by right-clicking on a menu item. To set properties for the submenu itself, right-click on either button.

Menu and bookmark items can be pasted to the toolbars, and custom toolbar items can be cut/copied and pasted elsewhere. Design Mode mouse shortcuts (see below) may also be used on toolbar items.

TIP: If you want to create a toolbar button which shows a custom submenu from another menu, without copying the submenu to the toolbar, you can use a socket command to show the submenu as a popup menu instead. To do so, add a New|Command to the toolbar (where "Menu Name" is the name of the existing custom submenu):

    zzzfm -s activate "Menu Name"

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. On a toolbar item, mouse shortcuts may be used.

Design Mode Shortcuts

Action	Key Combo	Mouse Combo
Design Menu	F2 or Menu	Right
Cut	Ctrl + X	Alt + Left-or-Right
Copy	Ctrl + C	Ctrl + Left-or-Right
Paste	Ctrl + V	Shift + Left-or-Right
New Command	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
Properties	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 Copy) and press F1.

If the shortcut action is not available for the current item (for example, performing Remove on a built-in menu item), 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 zzzFM, you may need to disable them in your window manager.

Although zzzFM does not include a full-featured MIME editor, zzzFM'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 zzzFM to edit your mimeapps.list file, setting the application as the default.

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 enables you to configure MIME associations and definitions for this file type. (Note that other methods may also be used to open files.)

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 other programs on your system which use the MIME database, not just zzzFM. However, some programs use other means for determining file types, or some combination of several methods, so not all MIME changes made in zzzFM will be reflected in all programs.

For more elaborate MIME adjustments, consider using a dedicated MIME editor.

How MIME Works
zzzFM uses freedesktop.org's shared-mime-info database to determine file types, display file type names, determine and adjust associated applications, and determine and adjust the default application for a type. (Note that other methods may also be used to open files, and that you can create file handlers to bypass MIME associations.)

It helps to know some basics about how MIME works so you can better control how your system handles file types. Note that zzzFM is not fully compliant with all freedesktop specifications. Where this manual and their specifications differ, this manual is authoritative on zzzFM's behavior.

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 directory, 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 directory 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

To determine what applications are associated with a given MIME type (what applications can be used to open files of that type), zzzFM 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 default or additional applications with a MIME type, or remove unwanted associations. Information about default applications, and added and removed associations are placed in mimeapps.list files located in the applications directories. ~/.config/mimeapps.list (or the older location: ~/.local/share/applications/mimeapps.list) in the user's home directory 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. (zzzFM will never modify defaults.list, but may read it.)

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

    sudo update-mime-database

At startup, zzzFM 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 zzzFM after changing MIME type definitions.

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 zzzFM this will move the application to the top of the Open submenu.

Specifically, zzzFM will edit your ~/.config/mimeapps.list file, adding the application's .desktop file to the beginning of the list for the given MIME type in [Default Applications] and [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 generally no longer appear in the Open submenu for this file type.

Specifically, zzzFM will edit your ~/.config/mimeapps.list file, removing the application's .desktop file for the given MIME type in [Default Applications] and [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, zzzFM will include applications associated with the MIME type (eg text/html) and applications associated with the generic '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, enabling 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, zzzFM will edit your ~/.config/mimeapps.list file, adding the application's .desktop file to the list for the given MIME type in [Default Applications] and [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 zzzfm.desktop). Selecting this item will open the copy of the desktop file located in ~/.local/share/applications/ using your text editor, enabling 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 (add an <icon name="icon-name"/> tag), 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, zzzFM 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 ~/.config/mimeapps.list (or the older location: ~/.local/share/applications/mimeapps.list) in your text editor, enabling you to examine added and removed associations, and edit them.

If you edit this file, be careful to use its default formatting. Any changes you make to this file will immediately take effect.

applications/
Selecting applications/ will open the ~/.local/share/applications/ directory in a new tab. This directory contains your local copies of .desktop files. (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, enabling 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 zzzFM for the changes to take effect. (zzzFM 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, zzzFM 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/ directory in a new tab. This directory contains your custom xml files used to redefine MIME types (see mime-type.xml above). After adding, editing, or removing files from this directory, you may then need to run 'update-mime-database ~/.local/share/mime' and/or restart zzzFM for the changes to take effect.

usr/
The usr/ submenu gives you access to files and directories 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 files in /usr/share, as a software upgrade may overwrite it. Instead, to make system-wide changes, place a copy in /usr/local/share/applications and edit that. To make changes for a single user only, place a copy in ~/.local/share/applications/).

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 enable 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 zzzFM.

Handlers are sets of commands which tell zzzFM how to perform a function, such as opening a file, mounting a device, or creating/extracting an archive. In some cases your handlers replace zzzFM's default behavior. Handlers come in several varieties: Devices, Protocols, Archives, and Files.

Device handlers tell zzzFM how to mount, unmount, and show properties for specific filesystems or devices. Anytime zzzFM or the zzzFM daemon mounts or unmounts a device (manually or automatically), or shows the properties of a device, it uses a handler to determine what commands to run. By adding custom device handlers, zzzFM can be made to mount and unmount virtually any type of device or filesystem.

To configure device handlers, right-click in the Devices list and select Settings|Device Handlers. The list at the left of the Device Handlers configuration window lists all device handlers. (Enlarge this window to see the handler commands more clearly.) Click on a handler's name to see its contents. The order of the list is important: Starting from the top, the first handler which matches the current device will be used. You can reorder the list by dragging entries, or using the Up & Down buttons. In this way, you determine what handlers have preference. The "Default" handler is usually listed last, and is used if no other handlers apply.

The right side of the window shows the selected handler's contents. If Enable Handler is unchecked, this handler will never be used. The Name contains the common name for the handler, which appears in the list and in debug messages. Next comes a Whitelist and Blacklist: these determine when this handler will be used. Finally, the Mount, Unmount, and Properties boxes contain scripted commands which will be run by the handler to mount, unmount, or list properties of a device.

TIP: If you just want to change the mount program that zzzFM uses to mount removable drives (such as udevil, pmount, or udisks), open Device Handlers and click the Default handler. Example Mount and Unmount commands are shown for each mount program. Just enable the section you want to use by removing the appropriate comment marks (#).

Whitelist
A handler's whitelist is a space-separated list of elements. In general, if any element in the list matches the device properties, then this handler may be used for this device. If a list element is prefixed with a plus sign '+', that element is required to match. Any element in the list may contain wildcards (an asterisk '*' to represent multiple characters, or a question mark '?' to represent single characters).

The following device whitelist elements are recognized:

    FSTYPE (eg ext3)
    dev=DEVICE (/dev/sdd1)
    id=UDI
    label=VOLUME_LABEL (include spaces as underscores)
    point=MOUNT_POINT
    audiocd=0 or 1
    optical=0 or 1
    removable=0 or 1
    mountable=0 or 1

If you want a handler to apply to several filesystem types, just list them:

    ext3 ext4

    +ext3 +dev=/dev/sdd* +label=My_Volume_Label

To see what handler zzzFM has selected to mount a device, and see the commands being issued, start the zzzfm program in a terminal window, and observe debugging output in the terminal while zzzFM is running. For example, mounting a USB stick you may see:

    Selected Device Handler 'Default': MOUNT [*]

Blacklist
A handler's blacklist is a space-separated list of elements. If any element in the list matches the device properties, this handler will never be used for this device.

For example, consider the following Whitelist/Blacklist combination:

    Whitelist: vfat
    Blacklist: dev=/dev/sde1 label=Ignored_Volume_Label

Mount
The Mount text box contains the commands which will be run if this handler is selected to mount a device (manually or automatically). The commands are run as a bash script, and may contain any valid bash syntax (version 4, or any greater version of bash you have installed). If the Run In Terminal box is checked, the script will be run in your configured terminal emulator window (which may permit the user to enter information). If Run As Task is checked, the running command will be listed in the task manager and error output will be shown in a popup. You can also edit the commands in your configured editor by clicking on 'Edit' in the upper-right corner, or press Alt-Enter while the cursor is in the box (remember to save the script in your editor when finished).

Several variables will be replaced before your commands are run:

    %v  device
    %o  volume-specific mount options (use in mount command only)
    %t  filesystem type being mounted (eg vfat)
    %a  create auto mount point

Finally, the presence of %a will cause zzzFM to create a new directory to be used as a mount point for the mount (eg ~/.cache/zzzfm/mountpoint), and %a will be replaced with the directory path. When the device is unmounted, this mount point will be removed. Or, if you wish to create your own mount point, or if your mount program automatically creates one in /media (such as udevil), then you may omit %a.

In addition to the above variables, zzzFM's exported bash variables may be used, as well as the substitution variables defined in Command Line.

Example Mount commands (enable only one section by removing #):

    # # udevil:
    #     udevil mount -o '%o' %v
    #
    # # pmount: (does not accept mount options)
    #     pmount %v
    #
    # # udisks v2:
    #     udisksctl mount -b %v -o '%o'
    #
    # # udisks v1: (enable all three lines!)
    #     fm_udisks=`udisks --mount %v --mount-options '%o' 2>&1`
    #     echo "$fm_udisks"
    #     [[ "$fm_udisks" = "${fm_udisks/ount failed:/}" ]]

If a handler's Mount command is empty (or contains only blank lines and comments), that handler will not be used. If no handler is found with a non-empty Mount command, zzzFM will automatically attempt to use udevil, pmount, udisks2, or udisks1 to mount the device (it will use whatever is installed, in this order of preference).

NOTE: Custom menu items, added with New|Command, may also be set as primitive device handlers via their Use as handler for option. When a device is clicked, if the menu item is enabled based on the current browser context, this menu item's command will be run rather than any other configured device handler. In addition, device events may be configured to trigger actions based on socket event evt_device.

Unmount
The Unmount text box contains the commands which will be run if this handler is selected to unmount a device (manually or automatically). The commands are run as a bash script, and may contain any valid bash syntax (version 4, or any greater version of bash you have installed). If the Run In Terminal box is checked, the script will be run in your configured terminal emulator window. If Run As Task is checked, the running command will be listed in the task manager and error output will be shown in a popup.

Several variables will be replaced before your commands are run:

    %v  device
    %a  current mount point

In addition to the above variables, zzzFM's exported bash variables may be used, as well as the substitution variables defined in Command Line.

Example Unmount commands (enable only one section by removing #):

    # # udevil:
    #     udevil umount %v
    #
    # # pmount:
    #     pumount %v
    #
    # # udisks v2:
    #     udisksctl unmount -b %v
    #
    # # udisks v1: (enable all three lines!)
    #     fm_udisks=`udisks --unmount %v 2>&1`
    #     echo "$fm_udisks"
    #     [[ "$fm_udisks" = "${fm_udisks/ount failed:/}" ]]

If a handler's Unmount command is empty (or contains only blank lines and comments), that handler will not be used. If no handler is found with a non-empty Unmount command, zzzFM will automatically attempt to use udevil, pmount, udisks2, or udisks1 to unmount the device (it will use whatever is installed, in this order of preference).

Properties
The Properties text box contains the commands which will be run if the user selects Properties from the right-click menu of the devices list. This is used to show any relevant properties and status of the device. If the Run In Terminal box is checked, the script will be run in your configured terminal emulator window, otherwise the output will be displayed in a zzzFM popup window. If Run As Task is checked, the running command will be listed in the task manager and error output will be shown in a popup.

If no applicable device handler has a non-empty Properties command, zzzFM's default properties will be shown.

Protocol handlers tell zzzFM how to respond when a URL is opened or unmounted, such as mounting or unmounting a network filesystem, or showing properties for a mounted URL. Anytime you enter a URL in zzzFM's Path Bar (eg ftp://mirrors.kernel.org), open a bookmark containing a URL, select Open URL from the file menu, or specify a URL on the command-line, a handler is used to open the URL. This handler can run another program (such as a web browser), can mount the URL as a filesystem, or take any other action you specify.

To configure protocol handlers, right-click in the Path Bar and select Protocol Handlers, or select Settings|Protocol Handlers from the Devices menu. Like Device Handlers, protocol handlers have an Enable checkbox, a whitelist and blacklist which determine when the handler is used, and command boxes.

Whitelist
As with device handlers, a protocol handler's whitelist is a space-separated list of elements. In general, if any element in the list matches the protocol properties, then this handler may be used. If a list element is prefixed with a plus sign '+', that element is required to match. Any element in the list may contain wildcards (an asterisk '*' to represent multiple characters, or a question mark '?' to represent single characters).

zzzFM recognizes a path bar entry as a protocol if it has the form PROTOCOL:// (such as ftp://). zzzFM recommends a standard URL format regardless of protocol. If the URL is in such a format, zzzFM will break the URL into parts and assign them to variables ready for your use. You can also use other URL formats (eg those specific to a mount program), but zzzFM may not correctly assign the parts to variables.

The following protocol whitelist elements are recognized:

    PROTOCOL (eg ssh)
    url=URL (ssh://...)
    host=HOSTNAME
    user=USERNAME
    mtab_fs=FSTYPE      (mounted fs type as shown in mtab)
    mtab_url=URL        (mounted url as shown in mtab)
    point=MOUNT_POINT

    ssh mtab_fs=fuse.sshfs

Note: The whitelist mtab_fs= property also may affect what mounted protocols zzzFM detects and lists in its Devices list. By default, zzzFM will list most non-block (eg fuse) filesystems which are mounted to a user-readable directory. To have it detect and list another filesystem in the devices list, add the type with mtab_fs=FSTYPE to a protocol handler's whitelist. This will also ensure that your protocol handler, rather than a device handler, is used to unmount and show properties for the mounted protocol.

Note that some of the above fields, such as mtab_fs, mtab_url, and point, are only set when performing an unmount. Also, any spaces in the values are replaced with underscores before being tested.

To see what handler zzzFM has selected to mount or unmount a URL, and see the commands being issued, start the zzzfm program in a terminal window, and observe debugging output in the terminal while zzzFM is running. For example, mounting and unmounting an ssh URL you may see:

    Selected Protocol Handler 'ssh': MOUNT [ssh] mtab_fs=fuse.sshfs
    Selected Protocol Handler 'ssh': UNMOUNT ssh [mtab_fs=fuse.sshfs]

After your protocol is mounted, the mount directory may or may not automatically open in zzzFM (depending on whether zzzFM can associate a new device with the protocol just mounted based on mtab, mount point, etc.) If it does not open, you can open a mount point after a successful mount command by adding a line such as:

    [[ $? -eq 0 ]] && zzzfm -t "%a"

Blacklist
As with device handlers, a protocol handler's blacklist is a space-separated list of elements. If any element in the list matches the protocol properties, this handler will never be used for this device.

Mount
The Mount text box contains the commands which will be run if this handler is selected to handle an entered URL. The commands are run as a bash script, and may contain any valid bash syntax (version 4, or any greater version of bash you have installed). If the Run In Terminal box is checked, the script will be run in your configured terminal emulator window (which may permit the user to enter information, such as a password). If Run As Task is checked, the running command will be listed in the task manager and error output will be shown in a popup. You can also edit the commands in your configured editor by clicking on 'Edit' in the upper-right corner, or press Alt-Enter while the cursor is in the box (remember to save the script in your editor when finished).

Several variables will be replaced before your commands are run:

    %url%     $fm_url
    %proto%   $fm_url_proto
    %host%    $fm_url_host
    %port%    $fm_url_port
    %user%    $fm_url_user
    %pass%    $fm_url_pass
    %path%    $fm_url_path
    %a        auto create mount point

In addition to the above variables, zzzFM's exported bash variables may be used, as well as the substitution variables defined in Command Line.

Note that the Mount command does not need to be used to mount a protocol, it may simply open the protocol with a program of your choice. For example, to open http:// URLs with Firefox, put "http" in the handler's whitelist, and use this Mount command:

    firefox "%url%" &

You can also open a website using a zzzFM socket command, which will guess the user's web browser:

    zzzfm -s run-task web "$fm_url"

If a handler's Mount command is empty (or contains only blank lines and comments), that handler will not be used. If no handler is found with a non-empty Mount command, zzzFM will not handle the protocol, and will display an error to the user.

Unmount
The Unmount text box contains the commands which will be run if this handler is selected to unmount a mounted URL, generally a network filesystem such as sshfs.

Several variables will be replaced before your commands are run:

    %url%     $fm_url
    %proto%   $fm_url_proto
    %host%    $fm_url_host
    %port%    $fm_url_port
    %user%    $fm_url_user
    %path%    $fm_url_path
    %a        current mount point
              $fm_mtab_fs   (mounted fs type as shown mtab)
              $fm_mtab_url  (mounted url as shown mtab)

If a protocol handler's Unmount command is empty (or contains only blank lines and comments), that handler will not be used. If no handler is found with a non-empty Unmount command, zzzFM will not unmount the filesystem, and will display an error to the user.

Properties
The Properties text box contains the commands which will be run if the user selects Properties from the right-click menu of the devices list. This is used to show any relevant properties and status of a mounted protocol. If the Run In Terminal box is checked, the script will be run in your configured terminal emulator window, otherwise the output will be displayed in a zzzFM popup window.

If no applicable protocol handler has a non-empty Properties command, zzzFM's default properties will be shown.

zzzFM includes a built-in facility for creating, extracting, and listing the contents of archive files (such as tar.gz or zip files).

Open Menu
zzzFM's Open menu for archive files, accessed by right-clicking on any archive file, enables you to choose Extract, Extract To, or List Contents. By default, choosing Extract will extract the selected archive files to folders of the same name, choosing Extract To will enable you to choose where to extract the files, or choosing List Contents will display the contents of the archive file(s).

Archive Defaults

With a default configuration, opening an archive file by double-clicking it in the file list will automatically extract it to a directory of the same name. You can change how zzzFM opens archives by right-clicking on an archive file and using the Open|Archive Defaults submenu:

Open With App
Selecting Open With App will cause zzzFM to open archive files using other methods. Even if you have Open With App selected as the default behavior for opening archive files, you can still manually choose Extract, Extract To, and List Contents from the Open menu to use zzzFM's built-in archive facility.

Extract
Extract is the default behavior of zzzFM. If selected, double-clicking on an archive in the file list will automatically extract its contents to a directory.

Extract To
The Extract To behavior is similar to Extract - it will extract the archive contents to a directory ~~ except that you will be able to choose the destination directory. Also, the Extract To dialog includes Create Subdirectory and Write Access options (see below).

List Contents
If List Contents is selected, double-clicking on an archive file will open a terminal window displaying the contents of the selected archive, but it will not be extracted.

In addition, the Archive Defaults submenu includes these options:

Create Subdirectory
If this option is selected, which is the default, then using Extract (manually or automatically on open) will create a subdirectory with the same name as the archive, and will extract the contents to it. If this option is not selected, the archive contents will be extracted to the current directory. (Note that the Extract To dialog also contains a Create Subdirectory option for that operation - that setting is remembered separately). Note that with Create Subdirectory disabled, some archive programs, such as tar , may overwrite files in the current directory if they have the same name as files in the archive.

Write Access
If this option is selected, after extraction the contents of the extraction directory will be made write-accessible to the current user. This option is only available if the Create Subdirectory option is enabled, and if the user is not root. Because some archives (such as tar.gz files made from CDROM) contain read-only files which then require an extra step to delete, this convenience option ensures the user can delete and change the extracted files.

Archive Handlers
Selecting Archive Handlers opens the Archive Handlers configuration window (see below).

Archive Handlers

Archive handlers tell zzzFM how to create, extract, and list the contents of various kinds of archive files (eg tar.gz files). To configure archive handlers, right-click on a known archive file and select Open|Archive Defaults|Archive Handlers. Or, right-click on any file, select New|Archive, and click the Configure button.

The list at the left of the Archive Handlers configuration window lists all archive handlers. (Enlarge this window to see the handler commands more clearly.) Click on a handler's name to see its contents. The order of the list is important: Starting from the top, the first handler which matches a file being extracted will be used. You can reorder the list by dragging entries, or using the Up & Down buttons.

The right side of the window shows the selected handler's contents. If Enable Handler is unchecked, this handler will never be used. The Name contains the common name for the handler. Next come MIME Type and Pathname text boxes: these determine when this handler will be used. Finally, the Compress, Extract, and List boxes contain scripted commands which will be run by the handler to perform archive functions.

MIME Type
This text box contains a space-separated list of MIME types (such as application/x-compressed-tar), which is used to associate the handler with those file types. Wildcards, such as asterisk '*' to represent multiple characters, and question mark '?' to represent a single character, are accepted. A handler must have a MIME Type or a Pathname pattern (see below), or it cannot be used to extract or list the contents of archive files.

Pathname
This text box contains a space-separated list of pathname globs to be used in addition to MIME type to identify files compatible with this handler. For example, a Pathname pattern of "*.tar.gz" will cause all filenames ending in ".tar.gz" to be associated with this handler. The first pathname pattern in the list will determine the default file extension used when creating archives with this handler. Note that the full pathname of the file (eg /home/user/archive.tar.gz) is tested against the pattern, so for advanced uses the pattern may contain directory parts (eg /home/user/*.tar.gz) to control how archives in specific locations are handled.

Compress
The Compress text box contains the commands which will be run if this handler is selected to create an archive (or a single compressed file, etc.) The command(s) are run as a bash script, and may contain any valid bash syntax (version 4, or any greater version of bash you have installed). If the Run In Terminal box is checked, the script will be run in your configured terminal emulator window (which may permit the user to enter information, such as a password). If Run As Task is checked, the running command will be listed in the task manager and error output will be shown in a popup. You can also edit the commands in your configured editor by clicking on 'Edit' in the upper-right corner, or press Alt-Enter while the cursor is in the box (remember to save the script in your editor when finished).

Several variables will be replaced before your commands are run:

    %n: First selected filename/dir to archive
    %N: All selected filenames/dirs to archive, or (with %O) a single filename
    %o: Resulting single archive file
    %O: Resulting archive per source file/directory (use changes %N meaning)

If you want to create a single archive containing all selected items, use %o to represent the name of the resulting archive file (which will be chosen by the user at run time). With %o, you will generally use %N to include the list of all selected files. (Or if you only use %n, only the first selected file will be included in your archive.) For example, to create a tar archive, you would use this Compress command:

    tar -cvf %o %N

    gzip -c %N > %O

Note: To include a literal '%N' or other string in your command without it being interpreted as a variable, use double percent signs (%%N).

In addition to the above variables, or instead of them, zzzFM's exported bash variables may be used.

To create an archive using your handler, select files to be archived in zzzFM's file list, right-click, and select New|Archive. Select your handler in the Format list. You can also edit the Compress command in this dialog, and the updated command will be saved to your handler.

To test your handler commands, run the zzzfm program in a terminal, and observe the output as zzzFM is working on archives. This will show you the handlers chosen, and the commands exactly as they are issued.

When running any commands in a terminal, zzzFM will add a query at the end to keep the terminal open if it sees a non-zero error status from the last command run, or when listing archive contents. If you need to keep the terminal open for other purposes, you can include these lines in your command:

    echo -n '[ Finished ]  Press Enter to close:'
    read

To trap any errors in commands containing multiple lines, you can use the built-in error trap after each line:

    tar -cvf %o %N || fm_handle_err

Extract
The Extract text box contains the commands which will be run if this handler is selected to extract an archive (or uncompress a single compressed file, etc.)

Several variables will be replaced before your commands are run:

    %x: Archive file to extract
    %g: Unique extraction target filename with optional subdirectory
    %G: Unique extraction target filename, never with subdirectory

  tar -xvf %x

    gzip -cd %x > %G

In addition to the above variables, or instead of them, zzzFM's exported bash variables may be used.

List
The List text box contains the commands which will be run if this handler is selected to list the contents of an archive file. It recognizes only the %x variable which is replaced with the archive filename, and zzzFM's exported bash variables may also be used.

When you double-click on a file to open it, zzzFM will use one of the following methods to open the file, in this order of preference:

• If a custom menu item is enabled and has context option Use as handler for: set to 'files', the custom menu item will be activated. This may be used to open files or take other actions. To add a custom menu item of this kind, simply right-click on almost any existing menu item and select New|Command. On the Context page of the Item Properties dialog, set 'Use as handler for: files'. Also be sure to add context rules which determine when this handler will be active (or it will activate for all types of files).
  
  
• If the first selected file is a recognized archive type (eg tar.gz), and Archive Defaults is set to Extract, Extract To, or List Contents, zzzFM will attempt to open all selected files with Archive Handlers, ignoring files for which it doesn't have an archive handler.
  
  
• Otherwise, if the MIME type or pathname of a selected file being opened matches a dedicated File Handler, and the handler has option Enable as a default opener enabled, the file handler will be run for that file.
  
  
• If the MIME type of a selected file being opened has an application associated with it in the MIME database, the default application will be used to open the file. zzzFM's MIME Menu may be used to change the application associated with a file type on your system.
  
  

Note that multiple files may be opened or extracted by selecting them and using Open|Open With Default, subject to the same rules above.

For feedback on how zzzFM is opening files, run the first instance of zzzfm in a terminal, and observe the output in the terminal after opening a file in zzzFM.

File Handlers

File handlers are one method of several that zzzFM may use to open specific types of files, or they can perform any other action when a file is clicked. These handlers work independently of the MIME associations on your system. To configure file handlers, right-click on any file and select Open|File Handlers.

The list at the left of the File Handlers configuration window lists all file handlers. (Enlarge this window to see the handler commands more clearly.) Click on a handler's name to see its contents. The order of the list is important: Starting from the top, the first handler which matches a file being opened will be used. You can reorder the list by dragging entries, or using the Up & Down buttons.

The right side of the window shows the selected handler's contents. If option 'Enable as a default opener' is checked, this handler will automatically run if you double-click on a file of its type. Or, if the option is unchecked, the handler will only run if you manually select it from the Open menu.

The Name and Icon text boxes are used to specify the common name and icon name for the handler, which will appear in the menu and Task Manager. Next come MIME Type and Pathname text boxes: these determine for what files this handler may be used. Finally, the Open Command box contains scripted commands which will be run by the handler to open the file(s), or perform any other function.

MIME Type
This text box contains a space-separated list of MIME types (such as text/plain), which is used to associate the handler with those file types. Wildcards, such as asterisk '*' to represent multiple characters, and question mark '?' to represent a single character, are accepted. For example, a MIME type of "video/*" will specify all video files. A handler must have a MIME Type or a Pathname pattern (see below), or it will not be used.

Pathname
This text box contains a space-separated list of pathname globs to be used in addition to MIME type to identify files compatible with this handler. For example, a Pathname pattern of "*.avi" will cause all AVI video files to be associated with this handler. Note that the full pathname of the file (eg /home/user/videos/movie.avi) is tested against the pattern, so for advanced uses the pattern may contain directory parts (eg /home/user/videos/*.avi) to control how files in specific locations are handled.

Open Command
This text box contains the commands which will be run if this handler is selected to open one or more files. The command(s) are run as a bash script, and may contain any valid bash syntax (version 4, or any greater version of bash you have installed). If the Run As Task option is checked, the script will be run synchronously (will appear in the Task Manager), and any error will be shown in a popup. If the Run In Terminal option is checked, the script will be run in your configured terminal emulator window (which enables the user to enter information). You can also edit the commands in your configured editor by clicking on Edit in the upper-right corner, or press Alt-Enter while the cursor is in the box (remember to save the script in your editor when finished).

Several variables will be replaced before your commands are run:

The presence of %a will cause zzzFM to create a new directory to be used as a mount point (eg ~/.cache/zzzfm/mountpoint, and %a will be replaced with the directory path. This can be used to mount files (eg iso files). When the device is unmounted, this mount point will be removed. For example, this command will mount an iso file using fuseoiso and open the mount point directory in zzzFM:

    fuseiso %f %a && zzzfm %a &

In addition to the above variables, zzzFM's exported bash variables may be used, as well as all the substitution variables defined in Command Line.

When running your commands in a terminal, if you need to keep the terminal open after your command finishes, you can include these lines at the end of your command:

    echo -n '[ Finished ]  Press Enter to close:'
    read

To test your handler commands, run the zzzfm program in a terminal, and observe the output as zzzFM is opening files. This will show you the handlers chosen, and the commands exactly as they are issued.

Each handler configuration window includes Options and Defaults buttons.

Pressing Defaults will restore the current handler to default values. The handler must be a built-in default handler for this button to be enabled.

The Options button opens a popup menu which provides the following options. Note that selecting any of these options automatically clicks Apply first if changes have been made to the current handler.

Restore Default Handlers
Restore Default Handlers will replace any missing default handlers that have been removed from the handlers list, and will also ask if you want to overwrite all existing default handlers. If you answer yes, all default handlers will be reset. If you answer no, only missing handlers will be added. Any custom handlers you have added are not affected.

zzzFM Dialog is a built-in feature of zzzFM which enables you to easily create and control custom GTK dialogs. Typically such dialogs are shown from scripts to gather information from the user. zzzFM Dialog enables 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 zzzFM Dialog exits, it writes variables to stdout which can be evaluated directly in bash, or easily parsed in other languages.

Although zzzFM 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.

zzzFM Dialog runs as a separate instance, whether other instances of zzzFM are running or not. This means you can use zzzFM Dialog from within custom command scripts in zzzFM, or in other scripts which run independently.

Help Reference

To see zzzFM Dialog's help reference, run:

$ zzzfm -g help
zzzFM 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:
    zzzfm --dialog|-g {ELEMENT [OPTIONS] [ARGUMENTS...]} ...
Example:
    zzzfm -g --label "A message" --button ok

ELEMENT:       OPTIONS & ARGUMENTS:
--------       --------------------
--title        TEXT|@FILE
               Set window title
--window-icon  ICON|@FILE
               Set window icon
--label        [--wrap|--nowrap] 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 [SAVEFILE]
               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
--click        COMMAND...
               Run COMMAND when an element is clicked or focused
--window-close COMMAND...
               Run COMMAND on window close attempt
--command      FILE|PIPE [COMMAND...]
               Read commands from FILE or PIPE.  COMMAND for init.

The following arguments may be used as shown above:
    STOCK    ok|cancel|close|open|yes|no|apply|delete|edit|help|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 A viewer's or editor's contents are saved to this file.
    COMMAND  An internal command or executable followed by arguments. Separate
             multiple commands with a -- argument.
             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 bash command line
                 %%           %
    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, --compact or --expand options may be
added to any element.  Also, 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      [REVERSE]
               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:

    zzzfm -g ELEMENT [OPTIONS] [ARGUMENTS] \
               ELEMENT [OPTIONS] [ARGUMENTS] \
               ELEMENT [OPTIONS] [ARGUMENTS] \
               ...

For example, to show a dialog with a message label and an OK button, run this command:

    zzzfm -g --label "This is a message." \
               --button ok

OPTIONS may include options specific to the element type. In addition, most elements accept a --font FONTNAME option to specify a font for the widget's text. Also, all elements accept --compact or --expand options to force how an element is packed into the current box.

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
    # zzzFM Dialog source output - execute this output to set variables
    # Example:  eval "`zzzfm --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'

    eval "`zzzfm -g --label "This is a message." \
                      --button ok`"

After running the above command, we can see the value is set:

    echo "$dialog_pressed"
    button1

    out="`zzzfm -g --label "This is a message." \
                     --button ok`"
    eval "$out"   # read
    echo "$out"   # display

Yet another method is to write the output to a file, then source the file. For example:

    zzzfm -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.

Elements tell zzzFM Dialog how to build your dialog. Each element is similar to a command line - it includes an element followed by arguments. When zzzFM 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

--title
Usage: --title TEXT|@FILE

The --title element sets the title of the dialog window ("zzzFM Dialog" is the default title if no --title element is used). For example:

    zzzfm -g --title "A Window Title"

    echo "A Window Title" > /tmp/dialog-title
    zzzfm -g --title @/tmp/dialog-title

    echo "Another Window Title" > /tmp/dialog-title

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 ("zzzfm-48-pyramid-blue" is the default icon if no --window-icon element is used). For example:

    zzzfm -g --window-icon gtk-open

    echo "gtk-open" > /tmp/dialog-wicon
    zzzfm -g --window-icon @/tmp/dialog-wicon

    echo "gtk-save" > /tmp/dialog-wicon

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 [--wrap|--nowrap] 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:

    zzzfm -g --label "The process is complete."

    echo "The process is complete." > /tmp/dialog-label
    zzzfm -g --label @/tmp/dialog-label

    echo "Another processs is complete." > /tmp/dialog-label

As with most elements, you can add multiple --label elements to a dialog.

Some escape sequences are unescaped when LABEL is read:

For example, to create a label with two lines:

    zzzfm -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:

    zzzfm -g --label "~This is plain.  <b>This is bold.</b>"

Labels accept a --wrap or --nowrap option to specify if the text in the label is to be wrapped to multiple lines. If neither option is specified, the GTK2 default is to always wrap, and the GTK3 default is to wrap unless the label is packed into an --hbox element.

Like most elements, --label also accepts a --font option to change the font and font size of the text:

    zzzfm -g --label --font "Times New Roman 16" "The process is complete."

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|help|save|stop (in lowercase)

For example, to add a stock OK button:

    zzzfm -g --button ok

If you don't want to use a stock button, you can include a custom button label instead:

    zzzfm -g --button _Update

You can also add an icon to your button using a colon:

    zzzfm -g --button _Update:gtk-apply

    echo "_Update:gtk-apply" > /tmp/dialog-button
    zzzfm -g --button @/tmp/dialog-button

    echo "close" > /tmp/dialog-button

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 enable your script to determine what button was pressed. For example:

    dialog_pressed='button1'
    dialog_pressed_index='0'
    dialog_pressed_label='_Update:gtk-apply'

    #!/bin/bash
    # This script shows a Yes/No dialog
    # Use QUOTED eval to read variables output by zzzFM Dialog:
    eval "`zzzfm -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: The stock 'cancel' button has a special function. If it is used to close the dialog (no COMMAND has been associated with the button), element @FILE values will NOT be saved. In this case, the element values written to stdout may not match the values stored in @FILEs. You can perform a source command first if you do want values to be written for @FILEs when Cancel is clicked.

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. Also, element @FILE values will NOT be saved, as if the user clicked a Cancel button.

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.

    zzzfm -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 enables the user to enter text in a single-line box. This can be as simple as:

   zzzfm -g --input

   zzzfm -g --input "Some default text"

    echo "Some default text" > /tmp/dialog-input
    zzzfm -g --input @/tmp/dialog-input --button ok

    echo "Some other text" > /tmp/dialog-input

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:

   zzzfm -g --input --select 3:6 "Some default text"

--input also accepts a --font option to change the font and font size of the text:

    zzzfm -g --input --font "Times New Roman 16" "Some default text"

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 zzzFM 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.

    zzzfm -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 [SAVEFILE]

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:

    zzzfm -g --viewer /etc/fstab

    zzzfm -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:
    zzzfm -g --viewer /tmp/dialog-pipe

    echo "some text to a pipe" > /tmp/dialog-pipe

    # Press Ctrl-C to cancel:
    while (( 1 )); do date > /tmp/dialog-pipe; sleep 1; done

    zzzfm -g --viewer /tmp/dialog-pipe /tmp/dialog-pipe-contents \
               --button ok

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'). Also note that the contents of the viewer are also saved to SAVEFILE whenever the internal command source is run.

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.

    zzzfm -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:

    zzzfm -g --editor

    zzzfm -g --editor /etc/fstab

    zzzfm -g --editor /etc/fstab /tmp/fstab-edited \
               --button ok

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 with any button except Cancel.

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).

    zzzfm -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, enabling 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:

    zzzfm -g --check "Option One"

    zzzfm -g --check "Option One" 1

    echo 1 > /tmp/dialog-check
    zzzfm -g --check "Option One" @/tmp/dialog-check \
               --button ok

    echo 0 > /tmp/dialog-check

Also, when the dialog is closed with any button except Cancel, 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 zzzFM 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.

    zzzfm -g --check "Show text" 1 show label1 %v \
               --label "Some text"

--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, enabling 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:

    zzzfm -g --radio "Apples"

    zzzfm -g --radio "Apples" 1

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:

    zzzfm -g --radio "Apples"    \
               --radio "Oranges" 1 \
               --radio "Pears"

As with --check elements, a @FILE may be substituted for VALUE, causing zzzFM 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:

    zzzfm -g --radio "Apples"  @/tmp/dialog-radio1 \
               --radio "Oranges" @/tmp/dialog-radio2 \
               --radio "Pears"   @/tmp/dialog-radio3 \
               --button ok

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 zzzFM 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:

    zzzfm -g --icon gtk-open

    echo "gtk-open" > /tmp/dialog-icon
    zzzfm -g --icon @/tmp/dialog-icon

    echo "gtk-close" > /tmp/dialog-icon

If a command is included, the COMMAND(s) will be run whenever the icon is clicked. For example:

    zzzfm -g --icon gtk-open bash -c 'echo "# %n clicked %v" >&2'

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:

    zzzfm -g --image ~/example-image.jpg

    echo "~/example-image.jpg" > /tmp/dialog-image
    zzzfm -g --image @/tmp/dialog-image

    echo "~/another-image.jpg" > /tmp/dialog-image

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:

    zzzfm -g --image ~/example-image.jpg bash -c 'echo "# %n clicked %v" >&2'

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:

    zzzfm -g --progress

    zzzfm -g --progress @/tmp/dialog-progress

    echo 50 > /tmp/dialog-progress

    echo pulse > /tmp/dialog-progress

    echo auto-pulse > /tmp/dialog-progress

    echo "25 % copying" > /tmp/dialog-progress

    echo "75 " > /tmp/dialog-progress

    echo "text" > /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 zzzFM 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.)

--drop
Usage: --drop {TEXT... --}|@FILE [DEFAULT|+N|@FILE [COMMAND...]]

A --drop element adds a drop-down list to the dialog, enabling the user to select a single option or item in the list.

The contents of the list can be passed to zzzFM Dialog as arguments on the command line or as a file. To pass the list on the command line:

    zzzfm -g --drop "Item One" "Item Two" "Item Three" --

To select a default item, add it to the command line after '--':

    zzzfm -g --drop "Item One" "Item Two" "Item Three" -- "Item Two"

    zzzfm -g --drop "Item One" "Item Two" "Item Three" -- +1

    # First, create a text file containing multiple lines of text:
    echo -e "Item One\nItem Two\nItem Three" > /tmp/dialog-drop
    # Tell zzzfm to load the drop list from a file:
    zzzfm -g --drop @/tmp/dialog-drop

    zzzfm -g --drop @/tmp/dialog-drop +1

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
    zzzfm -g --drop @/tmp/dialog-drop @/tmp/dialog-dropdef \
               --button ok

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 zzzFM 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. To run a command when the text entry box of a --combo element gets focus, add a --click element.

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 zzzFM 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 enables 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:

    zzzfm -g --list "Item One" "Item Two" "Item Three" --

    #!/bin/bash
    # This script creates a list from an array

    alist=( "Item One" "Item Two" "Item Three" )
    eval "`zzzfm -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

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 zzzfm to load the list from a file:
    zzzfm -g --list @/tmp/dialog-list

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:

    zzzfm -g --list ^Letter A B C ^Number 1 2 3 --

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:

    zzzfm -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

    zzzfm -g --list @/tmp/dialog-list

^Job
A
B
C
^Number:int
1
2
3
^Complete:progress
35
75
90

    zzzfm -g --list @/tmp/dialog-list

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. To detect single clicks in a list (item selection), add a --click element.

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 zzzFM 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

    zzzfm -g --list @/tmp/dialog-list bash -c 'echo "# %n = %v" >&2'

--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 zzzFM 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 "`zzzfm -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

--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, enabling 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 enable the user to select a file which already exists:

     zzzfm -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:

     zzzfm -g --chooser /etc/fstab

The default file or directory can also be read from a file. For example:

    echo "/etc/fstab" > /tmp/dialog-chooser
    zzzfm -g --chooser @/tmp/dialog-chooser \
               --button ok

To enable the user to select multiple files, add the --multi option (all options must precede any arguments):

     zzzfm -g --chooser --multi /etc

To permit the user to select a directory which already exists:

     zzzfm -g --chooser --dir

     zzzfm -g --chooser --dir --multi

To enable the user to select an existing file, or enter a filename that doesn't exist (to save a file, for example):

     zzzfm -g --chooser --save

To enable the user to select an existing directory, or enter a directory name that doesn't exist (to create a directory, for example):

     zzzfm -g --chooser --dir --save

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 permit the user to choose only files with MIME type "text/plain":

     zzzfm -g --chooser --filter text/plain

     zzzfm -g --chooser --filter '*.avi'

     zzzfm -g --chooser --filter '*.avi' --filter video/x-matroska

     zzzfm -g --chooser --filter '*.avi:*.mpg:video/*'

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 zzzFM 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.

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 zzzFM 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:

    zzzfm -g --prefix var

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
    zzzfm -g --prefix @/tmp/dialog-prefix

--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:

    zzzfm -g --window-size 800x600

Or, to only set a minimum width of 800, leaving the height at the default:

    zzzfm -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:

    zzzfm -g --window-size "800x600 10"

The minimum window size and padding can also be read from a file:

    zzzfm -g --window-size @/tmp/dialog-wsize \
               --button ok

    echo 500x500 > /tmp/dialog-wsize

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 zzzFM 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 enable to you create more sophisticated-looking dialogs. Instead of all elements being stacked vertically in the dialog, one after another, boxes also enable 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:

    zzzfm -g --hbox \
               --free-button "Button1" \
               --free-button "Button2" \
               --free-button "Button3"

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:

    zzzfm -g --hbox \
               --free-button "Button1" \
               --free-button "Button2" \
               --free-button "Button3" \
               --close-box \
               --free-button "Button4" \
               --free-button "Button5"

    zzzfm -g --hbox --compact \
               --free-button "Button1" \
               --free-button "Button2" \
               --free-button "Button3" \
               --close-box \
               --free-button "Button4" \
               --free-button "Button5"

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:

    zzzfm -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:

    zzzfm -g --free-button "Button1" \
               --free-button "Button2" \
               --free-button "Button3"

    # Produces the same dialog as:

    zzzfm -g --vbox \
               --free-button "Button1" \
               --free-button "Button2" \
               --free-button "Button3"

    zzzfm -g --hbox \
               --list AAA BBB CCC \
               --vbox \
               --check "Option Alpha" \
               --check "Option Beta" \
               --check "Option Gamma"

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:

    zzzfm -g --hbox \
               --list AAA BBB CCC \
               --vbox \
               --check "Option Alpha" \
               --check "Option Beta" \
               --check "Option Gamma" \
               --close-box \
               --close-box \
               --drop item

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:

    zzzfm -g --hbox \
               --list AAA BBB CCC \
               --vbox --compact \
               --check "Option Alpha" \
               --check "Option Beta" \
               --check "Option Gamma" \
               --close-box \
               --close-box \
               --drop item

    zzzfm -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:

    zzzfm -g --label "Press Ctrl+K" \
               --keypress 0x6b 0x4 bash -c 'echo "# %n %v" >&2' -- \
                                   set label1 "You pressed Ctrl+K"

Keycodes and modifiers may be obtained using zzzFM's Design Mode Key Shortcut setting. Right-click on a menu or toolbar item in zzzFM and select Key Shortcut. 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.

--click
Usage: --click COMMAND...

A --click element will run the COMMAND(s) when some elements are clicked, focused, or change value.

For --label, --input, --input-large, --password, --editor, and --viewer elements, COMMAND will be run whenever the element gets focus (is clicked or focused with keyboard).

For --drop, --combo, --list, --mlist, and --chooser elements, COMMAND will be run whenever a selection is chosen, or a --combo element's text entry box gets focus.

For other element types that get focus, COMMAND will not be run.

In commands, the value of a --click element (eg %v, %click1) will equal the name of the element that was focused, a space, and one or more space-separated values for the element.

For example, to print the value of whatever element is clicked:

    zzzfm -g --label "Click HERE" \
               --list 111 222 333 -- \
               --input \
               --click bash -c 'echo "%v" >&2'

Multiple --click elements can be added to a dialog. Each one can run a different command when there is a click. Or, a single --click element can run multiple commands, like any element.

Note that %v is passed to the command line as a single argument containing multiple quoted arguments. Thus you will generally want to run it through bash in order to expand the arguments into $1, $2, etc., even when running a script. This will also enable correct handling of filenames containing spaces, etc. For example, consider this script:

    #!/bin/bash

    echo "NAME: $1" >&2
    name="$1"
    shift

    if [ "$name" == "chooser1" ]; then
        md5sum "$@" >&2
    fi

    zzzfm -g --chooser --multi --label Nothing \
               --click bash -c 'md5.sh "%v"'

--window-close
Usage: --window-close COMMAND...

A --window-close element runs COMMAND when the user attempts to close the dialog (usually by clicking the 'X' button in the upper right corner or using Alt-F4, etc.) The window closure will be inhibited, but COMMAND can be used to close it conditionally.

For example:

    zzzfm -g --label "You can't close this window unless you enter text:" \
               --input \
               --window-close close %input1

--command
Usage: --command FILE|PIPE [COMMAND...]

A --command element causes zzzFM Dialog to monitor a regular file or a pipe for internal commands. For example, to monitor a regular file:

    zzzfm -g --command /tmp/dialog-cmd

    echo "set title A Window Title" > /tmp/dialog-cmd

Or, to monitor a pipe:

    # First create the pipe:
    mkfifo /tmp/dialog-cmdpipe
    zzzfm -g --command /tmp/dialog-cmdpipe

    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

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.)

One or more commands may be associated with a zzzFM 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). zzzFM 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:

    zzzfm -g --label "Press Button" \
               --button "Button" set label1 "Button was pressed" -- \
                                 bash -c 'echo "# Button %n was pressed" >&2'

Although commands are run in the order presented, note that external commands are run asynchronously. zzzFM 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 zzzFM 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
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 zzzFM 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 bash command line synchronously, and is substituted with the stdout output of the command. For example:

    zzzfm -g --label \
               --button 'Get Date' set label1 '%(date +%%D)'

IMPORTANT: Because the %(command) command line is run synchronously, zzzFM 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. For example:

zzzfm -g --check Option 0                                                     \
                   set label1 '%( echo -n Option is\ ;                          \
                                  (( %v )) && echo checked || echo unchecked )' \
           --label "Option is unchecked"

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:

    zzzfm -g --button ok noop

    zzzfm -g --button ok noop '%(myscript)' -- close

close
Usage: close [REVERSE]

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.

REVERSE, if supplied and equal to "", "0", or "false", causes the close command to do nothing. This can be used with the value from another element, for example, to make the close command conditional. For example:

    zzzfm -g --label "You can't close this window unless you enter text:" \
               --input \
               --window-close close %input1

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:

    zzzfm -g --icon gtk-ok press button1 \
               --button ok

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:

    zzzfm -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:

    zzzfm -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:

    zzzfm -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.

If no NAME argument is included, the dialog window is presented (this may mean raising the window in the stacking order, deiconifying it, and/or moving it to the current desktop, depending on window manager settings).

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).

If no NAME argument is included, the dialog window is presented (this may mean raising the window in the stacking order, deiconifying it, and/or moving it to the current desktop, depending on window manager settings).

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:

    zzzfm -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):

    zzzfm -g --label "Select a function and click OK:"           \
               --drop "Function A" "Function B" "Function C" -- "" \
                      enable button1 %v                            \
               --button ok                                         \
               --command "" disable button1

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 by the user pressing a button other than Cancel. It also saves the contents of an --editor or --viewer element to SAVEFILE.

If FILE is omitted or equals "", the output is written to stderr by the dialog process (useful for debugging). To run source with no output use 'source /dev/null'.

zzzFM socket commands enable external processes (including custom commands) to easily communicate with a running instance of zzzFM. They can be used to gather information about the state of the GUI, make changes to the GUI, and to run utility commands. When used in event handlers, socket commands can respond to various events in the zzzFM window.

When a user's first instance of zzzFM is started, either by the user opening a window, starting a daemon instance, or starting a desktop manager daemon instance, a socket is created in /tmp for this instance. This socket is used by zzzFM to open additional windows or tabs, and is also used to process socket commands. This enables other processes owned by the same user to communicate with the running instance.

For example, socket commands can be used to record or change the size of a zzzFM window; show or hide panels or side panes; resize panels, panes, and columns; select files in a given window, panel, or tab; place text or files on the clipboard; read text or files from the clipboard; place text in a panel's status bar; update the progress bar and other information displayed about running tasks, and much more.

To send a socket command and receive any reply, run zzzFM with the -s (--socket-cmd) option. Any reply will be written to stdout and any errors or warnings to stderr. If an error occurs, the exit status will be set.

Help Reference

To see the help reference for zzzFM's socket commands, run:

$ zzzfm -s help
zzzFM socket commands permit external processes (such as command scripts)
to read and set GUI property values and execute methods inside running zzzFM
windows.  To handle events see View|Event Manager in the main menu bar.

Usage:
    zzzfm --socket-cmd|-s METHOD [OPTIONS] [ARGUMENT...]
Example:
    zzzfm -s set window_size 800x600

METHODS
-------
zzzfm -s set [OPTIONS] PROPERTY [VALUE...]
    Sets a property

zzzfm -s get [OPTIONS] PROPERTY
    Gets a property

zzzfm -s set-task [OPTIONS] TASKID TASKPROPERTY [VALUE...]
    Sets a task property

zzzfm -s get-task [OPTIONS] TASKID TASKPROPERTY
    Gets a task property

zzzfm -s run-task [OPTIONS] TASKTYPE ARGUMENTS
    Starts a new task

zzzfm -s emit-key [OPTIONS] KEYCODE [MODIFIER]
    Activates an item by emitting its shortcut key

zzzfm -s activate [OPTIONS] NAME
    Runs custom command or shows submenu named NAME

zzzfm -s add-event EVENT COMMAND ...
    Add asynchronous handler COMMAND to EVENT

zzzfm -s replace-event EVENT COMMAND ...
    Add synchronous handler COMMAND to EVENT, replacing default handler

zzzfm -s remove-event EVENT COMMAND ...
    Remove handler COMMAND from EVENT

zzzfm -s help|--help
    Shows this help reference.

OPTIONS
-------
Add options after METHOD to specify a specific window, panel, and/or tab.
Otherwise the current tab of the current panel in the last window is used.

--window WINDOWID
    Specify window.  eg: zzzfm -s set --window 0x104ca80 window_size 800x600
--panel PANEL
    Specify panel 1-4.  eg: zzzfm -s set --panel 2 bookmarks_visible true
--tab TAB
    Specify tab 1-...  eg: zzzfm -s set --tab 3 selected_filenames fstab

PROPERTIES
----------
Set properties with METHOD 'set', or get the value with 'get'.

window_size                     eg '800x600'
window_position                 eg '100x50'
window_maximized                1|true|yes|0|false|no
window_fullscreen               1|true|yes|0|false|no
screen_size                     eg '1024x768'  (read-only)
window_vslider_top              eg '100'
window_vslider_bottom           eg '100'
window_hslider                  eg '100'
window_tslider                  eg '100'
focused_panel                   1|2|3|4|prev|next|hide
focused_pane                    filelist|devices|bookmarks|dirtree|pathbar
current_tab                     1|2|...|prev|next|close
tab_count                       1|2|...
new_tab                         [DIR]    Open DIR or default in a new tab
devices_visible                 1|true|yes|0|false|no
bookmarks_visible               1|true|yes|0|false|no
dirtree_visible                 1|true|yes|0|false|no
toolbar_visible                 1|true|yes|0|false|no
sidetoolbar_visible             1|true|yes|0|false|no
hidden_files_visible            1|true|yes|0|false|no
panel1_visible                  1|true|yes|0|false|no
panel2_visible                  1|true|yes|0|false|no
panel3_visible                  1|true|yes|0|false|no
panel4_visible                  1|true|yes|0|false|no
panel_hslider_top               eg '100'
panel_hslider_bottom            eg '100'
panel_vslider                   eg '100'
column_width                    name|size|type|permission|owner|modified WIDTH
sort_by                         name|size|type|permission|owner|modified
sort_ascend                     1|true|yes|0|false|no
sort_natural                    1|true|yes|0|false|no
sort_case                       1|true|yes|0|false|no
sort_hidden_first               1|true|yes|0|false|no
sort_first                      files|folders|mixed
show_thumbnails                 1|true|yes|0|false|no
large_icons                     1|true|yes|0|false|no
statusbar_text                  eg 'Current Status: Example'
pathbar_text                    [TEXT [SELSTART [SELEND]]]
current_dir                     DIR            eg '/etc'
selected_filenames              [FILENAME ...]
selected_pattern                [PATTERN]      eg '*.jpg'
clipboard_text                  eg 'Some\nlines\nof text'
clipboard_primary_text          eg 'Some\nlines\nof text'
clipboard_from_file             eg '~/copy-file-contents-to-clipboard.txt'
clipboard_primary_from_file     eg '~/copy-file-contents-to-clipboard.txt'
clipboard_copy_files            FILE ...  Files copied to clipboard
clipboard_cut_files             FILE ...  Files cut to clipboard

TASK PROPERTIES
---------------
status                          contents of Status task column  (read-only)
icon                            eg 'gtk-open'
count                           text to show in Count task column
folder                          text to show in Folder task column
item                            text to show in Item task column
to                              text to show in To task column
progress                        Progress percent (1..100) or '' to pulse
total                           text to show in Total task column
curspeed                        text to show in Current task column
curremain                       text to show in CRemain task column
avgspeed                        text to show in Average task column
avgremain                       text to show in Remain task column
elapsed                         contents of Elapsed task column (read-only)
started                         contents of Started task column (read-only)
queue_state                     run|pause|queue|stop
popup_handler                   COMMAND  command to show a custom task dialog

TASK TYPES
----------
cmd [--task] [--popup] [--scroll] [--terminal] [--icon ICON] \
    [--dir DIR] COMMAND...      Run COMMAND as USER in DIR
copy|move|link [--dir DIR] FILE|DIR... TARGET
                                Copy|Move|Link FILE(s) or DIR(s) to TARGET dir
delete [--dir DIR] FILE|DIR...  Recursively delete FILE(s) or DIR(s)
edit [--as-root] FILE           Open FILE in user's or root's text editor



mount DEVICE|URL                Mount DEVICE or URL
unmount DEVICE|DIR              Unmount DEVICE or mount point DIR

EVENTS
------
evt_start                       Instance start        %e
evt_exit                        Instance exit         %e
evt_win_new                     Window new            %e %w %p %t
evt_win_focus                   Window focus          %e %w %p %t
evt_win_move                    Window move/resize    %e %w %p %t
evt_win_click                   Mouse click           %e %w %p %t %b %m %f
evt_win_key                     Window keypress       %e %w %p %t %k %m
evt_win_close                   Window close          %e %w %p %t
evt_pnl_focus                   Panel focus           %e %w %p %t
evt_pnl_show                    Panel show/hide       %e %w %p %t %f %v
evt_pnl_sel                     Selection changed     %e %w %p %t
evt_tab_new                     Tab new               %e %w %p %t
evt_tab_chdir                   Tab change dir        %e %w %p %t %d
evt_tab_focus                   Tab focus             %e %w %p %t
evt_tab_close                   Tab close             %e %w %p %t
evt_device                      Device change         %e %f %v

Event COMMAND Substitution Variables:
%e   event name (evt_start|evt_exit|...)
%w   window ID
%p   panel number (1-4)
%t   tab number (1-...)
%d   quoted directory ('/etc')
%b   mouse button (0=double 1=left 2=middle 3=right ...
%k   key code  (eg 0x63)
%m   modifier key (eg 0x4  used with clicks and keypresses)
%f   focus element (panelN|filelist|devices|bookmarks|dirtree|pathbar)
%v   focus element is visible (0 or 1, or device state change)

Examples:

    window_size="$(zzzfm -s get window_size)"
    zzzfm -s set window_size 1024x768
    zzzfm -s set column_width name 100
    zzzfm -s set-task $fm_my_task progress 25
    zzzfm -s run-task --window $fm_my_window cmd --task --popup ls /etc
    zzzfm -s run-task copy --dir /etc fstab hosts /destdir
    zzzfm -r /etc; sleep 0.3; zzzfm -s set selected_filenames fstab hosts
    zzzfm -s set clipboard_copy_files /etc/fstab /etc/hosts
    zzzfm -s emit-key 0xffbe 0   # press F1 to show Help
    zzzfm -s activate --window $fm_my_window "Custom Menu"
    zzzfm -s add-event evt_pnl_sel 'zzzfm -s set statusbar_text "$fm_file"'

    #!/bin/bash
    eval copied_files="$(zzzfm -s get clipboard_copy_files)"
    echo "These files have been copied to the clipboard:"
    i=0
    while [ "${copied_files[i]}" != "" ]; do
        echo "    ${copied_files[i]}"
        (( i++ ))
    done
    if (( i != 0 )); then
        echo "MD5SUMS:"
        md5sum "${copied_files[@]}"
    fi

Methods represent different kinds of socket commands:

set
Usage: zzzfm -s set [OPTIONS] PROPERTY [VALUE...]

The set method sets a property to one or more values. Different properties accept different kinds of values. To see what values a property accepts, look the property up in the Help Reference.

As with all methods, by default the set method will apply to the current tab in the current panel of the last used zzzFM window. You can also specify a particular window, panel, and/or tab using the --window, --panel, and/or --tab OPTIONS. (The WINDOWID used by the --window option is obtained from the $fm_my_window bash variable.) For example:

    zzzfm -s set --window $fm_my_window --panel 3 --tab 2 pathbar_text "/"

Examples using the set method:

    # Set the size of the last used zzzFM window:
    zzzfm -s set window_size 1024x768

    # Set the size of my tasks's zzzFM window
    zzzfm -s set --window $fm_my_window window_size 1024x768

    # Maximize the window:
    zzzfm -s set window_maximized 1

    # Show panel 3:
    zzzfm -s set panel3_visible true

    # Focus panel 3:
    zzzfm -s set focused_panel 3

    # Hide the Dir Tree:
    zzzfm -s set dirtree_visible 0

    # Set the position of the vertical slider between panels 1 and 2:
    zzzfm -s set window_vslider_top 400

    # Set the width of the Name column:
    zzzfm -s set column_width name 100

    # Set the text in panel 2's status bar:
    zzzfm -s set --panel 2 statusbar_text "Custom Status"

    # Remove the custom text in panel 2's status bar:
    zzzfm -s set --panel 2 statusbar_text

    # Set the text in the pathbar:
    zzzfm -s set pathbar_text "/etc"

    # Set the text in the pathbar and select it:
    zzzfm -s set pathbar_text "/etc" 0

    # Focus the pathbar (put cursor there):
    zzzfm -s set focused_pane pathbar

    # Change to directory '/etc':
    zzzfm -s set current_dir '/etc'

    # Select files named 'fstab' and 'hosts', unselect others:
    zzzfm -s set selected_files 'fstab' 'hosts'

    # Unselect all files:
    zzzfm -s set selected_files

    # Select all files:
    zzzfm -s set selected_pattern '*'

    # Select all jpg files, unselect others:
    zzzfm -s set selected_pattern '*.jpg'

    # Copy text to the clipboard:
    zzzfm -s set clipboard_text 'Some text'

    # Copy multiple lines of text to the clipboard:
    zzzfm -s set clipboard_text 'Some\nlines\nof text'

    # Copy the contents of a text file to the clipboard:
    zzzfm -s set clipboard_from_file /etc/fstab

    # Copy text to the primary (middle-click) clipboard:
    zzzfm -s set clipboard_primary_text 'Some primary text'

    # Copy files to the clipboard:
    zzzfm -s set clipboard_copy_files /etc/fstab /etc/hosts

    # Cut files to the clipboard:
    zzzfm -s set clipboard_cut_files /etc/fstab /etc/hosts

    # Adjust sort settings:
    zzzfm -s set sort_by size
    zzzfm -s set sort_by name
    zzzfm -s set sort_ascend false
    zzzfm -s set sort_natural true
    zzzfm -s set sort_first directories

get
Usage: zzzfm -s get [OPTIONS] PROPERTY

The get method gets a property's value. The reply is written to stdout.

As with all methods, by default the get method will apply to the current tab in the current panel of the last used zzzFM window. You can also specify a particular window, panel, and/or tab using the --window, --panel, and/or --tab OPTIONS.

The reply to a get can be saved in a bash variable directly:

    size="$(zzzfm -s get window_size)"
    echo "$size"

    if [ "$(zzzfm -s get clipboard_text)" == "" ]; then
        echo "The clipboard is empty"
    fi

Examples using the get method:

    # Is the window maximized?
    zzzfm -s get window_maximized

    # Is panel 3 shown?
    zzzfm -s get panel3_visible

    # Which panel is focused?
    zzzfm -s get focused_panel

    # Is the Bookmarks pane shown in panel 4?
    zzzfm -s get --panel 4 bookmarks_visible

    # Get the position of the vertical slider between panels 1 and 2:
    zzzfm -s get window_vslider_top

    # Get the width of the Size column:
    zzzfm -s get column_width size

    # Get the text in panel 2's status bar:
    zzzfm -s get --panel 2 statusbar_text

    # Get the current directory of tab 2:
    zzzfm -s get --tab 2 current_dir

    # Get the text on the clipboard:
    zzzfm -s get clipboard_text

    # Get the text on the clipboard and write it to a file:
    zzzfm -s get clipboard_text > /tmp/clipboard-contents.txt

Or, when getting the value of clipboard_copy_files or clipboard_cut_files, zzzFM will reply with an array of quoted paths. For example:

    # First copy some files to the clipboard:
    zzzfm -s set clipboard_copy_files /etc/fstab /etc/hosts

    # Now get the files on the clipboard:
    zzzfm -s get clipboard_copy_files
    ('/etc/fstab' '/etc/hosts' )

    #!/bin/bash
    # Read the copied files into an array:
    eval copied_files="$(zzzfm -s get clipboard_copy_files)"

    echo "These files have been copied to the clipboard:"
    i=0
    while [ "${copied_files[i]}" != "" ]; do
        echo "    ${copied_files[i]}"
        (( i++ ))
    done
    if (( i != 0 )); then
        echo "MD5SUMS:"
        md5sum "${copied_files[@]}"
    fi

Traditionally, when cut files are successfully copied to another location, you should then delete them from their original location, whereas files which have merely been copied to the clipboard are never deleted.

Likewise, when getting the value of selected_filenames, zzzFM will reply with an array of quoted filenames. For example:

    #!/bin/bash
    # Read the selected filenames into an array:
    eval sel_files="$(zzzfm -s get selected_filenames)"

    echo "These filenames are selected:"
    i=0
    while [ "${sel_files[i]}" != "" ]; do
        echo "    ${sel_files[i]}"
        (( i++ ))
    done
    if (( i != 0 )); then
        cd "$(zzzfm -s get current_dir)"
        echo "MD5SUMS:"
        md5sum "${sel_files[@]}"
    fi

set-task
Usage: zzzfm -s set-task [OPTIONS] TASKID TASKPROPERTY [VALUE...]

The set-task method is used to change the display values for a task, and also to stop, pause, queue, or resume a task, by setting a task property. Different task properties accept different kinds of values. To see what values a task property accepts, look the task property up in the Help Reference.

Display values for a task are shown in the Task Manager, and also in task popup dialogs. These include such things as the Item, Total, Current, Remain, and other columns, the progress bar percentage, etc.

As with all methods, by default the set-task method will apply to the current tab in the current panel of the last used zzzFM window. You can also specify a particular window, panel, and/or tab using the --window, --panel, and/or --tab OPTIONS.

The set-task method requires a TASKID, which indicates what task is being modified. There are two ways to obtain the TASKID. One is to use the exported bash variable $fm_my_task, which refers to the current command task. The other is to use $fm_task_id, which refers to the task currently selected in the task list when the current task is run. Note that a TASKID is only valid in the window in which the task is currently running, so it's generally appropriate to specify a WINDOWID ($fm_my_window) with the --window option to ensure the correct window is accessed.

Note that when using $fm_my_task, the TASKID will not be valid when the command is first run - it usually takes about a half second for a task to appear in the task manager. If your script uses $fm_my_task immediately, it should plan for the socket command to fail until the task is shown in the task manager, or it can use a small delay (sleep 0.75) before sending task-related socket commands.

Also, if a custom command is run from the zzzFM desktop manager menu, note that there is no task manager or window associated with the task, so the TASKID will not be valid in socket commands.

Examples using the set-task method:

    # Set my task's progress bar to 25%:
    zzzfm -s set-task --window $fm_my_window $fm_my_task progress 25

    # Set the current item being processed in my task:
    zzzfm -s set-task --window $fm_my_window $fm_my_task item "File 2"

    # Set the average speed displayed for my task (any text is valid):
    zzzfm -s set-task --window $fm_my_window $fm_my_task avgspeed "10 M/s"

    # Pause my task:
    zzzfm -s set-task --window $fm_my_window $fm_my_task queue_state pause

    #!/bin/bash
    # Set a custom task dialog in zzzFM.
    # Run this script as a zzzFM custom command script.
    $fm_import

    # make a command pipe to talk to the dialog
    cmdpipe=/tmp/zzzfm-task-dialog.pipe
    rm -f "$cmdpipe"
    mkfifo "$cmdpipe"

    # must wait for this task to be shown in manager before setting property
    ( sleep .75; \
      zzzfm -s set-task $fm_my_task popup_handler "echo show > '$cmdpipe'" ) &

    # show dialog
    zzzfm -g --label "\nThis window will be shown when you click on this \
    task in zzzFM's Task Manager." \
               --button close rm "$cmdpipe" -- close \
               --command "$cmdpipe" \
               --window-close rm "$cmdpipe" -- close > /dev/null

    # cleanup
    zzzfm -s set-task $fm_my_task popup_handler
    rm -f "$cmdpipe"
    exit

When popup_handler is set, the additional Show Output menu item will appear in the right-click context menu for the task, which opens the normal popup dialog.

get-task
Usage: zzzfm -s get-task [OPTIONS] TASKID TASKPROPERTY

The get-task method gets a task property's value. The reply is written to stdout. For instructions on saving the reply to a variable or testing it directly, see the examples in get.

As with the set-task method, get-task requires a TASKID, and passing a WINDOWID is also recommended.

Examples using the get-task method:

    # Get my task's progress bar value:
    zzzfm -s get-task --window $fm_my_window $fm_my_task progress

    # Get the current status of my task (this is a read-only value):
    zzzfm -s get-task --window $fm_my_window $fm_my_task status

    # Get the running state of my task (run|pause|queue):
    zzzfm -s get-task --window $fm_my_window $fm_my_task queue_state

run-task
Usage: zzzfm -s run-task [OPTIONS] TASKTYPE [TYPEOPTIONS] ARGUMENTS

The run-task method is used to tell a running zzzFM window to start a new task. A task may run an asynchronous command (run and forget), a command run as a zzzFM task (shown in the Task Manager if it runs for more than one half second), or an internal task to copy, move, or delete files, or create links. A task can also be used to run a command in the user's configured terminal, open a file in the user's configured text editor.

To run a task in a particular zzzFM window, or with the exported bash variables of a particular tab, --window, --panel, and --tab OPTIONS may be included.

Each TASKTYPE accepts a different set of TYPEOPTIONS and ARGUMENTS, as detailed below.

cmd [--task] [--popup] [--scroll] [--terminal] [--icon ICON] [--dir DIR] COMMAND...

The cmd (or 'command') TASKTYPE is used to run a program or bash command. Exported bash variables may be used in any COMMAND - just remember to include the $fm_import line in your command or script. Note that the contents of the variables will reflect the window, panel, and tab active for the socket command, not necessarily the focused tab of zzzFM.

By default COMMAND is run asynchronously (run and forgotten). It will not appear in the Task Manager, and no popup will be shown. For example:

    zzzfm -s run-task cmd touch /tmp/a_new_file

TYPEOPTION	Use
--task	Run COMMAND as a zzzFM task and list it in the Task Manager if it runs for more than one half second, and show a popup dialog if the command's exit status is non-zero. This is equivalent to custom command options Run As Task plus Popup Error.
--popup	Run COMMAND as a zzzFM task and show a popup dialog if the task runs for longer than one half second or produces output or an error. This is equivalent to custom command options Run As Task plus Popup Output plus Popup Error.
--scroll	If option --task or --popup is used with --scroll, the scrollbar in the popup will be moved down, equivalent to custom command option Scroll.
--terminal	Run COMMAND in the user's configured terminal emulator. This is equivalent to custom command option Run In Terminal. Generally this option is used without --task or --popup.
--icon ICON	Use ICON as the task's icon in the Task Manager and popup dialog, where ICON is an icon name or absolute path. Not all icons may be shown due to various issues.
--dir DIR	Start COMMAND in working directory DIR. If not specified, zzzFM's current working directory is used.

If the --task or --popup options are used, meaning the task is run as a zzzFM task, the command will return values for $new_task_id and $new_task_window, to be used in future socket commands for this running task. For example:

    zzzfm -s run-task cmd --popup 'while true; do date; sleep 1; done'
    #!/bin/bash
    # Note: $new_task_id not valid until approx one half second after task start
    new_task_window=0x207a030
    new_task_id=0x2343150

    eval "`zzzfm -s run-task cmd --popup 'while true; do date; sleep 1; done'`"
    echo "Task window is $new_task_window and ID is $new_task_id."
    Task window is 0x207a030 and ID is 0x23432a0.

copy|move|link [--dir DIR] FILE|DIR... TARGET

The copy, move, and link TASKTYPEs start an internal zzzFM task to copy, move, or create links to files and directories. The task will be listed in the Task Manager if it runs for longer than one half second. If files already exist in the TARGET directory, the zzzFM overwrite query dialog will be shown as usual.

FILE(s) and DIR(s) may be specified as absolute paths. Or, if the --dir DIR option is used to specify an (absolute) source directory, they may be relative to DIR. Each FILE and DIR specified must exist. TARGET, which is required as the last argument, specifies an absolute destination directory.

For example:

    zzzfm -s run-task copy /etc/fstab /etc/hosts /tmp

    zzzfm -s run-task copy --dir /etc fstab hosts /tmp

Another example, to create links to files and directories:

    zzzfm -s run-task link /etc /etc/fstab /tmp

As with the cmd TASKTYPE, copy, move, and link TASKTYPEs will output $new_task_window and $new_task_id for evaluation and later use.

delete [--dir DIR] FILE|DIR...

The delete TASKTYPE starts an internal zzzFM task to recursively delete files and directories. The task will be listed in the Task Manager if it runs for longer than one half second.

FILE(s) and DIR(s) may be specified as absolute paths. Or, if the --dir DIR option is used to specify an (absolute) source directory, they may be relative to DIR. Each FILE and DIR must exist.

WARNING: No confirmation dialog is shown to the user before files are deleted permanently. If you want a confirmation dialog, your command or script must show one itself. Also note that any specified directories are deleted recursively.

For example, to delete the links created in the previous example:

    zzzfm -s run-task delete /tmp/etc /tmp/fstab

As with the cmd TASKTYPE, the delete TASKTYPE will output $new_task_window and $new_task_id for evaluation and later use.

edit [--as-root] FILE

The edit TASKTYPE opens FILE in the user's configured text editor (set in View|Preferences|Advanced). Or, if the --as-root option is included, FILE is opened in the user's configured root editor. This task type is always asynchronous (run and forgotten). For example:

    zzzfm -s run-task edit /etc/fstab

mount DEVICE|URL

The mount TASKTYPE uses the appropriate device or protocol handler to mount a DEVICE (eg /dev/sdd1) or URL (eg ftp://mirrors.kernel.org/). This task type may produce an error pop-up message, but does not set an error status on failure. For example:

    zzzfm -s run-task mount /dev/sdd1

    zzzfm /dev/sdd1
    or
    zzzfm ftp://mirrors.kernel.org/

unmount DEVICE|DIR

The unmount TASKTYPE uses the appropriate device or protocol handler to unmount a DEVICE (eg /dev/sdd1) or mount point DIR. This task type may produce an error pop-up message, but does not set an error status on failure. For example:

    zzzfm -s run-task unmount /dev/sdd1

emit-key
Usage: zzzfm -s emit-key [OPTIONS] KEYCODE [MODIFIER]

The emit-key method activates the menu or toolbar item with the given shortcut key, as if the user had pressed the key combination.

The KEYCODE and MODIFIER for a given key combination can be seen by right-clicking on an item, selecting Key Shortcut, and pressing the key combination.

For example, to activate the menu item associated with Ctrl+C (associated with Copy by default):

    zzzfm -s emit-key 0x63 0x4

activate
Usage: zzzfm -s activate [OPTIONS] NAME

The activate method is used to activate (run) a custom command, bookmark, or application from any menu or toolbar. Or, if the named item is a custom submenu, the submenu will be shown as a popup menu.

NAME is the name of the item or submenu as it appears in the menu (underscores may be omitted). If multiple items have NAME as their name, only one will be activated. Alternatively, you can specify the internal name of the command, found in the command directory name, such as "cstm_782d52a7".

For example, add a submenu anywhere named "My Gizmos", and add one or more commands inside the submenu. To make it popup:

    zzzfm -s activate 'My Gizmos'

When using activate to open a popup menu from within an evt_win_click event handler for the file list, a small delay may be needed before the menu is shown to prevent it from closing immediately when the mouse button is released:

    *if [ "%b" != "2" ]; then exit 1; fi; ( sleep .2; zzzfm -s activate "A-C" ) &

add-event
Usage: zzzfm -s add-event EVENT COMMAND ...

The add-event method is used to dynamically add an asynchronous handler command to an event, such that when EVENT occurs, COMMAND will be run asynchronously (zzzFM won't wait for it to finish).

COMMAND is a bash command line. If any arguments follow it, they are added to the command before it is passed to bash. For all events except evt_start, evt_exit, evt_tab_close, and evt_device, the exported bash variables can be used in the command. COMMAND also accepts event substitution variables, which will vary with the event type.

add-event may be used any number of times to add additional event handler commands to the same or different event types.

Note that COMMAND will continue to run anytime EVENT occurs during the lifetime of the current zzzFM instance, so be sure to remove the handler when your script is finished using it.

In addition to adding dynamic event handlers, you can also set static event handlers using the View|Event Manager menu.

Note that a single zzzFM instance may open multiple windows, so your handler will run when events occur in any window. The handler can test for a specific window using the %w (window ID) substitution variable in the command (which will correspond to a task's $fm_my_window bash variable).

For example, the following command will add a handler to the evt_pnl_sel (selection has changed) event, such that anytime the user changes the selection of files in the file list, the status bar will be set to display the first selected file's path:

    zzzfm -s add-event evt_pnl_sel 'zzzfm -s set statusbar_text "$fm_file"'

    zzzfm -s add-event evt_pnl_sel zzzfm -s set statusbar_text \"\$fm_file\"

replace-event
Usage: zzzfm -s replace-event EVENT COMMAND ...

The replace-event method is used to dynamically add a synchronous handler command to an event, such that when EVENT occurs, COMMAND will be run synchronously (zzzFM will wait for it to finish, and will examine the exit status).

Because the command is run synchronously, zzzFM's GUI will freeze while the command is being run. Your command should return a quick exit status to make this freeze minimal, then spawn a process to continue to perform whatever actions are desired.

For event types evt_win_click (a mouse click), evt_win_key (a keypress), and evt_pnl_sel (file selection changed), zzzFM will use the exit status of your command to determine whether zzzFM's built-in handler for the event type should run after your command. If the exit status is zero, this will inhibit the built-in handler. For example, if the user clicks the right mouse button, and your command returns zero exit status, zzzFM will not show the right-click context menu normally shown by the built-in handler.

If more than one replace-event is set for a evt_win_click, evt_win_key, or evt_pnl_sel event type (including one set in the View|Event Manager menu), any zero exit status will inhibit the built-in handler.

Using replace-event to set a handler for an event type other than evt_win_click, evt_win_key or evt_pnl_sel will cause the command to run synchronously (zzzFM will wait for it and it will freeze the GUI until it exits) but the exit status will have no effect. (These events are notification only, so there is no built-in handler to inhibit.)

COMMAND is a bash command line. If any arguments follow it, they are added to the command before it is passed to bash. Exported bash variables may NOT be used in COMMAND. COMMAND also accepts event substitution variables, which will vary with the event type.

replace-event may be used any number of times to add additional synchronous event handler commands to the same or different event types.

Note that COMMAND will continue to run anytime EVENT occurs during the lifetime of the current zzzFM instance, so be sure to remove the handler when your script is finished using it.

For example, the following command will add a handler to the evt_win_click event. If the user clicks a button other than the middle mouse button (%b = 2), the command returns exit status 1, so the built-in handler is used. But if the user clicks the middle mouse button, then a dialog message is displayed, and the command returns 0 (the default status on success), inhibiting the built-in handler.

    zzzfm -s replace-event evt_win_click 'if [ "%b" != "2" ]; then exit 1; fi; \
        zzzfm -g --label "\nMiddle button was clicked" --button ok &'

remove-event
Usage: zzzfm -s remove-event EVENT COMMAND ...

The remove-event method removes an event handler previously set with the add-event or replace-event methods. You must pass remove-event the exact same EVENT and COMMAND that you passed when adding the handler.

Because all handlers continue to run for the lifetime of the current zzzFM instance, your scripts should remove all handlers they have added before finishing. When the zzzFM instance exits, all dynamic event handlers are automatically removed. (If you want dynamic handlers to always be present, use the evt_start event to add them.)

remove-event cannot remove static handlers set in the View|Event Manager menu.

Events represent actions or changes in the GUI, such as the user closing a tab, selecting a file, or opening a new window. zzzFM has built-in handlers for these events, which update the GUI, open menus, or take other actions. You can also add your own handlers for events, commands which are run to take a custom action after the event occurs. In some cases your custom handler can replace the action normally taken by zzzFM's built-in handler, enabling you to modify the default behavior in the GUI.

Event handlers can be added in the Event Manager menu. Those handler commands always run until you remove them. Dynamic event handlers can also be added using the add-event or replace-event socket methods. These handlers will remain in effect until you remove them with the remove-event method, or until the zzzFM instance exits.

The following events are available. The name in parentheses is the event name as found in the Event Manager menu. Any event substitution variables available with the event are shown after it (eg %e).

evt_start (Instance|Start) %e
Occurs only once per instance when the zzzFM instance first starts. Note that a single zzzFM instance may open multiple windows. This is a good event to use to add any dynamic event handlers which you always want running.

evt_exit (Instance|Exit) %e
Occurs only once per instance when the zzzFM instance exits. If a daemon or desktop manager instance is running, this event will occur when the user logs out. Otherwise, the instance will exit when the last zzzFM window is closed.

evt_win_new (Window|New) %e %w %p %t
Occurs whenever a new zzzFM window is opened, including the initial window.

evt_win_focus (Window|Focus) %e %w %p %t
Occurs whenever a zzzFM window receives focus. For example, if you switch to another window in your window manager, then switch back to a zzzFM window, this event will occur.

evt_win_move (Window|Move) %e %w %p %t
Occurs whenever a zzzFM window is moved or resized. Note that during resizing, any handler for this event may be run multiple times (up to five times per second).

evt_win_click (Window|Click) %e %w %p %t %b %m %f
Occurs when the user clicks the mouse in most areas of a zzzFM window. The mouse button pressed is available via the substitution variable %b, any key modifier (eg Ctrl+Click) via %m, and the window element which received the click via %f.

If a handler set for the evt_win_click event is synchronous (has an asterisk prefix or is added with the replace-event method), and it returns a zero exit status, the built-in handler for the event will be inhibited.

When using activate to show a popup menu from within an evt_win_click event handler, a small delay may be needed before the menu is shown to prevent it from closing immediately when the mouse button is released:

    *if [ "%b" != "2" ]; then exit 1; fi; ( sleep .2; zzzfm -s activate "A-C" ) &

evt_win_key (Window|Keypress) %e %w %p %t %k %m
Occurs when the user presses a key in most areas of a zzzFM window. The key code pressed is available via the substitution variable %k, and any key modifier (eg Ctrl+C) via %m.

If a handler set for the evt_win_key event is synchronous (has an asterisk prefix or is added with the replace-event method), and it returns a zero exit status, the built-in handler for the event will be inhibited (zzzFM will not react to the keypress in most cases, even if it's assigned to a menu item).

evt_win_close (Window|Close) %e %w %p %t
Occurs whenever a zzzFM window is closed, including the last window of the instance.

evt_pnl_focus (Panel|Focus) %e %w %p %t
Occurs whenever a panel gets focus. Any handler command for this event will be run whenever a user clicks in the panel, even if the panel is not changed. The command will also be run if the user switches focus to another panel.

evt_pnl_show (Panel|Show) %e %w %p %t %f %v
Occurs whenever a panel or panel element is shown or hidden. The element shown or hidden is available via the substitution variable %f (panelN|filelist|devices|bookmarks|dirtree|pathbar), and the element's visibility (shown or hidden) is available via %v (1=shown or 0=hidden).

evt_pnl_sel (Panel|Select) %e %w %p %t
Occurs whenever the file selection in a panel changes.

If a handler set for the evt_pnl_sel event is synchronous (has an asterisk prefix or is added with the replace-event method), and it returns a zero exit status, the built-in handler for the event will be inhibited. (The built-in handler for evt_pnl_sel updates the contents of the panel's status bar, so if you want to handle this yourself, you can inhibit it.)

evt_tab_new (Tab|New) %e %w %p %t
Occurs whenever a new tab is added to a panel, including initial tabs when the window is opened or the panel is first shown.

evt_tab_chdir (Tab|Change Dir) %e %w %p %t %d
Occurs whenever a tab changes directory, such as when a new tab opens, or the user navigates to a different directory. %d will be replaced with the quoted new directory of the tab.

evt_tab_focus (Tab|Focus) %e %w %p %t
Occurs whenever a tab gets focus within a panel. For example, changing tabs will trigger this event. However, merely switching panels wil trigger the evt_pnl_focus event, but not evt_tab_focus.

evt_tab_close (Tab|Close) %e %w %p %t
Occurs whenever a tab is closed. The tab number which was closed is available via the substitution variable %t, and its panel via %p. (Note that closing a tab changes panel focus to the panel containing the tab being closed.)

Note that exported bash variables cannot be used in the handler commands for evt_tab_close.

evt_device (Device) %e %f %v
Occurs whenever a device is added, removed, or otherwise changes state (mounted, unmounted, media inserted, etc). The device file is available via the substitution variable %f, and the change via %v (added|removed|changed).

Note that exported bash variables cannot be used in the handler commands for evt_device.

The Event Manager submenu, located in the main menu bar's View menu, is used to configure static event handler commands to be run when events occur. Each item in this menu opens a dialog in which a program name or bash command line can be entered. The dialog for each event type also explains when the event occurs and what event substitution variables are available for use in the command for that event.

Socket commands are of particular use in these command lines. For example, to alter the default text in the status bar so that it shows only the filename of the first selected file, set Events|Panel|Select (an event which occurs when the file selection in a panel changes) to:

    zzzfm -s set statusbar_text "$fm_filename"

Any command line set in the Event Manager menu which is prefixed with an asterisk (*) as the first character, will be run synchronously, as if it was added with the replace-event method. (The asterisk is removed before the command is run.) This means the GUI will freeze while zzzFM waits for the command to exit. For evt_win_click, evt_win_key, and evt_pnl_sel event types, a zero exit status will also inhibit the built-in handler.

In addition to setting commands in the Event Manager menu, you can also add event handler commands dynamically using the add-event or replace-event socket command methods.

Your entire zzzFM configuration, including settings and custom menu and toolbar items, is stored in the config directory: ~/.config/zzzfm/ (unless you use --config-dir on the command line to specify another location).

If the config directory doesn't exist, and /etc/xdg/zzzfm/ does exist, the contents of /etc/xdg/zzzfm/ will be copied to the new config directory on startup.

Files in ~/.config/zzzfm/ 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. zzzFM saves the current session anytime you make a change to the configuration (at most once every 15 seconds or so). If zzzFM 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, zzzFM 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 zzzFM. If you encounter a configuration problem or loss of settings when starting or using zzzFM, be sure to make a backup copy of these files before running zzzFM again. To revert to an older session, stop all instances of zzzFM and rename the older session file 'session'.

session.tmp
For stability, when zzzFM 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.

mydat/
Contains the data directories for custom commands you have created, if any. If commands need to store persistent user data, this is where they store it. It should generally be safe to remove files from this folder directory, but your commands may lose their settings.

scripts/
Contains the command directories for custom commands you have added to zzzFM's menus or toolbars, if any.

Because zzzFM is highly configurable, you may have much time and effort invested in your zzzFM config directory, 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 (template) rather than the automatically generated one. When you create a new custom command as a Script, ~/.config/zzzfm/scripts/default-script will be copied to the command directory as exec.sh.

Other locations in your home directory used by zzzFM include:

~/.config/mimeapps.list
zzzFM reads mimeapps.list to determine associated MIME applications, and may modify the file when you change the default application for a MIME type. This file may also be located in its older location: ~/.local/share/applications/mimeapps.list
( zzzFM will read the older location, but will not modify that file. )

~/.local/share/applications/
This directory contains localized copies of desktop files which define applications available on your system. zzzFM may create custom desktop files when needed. The system-wide /usr/share/applications/ directory is used similarly, though settings in the local directory 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. zzzFM's MIME Menu automates some of these tasks.

~/.templates/
The ~/.templates/ directory (or $XDG_TEMPLATES_DIR/ or ~/Templates/) holds file and directory templates for use in the New File/Folder Dialog.

The first time you click OK in the View|Preferences dialog, and anytime you change your terminal or root editor in that dialog, zzzFM will ask to save some settings as root to /etc/zzzfm/  Although optional, this is recommended to help secure your use of zzzFM'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/zzzfm/:

zzzfm.conf
This file is designed to be edited by the system administrator. This file contains the following settings:

• tmp_dir specifies what temporary directory zzzFM should use. If unset, it defaults to /tmp. Be sure to use a temporary directory which is root-owned/protected and user-writable (see /tmp permissions). /dev/shm is usually a good choice too. The temporary directory may not contain spaces or other special characters - keep it simple. Because zzzFM may run commands as other users (including root), the temporary directory must be writable by ALL users of zzzFM.
  
  
• terminal_su specifies an additional custom terminal su program, or alternate location. This program will appear in the list in Preferences|Advanced|Terminal SU. zzzFM knows how to run su, sudo, and su-to-root.

USERNAME-as-root
For each USERNAME who runs zzzFM, 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.

/etc/xdg/zzzfm/
This directory, if it exists, is used to copy a default configuration for new zzzFM users. If no config directory (eg ~/.config/zzzfm) exists for the current user when zzzFM is first started, the contents of /etc/xdg/zzzfm/ will be copied to the new config directory (be sure to kill all running instances of zzzfm before testing this). This enables a distro or system admin to set a default zzzFM configuration for new users. To do so, simply configure zzzFM as you want it to appear and work by default, then copy the contents of the config directory to /etc/xdg/zzzfm/ as root. Be sure to set all files in /etc/xdg/zzzfm/ to be readable by all users:

    sudo cp -r /home/USER/.config/zzzfm /etc/xdg/zzzfm
    sudo chmod -R ugo+rX /etc/xdg/zzzfm

    killall zzzfm
    rm -rf /tmp/zzzfm-test-config
    zzzfm --config-dir /tmp/zzzfm-test-config

zzzFM writes small files to the temporary directory (which can be changed in zzzfm.conf). These include:

.zzzfm-socketDISPLAY-USERNAME
A socket which zzzFM uses to open additional windows and other functions (including socket commands), 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 zzzFM exits.

zzzfm.tmp/
This directory, shared by all users, contains temporary files used for running a command as root. Once a root command is run, this directory will be owned by root.

zzzfm-USERNAME-RANDOM.tmp/
This directory contains temporary files used by USERNAME running zzzFM. It is owned by the user and will be deleted on exit. Other users can access this directory, but usually not the files within it, unless a command is being run AsRoot.

zzzfm*.tmp/ID-tmp.sh
A temporary bash script used to execute a command run in zzzFM, 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

All of the files installed to /usr are created only when zzzFM is installed, and are not later changed by zzzFM. These include:

/usr/bin/zzzfm
The zzzFM executable file.

/usr/bin/zzzfm-auth
This script is used internally by zzzfm to authenticate temporary scripts run AsRoot (using /usr/bin/sha256sum). This file should not be modified or run directly. Its purpose is to simplify the command line for su programs, which often handle special characters poorly and have inconsistent command line usage. If zzzfm-auth or /usr/bin/sha256sum are missing, zzzFM will operate in a less secure mode.

/usr/share/zzzfm/ui/
A directory containing glade (layout) files for some of zzzFM's dialogs.

/usr/share/pixmaps/png imagefiles used for zzzfm icon, and various additional images

/usr/share/locale/*/LC_MESSAGES/zzzfm.mo
Language files used by zzzFM, where '*' is a locale.

/usr/share/applications/
This directory contains desktop files which define applications available on your system, and the defaults.list file specifies default applications for given MIME types. zzzFM checks both ~/.local/share/applications/ and /usr/share/applications/ to determine what application to use to open files. Settings in the local directory 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.

/usr/share/applications/zzzfm.desktop
A desktop file (aka "launcher") which opens a zzzFM window.

/usr/share/applications/zzzfm-find.desktop
A desktop file (aka "launcher") which opens a zzzFM File Search window.

/usr/share/applications/zzzfm-folder-handler.desktop
A desktop file which uses zzzFM to open a folder directory

/usr/share/mime/packages/zzzfm-mime.xml
Additional MIME types provided by libmimetype, adding globbing patterns for some missing but frequently seen file types.

Upon first-run, zzzFM creates a directory, pathed at: ~/.config/zzzfm/
and here it will save a "session" file containing your settings (preferences) along with details representing the current state of the running program (the number of panes, the arrangement of panes, the location currently displayed within each pane). Each time your launch zzzFM, it will restore itself to match the state of the previous session.

~/.config/zzzfm/session
~/.config/zzzfm/session-last
~/.config/zzzfm/session-prior

By default, /etc/udevil/udevil.conf is set to permit mounting of only local fileystems and ISO files,
with mounting of networks disallowed. To allow networks and files to be mounted, in /etc/udevil/udevil.conf set:

    allowed_types = $KNOWN_FILESYSTEMS, file, cifs, nfs, curlftpfs, sshfs  

NTFS-3G

If local ntfs filesystems are not mounted writable, you may need to configure your system to mount ntfs with ntfs-3g (on some distros this is already done). For example:

    sudo ln -s /sbin/mount.ntfs-3g /sbin/mount.ntfs

    # OR if mount.ntfs-3g is located in /usr/bin:
    sudo ln -s /usr/bin/mount.ntfs-3g /usr/bin/mount.ntfs

Set SUID

After installing udevil, /usr/bin/udevil should have the suid bit already set. If not, set it like this:

    sudo chown root:root /usr/bin/udevil
    sudo chmod u+s,go-s,ugo+x /usr/bin/udevil
    ls -l /usr/bin/udevil
        -rwsr-xr-x 1 root root 226625 May 22 08:13 /usr/bin/udevil

    sudo chown root:plugdev /usr/bin/udevil
    sudo chmod u+s,go-s,o-x /usr/bin/udevil
    ls -l /usr/bin/udevil
        -rwsr-xr-- 1 root plugdev 226625 May 22 08:13 /usr/bin/udevil

    sudo chown root:root /usr/bin/udevil
    sudo chmod ugo-s,ugo+x /usr/bin/udevil
    ls -l /usr/bin/udevil
        -rwxr-xr-x 1 root root 226625 May 22 08:13 /usr/bin/udevil

NAME
       udevil - alternative storage media interface

SYNOPSIS
       udevil [OPTIONS] COMMAND [COMMAND-OPTIONS] [COMMAND-ARGUMENTS]

DESCRIPTION
       udevil  -  alternative  storage media interface udevil mounts and unmounts
       removable devices and network shares without requiring password (set suid),
       shows device information, and monitors device changes.
       Its installation also includes the   devmon   automounting script.

EXAMPLES
        udevil mount /dev/sdd1
        udevil mount -o ro,noatime /dev/sdd1
        udevil mount -o ro,noatime /dev/sdd1 /media/custom
        udevil mount /tmp/example.iso     # ISO file
        udevil mount ftp://sys.domain     # ftp site - requires curlftpfs or ftpfs
        udevil mount ftp://user:pass@sys.domain/share    # ftp share with user and password
        udevil mount ftp://user:pass@sys.domain:21/share # ftp share with port, user and password
        udevil mount -t ftpfs sys.domain     # ftp site with ftpfs
        udevil mount -t curlftpfs sys.domain    # ftp site with curl
        udevil mount -t curlftpfs user:pass@sys.domain    # ftp site with curl u/p
        udevil mount nfs://sys.domain:/share    # nfs share
        udevil mount sys.domain:/share    # nfs share
        udevil mount smb://sys.domain/share    # samba share w/ cifs
        udevil mount smb://user:pass@10.0.0.1:50/share    # samba share w/ u/p/port
        udevil mount smb://WORKGROUP/user@sys.domain     # samba share w/ workgroup
        udevil mount //sys.domain/share    # samba share w/ cifs
        udevil mount //sys.domain/share -t smbfs    # samba share w/ smbfs
        udevil mount ssh://user@sys.domain    # sshfs with user - requires sshfs
        udevil mount -t sshfs user@sys.domain   # sshfs with user

        udevil mount tmpfs # make a ram drive
        WARNING !!! a password on the command line is UNSAFE - see filesystem docs

        udevil umount /dev/sdd1
               udevil umount /media/disk
               udevil umount -l /media/disk
               udevil umount /tmp/example.iso

        udevil info /dev/sdd1

        udevil monitor

        udevil clean


       OPTIONS
               --verbose
               print details

               --quiet
               minimal output

USAGE
        MOUNT  -  Mounts DEVICE to mount point DIR with MOUNT-OPTIONS:
               udevil mount|--mount [MOUNT-OPTIONS] [[-b|--block-device] DEVICE] [DIR]
               MOUNT-OPTIONS:
               -|--types|--filesystem-type|--mount-fstype TYPE
               (see man mount)
               -o|--options|--mount-options OPT,...  (see man mount)
               --no-user-interaction  ignored (for compatibility)

        udevil umount|unmount|--unmount|--umount [UNMOUNT-OPTIONS]
               {[-b|--block-device] DEVICE}|DIR
               UNMOUNT-OPTIONS:
               -l lazy unmount (see man umount)
               -f force unmount (see man umount)
               --no-user-interaction ignored (for compatibility)

        INFO  -  Show information about DEVICE emulating udisks v1 output:
               udevil info|--show-info|--info [-b|--block-device] DEVICE

        MONITOR  -  Display device events emulating udisks v1 output:
              udevil monitor|--monitor

        CLEAN  -  Remove unmounted udevil-created mount dirs in media dirs
               udevil clean

       HELP  -  Show this help
               udevil help|--help|-h