com.softwareag.mobile.runtime.toolkit.ui

Class ListView

java.lang.Object

com.softwareag.mobile.runtime.nui.nUIObject

com.softwareag.mobile.runtime.nui.nUIDisplayObject

com.softwareag.mobile.runtime.nui.nUIElementDisplay

com.softwareag.mobile.runtime.nui.nUIContainerElement

com.softwareag.mobile.runtime.toolkit.ui.ListView

All Implemented Interfaces:

com.softwareag.mobile.runtime.nui.ICustomBackground, com.softwareag.mobile.runtime.nui.nUIConstants, com.softwareag.mobile.runtime.nui.nUIEventListener

public class ListView
extends com.softwareag.mobile.runtime.nui.nUIContainerElement
implements com.softwareag.mobile.runtime.nui.nUIEventListener

A ListView displays a given number of nUIDisplayObjects, typically subclasses of nUITableButtons, in a vertically scrollable list. Each of the nUIDisplayObjects is referred to as a cell and represents one row in the ListView.

To create a ListView a IListViewDelegate needs to be provided. Using the delegate the ListView gets it's number of rows, cells for given row indexes, paginations settings and separators. Delegates are also notified of events on the cells. Overwrite notification methods in your delegate implementation to handle events.

To create or update a ListView call reload(). This will remove existing cells and recreate it's contents by again calling the IListViewDelegate.getNumberOfRows(ListView) and IListViewDelegate.getCell(ListView, int). Between cells there might be a separator that again could be any subclass of nUIDisplayObject, but typically nUISeparatorElements would be used.

A ListView might also have one header cell, that will always be the first cell at the top. This cell is not removed on reload() and is not counted as row. You might use a header cell to add for example add a nUISearchEntry.

If pagination is used, ListViews will split the total number of rows into pages with a maximum number of rows. This might be needed for large amounts of rows to reduce load time. Pagination cells will be added automatically to navigate back and forward, use IListViewDelegate.getPaginationNextPageCell(ListView, int) and IListViewDelegate.getPaginationPreviousPageCell(ListView, int) to create the cells with your content.

Version:

10.1.0.0000-0462

Field Summary

Fields inherited from class com.softwareag.mobile.runtime.nui.nUIContainerElement

SAVED_POINTER_LOCATIONS

Fields inherited from class com.softwareag.mobile.runtime.nui.nUIElementDisplay

Y_IDENTIFIER_PREV_BOTTOM

Fields inherited from class com.softwareag.mobile.runtime.nui.nUIDisplayObject

COLOR_BACKGROUND_NORMAL, COLOR_BLACK, COLOR_FOREGROUND_DARK, COLOR_FOREGROUND_LIGHT, COLOR_FOREGROUND_NORMAL, COLOR_TRANSPARENT, COLOR_WHITE, DIMENSIONS_IDENTIFIER_PARENT_DIMENSIONS

Fields inherited from class com.softwareag.mobile.runtime.nui.nUIObject

event_listener, event_listener_exclusive, first_child, last_child, next_sibling, nuiid, parent, prev_sibling, unlink_children_on_removal_from_parent

Fields inherited from interface com.softwareag.mobile.runtime.nui.nUIConstants

bottom, center, centre, CREATE, CUSTOM_EVENT_CODE0, EVT_BACK_BUTTON, EVT_COMPLETED_EDIT, EVT_DOUBLE_TAP, EVT_GAIN_FOCUS, EVT_LONG_PRESS, EVT_LOSE_FOCUS, EVT_ON_ADDITION, EVT_PICKER_CANCEL, EVT_PICKER_OK, EVT_POST_EDIT, EVT_PRE_EDIT, EVT_SWIPE_LEFT, EVT_SWIPE_RIGHT, EVT_TIMER_COMPLETE, EVT_TRANSITION_FROM_COMPLETE, EVT_TRIGGER, EVT_TRIGGER_HTTP_FAIL, EVT_TRIGGER_HTTP_SUCCESS, GESTURE_DOUBLE_TAP, GESTURE_LONG_PRESS, GESTURE_NONE, GESTURE_SWIPE, left, MAX_DY_FOR_SWIPE, MIN_DX_FOR_SWIPE, MIN_SCROLL_START_THRESHOLD, NO_YES, OFF_ON, POINTER_STATE_DRAGGED, POINTER_STATE_PRESSED, POINTER_STATE_PRESSED_AND_RELEASED, POINTER_STATE_RELEASED, REMOVE, right, size_absolute, size_huge, size_large, size_medium, size_relative, size_small, size_tiny, style_bold, style_default, style_italic, style_underlined, TEXT_DIRECTION_LTR, TEXT_DIRECTION_RTL, top

