kzu_virtual_item_list.h File Reference

Virtual item list. More...

#include <system/debug/kzs_error.h>
#include <system/kzs_types.h>
#include <system/kzs_header.h>

Data Structures
struct	KzuVirtualItemIterator
	Iterator for KzuVirtualItemList. More...
struct	KzuVirtualItemIntervalIterator
	Interval iterator for KzuVirtualItemList. More...

Typedefs
typedef kzFloat(*	KzuVirtualItemWidthFunction )(const struct KzcVector3 *size, void *userData)
	Function that returns a one-dimensional width of a virtual item, based on it's dimensions. More...
typedef kzsError(*	KzuVirtualItemSizeFunction )(kzUint index, void *userData, struct KzcVector3 *out_size)
	Function that returns size of an item in the list box. More...
typedef kzUint(*	KzuVirtualItemCountFunction )(void *userData)
	Function that returns item count of a list box. More...

Enumerations
enum	KzuVirtualItemListDirectionPreference { KZU_VIRTUAL_ITEM_LIST_PREFER_PREVIOUS, KZU_VIRTUAL_ITEM_LIST_PREFER_NEXT }
	Preferred element when exact match cannot be found. More...

Functions
kzBool	kzuVirtualItemIteratorIsValid (const struct KzuVirtualItemIterator *iterator)
	Returns whether the virtual item iterator is valid. More...
void	kzuVirtualItemIteratorInvalidate (struct KzuVirtualItemIterator *iterator)
	Sets the iterator invalid. More...
kzsError	kzuVirtualItemIteratorUpdateWidth (struct KzuVirtualItemIterator *iterator)
	Asks the iterator to update its width. More...
kzFloat	kzuVirtualItemIteratorGetRightEdge (const struct KzuVirtualItemIterator *iterator)
	Gets offset of the right edge of the item pointed by the the iterator. More...
kzFloat	kzuVirtualItemIteratorGetCenter (const struct KzuVirtualItemIterator *iterator)
	Gets offset of the center of the item pointed by the iterator. More...
kzFloat	kzuVirtualItemIteratorGetLeftEdge (const struct KzuVirtualItemIterator *iterator)
	Gets offset of the left edge of the item pointed by the iterator. More...
kzUint	kzuVirtualItemIteratorGetIndex (const struct KzuVirtualItemIterator *iterator)
	Gets index of the item pointed by the iterator. More...
kzBool	kzuVirtualItemIteratorHasNext (const struct KzuVirtualItemIterator *iterator)
	Returns whether the iterator has a next item. More...
kzBool	kzuVirtualItemIteratorHasPrevious (const struct KzuVirtualItemIterator *iterator)
	Returns whether the iterator has a previous item. More...
kzUint	kzuVirtualItemIteratorGetNextIndex (const struct KzuVirtualItemIterator *iterator)
	Gets index of the item after the item pointed by the iterator. More...
kzUint	kzuVirtualItemIteratorGetPreviousIndex (const struct KzuVirtualItemIterator *iterator)
	Gets index of the item before the item pointed by the iterator. More...
kzsError	kzuVirtualItemIteratorNext (struct KzuVirtualItemIterator *iterator)
	Iterates to the next item. More...
kzsError	kzuVirtualItemIteratorPrevious (struct KzuVirtualItemIterator *iterator)
	Iterates to the previous item. More...
kzsError	kzuVirtualItemIteratorIterateToOffset (struct KzuVirtualItemIterator *iterator, kzFloat target, enum KzuVirtualItemListDirectionPreference directionPreference)
	Iterates the iterator such that the target offset is between iterator's left and right edges. More...
kzsError	kzuVirtualItemIteratorPatchItemAdded (struct KzuVirtualItemIterator *iterator, kzUint addedItemIndex, const struct KzcVector3 *addedItemSize)
	Patches the iterator to be consistent after an item addition. More...
