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 37 38/*! 39 \fn BLocaleRoster::BLocaleRoster() 40 \brief Constructor. Does nothing. 41*/ 42 43 44/*! 45 \fn BLocaleRoster::~BLocaleRoster() 46 \brief Destructor. Does nothing. 47*/ 48 49 50/*! 51 \fn BLocaleRoster* BLocaleRoster::Default() 52 \brief Returns default BLocalRoster. 53*/ 54 55 56/*! 57 \fn status_t BLocaleRoster::Refresh() 58 \brief Refreshes the BLocalRoster. 59*/ 60 61 62/*! 63 \fn status_t BLocaleRoster::GetDefaultTimeZone(BTimeZone* timezone) const 64 \brief Get the default timezone. 65*/ 66 67 68/*! 69 \fn status_t BLocaleRoster::GetLanguage(const char* languagecode, 70 BLanguage** _language) const 71 \brief Instantiate a language from its code. 72*/ 73 74 75/*! 76 \fn status_t BLocaleRoster::GetPreferredLanguages(BMessage* message) const 77 \brief Return the list of user preferred languages. 78 79 This function fills in the given message with one or more language string 80 fields. They constitute the ordered list of user-selected languages to use 81 for string translation. 82*/ 83 84 85/*! 86 \fn status_t BLocaleRoster::GetAvailableLanguages(BMessage* message) const 87 \brief Fills \c message with 'language'-fields containing the language 88 ID(s) of all available languages. 89*/ 90 91 92/*! 93 \fn status_t BLocaleRoster::GetAvailableCountries(BMessage* message) const 94 \brief Fills in the passed in \a message with one or more 'country' 95 string fields, containing the (ISO-639) code of each country. 96*/ 97 98 99/*! 100 \fn status_t BLocaleRoster::GetAvailableTimeZones(BMessage* timeZones) const 101 \brief Fills in the passed in \a timeZones message with all time zone 102 strings for the locale. 103 104 \returns A status code. 105 \retval B_OK Everything went well. 106 \retval B_BAD_VALUE A \c NULL \a timeZones message was passed in. 107 \retval B_ERROR An error occurred trying to retrieve the localized time zone 108 strings. 109*/ 110 111 112/*! 113 \fn status_t BLocaleRoster::GetAvailableTimeZonesForCountry( 114 BMessage* timeZones, const char* countryCode) const 115 \brief Fills in the passed in \a timeZones message with one or more 116 time zone strings containing the time zones for the 117 country specified by \a countryCode for the locale. 118 119 \returns A status code. 120 \retval B_OK Everything went well. 121 \retval B_BAD_VALUE A \c NULL \a timeZones message was passed in. 122 \retval B_ERROR An error occurred trying to retrieve the localized time 123 zones most likely due to an invalid \a countryCode. 124*/ 125 126 127/*! 128 \fn status_t BLocaleRoster::GetFlagIconForCountry(BBitmap* flagIcon, 129 const char* countryCode) 130 \brief Sets \a flagIcon to the flag for the passed in \a countryCode. 131 132 \returns A status code. 133 \retval B_OK Everything went well. 134 \retval B_BAD_VALUE A \c NULL or invalid \a countryCode was passed in. 135 \retval B_ERROR Error locking the default RosterData. 136 \retval B_NAME_NOT_FOUND The flag could not be found for the 137 \a countryCode. 138*/ 139 140 141/*! 142 \fn status_t BLocaleRoster::GetFlagIconForLanguage(BBitmap* flagIcon, 143 const char* languageCode) 144 \brief Sets \a flagIcon to the flag for the passed in \a languageCode. 145 146 If a flag could not be located for the passed in \a languageCode then 147 GetFlagIconForLanguage() attempts to locate the default country's flag for 148 the \a languageCode instead. The default country flag for a language is 149 usually set to the country of the languages origin such as Germany for 150 German or Spain for Spanish. 151 152 \returns A status code. 153 \retval B_OK Everything went well. 154 \retval B_BAD_VALUE A \c NULL or invalid \a languageCode was passed in. 155 \retval B_ERROR Error locking the default RosterData. 156 \retval B_NAME_NOT_FOUND The flag could not be found for the 157 default country's flag for the \a languageCode. 158*/ 159 160 161/*! 162 \fn status_t BLocaleRoster::GetAvailableCatalogs(BMessage* languageList, 163 const char* sigPattern, const char* langPattern, 164 int32 fingerprint) const 165 \brief Get the available locales and catalogs. 166 167 Fills the passed \a languageList message with one or more 'locale' string 168 fields containing the locale names. 169 170 The optional parameters can be used to filter the list and only get the 171 locales for which a catalog is available for the given app (sigPattern, 172 fingerprint), or the locales with a given language. 173 174 \returns A status code. 175 \retval B_OK Everything went well. 176 \retval B_BAD_VALUE A \c NULL \a languageList message was passed in. 177 \retval B_ERROR Error locking the default RosterData. 178*/ 179 180 181/*! 182 \fn bool BLocaleRoster::IsFilesystemTranslationPreferred() const 183 \brief Returns whether or not filesystem translation is preferred. 184 185 \returns \c B_ERROR if there was an error locking the default RosterData. 186*/ 187 188 189/*! 190 \fn status_t BLocaleRoster::GetLocalizedFileName(BString& localizedFileName, 191 const entry_ref& ref, bool traverse) 192 \brief Looks up a localized filename from a catalog. 193 194 Attribute format: "signature:context:string" 195 (no colon in any of signature, context and string) 196 197 Lookup is done for the top preferred language only. 198 Lookup fails if a comment is present in the catalog entry. 199 200 \param localizedFileName A pre-allocated BString object for the result 201 of the lookup. 202 \param ref An entry_ref with an attribute holding data for catalog lookup. 203 \param traverse Determines if symlinks should be traversed. 204 205 \returns A status code. 206 \retval B_OK: success 207 \retval B_ENTRY_NOT_FOUND: failure. Attribute not found, entry not found 208 in catalog, etc. 209*/ 210 211 212/*! 213 \fn BCatalog* BLocaleRoster::_GetCatalog() 214 \brief Get the current image catalog. 215 216 This function returns the catalog for the calling image (application, 217 add-on, or shared library). Note that it doesn't allow to specify a 218 fingerprint. The language will be selected from the user preferences. 219 220 \warning This function needs the image to be lined with liblocalestub.a 221 222 \returns The catalog, if it was loaded successfully. 223*/ 224