Documentation | ApplicationKit | Application

SYNOPSIS

Perl

use HaikuR1::Application qw(B_QUIT_REQUESTED);

# define MyApplication subclass here

my $app = MyApplication->new($signature);
$looper->AddHandler($handler);

$app->Run();

# wait for an event to Quit the app

Python

from HaikuR1.ApplicationKit import Application, B_QUIT_REQUESTED

# define MyApplication subclass here

app = MyApplication(signature)
looper.AddHandler(handler)

app.Run()

# wait for an event to Quit the app

DESCRIPTION

Exposes the BApplication object.

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

METHODS

Constructor

Creates an Application.

Perl

my $app = HaikuR1::Application->new($initial);

Python

app = Application(initial)

initial

A Message containing an archived Application or a native string containing a signature for the Application.

When using a signature, that signature must be a valid MIME string with the supertype application. (And when using an archived Application, the archive must contain such a signature.)

"The phrase application/x-vnd. should lead off the signature. Any characters you want can follow the period, but convention states that this part of the MIME string consist of an abbreviation of your company's name, a hyphen, and then part or all of the program name."

- Programming the Be Operating System, Chapter 1, pp 24-25

When that book was published, use of x- and x. subtypes was already discouraged, and as of January 2013, x. is strongly discouraged, andx- is no longer considered valid. Of course, the body making these recommendations, the IETF, also thinks that "it should rarely, if ever, be necessary to use unregistered types". They clearly didn't have BeOS/Haiku application signatures in mind, since it makes no sense to register your application signature with a standards organization.

Sidebar

I have to wonder about the mindset of an organization that thinks registering a prs. (personal) subtype is a better alternative than simply using an unregistered x. subtype. Seriously, wasting time registering a personal subtype that is going to see extremely limited use is supposed to be better than simply agreeing among the concerned parties to use an unregistered subtype?

However, Haiku does seem to be taking the recommendations into account, because a pattern can be seen in the application signatures contained in the Haiku codebase:

application/x-vnd.Be-whatever (applications inherited from BeOS)
application/x-vnd.obos-whatever (applications inherited from OpenBeOS)
application/x-vnd.Haiku-whatever (early Haiku applications)
application/x.vnd-Haiku.whatever (more recent Haiku applications)

Given that, something like application/x.vnd-COMPANY.PROGRAM would probably be best for new application signatures. This is the pattern followed by WonderBrush, for example: application/x.vnd-YellowBites.WonderBrush. (Although it still uses an x- type for its images: image/x-wonderbrush.)

AppInfo

GetAppInfo

Returns an app_info structure describing the application, or signals an error.

Perl

$application->GetAppInfo();

Python

application.GetAppInfo()

Cursor

ShowCursor

HideCursor

ObscureCursor

IsCursorHidden

SetCursor

Cursor methods. ObscureCursor hides the cursor until the user moves the mouse. IsCursorHidden returns false if the cursor is merely obscured.

The other functions do what you expect.

Perl

$application->ShowCursor();
$application->HideCursor();
$application->ObscureCursor();
$application->IsCursorHidden();
$application->SetCursor($cursor, $sync);

Python

application.ShowCursor()
application.HideCursor()
application.ObscureCursor()
application.IsCursorHidden()
application.SetCursor(cursor, sync)

cursor

A Cursor or a byte string containing raw cursor data. (B_CURSOR_SYSTEM_DEFAULT and B_CURSOR_I_BEAM are valid cursor objects; B_HAND_CURSOR and B_I_BEAM_CURSOR contain valid cursor data.)

(See the Cursor constructor for the format of raw cursor data.)
sync

A boolean; if true (the default), forces a sync with the Application Server so the cursor changes immediately. Only applicable for Cursor objects; raw cursor data always syncs.

IsLaunching

Returns true until ReadyToRun returns.

Perl

$application->IsLaunching();

Python

application.IsLaunching()

Loopers

CountLoopers

LooperAt

RegisterLooper

UnregisterLooper

CountLoopers and LooperAt do what you expect.

RegisterLooper adds a looper to a list of Loopers that will automatically quit when the Application object is destroyed; UnregisterLooper removes a Looper from that list.

Although Window is a subclass of Looper, Windows do not need to be registered using this method.

Perl

$application->CountLoopers();
$application->LooperAt($index);
$application->RegisterLooper($looper);
$application->UnregisterLooper($looper);

Python

application.CountLoopers()
application.LooperAt(index)
application.RegisterLooper(looper)
application.UnregisterLooper(looper)

index

An integer, the index of the desired Looper.
looper

A Looper to register or unregister.

