The Translation Kit: BTranslator

The Translation Kit Table of Contents | The Translation Kit Index

# BTranslator

Derived from: BArchivable

Declared in: be/translation/Translator.h

Library: libtranslation.so

###### Summary

BTranslator is an abstract superclass that you subclass to define your own proprietary translator objects, one translator per BTranslator subclass. You add instances of your BTranslator subclasses to a BTranslatorRoster through `BTranslatorRoster::AddTranslator()`. BTranslator objects that your app creates and adds to the Roster are not visible to other applications.

Note that the BTranslator destructor is protected; you never `delete` a BTranslator from outside the class. Insead, you `Release()` it. See `Acquire()` for details.

The primary BTranslator functions are similar to the functions and data that a translator add-on supplies. Most of the BTranslator functions take you to the Translator Add-ons descriptions.

## Constructor and Destructor

### 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() `

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 *`Acquire(`void`) `
BTranslator *`Release(`void`) `
int32 `ReferenceCount(`void`)` 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.

### ReferenceCount() see Acquire()

### GetConfigurationMessage()

virtual status_t `GetConfigurationMessage(` BMessage *ioExtension`) `

| Optional

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 `Identify(`BPositionIO *inSource,
const translation_format *inFormat,
BMessage *ioExtension,
translator_info *outInfo,
uint32 outType`)` = 0

| Required

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` *`InputFormats`(int32 *count) const
virtual const `translation_format` *`OutputFormats`(int32 *count) const

| Optional

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.

| 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 `MakeConfigurationView(` BMessage *ioExtension, BView **outView, BRect *outExtent`) `

| Optional

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

### OutputFormats() see InputFormats()

### Translate()

virtual status_t `Translate(`BPositionIO *inSource,
const translator_info *inInfo,
BMessage *ioExtension,
uint32 outType,
BPositionIO *outDestination`)` = 0

| Required

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 *`TranslatorInfo(`void`)` const = 0
virtual const char *`TranslatorName(`void`)` const = 0
virtual int32 `TranslatorVersion(`void`)` const = 0

| Required

`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.

The Translation Kit Table of Contents | The Translation Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..