BHandler¶
A BHandler
object responds to messages that are handed to it
by a BLooper
. The BLooper
tells the
BHandler
about a message by invoking the
BHandler
’s MessageReceived()
function.
The Handler List¶
To be eligible to get messages from a BLooper
, a
BHandler
must be in the BLooper
’s list of
eligible handlers (as explained in the BLooper
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 MessageReceived()
and
the message will automatically be handed to the object’s “next” handler.
(System messages are not handed down the list.) The BLooper
that all these BHandler
s belong to is always the last the last
handler in the list (BLooper
inherits from
BHandler
).
A BHandler
’s next handler assignment can be changed through
SetNextHandler()
.
Targets¶
You can designate a target BHandler
for most messages. The
designation is made when calling BLooper
’s
PostMessage()
function or when
constructing the BMessenger
object that will send the message.
Messages that a user drags and drops are targeted to the object (a
BView
) that controls the part of the window where the message
was dropped. The messaging mechanism eventually passes the target
BHandler
to DispatchMessage()
, so that the message can be delivered to its
designated destination.
Filtering¶
Messages can be filtered before they’re dispatched; that is, you can
define a function that will look at the message before the target
BHandler
’s hook function is called. The filter function is
associated with a BMessageFilter
object, which records the
criteria for calling the function.
Filters that should apply only to messages targeted to a particular
BHandler
are assigned to the BHandler
by
SetFilterList()
or
AddFilter()
. Filters that might apply to
any message a BLooper
dispatches, regardless of its target,
are assigned by the parallel BLooper
functions,
SetCommonFilterList()
and
AddCommonFilter()
. See those
functions and the BMessageFilter
class for details.
Notifiers and Observers¶
A BHandler
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 what code.
Interested parties, called observers, can register to monitor changes in
one or more states by calling StartWatching()
and specifying the what code of the
state they want to be notified of changes to.
This notification occurs when the BHandler
calls
SendNotices()
; it’s the handler’s job
to call SendNotices()
whenever a state
changes, to ensure that observers are kept informed of the changes. The
BHandler
passes to SendNotices()
a message template to be sent to the observers.
When a notification is sent, observers receive a
B_OBSERVER_NOTICE_CHANGE
message with an int32
field B_OBSERVER_NOTICE_CHANGE
that contains the
what code of the state that changed, and a
B_OBSERVE_ORIGINAL_WHAT
field that contains the
what value that was in the template BMessage
.