The m17n Library: Fontset

# Fontset
[GUI API]

A fontset is an object that maps a character to fonts. More...

## Functions
MFontset * | mfontset (char *name)
| Return a fontset.
MSymbol | mfontset_name (MFontset *fontset)
| Return the name of a fontset.
MFontset * | mfontset_copy (MFontset *fontset, char *name)
| Make a copy of a fontset.
int | mfontset_modify_entry (MFontset *fontset, MSymbol script, MSymbol language, MSymbol charset, MFont *spec, MSymbol layouter_name, int how)
| Modify the contents of a fontset.
MPlist * | mfontset_lookup (MFontset *fontset, MSymbol script, MSymbol language, MSymbol charset)
| Lookup a fontset.

## Detailed Description

A fontset is an object that maps a character to fonts.

A fontset is an object of the type `MFontset`. When drawing an M-text, a fontset provides rules to select a font for each character in the M-text according to the following information.

- The script character property of a character.
- The language text property of a character.
- The charset text property of a character.

The documentation of mdraw_text() describes how that information is used.

## Function Documentation

MFontset * mfontset | ( | char * | name | ) |

Return a fontset.

The mfontset() function returns a pointer to a fontset object of name name. If name is `NULL`, it returns a pointer to the default fontset.

If no fontset has the name name, a new one is created. At that time, if there exists a data <`fontset`, name> in the m17n database, the fontset contents are initialized according to the data. If no such data exists, the fontset contents are left vacant.

The macro M17N_INIT() creates the default fontset. An application program can modify it before the first call of mframe().

Return value:
  This function returns a pointer to the found or newly created fontset.

MSymbol mfontset_name | ( | MFontset * | fontset | ) |

Return the name of a fontset.

The mfontset_name() function returns the name of fontset fontset.

MFontset * mfontset_copy | ( | MFontset * | fontset,
|  | char * | name |
| ) |  |  |

Make a copy of a fontset.

The mfontset_copy() function makes a copy of fontset fontset, gives it a name name, and returns a pointer to the created copy. name must not be a name of existing fontset. In such case, this function returns NULL without making a copy.

int mfontset_modify_entry | ( | MFontset * | fontset,
|  | MSymbol | script,
|  | MSymbol | language,
|  | MSymbol | charset,
|  | MFont * | spec,
|  | MSymbol | layouter_name,
|  | int | how |
| ) |  |  |

Modify the contents of a fontset.

The mfontset_modify_entry() function associates, in fontset fontset, a copy of font with the script / language pair or with charset.

Each font in a fontset is associated with a particular script/language pair, with a particular charset, or with the symbol `Mnil`. The fonts that are associated with the same item make a group.

If script is not `Mnil`, it must be a symbol identifying a script. In this case, language is either a symbol identifying a language or `Mnil`, and font is associated with the script / language pair.

If charset is not `Mnil`, it must be a symbol representing a charset object. In this case, font is associated with that charset.

If both script and charset are not `Mnil`, two copies of font are created. Then one is associated with the script / language pair and the other with that charset.

If both script and charset are `Mnil`, font is associated with `Mnil`. This kind of fonts are called fallback fonts.

The argument how specifies the priority of font. If how is positive, font has the highest priority in the group of fonts that are associated with the same item. If how is negative, font has the lowest priority. If how is zero, font becomes the only available font for the associated item; all the other fonts are removed from the group.

If layouter_name is not `Mnil`, it must be a symbol representing a Font Layout Table (font layout table). In that case, if font is selected for drawing an M-text, that font layout table is used to generate a glyph code sequence from a character sequence.

Return value:
  If the operation was successful, mfontset_modify_entry() returns 0. Otherwise it returns -1 and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_SYMBOL`

MPlist * mfontset_lookup | ( | MFontset * | fontset,
|  | MSymbol | script,
|  | MSymbol | language,
|  | MSymbol | charset |
| ) |  |  |

Lookup a fontset.

The mfontset_lookup() function lookups fontset and returns a plist that describes the contents of fontset corresponding to the specified script, language, and charset.

If script is `Mt`, keys of the returned plist are script name symbols for which some fonts are specified and values are NULL.

If script is a script name symbol, the returned plist is decided by language.

- If language is `Mt`, keys of the plist are language name symbols for which some fonts are specified and values are NULL. A key may be `Mt` which means some fallback fonts are specified for the script.

- If language is a language name symbol, the plist is a `FONT-GROUP` for the specified script and language. `FONT-GROUP` is a plist whose keys are FLT (FontLayoutTable) name symbols (`Mt` if no FLT is associated with the font) and values are pointers to MFont.

- If language is `Mnil`, the plist is fallback `FONT-GROUP` for the script.

If script is `Mnil`, the returned plist is decided as below.

- If charset is `Mt`, keys of the returned plist are charset name symbols for which some fonts are specified and values are NULL.

- If charset is a charset name symbol, the plist is a `FONT-GROUP` for the charset.

- If charset is `Mnil`, the plist is a fallback `FONT-GROUP`.

Return value:
  It returns a plist describing the contents of a fontset. The plist should be freed by m17n_object_unref().