<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-D8900275-FCD4-5296-A27A-75A1C5744D7F"><title>Localised Names of Plug-ins</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This API must be used by applications that display names of plug-ins to users. This API is used by the Character Conversion API's <codeph>CCnvCharacterSetNames</codeph> class to generate a localised list of character set conversion plug-ins. </p> <p>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: </p> <ul><li id="GUID-9869368B-7D56-57ED-8836-87CA36B0CE35"><p>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. </p> </li> <li id="GUID-46B45094-C5F9-5DF7-8B8C-668611903BE5"><p>sorting the list contents according to the new locale's collation rules — different locales have different rules for sorting text. </p> </li> <li id="GUID-02ABC23A-7B9C-5216-A983-2DBEE147DBEE"><p>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. </p> </li> </ul> <p>The parameters for the named plug-in list are packaged together into an object of type <codeph>CBaNamedPlugins::CParameters</codeph>, which is passed to <codeph>CBaNamedPlugins::NewL()</codeph> or <codeph>NewLC()</codeph>. </p> <p>Minimally, two parameters must be provided in this object — a list of <codeph>CBaNamedPlugins::TResourceFile</codeph> s, and a connected session with the file server. Each <codeph>TResourceFile</codeph> 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. </p> <p>Other parameters are optional. They include: </p> <ul><li id="GUID-14CB58F1-1B92-5C73-97D6-5C9F163501D8"><p>An object that generates a fallback name for plug-ins, if no resource file could be found with the correct language extension. </p> </li> <li id="GUID-1D452B0A-42DD-50D6-9317-6AB622A3C2CF"><p>A function that compares two plug-in names for collation. </p> </li> </ul> <p>Default implementations for both of these functions are provided. See <xref href="GUID-1B8D19AA-9FCF-32D5-B072-CDBA52F89CCD.dita"><apiname>CBaNamedPlugins</apiname></xref> for details. </p> <p>This API consists of a single class, <xref href="GUID-1B8D19AA-9FCF-32D5-B072-CDBA52F89CCD.dita"><apiname>CBaNamedPlugins</apiname></xref>. This is a descriptor array which implements the <codeph>MDesCArray</codeph> interface. 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 <codeph>MDesCArray</codeph> interface — <codeph>MdcaCount()</codeph> and <codeph>MdcaPoint()</codeph>. </p> <p>It uses the following: </p> <ul><li id="GUID-C9B177B2-F6E9-5188-BB13-E6E34D769206"><p> <b>Interface to resource files:</b> Localised plug-in names are provided in resource files. </p> </li> <li id="GUID-DC3CD9C4-A8D0-50DD-836B-36AB4991F8ED"><p> <b>File server client-side and application utilities:</b> A <codeph>CBaNamedPlugins</codeph> 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. <xref href="GUID-5F9CAA3E-D8BF-3488-9797-3B9FB4452930.dita#GUID-5F9CAA3E-D8BF-3488-9797-3B9FB4452930/GUID-BC05133B-2C69-302E-B2D4-11B4A88A8730"><apiname>BaflUtils::NearestLanguageFile()</apiname></xref> is used internally to create the correct language extension for each resource file. </p> </li> <li id="GUID-B506B848-487B-5B17-BE39-B801EC4A41A8"><p> <b>Descriptors:</b> The list can be sorted using a default algorithm, (<codeph>TDesC::CompareC()</codeph>). It also allows you to define and use a custom algorithm instead. </p> </li> </ul> <p> </p> </conbody><related-links><link href="GUID-3AF1F492-3D7D-5F8C-B1AE-16FBD8224775.dita"><linktext>Interface to Resource