xref: /haiku/docs/user/interface/ListView.dox (revision 4cbcabff5f0612db5ec10cd62155236bf099bd07)

/*
 * Copyright 2013 Haiku Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		John Scipione, jscipione@gmail.com
 *
 * Corresponds to:
 *		headers/os/interface/ListView.h	 hrev45555
 *		src/kits/interface/ListView.cpp	 hrev45555
 */


/*!
	\file ListView.h
	\ingroup interface
	\ingroup libbe
	\brief ListView class definition.
*/


/*!
	\class BListView
	\ingroup interface
	\ingroup libbe
	\brief Displays a list of items that the user can select and invoke.

	BListView's can be one of two types set by the type parameter of the constructor:
	- \c B_SINGLE_SELECTION_LIST	Can select only one item in the list at a time.
	     This is the default.
	- \c B_MULTIPLE_SELECTION_LIST	Can select any number of items by holding down
	     Option for a discontinuous selection, or Shift for a contiguous selection.

	An example of a BListView looks like this:
	\image html BListView_example.png

	Click on an item to select it and double-click an item to invoke it. The
	BListView doesn't define what it means to "invoke" an item. See
	BListView::SetSelectionMessage() and BListView::SetInvocationMessage() to set
	a message to be set when these actions occur. You can also select and invoke
	items with keyboard keys such as the up and down arrow keys, Page Up and Page
	Down and the Enter key or Space key to invoke the item.

	This class is based on the BList class from the Support Kit and many of the
	methods it uses behave similarly.

	Although a BListView is scrollable, it doesn't provide scroll bars by itself.
	You should add the BListView as a child of a BScrollView to make it scrollable.

	The code to add a BListView to a BScrollView looks something like this:

\code
	BListView* list = new BListView(frame, "List", B_SINGLE_SELECTION_LIST);
	list->AddItem(new BStringItem("Item 1"));
	list->AddItem(new BStringItem("Item 2"));
	...
	view->AddChild(new BScrollView("scroll_view", list,
		B_FOLLOW_LEFT | B_FOLLOW_TOP, 0, false, true));
\endcode

	\see BScrollView for more information on scrolling views.
	\see BList in the Support Kit.
	\see BOutlineListView
	\see BListItem
*/


/*!
	\fn BListView::BListView(BRect frame, const char* name, list_view_type type,
		uint32 resizingMode, uint32 flags)
	\brief Creates a new list view. This is the non-layout constructor.

	\param frame The frame rectangle of the view.
	\param name The name of the view.
	\param type Whether the list view supports a single selection or multiple
	       selections.
	\param resizingMode The resizing mode flags.
	\param flags The view flags.
*/


/*!
	\fn BListView::BListView(const char* name, list_view_type type, uint32 flags)
	\brief Creates a new list view suitable as part of a layout with the specified
	       \a name, \a type, and \a flags.

	\param name The name of the view.
	\param type Whether the list view supports a single selection or multiple
	       selections.
	\param flags The view flags.
*/


/*!
	\fn BListView::BListView(list_view_type type)
	\brief Creates a new list view suitable as part of a layout.

	\param type Whether the list view supports a single selection or multiple
	       selections.
*/


/*!
	\fn BListView::BListView(BMessage* archive)
	\brief Creates a list view from an \a archive message.

	\param archive The message to create the list view from.
*/


/*!
	\fn BListView::~BListView()
	\brief Delete the list view and free the memory used.

	This method does not free the list items.
*/


/*!
	\name Archiving
*/


//! @{


/*!
	\fn BArchivable* BListView::Instantiate(BMessage* archive)
	\brief Create a new list view from the message \a archive.

	\param archive The message to create the list view from.
*/


/*!
	\fn status_t BListView::Archive(BMessage* archive, bool deep) const
	\brief Archive the list view to a message.

	\param archive The message to archive the list view to.
	\param deep \c true to archive child views.
*/


//! @}


/*!
	\name Hook methods
*/


//! @{


/*!
	\fn void BListView::Draw(BRect updateRect)
	\brief Hook method called to draw the contents of the text view.

	You should not have to call this method directly, use Invalidate() instead.

	\param updateRect The rectangular area to draw.

	\see BView::Draw()
*/


/*!
	\fn void BListView::AttachedToWindow()
	\brief Hook method called when the list view is added to the view hierarchy.

	\see BView::AttachedToWindow()
*/


/*!
	\fn void BListView::DetachedFromWindow()
	\brief Hook method that is called when the list view is removed from the
	       view hierarchy.

	\see BView::DetachedFromWindow()
*/


/*!
	\fn void BListView::AllAttached()
	\brief Hook method called once all views are attached to the view.

	\see BView::AllAttached()
*/


/*!
	\fn void BListView::AllDetached()
	\brief Hook method called once all views are detached from the view.

	\see BView::AllDetached()
*/


/*!
	\fn void BListView::FrameResized(float width, float height)
	\brief Hook method called when the list view is resized.

	\param width The new \a width of the list view.
	\param height The new \a height of the list view.

	\see BView::FrameResized()
*/


/*!
	\fn void BListView::FrameMoved(BPoint new_position)
	\brief Hook method called when the list view is moved.

	\param new_position The list view's new position.
*/


/*!
	\fn void BListView::TargetedByScrollView(BScrollView *view)
	\brief Hook method called when the list view is attached to a BScrollView.

	\param view The BScrollView the list view is attached to.
*/


/*!
	\fn void BListView::WindowActivated(bool state)
	\brief Hook method that is called when the window becomes the active window
	       or gives up that status.

	\param state If \c true, window has just been activated. If \c false the
	       window has just been deactivated.

	\see BView::WindowActivated()
*/


/*!
	\fn void BListView::MessageReceived(BMessage* message)
	\brief Hook method called with a message is received by the list view.

	\param message The message received by the list view.

	\see BView::MessageReceived()
*/


/*!
	\fn void BListView::KeyDown(const char* bytes, int32 numBytes)
	\brief Hook method that is called when a key is pressed while the view is
	       the focus view of the active window.

	The following keys are used by the list view by default:
	- Up Arrow				Selects the previous item.
	- Down Arrow			Selects the next item.
	- Page Up				Selects the item one view height above the current item.
	- Page Down				Selects the item one view height below the current item.
	- Home					Selects the first item in the list.
	- End					Select the last item in the list.
	- Enter and Spacebar	Invokes the currently selected item.

	\param bytes The \a bytes representing the keys pushed down.
	\param numBytes The size of \a bytes.

	\see BView::KeyDown()
*/


/*!
	\fn void BListView::KeyUp(const char* bytes, int32 numBytes)
	\brief Hook method that is called when a keyboard key is released.

	\param bytes The \a bytes representing the keys released.
	\param numBytes The size of \a bytes.

	\see BView::KeyUp()
*/


/*!
	\fn void BListView::MouseDown(BPoint point)
	\brief Hook method that is called when a mouse button is pushed down while
	       the cursor is contained in the view.

	By default this method selects items on a single click, and invokes them on a
	double click. This method calls InitiateDrag() to allow derived classes the
	opportunity to drag and drop items from the list.

	\param point The \a point where the mouse button was pushed down.

	\see BView::MouseDown()
*/


/*!
	\fn void BListView::MouseUp(BPoint where)
	\brief Hook method that is called when a mouse button is released while
	       the cursor is contained in the view.

	\param where The location that the mouse button was released.

	\see BView::MouseUp()
*/


/*!
	\fn void BListView::MouseMoved(BPoint where, uint32 code,
		const BMessage* dragMessage)
	\brief Hook method that is called whenever the mouse cursor enters, exits
	       or moves inside the list view.

	\param where The point where the mouse cursor has moved to.
	\param code A code which indicating if the mouse entered or exited the view.
	\param dragMessage A message containing drag and drop information.

	\see BView::MouseMoved()
*/


/*!
	\fn bool BListView::InitiateDrag(BPoint point, int32 index, bool wasSelected)
	\brief Hook method called when a drag and drop operation is initiated.

	This method is used by derived classes to implement drag and drop. This method
	is called by the MouseDown() method. If the derived class initiates the drag &
	drop operation you should return \c true, otherwise return \c false. By default
	this method returns \c false.

	\param point Where the drag & drop operation started.
	\param index
	\param wasSelected Indicates whether or not the item was selected.

	\returns \c true if a drag & drop operation was initiated, \c false if not.
*/