kzsError	kzuVirtualItemIteratorPatchItemRemoved (struct KzuVirtualItemIterator *iterator, kzUint removedItemIndex, const struct KzcVector3 *removedItemSize)
	Patches the iterator to be consistent after an item addition. More...
kzsError	kzuVirtualItemIteratorPatchItemReplaced (struct KzuVirtualItemIterator *iterator, kzUint replacedItemIndex, const struct KzcVector3 *removedItemSize, const struct KzcVector3 *addedItemSize)
	Patches the iterator to be consistent after an item addition. More...
kzsError	kzuVirtualItemIteratorPatchSpacingChanged (struct KzuVirtualItemIterator *iterator, kzFloat oldSpacing)
	Patches the iterator to be consistent after a spacing change. More...
kzBool	kzuVirtualItemIntervalIteratorIsValid (const struct KzuVirtualItemIntervalIterator *iterator)
	Returns whether the virtual item iterator is valid. More...
void	kzuVirtualItemIntervalIteratorInvalidate (struct KzuVirtualItemIntervalIterator *iterator)
	Sets the iterator invalid. More...
struct KzuVirtualItemIterator	kzuVirtualItemIntervalIteratorGetLeftIterator (const struct KzuVirtualItemIntervalIterator *iterator)
	Returns a copy of the interval iterator's first edge iterator. More...
struct KzuVirtualItemIterator	kzuVirtualItemIntervalIteratorGetRightIterator (const struct KzuVirtualItemIntervalIterator *iterator)
	Returns a copy of the interval iterator's right edge iterator. More...
kzsError	kzuVirtualItemIntervalIteratorIterateToOffset (struct KzuVirtualItemIntervalIterator *iterator, kzFloat leftTarget, enum KzuVirtualItemListDirectionPreference leftDirectionPreference, kzFloat rightTarget, enum KzuVirtualItemListDirectionPreference rightDirectionPreference)
	Iterates the interval iterator's ends such that the left target offset will be between left iterator's left and right edges, and the right target offset will be between right iterator's left and right edges. More...
kzUint	kzuVirtualItemIntervalIteratorGetElementCount (const struct KzuVirtualItemIntervalIterator *iterator)
	Returns the number of elements in the interval, including the edge elements. More...
kzsError	kzuVirtualItemIntervalIteratorPatchItemAdded (struct KzuVirtualItemIntervalIterator *iterator, kzUint addedItemIndex, const struct KzcVector3 *addedItemSize)
	Patches the interval iterator to be consistent after an item addition. More...
kzsError	kzuVirtualItemIntervalIteratorPatchItemRemoved (struct KzuVirtualItemIntervalIterator *iterator, kzUint removedItemIndex, const struct KzcVector3 *removedItemSize)
	Patches the interval iterator to be consistent after an item removal. More...
kzsError	kzuVirtualItemIntervalIteratorPatchItemReplaced (struct KzuVirtualItemIntervalIterator *iterator, kzUint replacedItemIndex, const struct KzcVector3 *removedItemSize, const struct KzcVector3 *addedItemSize)
	Patches the interval iterator to be consistent after an item replacement. More...
kzsError	kzuVirtualItemIntervalIteratorPatchSpacingChanged (struct KzuVirtualItemIntervalIterator *iterator, kzFloat oldSpacing)
	Patches the interval iterator to be consistent after a spacing change. More...
kzsError	kzuVirtualItemListCreate (const struct KzcMemoryManager *memoryManager, KzuVirtualItemWidthFunction widthFunction, void *widthFunctionUserData, KzuVirtualItemSizeFunction sizeFunction, void *sizeFunctionUserData, KzuVirtualItemCountFunction countFunction, void *countFunctionUserData, struct KzuVirtualItemList **out_itemList)
	Creates a virtual item list that uses the given list box to provide item data. More...
kzsError	kzuVirtualItemListDelete (struct KzuVirtualItemList *itemList)
	Deletes a virtual item list. More...
