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::Locales;
 109
 110 void
 111 LocaleApp::LocaleExample2(void)
 112 {
 113         LocaleManager localeManager;
 114         localeManager.Construct();
 115
 116         IList* pAvailableLocales = localeManager.GetAvailableLocalesN();
 117         if (pAvailableLocales)
 118         {
 119                 for (int i = 0; i < pAvailableLocales->GetCount(); i++)
 120                 {
 121                         Locale* pLocale = (Locale*) (pAvailableLocales->GetAt(i));
 122
 123                         String languageCodeString = pLocale->GetLanguageCodeString();
 124                         String countryCodeString = pLocale->GetCountryCodeString();
 125                         String variantCodString = pLocale->GetVariantCodeString();
 126
 127                         // ...
 128                 }
 129         }
 130 }
 131
 132 @endcode
 133
 134  *
 135  */
 136 class _OSP_EXPORT_ LocaleManager
 137         : public Tizen::Base::Object
 138 {
 139 public:
 140         /**
 141          * This is the default constructor for this class. @n
 142          * 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.
 143          *
 144          * @since               2.0
 145          *
 146          * @see                         Construct()
 147          *
 148          */
 149         LocaleManager(void);
 150
 151         /**
 152          * This is the destructor for this class. @n
 153          * This destructor overrides Tizen::Base::Object::~Object().
 154          *
 155          * @since               2.0
 156          */
 157         virtual ~LocaleManager(void);
 158
 159         /**
 160          * Initializes this instance of %LocaleManager.
 161          *
 162          * @since                               2.0
 163          *
 164          * @return                              An error code
 165          * @exception                   E_SUCCESS                                       The method is successful.
 166          * @exception                   E_OUT_OF_MEMORY                         The memory is insufficient.
 167          */
 168         result Construct(void);
 169
 170
 171         /**
 172          * Gets the system locale of the device.
 173          *
 174          * @since                               2.0
 175          *
 176          * @return                              An instance of Locale
 177          * @exception                   E_SUCCESS                                       The method is successful.
 178          * @exception                   E_SYSTEM                                        A system error has occurred.
 179          * @remarks                             The specific error code can be accessed using the GetLastResult() method.
 180          *                                              The resulting Locale instance is Locale (LANGUAGE_INVALID, COUNTRY_INVALID).
 181          */
 182         Locale GetSystemLocale(void) const;
 183
 184
 185         /**
 186          * Gets a list of all the available locales.
 187          *
 188          * @since                               2.0
 189          *
 190          * @return                              A list of Locale instances, @n
 191          *                                              else @c null if the method fails
 192          * @exception                   E_SUCCESS                                       The method is successful.
 193          * @exception                   E_OUT_OF_MEMORY                         The memory is insufficient.
 194          * @exception                   E_SYSTEM                                        A system error has occurred.
 195          * @remarks                             The IList returned contains the list of all the locales installed on the system.
 196          *                                              The specific error code can be accessed using the GetLastResult() method.
 197          */
 198         Tizen::Base::Collection::IList* GetAvailableLocalesN(void) const;
 199
 200
 201         /**
 202          * Gets the currently selected language of the device by a user from the user setting menu.
 203          *
 204          * @since                               2.0
 205          *
 206          * @return                              An instance of Tizen::Base::String (ISO 639-2 code format), @n
 207          *                                              else empty string if the method fails
 208          * @exception                   E_SUCCESS                                       The method is successful.
 209          * @remarks                             The specific error code can be accessed using the GetLastResult() method.
 210          */
 211         Tizen::Base::String GetSelectedLanguage(void) const;
 212
 213
 214         /**
 215          * 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.
 216          *
 217          * @since                               2.0
 218          *
 219          * @return                              A list of Tizen::Base::String instances (ISO 639-2 code format), @n
 220          *                                              else @c null if the method fails
 221          * @exception                   E_SUCCESS                                       The method is successful.
 222          * @exception                   E_OUT_OF_MEMORY                         The memory is insufficient.
 223          * @exception                   E_SYSTEM                                        A system error has occurred.
 224          * @remarks                             The specific error code can be accessed using the GetLastResult() method.
 225          */
 226         Tizen::Base::Collection::IList* GetAvailableLanguagesN(void) const;
 227
 228
 229         /**
 230          * Gets a list of all the available time zone IDs.
 231          *
 232          * @since                               2.0
 233          *
 234          * @return                              A list of Tizen::Base::String instances, @n
 235          *                                              else @c null if the method fails
 236          * @exception                   E_SUCCESS                                       The method is successful.
 237          * @exception                   E_OUT_OF_MEMORY                         The memory is insufficient.
 238          * @exception                   E_SYSTEM                                        A system error has occurred.
 239          * @remarks                             The specific error code can be accessed using the GetLastResult() method.
 240          */
 241         Tizen::Base::Collection::IList* GetAvailableTimeZonesN(void) const;
 242
 243
 244         /**
 245          * Gets a list of all the available time zone IDs with the specified Greenwich Mean Time (GMT) offset for this time zone.
 246          *
 247          * @since                               2.0
 248          *
 249          * @return                              A list of Tizen::Base::String instances, @n
 250          *                                              else @c null if the method fails
 251          * @param[in]                   rawOffset                                       The specified GMT offset for this time zone (Daylight Saving Time (DST) is not considered) @n
 252          *                                                                                                      The value of @c rawOffset is in minutes.
 253          * @exception                   E_SUCCESS                                       The method is successful.
 254          * @exception                   E_OUT_OF_MEMORY                         The memory is insufficient.
 255          * @exception                   E_SYSTEM                                        A system error has occurred.
 256          * @remarks                             The specific error code can be accessed using the GetLastResult() method.
 257          *                                              If there are no time zones for the specified GMT offset, an empty list is returned.
 258          */
 259         Tizen::Base::Collection::IList* GetAvailableTimeZonesN(int rawOffset) const;
 260
 261
 262         /**
 263          * Gets the default system time zone.
 264          *
 265          * @since                               2.0
 266          *
 267          * @return                              The default system time zone, @n
 268          *                                              else the time zone name is an empty string and the offset is @c -1 if the method fails
 269          * @exception                   E_SUCCESS                                       The method is successful.
 270          * @remarks                             The specific error code can be accessed using the GetLastResult() method.
 271          */
 272         TimeZone GetSystemTimeZone(void) const;
 273
 274
 275         /**
 276          * Checks whether the specified instance of Locale is supported.
 277          *
 278          * @since                               2.0
 279          *
 280          * @return                              An error code
 281          * @param[in]                   locale                                          An instance of Locale
 282          * @param[out]                  isSupportedLocale                       The flag for checking the supported locale
 283          * @exception                   E_SUCCESS                                       The method is successful.
 284          */
 285         result IsSupportedLocale(const Locale& locale, bool& isSupportedLocale);
 286
 287 private:
 288         /**
 289          * The implementation of this copy constructor is intentionally blank and declared as private to
 290          * prohibit copying of objects.
 291          */
 292         LocaleManager(const LocaleManager& localeManager);
 293
 294         /**
 295          * The implementation of this copy assignment operator is intentionally blank and declared as private
 296          * to prohibit copying of objects.
 297          */
 298         LocaleManager& operator =(const LocaleManager& localeManager);
 299
 300         friend class _LocaleManagerImpl;
 301         class _LocaleManagerImpl* __pLocaleManagerImpl;
 302 }; // Locale
 303
 304 }} // Tizen::Locales
 305
 306 #endif //_FLCL_LOCALE_MANAGER_H_