IlvListGadgetItemHolder Class Reference

Item holder class. More...

#include <ilviews/gadgets/itemgdt.h>

Inheritance diagram for IlvListGadgetItemHolder:

List of all members.

Public Member Functions
virtual void	addLabel (const char *label, IlAny data=0)
	Adds an item with a label to the holder list.
virtual IlvGadgetItem *	applyToItems (IlvApplyGadgetItem func, IlAny arg)
	Applies the specified function to all the items of the holder.
virtual int	compareItems (const char *string1, const char *string2, IlAny value1, IlAny value2)
	Compares a pair of items.
virtual void	deSelectAll ()
	Deselects all the items.
virtual void	empty ()=0
	Empties the list.
IlUShort	getCardinal () const
	Returns the number of items stored in this holder.
IlShort	getFirstSelectedItem () const
	Returns the index of the first selected item.
IlShort	getIndex (const IlvGadgetItem *item, IlUShort start=0, IlUShort stop=(IlUShort)-1) const
	Returns the index of the specified item in the holder list.
IlvGadgetItem *	getItem (IlUShort index) const
	Returns an item from its position in the holder.
IlAny	getItemData (IlUShort index) const
	Returns an item user data.
IlvGadgetItem *const *	getItems (IlUShort &count) const
	Returns the array of all the items.
const char *	getLabel (IlUShort index) const
	Returns the ith label of the list.
const char *const *	getLabels (IlUShort &count) const
	Returns an array of all the items labels.
IlShort	getPosition (const char *label, IlUShort start=0) const
	Returns the position of an item using its label.
virtual const char *	getSelection () const
	Returns the first selected item label.
IlUShort const *	getSelectionIndices (IlUShort &count) const
	Returns an array containing the indexes of the selected item.
const char *const *	getSelections (IlUShort &count) const
	Returns an array of the selected items.
IlAny const *	getUserDataArray (IlUShort &count) const
	Returns an array of all the user data for the items.
IlUShort	insertBitmap (IlvBitmap *bitmap, IlShort pos=-1)
	Inserts an item with a bitmap at the given position in the holder list.
IlUShort	insertGraphic (IlvGraphic *graphic, IlShort pos=-1)
	Inserts an item with a graphic as picture at a given position in the holder list.
IlUShort	insertItem (IlvGadgetItem *item, IlShort index=-1)
	Inserts an item at a given position in the holder's list.
virtual void	insertLabel (IlUShort pos, const char *label, IlAny data=0)
	Inserts an item with a label at a given position in the holder list.
IlBoolean	isSelected (IlUShort index) const
	Specifies whether the item whose position is specified is selected.
void	removeItem (IlUShort index, IlBoolean destroy=IlTrue)
	Removes an item from the holder.
void	removeLabel (IlUShort index)
	Removes and destroys an item.
void	setItemData (IlUShort index, IlAny itemData)
	Sets an item user data.
virtual void	setItems (IlvGadgetItem *const *items, IlUShort count)
	Replaces the entire list of items.
void	setLabel (IlUShort index, const char *label, IlBoolean copy)
	Modifies the label of an item.
virtual void	setLabels (const char *const *labels, IlUShort count, IlBoolean copy=IlTrue)
	Replaces the entire list of items.
virtual void	setLabels (const char *const *labels, IlAny const *itemData, IlUShort count, IlBoolean copy=IlTrue)
	Replaces the entire list of items.
virtual void	sort (IlvListCompareFunction func=0)
	Sorts the items.

---

Detailed Description

Item holder class.

Library: ilvgadgt

IlvListGadgetItemHolder is a specific IlvGadgetItemHolder class that manages a list of items.

See also:

IlvAbstractMenu, IlvGadgetItem, IlvStringList, IlvComboBox, IlvOptionMenu.

---

Member Function Documentation

virtual void IlvListGadgetItemHolder::addLabel	(	const char *	label,
		IlAny	data = 0
	)			[virtual]

Adds an item with a label to the holder list.

label is copied. The item is created by calling the member function IlvGadgetItemHolder::createItem.

