Help language development. Donate to The Perl Foundation
Desktop::Notify cpan:FRITH last updated on 2020-01-08
Desktop::Notify
Desktop::Notify A simple interface to libnotify
Build Status
| Operating System | Build Status | CI Provider |
|---|---|---|
| Linux |  |
Travis CI |
Example
use Desktop::Notify::Simple;
my $n = Desktop::Notify::Simple.new(
:app-name('testone'),
:summary('Attention!'),
:body('What just happened?'),
:icon('stop')
).show;
sleep 2;
$n.update(:summary('Oh well!'), :body('Not quite a disaster!'), :icon('stop')).show;
use v6;
use Desktop::Notify :constants;
my $notify = Desktop::Notify.new(app-name => 'myapp');
my $n = $notify.new-notification('Attention!', 'What just happened?', 'stop');
$notify.set-timeout($n, NOTIFY_EXPIRES_NEVER);
$notify.show($n);
sleep 2;
$notify.update($n, 'Oh well!', 'Not quite a disaster!', 'stop');
$notify.show($n);
If you run the second program, note that the notification doesn't fade by itself, but you need to click on it in order to close it.
For more examples see the example directory.
Documentation
There are three interfaces available: the Raw interface which maps the library's C functions, an OO interface
which exposes most of the low level functionality, and a Simple interface.
To use the low-level interface:
use Desktop::Notify::Raw;
to use the intermediate-level interface:
use Desktop::Notify;
to use the simple interface:
use Desktop::Notify::Simple;
The Raw interface
Please refer to the original C library documentation here.
The intermediate-level interface
new(Str $appname)
Constructs a new Desktop::Notify object. It takes one mandatory argument:
app-name, the name of the app that will be registered with the notify dæmon.
is-initted(--> Bool)
Returns True if the object has been successfully initialized.
app-name(--> Str)
app-name(Str $appname)
Queries or sets the app name.
new-notification(Str $summary!, Str $body!, Str $icon! --> NotifyNotification)
new-notification(Str :$summary!, Str :$body!, Str :$icon!, Int :$timeout?, Str :$category?, NotifyUrgency :$urgency? --> NotifyNotification)
Creates a new notification.
The first form takes three positional arguments: the summary string, the notification string and
the icon to display (See the libnotify documentation for the available icons).
The second form takes a number of named argument. summary, body, and icon are mandatory,
the others are optional. If timeout, category, and urgency are defined, this method will call
the corresponding "set" methods documented below.
show(NotifyNotification $notification!, GError $err? --> Bool)
Shows the notification on screen. It takes one mandatory argument, the
NotifyNotification object, and one optional argument, the GError object.
(The default Desktop::Notify error handling is not thread safe. See Threading safety
for more info)
close(NotifyNotification $notification!, GError $err? --> Bool)
Closes the notification. It takes one mandatory argument, the NotifyNotification
object, and one optional argument, the GError object. (The default
Desktop::Notify error handling is not thread safe. See Threading safety for
more info)
Note that usually there's no need to explicitly close a notification, since
the default is to automatically expire after a while.
why-closed(NotifyNotification $notification! --> Int)
Returns the the closed reason code for the notification. It takes one argument, the NotifyNotification object. (See the libnotify documentation for the meaning of this code)
get-type(--> Int)
Returns the notification type.
update(NotifyNotification $notification!, Str $summary, Str $body, Str $icon --> Bool)
Modifies the messages of a notification which is already on screen.
set-timeout(NotifyNotification $notification!, Int $timeout!)
Sets the notification timeout. There are two available constants,
NOTIFY_EXPIRES_DEFAULT and NOTIFY_EXPIRES_NEVER, when explicitly imported
with use Desktop::Notify :constants;.
set-category(NotifyNotification $notification, Str $category!)
Sets the notification category (See the libnotify documentation).
set-urgency(NotifyNotification $notification, NotifyUrgency $urgency!)
Sets the notification urgency. An enum NotifyUrgency <NotifyUrgencyLow NotifyUrgencyNormal NotifyUrgencyCritical>
is available when explicitly imported with use Desktop::Notify :constants;.
server-caps(--> Seq)
Collects the server capabilities and returns a sequence.
server-info(--> Hash)
Reads the server info and returns an hash. The return value of the C function call is
returned as the value of the return key of the hash.
The simple interface
new(Str :$app-name!, Str :$summary!, Str :$body!, Str :$icon!, Int :$timeout?, Str :$category?, NotifyUrgency :$urgency?)
Constructs a new Desktop::Notify::Simple object. It takes four mandatory arguments:
- $app-name the name of the app that will be registered with the notify dæmon.
- $summary appears in bold on the top side of the notification
- $body notification body
- $icon icon name
and three optional arguments:
- $timeout expressed in seconds (while Desktop::Notify uses milliseconds)
- $category can be used by the notification server to filter or display the data in a certain way
- $urgency urgency level of this notification
An enum NotifyUrgency <NotifyUrgencyLow NotifyUrgencyNormal NotifyUrgencyCritical> is available.
show(GError $err?)
Shows the notification on screen. It takes one optional argument, the GError object.
(The default Desktop::Notify error handling is not thread safe. See Threading safety for more info)
update(Str :$summary, Str :$body, Str :$icon)
Modifies the messages of a notification which is already on screen.
close(GError $err?)
Closes the notification. It takes one optional argument, the GError object. (The default Desktop::Notify error
handling is not thread safe. See Threading safety for more info)
Note that usually there's no need to explicitly 'close' a notification, since the default is to automatically
expire after a while.
Threading safety
Desktop::Notify offers a simple interface which provides an error class member,
which is automatically used by the functions that need it.
Since error is a shared class member, if a program makes use of threading, its value
might be written by another thread before it's been read.
In this case one can declare their own GError variables:
my $err = Desktop::Notify::GError.new;
and pass it as an optional argument to the .show() and .close() methods; it will be used instead of the object-wide one.
Prerequisites
This module requires the libnotify library to be installed. Please follow the instructions below based on your platform:
Debian Linux
sudo apt-get install libnotify4
Installation
$ zef install Desktop::Notify
Testing
To run the tests:
$ prove -e "perl6 -Ilib"
Author
Fernando Santagata
License
The Artistic License 2.0