BTranslator

Constructor and Destructor

BTranslator()

BTranslator::BTranslator()

The constructor must create and return a new instance of your BTranslator subclass. Note that the constructor doesn’t Acquire() the object it returns.

~BTranslator()

BTranslator::~BTranslator()

Note that the destructor is protected; you can only delete a BTranslator object from within the implementation of the subclass. From outside the class, you call Release().

Member Functions

Acquire(), Release(), ReferenceCount()

BTranslator *BTranslator::Acquire()

BTranslator *BTranslator::Release()

int32 BTranslator::ReferenceCount()

Warning

ReferenceCount() Is For Debugging use only!

Acquire() and Release() increment and decrement the object’s reference count. The count starts at 1 (i.e .the object is implicitly acquired when it’s created); if the count falls to 0, the object is deleted.

When you add a BTranslator to a BTranslatorRoster, the BTranslator is automatically Acquire()’d. When the BTranslatorRoster is deleted, its BTranslators are Release()’d. Thus, when you instantiate a BTranslator and add it to a BTranslatorRoster, you and the Roster maintain joint ownership of the object. To give up ownership (such that the BTranslatorRoster will destroy the object when the Roster itself is destroyed), call Release() after adding the BTranslator to the Roster.

Acquire() and Release() both return a pointer to the BTranslator that was just acquired or released. If Release() caused the object to be deleted, it retruns NULL.

ReferenceCount(), which returns the current reference count value, is meant for debugging purposes only. It is not thread-safe! Don’t predicate your code on the value it returns.

GetConfigurationMessage()

virtual status_t BTranslator::GetConfigurationMessage(BMessage *ioExtension)

Hook function that asks the object to write its current state into the BMessage* argument. See GetConfigMessage() [Translator Add-ons] for details.

Identify()

virtual status_t BTranslator::Identify(BPositionIO *inSource, const translation_format *inFormat, BMessage *ioExtension, translator_info *outInfo, uint32 *outType) = 0

Hook function called by the Translator Roster to ask the BTranslator if it knows how to convert inSource into the type described by outType. See Identify() [Translator Add-ons] for details.

InputFormats(), OutputFormats()

virtual const translation_format *BTranslator::InputFormats(int32 *count) const

virtual const translation_format *BTranslator::OutputFormats(int32 *count) const

These functions should be implemented to return arrays of translation_format structures that describe the formats that this object supports. If the functions aren’t implemented, the object’s Identify() function will be called each time an application requests a translation. Both functions should set count to the number of elements in the format array.

Important

Unlike the analogous translator add-on format arrays, the arrays returned by these functions don’t have to be terminated by an empty translation_format structure.

MakeConfigurationView()

virtual status_t BTranslator::MakeConfigurationView(BMessage *ioExtension, BView **outView, BRect *outExtent)

Hook function that lets the BTranslator supply a configuration view. See MakeConfig() [Translator Add-ons] for details.

MakeConfigurationView()

virtual status_t BTranslator::MakeConfigurationView(BPositionIO *inSource, const translator_info *inInfo, BMessage *ioExtension, uint32 *outType, BPositionIO *outDestination) = 0

Hook function that asks the BTranslator to translate data from inSource to format outType, writing the output to outDestination. See Translate() [Translator Add-ons] for details.

TranslatorInfo(), TranslatorName(), TranslatorVersion()

virtual const char *BTranslator::TranslatorInfo() const = 0

virtual const char *BTranslator::TranslatorName() const = 0

virtual int32 BTranslator::TranslatorVersion() const = 0

TranslatorInfo() returns a pointer to the translator’s long name, e.g. “aiff translator by the Pie Man (pie@the.man)”.

TranslatorName() returns a pointer to the translator’s short name, e.g. “aiff translator”. The short name should be appropriate for display in a menu.

TranslatorVersion() gives an “MM.mm” version number for the translator. For example, a TranslatorVersion() of 314 is interpreted as version 3.14.