Parameters:

	label	The item label.
	data	The item client data.

See also:

insertItem, insertLabel, insertItem, insertGraphic, insertBitmap, setItems

virtual IlvGadgetItem* IlvListGadgetItemHolder::applyToItems	(	IlvApplyGadgetItem	func,
		IlAny	arg
	)			[virtual]

Applies the specified function to all the items of the holder.

Parameters:

	func	The function to be applied.
	arg	The argument that will be passed to the function func.

Returns:

The item that stopped the operation. See IlvApplyGadgetItem for details.

See also:

IlvApplyGadgetItem, recomputeAllItems, getItemByName.

Reimplemented from IlvGadgetItemHolder.

virtual int IlvListGadgetItemHolder::compareItems	(	const char *	string1,
		const char *	string2,
		IlAny	value1,
		IlAny	value2
	)			[virtual]

Compares a pair of items.

If no sorting function is provided, this method is called to compare each item pair. This function simply returns the result of strcmp on the two item labels.

Parameters:

	string1	The label of the first item.
	string2	The label of the second item.
	value1	The client data of the first item.
	value2	The client data of the second item.

See also:

sort

virtual void IlvListGadgetItemHolder::deSelectAll

(

)

[virtual]

Deselects all the items.

See also:

IlvGadgetItem::deSelect

Reimplemented in IlvAbstractMenu.

virtual void IlvListGadgetItemHolder::empty

(

)

[pure virtual]

Empties the list.

See also:

setItems, removeItem

Implemented in IlvAbstractMenu, IlvComboBox, IlvPopupMenu, IlvOptionMenu, IlvStringList, and IlvToolBar.

IlUShort IlvListGadgetItemHolder::getCardinal

(

)

const

Returns the number of items stored in this holder.

Returns:

The number of items stored in this holder.

See also:

insertItem, removeItem, setItems

IlShort IlvListGadgetItemHolder::getFirstSelectedItem

(

)

const

Returns the index of the first selected item.

Returns:

The index of the first selected item. Returns -1 if no item is selected.

See also:

isSelected, IlvGadgetItem::isSelected

IlShort IlvListGadgetItemHolder::getIndex	(	const IlvGadgetItem *	item,
		IlUShort	start = 0,
		IlUShort	stop = (IlUShort)-1
	)			const

Returns the index of the specified item in the holder list.

Returns:

The index of item beginning the search from start. It returns -1 if the item is not in the holder list.

Parameters:

	item	The item to be retrieved.
	start	The index where to begin the search.
	stop	The index where to stop the search. The search doesn't includes the item of index stop.

See also:

getItem

IlvGadgetItem* IlvListGadgetItemHolder::getItem

(

IlUShort

index

)

const

Returns an item from its position in the holder.

Parameters:

index

The item position.

Returns:

The index^th item. Returns 0 if index is not valid.

See also:

getIndex

Reimplemented in IlvAbstractMenu.

IlAny IlvListGadgetItemHolder::getItemData

(

IlUShort

index

)

const

Returns an item user data.

Parameters:

index

The item index.

Returns:

The index ^th item user data or 0 if there is none.

See also:

setItemData, IlvGadgetItem::setClientData

IlvGadgetItem* const* IlvListGadgetItemHolder::getItems

(

IlUShort &

count

)

const

Returns the array of all the items.

Parameters:

count

The number of items in the returned array.

Returns:

The array of all the items.

Warning:

[note] The returned array should never be modified or deleted.

See also:

setItems, getItem, getIndex

Reimplemented in IlvAbstractMenu.

const char* IlvListGadgetItemHolder::getLabel

(

IlUShort

index

)

const

Returns the i^th label of the list.

Parameters:

index

The item index.

Returns:

The index ^th label of the list. The returned string should not be modified or deleted. If index is not in the holder range, 0 is returned.

Reimplemented in IlvComboBox, and IlvOptionMenu.

const char* const* IlvListGadgetItemHolder::getLabels

(

IlUShort &

count

)

const

