libSnarl

Contents


libSnarl is a Windows COM component which provides access to the Snarl API without the need for hand-crafted requests.  It also provides seamless network access via SNP3 to instances of Snarl running on remote computers.



libSnarl is installed by Snarl during the setup process, however if you want to use libSnarl's functionality on computers without Snarl installed, you can download it using these links:
  • libSnarl 1.0 Beta 1 (current Beta)



Basic Usage
  • Create new SnarlApp object
  • Create new Classes object
  • Add classes to Classes object
  • Call SnarlApp->Show()
  • Receiving feedback
Network Notifications
  • Sending over the network
  • Adding destinations



Actions Object

Contains zero or more actions which are added to the notification when it is displayed.  Actions objects are assigned through the Notification.Actions property.  The same Actions object can be used with multiple notifications.  See the Snarl Integration Guide for more details on how to use actions with notifications.

Member Functions

Add()

Void Add(str Label, str Command)

Adds an action to the object.  When a notification is created, Label will be displayed in the notification's actions menu and Command will be returned via the SnarlApp.NotificationActionSelected event.

Note: Although it is legal to have multiple actions each with the same name and command in this object, Snarl will filter the actions before adding them to the notification.  Generally speaking, you should avoid using multiple actions with either the same Label, the same Command, or a mixture of both.

Add does not return a success value; to determine if the action was added successfully, do the following:

n = myActions.Count()
myActions.Add("foo", "bar")
WasSuccessful = (myActions.Count() = (n+1)

Count()

int32 Count()

Returns the number of items in this object.

MakeEmpty()

Void MakeEmpty()

Removes all items from the object.

Remove()

Void Remove(int32 Index)

Removes the item specified by one-based Index from the list of actions.  Note that this does not affect any existing on-screen notifications; only subsequent notifications created using this object.


Classes Object

Contains zero or more classes which are added to the application when it is registered.  Classes objects are assigned through the snarlApp.Classes property.  The same Classes object can be used with multiple registrations (although this would be unusual practice).  See the Snarl Integration Guide for more details on how to use classes.

Member Functions

Add()

Void Add(str Namestr Description, bool Enabled = TRUE, str DefaultTitle = "", str DefaultText = "", str DefaultIcon = "", str DefaultCallback = "")

Adds a new class to the object.  
Name
 and 
Description
 are required.  
Name
 is used to identify any notifications associated with the class; 
Description
 is displayed by Snarl to the end-user.  
Enabled
 determines the initial state of the class.  
DefaultTitle
DefaultText
DefaultIcon
 and 
DefaultCallback
 are all optional and are used by Snarl if any of the corresponding entries in a notification created using this class are omitted.

Count()

int32 Count()

Returns the number of items in this object.

MakeEmpty()

Void MakeEmpty()

Removes all items from the object.

Remove()

Void Remove(int32 Index)

Removes the item specified by one-based Index from the list of classes.  Note that this does not affect the application's registration with Snarl; only subsequent registrations created using this object.


Destinations Object

     
     
     



Notification Object

The notification object provides the actual content of the notification to display.  The same object can be used and re-used multiple times.

Properties

Name Type Description
Actions Actions Object containing zero or more actions to add to the notification 
CallbackScript String  Path to script containing callback handlers
CallbackScriptTypeString Callback script handler type (currently only "VBScript" and "JScript" are defined)
Class String Name of Class to use
DefaultCallbackString Filesystem path of command to run or URL of page to open if the user clicks the notification
DurationInt32 Amount of time (in seconds) the notification should remain on-screen for.  Use -1 to use the Snarl default; use zero to indicate an infinite duration ("sticky")
IconString Path or URL of the icon to use
MergeUIDString UID of existing notification to merge with
Priority NOTIFICATION_PRIORITYNotification priority
ReplaceUIDString UID of existing notification to replace
TextString Notification text
TitleString Notification title 
UIDString Unique IDentifier



SnarlApp Object

Events

Activated()

Void Activated()

Fired when the user selects the application's entry in the Snarl Daemons pop-up window.

NotificationActionSelected()

Void NotificationActionSelected(str UIDstr Identifier)

Fired when the user selects an action from a notification created by the application.   
UID
 identifies the notification;
 
Identifier
 
 is the action's command. 

NotificationExpired()

Void NotificationExpired(str UID)

Fired when a notification created by the application has disappeared without any interaction from the user.   
UID
 identifies the notification

NotificationInvoked()

Void NotificationInvoked(str UID)

Fired when a notification created by the application is clicked by the user.   
UID
 identifies the notification

Quit()

Void Quit()

Fired when the user selects the Quit option in the [Apps] page in Snarl's preferences.

ShowAbout()

Void ShowAbout()

Fired when the user selects the Details... option in the [Apps] page in Snarl's preferences.

ShowConfig()

Void ShowConfig()

Fired when the user selects the Configure option in the [Apps] page in Snarl's preferences.

SnarlLaunched()

Void ShowConfig()

Fired when Snarl is launched by the user.

SnarlQuit()

Void ShowConfig()

Fired when Snarl is about to quit.

Properties

NameType Description
ClassesClassesClasses object containing one or more notification classes to include during registration. 
ConfigToolString Path to the application's configuration tool.  If provided, Snarl will launch the tool whenever the user clicks Configure... in the [Apps] preference page. 
DestinationsDestinations 
HintString Application description.  If provided, Snarl will display a notification containing the hint if the user clicks Details... in the [Apps] preference page. 
IconIcon Path or URL to the icon to use. 
IsDaemonBoolean Identifies whether or not the application is a Daemon (GUI-less) - if TRUE, Snarl will add an entry for it in the Snarl Daemons pop-up window. 
SignatureString The application's signature. 
TitleString The application's title. 

Member Functions

GetEtcPath()

str GetEtcPath()

Returns the current path to Snarl's configuration folder.

Hide()

STATUS_CODE Hide(str UID)

Hides the notification identified by UID.

IsSnarlRunning()

bool IsSnarlRunning()

Returns TRUE if Snarl is currently running, FALSE otherwise.

MakePath()

str MakePath(str Path)

Ensures Path has a trailing blackslash.

Show()

STATUS_CODE Show(Notification Notification)

Displays Notification on-screen.

SnarlVersion()

int32 SnarlVersion()

Returns the version number of Snarl that's running on the user's computer.