Documentation | ApplicationKit | Message

SYNOPSIS

Perl

use HaikuR1::Message;

my $message = HaikuR1::Message->new($command);

my $name = 'someint';
$message->AddInt32($name, 42);
my $int1 = $message->FindInt32($name);

$message->ReplaceInt32($name, 101);
my $int2 = $message->FindInt32($name);

Python

from HaikuR1.ApplicationKit import Message

message = Message(command)

name = 'someint'
message.AddInt32(name, 42)
int1 = message.FindInt32(name)

message.ReplaceInt32(name, 101)
int2 = message.FindInt32(name)

DESCRIPTION

Exposes the BMessage object.

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

PROPERTIES

what

The command constant, an integer that indicates the purpose of the message; for example B_WINDOW_ACTIVATED, B_REPLY, or B_WINDOW_MOVE_TO, among many other system constants, or you can specify your own value.

When specifying your own value, keep in mind that the system constants are 32-bit values, defined so that each of the four bytes has the value of an upper-case ASCII character (or the underscore). So in order that your constants do no conflict with system constants, either make sure each byte in your constant is less than 0x41 ('A') or greater than 0x5f ('_').

Basically, any constant less than or equal to 0x40404040 (1 077 952 576) or greater than or equal to 0x60606060 (1 616 928 864) will suffice.

If you want easier numbers to remember, then stick to numbers less than 1 000 000 000 or between 2 000 000 000 and 4 000 000 000. (Remember, the upper limit on 32-bit numbers is 4 294 967 295.)

Or, even easier, use the code_to_int utility function defined in SupportKit to create a constant that will not conflict.

Perl

use HaikuR1::Message;
use HaikuR1::SupportKit qw(code_to_int);

my $type = code_to_int("abcd"); # lower-case!

my $message = new HaikuR1::Message($type);

# or

$message->what($type);

Python

from HaikuR1.ApplicationKit import Message
from HaikuR1.SupportKit import code_to_int

type = code_to_int("abcd"); # lower-case!

message = new Message(type)

# or

message.what = type

METHODS

Constructor

Creates a Message.

Perl

my $message = HaikuR1::Message->new($initial);

Python

message = Message(initial)

initial

Optional; can be a Message to copy or an integer command constant. If omitted, the command code will be 0.

copy

Copies the contents of another object into this object.

Perl

$message->copy($copy_from);

Python

message.copy(copy_from)

copy_from

A Message to copy.

AddData

AddAlignment

AddRect

AddPoint

AddSize

AddString

AddStrings

AddInt8

AddUInt8

AddInt16

AddUInt16

AddInt32

AddUInt32

AddInt64

AddUInt64

AddBool

AddFloat

AddDouble

AddColor

AddPointer

AddMessenger

AddMessage

AddRef

AddFlat

Adds data to the Message, or signals an error.

Perl

$message->AddData(
    data => $data,
    name => $name,
    type => $type,
    isFixedSize => $isFixedSize,
    count => $count,
);

Python

message.AddData(
    name = name,
    data = data,
    type = type,
    isFixedSize = isFixedSize,
    count = count,
)

name

A native string containing the name of the data field.
data

The value to store.
type

An integer type constant indicating the type of data to be stored under name. You may not use B_ANY_TYPE. If you have already added data under name, then this type must match the type used in the first call. If not provided, then it will default to the type already stored, unless this is the first piece of data being stored under this name, in which case it will use the guess_type algorithm.
isFixedSize

If true, all items of this type have the same size.
count

An integer, the number of items being stored. (Currently this is ignored in the bindings; you can only store on item at a time.)
autoconvert

A boolean; if true, the data will be automatically converted; if false, it will be assumed that the data is already in the appropriate binary form; defaults to true.If not provided, then it will use the guess_type algorithm.

Perl

