SUI.ListView

SUI.ListView is a component to display data in a list with columns. The list can be used to select one multiple rows. To aid the user's selection the rows can be sorted per column.

Extends SUI.Box
Defined in: ListView.js


Constructor summary

Attr. Name / Description
public

SUI.ListView(object, see, arg)

Construct a SUI.ListView object. A large number of variables can be set to customize the listview to your specific needs.

Member summary

Attr. Type Name Description
private SUI.Border

_border

The box's border.

private int

_bottom

The bottom position of the box.

private HTMLElementNode

_el

The box's element node.

private int

_height

The height of the box.

private int

_left

The left position of the box.

private int

_listeners

The listeners array.

private int

_maxHeight

The maximum height of the box.

private int

_maxWidth

The maximum width of the box.

private int

_minHeight

The minimum height of the box.

private int

_minWidth

The minimum width of the box.

private SUI.Padding

_padding

The box's padding.

private SUI.Box

_parent

The box's parent element.

private int

_right

The right position of the box.

private int

_top

The top position of the box.

private int

_width

The width of the box.

public

CELL_PADDING_SIDES

Left and right padding of a cell

public

CELL_PADDING_TOP

Top padding of a cell

public

HEADER_BORDER_BOTTOM_WIDTH

Header border (only below the header).

public

HEADER_HEIGHT

Header height (including bottom border)

public

HEADER_PADDING_LONG

Side padding for a header if a direction indicator needs to be drawn at that side.

public

HEADER_PADDING_SHORT

Side padding for a header if a no direction indicator needs to be drawn at that side.

public

HEADER_PADDING_TOP

Padding top of the headers

public

HEADER_SORT_ICON_MARGIN_TOP

Top margin of the sort direction indicator.

public

HEADER_SORT_ICON_SIZE

Size (width/height) of the icon for the sort direction indicator.

public

HEADER_SPACER_WIDTH

The half-width of the spacer

public

ICON_SIZE

Size (width/height) of the row icons.

public

ROW_BORDER_WIDTH

Row border width (top and bottom)

public

ROW_HEIGHT

Row height (including top and bottom border)

public

SEPARATOR_MARGIN_V

The vertical margin for the separator (determines the length of the separator).

public

SEPARATOR_WIDTH

Width of the separator on the spacer between the headers.

Method summary

Attr. Type Name / Description
public

absPos()

Get the absolute position (top/left) of this box on the page. Note: You can only use this function if the HTML content of the page is fully rendered.

public

addClass(cls)

Add a CSS class name to the class list of the HTML element associated with the box.

public

addListener(type, listener)

Add/register a listener function. This way it is possible to register more than one listener function on one target.

public SUI.Border

border(b)

Get or set the border definition of the box.

public int

bottom(b)

Get or set the bottom of the box.

public

callListener(type)

Call a listener function. Execute the default and additional listener functions. Note: the framework should not execute the default listeners directly but always through this method to ensure the execution of additional listener functions.

public int

clientHeight()

Get the client height of the box. The client height is the height of the box minus the top and bottom border and padding width.

public int

clientWidth()

Get the client width of the box. The client width is the width of the box minus the left and right border and padding width.

public

display()

Display the listview control. Set the CSS size and position of the list and all the headers. Then render the rows.

public

draw()