Constructor Summary

Constructors

Constructor and Description
ListView(int nuiid, IListViewDelegate delegate) Creates a new ListView with a given delegate.

Method Summary

Modifier and Type	Method and Description
java.util.Vector	allCells() Returns all cell objects without header cell, pagination cell and separators.
java.lang.Object	cellForRowIndex(int rowIndex) Returns the cell for a given index in the ListView.
int	getCurrentPaginationIndex() Returns the current page index of the ListView.
IListViewDelegate	getDelegate() Call this method if you want the IListViewDelegate that is currently used by the ListView.
com.softwareag.mobile.runtime.nui.nUIObject	getHeaderElement() Returns the current header cell used in the ListView.
int	getMaxNumberOfRowsPerPage() Returns the maximum number of rows used for pagination in the ListView.
int	getRowHeight() Deprecated. The native property is no longer supported. Please use the new ListView.
boolean	getUsesPagingation() Returns the current pagination setting of the ListView.
void	insertRowIndex(int row) Inserts a new cell at the passed index. Delegates to insertRowIndexes(int[]).
void	insertRowIndexes(int[] rows) Inserts new cells at the indexes passed in rows parameter.
void	insertRowIndexes(int rowIndex, int numberOfRows) Inserts a number of cells beginning at the provided rowIndex
boolean	nUIEventCallback(com.softwareag.mobile.runtime.nui.nUIObject object, int eventType) Manages all events for the cells in the ListView and forwards the events to the delegate.
void	onRemoved() Overwritten to clear the list view delegate.
void	reload() Call this method to reload the content of the ListView.
void	reloadRowIndex(int row) Reloads the cell at the passed index row.
void	reloadRowIndexes(int[] rows) Reloads all cells at the passed indexes.
void	removeAllElements() Removes all cells and clears the underlying cache.
void	removeRowIndex(int row) Removes a cell at the passed index.
void	removeRowIndexes(int[] rows) Removes all cells provided by the passed indexes.
int	rowIndexForCell(com.softwareag.mobile.runtime.nui.nUIObject cell) Returns the given cell's (row) index in the ListView.
void	setCurrentPaginationIndex(int index) Call this method with a new index to change the pagination index.
void	setDelegate(IListViewDelegate delegate) Call this method if you want to set a new IListViewDelegate.
void	setHeaderElement(com.softwareag.mobile.runtime.nui.nUIObject headerElement) Call this method to set a new header cell for the ListView.
void	setRowHeight(int rowHeight) Deprecated. The native property is no longer supported. Please use the new ListView.
void	setSelectionFromTop(int index, int offsetY) Deprecated. The native property is no longer supported. Please use the new ListView.
void	setSortEnabled(boolean enabled) Deprecated. The native property is no longer supported. Please use the new ListView.

Methods inherited from class com.softwareag.mobile.runtime.nui.nUIContainerElement

getBgimageScroll, getHscrollable, getScreenInnerX, getScreenInnerY, getVscrollable, insertAt, setBgimageScroll, setHscrollable, setVscrollable

Methods inherited from class com.softwareag.mobile.runtime.nui.nUIElementDisplay

applyBackground, applyBackground, applyBackground

Methods inherited from class com.softwareag.mobile.runtime.nui.nUIDisplayObject

getBackgroundDrawable, getBgcolor, getBottom, getFocus, getFocusable, getGesturable, getHeight, getInnerHeight, getInnerWidth, getInnerX, getInnerY, getLeft, getMaxChildX, getMaxChildY, getRight, getScreenX, getScreenY, getTop, getTopLevelParentView, getTopLevelParentWindow, getTriggerable, getWidth, getX, getY, insertAtInternal, isEnabled, isVisible, remove, setBackgroundDrawable, setBgcolor, setBottom, setChildFocus, setEnabled, setFocus, setFocusable, setGesturable, setHeight, setInnerHeight, setInnerWidth, setInnerX, setInnerY, setLeft, setRight, setTop, setTriggerable, setVisible, setWidth, setX, setY

