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*/ 271