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

/*
 * Copyright 2014 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

	\since BeOS R3
*/


/*!
	\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. See BView for details.
	\param flags The view flags. See BView for details.

	\since BeOS R3
*/


/*!
	\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. See BView for details.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\fn BListView::BListView(BMessage* archive)
	\brief Creates a BListView object from the \a archive message.

	\param archive The message to create the object from.

	\since BeOS R3
*/


/*!
	\fn BListView::~BListView()
	\brief Delete the BListView object and free the memory used by it.

	This method does not free the attached list items.

	\since BeOS R3
*/


/*!
	\name Archiving
*/


//! @{


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

	\copydetails BView::Instantiate()
*/


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

	\copydetails BView::Archive()
*/


//! @}


/*!
	\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()

	\since BeOS R3
*/


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

	\copydetails BView::AttachedToWindow()
*/


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

	\copydetails BView::DetachedFromWindow()
*/


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

	\copydetails BView::AllAttached()
*/


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

	\copydetails BView::AllDetached()
*/


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

	\copydetails BView::FrameResized()
*/


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

	\copydetails BView::FrameMoved()
*/


/*!
	\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.

	\since BeOS R3
*/


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

	\copydetails BView::WindowActivated()
*/


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

	\copydetails 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()

	\since BeOS R3
*/


/*!
	\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()

	\since BeOS R3
*/


/*!
	\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()

	\since BeOS R3
*/


/*!
	\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()

	\since BeOS R3
*/


/*!
	\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
	         otherwise.

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


//! @}


/*!
	\name Resizing
*/


//! @{


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

	\see BView::ResizeToPreferred()

	\since BeOS R3
*/


/*!
	\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()

	\since BeOS R3
*/


/*!
	\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()

	\since Haiku R1
*/


/*!
	\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()

	\since Haiku R1
*/


/*!
	\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()

	\since Haiku R1
*/


//! @}


/*!
	\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()

	\since BeOS R3
*/


/*!
	\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()

	\since BeOS R3
*/


/*!
	\name Scrolling
*/


//! @{


/*!
	\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()

	\since BeOS R3
*/


/*!
	\fn void BListView::ScrollTo(int32 index)
	\brief Scrolls to list item at \a index.

	If above top scroll to first item, if below bottom
	scroll to last item otherwise scroll to item at \a index.

	\see IndexOf(), MouseMoved(), ScrollToSelection()

	\since Haiku R1
*/


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

	\since BeOS R3
*/


//! @}


/*!
	\name Adding/Removing Items
*/


//! @{


/*!
	\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.

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


/*!
	\fn bool BListView::AddList(BList* list)
	\brief 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.

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


//! @}


/*!
	\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.

	\since BeOS R3
*/


/*!
	\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()

	\since BeOS R3
*/


/*!
	\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()

	\since BeOS R3
*/


/*!
	\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()

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


//! @}


/*!
	\name List Type Methods
*/


//! @{


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


	\since BeOS R3
	\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.

	\since BeOS R3
*/


//! @}


/*!
	\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.

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


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

	\return A pointer to the first item in the list or \c NULL if there are no items.

	\since BeOS R3
*/


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

	\return A pointer to the last item in the list or \c NULL if there are no items.

	\since BeOS R3
*/


/*!
	\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 \a item is in the list, \c false otherwise.

	\since BeOS R3
*/


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

	\return The number of items.

	\since BeOS R3
*/


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

	\since BeOS R3
*/


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

	\return \c true if the list view is empty, \c false otherwise.

	\since BeOS R3
*/


/*!
	\fn void BListView::DoForEach(bool (*func)(BListItem* item))
	\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.

	\since BeOS R3
*/


/*!
	\fn void BListView::DoForEach(bool (*func)(BListItem* item, void* arg),
		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.
	\param arg The second argument of the function.

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


//! @}


/*!
	\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.

	\since Haiku R1
*/


/*!
	\name Selection
*/


//! @{


/*!
	\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.

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


/*!
	\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.

	\param index The \a index of the item to get relative to the selected item's
	       index.

	\since BeOS R3
*/


//! @}


/*!
	\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()

	\since BeOS R3
*/


/*!
	\name Deselection
*/


//! @{


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

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


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

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

	\since BeOS R3
*/


//! @}


/*!
	\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.

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


/*!
	\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.

	\since BeOS R3
*/


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

	\copydetails BView::ResolveSpecifier()
*/


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

	\copydetails BView::GetSupportedSuites()
*/


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

	\copydetails BHandler::Perform()
*/


/*!
	\fn bool BListView::DoMiscellaneous(MiscCode code, MiscData* data)
	\brief Do a miscellaneous action.

	\param code The action \a code to use.
		- \c B_NO_OP: Do nothing
		- \c B_REPLACE_OP: Replace the item in \a data
		- \c B_MOVE_OP: Move the item in \a data.
		- \c B_SWAP_OP: Swap the items in \a data.
	\param data The \a data to act on.

	\since Haiku R1
*/