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

265 lines
46 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 Interface 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="TheInterfaceKit.html" title="The Interface Kit" /><link rel="prev" href="BShapeIterator.html" title="BShapeIterator" /><link rel="next" href="BSlider.html" title="BSlider" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BShapeIterator.html" title="BShapeIterator"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheInterfaceKit.html" title="The Interface Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="BSlider.html" title="BSlider"><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 Interface Kit</div></div><div id="headerB">Prev: <a href="BShapeIterator.html">BShapeIterator</a>  Up: <a href="TheInterfaceKit.html">The Interface Kit</a>  Next: <a href="BSlider.html">BSlider</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="BShelf"></a>BShelf</h2></div></div></div><a id="id1029540" 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="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a></td></tr><tr><td>Mix-in Classes:</td><td>–</td></tr><tr><td>Declared In:</td><td><code class="filename">interface/Shelf.h</code></td></tr><tr><td>Library:</td><td><code class="filename">libbe.so</code></td></tr><tr><td>Allocation:</td><td>Constructor only</td></tr></tbody></table></td><td>
<a class="link overview" href="BShelf_Overview.html" title="BShelf">Class Overview</a>
<div class="toc"><ul><li><span class="section"><a href="BShelf.html#BShelf_ConstructorDestructor">Constructor and Destructor</a></span></li><li><span class="section"><a href="BShelf.html#BShelf_HookFunctions">Hook Functions</a></span></li><li><span class="section"><a href="BShelf.html#BShelf_MemberFunctions">Member Functions</a></span></li><li><span class="section"><a href="BShelf.html#BShelf_StaticFunctions">Static Functions</a></span></li><li><span class="section"><a href="BShelf.html#BShelf_ScriptingSupport">Scripting Support</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="BShelf_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="BShelf_Constructor"></a>BShelf()</h4></div></div></div><div class="synopsisgroup">
<code class="constructorsynopsis cpp"><span class="methodname">BShelf</span>(<span class="methodparam"><span class="type"><a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>* </span><span class="parameter">view</span></span>,<br />       <span class="methodparam"><span class="type">bool </span><span class="parameter">allowsDragging</span><span class="initializer"> = <span class="constant">true</span></span></span>,<br />       <span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">name</span><span class="initializer"> = <span class="constant">NULL</span></span></span>);</code>
<code class="constructorsynopsis cpp"><span class="methodname">BShelf</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">entry_ref* </span><span class="parameter">ref</span></span>,<br />       <span class="methodparam"><span class="type"><a class="link" href="BView.html" title="BView"><code class="classname">BView</code>*</a> </span><span class="parameter">view</span></span>,<br />       <span class="methodparam"><span class="type">bool </span><span class="parameter">allowsDragging</span><span class="initializer"> = <span class="constant">true</span></span></span>,<br />       <span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">name</span><span class="initializer"> = <span class="constant">NULL</span></span></span>);</code>
<code class="constructorsynopsis cpp"><span class="methodname">BShelf</span>(<span class="methodparam"><span class="type"><a class="link" href="BDataIO.html" title="BDataIO"><code class="classname">BDataIO</code></a>* </span><span class="parameter">stream</span></span>,<br />       <span class="methodparam"><span class="type"><a class="link" href="BView.html" title="BView"><code class="classname">BView</code>*</a> </span><span class="parameter">view</span></span>,<br />       <span class="methodparam"><span class="type">bool </span><span class="parameter">allowsDragging</span><span class="initializer"> = <span class="constant">true</span></span></span>,<br />       <span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">name</span><span class="initializer"> = <span class="constant">NULL</span></span></span>);</code>
</div><p>
Initializes the <code class="classname">BShelf</code> object so that it serves a
container view. The versions that accept an <span class="type">entry_ref</span> or <a class="link" href="BDataIO.html" title="BDataIO"><code class="classname">BDataIO</code></a> argument prime the
shelf so that it (initially) contains the replicants that are archived in
the referred to file or stream using
<a class="link" href="BShelf.html#BShelf_Save" title="Save(), SaveLocation(), SetSaveLocation(), SetDirty(), IsDirty()"><code class="methodname">Save()</code></a>. The
<code class="parameter">ref</code>/<code class="parameter">stream</code> argument is also
used as the archival repository when you tell your
<code class="classname">BShelf</code> to
<a class="link" href="BShelf.html#BShelf_Save" title="Save(), SaveLocation(), SetSaveLocation(), SetDirty(), IsDirty()"><code class="methodname">Save()</code></a> itself.
</p><p>
If the <code class="parameter">allowsDragging</code> flag is <code class="constant">true</code>, the user will be able to drag
replicant view within the container's bounds. If the flag is <code class="constant">false</code>,
dropped views stay where they're first put.
</p><p>
<code class="parameter">name</code> is the <code class="classname">BShelf</code>'s handler name. The name can be important: It's
compared to the replicant's <code class="varname">shelf_type</code> field, as explained in
<a class="link" href="BShelf.html#BShelf_AddReplicant" title="AddReplicant()"><code class="methodname">AddReplicant()</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>There's an archive-accepting version of the <code class="classname">BShelf</code> constructor declared
in <code class="filename">Shelf.h</code>. Don't use it.</p></div></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="BShelf_Destructor"></a>~BShelf()</h4></div></div></div><code class="destructorsynopsis cpp"><span class="modifier">virtual </span><span class="methodname">~BShelf</span>();</code><p>
The destructor calls <a class="link" href="BShelf.html#BShelf_Save" title="Save(), SaveLocation(), SetSaveLocation(), SetDirty(), IsDirty()"><code class="methodname">Save()</code></a>,
and then frees the object.
</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="BShelf_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="BShelf_AdjustReplicantBy"></a>AdjustReplicantBy()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type"><a class="link" href="BPoint.html" title="BPoint"><code class="classname">BPoint</code></a> </span><span class="methodname">AdjustReplicantBy</span>(<span class="methodparam"><span class="type"><a class="link" href="BRect.html" title="BRect"><code class="classname">BRect</code></a> </span><span class="parameter">destRect</span></span>,<br />                                 <span class="methodparam"><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* </span><span class="parameter">archive</span></span>) <span class="modifier">const</span>;</code><p>
This hook function is invoked automatically when a replicant is dropped
on the <code class="classname">BShelf</code>. It gives the shelf a chance to fine-tune the placement of
the <code class="classname">BDragger</code> and its target view.
</p><p>
<code class="parameter">destRect</code> is the rectangle (in the container view's coordinates) in which
the dropped replicant is about to be drawn. Exactly what the rectangle
means depends on the relationship between the dragger and its target:
</p><ul class="itemizedlist"><li><p>
If the dragger is the target's parent, then <code class="parameter">destRect</code> encloses the
<a class="link" href="BDragger.html" title="BDragger"><code class="classname">BDragger</code></a>'s frame.
</p></li><li><p>
Otherwise (if the target is the parent, or if the two views are
siblings), <code class="parameter">destRect</code> encloses the target's frame. Note that in the case
of siblings, the <a class="link" href="BDragger.html" title="BDragger"><code class="classname">BDragger</code></a>'s
frame isn't included in the rectangle.
</p></li></ul><p>
<code class="parameter">archive</code> is the archive message that was dropped on the shelf.
</p><p>
The <a class="link" href="BPoint.html" title="BPoint"><code class="classname">BPoint</code></a> that this
function returns offsets (is added into) the
location of the replicant. If you don't want to move the replicant,
return <a class="link" href="BPoint.html" title="BPoint"><code class="classname">BPoint</code></a>(0, 0).
Note that the <a class="link" href="BDragger.html" title="BDragger"><code class="classname">BDragger</code></a>
and the view are both moved by this offset, even in the case where
<code class="parameter">destRect</code> doesn't include the
dragger's frame.
</p><p>
This function ignores the "allows dragging" flag given in the <code class="classname">BShelf</code>
constructor. In other words, you can adjust a replicant's placement
through this function even if the <code class="classname">BShelf</code> doesn't otherwise allow dragging.
</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="BShelf_CanAcceptReplicantMessage"></a><a id="BShelf_CanAcceptReplicantView"></a>
CanAcceptReplicantMessage(), CanAcceptReplicantView()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">bool </span><span class="methodname">CanAcceptReplicantMessage</span>(<span class="methodparam"><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* </span><span class="parameter">archive</span></span>) <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">bool </span><span class="methodname">CanAcceptReplicantView</span>(<span class="methodparam"><span class="type"><a class="link" href="BRect.html" title="BRect"><code class="classname">BRect</code></a> </span><span class="parameter">destRect</span></span>,<br />                                    <span class="methodparam"><span class="type"><a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>* </span><span class="parameter">view</span></span>,<br />                                    <span class="methodparam"><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* </span><span class="parameter">archive</span></span>) <span class="modifier">const</span>;</code><p>
These hook functions are invoked from within
<a class="link" href="BShelf.html#BShelf_AddReplicant" title="AddReplicant()"><code class="methodname">AddReplicant()</code></a> whenever a
replicant is dropped on the <code class="classname">BShelf</code>. You can implement these functions to
reject unwanted replicants.
</p><p>
<code class="methodname">CanAcceptReplicantMessage()</code> is called first; the argument is the archive
that (should) contain the replicated view. If you don't like the look of
the archive, return <code class="constant">false</code> and the message will be thrown away. Note that
you shouldn't return <code class="constant">false</code> if the archive doesn't seem to be in the
correct form (specifically, if it doesn't contain any views). Rejection
of such messages is handled more elegantly (and after this function is
invoked) by the <a class="link" href="BShelf.html#BShelf_AddReplicant" title="AddReplicant()"><code class="methodname">AddReplicant()</code></a> function.
</p><p>
<code class="methodname">CanAcceptReplicantView()</code> is invoked after the message has been
unarchived. <code class="parameter">destRect</code> is the rectangle that the replicant will occupy in
the <code class="classname">BShelf</code>'s container view's coordinates. <code class="parameter">view</code> is the replicated view
itself. <code class="parameter">archive</code> is the original message.
</p><p>
If either function returns <code class="constant">false</code>, the replicant is rejected and the
message is thrown away (it isn't passed on to another handler). A return
of <code class="constant">true</code> does the obvious thing.
</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="BShelf_ReplicantDeleted"></a>ReplicantDeleted()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">ReplicantDeleted</span>(<span class="methodparam"><span class="type">int32 </span><span class="parameter">index</span></span>,<br />                              <span class="methodparam"><span class="modifier">const </span><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* </span><span class="parameter">archive</span></span>,<br />                              <span class="methodparam"><span class="modifier">const </span><span class="type"><a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>* </span><span class="parameter">view</span></span>);</code><p>
This hook function is invoked from within
<a class="link" href="BShelf.html#BShelf_DeleteReplicant" title="DeleteReplicant()"><code class="methodname">DeleteReplicant()</code></a> to indicate a
replicant has been deleted from the <code class="classname">BShelf</code>. It is called after the view
has been removed from the shelf with the <code class="parameter">index</code> of the replicant in the
shelf, its <code class="parameter">archive</code> message, and the detached <code class="parameter">view</code>.
</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="BShelf_MemberFunctions"></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="BShelf_AddReplicant"></a>AddReplicant()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">AddReplicant</span>(<span class="methodparam"><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* </span><span class="parameter">archive</span></span>,<br />                      <span class="methodparam"><span class="type"><a class="link" href="BPoint.html" title="BPoint"><code class="classname">BPoint</code></a> </span><span class="parameter">point</span></span>);</code><p>
This function is invoked automatically when a replicant is dropped on the
<code class="classname">BShelf</code>. The <code class="parameter">archive</code> message contains the
<a class="link" href="BDragger.html" title="BDragger"><code class="classname">BDragger</code></a> archive that's being
dropped; <code class="parameter">point</code> is where, within the container view's bounds, the message
was dropped. The function goes through these steps to reject and adjust
the replicant:
</p><ul class="itemizedlist"><li><p>First, it invokes the
<a class="link" href="BShelf.html#BShelf_CanAcceptReplicantMessage" title="CanAcceptReplicantMessage(), CanAcceptReplicantView()"><code class="methodname">CanAcceptReplicantMessage()</code></a>
hook function. If the hook returns <code class="constant">false</code>, then
<code class="methodname">AddReplicant()</code> doesn't add the replicant.</p></li><li><p>Next, it looks for a <code class="varname">shelf_type</code> string field in the
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>. If it
finds one and the value of the field doesn't match the <code class="classname">BShelf</code>'s name,
the replicant is rejected.</p></li><li><p>If type enforcement is <code class="constant">true</code> (see
<a class="link" href="BShelf.html#BShelf_SetTypeEnforced" title="SetTypeEnforced() , IsTypeEnforced()"><code class="methodname">SetTypeEnforced()</code></a>)
and the shelf has a name, then the <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>
must have a <code class="varname">shelf_type</code> string and this
string must match the shelf name. Otherwise, the replicant is rejected.</p><p>There's no specific API for adding the <code class="varname">shelf_type</code> field to a view.
If you want to configure your views to accept only certain <code class="classname">BShelf</code>
objects, you have to add the field directly as part of the view's
<a class="link" href="BView.html#BView_Archive" title="Archive()"><code class="methodname">Archive()</code></a>
implementation.</p></li><li><p>The archive message is then unarchived (the replicant is
instantiated). If the archive doesn't contain a
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>, the message is
passed on to another handler (<code class="constant">B_DISPATCH_MESSAGE</code> is returned).</p></li><li><p>
<a class="link" href="BShelf.html#BShelf_CanAcceptReplicantView"><code class="methodname">CanAcceptReplicantView()</code></a>
hook function is called next (with a return
of <code class="constant">false</code> meaning rejection).
</p></li><li><p>
Finally, <a class="link" href="BShelf.html#BShelf_AdjustReplicantBy" title="AdjustReplicantBy()"><code class="methodname">AdjustReplicantBy()</code></a>
is called, and the replicant is drawn in the container view.
</p></li></ul><p>
Except in the case of a no-view archive, <code class="methodname">AddReplicant()</code> returns
<code class="constant">B_SKIP_MESSAGE</code>.
</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>If you want the ensure that the replicant is unique within the
container view, add a "be:unique_replicant" entry of type <code class="constant">B_BOOL_TYPE</code> to
the archive with the value <code class="constant">true</code>.</p></div></div></div><p>
It's possible to archive a <code class="classname">BDragger</code> and call this function yourself,
although that's not its expected use.
</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="BShelf_Archive"></a>Archive()</h4></div></div></div><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><code class="methodname">Archive()</code> is currently a no-op that
returns <code class="constant">B_ERROR</code>. You can't archive
a <code class="classname">BShelf</code>. If you want to archive something, archive the shelf's contents
by calling <a class="link" href="BShelf.html#BShelf_Save" title="Save(), SaveLocation(), SetSaveLocation(), SetDirty(), IsDirty()"><code class="methodname">Save()</code></a>.</p></div></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="BShelf_CountReplicants"></a>CountReplicants()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">int32 </span><span class="methodname">CountReplicants</span>() <span class="modifier">const</span>;</code><p>
Returns the number of replicants attached to the shelf.
</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="BShelf_DeleteReplicant"></a>DeleteReplicant()</h4></div></div></div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">DeleteReplicant</span>(<span class="methodparam"><span class="type"><a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>* </span><span class="parameter">replicant_view</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">DeleteReplicant</span>(<span class="methodparam"><span class="modifier">const </span><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* </span><span class="parameter">archive</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">DeleteReplicant</span>(<span class="methodparam"><span class="type">uint32 </span><span class="parameter">uid</span></span>);</code>
</div><p>
Removes the specified replicant from the shelf. It identifies replicants
by either a view, a replicant message, or a unique id.
</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="BShelf_IndexOf"></a><a id="BShelf_ReplicantAt"></a>
IndexOf(), ReplicantAt()</h4></div></div></div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">int32 </span><span class="methodname">IndexOf</span>(<span class="methodparam"><span class="modifier">const </span><span class="type"><a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>* </span><span class="parameter">replicant_view</span></span>) <span class="modifier">const</span>;</code>
<code class="methodsynopsis cpp"><span class="type">int32 </span><span class="methodname">IndexOf</span>(<span class="methodparam"><span class="modifier">const </span><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* </span><span class="parameter">archive</span></span>) <span class="modifier">const</span>;</code>
<code class="methodsynopsis cpp"><span class="type">int32 </span><span class="methodname">IndexOf</span>(<span class="methodparam"><span class="type">uint32 </span><span class="parameter">uid</span></span>) <span class="modifier">const</span>;</code>
</div><code class="methodsynopsis cpp"><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* </span><span class="methodname">ReplicantAt</span>(<span class="methodparam"><span class="type">int32 </span><span class="parameter">index</span></span>,<br />                      <span class="methodparam"><span class="type"><a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>** </span><span class="parameter">view</span><span class="initializer"> = <span class="constant">NULL</span></span></span>,<br />                      <span class="methodparam"><span class="type">uint32* </span><span class="parameter">view</span><span class="initializer"> = <span class="constant">NULL</span></span></span>,<br />                      <span class="methodparam"><span class="type">status_t </span><span class="parameter">err</span><span class="initializer"> = <span class="constant">NULL</span></span></span>) <span class="modifier">const</span>;</code><p>
<code class="methodname">IndexOf()</code> returns the index of a specified replicant in the shelf, or -1
if no such replicant exists. It accepts either a view, a replicant
message, or a unique id as identifiers.
</p><p>
<code class="methodname">ReplicantAt()</code> returns information about a replicant in a shelf given its
<code class="parameter">index</code> (as returned by <code class="methodname">IndexOf()</code>). It returns the
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> archive of the
replicant or <code class="constant">NULL</code> if the index is invalid. It returns the <code class="parameter">view</code> of the
replicant as well as its <code class="parameter">uid</code>, if these parameters are non-<code class="constant">NULL</code>. It
returns an error message in <code class="parameter">err</code> if there was an error in initializing the
given replicant.
</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="BShelf_Save"></a><a id="BShelf_SaveLocation"></a>
<a id="BShelf_SetSaveLocation"></a>
<a id="BShelf_SetDirty"></a>
<a id="BShelf_IsDirty"></a>
Save(), SaveLocation(), SetSaveLocation(), SetDirty(), IsDirty()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">Save</span>();</code><code class="methodsynopsis cpp"><span class="type"><a class="link" href="BDataIO.html" title="BDataIO"><code class="classname">BDataIO</code></a>* </span><span class="methodname">SaveLocation</span>(<span class="methodparam"><span class="type">entry_ref* </span><span class="parameter">ref</span></span>) <span class="modifier">const</span>;</code><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetSaveLocation</span>(<span class="methodparam"><span class="type"><a class="link" href="BDataIO.html" title="BDataIO"><code class="classname">BDataIO</code></a>* </span><span class="parameter">data_io</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetSaveLocation</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">entry_ref* </span><span class="parameter">ref</span></span>);</code>
</div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">SetDirty</span>(<span class="methodparam"><span class="type">bool </span><span class="parameter">flag</span></span>);</code><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">IsDirty</span>();</code><p>
Writes the shelf's contents (the replicants that it contains) as an archive
to the <span class="type">entry_ref</span> or <a class="link" href="BDataIO.html" title="BDataIO"><code class="classname">BDataIO</code></a> object that was
specified in the constructor. You can also set the location where the shelf
is saved with <code class="methodname">SetSaveLocation()</code> and fetch it with
<code class="methodname">SaveLocation()</code>. The <span class="type">entry_ref</span> is
stored in <code class="parameter">ref</code> (if ref is
non-<code class="constant">NULL</code>) and the <a class="link" href="BDataIO.html" title="BDataIO"><code class="classname">BDataIO</code></a> the shelf will be
written to is returned. If the shelf will be written to an
<span class="type">entry_ref</span> that is not a <a class="link" href="BDataIO.html" title="BDataIO"><code class="classname">BDataIO</code></a>,
<code class="methodname">SaveLocation()</code> returns <code class="constant">NULL</code>.
</p><p>
By default, the save is only performed if the object's "dirty" flag is
set—in other words, if it has changed since it was last written.
You can force set the dirty flag by calling <code class="methodname">SetDirty()</code>.
</p><p>
<code class="methodname">IsDirty()</code> returns the current state of the "dirty" flag.
</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="BShelf_SetAllowsDragging"></a><a id="BShelf_AllowsDragging"></a>
SetAllowsDragging() , AllowsDragging()</h4></div></div></div><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">SetAllowsDragging</span>(<span class="methodparam"><span class="type">bool </span><span class="parameter">state</span></span>);</code><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">AllowsDragging</span>() <span class="modifier">const</span>;</code><p>
<code class="methodname">SetAllowsDragging()</code> determines whether the <code class="classname">BShelf</code> accepts replicants
dragged into the view by the user. <code class="methodname">AllowsDragging()</code> returns whether the
<code class="classname">BShelf</code> accepts replicants dragged by the user into the container view's
frame
</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="BShelf_SetAllowsZombies"></a><a id="BShelf_AllowsZombies"></a>
<a id="BShelf_SetDisplayZombies"></a>
<a id="BShelf_DisplaysZombies"></a>
SetAllowsZombies(), AllowsZombies(), SetDisplayZombies(),
DisplaysZombies()</h4></div></div></div><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">SetAllowsZombies</span>(<span class="methodparam"><span class="type">bool </span><span class="parameter">state</span></span>);</code><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">AllowsZombies</span>() <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">SetDisplaysZombies</span>(<span class="methodparam"><span class="type">bool </span><span class="parameter">state</span></span>);</code><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">DisplaysZombies</span>() <span class="modifier">const</span>;</code><p>
<code class="methodname">SetAllowsZombies()</code> determines whether the
<code class="classname">BShelf</code> accepts zombie views.
<code class="methodname">AllowsZombies()</code> returns whether the
<code class="classname">BShelf</code> accepts zombie views. A zombie view is one
whose associated executable cannot be located.
</p><p>
Similarly, <code class="methodname">SetDisplaysZombies()</code> determines whether
the <code class="classname">BShelf</code> displays zombie views and
<code class="methodname">DisplaysZombies()</code> returns whether the
<code class="classname">BShelf</code> displays zombie views.
</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="BShelf_SetTypeEnforced"></a><a id="BShelf_IsTypeEnforced"></a>
SetTypeEnforced() , IsTypeEnforced()</h4></div></div></div><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">SetTypeEnforced</span>(<span class="methodparam"><span class="type">bool </span><span class="parameter">state</span></span>);</code><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">IsTypeEnforced</span>() <span class="modifier">const</span>;</code><p>
These two methods set and return the type enforcement flag. When it is
<code class="constant">true</code>, the shelf compares its name to the <code class="varname">shelf_type</code> field of any
dropped messages. The replicant is accepted only if the two match. If the
dropped message does not have a <code class="varname">shelf_type</code> field, then it is rejected.
Type enforcement is <code class="constant">false</code> by default.
</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="BShelf_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="BShelf_Instantiate"></a>Instantiate()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">static </span><span class="type"><a class="link" href="BArchivable.html" title="BArchivable"><code class="classname">BArchivable</code></a>* </span><span class="methodname">Instantiate</span>(<span class="methodparam"><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* </span><span class="parameter">archive</span></span>);</code><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><code class="methodname">Instantiate()</code> is currently a no-op that
returns <code class="constant">NULL</code>. You can't archive a
<code class="classname">BShelf</code>. If you want to archive something, archive
the shelf's contents by calling
<a class="link" href="BShelf.html#BShelf_Save" title="Save(), SaveLocation(), SetSaveLocation(), SetDirty(), IsDirty()"><code class="methodname">Save()</code></a>.</p></div></div></div></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="BShelf_ScriptingSupport"></a>Scripting Support</h3></div></div></div><p>
The <code class="classname">BShelf</code> class implements the suite called "suite/vnd.Be-shelf"
consisting of the following message:
</p><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="BShelf_PropertyReplicant"></a>The Replicant Property</h4></div></div></div><p>
The "Replicant" property provides access to the replicants contained in a
<code class="classname">BShelf</code>. It also allows you to manipulate the replicants themselves by
forwarding certain messages to a "suite/vnd.Be-replicant" interface. This
interface consists of the following messages:
</p><div class="informaltable"><table border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Message</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 number of replicants in the shelf.</td></tr><tr><td align="left"><code class="constant">B_CREATE_PROPERTIES</code></td><td align="left"><code class="constant">B_DIRECT_SPECIFIER</code></td><td align="left">Adds the archived replicant in the
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>
"data" to the view at the
<a class="link" href="BPoint.html" title="BPoint"><code class="classname">BPoint</code></a> in "location."</td></tr><tr><td align="left"><code class="constant">B_DELETE_PROPERTY</code></td><td align="left"><code class="constant">B_INDEX_SPECIFIER</code>,
<code class="constant">B_REVERSE_INDEX_SPECIFIER</code>,
<code class="constant">B_NAME_SPECIFIER</code>,
<code class="constant">B_ID_SPECIFIER</code></td><td align="left">Removes the specified replicant from the shelf.</td></tr><tr><td align="left"><code class="constant">B_GET_PROPERTY</code></td><td align="left"><code class="constant">B_INDEX_SPECIFIER</code>,
<code class="constant">B_REVERSE_INDEX_SPECIFIER</code>,
<code class="constant">B_NAME_SPECIFIER</code>,
<code class="constant">B_ID_SPECIFIER</code></td><td align="left">Archives the specified replicant into a BMessage in "result."</td></tr><tr><td align="left">anything else</td><td align="left"><code class="constant">B_INDEX_SPECIFIER</code>,
<code class="constant">B_REVERSE_INDEX_SPECIFIER</code>,
<code class="constant">B_NAME_SPECIFIER</code>,
<code class="constant">B_ID_SPECIFIER</code></td><td align="left">Directs the scripting message to the replicant interface
"suite/vnd.Be-replicant" (described below), first popping the current
specifier off the stack.</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"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BShelf_PropertyID"></a>The ID Property</h4></div></div></div><p>
The replicant ID
</p><div class="informaltable"><table border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Message</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">Returns the replicant ID.</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"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BShelf_PropertyName"></a>The Name Property</h4></div></div></div><p>
The name of the replicant view
</p><div class="informaltable"><table border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Message</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">Returns the name of the replicant view.</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"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BShelf_PropertySignature"></a>The Signature Property</h4></div></div></div><p>
The replicant add-on MIME signature
</p><div class="informaltable"><table border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Message</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">Returns the signature of the add-on
containing the code for the replicant.</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"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BShelf_PropertySuites"></a>The Suites Property</h4></div></div></div><p>
The supported scripting suites
</p><div class="informaltable"><table border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Message</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">Returns "suite/vnd.Be-replicant" in
"suites" and a flattened
<a class="link" href="BPropertyInfo.html" title="BPropertyInfo"><code class="classname">BPropertyInfo</code></a>
describing the scripting suite in "messages."</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"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BShelf_PropertyView"></a>The View Property</h4></div></div></div><p>
Redirects messages to the replicant view
</p><div class="informaltable"><table border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Message</th><th align="left">Specifier</th><th align="left">Description</th></tr></thead><tbody><tr><td align="left">any</td><td align="left"><code class="constant">B_DIRECT_SPECIFIER</code></td><td align="left">Directs the scripting message to the replicant
view, first popping the current specifier off the specifier stack.</td></tr></tbody></table></div></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BShapeIterator.html">BShapeIterator</a>  Up: <a href="TheInterfaceKit.html">The Interface Kit</a>  Next: <a href="BSlider.html">BSlider</a> </div><div id="footerB"><div id="footerBL"><a href="BShapeIterator.html" title="BShapeIterator"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheInterfaceKit.html" title="The Interface Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="BSlider.html" title="BSlider"><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