txt: ## dist_cpan-FRITH-Desktop-Notify.md
  ## Desktop::Notify
  
  Desktop::Notify A simple interface to libnotify
  
  ## Build Status
  
  | Operating System | Build Status | CI Provider |
  | --- | --- | --- |
  | Linux | [Build Status](https://travis-ci.org/frithnanth/perl6-Desktop-Notify) | 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](https://developer.gnome.org/libnotify/0.7/).
  
  ### 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
  