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.
Parameter | Description |
---|---|
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. |
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.
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.
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.
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.
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.
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 |
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) |