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