[haiku-commits] haiku: hrev48586 - docs/user/translation
- From: revol@xxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Tue, 30 Dec 2014 04:55:54 +0100 (CET)
hrev48586 adds 1 changeset to branch 'master'
old head: 38606bbb1cace972b5f298c2ff287e849975b530
new head: d7c90b627547c6a9b92ba84995b7e51c7b2397ba
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=d7c90b6+%5E38606bb
----------------------------------------------------------------------------
d7c90b6: Add doxygen file for BTranslator class.
By Markus Himmel (GCI2014).
[ François Revol <revol@xxxxxxx> ]
----------------------------------------------------------------------------
Revision: hrev48586
Commit: d7c90b627547c6a9b92ba84995b7e51c7b2397ba
URL: http://cgit.haiku-os.org/haiku/commit/?id=d7c90b6
Author: François Revol <revol@xxxxxxx>
Date: Tue Dec 30 03:54:19 2014 UTC
----------------------------------------------------------------------------
1 file changed, 313 insertions(+)
docs/user/translation/Translator.dox | 313 +++++++++++++++++++++++++++++++
----------------------------------------------------------------------------
diff --git a/docs/user/translation/Translator.dox
b/docs/user/translation/Translator.dox
new file mode 100644
index 0000000..dbffb9f
--- /dev/null
+++ b/docs/user/translation/Translator.dox
@@ -0,0 +1,313 @@
+/*
+ * Copyright 2014 Markus Himmel. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ *
+ * Authors:
+ * Markus Himmel, markus@xxxxxxxxxxxxxxxxx
+ *
+ * Corresponds to:
+ * headers/os/translation/Translator.h hrev48573
+ * src/kits/translation/Translator.cpp hrev48573
+ */
+
+/*!
+ \file Translator.h
+ \ingroup translation
+ \ingroup libbe
+ \brief BTranslator class definition.
+*/
+
+/*!
+ \file TranslationDefs.h
+ \ingroup translation
+ \ingroup libbe
+ \brief Defines structures and preprocessor macros that are used by the
+ translation kit.
+*/
+
+/*!
+ \file TranslatorFormats.h
+ \ingroup translation
+ \ingroup libbe
+ \brief Defines identifiers and structures for data formats and
configuration
+ messages.
+*/
+
+/*!
+ \class BTranslator
+ \ingroup translation
+ \ingroup libbe
+ \brief Abstract class that defines the necessary functionality of a
+ translator.
+
+ BTranslator is the core class of the translation kit.
+ Every translator defines input and output data types it can work with. A
+ BTranslator uses BPositionIO as an abstraction for the data it operates
on.
+ It is able to
+ decide wether incoming data is of any of its known input types and, upon
+ successful identification, translate it to any of its output formats. It
+ may also provide a config view that appears in the DataTranslations
+ preference app.
+
+ Usually, a translator is very specific. It only offers translations
+ between the format it was created for and the basic format for that
media
+ type. As an example, the translator for GIF images only translates
between
+ GIF images and bitmaps, the baseline format for images.
+
+ The function `make_nth_translator` enables add-ons to expose
translators.
+ Communication between applications and BTranslators is carried
+ out by the BTranslatorRoster class.
+
+ \note Another option to create a translator is using a BFuncTranslator.
+
+ \remark In most cases it is easier to derive from BaseTranslator instead
+ of BTranslator. BaseTranslator provides a lot of functionality
that is
+ common for most translators as well as a unified method to save
settings
+ and routines for handling bitmaps.
+
+ \since BeOS R3
+*/
+
+/*!
+ \name Constructor and reference counting
+*/
+
+//! @{
+
+/*!
+ \fn BTranslator::BTranslator()
+ \brief Creates a new BTranslator and sets its reference count to 1.
+
+ \since BeOS R3
+*/
+
+/*!
+ \fn BTranslator* BTranslator::Acquire()
+ \brief Increments the reference count by 1 and returns a pointer to
+ itself.
+
+ \returns `this`.
+
+ \since BeOS R3
+*/
+
+/*!
+ \fn BTranslator* BTranslator::Release()
+ \brief Decrements the reference count by 1. If the reference count is
+ decreased to zero, the object is deleted.
+
+ \returns `this` if the object was not destroyed, `NULL` if it was.
+
+ \since BeOS R3
+*/
+
+/*!
+ \fn int32 BTranslator::ReferenceCount()
+ \brief Gets the current reference count.
+
+ \returns The current reference count.
+
+ \since BeOS R3
+*/
+
+//! @}
+
+/*!
+ \name Accessors
+*/
+
+//! @{
+
+/*!
+ \fn virtual const char* BTranslator::TranslatorName() const = 0
+ \brief Pure virtual. Returns the name of the translator.
+
+ Amongst other uses, the name is used to populate Save as-dropdowns and
for
+ the preference window.
+
+ \returns The name of the translator.
+
+ \since BeOS R3
+*/
+
+/*!
+ \fn virtual const char* BTranslator::TranslatorInfo() const = 0
+ \brief Pure virtual. Returns a brief description of the translator.
+
+ \returns A brief description of the translator.
+
+ \since BeOS R3
+*/
+
+/*!
+ \fn virtual int32 BTranslator::TranslatorVersion() const = 0
+ \brief Pure virtual. Returns the version of the translator.
+
+ The correct way to format the version is using the
+ `B_TRANSLATION_MAKE_VERSION` macro from TranslationDefs.h.
+
+ \returns The version of the translator.
+
+ \since BeOS R3
+*/
+
+/*!
+ \fn virtual const translation_format*\
+ BTranslator::InputFormats(int32* _count) const = 0
+ \brief Pure virtual. Returns an array containing information about all
+ input formats the translator can handle.
+
+ \param _count Where the number of input formats that are returned will
be
+ written.
+
+ \returns A pointer to the first element of the array of input formats.
+
+ \since BeOS R3
+*/
+
+/*!
+ \fn virtual const translation_format*\
+ BTranslator::OutputFormats(int32* _count) const = 0
+ \brief Pure virtual. Returns an array containing information about all
+ output formats the translator can produce.
+
+ \param _count Where the number of output formats that are returned will
be
+ written.
+
+ \returns A pointer to the first element of the array of output formats.
+
+ \since BeOS R3
+*/
+
+//! @}
+
+/*!
+ \name Core methods
+*/
+
+//! @{
+
+/*!
+ \fn virtual status_t BTranslator::Identify(BPositionIO* source, const\
+ translation_format* format, BMessage* extension,
translator_info* info,\
+ uint32 outType) = 0;
+ \brief Pure virtual. Analyzes *source* and decides whether this
translator
+ can work with the provided format.
+
+ The translator examines the data in source and tries to identify its
format
+ (for instance by checking for magic numbers). It may use the hints
provided by *format*.
+ If it is successful, and it is able to translate the data at hand
+ to *outType*, it populates *info* with information about the input
format
+ and returns `B_OK`. If it is unable to identify the data or cannot
translate
+ it to *outType*, it returns `B_NO_TRANSLATOR`.
+
+ \param source Read and seek interface to the input data.
+ \param format Hints about the incoming data.
+ \param extension A message containing configuration information
for the
+ translator. A standard set of possible fields is defined in
+ TranslatorFormats.h.
+ \param info Where the translator will write information about the
determined
+ input format in case identification is successful.
+ \param outType If *outType* is non-zero, identification will only be
+ successful if the translator can transform the data in source
to the
+ format denoted by *outType*.
+ \warning When creating a translator, be prepared for the information
+ in *format* to be inaccurate or wrong.
+
+ \retval B_OK The translator has identified the data in *source*, has
+ verified its ability to translate it to *outType* and has
+ written information describing it to *info*.
+ \retval B_NO_TRANSLATOR The translator does not know how to handle the
+ data in *source* or cannot translate it to *outType*.
+ \retval B_BAD_VALUE *extension* was `NULL` or contained bad data.
+ \retval B_ERROR An error occurred.
+
+ \since BeOS R3
+*/
+
+/*!
+ \fn virtual status_t BTranslator::Translate(BPositionIO* source, const\
+ translation_format* info, BMessage* extension, uint32 outType,\
+ BPositionIO* destination) = 0
+ \brief Pure virtual. Reads the provided data and tries to translate it
+ to a given format.
+
+ The translator attempts to translate the data in *source*, which may or
may
+ not have the format represented by *info*, to *outType* and then write
+ the result to *destination*. Upon success, it returns `B_OK`.
+
+ \param source Read and seek interface to the input data.
+ \param info Hints about the incoming data.
+ \param extension A message containing configuration information for the
+ translator. A standard set of possible fields is defined in
+ TranslatorFormats.h.
+ \param outType The identifier of the desired output format. An
*outType* of
+ 0 is equivalent to the defualt format for the media type if the
+ translator.
+ \param destination Write interface for the destination of the data.
+ \warning When creating a translator, be prepared for the information
+ in *format* to be inaccurate or wrong.
+
+ \retval B_OK The translated data was successfully written to
destination.
+ \retval B_ERROR An error occurred during memory allocation or the
+ conversion itself.
+ \retval B_BAD_VALUE *extension* was `NULL` or contained bad data.
+ \retval B_NO_TRANSLATOR The translator cannot handle the input.
+
+ \since BeOS R3
+*/
+
+//! @}
+
+/*!
+ \name Configuration methods
+*/
+
+//! @{
+
+/*!
+ \fn virtual status_t BTranslator::MakeConfigurationView(BMessage*\
+ extension, BView** _view, BRect* _extent)
+ \brief Virtual. Creates a BView that contains information and
configuration
+ options for the translator.
+
+ This method is optional. If the translator chose not to implement
+ it, `B_ERROR` will be returned.
+
+ \param extension A message containing configuration information for the
+ translator. A standard set of possible fields is defined in
+ 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
+ be stored.
+ \retval B_OK Everything went well.
+ \retval B_ERROR An error occurred or the method was not overriden by the
+ translator.
+ \retval B_BAD_VALUE *_view* or *_extent* were `NULL` or *extension*
+ was `NULL` or contained bad data.
+
+ \since BeOS R3
+*/
+
+/*!
+ \fn virtual status_t BTranslator::GetConfigurationMessage(BMessage*\
+ extension)
+ \brief Populates a BMessage with the settings of the translator.
+
+ A standard set of possible fields is defined in TranslatorFormats.h.
This
+ method is optional. If the translator chose not to implement it,
`B_ERROR`
+ will be returned.
+
+ \param extension The BMessage that is populated.
+
+ \retval B_OK Everything went well.
+ \retval B_ERROR An error occurred or the method was not overriden by the
+ translator.
+ \retval B_BAD_VALUE *extension* was `NULL`.
+
+ \since BeOS R3
+*/
+
+//! @}
Other related posts:
- » [haiku-commits] haiku: hrev48586 - docs/user/translation - revol
