Gadget class. More...

#include <ilviews/gadgets/slist.h>

Inheritance diagram for IlvStringList:

Public Member Functions
	IlvStringList (IlvDisplay display, const IlvPoint &point, const char const labels=0, IlUShort count=0, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette palette=0)
	Constructor. More...

	IlvStringList (IlvDisplay display, const IlvRect &rect, const char const labels=0, IlUShort count=0, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette palette=0)
	Constructor. More...

	IlvStringList (IlvDisplay display, const IlvPoint &point, const char const labels, IlAny const itemData, IlUShort count, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette *palette=0)
	Constructor. More...

	IlvStringList (IlvDisplay display, const IlvRect &rect, const char const labels, IlAny const itemData, IlUShort count, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette *palette=0)
	Constructor. More...

void	addSelectCallback (IlvGraphicCallback callback)
	Adds a Select callback. More...

void	addSelectCallback (IlSymbol *callbackName)
	Adds a named Select callback. More...

void	addSelectCallback (IlvGraphicCallback callback, IlAny arg)
	Adds a Select callback. More...

void	addSelectCallback (IlSymbol *callbackName, IlAny arg)
	Adds a named Select callback. More...

virtual IlBoolean	allowDragDrop () const
	Indicates whether drag-and-drop operations are allowed for the string list. More...

void	allowDragDrop (IlBoolean allow)
	Specifies whether drag-and-drop operations should be allowed for the string list. More...

void	autoLabelAlignment (IlBoolean align, IlBoolean redraw=IlTrue)
	Specifies whether the automatic alignment mode should be used. More...

IlBoolean	autoLabelAlignment () const
	Indicates whether the automatic label alignment mode is on. More...

virtual void	doIt ()
	Is called when the user double-clicks an item in the list or presses the Enter key. More...

virtual void	drawBackground (IlvPort , const IlvTransformer , const IlvRegion *) const
	Draws the gadget background. More...

virtual void	drawFrame (IlvPort , const IlvTransformer , const IlvRegion *) const
	Draws the gadget frame. More...

virtual void	drawGadgetContents (IlvPort dst, const IlvTransformer t=0, const IlvRegion *clip=0) const
	Draws the gadget contents. More...

virtual void	drawGadgetItem (const IlvGadgetItem , IlvPort port, const IlvRect &rect, const IlvTransformer t, const IlvRegion clip) const
	Draws a specific gadget item. More...

virtual void	empty ()
	Empties the list. More...

void	ensureVisible (IlUShort index, IlBoolean redraw=IlFalse, IlBoolean horizontal=IlFalse)
	Changes the first visible item so that the specified item remains visible. More...

IlvDim	getDefaultItemHeight () const
	Returns the height of the items when all items are the same height. More...

IlUShort	getFirstItem () const
	Returns the index of the first visible item in the string list. More...

virtual IlvDim	getLabelOffset () const
	Returns the offset used to display each item label. More...

virtual void	getLabelOrientation (IlvOrientation &orientation, IlBoolean &flip) const
	Returns the default orientation of the labels associated with the string list items. More...

virtual IlvPosition	getLabelPosition () const
	Returns the default position of the labels associated with the string list items, relative to their picture. More...

IlUShort	getLastFullVisibleItem () const
	Returns the index of the last visible item that can be seen without scrolling the list. More...

IlUShort	getLastVisibleItem (const IlvTransformer *t=0) const
	Returns the index of the last visible item of the string list. More...

virtual IlvPalette *	getNormalTextPalette () const
	Returns the default palette used to draw an item. More...

IlvDim	getOffset () const
	Returns the horizontal offset set for the string list. More...

virtual IlvPalette *	getOpaquePalette () const
	Returns the opaque palette used to draw opaque items. More...

IlvGraphicCallback	getSelectCallback () const
	Returns a pointer to the first unnamed callback in the Select callback list. More...

IlSymbol *	getSelectCallbackName () const
	Returns the name of the first named callback in the Select callback list. More...

IlShort	getSelectionLimit () const
	Returns the maximum number of items that can be selected at the same time. More...

IlvStringListSelectionMode	getSelectionMode () const
	Returns the current selection mode of the string list. More...

IlvDim	getSpacing () const
	Returns the spacing between two items in the string list. More...

virtual IlBoolean	handleGadgetEvent (IlvEvent &event)
	Handles the gadget events. More...

IlBoolean	hasFullSelection () const
	Indicates whether the selection extends over the whole width of the string list. More...

virtual IlBoolean	hasToolTips () const
	Indicates whether the string list displays tooltips. More...

virtual IlBoolean	isEditable () const
	Indicates whether the string list can be edited. More...

IlBoolean	isExclusive () const
	Indicates whether the exclusive selection mode is on. More...

virtual IlBoolean	isShowingLabel () const
	Indicates whether the labels associated with the string list items are displayed. More...

virtual IlBoolean	isShowingPicture () const
	Indicates whether the pictures associated with the string list items are displayed. More...

IlBoolean	itemBBox (IlUShort index, IlvRect &bbox, const IlvTransformer *t=0) const
	Returns the bounding box of the specified item. More...

IlShort	pointToPosition (const IlvPoint &point, const IlvTransformer *t=0) const
	Returns the index of the item located at the specified position. More...

virtual void	recomputeAllItems ()
	Recomputes the size of all the items managed by the holder. More...

virtual void	scrollBarChanged (IlvScrollBar *scrollbar, IlvOrientation direction)
	Is called each time the user manipulates one of the scroll bars. More...

virtual void	select (IlUShort index)
	Is called when the user selects the specified item in the string list. More...

IlBoolean	selectionLimitReached () const
	Indicates whether the maximum number of items that can be selected at the same time has been reached. More...

void	setDefaultItemHeight (IlvDim height, IlBoolean redraw=IlTrue)
	Sets the height of all the items in the string list. More...

void	setEditable (IlBoolean value=IlTrue)
	Specifies whether the string list should be editable. More...

void	setExclusive (IlBoolean value=IlTrue)
	Sets the selection mode for the string list. More...

virtual void	setItems (IlvGadgetItem const items, IlUShort count)
	Replaces the entire list of items. More...

void	setLabelOffset (IlvDim offset, IlBoolean redraw=IlTrue)
	Sets the label offset of the string list. More...

void	setLabelOrientation (IlvOrientation orientation, IlBoolean flip=IlFalse, IlBoolean redraw=IlTrue)
	Sets the default orientation of the labels associated with the string list items. More...

void	setLabelPosition (IlvPosition position, IlBoolean redraw=IlTrue)
	Sets the default position of the string list item labels relative to their picture. More...

void	setOffset (IlvDim offset)
	Sets the horizontal offset of the string list. More...

void	setSelectCallback (IlvGraphicCallback callback)
	Sets a Select callback. More...

void	setSelectCallback (IlSymbol *callbackName)
	Sets a named Select callback. More...

void	setSelectCallback (IlvGraphicCallback callback, IlAny arg)
	Sets a Select callback. More...

void	setSelectCallback (IlSymbol *callbackName, IlAny arg)
	Sets a named Select callback. More...

virtual void	setSelected (IlUShort index, IlBoolean value=IlTrue, IlBoolean redraw=IlFalse)
	Selects or deselects an item. More...

void	setSelectionLimit (IlShort limit)
	Sets the maximum number of items that can be selected at the same time. More...

void	setSelectionMode (IlvStringListSelectionMode mode)
	Sets the selection mode of the string list. More...

virtual void	setSpacing (IlvDim spacing, IlBoolean redraw=IlFalse)
	Sets the spacing between two items in the string list. More...

void	showLabel (IlBoolean value=IlTrue, IlBoolean redraw=IlTrue)
	Indicates whether the labels associated with the string list items should be shown or hidden. More...

void	showPicture (IlBoolean value=IlTrue, IlBoolean redraw=IlTrue)
	Indicates whether the pictures associated with the string list items are displayed. More...

virtual void	sort (IlvListCompareFunction=0)
	Sorts the items. More...

virtual void	unSelect (IlUShort index)
	Is called when the user deselects the specified item in the string list. More...

void	useFullSelection (IlBoolean value=IlTrue, IlBoolean redraw=IlTrue)
	Specifies whether the full selection mode should be used. More...

void	useToolTips (IlBoolean value=IlTrue)
	Specifies whether the string list should display tooltips. More...

Public Member Functions inherited from IlvScrolledGadget
	IlvScrolledGadget (IlvDisplay display, const IlvRect &rect, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette palette=0)
	Constructor. More...

virtual void	adjustScrollBars (IlBoolean redraw=IlFalse)
	Recomputes the scroll bars. More...

void	computeBBox (IlvRect &ibox, IlvRect &vs, IlvRect &hs, const IlvTransformer *t=0) const
	Computes the bounding boxes of the elements that compose the gadget. More...

void	computeBBox (IlvRect &ibox, IlvRect &vbox, IlvRect &vs, IlvRect &hs, const IlvTransformer *t=0) const
	Computes the bounding boxes of the elements that compose the gadget. More...

virtual IlvScrollBar *	createScrollBar (const IlvRect &rect, IlvDirection direction, IlUShort thickness, IlvPalette *palette)
	Returns a new instance of the `IlvScrollBar` class. More...

virtual void	drawScrollBar (IlvPort dst, IlvDirection direction, const IlvTransformer t=0, const IlvRegion *clip=0) const
	Draws the specified internal scroll bar. More...

void	fitToRect (const IlvRect &rect)
	Resizes the object so that the scrollable area fits the specified rectangle. More...

IlUShort	getBottomMargin () const
	Returns the bottom margin. More...

IlvScrollBar *	getHorizontalScrollBar () const
	Returns a pointer to the internal horizontal scroll bar. More...

IlUShort	getLeftMargin () const
	Returns the left margin. More...

IlUShort	getRightMargin () const
	Returns the right margin. More...

IlvScrollBar *	getScrollBar (IlvDirection direction) const
	Returns a pointer to the specified internal scroll bar. More...

void	getScrollBarShowAsNeeded (IlBoolean &vert, IlBoolean &hor) const
	Returns the scroll bar mode of the internal scroll bars. More...

IlUShort	getTopMargin () const
	Returns the top margin. More...

IlvScrollBar *	getVerticalScrollBar () const
	Returns a pointer to the internal vertical scroll bar. More...

virtual IlBoolean	handleScrollBarsEvent (IlvEvent &event)
	Handles the internal scroll bars event. More...

void	hideScrollBar (IlvDirection direction, IlBoolean redraw=IlTrue)
	Hides the specified internal scroll bar. More...

virtual void	internalBBox (IlvRect &bbox, const IlvTransformer *t=0) const
	Returns the internal bounding box of the gadget. More...

void	moveScrollBar (IlvDirection direction, IlvPosition where, IlBoolean redraw=IlTrue)
	Moves the specified internal scroll bar to a new position. More...

virtual void	scrollableSize (IlvDim &width, IlvDim &height) const
	Returns the size of the scrollable area of the gadget. More...

virtual void	scrollBarBBox (IlvDirection direction, IlvRect &bbox, const IlvTransformer *t=0) const
	Returns the bounding box of the specified internal scroll bar. More...

void	scrollBarShowAsNeeded (IlBoolean vertical, IlBoolean horizontal, IlBoolean redraw=IlTrue)
	Sets the scroll bar mode of the internal scroll bars. More...

virtual void	scrollBarVisibilityChanged (IlvDirection direction)
	Is called when an internal scroll bar is shown or hidden. More...

void	setBottomMargin (IlUShort margin)
	Sets the bottom margin. More...

void	setLeftMargin (IlUShort margin)
	Sets the left margin. More...

void	setMargin (IlUShort val)
	Sets the left, right, top, and bottom margins. More...

void	setRightMargin (IlUShort margin)
	Sets the right margin. More...

void	setTopMargin (IlUShort margin)
	Sets the top margin. More...

void	showScrollBar (IlvDirection direction, IlBoolean redraw=IlTrue)
	Shows the specified internal scroll bar. More...

virtual void	visibleBBox (IlvRect &bbox, const IlvTransformer *t=0) const
	Returns the visible bounding box of the gadget. More...

IlvPosition	whereIsScrollBar (IlvDirection direction) const
	Returns the location of the specified internal scroll bar. More...

Public Member Functions inherited from IlvListGadgetItemHolder
virtual void	addLabel (const char *label, IlAny data=0)
	Adds an item with a label to the holder list. More...

virtual IlvGadgetItem *	applyToItems (IlvApplyGadgetItem, IlAny)
	Applies the specified function to all the items of the holder. More...

virtual int	compareItems (const char string1, const char string2, IlAny value1, IlAny value2)
	Compares a pair of items. More...

virtual void	deSelectAll ()
	Deselects all the items. More...

IlUShort	getCardinal () const
	Returns the number of items stored in this holder. More...

IlShort	getFirstSelectedItem () const
	Returns the index of the first selected item. More...

IlShort	getIndex (const IlvGadgetItem *item, IlUShort start=0, IlUShort stop=(IlUShort)-1) const
	Returns the index of the specified item in the holder list. More...

IlvGadgetItem *	getItem (IlUShort index) const
	Returns an item from its position in the holder. More...

IlAny	getItemData (IlUShort index) const
	Returns an item user data. More...

IlvGadgetItem const	getItems (IlUShort &count) const
	Returns the array of all the items. More...

const char *	getLabel (IlUShort index) const
	Returns the indicated label of the list. More...

const char const	getLabels (IlUShort &count) const
	Returns an array of all the items labels. More...

IlShort	getPosition (const char *label, IlUShort start=0) const
	Returns the position of an item using its label. More...

virtual const char *	getSelection () const
	Returns the first selected item label. More...

IlUShort const *	getSelectionIndices (IlUShort &count) const
	Returns an array containing the indexes of the selected item. More...

const char const	getSelections (IlUShort &count) const
	Returns an array of the selected items. More...

IlAny const *	getUserDataArray (IlUShort &count) const
	Returns an array of all the user data for the items. More...

IlUShort	insertBitmap (IlvBitmap *bitmap, IlShort pos=-1)
	Inserts an item with a bitmap at the given position in the holder list. More...

IlUShort	insertGraphic (IlvGraphic *graphic, IlShort pos=-1)
	Inserts an item with a graphic as picture at a given position in the holder list. More...

IlUShort	insertItem (IlvGadgetItem *item, IlShort index=-1)
	Inserts an item at a given position in the holder's list. More...

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. More...

IlBoolean	isSelected (IlUShort index) const
	Specifies whether the item whose position is specified is selected. More...

void	removeItem (IlUShort index, IlBoolean destroy=IlTrue)
	Removes an item from the holder. More...

void	removeLabel (IlUShort index)
	Removes and destroys an item. More...

void	setItemData (IlUShort index, IlAny itemData)
	Sets an item user data. More...

void	setLabel (IlUShort index, const char *label, IlBoolean copy)
	Modifies the label of an item. More...

virtual void	setLabels (const char const labels, IlAny const *itemData, IlUShort count, IlBoolean copy=IlTrue)
	Replaces the entire list of items. More...

virtual void	setLabels (const char const labels, IlUShort count, IlBoolean copy=IlTrue)
	Replaces the entire list of items. More...

Public Member Functions inherited from IlvGadgetItemHolder
virtual IlvGadgetItem *	createItem (const char label, IlvGraphic graphic=0, IlvBitmap bitmap=0, IlvBitmap selbitmap=0, IlBoolean copy=IlTrue) const
	Returns a new gadget item. More...

IlvGadgetItem *	getCallbackItem () const
	Returns the item that triggered a callback. More...

IlvGadgetItem *	getDragDropTarget () const
	Returns the target item of a drag-and-drop operation. More...

IlvGraphic *	getDraggedImage () const
	Returns the graphic object used to draw the ghost image during a drag-and-drop operation. More...

IlvGadgetItem *	getDraggedItem () const
	Returns the item that is being dragged during a drag-and-drop operation. More...

IlvGadgetItem *	getEditedItem () const
	Returns the item that is being edited. More...

virtual IlvPalette *	getHighlightTextPalette () const
	Returns the highlight palette used to draw the label of highlighted items. More...

virtual IlvGadgetItem *	getItemByName (const char *name) const
	Returns the item whose name is specified. More...

IlvGadgetItem *	getToolTipItem () const
	Returns the item that is displaying a tooltip. More...

virtual void	initReDrawItems ()
	Begins a redraw session. More...

virtual void	reDrawItems ()
	Ends a redraw session. More...

void	setDragDropTarget (IlvGadgetItem *item)
	Sets the target item of a drag-and-drop operation. More...

void	setDraggedImage (IlvGraphic *graphic)
	Sets the graphic object used to draw the ghost image during a drag-and-drop operation. More...

void	setDraggedItem (IlvGadgetItem *item)
	Sets the dragged item. More...

Static Public Member Functions
static IlSymbol *	SelectSymbol ()
	Returns the symbol of the Select callback list. More...

Static Public Member Functions inherited from IlvScrolledGadget
static IlSymbol *	ScrollBarMovedSymbol ()
	Returns the callback type for the Scroll Bar Moved callback. More...

static IlSymbol *	ScrollBarVisibilitySymbol ()
	Returns the callback type for the Scroll Bar Visibility Changed callback. More...

Protected Member Functions
virtual void	adjustFromScrollBar (const IlvScrollBar *sb, IlvDirection dir)
	Is called to adjust the gadget to the scroll bars values. More...

virtual void	adjustScrollBarValue (IlvScrollBar *sb, IlvDirection dir)
	Is called to adjust the scroll bar values. More...

virtual void	scrollBarHasMoved (IlvDirection dir)
	Is called when an internal scroll bar has moved. More...

Protected Member Functions inherited from IlvScrolledGadget
IlvDim	getLimitHeightValue () const
	Returns the limit value for the vertical scrolling. More...

IlvDim	getLimitWidthValue () const
	Returns the limit value for the horizontal scrolling. More...

IlvDim	getScrollableHeight () const
	Returns the height of the scrollable area. More...

IlvDim	getScrollableWidth () const
	Returns the width of the scrollable area. More...

void	setLimitHeightValue (IlvDim value)
	Sets the limit value for the vertical scrolling. More...

void	setLimitWidthValue (IlvDim value)
	Sets the limit value for the horizontal scrolling. More...

void	setScrollableHeight (IlvDim height)
	Sets the height of the scrollable area. More...

void	setScrollableWidth (IlvDim width)
	Sets the width of the scrollable area. More...

Friends
class	IlvDefaultStringListLFHandler

Detailed Description

Gadget class.

Library: ilvadvgdt

The IlvStringList class lets you display and manipulate lists of gadget items. You can store up to 32768 items in a string list.

A String List

The main callback manages double-click events. Use the IlvStringList::setSelectCallback() method to track the selection.

See Also: IlvGadgetItem

Styling

This class support the following CSS properties:

Graphic property	CSS propery	Type
Background color	`background-color`	Color
Text color	`color`	Color

Constructor & Destructor Documentation

IlvStringList::IlvStringList	(	IlvDisplay *	display,
		const IlvPoint &	point,
		const char const	labels = `0`,
		IlUShort	count = `0`,
		IlUShort	thickness = `IlvDefaultGadgetThickness`,
		IlvPalette *	palette = `0`
	)

Constructor.

Initializes a new instance of the IlvStringList class. The size of the object is computed by calling the IlvGadget::fitToContents() method. If you want to specify the size, use a constructor that takes an IlvRect reference instead of an IlvPoint object as parameter. The labels are copied.

Parameters

display	The connection to the display.
point	The position of the string list.
labels	An array of predefined labels.
count	The number of elements in the labels array.
thickness	The thickness of the string list.
palette	The palette used to draw the string list.

IlvStringList::IlvStringList	(	IlvDisplay *	display,
		const IlvRect &	rect,
		const char const	labels = `0`,
		IlUShort	count = `0`,
		IlUShort	thickness = `IlvDefaultGadgetThickness`,
		IlvPalette *	palette = `0`
	)

Constructor.

Initializes a new instance of the IlvStringList class. The labels are copied.

Parameters

display	The connection to the display.
rect	The size and position of the string list.
labels	An array of predefined labels.
count	The number of elements in the labels array.
thickness	The thickness of the string list.
palette	The palette used to draw the string list.

IlvStringList::IlvStringList	(	IlvDisplay *	display,
		const IlvPoint &	point,
		const char const	labels,
		IlAny const *	itemData,
		IlUShort	count,
		IlUShort	thickness = `IlvDefaultGadgetThickness`,
		IlvPalette *	palette = `0`
	)

Constructor.

Initializes a new instance of the IlvStringList class. The size of the object is computed by calling the IlvGadget::fitToContents() method. If you want to specify the size, use a constructor that takes an IlvRect reference instead of an IlvPoint object as parameter. The labels are copied.

Parameters

display	The connection to the display.
point	The position of the string list.
labels	An array of predefined labels.
itemData	An array of the predefined data that will be set to each created item. For details, see `IlvGadgetItem::setClientData()`.
count	The number of elements in the labels array.
thickness	The thickness of the string list.
palette	The palette used to draw the string list.

IlvStringList::IlvStringList	(	IlvDisplay *	display,
		const IlvRect &	rect,
		const char const	labels,
		IlAny const *	itemData,
		IlUShort	count,
		IlUShort	thickness = `IlvDefaultGadgetThickness`,
		IlvPalette *	palette = `0`
	)

Constructor.

Initializes a new instance of the IlvStringList class. The labels are copied.

Parameters

display	The connection to the display.
rect	The size and position of the string list.
labels	An array of predefined labels.
itemData	An array of the predefined data that will be set to each created item. See `IlvGadgetItem::setClientData()` for more details.
count	The number of elements in the labels array.
thickness	The thickness of the string list.
palette	The palette used to draw the string list.

Member Function Documentation

void IlvStringList::addSelectCallback ( IlvGraphicCallback callback )

Adds a Select callback.

Adds callback to the Select callback list. A Select callback is invoked whenever the selection in the string list changes.

Parameters

callback A pointer to the new callback.

See Also: focusIn(), setSelectCallback(), getSelectCallback().

void IlvStringList::addSelectCallback ( IlSymbol * callbackName )

Adds a named Select callback.

Adds callbackName to the Select callback list. A Select callback is invoked whenever the selection in the string list changes.

Parameters

callbackName The name of the new callback.

See Also: focusIn(), setSelectCallback(), getSelectCallbackName().

void IlvStringList::addSelectCallback	(	IlvGraphicCallback	callback,
		IlAny	arg
	)

Adds a Select callback.

Adds callback to the Select callback list. The callback function, when invoked, receives the user parameter arg. A Select callback is invoked whenever the selection in the string list changes.

Parameters

callback	A pointer to the new callback.
arg	The callback argument.

See Also: focusIn(), setSelectCallback(), getSelectCallback().

void IlvStringList::addSelectCallback	(	IlSymbol *	callbackName,
		IlAny	arg
	)

Adds a named Select callback.

Adds callbackName to the Select callback list. The callback function, when invoked, receives the user parameter arg. A Select callback is invoked whenever the selection in the string list changes.

Parameters

callbackName	The name of the new callback.
arg	The callback argument.

See Also: focusIn(), setSelectCallback(), getSelectCallbackName().

virtual void IlvStringList::adjustFromScrollBar	(	const IlvScrollBar *	scrollbar,
		IlvDirection	direction
	)

protectedvirtual

Is called to adjust the gadget to the scroll bars values.

Is called each time the scroll bar scrollbar of direction direction moves. If you want to detect these events, you must redefine this member function in a subclass. The default implementation does nothing.

Parameters

scrollbar	The scroll bar object.
direction	The direction of the scroll bar. Valid values are: `IlvHorizontal` and `IlvVertical`.

See Also: adjustScrollBarValue().

Reimplemented from IlvScrolledGadget.

virtual void IlvStringList::adjustScrollBarValue	(	IlvScrollBar *	scrollbar,
		IlvDirection	direction
	)

protectedvirtual

Is called to adjust the scroll bar values.

Is called by the member function adjustScrollBars() to adjust the values of the scroll bar scrollbar of direction direction. This member function must modify the scrollbar values to match the gadget scrolling mode. If you want to detect these events, you must redefine this member function in a subclass. The default implementation does nothing.

Parameters

scrollbar	The scroll bar object.
direction	The direction of the scroll bar. Valid values are: `IlvHorizontal` and `IlvVertical`.

See Also: adjustFromScrollBar().

Reimplemented from IlvScrolledGadget.

virtual IlBoolean IlvStringList::allowDragDrop ( ) const

virtual

Indicates whether drag-and-drop operations are allowed for the string list.

Returns: IlTrue if drag-and-drop operations are allowed and IlFalse otherwise.

See Also: IlvGadgetItemHolder::startDragItem(), allowDragDrop(IlBoolean).

Reimplemented from IlvGadgetItemHolder.

void IlvStringList::allowDragDrop ( IlBoolean allow )

Specifies whether drag-and-drop operations should be allowed for the string list.

Parameters

allow A Boolean value specifying whether drag-and-drop operations should be allowed (IlTrue).

See Also: IlvGadgetItemHolder::startDragItem(), allowDragDrop().

void IlvStringList::autoLabelAlignment	(	IlBoolean	align,
		IlBoolean	redraw = `IlTrue`
	)

Specifies whether the automatic alignment mode should be used.

When the automatic label alignment mode is enabled (the default), a label offset is automatically computed to make sure that all the item pictures are visible, and all the item labels are aligned.

Parameters

align	A Boolean value specifying whether the automatic alignment mode should be used.
redraw	A Boolean value specifying whether the string list should be redrawn.

See Also: setLabelOffset(), autoLabelAlignment().

IlBoolean IlvStringList::autoLabelAlignment ( ) const

Indicates whether the automatic label alignment mode is on.

Returns: IlTrue if the automatic label alignment mode is on and IlFalse otherwise.

See Also: autoLabelAlignment(IlBoolean, IlBoolean), setLabelOffset().

virtual void IlvStringList::doIt ( )

virtual

Is called when the user double-clicks an item in the list or presses the Enter key.

Its default implementation invokes the callback associated with the object.

See Also: IlvGraphic::callCallbacks().

virtual void IlvStringList::drawBackground	(	IlvPort *	dst,
		const IlvTransformer *	t,
		const IlvRegion *	clip
	)		const

virtual

Draws the gadget background.

Is called from the draw() method. This method is not called if the gadget is transparent.

Parameters

dst	The destination drawing port.
t	The transformer applied to the gadget.
clip	The clipping area.

See Also: drawFrame(), drawScrollBar(), drawGadgetContents(), IlvGadget::isTransparent().

Reimplemented from IlvScrolledGadget.

virtual void IlvStringList::drawFrame	(	IlvPort *	dst,
		const IlvTransformer *	t,
		const IlvRegion *	clip
	)		const

virtual

Draws the gadget frame.

Is called from the draw() method. This method is not called if the method isShowingFrame() returns IlFalse.

Parameters

dst	The destination drawing port.
t	The transformer applied to the gadget.
clip	The clipping area.

See Also: drawBackground(), drawScrollBar(), drawGadgetContents().

Reimplemented from IlvScrolledGadget.

virtual void IlvStringList::drawGadgetContents	(	IlvPort *	dst,
		const IlvTransformer *	t = `0`,
		const IlvRegion *	clip = `0`
	)		const

virtual

Draws the gadget contents.

Is called from the draw() method. The default implementation does nothing.

Parameters

dst	The destination drawing port.
t	The transformer applied to the gadget.
clip	The clipping area.

See Also: drawBackground(), drawScrollBar(), drawFrame().

Reimplemented from IlvScrolledGadget.

virtual void IlvStringList::drawGadgetItem	(	const IlvGadgetItem *	item,
		IlvPort *	port,
		const IlvRect &	rect,
		const IlvTransformer *	t,
		const IlvRegion *	clip
	)		const

virtual

Draws a specific gadget item.

Redraws item in port at the location specified by rect using the clipping area clip. This method simply calls IlvGadgetItem::draw() using the item instance.

Parameters

item	The item to be redrawn.
port	The destination drawing port.
rect	The bounding box of the item.
t	The transformer used to draw the item. Not used.
clip	The clipping area.

See Also: IlvGadgetItem::draw().

Reimplemented from IlvGadgetItemHolder.

virtual void IlvStringList::empty ( )

virtual

Empties the list.

See Also: setItems(), removeItem().

Implements IlvListGadgetItemHolder.

void IlvStringList::ensureVisible	(	IlUShort	index,
		IlBoolean	redraw = `IlFalse`,
		IlBoolean	horizontal = `IlFalse`
	)

Changes the first visible item so that the specified item remains visible.

Parameters

index	The index of the string list item.
redraw	A Boolean value specifying whether the string list should be redrawn.
horizontal	A Boolean value specifying whether the item visibility will be checked in the horizontal direction. In other words, the offset of the string list can be changed by this method if horizontal is set to `IlTrue`.

See Also: getOffset().

IlvDim IlvStringList::getDefaultItemHeight ( ) const

Returns the height of the items when all items are the same height.

Returns: The height of the items when all items are the same height. It returns 0 when the items are different heights.

See Also: setDefaultItemHeight().

IlUShort IlvStringList::getFirstItem ( ) const

Returns the index of the first visible item in the string list.

Returns: The index of the first visible item in the string list.

See Also: getLastVisibleItem(), getLastFullVisibleItem().

virtual IlvDim IlvStringList::getLabelOffset ( ) const

virtual

Returns the offset used to display each item label.

Returns: The offset used to display each item label or 0 if no offset has been defined.

See Also: setLabelOffset(), autoLabelAlignment(IlBoolean, IlBoolean).

Reimplemented from IlvListGadgetItemHolder.

virtual void IlvStringList::getLabelOrientation	(	IlvOrientation &	orientation,
		IlBoolean &	flip
	)		const

virtual

Returns the default orientation of the labels associated with the string list items.

Returns: The default orientation of the labels associated with the string items.

Parameters

orientation	The default orientation of the labels.
flip	A Boolean value specifying whether the labels should be flipped or not. See the `setLabelOrientation()` method for more details.

See Also: setLabelOrientation().

Reimplemented from IlvGadgetItemHolder.

virtual IlvPosition IlvStringList::getLabelPosition ( ) const

virtual

Returns the default position of the labels associated with the string list items, relative to their picture.

Returns: The default position of the labels associated with the string list items, relative to their pictures.

See Also: setLabelPosition().

Reimplemented from IlvGadgetItemHolder.

IlUShort IlvStringList::getLastFullVisibleItem ( ) const

Returns the index of the last visible item that can be seen without scrolling the list.

Returns: The index of the last visible item that can be seen without scrolling the list. If the first visible item is larger than the list height, its index is returned.

See Also: getFirstItem(), getLastVisibleItem().

IlUShort IlvStringList::getLastVisibleItem ( const IlvTransformer * t = 0 ) const

Returns the index of the last visible item of the string list.

Parameters

t	The transformer applied to the string list.

Returns: The index of the last visible item when this string list is displayed with the transformer t. The item can be visible only partially.

See Also: getLastFullVisibleItem(), getFirstItem().

virtual IlvPalette* IlvStringList::getNormalTextPalette ( ) const

virtual

Returns the default palette used to draw an item.

Returns: The default palette used to draw an item.

Implements IlvGadgetItemHolder.

IlvDim IlvStringList::getOffset ( ) const

Returns the horizontal offset set for the string list.

This offset moves the items horizontally in the list. The bigger the value, the further the items will be displayed to the left. This value is modified when moving the horizontal scroll bar.

See Also: setOffset(), getLabelOffset().

virtual IlvPalette* IlvStringList::getOpaquePalette ( ) const

virtual

Returns the opaque palette used to draw opaque items.

Returns: The opaque palette used to draw opaque items.

Reimplemented from IlvGadgetItemHolder.

IlvGraphicCallback IlvStringList::getSelectCallback ( ) const

Returns a pointer to the first unnamed callback in the Select callback list.

A Select callback is invoked whenever the selection in the string list changes.

Returns: The function pointer to the first unnamed callback in the Select callback list.

See Also: focusIn(), setSelectCallback(), addSelectCallback().

IlSymbol* IlvStringList::getSelectCallbackName ( ) const

Returns the name of the first named callback in the Select callback list.

A Select callback is invoked whenever the selection in the string list changes.

Returns: The name of the first named callback in the Select callback list.

See Also: focusIn(), setSelectCallback(), addSelectCallback().

IlShort IlvStringList::getSelectionLimit ( ) const

Returns the maximum number of items that can be selected at the same time.

Returns: The maximum number of items that can be selected at the same time.

See Also: setSelectionLimit().

IlvStringListSelectionMode IlvStringList::getSelectionMode ( ) const

Returns the current selection mode of the string list.

Returns: The current selection mode of the string list.

See Also: setSelectionMode(), IlvStringListSelectionMode.

IlvDim IlvStringList::getSpacing ( ) const

Returns the spacing between two items in the string list.

The default value is 0.

Returns: The spacing between two items in this string list.

See Also: setSpacing().

virtual IlBoolean IlvStringList::handleGadgetEvent ( IlvEvent & event )

virtual

Handles the gadget events.

Is called by handleEvent() when the member function handleScrollBarsEvent() returns IlFalse. Its default implementation does nothing. You can override this member function to implement your own gadget behavior.

Parameters

event The event.

See Also: handleScrollBarsEvent().

Reimplemented from IlvScrolledGadget.

IlBoolean IlvStringList::hasFullSelection ( ) const

Indicates whether the selection extends over the whole width of the string list.

Returns: IlTrue if the string list is in full selection mode and IlFalse otherwise.

See Also: useFullSelection().

virtual IlBoolean IlvStringList::hasToolTips ( ) const

virtual

Indicates whether the string list displays tooltips.

Returns: IlTrue if the string list displays tooltips and is not in full selection mode. It returns IlFalse if it does not display tooltips.

See Also: useToolTips().

Reimplemented from IlvGadgetItemHolder.

virtual IlBoolean IlvStringList::isEditable ( ) const

virtual

Indicates whether the string list can be edited.

Returns: IlTrue if the list can be edited and IlFalse otherwise.

Reimplemented from IlvGadgetItemHolder.

IlBoolean IlvStringList::isExclusive ( ) const

Indicates whether the exclusive selection mode is on.

In exclusive selection mode, only one item can be selected at a time.

Returns: IlTrue if the exclusive selection mode is set and IlFalse otherwise.

See Also: setExclusive(), getSelectionMode().

virtual IlBoolean IlvStringList::isShowingLabel ( ) const

virtual

Indicates whether the labels associated with the string list items are displayed.

Returns: IlTrue if the labels associated with the string list items are displayed and IlFalse otherwise.

See Also: showLabel(), isShowingPicture().

Reimplemented from IlvGadgetItemHolder.

virtual IlBoolean IlvStringList::isShowingPicture ( ) const

virtual

Indicates whether the pictures associated with the string list items are displayed.

Returns: IlTrue if the pictures associated with the string list items are displayed and IlFalse otherwise.

See Also: showPicture(), isShowingLabel().

Reimplemented from IlvGadgetItemHolder.

IlBoolean IlvStringList::itemBBox	(	IlUShort	index,
		IlvRect &	bbox,
		const IlvTransformer *	t = `0`
	)		const

Returns the bounding box of the specified item.

Parameters

index	The index of the item.
bbox	The returned bounding box of the specified item.
t	The transformer applied to the string list.

Returns: A Boolean value specifying whether the item is visible even partially.

See Also: pointToPosition().

IlShort IlvStringList::pointToPosition	(	const IlvPoint &	point,
		const IlvTransformer *	t = `0`
	)		const

Returns the index of the item located at the specified position.

Parameters

point	The position in view coordinates.
t	The transformer applied to the string list.

Returns: The index of the label located at the position specified by point when this string list is displayed with the transformer t.

See Also: itemBBox().

virtual void IlvStringList::recomputeAllItems ( )

virtual

Recomputes the size of all the items managed by the holder.

Calls the IlvGadgetItem::recomputeSize() member function for all the items managed by this holder.

See Also: IlvGadgetItem::recomputeSize(), applyToItems().

Reimplemented from IlvGadgetItemHolder.

virtual void IlvStringList::scrollBarChanged	(	IlvScrollBar *	scrollbar,
		IlvOrientation	direction
	)

virtual

Is called each time the user manipulates one of the scroll bars.

This method is obsolete. Use the IlvScrolledGadget::scrollBarHasMoved method instead. The default implementation does nothing. To detect events relating to scroll bars, you have to override this member function in a subclass.

Parameters

scrollbar	A pointer to the instance of the scroll bar that was changed.
direction	The direction of the scroll bar that was changed.

See Also: IlvScrolledGadget::scrollBarHasMoved().

virtual void IlvStringList::scrollBarHasMoved ( IlvDirection direction )

protectedvirtual

Is called when an internal scroll bar has moved.

Is called by handleEvent() each time the value of the internal scroll bar specified by direction changes. The default implementation invokes the Scroll Bar Moved callback.

Parameters

direction The direction of the internal scroll bar. Valid values are: IlvHorizontal and IlvVertical.

See Also: ScrollBarMovedSymbol().

Reimplemented from IlvScrolledGadget.

virtual void IlvStringList::select ( IlUShort index )

virtual

Is called when the user selects the specified item in the string list.

The default implementation selects the item by calling the setSelected() method.

Parameters

index The index of the selected item.

See Also: unSelect().

IlBoolean IlvStringList::selectionLimitReached ( ) const

Indicates whether the maximum number of items that can be selected at the same time has been reached.

Returns: IlTrue if the maximum number of items that can be selected at the same time has been reached and IlFalse otherwise.

See Also: getSelectionLimit(), setSelectionLimit().

static IlSymbol* IlvStringList::SelectSymbol ( )

static

Returns the symbol of the Select callback list.

Returns: The symbol of the Select callback list.

See Also: setSelectCallback(), IlvGraphic::setCallback().

void IlvStringList::setDefaultItemHeight	(	IlvDim	height,
		IlBoolean	redraw = `IlTrue`
	)

Sets the height of all the items in the string list.

Parameters

height	The new default height. If height is set to `0`, each item keeps its own height.
redraw	A Boolean value specifying whether the string list should be redrawn.

See Also: getDefaultItemHeight().

void IlvStringList::setEditable ( IlBoolean value = IlTrue )

Specifies whether the string list should be editable.

When the list is editable, you can edit one of its items by clicking on it once selected, or by pressing the F2 key.

Parameters

value A Boolean value specifying whether the string list should be editable (IlTrue) or not (IlFalse).

See Also: isEditable(), IlvGadgetItem::edit().

void IlvStringList::setExclusive ( IlBoolean value = IlTrue )

Sets the selection mode for the string list.

Parameters

value If value is set to IlTrue, only one item can be selected at a time. If it is set to IlFalse, several items can be selected simultaneously.

See Also: setSelectionMode().

virtual void IlvStringList::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 from IlvListGadgetItemHolder.

void IlvStringList::setLabelOffset	(	IlvDim	offset,
		IlBoolean	redraw = `IlTrue`
	)

Sets the label offset of the string list.

When a label offset is defined, all the item labels are aligned using this offset. Calling this method disables the automatic alignment mode.

Parameters

offset	The new label offset.
redraw	A Boolean value specifying whether the string list should be redrawn.

See Also: getLabelOffset(), autoLabelAlignment(IlBoolean, IlBoolean).

void IlvStringList::setLabelOrientation	(	IlvOrientation	orientation,
		IlBoolean	flip = `IlFalse`,
		IlBoolean	redraw = `IlTrue`
	)

Sets the default orientation of the labels associated with the string list items.

If the orientation is IlvHorizontal, labels are drawn from left to right. If the orientation is IlvVertical, labels are drawn vertically from top to bottom if flip is IlFalse, or from bottom to top if flip is IlFalse.

Parameters

orientation	The new orientation of the labels.
flip	A Boolean value specifying whether the labels are flipped or not.
redraw	A Boolean value specifying whether the string list should be redrawn.

