GraphStream style sheet reference

This is not a tutorial but more a reference. This page lists all the style properties available when using style sheets as well as their default values and effects.

Categories of style properties

Style elements or properties are pairs name:value that allow to construct rules that will apply to graph elements in style sheets.

See this tutorial for an explanation of how properties work and what is their basic syntax.

There are four categories : general properties that may apply to all graph elements, node properties that apply only to nodes, edges properties only for edges and sprite properties.

Values and units

Some properties take numeric values as arguments, other expect either a keyword or a more complex value (composed of several numeric values for example).

Colours

Colouurs values can be provided in three ways :

1. Name (e.g. red, lime, LightGrey).
2. HTML "sharp" notation (e.g. #F0aC45").
3. CSS notation (e.g. rgb(0,128,255)).

The colour names come from the "X11 colour name database" that share a large subset with the HTML colour name database. You can find this database here as well as some explanations about the colour names.

node { color: red; }

The HTML "sharp" notation uses three hexadecimal numbers to specify the red, green and blue components respectively of a colour in RGB colour space. In this model hexadecimal number 00 means no colour and FF is full colour. The values syntax is as follows : a sharp sign (#) followed without space by three hexadecimal numbers using two digits without spaces between them or between the digits. For example this #FF0000 is red, #00FF00 green and #FFFF00 yellow.

node { color: #A0b1C3; }

The CSS notation is the only one that allows to specify transparency also called "alpha" values. It can be specified in two ways, depending on the fact an alpha value is provided or not. For opaque colors you use the rgb(n,n,n) notation where n is a decimal number between 0 and 255, with 0 meaning no color and 255 full color. The three numbers are for red, green and blue values respectively. For example rgb(255,0,0) is red, rgb(0,255,0) is green and rgb(255,255,0) is yellow.

node { color: rgb(10,200,30); }

When you want to provide a transparency value, you can use the rgba(n,n,n,n) notation that works exactly the same as the rgb() notation but adds a fourth value that specify transparency, with 0 meaning no transparency (opaque) and 255 meaning full transparency.

node { color: rgba(10,200,30,128); }

Many properties can take several colours as argument. This allows to implement gradients, multicoloured elements, foreground/background elements, etc. You merely put several colour values separated by spaces to specify several colours.

sprite { color: red green blue cyan; }

Lengths and units

Length are simple decimal numeric values. However you can also specify an unit for the value. By default, when you do not specify the units, most values are understood in pixels, but this is not always the case (notably for fonts where points are used). The default unit is specified for each property.

There are three specifiable units :

1. pixels or PX,
2. graph units or GU,
3. and percents.

Pixels units are specified by appending px to a value without space between the value and the px specifier. Graph units are specified the same way using the gu suffix. Percents are specified using the % sign.

node { width: 0.3gu; border-width: 2px; }
sprite { width: 5%; }

Pixel units should be self-explanatory. Graph units are the units you use to specify the coordinates of nodes, edges and sprites in you program. This are the values you pass when you use the x, y, z, xy and xyz attributes on nodes, edges or sprites. If you use the default graph automatic layout and do not place graph elements by yourself, the GU are the units used by the automatic layout.

In default mode, the graph viewer ensures the whole graph is visible. So if you place three nodes at graph units (-1,0), (1,0) and (0,1), they will always be at the bottom-left, bottom-right and top-middle respectively of the viewer, whatever be the size in pixels of the viewer display. However, as by default node width is given in pixel units, the size of nodes will not vary if you enlarge the viewer window.

Percent units are percents of the graph display diagonal and allows to specify lengths that vary according to the size of the whole graph.

Fonts

To specify font names, you can use your operating system font names. You can use double-quotes or not if the font name is a single word. If the font name is composed of several words separated by spaces, you must use quoting. A good practice is to always use quotes.

Font sizes do not take unit specifier and are always specified in points.

node { text-size: 10; }

URLs

URLs are useful to specify images for example. The notation is as follows : url('text'), with text the value of the URL. Do not forget the simple (or double as you wish) quotes. URLs can refer to local files or Internet files.

You can then specify either directly a file name or an Internet URL (like http://foo/bar for example).

node { image: url('http://somewhere/over/the/rainbow.png') }

General style

Colors

color: <colours>;

The main colour of the given element. For some element styles and shapes several colors can be used. Simply put several color values separated by spaces.

The default value is plain opaque black.

node#A { color: purple; }
node#B { color: green; }
node#C { color: magenta; }
node#D { color: LimeGreen; }

Width

width: <length>;

Most graph elements can have a width. For nodes this is the overall diameter, excepted for some node shapes that have a special meaning (like the text boxes, where the width is computed according to the text). For edges this is the boldness of the stroke.

For nodes and sprites the default width is 12 pixels. For edges it is one pixel.

node { width: 5px; }

node { width: 20px; }

Height

height: <length>;

Some elements also have a height. Most node shapes are square or circle and therefore only consider the width property. However there are cases where a height is used. For example the "arrow" shape for sprites uses the width and the height properties (do not confuse them with the arrow-length and arrow-width used on edges, but that are not sprites).

For nodes and sprites the default height is 12 pixels. For edges it is one pixel.

sprite {
	sprite-shape: arrow;
	width: 30px;
	height: 10px;
}

sprite {
	sprite-shape: arrow;
	width: 10px;
	height: 30px;
}

Text

text-font: <font-name>;

The font name gives the font face to use. Examples are "sans-serif", "serif", "times", "Times New Roman", "Symbol", etc.

The default font name is "sans-serif".

text-size: <point-size>;

The text size is the size of the font in points. The default is 11 points. This length does not take a unit qualifier like other lengths as it is always given in points.

The default point size is 11 points.

text-color: <colour>

The text colour.

The default text colour is "gray".

text-style: <normal|bold|italic|bold-italic>

The text font style.

The default text style is normal.

text-align: <left|right|center|aside|along>

There are five alignments available  that are aligned according to different origins :

1. left Align the text at left of the element centre.
2. right Align the text at right of the element centre.
3. center Centre the text according to the element centre.
4. aside Put the text just at right of the overall element width.
5. along Put the text centred above an edge, rotated to run with the edge slope.

The default text alignment is center.

The three first values work according to the node, edge or sprite centre. This means that the text can overlap the element. For the aside value the text is put at right of the element, trying not to cover it. This is probably one of the most interesting value.

The along value is usable only for edges. It allows to put the text really along the edge, rotated to follow the edge slope. The text is always above the edge.

node {
	width: 8px;
	color: grey;
	text-font: 'Purisa';
	text-color: black;
	text-size: 10;
	text-style: bold;
	text-align: aside;
}

node {
	width: 18px;
	text-font: 'Purisa';
	text-color: white;
	text-size: 12;
	text-style: bold-italic;
	text-align: center;
}

Images

image: <URL>

Images can be used in various places. They can serve as node or sprite representation, as graph background, are decoration for node text boxes and text ellipses, etc.

By default the image URL is empty, which means no image is used.

Most often, the image property only specify the image URL. The only exception is for graphs. When you put an image property on a graph, it will serve as background.

For nodes and sprites you must also use the node-shape property with the value image. Also for nodes and sprites, the image is resized to the node width and height. Both the width and height must be specified.

node {
	node-shape: image;
	width: 48px;
	height: 48px;
	image: url('http://graphstream.sf.net/pix/node.png');
}

Be careful if you specify an image a width of a height for graphs, these properties are inherited by all nodes, edges and sprites.

image-offset: <number> <number>

When specifying a background image for graphs, the image width and height may be given. You can use image-offset to place it. To adjust the image to the graph size, you can use GU or percent units. In the example under, the graph range goes from (-1,-1) to (1,1).

graph {
	image: url('http://graphstream.sf.net/pix/node.png');
	image-offset: -1gu -1gu;
	width: 2gu;
	height: 2gu;
}
node { width: 10px; }
edge { width: 1px; }

(the fact the image was small and is scaled explains its appearance)

Borders

Borders can be drawn around all kinds of elements. The border takes the shape of the element and draw its contour. You can request a border on a graph to draw the graph overall extents.

border-width: <number>;

The width of the border gives the weight of the contour drawn around the element. The default is zero, which means no borders are drawn.

border-color: <colours>;

This works as for element colours.

The default colour for borders is plain opaque black.

node { color: yellow; border-color: black; border-width: 1px; }

node { color: white; border-color: grey; border-width: 2px; } edge { width: 2px; color: white; border-width: 2px; border-color: grey; }

Shadows

Shadows are quite similar to borders but are always drawn under all the rest. A Shadow is always the same shape as the element it pertains to, however they can be larger (or smaller, but this has very few uses). They may be plain or gradients using two colours. They can be exactly aligned under their elements in which case the only way to see them is to make them larger. They can also be offset as if they were cast by a light source.

shadow-style: <none|simple|gradient>

By default no shadows are drawn with the node value. The simple value draws plain shadows. The gradient value draw gradient shadows for which the two colours must be specified with the following property :

The default value is none.

shadow-color: <colours>

This works as for element colours. Notice that expected for very rare effects, it is not necessary to make shadow colours translucent using an alpha value since they are never drawn above anything else thant the graph background.

The default shadow colour is rgb(178, 178, 178).

shadow-offset: <number> <number>

When the shadow offsets are at zero, the shadows is exactly aligned with the element. Positive values offset the shadow down/right. There must be two values separated by spaces. The first is along the X axis, the other along the Y axis.

The default value is (0, 0) in pixels.

shadow-width: <number>

The shadow width is an additional width added to the size of the element that casts a shadow. For example if a node whose width is 12 pixels casts a shadows whose width is 2 pixels, the overall width of the shadow will be 14 pixels.

The default shadow width is 0.

Here is the basic use of shadows :

node {
	color: red;
	shadow-style: simple;
	shadow-offset: 3px 3px;
	shadow-width: 0px;
	shadow-color: grey;
}

But they can also be used to add a hollow around an element :

node {
	color: yellow;
	border-color: black;
	border-width: 1px;
	shadow-style: simple;
	shadow-width: 3px;
	shadow-offset: 0px 0px;
	shadow-color: blue;
}

Or for more advanced effects :

node {
	color: white;
	shadow-style: simple;
	shadow-width: 2px;
	shadow-offset: 0px 0px;
	shadow-color: grey;
}
edge {
	width: 2px;
	color: white;
	shadow-style: simple;
	shadow-width: 2px;
	shadow-offset: 0px 0px;
	shadow-color: grey;
}

This effect uses the fact shadows are always drawn first, under all the rest. You can compare this output with the one with borders above.

Z index

z-index: <number>;

The Z index property can be used to place elements one above the others. In other words it allows to define the rendering order of elements. Using this property you can draw all edges above nodes, or individual elements one above the other.

The numeric value for the Z index range from -127 to 127. By default edges are rendered first (Z index is 1), then nodes are rendered above them (Z index is 2) and finally sprites are rendered above all this (Z index 3).

It is not possible to change the z-index of shadows that are always drawn under all the rest.

node { color: grey; z-index: 1; }
edge { color: black; z-index: 2; }

Node style

Shapes

node-shape: <circle|square|cross|triangle|text-box|ellipse-box>

There are several node shapes :

• circle, square, cross and triangle are simple node shapes. These allow to draw graphs in black and white and still differentiate nodes.
• text-box and ellipse-box are special versions that draw the label of the node inside a box or ellipse. The shape enlarges itself according to the text. If an image is given, the image is drawn at the left of the text.

The default node shape is circle.

Here is an example of the text-box shape, also specifying an image.

node {
	node-shape: text-box;
	color: #E0E0E0;
	border-width: 1px;
	border-color: grey;
	image: url('http://graphstream.sf.net/pix/node.png');
}

Edge style

Shapes

edge-shape: <line|angle|cubic-curve>;

Most of the time, edges are straight lines, however you can also choose to represent them as an "angle" or as a cubic curve. Notice that the angle value works only for directed edges, as the idea is to represent a giant arrow. The width of the base of the arrow is the edge width whereas the other end is one pixel thick. as the edge width is one by default you will only see a line if you do not change the width.

The default edge shape is line.

edge { edge-shape: angle; width: 6px; }

Also note that the fact the "angle" base width is the same as the node diameter is a choice here, this is not a necessity.

The cubic-curve value makes the edges leave the nodes each 90 degrees (north, east, south, west) only. Then the edges are not drawn straight, but using a cubic curve.

edge { edge-shape: cubic-curve; }

Style

edge-style: <plain|dots|dashes>;

The edge style allows to vary the way the edge line is drawn.

The default edge style is plain.

edge#AB { edge-style: dots; }
edge#BC { edge-style: dashes; }
edge#AC { edge-style: dots; }
edge#DA { edge-style: dashes; }

Arrows

You can control the look of arrows on edges using the arrow-shape property.

arrow-shape: <none|simple|diamant|circle|image>;

The simple shape is a triangle, the diamant is a diamond. You can then control the width and length of these shapes using the two following properties :

The default arrow shape is simple.

arrow-width: <number>

The arrow width is the width perpendicular to the direction of the arrow.

The default arrow width is 4.

arrow-length: <number>

The arrow length is the width in the direction of the arrow.

The default arrow width is 16.

node {
	color: red;
	border-width: 1px;
}
edge { color: grey; }
edge#AB { arrow-shape: diamant; }
edge#BC { arrow-shape: circle; }
edge#CD {
	arrow-shape: image;
	arrow-image: url('http://graphstream.sf.net/pix/node.png');
	arrow-width: 16px;
	arrow-length: 16px;
}

Sprite style

Shapes

sprite-shape: <circle|square|image|flow|pie-chart|arrow>

The sprites are used to represent information on the edges, nodes or anywhere on the graph. The circle, square, and image work the same as for nodes. However image can be rotated to respect the sprite orientation (see under).

The flow value allows to draw a line along the edge. This line starts from the node of your choice and goes to the sprite position on the edge. This is like a fluid that fill up the edge (as if the edge was a tube.

The pie-chart allow to draw a pie chart whose colours are taken from the color property (you can pass several colours). The pie-chart values are passed as attributes of the sprite using the pie-values attribute.

The arrow value renders the sprite the same as arrows on edges, excepted the arrows can be positioned everywhere on edges, nodes or around them, as well as at any absolute position. Also the arrows can be rotate according to the sprite orientation, as seen under.

The default sprite shape is circle.

sprite-orientation: <none|from|to|origin>

Some sprite shapes can use an orientation specifier that will be interpreted according to the sprite attachment (node, edge or none). There are four orientations values :

1. none The sprite is drawn pointing up.
2. from Only usable for sprites attached to edges. The sprite will point at the source node of the edge (the one that as no arrow if the edge is directed).
3. to Only usable for sprites attached to edges. The sprite will point at the target node of the edge (the one that as the arrow if the edge is directed).
4. origin If the sprite is attached to a node, the origin is the node centre. If the sprite is attached to an edge, the origin is the sprite position on the edge.

The default sprite orientation is none.

sprite#'1' {
	sprite-shape: arrow;
	sprite-orientation: to;
	width: 6px;
	height: 20px;
}
sprite#'2' {
	sprite-shape: arrow;
	sprite-orientation: origin;
	width: 6px;
	height: 12px;
}

The example above uses two sprites whose identifiers are "1" and "2" attached to edges and positioned at (0.5,15px). The first coordinates is an half length of the edge (the middle) the other is 15 pixel perpendicular to the edge. One of the sprite points at the "target" node, the other points at the middle position on the edge.

Notice the #'1' and #'2' notation. The two sprites have identifiers whose value is "1" and "2". But the style sheet parser uses identifiers that cannot start by a number, hence the quotes.

sprite {
	sprite-shape: flow;
	z-index: -1;
	width: 7px;
}
sprite#'1' { color: #D0503077; }
sprite#'2' { color: #50D03077; }

In this example we draw two flow sprites, located at the middle of each edge. The flow starts by default from the source node. By default, the sprites are always rendered above nodes and edges. However they would here cover the nodes and edges. Here we use a z-index property to place all sprites under the nodes and edges.

sprite {
	sprite-shape: pie-chart;
	width: 20px;
	color: red green blue;
	border-width: 1px;
}

The example above requires to add the pie-values attribute to the sprites. Here we used s.addAttribute("pie-values", 0.2f,0.5f,0.3f); for example, with s a sprite. The number of colours given must match the number of values, else the colours are cycled (if there are four pie-values and three colours, the fourth pie value gets the first colour).

Graph style

Padding

padding: <number>;

Padding allows to add space around the graph. This number defines a border empty of any drawing around the graph. You can use it if some labels or sprites are out of display.

The default padding value is 0.

Background color

background-color: <colours>;

Although other elements may use this property later, actually only the graph supports it. It allows to define the colour of the background.

The default background colour is pure opaque white.