FCL/sf/mw/hb: comparison src/hbcore/i18n/hblocaleutil.cpp

equal deleted inserted replaced

-:b7da29130b0e
+:80e4d18b72f5
 #include <hblocaleutil.h>
 #if defined(Q_OS_SYMBIAN)
 #define LANGUAGE_LIST_FILE "/resource/hbi18n/translations/language_list.txt"
 #define LANGUAGE_MAPPINGS_FILE "/resource/hbi18n/translations/locale_mappings.txt"
-#define LANGUAGE_ID_PREFIX "language"
+#define LANGUAGE_ID_PREFIX "txt_language"
 #define LANGUAGE_TRANSLATOR_PATH "/resource/hbi18n/translations/languages"
 #define REGION_LIST_FILE "z:/resource/bootdata/regions.txt"
-#define REGION_ID_PREFIX "region"
+#define REGION_ID_PREFIX "txt_region"
 #define REGION_TRANSLATOR_PATH "/resource/hbi18n/translations/regions"
 #define REGION_DLL_PREFIX "elocl_reg."
 #define COLLATION_LIST_FILE "z:/resource/bootdata/collations.txt"
-#define COLLATION_ID_PREFIX "collation"
+#define COLLATION_ID_PREFIX "txt_collation"
 #define COLLATION_TRANSLATOR_PATH "/resource/hbi18n/translations/collations"
 #define COLLATION_DLL_PREFIX "elocl_col."
 #define COLLATION_DLL_PREFIX_POSITION 3
 #endif // Q_OS_SYMBIAN
 /*!
 @beta
 @hbcore
 \class HbLocaleUtil
-\brief HbLocaleUtil provides functions for quering supported languages, regions and collations and activing them.
+\brief The HbLocaleUtil class supports querying the supported languages, regions and collations, and activating them.
-Language and collation identifiers typically corresponds with two-letter ISO 639 language code, but for certain languages and collations combination of ISO 639 language code and  ISO 3166 country code id used.
+With HbLocaleUtil, you can query the supported languages, regions and
-Region identifiers always corresponds with two-letter ISO 3166 country code.
+collations from the device, and the ones currently set in the device. You
+can then use this data to activate the language, region and collation in the
-HbLocaleUtil also provides functions for converting language, region and collation identifiers to their localised names.
+device; either individually, or as a set determined by the specified
+language.
+HbLocaleUtil returns the data from the device as identifiers.
+The language and collation identifiers typically correspond to two-letter ISO 639 language codes.
+However, some languages and collations use a combination of an ISO 639 language code
+and an ISO 3166 country code which are separated by the underscore character.
+Region identifiers always correspond to a two-letter ISO 3166 country code.
+HbLocaleUtil also provides functions for converting language, region and
+collation identifiers to their localized names.
+Example:
+\snippet{unittest_hblocaleutil/unittest_hblocaleutil.cpp,1}
+\sa HbStringUtil, HbExtendedLocale
 */
 #if defined(Q_OS_SYMBIAN)
 struct HbLocaleMapping
 QList<int> collations;
 QStringList availCollations;
 QHash<QString, QString> locCollationNames;
 /*!
-\brief Reads langauge, region and collation mappings.
+\relates HbLocaleUtil
+Reads language, region and collation mappings.
 */
 void readMappings()
 {
 QString path = "c:";
 path += QString(LANGUAGE_MAPPINGS_FILE);
 #endif // Q_OS_SYMBIAN
 #if defined(Q_OS_SYMBIAN)
 /*!
-\brief Changes the system UI language.
+\relates HbLocaleUtil
-\param dllExtension extension of the locale dll
+Changes the system UI language.
-\return true if operation was successful
+\param dllExtension The extension of the locale DLL.
+\return True if successful, otherwise false.
 */
 bool setLocale( const QString &dllExtension )
 {
 TExtendedLocale dummy;
 dummy.LoadSystemSettings();
 return true;
 }
 #endif //Q_OS_SYMBIAN
 /*!
-\brief Return identifier of the current UI language.
+Returns the identifier of the current UI language.
-\attention Symbian specific API
+Identifier is typically two-letter ISO 639 code, like "en" for universal english,
+but for some languages such United States english it is combination of an ISO 639 code and an ISO 3166 code ("en_US")
-\return Identifier of the language code for Symbian and empty QString for other platforms.
+\attention Only fully implemented on the Symbian platform. For other
+platforms, always returns an empty QString.
+\sa supportedLanguages(), localisedLanguageName(), changeLanguage()
 */
 QString HbLocaleUtil::currentLanguage()
 {
 #if defined(Q_OS_SYMBIAN)
 TLanguage l = User::Language();
 #endif
 return QString();
 }
 /*!
-\brief Returns identifiers of languages supported in a device.
-Language identifier may be two-letter ISO 639 language code or combination of ISO 639 language code and ISO 3166 country code
+Returns the identifiers of the languages supported on the device. The
-Ex: Great Britain english it returns "en".
+language identifier can be either a two-letter ISO 639 language code, or a
-Ex: For U.S. english it returns "en_US"
+combination of an ISO 639 language code and an ISO 3166 country code. For
+example, for UK English, this returns "en", and for US English, this returns
-\attention Symbian specific API
+"en_US".
-\return identifiers of supported languages for Symbian and empty QStringList for other platforms
+\attention Only fully implemented on the Symbian platform. For other
+platforms, always returns an empty QStringList.
+\sa localisedLanguageName(), currentLanguage(), changeLanguage(), changeLocale()
 */
 QStringList HbLocaleUtil::supportedLanguages()
 {
 #if defined(Q_OS_SYMBIAN)
 QStringList languages;
 return QStringList();
 #endif
 }
 /*!
-\brief Converts two or five letter language identifier code to localised language name.
+Returns the localised language name for the specified language identifier.
-\attention Symbian specific API
+If the translation fails, returns an empty QString.
-\param language identifier
+\param language The two- or five-letter language identifier that correspond to an identifier returned by supportedLanguages()
-\return Symbian - localised name of the language, an empty String if translation fails
+\attention Only fully implemented on the Symbian platform. For other
-\return other platforms - empty QString
+platforms, always returns an empty QString.
+\sa changeLanguage(), currentLanguage()
 */
 QString HbLocaleUtil::localisedLanguageName( const QString &language )
 {
 #if defined(Q_OS_SYMBIAN)
 QTranslator translator;
 return QString();
 #endif
 }
 /*!
-\brief Changes the system language.
-The language parameter should correspond with one of the identifiers returned by supportedLanguages().
+Changes the system language to the one specified in \a language.
-\attention Symbian specific API
-\param language identifier of language to set active
+\param language The language identifier. This must correspond to an
+identifier returned by supportedLanguages().
-\return true if language change was successful and false for other platforms
+\return True if successful, otherwise false.
+\attention Only fully implemented on the Symbian platform. For other
+platforms, always returns false.
+\sa localisedLanguageName(), currentLanguage()
 */
 bool HbLocaleUtil::changeLanguage( const QString &language )
 {
 #if defined(Q_OS_SYMBIAN)
 if(mappingList.isEmpty()) {
 return;
 }
 #endif
 /*!
-\brief Returns names supported regions in a phone.
-Region names are identified by 2 letter code(ISO 3166 standard).
+Returns the identifiers of regions supported on the device. The region
-Ex: For United Kingdom it returns GB
+identifier is a two-letter ISO 3166 code, for example, "GB" for United
+Kingdom.
-\attention Symbian specific API
+\attention Only fully implemented on the Symbian platform. For other
-\return list of supported regions in a device for Symbian and empty QStringList for other platforms
+platforms, always returns an empty QStringList.
+\sa localisedRegionName(), currentRegion(), changeRegion()
 */
 QStringList HbLocaleUtil::supportedRegions()
 {
 #if defined(Q_OS_SYMBIAN)
 if(!availRegions.isEmpty())
 return QStringList();
 #endif
 }
 /*!
-\brief Converts two letter region identifier to localised region name.
+Returns the localised region name for the given two-letter region
-\attention Symbian specific API
+identifier. If the translation fails, returns an empty String. ###QString?
-\param region region identifier
+\param region The region identifier that correspond to an identifier
+returned by supportedRegions()
-\return Symbian - localised name of the region, an empty String if translation fails
-\return other platforms - empty QString
+\attention Only fully implemented on the Symbian platform. For other
+platforms, always returns an empty QString.
+\sa currentRegion(), changeRegion()
 */
 QString HbLocaleUtil::localisedRegionName( const QString &region )
 {
 #if defined(Q_OS_SYMBIAN)
 if(locRegionNames.isEmpty())
 return QString();
 #endif
 }
 /*!
-\brief Changes the system region.
+Changes the system region to the one specified in \a region.
-The region parameter should correspond with one of the identifiers returned by supportedRegions().
+\param region The region identifier. This must correspond to an identifier
-\attention Symbian specific API
+returned by supportedRegions().
-\param region identifier of region to set active
+\return True if successful, otherwise false.
-\return true if region change was successful for Symbian and false for other platforms
+\attention Only fully implemented on the Symbian platform. For other
+platforms, always returns false.
+\sa localisedRegionName(), currentRegion()
 */
 bool HbLocaleUtil::changeRegion( const QString &region )
 {
 #if defined(Q_OS_SYMBIAN)
 TExtendedLocale dummy;
 return false;
 #endif
 }
 /*!
-\brief Return identifier of the current region.
+Returns the identifier of the current region.
-\attention Symbian specific API
+\attention Only fully implemented on the Symbian platform. For other
-\return identifier of the region for Symbian and empty QString for other platforms
+platforms, always returns an empty QString.
+\sa supportedRegions(), localisedRegionName(), changeRegion()
 */
 QString HbLocaleUtil::currentRegion()
 {
 #if defined(Q_OS_SYMBIAN)
 if(mappingList.isEmpty())
 return ;
 }
 #endif
 /*!
-\brief Returns identifiers of collations supported in a device.
-Collation identifier may be two-letter ISO 639 language code or combination of ISO 639 language code and ISO 3166 country code
+Returns the identifiers of the collations supported on a device. The
-Ex: Great Britain english it returns "en".
+collation identifier is either an ISO 639 language code, or a combination of
-Ex: For U.S. english it returns "en_US"
+an ISO 639 language code and an ISO 3166 country code.
-\attention Symbian specific API
+\attention Only fully implemented on the Symbian platform. For other
+platforms, always returns an empty QStringList.
-\return identifiers of supported collations for Symbian and empty QStringList for other platforms
+\sa localisedCollationName(), currentCollation(), changeCollation()
 */
 QStringList HbLocaleUtil::supportedCollations()
 {
 #if defined(Q_OS_SYMBIAN)
 if(!availCollations.isEmpty())
 return QStringList();
 #endif
 }
 /*!
-\brief Converts collation identifier to localised collation name.
+Returns the localised collation name for the given collation identifier. If
-\attention Symbian specific API
+the translation fails, returns an empty QString.
-\param collation region collation identifier
+\param collation The region collation identifier corresponding to an
+identifier returned by supportedCollations().
-\return Symbian - localised name of the collation, an empty String if translation fails
-\return other platforms - empty QString
+\attention Only fully implemented on the Symbian platform. For other
+platforms, always returns an empty QString.
+\sa currentCollation(), changeCollation()
 */
 QString HbLocaleUtil::localisedCollationName( const QString &collation )
 {
 #if defined(Q_OS_SYMBIAN)
 if(locCollationNames.isEmpty())
 return QString();
 #endif
 }
 /*!
-\brief Changes the system collation.
-The collation parameter should correspond with one of the identifiers returned by supportedCollations().
+Changes the system collation to the one specified \a collation.
-\attention Symbian specific API
+\param collation The collation identifier. This must correspond to an
+identifier returned by supportedCollations().
-\param collation identifier of collation to set active
-\return true if collation change was successful for Symbian and false for other platforms
+\return True if successful, otherwise false.
+\attention Only fully implemented on the Symbian platform. For other
+platforms, always returns false.
+\sa localisedCollationName(), currentCollation()
 */
 bool HbLocaleUtil::changeCollation( const QString &collation )
 {
 #if defined(Q_OS_SYMBIAN)
 TExtendedLocale dummy;
 return false;
 #endif
 }
 /*!
-\brief Return identifier of the current collation.
+Returns the identifier of the current collation.
-\attention Symbian specific API
+Typically an identifier is ISO 639 code.
-\return identifier of the collation for Symbian and empty QString for other platforms
+\attention Only fully implemented on the Symbian platform. For other
+platforms, always returns an empty QString.
+\sa supportedCollations(), localisedCollationName(), changeCollation()
 */
 QString HbLocaleUtil::currentCollation()
 {
 #if defined(Q_OS_SYMBIAN)
 if(mappingList.isEmpty())
 #endif
 return QString();
 }
 /*!
-\brief Changes the system language, region and collation.
-The language parameter should correspond with one of the identifiers returned by supportedLanguages().
+Changes the system language, region and collation as specified by \a
-Proper region and collation is selected automatically according the language.
+language. The region and collation are selected automatically based on the
+specified language.
+\param language The language identifier. This must correspond to an
+identifier returned by supportedLanguages().
-\attention Symbian specific API
+\return True if successful, otherwise false.
-\param language identifier of language which language, region and collation settings should set active
+\attention Only fully implemented on the Symbian platform. For other
+platforms, always returns false.
-\return Symbian - true if language, region and collation change was successful
-\return other platforms - false
+\sa supportedRegions(), supportedCollations()
 */
 bool HbLocaleUtil::changeLocale( const QString &language )
 {
 #if defined(Q_OS_SYMBIAN)
 if(mappingList.isEmpty()) {
 Q_UNUSED(language);
 #endif // Q_OS_SYMBIAN
 return false;
 }
+/*!
+Returns list of language, region and collation ID mappings.
+For example for UK english entry have "en" as language, "GB" as region and "en" as collation.
+Similar values for US english are "en_US", "US" and "en_US"
+Returned list may contain languages which does not have corresponding region, then HbLanguageRegionMapping struct has an empty region QString.
+List may also contain regions which does not have corresponding language and collation, then HbLanguageRegionMapping struct contains an empty language and collation QStrings.
+Example:
+\snippet{unittest_hblocaleutil/unittest_hblocaleutil.cpp,2}
+\attention Symbian specific API
+\param onlySupported Should return mappings only for those languages, regions and collations which are supported on the device
+true - returns mappings only for those languages, regions and collations which are available on device.
+false - returns all know languages, regions and collations.
+\return Symbian - list of language, region and collation mappings
+\return other platforms - an empty list
+*/
+QList<HbLanguageRegionMapping> HbLocaleUtil::languageRegionMappings( bool onlySupported )
+{
+QList<HbLanguageRegionMapping> mps;
+#if defined(Q_OS_SYMBIAN)
+if (mappingList.isEmpty()) {
+readMappings();
+}
+QStringList supportedLanguages;
+QStringList supportedRegions;
+if (onlySupported) {
+supportedLanguages = HbLocaleUtil::supportedLanguages();
+supportedRegions = HbLocaleUtil::supportedRegions();
+}
+for (int i = 0;  i < mappingList.count(); ++i) {
+HbLocaleMapping map = mappingList.at(i);
+HbLanguageRegionMapping mapping;
+mapping.languageId = map.langName;
+mapping.regionId = map.regName;
+mapping.collationId = map.collName;
+if (onlySupported) {
+bool langSupported = supportedLanguages.contains(map.langName);
+bool regSupported = supportedRegions.contains(map.regName);
+if (!langSupported && !regSupported) {
+continue;
+}
+if (!langSupported) {
+mapping.languageId = "";
+}
+if (!regSupported) {
+mapping.regionId = "";
+}
+}
+mps.append(mapping);
+}
+#else
+Q_UNUSED(onlySupported);
+#endif // Q_OS_SYMBIAN
+return mps;
+}

changeset 30	80e4d18b72f5
parent 23	e6ad4ef83b23