nephele
/
haiku-website
0
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
haiku-website/static/legacy-docs/bebook/BApplication.html

240 lines
47 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Be Book - Classes And Methods - The Application Kit</title><link rel="stylesheet" href="be_book.css" type="text/css" media="all" /><link rel="shortcut icon" type="image/vnd.microsoft.icon" href="./images/favicon.ico" /><!--[if IE]>
<link rel="stylesheet" type="text/css" href="be_book_ie.css" />
<![endif]--><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="Access, BeOS, BeBook, API" /><link rel="start" href="index.html" title="The Be Book" /><link rel="up" href="TheApplicationKit.html" title="The Application Kit" /><link rel="prev" href="TheApplicationKit.html" title="The Application Kit" /><link rel="next" href="BClipboard.html" title="BClipboard" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="TheApplicationKit.html" title="The Application Kit"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheApplicationKit.html" title="The Application Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="BClipboard.html" title="BClipboard"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="headerTR"><div id="navigpeople"><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div><div class="navigboxed" id="navigindex"><a accesskey="i" href="ClassIndex.html" title="Index">I</a></div><div class="navigboxed" id="naviglang" title="English">en</div></div><div id="headerTC">The Be Book - Classes And Methods - The Application Kit</div></div><div id="headerB">Prev: <a href="TheApplicationKit.html">The Application Kit</a>  Up: <a href="TheApplicationKit.html">The Application Kit</a>  Next: <a href="BClipboard.html">BClipboard</a></div><hr /></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h2 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication"></a>BApplication</h2></div></div></div><a id="id661546" class="indexterm"></a><div class="classheader"><table border="0"><colgroup><col /><col /></colgroup><tbody><tr><td><table width="100%" border="0"><colgroup><col /><col /></colgroup><tbody><tr><td>Derived From:</td><td><a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a> &gt;
<a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a></td></tr><tr><td>Mix-in Classes:</td><td><a class="link" href="BArchivable.html" title="BArchivable"><code class="classname">BArchivable</code></a></td></tr><tr><td>Declared In:</td><td><code class="filename">app/Application.h</code></td></tr><tr><td>Library:</td><td><code class="filename">libbe.so</code></td></tr><tr><td>Allocation:</td><td>–</td></tr></tbody></table></td><td>
<a class="link overview" href="BApplication_Overview.html" title="BApplication">Class Overview</a>
<div class="toc"><ul><li><span class="section"><a href="BApplication.html#BApplication_ConstructorDestructor">Constructor and Destructor</a></span></li><li><span class="section"><a href="BApplication.html#BApplication_HookFunctions">Hook Functions</a></span></li><li><span class="section"><a href="BApplication.html#BApplicationMemberFunctions">Member Functions</a></span></li><li><span class="section"><a href="BApplication.html#BApplication_StaticFunctions">Static Functions</a></span></li><li><span class="section"><a href="BApplication.html#BApplication_GlobalVariables">Global Variables</a></span></li><li><span class="section"><a href="BApplication.html#BApplication_ArchivedFields">Archived Fields</a></span></li><li><span class="section"><a href="BApplication.html#BApplication_ScriptingSuites">Scripting Suites and Properties</a></span></li></ul></div>
</td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_ConstructorDestructor"></a>Constructor and Destructor</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_Constructor"></a>BApplication()</h4></div></div></div><div class="synopsisgroup">
<code class="constructorsynopsis cpp"><span class="methodname">BApplication</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">signature</span></span>);</code>
<code class="constructorsynopsis cpp"><span class="methodname">BApplication</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">signature</span></span>,<br />             <span class="methodparam"><span class="type">status_t* </span><span class="parameter">error</span></span>);</code>
<code class="constructorsynopsis cpp"><span class="methodname">BApplication</span>(<span class="methodparam"><span class="type">BMessage* </span><span class="parameter">archive</span></span>);</code>
</div><p>The constructor creates a new object, locks it, sets the global variable
<a class="link" href="BApplication.html#BApplication_be_app" title="be_app"><code class="varname">be_app</code></a> to point to it,
and establishes a connection to the <span class="application">Application Server</span>. From this point on,
your application can receive messages, although it won't start processing them until you call
<a class="link" href="BApplication.html#BApplication_Run" title="Run(), Quit()"><code class="methodname">Run()</code></a>.
You can also begin creating and displaying
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a> objects even
before you call
<a class="link" href="BApplication.html#BApplication_Run" title="Run(), Quit()"><code class="methodname">Run()</code></a>.</p><p>The <code class="parameter">signature</code> constructors assign the argument as the app's
application signature. The argument is ignored if a signature is already specified
in a resource or attribute of the application's executable (serious apps should
always set the signature as both an attribute and a resource). The signature is
a <acronym class="acronym" title="Multi-purpose Internet Mail Extensions">MIME</acronym> type string
that must have the supertype "application". For more information on
application signatures and how to set them, see
<span class="bold"><strong>TODO</strong></span>.</p><p>If you specify <code class="parameter">error</code>, a pointer to a <span class="type">status_t</span>, any error that occurs
while constructing the <code class="classname">BApplication</code> will be returned in
that variable. Alternately, you can call
<a class="link" href="BApplication.html#BApplication_InitCheck" title="InitCheck()"><code class="methodname">InitCheck()</code></a>
to check the results. If an error is returned by the constructor, you shouldn't call
<a class="link" href="BApplication.html#BApplication_Run" title="Run(), Quit()"><code class="methodname">Run()</code></a>.</p><p>The <code class="parameter">archive</code> constructor is an implementation detail; see the
<a class="link" href="BArchivable.html" title="BArchivable">BArchivable</a> class.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_Destructor"></a>~BApplication()</h4></div></div></div><code class="destructorsynopsis cpp"><span class="modifier">virtual </span><span class="methodname">~BApplication</span>();</code><p>Closes and deletes the application's
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a>s (and the
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>s they contain),
and severs the application's connection to the
<span class="application">Application Server</span>.</p><p>Never delete a <code class="classname">BApplication</code> object while it's
running; wait until
<a class="link" href="BApplication.html#BApplication_Run" title="Run(), Quit()"><code class="methodname">Run()</code></a>
returns. To stop a <code class="classname">BApplication</code> (and so cause
<a class="link" href="BApplication.html#BApplication_Run" title="Run(), Quit()"><code class="methodname">Run()</code></a>
to return), send it a
<a class="link" href="TheApplicationKit_MessageConstants.html#B_QUIT_REQUESTED" title="B_QUIT_REQUESTED"><code class="constant">B_QUIT_REQUESTED</code></a>
message:</p><pre class="programlisting example cpp"><code class="varname">be_app</code>-&gt;<code class="methodname">PostMessage</code>(<code class="constant">B_QUIT_REQUESTED</code>);</pre></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_HookFunctions"></a>Hook Functions</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_AboutRequested"></a>AboutRequested()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">AboutRequested</span>();</code><p>Hook function that's invoked when the <code class="classname">BApplication</code>
receives a
<a class="link" href="TheApplicationKit_MessageConstants.html#B_ABOUT_REQUESTED" title="B_ABOUT_REQUESTED"><code class="constant">B_ABOUT_REQUESTED</code></a> message, undoubtedly
because the user clicked an "<span class="guimenuitem">About…</span>"
menu item. You should implement the function to put a window on-screen that
provides the user with information about the application (version number,
license restrictions, authors' names, etc).</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_AppActivated"></a>AppActivated()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">AppActivated</span>(<span class="methodparam"><span class="type">bool </span><span class="parameter">active</span></span>);</code><p>Hook function that's invoked when the application receives a
<a class="link" href="TheApplicationKit_MessageConstants.html#B_APP_ACTIVATED" title="B_APP_ACTIVATED"><code class="constant">B_APP_ACTIVATED</code></a>
message. The message is sent when the
application gains or loses active application status. The <code class="parameter">active</code>
flag tells you which way the wind blows: <code class="constant">true</code> means
your application is now active; <code class="constant">false</code> means it isn't.</p><p>The user can activate an application by clicking on or unhiding one of its windows;
you can activate an application programmatically by calling <a class="link" href="BWindow.html#BWindow_Activate" title="Activate(), IsActive()"><code class="methodname">BWindow::Activate()</code></a> or
<a class="link" href="BRoster.html#BRoster_ActivateApp" title="ActivateApp()"><code class="methodname">BRoster::ActivateApp()</code>
</a>. (With regard to the latter: This function is called only if the
application has an "activatable" window i.e. a non-modal, non-floating
window).</p><p>During launch, this function is called after
<a class="link" href="BApplication.html#BApplication_ReadyToRun" title="ReadyToRun()"><code class="methodname">ReadyToRun()</code></a>
(provided the application is displaying an activatable window).</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_ArgvReceived"></a>ArgvReceived()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">ArgvReceived</span>(<span class="methodparam"><span class="type">int32 </span><span class="parameter">argc</span></span>,<br />                          <span class="methodparam"><span class="type">char** </span><span class="parameter">argv</span></span>);</code><p>Hook function that's invoked when the application receives a
<a class="link" href="TheApplicationKit_MessageConstants.html#B_ARGV_RECEIVED" title="B_ARGV_RECEIVED"><code class="constant">B_ARGV_RECEIVED</code></a>
message. The message is sent if command
line arguments are used in launching the application from the shell, or if
<code class="parameter">argv</code>/<code class="parameter">argc</code> values are passed to
<a class="link" href="BRoster.html#BRoster_Launch" title="Launch()"><code class="methodname">BRoster::Launch()</code></a>.</p><div class="admonition warning"><div class="title">Warning</div><div class="graphic"><img class="icon" alt="Warning" width="32" src="./images/admonitions/Stop_32.png" /><div class="text"><p>This function isn't called if there were no command line arguments, or if
<a class="link" href="BRoster.html#BRoster_Launch" title="Launch()"><code class="methodname">BRoster::Launch()</code></a>
was called without <code class="parameter">argv</code>/<code class="parameter">argc</code> values.</p></div></div></div><p>When the application is launched from the shell, <code class="methodname">ArgvReceived()</code>'s
arguments are identical to the traditional <code class="function">main()</code>
arguments: The number of command line arguments is passed as
<code class="parameter">argc</code>; the arguments themselves are passed as an array of
strings in <code class="parameter">argv</code>. The first <code class="parameter">argv</code>
string identifes the executable file; the other strings are the command line
arguments proper. For example, this…</p><pre class="screen">$ MyApp file1 file2</pre><p>…produces the <code class="parameter">argv</code> array
{ "./MyApp", "file1", "file2" }.
</p><p><a class="link" href="BRoster.html#BRoster_Launch" title="Launch()"><code class="methodname">BRoster::Launch()</code></a>
forwards its <code class="parameter">argv</code> and <code class="parameter">argc</code>
arguments, but adds the executable name to the front of the
<code class="parameter">argv</code> array and increments the
<code class="parameter">argc</code> value.</p><p>Normally, the <a class="link" href="TheApplicationKit_MessageConstants.html#B_ARGV_RECEIVED" title="B_ARGV_RECEIVED"><code class="constant">B_ARGV_RECEIVED</code></a>
message (if sent at all) is sent once, just before
<a class="link" href="TheApplicationKit_MessageConstants.html#B_READY_TO_RUN" title="B_READY_TO_RUN"><code class="constant">B_READY_TO_RUN</code></a>
is sent. However, if the user tries to re-launch (from the command line and with
arguments) an already-running application that's set to
<a class="link" href="BRoster.html#B_EXCLUSIVE_LAUNCH"><code class="constant">B_EXCLUSIVE_LAUNCH</code></a> or
<a class="link" href="BRoster.html#B_SINGLE_LAUNCH"><code class="constant">B_SINGLE_LAUNCH</code></a>,
the re-launch will generate a
<a class="link" href="TheApplicationKit_MessageConstants.html#B_ARGV_RECEIVED" title="B_ARGV_RECEIVED"><code class="constant">B_ARGV_RECEIVED</code></a>
message that's sent to the already-running image. Thus, for such apps, the
<a class="link" href="TheApplicationKit_MessageConstants.html#B_ARGV_RECEIVED" title="B_ARGV_RECEIVED"><code class="constant">B_ARGV_RECEIVED</code></a>
message can show up at any time.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_Pulse"></a>Pulse()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">Pulse</span>();</code><p><code class="methodname">Pulse()</code> is a hook function that's called when
the application receives a <a class="link" href="TheApplicationKit_MessageConstants.html#B_PULSE" title="B_PULSE"><code class="constant">B_PULSE</code></a>
message. The message is sent at the rate set in
<a class="link" href="BApplication.html#BApplication_SetPulseRate" title="SetPulseRate()"><code class="methodname">SetPulseRate()</code></a>.
The first <code class="methodname">Pulse()</code> message is sent after
<a class="link" href="BApplication.html#BApplication_ReadyToRun" title="ReadyToRun()"><code class="methodname">ReadyToRun()</code></a> returns.</p><p>You can implement <code class="methodname">Pulse()</code> to do whatever you want (the
default version does nothing), but don't try to use it for precision timing: The
pulse granularity is no better than 100,000 microseconds.</p><p>Keep in mind that <code class="methodname">Pulse()</code> executes in the app's message loop
thread along with all other message handling functions. Your application won't receive any
<code class="methodname">Pulse()</code> invocations while it's waiting for some other handler
function (including
<a class="link" href="BApplication.html#BApplication_MessageReceived" title="MessageReceived()"><code class="methodname">MessageReceived()</code></a>)
to finish. In the meantime,
<a class="link" href="TheApplicationKit_MessageConstants.html#B_PULSE" title="B_PULSE"><code class="constant">B_PULSE</code></a>
messages will be stacking up
in the message queue; when the loop becomes "unblocked", you'll see a burst
of <code class="methodname">Pulse()</code> invocations.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_QuitRequested"></a>QuitRequested()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">bool </span><span class="methodname">QuitRequested</span>();</code><p>Hook function that's invoked when the application receives a
<a class="link" href="TheApplicationKit_MessageConstants.html#B_QUIT_REQUESTED" title="B_QUIT_REQUESTED"><code class="constant">B_QUIT_REQUESTED</code></a>
message. As described in the
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a> class (which declares
this function), the request to quit is confirmed if
<code class="methodname">QuitRequested()</code> returns <code class="constant">true</code>, and
denied if it returns <code class="constant">false</code>.</p><p>In its implementation, <code class="classname">BApplication</code> sends
<a class="link" href="BLooper.html#BLooper_QuitRequested" title="QuitRequested()"><code class="methodname">BLooper::QuitRequested()</code></a>
to each of its <a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a>
objects. If they all agree to quit, the windows are all destroyed (through
<a class="link" href="BWindow.html#BWindow_Quit" title="Quit()"><code class="methodname">BWindow::Quit()</code></a>)
and this <code class="methodname">QuitRequested()</code> returns
<code class="constant">true</code>. But if any
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a> refuses to quit,
that window and all surviving windows are saved, and this
<code class="methodname">QuitRequested()</code> returns <code class="constant">false</code>.</p><p>Augment this function as you will, but be sure to call the
<code class="classname">BApplication</code> version in your implementation.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_ReadyToRun"></a>ReadyToRun()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">ReadyToRun</span>();</code><p>Hook function that's called when the application receives a
<a class="link" href="TheApplicationKit_MessageConstants.html#B_READY_TO_RUN" title="B_READY_TO_RUN"><code class="constant">B_READY_TO_RUN</code></a>
message. The message is sent automatically during the
<a class="link" href="BApplication.html#BApplication_Run" title="Run(), Quit()"><code class="methodname">Run()</code></a>
function, and is sent after the initial
<a class="link" href="TheApplicationKit_MessageConstants.html#B_REFS_RECEIVED" title="B_REFS_RECEIVED"><code class="constant">B_REFS_RECEIVED</code></a> and
<a class="link" href="TheApplicationKit_MessageConstants.html#B_ARGV_RECEIVED" title="B_ARGV_RECEIVED"><code class="constant">B_ARGV_RECEIVED</code></a>
messages (if any) have been handled. This is the only application message
that every running application is guaranteed to receive.</p><p>What you do with <code class="methodname">ReadyToRun()</code> is up to you,
if your application hasn't put up a window by the time this function is
called, you'll probably want to do it here. The default version of
<code class="methodname">ReadyToRun()</code> is empty.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_RefsReceived"></a>RefsReceived()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">RefsReceived</span>(<span class="methodparam"><span class="type">BMessage* </span><span class="parameter">message</span></span>);</code><p>Hook function that's called when the application receives a
<a class="link" href="TheApplicationKit_MessageConstants.html#B_REFS_RECEIVED" title="B_REFS_RECEIVED"><code class="constant">B_REFS_RECEIVED</code></a>
message. The message is sent when the user drops a file (or files) on your
app's icon, or double clicks a file that's handled by your app. The message
can arrive either at launch time, or while your application is already
running use
<a class="link" href="BApplication.html#BApplication_IsLaunching" title="IsLaunching()"><code class="methodname">IsLaunching()</code></a>
to tell which.</p><p><code class="parameter">message</code> contains a single field named
<code class="varname">be:refs</code> that contains one or more <span class="type">entry_ref</span>
(<code class="constant">B_REF_TYPE</code>) items one for each file that was dropped
or double-clicked. Do with them what you will; the default implementation
is empty. Typically, you would use the refs to create
<a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a> or
<a class="link" href="BFile.html" title="BFile"><code class="classname">BFile</code></a> objects.</p></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplicationMemberFunctions"></a>Member Functions</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_InitCheck"></a>InitCheck()</h4></div></div></div><p>????</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_Archive"></a>Archive()</h4></div></div></div><p>See <a class="link" href="BArchivable.html#BArchivable_Archive" title="Archive()"><code class="methodname">BArchivable::Archive()</code></a></p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_DispatchMessage"></a>DispatchMessage()</h4></div></div></div><p>See <a class="link" href="BLooper.html#BLooper_DispatchMessage" title="DispatchMessage()"><code class="methodname">BLooper::DispatchMessage()</code></a>
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_GetAppInfo"></a>GetAppInfo()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetAppInfo</span>(<span class="methodparam"><span class="type"><a class="link" href="BRoster.html#app_info" title="app_info"><span class="type">app_info</span></a>* </span><span class="parameter">theInfo</span></span>) <span class="modifier">const</span>;</code><p>Returns information about the application. This is a cover for</p><pre class="programlisting example cpp"><code class="varname">be_roster</code>-&gt;<code class="methodname">GetRunningAppInfo</code>(<code class="varname">be_app</code>-&gt;<code class="methodname">Team</code>(), <code class="varname">theInfo</code>);</pre><p>See <a class="link" href="BRoster.html#BRoster_GetAppInfo" title="GetAppInfo(), GetRunningAppInfo(), GetActiveAppInfo()"><code class="methodname">BRoster::GetAppInfo()</code></a>
for more information.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_GetSupportedSuites"></a>GetSupportedSuites()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">status_t </span><span class="methodname">GetSupportedSuites</span>(<span class="methodparam"><span class="type">BMessage* </span><span class="parameter">message</span></span>);</code><p>Adds the scripting suite "suite/vnd.Be-application" to message. See
"<a class="xref" href="BApplication.html#BApplication_ScriptingSuites" title="Scripting Suites and Properties">Scripting Suites and Properties</a>"
for the suite's properties. Also see
<a class="link" href="BHandler.html#BHandler_GetSupportedSuites" title="GetSupportedSuites()"><code class="methodname">BHandler::GetSupportedSuites()</code></a>
for more information on how this function works.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_IsLaunching"></a>IsLaunching()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">IsLaunching</span>() <span class="modifier">const</span>;</code><p>Returns <code class="constant">true</code> if the application is still
launching. An application is considered to be in its launching phase until
<a class="link" href="BApplication.html#BApplication_ReadyToRun" title="ReadyToRun()"><code class="methodname">ReadyToRun()</code></a>
returns. Invoked from within
<a class="link" href="BApplication.html#BApplication_ReadyToRun" title="ReadyToRun()"><code class="methodname">ReadyToRun()</code></a>,
<code class="methodname">IsLaunching()</code> returns
<code class="constant">true</code>.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_MessageReceived"></a>MessageReceived()</h4></div></div></div><p>See
<a class="link" href="BHandler.html#BHandler_MessageReceived" title="MessageReceived()"><code class="methodname">BHandler::MessageReceived()</code></a></p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_ResolveSpecifier"></a>ResolveSpecifier()</h4></div></div></div><p>See
<a class="link" href="BHandler.html#BHandler_ResolveSpecifier" title="ResolveSpecifier()"><code class="methodname">BHandler::ResolveSpecifier()</code></a></p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_Run"></a><a id="BApplication_Quit"></a>
Run(), Quit()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">thread_id </span><span class="methodname">Run</span>();</code><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">Quit</span>();</code><p>These functions, inherited from
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a>, are different
enough from their parent versions to warrant description.</p><p><code class="methodname">Run()</code> doesn't spawn a new thread—it runs
the message loop in the thread that it's called from, and doesn't return
until the message loop stops.</p><p><code class="methodname">Quit()</code> doesn't kill the looper thread it tells the
thread to finish processing the message queue (disallowing new messages) at
which point <code class="methodname">Run()</code> will be able to return. After so
instructing the thread, <code class="methodname">Quit()</code> returns, it doesn't
wait for the message queue to empty.</p><p>Also, <code class="methodname">Quit()</code> doesn't delete the
<code class="classname">BApplication</code> object. It's up to you to delete it
after <code class="methodname">Run()</code> returns. (However,
<code class="methodname">Quit()</code> <span class="emphasis"><em>does</em></span> delete the object
if it's called before the message loop starts i.e. before
<code class="methodname">Run()</code> is called.)</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_SetCursor"></a><a id="BApplication_HideCursor"></a>
<a id="BApplication_ShowCursor"></a>
<a id="BApplication_ObscureCursor"></a>
<a id="BApplication_IsCursorHidden"></a>
SetCursor(), HideCursor(), ShowCursor(), ObscureCursor(), IsCursorHidden()</h4></div></div></div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">SetCursor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">void* </span><span class="parameter">cursor</span></span>);</code>
<code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">SetCursor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type"><a class="link" href="BCursor.html" title="BCursor"><code class="classname">BCursor</code></a>* </span><span class="parameter">cursor</span></span>,<br />               <span class="methodparam"><span class="type">bool </span><span class="parameter">sync</span><span class="initializer"> = <span class="constant">true</span></span></span>);</code>
</div><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">HideCursor</span>();</code><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">ShowCursor</span>();</code><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">ObscureCursor</span>();</code><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">IsCursorHidden</span>() <span class="modifier">const</span>;</code><p><code class="methodname">SetCursor()</code> sets the cursor image that's used when
this is the active application.</p><p>You can pass one of the Be-defined cursor
constants (<a class="link" href="BCursor.html#B_HAND_CURSOR"><code class="constant">B_HAND_CURSOR</code></a> and
<a class="link" href="BCursor.html#B_I_BEAM_CURSOR"><code class="constant">B_I_BEAM_CURSOR</code></a>)
or create your own cursor image. The cursor data format is described
in the <a class="link" href="BCursor.html" title="BCursor"><code class="classname">BCursor</code></a>
<a class="link" href="BCursor_Overview.html" title="BCursor">class overview</a>.</p><p>You can also call <code class="methodname">SetCursor()</code> passing a
<a class="link" href="BCursor.html" title="BCursor"><code class="classname">BCursor</code></a> object;
specifying <code class="parameter">sync</code> as <code class="constant">true</code>
forces the Application Server to immediately
resynchronize, thereby ensuring that the cursor change takes place
immediately. The default <a class="link" href="BCursor.html" title="BCursor"><code class="classname">BCursor</code></a>s are
<a class="link" href="BCursor.html#B_CURSOR_SYSTEM_DEFAULT"><code class="constant">B_CURSOR_SYSTEM_DEFAULT</code></a>
for the hand cursor and
<a class="link" href="BCursor.html#B_CURSOR_I_BEAM"><code class="constant">B_CURSOR_I_BEAM</code></a>
for the I-beam text editing cursor.</p><p><code class="methodname">HideCursor()</code> removes the cursor from the screen.</p><p><code class="methodname">ShowCursor()</code> restores it.</p><p><code class="methodname">ObscureCursor()</code> hides the cursor until the user moves the mouse.</p><p><code class="methodname">IsCursorHidden()</code> returns <code class="constant">true</code>
if the cursor is hidden (but not obscured), and <code class="constant">false</code>
if not.</p><p>The cursor data format is described in the
"<a class="link" href="BCursor_Overview.html#BCursor_Overview_CursorDataFormat" title="Cursor Data Format">Cursor Data Format</a>" section
in the <a class="link" href="BCursor_Overview.html" title="BCursor"><code class="classname">BCursor</code> overview</a>.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_SetPulseRate"></a>SetPulseRate()</h4></div></div></div><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">SetPulseRate</span>(<span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">rate</span></span>);</code><p>Sets the period between
<a class="link" href="TheApplicationKit_MessageConstants.html#B_PULSE" title="B_PULSE"><code class="constant">B_PULSE</code></a>
messages being sent and the
<a class="link" href="BApplication.html#BApplication_Pulse" title="Pulse()"><code class="methodname">Pulse()</code></a>
method being called. If the pulse rate is 0 (the default), the
<a class="link" href="TheApplicationKit_MessageConstants.html#B_PULSE" title="B_PULSE"><code class="constant">B_PULSE</code></a>
messages aren't sent.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_WindowAt"></a><a id="BApplication_CountWindows"></a>
WindowAt(), CountWindows()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">BWindow* </span><span class="methodname">WindowAt</span>(<span class="methodparam"><span class="type">int32 </span><span class="parameter">index</span></span>) <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="type">int32 </span><span class="methodname">CountWindows</span>() <span class="modifier">const</span>;</code><p><code class="methodname">WindowAt()</code> returns the <code class="parameter">index</code>'th
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a> object in the
application's window list. If <code class="parameter">index</code> is out of range, the
function returns <code class="constant">NULL</code>.</p><p><code class="methodname">CountWindows()</code> returns the number of windows in the
window list.</p><p>The windows list includes all windows explicitly created by the app—whether
they're normal, floating, or modal, and whether or not they're actually
displayed—but excludes private windows created by Be classes.</p><p>The order of windows in the list has no signficance.</p><p>Locking the <code class="classname">BApplication</code> object doesn't lock the window
list. If you need coordinated access to the list, you'll have to provide your
own locking mechanism that protects these functions and all
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a> construction
and deletion.</p></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_StaticFunctions"></a>Static Functions</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_AppResources"></a>AppResources()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">static </span><span class="type"><a class="link" href="BResources.html" title="BResources"><code class="classname">BResources</code></a>* </span><span class="methodname">AppResources</span>();</code><p>Returns a <a class="link" href="BResources.html" title="BResources"><code class="classname">BResources</code></a> object that's
configured from your application's executable file. You may read the data
in the <a class="link" href="BResources.html" title="BResources"><code class="classname">BResources</code></a>
object, but you're not allowed to write it; see the <a class="link" href="BResources.html" title="BResources"><code class="classname">BResources</code></a> class for
details. The <a class="link" href="BResources.html" title="BResources"><code class="classname">BResources</code></a> object
belongs to the <code class="classname">BApplication</code> class and mustn't be
freed.</p><p>You needn't have a <code class="varname">be_app</code> object to
invoke this function.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_Instantiate"></a>Instantiate()</h4></div></div></div><p>See <a class="link" href="BArchivable.html#BArchivable_Instantiate" title="Instantiate()"><code class="methodname">BArchivable::Instantiate()</code></a></p></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_GlobalVariables"></a>Global Variables</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_be_app"></a>be_app</h4></div></div></div><pre class="programlisting definition cpp"><span class="type"><code class="classname">BApplication</code>*</span> <code class="varname">be_app</code>;</pre><p><code class="varname">be_app</code> is the global variable that
represents your <code class="classname">BApplication</code> object. You can refer
to <code class="varname">be_app</code> anywhere you need a reference to the <code class="classname">BApplication</code> object that you created. If you want to call a function that's declared by your <code class="classname">BApplication</code> subclass, you have to cast <code class="varname">be_app</code> to your subclass:</p><pre class="programlisting example cpp">((<span class="type">MyApp *</span>)<code class="varname">be_app</code>)-&gt;<code class="methodname">MyAppFunction</code>();</pre></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_be_app_messenger"></a>be_app_messenger</h4></div></div></div><pre class="programlisting definition cpp"><span class="type"><a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a>*</span> <code class="varname">be_app_messenger</code>;</pre><p><code class="varname">be_app_messenger</code> is a global
<a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a> that
targets your <code class="varname">be_app</code> object. It's created in the
<code class="classname">BApplication</code> <a class="link" href="BApplication.html#BApplication_Constructor" title="BApplication()">constructor</a>.</p></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_ArchivedFields"></a>Archived Fields</h3></div></div></div><div class="informaltable"><table border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Field</th><th align="left">Type code</th><th align="left">Description</th></tr></thead><tbody><tr><td align="left"><code class="varname">mime_sig</code></td><td align="left"><code class="constant">B_STRING_TYPE</code></td><td align="left">Application signature.</td></tr></tbody></table></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_ScriptingSuites"></a>Scripting Suites and Properties</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="id670603"></a>Suite: "suite/vnd.Be-application"</h4></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_CommandName"></a>"Name"</h5></div></div></div><div class="informaltable"><table border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Command</th><th align="left">Specifier</th><th align="left">Description</th></tr></thead><tbody><tr><td align="left"><code class="constant">B_GET_PROPERTY</code></td><td align="left"><code class="constant">B_DIRECT_SPECIFIER</code></td><td align="left">Gets the name of the application's main thread.</td></tr></tbody></table></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BApplication_CommandWindow"></a>"Window"</h5></div></div></div><div class="informaltable"><table border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Command</th><th align="left">Specifier</th><th align="left">Description</th></tr></thead><tbody><tr><td align="left"><code class="constant">B_COUNT_PROPERTIES</code></td><td align="left"><code class="constant">B_DIRECT_SPECIFIER</code></td><td align="left">Returns <a class="link" href="BApplication.html#BApplication_CountWindows"><code class="methodname">CountWindows()</code></a>.</td></tr><tr><td align="left">Not applicable.</td><td align="left"><code class="constant">B_NAME_SPECIFIER</code>,
<code class="constant">B_INDEX_SPECIFIER</code>,
<code class="constant">B_REVERSE_INDEX_SPECIFIER</code></td><td align="left">The message is forwarded to the specified <a class="link" href="BWindow.html" title="BWindow">BWindow</a>.</td></tr></tbody></table></div></div></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="TheApplicationKit.html">The Application Kit</a>  Up: <a href="TheApplicationKit.html">The Application Kit</a>  Next: <a href="BClipboard.html">BClipboard</a> </div><div id="footerB"><div id="footerBL"><a href="TheApplicationKit.html" title="The Application Kit"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheApplicationKit.html" title="The Application Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="BClipboard.html" title="BClipboard"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="footerBR"><div><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div></div><div id="footerBC"><a href="http://www.access-company.com/home.html" title="ACCESS Co."><img alt="Access Company" src="./images/access_logo.png" /></a></div></div></div><div id="licenseFooter"><div id="licenseFooterBL"><a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/" title="Creative Commons License"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/l/by-nc-nd/3.0/88x31.png" /></a></div><div id="licenseFooterBR"><a href="./LegalNotice.html">Legal Notice</a></div><div id="licenseFooterBC"><span id="licenseText">This work is licensed under a
<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative
Commons Attribution-Non commercial-No Derivative Works 3.0 License</a>.</span></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink