klocale.h

Go to the documentation of this file.

/* This file is part of the KDE libraries
    Copyright (C) 1997 Stephan Kulow <coolo@kde.org>
    Copyright (C) 1999-2003 Hans Petter Bieker <bieker@kde.org>
    Copyright (c) 2002 Lukas Tinkl <lukas@kde.org>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA 02110-1301, USA.
*/
#ifndef KLOCALE_H
#define KLOCALE_H

#include <kdecore_export.h>
#include <klocalizedstring.h>
#include <ksharedconfig.h>

#include <QtCore/QString>
#include <QtCore/QList>

class QStringList;
class QTextCodec;
class QDate;
class QTime;
class QDateTime;

class KDateTime;
class KCalendarSystem;
class KCurrencyCode;
class KDayPeriod;

class KLocalePrivate;

class KDECORE_EXPORT KLocale
{
public:
    explicit KLocale(const QString& catalog, KSharedConfig::Ptr config = KSharedConfig::Ptr());

    KLocale(const QString& catalog, const QString &language, const QString &country = QString(),
            KConfig *config = 0);

    KLocale(const KLocale & rhs);

    KLocale& operator= (const KLocale & rhs);

    virtual ~KLocale();

    void translateRawFrom(const char* catname, const char* msg, QString *lang, QString *trans) const;

    void translateRaw(const char* msg, QString *lang, QString *trans) const;

    void translateRawFrom(const char *catname, const char *ctxt, const char *msg, QString *lang, QString *trans) const;

    void translateRaw(const char *ctxt, const char *msg, QString *lang, QString *trans) const;

    void translateRawFrom(const char *catname, const char *singular, const char *plural,  unsigned long n,
                            QString *lang, QString *trans) const;

    void translateRaw(const char *singular, const char *plural,  unsigned long n, QString *lang,
                      QString *trans) const;

    void translateRawFrom(const char *catname, const char *ctxt, const char *singular, const char *plural,
                            unsigned long n, QString *lang, QString *trans) const;

    void translateRaw(const char *ctxt, const char *singular, const char *plural, unsigned long n,
                      QString *lang, QString *trans) const;

    bool setEncoding(int mibEnum);

    enum SignPosition {
        ParensAround = 0,
        BeforeQuantityMoney = 1,
        AfterQuantityMoney = 2,
        BeforeMoney = 3,
        AfterMoney = 4
    };

    enum DigitSet {
        ArabicDigits,             
        ArabicIndicDigits,        
        EasternArabicIndicDigits, 
        DevenagariDigits,         
        BengaliDigits,            
        GujaratiDigits,           
        GurmukhiDigits,           
        KannadaDigits,            
        KhmerDigits,              
        MalayalamDigits,          
        OriyaDigits,              
        TamilDigits,              
        TeluguDigits,             
        ThaiDigits                
    // The following Decimal Digit Sets are defined in Unicode but the associated
    // languages are not yet translated in KDE, so are not yet enabled.
    // The script names are taken from the Unicode standard, the associated
    // languages from Wikipedia.
    //  BalineseDigits,           /**< ᭐᭑᭒᭓᭔᭕᭖᭗᭘᭙ (Balinese) */
    //  ChamDigits,               /**< ꩐꩑꩒꩓꩔꩕꩖꩗꩘꩙ (Cham) */
    //  JavaneseDigits,           /**< ꧐꧑꧒꧓꧔꧕꧖꧗꧘꧙ (Javanese) */
    //  KayahLiDigits,            /**< ꤀꤁꤂꤃꤄꤅꤆꤇꤈꤉ (Kayah) */
    //  LaoDigits,                /**< ໐໑໒໓໔໕໖໗໘໙ (Lao) */
    //  LepchaDigits,             /**< ᱀᱁᱂᱃᱄᱅᱆᱇᱈᱉ (Lepcha) */
    //  LimbuDigits,              /**< ᥆᥇᥈᥉᥊᥋᥌᥍᥎᥏ (Limbu) */
    //  MeeteiMayekDigits,        /**< ꯰꯱꯲꯳꯴꯵꯶꯷꯸꯹ (Meitei) */
    //  MongolianDigits,          /**< ᠐᠑᠒᠓᠔᠕᠖᠗᠘᠙ (Mongolian) */
    //  MyanmarDigits,            /**< ၀၁၂၃၄၅၆၇၈၉ (Myanmar/Burmese ) */
    //  MyanmarShanDigits,        /**< ႐႑႒႓႔႕႖႗႘႙ (Shan) */
    //  NewTaiLueDigits,          /**< ᧐᧑᧒᧓᧔᧕᧖᧗᧘᧙ (Tai Lü) */
    //  NKoDigits,                /**< ߀߁߂߃߄߅߆߇߈߉ (Mande and N'Ko) */
    //  OlChikiDigits,            /**< ᱐᱑᱒᱓᱔᱕᱖᱗᱘᱙ (Santali) */
    //  OsmanyaDigits,            /**< ҠҡҢңҤҥҦҧҨҩ (Somali) */
    //  SaurashtraDigits,         /**< ꣐꣑꣒꣓꣔꣕꣖꣗꣘꣙ (Saurashtra) */
    //  SundaneseDigits,          /**< ᮰᮱᮲᮳᮴᮵᮶᮷᮸᮹ (Sundanese) */
    //  TaiThamDigits,            /**< ᪐᪑᪒᪓᪔᪕᪖᪗᪘᪙ (Tai Lü) */
    //  TibetanDigits,            /**< ༠༡༢༣༤༥༦༧༨༩ (Tibetan) */
    //  VaiDigits,                /**< ꘠꘡꘢꘣꘤꘥꘦꘧꘨꘩ (Vai) */
    };

