Use the Grid List Box 3D node to create scrollable lists of 3D items arranged in a grid. More...

#include <kanzi/ui/node/grid_list_box3d.hpp>

Inheritance diagram for kanzi::GridListBox3D:

Static Public Member Functions
static GridListBox3DSharedPtr	create (Domain *domain, string_view name)
	Creates a Grid List Box 3D node.

static PropertyTypeEditorInfoSharedPtr	makeEditorInfo ()

Static Public Member Functions inherited from kanzi::GridListBoxConceptImpl< Node3D, GridListBox3D, GridListBox3DTraits >
static PropertyTypeEditorInfoSharedPtr	makeEditorInfo ()

Static Public Member Functions inherited from kanzi::ListBoxConceptImpl< TBaseClass, TDerivedClass, ListBoxTraits >
static Vector2	doMeasure (Node2D &node)

static Vector3	doMeasure (Node3D &node)

Static Public Member Functions inherited from kanzi::ListBoxConcept
static PropertyTypeEditorInfoSharedPtr	makeEditorInfo ()

Static Public Member Functions inherited from kanzi::ListBoxScrollingConcept
static PropertyTypeEditorInfoSharedPtr	makeEditorInfo ()

Static Public Member Functions inherited from kanzi::GridListBoxConcept
static PropertyTypeEditorInfoSharedPtr	makeEditorInfo ()

Protected Member Functions
	GridListBox3D (Domain *domain, string_view name)

void	initialize ()

Protected Member Functions inherited from kanzi::GridListBoxConceptImpl< Node3D, GridListBox3D, GridListBox3DTraits >
void	arrangeOverride (VectorType actualSize) override

GridListBox3D *	getThisObject ()

const GridListBox3D *	getThisObject () const

	GridListBoxConceptImpl (Domain *domain, string_view name)

void	initialize ()

void	onNodePropertyChanged (AbstractPropertyType propertyType, PropertyNotificationReason reason) override

Protected Member Functions inherited from kanzi::ListBoxConceptImpl< TBaseClass, TDerivedClass, ListBoxTraits >
void	applySelectionBehavior (size_t itemIndex, bool smooth)
	Applies selection behavior to the selected item.

void	assignItemContainerGenerator (ItemContainerGeneratorSharedPtr itemContainerGenerator)
	Assigns list box item container generator to list box.

void	assignItemGenerator (ItemGeneratorSharedPtr itemGenerator)
	Assigns list box item generator to list box.

void	initialize (PresenterSharedPtr presenter)

	ListBoxConceptImpl (Domain *domain, string_view name)

bool	listBoxContainsKeyFocus () const
	Returns whether the key focus is on the List Box node or on one of the list items.

void	onAboutToGainFocus (FocusManager::PreFocusMessageArguments &messageArguments)
	Handles FocusManager::AboutToGainFocusMessage.

void	onAttached () override
	Node::onAttached() implementation.

void	onClicked (ClickManipulator::ClickMessageArguments &messageArguments)
	Handles ClickManipulator::ClickMessage.

void	onDetached () override
	Node::onDetached() implementation.

void	onFocusGained (FocusManager::PostFocusMessageArguments &messageArguments)
	Handles FocusManager::FocusGainedMessage.

void	onNodePropertyChanged (AbstractPropertyType propertyType, PropertyNotificationReason reason) override
	Node::onNodePropertyChanged() implementation.

void	setItemContainerGeneratorByProperty ()
	Creates and assigns item container generator by ItemGeneratorTypeName property value.

void	setItemGeneratorByProperty ()
	Creates and assigns item generator by ItemGeneratorTypeName property value.

void	synchronizeFocusAndSelection (Node &selectedItemContainer)
	ListBoxConcept uses this function to update the focus in the List Box to the selected item.

void	synchronizeItemCountProperty ()
	Updates the ItemCountProperty.

void	synchronizeSelectedItemIndexProperty ()
	Updates the SelectedItemIndexProperty after the List Box internally changes the selected item index.

void	tryMoveFocusToListBox ()
	Tries to move focus to List Box node itself.

void	trySetInitialFocus ()
	Tries to move the focus to the first visible and focusable item in a List Box node that holds the key focus and has no item selected.

void	updateFocusScopeInfo (FocusScopePtr &nodeScopeInfo) override
	Overrides Node::updateFocusScopeInfo().

void	updateGenerators (ItemGeneratorSharedPtr itemGenerator, ItemContainerGeneratorSharedPtr itemContainerGenerator)
	Replaces item and item container generators with new objects. Updates items and layout accordingly.

	~ListBoxConceptImpl () override

Additional Inherited Members
Public Types inherited from kanzi::ListBoxConceptImpl< TBaseClass, TDerivedClass, ListBoxTraits >
typedef shared_ptr< DefaultListBoxItemGenerator< ItemGeneratorClass > >	DefaultItemGeneratorSharedPtr

typedef ListBoxTraits::TItemClass	ItemClass

typedef ListBoxTraits::TItemContainerClass	ItemContainerClass

typedef ListBoxTraits::TItemContainerGeneratorClass	ItemContainerGeneratorClass

typedef shared_ptr< ItemContainerGeneratorClass >	ItemContainerGeneratorSharedPtr

typedef shared_ptr< ItemContainerClass >	ItemContainerSharedPtr

typedef ListBoxTraits::TItemGeneratorClass	ItemGeneratorClass

typedef shared_ptr< ItemGeneratorClass >	ItemGeneratorSharedPtr

typedef shared_ptr< ItemClass >	ItemSharedPtr

typedef TBaseClass::LayoutVectorType	LayoutVectorType

typedef ListBoxTraits::TPresenterClass	PresenterClass

typedef shared_ptr< PresenterClass >	PresenterSharedPtr

Public Types inherited from kanzi::ListBoxConcept
enum class	FocusMoveTarget { NextItem , PreviousItem , NextPage , PreviousPage , LastItem , FirstItem }
	Specifies the targets to which the focus can move in a List Box. More...

enum	SelectionBehavior { SelectionBehaviorNone , SelectionBehaviorBringToCenter }
	Behaviors for the List Box when an item in the List Box is selected. More...

Public Types inherited from kanzi::GridListBoxConcept
enum	GridDirection { GridDirectionRight , GridDirectionDown }

Public Member Functions inherited from kanzi::GridListBoxConceptImpl< Node3D, GridListBox3D, GridListBox3DTraits >
ScrollViewSharedPtr	getScrollView () const
	Returns the Scroll View that scrolls the Grid List Box.

GridDirection	getDirection () const
	Gets the value of DirectionProperty.

void	setDirection (GridDirection value)
	Sets the value of DirectionProperty.

float	getCellWidth () const
	Gets the value of CellWidthProperty.

void	setCellWidth (float value)
	Sets the value of CellWidthProperty.

float	getCellHeight () const
	Gets the value of CellHeightProperty.

void	setCellHeight (float value)
	Sets the value of CellHeightProperty.

float	getItemAreaBegin () const
	Gets the value of ItemAreaBeginProperty.

void	setItemAreaBegin (float value)
	Sets the value of ItemAreaBeginProperty.

float	getItemAreaEnd () const
	Gets the value of ItemAreaEndProperty.

void	setItemAreaEnd (float value)
	Sets the value of ItemAreaEndProperty.

Vector2	getScrollPosition () const
	Gets the value of ScrollPositionProperty.

Vector2	getScrollTargetPosition () const
	Gets the value of ScrollTargetPositionProperty.

Vector2	getScrollSpeed () const
	Gets the value of ScrollSpeedProperty.

bool	isScrolling () const
	Gets the value of ScrollingProperty.

bool	isReversedScrolling () const
	Returns the value of ReversedScrollingProperty.

void	setReversedScrolling (bool enable)
	Sets the value of the ReversedScrollingProperty.

Public Member Functions inherited from kanzi::ListBoxConceptImpl< TBaseClass, TDerivedClass, ListBoxTraits >
bool	addContentItem (NodeSharedPtr abstractItem) override

void	addItem (ItemSharedPtr item)
	Adds an item at the end of a List Box when using the default object generator.

void	arrangeOverride (LayoutVectorType actualSize) override

void	bringItemCenter (size_t itemIndex, bool smooth)
	Requests the List Box to bring the item in the passed itemIndex to the center of the list box area.

void	enableKeyNavigation (bool enabled)
	Enables directional key navigation between focusable items in a List Box.

void	extendAliveItemsRangeToItemIndex (size_t itemIndex)
	Extends the alive items range to contain the item at a given index.

optional< pair< size_t, size_t > >	getAliveItemsRange ()
	Returns the range of list items that are alive.

NodeSharedPtr	getContentItem (size_t index) override

size_t	getContentItemCount () override

optional< size_t >	getFocusedItemIndex () const
	Returns the index of the item that holds the focus in the List Box.

ItemSharedPtr	getItem (size_t index)
	Gets the item at the given index in a List Box.

string	getItemContainerGeneratorTypeName () const
	Gets the value of ItemContainerGeneratorTypeNameProperty.

PrefabTemplateSharedPtr	getItemContainerTemplate () const
	Gets the value of ItemContainerTemplateProperty.

size_t	getItemCount () const
	Returns the value of the ItemCountProperty.

string	getItemGeneratorTypeName () const
	Gets the value of ItemGeneratorTypeNameProperty.

optional< size_t >	getItemIndex (ItemSharedPtr item)
	Returns the index of the given item. If the item does not exist, returns empty.

LayoutVectorType	getItemSize (size_t index)
	Returns the size of the item at the given index.

PrefabTemplateSharedPtr	getItemTemplate () const
	Gets the value of ItemTemplateProperty.

int	getKeepAliveItemCount () const
	Gets the value of KeepAliveItemCountProperty.

PresenterSharedPtr	getPresenter () const

int	getSelectedItemIndex () const
	Gets the value of SelectedItemIndexProperty.

SelectionBehavior	getSelectionBehavior () const
	Gets the value of SelectionBehavior.

void	insertItem (size_t index, ItemSharedPtr item)
	Inserts an item at the given index in a List Box when using the default object generator.

bool	isEmpty ()
	Indicates whether a List Box has no items.

LayoutVectorType	measureOverride (LayoutVectorType availableSize) override

void	notifyItemAdded (size_t index) override
	Virtual functions for notifying item changes to list.

void	notifyItemContainerChanged ()

void	notifyItemCountChanged () override

void	notifyItemRemoved (size_t index) override

void	notifyItemReplaced (size_t index) override

void	removeAllContentItems () override

void	removeAllItems ()
	Removes all items from a List Box when using the default object generator.

bool	removeContentItem (NodeSharedPtr abstractItem) override

void	removeItem (size_t index)
	Removes the item at the given index from a List Box when using the default object generator.

void	removeLastItem ()
	Removes the last item from a List Box when using the default object generator.

void	replaceItem (size_t index, ItemSharedPtr item)
	Replaces the item at the given index in a List Box when using the default object generator.

void	selectItem (optional< size_t > itemIndex)
	Requests the List Box to select the item at the given index.

void	setItemContainerGenerator (ItemContainerGeneratorSharedPtr itemContainerGenerator)
	Sets the list box item container generator.

void	setItemContainerGeneratorTypeName (string_view value)
	Sets the value of ItemContainerGeneratorTypeNameProperty.

void	setItemContainerTemplate (PrefabTemplateSharedPtr value)
	Sets the value of ItemContainerTemplateProperty.

