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

141 lines
16 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 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_Overview.html" title="The Interface Kit" /><link rel="prev" href="BMenuItem_Overview.html" title="BMenuItem" /><link rel="next" href="BPicture_Overview.html" title="BPicture" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BMenuItem_Overview.html" title="BMenuItem"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheInterfaceKit_Overview.html" title="The Interface Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="BPicture_Overview.html" title="BPicture"><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 Interface Kit</div></div><div id="headerB">Prev: <a href="BMenuItem_Overview.html">BMenuItem</a>  Up: <a href="TheInterfaceKit_Overview.html">The Interface Kit</a>  Next: <a href="BPicture_Overview.html">BPicture</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="BOutlineListView_Overview"></a>BOutlineListView</h2></div></div></div><a id="id551366" class="indexterm"></a><p>
A <a class="link" href="BOutlineListView.html" title="BOutlineListView"><code class="classname">BOutlineListView</code></a>
displays a list of items that can be structured like
an outline, with items grouped under other items. The levels of the
outline are indicated by successive levels of indentation.
</p><div class="mediaobject"><img src="./images/TheInterfaceKit/outlinelist.png" alt="Outline ListView" /></div><p>
The outline list view shown above was created using the following code:
</p><pre class="programlisting example cpp"><span class="type">BOutlineListView *</span><code class="varname">outline</code>;
<span class="type">BListItem *</span><code class="varname">region</code>;
<span class="type">BListItem *</span><code class="varname">state</code>;
<code class="methodname">SetViewColor</code>(216,216,216,0);
<code class="varname">r</code> = <code class="methodname">Bounds</code>();
<code class="varname">r</code>.<code class="methodname">InsetBy</code>(5,5);
<code class="varname">r</code>.<code class="varname">right</code> -= 16;
<code class="varname">r</code>.<code class="varname">top</code> += 20;
<code class="varname">outline</code> = new <code class="classname">BOutlineListView</code>(<code class="varname">r</code>, "cities_list",
<code class="constant">B_MULTIPLE_SELECTION_LIST</code>);</pre><p>
First, the <a class="link" href="BOutlineListView.html" title="BOutlineListView"><code class="classname">BOutlineListView</code></a>
is created, with a rectangle computed by
insetting from the parent view's bounds rectangle. The
<code class="constant">B_MULTIPLE_SELECTION_LIST</code> flag is specified to indicate that the user
should be allowed to choose more than one item in the list.
</p><pre class="programlisting example cpp"><code class="varname">region</code> = new <code class="classname">BStringItem</code>("United States of America")
<code class="varname">outline</code>-&gt;<code class="methodname">AddItem</code>(<code class="varname">region</code>);</pre><p>
This creates a new item in level 0 (the "region" level).
</p><p>
The United States is then divided into states, which comprise level 1 of
the outline list. This line of code adds California to the list, placing
it "under" the region (United States of America):
</p><pre class="programlisting example cpp"><code class="varname">state</code> = new <code class="classname">BStringItem</code>("California")
<code class="varname">outline</code>-&gt;<code class="methodname">AddUnder</code>(<code class="varname">state</code>, <code class="varname">region</code>);</pre><p>
a pointer to the new item for California is saved in the variable <code class="varname">state</code>.
</p><pre class="programlisting example cpp"><code class="varname">outline</code>-&gt;<code class="methodname">AddUnder</code>(new <code class="classname">BStringItem</code>("Menlo Park"), <code class="varname">state</code>);
<code class="varname">outline</code>-&gt;<code class="methodname">AddUnder</code>(new <code class="classname">BStringItem</code>("Los Angeles"), <code class="varname">state</code>);</pre><p>
California is then further divided into cities: Menlo Park and Los
Angeles, which reside at level 2 of our outline list. These are inserted
under the California item by specifying the pointer to that item
(locality) when calling
<a class="link" href="BOutlineListView.html#BOutlineListView_AddUnder"><code class="methodname">AddUnder()</code></a>.
</p><p>
This process is repeated for New York state, which has three cities
available in our list:
</p><pre class="programlisting example cpp"><code class="varname">locality</code> = new <code class="classname">BStringItem</code>("New York")
<code class="varname">outline</code>-&gt;<code class="methodname">AddUnder</code>(<code class="varname">locality</code>, <code class="varname">region</code>);
<code class="varname">outline</code>-&gt;<code class="methodname">AddUnder</code>(new <code class="classname">BStringItem</code>("Albany"), <code class="varname">locality</code>);
<code class="varname">outline</code>-&gt;<code class="methodname">AddUnder</code>(new <code class="classname">BStringItem</code>("Buffalo"), <code class="varname">locality</code>);
<code class="varname">outline</code>-&gt;<code class="methodname">AddUnder</code>(new <code class="classname">BStringItem</code>("New York City"), <code class="varname">locality</code>);</pre><p>
Then the Europe region is added (in level 0), and the nations of France,
Germany, and Italy are added as localities (level 1). Each of those three
localities has cities, which are added into level 2.
</p><pre class="programlisting example cpp"><code class="varname">region</code> = new <code class="classname">BStringItem</code>("Europe")
<code class="varname">outline</code>-&gt;<code class="methodname">AddItem</code>(<code class="varname">region</code>);
<code class="varname">locality</code> = new <code class="classname">BStringItem</code>("France")
<code class="varname">outline</code>-&gt;<code class="methodname">AddUnder</code>(<code class="varname">locality</code>, <code class="varname">region</code>);
<code class="varname">outline</code>-&gt;<code class="methodname">AddUnder</code>(new <code class="classname">BStringItem</code>("Paris"), <code class="varname">locality</code>);
<code class="varname">locality</code> = new <code class="classname">BStringItem</code>("Germany")
<code class="varname">outline</code>-&gt;<code class="methodname">AddUnder</code>(<code class="varname">locality</code>, <code class="varname">region</code>);
<code class="varname">outline</code>-&gt;<code class="methodname">AddUnder</code>(new <code class="classname">BStringItem</code>("Berlin"), <code class="varname">locality</code>);
<code class="varname">outline</code>-&gt;<code class="methodname">AddUnder</code>(new <code class="classname">BStringItem</code>("Hamburg"), <code class="varname">locality</code>);
<code class="varname">locality</code> = new <code class="classname">BStringItem</code>("Italy")
<code class="varname">outline</code>-&gt;<code class="methodname">AddUnder</code>(<code class="varname">locality</code>, <code class="varname">region</code>);
<code class="varname">outline</code>-&gt;<code class="methodname">AddUnder</code>(new <code class="classname">BStringItem</code>("Milan"), <code class="varname">locality</code>);
<code class="varname">outline</code>-&gt;<code class="methodname">AddUnder</code>(new <code class="classname">BStringItem</code>("Rome"), <code class="varname">locality</code>);</pre><p>
Once the list has been completely constructed, a
<a class="link" href="BScrollView.html" title="BScrollView"><code class="classname">BScrollView</code></a> is created
to contain the outline list view, and is then added to the list. See the
<a class="link" href="BScrollView.html" title="BScrollView"><code class="classname">BScrollView</code></a>
class for details on how this works:
</p><pre class="programlisting example cpp"><code class="methodname">AddChild</code>(new <code class="classname">BScrollView</code>("scroll_cities", <code class="varname">outline</code>,
<code class="constant">B_FOLLOW_LEFT</code>|<code class="constant">B_FOLLOW_TOP</code>, 0, <code class="constant">false</code>, <code class="constant">true</code>));</pre><p>
Finally, a <a class="link" href="BStringView.html" title="BStringView"><code class="classname">BStringView</code></a>
is created to label the list with a prompt
indicating that you should "Select the Cities to Attack:".
</p><pre class="programlisting example cpp"><code class="varname">r</code> = <code class="methodname">Bounds</code>();
<code class="varname">r</code>.<code class="methodname">InsetBy</code>(5,5);
<code class="varname">r</code>.<code class="varname">bottom</code> = <code class="varname">r</code>.<code class="varname">top</code> + 12;
<code class="methodname">AddChild</code>(new <code class="classname">BStringView</code>(<code class="varname">r</code>, "message_string",
"Select the Cities to Attack:"));</pre><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="id552005"></a>Outline Structure</h3></div></div></div><p>
If an item has other items under it—that is, if the immediately
following item in the list is at a deeper level of the outline—it
is a superitem; the items grouped under it are its subitems. Superitems
are marked by a triangular icon or latch, in the usual interface for
hypertext lists.
</p><p>
The user can collapse or expand sections of the outline by manipulating
the latch. When a section is collapsed, only the superitem for that
section is visible (and the latch points to the superitem). All items
that follow the superitem are hidden, up to the next item that's not at a
deeper outline level. When a section is expanded, subitems are visible
(and the latch points downward).
</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="id552031"></a>Inherited Functions</h3></div></div></div><p>
The <a class="link" href="BOutlineListView.html" title="BOutlineListView"><code class="classname">BOutlineListView</code></a>
class inherits most of its functionality from the
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
class. However, inherited functions are concerned only with the
expanded sections of the list, not with sections that are hidden because
they're collapsed. If an inherited function returns an index or takes an
index as an argument, the index counts just the items that are shown
on-screen (or could be shown on-screen if they were scrolled into the
visible region of the view).
<a class="link" href="BListView.html#BListView_DoForEach" title="DoForEach()"><code class="methodname">DoForEach()</code></a>
skips items that can't be displayed.
<a class="link" href="BListView.html#BListView_CountItems" title="CountItems()"><code class="methodname">CountItems()</code></a>
counts items only in the expanded sections of the list.
</p><p>
However, the functions that the
<a class="link" href="BOutlineListView.html" title="BOutlineListView"><code class="classname">BOutlineListView</code></a>
class itself defines are concerned with all sections of the list, expanded or collapsed. For its
functions, an index counts all items in the list, whether visible or not.
</p><p>
The class defines some functions that match those it inherits, but its
versions prefix <code class="methodname">FullList…()</code> to the function name and don't ignore any
items. For example,
<a class="link" href="BOutlineListView.html#BOutlineListView_FullListCountItems" title="FullListCountItems(), FullListCurrentSelection(), FullListFirstItem() , FullListLastItem(), FullListIndexOf(), FullListItemAt(), FullListHasItem(), FullListIsEmpty(), FullListDoForEach(), FullListSortItems()"><code class="methodname">FullListCountItems()</code></a>
counts every item in the list and
<a class="link" href="BOutlineListView.html#BOutlineListView_FullListDoForEach"><code class="methodname">FullListDoForEach()</code></a>
doesn't skip items in collapsed sections.
</p><p>
In some cases, <a class="link" href="BOutlineListView.html" title="BOutlineListView"><code class="classname">BOutlineListView</code></a>
simply overrides an inherited function
without adding the <code class="methodname">FullList…()</code> prefix. You should always use the
<a class="link" href="BOutlineListView.html" title="BOutlineListView"><code class="classname">BOutlineListView</code></a>
versions of these functions, not the <a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a> versions.
For example, <a class="link" href="BOutlineListView.html" title="BOutlineListView"><code class="classname">BOutlineListView</code></a>'s
version of
<a class="link" href="BOutlineListView.html#BOutlineListView_MakeEmpty" title="MakeEmpty()"><code class="methodname">MakeEmpty()</code></a> truly empties the
list; <a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>'s
version would remove items from the screen, but not from the real list.
</p></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BMenuItem_Overview.html">BMenuItem</a>  Up: <a href="TheInterfaceKit_Overview.html">The Interface Kit</a>  Next: <a href="BPicture_Overview.html">BPicture</a> </div><div id="footerB"><div id="footerBL"><a href="BMenuItem_Overview.html" title="BMenuItem"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheInterfaceKit_Overview.html" title="The Interface Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="BPicture_Overview.html" title="BPicture"><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