haiku/docs/user/locale/LocaleRoster.dox

235 lines
6.9 KiB
Plaintext
Raw Normal View History

/*
* Copyright 2003-2010 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Axel Dörfler, axeld@pinc-software.de
* John Scipione, jscipione@gmail.com
* Oliver Tappe, zooey@hirschkaefer.de
*
* Corresponds to:
* headers/os/locale/LocaleRoster.h rev 42274
* src/kits/locale/LocaleRoster.cpp rev 42274
*/
/*!
\file LocaleRoster.h
\ingroup locale
\ingroup libbe
\brief Provides the BLocaleRoster class to access locale data.
*/
/*!
\class BLocaleRoster
\ingroup locale
\ingroup libbe
\brief Main class for accessing the Locale Kit data.
The Locale Roster is the central part of the locale kit. It is a global
object (\c be_locale_roster) storing all the useful locale data. Other
classes from the Locale Kit can be constructed on their own, but only the
Locale Roster allows you to do so while taking account of the user's locale
settings.
*/
/*!
\fn BLocaleRoster::BLocaleRoster()
\brief Constructor. Does nothing.
*/
/*!
\fn BLocaleRoster::~BLocaleRoster()
\brief Destructor. Does nothing.
*/
/*!
\fn BLocaleRoster* BLocaleRoster::Default()
\brief Returns default BLocalRoster.
*/
/*!
\fn status_t BLocaleRoster::Refresh()
\brief Refreshes the BLocalRoster.
*/
/*!
\fn status_t BLocaleRoster::GetDefaultTimeZone(BTimeZone* timezone) const
\brief Get the default timezone.
*/
/*!
\fn status_t BLocaleRoster::GetLanguage(const char* languagecode,
BLanguage** _language) const
\brief Instantiate a language from its code.
*/
/*!
\fn status_t BLocaleRoster::GetPreferredLanguages(BMessage* message) const
\brief Return the list of user preferred languages.
This function fills in the given message with one or more language string
fields. They constitute the ordered list of user-selected languages to use
for string translation.
*/
/*!
\fn status_t BLocaleRoster::GetAvailableLanguages(BMessage* message) const
\brief Fills \c message with 'language'-fields containing the language
ID(s) of all available languages.
*/
/*!
\fn status_t BLocaleRoster::GetAvailableCountries(BMessage* message) const
\brief Fills in the passed in \a message with one or more 'country'
string fields, containing the (ISO-639) code of each country.
*/
/*!
\fn status_t BLocaleRoster::GetAvailableTimeZones(BMessage* timeZones) const
\brief Fills in the passed in \a timeZones message with all time zone
strings for the locale.
\returns A status code.
\retval B_OK Everything went well.
\retval B_BAD_VALUE A \c NULL \a timeZones message was passed in.
\retval B_ERROR An error occurred trying to retrieve the localized time zone
strings.
*/
/*!
\fn status_t BLocaleRoster::GetAvailableTimeZonesForCountry(
BMessage* timeZones, const char* countryCode) const
\brief Fills in the passed in \a timeZones message with one or more
time zone strings containing the time zones for the
country specified by \a countryCode for the locale.
\returns A status code.
\retval B_OK Everything went well.
\retval B_BAD_VALUE A \c NULL \a timeZones message was passed in.
\retval B_ERROR An error occurred trying to retrieve the localized time
zones most likely due to an invalid \a countryCode.
*/
/*!
\fn status_t BLocaleRoster::GetFlagIconForCountry(BBitmap* flagIcon,
const char* countryCode)
\brief Sets \a flagIcon to the flag for the passed in \a countryCode.
\returns A status code.
\retval B_OK Everything went well.
\retval B_BAD_VALUE A \c NULL or invalid \a countryCode was passed in.
\retval B_ERROR Error locking the default RosterData.
\retval B_NAME_NOT_FOUND The flag could not be found for the
\a countryCode.
*/
/*!
\fn status_t BLocaleRoster::GetFlagIconForLanguage(BBitmap* flagIcon,
const char* languageCode)
\brief Sets \a flagIcon to the flag for the passed in \a languageCode.
If a flag could not be located for the passed in \a languageCode then
GetFlagIconForLanguage() attempts to locate the default country's flag for
the \a languageCode instead. The default country flag for a language is
usually set to the country of the languages origin such as Germany for
German or Spain for Spanish.
\returns A status code.
\retval B_OK Everything went well.
\retval B_BAD_VALUE A \c NULL or invalid \a languageCode was passed in.
\retval B_ERROR Error locking the default RosterData.
\retval B_NAME_NOT_FOUND The flag could not be found for the
default country's flag for the \a languageCode.
*/
/*!
\fn status_t BLocaleRoster::GetAvailableCatalogs(BMessage* languageList,
const char* sigPattern, const char* langPattern,
int32 fingerprint) const
\brief Get the available locales and catalogs.
Fills the passed \a languageList message with one or more 'locale' string
fields containing the locale names.
The optional parameters can be used to filter the list and only get the
locales for which a catalog is available for the given app (sigPattern,
fingerprint), or the locales with a given language.
\returns A status code.
\retval B_OK Everything went well.
\retval B_BAD_VALUE A \c NULL \a languageList message was passed in.
\retval B_ERROR Error locking the default RosterData.
*/
/*!
\fn bool BLocaleRoster::IsFilesystemTranslationPreferred() const
\brief Returns whether or not filesystem translation is preferred.
\returns \c B_ERROR if there was an error locking the default RosterData.
*/
/*!
\fn status_t BLocaleRoster::GetLocalizedFileName(BString& localizedFileName,
const entry_ref& ref, bool traverse)
\brief Looks up a localized filename from a catalog.
Attribute format: "signature:context:string"
(no colon in any of signature, context and string)
Lookup is done for the top preferred language only.
Lookup fails if a comment is present in the catalog entry.
\param localizedFileName A pre-allocated BString object for the result
of the lookup.
\param ref An entry_ref with an attribute holding data for catalog lookup.
\param traverse Determines if symlinks should be traversed.
\returns A status code.
\retval B_OK: success
\retval B_ENTRY_NOT_FOUND: failure. Attribute not found, entry not found
in catalog, etc.
*/
/*!
\fn BCatalog* BLocaleRoster::_GetCatalog(BCatalog* catalog,
vint32* catalogInitStatus)
\brief Get the current image catalog.
This function initializes and returns the catalog for the calling image
(application, add-on, or shared library). Note that it doesn't allow to
specify a fingerprint. The language will be selected from the user
preferences.
This function is used by the Locale Kit macros.
\warning This function needs the calling image to be linked with
liblocalestub.a
\returns The catalog, if it was loaded successfully.
\param catalog The catalog to load. The pointer location is used to identify
the image for which to load the catalog.
\param catalogInitStatus the state of the catalog. This will be set to true
on the first call for a given catalog, and if already true the function
will do nothing on subsequent calls.
*/