Documentation | ApplicationKit | Roster

SYNOPSIS

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);

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.

HaikuR1::Roster->new();

Roster()

ActivateApp

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

$roster->ActivateApp($team);

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.

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

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.

$roster->FindApp($app);

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).

$roster->GetAppList($signature);

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.

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

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.

$roster->IsRunning($app);

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.)

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

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.

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

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.

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

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.

$roster->TeamFor($app);

roster.TeamFor(app)

• app

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

CONSTANTS

Application flags

use HaikuR1::Roster qw(:app_flags)

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

use HaikuR1::Roster qw(:watch_notification)

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

use HaikuR1::Roster qw(:watch_request)

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.