void	kzuVirtualItemListSetLooping (struct KzuVirtualItemList *itemList, kzBool looping)
	Sets whether the virtual item list is looping. More...
kzBool	kzuVirtualItemListIsLooping (const struct KzuVirtualItemList *itemList)
	Gets whether the virtual item list is looping. More...
void	kzuVirtualItemListSetSpacing (struct KzuVirtualItemList *itemList, kzFloat spacing)
	Sets spacing between items in the virtual item list. More...
kzFloat	kzuVirtualItemListGetSpacing (const struct KzuVirtualItemList *itemList)
	Gets spacing between items in the virtual item list. More...
kzUint	kzuVirtualItemListGetIntervalElementCount (const struct KzuVirtualItemIterator *leftIterator, const struct KzuVirtualItemIterator *rightIterator)
	Gets the number of elements that are in between the left and right iterators, including the iterators. More...
kzBool	kzuVirtualItemListGetPeriodLength (const struct KzuVirtualItemList *itemList, kzFloat *out_period)
	Gets period length of virtual item list if it is known. More...
kzsError	kzuVirtualItemListGetIterator (struct KzuVirtualItemList *itemList, struct KzuVirtualItemIterator *out_iterator)
	Gets an iterator to the virtual item list. More...
kzsError	kzuVirtualItemListGetIntervalIterator (struct KzuVirtualItemList *itemList, struct KzuVirtualItemIntervalIterator *out_iterator)
	Gets an interval iterator to the virtual item list. More...

Detailed Description

Virtual item list.

Provides a list-like interface to a virtual collection of virtual items.

Copyright 2008-2019 by Rightware. All rights reserved.

Typedef Documentation

typedef kzFloat(* KzuVirtualItemWidthFunction)(const struct KzcVector3 *size, void *userData)

Function that returns a one-dimensional width of a virtual item, based on it's dimensions.

As an example, if used in a horizontal layout the function should return object's width. This value is used for determining how much space an item will need in the virtual item list.

typedef kzsError(* KzuVirtualItemSizeFunction)(kzUint index, void *userData, struct KzcVector3 *out_size)

Function that returns size of an item in the list box.

typedef kzUint(* KzuVirtualItemCountFunction)(void *userData)

Function that returns item count of a list box.

Enumeration Type Documentation

enum KzuVirtualItemListDirectionPreference

Preferred element when exact match cannot be found.

Enumerator
KZU_VIRTUAL_ITEM_LIST_PREFER_PREVIOUS	Prefer previous element.
KZU_VIRTUAL_ITEM_LIST_PREFER_NEXT	Prefer next element.

Function Documentation

kzBool kzuVirtualItemIteratorIsValid

(

const struct KzuVirtualItemIterator *

iterator)

Returns whether the virtual item iterator is valid.

void kzuVirtualItemIteratorInvalidate

(

struct KzuVirtualItemIterator *

iterator)

Sets the iterator invalid.

kzsError kzuVirtualItemIteratorUpdateWidth

(

struct KzuVirtualItemIterator *

iterator)

Asks the iterator to update its width.

kzFloat kzuVirtualItemIteratorGetRightEdge

(

const struct KzuVirtualItemIterator *

iterator)

Gets offset of the right edge of the item pointed by the the iterator.

kzFloat kzuVirtualItemIteratorGetCenter

(

const struct KzuVirtualItemIterator *

iterator)

Gets offset of the center of the item pointed by the iterator.

kzFloat kzuVirtualItemIteratorGetLeftEdge

(

const struct KzuVirtualItemIterator *

iterator)

Gets offset of the left edge of the item pointed by the iterator.

kzUint kzuVirtualItemIteratorGetIndex

(

const struct KzuVirtualItemIterator *

iterator)

Gets index of the item pointed by the iterator.

kzBool kzuVirtualItemIteratorHasNext

(

const struct KzuVirtualItemIterator *

iterator)

