Derived from: public BView
Declared in: <interface/ListView.h>
A BListView is a view that displays a list of items the user can select and invoke. This class is based on the BList class of the Support Kit. Every member function of the BList class is replicated by BListView, so you can treat a BListView object just like a BList. BListView simply makes the list visible.
In both classes, the list keeps track of data pointers. Adding an item to the list adds only the pointer; the data itself isn't copied. Neither class imposes a type restriction on the data (both declare items to be type void *). However, by default, BListView assumes they're pointers to strings (type char *). Its functions can display the strings, highlight them when selected, and so on. As long as only string pointers are placed in the list, a BListView object can be used as is. However, if the list is to contain another kind of data, it's necessary to derive a class from BListView and reimplement some of its hook functions.
When the contents of the list change, the BListView makes sure the visible list on-screen is updated. However, it can know that something changed only when a data pointer changes, since pointers are all that the list records. If any pointed-to data is altered, but the pointer remains the same, you must force the list to be redrawn (by calling the InvalidateItem() function or BView's Invalidate() ).
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 Down Arrow, Home, and Page Up) select items; Enter invokes the item that's currently selected.
The BListView highlights the selected item, but otherwise it doesn't define what, if anything, should take place when an item is selected. You can determine that yourself by registering a "selection message" (a BMessage object) that should be delivered to a target destination whenever the user selects an item.
Similarly, the BListView doesn't define what it means to "invoke" an item. You can register a separate "invocation message" that's posted whenever the user double-clicks an item or presses Enter while an item is selected. For example, if the user double-clicks an item in a list of file names, a message might be posted telling the BApplication object to open that file.
A BListView doesn't have a default selection message or invocation message. Messages are posted only if registered with the SetSelectionMessage() and SetInvocationMessage() functions. The registered message is only a model. When an item is selected or invoked, the BListView makes a copy of the model, adds information to the copy about itself and the item, then posts the copy. See the function descriptions for information on the data that automatically gets added to the message.
See also: the BList class in the Support Kit
DrawItem() | Draws the character string that the item points to; can be reimplemented to draw from another kind of data. |
HighlightItem() | Highlights the item by inverting all the colors in its frame rectangle; can be reimplemented to highlight in a different way. |
Invoke() | Posts the invocation message, if one has been registered for the BListView; can be augmented to do whatever else may be necessary when a item is invoked. |
ItemHeight() | Returns the height of a single item, assuming that it's a character string and is to be drawn in the current font; can be reimplemented to return the height required to draw a different kind of item. All items are taken to have the same height. |
Select() | Highlights the selected item and posts the selection message, if one has been registered for the BListView; can be augmented to take any collateral action that may be required when the selection changes. |
BListView(BRect frame, const char *name, ulong resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP, ulong flags = B_WILL_DRAW | B_NAVIGABLE | B_FRAME_EVENTS)
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 begins life empty. Call AddItem() or AddList() (documented for the BList class) to put items in the list. Call Select() (documented below) to select one of the items so that it's highlighted when the list is initially displayed to the user.
See also: the BView constructor, BList::AddItem()
virtual ~BListView(void)
Frees the model messages, if any, and all memory allocated to hold the list of items.
The BListView class reimplements all of the member functions of the BList class in the Support Kit. BListView's versions of these functions work identically to the BList versions, except that a BListView makes sure that the on-screen display is properly updated whenever the list changes.
Consequently, this section excludes all functions that BList and BListView have in common. It concentrates instead on those member functions that deal with the BListView's behavior as a view, not as a list. See the BList class for information on the functions that you can use to manipulate the BListView's list.
virtual void AttachedToWindow(void)
Sets up the BListView so that it's prepared to draw character strings for items, and makes the BWindow to which the object has become attached the target for messages posted by the Select() and Invoke() functions--provided another target hasn't already been set.
This function is called for you when the BListView becomes part of a window's view hierarchy.
See also: BView::AttachedToWindow(), SetTarget()
protected:
float BaselineOffset(void)
Returns the distance from the bottom of an item's frame rectangle to the baseline where the item, assuming it is a character string, is drawn. The string is drawn beginning at a point that's offset 2.0 coordinate units from the left of the frame rectangle and BaselineOffset() units from the bottom. The offsets are the same for all items.
This function will give unreliable results unless the BListView is attached to a window.
inline long CurrentSelection(void) const
Returns the index of the currently selected item, or a negative number if no item is selected.
See also: Select()
virtual void Draw(BRect updateRect)
Calls the DrawItem() hook function to draw each visible item in the updateRect area of the view and highlights the currently selected item by calling the HighlightItem() hook function.
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, even if you're defining a list that displays something other than character strings. You should implement data- specific versions of DrawItem() and HighlightItem() instead.
See also: BView::Draw() , DrawItem(), HighlightItem()
protected:
virtual void DrawItem(BRect updateRect, long index)
Draws the item at index. The default version of this function assumes that the item is a character string. It can be reimplemented by derived classes to draw differently, based on other kinds of data.
The updateRect rectangle is stated in the BListView's coordinate system. It's the portion of the item's frame rectangle that needs to be updated. The full frame rectangle of the item is returned by the ItemFrame() function.
The Draw() function determines which items in the BListView need to be updated and calls DrawItem() for each one.
See also: ItemHeight() , ItemFrame(), HighlightItem(), BaselineOffset()
virtual void FrameResized(float width, float height)
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()
protected:
virtual void HighlightItem(bool flag, long index)
Highlights the item at index if flag is TRUE , and removes the highlighting if flag is FALSE. Items are highlighted by inverting all colors in their frame rectangles.
This function is called (by Draw() ) to highlight the selected item and (by Select() ) to change the item that's highlighted whenever the selection changes. It can be reimplemented in a derived class to highlight in a different way.
void InvalidateItem(long index)
Invalidates the item at index so that an update message will be sent forcing the BListView to redraw it.
See also: BView::Invalidate()
virtual void Invoke(long index)
Invokes the item at index, provided that the index isn't out-of-range.
This function is called whenever the user double-clicks an item in the list, or presses the Enter key while the BListView is the current focus view for the window and there's a selected item. It can also be called from application code to invoke a particular item; usually Select() would first be called to select the item.
To invoke an item that's identified by a pointer, first call IndexOf() to find where it's located in the list:
long i = myList->IndexOf(someItem); myList->Select(i); myList->Invoke(i);
If a model "invocation message" has been registered with the BListView (through SetInvocationMessage()), Invoke() makes a copy of the message, adds information to the copy identifying the BListView and the invoked item, and posts the copy so that it will be handled by the designated target. The default target (established by AttachedToWindow()) is the BWindow where the BListView is located. SetTarget() can be called to name another BHandler for the message. It can also be called to set a particular BLooper where the message should be posted, but to let that BLooper's preferred handler respond to the message. In this case, the exact target will be picked when Invoke() is called.
What it means to "invoke" an item depends entirely on the BMessage that's posted and the receiver's response when it gets the message. This function does nothing but post the message.
See also: Select(), SetInvocationMessage(), SetTarget()
inline bool IsItemSelected(long index) const
Returns TRUE if the item at index is currently selected, and FALSE if it's not.
See also: CurrentSelection()
protected:
BRect ItemFrame(long index) const
Returns the frame rectangle of the item at index. The rectangle defines the area where the item is drawn; it's stated in the coordinate system of the BListView. The rectangle is calculated from the ordinal position of the item in the list and the value returned by ItemHeight().
It's expected that you'd need to find an item's frame rectangle only if you're implementing a DrawItem() function.
< This function currently doesn't check to be sure that the index is in range. >
See also: DrawItem()
protected:
virtual float ItemHeight(void) const
Returns how much vertical room is required to draw a single item in the list --how high each item's frame rectangle should be. The BListView calls ItemHeight() extensively to determine where items are located and where to draw them. By default, it returns a height sufficient to draw a character string in the current font.
A derived class that draws items other than character strings should reimplement ItemHeight() so that it returns the height required to draw one of its items.
See also: DrawItem()
virtual void KeyDown(ulong aChar)
Permits the user to operate the list using the following keys:
Keys | Perform Action |
---|---|
Up Arrow and Down Arrow | Select the items that are immediately before and immediately after the currently selected item. |
Page Up and Page Down | Select the items that are one viewful above and below the currently selected item --or the first and last items if there's no item a viewful away. |
Home and End | Select the first and last items in the list. |
Enter and the space bar | Invoke the currently selected item. |
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()
virtual void MakeFocus(bool focused = TRUE)
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 .
See also: BView::MakeFocus()
virtual void MouseDown(BPoint point)
Determines which item is located at point and calls Select() to select it (for a single-click or the first event in a series) and Invoke() to invoke it (for a double-click or the second in a series).
This function also makes the BListView the focus view so the user can operate the list from the keyboard.
MouseDown() is called to notify the BListView of a mouse-down event; you don't need to call it yourself.
See also: BView::MouseDown(), Select() , Invoke()
virtual void Select(long index)
Selects the item located at index, provided that the index isn't out-of-range. This function removes the highlighting from the previously selected item and highlights the new selection, scrolling the list so the item is visible if necessary. Selecting an item also marks it as the item that CurrentSelection() returns and that the Enter key can invoke.
Select() is called whenever the user selects an item, using either the keyboard or the mouse. It can also be called from application code to set an initial selection in the list or change the current selection.
If a model "selection message" has been registered with the BListView, Select() copies the message, adds information to the copy identifying the list and the item that was selected, and posts the copy so that it will be dispatched to the target BHandler. If a message hasn't been registered, "selecting" an item simply means to highlight it and mark is as the selected item.
Typically, BListViews are set up to post a message when an item is invoked, but not when one is selected.
See also: SetSelectionMessage() , Invoke()
virtual void SetFontName(const char *name) virtual void SetFontSize(float points) virtual void SetFontRotation(float degrees) virtual void SetFontShear(float angle)
SetFontName(), SetFontSize(), and SetFontShear() augment their BView counterparts to recalculate the layout of items in the list when the font changes. However, the list is not automatically redisplayed in the new font.
SetFontRotation() is disabled; a rotated font is incompatible with a list horizontal items.
See also: BView::SetFontName()
virtual void SetInvocationMessage(BMessage *message) BMessage *InvocationMessage(void) const ulong InvocationCommand(void) const
These functions set and return information about the BMessage that the BListView posts when an item is 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.
The BListView treats the BMessage as its "invocation message," a model for the message it posts when an item in the list is invoked. The Invoke() function makes a copy of the model and adds two pieces of relevant information. It then posts the copy, not the original.
The added information identifies the BListView and the invoked item:
Data name | Type code | Description |
---|---|---|
"source" | B_OBJECT_TYPE | A pointer to the BListView object. |
"index" | B_LONG_TYPE | The index of the item that was invoked. |
These names should not be used for any data that you add to the model message.
Given this information, the message receiver can get a pointer to item data. For example:
void myWindow::MessageReceived(BMessage *message) { BListView *theList; long theIndex; char *theItem; . . . theList = (BListView *)message->FindObject("source"); if ( message->Error() == B_NO_ERROR ) { theIndex = message->FindLong("index"); if ( message->Error() == B_NO_ERROR ) { theItem = (char *)theList->ItemAt(theIndex); . . . } } . . . }
(Although not shown in this example, you might also want to use the cast_as() macro to make sure that it's safe to cast the "source" object pointer to the BListView class.)
InvocationMessage() returns a pointer to the model 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. Nor should it be posted or sent anywhere, since that would eventually free it. To get rid of the current message, pass a NULL pointer to SetInvocationMessage() .
See also: Invoke(), the BMessage class
virtual void SetSelectionMessage(BMessage *message) BMessage *SelectionMessage(void) const ulong SelectionCommand(void) const
These functions set, and return information about, the message that a BListView posts whenever one of its items is selected. They're exact counterparts to the invocation message functions described above under SetInvocationMessage(), except that the "selection message" is posted whenever an item in the list is selected, rather than when invoked. It's more common to take action (to post a message) on invoking an item than on selecting one.
The message that SetSelectionMessage() assigns to the BListView is a model for the messages that the Select() function posts. Select() copies the model and posts the copy. It adds the same two pieces of information to the copy as are added to the invocation message:
Data name | Type code | Description |
---|---|---|
"source" | B_OBJECT_TYPE | A pointer to the BListView object. |
"index" | B_LONG_TYPE | The index of the item that was selected. |
You should not use these names for data you add to the model message .
See also: Select(), SetInvocationMessage(), the BMessage class
virtual void SetSymbolSet(const char *name)
Augments its BView counterpart to recalculate the layout of the list when the symbol set changes.
See also: BView::SetSymbolSet()
virtual long SetTarget(BHandler *target) virtual long SetTarget(BLooper *target, bool targetsPreferredHandler) BHandler *Target(BLooper **looper = NULL) const
These functions set and return the object that's expected to handle messages the BListView posts (through its Select() and Invoke() functions).
The version of SetTarget() that takes a single argument sets the target BHandler object. It's successful only if it can also discern a BLooper object where the BListView can post messages so that they will be dispatched to that target. To post a message, the BListView calls the BLooper's PostMessage() function and names the target as the object that should receive the message:
theLooper->PostMessage(theMessage, target);
Therefore, the target BHandler must either:
Once it's set as the BListView's target, the BHandler must continue its association with the BLooper. If it moves to another BLooper, PostMessage() will fail.
The version of SetTarget() that takes two arguments sets the BLooper object where the BListView function should post messages. If the targetsPreferredHandler flag is FALSE, messages will be targeted to the looper object itself --it will also act as the handler. In other words, passing a BLooper and FALSE to the version of SetTarget() that takes two arguments accomplishes the same thing as simply passing the BLooper alone to the version that takes one argument. These two lines of code are equivalent:
myListView->SetTarget(someLooper, FALSE); myListView->SetTarget(someLooper);
However, if the targetsPreferredHandler flag is TRUE , messages are targeted to the looper's preferred handler (the object returned by its PreferredHandler() function). This permits the targeting decision to be made dynamically:
looper->PostMessage(theMessage, looper->PreferredHandler());
For a BWindow, the preferred handler is the current focus view. Therefore, by passing a BWindow looper and TRUE to SetTarget(),
myListView->SetTarget(someWindow, TRUE);
the BListView can be targeted to whatever BView happens to be in focus at the time an item is invoked. (Note, however, that if the looper's PreferredHandler() is NULL, the BLooper itself becomes the target, just as it would if the targetsPreferredHandler flag were FALSE.)
When successful, SetTarget() returns B_NO_ERROR . It fails and returns B_BAD_VALUE if the proposed target or looper is NULL. The one-argument version also returns B_BAD_VALUE if it can't discover a BLooper from the target handler.
Target() returns the current target and, if a pointer to a looper is provided, fills in the BLooper where the BListView will post messages. If the target BHandler is the preferred handler of the looper, Target() returns NULL . In other words, passing a BLooper and TRUE to SetTarget() causes Target() to report that there is a looper , but a NULL target; the BLooper is known, but the target BHandler is not. Passing a BLooper and FALSE to SetTarget() causes Target() to report that the same object is both looper and target.
By default (established by AttachedToWindow() ), the BWindow where the list is located acts as both BLooper and BHandler.
See also: BView::Looper(), BWindow::PreferredHandler(), Invoke() , AttachedToWindow()
The Be Book, HTML Edition, for Developer Release 8 of the Be Operating System.
Copyright © 1996 Be, Inc. All rights reserved.
Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.
Last modified September 6, 1996.