Initializes the new BListView. The frame, name, resizingMode, and flags arguments are identical to those declared for the BView class and are passed unchanged to the BView constructor.

The list type can be either:

The list begins life empty. Call AddItem() or AddList() to put items in the list. Call Select() to select one of the items so that it's highlighted when the list is initially displayed to the user.

Frees the selection and invocation messages, if any, and any memory allocated to hold the list of items, but not the items themselves.

Sets up the BListView and makes the BWindow to which it has become attached the target for the messages it sends when items are selected or invoked—provided another target hasn't already been set. In addition, this function calls BListItem::Update() for each item in the list to give it a chance to adjust its layout. The BListView's vertical scroll bar is also adjusted.

This function is called for you when the BListView becomes part of a window's view hierarchy.

See also: BView::AttachedToWindow(), BInvoker::SetTarget()

Calls upon every item in the updateRect area of the view to draw itself.

Draw() is called for you whenever the list view is to be updated or redisplayed; you don't need to call it yourself. You also don't need to reimplement it; to change the way items are drawn, define a new version of DrawItem() in a class derived from BListItem.

See also: BView::Draw()

Updates the on-screen display in response to a notification that the BListView's frame rectangle has been resized. In particular, this function looks for a vertical scroll bar that's a sibling of the BListView. It adjusts this scroll bar to reflect the way the list view was resized, under the assumption that it must have the BListView as its target.

FrameResized() is called automatically at the appropriate times; you shouldn't call it yourself.

See also: BView::FrameResized()

Implemented by derived classes to permit users to drag items. This function is called from the BListView's MouseDown() function; it should initiate the drag-and-drop operation and return true, or refuse to do so and return false. By default, it always returns false.

The point that's passed to InitiateDrag() is the same as the point passed to MouseDown(); it's where the cursor was located when the user pressed the mouse button. The index of the item under the cursor (the item that would be dragged) is passed as the second argument, and the wasSelected flag indicates whether or not the item was selected before the mouse button went down.

A BListView allows users to autoscroll the list by holding the mouse button down and dragging outside its frame rectangle. If a derived class implements InitiateDrag() to drag an item each time the user moves the mouse with a button down, it will hide this autoscrolling behavior. Therefore, derived classes typically permit users to drag items only if they're already selected (if wasSelected is true). In other words, it takes two mouse-down events to drag an item—one to select it and one to begin dragging it.

See also: BView::DragMessage()

Permits the user to operate the list using the following keys:

This function also incorporates the inherited BView version so that the Tab key can navigate to another view.

KeyDown() is called to report B_KEY_DOWN messages when the BListView is the focus view of the active window; you shouldn't call it yourself.

See also: BView::KeyDown(), Select(), Invoke()

Responds to B_MOUSE_DOWN messages by selecting items, invoking them (if the mouse-down event is the second of a double-click), and autoscrolling the list (when the user drags with a mouse button down). This function also calls InitiateDrag() to give derived classes the opportunity to drag items. You can implement that function; you shouldn't override (or call) this one.

See also: BView::MouseDown(), Select(), Invoke(),

Implemented by derived classes to do whatever they please when the selection changes.

Notes the fact that the BListView is the target of a BScrollView and arranges for the border of the BScrollView to be highlighted when the BListView is the current focus view of the active window.

See also: BScrollView::SetBorderHighlighted()

Makes sure that the BScrollView that targets the BListView is redrawn when the window is activated and deactivated, if the BListView is the current focus view. This gives the BScrollView a chance to highlight or unhighlight its border, as appropriate.

See also: BView::WindowActivated()

Adds an item to the BListView at index—or, if no index is supplied, at the end of the list. If necessary, additional memory is allocated to accommodate the new item.

Adding an item never removes an item already in the list. If the item is added at an index that's already occupied, items currently in the list are bumped down one slot to make room.

If index is out of range (greater than the current item count, or less than zero), this function fails and returns false. Otherwise, it returns true.

See also: BListItem, BList::AddItem()

Adds the contents of another list to this BListView. The items from the BList are inserted at index—or, if no index is given, they're appended to the end of the list. If the index is out of range, the function fails and returns false. If successful, it returns true.

The BListView doesn't check to be sure that all the items it adds from the list are pointers to BListItem objects. It assumes that they are; if the assumption is false, subsequent BListView operations will fail.

See also: AddItem(), BList::AddList()

Stores the BListView in the BMessage archive.

See also: BArchivable::Archive(), Instantiate() static function

Returns the number of BListItems currently in the list.

See also: BList::CountItems

Returns the index of a currently selected item in the list, or a negative number if no item is selected. The domain of the index passed as an argument is the current set of selected items; the first selected item is at index 0, the second at index 1, and so on, even if the selection is not contiguous. The domain of the returned index is the set of all items in the list.

To get all currently selected items, increment the passed index until the function returns a negative number:

BListItem* item;
int32 selected;
while ( (selected = myListView->CurrentSelection(i)) >= 0 ) {
   item = ItemAt(selected);
   . . .
}

See also: Select()

These functions deselect the item at index, all the items, or all the items except those from index start through index finish.

See also: Select()

Calls the func function once for each item in the BListView. BListItems are visited in order, beginning with the first one in the list (index 0) and ending with the last. If a call to func returns true, the iteration is stopped, even if some items have not yet been visited.

func must be a function that takes one or two arguments. The first argument is a pointer to the BListItem; the second argument, if func requires one, is passed to DoForEach() as arg2.

See also: BList::DoForEach()

Returns true if item is in the list, and false if not.

See also: BList::HasItem()

Returns the index where a particular item—or the item whose display rectangle includes a particular point—is located in the list. If the item is in the list more than once, the index returned will be the position of its first occurrence. To determine whether an item lies at the specified point, only the y-coordinate value of the point is considered.

If the item isn't in the list or the y-coordinate of the point doesn't intersect with the data rectangle of the BListView, the return value will be a negative number.

See also: BList::IndexOf()

Invalidates the item at index so that an update message will be sent forcing the BListView to redraw it.

See also: BView::Invalidate()

Augments the BInvoker version of Invoke() to add three pieces of information to each message the BListView sends:

This function is called to send both the selection message and the invocation message. It can also be called from application code. The default target of the message (established by AttachedToWindow()) is the BWindow where the BListView is located.

What it means to "invoke" selected items depends entirely on the invocation BMessage and the receiver's response to it. This function does nothing but send the message.

See also: Select(), SetInvocationMessage(), BInvoker::SetTarget()

Returns true if the item at index is currently selected, and false if it's not.

See also: CurrentSelection()

The first of these functions returns the BListItem at index, or NULL if the index is out of range. The other two functions return the very first and very last items in the list, or NULL if the list is empty. None of the functions alters the contents of the list—they don't remove the returned item.

See also: Items(), BList::ItemAt(), BList::FirstItem(), BList::LastItem()

Returns the frame rectangle of the BListItem at index. The rectangle is stated in the coordinate system of the BListView and defines the area where the item is drawn. Items can differ in height, but all have the same width.

See also: DrawItem()

Returns a pointer to the BListView's list of BListItems. You can index directly into the list of items if you're certain that the index is in range:

BListItem* item = Items()[index];

Although the practice is discouraged, you can also step through the list of items by incrementing the list pointer that Items() returns. Be aware that the list isn't null-terminated—you have to detect the end of the list by some other means. The simplest method is to count items:

BListItem** ptr = myListView->Items();

for ( long i = myListView->CountItems(); i > 0; i—)
{
   . . .
   *ptr++;
}

You should never use the items pointer to alter the contents of the list.

See also: DoForEach(), SortItems(), BList::Items()

MakeEmpty() empties the BListView of all its items, without freeing the BListItem objects.

IsEmpty() returns true if the list is empty (if it contains no items), and false otherwise.

See also: RemoveItem(), BList::MakeEmpty()

Overrides the BView version of MakeFocus() to draw an indication that the BListView has become the focus for keyboard events when the focused flag is true, and to remove that indication when the flag is false.

MoveItem() moves the item located at the index from to the index specified by the to argument.

ReplaceItem() replaces the item located at the specifie index with the specified item.

SwapItems() swaps the items specified by index1 and index2 in the list.

These functions return true if the requested operation is completed successfully, or false if the operation failed (for example, if a specified index is out of range).

RemoveItem() removes a single item from the BListView. If passed an index, it removes the item at that index and returns it. If there's no item at the index, it returns NULL. If passed an item, this function looks for that particular item in the list, removes it, and returns true. If it can't find the item, it returns false. If the item is in the list more than once, this function removes only its first occurrence.

RemoveItems() removes count number of items from the BListView, beginning with the item at index. If the list doesn't contain count items between index and the end of the list, this function removes as many items as there are.

The list is compacted after an item is removed. Therefore, you shouldn't try to empty a list (or a range within a list) by removing items incrementing indices. You should either start with the highest index and move towards the head of the list, or remove at the same index (the lowest in the range) some number of times. As an example of the latter, the following code removes the first five items in the list:

for ( int32 i = 0; i <= 4; i++ )
   myListView->RemoveItem(0);

See also: MakeEmpty(), BList::RemoveItem()

Augments the BView version of ScrollTo() to do some class-internal housekeeping when the list is scrolled. For all practical purposes, these functions are identical to their BView counterparts.

Scrolls the list so that the first item in the current selection is visible.

Selects the item located at index—or all the items from the start index through the finish index – provided that none of the indices are out of range. If the extend flag is false, as it is by default, this function removes the highlighting from the previously selected item(s) and highlights the new selection. However, if the extend flag is true, the newly selected items are added to the current selection.

If you want your newly-selected item to be scrolled into view, you must call ScrollToSelection() after invoking Select(). The Select() function itself does not do any scrolling.

Select() can be called to set an initial selection in the list or change the current selection. It permits the program to select a number of items, even for a B_SINGLE_SELECTION_LIST list.

If you want to be informed of successful selections, you either have to implement SelectionChanged() or supply a selection message (through SetSelectionMessage() ). The former is invoked and the latter is sent when an item is selected.

See also: Invoke(), Deselect()

These functions set and return information about the BMessage that the BListView sends when currently selected items are invoked.

SetInvocationMessage() assigns message to the BListView, freeing any message previously assigned. The message becomes the responsibility of the BListView object and will be freed only when it's replaced by another message or the BListView is freed; you shouldn't free it yourself. Passing a NULL pointer to this function deletes the current message without replacing it.

When sending the message, the Invoke() function makes a copy of it and adds two pieces of relevant information—"when" the message is sent and the "source" BListView. These names should not be used for any data that you add to the invocation message.

InvocationMessage() returns a pointer to the BMessage and InvocationCommand() returns its what data member. The message belongs to the BListView; it can be altered by adding or removing data, but it shouldn't be deleted. To get rid of the current message, pass a NULL pointer to SetInvocationMessage().

See also: Invoke(), the BMessage class

These functions set and return the list type—whether or not it permits multiple selections. The list_view_type must be either B_SINGLE_SELECTION_LIST or B_MULTIPLE_SELECTION_LIST. The type is first set when the BListView is constructed.

See also: the BListView constructor

These functions set, and return information about, the message that a BListView sends whenever a new item is selected. They're exact counterparts to the functions described above under SetInvocationMessage(), except that the selection message is sent whenever an item in the list is selected, rather than when invoked. It's more common to take action (to initiate a message) when invoking an item than when selecting one.

See also: Select(), Invoke(), the BMessage class

Rearranges the items in the list. The items are sorted using the compareFunc comparison function passed as an argument. This function should return a negative number if the first item is ordered before the second, a positive number if the second comes before the first, and 0 if the two items are ordered equivalently.

Although the comparison function is, in the usual manner for such functions, declared to take two void* arguments, each argument should be a pointer to an item in the list—in other words, a pointer to a BListItem pointer:

int compare_func(BListItem** firstArg, BListItem** secondArg);

See also: Items(), BList::SortItems()

Returns a new BListView object, allocated by new and created with the version of the constructor that takes a BMessage archive. However, if the archive message doesn't contain data for a BListView object, this function returns NULL.

See also: BArchivable::Instantiate(), instantiate_object(), Archive()()

The "Item" property refers to individual BListItems in the list.

The "Selection" property refers to the set of selected BListItems. If the BListView is of type B_SINGLE_SELECTION_LIST, then only one item can be selected at any given instant; the list type cannot be overridden through the scripting interface. Attempting to access multiple selected list elements in a B_SINGLE_SELECTION_LIST results in an error.