#lang scribble/doc
@(require
  (lib "manual.ss" "scribble")
  (for-label
   (lib "class.ss" "scheme")
   "growl.ss"))

@title{Growl}

@section{The @filepath{growl.ss} Module}

@defmodule[(planet "growl.ss" ("murphy" "growl.plt" 1 1))]{
                  
  This library provides a simple interface to the UDP protocol for
  @link["http://growl.info"]{Growl} notifications.
  
}

@defclass[growl% object% ()]{
                             
  A notification center class. When the class is instantiated, it
  registers the application with the Growl server.
  
  @defconstructor[([name string?]
                   [notifications (listof (or/c (list/c symbol? string? any/c)
                                                (list/c symbol? string?)))]
                   [hostname string?]
                   [port-no (integer-in 1 65535)])]{
    Creates a notification center for the application called
    @scheme[name] and connects to the Growl server running on
    @scheme[hostname]:@scheme[port-no].
    
    The possible @scheme[notifications] that can be posted by the
    application are specified as an association list. Each element
    of the list has the form @scheme[(id type [default? #t])]. The
    @scheme[id] is used in calls to @scheme[notify] to reference
    the notification while the @scheme[type] is the string that
    will appear in the configuration interface of Growl to describe
    this notification type. @scheme[default?] indicates whether the
    notification type should be enabled by default.
    
    @scheme[name] and @scheme[notifications] are accessible as fields
    of the new object.
  }
  
  @defmethod[(notify [id symbol?]
                     [#:title title string? name] [#:description description string?]
                     [#:priority priority (integer-in -2 +2) 0] [#:sticky sticky? any/c #f]) void?]{
    Sends a notification to the Growl server. The type of notification
    to send is specified by the given @scheme[id].
    
    The @scheme[title] of the notification defaults to the name of
    the application. The @scheme[description] message has to be
    specified.
    
    Optionally you can specify a @scheme[priority] hint for the
    message and a @scheme[sticky?] flag hinting that the message
    should be displayed until dismissed by the user. The effect
    of these options depends on the display style used by the
    Growl server.
  }
  
  @defmethod[(close) void?]{
    Closes the UDP socket associated with this object. No further
    notifications can be sent using this object.
  }
  
}

@section{License}

Copyright (c) 2008 by @link["mailto:chust@web.de"]{Thomas Chust @"<chust@web.de>"}.

This package is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You can find a copy of the GNU Lesser General Public License at
@link["http://www.gnu.org/licenses/lgpl-3.0.html"]{http://www.gnu.org/licenses/lgpl-3.0.html}.