PulseRate

SetPulseRate

Sets the rate at which Pulse messages will be sent to the Application.

Perl

$application->SetPulseRate($rate);

Python

application.SetPulseRate(rate)

rate

An integer, the rate in microseconds.

Signature

Returns the Application's signature.

Perl

$application->Signature();

Python

application.Signature()

Windows

CountWindows

WindowAt

These methods do what you expect.

Perl

$application->CountWindows();
$application->WindowAt($index);

Python

application.CountWindows()
application.WindowAt(index)

index

An integer, the 0-based index of the desired window.

HOOKS

AboutRequested

Called when the app receives a B_ABOUT_REQUESTED message.

Perl

$application->AboutRequested();

Python

application.AboutRequested()

AppActivated

Called when the app receives a B_APP_ACTIVATED message. This message can be sent as a result of user action, or programmatically via Window.Activate or Roster.ActivateApp.

Perl

$application->AppActivated($active);

Python

application.AppActivated(active)

active

A boolean, true indicates the Application is becoming active; false indicates it is becoming inactive.

ArgvReceived

Called when the app receives a B_ARGV_RECEIVED message. This can happen if the app is launched from the command line, or via Roster.Launch. The first argument will be the executable name. Note that if the app is set to B_EXCLUSIVE_LAUNCH or B_SINGLE_LAUNCH, this event may be called multiple times.

Perl

$application->ArgvReceived($args);

Python

application.ArgvReceived(args)

argv

A native list of strings, the arguments, beginning with the executable name. (Note that this is the interpreter, not the script.)

Pulse

Called when the app receives a B_PULSE message. The app will not begin receiving this message until ReadyToRun returns.

Perl

$application->Pulse();

Python

application.Pulse()

ReadyToRun

Called when the app receives a B_READY_TO_RUN message. This message will be sent after Run is called, and after any B_REFS_RECEIVED and B_ARGV_RECEIVED messages.

Perl

$application->ReadyToRun();

Python

application.ReadyToRun()

RefsReceived

Called when the app receives a B_REFS_RECEIVED message. This message will be sent if our app is opened by double-clicking on an associated file, or if a file is dropped on your app's icon. This event may be called either before launch, or when the app is already running; you can tell which by using IsLaunching.

Perl

$application->RefsReceived($message);

Python

application.RefsReceived(message)

message

A Message with a field named refs, which includes one or more entry_refs.

CLASS METHODS

AppResources

A class method that returns a Resources object with data from the currently running executable.

Perl

HaikuR1::Application->AppResources();

Python

Application.AppResources()

ARCHIVABLE INTERFACE

Application inherits the methods and hooks of Archivable.

HANDLER INTERFACE

Application inherits the methods and hooks of Handler.

LOOPER INTERFACE

Application inherits the methods and hooks of Looper.

The following differs from the Looper version:

Run

See Looper.Run.

Unlike the Looper version, this method does not return until the Application quits. That is, instead of spawning a new thread for a message loop, its message loop takes over the calling thread.

GLOBALS

Perl

use HaikuR1::Application qw(:globals)

Python

Python does not support export tags.

be_app

The application object.

Python

Since be_app is not instantiated on the C++ side until the Application is created, it is initially set to None. If you wish to use it, you must wait to import it until after you have created your Application object.

The same does not apply to be_app_messenger; it is instantiated on startup, although it remains emtpy (i.e., without a valid target) until your Application object is created.

be_app_messenger

A Messenger that targets the application object.

SCRIPTING SUITE

The name of Looper's scripting suite is suite/vnd.Be-application.

Properties
- Looper
  - B_COUNT_PROPERTIES
    
    gets the number of Loopers in the Application
  - B_GET_PROPERTY
    
    gets a set of Messengers targeting each of the Application's Loopers
- Name
  - B_GET_PROPERTY
    
    a string, the name of the Application's main thread
- Window
  - B_COUNT_PROPERTIES
    
    gets the number of Windows in the Application
- Windows
  - B_GET_PROPERTY
    
    gets a set of Messengers targeting each of the Application's Windows
Specifiers
- Looper
  - B_ID_SPECIFIER
    
    targets a Looper by unique integer id (not yet implemented, as of Haiku revision ...) TODO: check this out
  - B_INDEX_SPECIFIER, B_REVERSE_INDEX_SPECIFIER
    
    targets the Application's indexth Looper, either from the front or the end of the list
- Window
  - B_INDEX_SPECIFIER, B_REVERSE_INDEX_SPECIFIER
    
    targets the Application's indexth Window, either from the front or the end of the list

Application also inherits the following suites: