Reference for the Mosaic class Core::VerticalList

Core::VerticalList
Endless
Item
ItemClass
ItemHeight
NoOfItems
OnLoadItem
OnQueryItemClass
OnQueryItemHeight
OnUpdate
PaddingBottom
PaddingTop
QueriedItemClass
QueriedItemHeight
ScrollOffset
SelectedItem
SlideHandler
View
ViewSize
AdjustList()
EnsureVisible()
GetItemAtPosition()
GetItemsArea()
GetPaddingBottomArea()
GetPaddingTopArea()
GetViewForItem()
InvalidateItems()
IsScrollEffectActive()
StopScrollEffect()
Core::Group
AlphaBlended
Buffered
Embedded
Enabled
Focus
Opacity
Visible
Add()
AddBehind()
BroadcastEvent()
BroadcastEventAtPosition()
CountDialogs()
CountViews()
DismissDialog()
DispatchEvent()
DrawBackground()
DrawForeground()
FadeGroup()
FindActiveDialogByClass()
FindCurrentDialog()
FindDialogByClass()
FindNextView()
FindPrevView()
FindSiblingView()
FindViewAtPosition()
FindViewInDirection()
FindViewWithinArea()
GetContentArea()
GetDialogAtIndex()
GetIndexOfDialog()
GetIndexOfView()
GetMinimalSize()
GetViewAtIndex()
GlobalPosition()
HasViewState()
Init()
InvalidateArea()
InvalidateLayout()
InvalidateViewState()
IsActiveDialog()
IsCurrentDialog()
IsDialog()
LocalPosition()
ObtainFocus()
PresentDialog()
Remove()
RemoveAll()
Restack()
RestackBack()
RestackBehind()
RestackTop()
SwitchToDialog()
UpdateLayout()
UpdateViewState()
Core::RectView
Bounds
Core::View
Layout
Owner
StackingPriority
AdjustDrawingArea()
ArrangeView()
ChangeViewState()
CursorHitTest()
Draw()
GetExtent()
GetRoot()
HandleEvent()
MoveView()

SEE ALSO

Using the List view to display vertically arranged items.

The class Core::VerticalList provides a generic vertical list view. Its purpose is the presentation and the management of list items. Within the view the items can be scrolled and the user can select them. This is very useful to show e.g. the records from a data base. Within the view the items are arranged vertically from top to bottom. If horizontal arrangement is desired, please use the class Core::HorizontalList.

method void AdjustList
(
arg Effects::Int32Effect aAnimationEffect,
arg slot aOnDoneScroll
);

The method AdjustList() scrolls the list in order to ensure that the entire view's area is filled as much as possible with items. The method is useful, if the number of items (NoOfItems) or the size of list view (Bounds) have been changed at the runtime.

This scroll operation can optionally be animated by an effect passed in the parameter aAnimationEffect. If aAnimationEffect == null, no animation is used and the scrolling is executed immediately. After the operation is done, a signal is sent to the optional slot method specified in the parameter aOnDoneScroll.

Please note, calling the method AdjustList() while an animation is running will terminate it abruptly without the slot method aOnDoneScroll being notified. More flexible approach to stop an activate animation is to use the method StopScrollEffect(). Whether an animation is currently running can be queried by using the method IsScrollEffectActive().

property bool Endless = false;

The property 'Endless' controls the mode of the list. Setting this property to the value 'true' will cause the list to behave as if its content were infinite. In particular the list displays all items according to their order and after the last item has been reached the list starts again with the first item. The effect is as if the list items were arranged on an endless band.

Please note, if the list area is bigger than the area occupied by all list items, several duplicates of one and the same item may appear within the list area.

method void EnsureVisible
(
arg int32 aItem,
arg bool aFullyVisible,
arg Effects::Int32Effect aAnimationEffect,
arg slot aOnDoneScroll
);

