[haiku-commits] r37898 - in haiku/trunk/docs/user: . locale
- From: pulkomandy@xxxxxxxxxxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Wed, 4 Aug 2010 14:01:38 +0200 (CEST)
Author: pulkomandy
Date: 2010-08-04 14:01:38 +0200 (Wed, 04 Aug 2010)
New Revision: 37898
Changeset: http://dev.haiku-os.org/changeset/37898
Modified:
haiku/trunk/docs/user/book.dox
haiku/trunk/docs/user/locale/Catalog.dox
haiku/trunk/docs/user/locale/Locale.dox
haiku/trunk/docs/user/locale/localeintro.dox
Log:
* Add the locale kit to the main page
* Complete and correct some parts of locale and catalog classes reference
* Ensure the methods are prefixed with the class name so doxygen knows where
they belong.
Modified: haiku/trunk/docs/user/book.dox
===================================================================
--- haiku/trunk/docs/user/book.dox 2010-08-04 11:11:56 UTC (rev 37897)
+++ haiku/trunk/docs/user/book.dox 2010-08-04 12:01:38 UTC (rev 37898)
@@ -5,6 +5,7 @@
- \ref app | \link app_intro \em Introduction \endlink
- \ref drivers
+ - \ref locale | \link locale_intro \em Introduction \endlink
- \ref midi1
- \ref midi2 | \link midi2_intro \em Introduction \endlink
- \ref support | \link support_intro \em Introduction \endlink
@@ -27,6 +28,8 @@
\brief Collection of utility classes that are used throughout the API.
\defgroup libbe (libbe.so)
\defgroup libroot (libroot.so)
+ \defgroup locale (liblocale.so)
+ \brief Collection of classes for localizing applications.
*/
///// Subgroups /////
Modified: haiku/trunk/docs/user/locale/Catalog.dox
===================================================================
--- haiku/trunk/docs/user/locale/Catalog.dox 2010-08-04 11:11:56 UTC (rev
37897)
+++ haiku/trunk/docs/user/locale/Catalog.dox 2010-08-04 12:01:38 UTC (rev
37898)
@@ -1,7 +1,7 @@
/*!
\class BCatalog
\ingroup locale
-\brief class handling string localization
+\brief class handling string localization.
BCatalog is the class that allows you to perform string localization. This
means
you give it a string in english, and it automatically returns the translation
of
@@ -28,11 +28,29 @@
but it will also allow to build the base catalog, the one that you will send to
the translator team, from your sourcecode.
+\section Chaining of catalogs
+The catalogs you get from the locale kit are designed to use a fallback system
+so that the user get strings in the language he's the more fluent with,
+depending onwhat isavailable.
+
+For example, if the user set hislanguage preferences as french(France),
spanish,
+english, when an application loads a catalog, the following rules are used :
+ \item Try to load a french(France) catalog. If it is found, this catalog
+will automatically include strings from the generic french catalog.
+ \item Try to load a generic french catalog.
+ \item Try to load a generic spanish catalog.
+ \item Try to load a generic english catalog.
+ \item If all of them failed, use the strings that ar ein the source
code.
+
+Note that french(France) will failback to french, but then directly to the
+language in the source code. This avoids mixing 3 or more languages in the same
+application if the catalogs are incomplete and avoids confusion.
+
*/
/*!
-\fn BCatalog(const char* signature, const char* language = NULL, uint32
fingerprint = 0)
-\brief Construct a catalog for the given application
+\fn BCatalog::BCatalog(const char* signature, const char* language = NULL,
uint32 fingerprint = 0)
+\brief Construct a catalog for the given application.
This constructor builds a catalog for the application with the given mime
signature. In Haiku, the mime signature is used as a way to uniquely identify a
@@ -51,9 +69,9 @@
*/
/*!
-\fn const char* GetString(const char* string, const char* context = NULL,
const char* comment = NULL)
+\fn const char* BCatalog::GetString(const char* string, const char* context =
NULL, const char* comment = NULL)
\fn const char* GetString(uint32 id)
-\brief Get a string from the catalog
+\brief Get a string from the catalog.
This method access the data of the catalog and reeturns you the translated
version of the string. You must pass it the context where the string is, as
@@ -73,3 +91,81 @@
*/
+/*!
+\fn const char* BCatalog::GetStringNoAutoCollate(const char* string, const
char* context = NULL, const char* comment = NULL)
+\fn const char* GetStringNoAutoCollate(uint32 id)
+\brief Get a string from the catalog, without registering it for
collectcatkeys.
+
+This function does exactly the same thing as GetString, except it will not be
+parsed by the collectcatkeys tool. This allows you, for example, to translate a
+string constant that you declared at another place, without getting a warning
+message from collectcatkeys.
+
+*/
+
+
+/*!
+\fn status_t BCatalog::GetData(const char* name, BMessage* msg)
+\fn status_t BCatalog::GetData(uint32 id, BMessage* msg)
+\brief Get custom data from the catalog.
+
+This function allows you to localize something else than raw text. This may
+include pictures, sounds, videos, or anything else. Note there is no support
for
+generatinga catalog with such data inside, and the current format may not
+support it. If you need to localize data that is not text, it is advised to
+handle it by yourself.
+
+*/
+
+/*!
+\fn status_t BCatalog::GetSignature(BString* sig)
+\brief Get the catalog mime-signature.
+
+This function fills the sig string with the mime-signature associated to the
+catalog.
+
+*/
+
+/*!
+\fn status_t BCatalog::GetLanguage(BString* lang)
+\brief Get the catalog language.
+
+This function fills the lang string with the language name for the catalog.
+*/
+
+/*!
+\fn status_t BCatalog::GetFingerprint(uint32* fp)
+\brief Get the catalog fingerprint.
+
+This function setsfp to the fingerprint of the catalog. This allows you to
check
+which version of the sourcecode this catalog was generated from.
+*/
+
+/*!
+\fn status_t BCatalog::SetCatalog(const char* signature, uint32 fingerprint)
+\brief Reload the string data.
+
+This function reloads the data for the given signature and fingerprint.
+*/
+
+/*!
+\fn status_t BCatalog::InitCheck()
+\brief Check if the catalog is in an useable state.
+
+This function returns B_OK if the catalog is initialized properly.
+*/
+
+/*!
+\fn int32 BCatalog::CountItems()
+\brief Returns the number of items in the catalog.
+
+This function returns the number of strings in the catalog.
+*/
+
+/*!
+\fn BCatalogaddOn* BCatalog::CatalogAddOn()
+\brief Returns the internal storage for this catalog.
+
+This function returns the internal storage class used by this catalog.
+You should not have to use it.
+*/
Modified: haiku/trunk/docs/user/locale/Locale.dox
===================================================================
--- haiku/trunk/docs/user/locale/Locale.dox 2010-08-04 11:11:56 UTC (rev
37897)
+++ haiku/trunk/docs/user/locale/Locale.dox 2010-08-04 12:01:38 UTC (rev
37898)
@@ -12,7 +12,7 @@
*/
/*!
-\fn const BCollator* Collator() const
+\fn const BLocale::BCollator* Collator() const
\brief Returns the collator associated to this locale
Returns the collator in use for this locale, allowing you to use it to sort a
@@ -21,7 +21,7 @@
*/
/*!
-\fn const BCountry* Country() const
+\fn const BLocale::BCountry* Country() const
\brief Returns the country associated to this locale
A locale is defined by the combination of a country and a language. This
@@ -31,14 +31,14 @@
*/
/*!
-\fn const BLanguage* Language() const
+\fn const BLocale::BLanguage* Language() const
\brief Returns the language associated to this locale
*/
/*!
-\fn int StringCompare(const char* s1, const char* s2) const
-\fn int StringCompare(const BString* s1, const BString* s2) const
+\fn int BLocale::StringCompare(const char* s1, const char* s2) const
+\fn int BLocale::StringCompare(const BString* s1, const BString* s2) const
\brief Compares two strings using the locale's collator
These methods are short-hands to Collator()->StringCompare.
@@ -46,7 +46,7 @@
*/
/*!
-\fn void GetSortKey(const char* string, BString* key) const
+\fn void BLocale::GetSortKey(const char* string, BString* key) const
\brief Computes the sort key of a string
This method is a short-hand to Collator()->GetSortKey.
Modified: haiku/trunk/docs/user/locale/localeintro.dox
===================================================================
--- haiku/trunk/docs/user/locale/localeintro.dox 2010-08-04 11:11:56 UTC
(rev 37897)
+++ haiku/trunk/docs/user/locale/localeintro.dox 2010-08-04 12:01:38 UTC
(rev 37898)
@@ -6,4 +6,13 @@
translations at runtime, but also more complex tasks such as formating numbers,
dates, and times in a way that match the locale preferences of the user.
+The main way to access locale data is through the be_locale_roster. This is a
+global instance of the BLocaleRoster class, storing the data for localizing an
+application according to the user's preferred settings. The locale roster also
+acts as a factory to instanciate most of the other classes. However, there are
+some cases where you will need to instanciate another class by yourself, to
+use it with custom settings. For example, you may need to format a date with
+a fixed format in english for including in an e-mail header, as it is the only
+format accepted there.
+
*/
Other related posts:
- » [haiku-commits] r37898 - in haiku/trunk/docs/user: . locale - pulkomandy
