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

191 lines
20 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="BFont_Overview.html" title="BFont" /><link rel="next" href="BListView_Overview.html" title="BListView" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BFont_Overview.html" title="BFont"><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="BListView_Overview.html" title="BListView"><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="BFont_Overview.html">BFont</a>  Up: <a href="TheInterfaceKit_Overview.html">The Interface Kit</a>  Next: <a href="BListView_Overview.html">BListView</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="BListItem_Overview"></a>BListItem</h2></div></div></div><a id="id548730" class="indexterm"></a><p>
A <a class="link" href="BListItem.html" title="BListItem"><code class="classname">BListItem</code></a>
represents a single item in a
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a> (or
<a class="link" href="BOutlineListView.html" title="BOutlineListView"><code class="classname">BOutlineListView</code></a>).
The <a class="link" href="BListItem.html" title="BListItem"><code class="classname">BListItem</code></a>
object provides drawing instructions
that can draw the item (through
<a class="link" href="BListItem.html#BListItem_DrawItem" title="DrawItem()"><code class="methodname">DrawItem()</code></a>),
and keeps track of the item's state. To use a
<a class="link" href="BListItem.html" title="BListItem"><code class="classname">BListItem</code></a>,
you must add it to a
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
through
<a class="link" href="BListView.html#BListView_AddItem" title="AddItem()"><code class="methodname">BListView::AddItem()</code></a>
(<a class="link" href="BOutlineListView.html" title="BOutlineListView"><code class="classname">BOutlineListView</code></a>
provides additional item-adding functions). The
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
object provides the drawing context for the
<a class="link" href="BListItem.html" title="BListItem"><code class="classname">BListItem</code></a>'s
<a class="link" href="BListItem.html#BListItem_DrawItem" title="DrawItem()"><code class="methodname">DrawItem()</code></a>
function.
</p><p>
<a class="link" href="BListItem.html" title="BListItem"><code class="classname">BListItem</code></a>
is abstract; each subclass must implement
<a class="link" href="BListItem.html#BListItem_DrawItem" title="DrawItem()"><code class="methodname">DrawItem()</code></a>.
<a class="link" href="BStringItem.html" title="BStringItem"><code class="classname">BStringItem</code></a>—the
only
<a class="link" href="BListItem.html" title="BListItem"><code class="classname">BListItem</code></a>
subclass provided by Be—implements the function to draw the item as a line of text. For
an example of a custom
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
subclass, see "<a class="xref" href="BListItem_Overview.html#BListItem_Overview_Custom" title="Creating a Custom List Item">Creating a Custom List Item</a>".
</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="id548887"></a>Synchronizing a List Item with its List View</h3></div></div></div><p>
A <a class="link" href="BListItem.html" title="BListItem"><code class="classname">BListItem</code></a>
object doesn't automatically get redrawn when the item
changes. If you change a list item's content or state, you must tell the item's owner (the
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a> object) to redraw the item by calling
<a class="link" href="BListView.html#BListView_InvalidateItem" title="InvalidateItem()"><code class="methodname">BListView::InvalidateItem()</code></a>.
For example:
</p><pre class="programlisting example cpp"><span class="comment">/* listItem belongs to listView.
We change the state of the item... */</span>
<code class="varname">listItem</code>-&gt;<code class="methodname">SetEnabled</code>(<code class="constant">false</code>);
<span class="comment">/* ...so we have to tell the list view to redraw it. */</span>
<code class="varname">listView</code>-&gt;<code class="methodname">LockLooper</code>();
<code class="varname">listView</code>-&gt;<code class="methodname">InvalidateItem</code>(<code class="varname">listView</code>-&gt;<code class="methodname">IndexOf</code>(<code class="varname">listItem</code>));
<code class="varname">listView</code>-&gt;<code class="methodname">UnlockLooper</code>();</pre><p>
If you're making a lot of changes, you can flush them all at the same
time through a single
<a class="link" href="BView.html#BView_Invalidate" title="Invalidate()"><code class="methodname">BView::Invalidate()</code></a> call:
</p><pre class="programlisting example cpp"><code class="varname">listItemA</code>-&gt;<code class="methodname">SetEnabled</code>(<code class="constant">false</code>);
<code class="varname">listItemB</code>-&gt;<code class="methodname">SetEnabled</code>(<code class="constant">false</code>);
<code class="varname">listItemC</code>-&gt;<code class="methodname">SetEnabled</code>(<code class="constant">false</code>);
<code class="varname">listView</code>-&gt;<code class="methodname">LockLooper</code>();
<code class="varname">listView</code>-&gt;<code class="methodname">Invalidate</code>();
<code class="varname">listView</code>-&gt;<code class="methodname">UnlockLooper</code>();</pre><p>
Note that you don't have to lock the list view's window to change one of
its items—you only have to lock the window when you talk to the
list view itself.
</p><p>
<a class="link" href="BListView.html" title="BListView"><code class="classname">BListView</code></a>
provides its own smart version
</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="BListItem_Overview_Custom"></a>Creating a Custom List Item</h3></div></div></div><p>
Although much of the time all you need to draw in a list are strings (in
which case you can use the
<a class="link" href="BStringItem.html" title="BStringItem"><code class="classname">BStringItem</code></a>
class), from time-to-time you may
need to display more than a simple text string—maybe you need to
display multiple pieces of information per item, or maybe you just want
to jazz up the display with some icons.
</p><p>
For example, let's say you need to let the user select a city from a
list, but also need to display the part of the world that each city is
in. You could just use
<a class="link" href="BStringItem.html" title="BStringItem"><code class="classname">BStringItem</code></a>
objects with strings like "Chicago
(USA)", but it might look nicer if you could lay out your list items in
two colums, maybe with a splash of color:
</p><div class="mediaobject"><img src="./images/TheInterfaceKit/custlistitem.png" alt="Custom ListItem" /></div><p>
To change the appearance of a list item, you override the
<a class="link" href="BListItem.html#BListItem_DrawItem" title="DrawItem()"><code class="methodname">DrawItem()</code></a>
function to draw the item's contents however you want it to look.
</p><p>
The following sections define the class that creates these list items.
</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="id549153"></a>The CityItem Declaration</h4></div></div></div><p>
The declaration for our <code class="classname">CityItem</code> class looks like this:
</p><pre class="programlisting example cpp">#include &lt;String.h&gt;
#include &lt;ListItem.h&gt;
class <code class="classname">CityItem</code> : public <code class="classname">BListItem</code>
{
public:
<code class="methodname">CityItem</code>(<span class="type">const char *</span><code class="parameter">city</code>, <span class="type">int32</span> <code class="parameter">region</code> = 0);
virtual <span class="type">void</span> <code class="methodname">DrawItem</code>(<span class="type">BView *</span><code class="parameter">owner</code>,
<code class="classname">BRect</code> <code class="parameter">frame</code>,
<span class="type">bool</span> <code class="parameter">complete</code> = <code class="constant">false</code>);
enum { <code class="constant">USA</code>, <code class="constant">ASIA</code>, <code class="constant">EUROPE</code>, <code class="constant">AUSTRALIA</code>, <code class="constant">OTHER</code> };
private:
<code class="classname">BString</code> <code class="varname">kCity</code>;
<span class="type">int32</span> <code class="varname">kRegion</code>;
};
<span class="type">const char *</span><code class="varname">region_names</code>[] = {
"USA", "Asia", "Eur.", "Aust.", "Other"
};</pre><p>
A <code class="classname">CityItem</code> object contains two pieces of data: a city name, and a region
code. The region code is used as an index into the array of region names.
</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="id549286"></a>The CityItem Definition</h4></div></div></div><p>
The constructor looks like this:
</p><pre class="programlisting example cpp"><code class="classname">CityItem</code>::<code class="methodname">CityItem</code>(<span class="type">const char *</span><code class="parameter">city</code>, <span class="type">int32</span> <code class="parameter">region</code>)
: <code class="classname">BListItem</code>()
{
<code class="varname">kCity</code> = <code class="parameter">city</code>;
<code class="varname">kRegion</code> = <code class="parameter">region</code>;
}</pre><p>
The <a class="link" href="BListItem.html#BListItem_DrawItem" title="DrawItem()"><code class="methodname">DrawItem()</code></a>
function does the actual work of drawing the item.
<a class="link" href="BListItem.html#BListItem_DrawItem" title="DrawItem()"><code class="methodname">DrawItem()</code></a>
receives three parameters:
</p><ul class="itemizedlist"><li><p>
A <a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a>
"owner"; this is the view that contains the
<a class="link" href="BListItem.html" title="BListItem"><code class="classname">BListItem</code></a>. All
drawing calls you issue should be made through this BView. For example:
</p><pre class="programlisting example cpp"><code class="varname">owner</code>-&gt;<code class="methodname">DrawString</code>(<code class="varname">item_text</code>);</pre></li><li><p>
A <a class="link" href="BRect.html" title="BRect"><code class="classname">BRect</code></a>,
which is the rectangle in which the item should be drawn.
</p></li><li><p>
A <span class="type">bool</span>, which is <code class="constant">true</code> if the item needs to be erased and redrawn, or
<code class="constant">false</code> if the item's contents can be safely redrawn without erasing the
current contents.
</p></li></ul><p>
<a class="link" href="BListItem.html#BListItem_DrawItem" title="DrawItem()"><code class="methodname">DrawItem()</code></a>
begins by checking to see if the item is selected (by calling
<a class="link" href="BListItem.html#BListItem_IsSelected"><code class="methodname">IsSelected()</code></a>)
or if a complete redraw is required. In either of these
cases, we want to redraw the background, to either the highlight color,
or the owner's view color:
</p><pre class="programlisting example cpp"><span class="type">void</span> <code class="classname">CityItem</code>::<code class="methodname">DrawItem</code>(<span class="type">BView *</span><code class="parameter">owner</code>, <code class="classname">BRect</code> <code class="parameter">frame</code>,
<span class="type">bool</span> <code class="parameter">complete</code>)
{
if (<code class="methodname">IsSelected</code>() || <code class="parameter">complete</code>) {
<span class="type">rgb_color</span> <code class="varname">color</code>;
if (<code class="methodname">IsSelected</code>()) {
<code class="varname">color</code> = <code class="varname">kHighlight</code>;
}
else {
<code class="varname">color</code> = <code class="varname">owner</code>-&gt;<code class="methodname">ViewColor</code>();
}
<code class="parameter">owner</code>-&gt;<code class="methodname">SetHighColor</code>(<code class="varname">color</code>);
<code class="parameter">owner</code>-&gt;<code class="methodname">FillRect</code>(<code class="varname">frame</code>);
}</pre><p>
Now we draw the text. First, we move the owner view's pen so it's inset
from the bottom left corner of the item's frame. (In a real application,
you would want to make the inset adjustments based on the font that's
being used; see the <a class="link" href="BFont.html" title="BFont"><code class="classname">BFont</code></a> class for more information.):
</p><pre class="programlisting example cpp"><code class="parameter">owner</code>-&gt;<code class="methodname">MovePenTo</code>(<code class="varname">frame</code>.<code class="varname">left</code>+4, <code class="varname">frame</code>.<code class="varname">bottom</code>-2);</pre><p>
If the item is enabled (selectable), we set the owner view's high color
to a shade of medium red; if it's disabled, we use a lighter red color
(the color definitions aren't shown). Then we use
<a class="link" href="BView.html#BView_DrawString" title="DrawString()"><code class="methodname">DrawString()</code></a> to draw
the region name:.
</p><pre class="programlisting example cpp"> if (<code class="methodname">IsEnabled</code>()) {
<code class="parameter">owner</code>-&gt;<code class="methodname">SetHighColor</code>(<code class="constant">kRedColor</code>);
}
else {
<code class="parameter">owner</code>-&gt;<code class="methodname">SetHighColor</code>(<code class="constant">kDimRedColor</code>);
}
<code class="parameter">owner</code>-&gt;<code class="methodname">DrawString</code>(<code class="varname">region_names</code>[<code class="varname">kRegion</code>]);</pre><p>
Move the pen to the right column and draw the city name:
</p><pre class="programlisting example cpp"> <code class="parameter">owner</code>-&gt;<code class="methodname">MovePenTo</code>(<code class="varname">frame</code>.<code class="varname">left</code>+38, <code class="varname">frame</code>.<code class="varname">bottom</code>-2);
if (<code class="methodname">IsEnabled</code>()) {
<code class="parameter">owner</code>-&gt;<code class="methodname">SetHighColor</code>(<code class="constant">kBlackColor</code>);
}
else {
<code class="parameter">owner</code>-&gt;<code class="methodname">SetHighColor</code>(<code class="constant">kMedGray</code>);
}
<code class="parameter">owner</code>-&gt;<code class="methodname">DrawString</code>(<code class="varname">kCity</code>.<code class="methodname">String</code>());
}</pre></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="id549742"></a>Using a CityItem Object</h4></div></div></div><p>
To use a <code class="classname">CityItem</code> object, simply construct a new object and pass it to
<a class="link" href="BListView.html#BListView_AddItem" title="AddItem()"><code class="methodname">BListView::AddItem()</code></a>:
</p><pre class="programlisting example cpp"><code class="varname">listView</code>-&gt;<code class="methodname">AddItem</code>(new <code class="classname">CityItem</code>("Chicago", <code class="classname">CityItem</code>::<code class="constant">USA</code>));</pre></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BFont_Overview.html">BFont</a>  Up: <a href="TheInterfaceKit_Overview.html">The Interface Kit</a>  Next: <a href="BListView_Overview.html">BListView</a> </div><div id="footerB"><div id="footerBL"><a href="BFont_Overview.html" title="BFont"><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="BListView_Overview.html" title="BListView"><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