--- a/src/hbcore/i18n/hblocaleutil.cpp Fri Sep 17 08:32:10 2010 +0300
+++ b/src/hbcore/i18n/hblocaleutil.cpp Mon Oct 04 00:38:12 2010 +0300
@@ -49,16 +49,16 @@
#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
@@ -68,12 +68,29 @@
@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.
- Region identifiers always corresponds with two-letter ISO 3166 country code.
+ With HbLocaleUtil, you can query the supported languages, regions and
+ 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
+ device; either individually, or as a set determined by the specified
+ language.
- HbLocaleUtil also provides functions for converting language, region and collation identifiers to their localised names.
+ 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)
@@ -98,7 +115,9 @@
QHash<QString, QString> locCollationNames;
/*!
- \brief Reads langauge, region and collation mappings.
+ \relates HbLocaleUtil
+
+ Reads language, region and collation mappings.
*/
void readMappings()
{
@@ -156,10 +175,14 @@
#if defined(Q_OS_SYMBIAN)
/*!
- \brief Changes the system UI language.
-
- \param dllExtension extension of the locale dll
- \return true if operation was successful
+ \relates HbLocaleUtil
+
+ Changes the system UI language.
+
+ \param dllExtension The extension of the locale DLL.
+
+ \return True if successful, otherwise false.
+
*/
bool setLocale( const QString &dllExtension )
{
@@ -179,11 +202,16 @@
#endif //Q_OS_SYMBIAN
/*!
- \brief Return identifier of the current UI language.
+
+ Returns the identifier of the current UI language.
+ 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")
- \attention Symbian specific API
+ \attention Only fully implemented on the Symbian platform. For other
+ platforms, always returns an empty QString.
+
+ \sa supportedLanguages(), localisedLanguageName(), changeLanguage()
- \return Identifier of the language code for Symbian and empty QString for other platforms.
*/
QString HbLocaleUtil::currentLanguage()
{
@@ -205,14 +233,18 @@
}
/*!
- \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
- Ex: Great Britain english it returns "en".
- Ex: For U.S. english it returns "en_US"
- \attention Symbian specific API
+ Returns the identifiers of the languages supported on the device. The
+ language identifier can be either a two-letter ISO 639 language code, or a
+ 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
+ "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()
{
@@ -248,14 +280,17 @@
}
/*!
- \brief Converts two or five letter language identifier code to localised language name.
- \attention Symbian specific API
+ Returns the localised language name for the specified language identifier.
+ If the translation fails, returns an empty QString.
+
+ \param language The two- or five-letter language identifier that correspond to an identifier returned by supportedLanguages()
- \param language identifier
+ \attention Only fully implemented on the Symbian platform. For other
+ platforms, always returns an empty QString.
- \return Symbian - localised name of the language, an empty String if translation fails
- \return other platforms - empty QString
+ \sa changeLanguage(), currentLanguage()
+
*/
QString HbLocaleUtil::localisedLanguageName( const QString &language )
{
@@ -287,14 +322,19 @@
}
/*!
- \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.
+
+ \param language The language identifier. This must correspond to an
+ identifier returned by supportedLanguages().
- \attention Symbian specific API
-
- \param language identifier of language to set active
+ \return True if successful, otherwise false.
- \return true if language change was successful and false for other platforms
+ \attention Only fully implemented on the Symbian platform. For other
+ platforms, always returns false.
+
+ \sa localisedLanguageName(), currentLanguage()
+
*/
bool HbLocaleUtil::changeLanguage( const QString &language )
{
@@ -381,13 +421,16 @@
#endif
/*!
- \brief Returns names supported regions in a phone.
- Region names are identified by 2 letter code(ISO 3166 standard).
- Ex: For United Kingdom it returns GB
+
+ Returns the identifiers of regions supported on the device. The region
+ 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
+ platforms, always returns an empty QStringList.
+
+ \sa localisedRegionName(), currentRegion(), changeRegion()
- \return list of supported regions in a device for Symbian and empty QStringList for other platforms
*/
QStringList HbLocaleUtil::supportedRegions()
{
@@ -429,14 +472,18 @@
}
/*!
- \brief Converts two letter region identifier to localised region name.
-
- \attention Symbian specific API
+
+ Returns the localised region name for the given two-letter region
+ 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 ®ion )
{
@@ -481,14 +528,18 @@
}
/*!
- \brief Changes the system region.
- The region parameter should correspond with one of the identifiers returned by supportedRegions().
-
- \attention Symbian specific API
+ Changes the system region to the one specified in \a region.
- \param region identifier of region to set active
+ \param region The region identifier. This must correspond to an identifier
+ returned by supportedRegions().
+
+ \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 ®ion )
{
@@ -547,11 +598,14 @@
}
/*!
- \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
+ platforms, always returns an empty QString.
+
+ \sa supportedRegions(), localisedRegionName(), changeRegion()
- \return identifier of the region for Symbian and empty QString for other platforms
*/
QString HbLocaleUtil::currentRegion()
{
@@ -607,14 +661,16 @@
#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
- Ex: Great Britain english it returns "en".
- Ex: For U.S. english it returns "en_US"
+
+ Returns the identifiers of the collations supported on a device. The
+ collation identifier is either an ISO 639 language code, or a combination of
+ an ISO 639 language code and an ISO 3166 country code.
- \attention Symbian specific API
-
- \return identifiers of supported collations 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 localisedCollationName(), currentCollation(), changeCollation()
+
*/
QStringList HbLocaleUtil::supportedCollations()
{
@@ -656,14 +712,18 @@
}
/*!
- \brief Converts collation identifier to localised collation name.
- \attention Symbian specific API
+ Returns the localised collation name for the given collation identifier. If
+ 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 )
{
@@ -708,13 +768,18 @@
}
/*!
- \brief Changes the system collation.
- The collation parameter should correspond with one of the identifiers returned by supportedCollations().
-
- \attention Symbian specific API
+
+ Changes the system collation to the one specified \a collation.
+
+ \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 )
{
@@ -772,11 +837,14 @@
}
/*!
- \brief Return identifier of the current collation.
+
+ Returns the identifier of the current collation.
+ Typically an identifier is ISO 639 code.
- \attention Symbian specific API
+ \attention Only fully implemented on the Symbian platform. For other
+ platforms, always returns an empty QString.
- \return identifier of the collation for Symbian and empty QString for other platforms
+ \sa supportedCollations(), localisedCollationName(), changeCollation()
*/
QString HbLocaleUtil::currentCollation()
{
@@ -813,16 +881,21 @@
}
/*!
- \brief Changes the system language, region and collation.
- The language parameter should correspond with one of the identifiers returned by supportedLanguages().
- Proper region and collation is selected automatically according the language.
+
+ Changes the system language, region and collation as specified by \a
+ 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 )
{
@@ -852,3 +925,70 @@
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;
+}
+