EZ Style Guide

EZ Style Guide - Introduction


Getting Started

Snarl EZ Styles are text-based static styles that allow you to create relatively advanced looking notifications for Snarl.


What You Need

Snarl R2.06 or later, a text editor and - optionally - some graphics.


Specifying Colours

A number of entries require colour values. The EZ style engine accepts colours in the following formats:

Format Syntax Examples
HTML #rrggbb[aa] #ca307f
#ee553388
Comma r,g,b[,a] 255,0,0
128,16,32,96
Long n/a 19356

 

EZ Style Basics


Style Contents

An EZ Style consists of the following:

  • A folder with an .ezstyle extension;
  • An ezstyle.conf file;
  • One or more scheme files;
  • A single style preview image or one or more individual scheme preview images.

The .ezstyle folder must be located in the user's application data folder for Snarl to find it. From Snarl R2.06 a 'Reload Styles' button has been included on the Styles tab - this lets the user reload all styles without having to stop and restart Snarl. The .ezstyle folder should be named such to avoid conflict with other EZ Styles. As such, the following naming convention should be used: 

author-style-version.ezstyle

Some examples: 

k23-hong_kong_phooey.ezstyle
k23-hong_kong_phooey-2.ezstyle
acme-wile-e-coyote.ezstyle

The ezstyle.conf File

This file should be located inside the .ezstyle folder. It should be a standard text file which follows the Windows 'INI' file style of format - that is, the file is broken down into sections and each section contains a number of "name=value" pairs, as follows:. 

[section 1]
myitem=some_value

[section 2]
something=something_else

The ezstyle.conf file current only supports a single section called [info]. Valid items within this section are:

name Required: defines the style name as it appears in the list in the Styles tab.
author Optional: name of the style's creator.
date Optional: date the style was released in d-mmm-yyyy format (e.g. 1-Jan-1978).
version Required: major version number.
revision Optional: minor version number.

Scheme Files

A scheme file follows the same 'INI' style format as the ezstyle.conf file, except that the filename is used as the scheme name. For this reason, complex (i.e. non-ASCII) characters in scheme names should be avoided.

A scheme file must consist of at least 3 sections - [background], [title], and [text] - and can also include an optional [icon] section.

[background] Section

type

Defines the notification background type, from the following:

solid Single-colour background
v-gradient Vertically shaded background
h-gradient Horizontally shaded background
image Multiple images

If type is solid, the following must also be specified:

colour1 The background colour to use - see the Colours section for more information on this

If type is v-gradient or h-gradient, the following must also be specified:

colour1 The top or left colour to use - see the Colours section for more information on this
colour2 The bottom or right colour to use - see the Colours section for more information on this

If type is image, the following must also be specified:

image-top Name of the image file to be used for the top of the notification
image-middle Name of the image file to be used for the middle of the notification
image-bottom Name of the image file to be used for the bottom of the notification

Note:

  • All three images must be specified (and valid);
  • All three images must be the same width;
  • All three images must be at least 1 pixel high;
  • The middle image will be tiled vertically to fit the notification height less the top and bottom images;
  • Where the notification is not exactly a whole number of images high, the middle image will be part-drawn to fit.

edge-type

Defines the notification edge type, from the following:

solid Single-colour edge

edge-colour

Defines the notification edge colour. See the Colours section for valid entries.

Note: If edge-type is not specified (or is specified but isn't solid) then no outer border is drawn. Also, edge-colour only needs to be specified if edge-type is solid.

[title] and [text] Sections

These two sections define how the title and text parts of the notification will look. Both sections use the same parameters, as follows:

font-face=Segoe UI
font-size=9
font-style=outline,bold
font-colour=0,85,170
outline-colour=255,255,255
margin-left=6
margin-top=2
margin-right=32

[icon] Section

This section defines how the notification's icon (if one is present) is displayed. This section is optional.

align

Defines the position of the icon in "horizontal,vertical" format, for example: 

align=left
align=top
align=left,top
left Align to the left
right Align to the right
centre Align centrally
top Align to the top
bottom Align to the bottom
middle Align centrally vertically

 

alpha

Specifies the opacity to draw the icon in with zero being completely transparent to 255 being completely opaque. If this entry is not specified, a value of 255 is used.

float

Identifies if the icon 'floats' or not. An icon which floats does not affect the position of the title or text of the notification, while one that doesn't float will cause the title or text to be adjusted to fit around it. If this entry is not specified, a value of yes is used.

yes Icon will float
no Icon does not float

 

offset-x and offset-y

These two values specify an offset in pixels applied to the alignment of the icon. These values only apply to alignment settings top, left, bottom and right. For bottom and right alignments, the value specified is subtracted; for the other two alignments, the value is added.

 

width

Specifies the size of the icon in pixels. Currently the icon is assumed to be square (both sides equal) so the same value is applied to the icon's width as well. Future revisions of the EZ Style engine will include support for non-square icons.