nephele
/
haiku-website
0
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
haiku-website/static/legacy-docs/bebook/BTranslator.html

78 lines
21 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Be Book - Classes And Methods - The Translation Kit</title><link rel="stylesheet" href="be_book.css" type="text/css" media="all" /><link rel="shortcut icon" type="image/vnd.microsoft.icon" href="./images/favicon.ico" /><!--[if IE]>
<link rel="stylesheet" type="text/css" href="be_book_ie.css" />
<![endif]--><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="Access, BeOS, BeBook, API" /><link rel="start" href="index.html" title="The Be Book" /><link rel="up" href="TheTranslationKit.html" title="The Translation Kit" /><link rel="prev" href="BTranslationUtils.html" title="BTranslationUtils" /><link rel="next" href="BTranslatorRoster.html" title="BTranslatorRoster" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BTranslationUtils.html" title="BTranslationUtils"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheTranslationKit.html" title="The Translation Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="BTranslatorRoster.html" title="BTranslatorRoster"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="headerTR"><div id="navigpeople"><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div><div class="navigboxed" id="navigindex"><a accesskey="i" href="ClassIndex.html" title="Index">I</a></div><div class="navigboxed" id="naviglang" title="English">en</div></div><div id="headerTC">The Be Book - Classes And Methods - The Translation Kit</div></div><div id="headerB">Prev: <a href="BTranslationUtils.html">BTranslationUtils</a>  Up: <a href="TheTranslationKit.html">The Translation Kit</a>  Next: <a href="BTranslatorRoster.html">BTranslatorRoster</a></div><hr /></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h2 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BTranslator"></a>BTranslator</h2></div></div></div><a id="id1292783" class="indexterm"></a><div class="classheader"><table border="0"><colgroup><col /><col /></colgroup><tbody><tr><td><table width="100%" border="0"><colgroup><col /><col /></colgroup><tbody><tr><td>Derived From:</td><td>–</td></tr><tr><td>Mix-in Classes:</td><td><a class="link" href="BArchivable.html" title="BArchivable"><code class="classname">BArchivable</code></a></td></tr><tr><td>Declared In:</td><td><code class="filename">translation/Translator.h</code></td></tr><tr><td>Library:</td><td><code class="filename">libtranslation.so</code></td></tr><tr><td>Allocation:</td><td>–</td></tr></tbody></table></td><td>
<a class="link overview" href="BTranslator_Overview.html" title="BTranslator">Class Overview</a>
<div class="toc"><ul><li><span class="section"><a href="BTranslator.html#BTranslator_ConstructorDestructor">Constructor and Destructor</a></span></li><li><span class="section"><a href="BTranslator.html#BTranslator_MemberFunctions">Member Functions</a></span></li></ul></div>
</td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BTranslator_ConstructorDestructor"></a>Constructor and Destructor</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BTranslator_Constructor"></a>BTranslator()</h4></div></div></div><code class="constructorsynopsis cpp"><span class="methodname">BTranslator</span>();</code><p>The constructor must create and return a new instance of your
<code class="classname">BTranslator</code>
subclass. Note that the constructor doesn't
<a class="link" href="BTranslator.html#BTranslator_Acquire" title="Acquire(), Release(), ReferenceCount()"><code class="methodname">Acquire()</code></a>
the object it returns.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BTranslator_Destructor"></a>~BTranslator()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="destructorsynopsis cpp"><span class="methodname">~BTranslator</span>();</code><p>Note that the destructor is protected; you can only delete a
<code class="classname">BTranslator</code>
object from within the implementation of the subclass. From outside the
class, you call
<a class="link" href="BTranslator.html#BTranslator_Release"><code class="methodname">Release()</code></a>.</p></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BTranslator_MemberFunctions"></a>Member Functions</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BTranslator_Acquire"></a><a id="BTranslator_ReferenceCount"></a>
<a id="BTranslator_Release"></a>
Acquire(), Release(), ReferenceCount()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">BTranslator* </span><span class="methodname">Acquire</span>();</code><code class="methodsynopsis cpp"><span class="type">BTranslator* </span><span class="methodname">Release</span>();</code><code class="methodsynopsis cpp"><span class="type">int32 </span><span class="methodname">ReferenceCount</span>();</code><div class="admonition warning"><div class="title">Warning</div><div class="graphic"><img class="icon" alt="Warning" width="32" src="./images/admonitions/Stop_32.png" /><div class="text"><p><code class="methodname">ReferenceCount()</code> Is For Debugging use only!</p></div></div></div><p><code class="methodname">Acquire()</code> and <code class="methodname">Release()</code>
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.</p><p>When you add a <code class="classname">BTranslator</code> to a
<a class="link" href="BTranslatorRoster.html" title="BTranslatorRoster"><code class="classname">BTranslatorRoster</code></a>,
the <code class="classname">BTranslator</code> is
automatically <code class="methodname">Acquire()</code>'d. When the
<a class="link" href="BTranslatorRoster.html" title="BTranslatorRoster"><code class="classname">BTranslatorRoster</code></a>
is deleted, its <code class="classname">BTranslator</code>s are <code class="methodname">Release()</code>'d.
Thus, when you instantiate a <code class="classname">BTranslator</code>
and add it to a
<a class="link" href="BTranslatorRoster.html" title="BTranslatorRoster"><code class="classname">BTranslatorRoster</code></a>,
you and the Roster maintain joint
ownership of the object. To give up ownership (such that the
<a class="link" href="BTranslatorRoster.html" title="BTranslatorRoster"><code class="classname">BTranslatorRoster</code></a>
will destroy the object when the Roster itself is
destroyed), call <code class="methodname">Release()</code> after adding the
<code class="classname">BTranslator</code> to the Roster.</p><p><code class="methodname">Acquire()</code> and <code class="methodname">Release()</code>
both return a pointer to the <code class="classname">BTranslator</code> that was
just acquired or released. If <code class="methodname">Release()</code> caused the object to be deleted,
it retruns <code class="constant">NULL</code>.</p><p><code class="methodname">ReferenceCount()</code>, 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.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BTranslator_GetConfigurationMessage"></a>GetConfigurationMessage()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">Optional</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">status_t </span><span class="methodname">GetConfigurationMessage</span>(<span class="methodparam"><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* </span><span class="parameter">ioExtension</span></span>);</code><p>Hook function that asks the object to write its current state into the
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>*
argument. See
<a class="link" href="TranslatorAddOns.html#GetConfigMessage" title="GetConfigMessage()"><code class="function">GetConfigMessage()</code></a>
[Translator Add-ons] for details.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BTranslator_Identify"></a>Identify()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">Required</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">status_t </span><span class="methodname">Identify</span>(<span class="methodparam"><span class="type"><a class="link" href="BPositionIO.html" title="BPositionIO"><code class="classname">BPositionIO</code></a>* </span><span class="parameter">inSource</span></span>,<br />                          <span class="methodparam"><span class="modifier">const </span><span class="type">translation_format* </span><span class="parameter">inFormat</span></span>,<br />                          <span class="methodparam"><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* </span><span class="parameter">ioExtension</span></span>,<br />                          <span class="methodparam"><span class="type">translator_info* </span><span class="parameter">outInfo</span></span>,<br />                          <span class="methodparam"><span class="type">uint32* </span><span class="parameter">outType</span></span>) <span class="modifier">= 0</span>;</code><p>Hook function called by the Translator Roster to ask the
<code class="classname">BTranslator</code> if it knows how to convert
<code class="parameter">inSource</code> into the type described by
<code class="parameter">outType</code>. See
<a class="link" href="TranslatorAddOns.html#Identify" title="Identify()"><code class="function">Identify()</code></a>
[Translator Add-ons] for details.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BTranslator_InputFormats"></a><a id="BTranslator_OutputFormats"></a>
InputFormats(), OutputFormats()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">Optional</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual const </span><span class="type">translation_format* </span><span class="methodname">InputFormats</span>(<span class="methodparam"><span class="type">int32* </span><span class="parameter">count</span></span>) <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="modifier">virtual const </span><span class="type">translation_format* </span><span class="methodname">OutputFormats</span>(<span class="methodparam"><span class="type">int32* </span><span class="parameter">count</span></span>) <span class="modifier">const</span>;</code><p>These functions should be implemented to return arrays of
<span class="type">translation_format</span> structures that describe the formats that this object
supports. If the functions aren't implemented, the object's
<a class="link" href="BTranslator.html#BTranslator_Identify" title="Identify()"><code class="methodname">Identify()</code></a>
function will be called each time an application requests a translation.
Both functions should set <code class="parameter">count</code> to the number of elements in the format
array.</p><div class="admonition important"><div class="title">Important</div><div class="graphic"><img class="icon" alt="Important" width="32" src="./images/admonitions/Warning_32.png" /><div class="text"><p>Unlike the analogous translator add-on format arrays, the arrays
returned by these functions don't have to be terminated by an empty
<span class="type">translation_format</span> structure.</p></div></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BTranslator_MakeConfigurationView"></a>MakeConfigurationView()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">Optional</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">status_t </span><span class="methodname">MakeConfigurationView</span>(<span class="methodparam"><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* </span><span class="parameter">ioExtension</span></span>,<br />                                       <span class="methodparam"><span class="type"><a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>** </span><span class="parameter">outView</span></span>,<br />                                       <span class="methodparam"><span class="type"><a class="link" href="BRect.html" title="BRect"><code class="classname">BRect</code></a>* </span><span class="parameter">outExtent</span></span>);</code><p>Hook function that lets the <code class="classname">BTranslator</code>
supply a configuration view. See
<a class="link" href="TranslatorAddOns.html#MakeConfig" title="MakeConfig()"><code class="function">MakeConfig()</code></a>
[Translator Add-ons] for details.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BTranslator_Translate"></a>Translate()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">Required</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">status_t </span><span class="methodname">MakeConfigurationView</span>(<span class="methodparam"><span class="type"><a class="link" href="BPositionIO.html" title="BPositionIO"><code class="classname">BPositionIO</code></a>* </span><span class="parameter">inSource</span></span>,<br />                                       <span class="methodparam"><span class="modifier">const </span><span class="type">translator_info* </span><span class="parameter">inInfo</span></span>,<br />                                       <span class="methodparam"><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* </span><span class="parameter">ioExtension</span></span>,<br />                                       <span class="methodparam"><span class="type">uint32* </span><span class="parameter">outType</span></span>,<br />                                       <span class="methodparam"><span class="type"><a class="link" href="BPositionIO.html" title="BPositionIO"><code class="classname">BPositionIO</code></a>* </span><span class="parameter">outDestination</span></span>) <span class="modifier">= 0</span>;</code><p>Hook function that asks the <code class="classname">BTranslator</code> to
translate data from <code class="parameter">inSource</code> to format
<code class="parameter">outType</code>, writing the output to
<code class="parameter">outDestination</code>. See
<a class="link" href="BTranslator.html#BTranslator_Translate" title="Translate()"><code class="methodname">Translate()</code></a>
[Translator Add-ons] for details.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BTranslator_TranslatorInfo"></a><a id="BTranslator_TranslatorName"></a>
<a id="BTranslator_TranslatorVersion"></a>
TranslatorInfo(), TranslatorName(), TranslatorVersion()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">Required</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual const </span><span class="type">char * </span><span class="methodname">TranslatorInfo</span>() <span class="modifier">const = 0</span>;</code><code class="methodsynopsis cpp"><span class="modifier">virtual const </span><span class="type">char * </span><span class="methodname">TranslatorName</span>() <span class="modifier">const = 0</span>;</code><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">int32 </span><span class="methodname">TranslatorVersion</span>() <span class="modifier">const = 0</span>;</code><p><code class="methodname">TranslatorInfo()</code> returns a pointer to the
translator's long name, e.g. "aiff translator by the Pie Man
(pie@the.man)".</p><p><code class="methodname">TranslatorName()</code> returns a pointer to the
translator's short name, e.g. "aiff translator". The short name
should be appropriate for display in a menu.</p><p><code class="methodname">TranslatorVersion()</code> gives an "MM.mm"
version number for the translator. For example, a
<code class="methodname">TranslatorVersion()</code> of 314 is interpreted as
version 3.14.</p></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BTranslationUtils.html">BTranslationUtils</a>  Up: <a href="TheTranslationKit.html">The Translation Kit</a>  Next: <a href="BTranslatorRoster.html">BTranslatorRoster</a> </div><div id="footerB"><div id="footerBL"><a href="BTranslationUtils.html" title="BTranslationUtils"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheTranslationKit.html" title="The Translation Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="BTranslatorRoster.html" title="BTranslatorRoster"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="footerBR"><div><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div></div><div id="footerBC"><a href="http://www.access-company.com/home.html" title="ACCESS Co."><img alt="Access Company" src="./images/access_logo.png" /></a></div></div></div><div id="licenseFooter"><div id="licenseFooterBL"><a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/" title="Creative Commons License"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/l/by-nc-nd/3.0/88x31.png" /></a></div><div id="licenseFooterBR"><a href="./LegalNotice.html">Legal Notice</a></div><div id="licenseFooterBC"><span id="licenseText">This work is licensed under a
<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative
Commons Attribution-Non commercial-No Derivative Works 3.0 License</a>.</span></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink