Desktop Notifications (GNU Emacs Lisp Reference Manual)

42.19 デスクトップ通知

Emacs is able to send notifications on systems that support the freedesktop.org Desktop Notifications Specification, MS-Windows, Haiku, and Android.

In order to use this functionality on POSIX hosts, Emacs must have been compiled with D-Bus support, and the notifications library must be loaded. See D-Bus in D-Bus integration in Emacs. The following function is supported when D-Bus support is available:

Function: notifications-notify &rest params ¶

この関数は引数paramsで指定された構成したパラメーターによりD-Busを通じてデスクトップに通知を送信する。これらの引数は交互になったキーワードと値のペアーで構成されていること。以下はサポートされているキーワードと値:

:bus bus

D-Busのバス。この引数は:session以外のバスを使用する場合のみ必要。

:title title

通知のタイトル。

:body text

通知のbodyのテキスト。通知サーバーの実装に依存して‘"<b>bold text</b>"’のようなHTMLマークアップ、ハイパーリンク、イメージをテキストに含むことができる。HTML特殊文字は‘"Contact <postmaster@localhost>!"’のようにエンコードしなければならない。

:app-name name

その通知を送信するアプリケーション名。デフォルトはnotifications-application-name。

:replaces-id id

この通知が置換する通知のid。idはnotifications-notifyの以前の呼び出し結果でなければならない。

:app-icon icon-file

The file name of the notification icon. If set to nil, no icon is displayed. The default is notifications-application-icon. If the value is a string, the function interprets it as a file name and converts to absolute by using expand-file-name; if it is a symbol, the function will use its name (which is useful when using the Icon Naming Specification ³³).

:actions (key title key title ...)

適用されるアクションのリスト。keyとtitleはどちらも文字列。デフォルトのアクション(通常は通知クリックで呼び出される)は‘"default"’という名前であること。実装がそれを表示しないようにするには自由だがtitleは何でもよい。

:timeout timeout

timeoutは通知が表示されてからその通知が自動的にクローズされるまでのミリ秒での時間。-1なら通知の有効期限は通知サーバーのセッティングに依存して、通知のタイプにより異なるかもしれない。0なら通知は失効しない。デフォルト値は-1。

:urgency urgency

緊急レベル。low、normal、criticalのいずれか。

:action-items

このキーワードが与えられるとアクションのtitle文字列はアイコン名として解釈される。

:category category

通知の種類の文字列。標準のカテゴリーのリストはDesktop Notifications Specificationを参照のこと。

:desktop-entry filename

これは‘"emacs"’のようにプログラムを呼び出すデスクトップファイル名の名前を指定する。

:image-data (width height rowstride has-alpha bits channels data)

これはそれぞれwidth、height、rowstride、およびalpha channel、bits per sample、channels、image dataの有無を記述するrawデータのイメージフォーマット。

:image-path path

これはURI(現在サポートされているのはURIスキーマは‘file://’のみ)、または‘$XDG_DATA_DIRS/icons’にあるfreedesktop.org準拠のアイコンテーマ名のいずれかを表す。

:sound-file filename

通知ポップアップ時に再生するサウンドファイルのパス。

:sound-name name

通知ポップアップ時に再生するfreedesktop.orgサウンド命名仕様準拠のテーマに対応した‘$XDG_DATA_DIRS/sounds’にある名前付きサウンド。アイコン名と同様にサウンドにたいしてのみ。例としては‘"message-new-instant"’。

:suppress-sound

それが可能ならサーバーにすべてのサウンドの再生を抑制させる。

:resident

セットするとアクション呼び出し時にサーバーは通知を自動的に削除しない。ユーザーか送信者により明示的に削除されるまで通知はサーバー内に常駐し続ける。恐らくこのヒントはサーバーが:persistence能力をもつときのみ有用。

:transient

セットするとサーバーはその通知を過渡的なものとして扱い、もしそれが永続的であるべきならサーバーのpersistence能力をバイパスする。

:x position

:y position

その通知がポイントすべきスクリーン上のXとYの座標を指定する。これらの引数は併せて使用しなければならない。

:on-action function

アクション呼び出し時に呼び出す関数。通知idとアクションのkeyは引数としてその関数に渡される。

:on-close function

タイムアウトかユーザーにより通知がクローズされたときに呼び出す関数。通知idとクローズ理由reasonは引数としてその関数に渡される。:

通知が失効した場合はexpired。
ユーザーが通知を却下したらdismissed。
notifications-close-notification呼び出しにより通知がクローズされたら close-notification
通知サーバーが理由を提供しなかったらundefined。

通知サーバーがどのパラメーターを受け入れるかのチェックはnotifications-get-capabilitiesを通じて行うことができる。

この関数は整数の通知idをリターンする。このidはnotifications-close-notificationや別のnotifications-notify呼び出しの:replaces-id引数で通知アイテムの操作に使用できる。たとえば:

(defun my-on-action-function (id key)
  (message "Message %d, key \"%s\" pressed" id key))
     ⇒ my-on-action-function

(defun my-on-close-function (id reason)
  (message "Message %d, closed due to \"%s\"" id reason))
     ⇒ my-on-close-function

(notifications-notify
 :title "Title"
 :body "This is <b>important</b>."
 :actions '("Confirm" "I agree" "Refuse" "I disagree")
 :on-action 'my-on-action-function
 :on-close 'my-on-close-function)
     ⇒ 22

A message window opens on the desktop.  Press ``I agree''.
     ⇒ Message 22, key "Confirm" pressed
        Message 22, closed due to "dismissed"

Function: notifications-close-notification id &optional bus ¶: この関数は識別子idの通知をクローズする。busはD-Bus接続を表す文字列でありデフォルトは:session。

Function: notifications-get-capabilities &optional bus ¶

通知サーバーの能力をシンボルのリストでリターンする。busはD-Bus接続を表す文字列でありデフォルトは:session。以下は期待できる能力:

:actions: サーバーはユーザーにたいする指定されたアクションを提供する。
:body: bodyのテキストをサポートする。
:body-hyperlinks: サーバーは通知内のハイパーリンクをサポートする。
:body-images: サーバーは通知内のイメージをサポートする。
:body-markup: サーバーは通知内のマークアップをサポートする。
:icon-multi: サーバーは与えられたイメージ配列内のすべてのフレームのアニメーションを描画できる。
:icon-static: 与えられたイメージ配列内の正確に1フレームの表示をサポートする。この値は、:icon-multiとは相互に排他。
:persistence: サーバーは通知の永続性をサポートする。
:sound: サーバーは通知のサウンドをサポートする。

これらに加えてベンダー固有の能力は:x-gnome-foo-capのように:x-vendorで始まる。

Function: notifications-get-server-information &optional bus ¶

通知サーバーの情報を文字列のリストでリターンする。busはD-Bus接続を表す文字列でありデフォルトは:session。リターンされるリストは(name vendor version spec-version)。

name: サーバーのプロダクト名。
vendor: ベンダー名。たとえば‘"KDE"’や‘"GNOME"’。
version: サーバーのバージョン番号。
spec-version: サーバーが準拠する仕様のバージョン。

spec_versionがnilならサーバーは‘"1.0"’以前の仕様をサポートする。

EmacsがMS-WindowsでGUIセッションとして実行時には、ネイティブのプリミティブを通じてD-Bus通知の小サブセットをサポートします:

Function: w32-notification-notify &rest params ¶

この関数はparamsの指定にしたがってMS-Windowsのトレー通知(tray notification)を表示する。MS-Windowsトレー通知はタスクバーのの通知エリア内のアイコンからのバルーン内に表示される。

値は以下で説明するw32-notification-closeで通知の削除に使用できる一意な通知ID。関数が失敗するとリターン値はnil。

引数paramsはkeyword/valueペアーで指定する。パラメーターはすべてオプションだが何もパラメーターを指定しなければ関数は何もせずにnilをリターンする。

は以下はサポートされるパラメーター:

:icon icon: システムトレーにiconを表示する。iconが文字列ならアイコンをロードするファイル名(Windowsのアイコンファイル.ico)を指定すること。iconが文字列以外、またはこのパラメーターが指定されなければEmacsの標準アイコンが使用される。
:tip tip: 通知のツールチップにtipを使用する。tipが文字列なら、通知により追加されたトレーアイコン上にマウスポインターを移動した際に表示されるツールチップのテキスト。tipが文字列以外またはこのパラメーターが指定されていなければ、ツールチップのデフォルトのテキストは‘Emacs notification’。ツールチップのテキストは127文字まで(Windows 2000以前は63文字)。それより長い文字列は切り捨てられる。
:level level: 通知の重大度レベルでinfo、warning、errorのいずれか。値が与えられた場合には、:titleパラメーターも指定されて、かつ文字列の場合のみ通知アイコンの左に表示されるアイコンを決定する。
:title title: 通知のタイトル。titleが文字列ならbodyテキストの直上に大きなフォントで表示される。タイトルのテキストは63文字まで。それより長い文字列は切り捨てられる。
:body body: 通知のbody(本文)。bodyが文字列なら通知メッセージのテキストを指定する。テキストを行に分割する方法を制御するには埋め込みの改行を使用する。bodyのテキストは255文字までで、それより長ければ切り捨てられる。D-Busとは異なりbodyテキストはマークアップを含まないプレーンテキストであること。

Windows 2000以前のWindowsでは:iconと:tipだけがサポートされることに注意。他のパラメーターを渡すことは可能だが、それらの古いシステムでは無視されるだろう。

一度にアクティブな通知は最大でも常に1つ。新たな通知を表示できるようにするにはw32-notification-closeを呼び出してアクティブな通知を削除しなければならない。

タスクバーから通知とアイコンを削除するには以下の関数を使用します:

Function: w32-notification-close id ¶: この関数は与えられた一意なidでトレー通知を削除する。

When Emacs runs under Haiku as a GUI program, it is also provides a restricted pastiche of the D-Bus desktop notifications interface previously addressed. The principle capabilities absent from the function detailed below are call-back functions such as :actions, :on-action and :on-close.

Function: haiku-notifications-notify &rest params ¶

This function sends a notification to the desktop notification server, incorporating a number of parameters that are akin to some of those accepted by notifications-notify. The parameters are:

:title title
:body body
:replaces-id replaces-id
:urgency urgency: These have the same meaning as they do when used in calls to notifications-notify.
:app-icon app-icon: This should be the file name designating an image file to use as the icon for the notification displayed. If nil, the icon presented will instead be Emacs’s app icon.

Its return value is a number identifying the notification, which can be exploited as the :replaces-id parameter to a subsequent call to this function.

When Emacs is built as an Android application package, displaying notifications is facilitated by the function android-notifications-notify. This function does not feature call-backs, and has several idiosyncrasies, when compared to notifications-notify.

Function: android-notifications-notify &rest params ¶

This function displays a desktop notification. params is a list of parameters analogous to its namesake in notifications-notify. The parameters are:

:title title

:body body

:replaces-id replaces-id

These have the same meaning as they do when used in calls to notifications-notify.

:urgency urgency

The set of values for urgency is the same as with notifications-notify, but the urgency applies to all notifications displayed with the defined group, except under Android 7.1 and earlier.

:group group

group is a string that designates a category to which the notification sent will belong. This category is reproduced within the system’s notification settings menus, but is ignored under Android 7.1 and earlier.

If group is nil or not present within params, it is replaced by the string ‘"Desktop Notifications"’.

Callers should provide one stable combination of urgency and group for each kind of notification they send, given that the system may elect to disregard urgency if it does not match that of any notification previously delivered to group.

:icon icon

This parameter controls the symbolic icon the notification will be displayed with. Its value is a string designating an icon within the android.R.drawable system package. See R.drawable | Android Developers for a list of such icons.

If it is not provided within params or icon does not exist, it defaults to ‘"ic_dialog_alert"’.

It returns a number identifying the notification, which may be supplied as the :replaces-id parameter to a later call to this function.

If Emacs is not afforded the permission to display notifications (see Android Environment in The GNU Emacs Manual) under Android 13 and later, any notifications sent will be silently disregarded.

42.19 デスクトップ通知

Footnotes

(33)