$message->AddAlignment($name, $alignment);    # Alignment object
$message->AddRect($name, $rect);              # Rect object
$message->AddPoint($name, $point);            # Point object
$message->AddSize($name, $size);              # Size object
$message->AddString($name, $string);          # String
$message->AddStrings($name, $strings);        # native list of Strings
$message->AddInt8($name, $value);             # 8-bit signed integer
$message->AddUInt8($name, $value);            # 8-bit unsigned integer
$message->AddInt16($name, $value);            # 16-bit signed integer
$message->AddUInt16($name, $value);           # 16-bit unsigned integer
$message->AddInt32($name, $value);            # 32-bit signed integer
$message->AddUInt32($name, $value);           # 32-bit unsigned integer
$message->AddInt64($name, $value);            # 64-bit signed integer
$message->AddUInt64($name, $value);           # 64-bit unsigned integer
$message->AddBool($name, $boolean);           # true or false
$message->AddFloat($name, $float);            # 32-bit floating point number
$message->AddDouble($name, $double);          # 64-bit floating point number
$message->AddColor($name, $color);            # RGB color
$message->AddPointer($name, $pointer, $type); # pointer to a memory address
$message->AddMessenger($name, $messenger);    # Messenger object
$message->AddRef($name, $ref);                # path (Haiku entry_ref object)
$message->AddMessage($name, $message);        # Message object
$message->AddFlat($name, $object);            # Flattenable object

Python

message.AddAlignment(name, alignment);   # Alignment object
message.AddRect(name, rect);             # Rect object
message.AddPoint(name, point);           # Point object
message.AddSize(name, size);             # Size object
message.AddString(name, string);         # String
message.AddStrings(name, strings);       # native list of Strings
message.AddInt8(name, value);            # 8-bit signed integer
message.AddUInt8(name, value);           # 8-bit unsigned integer
message.AddInt16(name, value);           # 16-bit signed integer
message.AddUInt16(name, value);          # 16-bit unsigned integer
message.AddInt32(name, value);           # 32-bit signed integer
message.AddUInt32(name, value);          # 32-bit unsigned integer
message.AddInt64(name, value);           # 64-bit signed integer
message.AddUInt64(name, value);          # 64-bit unsigned integer
message.AddBool(name, boolean);          # true or false
message.AddFloat(name, float);           # 32-bit floating point number
message.AddDouble(name, double);         # 64-bit floating point number
message.AddColor(name, color);           # RGB color
message.AddPointer(name, pointer, type); # pointer to a memory address
message.AddMessenger(name, messenger);   # Messenger object
message.AddRef(name, ref);               # path (Haiku entry_ref object)
message.AddMessage(name, message);       # Message object
message.AddFlat(name, object);           # Flattenable object

AddPointer takes an additional parameter to indicate the pointer type.

If you're wondering why a function to add a list of data items exists only for the string type, it's because there's a C++ class called BStringList that implements a list of C++ string objects. (The implemenation of similar functions for the other data types is left as an exercise for the reader.)

Append

Adds the contents of the given Message to this Message, or signals an error.

Perl

$message->Append($message);

Python

message.Append(message)

message

A Message, the message to append.

CountNames

Returns the number of named data fields that store the indicated type; for B_ANY_TYPE, counts all named fields.

Perl

$message->CountNames($type);

Python

message.CountNames(type)

type

An integer type constant, the data type.

DropPoint

Returns the coordinates where the Message was dropped; the first return is the position in absolute screen coordinates, the second is the position relative to the upper left corner of the dragging rectangle.

Perl

$message->DropPoint();

Python

message.DropPoint()

Flattening

FlattenedSize

Flatten

Unflatten

Although Message is not a subclass of Flattenable, it does have a similar interface.

Perl

$message->FlattenedSize();
$message->Flatten($target);
$message->Unflatten($source);

Python

message.FlattenedSize()
message.Flatten(target)
message.Unflatten(source)

target

Optional; a DataIO indicating where to write the data. If present, the Message will be flattened to the given stream; otherwise, the flattened Message will be returned as a byte string, which may contain null bytes. (In fact, it almost certainly will contain null bytes.)
source

