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

120 lines
22 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.

<?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 - System Overview - 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_Overview.html" title="The Application Kit" /><link rel="prev" href="TheApplicationKit_Scripting.html" title="Scripting" /><link rel="next" href="BClipboard_Overview.html" title="BClipboard" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="TheApplicationKit_Scripting.html" title="Scripting"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheApplicationKit_Overview.html" title="The Application Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="BClipboard_Overview.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 - System Overview - The Application Kit</div></div><div id="headerB">Prev: <a href="TheApplicationKit_Scripting.html">Scripting</a>  Up: <a href="TheApplicationKit_Overview.html">The Application Kit</a>  Next: <a href="BClipboard_Overview.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_Overview"></a>BApplication</h2></div></div></div><a id="id435678" class="indexterm"></a><p>The
<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>
class defines an object that represents your application, creates a connection to the
<span class="application">App Server</span>, and runs your app's main message loop. An app can only create one
<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>
object; the system automatically sets the global
<a class="link" href="BApplication.html#BApplication_be_app" title="be_app"><code class="varname">be_app</code></a>
object to point to the
<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>
object you create.</p><p>A <a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>
object's most pervasive task is to handle messages that are sent to your app, a subject that's described
in detail below. But message handling aside, you can also use your
<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>
object to…</p><dl class="variablelist"><dt><span class="term">Control the cursor.</span></dt><dd><p><a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>
defines functions that hide and show the cursor, and set the cursor's image. See
<a class="link" href="BApplication.html#BApplication_SetCursor" title="SetCursor(), HideCursor(), ShowCursor(), ObscureCursor(), IsCursorHidden()"><code class="methodname">SetCursor()</code></a>.</p></dd><dt><span class="term">Access the window list.</span></dt><dd><p>You can iterate through the windows that your application has created with
<a class="link" href="BApplication.html#BApplication_WindowAt" title="WindowAt(), CountWindows()"><code class="methodname">WindowAt()</code></a>.</p></dd><dt><span class="term">Get information about your application.</span></dt><dd><p>Your app's signature, executable location, and launch flags can be retrieved through
<a class="link" href="BApplication.html#BApplication_GetAppInfo" title="GetAppInfo()"><code class="methodname">GetAppInfo()</code></a>.
Additional information icons, version strings, recognized file types can be retrieved by creating an
<a class="link" href="BAppFileInfo.html" title="BAppFileInfo"><code class="classname">BAppFileInfo</code></a>
object based on your app's executable file.
<a class="link" href="BAppFileInfo.html" title="BAppFileInfo"><code class="classname">BAppFileInfo</code></a>
is defined in the
<a class="xref" href="TheStorageKit.html" title="The Storage Kit">The Storage Kit</a>.</p></dd></dl><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="id435862"></a><code class="varname">be_app</code> and Subclassing BApplication</h3></div></div></div><p>Because of its importance, the
<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>
object that you create is automatically assigned to the global
<a class="link" href="BApplication.html#BApplication_be_app" title="be_app"><code class="varname">be_app</code></a> variable.
Anytime you need to refer to your
<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a> object from
anywhere in your code you can use <a class="link" href="BApplication.html#BApplication_be_app" title="be_app"><code class="varname">be_app</code></a> instead.</p><p>Unless you're creating a very simple application, you should subclass <a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>. But be
aware that the <a class="link" href="BApplication.html#BApplication_be_app" title="be_app"><code class="varname">be_app</code></a> variable is
typed as (<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a> *).
You'll have to cast <a class="link" href="BApplication.html#BApplication_be_app" title="be_app"><code class="varname">be_app</code></a> when you call
a function that's declared by 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><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="id435973"></a>Constructing the Object and Running the Message Loop</h3></div></div></div><p>As with all <a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a>s, to use a
<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a> you construct
the object and then tell it to start its message loop by calling the
<a class="link" href="BApplication.html#BApplication_Run" title="Run(), Quit()"><code class="methodname">Run()</code></a> function.
However, unlike other loopers,
<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>'s
<a class="link" href="BApplication.html#BApplication_Run" title="Run(), Quit()"><code class="methodname">Run()</code></a> doesn't return
until the application is told to quit. And after
<a class="link" href="BApplication.html#BApplication_Run" title="Run(), Quit()"><code class="methodname">Run()</code></a> returns, you
delete the object it isn't deleted for you.</p><p>Typically, you create your
<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a> object in
your <code class="methodname">main()</code> function—it's usually the first object
you create. The barest outline of a typical <code class="methodname">main()</code> function
looks something like this:</p><pre class="programlisting example cpp">#include Application.h
<code class="function">main</code>()<a id="simplemain.main"></a><span class="callout"><img src="./images/callouts/1.png" alt="1" /></span>
{
<a id="simplemain.new"></a><span class="callout"><img src="./images/callouts/2.png" alt="2" /></span>new <code class="classname">BApplication</code>("application/x-vnd.your-app-sig")<a id="simplemain.sig"></a><span class="callout"><img src="./images/callouts/3.png" alt="3" /></span>;
<span class="comment">/* Further initialization goes here -- read settings,
set globals, etc. */</span>
<code class="varname">be_app</code>-&gt;<code class="methodname">Run</code>()<a id="simplemain.run"></a><span class="callout"><img src="./images/callouts/4.png" alt="4" /></span>;
<span class="comment">/* Clean up -- write settings, etc. */</span>
delete <code class="varname">be_app</code>;
}</pre><div class="calloutlist"><table summary="Callout list"><tr><td><a href="#simplemain.main"><span class="callout"><img src="./images/callouts/1.png" alt="1" /></span></a> </td><td><p>The <code class="methodname">main()</code> function doesn't declare <code class="varname">argc</code> and
<code class="varname">argv</code> parameters (used for passing along command line arguments). If
the user passes command line arguments to your app, they'll show up in the
<a class="link" href="BApplication.html#BApplication_ArgvReceived" title="ArgvReceived()"><code class="methodname">ArgvReceived()</code></a>
hook function.</p></td></tr><tr><td><a href="#simplemain.new"><span class="callout"><img src="./images/callouts/2.png" alt="2" /></span></a> </td><td><p>Why no pointer assignment? The constructor automatically assigns the object to
<a class="link" href="BApplication.html#BApplication_be_app" title="be_app"><code class="varname">be_app</code></a>, so you don't have
to assign it yourself.</p></td></tr><tr><td><a href="#simplemain.sig"><span class="callout"><img src="./images/callouts/3.png" alt="3" /></span></a> </td><td><p>The string passed to the constructor sets the application's signature. This is a
precautionary measure it's better to add the signature as a resource than to define it
here (a resource signature overrides the constructor signature). Use the
<span class="application">FileTypes</span> app to set the signature as a resource.</p></td></tr><tr><td><a href="#simplemain.run"><span class="callout"><img src="./images/callouts/4.png" alt="4" /></span></a> </td><td><p>As explained in the <a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a> class,
<a class="link" href="BApplication.html#BApplication_Run" title="Run(), Quit()"><code class="methodname">Run()</code></a>
is almost always called from the same thread in which you construct the
<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a> object. (More
accurately, the constructor locks the object, and
<a class="link" href="BApplication.html#BApplication_Run" title="Run(), Quit()"><code class="methodname">Run()</code></a> unlocks it. Since
locks are scoped to threads, the easiest thing to do is to construct and
<a class="link" href="BApplication.html#BApplication_Run" title="Run(), Quit()"><code class="methodname">Run()</code></a> in the same thread.)</p></td></tr></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_Overview_Application_Messages"></a>Application Messages</h3></div></div></div><p>After you tell your <a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a> to run,
its message loop begins to receive messages. In general, the messages are
handled in the expected fashion: They show up in <a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>'s <a class="link" href="BApplication.html#BApplication_MessageReceived" title="MessageReceived()"><code class="methodname">MessageReceived()</code></a>
function (or that of a designated <a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a>; for more on how
messages are dispatched to handlers, see
("<a class="xref" href="TheApplicationKit_Messaging.html#TheApplicationKit_Messaging_FromLooperToHandler" title="From Looper to Handler">From Looper to Handler</a>").</p><p>But <a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>
also recognizes a set of application messages that it handles by invoking
corresponding hook functions. The hook functions are invoked by <a class="link" href="BApplication.html#BApplication_DispatchMessage" title="DispatchMessage()"><code class="methodname">DispatchMessage()</code></a>
so the application messages never show up in <a class="link" href="BApplication.html#BApplication_MessageReceived" title="MessageReceived()"><code class="methodname">MessageReceived()</code></a>.</p><p>Overriding the hook functions that correspond to the application messages
is an important part of the implementation of a <a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a> subclass.</p><p>In the table below, the application messages (identified by their command
constants) are listed in roughly the order your <a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a> can
expect to receive them.</p><div class="informaltable"><table border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Command Constant</th><th align="left">Hook function</th><th align="left">Description</th></tr></thead><tbody><tr><td align="left"><a class="link" href="TheApplicationKit_MessageConstants.html#B_ARGV_RECEIVED" title="B_ARGV_RECEIVED"><code class="constant">B_ARGV_RECEIVED</code></a></td><td align="left"><a class="link" href="BApplication.html#BApplication_ArgvReceived" title="ArgvReceived()"><code class="methodname">ArgvReceived()</code></a></td><td align="left">Command line arguments are delivered through this message.</td></tr><tr><td align="left"><a class="link" href="TheApplicationKit_MessageConstants.html#B_REFS_RECEIVED" title="B_REFS_RECEIVED"><code class="constant">B_REFS_RECEIVED</code></a></td><td align="left"><a class="link" href="BApplication.html#BApplication_RefsReceived" title="RefsReceived()"><code class="methodname">RefsReceived()</code></a></td><td align="left">Files (<span class="type">entry_ref</span>s) that are dropped on your app's icon,
or that are double-clicked to launch your app are delivered through this
message.</td></tr><tr><td align="left"><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></td><td align="left"><a class="link" href="BApplication.html#BApplication_ReadyToRun" title="ReadyToRun()"><code class="methodname">ReadyToRun()</code></a></td><td align="left">Invoked from within <a class="link" href="BApplication.html#BApplication_Run" title="Run(), Quit()"><code class="methodname">Run()</code></a>, the
application has finished configuring itself and is ready to go. If you
haven't already created and displayed an initial window, you should do so
here.</td></tr><tr><td align="left"><a class="link" href="TheApplicationKit_MessageConstants.html#B_APP_ACTIVATED" title="B_APP_ACTIVATED"><code class="constant">B_APP_ACTIVATED</code></a></td><td align="left"><a class="link" href="BApplication.html#BApplication_AppActivated" title="AppActivated()"><code class="methodname">AppActivated()</code></a></td><td align="left">The application has just become the active application, or has relinquished that status.</td></tr><tr><td align="left"><a class="link" href="TheApplicationKit_MessageConstants.html#B_PULSE" title="B_PULSE"><code class="constant">B_PULSE</code></a></td><td align="left"><a class="link" href="BApplication.html#BApplication_Pulse" title="Pulse()"><code class="methodname">Pulse()</code></a></td><td align="left">If requested, pulse messages are sent at regular intervals by the system.</td></tr><tr><td align="left"><a class="link" href="TheApplicationKit_MessageConstants.html#B_ABOUT_REQUESTED" title="B_ABOUT_REQUESTED"><code class="constant">B_ABOUT_REQUESTED</code></a></td><td align="left"><a class="link" href="BApplication.html#BApplication_AboutRequested" title="AboutRequested()"><code class="methodname">AboutRequested()</code></a></td><td align="left">The user wants to see the app's About… box.</td></tr></tbody></table></div><p>The protocols for the application messages are described in
the "<a class="xref" href="TheApplicationKit_MessageConstants.html" title="Message Constants">Message Constants</a>"
section of this chapter.</p><p>For more information on the details of when and why the hook functions are invoked, see
the individual function descriptions.</p><p>A <a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>
can also receive the
<a class="link" href="TheApplicationKit_MessageConstants.html#B_QUIT_REQUESTED" title="B_QUIT_REQUESTED"><code class="constant">B_QUIT_REQUESTED</code></a>
looper message. As explained in
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a>,
<a class="link" href="TheApplicationKit_MessageConstants.html#B_QUIT_REQUESTED" title="B_QUIT_REQUESTED"><code class="constant">B_QUIT_REQUESTED</code></a> causes
<code class="methodname">Quit()</code> to be called, contingent on the value
returned by the
<code class="methodname">QuitRequested</code>()
hook function. However,
<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>'s
implementation of
<a class="link" href="BApplication.html#BApplication_Quit"><code class="methodname">Quit()</code></a> is
different from
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a>'s version. Don't
miss it.</p></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="id411493"></a>Other Topics</h3></div></div></div><dl class="variablelist"><dt><span class="term">Locking.</span></dt><dd><p>Like a <a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a>, a
<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>
must be locked before calling certain protected functions. The <a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a> locking
mechanism is inherited without modification from <a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a>.</p></dd><dt><span class="term">FileTypes settings.</span></dt><dd><p>The <a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>
object represents your application at run-time. However, some of the
characteristics of your application, whether it can be launched more than
once, the file types it can open, its icon are not run-time decisions.</p></dd></dl></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="TheApplicationKit_Scripting.html">Scripting</a>  Up: <a href="TheApplicationKit_Overview.html">The Application Kit</a>  Next: <a href="BClipboard_Overview.html">BClipboard</a> </div><div id="footerB"><div id="footerBL"><a href="TheApplicationKit_Scripting.html" title="Scripting"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheApplicationKit_Overview.html" title="The Application Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="BClipboard_Overview.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