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

160 lines
30 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 Media 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="TheMediaKit.html" title="The Media Kit" /><link rel="prev" href="BContinuousParameter.html" title="BContinuousParameter" /><link rel="next" href="BDiscreteParameter.html" title="BDiscreteParameter" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BContinuousParameter.html" title="BContinuousParameter"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheMediaKit.html" title="The Media Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="BDiscreteParameter.html" title="BDiscreteParameter"><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 Media Kit</div></div><div id="headerB">Prev: <a href="BContinuousParameter.html">BContinuousParameter</a>  Up: <a href="TheMediaKit.html">The Media Kit</a>  Next: <a href="BDiscreteParameter.html">BDiscreteParameter</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="BControllable"></a>BControllable</h2></div></div></div><a id="id1128251" 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><a class="link" href="BParameter.html" title="BParameter"><code class="classname">BParameter</code></a></td></tr><tr><td>Mix-in Classes:</td><td>–</td></tr><tr><td>Declared In:</td><td><code class="filename">media/ParameterWeb.h</code></td></tr><tr><td>Library:</td><td><code class="filename">libmedia.so</code></td></tr><tr><td>Allocation:</td><td>Constructor only</td></tr></tbody></table></td><td>
<a class="link overview" href="BControllable_Overview.html" title="BControllable">Class Overview</a>
<div class="toc"><ul><li><span class="section"><a href="BControllable.html#BControllable_ConstructorDestructor">Constructor and Destructor</a></span></li><li><span class="section"><a href="BControllable.html#BControllable_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="BControllable_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="BControllable_Constructor"></a>BControllable()</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="constructorsynopsis cpp"><span class="modifier">explicit </span><span class="methodname">BControllable</span>();</code><p>The <code class="classname">BControllable</code> constructor. You should override this in your derived
class to create a
<a class="link" href="BParameterWeb.html" title="BParameterWeb"><code class="classname">BParameterWeb</code></a>
object, configure it to describe the available parameters, and call
<a class="link" href="BControllable.html#BControllable_SetParameterWeb" title="SetParameterWeb(), Web()"><code class="methodname">SetParameterWeb()</code></a>
with that object before returning.</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="BControllable_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="BControllable_BroadcastChangedParameter"></a>BroadcastChangedParameter()</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="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">BroadcastChangedParameter</span>(<span class="methodparam"><span class="type">int32 </span><span class="parameter">parameterID</span></span>);</code><p>When the configuration of a specific parameter changes, you should call
this function with the ID of the changed parameter so that clients know
that they need to check with the node to determine the parameter's new
configuration.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>The configuration of a parameter changes only when the range of
possible values for the parameter changes. For example, if the
parameter's value is a CD track number, the configuration would change
(thus requiring a call to
<a class="link" href="BControllable.html#BControllable_BroadcastChangedParameter" title="BroadcastChangedParameter()"><code class="methodname">BroadcastChangedParameter()</code></a>)
if the user put in a different CD with a different number of tracks on it.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>No errors.</p></td></tr><tr><td><p><span class="term">Other errors.</span></p></td><td><p>See
<a class="link" href="BMessenger.html#BMessenger_SendMessage" title="SendMessage()"><code class="methodname">BMessenger::SendMessage()</code></a></p></td></tr></tbody></table></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="BControllable_BroadcastNewParameterValue"></a>BroadcastNewParameterValue()</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="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">BroadcastNewParameterValue</span>(<span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">when</span></span>,<br />                                    <span class="methodparam"><span class="type">int32 </span><span class="parameter">id</span></span>,<br />                                    <span class="methodparam"><span class="type">void* </span><span class="parameter">newValue</span></span>,<br />                                    <span class="methodparam"><span class="type">size_t </span><span class="parameter">valueSize</span></span>);</code><p>Call this function when a parameter value change takes effect and you
want people that are interested in knowing about the change to stay in
sync with you. Unlike
<a class="link" href="BControllable.html#BControllable_BroadcastChangedParameter" title="BroadcastChangedParameter()"><code class="methodname">BroadcastChangedParameter()</code></a>,
this function actually passes along the new value of the parameter.</p><p>The <code class="parameter">when</code> argument indicates the
performance time at which the change took effect. The
<code class="parameter">id</code> indicates the parameter ID of the parameter
whose value changed. <code class="parameter">newValue</code> is a pointer to
the parameter's data, and <code class="parameter">valueSize</code> defines the
size of that data.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term">Other errors.</span></p></td><td><p>An error occurred communicating with the Media Server,
or with a node in the roster.</p></td></tr></tbody></table></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="BControllable_GetParameterValue"></a><a id="BControllable_SetParameterValue"></a>
GetParameterValue(), SetParameterValue()</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="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">status_t </span><span class="methodname">GetParameterValue</span>(<span class="methodparam"><span class="type">int32 </span><span class="parameter">parameterID</span></span>,<br />                                   <span class="methodparam"><span class="type">bigtime_t* </span><span class="parameter">lastChangeTime</span></span>,<br />                                   <span class="methodparam"><span class="type">void* </span><span class="parameter">value</span></span>,<br />                                   <span class="methodparam"><span class="type">size_t* </span><span class="parameter">ioSize</span></span>) <span class="modifier"> = 0</span>;</code><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">SetParameterValue</span>(<span class="methodparam"><span class="type">int32 </span><span class="parameter">parameterID</span></span>,<br />                               <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">changeTime</span></span>,<br />                               <span class="methodparam"><span class="modifier">const </span><span class="type">void* </span><span class="parameter">value</span></span>,<br />                               <span class="methodparam"><span class="type">size_t </span><span class="parameter">size</span></span>) <span class="modifier"> = 0</span>;</code><p>You should implement
<code class="methodname">GetParameterValue()</code> to store the value of the
parameter with the specified <code class="parameter">parameterID</code> in the
memory pointed to by <code class="parameter">value</code>. The
<span class="type">size_t</span> value pointed to by
<code class="parameter">ioSize</code> specifies the size of the value buffer;
prior to returning, your implementation of
<code class="methodname">GetParameterValue()</code> should change
<code class="parameter">ioSize</code> to the actual size of the returned
data.</p><p>Also, you should set <code class="parameter">lastChangeTime</code>
to the time at which the control's value most recently changed.</p><p><code class="methodname">GetParameterValue()</code> should return
<code class="constant">B_OK</code> when done, or an appropriate error
code if something goes wrong.</p><p>Likewise, you should implement <code class="methodname">SetParameterValue()</code> to change the value of
the parameter; the <code class="parameter">changeTime</code> argument is the performance time at which
the change should occur; in other words, you may need to queue the
request so it can be handled at the requested time. <code class="parameter">value</code> points to the
value to which the parameter should be set, and <code class="parameter">size</code> is the number of
bytes of data in the value.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>It's possible that a single parameter may have several channels of
values, if that parameter is a multi-channel parameter. For example, if
the parameter is a two-channel slider (such as a stereo gain control,
where the left and right channels are controlled individually within a
single parameter), the <code class="parameter">value</code> argument would point to an array of two
<span class="type">float</span>s, and <code class="parameter">size</code> would be 8
(<span class="code"><code class="function">sizeof</code>(<span class="type">float</span>) * 2</span>).</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="BControllable_HandleMessage"></a>HandleMessage()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">status_t </span><span class="methodname">HandleMessage</span>(<span class="methodparam"><span class="type">int32 </span><span class="parameter">message</span></span>,<br />                               <span class="methodparam"><span class="modifier">const </span><span class="type">void* </span><span class="parameter">data</span></span>,<br />                               <span class="methodparam"><span class="type">size_t* </span><span class="parameter">size_t</span></span>);</code><p>When your node's service loop receives a message, in addition to passing
it to <a class="link" href="BMediaNode.html" title="BMediaNode"><code class="classname">BMediaNode</code></a>
and other superclasses of your node, you should also
pass it to
<code class="methodname">HandleMessage()</code>.
You should start at the most-derived class' implementation of
<code class="methodname">HandleMessage()</code> and work your way
upward until <code class="constant">B_OK</code> is returned.</p><p>If it's a message intended for the
<a class="link" href="BControllable.html" title="BControllable"><code class="classname">BControllable</code></a> interface, it'll be
dispatched and <code class="constant">B_OK</code> will be returned; otherwise,
<code class="methodname">HandleMessage()</code> will
return an error so you know to try something else.</p><pre class="programlisting example cpp"><span class="comment">/* Message received */</span>
if ((<code class="classname">BControllable</code>::<code class="methodname">HandleMessage</code>(<code class="varname">message</code>, <code class="varname">data</code>, <code class="varname">size</code>) != <code class="constant">B_OK</code>) &amp;&amp;
(<code class="classname">BMediaNode</code>::<code class="methodname">HandleMessage</code>(<code class="varname">message</code>, <code class="varname">data</code>, <code class="varname">size</code>) != <code class="constant">B_OK</code>)) {
<code class="classname">BMediaNode</code>::<code class="methodname">HandleMessage</code>(<code class="varname">message</code>, <code class="varname">data</code>, <code class="varname">size</code>);
}</pre><p>In this example, the
<code class="classname">BControllable</code> implementation of <code class="methodname">HandleMessage()</code> gets
the first crack at handling the request. If it doesn't know what to do
with the message, it's forwarded to
<a class="link" href="BMediaNode.html" title="BMediaNode"><code class="classname">BMediaNode</code></a>'s
implementation. If the
message still isn't handled, it's then sent to
<a class="link" href="BMediaNode.html#BMediaNode_HandleBadMessage" title="HandleBadMessage()"><code class="methodname">BMediaNode::HandleBadMessage()</code></a>
to be dealt with.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>The message was dispatched.</p></td></tr><tr><td><p><span class="term">Other errors.</span></p></td><td><p>Each message code may respond with various error codes.</p></td></tr></tbody></table><p>See also: "<a class="xref" href="TheMediaKit_Overview_Introduction.html#TheMediaKit_AboutMultipleVirtualInheritance" title="About Multiple Virtual Inheritance">About Multiple Virtual Inheritance</a>"</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="BControllable_LockParameterWeb"></a><a id="BControllable_UnlockParameterWeb"></a>
LockParameterWeb(), UnlockParameterWeb()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">LockParameterWeb</span>();</code><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">UnlockParameterWeb</span>();</code><p><code class="methodname">LockParameterWeb()</code> locks the web to
prevent access to it while you're working on it, and
<code class="methodname">UnlockParameterWeb()</code> releases it when you're
done. You should surround your accesses to the web with these
calls:</p><pre class="programlisting example cpp"><code class="methodname">LockParameterWeb</code>();
<code class="methodname">Web</code>()-&gt;<code class="methodname">MakeGroup</code>("EqualizerControls");
...
<code class="methodname">UnlockParameterWeb</code>();</pre></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="BControllable_MakeParameterData"></a><a id="BControllable_ApplyParameterData"></a>
MakeParameterData(), ApplyParameterData()</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="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">MakeParameterData</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">int32* </span><span class="parameter">parameterList</span></span>,<br />                           <span class="methodparam"><span class="type">int32 </span><span class="parameter">numParameters</span></span>,<br />                           <span class="methodparam"><span class="type">void* </span><span class="parameter">buffer</span></span>,<br />                           <span class="methodparam"><span class="type">size_t* </span><span class="parameter">ioSize</span></span>);</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">ApplyParameterData</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">void* </span><span class="parameter">value</span></span>,<br />                            <span class="methodparam"><span class="type">size_t </span><span class="parameter">ioSize</span></span>);</code><p>The <code class="methodname">MakeParameterData()</code> utility function takes a list of parameter IDs
from <code class="parameter">parameterList</code> and calls
<a class="link" href="BControllable.html#BControllable_GetParameterValue" title="GetParameterValue(), SetParameterValue()"><code class="methodname">GetParameterValue()</code></a>
for each of them,
storing the values in the specified <code class="parameter">buffer</code> until the size specified in
<code class="parameter">ioSize</code> is filled, or all the parameters are read. The number of bytes of
the buffer used will be returned in <code class="parameter">ioSize</code>.</p><p>If your <code class="classname">BControllable</code> is also a
<a class="link" href="BBufferConsumer.html" title="BBufferConsumer"><code class="classname">BBufferConsumer</code></a> that accepts
<code class="constant">B_MEDIA_PARAMETERS</code> type data on some input, call
<code class="methodname">ApplyParameterData()</code>
with <code class="parameter">value</code> set to the result of
<a class="link" href="BBuffer.html#BBuffer_Data" title="Data()"><code class="methodname">BBuffer::Data()</code></a>
and <code class="parameter">size</code> set to
<a class="link" href="BBuffer.html#BBuffer_SizeUsed" title="SizeUsed(), SetSizeUsed()"><code class="methodname">BBuffer::SizeUsed()</code></a>.
This function will then parse the parameter change
requests in the buffer and dispatch them to your <code class="methodname">SetParameterValue()</code>
function to fulfill the requests.</p><p>This lets your node support easy automation of parameter information.
Even more benefit can be obtained by also deriving from
<a class="link" href="BBufferProducer.html" title="BBufferProducer"><code class="classname">BBufferProducer</code></a>,
and providing an output for the <code class="constant">B_MEDIA_PARAMETERS</code> data format, so that
changes can be recorded as they occur. This provides a mechanism for
automating the parameters by recording a user's changes to them, then
playing back the changes later.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>No errors.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_MEMORY</code>.</span></p></td><td><p>The output buffer is too small.</p></td></tr></tbody></table></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="BControllable_SetParameterWeb"></a><a id="BControllable_Web"></a>
SetParameterWeb(), Web()</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="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetParameterWeb</span>(<span class="methodparam"><span class="type"><span class="classname">BParameterWeb</span>* </span><span class="parameter">web</span></span>);</code><code class="methodsynopsis cpp"><span class="type"><span class="classname">BParameterWeb</span>* </span><span class="methodname">SetParameterWeb</span>();</code><p>Your constructor should create a
<a class="link" href="BParameterWeb.html" title="BParameterWeb"><code class="classname">BParameterWeb</code></a>
object and call
<code class="methodname">SetParameterWeb()</code> with it as an argument. This will describe to the
outside world what parameters are available and how they relate to each
other; in other words, this describes your internal signal path, and how
it can be manipulated.</p><p>If the <code class="parameter">web</code> argument isn't
<code class="constant">NULL</code>, and is different from the
previously-established web for the <code class="classname">BControllable</code> node, a
<code class="constant">B_MEDIA_WEB_CHANGED</code> message is sent to everyone watching for media
notifications. See
<a class="link" href="BMediaRoster.html#BMediaRoster_StartWatching" title="StartWatching(), StopWatching()"><code class="methodname">StartWatching()</code></a>
for more information.</p><p><code class="methodname">SetParameterWeb()</code> will
return <code class="constant">B_OK</code> if the web was set without errors;
otherwise an error code will be returned.</p><p>The <code class="methodname">Web()</code> function returns the
<a class="link" href="BParameterWeb.html" title="BParameterWeb"><code class="classname">BParameterWeb</code></a>
assigned to the <code class="classname">BControllable</code>.</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="BControllable_StartControlPanel"></a>StartControlPanel()</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="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">status_t </span><span class="methodname">StartControlPanel</span>(<span class="methodparam"><span class="type"><span class="classname">BMessenger</span>* </span><span class="parameter">outMessenger</span></span>);</code><p>This hook function is called whenever a client application wants the node
to present its own control panel user interface (so that the user can
configure the node).</p><p>On return, <code class="parameter">outMessenger</code> is a
<a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a>
that you can use to communicate with the control panel.</p><p>Because the add-on lives in the Media Server, and a problem in the user
interface could bring down the entire system, it's recommended that the
control panel run as its own team. This can be done easily by writing
your node as both a Media Server add-on (by exporting
<code class="function">make_media_addon()</code>)
and an application (by implementing <code class="function">main()</code> and including
<code class="filename">start_dyn.o</code>
among the link libraries). Be sure you have the multi-launch application
flags set on your add-on, or this won't work right.</p><p>Then your <code class="methodname">StartControlPanel()</code>
implementation can simply launch the add-on
as an application, and if the user double-clicks the add-on, they'll be
presented with the control panel. In addition, the user benefits by only
having to install a single file for your add-on to work properly.</p><p>The first argv argument to your <code class="function">main()</code> function will be a string of the
format "node=%d" with the node ID in question as "%d".</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>The above implementation suggestion (providing your control panel by
launching the add-on as an application) is the default behavior of
<code class="methodname">StartControlPanel()</code>, so if that's how
you implement your <code class="classname">BControllable</code>,
you don't have to override <code class="methodname">StartControlPanel()</code>
at all. In this case, the returned
<a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a>
is for the control panel application, and not for a particular
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a> or
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
therein.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>No errors occurred.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_ERROR</code>.</span></p></td><td><p>Node wasn't loaded from an add-on.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code>.</span></p></td><td><p>An error occurred locating the image from which the node
was loaded, or the add-on can't be launched as an application.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_LAUNCH_FAILED</code>.</span></p></td><td><p>The control panel couldn't be launched for some
other reason, such as insufficient memory.</p></td></tr></tbody></table></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BContinuousParameter.html">BContinuousParameter</a>  Up: <a href="TheMediaKit.html">The Media Kit</a>  Next: <a href="BDiscreteParameter.html">BDiscreteParameter</a> </div><div id="footerB"><div id="footerBL"><a href="BContinuousParameter.html" title="BContinuousParameter"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheMediaKit.html" title="The Media Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="BDiscreteParameter.html" title="BDiscreteParameter"><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