1 /* This file is part of the KDE libraries 2 Copyright (C) 1997 Stephan Kulow <coolo@kde.org> 3 Copyright (C) 1999-2003 Hans Petter Bieker <bieker@kde.org> 4 Copyright (c) 2002 Lukas Tinkl <lukas@kde.org> 5 6 This library is free software; you can redistribute it and/or 7 modify it under the terms of the GNU Library General Public 8 License as published by the Free Software Foundation; either 9 version 2 of the License, or (at your option) any later version. 10 11 This library is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 Library General Public License for more details. 15 16 You should have received a copy of the GNU Library General Public License 17 along with this library; see the file COPYING.LIB. If not, write to 18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 19 Boston, MA 02110-1301, USA. 20 */ 21 #ifndef KLOCALE_H 22 #define KLOCALE_H 23 24 #include <kdelibs4support_export.h> 25 #include <ksharedconfig.h> 26 27 // Include for providing source code compatibility 28 #include <klocalizedstring.h> 29 30 #include <QString> 31 #include <QList> 32 33 class QStringList; 34 class QTextCodec; 35 class QDate; 36 class QTime; 37 class QDateTime; 38 39 class KDateTime; 40 class KCalendarSystem; 41 class KCurrencyCode; 42 class KDayPeriod; 43 44 class KLocalePrivate; 45 46 /** 47 * \file klocale.h 48 */ 49 50 /** 51 * KLocale provides support for language and country specific stuff. 52 * 53 * KLocale supports specifying the format 54 * for numbers, currency, time, and date. 55 * 56 * Use KLocale::global() to get pointer to the global KLocale object, 57 * containing the applications current locale settings. 58 * 59 * For example, to format the date May 17, 1995 in the current locale, use: 60 * 61 * \code 62 * QString date = KLocale::global()->formatDate(QDate(1995,5,17)); 63 * \endcode 64 * 65 * @author Stephan Kulow <coolo@kde.org>, Preston Brown <pbrown@kde.org>, 66 * Hans Petter Bieker <bieker@kde.org>, Lukas Tinkl <lukas.tinkl@suse.cz> 67 * @short class for supporting locale settings 68 * 69 * @deprecated since 5.0. For translation support use KLocalizedString (from the 70 * KI18n framework); for string formatting use QLocale() or KFormat (from the 71 * KCoreAddons framework) if QLocale doesn't provide the formatting you need. 72 * For more information about porting code that is still using KLocale see: 73 * https://community.kde.org/Frameworks/Porting_Notes#Localization 74 */ 75 class KDELIBS4SUPPORT_EXPORT KLocale 76 { 77 public: 78 /** 79 * Constructs a KLocale. 80 * 81 * The constructor looks for entries Language and Country 82 * in the group Locale in the configuration file. 83 * 84 * If no configuration file is specified, it will also look for languages 85 * and country using the environment variables (KDE_LANG, LC_MESSAGES, 86 * LC_ALL, LANG), as well as the global configuration file. 87 * 88 * If you specify a configuration file, it has to be valid until the KLocale 89 * object is destroyed. Note that a setLocale() will be performed on the 90 * config using the current locale language and country, which may cause 91 * a sync() and reparseConfiguration() which will save any changes 92 * you have made and load any changes other shared copies have made. 93 * 94 * @param config a configuration file with a Locale group detailing 95 * locale-related preferences (such as language, country, 96 * and formatting options). 97 */ 98 KDELIBS4SUPPORT_DEPRECATED explicit KLocale(KSharedConfig::Ptr config = KSharedConfig::Ptr()); 99 100 /** 101 * Constructs a KLocale. 102 * 103 * Allows you to override the language and, optionally, the 104 * country of this locale. 105 * 106 * If you specify a configuration file, a setLocale() will be performed on 107 * the config using the current locale language and country, 108 * which may cause a sync() and reparseConfiguration() which 109 * will save any changes you have made. 110 * 111 * @param language the ISO Language Code for the locale, e.g. "en" for English 112 * @param country the ISO Country Code for the locale, e.g. "US" for USA 113 * @param config a configuration file with a Locale group detailing 114 * locale-related preferences (such as language, country, 115 * and formatting options). 116 */ 117 KLocale(const QString &language, const QString &country = QString(), 118 KConfig *config = nullptr); 119 120 /** 121 * Copy constructor 122 */ 123 KLocale(const KLocale &rhs); 124 125 /** 126 * Assignment operator 127 */ 128 KLocale &operator= (const KLocale &rhs); 129 130 /** 131 * Destructor 132 */ 133 virtual ~KLocale(); 134 135 /** 136 * Changes the current encoding. 137 * 138 * @param mibEnum The mib of the preferred codec 139 * 140 * @return True on success. 141 */ 142 bool setEncoding(int mibEnum); 143 144 /** 145 * Various positions for where to place the positive or negative 146 * sign when they are related to a monetary value. 147 */ 148 enum SignPosition { 149 /** 150 * Put parantheses around the quantity, e.g. "$ (217)" 151 */ 152 ParensAround = 0, 153 /** 154 * Prefix the quantity with the sign, e.g. "$ -217" 155 */ 156 BeforeQuantityMoney = 1, 157 /** 158 * Suffix the quanitity with the sign, e.g. "$ 217-" 159 */ 160 AfterQuantityMoney = 2, 161 /** 162 * Prefix the currency symbol with the sign, e.g. "-$ 217" 163 */ 164 BeforeMoney = 3, 165 /** 166 * Suffix the currency symbol with the sign, e.g. "$- 217" 167 */ 168 AfterMoney = 4 169 }; 170 171 /** 172 * @since 4.3 173 * 174 * The set of digit characters used to display and enter numbers. 175 */ 176 enum DigitSet { 177 ArabicDigits, /**< 0123456789 (European and some Asian 178 languages and western Arabic dialects) */ 179 ArabicIndicDigits, /**< ٠١٢٣٤٥٦٧٨٩ (eastern Arabic dialects) */ 180 EasternArabicIndicDigits, /**< ۰۱۲۳۴۵۶۷۸۹ (Persian and Urdu) */ 181 DevenagariDigits, /**< ०१२३४५६७८९ (Hindi) */ 182 BengaliDigits, /**< ০১২৩৪৫৬৭৮৯ (Bengali and Assamese) */ 183 GujaratiDigits, /**< ૦૧૨૩૪૫૬૭૮૯ (Gujarati) */ 184 GurmukhiDigits, /**< ੦੧੨੩੪੫੬੭੮੯ (Punjabi) */ 185 KannadaDigits, /**< ೦೧೨೩೪೫೬೭೮೯ (Kannada) */ 186 KhmerDigits, /**< ០១២៣៤៥៦៧៨៩ (Khmer) */ 187 MalayalamDigits, /**< ൦൧൨൩൪൫൬൭൮൯ (Malayalam) */ 188 OriyaDigits, /**< ୦୧୨୩୪୫୬୭୮୯ (Oriya) */ 189 TamilDigits, /**< ௦௧௨௩௪௫௬௭௮ (Tamil) */ 190 TeluguDigits, /**< ౦౧౨౩౪౫౬౭౯ (Telugu) */ 191 ThaiDigits /**< ๐๑๒๓๔๕๖๗๘๙ (Thai) */ 192 // The following Decimal Digit Sets are defined in Unicode but the associated 193 // languages are not yet translated in KDE, so are not yet enabled. 194 // The script names are taken from the Unicode standard, the associated 195 // languages from Wikipedia. 196 // BalineseDigits, /**< ᭐᭑᭒᭓᭔᭕᭖᭗᭘᭙ (Balinese) */ 197 // ChamDigits, /**< ꩐꩑꩒꩓꩔꩕꩖꩗꩘꩙ (Cham) */ 198 // JavaneseDigits, /**< ꧐꧑꧒꧓꧔꧕꧖꧗꧘꧙ (Javanese) */ 199 // KayahLiDigits, /**< ꤀꤁꤂꤃꤄꤅꤆꤇꤈꤉ (Kayah) */ 200 // LaoDigits, /**< ໐໑໒໓໔໕໖໗໘໙ (Lao) */ 201 // LepchaDigits, /**< ᱀᱁᱂᱃᱄᱅᱆᱇᱈᱉ (Lepcha) */ 202 // LimbuDigits, /**< ᥆᥇᥈᥉᥊᥋᥌᥍᥎᥏ (Limbu) */ 203 // MeeteiMayekDigits, /**< ꯰꯱꯲꯳꯴꯵꯶꯷꯸꯹ (Meitei) */ 204 // MongolianDigits, /**< ᠐᠑᠒᠓᠔᠕᠖᠗᠘᠙ (Mongolian) */ 205 // MyanmarDigits, /**< ၀၁၂၃၄၅၆၇၈၉ (Myanmar/Burmese ) */ 206 // MyanmarShanDigits, /**< ႐႑႒႓႔႕႖႗႘႙ (Shan) */ 207 // NewTaiLueDigits, /**< ᧐᧑᧒᧓᧔᧕᧖᧗᧘᧙ (Tai Lü) */ 208 // NKoDigits, /**< ߀߁߂߃߄߅߆߇߈߉ (Mande and N'Ko) */ 209 // OlChikiDigits, /**< ᱐᱑᱒᱓᱔᱕᱖᱗᱘᱙ (Santali) */ 210 // OsmanyaDigits, /**< ҠҡҢңҤҥҦҧҨҩ (Somali) */ 211 // SaurashtraDigits, /**< ꣐꣑꣒꣓꣔꣕꣖꣗꣘꣙ (Saurashtra) */ 212 // SundaneseDigits, /**< ᮰᮱᮲᮳᮴᮵᮶᮷᮸᮹ (Sundanese) */ 213 // TaiThamDigits, /**< ᪐᪑᪒᪓᪔᪕᪖᪗᪘᪙ (Tai Lü) */ 214 // TibetanDigits, /**< ༠༡༢༣༤༥༦༧༨༩ (Tibetan) */ 215 // VaiDigits, /**< ꘠꘡꘢꘣꘤꘥꘦꘧꘨꘩ (Vai) */ 216 }; 217 218 /** 219 * @since 4.3 220 * 221 * Convert a digit set identifier to a human readable, localized name. 222 * 223 * @param digitSet the digit set identifier 224 * @param withDigits whether to add the digits themselves to the name 225 * 226 * @return the human readable and localized name of the digit set 227 * 228 * @see DigitSet 229 */ 230 QString digitSetToName(DigitSet digitSet, bool withDigits = false) const; 231 232 /** 233 * @since 4.3 234 * 235 * Provides list of all known digit set identifiers. 236 * 237 * @return list of all digit set identifiers 238 * @see DigitSet 239 * @see digitSetToName 240 */ 241 QList<DigitSet> allDigitSetsList() const; 242 243 /** 244 * Returns what a decimal point should look like ("." or "," etc.) 245 * according to the current locale or user settings. 246 * 247 * @return The decimal symbol used by locale. 248 */ 249 QString decimalSymbol() const; 250 251 /** 252 * Returns what the thousands separator should look 253 * like ("," or "." etc.) 254 * according to the current locale or user settings. 255 * 256 * @return The thousands separator used by locale. 257 */ 258 QString thousandsSeparator() const; 259 260 /** 261 * @since 4.3 262 * 263 * Returns the identifier of the digit set used to display numbers. 264 * 265 * @return the digit set identifier 266 * @see DigitSet 267 * @see digitSetToName 268 */ 269 DigitSet digitSet() const; 270 271 /** 272 * @since 4.4 273 * 274 * Returns the ISO 4217 Currency Code for the current locale 275 * 276 * @return The default ISO Currency Code used by locale. 277 */ 278 QString currencyCode() const; 279 280 /** 281 * @since 4.4 282 * 283 * Returns the Currency Code object for the current locale 284 * 285 * @return The default Currency Code object used by locale. 286 */ 287 KCurrencyCode *currency() const; 288 289 /** 290 * Returns what the symbol denoting currency in the current locale 291 * as as defined by user settings should look like. 292 * 293 * @return The default currency symbol used by locale. 294 */ 295 QString currencySymbol() const; 296 297 /** 298 * Returns what a decimal point should look like ("." or "," etc.) 299 * for monetary values, according to the current locale or user 300 * settings. 301 * 302 * @return The monetary decimal symbol used by locale. 303 */ 304 QString monetaryDecimalSymbol() const; 305 306 /** 307 * Returns what a thousands separator for monetary values should 308 * look like ("," or " " etc.) according to the current locale or 309 * user settings. 310 * 311 * @return The monetary thousands separator used by locale. 312 */ 313 QString monetaryThousandsSeparator() const; 314 315 /** 316 * Returns what a positive sign should look like ("+", " ", etc.) 317 * according to the current locale or user settings. 318 * 319 * @return The positive sign used by locale. 320 */ 321 QString positiveSign() const; 322 323 /** 324 * Returns what a negative sign should look like ("-", etc.) 325 * according to the current locale or user settings. 326 * 327 * @return The negative sign used by locale. 328 */ 329 QString negativeSign() const; 330 331 /** 332 * @deprecated use decimalPlaces() or monetaryDecimalPlaces() 333 * 334 * The number of fractional digits to include in monetary values (usually 2). 335 * 336 * @return Default number of fractional digits used by locale. 337 */ 338 KDELIBS4SUPPORT_DEPRECATED int fracDigits() const; 339 340 /** 341 * @since 4.4 342 * 343 * The number of decimal places to include in numeric values (usually 2). 344 * 345 * @return Default number of numeric decimal places used by locale. 346 */ 347 int decimalPlaces() const; 348 349 /** 350 * @since 4.4 351 * 352 * The number of decimal places to include in monetary values (usually 2). 353 * 354 * @return Default number of monetary decimal places used by locale. 355 */ 356 int monetaryDecimalPlaces() const; 357 358 /** 359 * If and only if the currency symbol precedes a positive value, 360 * this will be true. 361 * 362 * @return Where to print the currency symbol for positive numbers. 363 */ 364 bool positivePrefixCurrencySymbol() const; 365 366 /** 367 * If and only if the currency symbol precedes a negative value, 368 * this will be true. 369 * 370 * @return True if the currency symbol precedes negative numbers. 371 */ 372 bool negativePrefixCurrencySymbol() const; 373 374 /** 375 * Returns the position of a positive sign in relation to a 376 * monetary value. 377 * 378 * @return Where/how to print the positive sign. 379 * @see SignPosition 380 */ 381 SignPosition positiveMonetarySignPosition() const; 382 383 /** 384 * Denotes where to place a negative sign in relation to a 385 * monetary value. 386 * 387 * @return Where/how to print the negative sign. 388 * @see SignPosition 389 */ 390 SignPosition negativeMonetarySignPosition() const; 391 392 /** 393 * @since 4.3 394 * 395 * Retuns the digit set used to display monetary values. 396 * 397 * @return the digit set identifier 398 * @see DigitSet 399 * @see digitSetToName 400 */ 401 DigitSet monetaryDigitSet() const; 402 403 /** 404 * Given a double, converts that to a numeric string containing 405 * the localized monetary equivalent. 406 * 407 * e.g. given 123456, return "$ 123,456.00". 408 * 409 * If precision isn't specified or is < 0, then the default monetaryDecimalPlaces() is used. 410 * 411 * @param num The number we want to format 412 * @param currency The currency symbol you want. 413 * @param precision Number of decimal places displayed 414 * 415 * @return The number of money as a localized string 416 * @see monetaryDecimalPlaces() 417 */ 418 QString formatMoney(double num, const QString ¤cy = QString(), int precision = -1) const; 419 420 /** 421 * Given a double, converts that to a numeric string containing 422 * the localized numeric equivalent. 423 * 424 * e.g. given 123456.78F, return "123,456.78" (for some European country). 425 * 426 * If precision isn't specified or is < 0, then the default decimalPlaces() is used. 427 * 428 * This function is a wrapper that is provided for convenience. 429 * 430 * @param num The number to convert 431 * @param precision Number of decimal places used. 432 * 433 * @return The number as a localized string 434 * @see formatNumber(const QString, bool, int) 435 * @see decimalPlaces() 436 */ 437 QString formatNumber(double num, int precision = -1) const; 438 439 /** 440 * Given a string representing a number, converts that to a numeric 441 * string containing the localized numeric equivalent. 442 * 443 * e.g. given 123456.78F, return "123,456.78" (for some European country). 444 * 445 * If precision isn't specified or is < 0, then the default decimalPlaces() is used. 446 * 447 * @param numStr The number to format, as a string. 448 * @param round Round fractional digits. (default true) 449 * @param precision Number of fractional digits used for rounding. Unused if round=false. 450 * 451 * @return The number as a localized string 452 */ 453 QString formatNumber(const QString &numStr, bool round = true, int precision = -1) const; 454 455 /** 456 * Given an integer, converts that to a numeric string containing 457 * the localized numeric equivalent. 458 * 459 * e.g. given 123456L, return "123,456" (for some European country). 460 * 461 * @param num The number to convert 462 * 463 * @return The number as a localized string 464 */ 465 QString formatLong(long num) const; 466 467 /** 468 * These binary units are used in KDE by the formatByteSize() 469 * functions. 470 * 471 * NOTE: There are several different units standards: 472 * 1) SI (i.e. metric), powers-of-10. 473 * 2) IEC, powers-of-2, with specific units KiB, MiB, etc. 474 * 3) JEDEC, powers-of-2, used for solid state memory sizing which 475 * is why you see flash cards labels as e.g. 4GB. These (ab)use 476 * the metric units. Although JEDEC only defines KB, MB, GB, if 477 * JEDEC is selected all units will be powers-of-2 with metric 478 * prefixes for clarity in the event of sizes larger than 1024 GB. 479 * 480 * Although 3 different dialects are possible this enum only uses 481 * metric names since adding all 3 different names of essentially the same 482 * unit would be pointless. Use BinaryUnitDialect to control the exact 483 * units returned. 484 * 485 * @since 4.4 486 * @see binaryUnitDialect 487 */ 488 enum BinarySizeUnits { 489 /// Auto-choose a unit such that the result is in the range [0, 1000 or 1024) 490 DefaultBinaryUnits = -1, 491 492 // The first real unit must be 0 for the current implementation! 493 UnitByte, ///< B 1 byte 494 UnitKiloByte, ///< KiB/KB/kB 1024/1000 bytes. 495 UnitMegaByte, ///< MiB/MB/MB 2^20/10^06 bytes. 496 UnitGigaByte, ///< GiB/GB/GB 2^30/10^09 bytes. 497 UnitTeraByte, ///< TiB/TB/TB 2^40/10^12 bytes. 498 UnitPetaByte, ///< PiB/PB/PB 2^50/10^15 bytes. 499 UnitExaByte, ///< EiB/EB/EB 2^60/10^18 bytes. 500 UnitZettaByte, ///< ZiB/ZB/ZB 2^70/10^21 bytes. 501 UnitYottaByte, ///< YiB/YB/YB 2^80/10^24 bytes. 502 UnitLastUnit = UnitYottaByte 503 }; 504 505 /** 506 * This enum chooses what dialect is used for binary units. 507 * 508 * Note: Although JEDEC abuses the metric prefixes and can therefore be 509 * confusing, it has been used to describe *memory* sizes for quite some time 510 * and programs should therefore use either Default, JEDEC, or IEC 60027-2 511 * for memory sizes. 512 * 513 * On the other hand network transmission rates are typically in metric so 514 * Default, Metric, or IEC (which is unambiguous) should be chosen. 515 * 516 * Normally choosing DefaultBinaryDialect is the best option as that uses 517 * the user's selection for units. 518 * 519 * @since 4.4 520 * @see binaryUnitDialect 521 * @see setBinaryUnitDialect 522 */ 523 enum BinaryUnitDialect { 524 DefaultBinaryDialect = -1, ///< Used if no specific preference 525 IECBinaryDialect, ///< KDE Default, KiB, MiB, etc. 2^(10*n) 526 JEDECBinaryDialect, ///< KDE 3.5 default, KB, MB, etc. 2^(10*n) 527 MetricBinaryDialect, ///< SI Units, kB, MB, etc. 10^(3*n) 528 LastBinaryDialect = MetricBinaryDialect 529 }; 530 531 /** 532 * Converts @p size from bytes to the string representation using the 533 * user's default binary unit dialect. The default unit dialect is 534 * IEC 60027-2. 535 * 536 * Example: 537 * formatByteSize(1024) returns "1.0 KiB" by default. 538 * 539 * @param size size in bytes 540 * @return converted size as a string - e.g. 123.4 KiB , 12.0 MiB 541 * @see BinaryUnitDialect 542 * @todo KDE 5: Remove in favor of overload added in KDE 4.4. 543 */ 544 QString formatByteSize(double size) const; 545 546 /** 547 * @since 4.4 548 * 549 * Converts @p size from bytes to the appropriate string representation 550 * using the binary unit dialect @p dialect and the specific units @p specificUnit. 551 * 552 * Example: 553 * formatByteSize(1000, unit, KLocale::UnitKiloByte) returns: 554 * for KLocale::MetricBinaryDialect, "1.0 kB", 555 * for KLocale::IECBinaryDialect, "0.9 KiB", 556 * for KLocale::JEDECBinaryDialect, "0.9 KB". 557 * 558 * @param size size in bytes 559 * @param precision number of places after the decimal point to use. KDE uses 560 * 1 by default so when in doubt use 1. 561 * @param dialect binary unit standard to use. Use DefaultBinaryDialect to 562 * use the localized user selection unless you need to use a specific 563 * unit type (such as displaying a flash memory size in JEDEC). 564 * @param specificUnit specific unit size to use in result. Use 565 * DefaultBinaryUnits to automatically select a unit that will return 566 * a sanely-sized number. 567 * @return converted size as a translated string including the units. 568 * E.g. "1.23 KiB", "2 GB" (JEDEC), "4.2 kB" (Metric). 569 * @see BinaryUnitDialect 570 */ 571 QString formatByteSize(double size, int precision, 572 BinaryUnitDialect dialect = KLocale::DefaultBinaryDialect, 573 BinarySizeUnits specificUnit = KLocale::DefaultBinaryUnits) const; 574 575 /** 576 * Returns the user's configured binary unit dialect. 577 * e.g. if MetricBinaryDialect is returned then the values 578 * configured for how much a set of bytes are worth would 579 * be 10^(3*n) and KB (1000 bytes == 1 KB), in this case. 580 * 581 * Will never return DefaultBinaryDialect. 582 * 583 * @since 4.4 584 * @return User's configured binary unit dialect 585 * @see BinaryUnitDialect 586 */ 587 BinaryUnitDialect binaryUnitDialect() const; 588 589 /** 590 * Sets @p newDialect to be the default dialect for this locale (and only 591 * this locale). Newly created KLocale objects will continue to default 592 * to the user's choice. 593 * 594 * @param newDialect the new dialect to set as default for this locale object. 595 * @since 4.4 596 */ 597 void setBinaryUnitDialect(BinaryUnitDialect newDialect); 598 599 /** 600 * Given a number of milliseconds, converts that to a string containing 601 * the localized equivalent 602 * 603 * e.g. given formatDuration(60000), returns "1.0 minutes" 604 * 605 * @param mSec Time duration in milliseconds 606 * @return converted duration as a string - e.g. "5.5 seconds" "23.0 minutes" 607 */ 608 QString formatDuration(unsigned long mSec) const; 609 610 /** 611 * Given a number of milliseconds, converts that to a pretty string containing 612 * the localized equivalent. 613 * 614 * e.g. given prettyFormatDuration(60001) returns "1 minute" 615 * given prettyFormatDuration(62005) returns "1 minute and 2 seconds" 616 * given prettyFormatDuration(90060000) returns "1 day and 1 hour" 617 * 618 * @param mSec Time duration in milliseconds 619 * @return converted duration as a string. 620 * Units not interesting to the user, for example seconds or minutes when the first 621 * unit is day, are not returned because they are irrelevant. The same applies for 622 * seconds when the first unit is hour. 623 * @since 4.2 624 */ 625 QString prettyFormatDuration(unsigned long mSec) const; 626 627 /** 628 * @deprecated 629 * 630 * Use this to determine whether nouns are declined in 631 * locale's language. This property should remain 632 * read-only (no setter function) 633 * 634 * @return If nouns are declined 635 */ 636 KDELIBS4SUPPORT_DEPRECATED bool nounDeclension() const; 637 638 /** 639 * @since 4.6 640 * 641 * Available Calendar Systems 642 * 643 * @see setCalendarSystem() 644 * @see calendarSystem() 645 */ 646 enum CalendarSystem { 647 GregorianCalendar = 1, /**< KDE Default, proleptic Gregorian Calendar as used by QDate */ 648 //BahaiCalendar = 2, /**< Baha'i Calendar */ 649 //BuddhistLunarCalendar = 3, /**< Buddhist Lunar Calendar*/ 650 //ChineseCalendar = 4, /**< Chinese Calendar */ 651 CopticCalendar = 5, /**< Coptic Calendar as used Coptic Church and some parts of Egypt */ 652 EthiopianCalendar = 6, /**< Ethiopian Calendar, aka Ethiopic Calendar */ 653 //EthiopianAmeteAlemCalendar = 7, /**< Ethiopian Amete Alem version, aka Ethiopic Amete Alem */ 654 HebrewCalendar = 9, /**< Hebrew Calendar, aka Jewish Calendar */ 655 //HinduCalendar = 10, /**< Hindu Lunar Calendar */ 656 //IslamicLunarCalendar = 11, /**< Islamic Lunar Calendar */ 657 IslamicCivilCalendar = 12, /**< Islamic Civil Calendar, aka Hijri, not the Lunar Calendar */ 658 //IslamicUmAlQuraCalendar = 13, /**< Islamic Lunar Calendar, Um Al Qura varient used in Saudi Arabia */ 659 IndianNationalCalendar = 14, /**< Indian National Calendar, not the Lunar Calendar */ 660 //Iso8601Calendar = 15, /**< ISO 8601 Standard Calendar */ 661 JalaliCalendar = 16, /**< Jalali Calendar, aka Persian or Iranian, also used in Afghanistan */ 662 //JalaliBirashkCalendar = 17, /**< Jalali Calendar, Birashk Algorythm variant */ 663 //Jalali33YearCalendar = 18, /**< Jalali Calendar, 33 Year cycle variant */ 664 JapaneseCalendar = 19, /**< Japanese Calendar, Gregorian calculation using Japanese Era (Nengô) */ 665 //JucheCalendar = 20, /**< Juche Calendar, used in North Korea */ 666 JulianCalendar = 21, /**< Julian Calendar, as used in Orthodox Churches */ 667 MinguoCalendar = 22, /**< Minguo Calendar, aka ROC, Republic of China or Taiwanese */ 668 ThaiCalendar = 23, /**< Thai Calendar, aka Buddhist or Thai Buddhist */ 669 670 QDateCalendar = GregorianCalendar /**< @deprecated Alias for GregorianCalendar */ 671 }; 672 673 /** 674 * @since 4.6 675 * 676 * System used for Week Numbers 677 * 678 * @see setWeekNumberSystem() 679 * @see weekNumberSystem() 680 */ 681 enum WeekNumberSystem { 682 DefaultWeekNumber = -1, /**< The system locale default */ 683 IsoWeekNumber = 0, /**< ISO Week Number */ 684 FirstFullWeek = 1, /**< Week 1 starts on the first Week Start Day in year ends after 7 days */ 685 FirstPartialWeek = 2, /**< Week 1 starts Jan 1st ends day before first Week Start Day in year */ 686 SimpleWeek = 3 /**< Week 1 starts Jan 1st ends after 7 days */ 687 }; 688 689 /** 690 * @since 4.4 691 * 692 * Standard used for Date Time Format String 693 */ 694 enum DateTimeFormatStandard { 695 KdeFormat, /**< KDE Standard */ 696 PosixFormat, /**< POSIX Standard */ 697 UnicodeFormat /**< UNICODE Standard (Qt/Java/OSX/Windows) */ 698 }; 699 700 /** 701 * @since 4.6 702 * 703 * Mode to use when parsing a Date Time input string 704 */ 705 enum DateTimeParseMode { 706 LiberalParsing /**< Parse Date/Time liberally. So long as the 707 input string contains at least a reconizable 708 month and day the input will be accepted. */ 709 //ModerateParsing, /**< Parse Date/Time with modeate tolerance. 710 // The date components in the format must all 711 // occur in the input and in the same order, 712 // but the spacing and the componants themselves 713 // may vary from the strict format. */ 714 //StrictParsing /**< Parse Date/Time strictly to the format. */ 715 }; 716 717 /** 718 * @since 4.6 719 * 720 * The various Components that make up a Date / Time 721 * In the future the Components may be combined as flags for dynamic 722 * generation of Date Formats. 723 * 724 * @see KCalendarSystem 725 * @see KLocalizedDate 726 * @see DateTimeComponentFormat 727 */ 728 enum DateTimeComponent { 729 Year = 0x1, /**< The Year portion of a date, may be number or name */ 730 YearName = 0x2, /**< The Year Name portion of a date */ 731 Month = 0x4, /**< The Month portion of a date, may be number or name */ 732 MonthName = 0x8, /**< The Month Name portion of a date */ 733 Day = 0x10, /**< The Day portion of a date, may be number or name */ 734 DayName = 0x20, /**< The Day Name portion of a date */ 735 JulianDay = 0x40, /**< The Julian Day of a date */ 736 EraName = 0x80, /**< The Era Name portion of a date */ 737 EraYear = 0x100, /**< The Era and Year portion of a date */ 738 YearInEra = 0x200, /**< The Year In Era portion of a date */ 739 DayOfYear = 0x400, /**< The Day Of Year portion of a date, may be number or name */ 740 DayOfYearName = 0x800, /**< The Day Of Year Name portion of a date */ 741 DayOfWeek = 0x1000, /**< The Day Of Week / Weekday portion of a date, may be number or name */ 742 DayOfWeekName = 0x2000, /**< The Day Of Week Name / Weekday Name portion of a date */ 743 Week = 0x4000, /**< The Week Number portion of a date */ 744 WeekYear = 0x8000, /**< The Week Year portion of a date */ 745 MonthsInYear = 0x10000, /**< The Months In Year portion of a date */ 746 WeeksInYear = 0x20000, /**< The Weeks In Year portion of a date */ 747 DaysInYear = 0x40000, /**< The Days In Year portion of a date */ 748 DaysInMonth = 0x80000, /**< The Days In Month portion of a date */ 749 DaysInWeek = 0x100000, /**< The Days In Week portion of a date */ 750 Hour = 0x200000, /**< The Hours portion of a date */ 751 Minute = 0x400000, /**< The Minutes portion of a date */ 752 Second = 0x800000, /**< The Seconds portion of a date */ 753 Millisecond = 0x1000000, /**< The Milliseconds portion of a date */ 754 DayPeriod = 0x2000000, /**< The Day Period portion of a date, e.g. AM/PM */ 755 DayPeriodHour = 0x4000000, /**< The Day Period Hour portion of a date */ 756 Timezone = 0x8000000, /**< The Time Zone portion of a date, may be offset or name */ 757 TimezoneName = 0x10000000, /**< The Time Zone Name portion of a date */ 758 UnixTime = 0x20000000 /**< The UNIX Time portion of a date */ 759 }; 760 Q_DECLARE_FLAGS(DateTimeComponents, DateTimeComponent) 761 762 /** 763 * @since 4.6 764 * 765 * Format used for individual Date/Time Components when converted to/from a string 766 * Largely equivalent to the UNICODE CLDR format width definitions 1..5 767 * 768 * @see DateTimeComponentFormat 769 */ 770 enum DateTimeComponentFormat { 771 DefaultComponentFormat = -1, /**< The system locale default for the componant */ 772 ShortNumber = 0, /**< Number at its natural width, e.g. 2 for the 2nd*/ 773 LongNumber, /**< Number padded to a required width, e.g. 02 for the 2nd*/ 774 //OrdinalNumber /**< Ordinal number format, e.g. "2nd" for the 2nd */ 775 NarrowName = 3, /**< Narrow text format, may not be unique, e.g. M for Monday */ 776 ShortName, /**< Short text format, e.g. Mon for Monday */ 777 LongName /**< Long text format, e.g. Monday for Monday */ 778 }; 779 780 /** 781 * Format for date string. 782 */ 783 enum DateFormat { 784 ShortDate, /**< Locale Short date format, e.g. 08-04-2007 */ 785 LongDate, /**< Locale Long date format, e.g. Sunday 08 April 2007 */ 786 FancyShortDate, /**< Same as ShortDate for dates a week or more ago. For more 787 recent dates, it is represented as Today, Yesterday, or 788 the weekday name. */ 789 FancyLongDate, /**< Same as LongDate for dates a week or more ago. For more 790 recent dates, it is represented as Today, Yesterday, or 791 the weekday name. */ 792 IsoDate, /**< ISO-8601 Date format YYYY-MM-DD, e.g. 2009-12-31 */ 793 IsoWeekDate, /**< ISO-8601 Week Date format YYYY-Www-D, e.g. 2009-W01-1 */ 794 IsoOrdinalDate /**< ISO-8601 Ordinal Date format YYYY-DDD, e.g. 2009-001 */ 795 }; 796 797 /** 798 * Returns a string formatted to the current locale's conventions 799 * regarding dates. 800 * 801 * @param date the date to be formatted 802 * @param format category of date format to use 803 * 804 * @return the date as a string 805 */ 806 QString formatDate(const QDate &date, DateFormat format = LongDate) const; 807 808 /** 809 * Returns a string formatted to the current locale's conventions 810 * regarding both date and time. 811 * 812 * @param dateTime the date and time to be formatted 813 * @param format category of date format to use 814 * @param includeSecs if @c true, the string will include the seconds part 815 * of the time; otherwise, the seconds will be omitted 816 * 817 * @return the date and time as a string 818 */ 819 QString formatDateTime(const QDateTime &dateTime, DateFormat format = ShortDate, 820 bool includeSecs = false) const; 821 822 /** 823 * Options for formatting date-time values. 824 */ 825 enum DateTimeFormatOption { 826 TimeZone = 0x01, /**< Include a time zone string */ 827 Seconds = 0x02 /**< Include the seconds value */ 828 }; 829 Q_DECLARE_FLAGS(DateTimeFormatOptions, DateTimeFormatOption) 830 831 /** 832 * Returns a string formatted to the current locale's conventions 833 * regarding both date and time. 834 * 835 * @param dateTime the date and time to be formatted 836 * @param format category of date format to use 837 * @param options additional output options 838 * 839 * @return The date and time as a string 840 */ 841 QString formatDateTime(const KDateTime &dateTime, DateFormat format = ShortDate, 842 DateTimeFormatOptions options = {}) const; 843 844 /** 845 * Use this to determine whether in dates a possessive form of month 846 * name is preferred ("of January" rather than "January") 847 * 848 * @return If possessive form should be used 849 */ 850 bool dateMonthNamePossessive() const; 851 852 /** 853 * @deprecated replaced by formatLocaleTime() 854 * 855 * Returns a string formatted to the current locale's conventions 856 * regarding times. 857 * 858 * @param pTime The time to be formatted. 859 * @param includeSecs if true, seconds are included in the output, 860 * otherwise only hours and minutes are formatted. 861 * @param isDuration if true, the given time is a duration, not a clock time. 862 * This means "am/pm" shouldn't be displayed. 863 * 864 * @return The time as a string 865 */ 866 QString formatTime(const QTime &pTime, bool includeSecs = false, bool isDuration = false) const; 867 868 /** 869 * @since 4.4 870 * 871 * Format flags for readLocaleTime() and formatLocaleTime() 872 */ 873 enum TimeFormatOption { 874 TimeDefault = 0x0, ///< Default formatting using seconds and the format 875 ///< as specified by the locale. 876 TimeWithoutSeconds = 0x1, ///< Exclude the seconds part of the time from display 877 TimeWithoutAmPm = 0x2, ///< Read/format time string without am/pm suffix but 878 ///< keep the 12/24h format as specified by locale time 879 ///< format, eg. "07.33.05" instead of "07.33.05 pm" for 880 ///< time format "%I.%M.%S %p". 881 TimeDuration = 0x6, ///< Read/format time string as duration. This will strip 882 ///< the am/pm suffix and read/format times with an hour 883 ///< value of 0-23 hours, eg. "19.33.05" instead of 884 ///< "07.33.05 pm" for time format "%I.%M.%S %p". 885 ///< This automatically implies @c TimeWithoutAmPm. 886 TimeFoldHours = 0xE ///< Read/format time string as duration. This will not 887 ///< not output the hours part of the duration but will 888 ///< add the hours (times sixty) to the number of minutes, 889 ///< eg. "70.23" instead of "01.10.23" for time format 890 ///< "%I.%M.%S %p". 891 }; 892 Q_DECLARE_FLAGS(TimeFormatOptions, TimeFormatOption) 893 894 /** 895 * @since 4.4 896 * 897 * Returns a string formatted to the current locale's conventions 898 * regarding times. 899 * 900 * @param pTime the time to be formatted 901 * @param options format option to use when formatting the time 902 * @return The time as a string 903 */ 904 QString formatLocaleTime(const QTime &pTime, 905 TimeFormatOptions options = KLocale::TimeDefault) const; 906 907 /** 908 * @since 4.3 909 * 910 * Returns the identifier of the digit set used to display dates and time. 911 * 912 * @return the digit set identifier 913 * @see DigitSet 914 * @see digitSetToName 915 */ 916 DigitSet dateTimeDigitSet() const; 917 918 /** 919 * Use this to determine if the user wants a 12 hour clock. 920 * 921 * @return If the user wants 12h clock 922 * @deprecated. A possible equivalent would be: 923 * @code 924 * static bool use12Clock() 925 * { 926 * const QString str = QLocale().timeFormat(); 927 * // 'A' or 'a' means am/pm is shown (and then 'h' uses 12-hour format) 928 * // but 'H' forces a 24-hour format anyway, even with am/pm shown. 929 * return str.contains(QLatin1Char('a'), Qt::CaseInsensitive) && !str.contains(QLatin1Char('H')); 930 * } 931 * @endcode 932 */ 933 bool use12Clock() const; 934 935 /** 936 * @since 4.6 937 * 938 * Returns the Day Period matching the time given 939 * 940 * @param time the time to return the day period for 941 * @param format the format to return teh day period in 942 * @return the Day Period for the given time 943 */ 944 QString dayPeriodText(const QTime &time, DateTimeComponentFormat format = DefaultComponentFormat) const; 945 946 /** 947 * Use this to determine which day is the first day of the week. 948 * 949 * @return an integer (Monday=1..Sunday=7) 950 */ 951 int weekStartDay() const; 952 953 /** 954 * Use this to determine which day is the first working day of the week. 955 * 956 * @since 4.2 957 * @return an integer (Monday=1..Sunday=7) 958 */ 959 int workingWeekStartDay() const; 960 961 /** 962 * Use this to determine which day is the last working day of the week. 963 * 964 * @since 4.2 965 * @return an integer (Monday=1..Sunday=7) 966 */ 967 int workingWeekEndDay() const; 968 969 /** 970 * Use this to determine which day is reserved for religious observance 971 * 972 * @since 4.2 973 * @return day number (None = 0, Monday = 1, ..., Sunday = 7) 974 */ 975 int weekDayOfPray() const; 976 977 /** 978 * Returns a pointer to the calendar system object. 979 * 980 * @return the current calendar system instance 981 */ 982 const KCalendarSystem *calendar() const; 983 984 /** 985 * @deprecated use calendarSystem() instead 986 * 987 * Returns the name of the calendar system that is currently being 988 * used by the system. 989 * 990 * @see calendarSystem() 991 * @return the name of the calendar system 992 */ 993 KDELIBS4SUPPORT_DEPRECATED QString calendarType() const; 994 995 /** 996 * @since 4.6 997 * 998 * Returns the type of Calendar System used in this Locale 999 * 1000 * @see KLocale::CalendarSystem 1001 * @see KCalendarSystem 1002 * @return the type of Calendar System 1003 */ 1004 KLocale::CalendarSystem calendarSystem() const; 1005 1006 /** 1007 * @deprecated use setCalendarSystem() instead 1008 * 1009 * Changes the current calendar system to the calendar specified. 1010 * If the calendar system specified is not found, gregorian will be used. 1011 * 1012 * @see setCalendarSystem() 1013 * @param calendarType the name of the calendar type 1014 */ 1015 KDELIBS4SUPPORT_DEPRECATED void setCalendar(const QString &calendarType); 1016 1017 /** 1018 * @since 4.6 1019 * 1020 * Sets the type of Calendar System to use in this Locale 1021 * 1022 * @see KLocale::CalendarSystem 1023 * @see KCalendarSystem 1024 * @param calendarSystem the Calendar System to use 1025 */ 1026 void setCalendarSystem(KLocale::CalendarSystem calendarSystem); 1027 1028 /** 1029 * @since 4.6 1030 * 1031 * Sets the type of Week Number System to use in this Locale 1032 * 1033 * @see Klocale::WeekNumberSystem 1034 * @see weekNumberSystem() 1035 * @param weekNumberSystem the Week Number System to use 1036 */ 1037 void setWeekNumberSystem(KLocale::WeekNumberSystem weekNumberSystem); 1038 1039 /** 1040 * @since 4.6 1041 * 1042 * Returns the type of Week Number System used in this Locale 1043 * 1044 * @see Klocale::WeekNumberSystem 1045 * @see setWeekNumberSystem() 1046 * @returns the Week Number System used 1047 */ 1048 KLocale::WeekNumberSystem weekNumberSystem(); 1049 1050 /** 1051 * @since 4.7 1052 * 1053 * Returns the type of Week Number System used in this Locale 1054 * 1055 * @see Klocale::WeekNumberSystem 1056 * @see setWeekNumberSystem() 1057 * @returns the Week Number System used 1058 */ 1059 KLocale::WeekNumberSystem weekNumberSystem() const; 1060 1061 /** 1062 * Converts a localized monetary string to a double. 1063 * 1064 * @param numStr the string we want to convert. 1065 * @param ok the boolean that is set to false if it's not a number. 1066 * If @p ok is 0, it will be ignored 1067 * 1068 * @return The string converted to a double 1069 */ 1070 double readMoney(const QString &numStr, bool *ok = nullptr) const; 1071 1072 /** 1073 * Converts a localized numeric string to a double. 1074 * 1075 * @param numStr the string we want to convert. 1076 * @param ok the boolean that is set to false if it's not a number. 1077 * If @p ok is 0, it will be ignored 1078 * 1079 * @return The string converted to a double 1080 */ 1081 double readNumber(const QString &numStr, bool *ok = nullptr) const; 1082 1083 /** 1084 * Converts a localized date string to a QDate. This method will try all 1085 * ReadDateFlag formats in preferred order to read a valid date. 1086 * 1087 * The bool pointed by ok will be invalid if the date entered was not valid. 1088 * 1089 * @param str the string we want to convert. 1090 * @param ok the boolean that is set to false if it's not a valid date. 1091 * If @p ok is 0, it will be ignored 1092 * 1093 * @return The string converted to a QDate 1094 * @see KCalendarSystem::readDate() 1095 */ 1096 QDate readDate(const QString &str, bool *ok = nullptr) const; 1097 1098 /** 1099 * Converts a localized date string to a QDate, using the specified format. 1100 * You will usually not want to use this method. 1101 * @see KCalendarSystem::readDate() 1102 */ 1103 QDate readDate(const QString &intstr, const QString &fmt, bool *ok = nullptr) const; 1104 1105 /** 1106 * Flags for readDate() 1107 */ 1108 enum ReadDateFlags { 1109 NormalFormat = 1, /**< Only accept a date string in 1110 the locale LongDate format */ 1111 ShortFormat = 2, /**< Only accept a date string in 1112 the locale ShortDate format */ 1113 IsoFormat = 4, /**< Only accept a date string in 1114 ISO date format (YYYY-MM-DD) */ 1115 IsoWeekFormat = 8, /**< Only accept a date string in 1116 ISO Week date format (YYYY-Www-D) */ 1117 IsoOrdinalFormat = 16 /**< Only accept a date string in 1118 ISO Week date format (YYYY-DDD) */ 1119 }; 1120 1121 /** 1122 * Converts a localized date string to a QDate. 1123 * This method is stricter than readDate(str,&ok): it will only accept 1124 * a date in a specific format, depending on @p flags. 1125 * 1126 * @param str the string we want to convert. 1127 * @param flags what format the the date string will be in 1128 * @param ok the boolean that is set to false if it's not a valid date. 1129 * If @p ok is 0, it will be ignored 1130 * 1131 * @return The string converted to a QDate 1132 * @see KCalendarSystem::readDate() 1133 */ 1134 QDate readDate(const QString &str, ReadDateFlags flags, bool *ok = nullptr) const; 1135 1136 /** 1137 * Converts a localized time string to a QTime. 1138 * This method will try to parse it with seconds, then without seconds. 1139 * The bool pointed to by @p ok will be set to false if the time entered was 1140 * not valid. 1141 * 1142 * @param str the string we want to convert. 1143 * @param ok the boolean that is set to false if it's not a valid time. 1144 * If @p ok is 0, it will be ignored 1145 * 1146 * @return The string converted to a QTime 1147 */ 1148 QTime readTime(const QString &str, bool *ok = nullptr) const; 1149 1150 /** 1151 * Flags for the old version of readTime() 1152 * 1153 * @deprecated replaced by TimeFormatOptions 1154 */ 1155 enum ReadTimeFlags { 1156 WithSeconds = 0, ///< Only accept a time string with seconds. Default (no flag set) 1157 WithoutSeconds = 1 ///< Only accept a time string without seconds. 1158 }; // (maybe use this enum as a bitfield, if adding independent features?) 1159 1160 /** 1161 * @deprecated replaced readLocaleTime() 1162 * 1163 * Converts a localized time string to a QTime. 1164 * This method is stricter than readTime(str,&ok): it will either accept 1165 * a time with seconds or a time without seconds. 1166 * Use this method when the format is known by the application. 1167 * 1168 * @param str the string we want to convert. 1169 * @param flags whether the time string is expected to contain seconds or not. 1170 * @param ok the boolean that is set to false if it's not a valid time. 1171 * If @p ok is 0, it will be ignored 1172 * 1173 * @return The string converted to a QTime 1174 */ 1175 QTime readTime(const QString &str, ReadTimeFlags flags, bool *ok = nullptr) const; 1176 1177 /** 1178 * Additional processing options for readLocaleTime(). 1179 * 1180 * @remarks This is currently used as an enum but declared as a flag 1181 * to be extensible 1182 */ 1183 enum TimeProcessingOption { 1184 ProcessStrict = 0x1, ///< Process time in a strict manner, ie. 1185 ///< a read time string has to exactly match 1186 ///< the defined time format. 1187 ProcessNonStrict = 0x2 ///< Process time in a lax manner, ie. 1188 ///< allow spaces in the time-format to be 1189 ///< left out when entering a time string. 1190 }; 1191 Q_DECLARE_FLAGS(TimeProcessingOptions, TimeProcessingOption) 1192 1193 /** 1194 * @since 4.4 1195 * 1196 * Converts a localized time string to a QTime. 1197 * This method is stricter than readTime(str, &ok) in that it will either 1198 * accept a time with seconds or a time without seconds. 1199 * 1200 * @param str the string we want to convert 1201 * @param ok the boolean that is set to false if it's not a valid time. 1202 * If @p ok is 0, it will be ignored. 1203 * @param options format option to apply when formatting the time 1204 * @param processing if set to @c ProcessStrict, checking will be strict 1205 * and the read time string has to have the exact time format 1206 * specified. If set to @c ProcessNonStrict processing the time 1207 * is lax and spaces in the time string can be left out. 1208 * 1209 * @return The string converted to a QTime 1210 */ 1211 QTime readLocaleTime(const QString &str, bool *ok = nullptr, 1212 TimeFormatOptions options = KLocale::TimeDefault, 1213 TimeProcessingOptions processing = ProcessNonStrict) const; 1214 1215 /** 1216 * Returns the language code used by this object. 1217 * 1218 * Use languageCodeToName(language) to get human readable, localized 1219 * language name. 1220 * 1221 * @return the currently used language code 1222 * 1223 * @see languageCodeToName 1224 */ 1225 QString language() const; 1226 1227 /** 1228 * Returns the country code of the country where the user lives. 1229 * 1230 * The returned code complies with the ISO 3166-1 alpha-2 standard, 1231 * except by KDE convention it is returned in lowercase whereas the 1232 * official standard is uppercase. 1233 * See http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for details. 1234 * 1235 * defaultCountry() is returned by default, if no other available, 1236 * this will always be uppercase 'C'. 1237 * 1238 * Use countryCodeToName(country) to get human readable, localized 1239 * country names. 1240 * 1241 * @return the country code for the user 1242 * 1243 * @see countryCodeToName 1244 */ 1245 QString country() const; 1246 1247 /** 1248 * @since 4.6 1249 * 1250 * Returns the Country Division Code of the Country where the user lives. 1251 * When no value is set, then the Country Code will be returned. 1252 * 1253 * The returned code complies with the ISO 3166-2 standard. 1254 * See http://en.wikipedia.org/wiki/ISO_3166-2 for details. 1255 * 1256 * Note that unlike country() this method will return the correct case, 1257 * i.e. normally uppercase.. 1258 * 1259 * In KDE 4.6 it is the apps responsibility to obtain a translation for the 1260 * code, translation and other services will be priovided in KDE 4.7. 1261 * 1262 * @return the Country Division Code for the user 1263 * @see setCountryDivisionCode 1264 */ 1265 QString countryDivisionCode() const; 1266 1267 /** 1268 * Returns the language codes selected by user, ordered by decreasing 1269 * priority. 1270 * 1271 * Use languageCodeToName(language) to get human readable, localized 1272 * language name. 1273 * 1274 * @return list of language codes 1275 * 1276 * @see languageCodeToName 1277 */ 1278 QStringList languageList() const; 1279 1280 /** 1281 * @since 4.4 1282 * 1283 * Returns the ISO Currency Codes used in the locale, ordered by decreasing 1284 * priority. 1285 * 1286 * Use KCurrency::currencyCodeToName(currencyCode) to get human readable, 1287 * localized language name. 1288 * 1289 * @return list of ISO Currency Codes 1290 * 1291 * @see currencyCodeToName 1292 */ 1293 QStringList currencyCodeList() const; 1294 1295 /** 1296 * Returns the user's preferred encoding. 1297 * 1298 * @return The name of the preferred encoding 1299 * 1300 * @see codecForEncoding 1301 * @see encodingMib 1302 */ 1303 const QByteArray encoding() const; 1304 1305 /** 1306 * Returns the user's preferred encoding. 1307 * 1308 * @return The Mib of the preferred encoding 1309 * 1310 * @see encoding 1311 * @see codecForEncoding 1312 */ 1313 int encodingMib() const; 1314 1315 /** 1316 * Returns the user's preferred encoding. Should never be NULL. 1317 * 1318 * @return The codec for the preferred encoding 1319 * 1320 * @see encoding 1321 * @see encodingMib 1322 */ 1323 QTextCodec *codecForEncoding() const; 1324 1325 /** 1326 * Returns the file encoding. 1327 * 1328 * @return The Mib of the file encoding 1329 * 1330 * @see QFile::encodeName 1331 * @see QFile::decodeName 1332 */ 1333 int fileEncodingMib() const; 1334 1335 /** 1336 * Changes the current date format. 1337 * 1338 * The format of the date is a string which contains variables that will 1339 * be replaced: 1340 * @li %Y with the whole year (e.g. "2004" for "2004") 1341 * @li %y with the lower 2 digits of the year (e.g. "04" for "2004") 1342 * @li %n with the month (January="1", December="12") 1343 * @li %m with the month with two digits (January="01", December="12") 1344 * @li %e with the day of the month (e.g. "1" on the first of march) 1345 * @li %d with the day of the month with two digits (e.g. "01" on the first of march) 1346 * @li %b with the short form of the month (e.g. "Jan" for January) 1347 * @li %B with the long form of the month (e.g. "January") 1348 * @li %a with the short form of the weekday (e.g. "Wed" for Wednesday) 1349 * @li %A with the long form of the weekday (e.g. "Wednesday" for Wednesday) 1350 * 1351 * Everything else in the format string will be taken as is. 1352 * For example, March 20th 1989 with the format "%y:%m:%d" results 1353 * in "89:03:20". 1354 * 1355 * @param format The new date format 1356 */ 1357 void setDateFormat(const QString &format); 1358 1359 /** 1360 * Changes the current short date format. 1361 * 1362 * The format of the date is a string which contains variables that will 1363 * be replaced: 1364 * @li %Y with the whole year (e.g. "1984" for "1984") 1365 * @li %y with the lower 2 digits of the year (e.g. "84" for "1984") 1366 * @li %n with the month (January="1", December="12") 1367 * @li %m with the month with two digits (January="01", December="12") 1368 * @li %e with the day of the month (e.g. "1" on the first of march) 1369 * @li %d with the day of the month with two digits(e.g. "01" on the first of march) 1370 * @li %b with the short form of the month (e.g. "Jan" for January) 1371 * @li %B with the long form of the month (e.g. "January") 1372 * @li %a with the short form of the weekday (e.g. "Wed" for Wednesday) 1373 * @li %A with the long form of the weekday (e.g. "Wednesday" for Wednesday) 1374 * 1375 * Everything else in the format string will be taken as is. 1376 * For example, March 20th 1989 with the format "%y:%m:%d" results 1377 * in "89:03:20". 1378 * 1379 * @param format The new short date format 1380 */ 1381 void setDateFormatShort(const QString &format); 1382 1383 /** 1384 * Changes the form of month name used in dates. 1385 * 1386 * @param possessive True if possessive forms should be used 1387 */ 1388 void setDateMonthNamePossessive(bool possessive); 1389 1390 /** 1391 * Changes the current time format. 1392 * 1393 * The format of the time is string a which contains variables that will 1394 * be replaced: 1395 * @li %H with the hour in 24h format and 2 digits (e.g. 5pm is "17", 5am is "05") 1396 * @li %k with the hour in 24h format and one digits (e.g. 5pm is "17", 5am is "5") 1397 * @li %I with the hour in 12h format and 2 digits (e.g. 5pm is "05", 5am is "05") 1398 * @li %l with the hour in 12h format and one digits (e.g. 5pm is "5", 5am is "5") 1399 * @li %M with the minute with 2 digits (e.g. the minute of 07:02:09 is "02") 1400 * @li %S with the seconds with 2 digits (e.g. the minute of 07:02:09 is "09") 1401 * @li %p with pm or am (e.g. 17.00 is "pm", 05.00 is "am") 1402 * 1403 * Everything else in the format string will be taken as is. 1404 * For example, 5.23pm with the format "%H:%M" results 1405 * in "17:23". 1406 * 1407 * @param format The new time format 1408 */ 1409 void setTimeFormat(const QString &format); 1410 1411 /** 1412 * @since 4.3 1413 * 1414 * Set digit characters used to display dates and time. 1415 * 1416 * @param digitSet the digit set identifier 1417 * @see DigitSet 1418 */ 1419 void setDateTimeDigitSet(DigitSet digitSet); 1420 1421 /** 1422 * Changes how KLocale defines the first day in week. 1423 * 1424 * @param day first day of the week (Monday=1..Sunday=7) as integer 1425 */ 1426 void setWeekStartDay(int day); 1427 1428 /** 1429 * Changes how KLocale defines the first working day in week. 1430 * 1431 * @since 4.2 1432 * @param day first working day of the week (Monday=1..Sunday=7) as integer 1433 */ 1434 void setWorkingWeekStartDay(int day); 1435 1436 /** 1437 * Changes how KLocale defines the last working day in week. 1438 * 1439 * @since 4.2 1440 * @param day last working day of the week (Monday=1..Sunday=7) as integer 1441 */ 1442 void setWorkingWeekEndDay(int day); 1443 1444 /** 1445 * Changes how KLocale defines the day reserved for religious observance. 1446 * 1447 * @since 4.2 1448 * @param day day of the week for religious observance (None=0,Monday=1..Sunday=7) as integer 1449 */ 1450 void setWeekDayOfPray(int day); 1451 1452 /** 1453 * Returns the currently selected date format. 1454 * 1455 * @return Current date format. 1456 * @see setDateFormat() 1457 */ 1458 QString dateFormat() const; 1459 1460 /** 1461 * Returns the currently selected short date format. 1462 * 1463 * @return Current short date format. 1464 * @see setDateFormatShort() 1465 */ 1466 QString dateFormatShort() const; 1467 1468 /** 1469 * Returns the currently selected time format. 1470 * 1471 * @return Current time format. 1472 * @see setTimeFormat() 1473 */ 1474 QString timeFormat() const; 1475 1476 /** 1477 * Changes the symbol used to identify the decimal pointer. 1478 * 1479 * @param symbol The new decimal symbol. 1480 */ 1481 void setDecimalSymbol(const QString &symbol); 1482 1483 /** 1484 * Changes the separator used to group digits when formating numbers. 1485 * 1486 * @param separator The new thousands separator. 1487 */ 1488 void setThousandsSeparator(const QString &separator); 1489 1490 /** 1491 * Changes the sign used to identify a positive number. Normally this is 1492 * left blank. 1493 * 1494 * @param sign Sign used for positive numbers. 1495 */ 1496 void setPositiveSign(const QString &sign); 1497 1498 /** 1499 * Changes the sign used to identify a negative number. 1500 * 1501 * @param sign Sign used for negative numbers. 1502 */ 1503 void setNegativeSign(const QString &sign); 1504 1505 /** 1506 * @since 4.3 1507 * 1508 * Changes the set of digit characters used to display numbers. 1509 * 1510 * @param digitSet the digit set identifier 1511 * @see DigitSet 1512 */ 1513 void setDigitSet(DigitSet digitSet); 1514 1515 /** 1516 * Changes the sign position used for positive monetary values. 1517 * 1518 * @param signpos The new sign position 1519 */ 1520 void setPositiveMonetarySignPosition(SignPosition signpos); 1521 1522 /** 1523 * Changes the sign position used for negative monetary values. 1524 * 1525 * @param signpos The new sign position 1526 */ 1527 void setNegativeMonetarySignPosition(SignPosition signpos); 1528 1529 /** 1530 * Changes the position where the currency symbol should be printed for 1531 * positive monetary values. 1532 * 1533 * @param prefix True if the currency symbol should be prefixed instead of 1534 * postfixed 1535 */ 1536 void setPositivePrefixCurrencySymbol(bool prefix); 1537 1538 /** 1539 * Changes the position where the currency symbol should be printed for 1540 * negative monetary values. 1541 * 1542 * @param prefix True if the currency symbol should be prefixed instead of 1543 * postfixed 1544 */ 1545 void setNegativePrefixCurrencySymbol(bool prefix); 1546 1547 /** 1548 * @deprecated use setDecimalPlaces() or setMonetaryDecimalPlaces() 1549 * 1550 * Changes the number of digits used when formating numbers. 1551 * 1552 * @param digits The default number of digits to use. 1553 */ 1554 KDELIBS4SUPPORT_DEPRECATED void setFracDigits(int digits); 1555 1556 /** 1557 * @since 4.4 1558 * 1559 * Changes the number of decimal places used when formating numbers. 1560 * 1561 * @param digits The default number of digits to use. 1562 */ 1563 void setDecimalPlaces(int digits); 1564 1565 /** 1566 * @since 4.4 1567 * 1568 * Changes the number of decimal places used when formating money. 1569 * 1570 * @param digits The default number of digits to use. 1571 */ 1572 void setMonetaryDecimalPlaces(int digits); 1573 1574 /** 1575 * Changes the separator used to group digits when formating monetary values. 1576 * 1577 * @param separator The new thousands separator. 1578 */ 1579 void setMonetaryThousandsSeparator(const QString &separator); 1580 1581 /** 1582 * Changes the symbol used to identify the decimal pointer for monetary 1583 * values. 1584 * 1585 * @param symbol The new decimal symbol. 1586 */ 1587 void setMonetaryDecimalSymbol(const QString &symbol); 1588 1589 /** 1590 * @since 4.4 1591 * 1592 * Changes the current ISO Currency Code. 1593 * 1594 * @param newCurrencyCode The new Currency Code 1595 */ 1596 void setCurrencyCode(const QString &newCurrencyCode); 1597 1598 /** 1599 * Changes the current currency symbol. 1600 * 1601 * This symbol should be consistant with the selected Currency Code 1602 * 1603 * @param symbol The new currency symbol 1604 * @see currencyCode, KCurrency::currencySymbols 1605 */ 1606 void setCurrencySymbol(const QString &symbol); 1607 1608 /** 1609 * @since 4.3 1610 * 1611 * Set digit characters used to display monetary values. 1612 * 1613 * @param digitSet the digit set identifier 1614 * @see DigitSet 1615 */ 1616 void setMonetaryDigitSet(DigitSet digitSet); 1617 1618 /** 1619 * Returns the preferred page size for printing. 1620 * 1621 * @return The preferred page size, cast it to QPrinter::PaperSize 1622 */ 1623 int pageSize() const; 1624 1625 /** 1626 * Changes the preferred page size when printing. 1627 * 1628 * @param paperFormat the new preferred page size in the format QPrinter::PaperSize 1629 */ 1630 void setPageSize(int paperFormat); 1631 1632 /** 1633 * The Metric system will give you information in mm, while the 1634 * Imperial system will give you information in inches. 1635 */ 1636 enum MeasureSystem { 1637 Metric, ///< Metric system (used e.g. in Europe) 1638 Imperial ///< Imperial system (used e.g. in the United States) 1639 }; 1640 1641 /** 1642 * Returns which measuring system we use. 1643 * 1644 * @return The preferred measuring system 1645 */ 1646 MeasureSystem measureSystem() const; 1647 1648 /** 1649 * Changes the preferred measuring system. 1650 * 1651 * @return value The preferred measuring system 1652 */ 1653 void setMeasureSystem(MeasureSystem value); 1654 1655 /** 1656 * Provides list of all known language codes. 1657 * 1658 * Use languageCodeToName(language) to get human readable, localized 1659 * language names. 1660 * 1661 * @return list of all language codes 1662 * 1663 * @see languageCodeToName 1664 * @see installedLanguages 1665 */ 1666 QStringList allLanguagesList() const; 1667 1668 /** 1669 * @since 4.6 1670 * 1671 * Provides list of all installed KDE Language Translations. 1672 * 1673 * Use languageCodeToName(language) to get human readable, localized 1674 * language names. 1675 * 1676 * @return list of all installed language codes 1677 * 1678 * @see languageCodeToName 1679 */ 1680 QStringList installedLanguages() const; 1681 1682 /** 1683 * Convert a known language code to a human readable, localized form. 1684 * If an unknown language code is supplied, empty string is returned; 1685 * this will never happen if the code has been obtained by one of the 1686 * KLocale methods. 1687 * 1688 * @param language the language code 1689 * 1690 * @return the human readable and localized form if the code is known, 1691 * empty otherwise 1692 * 1693 * @see language 1694 * @see languageList 1695 * @see allLanguagesList 1696 * @see installedLanguages 1697 */ 1698 QString languageCodeToName(const QString &language) const; 1699 1700 /** 1701 * Provides list of all known country codes. 1702 * 1703 * Use countryCodeToName(country) to get human readable, localized 1704 * country names. 1705 * 1706 * @return a list of all country codes 1707 * 1708 * @see countryCodeToName 1709 */ 1710 QStringList allCountriesList() const; 1711 1712 /** 1713 * Convert a known country code to a human readable, localized form. 1714 * 1715 * If an unknown country code is supplied, empty string is returned; 1716 * this will never happen if the code has been obtained by one of the 1717 * KLocale methods. 1718 * 1719 * @param country the country code 1720 * 1721 * @return the human readable and localized form of the country name 1722 * 1723 * @see country 1724 * @see allCountriesList 1725 */ 1726 QString countryCodeToName(const QString &country) const; 1727 1728 /** 1729 * Parses locale string into distinct parts. 1730 * The format of locale is language_COUNTRY@modifier.CHARSET 1731 * 1732 * @param locale the locale string to split 1733 * @param language set to the language part of the locale 1734 * @param country set to the country part of the locale 1735 * @param modifier set to the modifer part of the locale 1736 * @param charset set to the charset part of the locale 1737 */ 1738 static void splitLocale(const QString &locale, QString &language, QString &country, 1739 QString &modifier, QString &charset); 1740 1741 /** 1742 * Return the global KLocale instance. 1743 * This is the one used by default by all i18n calls. 1744 * 1745 * Note: in multi-threaded programs, you should call KLocale::global() 1746 * in the main thread (e.g. in main(), after creating the QCoreApplication 1747 * and setting the main component), to ensure that the initialization is 1748 * done in the main thread. However KApplication takes care of this, so this 1749 * is only needed when not using KApplication. 1750 * 1751 * @since 5.0 1752 */ 1753 static KLocale *global(); 1754 1755 /** 1756 * Returns the name of the internal language. 1757 * 1758 * @return Name of the default language 1759 */ 1760 static QString defaultLanguage(); 1761 1762 /** 1763 * Returns the code of the default country, i.e. "C" 1764 * 1765 * This function will not provide a sensible value to use in your app, 1766 * please use country() instead. 1767 * 1768 * @see country 1769 * 1770 * @return Name of the default country 1771 */ 1772 static QString defaultCountry(); 1773 1774 /** 1775 * @since 4.4 1776 * 1777 * Returns the ISO Code of the default currency. 1778 * 1779 * @return ISO Currency Code of the default currency 1780 */ 1781 static QString defaultCurrencyCode(); 1782 1783 /** 1784 * Changes the current country. The current country will be left 1785 * unchanged if failed. It will force a reload of the country specific 1786 * configuration. 1787 * 1788 * An empty country value will set the country to the system default. 1789 * 1790 * If you specify a configuration file, a setLocale() will be performed on 1791 * the config using the current locale language, which may cause a sync() 1792 * and reparseConfiguration() which will save any changes you have made. 1793 * 1794 * @param country the ISO 3166 country code 1795 * @param config a configuration file with a Locale group detailing 1796 * locale-related preferences (such as language, contry, 1797 * and formatting options). 1798 * 1799 * @return @c true on success, @c false on failure 1800 */ 1801 bool setCountry(const QString &country, KConfig *config); 1802 1803 /** 1804 * @since 4.6 1805 * 1806 * Sets the Country Division Code of the Country where the user lives. 1807 * 1808 * The code must comply with the ISO 3166-2 standard. 1809 * See http://en.wikipedia.org/wiki/ISO_3166-2 for details. 1810 * 1811 * In KDE 4.6 it is the apps responsibility to validate the input, 1812 * full validation and other services will be provided in KDE 4.7. 1813 * 1814 * @param countryDivision the Country Division Code for the user 1815 * @return @c true on success, @c false on failure 1816 * @see countryDivisionCode 1817 */ 1818 bool setCountryDivisionCode(const QString &countryDivision); 1819 1820 /** 1821 * Changes the current language. The current language will be left 1822 * unchanged if failed. It will force a reload of the country specific 1823 * configuration as well. 1824 * 1825 * If you specify a configuration file, a setLocale() will be performed on 1826 * the config using the current locale language, which may cause a sync() 1827 * and reparseConfiguration() which will save any changes you have made. 1828 * 1829 * @param language the language code 1830 * @param config a configuration file with a Locale group detailing 1831 * locale-related preferences (such as language, country, 1832 * and formatting options). 1833 * 1834 * @return true on success 1835 */ 1836 bool setLanguage(const QString &language, KConfig *config); 1837 1838 /** 1839 * Changes the list of preferred languages for the locale. The first valid 1840 * language in the list will be used, or the default language (en_US) 1841 * if none of the specified languages were available. 1842 * 1843 * @param languages the list of language codes 1844 * 1845 * @return true if one of the specified languages were used 1846 */ 1847 bool setLanguage(const QStringList &languages); 1848 1849 /** 1850 * @since 4.3 1851 * 1852 * Convert all digits in the string to the given digit set. 1853 * 1854 * Conversion is normally not performed if the given digit set 1855 * is not appropriate in the current locale and language context. 1856 * Unconditional conversion may be requested by setting 1857 * @p ignoreContext to @c true. 1858 * 1859 * @param str the string to convert 1860 * @param digitSet the digit set identifier 1861 * @param ignoreContext unconditional conversion if @c true 1862 * 1863 * @return string with converted digits 1864 * 1865 * @see DigitSet 1866 */ 1867 QString convertDigits(const QString &str, DigitSet digitSet, 1868 bool ignoreContext = false) const; 1869 1870 /** 1871 * @since 4.8 1872 * 1873 * Reparse locale configuration files for the current selected 1874 * language. 1875 */ 1876 void reparseConfiguration(); 1877 1878 private: 1879 friend class KLocalePrivate; 1880 friend class KLocaleTest; 1881 friend class KDateTimeFormatter; 1882 KLocalePrivate *const d; 1883 }; 1884 1885 Q_DECLARE_OPERATORS_FOR_FLAGS(KLocale::DateTimeFormatOptions) 1886 Q_DECLARE_OPERATORS_FOR_FLAGS(KLocale::DateTimeComponents) 1887 Q_DECLARE_OPERATORS_FOR_FLAGS(KLocale::TimeFormatOptions) 1888 Q_DECLARE_OPERATORS_FOR_FLAGS(KLocale::TimeProcessingOptions) 1889 1890 #endif 1891