tin 0.0.2 → 1.0.0

data/README.md

@@ -11,21 +11,34 @@ tin provides a simple interface to libnotify.
 FEATURES/PROBLEMS:
 ------------------
 
-* Very simple
+* Simple, one method notifications
+* Notification class for more complicated needs
+* Includes most (non-deprecated) libnotify features
+
 
 SYNOPSIS:
 ---------
 
     require 'sn'
 
+    # a simple demo
     summary = 'tin demo'
     message = 'Just a quick message from tin!'
-    Sn::Notification.new(summary, message).show
+    Sn.notify(summary, message)
+
+    # a customized demo
+    notification = Sn::Notification.new(summary, message)
+    notification.timeout = :never
+    notification.show
+    sleep 6
+    notification.close
+
 
 REQUIREMENTS:
 -------------
 
 * Ruby 1.9
+* libnotify (tested with version 0.7.5)
 
 INSTALL:
 --------
@@ -35,12 +48,7 @@ INSTALL:
 DEVELOPERS:
 -----------
 
-After checking out the source, run:
-
-    $ rake newb
-
-This task will install any missing dependencies, run the tests/specs,
-and generate the RDoc.
+There is nothing special to know...
 
 LICENSE:
 --------

data/lib/sn.rb

@@ -1,46 +1,190 @@
 require 'fiddle'
 
+=begin
+
+Tin is a simple interface to libnotify using Fiddle.
+
+== Example
+
+    require 'sn'
+
+    # a simple demo
+    summary = 'tin demo'
+    message = 'Just a quick message from tin!'
+    Sn.notify(summary, message)
+
+    # a customized demo
+    notification = Sn::Notification.new(summary, message)
+    notification.timeout = :never
+    notification.show
+    sleep 6
+    notification.close
+
+== Notes
+
+Deprecated functions are not included in the those available through Sn.
+
+These function are also not included (for lack of a good implementation):
+ * void notify_notification_set_hint(NotifyNotification *notification,
+        const char *key, GVariant *value);
+ * void notify_notification_clear_hints(NotifyNotification *notification);
+ * void notify_notification_set_image_from_pixbuf(
+        NotifyNotification *notification, GdkPixbuf *pixbuf);
+ * void notify_notification_add_action(NotifyNotification *notification,
+        const char *action, const char *label, NotifyActionCallback callback,
+        gpointer user_data, GFreeFunc free_func);
+ * void notify_notification_clear_actions(NotifyNotification *notification);
+=end
+
 module Sn
   include Fiddle
 
-  def self.start(app_name)
-    @dl = DL.dlopen 'libnotify.so'
-    @init = Function.new(@dl['notify_init'], [TYPE_VOIDP], TYPE_INT)
-    @uninit = Function.new(@dl['notify_uninit'], [], TYPE_VOID)
-    @newnot = Function.new(@dl['notify_notification_new'],
-                           [TYPE_VOIDP, TYPE_VOIDP, TYPE_VOIDP], TYPE_VOIDP)
-    @shownot = Function.new(@dl['notify_notification_show'],
-                            [TYPE_VOIDP, TYPE_VOIDP], TYPE_INT)
-    @init.call app_name
-  end
+  # Mapping from keyword urgencies to the in values used by libnotify
+  URGENCIES = {:low => 0, :normal => 1, :critical => 2}
 
+  # Uninitialize libnotify
   def self.stop
-    @uninit.call
+    @notify[:uninit].call
   end
 
