SYNOPSIS

Perl

use HaikuR1::Roster qw(B_SOME_APP_LAUNCHED B_SOME_APP_QUIT);

my $roster = HaikuR1::Roster->new();

my $team = $roster->Launch($some_app);
my $info = $roster->GetRunningAppInfo($team);

Python

from HaikuR1.ApplicationKit import Roster, B_SOME_APP_LAUNCHED B_SOME_APP_QUIT

roster = Roster()

team = roster.Launch(some_app)
info = roster.GetRunningAppInfo(team)

DESCRIPTION

Exposes the BRoster object.

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

METHODS

Constructor

Creates a Roster object.

Perl

HaikuR1::Roster->new();

Python

Roster()

ActivateApp

Activates the application with the given team id. The target application must have a Window on screen. May signal an error.

Perl

$roster->ActivateApp($team);

Python

roster.ActivateApp(team)

team

An integer, the id of the team to activate.

Broadcast

Sends a Message to all running applications, unless the application does not accept messages. May signal an error.

Perl

$roster->Broadcast($message, $replyTo);

Python

roster.Broadcast(message, replyTo)

message

The Message to send.
replyTo

The Messenger to reply to; defaults to be_app_messenger.

FindApp

Returns an entry_ref for the application that handles a given file, or signals an error if no such application is found.

Perl

$roster->FindApp($app);

Python

roster.FindApp(app)

app

A native string containing either a mime type or the file name. If the mime type or the file refers to an application, that application will be found; if it represents a file or file type, then the file or type's preferred application will be found.

GetAppList

Returns a List of ids for running teams (= processes).

Perl

$roster->GetAppList($signature);

Python

roster.GetAppList(signature)

signature

Optional, a native string containing a signature. If provided, only teams (= processes) with matching signature will be returned; if omitted, all teams will be returned.

GetAppInfo

GetRunningAppInfo

GetActiveAppInfo

Returns an app_info structure for the application in question, or signals B_ERROR if no such application is running.

Perl

$roster->GetAppInfo($app);
$roster->GetRunningAppInfo($team);
$roster->GetActiveAppInfo();

Python

roster.GetAppInfo(app)
roster.GetRunningAppInfo(team)
roster.GetActiveAppInfo()

app

A native string containing either the signature or the file name of the application to check.
team

An integer, the team id to check.

IsRunning

Returns true if a given application is running.

Perl

$roster->IsRunning($app);

Python

roster.IsRunning(app)

app

A native string containing either the signature or the file name of the application to check.

Launch

Launches an application and returns the team id for the new application, or signals an error if it fails.

If you need to know whether an application was already running, you can check the error variable (Perl $HaikuR1::Error, Python HaikuR1.error). Although the method does not signal an error for an application that is already running, it does set this error to B_ALREADY_RUNNING. (Of course, it only does this if the application's flags are set to B_EXCLUSIVE_LAUNCH or B_SINGLE_LAUNCH.)

Perl

$roster->Launch($app, $args);

Python

roster.Launch(app, args)

app

A native string containing either a mime type or the file name. If the mime type or the file refers to an application, that application will be launched; if it represents a file or file type, then the file or type's preferred application will be found.

In the case of a file, the file will also be passed to the application in a B_REFS_RECEIVED message.
args

A Message, a native list of Messages, or a native list of native strings, to be passed to the application. Messages will be passed to the Application's message loop, and string arguments will be passed to the application as though they had been passed on the command line.

Notifications

StartWatching

StopWatching

Starts or stops watching for application events: launch, quit, activate. May signal an error.

Perl

$roster->StartWatching($target, $eventMask);
$roster->StopWatching($target);

Python

roster.StartWatching(target, eventMask)
roster.StopWatching(target)

target

The Messenger to send the event notifications to.
eventMask

An integer watch request constants, the event(s) to watch for; defaults to B_REQUEST_LAUNCHED | B_REQUEST_QUIT.

Recent Items

GetRecentDocuments

GetRecentFolders

GetRecentApps

AddToRecentDocuments

AddToRecentFolders

The Get methods return a Message; the items fetched will be entry_refs in the Message's refs field.

Other than that, these methods do what you expect.

Perl

$roster->GetRecentDocuments($maxCount, $fileTypes, $signature);
$roster->GetRecentFolders($maxCount, $signature);
$roster->GetRecentApps($maxCount);
$roster->AddToRecentDocuments($document, $signature);
$roster->AddToRecentFolders($folder, $signature);

Python

roster.GetRecentDocuments(maxCount, fileTypes, signature)
roster.GetRecentFolders(maxCount, signature)
roster.GetRecentApps(maxCount)
roster.AddToRecentDocuments(document, signature)
roster.AddToRecentFolders(folder, signature)

maxCount

An integer, the maximum number of items to return.
fileTypes

Optional; A native string or native list of native strings containing mime types; if present only recent documents that match one of the file types will be returned.
signature

Optional; a native string containing an application signature. If present when Getting, only recent documents opened by the given application will be returned. If present when Setting, the system will record that the document was used by the given application.
document, folder

A native string containing the file or folder name to add.

TeamFor

Returns the team (= process) id for a given application, or signals B_ERROR if no such application is running.

Perl

$roster->TeamFor($app);

Python

roster.TeamFor(app)

app

A native string containing either the signature or the file name of the application to check.

CONSTANTS

Application flags

Perl

use HaikuR1::Roster qw(:app_flags)

Python

Python does not support export tags.

B_SINGLE_LAUNCH

Indicates that an application can only be launched once from a particular file; that is, if this file is already running, the app will fail to launch.
B_MULTIPLE_LAUNCH

Indicates that an application can launched any number of times.
B_EXCLUSIVE_LAUNCH

Indicates that an application can only be launched once per application signature; that is, if an application with this signature is already running, the app will fail to launch.
B_LAUNCH_MASK

Allows you to mask off the above three launch flags from the rest of the application flags.
B_BACKGROUND_APP

Indicates that an application should run in the background.
B_ARGV_ONLY

Indicates that the application does not accept Messages; only string arguments.

Watch notifications

Perl

use HaikuR1::Roster qw(:watch_notification)

Python

Python does not support export tags.

B_SOME_APP_LAUNCHED

Sent when an application is launched.
B_SOME_APP_QUIT

Sent when an application is quit.
B_SOME_APP_ACTIVATED

Sent when an application is activated.

These three notification messages will have the following fields:

be:signature

a String with the application signature
be:team

an Int32, the application's team (= process) id
be:thread

an Int32, the id of the application's main thread
be:flags

a Uint32, the application flags
be:ref

a String, the application's file name
be:signature

a String with the application signature

Watch requests

Perl

use HaikuR1::Roster qw(:watch_request)

Python

Python does not support export tags.

B_REQUEST_LAUNCHED

Tells the target of StartWatching to watch for B_SOME_APP_LAUNCHED.
B_REQUEST_QUIT

Tells the target of StartWatching to watch for B_SOME_APP_QUIT.
B_REQUEST_ACTIVATED

Tells the target of StartWatching to watch for B_SOME_APP_ACTIVATED.