Source: klocale.h


Annotated List
Files
Globals
Hierarchy
Index
/* This file is part of the KDE libraries
    Copyright (C) 1997 Stephan Kulow (coolo@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., 59 Temple Place - Suite 330,
    Boston, MA 02111-1307, USA.
*/
#ifndef _KLOCALE_H
#define _KLOCALE_H

#include 
#include 

class QTextCodec;
class QStrList;
class QDate;
class QTime;
class QDateTime;
class KConfig;
class KLocalePrivate;

#ifndef I18N_NOOP
#define I18N_NOOP(x) (x)
#endif

/**
 *  i18n is the function that does everything you need to translate
 *  a string. You just wrap around every user visible string a i18n
 *  call to get a QString with the string in the user's prefered
 *  language.
 **/
QString i18n(const char *text);

/**
 *  If the string is too ambigious to be translated well to a non-english
 *  language, use this form of i18n to separate lookup string and english
 *  text
 *  @see translate
 **/
QString i18n(const char *index, const char *text);

/**
 *  If you want to handle plural forms, use this form of i18n.
 *  The plural has to contain a %n where n fits into.
 *  @see translate
 **/
QString i18n(const char *singular, const char *plural, unsigned long n);

/**
  *
  * KLocale provides support for country specific stuff like
  * the national language.
  *
  * KLocale supports translating, as well as specifying the format
  * for numbers, currency, time, and date.
  *
  * @author Stephan Kulow , Preston Brown , Hans Petter Bieker 
  * @short class for supporting locale settings and national language
  */
class KLocale {

      friend class KGlobal;
public:
    /**
      * Create a KLocale with the given catalogue name.
      * If no catalogue is given, the application name is used.
      * The constructor looks for an entry Locale/Language in the
      * configuration file.
      * If nothing is set there, it looks for the environment variable
      * $LANG. The format for LANG is de, if de (german) is your
      * prefered language. If none of them can be find, the default (C)
      * will be used.
      *
      * @param catalogue The name of the language file
      */
    KLocale( const QString& catalogue = QString::null );

    /**
      * Destructor.
      */
    ~KLocale();

    /**
      * Translate the string into the corresponding string in
      * the national language, if available. If not, returns
      * the string itself.
      * There is a KDE wide message file that contains the most
      * often used phrases, so we can avoid duplicating the
      * translation of these phrases. If a phrase is not found
      * in the catalogue given to the constructor, it will search
      * in the system catalog. This makes it possible to override
      * some phrases for your needs.
      *
      * @param index The lookup text and default text, if not found.
      */
    QString translate( const char *index ) const;

    /**
     * Translate the string into the corresponding string in the
     * national language, if available.
     *
     * The real contents of the string is in the argument fallback,
     * but the meaning of it is coded into the argument index.
     * In some cases you'll need this function, when english is
     * too ambigious to express it.
     *
     * Most of the times the translators will tell you if it can't
     * be translated as it, but think of cases as "New", where the
     * translations differs depending on what is New.
     * Or simple cases as "Open", that can be used to express something
     * is open or it can be used to express that you want something to
     * open... There are tons of such examples.
     *
     * If translate("Open") is not enough to translate it well, use
     * translate("To Open", "Open") or translate("Is Open", "Open").
     * The english user will see "Open" in both cases, but the translated
     * version may vary. Of course you can also use i18n()
     *
     * @param index The lookup text
     * @param fallback the default text, if not found
     * @return translation
     */
    QString translate( const char *index, const char *fallback) const;

    QString translate( const char *singular, const char *plural,
                       unsigned long n) const;

    /**
     * Allows programs such as kcmlocale to choose which translation to use.
     *
     * @param _lang The language you want to use.
     */
    void setLanguage(const QString &_lang);

    /**
     * Various positions for where to place the positive or negative
     * sign when they are related to a monetary value.
     */
    enum SignPosition { ParensAround = 0, BeforeQuantityMoney = 1,
			AfterQuantityMoney = 2,
			BeforeMoney = 3, AfterMoney = 4 };

    /**
     * Retrieve what a decimal point should look like ("." or "," etc.)
     * according to the current locale or user settings.
     *
     * @return The decimal symbol used by locale.
     */
    QString decimalSymbol() const;

    /**
     * Retrieve what the thousands separator should look
     * like ("," or "." etc.)
     * according to the current locale or user settings.
     *
     * @return The thousands separator used by locale.
     */
    QString thousandsSeparator() const;

    /**
     * Retrieve what the symbol denoting currency in the current locale
     * as as defined by user settings should look like.
     *
     * @return The default currecy symbol used by locale.
     */
    QString currencySymbol() const;

    /**
     * Retrieve what a decimal point should look like ("." or "," etc.)
     * for monetary values, according to the current locale or user
     * settings.
     *
     * @return The monetary decimal symbol used by locale.
     */
    QString monetaryDecimalSymbol() const;

    /**
     * Retrieve what a thousands separator for monetary values should
     * look like ("," or " " etc.) according to the current locale or
     * user settings.
     *
     * @return The monetary thousands separator used by locale.
     */
    QString monetaryThousandsSeparator() const;

    /**
     * Retrieve what a positive sign should look like ("+", " ", etc.)
     * according to the current locale or user settings.
     *
     * @return The positive sign used by locale.
     */
    QString positiveSign() const;

    /**
     * Retrieve what a negative sign should look like ("-", etc.)
     * according to the current locale or user settings.
     *
     * @return The negative sign used by locale.
     */
    QString negativeSign() const;

    /**
     * The number of fractional digits to include in numeric/monetary
     * values (usually 2).
     *
     * @return Default number of fractional digits used by locale.
     */
    int fracDigits() const;

    /**
     * If and only if the currency symbol precedes a positive value,
     * this will be true.
     *
     * @return Where to print the currency symbol for positive numbers.
     */
    bool positivePrefixCurrencySymbol() const;

    /**
     * If and only if the currency symbol precedes a negative value,
     * this will be true.
     *
     * @return Where to print the currecy symbol for negative numbers.
     */
    bool negativePrefixCurrencySymbol() const;

    /**
     * Retrieve the position of a positive sign in relation to a
     * monetary value.
     *
     * @return Where/how to print the positive sign.
     * @see SignPosition
     */
    SignPosition positiveMonetarySignPosition() const;

    /**
     * Denotes where to place a negative sign in relation to a
     * monetary value.
     *
     * @return Where/how to print the negative sign.
     * @see SignPosition
     */
    SignPosition negativeMonetarySignPosition() const;

    /**
     * Given a double, convert that to a numeric string containing
     * the localized monetary equivalent.
     *
     * e.g. given 123456, return "$ 123,456.00".
     *
     * @param num The number we want to format
     * @param currency The currency symbol you want.
     * @param digits Number of fractional digits.
     *
     * @return The number of money as a localized string
     */
    QString formatMoney(double num, const QString ¤cy = QString::null, int digits = -1) const;

    /**
     * This function differs from the above only in that it can take
     * a QString as the argument for convenience.
     *
     * @param numStr The string you want to reformat.
     *
     * @return The number of money as a localized string
     */
    QString formatMoney(const QString &numStr) const;

    /**
     * Given a double, convert that to a numeric string containing
     * the localized numeric equivalent.
     *
     * e.g. given 123456.78, return "123,456.78" (for some European country).
     * If precision isn't specified, 2 is used.
     *
     * @param num The number to convert
     * @param precision Number of fractinal digits used.
     *
     * @return The number as a localized string
     */
    QString formatNumber(double num, int precision = -1) const;

    /**
     * This function differs from the above only in that it can take
     * a QString as the argument for convenience.
     *
     * @param numStr The string you want to convert.
     *
     * @return The number as a formated string
     */
    QString formatNumber(const QString &numStr) const;