The method EnsureVisible() scrolls the content of the list until the list item with the index aItem lies partially or fully within the view's area Bounds. The first list item has the index 0, the second 1, and so far. The respective mode is determined by the parameter aFullyVisible.

This scroll operation can optionally be animated by an effect passed in the parameter aAnimationEffect. If aAnimationEffect == null, no animation is used and the scrolling is executed immediately. After the operation is done, a signal is sent to the optional slot method specified in the parameter aOnDoneScroll.

Please note, calling the method EnsureVisible() while an animation is running will terminate it abruptly without the slot method aOnDoneScroll being notified. More flexible approach to stop an activate animation is to use the method StopScrollEffect(). Whether an animation is currently running can be queried by using the method IsScrollEffectActive().

method int32 GetItemAtPosition
(
arg point aPos
);

The method GetItemAtPosition() tries to determine an item at the given position aPosition. This position is valid in the coordinate space of the view's Owner. If an item could be found, the method returns its index. The first item has the index 0, the second 1, and so far. If no item is found, the method returns -1.

method rect GetItemsArea
(
arg int32 aFirstItem,
arg int32 aLastItem
);

The method GetItemsArea() determines a rectangular area within the list view occupied by one or more items. The index of the item to start the calculation is specified in the parameter aFirstItem. The parameter aLastItem specifies the index of the last affected item. The first item has the index 0, the second 1, and so far. The determined area is expressed in coordinates relative to the top-left corner of the view's Owner. If none of the specified items does exist, the method returns an empty area.

Please note, if the list is configured with the property Endless == 'true', multiple copies of one and the same item may be displayed on the screen. In such case the method returns the area corresponding to the first set of items lying actually within the list view.

method rect GetPaddingBottomArea();

The method GetPaddingBottomArea() returns a rectangular area within the list view reserved for the padding specified in the property PaddingBottom. The area is expressed in coordinates relative to the top-left corner of the view's Owner. If no PaddingBottom has been specified, the method returns an empty rectangle.

Please note, if the list is configured with the property Endless == 'true', the padding area is ignored and this method returns an empty rectangle <0,0,0,0>.

method rect GetPaddingTopArea();

The method GetPaddingTopArea() returns a rectangular area within the list view reserved for the padding specified in the property PaddingTop. The area is expressed in coordinates relative to the top-left corner of the view's Owner. If no PaddingTop has been specified, the method returns an empty rectangle.

Please note, if the list is configured with the property Endless == 'true', the padding area is ignored and this method returns an empty rectangle <0,0,0,0>.

method Core::View GetViewForItem
(
arg int32 aItem
);

The method GetViewForItem() returns the view corresponding to the item with the number specified in the parameter aItem. The first item has the number 0, the second 1, and so far.

Since this list component manages the views internally within a small cache maintaining only such views which are visible, the method may return 'null' when asking for the view corresponding to an item lying outside the visible area of the list. Similarly, the method returns 'null' when it has been used in context of the OnLoadItem slot method. OnLoadItem is signaled while the list updates and rearranges its items. Trying to access the views during this phase would interfere with the update process returning incorrect views. Don't call GetViewForItem() from OnLoadItem slot method.

Please note, if the list is configured with the property Endless == 'true', multiple copies of one and the same item may be displayed on the screen. In such case the method returns the view corresponding to the first matching item lying actually within the cache.

method void InvalidateItems
(
arg int32 aFirstItem,
arg int32 aLastItem
);

The method InvalidateItems() forces the list to reload one or more items. The index of the item to start the reload operation is specified in the parameter aFirstItem. The parameter aLastItem specifies the index of the last affected item. The first item has the index 0, the second 1, and so far. The operation can cause the list view to invoke the external OnLoadItem slot method for each affected item.

If the list is configured to manage items of different height (see the property OnQueryItemHeight), invalidating items also updates the size of the affected items as well as the position of all following items.

method bool IsScrollEffectActive();

The method IsScrollEffectActivate() returns 'true' if the vertical list is currently performing a scroll animation initiated by a preceding invocation of the EnsureVisible() or AdjustList() method.

