GnListView

GnListView

Inherited classes

View

Android class type

LinearLayout

Child elements

FrameLayout, ListView

Widget XML tag

<com.ginstr.widgets.GnListView>

GnListView is used to show data in a table appearance, with header on the top and data in rows with cells below.

Data for listview can be queried via regular actions i.e. gn:act_query and the fields it returns depend on queries.xml.

XML Attributes Description

Attribute	Description
gn:data_columns_width	Defines the width of each column from left to right that appears in listview
gn:data_columns_name	Defines the names from left to right that will appear in header columns
gn:data_columns_settings	Defines the settings for each column from left to right that is displayed in listview
gn:data_columns_id	Defines column identifiers
gn:data_columns_type	Defines cell type for each row which will display data
gn:data_filters	Defines filter parameter to sort data
gn:data_columns_sort	Defines column by which data will be sorted in GnListView
gn:lstRefreshNoFilter	Defines that on refresh data will not be filtered (used only in special cases when business logic implementation is used)
gn:lstExpandToFitChildren	Stretches GnListView to load all children without scroll

GnListView Filtering

Once data is loaded from the database it can be filtered by a filter mechanism. You can also filter the data loaded into the GnListView by using the following filter types:

• VALUE
• WIDGET
• KEYWORD

Filters can also be chained by chain words:

• AND
• OR

If the filters are chained then each of filter statements has to be true in order to show some record that is in GnListView data.

i.e.[@+id/widgetOne]|[=]|[columnOne],[AND]|[#today]|[=]|[timestamp],[AND]|[dog]|[=]|[columnAnimalType]

The upper statement filters the GnListView in the following way:

IF the widget that has id “@+id/widgetOne” has a value equal to the value in columnOne in listview rows AND if timestamp value in listview rows is within today AND if columnAnimalType value in listview rows is equal to “dog”, then the row from listview rows will be displayed in GnListView.

Based on upper example, the filter chaining definition is

[CHAIN WORD]|[FILTER],[CHAIN WORD]|[FILTER1]…

General filter [FILTER] definition is

[VALUE]|[COMPARATOR]|[COLUMNID]

[VALUE] depending on the content of this field filters behave differently.

Value field special characters

Special Character	Description
::	Defines range in VALUE (turns filter into RANGE filter) (not yet implemented)
*	Equivalent to like
#	Keyword identifier (turns filter into KEYWORD filter)
@+id/	Widget id
\	Escape character

In order to use special characters as standard text you need to escape them as follows: \::, \*, \#, \@+id/ or \\

Comparators

Comparators define the relation between the two values that are being compared.

The following comparators can be used to compare:

Comparator Symbol	Description	Value Types Allowed
=	Equals to values	STRING, NUMBER
c=	Case sensitive equals to values	STRING, NUMBER
>	Greater than value	NUMBER

Value filter

Compares a value against value loaded into GnListView data rows.

The definition of value filter is as follows :

[VALUE]|[COMPARATOR]|[COLUMNID]

i.e. [two]|[=]|[columnOne]

The following filter will compare data row value if is equal to two, filter will return true and data row loaded into GnListView.

Widget filter

If [VALUE] field contains special character @+id/ filter will behave as Widget filter.

Widget filter compares listview datarow value with value of a certain widget.

[@+id/WIDGET_ID]|[COMPARATOR]|[COLUMNID]

i.e. [@+id/widgetOne]|[=]|[columnA]

This filter checks if a widget with id @+id/widgetOne has value equal to columnA of listview datarow. If true row will be shown.

Keyword filter

Keyword filter compares values from list with special values that cannot be obtained by other means.

[#KEYWORD]|[COMPARATOR]|[COLUMNID]

#today

Keyword #today checks if value from listview is within today's date. If it is then it returns true and row is displayed.

i.e. [#today]|[=]|[timestamp] is timestamp field within today's date

When using the timestamp the date_time datatype has to be used.

gn:data_columns_width

Defines the width of each column from left to right that appears in listview

(String) values = 0–100 (percent) OR 100DP, 115DP

When percentage values are used, the sum of all values must be 100

i.e. 30,70, 20,20,20,20,20

When DP values (density pixels) are used, the sum of values is irrelevant.

gn:data_columns_name

Defines the names from left to right that will appear in header columns

(String) values = column1, column2 ... lastcolumn

gn:data_columns_settings

Defines the settings for each column from left to right that is displayed in listview.

If there is a single column to be shown in listview there is no separator between settings for columns.

If there are 2 or more columns whose settings should be configured “pipe” (|) is used to separate them

i.e. “settingsColumn1|settingsColumn2|…”.

Settings:

Dt “dateTime”

format – converting long to human readable date and time, correct formats here

gn:data_columns_id

Defines column identifiers, which are directly related with dbRequest fields.

If the data is loading from a dbRequest that has columns i.e. name, surname, to read that data to listview your columns should have same id’s surname, name. Note that the order here is not important.

gn:data_columns_type

Defines cell type for each row which will display data

(String) values = Dt "text", Dt "pictures", Dt "pointer", Dt "dateTime", Dt "phoneNumbers"

Value	Description
Dt "text"	Shows text in cell
Dt "pictures"	Shows pictures in cell
Dt "pointer"	When pointer is used, additional widget attributes must be set
Dt "dateTime"	shows date as long, if gn:data_columns_settings set, it is possible to show date as formatted text, see here.
Dt "phoneNumbers"	Shows all phone numbers stored in column of type phoneNumber

Dt "pointer" additional widget attributes

gn:data_source_request=”query”

id of query which will be used to get pointed value

gn:data_source_table=”table”

name of table which will get queried

gn:data_source_field

column of referenced table which we would like to display supported referencing columns of data type Dt “text”

gn:data_source_keys (optional)

query keys in case referenced table values need to be reduced. This optimises memory on large table loads. Permitted query keys are listed here.

gn:data_filters

Once data is loaded into GnListView, it can be filtered by defining filter parameter.

Filters are separated by , (comma symbol) and they have special syntax. More about filters here.

gn:data_columns_sort

Defines column by which data will be sorted in GnListView

Currently, sorting only accepts ascending sort by columnID defined by value of this attribute. For example if dbRequest has columns: name,surname,timestamp, and name is set as a value for this attribute then all rows will be sorted ascending by name.

gn:lstRefreshNoFilter

Defines that on refresh data will not be filtered (used only in special cases when business logic implementation is used)

This attribute is not relevant to designer and if developing a standard ginstr app then it can be omitted.

(Boolean) value = true

gn:lstExpandToFitChildren

Can be used only if listView is: com.ginstr.widgets.internal.ExpandableHeightListView in control/widget_en_listview.xml, if set to true, GnListView will stretch to load all children without scroll

(Boolean) value = true