-  def self.create(summary, message="", icon="")
-    @newnot.call summary, message, icon
+  # Setup the libnotify interface and initialize libnotify.
+  def self.start(app_name)
+    notify_cmd = {
+        :init => {:arg => [TYPE_VOIDP], :ret => TYPE_INT},
+        :uninit => {:arg => [], :ret => TYPE_INT}
+    }
+
+    notification_cmd = {
+      :new => {:arg => [TYPE_VOIDP, TYPE_VOIDP, TYPE_VOIDP],
+               :ret => TYPE_VOIDP},
+      :show => {:arg => [TYPE_VOIDP, TYPE_VOIDP], :ret => TYPE_INT},
+      :update => {:arg => [TYPE_VOIDP, TYPE_VOIDP, TYPE_VOIDP, TYPE_VOIDP],
+                  :ret => TYPE_INT},
+      :set_urgency => {:arg => [TYPE_VOIDP, TYPE_INT], :ret => TYPE_VOID},
+      :close => {:arg => [TYPE_VOIDP, TYPE_VOIDP], :ret => TYPE_INT},
+      :get_closed_reason => {:arg => [TYPE_VOIDP], :ret => TYPE_INT},
+      :set_app_name => {:arg => [TYPE_VOIDP, TYPE_VOIDP], :ret => TYPE_VOID},
+      :set_timeout => {:arg => [TYPE_VOIDP, TYPE_INT], :ret => TYPE_VOID},
+      :set_category => {:arg => [TYPE_VOIDP, TYPE_VOIDP], :ret => TYPE_VOID},
+    }
+
+    dl = DL.dlopen 'libnotify.so'
+    
+    @notify = {}
+    notify_cmd.each do |k, v|
+      name = "notify_#{k.to_s}"
+      @notify[k] = Function.new(dl[name], v[:arg], v[:ret])
+    end
+
+    @notification = {}
+    notification_cmd.each do |k, v|
+      name = "notify_notification_#{k.to_s}"
+      @notification[k] = Function.new(dl[name], v[:arg], v[:ret])
+    end
+
+    @app_name = app_name
+    @notify[:init].call app_name # 1 or 0
+
+    at_exit do
+      Sn.stop
+    end
   end
 
-  def self.show(notification)
-    @shownot.call notification, nil
+  start $0 # Run start immediatle so @notification and @app_name are available
+
+  # Provides access to the individual Fiddle::Function objects.
+  NOTIFICATION = @notification
+
+  # The application name used to initialize libnotify
+  APP_NAME = @app_name
+
+  # Create and display a notification using (mostly) default values.
+  def self.notify(summary, message="", icon="")
+    n = @notification[:new].call(summary, message, icon)
+    @notification[:show].call n, nil
   end
 
+  # This class manages an application notification.
   class Notification
+    attr_reader :app_name, :category, :summary, :message, :urgency, :icon
+
+    # Mapping from keyword timeouts to the int values libnotify uses
+    @@timeout_consts = {:default => -1, :never => 0}
+
+    # +summary+:: the summary line generally displayed at the top of the
+    # notification
+    #
+    # +message+:: the message text of the notification
+    # 
+    # +icon+:: a theme name or file path for an icon to display with the
+    # notification (if this is supported?)
     def initialize(summary, message="", icon="")
-      @notification = Sn.create summary, message, icon
+      @summary = summary
+      @message = message
+      @icon = icon
+      @urgency = :normal
+      @category = ""
+      @app_name = APP_NAME
+      @notification = NOTIFICATION[:new].call summary, message, icon
     end
     
+    # Send the notification to the system
     def show
-      Sn.show @notification
+      NOTIFICATION[:show].call @notification, nil
+    end
+    
+    # Close this notification.
+    def close
+      NOTIFICATION[:close].call @notification, nil
+    end
+
+    # Obtain the reason that this notification was closed.
+    def closed_reason
+      NOTIFICATION[:get_closed_reason].call @notification
     end
-  end
-end
 
-Sn.start $0
+    # Register changed summary, body, and icon values.
+    # Each time any of these fields are assigned, they will be updated by
+    # calling this method automatically.  Generally, it should not be necessary
+    # to call this method explicitly.
+    def update
+      NOTIFICATION[:update].call @notification, @summary, @body, @icon
+    end
+
+    def summary=(value)
+      @summary = value
+      update
+    end
 
-at_exit do
-  Sn.stop
+    def message=(value)
+      @message = value
+      update
+    end
+
+    def icon=(value)
+      @icon = value
+      update
+    end
+
+    def category=(value)
+      @category = category
+      NOTIFICATION[:set_category].call @notification, @category
+    end
+
+    # Set the timeout that controls when the notification will be closed.  The
+    # timeout can be specified as a number of milliseconds or using the keywords
+    # +:default+ or +:never+.
+    def timeout=(timeout=:default)
+      @timeout = @@timeout_consts[timeout] if @@timeout_consts.member?(timeout)
+      NOTIFICATION[:set_timeout].call @notification, @timeout
+    end
+
+    def urgency=(value)
+      @urgency = value
+      NOTIFICATION[:set_urgency].call @notification, URGENCIES[@urgency]
+    end
+  end
 end
 
 
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tin
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-10 00:00:00.000000000 Z
+date: 2012-05-21 00:00:00.000000000 Z
 dependencies: []
 description: An incredibly simple interface to libnotify using Fiddle.
 email: baguthrie@sbcglobal.net
@@ -40,7 +40,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: tin
-rubygems_version: 1.8.23
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
 summary: Very simple libnotify access