Launcher

Launcher settings are named settings objects stored at $HOME/.config/qtermy/launchers and at prefix/share/qtermy/launchers. Files in HOME take precedence over files in the system directory. Launchers can be created and edited from the Manage Launchers window. The files can also be edited directly in a text editor, but note that qtermy does not monitor for external changes to settings files. Use the reload files button in the Manage Launchers window to load external changes and new files without restarting the application.

A launcher describes the execution of a command by qtermy or by a local or remote server. Launchers are used for two purposes within qtermy: to run commands with optional processing of input and output streams, and to launch programs to handle files opened via OpenFile through context menus or the Files tool.

A fallback launcher named "Default" must exist at all times. One launcher (which need not be the one named "Default") is designated as the default launcher. The default launcher is used to open files in the absence of a specific launcher name. The default launcher as shipped by qtermy opens files using OpenDesktopUrl, but this can be changed (see the tip below).

A launcher used to open files and URL's should contain one or more of the following markers in its Command. The marker will be replaced at launch time with the corresponding URL, path, or name, treated as a single word.

• %U or %u: substitute target URL.
• %F or %f: substitute full path of target file.
• %n: substitute name of file.
• %d: substitute enclosing directory of file.

These markers are identical to those used in desktop entry files and it is possible to import a desktop entry file as a new launcher in the Manage Launchers window. It's also possible for a launcher to make use of custom markers not listed here, using the Substitutions parameter to OpenFile and LaunchCommand. This feature can be used by custom actions or by semantic regions created by semantic parsers to launch commands with arbitrary argument substitutions.

Launchers may specify filename extensions and URI schemes to match against when used to open files and URL's.

Tip

For maximum flexibility when opening files using desktop applications, create your own custom script which launches the application of your choice depending on the URL or path provided as its %u or %f argument, and run that script from the default launcher. You can even create multiple launchers which run the script with different arguments to achieve different results.

Tip

Run commonly used commands in a single keystroke by making a key binding to to the LaunchCommand action with your custom launcher specified as the LauncherName parameter. Try creating a launcher to run fortune(6) as a bare command with its output displayed in a dialog box!

Match

FileExtensions (string)

A list of space-separated filename extensions which the launcher is intended to be used to open. This setting is a hint used to prioritize launchers when building the "Open with" context menu.

URISchemes (string)

A list of space-separated URI schemes such as "https" which the launcher is intended to be used to open. This setting is a hint used to prioritize launchers when building the "Open with" context menu.

Launcher

LaunchType (enumeration)

The type of command to be launched. The choices are as follows:

• Open file via local desktop environment: The OpenDesktopUrl action is used to open the target via the local desktop environment. If the target file is on a remote server, it may be mounted first, depending on the value of MountType. If this is done, the locally mounted file name will be passed to OpenDesktopUrl rather than the remote path. Command and input/output settings are ignored.
• Run bare command on the local machine: A task is initiated to run the launcher's Command as a child process of qtermy itself. Command and input/output settings are honored. When used to open a remote file, a file mount may be performed as described in the first choice.
• Run bare command on the remote machine: A task is initiated to run the launcher's Command as a child process of the target file's server or the server specified in a call to LaunchCommand. Note that this option encompasses all servers including local servers. Command and input/output settings are honored. A mount will never be performed since the command is run on the same server as the target file.
• Run command in a new local terminal: A terminal is created on the local server using the specified Profile and the launcher's Command is run within it rather than the command specified in the profile. Command settings are honored but input/output settings are not. When used to open a remote file, a file mount may be performed as described in the first choice.
• Run command in a new remote terminal: A terminal is created on the target file's server or the server specified in a call to LaunchCommand, using the specified Profile, and the launcher's Command is run within it rather than the command specified in the profile. Command settings are honored but input/output settings are not. A mount will never be performed since the command is run on the same server as the target file.
• Write command text into the active terminal: The Command string will be written into the active terminal using WriteText, rather than being executed. When used to open a remote file, a file mount may be performed as described in the first choice.

Profile (string)

The profile to use to create a new terminal. Only applicable when the LaunchType is configured to create a terminal. Note that the Command set in the profile itself will be ignored.

MountType (enumeration)

The type of mount to perform if a launcher configured to run a local command is used to open a file on a remote server. Mounts can be disabled or can be made read-only or read-write. If mounts are disabled, the launcher can only be used to open files on the local machine.

Note that mount tasks started by launchers are considered "background tasks." The MountAction configured in the Global settings will not be run, nor will a task status dialog be shown even if AutoShowTaskStatus is enabled. A task status dialog can be manually shown using the Tasks tool or InspectTask action.

UnmountIdleTime (integer)

The maximum time that a mount task run by this launcher will remain idle before being automatically unmounted. A mount is considered "idle" if there are no open filehandles to files within it. If disabled, the mount task will never time out and must be manually canceled using the Tasks tool or CancelTask action.

Caution

Some applications and editors don't hold open filehandles to the file that they are editing. In this case, the mount may time out while the file is still open within the application or editor. Test each application, checking whether the status of the mount task is "Idle" while the file is open within the application. If so, consider disabling this setting.

DisplayIcon (string)

Sets the icon for the launcher, displayed in context menus and the Manage Launchers window. An SVG file with the specified name will be loaded from $HOME/.local/share/qtermy/images/command and prefix/share/qtermy/images/command in that order. If no such file is found, the name "default" is used instead.

Command

Command (stringlist)

The command to run. This is a list of strings consisting of an executable name and argument vector (including argument zero).

The command may contain markers of the form %X where X is a letter or number. Predefined markers listed above are used to substitute file paths and URL's. Other markers can be substituted using the Substitutions parameter to OpenFile and LaunchCommand.

Commands entered into the text field will be split on whitespace and the first word will be used as both the executable to run and argument zero of the argument vector, unless the first word ends with a separate argument in square brackets. In this case, the portion before the square brackets is used as the executable name and the portion within the square brackets is used as argument zero.

For more control over the argument vector, click the Advanced button to bring up a command editor dialog. The dialog displays the executable name and argument vector separately and supports arguments containing whitespace.

Important

Shell constructs such as quoting and variable expansion should not be used since the command may not be run by a shell. Use a wrapper script if this is required.

Directory (string)

The directory which the Command is run from. If unspecified, the command will be started in the user's HOME directory. Ignored if FileDirectory is set and the launcher is used to open a file.

FileDirectory (boolean)

If enabled, the Command will be run from the target file's enclosing directory, if available, rather than the configured Directory.

Environment (stringlist)

Environment variable rules used to set and clear environment variables before running the Command.

InputOutput

InputType (enumeration)

Specifies what to provide to the launched Command on its standard input stream. Only applicable when the LaunchType is configured to run a bare command.

InputFile (string)

The file to read input from if InputType is configured to read from a local file. This file must be accessible to qtermy. Select a predefined value from the dropdown list or specify a custom path.

OutputType (enumeration)

Specifies what to do with the standard output and standard error streams of the launched Command. Only applicable when the LaunchType is configured to run a bare command.

Warning

The Interpret output as action to run option will interpret the output of the command as an arbitrary action invocation, which could result in local commands being run. Do not run launchers of this type on untrusted or shared servers.

OutputFile (string)

The file to write output to if OutputType is configured to write output to a local file. This file must be accessible to qtermy. Select a predefined value from the dropdown list or specify a custom path.

OutputFileConfirmation (enumeration)

What to do if OutputType is configured to write output to a local file that already exists.