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

157 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="BListItem_Overview.html" title="BListItem" /><link rel="next" href="BMenu_Overview.html" title="BMenu" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BListItem_Overview.html" title="BListItem"><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="BMenu_Overview.html" title="BMenu"><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="BListItem_Overview.html">BListItem</a>  Up: <a href="TheInterfaceKit_Overview.html">The Interface Kit</a>  Next: <a href="BMenu_Overview.html">BMenu</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="BListView_Overview"></a>BListView</h2></div></div></div><a id="id549808" class="indexterm"></a><p>
A <a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
displays a list of items the user can select and invoke. Each
item is a kind of <a class="link" href="BListItem.html" title="BListItem"><code class="classname">BListItem</code></a> object. The
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a> manages the layout of
the list and the interaction with the user; it leaves the display of each
item to the <a class="link" href="BListItem.html" title="BListItem"><code class="classname">BListItem</code></a>
objects. A <a class="link" href="BListItem.html" title="BListItem"><code class="classname">BListItem</code></a>
is not a view and draws only when called upon by the
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>.
</p><p>
The figure below depicts a window that contains a sample
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>.
</p><div class="mediaobject"><img src="./images/TheInterfaceKit/listview.png" alt="ListView" /></div><p>
A <a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
displays all items unindented at a single level. A derived class,
<a class="link" href="BOutlineListView.html" title="BOutlineListView"><code class="classname">BOutlineListView</code></a>,
can arrange items in an hierarchical outline.
</p><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="id549920"></a>Lists and List Views</h3></div></div></div><p>
This class is based on the
<a class="link" href="BList.html" title="BList"><code class="classname">BList</code></a> class
of the <a class="link" href="TheSupportKit.html" title="The Support Kit">Support Kit</a>.
It implements counterparts for all
<a class="link" href="BList.html" title="BList"><code class="classname">BList</code></a>
member functions, so you can treat a
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
object just like a
<a class="link" href="BList.html" title="BList"><code class="classname">BList</code></a>.
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
simply makes the list visible.
</p><p>
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
functions work identically to their
<a class="link" href="BList.html" title="BList"><code class="classname">BList</code></a>
counterparts, except for two things:
</p><ul class="itemizedlist"><li><p>
A <a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
assumes that the list contains pointers to
<a class="link" href="BListItem.html" title="BListItem"><code class="classname">BListItem</code></a>
objects, not <span class="type">void*</span> pointers.
</p></li><li><p>
A <a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
makes sure that the on-screen display is properly updated
whenever the items in the list change.
</p></li></ul><p>
In both classes, the list keeps track of data
pointers—<span class="type">void*</span> pointers in the case of
<a class="link" href="BList.html" title="BList"><code class="classname">BList</code></a> and pointers to
<a class="link" href="BListItem.html" title="BListItem"><code class="classname">BListItem</code></a>s in the case of
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>.
Adding an item to the list adds only the pointer; the
pointed-to object isn't copied.
</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="id550064"></a>Updating the List</h3></div></div></div><p>
When the contents of the list change, the
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a> makes sure the
visible list on-screen is updated. However, since it records only
pointers to data, it can know that something changed only when a
<a class="link" href="BListItem.html" title="BListItem"><code class="classname">BListItem</code></a>
is added or removed. If an item pointer remains the same but
the data the item displays is altered, the
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a> won't know about it.
In this case, you must force the list to be redrawn (by calling the
<a class="link" href="BListView.html#BListView_InvalidateItem" title="InvalidateItem()"><code class="methodname">InvalidateItem()</code></a>
function or
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>'s
<a class="link" href="BView.html#BView_Invalidate" title="Invalidate()"><code class="methodname">Invalidate()</code></a>).
</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="id550124"></a>Selecting and Invoking Items</h3></div></div></div><p>
The user can click an item in the list to select it and double-click an
item to both select and invoke it. The user can also select and invoke
items from the keyboard. The navigation keys (such as
<span class="keycap">Down Arrow</span>, <span class="keycap">Home</span>,
and <span class="keycap">Page Up</span>) select items; <span class="keycap">Enter</span> and the space bar invoke them.
</p><p>
By default, a <a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
permits only one item to be selected at a time.
However, at construction and with the
<a class="link" href="BListView.html#BListView_SetListType" title="SetListType() , ListType()"><code class="methodname">SetListType()</code></a>
function, you can set
it up to allow multiple selections. The user can make contiguous
extensions to the current selection by holding down a <span class="keycap">Shift</span> key, and
discontinuous extensions by holding down an <span class="keycap">Option</span> key.
</p><p>
The <a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
highlights items as they're selected, but otherwise it
doesn't define what, if anything, should take place when the selection
changes. You can determine that yourself either by implementing a
<a class="link" href="BListView.html#BListView_SelectionChanged" title="SelectionChanged()"><code class="methodname">SelectionChanged()</code></a>
function in a derived class or by registering a
selection message (a <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> object) with the
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>. The function is
called and the message is delivered to a target destination whenever the
user modifies the selection.
</p><p>
Similarly, the <a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
doesn't define what it means to "invoke" an
item. You can register a separate invocation message that's sent whenever
the user double-clicks an item or presses <span class="keycap">Enter</span> or the space bar while
items are selected. For example, if the user double-clicks an item in a
list of file names, the message might tell the
<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>
object to open that file.
</p><p>
A <a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
doesn't have default selection and invocation messages.
Messages are sent only if registered with the
<a class="link" href="BListView.html#BListView_SetSelectionMessage" title="SetSelectionMessage(), SelectionMessage(), SelectionCommand()"><code class="methodname">SetSelectionMessage()</code></a> and
<a class="link" href="BListView.html#BListView_SetInvocationMessage" title="SetInvocationMessage(), InvocationMessage(), InvocationCommand()"><code class="methodname">SetInvocationMessage()</code></a>
functions. Before sending either type of message,
the <a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
adds information to it identifying itself and the items
that are currently selected. See the
<a class="link" href="BInvoker.html#BInvoker_Invoke" title="Invoke(), InvokeNotify()"><code class="methodname">Invoke()</code></a>
function for details.
</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="id550292"></a>Autoscrolling and Dragging Items</h3></div></div></div><p>
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
provides an autoscroll feature: There's an invisible area about
25 pixels high both above and below the list view; if the user clicks
inside the list view and then drags into this autoscroll area, the
contents of the list will scroll in the direction of the mouse.
</p><p>
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
also provides optional item-dragging that let's the user
reorder the items in the list. To turn on this feature, you have to
subclass <a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
and implement
<a class="link" href="BListView.html#BListView_InitiateDrag" title="InitiateDrag()"><code class="methodname">InitiateDrag()</code></a>
to return <code class="constant">true</code>.
</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="id550346"></a>Adding a Scroll Bar to a BListView</h3></div></div></div><p>
Note that although a <a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
is scrollable, it doesn't provide scroll bars. You can place the
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
inside a <a class="link" href="BScrollView.html" title="BScrollView"><code class="classname">BScrollView</code></a> to get the more
traditional appearance for your list:
</p><p>
The code for this might look something like this:
</p><pre class="programlisting example cpp"><span class="type">BListView*</span> <code class="varname">list</code> = new <code class="classname">BListView</code>(<code class="varname">r</code>, "City",
<code class="constant">B_MULTIPLE_SELECTION_LIST</code>);
<code class="varname">list</code>-&gt;<code class="methodname">AddItem</code>(new <code class="classname">BStringItem</code>("Chicago"));
...
<code class="varname">theView</code>-&gt;<code class="methodname">AddChild</code>(new <code class="classname">BScrollView</code>("scroll_cities", <code class="varname">list</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>
See the <a class="link" href="BScrollView.html" title="BScrollView"><code class="classname">BScrollView</code></a>
class for a more in-depth explanation of scrolling views.
</p><p>
See also: the <a class="link" href="BList.html" title="BList"><code class="classname">BList</code></a>
class in the Support Kit, the
<a class="link" href="BOutlineListView.html" title="BOutlineListView"><code class="classname">BOutlineListView</code></a> and
<a class="link" href="BListItem.html" title="BListItem"><code class="classname">BListItem</code></a> classes
</p></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BListItem_Overview.html">BListItem</a>  Up: <a href="TheInterfaceKit_Overview.html">The Interface Kit</a>  Next: <a href="BMenu_Overview.html">BMenu</a> </div><div id="footerB"><div id="footerBL"><a href="BListItem_Overview.html" title="BListItem"><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="BMenu_Overview.html" title="BMenu"><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