Desktop Notifications (GNU Emacs Lisp Reference Manual)

43.19 デスクトップ通知

Emacsはfreedesktop.orgのDesktop Notifications Specification(デスクトップ通知仕様)をサポートするMS-Windows、Haiku、Androidといったシステムで通知(notifications)を送ることができます。

この機能をPOSIXホストで使用するにはEmacsがD-Busサポート付きでコンパイルされていて、notificationsライブラリーがロードされていなければなりません。D-Bus in D-Bus integration in Emacsを参照してください。D-Busサポートが利用できるときには以下の関数がサポートされます。

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

通知アイコンのファイル名。nilにセットされているとアイコンは表示されない。デフォルトはnotifications-application-icon。値が文字列の場合には、関数はそれをファイル名と解釈してexpand-file-nameを用いて絶対ファイル名に変換するシンボルの場合には、関数はそのシンボルの名前を使用する(これは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でトレー通知を削除する。

EmacsがGUIプログラムとしてHaikuで実行されている際には、前述したDBusデスクトップ通知インターフェイスの制限された模倣バージョンも提供されます。以下で詳しく説明する関数から欠落している基本的な機能は:actions、:on-action、:on-close.<といったコールバック関数です。

Function: haiku-notifications-notify &rest params ¶

この関数はnotifications-notifyが受け取る一部のパラメーターと似たいくつかのパラメーターと組み合わせて、通知をデスクトップ通知サーバーに送信する。パラメーターは:

:title title
:body body
:replaces-id replaces-id
:urgency urgency: これらのパラメーターはnotifications-notify呼び出しで使用された際と同じ意味をもつ
:app-icon app-icon: これは通知の表示にアイコンとして使用するイメージファイルを示すファイル名であること。nilならかわりにEmacsのアプリケーションアイコンが表示される。

関数は通知を識別する数値をリターンする。このリターン値はこの関数の後続の呼び出しにおいて、:replaces-idパラメーターとして利用できる。

EmacsをAndroidのアプリケーションパッケージとしてビルドした際には、通知は関数android-notifications-notifyによって容易に表示できます。この関数はコールバック機能をもたず、notifications-notifyと比較していくつか特異な点があります。

Function: android-notifications-notify &rest params ¶

この関数はデスクトップ通知を表示する。paramsはnotifications-notifyにちなんだ類似するパラメーターのリスト。パラメーターは:

:title title

:body body

:replaces-id replaces-id

:on-action on-action

:on-cancel on-close

:actions actions

:timeout timeout

:resident resident

これらはデフォルト以外のアクションが3つまでしか表示されない点を除けば、notifications-notify呼び出しで用いた場合と同じ意味をもつ。

:urgency urgency

urgencyが受け付ける値セットはnotifications-notifyの場合と同じだが、Android 7.1以前を除きgroupで定義された通知の表示すべてにurgency(緊急)が適用される。

:group group

groupは通知の送信元が属するカテゴリーを示す文字列。このカテゴリーはシステムの通知のセッティングメニューで再生成されるが、Android 7.1以前では無視される。

groupがnil、またはparamsで指定されなければ、文字列‘"Desktop Notifications"’で置き換えられる。

以前groupに配信された通知とマッチしなければシステムがurgencyを無視することを選択するかもしれないことを考慮すると、呼び出し側は送信する通知の種類それぞれにたいして、1つの永続性のあるurgencyとgroupの組み合わせを提供すること。

:icon icon

このパラメーターは通知とともに表示されるシンボリックアイコンを制御する。値はandroid.R.drawableシステムパッケージにおいてアイコンを識別する文字列。このようなアイコンのリストについてはR.drawable | Android Developersを参照のこと。

paramsで提供されない、あるいはiconが存在しなければデフォルトは‘"ic_dialog_alert"’。

関数は通知を識別する数値をリターンする。この関数を後で呼び出す際に、:replaces-idパラメーターとして提供され得る。

Android 13以降においてEmacsに通知を表示する権限がなければ(Android Environment in The GNU Emacs Manualを参照)、送信したすべての通知は暗黙裡に破棄される。

43.19 デスクトップ通知

Footnotes

(34)