A native string or a DataIO, in either case containing a flattened message.

FindData

FindAlignment

FindRect

FindPoint

FindSize

FindString

FindStrings

FindInt8

FindUInt8

FindInt16

FindUInt16

FindInt32

FindUInt32

FindInt64

FindUInt64

FindBool

FindFloat

FindDouble

FindColor

FindPointer

FindMessenger

FindRef

FindMessage

FindFlat

Finds named data in the Message, or signals an error.

Perl

$message->FindData($name, $type, $index);

Python

message.FindData(name, type, index)

name

A native string containing the name of the data field.
type

An integer type constant. This function uses the actual type of the stored data internally, but will use this type to convert the fetched data into a native type to return. If not provided, defaults to type of the stored data.
index

Optional; an integer index into the data items stored under name. Defaults to 0 (the first item, which is in many cases the only item).

Perl

$message->FindAlignment($name, $index);      # Alignment object
$message->FindRect($name, $index);           # Rect object
$message->FindPoint($name, $index);          # Point object
$message->FindSize($name, $index);           # Size object
$message->FindString($name, $index);         # String
$message->FindStrings($name);                # native list of Strings
$message->FindInt8($name, $index);           # 8-bit signed integer
$message->FindUInt8($name, $index);          # 8-bit unsigned integer
$message->FindInt16($name, $index);          # 16-bit signed integer
$message->FindUInt16($name, $index);         # 16-bit unsigned integer
$message->FindInt32($name, $index);          # 32-bit signed integer
$message->FindUInt32($name, $index);         # 32-bit unsigned integer
$message->FindInt64($name, $index);          # 64-bit signed integer
$message->FindUInt64($name, $index);         # 64-bit unsigned integer
$message->FindBool($name, $index);           # true or false
$message->FindFloat($name, $index);          # 32-bit floating point number
$message->FindDouble($name, $index);         # 64-bit floating point number
$message->FindColor($name, $index);          # RGB color
$message->FindPointer($name, $type, $index); # pointer to a memory address
$message->FindMessenger($name, $index);      # Messenger object
$message->FindRef($name, $index);            # path (Haiku entry_ref object)
$message->FindMessage($name, $index);        # Message object
$message->FindFlat($name, $param, $index);   # Flattenable object

Python

message.FindAlignment(name, index);     # Alignment object
message.FindRect(name, index);          # Rect object
message.FindPoint(name, index);         # Point object
message.FindSize(name, index);          # Size object
message.FindString(name, index);        # String
message.FindStrings(name);              # native list of Strings
message.FindInt8(name, index);          # 8-bit signed integer
message.FindUInt8(name, index);         # 8-bit unsigned integer
message.FindInt16(name, index);         # 16-bit signed integer
message.FindUInt16(name, index);        # 16-bit unsigned integer
message.FindInt32(name, index);         # 32-bit signed integer
message.FindUInt32(name, index);        # 32-bit unsigned integer
message.FindInt64(name, index);         # 64-bit signed integer
message.FindUInt64(name, index);        # 64-bit unsigned integer
message.FindBool(name, index);          # true or false
message.FindFloat(name, index);         # 32-bit floating point number
message.FindDouble(name, index);        # 64-bit floating point number
message.FindColor(name, index);         # RGB color
message.FindPointer(name, type, index); # pointer to a memory address
message.FindMessenger(name, index);     # Messenger object
message.FindRef(name, index);           # path (Haiku entry_ref object)
message.FindMessage(name, index);       # Message object
message.FindFlat(name, param, index);   # Flattenable object

A couple of things to notice:

First, FindStrings does not take an index; it returns all the strings stored under name.

Second, FindFlat takes an additional parameter. This is because Flattenable is an abstract class, and the Message class doesn't know which subclass of Flattenable to use unless you tell it.

FindPointer also takes an additional parameter, to indicate the pointer type.

