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 that help in providing 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, the days of the week, and the time zone data.
  41  * 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 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.
  43  *
  44  * 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>.
  45  *
  46  * @see                 Tizen::Locales::DateTimeFormatter
  47  *
  48  */
  49 class _OSP_EXPORT_ DateTimeSymbols
  50         : public Tizen::Base::Object
  51 {
  52
  53 public:
  54         /**
  55          * This is the default constructor for this class. @n
  56          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
  57          *
  58          * @since                       2.0
  59          *
  60          * @see                         Construct()
  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 by '|'. For example: "AD|BC".
 160          *
 161          * @since                               2.0
 162          *
 163          * @return                              An error code
 164          * @param[in]                   eras                                            The era strings concatenated by '|'
 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", etc.
 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 by '|'. @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 new month strings concatenated by '|'
 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", etc.
 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 by '|'. @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 new short month name strings concatenated by '|'
 220          * @exception                   E_SUCCESS                               The method is successful.
 221          * @exception                   E_INVALID_ARG                   The specified @c shortMonths contains an invalid value. @n See the valid string in the description of the method.
 222          * @see                                         GetShortMonths()
 223          */
 224         result SetShortMonths(const Tizen::Base::String& shortMonths);
 225
 226
 227         /**
 228          * Gets the list of the weekday name strings. @n
 229          * For example: "Sunday", "Monday", etc.
 230          *
 231          * @since                               2.0
 232          *
 233          * @return                              A pointer to the list of weekday name strings, @n
 234          *                                              else @c null if this instance has not been constructed as yet
 235          * @see                                 SetWeekdays()
 236          */
 237         const Tizen::Base::Collection::IList* GetWeekdays(void) const;
 238
 239
 240         /**
 241          * Sets the weekday name strings concatenated by '|'. @n
 242          * For example: "Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday".
 243          *
 244          * @since                               2.0
 245          *
 246          * @return                              An error code
 247          * @param[in]                   weekdays                                        The new weekday name strings concatenated by '|'
 248          * @exception                   E_SUCCESS                                       The method is successful.
 249          * @exception                   E_INVALID_ARG                           The specified @c weekdays contains an invalid value.
 250          * @see                                 GetWeekdays()
 251          */
 252         result SetWeekdays(const Tizen::Base::String& weekdays);
 253
 254
 255         /**
 256          * Gets the list of the short weekday name strings. @n
 257          * For example: "Sun", "Mon", etc.
 258          *
 259          * @since                               2.0
 260          *
 261          * @return                              A pointer to the list of short weekday name strings, @n
 262          *                                              else @c null if this instance has not been constructed as yet
 263          * @see                                 SetShortWeekdays()
 264          */
 265         const Tizen::Base::Collection::IList* GetShortWeekdays(void) const;
 266
 267
 268         /**
 269          * Sets the weekday name strings concatenated by '|'. @n
 270          * For example: "Sun|Mon|Tue|Wed|Thu|Fri|Sat".
 271          *
 272          * @since                               2.0
 273          *
 274          * @return                              An error code
 275          * @param[in]                   shortWeekdays                           The new short weekday strings concatenated by '|'
 276          * @exception                   E_SUCCESS                                       The method is successful.
 277          * @exception                   E_INVALID_ARG                           The specified @c shortWeekdays contains an invalid value.
 278          * @see                                 GetShortWeekdays()
 279          */
 280         result SetShortWeekdays(const Tizen::Base::String& shortWeekdays);
 281
 282
 283         /**
 284          * Gets the list of the AM/PM strings. @n
 285          * For example: "AM" and "PM".
 286          *
 287          * @since                               2.0
 288          *
 289          * @return                              A pointer to the list of AM/PM strings, @n
 290          *                                              else @c null if this instance has not been constructed as yet
 291          * @see                                 SetAmPm()
 292          */
 293         const Tizen::Base::Collection::IList* GetAmPm(void) const;
 294
 295
 296         /**
 297          * Sets the AM/PM strings concatenated by '|'. @n
 298          * For example: "AM|PM".
 299          *
 300          * @since                               2.0
 301          *
 302          * @return                              An error code
 303          * @param[in]                   amPm                                            The new AM/PM strings concatenated by '|'
 304          * @exception                   E_SUCCESS                                       The method is successful.
 305          * @exception                   E_INVALID_ARG                           The specified @c amPm contains an invalid value.
 306          * @see                                 GetAmPm()
 307          */
 308         result SetAmPm(const Tizen::Base::String& amPm);
 309
 310
 311         /**
 312          * Gets the name of the time zone. @n
 313          * For example: "Eastern European Time (EET)", "Eastern European Summer Time (EEST)".
 314          *
 315          * @since                               2.0
 316          *
 317          * @return                              The time zone name, @n
 318          *                                              else an empty string if @c timeZoneId is not found @n
 319          *                                              or the time zone name of @c timeZoneStyle is not found.
 320          * @param[in]   timeZoneId              The time zone ID
 321          * @param[in]   timeZoneStyle   The parameter may contain one of the following time zone styles:
 322          *                                                              @li The normal time zone (0)
 323          *                                                              @li The abbreviated time zone (1)
 324          *                                                              @li The normal summer time zone (2)
 325          *                                                              @li The abbreviated summer time zone (3)
 326          * @see                                                 SetTimeZoneName()
 327          * @see                                                 AddTimeZoneName()
 328          */
 329         Tizen::Base::String GetTimeZoneName(Tizen::Base::String& timeZoneId, int timeZoneStyle = 0) const;
 330
 331
 332         /**
 333          * Sets the time zone name string related to the specified time zone ID.
 334          *
 335          * @since                               2.0
 336          *
 337          * @return                              An error code
 338          * @param[in]                   timeZoneId                                                      The time zone ID @n
 339          *                                                                                                                      For example: "Europe/Helsinki".
 340          * @param[in]                   concatenatedTimeZoneName                        The new concatenated time zone name @n
 341          *                                                                                                                      For example, "Eastern European Time|EET|Eastern European Summer Time|EEST".
 342          * @exception                   E_SUCCESS                       The method is successful.
 343          * @exception                   E_INVALID_ARG           The specified @c timeZoneId or @c concatenatedTimeZoneName contains an invalid value.
 344          * @exception                   E_OBJ_NOT_FOUND         The specified @c timeZoneId is not found.
 345          * @see                                         GetTimeZoneName()
 346          * @see                                         AddTimeZoneName()
 347          */
 348         result SetTimeZoneName(const Tizen::Base::String& timeZoneId, const Tizen::Base::String& concatenatedTimeZoneName);
 349
 350
 351         /**
 352          * Adds a new time zone name string that is related to time zone ID.
 353          *
 354          * @since                               2.0
 355          *
 356          * @return                              An error code
 357          * @param[in]                   timeZoneId                                                      The time zone ID @n
 358          *                                                                                                                      For example: "Europe/Helsinki".
 359          * @param[in]                   concatenatedTimeZoneName                        The concatenated time zone name @n
 360          *                                                                                                                      For example, "Eastern European Time|EET|Eastern European Summer Time|EEST".
 361          * @exception                   E_SUCCESS                       The method is successful.
 362          * @exception                   E_INVALID_ARG           A specified input parameter is invalid.
 363          * @exception                   E_OBJ_ALREADY_EXIST     The specified @c timeZoneId already exists.
 364          * @see                                 GetTimeZoneName()
 365          * @see                                 SetTimeZoneName()
 366          */
 367         result AddTimeZoneName(const Tizen::Base::String& timeZoneId, const Tizen::Base::String& concatenatedTimeZoneName);
 368
 369 private:
 370         /**
 371          * The implementation of this copy constructor is intentionally blank and declared as private to
 372          * prohibit copying of objects.
 373          */
 374         DateTimeSymbols(const DateTimeSymbols& dateTimeSymbols);
 375
 376         /**
 377          * The implementation of this copy assignment operator is intentionally blank and declared as private
 378          * to prohibit copying of objects.
 379          */
 380         DateTimeSymbols& operator =(const DateTimeSymbols& dateTimeSymbols);
 381
 382         friend class _DateTimeSymbolsImpl;
 383         class _DateTimeSymbolsImpl* __pDateTimeSymbolsImpl;
 384
 385 }; // DateTimeSymbols
 386
 387 }} // Tizen::Locales
 388
 389 #endif //_FLCL_DATE_TIME_SYMBOLS_H_
 390