    QString digitSetToName(DigitSet digitSet, bool withDigits = false) const;

    QList<DigitSet> allDigitSetsList() const;

    QString decimalSymbol() const;

    QString thousandsSeparator() const;

    DigitSet digitSet() const;

    QString currencyCode() const;

    KCurrencyCode *currency() const;

    QString currencySymbol() const;

    QString monetaryDecimalSymbol() const;

    QString monetaryThousandsSeparator() const;

    QString positiveSign() const;

    QString negativeSign() const;

    KDE_DEPRECATED int fracDigits() const;

    int decimalPlaces() const;

    int monetaryDecimalPlaces() const;

    bool positivePrefixCurrencySymbol() const;

    bool negativePrefixCurrencySymbol() const;

    SignPosition positiveMonetarySignPosition() const;

    SignPosition negativeMonetarySignPosition() const;

    DigitSet monetaryDigitSet() const;

    QString formatMoney(double num, const QString &currency = QString(), int precision = -1) const;

    QString formatNumber(double num, int precision = -1) const;

    QString formatNumber(const QString &numStr, bool round = true, int precision = -1) const;

    QString formatLong(long num) const;

    enum BinarySizeUnits {
        DefaultBinaryUnits = -1,

        // The first real unit must be 0 for the current implementation!
        UnitByte,      
        UnitKiloByte,  
        UnitMegaByte,  
        UnitGigaByte,  
        UnitTeraByte,  
        UnitPetaByte,  
        UnitExaByte,   
        UnitZettaByte, 
        UnitYottaByte, 
        UnitLastUnit = UnitYottaByte
    };

    enum BinaryUnitDialect {
        DefaultBinaryDialect = -1, 
        IECBinaryDialect,          
        JEDECBinaryDialect,        
        MetricBinaryDialect,       
        LastBinaryDialect = MetricBinaryDialect
    };

    QString formatByteSize(double size) const;

    QString formatByteSize(double size, int precision,
                           BinaryUnitDialect dialect = KLocale::DefaultBinaryDialect,
                           BinarySizeUnits specificUnit = KLocale::DefaultBinaryUnits) const;

    BinaryUnitDialect binaryUnitDialect() const;

    void setBinaryUnitDialect(BinaryUnitDialect newDialect);

    QString formatDuration(unsigned long mSec) const;

    QString prettyFormatDuration(unsigned long mSec) const;

    KDE_DEPRECATED bool nounDeclension() const;

