Developers‎ > ‎Creating AddOns‎ > ‎

Runnable Styles


Introduction

Runnable styles are just that - styles which Snarl 'runs' in order to generate content which can then be displayed as a notification.  The style has full control over the look of the content (including the size and shape); Snarl retains control over where the content is displayed.  Consequently, runnable styles offer a happy medium between ease of creation and control over the resulting content.

Setting Up

Required Components

A runnable style must provide the following:
  • A configuration file called runnable.conf;
  • A style executable called style.exe (however, see note in Configuration File Settings below);
  • An icon called icon.png.
All of the above must exist within a folder named using the following convention:

vendor-style_name

Ultimately, the folder naming convention is there to ensure two styles with the same name but from different vendors do not compete for the same folder name.  The following are examples of acceptable folder names:
  • acme-my_style
  • foo-bar_style
  • qux-a_long_style_name_with_no_spaces

Configuration File Settings

The configuration file (runnable.conf) is a standard text file which can be created using any suitable editor.  It should consist of a [general] section and an optional [schemes] section.
 

General Section

Only some settings are mandatory - the following table describes the settings supported, what they do, and indicates whether they are required or not:

Setting  Requirement Description Comments
description  Mandatory  Provides a description of the style   
email  Optional  Email address that users can use for technical support  
icon  Optional  Provides an alternative icon name (for example, if a non-PNG icon is used) If missing, "icon.png" is assumed 
major  Mandatory  The major version number of the style  Must be numeric 
minor  Mandatory  The minor version number of the style  Must be numeric 
name  Mandatory  The name of the style   
redirect Optional Set to "1" if the style is a redirect If missing, the style is assumed to be a standard display 
style_exe  Optional  Alternative name of style executable (e.g. "style.vbs")  If missing, "style.exe" is assumed 
url  Optional  URL to the style provider's website   
 

Schemes Section

Available schemes should be listed as they are expected to appear to the user (that is, with the required upper and lowercase).

Example Configuration File

[general]
description=Just a simple demonstration...
icon=icon.png
major=1
minor=0
name=Alectric
email=info@fullphat.net
url=http://www.fullphat.net
 
[schemes]
Dark
Light

Icon Requirements

The supplied icon.png should conform to the following:
  • It should be a PNG image with transparency enabled.  JPEG, GIF and BMP images are also acceptable but not recommended;
  • It should be square (that is, the width should match the height);
  • It should be a least 256 pixels wide (and, thus, 256 pixels tall).

Style Creation

Style creation is the job of the style executable.  The executable can be a standard Windows executable file, or it can be a script file which Windows is able to execute indirectly (e.g. via knowledge of the extension) so something like style.vbs would work fine under most conditions.

In order to generate suitable content, the style executable must:
  • Generate a PNG image in the same folder as the executable;
  • Ensure the image is called content.png;
  • Complete all it needs to do within 500ms (this setting is configurable but applies to all runnable styles);
  • Terminate gracefully either after successfully creating the PNG image, or in the event of an error occurring.
Failure to do any of the above will result in Snarl rejecting the generated content.  The notification will still be displayed however, only using Snarl's own internal style.

Note: If the style has indicated that it is a redirect (by setting the appropriate value in runnable.conf) then the style must still create a content.png file, however this file may be zero bytes (and, thus, not a genuine PNG image).

Command Line Arguments

Snarl communicates with the style executable in two ways:
  • If it needs the style to do something (for example, to display its user interface);
  • If it needs the style to create updated graphical content.
If Snarl needs the style to do something other than create its graphical content, the first argument will be preceded with a minus sign ('-') for example:

style.exe -configure

Is Snarl's way of asking the style to display its user interface.

In these cases the style should handle the command silently (even if it doesn't support the command) and not generate any image content.

If the argument does not begin with a minus sign, then Snarl is asking the style to generate updated graphical content and the argument will be the originating API request which Snarl received.

Specifics

In addition to the mandatory requirements for the style executable, developers should also note the following:
  • If a non-binary executable is used as the style executable, care should be taken that a user's environment and security settings enable the execution of the style;
  • It's the responsibility of the style to ensure any required libraries, frameworks, etc. are present on the user's machine.


Distribution

Once completed, you should create a zip of the folder containing your style.  You must ensure the folder path structure is preserved inside the zip file, as follows:

acme-foo/icon.png
acme-foo/runnable.conf
acme-foo/style.exe

Finally, you should rename the zip file so that it has a '.rsz' extension.  Snarl users can then double-click the file or drag it onto Snarl's Preferences panel in order to install it.

Worked Example

This example uses VBscript to create a very simple redirect style which simply logs notifications to a text file.  Error detection, actually doing something useful with the notification content, and so on are all left to the developer as further work.

Setting Up

The first thing to do is create the required folder structure:
  • Navigate to %Application Data%\full phat\snarl\styles\runnable\
  • Create a folder called "acme-logger"
  • Open the folder and create a new text file (right-click, select New->Text Document)
  • Rename the resulting New Text Document.txt to runnable.conf
  • Create another text file and name it style.vbs

The Configuration File

Now we need to populate the runnable.conf file: 
  • Open runnable.conf (right-click it, select Open With... and then pick Notepad from the list that appears)
  • Paste the following into Notepad:
[general]
description=Simple example
major=1
minor=0
name=Logger
redirect=1
style_exe=style.vbs
 
  • Save the file and quit Notepad.

The Style Executable

Now we need to create the style executable.  For this example style, we'll use a simple VBscript:
  • Open style.vbs (right-click it and select Edit)
  • Paste the following into Notepad:
Dim oSh, oFSO, oArgs, oFile
 
set oSh = CreateObject("WScript.Shell")
Set oFSO = CreateObject("Scripting.FileSystemObject")
Set oFile = oFSO.OpenTextFile(oSh.CurrentDirectory & "\log.txt", 8, True)
Set oArgs = Wscript.Arguments
 
If oArgs.Count > 0 then _
    oFile.WriteLine(oArgs(0))
 
oFile.Close
 
Set oArgs = Nothing
Set oFile = Nothing
Set oFSO = Nothing
Set oSh = Nothing
  • Save the file and quit Notepad.

Testing

To test the style, the runnable style engine will need to be stopped and restarted.  To do this:
  • Open Snarl's preferences
  • Select the Styles page
  • Click the Advanced... button
  • In the Installed Style Engines window which appears, select the Runnable entry
  • Click Stop
  • Wait for Snarl to notify the style engine has stopped
  • Click Start
  • Close the Installed Style Engines window
  • In the Styles page, select the Redirect Styles tab (R2.5 only)
  • In the list of styles, select Logger
  • Click Test
To verify that the test worked successfully, navigate to the acme-logger folder you created at the start of the example and open the log.txt file.
Comments