Returns an array of all the items labels.

Parameters:

count

The number of elements of the returned array.

Returns:

An array of count strings that includes all the items stored in the object.

Warning:

[note] The returned array is a static array, managed internally. Other Rogue Wave Views routines may overwrite this buffer so it should be copied in a safe place if it needs to be persistent.

See also:

setLabels, setItems

Reimplemented in IlvStringList.

IlShort IlvListGadgetItemHolder::getPosition	(	const char *	label,
		IlUShort	start = 0
	)			const

Returns the position of an item using its label.

Parameters:

	label	The label of the searched item.
	start	The index where to begin the search.

Returns:

The position of the item with the label label, beginning the search from start. Returns -1 if the label cannot be found.

See also:

getIndex, IlvListGadgetItemHolder::getItemByName

virtual const char* IlvListGadgetItemHolder::getSelection

(

)

const [virtual]

Returns the first selected item label.

Returns:

The first selected item label. The returned string should never be modified or deleted.

See also:

getSelections, getSelectionIndices, isSelected

Reimplemented in IlvComboBox.

IlUShort const* IlvListGadgetItemHolder::getSelectionIndices

(

IlUShort &

count

)

const

Returns an array containing the indexes of the selected item.

Parameters:

count

The number of elements in the returned array.

Returns:

An array of IlUShort values that indicate the indexes of a selected item. The total number of selected items (and therefore, of valid values in the returned array) is returned in the count parameter.

Warning:

[note] The returned array is a static array, managed internally. Other Rogue Wave Views routines may overwrite this buffer so it should be copied in a safe place if it needs to be persistent.

See also:

getSelections, getFirstSelectedItem, isSelected

const char* const* IlvListGadgetItemHolder::getSelections

(

IlUShort &

count

)

const

Returns an array of the selected items.

Parameters:

count

The number of elements in the returned array.

Returns:

An array of count strings that includes all the selected items.

Warning:

[note] The returned array is a static array, managed internally. Other Rogue Wave Views routines may overwrite this buffer so it should be copied in a safe place if it needs to be persistent.

See also:

getSelectionIndices, getFirstSelectedItem, isSelected

IlAny const* IlvListGadgetItemHolder::getUserDataArray

(

IlUShort &

count

)

const

Returns an array of all the user data for the items.

Parameters:

count

The number of elements in the returned array.

Returns:

An array of all the user data for the items. On return, the count parameter is set to the total number of items in the list. If user data has never been set to an item, the return value is 0. The user must not modify or delete the returned array.

See also:

setItemData, getItemData

IlUShort IlvListGadgetItemHolder::insertBitmap	(	IlvBitmap *	bitmap,
		IlShort	pos = -1
	)

Inserts an item with a bitmap at the given position in the holder list.

The specified bitmap is locked. The item is created by calling the member function IlvGadgetItemHolder::createItem.

Parameters:

	bitmap	The item picture.
	pos	The item position. If pos is -1, the item is appended to the holder list.

Returns:

The real index where the item was inserted.

See also:

insertItem, insertGraphic, insertLabel, setItems

IlUShort IlvListGadgetItemHolder::insertGraphic	(	IlvGraphic *	graphic,
		IlShort	pos = -1
	)

Inserts an item with a graphic as picture at a given position in the holder list.

The item is created by calling the member function IlvGadgetItemHolder::createItem.

Parameters:

	graphic	The item picture.
	pos	The item position. If pos is -1, the item is appended to the holder list.

Returns:

The real index where the item was inserted.

See also:

insertItem, insertBitmap, insertLabel, setItems

IlUShort IlvListGadgetItemHolder::insertItem	(	IlvGadgetItem *	item,
		IlShort	index = -1
	)

Inserts an item at a given position in the holder's list.

Parameters:

	item	The item.
	index	The item position. If index is -1, the item is appended to the holder list.

See also:

insertBitmap, insertGraphic, InsertLabel, setItems

virtual void IlvListGadgetItemHolder::insertLabel	(	IlUShort	pos,
		const char *	label,
		IlAny	data = 0
	)			[virtual]

