Index

C/C++ Functions

dtFontGetStringValues

DT_SLONG dtFontGetStringValues(DT_DTENGINE engine, DT_UWORD flags, DT_ID_SWORD font_index, DT_ID_SWORD string_id, DT_UBYTE* buffer, DT_SLONG max_buffer_len, DT_SLONG* max_arr_len, DT_ULONG lang_and_platform_id_arr[], DT_SLONG langtag_offset_arr[], DT_SLONG langtag_len_arr[], DT_SLONG string_offset_array[], DT_SLONG string_len_array[])

Short Description: Get string values from font in multiple languages

This function retrieves various multi-lingual string values that may be available in the referenced font. Some of these values are format specific while others are format independent and/or have a more general purpose.

dtFontGetStringValues is an enhanced version of the dtFontGetStringValue function. Unlike dtFontGetStringValue which returns a single string value for the specified string identifier, the dtFontGetStringValues function may return multiple (language dependent) string values for the same string identifier. In order to understand how this function works, you must be familiar with the dtFontGetStringValue function.

Parameters

ParameterDescription

engine

Handle of the previously created Standard Engine instance.

flags

Reserved for future. Must be set to 0.

font_index

Font index of the font or font instance in the Font Catalog.

string_id

Identifies the string whose multi-lingual value(s) will be retrieved. Same as the string_id parameter of the dtFontGetStringValue function. See dtFontGetStringValue for details.

buffer

A valid pointer to a user-supplied buffer to which the function will copy multi-lingual string value(s) associated with string_id. All multi-lingual string values associated with string_id that are found in the font will be copied to this buffer (assuming the buffer is big enough). No particular order of multi-lingual string values in the buffer should be assumed.

max_buffer_len

Size of the user-supplied buffer, i.e. the maximum number of bytes that can be stored in the buffer.

max_arr_len

A valid pointer to a variable used for both input and output. When the function is called (input), the value of this variable represents the maximum number of multi-lingual string values to retrieve and must be positive. This value is also the size of the lang_and_platform_id_arr, langtag_offset_arr, langtag_len_arr, string_offset_array and string_len_array arrays. For example, if you wish to retrieve the first three multi-lingual string values associated with string_id that are found in the font, set this value to 3 and ensure that the lang_and_platform_id_arr, langtag_offset_arr, langtag_len_arr, string_offset_array and string_len_array arrays are big enough to hold 3 elements.

When the function returns (output), the value of this variable represents the actual number of multi-lingual string values associated with string_id that are found in the font.

lang_and_platform_id_arr

User-supplied array to which the function will copy language and platform specific codes associated with each multi-lingual string value retrieved. The language code occupies the lower 16 bits of each array element. See below for the list of language codes. The platform specific code occupies the upper 16 bits of each array element. This value is font format specific. For example, for TrueType/OpenType fonts, this is the Platform-specific encoding ID. See the TrueType/OpenType Naming Table Specification at http://www.microsoft.com/typography/otspec/name.htm for more details. Note that this value is not available for all font formats (in which case it will be set to 0).

The size of this array is supplied via the input value of the variable pointed by max_arr_len.

This pointer can be DV_NULL. In this case, the function will not copy anything to the lang_and_platform_id_arr array.

langtag_offset_arr

User-supplied array to which the function will copy offsets associated with each language tag retrieved, if available at all in the font. See below for more information on language tags. The size of this array is supplied via the input value of the variable pointed by max_arr_len.

Each offset represents a location in buffer at which the corresponding language tag begins, relative to the beginning of the buffer. All offsets are expressed in bytes.

This pointer can be DV_NULL. In this case, the function will not copy anything to the langtag_offset_arr array.

langtag_len_arr

User-supplied array to which the function will copy lengths associated with each language tag retrieved, if available at all in the font. See below for more information on language tags. The size of this array is supplied via the input value of the variable pointed by max_arr_len.

Each length represents the number of bytes that the corresponding language tag consumes in buffer. If a particular language tag is not available, the length will be 0.

This pointer can be DV_NULL. In this case, the function will not copy anything to the langtag_len_arr array.

string_offset_array

User-supplied array to which the function will copy offsets associated with each multi-lingual string value retrieved. The size of this array is supplied via the input value of the variable pointed by max_arr_len.

Each offset represents a location in buffer at which the corresponding multi-lingual string value begins, relative to the beginning of the buffer. All offsets are expressed in bytes.

This pointer can be DV_NULL. In this case, the function will not copy anything to the string_offset_array array.

string_len_array

User-supplied array to which the function will copy lengths associated with each multi-lingual string value retrieved. The size of this array is supplied via the input value of the variable pointed by max_arr_len.

