docs/user/locale/LocaleRoster.dox

   1 /*
   2  * Copyright 2003-2010 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Axel Dörfler, axeld@pinc-software.de
   7  *              John Scipione, jscipione@gmail.com
   8  *              Oliver Tappe, zooey@hirschkaefer.de
   9  *
  10  * Corresponds to:
  11  *              headers/os/locale/LocaleRoster.h         rev 42274
  12  *              src/kits/locale/LocaleRoster.cpp         rev 42274
  13  */
  14
  15
  16 /*!
  17         \file LocaleRoster.h
  18         \ingroup locale
  19         \ingroup libbe
  20         \brief Provides the BLocaleRoster class to access locale data.
  21 */
  22
  23
  24 /*!
  25         \class BLocaleRoster
  26         \ingroup locale
  27         \ingroup libbe
  28         \brief Main class for accessing the Locale Kit data.
  29
  30         The Locale Roster is the central part of the locale kit. It is a global
  31         object (\c be_locale_roster) storing all the useful locale data. Other
  32         classes from the Locale Kit can be constructed on their own, but only the
  33         Locale Roster allows you to do so while taking account of the user's locale
  34         settings.
  35
  36         \since Haiku R1
  37 */
  38
  39
  40 /*!
  41         \fn BLocaleRoster::BLocaleRoster()
  42         \brief Constructor. Does nothing.
  43
  44         \since Haiku R1
  45 */
  46
  47
  48 /*!
  49         \fn BLocaleRoster::~BLocaleRoster()
  50         \brief Destructor. Does nothing.
  51
  52         \since Haiku R1
  53 */
  54
  55
  56 /*!
  57         \fn BLocaleRoster* BLocaleRoster::Default()
  58         \brief Returns default BLocalRoster.
  59
  60         \since Haiku R1
  61 */
  62
  63
  64 /*!
  65         \fn status_t BLocaleRoster::Refresh()
  66         \brief Refreshes the BLocalRoster.
  67
  68         \since Haiku R1
  69 */
  70
  71
  72 /*!
  73         \fn status_t BLocaleRoster::GetDefaultTimeZone(BTimeZone* timezone) const
  74         \brief Get the default timezone.
  75
  76         \since Haiku R1
  77 */
  78
  79
  80 /*!
  81         \fn status_t BLocaleRoster::GetLanguage(const char* languagecode,
  82                 BLanguage** _language) const
  83         \brief Instantiate a language from its code.
  84
  85         \since Haiku R1
  86 */
  87
  88
  89 /*!
  90         \fn status_t BLocaleRoster::GetPreferredLanguages(BMessage* message) const
  91         \brief Return the list of user preferred languages.
  92
  93         This function fills in the given message with one or more language string
  94         fields. They constitute the ordered list of user-selected languages to use
  95         for string translation.
  96
  97         \since Haiku R1
  98 */
  99
 100
 101 /*!
 102         \fn status_t BLocaleRoster::GetAvailableLanguages(BMessage* message) const
 103         \brief Fills \c message with 'language'-fields containing the language
 104                ID(s) of all available languages.
 105
 106         \since Haiku R1
 107 */
 108
 109
 110 /*!
 111         \fn status_t BLocaleRoster::GetAvailableCountries(BMessage* message) const
 112         \brief Fills in the passed in \a message with one or more 'country'
 113                string fields, containing the (ISO-639) code of each country.
 114
 115         \since Haiku R1
 116 */
 117
 118
 119 /*!
 120         \fn status_t BLocaleRoster::GetAvailableTimeZones(BMessage* timeZones) const
 121         \brief Fills in the passed in \a timeZones message with all time zone
 122                strings for the locale.
 123
 124         \returns A status code.
 125         \retval B_OK Everything went well.
 126         \retval B_BAD_VALUE A \c NULL \a timeZones message was passed in.
 127         \retval B_ERROR An error occurred trying to retrieve the localized time zone
 128                 strings.
 129
 130         \since Haiku R1
 131 */
 132
 133
 134 /*!
 135         \fn status_t BLocaleRoster::GetAvailableTimeZonesForCountry(
 136                 BMessage* timeZones, const char* countryCode) const
 137         \brief Fills in the passed in \a timeZones message with one or more
 138                time zone strings containing the time zones for the
 139                country specified by \a countryCode for the locale.
 140
 141         \returns A status code.
 142         \retval B_OK Everything went well.
 143         \retval B_BAD_VALUE A \c NULL \a timeZones message was passed in.
 144         \retval B_ERROR An error occurred trying to retrieve the localized time
 145                 zones most likely due to an invalid \a countryCode.
 146
 147         \since Haiku R1
 148 */
 149
 150
 151 /*!
 152         \fn status_t BLocaleRoster::GetFlagIconForCountry(BBitmap* flagIcon,
 153                 const char* countryCode)
 154         \brief Sets \a flagIcon to the flag for the passed in \a countryCode.
 155
 156         \returns A status code.
 157         \retval B_OK Everything went well.
 158         \retval B_BAD_VALUE A \c NULL or invalid \a countryCode was passed in.
 159         \retval B_ERROR Error locking the default RosterData.
 160         \retval B_NAME_NOT_FOUND The flag could not be found for the
 161                 \a countryCode.
 162
 163         \since Haiku R1
 164 */
 165
 166
 167 /*!
 168         \fn status_t BLocaleRoster::GetFlagIconForLanguage(BBitmap* flagIcon,
 169                 const char* languageCode)
 170         \brief Sets \a flagIcon to the flag for the passed in \a languageCode.
 171
 172         If a flag could not be located for the passed in \a languageCode then
 173         GetFlagIconForLanguage() attempts to locate the default country's flag for
 174         the \a languageCode instead. The default country flag for a language is
 175         usually set to the country of the languages origin such as Germany for
 176         German or Spain for Spanish.
 177
 178         \returns A status code.
 179         \retval B_OK Everything went well.
 180         \retval B_BAD_VALUE A \c NULL or invalid \a languageCode was passed in.
 181         \retval B_ERROR Error locking the default RosterData.
 182         \retval B_NAME_NOT_FOUND The flag could not be found for the
 183                 default country's flag for the \a languageCode.
 184
 185         \since Haiku R1
 186 */
 187
 188
 189 /*!
 190         \fn status_t BLocaleRoster::GetAvailableCatalogs(BMessage* languageList,
 191                 const char* sigPattern, const char* langPattern,
 192                 int32 fingerprint) const
 193         \brief Get the available locales and catalogs.
 194
 195         Fills the passed \a languageList message with one or more 'locale' string
 196         fields containing the locale names.
 197
 198         The optional parameters can be used to filter the list and only get the
 199         locales for which a catalog is available for the given app (sigPattern,
 200         fingerprint), or the locales with a given language.
 201
 202         \returns A status code.
 203         \retval B_OK Everything went well.
 204         \retval B_BAD_VALUE A \c NULL \a languageList message was passed in.
 205         \retval B_ERROR Error locking the default RosterData.
 206
 207         \since Haiku R1
 208 */
 209
 210
 211 /*!
 212         \fn bool BLocaleRoster::IsFilesystemTranslationPreferred() const
 213         \brief Returns whether or not filesystem translation is preferred.
 214
 215         \returns \c B_ERROR if there was an error locking the default RosterData.
 216
 217         \since Haiku R1
 218 */
 219
 220
 221 /*!
 222         \fn status_t BLocaleRoster::GetLocalizedFileName(BString& localizedFileName,
 223                 const entry_ref& ref, bool traverse)
 224         \brief Looks up a localized filename from a catalog.
 225
 226         Attribute format:  "signature:context:string"
 227         (no colon in any of signature, context and string)
 228
 229         Lookup is done for the top preferred language only.
 230         Lookup fails if a comment is present in the catalog entry.
 231
 232         \param localizedFileName A pre-allocated BString object for the result
 233                 of the lookup.
 234         \param ref An entry_ref with an attribute holding data for catalog lookup.
 235         \param traverse Determines if symlinks should be traversed.
 236
 237         \returns A status code.
 238         \retval B_OK: success
 239         \retval B_ENTRY_NOT_FOUND: failure. Attribute not found, entry not found
 240                 in catalog, etc.
 241
 242         \since Haiku R1
 243 */
 244
 245
 246 /*!
 247         \fn BCatalog* BLocaleRoster::_GetCatalog(BCatalog* catalog,
 248                 vint32* catalogInitStatus)
 249         \brief Get the current image catalog.
 250
 251         This function initializes and returns  the catalog for the calling image
 252         (application, add-on, or shared library). Note that it doesn't allow to
 253         specify a fingerprint. The language will be selected from the user
 254         preferences.
 255
 256         This function is used by the Locale Kit macros.
 257
 258         \warning This function needs the calling image to be linked with
 259                  liblocalestub.a
 260
 261         \returns The catalog, if it was loaded successfully.
 262
 263         \param catalog The catalog to load. The pointer location is used to
 264                identify the image for which to load the catalog.
 265         \param catalogInitStatus the state of the catalog. This will be set to
 266                true on the first call for a given catalog, and if already true
 267                the function will do nothing on subsequent calls.
 268
 269         \since Haiku R1
 270 */