Reference for the Mosaic class Core::HorizontalList
The class Core::HorizontalList provides a generic horizontal 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 horizontally from left to right. If vertical arrangement is desired, please use the class Core::VerticalList.
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 the given items don't 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 GetPaddingLeftArea();
The method GetPaddingLeftArea() returns a rectangular area within the list view reserved for the padding specified in the property PaddingLeft. The area is expressed in coordinates relative to the top-left corner of the view's Owner. If no PaddingLeft 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 GetPaddingRightArea();
The method GetPaddingRightArea() returns a rectangular area within the list view reserved for the padding specified in the property PaddingRight. The area is expressed in coordinates relative to the top-left corner of the view's Owner. If no PaddingRight 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 rearrages 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.
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 external slot method OnLoadItem. In this manner the slot method can determine the corresponding content in the associated data source. The first item has the index 0, the second 1, and so far. The item itself is available in the variable View.
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.
property int32 ItemWidth = 24;
The property 'ItemWidth' stores the width of all items within the list and is expressed in pixel.
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 and the item's view can be accessed. For this purpose the variables Item and View are available. Please note, the class of the item is predetermined by the property ItemClass. Therefore you will explicitly need to typecast the View variable to this class before accessing any of its properties.
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 width 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 PaddingLeft = 0;
The property 'PaddingLeft' determines how many pixel should be reserved left to the first list item. This area is assumed as an empty part of the list.
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 left padding use the method GetPaddingLeftArea().
Please note, if the list is configured with the property Endless == 'true', the padding area is ignored.
property int32 PaddingRight = 0;
The property 'PaddingRight' determines how many pixel should be reserved right to the last list item. This area is assumed as an empty part of the list.
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 right padding use the method GetPaddingRightArea().
Please note, if the list is configured with the property Endless == 'true', the padding area is ignored.
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 item which is about to be loaded by the external slot method OnLoadItem. In this manner the slot method can directly access and modify the item's properties. Please note, the class of the item is predetermined by the property ItemClass. The index of the item is available in the variable Item.