|
Next revision
|
Previous revision
Next revision
Both sides next revision
|
doc:customising-en [2010/01/18 23:44]
shelagh created |
doc:customising-en [2010/01/18 23:54]
shelagh Hoping this is the correct link |
| 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: | 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 | **origin** |
| |
| A textual description of the likely origin of the mapped font (not the origin of the mapping file). | A textual description of the likely origin of the mapped font (not the origin of the mapping file). |
| |
| copyright | **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. | 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 | **mapped-by** |
| |
| The name of the creator of the mapping file (i.e. you, presumably). | The name of the creator of the mapping file (i.e. you, presumably). |
| |
| type | **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”. | 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. | 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 | **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. | 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 | **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. | 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. |
| === font-requirements === | === font-requirements === |
| |
| 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 [[/#developers-note-fonts-mapping-format-font-symbol-map|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. | 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 [[doc:customising-en#font-symbol-map|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-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 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.) | 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 | **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. | 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 | **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. | 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 | **beam-thickness** |
| |
| Optional. Defines the thickness of a beam. | Optional. Defines the thickness of a beam. |
| |
| staff-line-thickness | **staff-line-thickness** |
| |
| Optional. Defines the thickness of a staff line. | Optional. Defines the thickness of a staff line. |
| |
| stem-thickness | **stem-thickness** |
| |
| Optional. Defines the thickness of a note stem. | Optional. Defines the thickness of a note stem. |
| |
| flag-spacing | **flag-spacing** |
| |
| Optional. Defines the gap between note flags in cases where multiple flags are drawn by drawing a single flag several times. | Optional. Defines the gap between note flags in cases where multiple flags are drawn by drawing a single flag several times. |
| |
| border-x | **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. | 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 | **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. | 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. |
| 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: | 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 | **name** |
| |
| Mandatory. This attribute should contain the name of the notation symbol. If the symbol exists in the [[http://www.unicode.org/charts/PDF/U1D100.pdf|Unicode 3.2 standard]], the name should be that used to identify the symbol in the standard. | Mandatory. This attribute should contain the name of the notation symbol. If the symbol exists in the [[http://www.unicode.org/charts PDF/U1D100.pdf|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). | 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 [[/#developers-note-styles|notation style]]. | 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 [[doc:customising-en#rosegarden-note-style|notation style]]. |
| |
| src | **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. | 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 | **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. | 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 | **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. | 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 | **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. | 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 | **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. | 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 | **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. | 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 | **font-id** |
| |
| The id of the system font from which this symbol should be loaded, as defined in the [[/#developers-note-fonts-mapping-format-font-requirements|font-requirements]] element. The default is 0. | The id of the system font from which this symbol should be loaded, as defined in the [[doc:customising-en#font-requirements|font-requirements]] element. The default is 0. |
| |
| codebase | **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. | 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. |
| The attributes for these elements are as follows. All of these are optional except as described: | The attributes for these elements are as follows. All of these are optional except as described: |
| |
| type | **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”). | 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 | **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. | 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 | **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 [[/#developers-note-fonts-mapping-format-font-symbol-map|symbol map]] (in a “name” attribute). | 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 [[/#developers-note-fonts-mapping-format-font-symbol-map|symbol map]] (in a “name” attribute). |
| |
| filled | **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”. | 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 | **stem** |
| |
| Specifies whether this note should have a stem. Must be “true” or “false”. | Specifies whether this note should have a stem. Must be “true” or “false”. |
| |
| flags | **flags** |
| |
| Defines how many flags or beams this note should have. The valid range is 0 to 4. | Defines how many flags or beams this note should have. The valid range is 0 to 4. |
| |
| slashes | **slashes** |
| |
| Defines how many slashes this note should have across its stem. | Defines how many slashes this note should have across its stem. |
| |
| hfixpoint | **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). | 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 | **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”. | 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”. |