This additional parameter can be either an instance of the subclass, in which case the object's contents will be replaced with the unflattened data, or the subclass itself, in which case a new object of that class will be created. In either case, the unflattened object is returned.

Perl

my $object = MyFlattenable->new();
$message->FindFlat("flattened", $object);

# or

my $object = $message->FindFlat("flattened", "MyFlattenable");

Python

object = MyFlattenable()
message.FindFlat("flattened", object)

# or

object = message.FindFlat("flattened", MyFlattenable)

GetInfo

Gets info on a data field, or signals an error.

Perl

$message->GetInfo($param, $index);

Python

message.GetInfo(param, index)

param

An integer containing a data type or a native string containing a data name.
index

Optional; when specifying a type, indicates the instance of that type in the Message. Defaults to 0; or in other words, the first instance of the given type. (Note: this is the index of the specified type, not the overall index of the data field within the Message.) Can be used with param set to B_ANY_TYPE to iterate through all the data fields in the Message.

This parameter is ignored when param is a string. (Because all the data under a single name is the same type.)

Returns a native map of information about the specified field, with the following fields:

name

The name of the field.
type

The integer type constant representing the type of the field.
count

The number of items stored under this name.
fixed

True if all the items stored under this name are the same size, false if the size is variable.

IsEmpty

Returns true if the Message has no data fields.

Perl

$message->IsEmpty();

Python

message.IsEmpty()

IsReply

Returns true if the Message is a reply.

Perl

$message->IsReply();

Python

message.IsReply()

IsSourceRemote

Returns true if the Message sender is in another team (= process).

Perl

$message->IsSourceRemote();

Python

message.IsSourceRemote()

IsSourceWaiting

Returns true if the Message sender is waiting for a synchronous reply.

Perl

$message->IsSourceWaiting();

Python

message.IsSourceWaiting()

IsSystem

Returns true if the Message is system-defined.

Perl

$message->IsSystem();

Python

message.IsSystem()

MakeEmpty

Empties the Message of data fields, but does not change the what property. Signals an error on failure.

Perl

$message->MakeEmpty();

Python

message.MakeEmpty()

If this Message is an asynchronous reply, returns the Message that this Message is replying to.

Perl

$message->Previous();

Python

message.Previous()

PrintToStream

Prints the contents of the Message to standard out.

Perl

$message->PrintToStream();

Python

message.PrintToStream()

RemoveData

Removes the data at index of the named field, or signals an error.

Perl

$message->RemoveData($name, $index);

Python

message.RemoveData(name, index)

name

The name of the field.
index

The index of the data field to remove.

RemoveName

Removes the named field, or signals an error.

Perl

$message->RemoveName($name);

Python

message.RemoveName(name)

name

The name of the field to remove.

Rename

Renames the field or signals an error.

Perl

$message->Rename($oldEntry, $newEntry);

Python

message.Rename(oldEntry, newEntry)

oldEntry

The old name.
newEntry

The new name.

ReplaceData

ReplaceAlignment

ReplaceRect

ReplacePoint

ReplaceSize

ReplaceString

ReplaceInt8

ReplaceUInt8

ReplaceInt16

ReplaceUInt16

ReplaceInt32

ReplaceUInt32

ReplaceInt64

ReplaceUInt64

ReplaceBool

ReplaceFloat

ReplaceDouble

ReplaceColor

ReplacePointer

ReplaceMessenger

ReplaceRef

ReplaceMessage

ReplaceFlat

Replaces named data in the Message, or signals an error.

Perl

$message->ReplaceData(
    name => $name,
    data => $data,
    type => $type,
    index => $index,
);

Python

message.ReplaceData(
    name = name,
    data = data,
    type = type,
    index = index,
)

name

A native string containing the name of the data field.
data

The value to store.
type

An integer type constant, which must match the type of data that is actually stored under name. You may not use B_ANY_TYPE. If not provided, then it will default to the type of the existing data.
index