/*!
	\fn void BListView::SelectionChanged()
	\brief Hook method that is called when the selection changes.

	This method should be implemented by derived classes, the default
	implementation does nothing.
*/


//! @}


/*!
	\name Resize methods
*/


//! @{


/*!
	\fn void BListView::ResizeToPreferred()
	\brief Resize the view to it's preferred size.

	\see BView::ResizeToPreferred()
*/


/*!
	\fn void BListView::GetPreferredSize(float *_width, float *_height)
	\brief Fill out the \a _width and \a _height parameters with the preferred
	       width and height of the list view.

	\param _width The list view's preferred width is written to \a _width.
	\param _height The list view's preferred height is written to \a _height.

	\see BView::GetPreferredSize()
*/


/*!
	\fn BSize BListView::MinSize()
	\brief Returns the minimum size of the list view.

	\return The minimum size of the list view as a BSize.

	\see BView::MinSize()
*/


/*!
	\fn BSize BListView::MaxSize()
	\brief Returns the maximum size of the list view.

	\return The maximum size of the list view as a BSize.

	\see BView::MaxSize()
*/


/*!
	\fn BSize BListView::PreferredSize()
	\brief Returns the preferred size of the list view.

	\return The preferred size of the list view as a BSize.

	\see BView::PreferredSize()
*/


//! @}


/*!
	\fn void BListView::MakeFocus(bool focused)
	\brief Highlight or unhighlight the selection when the list view acquires
		or loses its focus state.

	\param focused \c true to receive focus or \c false to lose it.

	\see BView::MakeFocus()
*/


/*!
	\fn void BListView::SetFont(const BFont* font, uint32 mask)
	\brief Sets the font of the list view to \a font with the font parameters set
	       by \a mask.

	\param font The \a font to set the list view to.
	\param mask A \a mask indicating which properties of \a font to set.

	\see BView::SetFont()
*/


/*!
	\fn void BListView::ScrollTo(BPoint point)
	\brief Scroll the view to the specified \a point.

	\param point The location to scroll the list view to.

	\see BView::ScrollTo()
*/


/*!
	\name Add and remove item methods
*/


//! @{


/*!
	\fn bool BListView::AddItem(BListItem *item, int32 index)
	\brief Add an \a item to the list view at the specified \a index.

	\param item The list item to add.
	\param index The \a index of where to add the list item, if not specified the
	       item is added to the end.

	\return \c true if the list item was added, \c false otherwise.
*/


/*!
	\fn bool BListView::AddList(BList* list, int32 index)
	\brief Add a \a list of list items to the list view at the specified \a index.

	\param list The \a list of list items to add.
	\param index The \a index of where to add the list, if not specified the
	       \a list is added to the end.

	\return \c true if the \a list was added, \c false otherwise.
*/


/*!
	\fn bool BListView::AddList(BList* list)
	\fn Add a \a list of list items to the end of the list view.

	\param list The \a list of list items to add.

	\return \c true if the \a list was added, \c false otherwise.
*/


/*!
	\fn BListItem* BListView::RemoveItem(int32 index)
	\brief Remove the item at \a index from the list.

	\param index The \a index of the item to remove.

	\return \c true if the item was removed, \c false otherwise.
*/


/*!
	\fn bool BListView::RemoveItem(BListItem* item)
	\brief Remove the specified list item.

	\param item The list item to remove.

	\return \c true if the \a item was removed, \c false otherwise.
*/


/*!
	\fn bool BListView::RemoveItems(int32 index, int32 count)
	\brief Removes the items from \a index and the next \a count items.

	\param index The location to start removing items from.
	\param count The number of items past \a index to remove.

	return \c true if the \a items were removed, \c false otherwise.
*/


//! @}


/*!
	\name Selection and Invocation message methods
*/


//! @{


/*!
	\fn void BListView::SetSelectionMessage(BMessage* message)
	\brief Sets the \a message that the list view sends when a new item is selected.

	\param message The selection \a message to set.
*/