Each length represents the number of bytes that the corresponding multi-lingual string value consumes in buffer.

This pointer can be DV_NULL. In this case, the function will not copy anything to the string_len_array array.

Return Value

If the function was not successful, the return value is 0. In that case the function will not change the value of the variable pointed by max_arr_len.

If the function was successful, the return value is the actual number of bytes required to store in the buffer all multi-lingual string values associated with string_id that are found in the font. In that case the function will also set the value of the variable pointed by max_arr_len to indicate the actual number of multi-lingual string values associated with string_id that are found in the font.

If the total size of all retrieved multi-lingual string values exceeds max_buffer_len bytes, then some multi-lingual string values will be missing from the buffer (and the last one in the buffer may be truncated). In this case, your application can use the return value to increase the size of the buffer and call this function again.

What is copied to the buffer depends on string_id. The dtFontGetStringValues function supports the same string identifiers as the dtFontGetStringValue function (e.g. DV_SVAL_ASC_FONTNAME, DV_SVAL_ASC_FAMILYNAME, DV_SVAL_ASC_COPYRIGHT, DV_SVAL_UNI_FONTNAME, DV_SVAL_UNI_FAMILYNAME, DV_SVAL_UNI_COPYRIGHT etc). Some string values are in ASCII format and some are in Unicode. For details see dtFontGetStringValue.

Comments

lang_and_platform_id_arr, langtag_offset_arr, langtag_len_arr, string_offset_array and string_len_array are five parallel arrays allocated by your application. The size of this array is supplied via the input value of the variable pointed by max_arr_len. The dtFontGetStringValues function will copy the same number of elements to all five arrays. If max_arr_len is not large enough, only the first max_arr_len elements will be copied. In this case, your application can use the output value of the variable pointed by max_arr_len and call this function again. Considering that the TrueType/OpenType Naming Table Specification does not define more than 300 language codes, setting max_arr_len to 300 will ensure that all multi-lingual string values in any font are returned. In practice, it is unlikely that there exist a TrueType/OpenType font with more than 40-50 multi-lingual string values for any given string_id. Thus, in practice, max_arr_len can be set to a value much lower than 300.

All language tags and all multi-lingual string values in the buffer are null terminated (provided there is enough space in the buffer). However, it is recommended that applications use the langtag_len_arr and string_len_array arrays to determine the end of each tag/string.

Note 1

Only TrueType/OpenType and D-Type font format is capable of supporting multi-lingual strings. See the TrueType/OpenType Naming Table Specification at http://www.microsoft.com/typography/otspec/name.htm for details. D-Type format is capable of supporting the same multi-lingual strings as the TrueType/OpenType format. Consequently, this function may return multiple string values only for TrueType, OpenType and D-Type fonts.

This function will not return multiple string values for any other font format (e.g. Type 1, Type 3, CFF). For those font formats, the function will copy a single string value to the buffer (the only string value available in the font associated with string_id). Consequently, when the function returns, the value of the variable pointed by max_arr_len will never exceed 1.

Note 2

Language tags, if available at all in the font, are encoded in UTF-16BE. In valid fonts, the language tags conform to IETF specification BCP 47. This provides tags such as "en", "fr-CA" and "zh-Hant" to identify languages, including dialects, written form and other variations. At present, not too many existing TrueType/OpenType fonts support this language tag mechanism.

Note 3

Language codes, language tags and multi-lingual string values are returned to your application as recorded in the font file. D-Type Font Engine does not attempt to interpret or modify the returned data in any way. Thus, if you receive a language string value in Chinese and the language code and/or language tag indicate that this value is in English, this is because the data is recorded this way in the font file. It is not the responsibility of D-Type Font Engine to check or correct for these types of inconsistencies.

Language Codes Associated With DV_SVAL_ASC_... String Identifiers

The following is a list of currently available language codes that can be returned when string_id is one of the DV_SVAL_ASC_... values (e.g. 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008). Language code 0 is an alias for English.