    //KDE5 move to KDateTime namespace
    enum CalendarSystem {
        QDateCalendar = 1, 
        //BahaiCalendar = 2, /**< Baha'i Calendar */
        //BuddhistLunarCalendar = 3, /**< Buddhist Lunar Calendar*/
        //ChineseCalendar = 4, /**< Chinese Calendar */
        CopticCalendar = 5, 
        EthiopianCalendar = 6, 
        //EthiopianAmeteAlemCalendar = 7, /**< Ethiopian Amete Alem version, aka Ethiopic Amete Alem */
        GregorianCalendar = 8, 
        HebrewCalendar = 9, 
        //HinduCalendar = 10, /**< Hindu Lunar Calendar */
        //IslamicLunarCalendar = 11, /**< Islamic Lunar Calendar */
        IslamicCivilCalendar = 12, 
        //IslamicUmAlQuraCalendar = 13, /**< Islamic Lunar Calendar, Um Al Qura varient used in Saudi Arabia */
        IndianNationalCalendar = 14, 
        //Iso8601Calendar = 15, /**< ISO 8601 Standard Calendar */
        JalaliCalendar = 16, 
        //JalaliBirashkCalendar = 17, /**< Jalali Calendar, Birashk Algorythm variant */
        //Jalali33YearCalendar = 18, /**< Jalali Calendar, 33 Year cycle variant */
        JapaneseCalendar= 19, 
        //JucheCalendar = 20, /**< Juche Calendar, used in North Korea */
        JulianCalendar = 21, 
        MinguoCalendar= 22, 
        ThaiCalendar = 23 
    };

    //KDE5 move to KDateTime namespace
    enum WeekNumberSystem {
        DefaultWeekNumber = -1, 
        IsoWeekNumber     =  0, 
        FirstFullWeek     =  1, 
        FirstPartialWeek  =  2, 
        SimpleWeek        =  3  
    };

    //KDE5 move to KDateTime namespace
    enum DateTimeFormatStandard {
         KdeFormat,        
         PosixFormat,      
         UnicodeFormat     
    };

    //KDE5 move to KDateTime namespace
    enum DateTimeParseMode {
         LiberalParsing   
         //ModerateParsing, /**< Parse Date/Time with modeate tolerance.
         //                      The date components in the format must all
         //                      occur in the input and in the same order,
         //                      but the spacing and the componants themselves
         //                      may vary from the strict format. */
         //StrictParsing    /**< Parse Date/Time strictly to the format. */
    };

    //KDE5 move to KDateTime namespace
    enum DateTimeComponent {
        Year          = 0x1,        
        YearName      = 0x2,        
        Month         = 0x4,        
        MonthName     = 0x8,        
        Day           = 0x10,       
        DayName       = 0x20,       
        JulianDay     = 0x40,       
        EraName       = 0x80,       
        EraYear       = 0x100,      
        YearInEra     = 0x200,      
        DayOfYear     = 0x400,      
        DayOfYearName = 0x800,      
        DayOfWeek     = 0x1000,     
        DayOfWeekName = 0x2000,     
        Week          = 0x4000,     
        WeekYear      = 0x8000,     
        MonthsInYear  = 0x10000,    
        WeeksInYear   = 0x20000,    
        DaysInYear    = 0x40000,    
        DaysInMonth   = 0x80000,    
        DaysInWeek    = 0x100000,   
        Hour          = 0x200000,   
        Minute        = 0x400000,   
        Second        = 0x800000,   
        Millisecond   = 0x1000000,  
        DayPeriod     = 0x2000000,  
        DayPeriodHour = 0x4000000,  
        Timezone      = 0x8000000,  
        TimezoneName  = 0x10000000, 
        UnixTime      = 0x20000000  
    };
    Q_DECLARE_FLAGS(DateTimeComponents, DateTimeComponent)

    //KDE5 move to KDateTime namespace
    enum DateTimeComponentFormat {
        DefaultComponentFormat = -1, 
        ShortNumber = 0,             
        LongNumber,                  
        //OrdinalNumber                /**< Ordinal number format, e.g. "2nd" for the 2nd */
        NarrowName = 3,              
        ShortName,                   
        LongName                     
    };

