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

equal deleted inserted replaced

-:06ff229162e9
+:11d3954df52a
 \sa QLocale
 */
 /*!
 Returns the date separator, which can occur in four different positions:
-Beginning of the expression
+Beginning of the expression;
-Between the first and second part
+Between the first and second part;
-Between the second and third part
+Between the second and third part;
-At the end of the expression
+At the end of the expression;
-Some of the positions may contain an empty string if a separator is not used in that position in the locale in question
+Some of the positions may contain an empty string if a separator is not used in that position in the locale in question.
-\return one of the four characters used to separate the day,
+\attention Symbian specific API
+\return Symbian - One of the four characters used to separate the day,
 month and year components of the date according to the
-system locale.
+system locale
+\return other platforms - Empty QChar or '\' (depending on index)
 \param index Index of the separator (0-3)
 */
 QChar HbExtendedLocale::dateSeparator( int index ) const
 {
 /*!
 Sets one of the four characters used to separate the day,
 month and year components of the date according to the
 system locale.
+\attention Symbian specific API
 \param ch Character to set,
 \param index Index of the separator (0-3)
 \return true for Symbian if succesfull and false for other OS
 */
 return false;
 #endif
 }
 /*!
-Retrieves the time separator (for example, colon or full stop)
+Retrieves the time separator (for example, colon or full stop).
-\return one of the four characters used to separate the hour,
+\attention Symbian specific API
+\return Symbian - One of the four characters used to separate the hour,
 minute and second components of the date according to the
-system locale.
+system locale
+\return other platforms - Empty QChar or ':' (depending on index)
 \param index Index of the separator (0-3)
 */
 QChar HbExtendedLocale::timeSeparator( int index ) const
 {
 }
 /*!
 Sets one of the four characters used to separate the hour,
 minute and second components of the date.
+\attention Symbian specific API
 \param ch Character to set,
 \param index Index of the separator (0-3)
 \return true for Symbian if succesfull and false for other OS
 returns the order of the date components: day-month-year (the most commonly used format)
 month-day-year (mostly used in the U.S. and Canada)
 or year-month-day (used, for example, in Japanese, Chinese and Swedish)
 This enum defines the order of date components.
 \value American American order (mm/dd/yyyy)
 \value European European order (dd/mm/yyyy)
 \value Japanese Japanese order (yyyy/mm/dd)
 \sa dateStyle(), setDateStyle()
 */
 /*!
-\return date style from system locale. The date style is returned according to DateStyle.
+Returns date style from system locale. The date style is returned according to DateStyle.
+\attention Symbian specific API
+\return date style for Symbian and HbExtendedLocale::American for other platforms
 */
 HbExtendedLocale::DateStyle HbExtendedLocale::dateStyle() const
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 }
 /*!
 Sets date style to system locale.
 The date style is chosen according to the \a style parameter.
+\attention Symbian specific API
 \return true for Symbian and false for other OS
 */
 bool HbExtendedLocale::setDateStyle( const DateStyle style )
 {
 /*!
 \enum HbExtendedLocale::TimeStyle
 Finds out if the 12-hour or the 24-hour clock is used
 \value Time12 12 hour clock style
 \value Time24 24 hour clock style
 \sa timeStyle(), setTimeStyle()
 */
 /*!
-\return time style from system locale. The time style is returned according to TimeStyle.
+Returns time style from system locale. The time style is returned according to TimeStyle.
+\attention Symbian specific API
+\return time style for Symbian and HbExtendedLocale::Time12 for other platforms
 */
 HbExtendedLocale::TimeStyle HbExtendedLocale::timeStyle() const
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 }
 /*!
 Sets time style to system locale.
 The time style is chosen according to the \a style parameter.
+\attention Symbian specific API
 \return true for Symbian and false for other OS
 */
 bool HbExtendedLocale::setTimeStyle( const TimeStyle style )
 {
 #endif
 }
 /*!
-Finds out if the AM/PM symbol is separated by a space from the time expression
+Finds out if the AM/PM symbol is separated by a space from the time expression.
-\return true if space is inserted between the time and the preceding or trailing am/pm text; otherwise returns false.
+\attention Symbian specific API
+\return Symbian - True if space is inserted between the time and the preceding or trailing am/pm text; otherwise returns false.
+\return other platforms - true
 */
 bool HbExtendedLocale::amPmSpace() const
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 #endif
 }
 /*!
 Sets whether a \a space is inserted between the time and the preceding or trailing am/pm text.
+\attention Symbian specific API
 \return true for Symbian and false for other OS
 */
 bool HbExtendedLocale::setAmPmSpace( const bool space )
 {
 /*!
 \enum HbExtendedLocale::SymbolPos
 \value Before
 \value After
 Retrieves the position of the AM/PM symbol (before or after the time expression)
 \sa amPmSymbolPosition(), setAmPmSymbolPosition()
 \sa currencySymbolPosition(), setCurrencySymbolPosition()
 */
 /*!
-\return Before if am/pm text is positioned before time; otherwise returns After.
+Returns HbExtendedLocale::Before if am/pm text is positioned before time; otherwise returns HbExtendedLocale::After.
+\attention Symbian specific API
+\return After/Before for Symbian and HbExtendedLocale::After for other platforms
 */
 HbExtendedLocale::SymbolPos HbExtendedLocale::amPmSymbolPosition() const
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 	return HbExtendedLocale::After;
 }
 #else
 return HbExtendedLocale::After;
 #endif
