If you have a notation font installed on your system in a scalable format (TrueType or Type-1) but it is not currently supported by Rosegarden, you can create your own mapping XML file to describe the font's character map and metrics in a way Rosegarden can use. These files are installed in the fonts/mappings subdirectory of the Rosegarden installation directory, and a number of samples are included with the distribution.

You can also use these mapping files to define new pixmap-based fonts, in which every shape in a particular size is loaded from a separate pixmap file. The two standard notation fonts supplied with Rosegarden are pixmap fonts defined in exactly this way.

It is even possible to define a notation font as using one or more scalable system fonts, augmented with pixmaps for particular sizes or for characters not found in the scalable fonts. This is because most of the mapping file format is the same for scalable and pixmap fonts, and where there are different elements for the different sorts of fonts, it is usually possible to include both of them. Rosegarden will usually use pixmaps where available and scalable fonts otherwise.

You may also wish to edit the mapping files supplied with Rosegarden if you find their measurements for alignment or sizing are not to your liking. (If you believe that any of the supplied files are actually wrong, please let us know.)

Here is a summary of the XML elements that may be used in the font mapping file.

This element must exist in every mapping file, and should contain all the other elements. The only attribute is “name”, which contains the font's name as shown in the font selection dropdown. Although the file format will permit any name to be used here, Rosegarden will only pick up the font corectly if the XML file has the same name as the contents of this attribute (except that the XML file should be named in lower-case and should end in “.xml”).

This should normally be the first child element of “rosegarden-font-encoding”. It may have any of the following attributes, all of which are optional:

origin

A textual description of the likely origin of the mapped font (not the origin of the mapping file).

copyright

A textual description of the likely copyright status of the mapped font (not the copyright status of the mapping file). Note that because the mapping file contains information such as origin and copyright of the font itself, it is usually advisable to make separate mapping files for separate fonts where practical, even if the fonts share other mapping data.

mapped-by

The name of the creator of the mapping file (i.e. you, presumably).

type

The type of the font. This attribute should contain one of the values “pixmap” or “scalable”. Fonts that are loaded into the windowing system and are available to Rosegarden as standard system fonts have type “scalable”; fonts that need to be loaded from pixmap files corresponding to individual sizes of pixmap (such as the feta and rg21 fonts included with Rosegarden) have type “pixmap”.

This information is only intended for the user reference; it isn't actually used by Rosegarden. It is legitimate in practice for a font to be a mixture of the two, but in general we will assume in this documentation that a font is either scalable or pixmap.

smooth

A boolean attribute indicating whether the font is antialiased (smooth) or not. Should have the value “true” or “false”. If the font is smooth, other display elements such as beams and slurs that are not generated from the font will also be antialiased.

autocrop

Only relevant for scalable (system) fonts. Rosegarden usually expects the metrics for a font to contain the vertically smallest bounding boxes for elements such as note heads and accents, rather than including empty space above or below these elements for alignment purposes. Most fonts do not do what Rosegarden expects. Therefore for these fonts you should set the autocrop attribute to “true”; then Rosegarden will crop any unnecessary space from the top and bottom of these elements when rendering them.

This element is only relevant for scalable fonts. It is used to specify that this font should only be offered if certain system fonts are available, as well as to associate IDs with those system fonts to refer to in the font-symbol-map element. This scheme is used to decide which notation fonts should be offered to the user, and also allows you to compose a Rosegarden notation font from more than one system font if desired.

The “font-requirements” element should contain a list of “font-requirement” child elements. Each of these has two attributes: “font-id”, containing a numerical ID of your choice for reference elsewhere in the file, and either a “name” or a “names” attribute. If “name” is provided, it will be used as the name of a single system font to be associated with the font id; if “names” is provided, it will be treated as a comma-separated list of system fonts and the first one found will be associated with the font id.

The “font-sizes” element specifies which notation font sizes are available, and how the nominal font size relates to the dimensions of non-font elements such as stems, staff lines and beams. The “size” of a notation font is assumed to be the distance in pixels between staff lines, or more precisely, the height of a conventional note head that completely fills the space between lines: the size therefore does not include the thickness of either of the neighbouring staff lines.