    /**
     * Return a string formatted to the current locale's conventions
     * regarding dates.
     *
     * @param pDate The date to be formated.
     * @param shotfmt True for non text dates.
     *
     * @return The date as a string
     */
    QString formatDate(const QDate &pDate, bool shortfmt = false) const;

    /**
     * Return a string formatted to the current locale's conventions
     * regarding times.
     *
     * @param pTime The time to be formated.
     * @param includeSecs if true, seconds are included in the output,
     *        otherwise only hours and minutes are formatted.
     *
     * @return The time as a string
     */
    QString formatTime(const QTime &pTime, bool includeSecs = false) const;

    /**
     * Use this to determine if the user wants a 12 hour clock.
     *
     * @return If the user wants 12h clock
     */
    bool use12Clock() const;

    /**
     * Use this to determine if the user wants the week to start on monday.
     *
     * @return true if the week starts on monday
     */
    bool weekStartsMonday() const;

    /**
     * Return a string containing the name of the month name.
     *
     * @param i the month number of the year starting at 1/January.
     * @param _short we will return the short versoin of the string.
     *
     * @return The name of the month
     */
    QString monthName(int i, bool _short = false) const;

    /**
     * Return a string containing the name of the week day.
     *
     * @param i the day number of the week starting at 1/Monday.
     * @param _short we will return the short versoin of the string.
     *
     * @return The name of the week
     */
    QString weekDayName(int i, bool _short = false) const;

    /**
     * Return a string formated to the current locale's conventions
     * regarding both date and time. Defaults to short date format.
     *
     * @param pDateTime The date and time to be formated.
     *
     * @return The date and time as a string
     */
    QString formatDateTime(const QDateTime &pDateTime) const;

    /**
     * Return a string formated to the current locale's conventions
     * regarding both date and time.
     *
     * @param pDateTime The date and time to be formated.
     * @param shortfmt using the short date format.
     * @param includeSeconds using the short date format.
     *
     * @return The date and time as a string
     */
    QString formatDateTime(const QDateTime &pDateTime, bool shortfmt, bool includeSecs = false) const;

    /**
     * Converts a localized monetary string to a double.
     *
     * @param numStr the string we want to convert.
     * @param ok the boolean that is set to false if it's not a number.
     *
     * @return The string converted to a double
     */
    double readMoney(const QString &numStr, bool * ok=0) const;

    /**
     * Converts a localized numeric string to a double.
     *
     * @param numStr the string we want to convert.
     * @param ok the boolean that is set to false if it's not a number.
     *
     * @return The string converted to a double
     */
    double readNumber(const QString &numStr, bool * ok=0) const;

    /**
     * Converts a localized date string to a QDate.
     * isValid() on the returning object will be false
     * if the date entered was not valid.
     *
     * Note: This only works on short dates for the time beeing.
     *
     * @param str the string we want to convert.
     *
     * @return The string converted to a QDate
     */
    QDate readDate(const QString &str) const;

    /**
     * Converts a localized time string to a QTime.
     * isValid() on the returning object will be false
     * if the time entered was not valid.
     *
     * @param str the string we want to convert.
     *
     * @return The string converted to a QTime
     */
    QTime readTime(const QString &str) const;

    /**
      * Returns the language used by this object. The domain AND the
      * library translation must be available in this language.
      * 'C' is default, if no other available.
      *
      * @return The currently used language.
      */
    QString language() const;

    /**
      * Returns the country code of the country where the user lives.
      * 'C' is default, if no other available
      *
      * @return The country code for the user.
      */
    QString country() const;

    /**
      * Returns the languages selected by user.
      *
      * @return String containing language codes separated by colons
      */
    QString languages() const;

    /**
      * Returns the languages selected by user.
      *
      * @return List of language codes
      */
    QStringList languageList() const;

    /**
      * Returns the charset name by selected locale.
      * This will be the charset defined in the config file.
      * NOTE: This is no longer the same as encoding.
      * "iso-8859-1" is default
      *
      * @return Name of the prefered charset for fonts
      */
    QString charset() const { return chset; }

