--- a/src/hbcore/i18n/hbextendedlocale.cpp Fri May 14 16:09:54 2010 +0300
+++ b/src/hbcore/i18n/hbextendedlocale.cpp Thu May 27 13:10:59 2010 +0300
@@ -115,15 +115,18 @@
/*!
Returns the date separator, which can occur in four different positions:
- Beginning of the expression
- Between the first and second part
- Between the second and third part
- 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
+ Beginning of the expression;
+ Between the first and second part;
+ Between the second and third part;
+ 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.
+
+ \attention Symbian specific API
- \return one of the four characters used to separate the day,
+ \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)
*/
@@ -147,6 +150,8 @@
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)
@@ -171,11 +176,14 @@
}
/*!
- 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)
*/
@@ -198,6 +206,8 @@
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)
@@ -229,15 +239,19 @@
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)
+ \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
{
@@ -265,6 +279,8 @@
/*!
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
*/
@@ -301,14 +317,18 @@
\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
+ \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
{
@@ -331,6 +351,8 @@
/*!
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
*/
@@ -360,9 +382,12 @@
/*!
- 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.
+
+ \attention Symbian specific API
- \return true if space is inserted between the time and the preceding or trailing am/pm text; otherwise returns false.
+ \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
{
@@ -376,6 +401,8 @@
/*!
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
*/
@@ -396,7 +423,7 @@
\enum HbExtendedLocale::SymbolPos
\value Before
- \value After
+ \value After
Retrieves the position of the AM/PM symbol (before or after the time expression)
\sa amPmSymbolPosition(), setAmPmSymbolPosition()
@@ -404,7 +431,11 @@
*/
/*!
- \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
{
@@ -419,12 +450,13 @@
#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
*/
@@ -462,10 +494,13 @@
*/
/*!
- Retrives the measurement system (if metric or imperial units are in use)
+ Retrives the measurement system (if metric or imperial units are in use).
+
+ \attention Symbian specific API
- \return short unit distance format from system locale. Format is specified by UnitsFormat.
- */
+ \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)
@@ -486,6 +521,8 @@
/*!
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 )
@@ -514,7 +551,11 @@
}
/*!
- \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
{
@@ -535,6 +576,8 @@
/*!
Sets long unit distance \a format to system locale.
+
+ \attention Symbian specific API
\return true for Symbian and false for other OS
*/
@@ -564,8 +607,10 @@
/*!
Sets general unit distance \a format to system locale.
+
+ \attention Symbian specific API
- \return true for Symbian and -1 for other OS
+ \return true for Symbian and false for other OS
*/
bool HbExtendedLocale::setUnitsGeneral( const QLocale::MeasurementSystem format )
{
@@ -607,8 +652,12 @@
*/
/*!
- \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)
@@ -632,6 +681,8 @@
/*!
Sets negative currency \a format to system locale.
+
+ \attention Symbian specific API
\return true for Symbian and false for other OS
*/
@@ -666,7 +717,11 @@
/*!
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
{
@@ -681,6 +736,8 @@
/*!
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.
@@ -703,9 +760,12 @@
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
{
@@ -722,6 +782,8 @@
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 )
@@ -741,8 +803,10 @@
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
{
@@ -757,7 +821,9 @@
/*!
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 )
{
@@ -774,10 +840,15 @@
/*!
- \return true if a space is inserted between the currency symbol and
- a positive currency value; otherwise returns false.
+ Returns boolean which tells if currency format contains a space.
+
+ \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
@@ -794,7 +865,9 @@
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 )
{
@@ -813,7 +886,10 @@
/*!
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
{
@@ -829,6 +905,8 @@
/*!
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 )
@@ -850,9 +928,13 @@
/*!
Retrieves position of the currency symbol (before or after the amount).
- \return the currency symbol position.
+
+ \attention Symbian specific API
+
+ \return Symbian - the currency symbol position
+ \return other platforms - HbExtendedLocale::Before
- \note For negative currency values, this position may be reversed using
+ \note For negative currency values, this position may be reversed using
SetNegativeCurrencySymbolOpposite().
*/
HbExtendedLocale::SymbolPos HbExtendedLocale::currencySymbolPosition() const
@@ -873,9 +955,11 @@
}
/*!
- Sets the currency symbol \a position.
+ Sets the currency symbol \a position.
+
+ \attention Symbian specific API
- \return true for Symbian and false for other OS
+ \return true for Symbian and false for other OS
*/
bool HbExtendedLocale::setCurrencySymbolPosition( const SymbolPos position )
{
@@ -901,7 +985,12 @@
}
/*!
- \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
{
@@ -914,9 +1003,11 @@
}
/*!
- Sets the number of decimal \a places to which currency values should be set.
+ Sets the number of decimal \a places to which currency values should be set.
+
+ \attention Symbian specific API
- \return true for Symbian and false for other OS
+ \return true for Symbian and false for other OS
*/
bool HbExtendedLocale::setCurrencyDecimalPlaces( const int places )
{
@@ -955,6 +1046,9 @@
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(),
@@ -1018,6 +1112,8 @@
/*!
Sets decimal point character \a ch to system locale.
+
+ \attention Symbian specific API
\return true for Symbian and false for other OS
*/
@@ -1037,6 +1133,8 @@
/*!
Sets group separator character \a ch to system locale.
+
+ \attention Symbian specific API
\return true for Symbian and false for other OS
*/
@@ -1057,6 +1155,8 @@
/*!
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 )
@@ -1174,10 +1274,15 @@
#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 )
@@ -1223,9 +1328,14 @@
}
/*!
- \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.
+ returns a empty string.
+
+ \attention Symbian specific API
+
+ \return Symbian - RFC3066 style language code
+ \return other platforms - empty QString
\sa User::Language()
*/
@@ -1237,9 +1347,11 @@
/*!
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 )
{
@@ -1287,7 +1399,12 @@
/*!
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.
+ 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 )
{
@@ -1658,15 +1775,17 @@
\enum HbExtendedLocale::WeekDay
This enum defines weekdays.
- \sa startOfWeek()
+ \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
{
@@ -1697,8 +1816,13 @@
/*!
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()
*/
@@ -1744,13 +1868,15 @@
/*!
- 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.
+ Gets days which are working days of week.
+ 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
+ \return other platforms - "0011111"
- \sa setWorkDays()
+ \sa setWorkDays()
*/
QString HbExtendedLocale::workDays() const
{
@@ -1768,7 +1894,10 @@
}
/*!
- Sets working days of week.
+ 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.
@@ -1798,8 +1927,12 @@
}
/*!
- 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
+ Checks whether or not daylight saving is set for the home city.
+
+ \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
@@ -1815,12 +1948,17 @@
/*!
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
@@ -1847,7 +1985,10 @@
}
/*!
- 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
@@ -1861,6 +2002,11 @@
#endif
}
+/*!
+ Constructor of HbExtendedLocale.
+
+ \attention Cross-Platform API
+ */
HbExtendedLocale::HbExtendedLocale()
{
#if defined(Q_OS_SYMBIAN)
@@ -1869,7 +2015,11 @@
#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
@@ -1883,10 +2033,12 @@
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 )
{
@@ -1940,7 +2092,7 @@
#else
Q_UNUSED(dateFormat);
- return toString(date, ShortFormat );
+ return toString(date, ShortFormat );
#endif
}
@@ -1949,10 +2101,12 @@
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.
- \param timeFormat The wanted format to be used.
+ \attention Cross-Platform API
+
+ \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 )
{
@@ -1997,6 +2151,6 @@
return TDesC2QString(s60TimeStr->Des());
#else
Q_UNUSED(timeFormat);
- return toString(time, ShortFormat);
+ return toString(time, ShortFormat);
#endif
}