/*!
	\fn void BListView::SetInvocationMessage(BMessage* message)
	Sets the \a message that the list view sends when an item is invoked.

	\param message The invocation \a message to set.

	\see BInvoker::SetMessage()
*/


/*!
	\fn BMessage* BListView::InvocationMessage() const
	\brief Returns the message that is send when an item is invoked.

	\return The current invocation method as a BMessage.

	\see BInvoker::Message()
*/


/*!
	\fn uint32 BListView::InvocationCommand() const
	\brief Returns the what parameter of the current invocation method.

	\returns The what parameter of the currently set invocation method.

	\see BInvoker::Command()
*/


/*!
	\fn BMessage* BListView::SelectionMessage() const
	\brief Returns the message that is send when an item is selected.

	\return The current selection message as a BMessage.
*/


/*!
	\fn uint32 BListView::SelectionCommand() const
	\brief Returns the what parameter of the message that is send when an item is
	       selected.

	\return The what parameter of the current selection message.
*/


//! @}


/*!
	\name List type methods
*/


//! @{


/*!
	\fn void BListView::SetListType(list_view_type type)
	\brief Sets the list view \a type.

	\param type The list view \a type to set.
*/


/*!
	\fn list_view_type BListView::ListType() const
	\brief Returns the current list view type.

	\return The list view type.
*/


//! @}


/*!
	\name List methods
*/


//! @{


/*!
	\fn BListItem* BListView::ItemAt(int32 index) const
	\brief Returns the list item at the specified \a index.

	\param index

	\return The list item at the specified \a index.
*/


/*!
	\fn int32 BListView::IndexOf(BListItem* item) const
	\brief Returns the index of the specified \a item.

	\param item The list item to get the index of.

	\return The index of the specified \a item.
*/


/*!
	\fn int32 BListView::IndexOf(BPoint point) const
	\brief Returns the index of the item at the specified \a point.

	\param point The location of the list item to get the index of.

	\return The index of the list item at the specified \a point.
*/


/*!
	\fn BListItem* BListView::FirstItem() const
	\brief Returns the first list item.

	\return The first item in the list.
*/


/*!
	\fn BListItem* BListView::LastItem() const
	\brief Returns the last list item.

	\return The last item in the list.
*/


/*!
	\fn bool BListView::HasItem(BListItem *item) const
	\brief Returns whether or not the list contains the specified \a item.

	\param item The list item to check.

	\return \c true if the list item is contained in the list view, \c false
	        otherwise.
*/


/*!
	\fn int32 BListView::CountItems() const
	\brief Returns the number of list items contained in the list view.

	\return The number of list items.
*/


/*!
	\fn void BListView::MakeEmpty()
	\brief Empties the list view of all list items.
*/


/*!
	\fn bool BListView::IsEmpty() const
	\brief Returns whether or not the list view is empty or not.

	\return \c true if the list view was empty, \c false otherwize.
*/


/*!
	\fn void BListView::DoForEach(bool (*func)(BListItem*))
	\brief Calls the specified function on each item in the list.

	The \a func is called on the items in order starting with the item at index 0
	and ending at the last item in the list. This method stops calling the \a func
	once it returns \a true or the end of the list is reached.

	The first argument of \a func is a pointer to the list item.

	\param func The function to call on each item.
*/


/*!
	\fn void BListView::DoForEach(bool (*func)(BListItem*, void*), void* arg)
	\brief Calls the specified function on each item in the list.

	The \a func is called on the items in order starting with the item at index 0
	and ending at the last item in the list. This method stops calling the \a func
	once it returns \a true or the end of the list is reached.

	The first argument of \a func is a pointer to the list item, \a arg is passed in
	as the second argument.

	\param func The function to call on each item.
*/


/*!
	\fn const BListItem** BListView::Items() const
	\brief Returns a pointer to the list of list items.

	\returns a pointer to the list of list items.
*/


//! @}


/*!
	\fn void BListView::InvalidateItem(int32 index)
	\brief Draws the list item at the specified \a index.

	\param index The \a index of the list item to draw.
*/


/*!
	\name Selection methods
*/


//! @{


/*!
	\fn void BListView::ScrollToSelection()
	\brief Scrolls to selected list item.
*/