Inserts an item with a label at a given position in the holder list.

The item is created by calling the member function IlvGadgetItemHolder::createItem.

Parameters:

	pos	The item's position.
	label	The item label.
	data	The item client data.

See also:

addLabel, insertItem, insertGraphic, insertBitmap, setItems

IlBoolean IlvListGadgetItemHolder::isSelected

(

IlUShort

index

)

const

Specifies whether the item whose position is specified is selected.

Parameters:

index

The item index.

Returns:

IlTrue if index^th item is selected.

See also:

IlvGadgetItem::isSelected

void IlvListGadgetItemHolder::removeItem	(	IlUShort	index,
		IlBoolean	destroy = IlTrue
	)

Removes an item from the holder.

Parameters:

	index	The item position.
	destroy	A Boolean value specifying whether the item should be destroyed.

See also:

insertItem

void IlvListGadgetItemHolder::removeLabel

(

IlUShort

index

)

Removes and destroys an item.

Parameters:

index

The item position.

See also:

removeItem, insertItem

void IlvListGadgetItemHolder::setItemData	(	IlUShort	index,
		IlAny	itemData
	)

Sets an item user data.

Parameters:

	index	The item index.
	itemData	The item data.

See also:

getItemData, IlvGadgetItem::getClientData

virtual void IlvListGadgetItemHolder::setItems	(	IlvGadgetItem *const *	items,
		IlUShort	count
	)			[virtual]

Replaces the entire list of items.

Sets the items of the holder to items, which must be an array of count IlvGadgetItem objects. Items are not copied, but the deletion of the array items is the responsibility of the caller.

Parameters:

	items	The new items.
	count	The number of items in items.

See also:

getItems, insertItem, removeItem

Reimplemented in IlvAbstractMenu, IlvComboBox, and IlvStringList.

void IlvListGadgetItemHolder::setLabel	(	IlUShort	index,
		const char *	label,
		IlBoolean	copy
	)

Modifies the label of an item.

Parameters:

	index	The item index.
	label	The new item label.
	copy	A Boolean value specifying whether a label should be copied. If the value is IlFalse, then you must allocate some memory for the label because in any case the label characters are deleted from the memory by the IlvGadgetItem.

See also:

getLabel

virtual void IlvListGadgetItemHolder::setLabels	(	const char *const *	labels,
		IlUShort	count,
		IlBoolean	copy = IlTrue
	)			[virtual]

Replaces the entire list of items.

Replaces the entire internal list of items to match the count labels provided in the parameter labels.

Parameters:

	labels	The new items labels.
	count	The number of elements in the labels.
	copy	A Boolean value specifying whether the labels should be copied. If the value is IlFalse, then you must allocate some memory for the label because in any case the labels characters are deleted from the memory by the IlvGadgetItem.

See also:

getLabels, setItems

virtual void IlvListGadgetItemHolder::setLabels	(	const char *const *	labels,
		IlAny const *	itemData,
		IlUShort	count,
		IlBoolean	copy = IlTrue
	)			[virtual]

Replaces the entire list of items.

Replaces the entire internal list of items to match the count labels provided in the parameter labels. Each item created is associated with its data read from the itemData array.

Parameters:

	labels	The new items labels.
	itemData	The data associated with the items.
	count	The number of elements in the labels and itemData arrays.
	copy	A Boolean value specifying whether the labels should be copied. If the value is IlFalse, then you must allocate some memory for the label because in any case the labels characters are deleted from the memory by the IlvGadgetItem.

See also:

getLabels, setItems

virtual void IlvListGadgetItemHolder::sort

(

IlvListCompareFunction

func = 0

)

[virtual]

Sorts the items.

Runs the sorting algorithm on all the items. If you provide a sorting function in the form of an IlvListCompareFunction, this function is called to compare each item pair. If you do not provide a sorting function, a default comparison function is used.

Parameters:

func

A sorting function.

See also:

IlvListCompareFunction, compareItems

Reimplemented in IlvStringList.