i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge work by John Scipione on the Haiku Book.

Browse Source 
* Some new classes documented
 * Screenshots for the interface kit controls
 * A lot of typo fixes
 * Some css tweaks

This has some backporting to the current version of Doxygen, since 
there are experiments to get coloring similar to the one in the Be 
Book that will hopefully be upstreamed in Doxygen.


git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@42608 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Adrien Destugues
2011-08-09 21:46:13 +00:00
parent 61a02f6d99
commit a33f8fbdec
43 changed files with 7151 additions and 2814 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/locale/Catalog.dox
+201 -174
View File
@@ -1,221 +1,248 @@
/*!
\class BCatalog
\ingroup locale
\brief Class handling string localization.
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Axel Dörfler, [email protected]
* John Scipione, [email protected]
* Oliver Tappe, [email protected]
*
* Corresponds to:
* /trunk/headers/os/locale/Catalog.h rev 42274
* /trunk/src/kits/locale/Catalog.cpp rev 42274
*/
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
this string in the user's specified language, if available.
Most of the time, you don't have to deal with BCatalog directly. You use the
translation macros instead. However, there are some cases where you will have to
use catalogs directly. These include :
\li Tools for managing catalogs : if you want to add, remove or edit
entries in a catalog, you need to do it using the BCatalog class.
\li Accessing catalogs other than your own : the macros only grant you
access to the catalog linked with your application. To access other catalogs
(for example if you create a script interpreter and want to localize the
scripts), you will have to open a catalog associated with your script.
\section macros Using the macros
You don't have to do much in your program to handle catalogs. You must first
set the B_TRANSLATE_CONTEXT define to a string that identifies which part of the
application the strings you will translate are in. This allows the translators
to keep track of the strings in the catalog more easily, and find where they are
visible in the application. then, all you have to do, is enclose any string you
want to make translatable in the B_TRANSLATE() macro. This macro has two uses,
it will allow your text to be replaced at run-time by the proper localized one,
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 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 most fluent with,
depending on what catalogs are available.
For example, if the user sets his language preferences as french(France),
spanish, english, when an application loads a catalog, the following rules are
used :
\li Try to load a french(France) catalog. If it is found, this catalog
will automatically include strings from the generic french catalog.
\li Try to load a generic french catalog.
\li Try to load a generic spanish catalog.
\li Try to load a generic english catalog.
\li If all of them failed, use the strings that are in 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::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
catalog and match it with the corresponding application.
If you don't specify a language, the system default list will be used.
The language is passed here as a 2 letter ISO code.
The fingerprint is a way to check that the catalog that will be loaded matches
the current version of the application. A catalog made for a different version
of the application can be loaded if you set the fingerprint to 0. This is
usually not a problem, it only means that some strings may not be translated
properly. But if you want to provide different versions of your application, it
may be useful to separate their catalogs.
\param signature Mime-signature of the application for which to load a catalog.
\param language The language of the catalog to load. If NULL, the user settings
will be used.
\param fingerprint The fingerprint version-info for the catalog to load. If 0,
the fingerprint will not be checked,and any version of the catalog will be
loaded.
*/
/*!
\fn const char* BCatalog::GetString(const char* string, const char* context = NULL, const char* comment = NULL)
\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
the same string may appear somewhere else and need a differnet translation.
The comment is optional. It is meant as an help to translators, when the string
alone is not helpful enough or there are special things to note. The comment is
also used as a way to uniquely identify a string, so if two identical strings
share the same context, it is still possible to provide different translations.
\returns The translated string, or the one passed as a parameter if no
translation was found.
\param string The string to translate.
\param context The context where the string is located.
\param comment Supplementary comment for translators.
*/
/*!
\fn const char* BCatalog::GetString(uint32 id)
\brief Get a string by id from the catalog.
The id based version of this method is slightly faster, as it doesn't have to
compute the hash from the 3 parameters. However, it will fail if there is an
hash collision, so you should still fallback to the first one in case of
problems. Also note that the hash value may be different from one catalog to
another, depending on the file format they are stored in, so you shouldn't rely
on this method unless you are sure you can keep all the catalog files under
control.
\returns The translated string if found, or an empty string.
\param id The identifier of the string.
*/
/*!
\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.
\returns The translated string, or the one passed as a parameter if no
translation was found.
\param string The string to translate.
\param context The context where the string is located.
\param comment Supplementary comment for translators.
\file Catalog.h
\brief Provides the BCatalog class.
*/
/*!
\fn status_t BCatalog::GetData(const char* name, BMessage* msg)
\brief Get custom data from the catalog.
\class BCatalog
\ingroup locale
\brief Class handling string localization.
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.
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 this string in the user's specified language, if available.
\returns An error code.
\param name The name of the data to retrieve.
\param msg The BMessage to fill in with the data.
Most of the time, you don't have to deal with BCatalog directly. You use
the translation macros instead. However, there are some cases where you
will have to use catalogs directly. These include :
\li Tools for managing catalogs : if you want to add, remove or edit
entries in a catalog, you need to do it using the BCatalog class.
\li Accessing catalogs other than your own : the macros only grant you
access to the catalog linked with your application. To access
other catalogs (for example if you create a script interpreter and
want to localize the scripts), you will have to open a catalog
associated with your script.
\section macros Using the macros
You don't have to do much in your program to handle catalogs. You must
first set the B_TRANSLATE_CONTEXT define to a string that identifies which
part of the application the strings you will translate are in. This allows
the translators to keep track of the strings in the catalog more easily,
and find where they are visible in the application. then, all you have to
do, is enclose any string you want to make translatable in the
B_TRANSLATE() macro. This macro has two uses, it will allow your text to
be replaced at run-time by the proper localized one, 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 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 most fluent
with, depending on what catalogs are available.
For example, if the user sets his language preferences as french(France),
spanish, english, when an application loads a catalog, the following rules
are used :
\li Try to load a french(France) catalog. If it is found, this catalog
will automatically include strings from the generic french catalog.
\li Try to load a generic french catalog.
\li Try to load a generic spanish catalog.
\li Try to load a generic english catalog.
\li If all of them failed, use the strings that are in 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 status_t BCatalog::GetData(uint32 id, BMessage* msg)
\brief Get custom data from the catalog.
\fn BCatalog::BCatalog(const char* signature, const char* language = NULL,
uint32 fingerprint = 0)
\brief Construct a catalog for the given application.
As for GetString, the id-based version may be subject to hash-collisions, but is
faster.
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 catalog and match it with the corresponding application.
Note the current catalog format doesn't allow storing custom data in catalogs,
so the only way to use this function is providing your own catalog add-on for
storing the data.
If you don't specify a language, the system default list will be used.
The language is passed here as a 2 letter ISO code.
The fingerprint is a way to check that the catalog that will be loaded
matches the current version of the application. A catalog made for a
different version of the application can be loaded if you set the
fingerprint to \c 0. This is usually not a problem, it only means that
some strings may not be translated properly. But if you want to provide
different versions of your application, it may be useful to separate their
catalogs.
\param signature Mime-signature of the application for which to load a
catalog.
\param language The language of the catalog to load. If NULL, the user
settings will be used.
\param fingerprint The fingerprint version-info for the catalog to load.
If \c 0, the fingerprint will not be checked,and any version of the
catalog will be loaded.
*/
/*!
\fn status_t BCatalog::GetSignature(BString* sig)
\brief Get the catalog mime-signature.
\fn const char* BCatalog::GetString(const char* string,
const char* context = NULL, const char* comment = NULL)
\brief Get a string from the catalog.
This function fills the sig string with the mime-signature associated to 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
the same string may appear somewhere else and need a differnet translation.
The comment is optional. It is meant as an help to translators, when the
string alone is not helpful enough or there are special things to note.
The comment is also used as a way to uniquely identify a string, so if two
identical strings share the same context, it is still possible to provide
different translations.
\param sig The string where to copy the signature.
\returns An error code.
\param string The string to translate.
\param context The context where the string is located.
\param comment Supplementary comment for translators.
\returns The translated string, or the one passed as a parameter if no
translation was found.
*/
/*!
\fn status_t BCatalog::GetLanguage(BString* lang)
\brief Get the catalog language.
\fn const char* BCatalog::GetString(uint32 id)
\brief Get a string by id from the catalog.
This function fills the lang string with the language name for the catalog.
The id based version of this method is slightly faster, as it doesn't
have to compute the hash from the 3 parameters. However, it will fail
if there is an hash collision, so you should still fallback to the first
one in case of problems. Also note that the hash value may be different
from one catalog to another, depending on the file format they are stored
in, so you shouldn't rely on this method unless you are sure you can keep
all the catalog files under control.
\param sig The string where to copy the language.
\returns An error code.
\param id The identifier of the string.
\returns The translated string if found, or an empty string.
*/
/*!
\fn status_t BCatalog::GetFingerprint(uint32* fp)
\brief Get the catalog fingerprint.
\fn status_t BCatalog::GetData(const char* name, BMessage* msg)
\brief Get custom data from the catalog.
This function setsfp to the fingerprint of the catalog. This allows you to check
which version of the sourcecode this catalog was generated from.
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 generating a 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.
\returns An error code.
\param fp The integer to set to the fingerprint value.
\param name The name of the data to retrieve.
\param msg The BMessage to fill in with the data.
\returns An error code.
*/
/*!
\fn status_t BCatalog::SetCatalog(const char* signature, uint32 fingerprint)
\brief Reload the string data.
\fn status_t BCatalog::GetData(uint32 id, BMessage* msg)
\brief Get custom data from the catalog.
This function reloads the data for the given signature and fingerprint.
As for GetString, the id-based version may be subject to hash-collisions,
but is faster.
\returns An error code.
\param signature The signature of the catalog youwant to load
\param fingerprint The fingerprint of the catalog you want to load.
Note the current catalog format doesn't allow storing custom data in
catalogs, so the only way to use this function is providing your own
catalog add-on for storing the data.
*/
/*!
\fn status_t BCatalog::InitCheck() const
\brief Check if the catalog is in an useable state.
\fn status_t BCatalog::GetSignature(BString* sig)
\brief Get the catalog mime-signature.
This function returns B_OK if the catalog is initialized properly.
This function fills the sig string with the mime-signature associated to the
catalog.
\param sig The string where to copy the signature.
\returns An error code.
*/
/*!
\fn int32 BCatalog::CountItems()
\brief Returns the number of items in the catalog.
\fn status_t BCatalog::GetLanguage(BString* lang)
\brief Get the catalog language.
This function returns the number of strings in the catalog.
This function fills the lang string with the language name for the catalog.
\param lang The string where to copy the language.
\returns An error code.
*/
/*!
\fn BCatalogaddOn* BCatalog::CatalogAddOn()
\brief Returns the internal storage for this catalog.
\fn status_t BCatalog::GetFingerprint(uint32* fp)
\brief Get the catalog fingerprint.
This function returns the internal storage class used by this catalog.
You should not have to use it.
This function setsfp to the fingerprint of the catalog. This allows you
to check which version of the sourcecode this catalog was generated from.
\param fp The integer to set to the fingerprint value.
\returns An error code.
*/
/*!
\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.
\param signature The signature of the catalog youwant to load
\param fingerprint The fingerprint of the catalog you want to load.
\returns An error code.
*/
/*!
\fn status_t BCatalog::InitCheck() const
\brief Check if the catalog is in an useable state.
\returns \c B_OK if the catalog is initialized properly.
*/
/*!
\fn int32 BCatalog::CountItems()
\brief Returns the number of items in the catalog.
\returns the number of strings in the catalog.
*/
/*!
\fn BCatalogaddOn* BCatalog::CatalogAddOn()
\brief Returns the internal storage for this catalog.
\returns the internal storage class used by this catalog. You should
not have to use it.
*/
docs/user/locale/Collator.dox
+155 -84
View File
@@ -1,154 +1,225 @@
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Axel Dörfler, [email protected]
* Adrien Destugues <[email protected]>
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/locale/Collator.h rev 42274
* /trunk/src/kits/locale/Collator.cpp rev 42274
*/
/*!
\class BCollator
\ingroup locale
\brief Class for handling collation of string
\file Collator.h
\brief Provides the BCollator class.
*/
BCatalog is designed to handle collations (sorting) of strings.
The collation is done using a set of rules that changes from a country to another.
For example, in spanish, 'ch' is consiidered as a letter and is sorted between 'c' and 'd'.
This class is alsoable to perform natural sorting, so that '2' is sorted before '10',
which is not the case when you do a simple ASCII sort.
\warning This class is not multithread-safe, as Compare() and GetKey() change
the ICUCollator (the strength). So if you want to use a BCollator from
more than one thread, you need to protect it with a lock.
/*!
\class BCollator
\ingroup locale
\brief Class for handling collation of string
BCatalog is designed to handle collations (sorting) of strings.
The collation is done using a set of rules that changes from a country
to another. For example, in spanish, 'ch' is consiidered as a letter
and is sorted between 'c' and 'd'. This class is alsoable to perform
natural sorting, so that '2' is sorted before '10', which is not the
case when you do a simple ASCII sort.
\warning This class is not multithread-safe, as Compare() and GetKey()
change the ICUCollator (the strength). So if you want to use a
BCollator from more than one thread, you need to protect it with a lock.
*/
/*!
\fn BCollator::BCollator()
\brief Construct a collator for the default locale.
\fn BCollator::BCollator()
\brief Construct a collator for the default locale.
Empty contructor.
*/
/*!
\fn BCollator::BCollator(const char* locale, int8 strength = B_COLLATE_PRIMARY, bool ignorePunctiation = false)
\brief Construct a collator for the given locale.
\fn BCollator::BCollator(const char* locale,
int8 strength = B_COLLATE_PRIMARY, bool ignorePunctuation = false)
\brief Construct a collator for the given locale.
This constructor loads the data for the given locale. You can also adjust the strength and
tell if the collator should take punctuation into account when sorting.
This constructor loads the data for the given locale. You can also
adjust the strength and tell if the collator should take punctuation
into account when sorting.
\param locale The \a locale.
\param strength The collator class provide four level of strength. These
define the handling of various things.
\li \c B_COLLATE_PRIMARY doesn't differentiate e from é,
\li \c B_COLLATE_SECONDARY takes letter accents into account,
\li \c B_COLLATE_TERTIARY is case sensitive,
\li \c B_COLLATE_QUATERNARY is very strict. Most of the time you
shouldn't need to go that far.
\param ignorePunctuation Ignore punctuation in the Collator when sorting.
*/
/*!
\fn BCollator::BCollator(BMessage* archive)
\brief Unarchive a collator.
\fn BCollator::BCollator(BMessage* archive)
\brief Unarchive a collator from a message.
\param archive The message to unarchive the BCollator from.
*/
/*!
\fn BCollator::BCollator(const BCollator& other)
\brief Copy constructor.
\fn BCollator::BCollator(const BCollator& other)
\brief Copy constructor.
Constructs a BCollator by making a copy of another BCollator.
\param other The BCollator to copy from.
*/
/*!
\fn BCollator::~Bcollator()
\brief Destructor.
\fn BCollator::~BCollator()
\brief Destructor.
Standard destructor method.
*/
/*!
\fn Bcollator& BCollator::operator=(const BColltr& other)
\brief Assignment operator.
\fn Bcollator& BCollator::operator=(const BCollator& other)
\brief Assignment operator.
\param other the BCollator to assign from.
*/
/*!
\fn void BCollator::SetDefaultStrength(int8 strength)
\brief Set the strength of the collator.
\fn void BCollator::SetDefaultStrength(int8 strength)
\brief Set the strength of the collator.
The collator class provide four level of strength. These define the handling of
various things.
\item B_COLLATE_PRIMARY doesn't differenciate e from é,
\item B_COLLATE_SECONDARY takes them into account,
\item B_COLLATE_TERTIARY is case sensitive,
\item B_COLLATE_QUATERNARY is very strict. Most of the time you shouldn't need
to go that far.
Note that the \a strength can also be given on a case-by-case basis
when calling other methods.
Note the strength can also be given on a case-by-case basis when calling other
methods.
\param strength The strength the catalog should use as default.
\param strength The collator class provide four level of strength.
These define the handling of various things.
\li \c B_COLLATE_PRIMARY doesn't differentiate e from é,
\li \c B_COLLATE_SECONDARY takes letter accents into account,
\li \c B_COLLATE_TERTIARY is case sensitive,
\li \c B_COLLATE_QUATERNARY is very strict. Most of the time you
shouldn't need to go that far.
*/
/*!
\fn int8 BCollator::DefaultStrength() const
\brief Returns the current strength of this catalog.
\fn int8 BCollator::DefaultStrength() const
\brief Get the current strength of this catalog.
\returns the current strength of this catalog.
*/
/*!
\fn void BCollator::SetIgnorePunctuation(bool ignore)
\brief Enable or disable punctuation handling
\fn void BCollator::SetIgnorePunctuation(bool ignore)
\brief Enable or disable punctuation handling
This function enables or disables the handling of punctuations.
This function enables or disables the handling of punctuations.
\param ignore Boolean telling if the punctuation should be ignored.
\param ignore Boolean telling if the punctuation should be ignored.
*/
/*!
\fn bool BCollator::IgnorePunctuation() const
\brief Return the behaviour ofthe collator regarding punctuation.
\fn bool BCollator::IgnorePunctuation() const
\brief Gets the behavior of the collator regarding punctuation.
This function returns true if the collator will take punctuation into account
when sorting.
This function returns \c true if the collator will take punctuation into
account when sorting.
*/
/*!
\fn satus_t BCollator::GetSortKey(const char* string, BString* key, int8 strength) const
\brief Compute the sortkey of a string
\fn satus_t BCollator::GetSortKey(const char* string, BString* key,
int8 strength) const
\brief Compute the sortkey of a string.
A sortkey is a modified version of the string that you can use for faster
comparison with other sortkeys, using strcmp or a similar ASCII comparison. If
you need to compare a string with other ones a lot of times, storing the sortkey
will allow you to do the comparisons faster.
A sortkey is a modified version of the string that you can use for faster
comparison with other sortkeys, using strcmp or a similar ASCII comparison.
If you need to compare a string with other ones a lot of times, storing
the sortkey will allow you to do the comparisons faster.
\param string String from which to compute the sortkey.
\param key The resulting sortkey.
\param strength The strength to use for computing the sortkey.
\param string String from which to compute the sortkey.
\param key The resulting sortkey.
\param strength The \a strength to use for computing the sortkey.
\returns B_OK if everything went well.
\returns B_OK if everything went well.
*/
/*!
\fn int BCollator::Compare(const char* s1, const char* s2, int8 strength) const
\brief Compare two strings.
\fn int BCollator::Compare(const char* s1, const char* s2,
int8 strength) const
\brief Compare two strings.
This function returns the difference betweens the two strings, in a way similar
to strcmp.
Returns the difference betweens the two strings similar to strcmp().
\param s1,s2 The strings to compare.
\returns The comparison value. 0 if the strings are equal, negative if s1<s2,
positive if s1>s2.
\param s1 The first string to compare.
\param s2 The second string to compare.
\param strength The \a strength to use for comparing the strings.
\retval 0 if the strings are equal.
\retval <0 if s1 is less than s2.
\retval >0 if s1 is greater than s2.
*/
/*!
\fn bool BCollator::Equal(const char* s1, const char* s2, int8 strength) const
\brief Checks two strings for equality.
\fn bool BCollator::Equal(const char* s1, const char* s2,
int8 strength) const
\brief Checks two strings for equality.
Compares two strings for equality. Note that different strings may end up being
equal, for example if the differences are only in case and punctuation,
depending on the strenght used. Quaterary strength will make this function
return true only if the strings are byte-for-byte identical.
Compares two strings for equality. Note that different strings may end
up being equal, for example if the differences are only in case and
punctuation, depending on the strength used. Quaterary strength will
make this function return true only if the strings are byte-for-byte
identical.
\returns True if the two strings are identical.
\param s1 The first string to compare.
\param s2 The second string to compare.
\param strength The \a strength to use for comparing the strings.
\returns \c true if the strings are identical, otherwise \c false.
*/
/*!
\fn bool BCollator::Greater(cosnt char* s1, const char* s2, int8 strength) const)
\brief Tell if a string is greater than another.
\fn bool BCollator::Greater(cosnt char* s1, const char* s2,
int8 strength) const
\brief Determine if a string is greater than another.
\returns True if s1 is greater (not equal) than s2.
\note !Greater(s1, s2) does the same thing as Greater(s2, s1)
\note !Greater(s1, s2) does the same thing as Greater(s2, s1)
\param s1 The first string to compare.
\param s2 The second string to compare.
\param strength The \a strength to use for comparing the strings.
\returns \c true if s1 is greater than, but not equal to, s2.
*/
/*!
\fn bool BCollator::GreaterOrEqual(cosnt char* s1, const char* s2, int8 strength) const)
\brief Tell if a string is greater than another.
\fn bool BCollator::GreaterOrEqual(cosnt char* s1, const char* s2,
int8 strength) const
\brief Tell if a string is greater than another.
\returns True if s1 is greater or equal to s2.
\param s1 The first string to compare.
\param s2 The second string to compare.
\param strength The \a strength to use for comparing the strings.
\returns \c true if s1 is greater or equal than s2.
*/
/*!
\fn static BArchivable* BCollator::Instanciate(BMessage* archive)
\brief Unarchive the collator
\fn static BArchivable* BCollator::Instantiate(BMessage* archive)
\brief Unarchive the collator
Thif function allows you to restore a collator that you previously archived. It
is faster to do that than to buid a collator and set it up by hand every time
you need it with the same settings.
This function allows you to restore a collator that you previously
archived. It is faster to do that than to buid a collator and set
it up by hand every time you need it with the same settings.
\param archive The message to restore the collator from.
\returns A BArchivable object containing the BCollator or \c NULL.
*/
docs/user/locale/Country.dox
+66 -45
View File
@@ -1,70 +1,91 @@
/*!
\class BCountry
\ingroup locale
\brief Class representing a country
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Axel Dörfler, [email protected].
* Adrien Destugues, [email protected].
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/locale/Country.h rev 42274
* /trunk/src/kits/locale/Country.cpp rev 42274
*/
BCountry provides all the information about a particular country.
This includes the country flag (as an HVIF icon), the localized name of the
country, and the iso country code.
Date, timeand numer formatting also depends to some extent of the language,
so they are done in the BLocale classinstead.
/*! \file Country.h
\brief BCountry class definition.
*/
/*!
\fn BCountry::BCountry(const char* languageCode, const char* countryCode)
\brief Constructor.
Construct a BCountry from a language and a country code.
/*! \class BCountry
\ingroup locale
\brief Class representing a country
BCountry provides all the information about a particular country.
This includes the country flag (as an HVIF icon), the localized name
of the country, and the ISO country code.
Date, time, and numer formatting also depends to some extent on the
language used, so they are found in the BLocale class instead.
*/
/*!
\fn bool BCountry::GetName(BString& name) const
\brief Get the name of the country
Fills in the name parameter with the name of the country, in the user's locale.
*/
/*!
\fn const char* BCountry::Code() const
\brief Returns the country code.
\fn BCountry::BCountry(const char* countryCode)
\brief Initialize a BCountry from a country code.
\param countryCode The country code to initialize from.
*/
/*!
\fn status_t BCountry::GetIcon(BBitmap* result) const;
\brief Render the country's flag to the given BBitmap
\fn BCountry::BCountry(const BCountry& other)
\brief Initialize a BCountry from another BCountry object.
This function renders the Country's flag to the given BBitmap. The bitmap
should already be set to the pixel format and size you want to use.
The flag is stored in HVIF format and can be rendered atany size and color depth.
\param result The BBitmap to drag the flag to.
\returns B_OK if the drawing was successful.
\param other The BCountry object to initialize from.
*/
/*!
\fn const char* BCountry::GetLocalizedString(uint32 id) const;
\brief Get one of the default localized strings for this country.
The strings include monetary symbols and other similar things.
\fn BCountry& BCountry::operator=(const BCountry& other)
*/
/*!
\fn int8 BCountry::Measurement() const
\brief Returrns the measurement used in this country.
\returns B_METRIC for the metric system, or B_US for the USA's system.
\fn BCountry::~BCountry()
\brief Destructor method.
*/
/*!
\fn int BCountry::GetTimeZones(BList& timezones) const
\brief Returns all the timeaones used in this country.
\fn bool BCountry::GetName(BString& name) const
\brief Get the name of the country.
The count may vary from 0 for countries where there is no data, to twelve, for Russia.
\returns The number of timezones that were added to the list.
Fills in the name parameter with the name of the country in the
language set by the user's locale.
*/
/*!
\fn const char* BCountry::Code() const
\brief Gets the ISO country code for the country.
\returns The ISO country code for the country.
*/
/*!
\fn status_t BCountry::GetIcon(BBitmap* result) const;
\brief Render the country's flag to the given BBitmap.
This function renders the country's flag to the given BBitmap. The bitmap
should already be set to the pixel format and size you want to use.
The flag is stored in HVIF format so it can be rendered at any size and
color depth.
\param result The BBitmap to drag the flag into.
\returns \c B_OK if the drawing was successful.
*/
docs/user/locale/Locale.dox
+453 -90
View File
@@ -1,154 +1,517 @@
/*!
\class BLocale
\ingroup locale
\brief Class for representing a locale and its settings.
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Axel Dörfler, [email protected].
* John Scipione, [email protected]
* Oliver Tappe, [email protected].
*
* Corresponds to:
* /trunk/headers/os/locale/Locale.h rev 42274
* /trunk/src/kits/locale/Locale.cpp rev 42274
*/
A locale is defined by the combination of a country and a language. Using these
two informations, it is possible to determine the format to use for date, time,
and number formatting. The BLocale class also provide collators, which allows
you to sort a list of strings properly depending on a set of rules about
accented chars and other special cases that vary over the different locales.
BLocale is also the class to use when you want to perform formatting or parsing
of dates, times, and numbers, in the natural language of the user.
*/
/*!
\fn const BCollator* BLocale::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
set of strings.
\file Locale.h
\brief Provides the BLocale class.
*/
/*! \class BLocale
\ingroup locale
\brief Class for representing a locale and its settings.
A locale is defined by the combination of a country and a language.
Using these two informations, it is possible to determine the format
to use for date, time, and number formatting. The BLocale class also
provide collators, which allows you to sort a list of strings properly
depending on a set of rules about accented chars and other special
cases that vary over the different locales.
BLocale is also the class to use when you want to perform formatting
or parsing of dates, times, and numbers, in the natural language of
the user.
*/
/*!
\fn const BCountry* BLocale::Country() const
\brief Returns the country associated to this locale.
A locale is defined by the combination of a country and a language. This
method gets the country part of this information, so you can access the
data that is not language-dependant (such as the country flag).
\fn BLocale::BLocale(const BLanguage* language,
const BFormattingConventions* conventions)
\brief Initializes a BLocale object corresponding to the passed in
\a language and \a conventions.
*/
/*!
\fn const BLanguage* BLocale::Language() const
\brief Returns the language associated to this locale.
\fn BLocale::BLocale(const BLocale& other)
\brief Initializes a BLocale object.
*/
/*!
\fn const char* BLocale::Code() const
\brief Returns the locale code.
status_t BLocale::GetCollator(BCollator* collator) const
\brief Gets the collator associated to this locale.
This function returns the locale name (such as en_US for united states english).
Returns the collator in use for this locale, allowing you to use it
to sort a set of strings.
*/
/*!
\fn bool BLocale::GetName(BString& name) const
\brief Get the name of the locale.
This function fills the name string with the localized name of this locale.
For example, if the locale us en_US and the user language is french, this function will return "anglais (Etats-Unis)".
\fn BLocale& BLocale::operator=(const BLocale& other)
*/
/*!
\fn void BLocale::SetCountry(const BCountry& newCountry)
\brief Set the country for this locale.
\fn BLocale::~BLocale()
\brief Destructor method.
*/
/*!
\fn void BLocale::SetCollator(const BCollator& newCollator)
\brief Set the collator for this locale.
\fn status_t BLocale::GetCollator(BCollator* collator) const
\brief Sets \a collator object to the default collator for the BLocale.
\param collator A pointer to a BCollator object to fill out.
\returns A status code.
\retval B_OK Everything went well.
\retval B_BAD_VALUE \c NULL \a collator object passed in.
\retval B_ERROR Unable to lock the BLocale.
*/
/*!
\fn void BLocale::SetLanguage(const char* languageCode)
\brief Set the language for this locale.
\fn status_t BLocale::GetLanguage(BLanguage* language) const
\brief Sets \a language object to the default language for the BLocale.
\param language A pointer to a BLanguage object to fill out.
\returns A status code.
\retval B_OK Everything went well.
\retval B_BAD_VALUE \c NULL \a language object passed in.
\retval B_ERROR Unable to lock the BLocale.
*/
/*!
\fn status_t BLocale::FormatDate(char* string, size_t maxSize, time_t time, bool longFormat)
\brief Format a date.
\fn status_t BLocale::GetFormattingConventions(
BFormattingConventions* conventions) const
\brief Sets \a conventions object to the default formatting conventions
for the BLocale.
Fills in the string with a formatted date. The longFormat parameter allows you
to select the short or the full format.
\param conventions A pointer to a BFormattingConventions object to fill out.
\param string The string buffer to fill with the formated date.
\param maxSize The size of the buffer.
\param time The time (in seconds since epoch) to format
\param longFormat If true, uses the long format (with day name, full month name). If false, use the short format, 08/12/2010 or similar.
\returns A status code.
\retval B_OK Everything went well.
\retval B_BAD_VALUE \c NULL \a conventions object passed in.
\retval B_ERROR Unable to lock the BLocale.
*/
/*!
\fn status_t BLocale::FormatDate(BString* string, time_t time, bool longFormat)
\brief Formats a date to a BString.
\fn const char* BLocale::GetString(uint32 id) const
\brief Gets the language string for the locale.
\param id The locale \a id to get the language of.
\internal Assumes a certain order of the string bases.
\returns a blank string in the case of an error or the string "UTF-8"
if there is \a id is set to \a B_CODESET.
*/
/*!
\fn status_t BLocale::FormatDate(BString* string, int*& fieldPositions, int& fieldCount, time_t time, bool longFormat)
\brief Format a date and get information about the different fields.
\fn void BLocale::SetFormattingConventions(
const BFormattingConventions& conventions)
\brief Sets the formatting convention for this locale.
This works the same way as the other FormatDatz methods, but also gives you the
offset of the beginning of each field in the date. This is useful if you need to
split the date in different parts for an user-modifiable area (see the Time
preflet for an example).
To identify the content of each field, you can use GetDateFields.
This function allocates the fieldPositions arrays, you have to free it when you
are finished with it.
\sa GetDateFields
\param conventions The formatting convention to set.
*/
/*!
\fn status_t BLocale::GetDateFields(BDateElement*& fields, int& fieldCount, bool longFormat) const
\brief Get the type of each field in this date format
This function is most often used in combination with FormatDate. FormatDate
gives you the offset of each field in a formated string, anf GetDateFields gives
you the type of the field at a given offset. With these informations, you can
handle the formatted date string as a list of fields that you can split and
alter at will.
\fn void BLocale::SetCollator(const BCollator& newCollator)
\brief Set the collator for this locale.
\param newCollator The collator to set.
*/
/*!
\fn status_t BLocale::GetDateFormat(BString& format, bool longFormat) const
\brief Get the date format string
\fn void BLocale::SetLanguage(const BLanguage& newLanguage)
\brief Set the language for this locale.
This function returns the string used internally to represent a date format.
\param newLanguage The code of the language to set to locale to.
*/
/*!
\fn status_t BLocale::SetDateFormat(const char* formatString, bool longFormat)
\brief Set the date format for this locale
\fn ssize_t BLocale::FormatDate(char* string, size_t maxSize, time_t time,
BDateFormatStyle style) const
\brief Fills in \a string with a formatted date up to \a maxSize bytes for
the given \a time and \a style for the locale.
Thisfunction allows you to define your own date format for specific purposes.
\param string The string buffer to fill with the formatted date.
\param maxSize The size of the buffer.
\param time The time (in seconds since epoch) to format
\param style Specify the long format (with day name, full
month name) or the short format, 08/12/2010 or similar.
\returns The number of bytes written during the date formatting.
\retval B_ERROR Unable to lock the BLocale.
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
\retval B_BAD_VALUE CheckedArrayByteSink overflowed.
\sa BLocale::FormatDateTime(char* target, size_t maxSize,
time_t time, BDateFormatStyle dateStyle,
BTimeFormatStyle timeStyle) const
\sa BLocale::FormatTime(char* string, size_t maxSize, time_t time,
BTimeFormatStyle style) const
*/
/*!
\fn int BLocale::StartOfWeek() const
\brief Returns the day used as start of week in this locale.
\fn status_t BLocale::FormatDate(BString *string, time_t time,
BDateFormatStyle style, const BTimeZone* timeZone) const
\brief Fills in \a string with a formatted date for the given
\a time, \a style, and \a timeZone for the locale.
\param string The string buffer to fill with the formatted date.
\param time The time (in seconds since epoch) to format
\param style Specify the long format (with day name, full
month name) or the short format, 08/12/2010 or similar.
\param timeZone The time zone.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_ERROR Unable to lock the BLocale.
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
\sa BLocale::FormatDateTime(BString* target, time_t time,
BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle,
const BTimeZone* timeZone) const
\sa status_t BLocale::FormatTime(BString* string, time_t time,
BTimeFormatStyle style, const BTimeZone* timeZone) 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
\fn status_t BLocale::FormatDate(BString* string, int*& fieldPositions,
int& fieldCount, time_t time, BDateFormatStyle style) const
\brief Fills in \a string with a formatted date for the given
\a time and \a style for the locale.
These methods are short-hands to Collator()->StringCompare.
\param string The string buffer to fill with the formatted date.
\param fieldPositions ???
\param fieldCount ???
\param time The time (in seconds since epoch) to format
\param style Specify the long format (with day name, full
month name) or the short format, 08/12/2010 or similar.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_ERROR Unable to lock the BLocale or an error formatting the date.
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
\sa BLocale::FormatTime(BString* string, int*& fieldPositions,
int& fieldCount, time_t time, BTimeFormatStyle style) const
*/
/*!
\fn void BLocale::GetSortKey(const char* string, BString* key) const
\brief Computes the sort key of a string
\fn status_t BLocale::GetDateFields(BDateElement*& fields, int& fieldCount,
BDateFormatStyle style) const
\brief Get the type of each field in the date format of the locale.
This method is a short-hand to Collator()->GetSortKey.
This function is most often used in combination with FormatDate().
FormatDate() gives you the offset of each field in a formatted string,
and GetDateFields() gives you the type of the field at a given offset.
With these informations, you can handle the formatted date string as
a list of fields that you can split and alter at will.
\param fields Pointer to the fields object.
\param fieldCount The number of fields.
\param style Specify the long format (with day name, full
month name) or the short format, 08/12/2010 or similar.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_ERROR Unable to lock the BLocale or an error getting the date
fields.
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
\sa BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount,
BTimeFormatStyle style) const
*/
/*!
\fn int BLocale::StartOfWeek() const
\brief Returns the number of the day used as start of week in this locale.
\returns a flag that indicates the day of the week that the week starts or
B_ERROR if there was an error.
\retval B_ERROR Unable to lock the BLocale.
\retval B_WEEK_START_SUNDAY If the beginning of the week starts on Sunday.
\retval B_WEEK_START_MONDAY If the beginning of the week starts on Monday.
*/
/*!
\fn ssize_t BLocale::FormatDateTime(char* target, size_t maxSize,
time_t time, BDateFormatStyle dateStyle,
BTimeFormatStyle timeStyle) const
\brief Fills in \a string with a formatted datetime up to \a maxSize bytes
for the given \a time and \a style for the locale.
\param target The string buffer to fill with the formatted datetime.
\param maxSize The size of the buffer.
\param time The time (in seconds since epoch) to format
\param dateStyle Specify the long format or the short format of the date.
\param timeStyle Specify the long format or the short format of the time.
\returns The number of bytes written during the datetime formatting.
\retval B_ERROR Unable to lock the BLocale.
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
\retval B_BAD_VALUE CheckedArrayByteSink overflowed.
\sa BLocale::FormatDate(char* string, size_t maxSize, time_t time,
BDateFormatStyle style) const
\sa BLocale::FormatTime(char* string, size_t maxSize, time_t time,
BTimeFormatStyle style) const
*/
/*!
\fn status_t BLocale::FormatDateTime(BString* target, time_t time,
BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle,
const BTimeZone* timeZone) const
\brief Fills in \a string with a formatted datetime for the given
\a time, \a timeStyle, and \a timeZone for the locale.
\param target The string buffer to fill with the formatted date.
\param time The time (in seconds since epoch) to format
\param dateStyle Specify the long format or the short format of the date.
\param timeStyle Specify the long format or the short format of the time.
\param timeZone The time zone.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_ERROR Unable to lock the BLocale.
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
\sa BLocale::FormatDate(BString *string, time_t time,
BDateFormatStyle style, const BTimeZone* timeZone) const
\sa status_t BLocale::FormatTime(BString* string, time_t time,
BTimeFormatStyle style, const BTimeZone* timeZone) const
*/
/*!
\fn ssize_t BLocale::FormatTime(char* string, size_t maxSize, time_t time,
BTimeFormatStyle style) const
\brief Fills in \a string with a formatted date up to \a maxSize bytes for
the given \a time and \a style for the locale.
\param string The string buffer to fill with the formatted time.
\param maxSize The size of the buffer.
\param time The time (in seconds since epoch) to format
\param style Specify the long format or the short format.
\returns The number of bytes written during the time formatting.
\retval B_ERROR Unable to lock the BLocale.
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
\retval B_BAD_VALUE CheckedArrayByteSink overflowed.
\sa BLocale::FormatDate(char* string, size_t maxSize, time_t time,
BDateFormatStyle style) const
\sa BLocale::FormatDateTime(char* target, size_t maxSize,
time_t time, BDateFormatStyle dateStyle,
BTimeFormatStyle timeStyle) const
*/
/*!
\fn status_t BLocale::FormatTime(BString* string, time_t time,
BTimeFormatStyle style, const BTimeZone* timeZone) const
\brief Fills in \a string with a formatted time for the given
\a time, \a style, and \a timeZone for the locale.
\param string The string buffer to fill with the formatted date.
\param time The time (in seconds since epoch) to format
\param style Specify the long format or the short format.
\param timeZone The time zone.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_ERROR Unable to lock the BLocale.
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
\sa BLocale::FormatDate(BString *string, time_t time,
BDateFormatStyle style, const BTimeZone* timeZone) const
\sa BLocale::FormatDateTime(BString* target, time_t time,
BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle,
const BTimeZone* timeZone) const
*/
/*!
\fn status_t BLocale::FormatTime(BString* string, int*& fieldPositions,
int& fieldCount, time_t time, BTimeFormatStyle style) const
\brief Fills in \a string with a formatted time for the given
\a time and \a style for the locale.
\param string The string buffer to fill with the formatted time.
\param fieldPositions ???
\param fieldCount ???
\param time The time (in seconds since epoch) to format.
\param style Specify the long format or the short format.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_ERROR Unable to lock the BLocale or an error formatting the time.
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
\sa BLocale::FormatDate(BString* string, int*& fieldPositions,
int& fieldCount, time_t time, BDateFormatStyle style) const
*/
/*!
\fn status_t BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount,
BTimeFormatStyle style) const
\brief Get the type of each field in the time format of the locale.
This function is most often used in combination with FormatTime().
FormatTime() gives you the offset of each field in a formatted string,
and GetTimeFields() gives you the type of the field at a given offset.
With these informations, you can handle the formatted date string as
a list of fields that you can split and alter at will.
\param fields Pointer to the fields object.
\param fieldCount The number of fields.
\param style Specify the long format or the short format.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_ERROR Unable to lock the BLocale or an error getting the time
fields.
\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
\sa BLocale::GetDateFields(BDateElement*& fields, int& fieldCount,
BDateFormatStyle style) const
*/
/*!
\fn ssize_t BLocale::FormatNumber(char* string, size_t maxSize,
double value) const
\brief Format the \c double \a value as a string and put the result
into \a string up to \a maxSize bytes in the current locale.
\param string The string to put the formatted number into.
\param maxSize The maximum of bytes to copy into \a string.
\param value The number that you want to get a formatted version of.
\returns The length of the string created or an error status code in
the case of an error.
\sa BLocale::FormatNumber(char* string, size_t maxSize,
int32 value) const
\sa ssize_t BLocale::FormatMonetary(char* string, size_t maxSize,
double value) const
*/
/*!
\fn status_t BLocale::FormatNumber(BString* string, double value) const
\brief \brief Format the \c double \a value as a string and put the result
into \a string in the current locale.
\param string The string to put the formatted number into.
\param value The number that you want to get a formatted version of.
\returns The length of the string created or an error status code in
the case of an error.
\sa BLocale::FormatNumber(BString* string, int32 value) const
\sa BLocale::FormatMonetary(BString* string, double value) const
*/
/*!
\fn ssize_t BLocale::FormatNumber(char* string, size_t maxSize,
int32 value) const
\brief Format the \c int32 \a value as a string and put the result
into \a string up to \a maxSize bytes in the current locale.
\param string The string to put the formatted number into.
\param maxSize The maximum of bytes to copy into \a string.
\param value The number that you want to get a formatted version of.
\returns The length of the string created or an error status code in
the case of an error.
\sa BLocale::FormatNumber(char* string, size_t maxSize,
double value) const
\sa BLocale::FormatMonetary(char* string, size_t maxSize,
double value) const
*/
/*!
\fn status_t BLocale::FormatNumber(BString* string, int32 value) const
\brief \brief Format the \c int32 \a value as a string and put the result
into \a string in the current locale.
\param string The string to put the formatted number into.
\param value The number that you want to get a formatted version of.
\returns The length of the string created or an error status code in
the case of an error.
\sa BLocale::FormatNumber(BString* string, double value) const
\sa BLocale::FormatMonetary(BString* string, double value) const
*/
/*!
\fn ssize_t BLocale::FormatMonetary(char* string, size_t maxSize,
double value) const
\brief Format the \c double \a value as a monetary string and put the
result into \a string up to \a maxSize bytes in the current locale.
\param string The string to put the monetary formatted number into.
\param maxSize The maximum of bytes to copy into \a string.
\param value The number that you want to get a monetary formatted version
of.
\returns The length of the string created or an error status code in
the case of an error.
\sa BLocale::FormatNumber(char* string, size_t maxSize,
double value) const
\sa BLocale::FormatNumber(char* string, size_t maxSize,
int32 value) const
*/
/*!
\fn status_t BLocale::FormatMonetary(BString* string, double value) const
\brief \brief Format the \c double \a value as a monetary string and put
the result into \a string in the current locale.
\param string The string to put the monetary formatted number into.
\param value The number that you want to get a monetary formatted version
of.
\returns The length of the string created or an error status code in
the case of an error.
\sa BLocale::FormatNumber(BString* string, double value) const
\sa BLocale::FormatNumber(BString* string, int32 value) const
*/
docs/user/locale/LocaleRoster.dox
+178 -56
View File
@@ -1,92 +1,214 @@
/*!
\class BLocaleRoster
\ingroup locale
\brief Main class for accessing the locale kit data
/*
* Copyright 2003-2010, Haiku. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Axel Dörfler, [email protected]
* John Scipione, [email protected]
* Oliver Tappe, [email protected]
*
* Corresponds to:
* /trunk/headers/os/locale/LocaleRoster.h rev 42274
* /trunk/src/kits/locale/LocaleRoster.cpp rev 42274
*/
The Locale Roster is the central part of the locale kit.
It is a global object (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 status_t BLocaleRoster::GetDefaultCollator(BCollator* collator) const
\brief Get the default collator.
\class BLocaleRoster
\ingroup locale
\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 status_t BLocaleRoster::GetDefaultLocale(BLocale* locale) const
\brief Get the default locale.
\fn BLocaleRoster::BLocaleRoster()
\brief Constructor. Does nothing.
*/
/*!
\fn status_t BLocaleRoster::GetDefaultCountry(BCountry* country) const
\brief Get the default country.
\fn BLocaleRoster::~BLocaleRoster()
\brief Destructor. Does nothing.
*/
/*!
\fn status_t BLocaleRoster::GetDefaultLanguage(BLanguage* language) const
\brief Get the default language.
\fn BLocaleRoster* BLocaleRoster::Default()
\brief Returns default BLocalRoster.
*/
/*!
\fn status_t BLocaleRoster::GetDefaultTimeZone(BTimeZone* timezone) const
\brief Get the default timezone.
\fn status_t BLocaleRoster::Refresh()
\brief Refreshes the BLocalRoster.
*/
/*!
\fn status_t BLocaleRoster::GetLanguage(const char* languagecode, BLanguage** _language) const
\brief Instanciate a language from its code.
\fn status_t BLocaleRoster::GetDefaultTimeZone(BTimeZone* timezone) const
\brief Get the default timezone.
*/
/*!
\fn status_t BLocaleRoster::GetAvailableLanguages(BMessage* message) const
\brief List the available languages
This function fills the passed BMessage with one or more 'language' string
fields, containing the language(s) ID(s).
\fn status_t BLocaleRoster::GetLanguage(const char* languagecode,
BLanguage** _language) const
\brief Instantiate a language from its code.
*/
/*!
\fn status_t BLocaleRoster::GetAvailableCountries(BMessage* message) const
\brief List the available countries
This function filles the passed BMessage with one or more 'country' string
fields, containing the (ISO-639) code of each country.
\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::GetInstalledCatalogs(BMessage* message, const char* sigPattern = NULL, const char* langPattern = NULL, int32 fingerprint = 0) const
\brief Get the available locales and catalogs
This function fills the passed BMessage 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.
\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 BCatalog* BLocaleRoster::GetCatalog()
\brief Get the current image catalog.
This function 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.
\returns The catalog, if it was loaded successfully.
\warning This function needs the image to be lined with liblocalestub.a
\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::GetPreferredLanguages(BMessage* message) const
\brief Return the list of user preferred languages.
\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.
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.
\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()
\brief Get the current image catalog.
This function 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.
\warning This function needs the image to be lined with liblocalestub.a
\returns The catalog, if it was loaded successfully.
*/
docs/user/locale/TimeZone.cpp
-72
View File
@@ -1,72 +0,0 @@
/*!
\class BTimeZone
\ingroup locale
\brief Class holding information for a time zone.
*/
/*!
\fn BTimeZone::BTimeZone(const char* zoneCode)
\brief Construct a timezone from its code.
The constructor only allows you to construct a timezone if you already know its
code. If you don't know the code, you can instead go through the BCountry class
which can enumerate all timezones in a country, or use the BLocaleRoster, which
knows the timezone selected by the user.
*/
/*!
\fn const BString& BTimeZone::Code() const
\brief Returns the timezone code.
Note different time zones with different codes may have the same rules.
*/
/*!
\fn const BString& BTimeZone::Name() const
\brief Returns the localized name of the time zone
Use this for displaying information to the user.
*/
/*!
\fn const BString& BTimeZone::DaylightSavingName() const
\brief Return the name of the daylight savings rules used in this timezone.
*/
/*!
\fn const BString& BTimeZone::ShortName() const
\brief Return the short name of the timezone, in the user's locale.
*/
/*!
\fn const BString& BTimeZone::DaylightSavingName() const
\brief Return the short name of the daylight savings rules used in this
timezone.
*/
/*!
\fn int BTimeZone::OffsetFromGMT() const
\brief Return the offset from GMT.
The offset is a number of seconds, positive or negative.
*/
/*!
\fn bool BTimeZone::SupportsDaylightSaving() const
\brief Return true if the time zone has daylight saving rules
*/
/*!
\fn status_t BTimeZone::InitCheck() const
\brief Return false if there was an error creating the timezone (you called the
constructor or SetTo with an invalid code).
*/
/*!
\fn status_t BTimeZone::SetTo(const char* zoneCode)
\brief Set the timezone to another code.
\returns false if there was an error (likely you given an invalid code)
*/
docs/user/locale/TimeZone.dox
+110
View File
@@ -0,0 +1,110 @@
/*
* Copyright 2011, Haiku inc.
* Distributed under the terms of the MIT Licence.
*
* Documentation by:
* Adrien Destugues <[email protected]>
* John Scipione <[email protected]>
* Oliver Tappe <[email protected]>
* Corresponds to:
* /trunk/headers/os/locale/TimeZone.h rev 42274
* /trunk/src/kits/locale/TimeZone.cpp rev 42274
*/
/*!
\file TimeZone.h
\brief Provides for the BTimeZone class.
*/
/*!
\class BTimeZone
\ingroup locale
\brief Provides information about time zones.
*/
/*!
\fn BTimeZone::BTimeZone(const char* zoneID, const BLanguage* language)
\brief Construct a timezone from its \a zoneID and \a language.
The constructor only allows you to construct a timezone if you already
know its code. If you don't know the code, you can instead go through the
BCountry class which can enumerate all timezones in a country, or use the
BLocaleRoster, which knows the timezone selected by the user.
*/
/*!
\fn BTimeZone::BTimeZone(const BTimeZone& other)
*/
/*!
\fn BTimeZone& BTimeZone::operator=(const BTimeZone& source)
*/
/*!
\fn const BString& BTimeZone::ID() const
\brief Returns the ID of the time zone.
*/
/*!
\fn const BString& BTimeZone::Name() const
\brief Returns the localized name of the time zone.
Use this method to display the time zone's name to the user.
*/
/*!
\fn const BString& BTimeZone::DaylightSavingName() const
\brief Returns the name of the daylight savings rules used in this timezone.
*/
/*!
\fn const BString& BTimeZone::ShortName() const
\brief Returns the short name of the timezone, in the user's locale.
*/
/*!
\fn const BString& BTimeZone::ShortDaylightSavingName() const
\brief Returns the short name of the daylight savings rules used in this
timezone.
*/
/*!
\fn int BTimeZone::OffsetFromGMT() const
\brief Return the offset from GMT.
The offset is a number of seconds, positive or negative.
*/
/*!
\fn bool BTimeZone::SupportsDaylightSaving() const
\brief Return true if the time zone has daylight saving rules
*/
/*!
\fn status_t BTimeZone::InitCheck() const
\brief Return \c false if there was an error creating the timezone
for instance if you called the constructor or SetTo() with an invalid
timezone code.)
*/
/*!
\fn status_t BTimeZone::SetTo(const char* zoneCode)
\brief Set the timezone to another code.
\returns \c false if there was an error (likely due to an invalid
timezone code.)
*/
docs/user/locale/UnicodeChar.dox
+161 -83
View File
@@ -1,167 +1,245 @@
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Distributed under the terms of the OpenBeOS License.
*
* Authors:
* Axel Dörfler <[email protected]>
* John Scipione <[email protected]>
*
* Corresponds to:
* /trunk/headers/os/locale/UnicodeChar.h rev 42274
* /trunk/src/kits/locale/UnicodeChar.cpp rev 42274
*/
/*!
\class BUnicodeChar
\ingroup locale
\class BUnicodeChar
\ingroup locale
\brief Management of all information about characters.
\brief Management of all information about characters.
This class provide a set of tools for managing the whole set of characters
defined in unicode. This include informations such as knowing if the character is
whitespace, if it is alphanumeric, or solething else ; what is the uppercase
equivalent of a character ; or wether it can be ornamented with accents.
This class provide a set of tools for managing the whole set of characters
defined by unicode. This include information about special sets of
characters such as if the character is whitespace, or alphanumeric. It also
provides the uppercase equivalent of a character and determines whether a
character can be ornamented with accents.
This class consists entirely of static methods, which means you don't have to
instanciate it. Just call one of the methods with the char you want examinated.
Note all the function work with chars encoded in utf-32. This is not the most usual
way to handle characters, but it is the faster. To convert an utf-8 string to an
utf-32 character, pass it to the FromUTF8 function.
This class consists entirely of static methods, so you do not have to
instantiate it. You can call one of the methods passing in the character
that you want to be examined.
Note all the function work with chars encoded in utf-32. This is not the
most usual way to handle characters, but it is the fastest. To convert an
utf-8 string to an utf-32 character use the FromUTF8() method.
*/
/*!
\fn static bool BUnicodeChar::IsAlpha(uint32 c)
\brief Tell if the character is alphabetic.
\fn static bool BUnicodeChar::IsAlpha(uint32 c)
\brief Determine if \a c is alphabetic.
\returns \c true if the specified unicode character is an
alphabetic character.
*/
/*!
\fn static bool BUnicodeChar::IsAlNum(uint32 c)
\brief Tell if the character is alphanumeric.
\fn static bool BUnicodeChar::IsAlNum(uint32 c)
\brief Determine if \a c is alphanumeric.
\returns \c true if the specified unicode character is a
alphabetic or numeric character.
*/
/*!
\fn static bool BUnicodeChar::IsDigit(uint32 c)
\brief Tell if the caracter is numeric.
\fn static bool BUnicodeChar::IsDigit(uint32 c)
\brief Determine if \a c is numeric.
\returns \c true if the specified unicode character is a
number character.
*/
/*!
\fn static bool BUnicodeChar::IsHexDigit(uint32 c)
\brief Tell if the character is numeric in base 16.
\fn static bool BUnicodeChar::IsHexDigit(uint32 c)
\brief Determine if \a c is a hexadecimal digit.
\returns \c true if the specified unicode character is a
hexadecimal number character.
*/
/*!
\fn static bool BUnicodeChar::IsUpper(uint32 c)
\brief Tell if the character is uppercase.
\fn static bool BUnicodeChar::IsUpper(uint32 c)
\brief Determine if \a c is uppercase.
\returns \c true if the specified unicode character is an
uppercase character.
*/
/*!
\fn static bool BUnicodeChar::IsLower(uint32 c)
\brief Tell if the character is lowercase.
\fn static bool BUnicodeChar::IsLower(uint32 c)
\brief Determine if \a c is lowercase.
\returns \c true if the specified unicode character is a
lowercase character.
*/
/*!
\fn static bool BUnicodeChar::IsSpace(uint32 c)
\brief Tell if the character is space.
\fn static bool BUnicodeChar::IsSpace(uint32 c)
\brief Determine if \a c is a space.
Unlike IsWhitespace, this function will return true for non-breakable
spaces. It is the one to use for determining if the character will render
as an empty space on screen and can be stretched to make the text look
nicer.
Unlike IsWhitespace() this function will return \c true for non-breakable
spaces. This method is useful for determining if the character will render
as an empty space which can be stretched on-screen.
\returns \c true if the specified unicode character is some
kind of a space character.
\sa IsWhitespace()
*/
/*!
\fn static bool BUnicodeChar::IsWhitespace(uint32 c)
\brief Tell if the character is whitespace.
\fn static bool BUnicodeChar::IsWhitespace(uint32 c)
\brief Determine if \a c is whitespace.
Unlike IsSpace, this method will return false for non-breakable spaces.
It is the one to use for selecting where to insert line breaks.
This method is essentially the same as IsSpace(), but excludes all
non-breakable spaces.
\returns \c true if the specified unicode character is a whitespace
character.
\sa IsSpace()
*/
/*!
\fn static bool BUnicodeChar::IsControl(uint32 c)
\brief Tell if the character is a control character.
\fn static bool BUnicodeChar::IsControl(uint32 c)
\brief Determine if \a c is a control character.
Example control characters are the non-printable ASCII characters 0 to 0x1F.
Example control characters are the non-printable ASCII characters from
0x0 to 0x1F.
\returns \c true if the specified unicode character is a control
character.
\sa IsPrintable()
*/
/*!
\fn static bool BUnicodeChar::IsPunctuation(uint32 c)
\brief Tell if the character is a punctuation.
\fn static bool BUnicodeChar::IsPunctuation(uint32 c)
\brief Determine if \a c is punctuation character.
\returns \c true if the specified unicode character is a
punctuation character.
*/
/*!
\fn static bool BUnicodeChar::IsPrintable(uint32 c)
\brief Tell if the character is printable.
\fn static bool BUnicodeChar::IsPrintable(uint32 c)
\brief Determine if \a c is printable.
Printable characters are not control characters.
\returns \c true if the specified unicode character is a printable
character.
\sa IsControl()
*/
/*!
\fn static bool BUnicodeChar::IsTitle(uint32 c)
\brief Tell if the character is title case.
\fn static bool BUnicodeChar::IsTitle(uint32 c)
\brief Determine if \a c is title case.
Title case is usually a smaller version of upercase letters.
Title case characters are a smaller version of normal uppercase letters.
\returns \c true if the specified unicode character is a title case
character.
*/
/*!
\fn static bool BUnicodeChar::IsDefined(uint32 c)
\brief Tell if the character is defined at all.
\fn static bool BUnicodeChar::IsDefined(uint32 c)
\brief Determine if \a c is defined.
In unicode, some codes are not valid, or not attributed yet.
For these, this method wil lreturn false.
In unicode some codes are not valid or not attributed yet.
For these codes this method will return \c false.
\returns \c true if the specified unicode character is defined.
*/
/*!
\fn static bool BUnicodeChar::IsBase(uint32 c)
\brief Tell if the character can be used with a diacritic.
\fn static bool BUnicodeChar::IsBase(uint32 c)
\brief Determine if \a c can be used with a diacritic.
\note IsBase() does not determine if a unicode character is distinct.
\returns \c true if the specified unicode character is a base
form character that can be used with a diacritic.
*/
/*!
\fn static int8 BUnicodeChar::Type(uint32 c)
\brief Returns the type of the character.
\fn static int8 BUnicodeChar::Type(uint32 c)
\brief Gets the type of a character.
Return value is a member of the unicode_char_category enum.
\returns A member of the \c unicode_char_category enum.
*/
/*!
\fn static uint32 ToLower(uint32 c);
\brief Returns the lowercase version of a character.
\fn uint32 BUnicodeChar::ToLower(uint32 c)
\brief Transforms \a c to lowercase.
\returns The lowercase version of the specified unicode character.
*/
/*!
\fn static uint32 ToUpper(uint32 c);
\brief Returns the uppercase version of a character.
\fn uint32 BUnicodeChar::ToUpper(uint32 c)
\brief Transforms \a c to uppercase.
\returns The uppercase version of the specified unicode character.
*/
/*!
\fn static uint32 ToTitle(uint32 c);
\brief Returns the titlecase version of a character.
\fn uint32 BUnicodeChar::ToTitle(uint32 c)
\brief Transforms \a c to title case.
\returns The title case version of the specified unicode character.
*/
/*!
\fn static int32 DigitValue(uint32 c);
\brief Returns the numeric value of the character.
\fn int32 BUnicodeChar::DigitValue(uint32 c)
\brief Gets the numeric value \a c.
\returns The numeric version of the specified unicode character.
*/
/*!
\fn static void ToUTF8(uint32c, char ù**ou
\brief Convert a character to utf8 encoding.
\fn void BUnicodeChar::ToUTF8(uint32 c, char **out)
\brief Transform a character to utf-8 encoding.
\returns The utf-8 encoding of the specified unicode character.
*/
/*!
\fn static uint32 FromUTF8(const char** in)
\brief Convert an utf-8 string to an utf-32 character.
\fn uint32 BUnicodeChar::FromUTF8(const char **in)
\brief Transform a utf-8 string to an utf-32 character.
If the string contains multiple characters, only the fist one is used.
This function updates the in pointer so that it points on the next
character for the following call.
If the string contains multiple characters, only the fist one is used.
This function updates the in pointer so that it points on the next
character for the following call.
\returns The utf-32 encoded version of \a in.
*/
/*!
\fn static uint32 FromUTF8(const char* in)
\brief Convert an utfÃ-8 string to an utfÃ-32 character.
\fn size_t BUnicodeChar::UTF8StringLength(const char *str)
\brief Counts the characters in the given \c NUL terminated string.
If the string contains multiple characters, only the first one is used.
The in pointer is not modified.
\returns the number of utf-8 characters in the \c NUL terminated string.
\sa BString::CountChars()
*/
/*!
\fn static size_t UTF8StringLength(const char* str)
\brief This function counts the characters in the given null-terminated string.
\fn size_t BUnicodeChar::UTF8StringLength(const char *str, size_t maxLength)
\brief Counts the characters in the given string up to \a maxLength
characters.
\sa BString::CountChars()
*/
/*!
\fn static size_t UTF8StringLength(const char* str, size_t maxLength)
\brief This function counts the characters in the given string.
The string does not need to be null-terminated if you specify the length.
The string does not need to be \c NUL terminated if you specify a
\a maxLength that is shorter than the maximum length of the string.
\returns the number of utf-8 characters in the \c NUL terminated string
up to \a maxLength characters.
*/