Returns whether the iterator has a next item.

kzBool kzuVirtualItemIteratorHasPrevious

(

const struct KzuVirtualItemIterator *

iterator)

Returns whether the iterator has a previous item.

kzUint kzuVirtualItemIteratorGetNextIndex

(

const struct KzuVirtualItemIterator *

iterator)

Gets index of the item after the item pointed by the iterator.

kzUint kzuVirtualItemIteratorGetPreviousIndex

(

const struct KzuVirtualItemIterator *

iterator)

Gets index of the item before the item pointed by the iterator.

kzsError kzuVirtualItemIteratorNext

(

struct KzuVirtualItemIterator *

iterator)

Iterates to the next item.

kzsError kzuVirtualItemIteratorPrevious

(

struct KzuVirtualItemIterator *

iterator)

Iterates to the previous item.

kzsError kzuVirtualItemIteratorIterateToOffset	(	struct KzuVirtualItemIterator *	iterator,
		kzFloat	target,
		enum KzuVirtualItemListDirectionPreference	directionPreference
	)

Iterates the iterator such that the target offset is between iterator's left and right edges.

If this is not possible, prefers the item in the preferred direction.

kzsError kzuVirtualItemIteratorPatchItemAdded	(	struct KzuVirtualItemIterator *	iterator,
		kzUint	addedItemIndex,
		const struct KzcVector3 *	addedItemSize
	)

Patches the iterator to be consistent after an item addition.

kzsError kzuVirtualItemIteratorPatchItemRemoved	(	struct KzuVirtualItemIterator *	iterator,
		kzUint	removedItemIndex,
		const struct KzcVector3 *	removedItemSize
	)

Patches the iterator to be consistent after an item addition.

kzsError kzuVirtualItemIteratorPatchItemReplaced	(	struct KzuVirtualItemIterator *	iterator,
		kzUint	replacedItemIndex,
		const struct KzcVector3 *	removedItemSize,
		const struct KzcVector3 *	addedItemSize
	)

Patches the iterator to be consistent after an item addition.

kzsError kzuVirtualItemIteratorPatchSpacingChanged	(	struct KzuVirtualItemIterator *	iterator,
		kzFloat	oldSpacing
	)

Patches the iterator to be consistent after a spacing change.

kzBool kzuVirtualItemIntervalIteratorIsValid

(

const struct KzuVirtualItemIntervalIterator *

iterator)

Returns whether the virtual item iterator is valid.

void kzuVirtualItemIntervalIteratorInvalidate

(

struct KzuVirtualItemIntervalIterator *

iterator)

Sets the iterator invalid.

struct KzuVirtualItemIterator kzuVirtualItemIntervalIteratorGetLeftIterator

(

const struct KzuVirtualItemIntervalIterator *

iterator)

Returns a copy of the interval iterator's first edge iterator.

struct KzuVirtualItemIterator kzuVirtualItemIntervalIteratorGetRightIterator

(

const struct KzuVirtualItemIntervalIterator *

iterator)

Returns a copy of the interval iterator's right edge iterator.

kzsError kzuVirtualItemIntervalIteratorIterateToOffset	(	struct KzuVirtualItemIntervalIterator *	iterator,
		kzFloat	leftTarget,
		enum KzuVirtualItemListDirectionPreference	leftDirectionPreference,
		kzFloat	rightTarget,
		enum KzuVirtualItemListDirectionPreference	rightDirectionPreference
	)

Iterates the interval iterator's ends such that the left target offset will be between left iterator's left and right edges, and the right target offset will be between right iterator's left and right edges.

If this is not possible, prefers the items in the preferred directions.

kzUint kzuVirtualItemIntervalIteratorGetElementCount

(

const struct KzuVirtualItemIntervalIterator *

iterator)

Returns the number of elements in the interval, including the edge elements.

See Also

kzuVirtualItemListGetIntervalElementCount.