    //KDE5 move to KDateTime namespace
    enum DateFormat {
        ShortDate,        
        LongDate,         
        FancyShortDate,   
        FancyLongDate,    
        IsoDate,          
        IsoWeekDate,      
        IsoOrdinalDate    
    };

    //KDE5 move to KDateTime namespace
    QString formatDate(const QDate &date, DateFormat format = LongDate) const;

    //KDE5 move to KDateTime namespace
    QString formatDateTime(const QDateTime &dateTime, DateFormat format = ShortDate,
                           bool includeSecs = false) const;

    //KDE5 move to KDateTime namespace
    enum DateTimeFormatOption {
        TimeZone = 0x01,    
        Seconds  = 0x02     
    };
    Q_DECLARE_FLAGS(DateTimeFormatOptions, DateTimeFormatOption)

    //KDE5 move to KDateTime namespace
    QString formatDateTime(const KDateTime &dateTime, DateFormat format = ShortDate,
                           DateTimeFormatOptions options = 0) const;

    bool dateMonthNamePossessive() const;

    QString formatTime(const QTime &pTime, bool includeSecs = false, bool isDuration = false) const;

    //KDE5 move to KDateTime namespace
    enum TimeFormatOption {
        TimeDefault        = 0x0,   
        TimeWithoutSeconds = 0x1,   
        TimeWithoutAmPm    = 0x2,   
        TimeDuration       = 0x6,   
        TimeFoldHours      = 0xE    
    };
    Q_DECLARE_FLAGS(TimeFormatOptions, TimeFormatOption)

    //KDE5 move to KDateTime namespace
    QString formatLocaleTime(const QTime &pTime,
                             TimeFormatOptions options = KLocale::TimeDefault) const;

    DigitSet dateTimeDigitSet() const;

    bool use12Clock() const;

    QString dayPeriodText(const QTime &time, DateTimeComponentFormat format = DefaultComponentFormat) const;

    int weekStartDay() const;

    int workingWeekStartDay() const;

    int workingWeekEndDay() const;

    int weekDayOfPray() const;

    const KCalendarSystem * calendar() const;

    //KDE5 remove
    KDE_DEPRECATED QString calendarType() const;

    KLocale::CalendarSystem calendarSystem() const;

    //KDE5 remove
    KDE_DEPRECATED void setCalendar(const QString & calendarType);

    void setCalendarSystem(KLocale::CalendarSystem calendarSystem);

    void setWeekNumberSystem(KLocale::WeekNumberSystem weekNumberSystem);

    //KDE5 remove in favour of const version
    KLocale::WeekNumberSystem weekNumberSystem();

    KLocale::WeekNumberSystem weekNumberSystem() const;

    double readMoney(const QString &numStr, bool * ok = 0) const;

    double readNumber(const QString &numStr, bool * ok = 0) const;

    //KDE5 move to KDateTime namespace
    QDate readDate(const QString &str, bool* ok = 0) const;

    //KDE5 move to KDateTime namespace
    QDate readDate(const QString &intstr, const QString &fmt, bool* ok = 0) const;

    //KDE5 move to KDateTime namespace
    enum ReadDateFlags {
        NormalFormat          =    1, 
        ShortFormat           =    2, 
        IsoFormat             =    4, 
        IsoWeekFormat         =    8, 
        IsoOrdinalFormat      =   16  
    };

    //KDE5 move to KDateTime namespace
    QDate readDate(const QString &str, ReadDateFlags flags, bool *ok = 0) const;

    QTime readTime(const QString &str, bool* ok = 0) const;

    enum ReadTimeFlags {
        WithSeconds = 0,    
        WithoutSeconds = 1  
    }; // (maybe use this enum as a bitfield, if adding independent features?)

    QTime readTime(const QString &str, ReadTimeFlags flags, bool *ok = 0) const;

    enum TimeProcessingOption {
        ProcessStrict    = 0x1,    
        ProcessNonStrict = 0x2     
    };
    Q_DECLARE_FLAGS(TimeProcessingOptions, TimeProcessingOption)

    
    QTime readLocaleTime(const QString &str, bool *ok = 0,
                         TimeFormatOptions options = KLocale::TimeDefault,
                         TimeProcessingOptions processing = ProcessNonStrict) const;