void	setItemGenerator (ItemGeneratorSharedPtr itemGenerator)
	Sets the list box item generator.

void	setItemGeneratorTypeName (string_view value)
	Sets the value of ItemGeneratorTypeNameProperty.

void	setItemTemplate (PrefabTemplateSharedPtr value)
	Sets the value of ItemTemplateProperty.

void	setKeepAliveItemCount (int value)
	Sets the value of KeepAliveItemCountProperty.

void	setSelectedItemIndex (int value)
	Sets the value of SelectedItemIndexProperty.

void	setSelectionBehavior (SelectionBehavior value)
	Sets the value of SelectionBehavior.

bool	trySetFocusItem (size_t itemIndex, bool fallback)
	Tries to set the application focus to an item at a given index and brings the item alive.

void	updateAliveItemsRange (size_t beginIndex, size_t itemCount, bool sendMessages=true)
	Requests items from the item generator.

void	updateAliveItemsRangeQuiet (size_t beginIndex, size_t itemCount)
	Requests items from the item generator.

Public Member Functions inherited from kanzi::ContentItemCollectionModel
virtual	~ContentItemCollectionModel ()

Static Public Attributes inherited from kanzi::ListBoxConcept
static MessageType< ItemLoadedMessageArguments >	ItemLoadedMessage
	List Box node dispatches this message whenever the List Box loads one of its items.

static MessageType< ItemSelectedMessageArguments >	ItemSelectedMessage
	List Box node dispatches this message whenever an item in the List Box is selected.

static MessageType< ItemUnloadedMessageArguments >	ItemUnloadedMessage
	List Box node dispatches this message whenever the List Box unloads one of its items.

static PropertyType< int >	ItemCountProperty
	Reports the number of items in a List Box, including virtual items.

static PropertyType< int >	KeepAliveItemCountProperty
	Sets the size of the buffer for invisible List Box items.

static PropertyType< ListBoxConcept::SelectionBehavior >	SelectionBehaviorProperty
	Sets how a List Box node behaves when the user selects an item.

static PropertyType< string >	ItemGeneratorTypeNameProperty
	Sets the name of the item generator type to use to provide items dynamically for a List Box node.

static PropertyType< string >	ItemContainerGeneratorTypeNameProperty
	Sets the name of the item container generator type to use to provide item containers dynamically for a List Box node.

static PropertyType< ResourceSharedPtr >	ItemTemplateProperty
	Sets the prefab template to use for the List Box items.

static PropertyType< ResourceSharedPtr >	ItemContainerTemplateProperty
	Sets the ListBoxItemContainer prefab that sets the appearance and behavior of the List Box items.

static PropertyType< int >	SelectedItemIndexProperty
	Sets and reports the index of the item that is currently selected in a List Box node.

static MessageType< TrySetFocusToItemMessageArguments >	TrySetFocusToListItemMessage
	Dispatch this message to set the focus to the list item at a given index.

static MessageType< MoveFocusMessageArguments >	MoveFocusMessage
	Dispatch this message to move the focus between List Box items to a given target.

Static Public Attributes inherited from kanzi::ListBoxScrollingConcept
static MessageType< ScrolledMessageArguments >	ScrolledMessage
	List Box node dispatches this message whenever the List Box node scrolls.

static MessageType< ScrollFinishedMessageArguments >	ScrollFinishedMessage
	List Box node dispatches this message whenever the List Box stops scrolling.

static MessageType< ScrollStartedMessageArguments >	ScrollStartedMessage
	List Box node dispatches this message whenever the List Box starts to scroll.

static MessageType< TargetChangedMessageArguments >	TargetChangedMessage
	List Box node dispatches this message whenever there is a change in scroll target item in List Box.

static MessageType< UserScrollFinishedMessageArguments >	UserScrollFinishedMessage
	List Box node dispatches this message when the user stops scrolling the List Box content.