See Also: getLabelOrientation().

void IlvStringList::setLabelPosition	(	IlvPosition	position,
		IlBoolean	redraw = `IlTrue`
	)

Sets the default position of the string list item labels relative to their picture.

This setting is used to compute the geometry of each string list item. For more information, see the member function IlvGadgetItem::setLabelPosition().

Parameters

position	The new position of the items labels relative to their pictures.
redraw	A Boolean value specifying whether the string list should be redrawn.

void IlvStringList::setOffset ( IlvDim offset )

Sets the horizontal offset of the string list.

This offset lets you move the items horizontally in the list. The bigger the value, the further the items will be displayed to the left. This value is modified when moving the horizontal scroll bar.

Parameters

offset The new horizontal offset.

See Also: getOffset(), setLabelOffset().

void IlvStringList::setSelectCallback ( IlvGraphicCallback callback )

Sets a Select callback.

Removes all the existing Select callbacks before adding callback to the Select callback list. A Select callback is invoked whenever the selection in the string list changes.

Parameters

callback A pointer to the new callback.

See Also: focusIn(), addSelectCallback(), getSelectCallback().

void IlvStringList::setSelectCallback ( IlSymbol * callbackName )

Sets a named Select callback.

Removes all the existing Select callbacks before adding callbackName to the Select callback list. A Select callback is invoked whenever the selection in the string list changes.

Parameters

callbackName The name of the new callback.

See Also: focusIn(), addSelectCallback(), getSelectCallbackName().

void IlvStringList::setSelectCallback	(	IlvGraphicCallback	callback,
		IlAny	arg
	)

Sets a Select callback.

Removes all the existing Select callbacks before adding callback to the Select callback list. The callback function, when invoked, receives the user parameter arg. A Select callback is invoked whenever the selection in the string list changes.

Parameters

callback	A pointer to the new callback.
arg	The callback argument.

See Also: focusIn(), addSelectCallback(), getSelectCallback().

void IlvStringList::setSelectCallback	(	IlSymbol *	callbackName,
		IlAny	arg
	)

Sets a named Select callback.

Removes all the existing Select callbacks before adding callbackName to the Select callback list. The callback function, when invoked, receives the user parameter arg. A Select callback is invoked whenever the selection in the string list changes.

Parameters

callbackName	The name of the new callback.
arg	The callback argument.

See Also: focusIn(), addSelectCallback(), getSelectCallbackName().

virtual void IlvStringList::setSelected	(	IlUShort	index,
		IlBoolean	value = `IlTrue`,
		IlBoolean	redraw = `IlFalse`
	)

virtual

Selects or deselects an item.

Parameters

index	The index of the item.
value	A Boolean value specifying whether the item specified by index should be selected or deselected.
redraw	A Boolean value specifying whether the string list should be redrawn.

void IlvStringList::setSelectionLimit ( IlShort limit )

Sets the maximum number of items that can be selected at the same time.

Parameters

limit The maximum number of items that can be selected simultaneously.

See Also: getSelectionLimit().

void IlvStringList::setSelectionMode ( IlvStringListSelectionMode mode )

Sets the selection mode of the string list.

Changes the selection mode only if mode matches the setting defined by setExclusive(). For example, calling this method with IlvStringListSingleSelection as parameter if the exclusive selection mode is not set (that is, isExclusive() returns IlFalse) has no effect.

Parameters

mode	The new selection mode.

See Also: getSelectionMode(), IlvStringListSelectionMode.

virtual void IlvStringList::setSpacing	(	IlvDim	spacing,
		IlBoolean	redraw = `IlFalse`
	)

virtual

Sets the spacing between two items in the string list.

Parameters

spacing	The new spacing value.
redraw	A Boolean value specifying whether the string list should be redrawn.

void IlvStringList::showLabel	(	IlBoolean	value = `IlTrue`,
		IlBoolean	redraw = `IlTrue`
	)

Indicates whether the labels associated with the string list items should be shown or hidden.

Parameters

value	A Boolean value specifying whether the labels of the string list items should be shown (`IlTrue`) or hidden (`IlFalse`).
redraw	A Boolean value specifying whether the string list should be redrawn.

See Also: isShowingLabel(), showPicture().

void IlvStringList::showPicture	(	IlBoolean	value = `IlTrue`,
		IlBoolean	redraw = `IlTrue`
	)

Indicates whether the pictures associated with the string list items are displayed.

Parameters

value	A Boolean value specifying whether the pictures of the string list items should be shown or hidden.
redraw	A Boolean value specifying whether the string list should be redrawn.

See Also: isShowingPicture(), showLabel().

virtual void IlvStringList::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 from IlvListGadgetItemHolder.

virtual void IlvStringList::unSelect ( IlUShort index )

virtual

Is called when the user deselects the specified item in the string list.

The default implementation deselects the item by calling the setSelected() method.

Parameters

index The index of the deselected item.

See Also: select().

void IlvStringList::useFullSelection	(	IlBoolean	value = `IlTrue`,
		IlBoolean	redraw = `IlTrue`
	)

Specifies whether the full selection mode should be used.

Parameters

value	If value is `IlTrue`, the selection extends over the whole width of the string list. If value is `IlFalse`, only the labels are selected.
redraw	A Boolean value specifying whether the string list should be redrawn.

See Also: hasFullSelection().

void IlvStringList::useToolTips ( IlBoolean value = IlTrue )

Specifies whether the string list should display tooltips.

A tooltip is displayed when the cursor is over a partially visible item.

Parameters

value A Boolean value specifying whether the string list should display tooltips (IlTrue) or not (IlFalse).

See Also: hasToolTips().

Rogue Wave ViewsGadgets Package API Reference Guide

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Styling

Constructor & Destructor Documentation

Member Function Documentation

Rogue Wave Views
Gadgets Package API Reference Guide