Language Region Language Code (Hex Value)
Afrikaans South Africa 0436
Albanian Albania 041C
Alsatian France 0484
Amharic Ethiopia 045E
Arabic Algeria 1401
Arabic Bahrain 3C01
Arabic Egypt 0C01
Arabic Iraq 0801
Arabic Jordan 2C01
Arabic Kuwait 3401
Arabic Lebanon 3001
Arabic Libya 1001
Arabic Morocco 1801
Arabic Oman 2001
Arabic Qatar 4001
Arabic Saudi Arabia 0401
Arabic Syria 2801
Arabic Tunisia 1C01
Arabic U.A.E. 3801
Arabic Yemen 2401
Armenian Armenia 042B
Assamese India 044D
Azeri (Cyrillic) Azerbaijan 082C
Azeri (Latin) Azerbaijan 042C
Bashkir Russia 046D
Basque Basque 042D
Belarusian Belarus 0423
Bengali Bangladesh 0845
Bengali India 0445
Bosnian (Cyrillic) Bosnia and Herzegovina 201A
Bosnian (Latin) Bosnia and Herzegovina 141A
Breton France 047E
Bulgarian Bulgaria 0402
Catalan Catalan 0403
Chinese Hong Kong S.A.R. 0C04
Chinese Macao S.A.R. 1404
Chinese People's Republic of China 0804
Chinese Singapore 1004
Chinese Taiwan 0404
Corsican France 0483
Croatian Croatia 041A
Croatian (Latin) Bosnia and Herzegovina 101A
Czech Czech Republic 0405
Danish Denmark 0406
Dari Afghanistan 048C
Divehi Maldives 0465
Dutch Belgium 0813
Dutch Netherlands 0413
English Australia 0C09
English Belize 2809
English Canada 1009
English Caribbean 2409
English India 4009
English Ireland 1809
English Jamaica 2009
English Malaysia 4409
English New Zealand 1409
English Republic of the Philippines 3409
English Singapore 4809
English South Africa 1C09
English Trinidad and Tobago 2C09
English United Kingdom 0809
English United States 0409
English Zimbabwe 3009
Estonian Estonia 0425
Faroese Faroe Islands 0438
Filipino Philippines 0464
Finnish Finland 040B
French Belgium 080C
French Canada 0C0C
French France 040C
French Luxembourg 140C
French Principality of Monoco 180C
French Switzerland 100C
Frisian Netherlands 0462
Galician Galician 0456
Georgian Georgia 0437
German Austria 0C07
German Germany 0407
German Liechtenstein 1407
German Luxembourg 1007
German Switzerland 0807
Greek Greece 0408
Greenlandic Greenland 046F
Gujarati India 0447
Hausa (Latin) Nigeria 0468
Hebrew Israel 040D
Hindi India 0439
Hungarian Hungary 040E
Icelandic Iceland 040F
Igbo Nigeria 0470
Indonesian Indonesia 0421
Inuktitut Canada 045D
Inuktitut (Latin) Canada 085D
Irish Ireland 083C
isiXhosa South Africa 0434
isiZulu South Africa 0435
Italian Italy 0410
Italian Switzerland 0810
Japanese Japan 0411
Kannada India 044B
Kazakh Kazakhstan 043F
Khmer Cambodia 0453
K'iche Guatemala 0486
Kinyarwanda Rwanda 0487
Kiswahili Kenya 0441
Konkani India 0457
Korean Korea 0412
Kyrgyz Kyrgyzstan 0440
Lao Lao P.D.R. 0454
Latvian Latvia 0426
Lithuanian Lithuania 0427
Lower Sorbian Germany 082E
Luxembourgish Luxembourg 046E
Macedonian (FYROM) Former Yugoslav Republic of Macedonia 042F
Malay Brunei Darussalam 083E
Malay Malaysia 043E
Malayalam India 044C
Maltese Malta 043A
Maori New Zealand 0481
Mapudungun Chile 047A
Marathi India 044E
Mohawk Mohawk 047C
Mongolian (Cyrillic) Mongolia 0450
Mongolian (Traditional) People's Republic of China 0850
Nepali Nepal 0461
Norwegian (Bokmal) Norway 0414
Norwegian (Nynorsk) Norway 0814
Occitan France 0482
Oriya India 0448
Pashto Afghanistan 0463
Polish Poland 0415
Portuguese Brazil 0416
Portuguese Portugal 0816
Punjabi India 0446
Quechua Bolivia 046B
Quechua Ecuador 086B
Quechua Peru 0C6B
Romanian Romania 0418
Romansh Switzerland 0417
Russian Russia 0419
Sami (Inari) Finland 243B
Sami (Lule) Norway 103B
Sami (Lule) Sweden 143B
Sami (Northern) Finland 0C3B
Sami (Northern) Norway 043B
Sami (Northern) Sweden 083B
Sami (Skolt) Finland 203B
Sami (Southern) Norway 183B
Sami (Southern) Sweden 1C3B
Sanskrit India 044F
Serbian (Cyrillic) Bosnia and Herzegovina 1C1A
Serbian (Cyrillic) Serbia 0C1A
Serbian (Latin) Bosnia and Herzegovina 181A
Serbian (Latin) Serbia 081A
Sesotho sa Leboa South Africa 046C
Setswana South Africa 0432
Sinhala Sri Lanka 045B
Slovak Slovakia 041B
Slovenian Slovenia 0424
Spanish Argentina 2C0A
Spanish Bolivia 400A
Spanish Chile 340A
Spanish Colombia 240A
Spanish Costa Rica 140A
Spanish Dominican Republic 1C0A
Spanish Ecuador 300A
Spanish El Salvador 440A
Spanish Guatemala 100A
Spanish Honduras 480A
Spanish Mexico 080A
Spanish Nicaragua 4C0A
Spanish Panama 180A
Spanish Paraguay 3C0A
Spanish Peru 280A
Spanish Puerto Rico 500A
Spanish (Modern Sort) Spain 0C0A
Spanish (Traditional Sort) Spain 040A
Spanish United States 540A
Spanish Uruguay 380A
Spanish Venezuela 200A
Sweden Finland 081D
Swedish Sweden 041D
Syriac Syria 045A
Tajik (Cyrillic) Tajikistan 0428
Tamazight (Latin) Algeria 085F
Tamil India 0449
Tatar Russia 0444
Telugu India 044A
Thai Thailand 041E
Tibetan PRC 0451
Turkish Turkey 041F
Turkmen Turkmenistan 0442
Uighur PRC 0480
Ukrainian Ukraine 0422
Upper Sorbian Germany 042E
Urdu Islamic Republic of Pakistan 0420
Uzbek (Cyrillic) Uzbekistan 0843
Uzbek (Latin) Uzbekistan 0443
Vietnamese Vietnam 042A
Welsh United Kingdom 0452
Wolof Senegal 0448
Yakut Russia 0485
Yi PRC 0478
Yoruba Nigeria 046A

