# Creating Themes

This document is a brief guide to creating themes for use with NetSurf and packaging them with NSTheme. It is split up into the following sections:

- Overview
- Sprites
- Using NSTheme
- Distribution

Last updated 22 March 2005

## Overview

A theme contains a set of sprites for NetSurf's toolbar icons and some further information about the theme, such as the background colour of the toolbar and the theme name. NSTheme is an application that loads the sprites, allows the additional information to be set and then packages the theme into a single file for distribution.

## Sprites

A theme contains a number of sprites; two for each button, a single separator sprite and extra sprites for the throbber animation. These sprites are to be grouped into a single sprite file and each sprite must be given a certain name, so that they can be attributed to the correct button.

The toolbar buttons and the matching sprite names are listed below.

Browser Window
Button | Sprite name
--- | ---
Back | back
Forward | forward
History | history
Home | home
Hotlist | hotlist
Print | print
Reload | reload
Save | save
Scale View | scale
Search / Find Text | search
Stop | stop
Up | up

Hotlist Window
Button | Sprite name
--- | ---
Create Directory | create
Delete Selection | delete
Launch Selection | launch
Open Directory | open
Expand Addresses | expand

Global History Window
Button | Sprite name
--- | ---
Delete Selection | delete
Launch Selection | launch
Open Directory | open
Expand Addresses | expand

Each button has a sprite for its pressed and unpressed states. The pressed sprites are preceded with the letter 'p'. For the Save button, there will be both 'save' and 'psave' sprites.

A sprite named 'separator' is used to separate groups of icons on the toolbar and the throbber is made up of any number of sprites named 'throbber0' to 'throbberN'. When NetSurf is inactive, 'throbber0' is displayed and when it is active, the throbber animation loops through 'throbber1' to 'throbberN'.

For a five frame animation, there would be five sprites named 'throbber1' to 'throbber5' plus the inactive sprite, 'throbber0'.

The sprites can have any dimensions and if some sprites are larger than others, NetSurf will centre the smaller ones on the toolbar automatically.

## Using NSTheme

NSTheme's user interface should be fairly self explanatory and interactive help is available throughout the application. An existing theme can be loaded by dragging it to the NSTheme window. To create a new theme, drag a sprite file to NSTheme. Theme name and author information can be entered or altered with writable icons.

Tick "Left align throbber" if you want the throbber to appear at the left of the toolbar. If un-ticked, the throbber will be displayed at the right. If your throbber animation uses a mask that moves from frame to frame, tick "Redraw every frame", which clears the previous frame of amimation before plotting the new one on top. Leave "Redraw every frame" un-ticked if the throbber doesn't feature a moving mask as this feature can make the throbber flicker while it animates.

The Generate report button warns of any problems with the theme. For example, if no sprites have been loaded it will report, "No sprite file present". If a sprite file is loaded but the pressed Save button is missing, it will report, "Sprite 'psave' (browser save icon (pushed)) is missing". The Remove sprites button removes any sprites that had been loaded into the program.

Sprites can be extracted from an existing theme with the Export option on the NSTheme window menu. When creating a new theme it may be helpful to extract the sprite file from the supplied theme (`!NetSurf.Resources.Theme`) and replace these sprites with your own.

In the colours section, the background colours for the browser window toolbar, the hotlist toolbar and the browser window's status bar can be configured, along with the colour of text displayed in the status bar.

To save a finished theme, use the save option in the NSTheme window menu. Once a theme file has been created, it must be placed in `Choices:WWW.NetSurf.Themes` to be found by NetSurf.

## Distribution

Completed themes can be submitted for inclusion on NetSurf's themes page. They are served as `Content-Type: application/x-netsurf-theme` which NetSurf recognizes and installs as themes.