inc/FLclLocaleManager.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                FLclLocaleManager.h
  19  * @brief               This is the header file for the %LocaleManager class.
  20  *
  21  * This header file contains the declarations of the %LocaleManager class.
  22  *
  23  */
  24 #ifndef _FLCL_LOCALE_MANAGER_H_
  25 #define _FLCL_LOCALE_MANAGER_H_
  26
  27 #include <FBaseString.h>
  28 #include <FBaseColIList.h>
  29 #include <FLclTimeZone.h>
  30 #include <FLclLocale.h>
  31
  32 namespace Tizen { namespace Locales
  33 {
  34
  35 /**
  36  * @class               LocaleManager
  37  * @brief               This class provides methods for %LocaleManager identification.
  38  *
  39  * @since               2.0
  40  *
  41  * @final       This class is not intended for extension.
  42  *
  43  * The %LocaleManager class provides methods for the system locale information of the device. Each device system has at least
  44  * one installed locale and often has many locales from which the user can choose.
  45  *
  46  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/locales/lang_country_codes.htm">Retrieving Language and Country Codes</a>.
  47
  48  * @see Locale
  49  * @see NumberFormatter
  50  * @see DateTimeFormatter
  51  *
  52  * The following example demonstrates how to use the %LocaleManager class to get and set system locale information.
  53  *
  54  * @code
  55
  56 #include <FBase.h>
  57 #include <FLocales.h>
  58
  59 using namespace Tizen::Base;
  60 using namespace Tizen::Locales;
  61
  62 void
  63 LocaleApp::LocaleExample1(void)
  64 {
  65     LocaleManager localeManager;
  66     localeManager.Construct();
  67
  68     // Gets the system locale information.
  69     Locale      systemLocale = localeManager.GetSystemLocale();
  70
  71     String countryCodeString = systemLocale.GetCountryCodeString();
  72     String languageCodeString = systemLocale.GetLanguageCodeString();
  73     String variantCodString = systemLocale.GetVariantCodeString();
  74
  75     // Gets the formatted number that is localized.
  76     NumberFormatter* pNumberFormatter = NumberFormatter::CreateNumberFormatterN(systemLocale);
  77
  78     String formattedString;
  79     long inputNumber = 123456;
  80     pNumberFormatter->Format((long) inputNumber, formattedString);
  81
  82     // Gets the formatted date/time that is localized.
  83     DateTimeFormatter* pDateTimeFormatter = DateTimeFormatter::CreateDateTimeFormatterN(systemLocale);
  84     DateTime dateTime;
  85     dateTime.SetValue(2009, 2, 24, 15, 22, 00);
  86     pDateTimeFormatter->Format(dateTime, formattedString);
  87
  88     // Gets the currency symbol that is localized.
  89     NumberFormatter* pCurrencyFormatter = NumberFormatter::CreateCurrencyFormatterN(systemLocale);
  90     inputNumber = 4000;
  91     pCurrencyFormatter->Format(inputNumber, formattedString);
  92
  93
  94     delete pNumberFormatter;
  95     delete pDateTimeFormatter;
  96     delete pCurrencyFormatter;
  97 }
  98
  99 @endcode
 100  *
 101  * The following example demonstrates how to use the %LocaleManager class to get a list of all the available locales from the system.
 102  *
 103  * @code
 104
 105 #include <FBase.h>
 106 #include <FLocales.h>
 107
 108 using namespace Tizen::Base;
 109 using namespace Tizen::Base::Collection;
 110 using namespace Tizen::Locales;
 111
 112 void
 113 LocaleApp::LocaleExample2(void)
 114 {
 115         LocaleManager localeManager;
 116         localeManager.Construct();
 117
 118         IList* pAvailableLocales = localeManager.GetAvailableLocalesN();
 119         if (pAvailableLocales)
 120         {
 121                 for (int i = 0; i < pAvailableLocales->GetCount(); i++)
 122                 {
 123                         Locale* pLocale = (Locale*) (pAvailableLocales->GetAt(i));
 124
 125                         String languageCodeString = pLocale->GetLanguageCodeString();
 126                         String countryCodeString = pLocale->GetCountryCodeString();
 127                         String variantCodString = pLocale->GetVariantCodeString();
 128
 129                         // ...
 130                 }
 131         }
 132 }
 133
 134 @endcode
 135
 136  *
 137  */
 138 class _OSP_EXPORT_ LocaleManager
 139         : public Tizen::Base::Object
 140 {
 141 public:
 142         /**
 143          * This is the default constructor for this class. @n
 144          * The object is not fully constructed after this constructor is called. For full construction, the Construct()
 145          * method must be called right after calling this constructor.
 146          *
 147          * @since               2.0
 148          *
 149          */
 150         LocaleManager(void);
 151
 152         /**
 153          * This is the destructor for this class. @n
 154          * This destructor overrides Tizen::Base::Object::~Object().
 155          *
 156          * @since               2.0
 157          */
 158         virtual ~LocaleManager(void);
 159
 160         /**
 161          * Initializes this instance of %LocaleManager.
 162          *
 163          * @since                               2.0
 164          *
 165          * @return                              An error code
 166          * @exception                   E_SUCCESS                                       The method is successful.
 167          * @exception                   E_OUT_OF_MEMORY                         The memory is insufficient.
 168          */
 169         result Construct(void);
 170
 171
 172         /**
 173          * Gets the system locale of the device.
 174          *
 175          * @since                               2.0
 176          *
 177          * @return                              The system locale
 178          * @exception                   E_SUCCESS                                       The method is successful.
 179          * @exception                   E_SYSTEM                                        A system error has occurred.
 180          * @remarks
 181          *                                      - The specific error code can be accessed using the GetLastResult() method.
 182          *                                      - The resulting Locale instance is Locale(@c LANGUAGE_INVALID, @c COUNTRY_INVALID).
 183          */
 184         Locale GetSystemLocale(void) const;
 185
 186
 187         /**
 188          * Gets the list of all the available locales.
 189          *
 190          * @since                               2.0
 191          *
 192          * @return                              The list of available locales, @n
 193          *                                              else @c null if it fails
 194          * @exception                   E_SUCCESS                                       The method is successful.
 195          * @exception                   E_OUT_OF_MEMORY                         The memory is insufficient.
 196          * @exception                   E_SYSTEM                                        A system error has occurred.
 197          * @remarks
 198          *                                      - The Tizen::Base::Collection::IList returned contains the list of all the locales installed on the system.
 199          *                                      - The specific error code can be accessed using the GetLastResult() method.
 200          */
 201         Tizen::Base::Collection::IList* GetAvailableLocalesN(void) const;
 202
 203
 204         /**
 205          * Gets the currently selected language of the device by a user from the user setting menu.
 206          *
 207          * @since                               2.0
 208          *
 209          * @return                              The user selected language as an instance of Tizen::Base::String (ISO 639-2 code format), @n
 210          *                                              else empty string if the method fails
 211          * @exception                   E_SUCCESS                                       The method is successful.
 212          * @remarks                             The specific error code can be accessed using the GetLastResult() method.
 213          */
 214         Tizen::Base::String GetSelectedLanguage(void) const;
 215
 216
 217         /**
 218          * Gets the list of all the available languages supported by the device, which can be different according to the target
 219          * country/region of the device.
 220          *
 221          * @since                               2.0
 222          *
 223          * @return                              The list of all available languages as Tizen::Base::String instances (ISO 639-2 code format), @n
 224          *                                              else @c null if it fails
 225          * @exception                   E_SUCCESS                                       The method is successful.
 226          * @exception                   E_OUT_OF_MEMORY                         The memory is insufficient.
 227          * @exception                   E_SYSTEM                                        A system error has occurred.
 228          * @remarks                             The specific error code can be accessed using the GetLastResult() method.
 229          */
 230         Tizen::Base::Collection::IList* GetAvailableLanguagesN(void) const;
 231
 232
 233         /**
 234          * Gets the list of all the available time zone IDs.
 235          *
 236          * @since                               2.0
 237          *
 238          * @return                              The list of all available time zone IDs as Tizen::Base::String instances, @n
 239          *                                              else @c null if it fails
 240          * @exception                   E_SUCCESS                                       The method is successful.
 241          * @exception                   E_OUT_OF_MEMORY                         The memory is insufficient.
 242          * @exception                   E_SYSTEM                                        A system error has occurred.
 243          * @remarks                             The specific error code can be accessed using the GetLastResult() method.
 244          */
 245         Tizen::Base::Collection::IList* GetAvailableTimeZonesN(void) const;
 246
 247
 248         /**
 249          * Gets the list of all the available time zone IDs with the specified Greenwich Mean Time (GMT) offset for this time zone.
 250          *
 251          * @since                               2.0
 252          *
 253          * @return                              The list of all availabke time zone IDs with the GMT offset as Tizen::Base::String instances, @n
 254          *                                              else @c null if it fails
 255          * @param[in]                   rawOffset                                       The specified GMT offset for this time zone (Daylight Saving Time (DST) is not considered) @n
 256          *                                                                                                      The value of @c rawOffset is in minutes.
 257          * @exception                   E_SUCCESS                                       The method is successful.
 258          * @exception                   E_OUT_OF_MEMORY                         The memory is insufficient.
 259          * @exception                   E_SYSTEM                                        A system error has occurred.
 260          * @remarks
 261          *                                              - The specific error code can be accessed using the GetLastResult() method.
 262          *                                              - If there are no time zones for the specified GMT offset, an empty list is returned.
 263          */
 264         Tizen::Base::Collection::IList* GetAvailableTimeZonesN(int rawOffset) const;
 265
 266
 267         /**
 268          * Gets the default system time zone.
 269          *
 270          * @since                               2.0
 271          *
 272          * @return                              The default system time zone, @n
 273          *                                              else the time zone name is an empty string and the offset is @c -1 if the method fails
 274          * @exception                   E_SUCCESS                                       The method is successful.
 275          * @remarks                             The specific error code can be accessed using the GetLastResult() method.
 276          */
 277         TimeZone GetSystemTimeZone(void) const;
 278
 279
 280         /**
 281          * Checks whether the specified instance of Locale is supported.
 282          *
 283          * @since                               2.0
 284          *
 285          * @return                              An error code
 286          * @param[in]                   locale                                          An instance of Locale
 287          * @param[out]                  isSupportedLocale                       The flag for checking the supported locale
 288          * @exception                   E_SUCCESS                                       The method is successful.
 289          */
 290         result IsSupportedLocale(const Locale& locale, bool& isSupportedLocale);
 291
 292 private:
 293         /**
 294          * The implementation of this copy constructor is intentionally blank and declared as private to
 295          * prohibit copying of objects.
 296          */
 297         LocaleManager(const LocaleManager& localeManager);
 298
 299         /**
 300          * The implementation of this copy assignment operator is intentionally blank and declared as private
 301          * to prohibit copying of objects.
 302          */
 303         LocaleManager& operator =(const LocaleManager& localeManager);
 304
 305         friend class _LocaleManagerImpl;
 306         class _LocaleManagerImpl* __pLocaleManagerImpl;
 307 }; // Locale
 308
 309 }} // Tizen::Locales
 310
 311 #endif //_FLCL_LOCALE_MANAGER_H_