Methods inherited from class com.softwareag.mobile.runtime.nui.nUIObject

add, addEventListener, childElementAt, childIndexOf, getTag, insertAfter, insertBefore, outputChildHierarchy, remove, removeEventListener, replace, replace, setTag

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ListView

public ListView(int nuiid,
                IListViewDelegate delegate)

Creates a new ListView with a given delegate. It is important to provide a IListViewDelegate when creating the ListView, because reload() will be automatically called to create and display cells.

Parameters:

nuiid -

delegate -

Method Detail

reload

public void reload()

Call this method to reload the content of the ListView. When reloaded, first all existing cells are removed (except header cells) and IListViewDelegate.getNumberOfRows(ListView) is called to get the new number of cells (rows) to be displayed. For each row IListViewDelegate.getCell(ListView, int) is called again with the current index

You typically invoke this method if your data model changed and cells need to be recreated or updated to reflect the changes in the UI. Make sure to only reload if really needed, this will recreate all the cells.

reloadRowIndex

public void reloadRowIndex(int row)

Reloads the cell at the passed index row.
Delegates to reloadRowIndexes(int[]).

Parameters:

row -

reloadRowIndexes

public void reloadRowIndexes(int[] rows)

Reloads all cells at the passed indexes.

Parameters:

rows -

insertRowIndex

public void insertRowIndex(int row)

Inserts a new cell at the passed index.
Delegates to insertRowIndexes(int[]).

Parameters:

row -

See Also:

insertRowIndexes(int, int)

insertRowIndexes

public void insertRowIndexes(int rowIndex,
                             int numberOfRows)

Inserts a number of cells beginning at the provided rowIndex


Parameters:

rowIndex -

numberOfRows -

See Also:

insertRowIndexes(int, int)

insertRowIndexes

public void insertRowIndexes(int[] rows)

Inserts new cells at the indexes passed in rows parameter. For every index IListViewDelegate.getCell(ListView, int) will be called passing the index to the delegate to create a new instance of the nUIDisplayObject to be inserted.

The indexes must be greater than or equal to 0 and less than or equal to the current number of elements managed by the ListView plus the number of indexes to be inserted. In case the index equals the latter condition the element is added (appended) to the ListView. Indexes to be inserted must also be ordered increasing, e.g. new int[] {0,2,3,5}. An IndexOutOfBoundsException will be thrown if indexes do not match those conditions.

Parameters:

rows - the indexes starting with 0 of the rows to be insterted

Throws:

java.lang.IndexOutOfBoundsException - if indexes are out of range

removeRowIndex

public void removeRowIndex(int row)

Removes a cell at the passed index.
Delegates to removeRowIndexes(int[]).

Parameters:

row -

removeRowIndexes

public void removeRowIndexes(int[] rows)

Removes all cells provided by the passed indexes.

Parameters:

rows -

removeAllElements

public void removeAllElements()

Removes all cells and clears the underlying cache.
Does not remove the header element. To remove the header, call setHeaderElement(nUIObject) with null as parameter value.

rowIndexForCell

public int rowIndexForCell(com.softwareag.mobile.runtime.nui.nUIObject cell)

Returns the given cell's (row) index in the ListView. For index calculation only cells are used, header and separators do not have rowIndexes. Call this method in combination with cellForRowIndex(int). Please note, nUIObject.childIndexOf(nUIObject) will not necessarily return the same index.

Parameters:

cell - the cell object you want to get the index for

Returns:

the index of the given cell in the ListView

cellForRowIndex

public java.lang.Object cellForRowIndex(int rowIndex)

Returns the cell for a given index in the ListView. Only use rowIndexForCell(nUIObject) to get the row index of a cell. Please note, nUIObject.childElementAt(int) will not necessarily return the same index

Parameters:

rowIndex - the index of a cell (row) you want the cell object for

Returns:

the cell object at given index

setSelectionFromTop

public void setSelectionFromTop(int index,
                                int offsetY)

Deprecated. The native property is no longer supported. Please use the new ListView.

Sets the selection to the passed cell index. The ListView scrolls to the cell, correspondent by the passed index, if this cell isn't in the ListView's visible area.

This method has only an effect by using the native ListView feature.

Parameters:

index -

offsetY -

allCells

