xref: /haiku/docs/user/locale/LocaleRoster.dox (revision edc845a32393ce99cdc62cbc60216941f745165f)

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

	\since Haiku R1
*/


/*!
	\fn BLocaleRoster::BLocaleRoster()
	\brief Constructor. Does nothing.

	\since Haiku R1
*/


/*!
	\fn BLocaleRoster::~BLocaleRoster()
	\brief Destructor. Does nothing.

	\since Haiku R1
*/


/*!
	\fn BLocaleRoster* BLocaleRoster::Default()
	\brief Returns default BLocalRoster.

	\since Haiku R1
*/


/*!
	\fn status_t BLocaleRoster::Refresh()
	\brief Refreshes the BLocalRoster.

	\since Haiku R1
*/


/*!
	\fn status_t BLocaleRoster::GetDefaultTimeZone(BTimeZone* timezone) const
	\brief Get the default timezone.

	\since Haiku R1
*/


/*!
	\fn status_t BLocaleRoster::GetLanguage(const char* languagecode,
		BLanguage** _language) const
	\brief Instantiate a language from its code.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\fn status_t BLocaleRoster::GetAvailableLanguages(BMessage* message) const
	\brief Fills \c message with 'language'-fields containing the language
	       ID(s) of all available languages.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/