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