Documentation | ApplicationKit | Invoker

SYNOPSIS

Perl

use HaikuR1::Invoker;

my $invoker1 = TestInvoker->new; # empty
my $invoker2 = TestInvoker->new($message, $handler); # handler as target
my $invoker3 = TestInvoker->new($message, undef, $looper); # looper's preferred handler as target
my $invoker4 = TestInvoker->new($message, $messenger); # messenger as target

$invoker->Invoke(); # invoke with default message (passed to constructor)
$invoker->Invoke($message); # invoke with a non-default message

$invoker->InvokeNotify($message, $kind); # invoke and send a notification to the target's watchers

Python

from HaikuR1.ApplicationKit import Invoker

invoker1 = TestInvoker->new; # empty
invoker2 = TestInvoker->new(message, handler); # handler as target
invoker3 = TestInvoker->new(message, None, looper); # looper's preferred handler as target
invoker4 = TestInvoker->new(message, messenger); # messenger as target

invoker->Invoke(); # invoke with default message (passed to constructor)
invoker->Invoke(message); # invoke with a non-default message

invoker->InvokeNotify(message, kind); # invoke and send a notification to the target's watchers

DESCRIPTION

Exposes the BInvoker object.

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

METHODS

Constructor

Creates an Invoker.

Perl

HaikuR1::Invoker->new();
HaikuR1::Invoker->new($message, $target); # Messenger, Handler or Looper
HaikuR1::Invoker->new($message, undef, $looper); # Looper's preferred handler

Python

Invoker()
Invoker(message, target) # Messenger, Handler or Looper
Invoker(message, None, looper) # Looper's preferred handler

message

Optional; a Message, the default Message to send when the Invoker is invoked.
target

Required when message is present; a Handler or a Messenger, the target to send the Message to. Can be the empty value to target looper's preferred handler. Only a handler that already belongs to a looper (see Looper.AddHandler can be a valid target.
looper

A Looper, the Looper to send the invocation message to. This parameter is not necessary unless target is the empty value; the Looper will be determined from target in all other cases. (To use a Looper itself as the target, rather than its preferred handler, pass the Looper as target; since Looper is a subclass of Handler, it is a valid target.)

HandlerForReply

SetHandlerForReply

Gets or sets the Handler to receive replies to the invocation Message. Signals an error on failure.

Perl

$invoker->HandlerForReply();
$invoker->SetHandlerForReply($handler);

Python

invoker.HandlerForReply()
invoker.SetHandlerForReply(handler)

handler

A Handler, the Handler that will receive replies.

InvokeNotify

InvokeKind

BeginInvokeNotify

EndInvokeNotify

InvokeNotify is a wrapper around the Invoke hook that allows you to set a notification code to be sent to any handlers that are watching the Invoker's target. It signals an error on failure.

InvokeKind allows you to determine from within the hook whether it is being called by the wrapper. It returns two items: the kind value that was passed to InvokeNotify and a boolean that is true if the hook was called from the wrapper.

BeginInvokeNotify and EndInvokeNotify allow you to emulate a call to InvokeNotify from within Invoke.

Perl

$invoker->InvokeNotify($message, $kind);
$invoker->InvokeKind();
$invoker->BeginInvokeNotify($kind);
$invoker->EndInvokeNotify();

Python

invoker.InvokeNotify(message, kind)
invoker.InvokeKind()
invoker.BeginInvokeNotify(kind)
invoker.EndInvokeNotify()

message

A Message, the invocation message; if you omit this, the notification will be sent to watchers, but no message will be sent to the target.
kind

An integer notification code; defaults to B_CONTROL_INVOKED.

Be aware that the notification will not automatically be sent; you need to override Invoke in a subclass to do that, with something like this:

Perl

sub Invoke {
    my ($self, $message) = @_;
    my ($kind, $notify) = $self->InvokeKind();

    # if we were called as a plain Invoke, we want to replace a missing
    # message with the default message, but if we called as part of an
    # InvokeNotify call, an omitted message is allowed
    if (! $message && ! $notify) {
        $message = $self->Message();
    }

    # at this point, if we have a message, we want to send it
    if ($message) {
        $self->SUPER::Invoke($message);
    }

    # at this point, if we were called as part of InvokeNotify, we want to
    # send the notification
    if ($notify) {
        my ($handler, $looper) = $self->Target();
        my $target = $handler ? $handler : $looper;
        $target->SendNotices($kind, $message);
    }

    # return a true value to signal success
    return 1;
}

Python

def Invoke(self, message=None):
    invoke_kind = self.InvokeKind()
    kind = invoke_kind[0]
    notify = invoke_kind[1]

    # if we were called as a plain Invoke, we want to replace a missing
    # message with the default message, but if we called as part of an
    # InvokeNotify call, an omitted message is allowed
    if message is None and not notify:
        message = self.Message()

    # at this point, if we have a message, we want to send it
    if message:
        super(MyInvoker, self).Invoke(message)

    # at this point, if we were called as part of InvokeNotify, we want to
    # send the notification
    if notify:
        target = self.Target()
        handler = target[0]
        looper = target[1]
        if handler:
            target = handler
        else:
            target = looper
        target.SendNotices(kind, message)

Message

Command

SetMessage

Gets or sets default Message to send when the Invoker is invoked, or its what value. Signals an error on failure.

Perl

$invoker->Message();
$invoker->Command();
$invoker->SetMessage($message);

Python

invoker.Message()
invoker.Command()
invoker.SetMessage(message)

A common way to use this Message is as a template, so you can add extra fields as desired:

Perl

my $message = $invoker->Message()->clone();
$message->AddString("info", "some extra info");
$invoker->Invoke($message);

Python

message = invoker.Message().clone()
message.AddString("info", "some extra info")
invoker.Invoke(message)

message

A Message, the new Message to send when the Invoker is invoked.

Target

Messenger

SetTarget

Gets or sets the target; that is, the Handler to which the Invoker's Message is sent. Signals an error on failure.

Perl

$invoker->Target();
$invoker->Messenger();
$invoker->SetTarget($target, $looper);
$invoker->SetTarget($messenger);

Python

invoker.Target()
invoker.Messenger()
invoker.SetTarget(target, looper)
invoker.SetTarget(messenger)

target
looper
messenger

These parameters have the same meanings as in the constructor.

Timeout

SetTimeout

Gets or sets the timeout for the invocation message. The timeout defaults to B_INFINITE_TIMEOUT when the Invoker is created. Signals an error on failure.

Perl

$invoker->Timeout();
$invoker->SetTimeout($timeout);

Python

invoker.Timeout()
invoker.SetTimeout(timeout)

timeout

An integer, the timeout.

HOOKS

Invoke

Sends the invocation message to the target. Signals an error on failure.

Perl

$invoker->Invoke($message);

Python

invoker.Invoke(message)

message

A Message, the message to send; if omitted, the default message should be sent.