This function activates a font in the Font Catalog of the specified Standard Engine instance.
Parameter | Description |
---|---|
engine |
Handle of the previously created Standard Engine instance. |
font_index |
Index of the font to be activated. |
level |
The desired font activation level. Must be one of the following:
|
last_fcnr |
A valid pointer to the DT_SWORD type that will receive the last font collection number of the font (collection) referenced by font_index. This is the total number of fonts in the specified font collection. See dtFontAddViaStream for details. However, if you do not wish to receive the value of the above parameter, you may set this pointer to DV_NULL. |
If successful, the function returns 1. Otherwise the function returns 0.
In a typical scenario, it is not necessary for applications to explicitly call this function. Fonts are activated automatically to the appropriate activation level by the Font Engine as they are used. However, this function can be useful to applications that wish to perform a basic validation of the font and/or retrieve the total number of fonts in the font collection (if the font file corresponding to the font_index is actually a font collection). For more details, see the dtFontAddViaStream function. Also, see the following example.
This example shows how to add a new font to the Font Catalog using the dtFontAddViaStream function and then perform a basic validation of the newly added font using the dtFontMakeActive function.
DT_ID_SWORD font_format_id = DV_FONT_OPENTYPE_TTF_WINUNICODE; DT_CHAR* fuid = DV_NULL; DT_SWORD fcnr = 0; DT_ID_SWORD cmap_id = -1; DT_ID_UBYTE caching = 0; DT_ID_UBYTE hinting = 1; DT_ID_SWORD font_index; DT_STREAM_FILE(sd, "chopsie.ttf"); font_index = dtFontAddViaStream(engine, font_format_id, fuid, fcnr, cmap_id, caching, hinting, &sd); if (font_index >= 0) { if (dtFontMakeActive(engine, font_index, 2, &last_fcnr) == 1) { sprintf(s, "The selected font has been successfully added to the font catalog and assigned a unique font index %d. Use the \"Select Font\" option from the \"View\" menu to see it.", font_index); } else { sprintf(s, "The selected font has been added to the font catalog and assigned a unique font index %d. However, D-Type Font Engine could not activate it. Most likely this font is corrupt or is in a wrong format. You may try the \"Select Font\" option from the \"View\" menu, however be aware that this font may not render correctly.", font_index); } } else { sprintf(s, "The selected font could not be added to the font catalog. Most likely the specified font format is not supported or an internal error has occurred."); } printf(s);
Output — Scenario 1:
The selected font has been successfully added to the font catalog and assigned a unique font index 24. Use the "Select Font" option from the "View" menu to see it.
Output — Scenario 2:
The selected font has been added to the font catalog and assigned a unique font index 24. However, D-Type Font Engine could not activate it. Most likely this font is corrupt or is in a wrong format. You may try the "Select Font" option from the "View" menu, however be aware that this font may not render correctly.
Output — Scenario 3:
The selected font could not be added to the font catalog. Most likely the specified font format is not supported or an internal error has occurred.