Localised Names of Plug-ins Overview

This API should be used by applications that display names of plug-ins to users. Some devices allow users to switch between different languages. On such a device, lists of plug-in names displayed to users need to be localised. Localising a list of plug-in names involves:

• translating plug-in names into the device's new language. The plug-in names need to be read from resource files. The list cannot simply use filenames.

• sorting the list contents according to the new locale's collation rules — different locales have different rules for sorting text.

• filtering the list. The user will not necessarily need to be shown the names of all plug-ins for a given framework in all locales. Some plug-ins may not be applicable to all locales, so that their names may need to be removed from the list. For this to happen, the localised name of the plug-in should be an empty string.

This API consists of a single class, CBaNamedPlugins. This is a descriptor array which implements the MDesCArray interface.

It uses the following APIs:

Interface to Resource Files. Localised plug-in names are provided in resource files.

File Server Client Side and Application Utilities. A CBaNamedPlugins object populates its named plug-in list by searching the file sytem for localised versions of resource files, then opens them for reading. It requires a connected session with the file server to do this. BaflUtils::NearestLanguageFile() is used internally to create the correct language extension for each resource file.

Descriptors. The list can be sorted using a default algorithm, (TDesC::CompareC()). It also allows you to define and use a custom algorithm instead.

This API is used by the Character Conversion API's CCnvCharacterSetNames class to generate a localised list of character set conversion plug-ins.

The API is used as follows.

The parameters for the named plug-in list are packaged together into an object of type CBaNamedPlugins::CParameters, which is passed to CBaNamedPlugins::NewL() or NewLC().

Minimally, two parameters must be provided in this object — a list of CBaNamedPlugins::TResourceFiles, and a connected session with the file server. Each TResourceFile object contains the language-independent name of a resource file and a unique identifier for the plug-in it names. One resource file should be specified for each plug-in.

Other parameters are optional. They include:

• An object that generates a fallback name for plug-ins, if no resource file could be found with the correct language extension.

• A function that compares two plug-in names for collation.

Default implementations for both of these functions are provided: see the documentation of class CBaNamedPlugins for details.

When the list has been populated, it is sorted using the second function, then items in the list can be retrieved using the implementation of the MDesCArray interface — MdcaCount() and MdcaPoint().

Interface to Resource Files

File Server Client Side

Application Utilities

Descriptors