    /**
     * adds another catalogue to search for translation lookup.
     * This function is useful for extern libraries and/or code,
     * that provides its own messages.
     *
     * If the catalogue does not exist for the chosen language,
     * it will be ignored and C will be used.
     *
     * @param catalogue The catalogue to add.
     **/
    void insertCatalogue(const QString& catalogue);

    /**
     * translates a message as a QTranslator is supposed to.
     * The parameters are similiar to i18n(), but the result
     * value has other semantics (it can be QString::null)
     **/
    QString translateQt(const char *context, const char *sourceText) const;

    /**
     * returns the parts of the parameter str understood as language setting
     * the format is language_country.charset
     * @param str The string to split.
     * @param language This will be set to the language part of the string.
     * @param country This will be set to the country part of the string.
     * @param charset This will be set to the charset part of the stirng.
     */
    static void splitLocale(const QString& str,QString& language, QString& country,
                     QString &charset);

    /**
     * Init the localization part of the instance with the config object.
     *
     * @param config The configuration object used for init.
     */
    void initFormat(KConfig *config);

    /**
     * Init the language part of the instance with the given config object. It
     * should be valid and contain the global entries.
     *
     * @param config The configuration object used for init.
     * @param catalogue The main catalogue to use.
     **/
    void initLanguage(KConfig *config, const QString& catalogue);

    /**
     * @return True if the KLocale instance is initialized already. You can't
     * translate before it is.
     * The constructor will initialize the instance, but under some
     * circumstances - when the circumstances do not fit for initialization
     * - it will just delay the initialization til you call initLanguage
     *
     * @return Returns true if locale is inited.
     */
    bool inited() const { return _inited; }

    /**
     * Use this to as main catalogue for *all* KLocales, if not the appname
     * will be used.
     *
     * @param catalogue Catalogue to override all other main catalogues.
     */
     static void setMainCatalogue(const char *catalogue);

    /**
     * Find localized resource in resourceDir( rtype ) +  + fname.
     *
     * @param fname relative path to find
     * @param rtype resource type to use
     */
    static QString langLookup(const QString &fname, const char *rtype = "html");

protected:
    QString chset;
    bool m_weekStartsMonday;

    // Numbers and money
    QString _decimalSymbol;
    QString _thousandsSeparator;
    QString _currencySymbol;
    QString _monetaryDecimalSymbol;
    QString _monetaryThousandsSeparator;
    QString _positiveSign;
    QString _negativeSign;
    int _fracDigits;
    bool _positivePrefixCurrencySymbol;
    bool _negativePrefixCurrencySymbol;
    SignPosition _positiveMonetarySignPosition;
    SignPosition _negativeMonetarySignPosition;

    // Date and time
    QString _timefmt;
    QString _datefmt;
    QString _datefmtshort;

    QStrList *catalogues;
    bool _inited;

    QCString lang; // The current language used by the locale
    QTextCodec *_codec; // Codec used for translations
    QString langs; // Prefered languages
    QString _country; // Where the user lives

    /**
     * @internal function used by readTime(const QString &) const.
     */
    QTime readTime(const QString &str, bool seconds) const;

    /**
     * @internal function used by readDate(const QString &) const.
     */
    QDate readDate(const QString &str, bool shortfmt) const;

    /**
     * @internal function used by the constructor.
     */
    void setEncodingLang(const QString &_lang);

    // Disallow assignment and copy-construction
    KLocale( const KLocale& );
    KLocale& operator= ( const KLocale& );

private:
    static void initInstance();
    /**
     * @internal function used by the two translate versions
     */
    QString translate_priv(const char *index, const char *text, const char **original = 0) const;

    KLocalePrivate *d;
};

#endif

Generated by: dfaure on kde.faure.org on Thu Jan 17 22:15:01 2002, using kdoc 2.0a53.