Using the IDLffLangCat Class
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.
Creating a Language Catalog Object
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 LANGUAGE).
Note
Whenever the object encounters a key (or language) that already exists, the key (or language) is overwritten with the new value.
The VERBOSE flag on the command sends all catalog-loading messages to the IDL Workbench output window. This list contains details resulting from the object's initialization (the names and numbers of keys loaded, keys overwritten, etc.).
Adding Application Keys
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.
Getting and Setting Languages
To return the available languages in a language catalog object:
This command stores the list of available languages as a string array in availLangs.
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 LANGUAGE='engLISh', then 'engLISh' will be returned, although only one ENGLISH language exists in the current catalog.
Performing Queries
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.
This command searches oLangCat for keys with the NAME value of `Menu:File:New' and returns the match in keyVal. If 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.
Destroying a Language Catalog Object
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.