The active animation can be stopped in a controlled way by using the method StopScrollEffect().

var int32 Item = -1;

The variable 'Item' stores the index of the item which is about to be loaded by the slot method associated to the property OnLoadItem, or the index of the item to estimate its size by the slot method associated to the property OnQueryItemHeight, or the index of the item to estimate its class by the slot method associated to the property OnQueryItemClass.

In this manner the slot methods can determine the corresponding contents in the associated data source. The first item has the index 0, the second 1, and so far.

property class ItemClass = Views::Text;

The property 'ItemClass' determines the kind of items to display in the list. Depending on this class, simple text items, image items or even complex GUI components can be shown. At the runtime the list view uses this class to create new items dynamically. The loading of the items is realized by an external slot method which should be assigned to the property OnLoadItem. Please note, that only classes derived from Core::View are able to be shown.

If your application case does require the list to manage items of different types, use the property OnQueryItemClass. In such case, the property 'ItemClass' will store the default item class, which is used if no other value has been provided in the 'OnQueryItemClass' slot method.

property int32 ItemHeight = 24;

The property 'ItemHeight' stores the height, in pixel, for the items existing within the list. Consequently, all list items will have equal height. Please note, the minimum height for the items is limited to 1 pixel.

If your application case does require the list to manage items of different height, use the property OnQueryItemHeight. In such case, the property 'ItemHeight' will store the default item height, which is used if no other value has been provided in the 'OnQueryItemHeight' slot method.

property int32 NoOfItems = 0;

The property 'NoOfItems' stores how many items are currently managed within the list. This value should correspond to the number of e.g. records in the associated data source.

property slot OnLoadItem = null;

The property 'OnLoadItem' should refer to a slot method, which will be invoked by the list view in order to load an item with its corresponding content. Within the slot method the index of the affected item, the item's view and the expected size of the item can be accessed. For this purpose the variables Item, View and ViewSize are available.

Please note, the class of the item's view is predetermined by the property ItemClass or the value obtained by the slot method associated to the property OnQueryItemClass. Therefore you will explicitly need to typecast the View variable to this class before accessing any of its properties.

Important, the implementation of the OnLoadItem slot method should also adjust the size of the view to be ViewSize. For performance reasons, the implementation of the slot method should be as fast as possible.

property slot OnQueryItemClass = null;

The property 'OnQueryItemClass' can refer to a slot method, the list view will invoke in order to query the class of an item. In this manner, the list view can manage items of different classes. If there is no slot method associated to this property, all items within the list will have equal class according to the value stored in the property ItemClass.