Optional; an integer index into the data items stored under name. Defaults to 0.
autoconvert

A boolean; if true, the data will be automatically converted; if false, it will be assumed that the data is already in the appropriate binary form; defaults to true.

Perl

$message->ReplaceAlignment($name, $alignment, $index);    # Alignment object
$message->ReplaceRect($name, $rect, $index);              # Rect object
$message->ReplacePoint($name, $point, $index);            # Point object
$message->ReplaceSize($name, $size, $index);              # Size object
$message->ReplaceString($name, $string, $index);          # String
$message->ReplaceInt8($name, $value, $index);             # 8-bit signed integer
$message->ReplaceUInt8($name, $value, $index);            # 8-bit unsigned integer
$message->ReplaceInt16($name, $value, $index);            # 16-bit signed integer
$message->ReplaceUInt16($name, $value, $index);           # 16-bit unsigned integer
$message->ReplaceInt32($name, $value, $index);            # 32-bit signed integer
$message->ReplaceUInt32($name, $value, $index);           # 32-bit unsigned integer
$message->ReplaceInt64($name, $value, $index);            # 64-bit signed integer
$message->ReplaceUInt64($name, $value, $index);           # 64-bit unsigned integer
$message->ReplaceBool($name, $boolean, $index);           # true or false
$message->ReplaceFloat($name, $float, $index);            # 32-bit floating point number
$message->ReplaceDouble($name, $double, $index);          # 64-bit floating point number
$message->ReplaceColor($name, $color, $index);            # RGB color
$message->ReplacePointer($name, $pointer, $type, $index); # pointer to a memory address
$message->ReplaceMessenger($name, $messenger, $index);    # Messenger object
$message->ReplaceRef($name, $ref, $index);                # path (Haiku entry_ref object)
$message->ReplaceMessage($name, $message, $index);        # Message object
$message->ReplaceFlat($name, $object, $index);            # Flattenable object

Python

message.ReplaceAlignment(name, alignment, index);   # Alignment object
message.ReplaceRect(name, rect, index);             # Rect object
message.ReplacePoint(name, point, index);           # Point object
message.ReplaceSize(name, size, index);             # Size object
message.ReplaceString(name, string, index);         # String
message.ReplaceInt8(name, value, index);            # 8-bit signed integer
message.ReplaceUInt8(name, value, index);           # 8-bit unsigned integer
message.ReplaceInt16(name, value, index);           # 16-bit signed integer
message.ReplaceUInt16(name, value, index);          # 16-bit unsigned integer
message.ReplaceInt32(name, value, index);           # 32-bit signed integer
message.ReplaceUInt32(name, value, index);          # 32-bit unsigned integer
message.ReplaceInt64(name, value, index);           # 64-bit signed integer
message.ReplaceUInt64(name, value, index);          # 64-bit unsigned integer
message.ReplaceBool(name, boolean, index);          # true or false
message.ReplaceFloat(name, float, index);           # 32-bit floating point number
message.ReplaceDouble(name, double, index);         # 64-bit floating point number
message.ReplaceColor(name, color, index);           # RGB color
message.ReplacePointer(name, pointer, type, index); # pointer to a memory address
message.ReplaceMessenger(name, messenger, index);   # Messenger object
message.ReplaceRef(name, ref, index);               # path (Haiku entry_ref object)
message.ReplaceMessage(name, message, index);       # Message object
message.ReplaceFlat(name, object, index);           # Flattenable object

ReplacePointer takes an additional parameter to indicate the pointer type.

Notice that there is no ReplaceStrings; strings can only be replaced one at a time.

ReturnAddress

Returns a Messenger that can be used to reply to the Message.

Perl

$message->ReturnAddress();

Python

message.ReturnAddress()

SendReply

Sends a reply to this Message and asks for a reply to your reply to be sent to the given Handler. Signals an error on failure.

Perl

$message->SendReply(
    message => $message,
    replyTo => $replyTo,
    timeout => $timeout,
    replyTimeout => $replyTimeout,
    synchronous => $synchronous,
);

