[haiku-commits] haiku: hrev48595 - docs/user/translation
- From: revol@xxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Sat, 3 Jan 2015 01:24:18 +0100 (CET)
hrev48595 adds 3 changesets to branch 'master'
old head: 4536c6033b1d74b169191300fbce2f1334ae09ad
new head: 70dc2e27e998e93c980065c0b92956a5dce3e83c
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=70dc2e2+%5E4536c60
----------------------------------------------------------------------------
02bdb5d: Add libtranslation group definition to doxygen stuff
[ François Revol <revol@xxxxxxx> ]
b9e01b3: Fixup BTranslator documentation
[ Markus Himmel <markus@xxxxxxxxxxxxxxxxx> ]
70dc2e2: Add BTranslatorRoster documentation
[ Markus Himmel <markus@xxxxxxxxxxxxxxxxx> ]
----------------------------------------------------------------------------
3 files changed, 528 insertions(+), 6 deletions(-)
docs/user/book.dox | 2 +
docs/user/translation/Translator.dox | 12 +-
docs/user/translation/TranslatorRoster.dox | 520 +++++++++++++++++++++++++
############################################################################
Commit: 02bdb5db9a9c32cdb21c17c19a8d6876cfd61036
URL: http://cgit.haiku-os.org/haiku/commit/?id=02bdb5d
Author: François Revol <revol@xxxxxxx>
Date: Sat Jan 3 00:04:41 2015 UTC
Add libtranslation group definition to doxygen stuff
----------------------------------------------------------------------------
diff --git a/docs/user/book.dox b/docs/user/book.dox
index 86386e9..72f751d 100644
--- a/docs/user/book.dox
+++ b/docs/user/book.dox
@@ -554,6 +554,8 @@ snooze_until(time - Latency(), B_SYSTEM_TIMEBASE);
formats.
+ \defgroup libtranslation (libtranslation.so)
+
\defgroup libbe (libbe.so)
############################################################################
Commit: b9e01b33edc097080bb44d0ab4cec7d3dc2ce0f1
URL: http://cgit.haiku-os.org/haiku/commit/?id=b9e01b3
Author: Markus Himmel <markus@xxxxxxxxxxxxxxxxx>
Date: Thu Jan 1 02:09:50 2015 UTC
Committer: François Revol <revol@xxxxxxx>
Commit-Date: Sat Jan 3 00:20:28 2015 UTC
Fixup BTranslator documentation
----------------------------------------------------------------------------
diff --git a/docs/user/translation/Translator.dox
b/docs/user/translation/Translator.dox
index 34ec794..62219c5 100644
--- a/docs/user/translation/Translator.dox
+++ b/docs/user/translation/Translator.dox
@@ -1,5 +1,5 @@
/*
- * Copyright 2014 Markus Himmel. All rights reserved.
+ * Copyright 2014-2015 Markus Himmel. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -13,14 +13,14 @@
/*!
\file Translator.h
\ingroup translation
- \ingroup libbe
+ \ingroup libtranslation
\brief BTranslator class definition.
*/
/*!
\file TranslationDefs.h
\ingroup translation
- \ingroup libbe
+ \ingroup libtranslation
\brief Defines structures and preprocessor macros that are used by the
translation kit.
*/
@@ -28,7 +28,7 @@
/*!
\file TranslatorFormats.h
\ingroup translation
- \ingroup libbe
+ \ingroup libtranslation
\brief Defines identifiers and structures for data formats and
configuration
messages.
*/
@@ -36,7 +36,7 @@
/*!
\class BTranslator
\ingroup translation
- \ingroup libbe
+ \ingroup libtranslation
\brief Abstract class that defines the necessary functionality of a
translator.
@@ -279,7 +279,7 @@
TranslatorFormats.h.
\param _view Where a pointer to the newly created configuration view
will
be stored.
- \param _extent Where the size of the newly created configureation view
will
+ \param _extent Where the size of the newly created configuration view
will
be stored.
\retval B_OK Everything went well.
\retval B_ERROR An error occurred or the method was not overriden by the
############################################################################
Revision: hrev48595
Commit: 70dc2e27e998e93c980065c0b92956a5dce3e83c
URL: http://cgit.haiku-os.org/haiku/commit/?id=70dc2e2
Author: Markus Himmel <markus@xxxxxxxxxxxxxxxxx>
Date: Thu Jan 1 02:09:50 2015 UTC
Committer: François Revol <revol@xxxxxxx>
Commit-Date: Sat Jan 3 00:20:35 2015 UTC
Add BTranslatorRoster documentation
----------------------------------------------------------------------------
diff --git a/docs/user/translation/TranslatorRoster.dox
b/docs/user/translation/TranslatorRoster.dox
new file mode 100644
index 0000000..b306be6
--- /dev/null
+++ b/docs/user/translation/TranslatorRoster.dox
@@ -0,0 +1,520 @@
+/*
+ * Copyright 2014-2015 Markus Himmel. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ * Markus Himmel, markus@xxxxxxxxxxxxxxxxx
+ *
+ * Corresponds to:
+ * headers/os/translation/TranslatorRoster.h hrev48588
+ * src/kits/translation/TranslatorRoster.cpp hrev48588
+ */
+
+/*!
+ \file TranslatorRoster.h
+ \ingroup translation
+ \ingroup libtranslation
+ \brief BTranslatorRoster class definition
+*/
+
+/*!
+ \class BTranslatorRoster
+ \ingroup translation
+ \ingroup libtranslation
+ \brief Class that serves as an interface between applications and
+ translators.
+
+ BTranslatorRoster gives applications access to the translation kit.
+ Applications can request translations and BTranslatorRoster will
+ automatically search for a matching translator and have it perfrom the
+ translation.
+
+ \warning BTranslatorRoster does not perform chaining of any sort. Only
+ translations that can be made by invoking a single translator
are
+ supported.
+
+ \note BTranslationUtils provides some helper methods that perform the
+ interaction with BTranslatorRoster for you.
+
+ BTranslationRoster acts as a container. While in most cases the default
+ roster is used, it is possible to create a roster that interacts with a
+ custom set of translators.
+*/
+
+/*!
+ \name Constructors and Destructor
+*/
+
+//! @{
+
+/*!
+ \fn BTranslatorRoster::BTranslatorRoster()
+ \brief Constructs an empty BTranslatorRoster.
+
+ \warning Only call the contructor if you want to use a custom
collection of
+ translators. Use Default() if you don't.
+*/
+
+/*!
+ \fn BTranslatorRoster::BTranslatorRoster(BMessage* model);
+ \brief Constructs a BTranslatorRoster and fills it.
+
+ \param model A message that contains information about a
+ BTranslatorRoster.
+
+ After initialization, \a model is searched for strings with the name
+ \c "be:translator_path". The translators that are located at each path
+ are added to the roster. If multiple paths point to translators with the
+ same name, the translator at the path with the lowest index within the
+ message will be kept.
+
+ \warning Use Instantiate() instead of this constructor if \a model was
+ created using Archive().
+*/
+
+/*!
+ \fn BTranslatorRoster::~BTranslatorRoster();
+ \brief Deletes this BTranslatorRoster.
+
+ If the BTranslatorRoster that is deleted is the default roster, a new
+ default roster will be created when BTranslatorRoster::Default() is
called
+ for the next time.
+
+ Release() is called on all translators in the roster.
+*/
+
+/*!
+ \fn static BTranslatorRoster* BTranslatorRoster::Default();
+ \brief Gets the default BTranslatorRoster.
+
+ There is only one default translator. It is created when it is first
+ requested. It is poplated according to the following rules:
+
+ If the environment variable \c TRANSLATORS is set, it will be populated
+ with all translators that are present in the directories denoted by
+ \c TRANSLATORS. The paths are separated by a colon (<tt>:</tt>). If
+ multiple paths contain a translator with the same name, the translator
+ that is located in the path that appears earliest in \c TRANSLATORS will
+ be kept.
+
+ If \c TRANSLATORS is unset, the user non-packaged add-ons directory, the
+ user add-ons directory, the system non-packaged add-ons directory and
the
+ system add-ons directory will be used. If those directories do not
contain
+ a subdirectory \c Translators, it will be created. The subdirectories
are
+ then added in the above order. If multiple directories contain a
translator
+ with the same name, the translator that is located in the path that
appears
+ earliest in the above list will be kept.
+*/
+
+//! @}
+
+/*!
+ \name Archiving
+*/
+
+//! @{
+
+/*!
+ \fn virtual status_t BTranslatorRoster::Archive(BMessage* into, bool
deep\
+ = true) const;
+ \brief Archive this BTranslatorRoster into a BMessage.
+
+ \param into Where the BTranslatorRoster will be stored.
+ \param deep Unused.
+
+ \retval B_OK The operation was successful.
+ \retval B_BAD_VALUE \a into was NULL.
+ \retval B_ERROR The operation failed.
+*/
+
+/*!
+ \fn static BArchivable* BTranslatorRoster::Instantiate(BMessage* from);
+ \brief Creates a new BTranslatorRoster from a message.
+
+ \param from The message that contains information about a
+ BTranslatorRoster.
+
+ \returns \c NULL if \a from was \c NULL, contained invalid archive data
or
+ archive data of a class that is not BTranslatorRoster. A
pointer to a
+ new BTranslatorRoster containing the information from \a from
+ otherwise.
+*/
+
+//! @}
+
+/*!
+ \name Roster Management
+*/
+
+//! @{
+
+/*!
+ \fn status_t BTranslatorRoster::AddTranslators(const char* loadPath =\
+ NULL);
+ \brief Adds translators from a directory to the roster.
+
+ \param loadPath A colon-separated list of directories to search for
+ translators in.
+
+ The following method is used to determine which translators to add:
+
+ If \a loadPath is not \c NULL, the roster will be populated with all
+ translators that are present in the directores denoted by \a loadPath.
The
+ paths are separated by a colon (<tt>:</tt>). If multiple paths contain a
+ translator with the same name, the translator that is located in the
path
+ that appears earliest in \a loadPath will be kept.
+
+ If \a loadPath is \c NULL and the environment variable \c TRANSLATORS is
+ set, it will be populated with all translators that are present in the
+ directories denoted by \c TRANSLATORS. The paths are separated by a
colon
+ (<tt>:</tt>). If multiple paths contain a translator with the same name,
+ the translator that is located in the path that appears earliest in
+ \c TRANSLATORS will be kept.
+
+ If \a loadPath is \c NULL and \c TRANSLATORS is unset, the user
+ non-packaged add-ons directory, the user add-ons directory, the system
+ non-packaged add-ons directory and the system add-ons directory will be
+ used. If those directories do not contain a subdirectory \c
Translators, it
+ will be created. The subdirectories are then added in the above order.
If
+ multiple directories contain a translator with the same name, the
+ translator that is located in the path that appears earliest in the
above
+ list will be kept.
+
+ \returns \c B_OK if everything went well, an error code specific to the
+ operation that failed otherwise.
+*/
+
+/*!
+ \fn status_t BTranslatorRoster::AddTranslator(BTranslator* translator);
+ \brief Adds a single BTranslator to the roster.
+
+ \param translator The translator that should be added.
+
+ \remark AddTranslator() calls Acquire() on the translator, so it is safe
+ to release it if you had acquired it before.
+
+ \retval B_OK The translator was successfully added to the roster.
+ \retval B_NO_MEMORY There was no memory to enlarge the roster.
+ \retval B_BAD_VALUE \a translator was \c NULL.
+*/
+
+//! @}
+
+/*!
+ \name Translator Access
+*/
+
+//! @{
+
+/*!
+ \fn virtual status_t BTranslatorRoster::GetTranslators(BPositionIO*\
+ source, BMessage* ioExtension, translator_info** _info, int32*\
+ _numInfo, uint32 hintType = 0, const char* hintMIME = NULL,
uint32\
+ wantType = 0);
+ \brief Collects information about all translators that are able to
perform
+ a certain conversion in an array.
+
+ \param source Read and seek interface to the data to be examinded.
+ \param ioExtension A message containing configuration information for
the
+ translators.
+ \param _info Where the resulting array will be stored.
+ \param _numInfo Where the number of elements in the resulting array will
+ be stored.
+ \param hintType A hint about the data format in \a source. \c 0
represents
+ an unknown type.
+ \param hintMIME A hint about the MIME type of \a source. \c NULL
represents
+ an unknown type.
+ \param wantType The format that \a source needs to be translated into.
\c 0
+ permits any output type.
+
+ If this function returns \c B_OK the caller has to call \c delete[] when
+ they are done using \a _info.
+
+ \retval B_OK \a _info and \a _numInfo were successfully populated.
+ \retval B_NO_TRANSLATOR No suitable translator was found.
+ \retval B_BAD_VALUE \a source, \a _info or \a _numInfo was \c NULL.
+ \retval B_IO_ERROR There was an error interacting with \a source.
+ \retval B_NO_MEMORY Could not allocate enough memory for the array.
+*/
+
+/*!
+ \fn virtual status_t
BTranslatorRoster::GetAllTranslators(translator_id**\
+ _list, int32* _count);
+ \brief Collects the IDs of all translators in the roster in an array.
+
+ \param _list Where the resulting array will be stored.
+ \param _count Where the number of elements in the resulting array will
be
+ stored.
+
+ If this function returns \c B_OK the caller has to call \c delete[] when
+ they are done using \a _info.
+
+ \retval B_OK \a _list and \a _count were populated successfully.
+ \retval B_NO_MEMORY Could not allocate the memory for the array.
+*/
+
+/*!
+ \fn virtual status_t BTranslatorRoster::GetTranslatorInfo(translator_id\
+ translatorID, const char** _name, const char** _info, int32*
_version);
+ \brief Looks up general information of the translator with a given ID.
+
+ \param translatorID The ID of the translator whose information is
+ requested.
+ \param _name Where the name of the translator will be stored.
+ \param _info Where the description of the translator will be stored.
+ \param _version Where the version of the translator will be stored.
+
+ Do not free any returned data. If any of \a _name, \a _info and \a
_version
+ are \c NULL, the non-null pointers will still be written to.
+
+ \retval B_OK All non-null pointers were written to successfully.
+ \retval B_BAD_VALUE All three pointers were \c NULL.
+ \retval B_NO_TRANSLATOR The roster does not contain any translator with
the
+ ID \a translatorID.
+*/
+
+/*!
+ \fn virtual status_t BTranslatorRoster::GetInputFormats(translator_id\
+ translatorID, const translation_format** _formats, int32*
_numFormats);
+ \brief Looks up the input formats of the translator with a given ID.
+
+ \param translatorID The ID of the translator whose input formats are
+ requested.
+ \param _formats Where the array of input formats will be stored.
+ \param _numFormats Where the number of elements in the array of input
+ formats will be stored.
+
+ Do not free any of the returned data.
+
+ \retval B_OK \a _formats and \a _numFormats were successfully set.
+ \retval B_BAD_VALUE \a _formats or \a _numFormats was \c NULL.
+ \retval B_NO_TRANSLATOR The roster does not contain any translator with
the
+ ID \a translatorID.
+*/
+
+/*!
+ \fn virtual status_t BTranslatorRoster::GetOutputFormats(translator_id\
+ translatorID, const translation_format** _formats, int32*
_numFormats);
+ \brief Looks up the output formats of the translator with a given ID.
+
+ \param translatorID The ID of the translator whose output formats are
+ requested.
+ \param _formats Where the array of output formats will be stored.
+ \param _numFormats Where the number of elements in the array of output
+ formats will be stored.
+
+ Do not free any of the returned data.
+
+ \retval B_OK \a _formats and \a _numFormats were successfully set.
+ \retval B_BAD_VALUE \a _formats or \a _numFormats was \c NULL.
+ \retval B_NO_TRANSLATOR The roster does not contain any translator with
the
+ ID \a translatorID.
+*/
+
+/*!
+ \fn virtual status_t BTranslatorRoster::MakeConfigurationView(\
+ translator_id translatorID, BMessage* ioExtension, BView**
_view,\
+ BRect* _extent);
+ \brief Creates the configuration view of a specified translator from the
+ roster.
+
+ \param translatorID The ID of the translator whose configuration view
+ should be created.
+ \param ioExtension A message containing configuration information for
the
+ translator.
+ \param _view Where a pointer to the newly created configuration view
will
+ be stored.
+ \param _extent Where the size of of the newly created configuration view
+ will be stored.
+
+ \retval B_OK Everything went well.
+ \retval B_BAD_VALUE \a _view or \a _extent were \c NULL or \a
ioExtension
+ was \c NULL or contained bad data.
+ \retval B_NO_TRANSLATOR The roster does not contain any translator with
the
+ ID \a translatorID.
+ \retval B_ERROR An error occurred or the translator chose not to supply
+ a configuration view.
+*/
+
+/*!
+ \fn virtual status_t BTranslatorRoster::GetConfigurationMessage(\
+ translator_id translatorID, BMessage* ioExtension)
+ \brief Populates a BMessage with the settings of the specified
translator.
+
+ \param translatorID The ID of the translator whose settings \a
ioExtension
+ should be populated with.
+ \param ioExtension The message that should be populated.
+
+ \retval B_OK \a ioExtension was populated successfully.
+ \retval B_NO_TRANSLATOR The roster does not contain any translator with
the
+ ID \a translatorID.
+ \retval B_BAD_VALUE \a ioExtension was \c NULL.
+ \retval B_ERROR An error occurred or the translator chose not to provide
+ this functionality.
+*/
+
+/*!
+ \fn status_t BTranslatorRoster::GetRefFor(translator_id translatorID,\
+ entry_ref* ref);
+ \brief Returns the entry_ref of the specified translator.
+
+ \param translatorID The ID of the translator whose entry_ref is to be
+ found.
+ \param ref Where the entry_ref will be written.
+
+ \retval B_OK Everything went well.
+ \retval B_BAD_VALUE \a ref was \c NULL.
+ \retval B_NO_TRANSLATOR The roster does not contain any translator with
the
+ ID \a translatorID.
+ \retval B_ERROR An error occurred.
+*/
+
+//! @}
+
+/*!
+ \name Core Methods
+*/
+
+//! @{
+
+/*!
+ \fn virtual status_t BTranslatorRoster::Identify(BPositionIO* source,\
+ BMessage* ioExtension, translator_info* _info, uint32 hintType
= 0,\
+ const char* hintMIME = NULL, uint32 wantType = 0);
+ \brief Determines the best translator in the roster to perform a certain
+ conversion.
+
+ \param source Read and seek interface to the data to be examined.
+ \param ioExtension A message containing configuration infortmation for
the
+ translators.
+ \param _info Where information about the best translator will be
written.
+ \param hintType A hint about the data format in \a source. \c 0
represents
+ an unknown type.
+ \param hintMIME A hint about the MIME type of \a source. \c NULL
represents
+ an unknown type.
+ \param wantType The format that \a source needs to be translated into.
\c 0
+ permits any output type.
+
+ To determine the best translator, for all translators that report that
+ they are able to perform the translation, the values they return for
+ quality and capability are multiplied. The translator with the highest
+ value gets returned. Note that quality and capability for the output
+ format are not taken into consideration.
+
+ \retval B_OK Identification was successful. Information about the chosen
+ translator was written to \a _info.
+ \retval B_NO_TRANSLATOR No suitable translator was found.
+ \retval B_BAD_VALUE \a source or \a _info was \c NULL.
+ \retval B_IO_ERROR There was an error interacting with \a source.
+*/
+
+/*!
+ \fn virtual status_t BTranslatorRoster::Translate(BPositionIO* source,\
+ const translator_info* info, BMessage* ioExtension,
BPositionIO*\
+ destination, uint32 wantOutType, uint32 hintType = 0, const
char*\
+ hintMIME = NULL);
+ \brief Finds and invokes the best translator for a conversion.
+
+ \param source Read and seek interface to the input data.
+ \param info Information about wich translator should be used. If
+ \a info is \c NULL, Identify() will be used to find a suitable
+ translator.
+ \param ioExtension A message containing configuration information for
the
+ translator.
+ \param destination Write interface to the output location.
+ \param wantOutType The desired output format. If this is \c 0, any type
+ is permitted.
+ \param hintType A hint about the type of the data in \a source.
+ \param hintMIME A hint about the MIME type of the data in \a source.
+
+ \retval B_OK The translated data was successfully written to
+ \a destination.
+ \retval B_NO_TRANSLATOR \a info was non-null but did not match to any
+ translator in the roster.
+ \retval B_NO_TRANSLATOR \a info was \c NULL and no suitable translator
was
+ found.
+ \retval B_ERROR An error occurred.
+ \retval B_BAD_VALUE \a source or \a destination was \c NULL or
+ \a ioExtension was \c NULL or contained bad data.
+ \retval B_IO_ERROR An error occurred accessing \a source or \a
destination.
+*/
+
+/*!
+ \fn virtual status_t BTranslatorRoster::Translate(translator_id\
+ translatorID, BPositionIO* source, BMessage* ioExtension,
BPositionIO*\
+ destination, uint32 wantOutType);
+ \brief Uses a specified translator from the roster to perform a
conversion.
+
+ \param translatorID The ID of the translator that should be used.
+ \param source Read and seek interface to the input data.
+ \param ioExtension A message containing configuration information for
the
+ translator.
+ \param destination Write interface to the output location.
+ \param wantOutType The desired output format. If this is \c 0, any type
is
+ permitted.
+
+ \retval B_OK The translated data was successfully written to
+ \a destination.
+ \retval B_NO_TRANSLATOR The specified translator cannot handle the data
in
+ \a source.
+ \retval B_ERROR An error occurred.
+ \retval B_BAD_VALUE \a source or \a destination was \c NULL or
+ \a ioExtension was \c NULL or contained bad data.
+ \retval B_IO_ERROR An error occurred accessing \a source or \a
destination.
+*/
+
+//! @}
+
+/*!
+ \name Miscellaneous
+*/
+
+//! @{
+
+/*!
+ \fn bool BTranslatorRoster::IsTranslator(entry_ref* ref);
+ \brief Determines whether the specified add-on contains at least one
+ translator.
+
+ \param ref The entry_ref to be tested.
+
+ \retval true The add-on exposes translators.
+ \retval false The add-on exposes no translators or an error occurred.
+*/
+
+//! @}
+
+/*!
+ \name Notifications
+*/
+
+//! @{
+
+/*!
+ \fn status_t BTranslatorRoster::StartWatching(BMessenger target);
+ \brief Register a messenger to be notified when the roster changes.
+
+ \param target The BMessenger to be registered.
+
+ Whenever a translator is added to or removed from the roster, all
+ messengers that were registered through this method are sent a message.
+ \c message->what will be \c B_TRANSLATOR_ADDED or \c
B_TRANSLATOR_REMOVED
+ (as defined in AppDefs.h) respectively.
+
+ \retval B_OK \a target was successfully registered.
+ \retval B_NO_MEMORY Unable to allocate more memory for the list of
targets.
+*/
+
+/*!
+ \fn status_t BTranslatorRoster::StopWatching(BMessenger target);
+ \brief Unregister a messenger from the notification list.
+
+ \param target The BMessenger to be removed.
+
+ \retval B_OK \a target was successfully unsubscribed.
+ \retval B_BAD_VALUE \a target could not be found on the notification
list.
+
+ \sa StartWatching(BMessenger target)
+*/
+
+//! @}
Other related posts:
- » [haiku-commits] haiku: hrev48595 - docs/user/translation - revol