Within the associated slot method the implementation should access the index of the affected item by evaluating the variable Item, estimate the class of this item and store this value in the variable QueriedItemClass (don't confuse it with the property ItemClass).

Using OnQueryItemClass allows the implementation of lists with flexible item types. This, however, requires the list to discard and recreate the item views when the list is scrolled. This may reduce the performance of the list. In any case the implementation of the associated slot method should be optimized to be as fast as possible. Especially when the list manages many items.

property slot OnQueryItemHeight = null;

The property 'OnQueryItemHeight' can refer to a slot method, the list view will invoke in order to query the height of an item. In this manner, the list view can manage items of different height. If there is no slot method associated to this property, all items within the list will have equal height according to the value stored in the property ItemHeight.

Within the associated slot method the implementation should access the index of the affected item by evaluating the variable Item, estimate the height of this item and store this value in the variable QueriedItemHeight (don't confuse it with the property ItemHeight). Please note, the minimum height of an item is limited to 1 pixel.

Using OnQueryItemHeight allows the implementation of lists with flexible item height. This, however, requires the list to iterate over the items when the position of an item is calculated. This may reduce the performance of the list significantly. In any case the implementation of the associated slot method should be optimized to be as fast as possible. Especially when the list manages many items.

property slot OnUpdate = null;

The property 'OnUpdate' can refer to a slot method, which should be invoked by the list component each time the displayed content is scrolled, the number of items is changed or the height of an item is altered. This method is intended to update the position of decorations, like list headers or footers. It's up to you to provide the slot method and to fill it with the desired behavior.

property int32 PaddingBottom = 0;

The property 'PaddingBottom' determines how many pixel should be reserved below the last list item. This area is assumed as an empty part of the list. Please note, if the list is configured with the property Endless == 'true', the padding area is ignored.

The padding allows you to combine the list with additional decorations like a footer view, etc.. To ensure that the decoration is arranged when the list scrolls please implement a slot method and attach it to the property OnUpdate. In the slot method the position of the decoration can be adjusted.

To get the current position of the bottom padding use the method GetPaddingBottomArea().

property int32 PaddingTop = 0;

The property 'PaddingTop' determines how many pixel should be reserved above the first list item. This area is assumed as an empty part of the list. Please note, if the list is configured with the property Endless == 'true', the padding area is ignored.

The padding allows you to combine the list with additional decorations like a header view, etc.. To ensure that the decoration is arranged when the list scrolls please implement a slot method and attach it to the property OnUpdate. In the slot method the position of the decoration can be adjusted.

To get the current position of the top padding use the method GetPaddingTopArea().

var class QueriedItemClass;

The variable 'QueriedItemClass' is used to receive the class of an item in case of a list configured to manage items of different types. In such case, the list will invoke the slot method stored in the property OnQueryItemClass. This slot method should evaluate the variable Item as index to address the item whose class should be estimated. The estimated class should then be stored in the variable QueriedItemClass.

var int32 QueriedItemHeight;

The variable 'QueriedItemHeight' is used to receive the height of an item in case of a list configured to manage items of different size. In such case, the list will invoke the slot method stored in the property OnQueryItemHeight. This slot method should evaluate the variable Item as index to address the item whose height should be estimated. The estimated height should then be stored in the variable QueriedItemHeight.

property int32 ScrollOffset = 0;

The property 'ScrollOffset' stores the displacement of the list content. Changing of this property automatically causes the list to move its items accordingly.

property int32 SelectedItem = -1;

The property 'SelectedItem' stores the index of the currently selected item or -1 if no item is selected. The first item has the index 0, the second 1, and so far. If visible, the selected item can additionally become focused and thus react to keyboard events. To highlight the selected item you can implement the method UpdateViewState() of the item's class and adapt there the aspect of the item accordingly to its current state Focused and Selected.

property Core::SlideTouchHandler SlideHandler = null;

The property 'SlideHandler' provides an interface, where a slide handler can be attached. In this manner the handler can control the list view and the user can scroll its content by simply touching the slide handler on the screen.

method void StopScrollEffect
(
arg bool aSetEndValue,
arg bool aSignalOnDoneScroll
);

The method StopScrollEffect() stops the actually active scroll animation effect initiated by the preceding invocation of the method EnsureVisible() or AdjustList().

If the parameter aSetEndValue is 'true' the scroll position of the list is set to the end value of the actually active animation effect as if the effect had reached its end position. If this parameter is 'false' the latest scroll position remains unchanged.

If the parameter aSignalOnDoneScroll is 'true' a signal is sent to the slot method passed in the parameter aOnDoneScroll in the invocation of EnsureVisible() or AdjustList() as if the animation had been finished regularly. If this parameter is 'false' the actual animation is stopped without notifying the slot method.

var Core::View View;

The variable 'View' refers to the view of the item which is about to be loaded by the slot method associated to the property OnLoadItem. In this manner the slot method can directly access and modify the view's properties. Please note, the class of the item's view is predetermined by the property ItemClass or by the value obtained by the slot method associated to the property OnQueryItemClass. The index of the item is available in the variable Item.

var point ViewSize;

The variable 'ViewSize' stores the size of the item which is about to be loaded by the slot method associated to the property OnLoadItem. In this manner the slot method can adjust the size of the corresponding view.