Documentation | ApplicationKit | Handler

SYNOPSIS

use HaikuR1::Handler qw(B_OBSERVE_WHAT_CHANGE B_OBSERVE_ORIGINAL_WHAT B_OBSERVER_OBSERVE_ALL);

# define MyHandler subclass here

my $handler = MyHandler->new($name);
$looper->AddHandler($handler);
$looper->PostMessage($message, $handler);

from HaikuR1.ApplicationKit import Handler, B_OBSERVE_WHAT_CHANGE B_OBSERVE_ORIGINAL_WHAT B_OBSERVER_OBSERVE_ALL

# define MyHandler subclass here

handler = MyHandler(name)
looper.AddHandler(handler)
looper.PostMessage(message, handler)

DESCRIPTION

Exposes the BHandler object.

For more information on Handler, see the Be Book class description, the Be Book overview, and the Haiku Book class description.

METHODS

Constructor

Creates a Handler.

my $handler = HaikuR1::Handler->new($initial);

handler = Handler(initial)

• initial

  Optional; can be a Message containing an archived Handler or a native string containing a name for the Handler.

Filters

AddFilter

RemoveFilter

SetFilterList

FilterList

These methods maintain the Handler's filters.

A MessageFilter may only belong to one object at a time. You cannot add a MessageFilter to an object it already belongs to. (Although you can remove it and then re-add it later.)

The Handler's Looper must be locked before changing the filter list. (Although you can call FilterList without locking the Looper.)

AddFilter, RemoveFilter, and SetFilterList can also be called as hooks.

$handler->AddFilter($filter);
$handler->RemoveFilter($filter);
$handler->SetFilterList($filters);
$handler->FilterList();

handler.AddFilter(filter)
handler.RemoveFilter(filter)
handler.SetFilterList(filters)
handler.FilterList()

• filter

  The MessageFilter to add or remove.

• filters

  A list of MessageFilters, the new list.

Locking

LockLooper

LockLooperWithTimeout

UnlockLooper

These methods do what you expect. LockLooperWithTimeout signals an error if it fails to obtain a lock.

$handler->LockLooper();
$handler->LockLooperWithTimeout($timeout);
$handler->UnlockLooper();

handler.LockLooper()
handler.LockLooperWithTimeout(timeout)
handler.UnlockLooper()

• timeout

  An integer, the timeout value in microseconds.

Looper

Returns the Looper that the Handler belongs to.

$handler->Looper();

handler.Looper()

Name

SetName

Gets or sets the Handler's name.

$handler->Name();
$handler->SetName($name);

handler.Name()
handler.SetName(name)

• name

  A native string, the new name.

NextHandler

SetNextHandler

Gets or sets the next handler in the handler chain.

SetNextHandler can also be called as a hook.

$handler->NextHandler();
$handler->SetNextHandler($handler);

handler.NextHandler()
handler.SetNextHandler(handler)

• handler

  A Handler, the next handler.

Notifications

StartWatching

StartWatchingAll

StopWatching

StopWatchingAll

SendNotices

IsWatched

SendNotices sends a state change notification to any Handlers that are watching this Handler. (A state change notification is a Message with a what value of B_OBSERVER_NOTICE_CHANGE.)

SendNotices can also be called as a hook.

The other methods do what you expect; they also signal an error on failure.

Take note of the meaning of target, below.

$handler->StartWatching($target, $what);
$handler->StartWatchingAll($target);
$handler->StopWatching($target, $what);
$handler->StopWatchingAll($target);
$handler->IsWatched();

$handler->SendNotices($what, $notice);

handler.StartWatching(target, what)
handler.StartWatchingAll(target)
handler.StopWatching(target, what)
handler.StopWatchingAll(target)
handler.IsWatched()

handler.SendNotices(what, notice)

• target

  A Messenger or a Handler; if a Messenger, the Handler on which you call StartWatching receives the notifications and the target of the Messenger is the subject of the notifications; if a Handler, then the Handler on which you call StartWatching is the subject of the notifications and target itself receives the notifications.

In other words:

$watcher->StartWatching(HaikuR1::Messenger->new($watched), $what);

# but

$watched->StartWatching($watcher, $what);

watcher.StartWatching(Messenger(watched), what)

# but

watched.StartWatching(watcher, what)

Signals an error on failure.

• what

  An integer, the state that has changed. This will appear in the state change Message as an Int32 under the name B_OBSERVE_WHAT_CHANGE.

• notice

  Optional; a Message to be sent as the notification. If you specify a Message here, the Message will be copied to use as the Message sent to the watchers, with the copy's what replaced withB_OBSERVER_NOTICE_CHANGE; the original what value of notice will be copied as an Int32 under the name B_OBSERVE_ORIGINAL_WHAT.

HOOKS

GetSupportedSuites

This hook is generally called in response a request for the scripting property Suites, described below. You should add your suite and then pass it to the base class's version so it can add its own suite.

You should signal an error if you are unable to add your suite to the Message.

$looper->GetSupportedSuites($data);

looper.GetSupportedSuites(data)

• data

  A Message, each class should add the scripting suites it supports to the suites member of this message, and the relevant properties to the messages member. Each suite is a MIME string that begins "suite/". Each property is a flattened PropertyInfo object.

MessageReceived

Called when the Handler receives a message. Determine whether to handle the message by looking at its what property. Pass unhandled messages to the base class version.

$looper->MessageReceived($message);

looper.MessageReceived(message)

• message

  A Message; the contents will depend on the action that generated the event.

ResolveSpecifier

Returns the Handler that will handle the given scripting message. If you cannot resolve the specifier, pass it to the base class version.

$looper->ResolveSpecifier(
    message => $message,
    index => $index,
    specifier => $specifier,
    what => $what,
    property => $property,
);

looper.ResolveSpecifier(
    message = message,
    index = index,
    specifier = specifier,
    what = what,
    property = property,
)

• message

  The scripting Message.

• index

  An integer, the index of the current specifier.

• specifier

  A Message, the current specifier.

• what

  An integer, the what property of the current specifier.

• property

  A native string, the property name.

ARCHIVABLE INTERFACE

Handler inherits the methods and hooks of Archivable.

CONSTANTS

• B_OBSERVE_WHAT_CHANGE

The name of an int32 stored in the B_OBSERVER_NOTICE_CHANGE message; it contains the what value passed to SendNotices.

• B_OBSERVE_ORIGINAL_WHAT

The name of an int32 stored in the B_OBSERVER_NOTICE_CHANGE message; it contains the original what value if a Message was passed to SendNotices.

• B_OBSERVER_OBSERVE_ALL

If you use this value as the what for StartWatching or StopWatching, it has the same effect as calling StartWatchingAll or StopWatchingAll.

SCRIPTING SUITE

The name of Handler's scripting suite is suite/vnd.Be-handler.

• Properties

  • InternalName

    • B_GET_PROPERTY

      gets the name of the Handler

  • Messenger

    • B_GET_PROPERTY

      gets a Messenger that targets the Handler

  • Suites

    • B_GET_PROPERTY

      as described under GetSupportedSuites