You use the IDLffLangCat class to find and load an XML language catalog. The class also provides methods for retrieving text strings by matching key names.
The IDL installation comes with an English language catalog for the iTools menu, called
itoolsmenu_eng.cat, in the
/resource/langcat directory of the IDL installation. To load the keys in this file:
oLangCat = OBJ_NEW( 'IDLffLangCat', 'ENGLISH', $ APP_NAME='itools menu', $ APP_PATH=FILEPATH('', $ SUBDIRECTORY=['resource','langcat','itools']), /VERBOSE )
This command searches the given directory for language catalog keys in English that match the application of `itools menu.' In fact, if there are any other language catalog files, besides
itoolsmenu_eng.cat, containing keys whose
LANGUAGE value is `ENGLISH' and
APPLICATION value is `itools menu,' the object adds those keys as well. The matches must be exact in that `itools menu2,' for example, is not a match; however, the matching is not case-sensitive (i.e., 'ENGLISH' and `English' are both matches for
VERBOSE flag on the command sends all catalog-loading messages to the IDLDE output window. This list contains details resulting from the object's initialization (the names and numbers of keys loaded, keys overwritten, etc.).
You might want to add keys for a different application to an existing language catalog object. To do so:
retval = oLangCat->AppendCatalog( APP_NAME='itools ui', $ APP_PATH=FILEPATH('', $ SUBDIRECTORY=['resource','langcat','itools']) )
This command searches the given directory for keys matching an
APPLICATION value of `itools ui' and appends them to
oLangCat. The method returns a value indicating success or failure of the operation.
To return the available languages in a language catalog object:
This command stores the list of available languages as a string array in
To set the current language of a language catalog object (the language used for query searches and matching):
You can use these two methods for getting and setting other properties of a language catalog object. For the list of available object properties, see IDLffLangCat Properties in the IDL Reference Guide manual.
Comparisons such as those done with the Query method (see Performing Queries) are case insensitive, but the values returned by the GetProperty method are exactly as the last encountered value. The exception is that all key names are returned in uppercase. For example, if File 1 has
LANGUAGE='English' and File 2 has
'engLISh' will be returned, although only one
ENGLISH language exists in the current catalog.
To populate the text fields of a widget or other interface object, for example, you can query a language catalog object for key values it contains. IDL performs the search on the
NAME attribute of the keys; matches are not case-sensitive.
keyVal = oLangCat->Query( 'Menu:File:New', $ DEFAULT_STRING='Key not found' )
This command searches
oLangCat for keys with the
NAME value of `Menu:File:New' and returns the match in
oLangCat finds a match in the current language,
keyVal will hold that value string. If a given key does not exist in the current language, the default language is queried (if one exists). If there are still no matches, the default string is returned.
You can use more than one key in a query by passing an array of strings to the Query method (e.g.,
['Menu:File:New','Menu:File:Open']). Similarly, you can supply an array of strings for the
DEFAULT_STRING keyword. In such a case, only those values in the array whose indices match the missing keys will be returned. If you do not specify
DEFAULT_STRING, a null string will be returned instead.
You can destroy a catalog object as you would any other IDL object, as follows:
Destroying a language catalog object does not affect any files from which the object drew its keys.