static MessageType< UserScrollStartedMessageArguments >	UserScrollStartedMessage
	List Box node dispatches this message when the user starts to scroll the List Box content.

Static Public Attributes inherited from kanzi::GridListBoxConcept
static PropertyType< GridListBoxConcept::GridDirection >	DirectionProperty
	Sets the direction in which a Grid List Box node arranges its items.

static PropertyType< float >	CellWidthProperty
	Sets the width of each cell in a Grid List Box node.

static PropertyType< float >	CellHeightProperty
	Sets the height of each cell in a Grid List Box node.

static PropertyType< float >	ItemAreaBeginProperty
	Sets the proportional offset where the area meant for the fully visible items in a Grid List Box node starts.

static PropertyType< float >	ItemAreaEndProperty
	Sets the proportional offset where the area meant for the fully visible items in a Grid List Box node ends.

static PropertyType< float >	RecognitionThresholdProperty
	Sets the distance in pixels that the pointer has to move for the scrolling to start in a Grid List Box node.

static PropertyType< int >	MinimumNumberOfTouchesProperty
	Sets the minimum number of touch points required on the Grid List Box node area for scrolling.

static PropertyType< int >	MaximumNumberOfTouchesProperty
	Sets the maximum number of touch points allowed on the Grid List Box node area for scrolling.

static PropertyType< float >	SensitivityProperty
	Sets the amount that the scroll position changes relative to the movement of the pointer.

static PropertyType< float >	SlidingAccelerationCoefficientProperty
	Sets the acceleration of a Grid List Box node after the user releases the pointer with which they scroll the Grid List Box.

static PropertyType< float >	SlidingDragCoefficientProperty
	Sets the amount that drag affects the movement of a Grid List Box node after the user releases the pointer with which they scroll the Grid List Box.

static PropertyType< float >	DraggingAccelerationCoefficientProperty
	Sets the acceleration of a Grid List Box node when the user scrolls the Grid List Box by dragging the pointer.

static PropertyType< float >	DraggingDragCoefficientProperty
	Sets the amount that drag affects the movement of a Grid List Box node when the user scrolls the Grid List Box by dragging the pointer.

static PropertyType< float >	DraggingImpulseFactorProperty
	Sets the amount of impulse to generate from the pointer movement when the user scrolls a Grid List Box node by dragging the pointer.

static PropertyType< float >	SwipeDistanceProperty
	Sets the distance that a swipe sends the scroll value in a Grid List Box node, relative to the speed of the pointer.

static PropertyType< float >	CalculatedOffsetProperty
	Reports the current relative offset of an item in a Grid List Box node in proportional range [0.0, 1.0].

static PropertyType< Vector2 >	ScrollPositionProperty
	Reports the scroll position of a Grid List Box node along the x and y axes as a relative position within the Grid List Box area.

static PropertyType< Vector2 >	ScrollTargetPositionProperty
	Reports the current target scroll value of a Grid List Box.

static PropertyType< Vector2 >	ScrollSpeedProperty
	Reports the current scroll speed of a Grid List Box.

static PropertyType< bool >	ScrollingProperty
	Indicates whether a Grid List Box is currently scrolling.

static PropertyType< bool >	ReversedScrollingProperty
	Indicates whether the change in the scroll position is reversed in relation to the direction of the pan gesture.

Static Protected Member Functions inherited from kanzi::ListBoxConceptImpl< TBaseClass, TDerivedClass, ListBoxTraits >
static PropertyTypeEditorInfoSharedPtr	makeEditorInfo ()

Protected Attributes inherited from kanzi::GridListBoxConceptImpl< Node3D, GridListBox3D, GridListBox3DTraits >
GridLayoutSharedPtr	m_layout

ConceptClass::PresenterSharedPtr	m_presenter

ScrollViewSharedPtr	m_scrollView

Detailed Description

Use the Grid List Box 3D node to create scrollable lists of 3D items arranged in a grid.

