Terminal Intent

Non-graphical applications (‘termapps’) must be launched in a terminal emulator.

This specification aims to provide a common interface for launching commands, including termapps, environments can use rather than hard coding specific emulators

TODO: Better into

Terminal1

org.freedesktop.Terminal1

The D-Bus interface

<!DOCTYPE node PUBLIC
      "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
      "https://dbus.freedesktop.org/doc/introspect.dtd" >
<node>
  <interface name="org.freedesktop.Terminal1">
    <method name="LaunchCommand">
      <arg type='aay' name='exec' direction='in' />
      <arg type='ay' name='working_directory' direction='in' />
      <arg type='ay' name='desktop_entry' direction='in' />
      <arg type='aay' name='env' direction='in' />
      <arg type='a{sv}' name='options' direction='in' />
      <arg type='a{sv}' name='platform_data' direction='in' />
    </method>
  </interface>
</node>

LaunchCommand

Launch a terminal with a given command

As paths may contain non-UTF-8 data parameters use null-terminated ay rather than s. Implementations should take care when handling these bytestrings.

Parameter

Type

Description

exec

aay

Argument vector (execve(2)-style), or zero length

If the vector has zero length, a regular shell session should be launched instead.

When launching a Desktop Entry the expanded Exec should be used

working_directory

Specifies the directory exec should be launched in

If the bytestring has zero length, implementations should use $HOME or equivalent instead.

When launching a Desktop Entry the value of Path should be used (if present)

desktop_entry

The full path to the Desktop Entry for exec, or zero length when not applicable

Implementations may use this for things such as window title, though such behaviour is optional.

Users should pass this when lunching termapp whenever possible

env

aay

Environment list (execve(2)-style), or zero length

These "key=value" values should modify (rather than substitute) the environment an implementation would otherwise use when invoking exec

options

a{sv}

Additional options

Implementations should try to implement as many of these options as possible

Option	Type	Description
keep-terminal-open	b	Terminal should be held open after exec exists so a user can inspect the output

options may be expanded in future, unrecognised options should simply be ignored

platform_data

a{sv}

Meta information such as desktop-startup-id or activation-token

See org.freedesktop.Application

Example Usage

Given a hypothetical text-based editor

org.freedesktop.Editor.desktop

A terminal text editor

[Desktop Entry]
Version=1.0
Type=Application
Terminal=true
Name=Editor
Comment=A terminal text editor
Exec=xdg-editor %f
Path=/opt/xdg/editor
Icon=org.freedesktop.DuperEditor
MimeType=text/plain

And a chosen terminal emulator

org.freedesktop.SuperTerm.desktop

A terminal emulator providing Terminal1

[Desktop Entry]
Version=1.0
Type=Application
Name=SuperTerm
Comment=The best terminal available!
Exec=xdg-super-term
Icon=org.freedesktop.SuperTerm
Implements=org.freedesktop.Terminal1

A file “sweden.txt” would be opened in Editor (via SuperTerm) with a call resembling

Name: org.freedesktop.SuperTerm
Path: /org/freedesktop/SuperTerm
org.freedesktop.Terminal1.LaunchCommand(b'xdg-editor /path/to/sweden.txt',
                                        b'/opt/xdg/editor',
                                        b'/usr/share/applications/org.freedesktop.Editor.desktop',
                                        [],
                                        {},
                                        {'desktop-startup-id': 'token'})