Customizing Snowberry

From Doomsday Wiki
Jump to: navigation, search

Update Note:
The content of this article is out-of-date and should be updated with the latest details.

Cleanup Note: This article should be cleaned up to be more readable and/or to more closely follow the Wiki article guidelines.

Breakdown Note: This article should be broken down to multiple articles so that each one covers a more specific topic. Remember to categorize!

In Snowberry you can customize the user interface in several ways. For example you can

  • change the language of the user interface,
  • define your own settings or components, and
  • add new functionality to Snowberry with your own plugins.

Snowberry is an open source project: it is available for anyone and free to be modified (under GNU GPL).

Folders

As part of Snowberry's plugin architecture, files have been divided into two different places: the original system-specific installation folder (symbol <SYSTEM>), i.e. C:\Program Files\Snowberry, and the user-specific folder (symbol <HOME>), i.e.: C:\Documents and Settings\John\.snowberry.

The system-specific folders of the application (<SYSTEM>\):

\addons
\conf
\lang
\plugins
\profiles
\graphics

The user-specific folders of the application (<HOME>\):

\addons
\conf
\lang
\plugins
\profiles
\graphics
\uninstalled
\runtime

Only the user-specific folders are used via the user interface of the application. For example addons must be copied to the system-specific folder \addons by hand if needed. In \uninstalled there are the addons which you have uninstalled some time earlier and in \runtime there are i.e. files Options.rsp and log file conflicts.log. The first one contains the command line options used last time, and the second gathers the conflicts between addons attempted to load.

Configuration files

See also: Snowberry configuration file syntax

The term configuration file is used here to refer to many kinds of files:

  • The .conf files that contain information about the components of the Doomsday Engine and the configuration options offered by Doomsday. These are located in the "conf/" folder.
  • The .lang localization files that contain text strings for a particular language. These are located in the "lang/" folder.
  • The Info files that contain metadata in addons and plugin bundles.

Addons and plugins can customize Snowberry by providing their own configuration data. For example, an addon can define settings that will appear in the Settings tab when the addon is selected for loading.

Snowberry has its own format for configuration files. It is a text-based format reminiscent of Doomsday's DED files.

In conf/ folder there is four configuration files that are used to configure Snowberry and Doomsday Engine:

  • Appearance.conf: Snowberry appearance configuration; defines the styles of Snowberry UI labels
  • Components.conf: Defines the Doomsday components
  • Doomsday.conf: Defines all the Doomsday Engine settings displayed in Snowberry; i.e. their min/max value, command line option, default value, and the options for the setting displayed on the screen and their corresponding value alternatives
  • Snowberry.conf: Settings used only Snowberry; defines the Snowberry window title and the location of Doomsday.exe.

Example

Below is an example of what the definition of a setting might look like:

toggle run-in-window (
    option: -wnd
    default: no
  )

Here is another example from a .lang file:

finnish: Suomi

configure definition

Configure definitions may define any settings for Snowberry, i.e. the location of Doomsday, or the title and version of Snowberry as in Snowberry.conf [6.3]. These settings are only used by Snowberry itself.

An example on the Windows platform:

configure doomsday (
  binary: ..\Bin\Doomsday.exe
  base: ..
)

appearance definition

Appearance definitions are being used for defining styles of labels in Snowberry UI. One appearance definition is for one text style. Together these work like a CSS stylesheet.

An example of an appearance definition:

appearance style-italic (
  size: 9
  weight: normal
  slant: italic
)

setting definition

Keys common to all settings:

  • group: Group where the setting belongs to. This appears as an icon in the Settings tab.
  • subgroup: Settings are grouped on the Settings tab based on the value of this key.
  • component: One or more components that are required for using the setting.
  • addon: Identifier of the addon that is required for using the setting.

Snowberry implements a number of different setting types [5.2]: "toggle":

  • option: Doomsday command line option
  • default: Default value for the setting ("yes" or "no")
  • option-inactive: Doomsday command line option when the setting is disabled (i.e. when the value is "no")

"range"

  • option: Doomsday command line option
  • default: Default value
  • min: Minimum value
  • max: Maximum value
  • suffix: Text to append immediately after the value on the command line

"choice"

  • option: Doomsday command line option
  • default: Default value
  • alts: Altenative values
  • opts: Corresponding value options used on the command line when launching Doomsday
choice renderer (
  option: -gl
  default: opengl
  alts < opengl, direct3d >
  opts < "drOpenGL.dll", "drD3D.dll" >
)
  • existing: This is a special keyword. It allows adding new alternatives to an existing choice setting. For example, assuming a choice setting called "game" has already been defined, the following definition would add one new alternative to it, without modifying the existing setting in any other way.
choice game ( 
  existing: merge
  alts < myowngame >
  opts < "myown.dll" >
)

"text"

  • No additional keys for this setting type

"slider"

  • option: Doomsday command line option
  • default: Default value
  • min: Minimum value
  • max: Maximum value
  • step: Step by which the value of the setting is increased or decreased

Profile files

Profile files use the configuration file syntax as well. In this section the contents of .prof profile files will be described.

Localization

See: Localizing Snowberry