/*!
	\fn void BListView::Select(int32 index, bool extend)
	\brief Selects the list item at the specified \a index.

	\param index The \a index of the item to select.
	\param extend Whether or not to also select child items.
*/


/*!
	\fn void BListView::Select(int32 start, int32 finish, bool extend)
	\brief Select items from \a start to \a finish.

	\param start The index of the item to start the selection.
	\param finish The index of the item to end the selection.
	\param extend Whether or not to also select child items.
*/


/*!
	\fn bool BListView::IsItemSelected(int32 index) const
	\brief Returns whether or not the item at \a index is selected.

	\return \c true if the item was selected, \c false otherwise.
*/


/*!
	\fn int32 BListView::CurrentSelection(int32 index) const
	\brief Returns the index of a currently selected item relative to the passed
	       in \a index.

	If the index of the selected item is lower than \a index the value returned
	is negative, if the index of the selected item is greater than \a index the
	value returned is positive. If the index of the selected item is equal to
	\a index then 0 is returned.

	\brief index The \a index of the item to get relative to the selected item's
	       index.
*/


//! @}


/*!
	\fn status_t BListView::Invoke(BMessage* message)
	\brief Invoke the list view, either with the current invocation message or
	       \a message if it is specified.

	\param message The message to send or \c NULL to send the current invocation
	       message.

	\see BControl::Invoke()
*/


/*!
	\name Deselection methods
*/


//! @{


/*!
	\fn void BListView::DeselectAll()
	\brief Deselect all items.
*/


/*!
	\fn void BListView::DeselectExcept(int32 exceptFrom, int32 exceptTo)
	\brief Deselect all items except the items with index in the range of
	       \a exceptFrom to \a exceptTo.

	\param exceptFrom The index of the start of the exception list.
	\param exceptTo The index of the end of the exception list.
*/


/*!
	\fn void BListView::Deselect(int32 index)
	\brief Deselect the item at \a index.

	\param index The \a index of the item to deselect.
*/


//! @}


/*!
	\fn void BListView::SortItems(int (*cmp)(const void *, const void *))
	\brief sort the items according the the passed in \a cmp function.

	\param cmp The compare function to use to sort the items.
*/


/*!
	\fn bool BListView::SwapItems(int32 a, int32 b)
	\brief Swap item \a a with item \a b.

	\param a The index of the first item to swap.
	\param b The index of the second item to swap.

	\return \c true if the items were swapped, \c false otherwise.
*/


/*!
	\fn bool BListView::MoveItem(int32 from, int32 to)
	\brief Move the item at index \a from to the position in the list at index \a to.

	\param from The index of the item to move.
	\param to The index to move the item to.

	\return \c true if the item was moved, \c false otherwise.
*/


/*!
	\fn bool BListView::ReplaceItem(int32 index, BListItem* item)
	\brief Replace the item at index \a index with \a item.

	\param index The \a index of the item to replace.
	\param item The \a item to replace the item at \a index with.

	\return \c true if the item was replaced, \c false otherwise.
*/


/*!
	\fn BRect BListView::ItemFrame(int32 index)
	\brief Return the frame of the item at the specified \a index.

	\param index The \a index of the item to get the frame of.

	\returns The frame of the item at \a index.
*/


/*!
	\fn BHandler* BListView::ResolveSpecifier(BMessage* message, int32 index,
		BMessage* specifier, int32 form, const char* property);
	\brief Returns the proper handler for the passed in scripting \a message.

	\param message The scripting message to determine the handler.
	\param index The index of the specifier.
	\param specifier The message which contains the specifier.
	\param form The 'what' field of the specifier message.
	\param property The name of the target property.

	\return The proper BHandler for the passed in scripting \a message.

	\see BView::ResolveSpecifier()
*/


/*!
	\fn status_t BListView::GetSupportedSuites(BMessage* data)
	\brief Reports the suites of messages and specifiers that derived classes
		understand.

	\param data The message to report the suite of messages and specifiers.

	\see BView::GetSupportedSuites()
*/


/*!
	\fn status_t BListView::Perform(perform_code code, void* _data)
	\brief Performs an action give a perform_code and data. (Internal Method)

	\param code The perform code
	\param _data A pointer to some data to perform on

	\return A status code.

	\see BView::Perform()
*/