Python

message.SendReply(
    message = message,
    replyTo = replyTo,
    timeout = timeout,
    replyTimeout = replyTimeout,
    synchronous = synchronous,
)

message

A Message or an integer command code; if an integer, it will be used to create a Message internally.
replyTo

Optional; a Handler or a Messenger that any reply to this reply will be sent to.
timeout

Optional; an integer that specifies a timeout for sending this reply; defaults to B_INFINITE_TIMEOUT.
replyTimeout

Optional; an integer that specifies a timeout for reciving a reply to this reply; defaults to B_INFINITE_TIMEOUT.
synchronous

Optional; an boolean that specifies whether the call should be synchronous (waits for a reply to this reply) or asynchronous (returns once it has successfully sent this reply); defaults to false (asynchronous call).

This option will be ignored if replyTo is specified; specifying a reply target always results in an asynchronous call.

If you specify a synchronous call, the successful return value will be a Message, the reply to this reply; otherwise, the successful return value will simply be true. In either case, an unsuccessful call will generate an error.

Specifiers

AddSpecifier

SetCurrentSpecifier

GetCurrentSpecifier

HasSpecifiers

PopSpecifier

PopSpecifier does not actually delete anything; it simply decrements the Message's internal specifier index. Otherwise, these messages do what you expect.

AddSpecifier can either take a pre-built specifier Message, or it will build one for you based on the parameters.

All but HasSpecifiers signal an error on failure.

Perl

$message->AddSpecifier($message);
$message->AddSpecifier(
    property => $property,
    name     => $name,
    index    => $index,
    range    => $range,
);
$message->SetCurrentSpecifier($new_index);
$message->GetCurrentSpecifier();
$message->HasSpecifiers();
$message->PopSpecifier();

Python

message.AddSpecifier(message)
message.AddSpecifier(
    property = property,
    name     = name,
    index    = index,
    range    = range,
)
message.SetCurrentSpecifier(new_index)
message.GetCurrentSpecifier()
message.HasSpecifiers()
message.PopSpecifier()

The first version adds a pre-built specifier Message. The second version builds a specifier Message from the given parameters.

message

A pre-built specifier Message.
property

A native string, the property being specified; used with no other parameters to build a B_DIRECT_SPECIFIER.
name

A native string, the specifier name; used with property to build a B_NAME_SPECIFIER.
index

An integer, the specifier index; used with property (but not range) to build a B_INDEX_SPECIFIER.
range

An integer, the specifier range; used with property and index to build a B_RANGE_SPECIFIER.
new_index

An integer, the index of the new current specifier.

For more information on how to use specifiers, see the manual chapter on scripting.

WasDelivered

Returns true if the Message has been delivered to its target.

Perl

$message->WasDelivered();

Python

message.WasDelivered()

WasDropped

Returns true if the Message was sent via drag-and-drop.

Perl

$message->WasDropped();

Python

message.WasDropped()

CONSTANTS

Specifiers

Perl

use HaikuR1::Message qw(:specifiers)

Python

Python does not support export tags.

B_NO_SPECIFIER

There is no specifier.
B_DIRECT_SPECIFIER

The property name itself is the specifier.
B_INDEX_SPECIFIER

The message contains an index field that specifies an instance of the property.
B_REVERSE_INDEX_SPECIFIER

The index counts backwards from the end of the list.
B_RANGE_SPECIFIER

The message contains an index field and a range field that specify a number of instances of the property.
B_REVERSE_RANGE_SPECIFIER

The message contains an index field and a range field that specify a number of instances of the property; the index counts backwards from the end of the list.
B_NAME_SPECIFIER

The message contains a name field that specifies an instance of the property.
B_ID_SPECIFIER

The message contains an id field that specifies an instance of the property.
B_SPECIFIERS_END

This constant reserves space for standard specifier constants; any user-specified constants should be greater than this.