kzsError kzuVirtualItemIntervalIteratorPatchItemAdded	(	struct KzuVirtualItemIntervalIterator *	iterator,
		kzUint	addedItemIndex,
		const struct KzcVector3 *	addedItemSize
	)

Patches the interval iterator to be consistent after an item addition.

kzsError kzuVirtualItemIntervalIteratorPatchItemRemoved	(	struct KzuVirtualItemIntervalIterator *	iterator,
		kzUint	removedItemIndex,
		const struct KzcVector3 *	removedItemSize
	)

Patches the interval iterator to be consistent after an item removal.

kzsError kzuVirtualItemIntervalIteratorPatchItemReplaced	(	struct KzuVirtualItemIntervalIterator *	iterator,
		kzUint	replacedItemIndex,
		const struct KzcVector3 *	removedItemSize,
		const struct KzcVector3 *	addedItemSize
	)

Patches the interval iterator to be consistent after an item replacement.

kzsError kzuVirtualItemIntervalIteratorPatchSpacingChanged	(	struct KzuVirtualItemIntervalIterator *	iterator,
		kzFloat	oldSpacing
	)

Patches the interval iterator to be consistent after a spacing change.

kzsError kzuVirtualItemListCreate	(	const struct KzcMemoryManager *	memoryManager,
		KzuVirtualItemWidthFunction	widthFunction,
		void *	widthFunctionUserData,
		KzuVirtualItemSizeFunction	sizeFunction,
		void *	sizeFunctionUserData,
		KzuVirtualItemCountFunction	countFunction,
		void *	countFunctionUserData,
		struct KzuVirtualItemList **	out_itemList
	)

Creates a virtual item list that uses the given list box to provide item data.

Parameters

widthFunction	Returns width from an object size.
sizeFunction	Returns size of an object by index.
countFunction	Returns total item count of virtual item list.

kzsError kzuVirtualItemListDelete

(

struct KzuVirtualItemList *

itemList)

Deletes a virtual item list.

void kzuVirtualItemListSetLooping	(	struct KzuVirtualItemList *	itemList,
		kzBool	looping
	)

Sets whether the virtual item list is looping.

kzBool kzuVirtualItemListIsLooping

(

const struct KzuVirtualItemList *

itemList)

Gets whether the virtual item list is looping.

void kzuVirtualItemListSetSpacing	(	struct KzuVirtualItemList *	itemList,
		kzFloat	spacing
	)

Sets spacing between items in the virtual item list.

kzFloat kzuVirtualItemListGetSpacing

(

const struct KzuVirtualItemList *

itemList)

Gets spacing between items in the virtual item list.

kzUint kzuVirtualItemListGetIntervalElementCount	(	const struct KzuVirtualItemIterator *	leftIterator,
		const struct KzuVirtualItemIterator *	rightIterator
	)

Gets the number of elements that are in between the left and right iterators, including the iterators.

For example:

• kzuVirtualItemListGetIntervalElementCount(iterator, iterator) returns 1.
• kzuVirtualItemListGetIntervalElementCount(current, next) returns 2.

Calling this function with invalid iterators results in undefined behavior.

kzBool kzuVirtualItemListGetPeriodLength	(	const struct KzuVirtualItemList *	itemList,
		kzFloat *	out_period
	)

Gets period length of virtual item list if it is known.

Otherwise returns KZ_FALSE.

kzsError kzuVirtualItemListGetIterator	(	struct KzuVirtualItemList *	itemList,
		struct KzuVirtualItemIterator *	out_iterator
	)

Gets an iterator to the virtual item list.

The iterator will point to the first item of the list, or be invalid.

kzsError kzuVirtualItemListGetIntervalIterator	(	struct KzuVirtualItemList *	itemList,
		struct KzuVirtualItemIntervalIterator *	out_iterator
	)

Gets an interval iterator to the virtual item list.

The iterator will be an empty interval with both ends pointing to the first item of the list, or invalid.