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

104 lines
13 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.

<?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 - System Overview - The Application 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="TheApplicationKit_Overview.html" title="The Application Kit" /><link rel="prev" href="BCursor_Overview.html" title="BCursor" /><link rel="next" href="BInvoker_Overview.html" title="BInvoker" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BCursor_Overview.html" title="BCursor"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheApplicationKit_Overview.html" title="The Application Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="BInvoker_Overview.html" title="BInvoker"><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 - System Overview - The Application Kit</div></div><div id="headerB">Prev: <a href="BCursor_Overview.html">BCursor</a>  Up: <a href="TheApplicationKit_Overview.html">The Application Kit</a>  Next: <a href="BInvoker_Overview.html">BInvoker</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="BHandler_Overview"></a>BHandler</h2></div></div></div><a id="id444016" class="indexterm"></a><p>
A <a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a>
object responds to messages that are handed to it by a
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a>. The
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a> tells the
<a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a> about a message by invoking the
<a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a>'s
<a class="link" href="BHandler.html#BHandler_MessageReceived" title="MessageReceived()"><code class="methodname">MessageReceived()</code>
</a> function.
</p><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="BHandler_Overview_TheHandlerList"></a>The Handler List</h3></div></div></div><p>
To be eligible to get messages from a
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a>, a
<a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a> must be in the
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a>'s list of eligible
handlers (as explained in the
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a> class). The list of
eligible handlers is ordered; if the "first" handler doesn't want
to respond to a message that it has received, it simply calls the inherited
version of
<a class="link" href="BHandler.html#BHandler_MessageReceived" title="MessageReceived()"><code class="methodname">MessageReceived()</code></a>
and the message will automatically be handed to the object's
"next" handler. (System messages are not handed down the list.)
The <a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a> that all
these <a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a>s belong to is always the last the
last handler in the list (<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a> inherits from
<a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a>).
</p><p>
A <a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a>'s
next handler assignment can be changed through
<a class="link" href="BHandler.html#BHandler_SetNextHandler" title="SetNextHandler(), NextHandler()"><code class="methodname">SetNextHandler()</code></a>.
</p></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="BHandler_Overview_Targets"></a>Targets</h3></div></div></div><p>
You can designate a target <a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a> for most
messages. The designation is made when calling
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a>'s
<a class="link" href="BLooper.html#BLooper_PostMessage" title="PostMessage()"><code class="methodname">PostMessage()</code></a>
function or when constructing the
<a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a> object that
will send the message. Messages that a user drags and drops are targeted to
the object (a <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>)
that controls the part of the window where the message was dropped. The
messaging mechanism eventually passes the target
<a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a> to
<a class="link" href="BLooper.html#BLooper_DispatchMessage" title="DispatchMessage()"><code class="methodname">DispatchMessage()</code></a>
, so that the message can be delivered to its designated destination.
</p></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="BHandler_Overview_Filtering"></a>Filtering</h3></div></div></div><p>
Messages can be filtered before they're dispatched; that is, you can define
a function that will look at the message before the target
<a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a>'s hook function is called. The filter
function is associated with a
<a class="link" href="BMessageFilter.html" title="BMessageFilter"><code class="classname">BMessageFilter</code></a>
object, which records the criteria for calling the function.
</p><p>
Filters that should apply only to messages targeted to a particular
<a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a> are assigned to the
<a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a> by
<a class="link" href="BHandler.html#BHandler_SetFilterList" title="SetFilterList(), FilterList(), AddFilter(), RemoveFilter()"><code class="methodname">SetFilterList()</code></a>
or <a class="link" href="BHandler.html#BHandler_AddFilter"><code class="methodname">AddFilter()</code></a>.
Filters that might apply to any message a
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a> dispatches,
regardless of its target, are assigned by the parallel
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a> functions,
<a class="link" href="BLooper.html#BLooper_SetCommonFilterList"><code class="methodname">SetCommonFilterList()</code></a>
and
<a class="link" href="BLooper.html#BLooper_AddCommonFilter" title="AddCommonFilter(), RemoveCommonFilter(), SetCommonFilterList(), CommonFilterList()"><code class="methodname">AddCommonFilter()</code></a>.
See those functions and the
<a class="link" href="BMessageFilter.html" title="BMessageFilter"><code class="classname">BMessageFilter</code></a> class
for details.
</p></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="BHandler_Overview_NotifiersAndObservers"></a>Notifiers and Observers</h3></div></div></div><p>
A <a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a> can be a notifier. A notifier is a
handler that maintains one or more states and notifies interested parties
when those states change. Each state is idenfified by a 32-bit
<code class="varname">what</code> code. Interested parties, called observers, can register
to monitor changes in one or more states by calling
<a class="link" href="BHandler.html#BHandler_StartWatching" title="StartWatching(), StartWatchingAll(), StopWatching(), StopWatchingAll()"><code class="methodname">StartWatching()</code></a>
and specifying the <code class="varname">what</code> code of the state they want to be
notified of changes to.
</p><p>
This notification occurs when the <a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a> calls
<a class="link" href="BHandler.html#BHandler_SendNotices" title="SendNotices()"><code class="methodname">SendNotices()</code></a>;
it's the handler's job to call
<a class="link" href="BHandler.html#BHandler_SendNotices" title="SendNotices()"><code class="methodname">SendNotices()</code></a>
whenever a state changes, to ensure that observers are kept informed of the
changes. The <a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a> passes to
<a class="link" href="BHandler.html#BHandler_SendNotices" title="SendNotices()"><code class="methodname">SendNotices()</code></a>
a message template to be sent to the observers.
</p><p>
When a notification is sent, observers receive a
<a class="link" href="TheApplicationKit_MessageConstants.html#B_OBSERVER_NOTICE_CHANGE" title="B_OBSERVER_NOTICE_CHANGE"><code class="constant">B_OBSERVER_NOTICE_CHANGE</code></a>
message with an <span class="type">int32</span> field
<a class="link" href="TheApplicationKit_MessageConstants.html#B_OBSERVER_NOTICE_CHANGE" title="B_OBSERVER_NOTICE_CHANGE"><code class="constant">B_OBSERVER_NOTICE_CHANGE</code></a>
that contains the <code class="varname">what</code> code of the state that changed, and a
<code class="constant">B_OBSERVE_ORIGINAL_WHAT</code>
field that contains the
<code class="varname">what</code> value that was in the template
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>.
</p></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BCursor_Overview.html">BCursor</a>  Up: <a href="TheApplicationKit_Overview.html">The Application Kit</a>  Next: <a href="BInvoker_Overview.html">BInvoker</a> </div><div id="footerB"><div id="footerBL"><a href="BCursor_Overview.html" title="BCursor"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheApplicationKit_Overview.html" title="The Application Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="BInvoker_Overview.html" title="BInvoker"><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