inc/FLclDateTimeSymbols.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the License);
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16
  17 /**
  18  * @file                FLclDateTimeSymbols.h
  19  * @brief               This is the header file for the %DateTimeSymbols class.
  20  *
  21  * This header file contains the declarations of the %DateTimeSymbols class.
  22  *
  23  */
  24 #ifndef _FLCL_DATE_TIME_SYMBOLS_H_
  25 #define _FLCL_DATE_TIME_SYMBOLS_H_
  26
  27 #include <FBaseColArrayList.h>
  28 #include <FLclLocale.h>
  29 #include <FLclCalendar.h>
  30
  31 namespace Tizen { namespace Locales
  32 {
  33
  34 /**
  35  * @class               DateTimeSymbols
  36  * @brief               This class provides methods for date and time symbols.
  37  *
  38  * @since               2.0
  39  *
  40  * The %DateTimeSymbols class is used for encapsulating localizable date-time formatting data, such as the names of the months,
  41  * the days of the week, and the time zone data. It is also used by DateTimeFormatter.
  42  * %DateTimeSymbols specifies the exact character strings to use for various parts of a date or time. For example, the names of
  43  * the months and days of the week, the strings for AM and PM, and the day of the week considered to be the first day of the week.
  44  *
  45  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/locales/datetime_formatter.htm">Date and Time Formatter</a>.
  46  *
  47  * @see                 Tizen::Locales::DateTimeFormatter
  48  *
  49  */
  50 class _OSP_EXPORT_ DateTimeSymbols
  51         : public Tizen::Base::Object
  52 {
  53
  54 public:
  55         /**
  56          * This is the default constructor for this class. @n
  57          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method
  58          * must be called right after calling this constructor.
  59          *
  60          * @since                       2.0
  61          */
  62         DateTimeSymbols(void);
  63
  64         /**
  65          * This is the destructor for this class. @n
  66          * This destructor overrides Tizen::Base::Object::~Object().
  67          *
  68          * @since               2.0
  69          */
  70         virtual ~DateTimeSymbols(void);
  71
  72
  73         /**
  74          * Initializes this instance of %DateTimeSymbols with the specified @c locale and @c calendarType.
  75          *
  76          * @if OSPCOMPAT
  77          * @brief               <i> [Compatibility] </i>
  78          * @endif
  79          * @since                               2.0
  80          * @if OSPCOMPAT
  81          * @compatibility               This method has compatibility issues with OSP compatible applications. @n
  82          *                                              For more information, see @ref CompDateTimeSymbolsConstructPage "here".
  83          * @endif
  84          *
  85          * @return                              An error code
  86          * @param[in]                   locale                                                  The locale
  87          * @param[in]                   calendarType                                    The calendar type
  88          * @exception                   E_SUCCESS                                               The method is successful.
  89          * @exception                   E_OUT_OF_MEMORY                                 The memory is insufficient.
  90          * @exception                   E_INVALID_ARG                                   The specified @c locale or @c calendarType is invalid.
  91          */
  92         result Construct(const Locale& locale, CalendarType calendarType = CALENDAR_GREGORIAN);
  93
  94
  95         /**
  96          * Initializes this instance of %DateTimeSymbols with the specified parameter. @n
  97          * This method loads the format data from the resources for the default locale into the default calendar.
  98          *
  99          * @if OSPCOMPAT
 100          * @brief <i> [Compatibility] </i>
 101          * @endif
 102          * @since                               2.0
 103          * @if OSPCOMPAT
 104          * @compatibility               This method has compatibility issues with OSP compatible applications. @n
 105          *                                              For more information, see @ref CompDateTimeSymbolsConstructPage "here".
 106          * @endif
 107          *
 108          * @return                              An error code
 109          * @param[in]                   calendarType                                    The calendar type
 110          * @exception                   E_SUCCESS                                               The method is successful.
 111          * @exception                   E_OUT_OF_MEMORY                                 The memory is insufficient.
 112          * @exception                   E_INVALID_ARG                                   The specified @c calendarType is invalid.
 113          */
 114         result Construct(CalendarType calendarType);
 115
 116         /**
 117          * @if OSPCOMPAT
 118          * @page                CompDateTimeSymbolsConstructPage Compatibility for Construct()
 119          * @section             CompDateTimeSymbolsConstructIssueSection Issues
 120          * Implementation of this method in OSP compatible applications has the following issue: @n
 121          * -# The method returns E_UNSUPPORTED_OPERATION if the @c calendarType is invalid.
 122          *
 123          * @section             CompDateTimeSymbolsConstructSolutionSection Resolutions
 124          * This issue has been resolved in Tizen.
 125          * @par When working in Tizen:
 126          * -# The method returns E_INVALID_ARG if the @c calendarType is invalid.
 127          * @endif
 128          */
 129
 130
 131         /**
 132          * Initializes this instance of %DateTimeSymbols with the specified parameter.
 133          *
 134          * @since                               2.0
 135          *
 136          * @return                              An error code
 137          * @param[in]                   other                                                   An instance of %DateTimeSymbols
 138          * @exception                   E_SUCCESS                                               The method is successful.
 139          * @exception                   E_OUT_OF_MEMORY                                 The memory is insufficient.
 140          */
 141         result Construct(const DateTimeSymbols& other);
 142
 143
 144         /**
 145          * Gets the list of the era strings. @n
 146          * For example: "AD" and "BC".
 147          *
 148          * @since                               2.0
 149          *
 150          * @return                              A pointer to the list of era strings, @n
 151          *                                              else @c null if this instance has not been constructed as yet
 152          * @see                                 SetEras()
 153          */
 154         const Tizen::Base::Collection::IList* GetEras(void) const;
 155
 156
 157         /**
 158          * Sets the era strings. @n
 159          * Multiple strings can be concatenated using '|'. For example: "AD|BC".
 160          *
 161          * @since                               2.0
 162          *
 163          * @return                              An error code
 164          * @param[in]                   eras                                            The era strings concatenated using '|'
 165          * @exception                   E_SUCCESS                                       The method is successful.
 166          * @exception                   E_INVALID_ARG                           The specified @c eras contains an invalid value.
 167          * @see                                 GetEras()
 168          */
 169         result SetEras(const Tizen::Base::String& eras);
 170
 171
 172         /**
 173          * Gets the list of the month name strings. @n
 174          * For example: "January", "February".
 175          *
 176          * @since                               2.0
 177          *
 178          * @return                              A pointer to the list of month name strings, @n
 179          *                                              else @c null if this instance has not been constructed as yet
 180          * @see                                 SetMonths()
 181          */
 182         const Tizen::Base::Collection::IList* GetMonths(void) const;
 183
 184
 185         /**
 186          * Sets the month name strings concatenated using '|'. @n
 187          * For example: "January|February|March|April|May|June|July|August|September|October|November|December".
 188          *
 189          * @since                               2.0
 190          *
 191          * @return                              An error code
 192          * @param[in]                   months                                          The month strings concatenated using '|'
 193          * @exception                   E_SUCCESS                                       The method is successful.
 194          * @exception                   E_INVALID_ARG                           The specified @c months contains an invalid value.
 195          * @see                                         GetMonths()
 196          */
 197         result SetMonths(const Tizen::Base::String& months);
 198
 199
 200         /**
 201          * Gets the list of the short month name strings. @n
 202          * For example: "Jan", "Feb".
 203          *
 204          * @since                               2.0
 205          *
 206          * @return                              A pointer to the list of short month name strings, @n
 207          *                                              else @c null if this instance has not been constructed as yet
 208          * @see                                 SetShortMonths()
 209          */
 210         const Tizen::Base::Collection::IList* GetShortMonths(void) const;
 211
 212
 213         /**
 214          * Sets the short month name strings concatenated using '|'. @n
 215          * For example: "Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec".
 216          *
 217          * @since                               2.0
 218          * @return                              An error code
 219          * @param[in]                   shortMonths                             The short month name strings concatenated using '|'
 220          * @exception                   E_SUCCESS                               The method is successful.
 221          * @exception                   E_INVALID_ARG                   The specified @c shortMonths contains an invalid value. @n
 222          *                                                                                              See the valid string in the description of the method.
 223          * @see                                 GetShortMonths()
 224          */
 225         result SetShortMonths(const Tizen::Base::String& shortMonths);
 226
 227
 228         /**
 229          * Gets the list of the weekday name strings. @n
 230          * For example: "Sunday", "Monday".
 231          *
 232          * @since                               2.0
 233          *
 234          * @return                              A pointer to the list of weekday name strings, @n
 235          *                                              else @c null if this instance has not been constructed as yet
 236          * @see                                 SetWeekdays()
 237          */
 238         const Tizen::Base::Collection::IList* GetWeekdays(void) const;
 239
 240
 241         /**
 242          * Sets the weekday name strings concatenated by '|'. @n
 243          * For example: "Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday".
 244          *
 245          * @since                               2.0
 246          *
 247          * @return                              An error code
 248          * @param[in]                   weekdays                                        The weekday name strings concatenated using '|'
 249          * @exception                   E_SUCCESS                                       The method is successful.
 250          * @exception                   E_INVALID_ARG                           The specified @c weekdays contains an invalid value.
 251          * @see                                 GetWeekdays()
 252          */
 253         result SetWeekdays(const Tizen::Base::String& weekdays);
 254
 255
 256         /**
 257          * Gets the list of the short weekday name strings. @n
 258          * For example: "Sun", "Mon".
 259          *
 260          * @since                               2.0
 261          *
 262          * @return                              A pointer to the list of short weekday name strings, @n
 263          *                                              else @c null if this instance has not been constructed as yet
 264          * @see                                 SetShortWeekdays()
 265          */
 266         const Tizen::Base::Collection::IList* GetShortWeekdays(void) const;
 267
 268
 269         /**
 270          * Sets the weekday name strings concatenated using '|'. @n
 271          * For example: "Sun|Mon|Tue|Wed|Thu|Fri|Sat".
 272          *
 273          * @since                               2.0
 274          *
 275          * @return                              An error code
 276          * @param[in]                   shortWeekdays                           The short weekday strings concatenated using '|'
 277          * @exception                   E_SUCCESS                                       The method is successful.
 278          * @exception                   E_INVALID_ARG                           The specified @c shortWeekdays contains an invalid value.
 279          * @see                                 GetShortWeekdays()
 280          */
 281         result SetShortWeekdays(const Tizen::Base::String& shortWeekdays);
 282
 283
 284         /**
 285          * Gets the list of the AM/PM strings. @n
 286          * For example: "AM" and "PM".
 287          *
 288          * @since                               2.0
 289          *
 290          * @return                              A pointer to the list of AM/PM strings, @n
 291          *                                              else @c null if this instance has not been constructed as yet
 292          * @see                                 SetAmPm()
 293          */
 294         const Tizen::Base::Collection::IList* GetAmPm(void) const;
 295
 296
 297         /**
 298          * Sets the AM/PM strings concatenated using '|'. @n
 299          * For example: "AM|PM".
 300          *
 301          * @since                               2.0
 302          *
 303          * @return                              An error code
 304          * @param[in]                   amPm                                            The AM/PM strings concatenated using '|'
 305          * @exception                   E_SUCCESS                                       The method is successful.
 306          * @exception                   E_INVALID_ARG                           The specified @c amPm contains an invalid value.
 307          * @see                                 GetAmPm()
 308          */
 309         result SetAmPm(const Tizen::Base::String& amPm);
 310
 311
 312         /**
 313          * Gets the name of the time zone. @n
 314          * For example: "Eastern European Time (EET)", "Eastern European Summer Time (EEST)".
 315          *
 316          * @since                                               2.0
 317          *
 318          * @return                                              The time zone name, @n
 319          *                                                              else an empty string if @c timeZoneId is not found @n
 320          *                                                              or the time zone name of @c timeZoneStyle is not found.
 321          * @param[in]   timeZoneId              The time zone ID
 322          * @param[in]   timeZoneStyle   The parameter may contain one of the following time zone styles:
 323          *                                                              @li The normal time zone (0)
 324          *                                                              @li The abbreviated time zone (1)
 325          *                                                              @li The normal summer time zone (2)
 326          *                                                              @li The abbreviated summer time zone (3)
 327          * @see                                                 SetTimeZoneName()
 328          * @see                                                 AddTimeZoneName()
 329          */
 330         Tizen::Base::String GetTimeZoneName(Tizen::Base::String& timeZoneId, int timeZoneStyle = 0) const;
 331
 332
 333         /**
 334          * Sets the time zone name string related to the specified time zone ID.
 335          *
 336          * @since                               2.0
 337          *
 338          * @return                              An error code
 339          * @param[in]                   timeZoneId                                                      The time zone ID @n
 340          *                                                                                                                      For example: "Europe/Helsinki".
 341          * @param[in]                   concatenatedTimeZoneName                        The concatenated time zone name @n
 342          *                                                                                                                      For example, "Eastern European Time|EET|Eastern European Summer Time|EEST".
 343          * @exception                   E_SUCCESS                       The method is successful.
 344          * @exception                   E_INVALID_ARG           The specified @c timeZoneId or @c concatenatedTimeZoneName contains an invalid value.
 345          * @exception                   E_OBJ_NOT_FOUND         The specified @c timeZoneId is not found.
 346          * @see                                 GetTimeZoneName()
 347          * @see                                 AddTimeZoneName()
 348          */
 349         result SetTimeZoneName(const Tizen::Base::String& timeZoneId, const Tizen::Base::String& concatenatedTimeZoneName);
 350
 351
 352         /**
 353          * Adds the time zone name that is related to time zone ID.
 354          *
 355          * @since                               2.0
 356          *
 357          * @return                              An error code
 358          * @param[in]                   timeZoneId                                                      The time zone ID @n
 359          *                                                                                                                      For example: "Europe/Helsinki".
 360          * @param[in]                   concatenatedTimeZoneName                        The concatenated time zone name @n
 361          *                                                                                                                      For example, "Eastern European Time|EET|Eastern European Summer Time|EEST".
 362          * @exception                   E_SUCCESS                       The method is successful.
 363          * @exception                   E_INVALID_ARG           A specified input parameter is invalid.
 364          * @exception                   E_OBJ_ALREADY_EXIST     The specified @c timeZoneId already exists.
 365          * @see                                 GetTimeZoneName()
 366          * @see                                 SetTimeZoneName()
 367          */
 368         result AddTimeZoneName(const Tizen::Base::String& timeZoneId, const Tizen::Base::String& concatenatedTimeZoneName);
 369
 370 private:
 371         /**
 372          * The implementation of this copy constructor is intentionally blank and declared as private to
 373          * prohibit copying of objects.
 374          */
 375         DateTimeSymbols(const DateTimeSymbols& dateTimeSymbols);
 376
 377         /**
 378          * The implementation of this copy assignment operator is intentionally blank and declared as private
 379          * to prohibit copying of objects.
 380          */
 381         DateTimeSymbols& operator =(const DateTimeSymbols& dateTimeSymbols);
 382
 383         friend class _DateTimeSymbolsImpl;
 384         class _DateTimeSymbolsImpl* __pDateTimeSymbolsImpl;
 385
 386 }; // DateTimeSymbols
 387
 388 }} // Tizen::Locales
 389
 390 #endif //_FLCL_DATE_TIME_SYMBOLS_H_
 391