XDG-ASSIST(1)

NAME
xdg-assist - startup-notification assist window managers and clients

SYNOPSIS
xdg-assist [OPTIONS]

DESCRIPTION
xdg-assist is a "C"-language daemon process that assists light-weight window managers and non-conforming clients with startup-notification and EWMH support. xdg-assist is a background process that should be started before the window manager or any other client.

OPTIONS
The options that are detailed below are recognized by xdg-assist. xdg-assist uses getopt_long_only(3), so unambiguous abbreviations of long options and long options with a single dash are also supported.

xdg-assist supports the following options:

  COMMAND OPTIONS
The default is to start xdg-assist and daemonize it (placing it in the background).

[-m, --monitor]
    Run as a monitoring process. This is the default if no other command option is specified.

-r, --replace
    Restart xdg-assist by replacing the existing running process with the current one.

-q, --quit
    Asks a running xdg-assist process to stop.

-h, --help
    Prints usage information to standard output and exits.

-V, --version
    Prints detailed version information and exits.

-C, --copying
    Prints detailed copying permissions and exits.

  GENERAL OPTIONS

-f, --foreground
    Run xdg-assist in the foreground for debugging (so that standard error goes to the terminal.

-g, --guard-time TIMEOUT
    Specifies the amount of time, TIMEOUT, in milliseconds, that xdg-assist will wait for a destop application to launch.

USAGE
The primary purpose of the xdg-assist program is to support window managers and clients for launchers other than xdg-launch(1). xdg-launch(1) can provide its own startup notification monitoring and completion in a superior fashion to xdg-assist. This is because xdg-launch(1) runs on the same host as the launched process, whereas, xdg-assist may not be running on the same host that launched and is running the process.

Nevertheless, it is advantageous to start xdg-assist(1) and run it as a background process before the window manager starts. An XDG autostart .desktop file is provided for this purpose.

BEHAVIOUR
Non-startup-notification aware clients and window managers are assisted when xdg-assist is running and it detects that the window manager does not support full startup notification.

When running and when xdg-assist detects that the client or window manager does not support startup notification (or cannot decide one way or the other), xdg-assist will perform the following actions:

1.  xdg-assist forks a monitoring process, daemonizes it, placing it in the background. This process will run until killed.

2.  xdg-assist monitors for startup notification messages and collects outstanding startup notification sequences.

3.  xdg-assist monitor for the appearance of new top-level and client windows.

    •   For EWMH/NetWM compliant window managers, this can be determined using the _NET_CLIENT_LIST property on the root window of the screen on which the client is launching.

    •   For WMH/WinWM compliant window managers, this can be determined using the _WIN_CLIENT_LIST property on the root window.

    •   For ICCCM compliant window managers, the appearance of a WM_STATE property on a top-level window with a state other than "WithdrawnState" can be used.

4.  When a definitive match can be made from the properties of the mapped window, xdg-launch will populate the following properties unless otherwise populated by the client or window manager:

    _NET_STARTUP_ID
        This property will be populated with the startup id of the launched desktop application when it is missing. (Very few applications in fact populate this property: not because their toolkits do not support it, but because the facility of the toolkit has not been invoked.)

    _NET_WM_USER_TIME
        This property will be populated with the time stamp, unless it already exists.

    _NET_WM_PID
        This property will be populated with the launched process id.

    _NET_WM_DESKTOP, _WIN_WORKSPACE, _DT_WORKSPACE_PRESENCE
        These properties will be populated with the desktop for the launched application unless this property was set by the client (and not the window manager). If the property was not set by the client but was set by the window manager and it does not match the value requested during launch, xdg-launch will send the appropriate client messages to effect the transfer.

    WM_NAME, _NET_WM_NAME, _NET_WM_VISIBLE_NAME
        When none of these properties are present, xdg-launch will populate them from the "NAME=" field of the startup notification sequence.

    WM_ICON, _NET_WM_ICON, _KDE_NET_WM_ICON
        When none of these properties are present, xdg-assist will populate them from the "ICON=" field of the startup notification sequence.

    _NET_WM_FULLSCREEN_MONITORS
        This property will be populated with the monitor number on which the desktop application was to launch. If the client has already mapped, a client message to change the value will be sent to the root window when the window manager supports such things.

    WM_HINTS
        If the client window has mapped on the incorrect monitor, and the client has not specified the initial location using WM_HINTS, xdg-launch will unmap the window, set the WM_HINTS property for the appropriate monitor, and remap the window.

    WM_COMMAND
        This property will be populated with the command and arguments of the launched process, unless otherwise populated.

    WM_CLIENT_MACHINE
        This property will be populated with the fully qualified host name even when populated by the client.

5.  xdg-assist monitors for the creation and removal of process ids (using inotify(7) on the /proc file system). It performs startup notification completion on process ids that are removed or which perform an execve(3) or related function that changes the current executable, and command arguments.

    xdg-assist can also monitor when process ids appear that have a specified DESKTOP_STARTUP_ID variable in their environment.

ENVIRONMENT
The following environment variables are examined by xdg-assist, both in its own environment as well as in the environments of monitored processes:

DISPLAY
    Used by xdg-assist to determine the X display and default screen on which it has been invoked.

DESKTOP_STARTUP_ID
    Used by xdg-assist at program startup to determine whether it itself has been launched with startup notification. The DESKTOP_STARTUP_ID is removed from the environment in this case and a startup notification "remove:" message is issued to complete its own startup.

    xdg-assist also monitors for this environment variables in processes to which it has access to match appearing processes with startup notification. A client that property supports desktop startup notification will remove this environment variable from its environment at startup. One that ignores the environment variable will not remove it.

AUTHOR
Brian Bidulock <bidulock@openss7.org>