public java.util.Vector allCells()

Returns all cell objects without header cell, pagination cell and separators.

Returns:

all cell objects

getDelegate

public IListViewDelegate getDelegate()

Call this method if you want the IListViewDelegate that is currently used by the ListView. If not set, null will be returned.

Returns:

the ListView IListViewDelegate or null

setDelegate

public void setDelegate(IListViewDelegate delegate)

Call this method if you want to set a new IListViewDelegate. All following calls of the ListView to it's delegate will use the new instance. Make sure to provide a delegate when creating the ListView instance by using ListView(int, IListViewDelegate) constructor.

Parameters:

delegate -

getRowHeight

public int getRowHeight()

Deprecated. The native property is no longer supported. Please use the new ListView.

Returns the current assigned row height.

This method has only an effect by using the native ListView feature.

Returns:

setRowHeight

public void setRowHeight(int rowHeight)

Deprecated. The native property is no longer supported. Please use the new ListView.

Sets the rowHeight for each cell based on the passed positive integer value. The method is only implemented for native ListViews on iOS. Use this method to globally set the rowHeight for each cell. This will have an performance advantage by using a huge amount of cells (>200).

This method has only an effect by using the native ListView feature.

Parameters:

rowHeight -

getHeaderElement

public com.softwareag.mobile.runtime.nui.nUIObject getHeaderElement()

Returns the current header cell used in the ListView. The header cell will always be the first cell, but will scroll vertically! If you need to have a static, not scrolling, header above the scrollable list of cells

Returns:

the current header cell used or null.

setHeaderElement

public void setHeaderElement(com.softwareag.mobile.runtime.nui.nUIObject headerElement)

Call this method to set a new header cell for the ListView. The new header cell will replace an existing one. It will always be the first cell in the ListView and does not have a row index. Use getHeaderElement() to access the current cell instead. Header cells do scroll with all other cells, it is not statically bound to the top of the ListView.

Parameters:

headerElement - the new header cell to be used or null to remove the current cell in use

getUsesPagingation

public boolean getUsesPagingation()

Returns the current pagination setting of the ListView. If pagination is used, getMaxNumberOfRowsPerPage() is called to determine the maximum number of rows to be displayed in the ListView and the total number of cells will be split into pages with the given getMaxNumberOfRowsPerPage().

To navigate the pages, the ListView will automatically add cells to go back or forward one. To configure the cells to be used for navigation, use IListViewDelegate.getPaginationPreviousPageCell(ListView, int) and IListViewDelegate.getPaginationNextPageCell(ListView, int).

Returns:

true if pagination is enabled, false if not

getMaxNumberOfRowsPerPage

public int getMaxNumberOfRowsPerPage()

Returns the maximum number of rows used for pagination in the ListView. To change the value, use IListViewDelegate.getMaxNumberPaginationRows(ListView).

Returns:

the current maximum number of cells (rows) per page

getCurrentPaginationIndex

public int getCurrentPaginationIndex()

Returns the current page index of the ListView. This index changes automatically as the user navigates the list.

Returns:

the current page index of the ListView

setCurrentPaginationIndex

public void setCurrentPaginationIndex(int index)

Call this method with a new index to change the pagination index. You need to call reload() after changing the pagination index to make the ListView actually change to the new index.

Parameters:

index - the new index of the page to be used.

setSortEnabled

public void setSortEnabled(boolean enabled)

Deprecated. The native property is no longer supported. Please use the new ListView.

Enable or disable drag&drop based resorting of the elements in the ListView. Make sure to implement the delegate methods for managing manual sorting.

This method has only an effect by using the native ListView feature.

Parameters:

enabled - true if sorting should be enabled, false if sorting should be disabled

nUIEventCallback

public boolean nUIEventCallback(com.softwareag.mobile.runtime.nui.nUIObject object,
                                int eventType)

Manages all events for the cells in the ListView and forwards the events to the delegate.

Specified by:

nUIEventCallback in interface com.softwareag.mobile.runtime.nui.nUIEventListener

Returns:

true if the event was handled, false if it was not handled

onRemoved

public void onRemoved()

Overwritten to clear the list view delegate.

If this method is overwritten, clients need to make sure to call the super method, othwerwise memory leaks are possible.

Overrides:

onRemoved in class com.softwareag.mobile.runtime.nui.nUIDisplayObject