To set the size of the grid cells, use the CellWidthProperty and CellHeightProperty properties in the Grid List Box 3D node. All cells in a Grid List Box 3D node are of the same size.

The size of a Grid List Box 3D node determines the number of rows and columns: a Grid List Box 3D node shows as many cells as fit within its area. Kanzi hides the list items that are in cells that do not fit in the list box area. The user can scroll the list box to see more items. The user can temporarily drag list items out of the grid, but when the user is not providing input, the list box scrolls the items back to the grid area.

To handle input, the Grid List Box 3D internally uses ScrollView3D. To make the input work:

Position the Grid List Box 3D in front of the camera oriented so that the scroll plane is perpendicular to the camera view ray.
Set the size of the Grid List Box 3D. The scroll view uses that area to collect input.

To configure the scroll view, Kanzi internally binds the properties that you set in the Grid List Box 3D to the corresponding properties in the scroll view. You can send to a Grid List Box 3D node ScrollViewConcept messages, such as ScrollViewConcept::ScrollDownMessage, ScrollViewConcept::ScrollHomeMessage, and ScrollViewConcept::ScrollPageDownMessage.

See also: ListBoxConceptImpl

Examples

To create a Grid List Box 3D node:

// Create a Grid List Box 3D named MyListBox.

GridListBox3DSharedPtr gridListBox = GridListBox3D::create(domain, "MyListBox");

To configure the grid area:

        // Make each grid cell be a 1x1x1 cube.
        gridListBox->setCellWidth(1.0f);
        gridListBox->setCellHeight(1.0f);
        gridListBox->setDepth(1.0f);
        // Make the grid contain three rows that are filled column by column.
        gridListBox->setHeight(3.0f);
        gridListBox->setDirection(GridListBoxConcept::GridDirectionDown);
        // Make the grid contain 10 columns. Items that are dragged beyond these columns are made invisible.
        gridListBox->setWidth(10.0f);
        // Change the resting position when the list is scrolled to the beginning or end, so that items are not right at the grid edge.
        gridListBox->setItemAreaBegin(0.2f);
        gridListBox->setItemAreaEnd(0.8f);

To add items to the list box:

        // Create cube meshes and add them as items of the list box.
        // Items on the grid appear in the order you add them to the list.
        Model3DSharedPtr item1 = Model3D::createCube(domain, "item1", 1.0f, ThemeRed);
        Model3DSharedPtr item2 = Model3D::createCube(domain, "item2", 1.0f, ThemeGreen);
        Model3DSharedPtr item3 = Model3D::createCube(domain, "item3", 1.0f, ThemeBlue);
        Model3DSharedPtr item4 = Model3D::createCube(domain, "item4", 1.0f, ThemeOrange);
        Model3DSharedPtr item5 = Model3D::createCube(domain, "item5", 1.0f, ThemeYellow);
        gridListBox->addItem(item1);
        gridListBox->addItem(item2);
        gridListBox->addItem(item3);
        gridListBox->addItem(item4);
        gridListBox->addItem(item5);

Constructor & Destructor Documentation

◆ GridListBox3D()

kanzi::GridListBox3D::GridListBox3D	(	Domain *	domain,
		string_view	name )

explicitprotected

Member Function Documentation

◆ create()

static GridListBox3DSharedPtr kanzi::GridListBox3D::create	(	Domain *	domain,
		string_view	name )

static

Creates a Grid List Box 3D node.

Parameters

domain	The UI domain to which the node belongs.
name	The name of the node.

◆ makeEditorInfo()

static PropertyTypeEditorInfoSharedPtr kanzi::GridListBox3D::makeEditorInfo ( )

static

◆ initialize()

void kanzi::GridListBox3D::initialize ( )

protected

The documentation for this class was generated from the following file:

kanzi/ui/node/grid_list_box3d.hpp

Static Public Member Functions

Protected Member Functions

Additional Inherited Members