Not limited to what they can do.
Snarl handles registration; extension just provides info.
Each script extension must be in its own folder. There is no set naming convention but, in order to avoid naming clashes, the recommendation is to use a folder name that follows this template:
Within the folder, there must be a script file called script.vbs which contains the extension's code. Other files (for example, icons) may also be included in this folder, and can be retrieved by the script using the ScriptExtension object's Path property.
The extension script must supply a series of procedures - known as "hooks" - which Snarl can call when it needs the extension to do something. Only one hook - ext_Init() - is mandatory.
Every extension must support an ext_Init() hook. This is called by the extension loader while Snarl starts up. The return value is not important here at present, although for compatibility with future releases of Snarl, the extension should return zero.
Prior to the call to ext_Init(), Snarl will create a ScriptExtension object and make it visible to the script with the object name of sx. In order to be loaded successfully, the extension must populate the ScriptExtensionInfo object referenced by sx.Info. The extension should complete all fields, however only the Name and Vendor fields are mandatory.
An extension can indicate it has a problem which prevents it from starting by setting the Error field to a non-zero value and entering a description of the problem in the Reason field, as follows:
Extension can provide either ext_Start(), ext_Stop() or both hooks. If provided, ext_Start() is called when the extension is enabled; ext_Stop() is called when the extension is disabled.
Currently, Snarl only ever calls these two functions as part of its startup and shutdown code, however a future release may allow the end user to selectively stop individual extensions under circumstances (when they are away or busy for example).
Classes are added and removed using AddClass() and RemoveClass() respectively.
An extension can use either Show() or ShowEx() to create notifications. ShowEx() allows a completely free-form notify command to be sent to Snarl and is therefore more powerful, but slightly more complex to use than Show() which requires a series of optional parameters.
When an extension is unloaded, Snarl calls its ext_TidyUp() hook, if it exists. An extension would typically free any resources it has allocated during its lifetime here.
Hooks are procedures which are called in response to various asynchronous events. A script only needs to define hooks for which events it wants to know about, however all scripts must define an ext_Init() hook. Some functions rely on certain hooks begin defined - for example, SetPulseRate() will ignore any value passed to it if the script does not define an ext_Pulse() hook.
Called whenever a request initiated by DoAsyncWebRequest() completes. Success will be "1" if the request was successful; "0" if it wasn't. If the request was successful, Content will contain the data retrieved from the URL.
Note that no sanity checking of the returned content is performed, so if the URL used points (for example) to a missing web page, it's more than likely that Content will contain the HTML code of a 404 error.
Called when the extension is first loaded by Snarl. The extension should complete the required elements of sx.Info or indicate a failure by setting sx.Info->Error and sx.Info->Reason accordingly. All extensions must provide this hook - see Initialising for more information.
Called when the user selects an item from the Actions Menu of a notification created by either Show() or ShowEx(). UID will contain the unique identifier assigned to the notification when it was created; Identifier will be the identifier assigned to the action selected.
Note that Snarl does not automatically remove a notification when an action is selected; your application should use Hide() if it wants to remove the notification after a particular action has been performed.
Called when a notification created by either Show() or ShowEx() was invoked by the user (invoking constitutes the user pressing and releasing the mouse button on any part of the notification not obscured by a gadget) . UID will contain the unique identifier assigned to the notification when it was created.
If defined by an extension, this hook will be called at regular intervals. The default interval is 250 milliseconds and can be changed by calling SetPulseRate().
Adds a notification class. Identifier is the internal name used in subsequent calls to Show() and ShowEx(); Name is displayed in the application list in Snarl's preferences panel. If Enabled is set to FALSE, the class will be disabled by default, otherwise it will be enabled.
DefaultTitle, DefaultText, DefaultIcon, DefaultSound and DefaultCallback are all optional and, if provided, will be used in subsequent notifications where no corresponding item is provided.
Cancels any asynchronous web request initiated by DoAsyncWebRequest().
This function does nothing if no web request is currently in progress.
Initiates an asynchronous download of content from URL. TimeoutInSeconds can be used to adjust the amount of time that may elapse before the request is cancelled. Username and Password may be provided if authentication to the site hosting the URL is required.
The script must provide an ext_AsyncWebRequestDone() hook which receives the retrieved content when the request completes.
This function fails if an existing web request is currently in progress - call CancelAsyncWebRequest() to immediately terminate any existing request.
Hides the notification identified by UID.
Care should be taken when programmatically removing notifications from the screen. See Notification Guidelines in the Developer Guide for more information.
Returns the current pulse rate for the extension. The default is 250 milliseconds.
Removes the notification class referenced by Identifier which was previously added using AddClass().
Sets the pulse rate for the notification. Milliseconds indicates the frequency of the pulse and must be at least 100. The extension must provide an ext_Pulse() hook for this function to have any effect.
Creates a notification. Class is the notification class identifier to use for the notification; UID is used to subsequently identify the notification if its content should be updated, and when a hook is called.
Title and Text are the notification's title text and body text respectively; Icon is the icon to use (see the Icons section in the Developer Guide for more information about valid icon formats).
Duration indicates the amount of time, in seconds, the notification should be displayed for. Generally speaking this should remain at the default of -1, which indicates the user-defined global setting within Snarl should be used.
If Callback is provided, then Snarl will launch the file or open the URL pointed to by it. Note that the ext_NotificationInvoked() hook is not called if a callback is provided here. See the Callbacks section of the Developer Guide for more details.
Priority indicates the urgency of the notification. Typically this should be left to the default value of zero (normal) - see Notification Priorities in the Developer Guide for more information. Similarly, Sensitivity indicates whether or not the notification contains sensitive information. Certain styles alter how they handle notifications based on the sensitivity rating - see Sensitive Notifications in the Developer Guide and the documentation for the style in question for more information.
Actions should consist of one or more "Label,Identifier" entries separated by semi-colons - see the example below.
The following creates a high priority, confidential notification with three actions:
Allows the extension to send a free-form notify command. Request is prefixed with "notify?" and the extension's signature and password before being passed to Snarl.
The following creates a notification with a tile, some text, and a meter set to 30% (if the style displaying it supports meters). It also includes the custom variable "custom-foo" set to "bar".
The ScriptExtensionInfo object allows the script to provide information about itself and must be completed during the call to ext_Init(). It is accessed through the ScriptExtension.Info property.
Adds a custom item to the object. This is reserved for future use.
The following examples demonstrate the different features available.
This example uses the ext_Pulse() hook to display a notification showing the current time. The pulse rate is set to 0.9 seconds as it doesn't need to be any more frequent than that. On each pulse, a notification with UID "_the_time_now" is displayed. Using the same UID saves screen real-estate as any existing notification will be updated rather than a new one created. When the extension is stopped, the notification is removed immediately.
This example shows how to use DoAsyncWebRequest() to retrieve the computer's current external IP address from http://whatismyip.com/. Again, we use the ext_Pulse() hook, but this time set it to only fire every 5 minutes. Note that a notification is only displayed if the IP address has changed next time the request completes.
This example shows how easy it is to create relatively complex notifications and also handle callbacks quickly and easily within a script environment.