    QString language() const;

    QString country() const;

    QString countryDivisionCode() const;

    QStringList languageList() const;

    QStringList currencyCodeList() const;

    const QByteArray encoding() const;

    int encodingMib() const;

    QTextCodec * codecForEncoding() const;

    int fileEncodingMib() const;

    void setDateFormat(const QString & format);

    void setDateFormatShort(const QString & format);

    void setDateMonthNamePossessive(bool possessive);

    void setTimeFormat(const QString & format);

    void setDateTimeDigitSet(DigitSet digitSet);

    void setWeekStartDay(int day);

    void setWorkingWeekStartDay(int day);

    void setWorkingWeekEndDay(int day);

    void setWeekDayOfPray(int day);

    QString dateFormat() const;

    QString dateFormatShort() const;

    QString timeFormat() const;

    void setDecimalSymbol(const QString & symbol);

    void setThousandsSeparator(const QString & separator);

    void setPositiveSign(const QString & sign);

    void setNegativeSign(const QString & sign);

    void setDigitSet(DigitSet digitSet);

    void setPositiveMonetarySignPosition(SignPosition signpos);

    void setNegativeMonetarySignPosition(SignPosition signpos);

    void setPositivePrefixCurrencySymbol(bool prefix);

    void setNegativePrefixCurrencySymbol(bool prefix);

    KDE_DEPRECATED void setFracDigits(int digits);

    void setDecimalPlaces(int digits);

    void setMonetaryDecimalPlaces(int digits);

    void setMonetaryThousandsSeparator(const QString & separator);

    void setMonetaryDecimalSymbol(const QString & symbol);

    void setCurrencyCode(const QString &newCurrencyCode);

    void setCurrencySymbol(const QString & symbol);

    void setMonetaryDigitSet(DigitSet digitSet);

    int pageSize() const;

    void setPageSize(int paperFormat);

    enum MeasureSystem {
        Metric,    
        Imperial   
    };

    MeasureSystem measureSystem() const;

    void setMeasureSystem(MeasureSystem value);

    void insertCatalog(const QString& catalog);

    void removeCatalog(const QString &catalog);

    void setActiveCatalog(const QString &catalog);

    QString translateQt(const char *context, const char *sourceText, const char *comment) const;

    QStringList allLanguagesList() const;

    QStringList installedLanguages() const;

    QString languageCodeToName(const QString &language) const;

    QStringList allCountriesList() const;

    QString countryCodeToName(const QString &country) const;

    static void splitLocale(const QString &locale, QString &language, QString &country,
                            QString &modifier, QString &charset);

    static void setMainCatalog(const char *catalog);

    static QString langLookup(const QString &fname, const char *rtype = "html");

    static QString defaultLanguage();

    static QString defaultCountry();

    static QString defaultCurrencyCode();

    bool useTranscript() const;

    bool isApplicationTranslatedInto(const QString & language);

    void copyCatalogsTo(KLocale *locale);

    bool setCountry(const QString & country, KConfig *config);

    bool setCountryDivisionCode(const QString & countryDivision);

    bool setLanguage(const QString &language, KConfig *config);

    bool setLanguage(const QStringList &languages);

    QString localizedFilePath(const QString &filePath) const;

    QString removeAcceleratorMarker(const QString &label) const;

    QString convertDigits(const QString &str, DigitSet digitSet,
                          bool ignoreContext = false) const;

    void reparseConfiguration();

private:
    friend class KLocalePrivate;
    friend class KLocaleTest;
    friend class KDateTimeFormatter;
    KLocalePrivate * const d;
};

Q_DECLARE_OPERATORS_FOR_FLAGS(KLocale::DateTimeFormatOptions)
Q_DECLARE_OPERATORS_FOR_FLAGS(KLocale::DateTimeComponents)
Q_DECLARE_OPERATORS_FOR_FLAGS(KLocale::TimeFormatOptions)
Q_DECLARE_OPERATORS_FOR_FLAGS(KLocale::TimeProcessingOptions)

#endif