43.20 Controlling System GUI Taskbar Features ¶

See System Taskbar in The GNU Emacs Manual, for an overview and configuration.

Function: system-taskbar-badge &optional count ¶

This function displays count as an overlay on the system taskbar Emacs icon.

If count is an integer, display that.

If count is a string on back ends that support strings, display that. The string should be short.

On back ends which do not support strings, convert count to an integer, or nil if that fails.

If count is nil or an empty string, remove the counter or short string.

Display the system taskbar icon badge set to count. If count is nil, clear the badge. count is typically an integer.

If count is a string, it is converted to an integer on systems that do not support string badges, such as GNU/Linux D-Bus, and the badge will be cleared if the string is an invalid integer representation. On systems that support strings, such as macOS/GNUstep and MS-Windows, the badge is set to the string and displayed, and may be truncated to fit the visual space allocated by the system. In any case, if the string is empty, clear the badge.

Function: system-taskbar-attention &optional urgency timeout ¶

This function flashes or bounces system taskbar Emacs icon and/or its frame to alert the user.

urgency can be one of the symbols informational, or critical.

If urgency is nil, clear the attention indicator.

The attention indicator is cleared by the earliest of bringing the Emacs GUI into focus, or after timeout seconds. If timeout is nil, the system GUI behavior has priority.

On some back ends, critical has the same effect as informational.

On some back ends, attention will be displayed only if Emacs is not the currently focused application.

Function: system-taskbar-progress &optional progress ¶

This function displays a progress indicator overlay on the system taskbar Emacs icon.

progress is a float in the range 0.0 to 1.0. If progress is nil, remove the progress indicator.

It is convenient to use the built-in progress reporter functions which, when system-taskbar-mode is enabled, integrate with system-taskbar-progress by default. See Reporting Operation Progress.

Examples of system taskbar functions:

;; Enable and initialize system-taskbar-mode before calling its
;; package functions.
(system-taskbar-mode)

;; Display a badge integer on the taskbar icon.
(system-taskbar-badge emacs-major-version)

;; A string representation of an integer is converted to an
;; integer on GNU/Linux.
(system-taskbar-badge "31")

;; Short strings are displayed on macOS/GNUstep and MS-Windows.
(system-taskbar-badge "Test")

;; Clear the badge.
(system-taskbar-badge)

;; Get the user's attention and clear the request after 3 seconds.
(system-taskbar-attention 'informational 3)

;; Get the user's attention and clear when Emacs is focused.
(system-taskbar-attention 'critical)

;; Clear the attention request.
(system-taskbar-attention)

;; Make sure system taskbar is integrated with progress-reporter.
(setopt system-taskbar-use-progress-reporter t) ; t is the default
(system-taskbar-mode)

;; Report `dotimes` progress on the taskbar icon.
(dotimes-with-progress-reporter
    (i 10)
    "Counting from 1 to 10..."
  (sleep-for 1))

;; Report `dolist` progress on the taskbar icon.
(dolist-with-progress-reporter
    (i (make-list 10 t))
    "Progress from 1 to 10 elements..."
  (sleep-for 1))