-return HbExtendedLocale::After;
 }
 /*!
 Sets the am/pm text position.
 The position is chosen according to the \a position parameter.
+\attention Symbian specific API
 \return true for Symbian if succesfull and false for other OS
 */
 bool HbExtendedLocale::setAmPmSymbolPosition( const SymbolPos position )
 {
 \sa unitsDistanceShort(), unitsDistanceLong()
 */
 /*!
-Retrives the  measurement system (if metric or imperial units are in use)
+Retrives the  measurement system (if metric or imperial units are in use).
-\return short unit distance format from system locale. Format is specified by UnitsFormat.
+\attention Symbian specific API
-*/
+\return Symbian - Short unit distance format from system locale. Format is specified by UnitsFormat.
+\return other platforms - QLocale::MetricSystem
+*/
 QLocale::MeasurementSystem HbExtendedLocale::unitsDistanceShort() const
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 TUnitsFormat val = _symbianLocale.GetLocale()->UnitsDistanceShort();
 }
 /*!
 Sets short unit distance \a format to system locale.
+\attention Symbian specific API
 \return true for Symbian and false for other OS
 */
 bool HbExtendedLocale::setUnitsDistanceShort( const QLocale::MeasurementSystem format )
 {
 #if defined(Q_OS_SYMBIAN)
 return false;
 #endif
 }
 /*!
-\return long unit distance format from system locale. Format is specified by UnitsFormat.
+Returns long unit distance format from system locale. Format is specified by UnitsFormat.
+\attention Symbian specific API
+\return long unit distance format for Symbian and QLocale::MetricSystem for other platforms
 */
 QLocale::MeasurementSystem HbExtendedLocale::unitsDistanceLong() const
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 #endif
 }
 /*!
 Sets long unit distance \a format to system locale.
+\attention Symbian specific API
 \return true for Symbian and false for other OS
 */
 bool HbExtendedLocale::setUnitsDistanceLong( const QLocale::MeasurementSystem format )
 {
 #endif
 }
 /*!
 Sets general unit distance \a format to system locale.
-\return true for Symbian and -1 for other OS
+\attention Symbian specific API
+\return true for Symbian and false for other OS
 */
 bool HbExtendedLocale::setUnitsGeneral( const QLocale::MeasurementSystem format )
 {
 #if defined(Q_OS_SYMBIAN)
 TUnitsFormat set;
 \sa negativeCurrencyFormat(), setNegativeCurrencyFormat()
 */
 /*!
-\return the negative currency format from system locale.
+Returns the negative currency format from system locale.
-*/
+\attention Symbian specific API
+\return the negative currency format for Symbian and HbExtendedLocale::LeadingMinusSign for other platforms
+*/
 HbExtendedLocale::NegativeCurrencyFormat HbExtendedLocale::negativeCurrencyFormat() const
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 TLocale::TNegativeCurrencyFormat val = _symbianLocale.GetLocale()->NegativeCurrencyFormat();
 #endif
 }
 /*!
 Sets negative currency \a format to system locale.
+\attention Symbian specific API
 \return true for Symbian and false for other OS
 */
 bool HbExtendedLocale::setNegativeCurrencyFormat( const NegativeCurrencyFormat format )
 {
 #endif
 }
 /*!
 Finds out if the currency symbol is separated by a space from the amount.
-\return true if negative currency values have a space between the currency symbol and the value; otherwise returns false.
+\attention Symbian specific API
+\return Symbian - True if negative currency values have a space between the currency symbol and the value; otherwise returns false.
+\return other platforms - false
 */
 bool HbExtendedLocale::negativeCurrencySpace() const
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 }
 /*!
 Sets whether negative currency values have a space between the currency symbol and the value.
+\attention Symbian specific API
 \param space True to set a flag which indicates that negative currency values should have
 the space between the value and the symbol. False to unset it.
 \return true for Symbian and false for other OS
 */
 /*!
 Finds out if the currency symbol is placed on the opposite side with negative
 currencies compared to where it is placed with non-negative currencies.
-\return true if in negative currency values, the position of the currency
+\attention Symbian specific API
+\return Symbian - True if in negative currency values, the position of the currency
 symbol is set to be the opposite of the position used for non-negative
 values; otherwise returns false.
+\return other platforms - false
 */
 bool HbExtendedLocale::negativeCurrencySymbolOpposite() const
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 /*!
 Sets whether the position of the currency symbol for negative currency
 values should be the \a opposite of the position used for
 non-negative values.
+\attention Symbian specific API
 \return true for Symbian and false for other OS
 */
 bool HbExtendedLocale::setNegativeCurrencySymbolOpposite( const bool opposite )
 {
 #if defined(Q_OS_SYMBIAN)
 /*!
 Finds out if currency triads are used (the grouping of digits in large numbers, for example, 123 456 789).
 The Symbian OS only supports the grouping of currency amounts.
-\return true if currency triads are allowed in currency values; otherwise returns false.
+\attention Symbian specific API
+\return Symbian - True if currency triads are allowed in currency values; otherwise returns false.
+\return other platforms - false
 */
 bool HbExtendedLocale::currencyTriadsAllowed() const
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 }
 /*!
 Sets whether triads are \a allowed in currency values.
-\return true for Symbian and false for other CS
+\attention Symbian specific API
+\return true for Symbian and false for other OS
 */
 bool HbExtendedLocale::setCurrencyTriadsAllowed( const bool allowed )
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 #endif
 }
 /*!
-\return true if a space is inserted between the currency symbol and
+Returns boolean which tells if currency format contains a space.
-a positive currency value; otherwise returns false.
+\attention Symbian specific API
-\note For negative currency values, the space can be inserted using
+\return Symbian - True if a space is inserted between the currency symbol and
+a positive currency value; otherwise returns false.
+\return other platforms - false
+\note For negative currency values, the space can be inserted using
 setNegativeCurrencySpace().
 */
 bool HbExtendedLocale::currencySpace() const
 {
 #if defined(Q_OS_SYMBIAN)
 /*!
 Sets whether a \a space is inserted between the currency symbol and the
 currency amount.
-\return true for Symbian and false for other OS
+\attention Symbian specific API
+\return true for Symbian and false for other OS
 */
 bool HbExtendedLocale::setCurrencySpace( const bool space )
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 /*!
 The currency symbol may contain a different number of characters in different countries/regions.
 Example: œ, $, Ft, kn, Euro symbol
-\return the currency symbol.
+\attention Symbian specific API
+\return the currency symbol for Symbian and empty QString for other platforms
 */
 QString HbExtendedLocale::currencySymbol() const
 {
 // copy from other similar method
 #if defined(Q_OS_SYMBIAN)
 }
 /*!
 Sets the currency \a symbol.
+\attention Symbian specific API
 \return true for Symbian if succesfull and false for other OS
 */
 bool HbExtendedLocale::setCurrencySymbol( const QString &symbol )
 {
 #if defined(Q_OS_SYMBIAN)
 #endif
 }
 /*!
 Retrieves position of the currency symbol (before or after the amount).
-\return the currency symbol position.
+\attention Symbian specific API
-\note For negative currency values, this position may be reversed using
+\return Symbian - the currency symbol position
+\return other platforms - HbExtendedLocale::Before
+\note For negative currency values, this position may be reversed using
 SetNegativeCurrencySymbolOpposite().
 */
 HbExtendedLocale::SymbolPos HbExtendedLocale::currencySymbolPosition() const
 {
 #if defined(Q_OS_SYMBIAN)
 return HbExtendedLocale::Before;
 #endif
 }
 /*!
 Sets the currency symbol \a position.
-\return true for Symbian and false for other OS
+\attention Symbian specific API
+\return true for Symbian and false for other OS
 */
 bool HbExtendedLocale::setCurrencySymbolPosition( const SymbolPos position )
 {
 #if defined(Q_OS_SYMBIAN)
 TLocalePos pos;
 return false;
 #endif
 }
 /*!
-\return the number of decimal places to which currency values are set.
+Returns the number of decimal places to which currency values are set.
+\attention Symbian specific API
+\return Symbian - the number of decimal place
+\return other platforms - '0'
 */
 int HbExtendedLocale::currencyDecimalPlaces() const
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 return 0;
 #endif
 }
 /*!
 Sets the number of decimal \a places to which currency values should be set.
-\return true for Symbian and false for other OS
+\attention Symbian specific API
+\return true for Symbian and false for other OS
 */
 bool HbExtendedLocale::setCurrencyDecimalPlaces( const int places )
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 /*!
 Returns a currency \a amount as a string, based on the locale's
 currency and numeric format settings.
 These settings include the currency symbol, the symbol's
 position and how negative values are formatted.
+\attention Cross-Platform API
+\attention Uses QString::number() function with other platforms than Symbian.
 \sa setCurrencyDecimalPlaces(), setCurrencySpace(), setCurrencySymbol(),
 setCurrencySymbolPosition(), setNegativeCurrencySpace(), setNegativeCurrencyFormat(),
 setCurrencyTriadsAllowed(), setNegativeCurrencySymbolOpposite(),
 setGroupSeparator(), setDecimalPoint()
 #endif
 }
 /*!
 Sets decimal point character \a ch to system locale.
+\attention Symbian specific API
 \return true for Symbian and false for other OS
 */
 bool HbExtendedLocale::setDecimalPoint( const QChar ch )
 {
 #endif
 }
 /*!
 Sets group separator character \a ch to system locale.
+\attention Symbian specific API
 \return true for Symbian and false for other OS
 */
 bool HbExtendedLocale::setGroupSeparator( const QChar ch )
 {
 #endif
 }
 /*!
 Sets zero digit \a type to system locale.
+\attention Symbian specific API
 \return true for Symbian and false for other OS
 */
 bool HbExtendedLocale::setZeroDigit( const DigitType type )
 {
 { ELangIndonesian_Apac,     "id_APAC" }
 };
 #endif
 /*!
-\return ISO name corresponding to the Symbian language \a code.
+Returns ISO name corresponding to the Symbian language \a code.
 If the code does not does not correspond to any Symbian language,
 returns a empty string.
+\attention Symbian specific API
+\return Symbian - ISO style language code
+\return other platforms - empty QString
 \sa User::Language()
 */
 QString HbExtendedLocale::symbianLangToISO( const int code )
 {
 return QString();
 #endif
 }
 /*!
-\return RFC3066 name corresponding to the Symbian language \a code.
+Returns RFC3066 name corresponding to the Symbian language \a code.
 If the code does not does not correspond to any Symbian language,
 returns a empty string.
+\attention Symbian specific API
+\return Symbian - RFC3066 style language code
+\return other platforms - empty QString
 \sa User::Language()
 */
 QString HbExtendedLocale::symbianLangToRfc3066( const int code )
 {
 }
 /*!
 Converts ISO tag to Symbian language code.
+\attention Symbian specific API
 \param langAndCountry ISO tag, example "fi_FI"
-\return Symbian language code or -1 (failed case)
+\return Symbian language code if successful. With other platforms or if case fails then '-1'.
 */
 int HbExtendedLocale::ISOToSymbianLang( const QString &langAndCountry )
 {
 #if defined(Q_OS_SYMBIAN)
 #endif
 /*!
 Returns a Qt version of the given \a sys_fmt Symbian datetime format string.
 Some convertable fields use data from current system locale,
 unwanted locale may cause unexpected results.
+\attention Symbian specific API
+\return Symbian - datetime format string
+\return other platforms - "not supported"
 */
 QString HbExtendedLocale::symbianDateTimeToQt( const QString &sys_fmt )
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 /*!
 \enum HbExtendedLocale::WeekDay
 This enum defines weekdays.
 \sa startOfWeek()
 */
 /*!
 Gets first day of the week.
 It is usually Saturday, Sunday or Monday, but the Symbian OS allows setting any weekday as the first.
-Returns enum WeekDay.
+\attention Symbian specific API
-\return Monday for other OS
+\return Symbian - enum of WeekDay
+\return other platforms - HbExtendedLocale::Monday
 */
 HbExtendedLocale::WeekDay HbExtendedLocale::startOfWeek() const
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 #endif
 }
 /*!
 Sets the day which is considered to be the first day of the week.
-\param day  The first day of the week.
+\attention Symbian specific API
+\param day The first day of the week.
 \return true for Symbian and false for other OS
 \sa startOfWeek()
 */
 bool HbExtendedLocale::setStartOfWeek(WeekDay day)
 {
 #endif
 }
 /*!
 Gets days which are working days of week.
-Returns QString which describes workdays as binary array.
+1 meaning workday and 0 as non working day.
-1 meaning workday and 0 as non working day.
+\attention Symbian specific API
-\return 0011111 for other OS
+\return Symbian - QString which describes workdays as binary array
-\sa setWorkDays()
+\return other platforms - "0011111"
+\sa setWorkDays()
 */
 QString HbExtendedLocale::workDays() const
 {
 #if defined(Q_OS_SYMBIAN)
 _symbianLocale.LoadSystemSettings();
 return QString("0011111");
 #endif
 }
 /*!
 Sets working days of week.
+\attention Symbian specific API
 \param days which describes workdays as QString binary array.
 1 meaning workday and 0 non workday.
 \return true for Symbian if succesfull and false for other OS
 return false;
 #endif
 }
 /*!
-Checks whether or not daylight saving is set for the home city
+Checks whether or not daylight saving is set for the home city.
-\return True if home daylight saving is set, false if home daylight saving is not set
+\attention Symbian specific API
+\return Symbian - True if home daylight saving is set. False if home daylight saving is not set.
+\return other platforms - false
 */
 bool HbExtendedLocale::homeHasDaylightSavingOn() const
 {
 #if defined(Q_OS_SYMBIAN)
 }
 /*!
 Returns the daylight saving zone in which the home city is located.
+\attention Symbian specific API
 \value Home Home daylight saving zone
 \value European European daylight saving zone
 \value Northern Northern hemisphere (non-European) daylight saving zone
 \value Southern Southern hemisphere daylight saving zone
 \value None No daylight saving zone
+\return Symbian - the daylight saving zone
+\return other platforms - HbExtendedLocale::None
 \sa setHomeDaylightSavingZone()
 */
 HbExtendedLocale::DaylightSavingZone HbExtendedLocale::homeDaylightSavingZone() const
 {
 return HbExtendedLocale::None;
 #endif
 }
 /*!
-Gets the locale’s universal time offset
+Gets the locale’s universal time offset.
+\attention Symbian specific API
 \return Offset in seconds from universal time. For other platforms it returns 0.
 */
 int HbExtendedLocale::universalTimeOffset() const
 {
 #if defined(Q_OS_SYMBIAN)
 #else
 return 0;
 #endif
 }
+/*!
+Constructor of HbExtendedLocale.
+\attention Cross-Platform API
+*/
 HbExtendedLocale::HbExtendedLocale()
 {
 #if defined(Q_OS_SYMBIAN)
 QLocale::system();
 _symbianLocale.LoadSystemSettings();
 #endif
 }
-//! Returns new/dummy copy of HbExtendedLocale.
+/*!
+Returns new/dummy copy of HbExtendedLocale.
+\attention Cross-Platform API
+*/
 HbExtendedLocale HbExtendedLocale::system()
 {
 // make sure QLocale's lp is updated if in future QApplication does not do it
 // currently this does not do anything
 // just return default set locale
 /*!
 Formats the given date to a string according to the given date format.
 For example, what date components are included, and if leading zeroes are used.
 This is a function uses the date formats defined in the hbi18ndef.h header file.
+\attention Cross-Platform API
 \param date The date to be formatted.
 \param dateFormat The wanted format to be used.
-\return The date as a string.
+\return the date as a string
 */
 QString HbExtendedLocale::format( const QDate &date, const QString &dateFormat )
 {
 #if defined(Q_OS_SYMBIAN)
 QScopedPointer<CTrapCleanup> sp;
 	}
 	return TDesC2QString(s60DateStr->Des());
 #else
 Q_UNUSED(dateFormat);
-	return toString(date, ShortFormat );
+return toString(date, ShortFormat );
 #endif
 }
 /*!
 Formats the given time to a string according to the given time format.
 For example, what components are included (hours/minutes/seconds), and if leading zeroes and AM/PM or am/pm symbols are used.
 This is a function uses the time formats defined in the hbi18ndef.h header file.
-\param time The time to be formatted.
+\attention Cross-Platform API
-\param timeFormat The wanted format to be used.
+\param time The time to be formatted.
+\param timeFormat The wanted format to be used.
-\return The time as a string.
+\return the time as a string
 */
 QString HbExtendedLocale::format( const QTime &time, const QString &timeFormat )
 {
 #if defined(Q_OS_SYMBIAN)
 QScopedPointer<CTrapCleanup> sp;
 		return QString("");
 	}
 	return TDesC2QString(s60TimeStr->Des());
 #else
 Q_UNUSED(timeFormat);
-	return toString(time, ShortFormat);
+return toString(time, ShortFormat);
 #endif
 }

changeset 3	11d3954df52a
parent 2	06ff229162e9
child 5	627c4a0fd0e7