There are two possible child elements of “font-sizes”: “font-scale” and “font-size”. Their use depends on the type of font being described.

For pixmap (non-scalable) fonts, the “font-sizes” element should contain a list of “font-size” elements, one for each size of pixmaps available. The pixmaps themselves must be installed in the fonts/<font-name>/<font-size> subdirectory of the Rosegarden installation directory, where <font-name> is the name of the font (as specified in the “rosegarden-font-encoding” element at the start of the mapping file), or a lower-case version of the name, and <font-size> is the pixel size of the font. A font size will only be made available to the user if it has an entry in the “font-sizes” list and the pixmap directory is found.

For scalable fonts, the “font-sizes” element should contain one “font-scale” element that defines the relationships between font and non-font elements in a general way, and also defines the relationship between Rosegarden's nominal font size and the size of the corresponding system font. If this “font-scale” element is found, then Rosegarden will assume the font is available in any size. You can however still include one or more “font-size” elements to define precise proportions for any particular size for which the general proportions do not quite work correctly, for example because of rounding error.

The attributes of “font-scale” and “font-size” are very similar. The main difference is that all attributes of “font-scale” are floating-point values relative to the font size, where 1.0 is the base font size (i.e. the distance between staff lines), whereas attributes of “font-size” are integer pixel values. The attributes available are as follows. (Those marked “optional” have vaguely sensible defaults, so it's a good idea to try not setting them first.)

note-height

This attribute is only available for the “font-size” element, and it is mandatory in that element. It defines the base size of font to which the other attributes in this element apply, and a size that will be offered to the user and used when looking up pixmaps for this font.

font-height

May be used in either “font-size” or “font-scale”. This is only relevant for scalable fonts, but is mandatory for them if used in the “font-scale” element. This defines the size of the system font used to draw a given size of notation font.

beam-thickness

Optional. Defines the thickness of a beam.

staff-line-thickness

Optional. Defines the thickness of a staff line.

stem-thickness

Optional. Defines the thickness of a note stem.

flag-spacing

Optional. Defines the gap between note flags in cases where multiple flags are drawn by drawing a single flag several times.

border-x

Optional. Specifies that the note head pixmaps have a fixed area to left and right that should not be considered part of the note head. This attribute gives the thickness of that area.

border-y

Optional. Specifies that the note head pixmaps have a fixed area to top and bottom that should not be considered part of the note head. This attribute gives the thickness of that area.

This element lists the symbols available in this notation font, and which pixmap files or system font code points they should be drawn from.

It should contain a list of “symbol” elements. These have several possible attributes, the choice of which will normally depend on whether the font is based on pixmaps or system fonts:

name

Mandatory. This attribute should contain the name of the notation symbol. If the symbol exists in the Unicode 3.2 standard, the name should be that used to identify the symbol in the standard.

Most of the symbols Rosegarden expects to find are in the standard; one exception is that many fonts have a special version of the flag symbol that is intended to be used when composing multiple flags from individual single flags. Rosegarden refers to this as “MUSICAL SYMBOL COMBINING FLAG-0”, a name not used in the Unicode standard (which has flags 1-5 only).

For a definitive set of the symbol names Rosegarden knows about, see the file “gui/notecharname.cpp” in the Rosegarden source distribution. Note however that it is possible to use additional symbol names by introducing them in a notation style.

src

The name of the pixmap file from which this symbol should be loaded, without a directory or extension. This is the usual way of describing a symbol in a pixmap font. The file itself should be installed to fonts/<font-name>/<font-size>/<src>.xpm under the Rosegarden installation directory.

inversion-src

The name of a pixmap file from which an inverted version of this symbol may be loaded, without a directory or extension. If this attribute is absent and an inverted version of the symbol is required, it will be generated simply by loading the normal version and reflecting it in a central x-axis.

code

The code point at which this symbol may be found in the relevant system font, as a decimal integer. This is a way of describing a symbol in a scalable font. This attribute will only be referred to if no pixmap file is supplied, or if the pixmap file fails to load.

inversion-code

The code point at which an inverted version of this symbol may be found in the relevant system font. If this attribute is absent and an inverted version of the symbol is required, it will be generated simply by loading the normal version and reflecting it in a central x-axis.

glyph

The raw glyph index at which this symbol may be found in the relevant system font, as a decimal integer. This is a way of describing a symbol in a scalable font. This attribute will only be referred to if no pixmap file is supplied, or if the pixmap file fails to load.

inversion-glyph

The raw glyph index at which an inverted version of this symbol may be found in the relevant system font. If this attribute is absent and an inverted version of the symbol is required, it will be generated simply by loading the normal version and reflecting it in a central x-axis.

font-id

The id of the system font from which this symbol should be loaded, as defined in the font-requirements element. The default is 0.

codebase

This (decimal integer) attribute may be of use if many of the symbols in a scalable font cover a short range of code points starting at a relatively high code page. If supplied, the codebase value will be added to each of the subsequent code and inversion-code values when looking up a symbol.

Although none of these attributes is mandatory except for the name, a symbol obviously needs to supply at least one of “src”, “inversion-src”, “code”, “inversion-code”, “glyph”, or “inversion-glyph” to stand any chance of being rendered at all. It is of course perfectly legitimate to supply several or all of these attributes.

Rosegarden's notation editor has the ability to display and edit notes in various standard styles: classical, diamond heads and so on. These styles are all defined in XML style definition files installed along with the application, and it's possible to create a new one by writing a simple XML file. Rosegarden simply looks at the set of installed files to determine which styles to offer the user. You can refer to the default set of files in the styles subdirectory of the Rosegarden installation directory for examples.

The file format is not yet especially comprehensive; at the moment it has been designed to be powerful enough to describe the standard styles that come with Rosegarden, but not much more. If you should try to create new styles this way, we'd be very interested in your feedback on the Rosegarden mailing-lists.

Here is a summary of the XML elements that may be used in a style definition file.

This element must exist in every style file, and should contain all the other elements. It has one optional attribute, “base-style”, which may be used to name a style from which this style takes the default values for any parameters not specified elsewhere in the present file. It's often good practice to define a style in terms of the minimal difference from a given base style: see the supplied Cross.xml for a particularly simple example.

Note that the “rosegarden-note-style” element does not give the name of the style being defined, which is instead currently drawn from the name of the file. At some point in the future we may add internationalizable style name attributes to this element.

Within the “rosegarden-note-style” element, there may be one “global” element and any number of “note” elements. We describe these together, as they have almost identical sets of attributes. The “global” element simply provides default values for those parameters not specified for a particular note type in any following “note” element.

The attributes for these elements are as follows. All of these are optional except as described:

type

Only relevant to the “note” element, and mandatory for that element. This attribute specifies which sort of note is being styled. Legal values are textual American or British note names (from “64th”, “sixth-fourth note”, “hemidemisemiquaver” etc to “double whole note”).

shape

Defines a note head shape for this style. Any string is a legal value, but the only values implemented so far are “angled oval”, “level oval”, “breve”, “cross”, “triangle up”, “triangle down”, “diamond” and “rectangle”. The value “number” is also recognised but not yet implemented.

charname

Defines a note font character name to be used as the note head for this style. An element may supply a “shape” or “charname” attribute, but not both. The name should be one of those defined in the current notation font's symbol map (in a “name” attribute).

filled

Specifies whether this note should have a filled head (where applicable, i.e. where the shape attribute supplies a shape that is available both filled and unfilled). Must be “true” or “false”.

stem

Specifies whether this note should have a stem. Must be “true” or “false”.

flags

Defines how many flags or beams this note should have. The valid range is 0 to 4.

slashes

Defines how many slashes this note should have across its stem.

hfixpoint

Specifies in which x position the stem fixes to the note head. Acceptable values are “normal” (the right side when the stem points up, the left when it points down), “central”, and “reversed” (left side when the stem points up, right when it points down).

vfixpoint

Specifies in which y position the stem fixes to the note head. Acceptable values are “near” (the stem fixes to the top when pointing up, the bottom when pointing down), “middle”, or “far”.