Draw the box on the screen. It executes a two phase process: a layout phase in which the size and positions of the box (and of it's contents, for more complex derivatives) is calculated and a display phase in which the CSS size and position of the box's (and possible it's child elements) is set.

public HTMLElementNode

el()

Get the HTML element node of the box.

public int

height(h)

Get or set the height of the box.

public

layOut()

Lay out the listview control. Calculate the size and position of the list and headers.

public int

left(l)

Get or set the left of the box.

public

loadData(data, selected, focussed)

(Re)load data into the list view.

public int

maxHeight(mh)

Get or set the maximum height of the box.

public int

maxWidth(mw)

Get or set the maximum width of the box.

public int

minHeight(mh)

Get or set the minimum height of the box.

public int

minWidth(mw)

Get or set the minimum width of the box.

public

onClick(row)

onClick event handler: is executed when the user clicks on a row.

public

onContextMenu(x, y)

onContextMenu event handler: is executed when the user uses the context menu click on a row.

public

onDblClick(row)

onDblClick event handler: is executed when the user double clicks on a row.

public

onSelectionChange()

onSelectionChange event handler: is executed when the (set of) row selection(s) changes. TODO: this event handler is not called properly from the code (f.i. id not called when rows are deselected).

public SUI.Padding

padding(p)

Get or set the padding definition of the box.

public SUI.Box

parent(p)

Get or set the parent box of the box. When setting the parent the box's element node will be appended to the parent box's HTML element node.

public

removeBox()

Remove a box from the DOM tree.

public

removeClass(cls)

Remove a CSS class name from the class list of the HTML element associated with the box.

public int

right(r)

Get or set the right of the box.

public

setDim()

Set the CSS dimensions of this box and it's borders and padding. This is typically used in display functions to display boxes at the size and position that was calculated during layout.

public

setIsLoadingImage()

Replace the listview contents with an "is loading" image. Recommended when data is loaded from an external resource.

public

setPos()

Set the CSS postion of this box. This is typically used in display functions to display boxes at position that was calculated during layout. Note: use setDim if you want to set the position and size of the box.

public

setRect(t, l, w, h)

Set the top, left, width and height of a box in one go.

public int

top(t)

Get or set the top of the box.

public int

width(w)

Get or set the width of the box.

 


Constructor

public SUI.ListView( Object object, see, object arg)

Construct a SUI.ListView object. A large number of variables can be set to customize the listview to your specific needs.

Parameters:

Name Type Description
Object object in which the follow entries can be set
see base class
boolean arg.multiselect Enable multiple selection
object[] arg.data The data array of objects in which each object contains column (key) / values pairs
String arg.sort The column key for which the data should be sorted initially
int | Array.<int> arg.selected Array of indexes for the initial row selection
int arg.focussed Index of the row to focus initially
object[] arg.cols The column definition: an array with objects which can contain the following fields:
String arg.cols[].title The header title
String arg.cols[].key Key that corresponds with a key in the data array
int arg.cols[].width Width of the header
int arg.cols[].minWidth Minimum width of the header
int arg.cols[].maxWidth Maximum width of the header
String arg.cols[].align Alignment of the header, options are "left" (default), "center" and "right"
string | function arg.cols[].icon false (default) if no icon is needed or a location of an icon file or a function that returns one. This function takes to parameters, the first is a reference to the row and the second is key of the column to generate an icon location for.
string | function arg.cols[].sort a build in sort method or a user defined one. "text" (default) and "number" are the build in sort methods. The sort function take three parameters: the first is a reference to the data array, the second is the key on which to sort and the third is the search direction (1 or -1).
Function arg.cols[].format_func A user defined format function, this function takes to parameters, the first is a reference to the row and the second is key of the column that needs to be formatted.

Members

private SUI.Border _border

The box's border.

Inherited From: SUI.Box#_border

private int _bottom

The bottom position of the box.

Inherited From: SUI.Box#_bottom

private HTMLElementNode _el

The box's element node.

Inherited From: SUI.Box#_el

private int _height

The height of the box.

Inherited From: SUI.Box#_height

private int _left

The left position of the box.

Inherited From: SUI.Box#_left

private int _listeners

The listeners array.

Inherited From: SUI.Box#_listeners

private int _maxHeight

The maximum height of the box.

Inherited From: SUI.Box#_maxHeight

private int _maxWidth

The maximum width of the box.

Inherited From: SUI.Box#_maxWidth

private int _minHeight

The minimum height of the box.

Inherited From: SUI.Box#_minHeight

private int _minWidth

The minimum width of the box.

Inherited From: SUI.Box#_minWidth

private SUI.Padding _padding

The box's padding.

Inherited From: SUI.Box#_padding

private SUI.Box _parent

The box's parent element.

Inherited From: SUI.Box#_parent

private int _right

The right position of the box.

Inherited From: SUI.Box#_right

private int _top

The top position of the box.

Inherited From: SUI.Box#_top

private int _width

The width of the box.

Inherited From: SUI.Box#_width

public CELL_PADDING_SIDES

Left and right padding of a cell

public CELL_PADDING_TOP

Top padding of a cell

public HEADER_BORDER_BOTTOM_WIDTH

Header border (only below the header).

public HEADER_HEIGHT

Header height (including bottom border)

public HEADER_PADDING_LONG

Side padding for a header if a direction indicator needs to be drawn at that side.

public HEADER_PADDING_SHORT

Side padding for a header if a no direction indicator needs to be drawn at that side.

public HEADER_PADDING_TOP

Padding top of the headers

public HEADER_SORT_ICON_MARGIN_TOP

Top margin of the sort direction indicator.

public HEADER_SORT_ICON_SIZE

Size (width/height) of the icon for the sort direction indicator.

public HEADER_SPACER_WIDTH

The half-width of the spacer

public ICON_SIZE

Size (width/height) of the row icons.

public ROW_BORDER_WIDTH

Row border width (top and bottom)

public ROW_HEIGHT

Row height (including top and bottom border)

public SEPARATOR_MARGIN_V

The vertical margin for the separator (determines the length of the separator).

public SEPARATOR_WIDTH

Width of the separator on the spacer between the headers.


Methods

public absPos()

Get the absolute position (top/left) of this box on the page. Note: You can only use this function if the HTML content of the page is fully rendered.

Inherited From: SUI.Box#absPos

public addClass( String cls)

Add a CSS class name to the class list of the HTML element associated with the box.

Parameters:

Name Type Description
String cls the CSS class name to add

Inherited From: SUI.Box#addClass

public addListener( String type, Function listener)

Add/register a listener function. This way it is possible to register more than one listener function on one target.

Parameters:

Name Type Description
String type The listener type (i.e. "onClick", "onOK", etc).
Function listener The listener function.

Inherited From: SUI.Box#addListener

public SUI.Border border( SUI.Border b)

Get or set the border definition of the box.

Parameters:

Name Type Argument Description
SUI.Border b <optional>
The new border definition (or none to use this method as a getter).

Returns:

SUI.Border the border definition of the box (or null if this method was used as a setter).

Inherited From: SUI.Box#border

public int bottom( int b)

Get or set the bottom of the box.

Parameters:

Name Type Argument Description
int b <optional>
The new bottom of the box (or none to use this method as a getter).

Returns:

int The bottom of the box (or null if this method was used as a setter).

Inherited From: SUI.Box#bottom

public callListener( String type)

Call a listener function. Execute the default and additional listener functions. Note: the framework should not execute the default listeners directly but always through this method to ensure the execution of additional listener functions.

Parameters:

Name Type Description
String type The listener type (i.e. "onClick", "onOK", etc).

Inherited From: SUI.Box#callListener

public int clientHeight()

Get the client height of the box. The client height is the height of the box minus the top and bottom border and padding width.

Returns:

int The client height of the box.

Inherited From: SUI.Box#clientHeight

public int clientWidth()

Get the client width of the box. The client width is the width of the box minus the left and right border and padding width.

Returns:

int The client width of the box.

Inherited From: SUI.Box#clientWidth

public display()

Display the listview control. Set the CSS size and position of the list and all the headers. Then render the rows.

public draw()

Draw the box on the screen. It executes a two phase process: a layout phase in which the size and positions of the box (and of it's contents, for more complex derivatives) is calculated and a display phase in which the CSS size and position of the box's (and possible it's child elements) is set.

Inherited From: SUI.Box#draw

public HTMLElementNode el()

Get the HTML element node of the box.

Returns:

HTMLElementNode the HTML element node of the box.

Inherited From: SUI.Box#el

public int height( int h)

Get or set the height of the box.

Parameters:

Name Type Argument Description
int h <optional>
The new height of the box (or none to use this method as a getter).

Returns:

int The height of the box (or null if this method was used as a setter).

Inherited From: SUI.Box#height

public layOut()

Lay out the listview control. Calculate the size and position of the list and headers.

public int left( int l)

Get or set the left of the box.

Parameters:

Name Type Argument Description
int l <optional>
The new left of the box (or none to use this method as a getter).

Returns:

int The left of the box (or null if this method was used as a setter).

Inherited From: SUI.Box#left

public loadData( object[] data, int/int[] selected, int focussed)

(Re)load data into the list view.

Parameters:

Name Type Description
object[] data The data array of objects in which each object contains column (key) / values pairs
int/int[] selected Array of indexes for the initial row selection
int focussed Index of the row to focus initially
public int maxHeight( int mh)

Get or set the maximum height of the box.

Parameters:

Name Type Argument Description
int mh <optional>
The new maximum height of the box (or none to use this method as a getter).

Returns:

int The maximum height of the box (or null if this method was used as a setter).

Inherited From: SUI.Box#maxHeight

public int maxWidth( int mw)

Get or set the maximum width of the box.

Parameters:

Name Type Argument Description
int mw <optional>
The new maximum width of the box (or none to use this method as a getter).

Returns:

int The maximum width of the box (or null if this method was used as a setter).

Inherited From: SUI.Box#maxWidth

public int minHeight( int mh)

Get or set the minimum height of the box.

Parameters:

Name Type Argument Description
int mh <optional>
The new minimum height of the box (or none to use this method as a getter).

Returns:

int The minimum height of the box (or null if this method was used as a setter).

Inherited From: SUI.Box#minHeight

public int minWidth( int mw)

Get or set the minimum width of the box.

Parameters:

Name Type Argument Description
int mw <optional>
The new minimum width of the box (or none to use this method as a getter).

Returns:

int The minimum width of the box (or null if this method was used as a setter).

Inherited From: SUI.Box#minWidth

public onClick( Object row)

onClick event handler: is executed when the user clicks on a row.

Parameters:

Name Type Description
Object row A reference to the selected row in the data table
public onContextMenu( int x, int y)

onContextMenu event handler: is executed when the user uses the context menu click on a row.

Parameters:

Name Type Description
int x The x location of the click
int y The y location of the click
public onDblClick( Object row)

onDblClick event handler: is executed when the user double clicks on a row.

Parameters:

Name Type Description
Object row A reference to the selected row in the data table
public onSelectionChange()

onSelectionChange event handler: is executed when the (set of) row selection(s) changes. TODO: this event handler is not called properly from the code (f.i. id not called when rows are deselected).

public SUI.Padding padding( SUI.Padding p)

Get or set the padding definition of the box.

Parameters:

Name Type Argument Description
SUI.Padding p <optional>
The new padding definition (or none to use this method as a getter).

Returns:

SUI.Padding The padding definition of the box (or null if this method was used as a setter).

Inherited From: SUI.Box#padding

public SUI.Box parent( SUI.Box p)

Get or set the parent box of the box. When setting the parent the box's element node will be appended to the parent box's HTML element node.

Parameters:

Name Type Description
SUI.Box p The parent box for this box (or none to use this method as a getter).

Returns:

SUI.Box The parent box of the box (or null if this method was used as a setter).

Inherited From: SUI.Box#parent

public removeBox()

Remove a box from the DOM tree.

Inherited From: SUI.Box#removeBox

public removeClass( String cls)

Remove a CSS class name from the class list of the HTML element associated with the box.

Parameters:

Name Type Description
String cls The CSS class name to remove.

Inherited From: SUI.Box#removeClass

public int right( int r)

Get or set the right of the box.

Parameters:

Name Type Description
int r The new right of the box (or none to use this method as a getter).

Returns:

int The right of the box (or null if this method was used as a setter).

Inherited From: SUI.Box#right

public setDim()

Set the CSS dimensions of this box and it's borders and padding. This is typically used in display functions to display boxes at the size and position that was calculated during layout.

Inherited From: SUI.Box#setDim

public setIsLoadingImage()

Replace the listview contents with an "is loading" image. Recommended when data is loaded from an external resource.

public setPos()

Set the CSS postion of this box. This is typically used in display functions to display boxes at position that was calculated during layout. Note: use setDim if you want to set the position and size of the box.

Inherited From: SUI.Box#setPos

public setRect( int | SUI.Box t, int l, int w, int h)

Set the top, left, width and height of a box in one go.

Parameters:

Name Type Argument Description
int | SUI.Box t The new top of the box or another reference box to copy the values from.
int l <optional>
The new left of the box (if the t parameter wasn't a reference Box).
int w <optional>
The new width of the box (if the t parameter wasn't a reference Box).
int h <optional>
The new length of the box (if the t parameter wasn't a reference Box).

Inherited From: SUI.Box#setRect

public int top( int t)

Get or set the top of the box.

Parameters:

Name Type Argument Description
int t <optional>
The new top of the box (or none to use this method as a getter).

Returns:

int The top of the box (or null if this method was used as a setter).

Inherited From: SUI.Box#top

public int width( int w)

Get or set the width of the box.

Parameters:

Name Type Argument Description
int w <optional>
The new width of the box (or none to use this method as a getter).

Returns:

int The width of the box (or null if this method was used as a setter).

Inherited From: SUI.Box#width