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.