Language Codes Associated With DV_SVAL_UNI_... String Identifiers

The following is a list of currently available language codes that can be returned when string_id is one of the DV_SVAL_UNI_... values (e.g. 1101, 1102, 1103, 1104, 1105, 1106, 1107, 1108).

Language Code Language Language Code Language
0 English 59 Pashto
1 French 60 Kurdish
2 German 61 Kashmiri
3 Italian 62 Sindhi
4 Dutch 63 Tibetan
5 Swedish 64 Nepali
6 Spanish 65 Sanskrit
7 Danish 66 Marathi
8 Portuguese 67 Bengali
9 Norwegian 68 Assamese
10 Hebrew 69 Gujarati
11 Japanese 70 Punjabi
12 Arabic 71 Oriya
13 Finnish 72 Malayalam
14 Greek 73 Kannada
15 Icelandic 74 Tamil
16 Maltese 75 Telugu
17 Turkish 76 Sinhalese
18 Croatian 77 Burmese
19 Chinese (Traditional) 78 Khmer
20 Urdu 79 Lao
21 Hindi 80 Vietnamese
22 Thai 81 Indonesian
23 Korean 82 Tagalong
24 Lithuanian 83 Malay (Roman script)
25 Polish 84 Malay (Arabic script)
26 Hungarian 85 Amharic
27 Estonian 86 Tigrinya
28 Latvian 87 Galla
29 Sami 88 Somali
30 Faroese 89 Swahili
31 Farsi/Persian 90 Kinyarwanda/Ruanda
32 Russian 91 Rundi
33 Chinese (Simplified) 92 Nyanja/Chewa
34 Flemish 93 Malagasy
35 Irish Gaelic 94 Esperanto
36 Albanian 128 Welsh
37 Romanian 129 Basque
38 Czech 130 Catalan
39 Slovak 131 Latin
40 Slovenian 132 Quenchua
41 Yiddish 133 Guarani
42 Serbian 134 Aymara
43 Macedonian 135 Tatar
44 Bulgarian 136 Uighur
45 Ukrainian 137 Dzongkha
46 Byelorussian 138 Javanese (Roman script)
47 Uzbek 139 Sundanese (Roman script)
48 Kazakh 140 Galician
49 Azerbaijani (Cyrillic script) 141 Afrikaans
50 Azerbaijani (Arabic script) 142 Breton
51 Armenian 14 Inuktitut
52 Georgian 144 Scottish Gaelic
53 Moldavian 145 Manx Gaelic
54 Kirghiz 146 Irish Gaelic (with dot above)
55 Tajiki 147 Tongan
56 Turkmen 148 Greek (polytonic)
57 Mongolian (Mongolian script) 149 Greenlandic
58 Mongolian (Cyrillic script) 150 Azerbaijani (Roman script)
 

Index