From wiki.ginstr.com
Jump to: navigation, search
m
 
(82 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
<div style="float:right; clear:both; margin-left:0.5em;">__TOC__</div>
 
<div style="float:right; clear:both; margin-left:0.5em;">__TOC__</div>
[[Category:Widget_Library]]
+
<span STYLE="font-size: xx-large"><code>GnListView</code></span>
[[File:GnListView.png|thumb|290px|GnListView]]
+
[[Category:Widget_Library]][[Category:Controls]]
;Inherited classes: <code>[http://developer.android.com/reference/android/view/View.html View]</code>
 
;Android class type: <code>[http://developer.android.com/reference/android/widget/LinearLayout.html LinearLayout]</code>
 
;Child elements: <code>[http://developer.android.com/reference/android/widget/FrameLayout.html FrameLayout]</code>, <code>[http://developer.android.com/reference/android/widget/ListView.html ListView]</code>
 
;Widget XML tag: <code><com.ginstr.widgets.GnListView></code>
 
  
 +
;Widget XML tag
 +
: <code><com.ginstr.widgets.GnListView></code>
  
<code>[[GnListView]]</code> is used to show data in a table appearance, with header on the top and data in rows with cells below.
+
;Description
 
+
: <code>'''GnListView'''</code> 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. <code>[[gn:act_query]]</code> and the fields it returns depend on [[Database#queries.xml|queries.xml]].
+
: Column <code>_id</code> is a special column which represents unique rows. In case this column exists, the value in each row must be unique or not defined.
  
 
==XML Attributes Description==
 
==XML Attributes Description==
Line 18: Line 16:
 
! scope="col" | Description
 
! scope="col" | Description
 
|-
 
|-
| title="Attribute" | <code>[[#gn:data_columns_width|gn:data_columns_width]]</code>
+
| title="Attribute" | <code>gn:data_columns_width{n}</code>
 
| title="Description" | Defines the width of each column from left to right that appears in listview
 
| title="Description" | Defines the width of each column from left to right that appears in listview
 +
Can be
 +
* hardcoded, i.e. <code>50,50,50</code>
 
|-
 
|-
| title="Attribute" | <code>[[#gn:data_columns_name|gn:data_columns_name]]</code>
+
| title="Attribute" | <code>gn:data_columns_name{n}</code>
 
| title="Description" | Defines the names from left to right that will appear in header columns
 
| title="Description" | Defines the names from left to right that will appear in header columns
 +
Can be
 +
* hardcoded, i.e. <code>resident_nfcTagUid,resident_firstName</code>
 +
* <code>@string</code>
 
|-
 
|-
| title="Attribute" | <code>[[#gn:data_columns_settings|gn:data_columns_settings]]</code>
+
| title="Attribute" | <code>gn:data_columns_settings{n}</code>
| title="Description" | Defines the settings for each column from left to right that is displayed in listview
+
| title="Description" | 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, a “pipe” character (<code>|</code>) is used to separate them i.e. “<code>settingsColumn1|settingsColumn2|…</code>”.
 +
 
 +
Can be
 +
* <code>format</code> – converting long to human readable date and time, correct formats [http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html here]
 
|-
 
|-
| title="Attribute" | <code>[[#gn:data_columns_id|gn:data_columns_id]]</code>
+
| title="Attribute" | <code>gn:data_columns_id{n}</code>
 
| title="Description" | Defines column identifiers
 
| title="Description" | Defines column identifiers
 +
 +
If the data is loading from database that has columns i.e. <code>name, surname</code>, to read that data to listview your columns should have same id’s <code>surname, name</code>. Note that the order here is not important.
 +
 +
Can be
 +
* hardcoded, i.e. <code>resident_nfcTagUid,resident_firstName</code>
 +
* <code>@string</code>
 
|-
 
|-
| title="Attribute" | <code>[[#gn:data_columns_type|gn:data_columns_type]]</code>
+
| title="Attribute" | <code>gn:data_columns_type</code>
| title="Description" | Defines cell type for each row which will display data  
+
| title="Description" | Defines cell type for each row which will display data
 +
Can be
 +
* <code>text</code>
 +
* <code>pictures</code>
 +
* <code>pointer</code> - must be used in combination with additional pointer attributes. More about attributes [[#pointer_additional_XML_attributes|here]]
 +
* <code>dateTime</code>
 +
* <code>phoneNumber</code>
 
|-
 
|-
| title="Attribute" | <code>[[#gn:data_filters|gn:data_filters]]</code>
+
| title="Attribute" | <code>gn:data_filters{n}</code>
 
| title="Description" | Defines filter parameter to sort data
 
| title="Description" | Defines filter parameter to sort data
 +
 +
Once data is loaded into <code>[[GnListView]]</code>, it can be filtered by defining filter parameter.
 +
 +
Filters are separated by <code>,</code> (comma symbol) and they have special syntax. More about filters [[#Filtering|here]].
 +
|-
 +
| title="Attribute" | <code>gn:data_columns_sort</code>
 +
| title="Description" | Defines column by which data will be sorted
 +
 +
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.
 
|-
 
|-
| title="Attribute" | <code>[[#gn:data_columns_sort|gn:data_columns_sort]]</code>
+
| <code>gn:sortOrder</code>
| title="Description" | Defines column by which data will be sorted in <code>[[GnListView]]</code>
+
| represents sorting order
 +
Can be
 +
* hardcoded
 +
** <code>regular</code> - default
 +
** <code>reverse</code>
 
|-
 
|-
| title="Attribute" | <code>[[#gn:lstRefreshNoFilter|gn:lstRefreshNoFilter]]</code>
+
| title="Attribute" | <code>gn:lstRefreshNoFilter</code>
 
| title="Description" | Defines that on refresh data will not be filtered (used only in special cases when business logic implementation is used)
 
| title="Description" | 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.
 +
 +
Can be
 +
* <code>true</code>
 +
* <code>false</code>
 
|-
 
|-
| title="Attribute" | <code>[[#gn:lstExpandToFitChildren|gn:lstExpandToFitChildren]]</code>
+
| title="Attribute" | <code>gn:lstExpandToFitChildren</code>
 
| title="Description" | Stretches <code>[[GnListView]]</code> to load all children without scroll
 
| title="Description" | Stretches <code>[[GnListView]]</code> to load all children without scroll
 +
Used only if listView is <code>com.ginstr.widgets.internal.ExpandableHeightListView</code> in <code>control/widget_en_listview.xml</code>.
 +
 +
If set to <code>true</code>, <code>[[GnListView]]</code> will stretch to load all children without scroll.
 +
 +
Can be
 +
* <code>true</code>
 +
* <code>false</code>
 +
|-
 +
| title="Attribute" | <code>gn:complex_cell_layout</code>
 +
| title="Description" | to create complex list layouts based on one cell in row
 +
 +
Can be
 +
* <code>true</code>
 +
* <code>false</code>
 +
|-
 +
| title="Attribute" | <code>gn:custom_xml</code>
 +
| title="Description" | customised XML listview layout
 +
 +
Can be
 +
* hardcoded - the name of xml file
 +
|-
 +
| title="Attribute" | <code>gn:custom_header_xml</code>
 +
| title="Description" | customised XML listview header layout
 +
 +
Can be
 +
* hardcoded - the name of xml file
 +
|-
 +
| title="Attribute" | <code>gn:custom_row_xml</code>
 +
| title="Description" | customised XML row layout
 +
 +
Can be
 +
* hardcoded - the name of xml file
 +
|-
 +
| title="Attribute" | <code>gn:custom_row_xml_odd</code>(M103.8.0.5)
 +
| title="Description" | customised XML row layout for odd rows. If not defined, gn:custom_row_xml will be used instead.
 +
 +
Can be
 +
* hardcoded - the name of xml file
 +
|-
 +
| title="Attribute" | <code>gn:custom_row_xml_even</code>(M103.8.0.5)
 +
| title="Description" | customised XML row layout for even rows. If not defined, gn:custom_row_xml will be used instead
 +
 +
Can be
 +
* hardcoded - the name of xml file
 +
|-
 +
| title="Attribute" | <code>gn:disablePreloadActionsDuringListViewResize</code>
 +
| title="Description" | Disables loading beforeLoad and afterLoad actions on row during keyboard opening on list which is <code>gn:lstExpandToFitChildren</code> set to <code>true</code>. This avoids heavy load on lists with checkboxes but decreases performance on list with dropdowns.
 +
|-
 +
| title="Attribute" | <code>gn:s_listSelector</code>
 +
| title="Description" | is used to highlight the currently selected item
 +
 +
Can be
 +
* hardcoded - e.g. "#00FF00"
 
|}
 
|}
  
==GnListView Filtering==
+
==Events==
Once data is loaded from the database it can be filtered by a filter mechanism. You can also filter the data loaded into the <code>[[GnListView]]</code> by using the following filter types:
+
: <code>[[gn:act_setClick]]</code>
*<code>VALUE</code>
+
: <code>[[gn:act_setLongClick]]</code>
*<code>WIDGET</code>
+
: <code>[[gn:act_setOnScrollEnd]]</code>
*<code>KEYWORD</code>
+
: <code>[[gn:event_onRowCreated]]</code>
  
Filters can also be chained by chain words:
+
==Data types==
*<code>AND</code>
+
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
*<code>OR</code>
+
|-
 +
! scope="col" | Input
 +
|-
 +
| title="Value" | <code>[[Datatypes#rows|rows]]</code>
 +
|}
  
If the filters are chained then each of filter statements has to be true in order to show some record that is in <code>[[GnListView]]</code> data.
+
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
:i.e.<code>[@+id/widgetOne]|[=]|[columnOne],[AND]|[#today]|[=]|[timestamp],[AND]|[dog]|[=]|[columnAnimalType]</code>
+
|-
 +
! scope="col" | Output
 +
|-
 +
| title="Value" | <code>[[Datatypes#rows|rows]]</code>
 +
|}
 +
 
 +
==Example==
 +
<syntaxhighlight code="xml">
 +
<com.ginstr.widgets.GnListView
 +
  android:id="@+id/lstResidents"
 +
  android:layout_width="match_parent"
 +
  android:layout_height="match_parent"
 +
  android:layout_gravity="center_horizontal"
 +
  android:background="#e1e1e1"
 +
  gn:data_columns_name="resident_nfcTagUid,resident_firstName,resident_lastName,resident_roomNo,resident_buildingCode"
 +
  gn:data_columns_id="resident_nfcTagUid,resident_firstName,resident_lastName,resident_roomNo,resident_buildingCode"
 +
  gn:data_columns_type="text,text,text,text,text"
 +
  gn:serverTableGenerator="ignore"
 +
  gn:lstRefreshNoFilter="true"
 +
  gn:s_listSelector="#00000000"
 +
  gn:custom_xml="customList_listview.xml"
 +
  gn:custom_header_xml="residentsList_header.xml"
 +
  gn:custom_row_xml="residentsList_row.xml"
 +
  gn:complex_cell_layout="true" />
 +
</syntaxhighlight>
 +
 
 +
==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 <code>[[GnListView]]</code> by using the following filter types:
 +
::* <code>VALUE</code>
 +
::* <code>WIDGET</code>
 +
::* <code>KEYWORD</code>
  
The upper statement filters the <code>[[GnListView]]</code> in the following way:
+
: Filters can also be chained by chain words:
:'''IF''' the widget that has id <code>“@+id/widgetOne”</code> has a value equal to the value in <code>columnOne</code> in listview rows '''AND''' if <code>timestamp</code> value in listview rows is within today '''AND''' if <code>columnAnimalType</code> value in listview rows is equal to <code>“dog”</code>, then the row from listview rows will be displayed in <code>[[GnListView]]</code>.
+
::* <code>AND</code>
 +
::* <code>OR</code>
  
;Based on upper example, the filter chaining definition is:
+
: If the filters are chained then each of filter statements must be true in order to show some record that is in <code>[[GnListView]]</code> data.
<code>[CHAIN WORD]|[FILTER],[CHAIN WORD]|[FILTER1]</code>
+
: i.e.<code>[@+id/widgetOne]|[=]|[columnOne],[AND]|[#today]|[=]|[timestamp],[AND]|[dog]|[=]|[columnAnimalType]</code>
  
;General filter [FILTER] definition is:
+
: The upper statement filters the <code>[[GnListView]]</code> in the following way:
<code>[VALUE]|[COMPARATOR]|[COLUMNID]</code>
+
: '''IF''' the widget that has id “<code>@+id/widgetOne</code>” has a value equal to the value in <code>columnOne</code> in listview rows '''AND''' if <code>timestamp</code> value in listview rows is within today '''AND''' if <code>columnAnimalType</code> value in listview rows is equal to “<code>dog</code>”, then the row from listview rows will be displayed in <code>[[GnListView]]</code>.
  
<code>[VALUE]</code> depending on the content of this field filters behave differently.
+
: Based the example above, the filter chaining definition is:
 +
: <code>[CHAIN WORD]|[FILTER],[CHAIN WORD]|[FILTER1]…</code>
  
===Value field special characters===
+
: General filter <code>[FILTER]</code> definition is:
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
+
: <code>[VALUE]|[COMPARATOR]|[COLUMNID]</code>
 +
 
 +
: Filters behave differently depending on the content of the <code>[VALUE]</code> field.
 +
 
 +
===<code>[VALUE]</code> field special characters===
 +
:{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 
|-
 
|-
 
! scope="col" | Special Character
 
! scope="col" | Special Character
Line 92: Line 226:
 
|}
 
|}
  
In order to use '''special characters''' as standard text you need to escape them as follows: <code>\::</code>, <code>\*</code>, <code>\#</code>, <code>\@+id/</code> or <code>\\</code>
+
: In order to use '''special characters''' as standard text you need to escape them as follows: <code>\::</code>, <code>\*</code>, <code>\#</code>, <code>\@+id/</code> or <code>\\</code>
  
 
===Comparators===
 
===Comparators===
Comparators define the relation between the two values that are being compared.
+
: Comparators define the relation between the two values that are being compared.
 
+
: The following comparators can be used to compare:
The following comparators can be used to compare:
+
:{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 
 
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 
 
|-
 
|-
 
! scope="col" | Comparator Symbol
 
! scope="col" | Comparator Symbol
Line 118: Line 250:
 
|}
 
|}
  
====Value filter====
+
===Filters===
Compares a value against value loaded into <code>[[GnListView]]</code> data rows.
+
:{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 
+
|-
The definition of value filter is as follows :
+
! scope="col" | Filter
;<code>[VALUE]|[COMPARATOR]|[COLUMNID]</code>:i.e. <code>[two]|[=]|[columnOne]</code>
+
! scope="col" | Description
 
+
|-
The following filter will compare data row value if is equal to <code>two</code>, filter will return <code>true</code> and data row loaded into <code>[[GnListView]]</code>.
+
| title="Filter" | <code>[VALUE]</code>
 
+
| title="Description" |
====Widget filter====
+
: Compares a value against value loaded into <code>[[GnListView]]</code> data rows.
If <code>[VALUE]</code> field contains special character <code>@+id/</code> filter will behave as '''Widget filter'''.
+
: The definition of value filter is as follows:
 
+
: <code>[VALUE]|[COMPARATOR]|[COLUMNID]</code>:i.e. <code>[two]|[=]|[columnOne]</code>
'''Widget filter''' compares listview datarow value with value of a certain widget.
+
: The following filter will compare data row value if is equal to <code>two</code>, filter will return <code>true</code> and data row loaded into <code>[[GnListView]]</code>.
 
+
|-
;<code>[@+id/WIDGET_ID]|[COMPARATOR]|[COLUMNID]</code>:i.e. <code>[@+id/widgetOne]|[=]|[columnA]</code>
+
| title="Filter" | <code>[WIDGET]</code>
 
+
| title="Description" |
This filter checks if a widget with id <code>@+id/widgetOne</code> has value equal to <code>columnA</code> of listview datarow. If <code>true</code> row will be shown.
+
: If <code>[VALUE]</code> field contains special character <code>@+id/</code> filter will behave as '''Widget filter'''.
 
+
: <code>[WIDGET]</code> filter compares listview datarow value with value of a certain widget.
====Keyword filter====
+
: <code>[@+id/WIDGET_ID]|[COMPARATOR]|[COLUMNID]</code>:i.e. <code>[@+id/widgetOne]|[=]|[columnA]</code>
'''Keyword filter''' compares values from list with special values that cannot be obtained by other means.  
+
: This filter checks if a widget with id <code>@+id/widgetOne</code> has value equal to <code>columnA</code> of listview datarow. If <code>true</code> row will be shown.
;<code>[#KEYWORD]|[COMPARATOR]|[COLUMNID]</code>
+
|-
 
+
| title="Filter" | <code>[KEYWORD]</code>
=====#today=====
+
| title="Description" |
Keyword <code>#today</code> checks if value from listview is within today's date. If it is then it returns <code>true</code> and row is displayed.
+
: <code>[KEYWORD]</code> filter compares values from list with special values that cannot be obtained by other means.  
 
+
: <code>[#KEYWORD]|[COMPARATOR]|[COLUMNID]</code>
:i.e. <code>[#today]|[=]|[timestamp]</code> is timestamp field within today's date
+
: Keyword <code>#today</code> checks if value from listview is within today's date. If it is then it returns <code>true</code> and row is displayed.
When using the timestamp the <code>date_time</code> datatype has to be used.
+
: i.e. <code>[#today]|[=]|[timestamp]</code> is timestamp field within today's date
 
+
: When using the timestamp the <code>[[Datatypes#dateTime|dateTime]]</code> [[Datatypes|datatype]] must be used.
==gn:data_columns_width==
+
|}
Defines the width of each column from left to right that appears in listview
 
 
 
''(String)'' values = <code>0</code>–<code>100</code> (percent) '''OR''' <code>100DP</code>, <code>115DP</code>
 
 
 
When percentage values are used, the sum of all values must be 100
 
:i.e. <code>30,70</code>, <code>20,20,20,20,20</code>
 
 
 
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 = <code>column1</code>, <code>column2</code> ... <code>lastcolumn</code>
 
 
 
==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” (<code>|</code>) is used to separate them
 
:i.e. <code>“settingsColumn1|settingsColumn2|…”</code>.
 
 
 
Settings:
 
;<code>Dt “dateTime”</code>:<code>format</code> – converting long to human readable date and time, correct formats [http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html here]
 
 
 
==gn:data_columns_id==
 
Defines column identifiers, which are directly related with <code>dbRequest</code> fields.
 
 
 
If the data is loading from a <code>dbRequest</code> that has columns i.e. <code>name, surname</code>, to read that data to listview your columns should have same id’s <code>surname, name</code>. Note that the order here is not important.
 
 
 
==gn:data_columns_type==
 
Defines cell type for each row which will display data
 
 
 
''(String)'' values = <code>Dt "text"</code>, <code>Dt "pictures"</code>, <code>Dt "pointer"</code>, <code>Dt "dateTime"</code>, <code>Dt "phoneNumbers"</code>
 
  
 +
==pointer additional XML attributes==
 
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 
|-
 
|-
! scope="col" | Value
+
! scope="col" | Attribute
 
! scope="col" | Description
 
! scope="col" | Description
 
|-
 
|-
| title="Value" | <code>Dt "text"</code>
+
| title="Attribute" | <code>gn:data_source_request</code>
| title="Description" | Shows text in cell
+
| title="Description" | id of query which will be used to get pointed value
|-
+
: Can be
| title="Value" | <code>Dt "pictures"</code>
+
* hardcoded
| title="Description" | Shows pictures in cell
 
 
|-
 
|-
| title="Value" | <code>Dt "pointer"</code>
+
| title="Attribute" | <code>gn:data_source_table</code>
| title="Description" | When pointer is used, [[#Dt_"pointer"_additional_attributes|additional widget attributes]] must be set
+
| title="Description" | name of table which will get queried
 +
: Can be
 +
* hardcoded
 
|-
 
|-
| title="Value" | <code>Dt "dateTime"</code>
+
| title="Attribute" | <code>gn:data_source_field</code>
| title="Description" | shows date as long, if <code>[[#gn:data_columns_settings|gn:data_columns_settings]]</code> set, it is possible to show date as formatted text, see [[#gn:data_columns_settings|here]].
+
| title="Description" | column of referenced table which we would like to display  supported referencing columns of data type <code>[[Datatypes#text|text]]</code>
 +
: Can be
 +
* hardcoded
 
|-
 
|-
| title="Value" | <code>Dt "phoneNumbers"</code>
+
| title="Attribute" | <code>gn:data_source_keys</code>
| title="Description" | Shows all phone numbers stored in column of type <code>phoneNumber</code>
+
| title="Description" | <div style="text-align: right;">'''optional'''</div>
 +
query keys in case referenced table values need to be reduced. This optimises memory on large table loads.
 +
: Can be
 +
* hardcoded
 
|}
 
|}
  
===Dt "pointer" additional widget attributes===
+
==Alternative layout==
 +
Alternative layout can be set into control folder.
  
;<code>gn:data_source_request=”query”</code>: id of query which will be used to get pointed value
+
Special widget which has multiple XML files defining multiple parts of this composite widget:
;<code>gn:data_source_table=”table”</code>: name of table which will get queried
+
===widget_en_listview_row_container.xml===
;<code>gn:data_source_field</code>: column of referenced table which we would like to display  supported referencing columns of data type <code>Dt “text”</code>
+
: defines how listview container appearance will look
;<code>gn:data_source_keys</code> (optional): query keys in case referenced table values need to be reduced. This optimises memory on large table loads. Permitted query keys are listed [[gn:act_rawQueryToWidget#Query_keys_from_target|here]].
 
  
==gn:data_filters==
+
===widget_en_listview_header_container.xml===
Once data is loaded into <code>[[GnListView]]</code>, it can be filtered by defining filter parameter.
+
: defines how header container appearance will look
  
Filters are separated by <code>,</code> (comma symbol) and they have special syntax. More about filters [[#GnListView_Filtering|here]].
+
===widget_en_listview_column_string.xml===
 +
: defines how column cell of type string will look
 +
:{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
! scope="col" | id
 +
! scope="col" | Type
 +
|-
 +
| title="id" | <code>@+id/tvDisplayView</code>
 +
| title="Type" | <code>[http://developer.android.com/reference/android/view/TextView.html TextView]</code>
 +
|}
  
==gn:data_columns_sort==
+
===widget_en_listview_column_pointer.xml===
Defines column by which data will be sorted in <code>[[GnListView]]</code>
+
: defines how column cell of type pointer will look
 +
:{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
! scope="col" | id
 +
! scope="col" | Type
 +
|-
 +
| title="id" | <code>@+id/tvDisplayView</code>
 +
| title="Type" | <code>[http://developer.android.com/reference/android/view/TextView.html TextView]</code>
 +
|}
  
Currently, sorting only accepts ascending sort by <code>columnID</code> defined by value of this attribute. For example if <code>dbRequest</code> has columns: <code>name,surname,timestamp</code>, and <code>name</code> is set as a value for this attribute then all rows will be sorted ascending by name.
+
===widget_en_listview.xml===
 
+
: defines the appearance of the listview container
==gn:lstRefreshNoFilter==
+
:{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
Defines that on refresh data will not be filtered (used only in special cases when business logic implementation is used)
+
|-
 
+
! scope="col" | id
This attribute is not relevant to designer and if developing a standard ginstr app then it can be omitted.
+
! scope="col" | Type
 
+
|-
''(Boolean)'' value = <code>true</code>
+
| title="id" | <code>@+id/lstHeader</code>
 
+
| title="Type" | <code>[http://developer.android.com/reference/android/view/FrameLayout.html FrameLayout]</code>
==gn:lstExpandToFitChildren==
+
|-
Can be used only if listView is: <code>com.ginstr.widgets.internal.ExpandableHeightListView</code> in '''control/widget_en_listview.xml''', if set to <code>true</code>, <code>[[GnListView]]</code> will stretch to load all children without scroll
+
| title="id" | <code>@+id/lstListView</code>
 
+
| title="Type" | <code>[http://developer.android.com/reference/android/view/ListView.html ListView]</code>
''(Boolean)'' value = <code>true</code>
+
|}

Latest revision as of 10:36, 26 October 2020

GnListView

Widget XML tag
<com.ginstr.widgets.GnListView>
Description
GnListView is used to show data in a table appearance, with header on the top and data in rows with cells below.
Column _id is a special column which represents unique rows. In case this column exists, the value in each row must be unique or not defined.

XML Attributes Description

Attribute Description
gn:data_columns_width{n} Defines the width of each column from left to right that appears in listview

Can be

  • hardcoded, i.e. 50,50,50
gn:data_columns_name{n} Defines the names from left to right that will appear in header columns

Can be

  • hardcoded, i.e. resident_nfcTagUid,resident_firstName
  • @string
gn:data_columns_settings{n} 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, a “pipe” character (|) is used to separate them i.e. “settingsColumn1|settingsColumn2|…”.

Can be

  • format – converting long to human readable date and time, correct formats here
gn:data_columns_id{n} Defines column identifiers

If the data is loading from database 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.

Can be

  • hardcoded, i.e. resident_nfcTagUid,resident_firstName
  • @string
gn:data_columns_type Defines cell type for each row which will display data

Can be

  • text
  • pictures
  • pointer - must be used in combination with additional pointer attributes. More about attributes here
  • dateTime
  • phoneNumber
gn:data_filters{n} Defines filter parameter to sort data

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

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:sortOrder represents sorting order

Can be

  • hardcoded
    • regular - default
    • reverse
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.

Can be

  • true
  • false
gn:lstExpandToFitChildren Stretches GnListView to load all children without scroll

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.

Can be

  • true
  • false
gn:complex_cell_layout to create complex list layouts based on one cell in row

Can be

  • true
  • false
gn:custom_xml customised XML listview layout

Can be

  • hardcoded - the name of xml file
gn:custom_header_xml customised XML listview header layout

Can be

  • hardcoded - the name of xml file
gn:custom_row_xml customised XML row layout

Can be

  • hardcoded - the name of xml file
gn:custom_row_xml_odd(M103.8.0.5) customised XML row layout for odd rows. If not defined, gn:custom_row_xml will be used instead.

Can be

  • hardcoded - the name of xml file
gn:custom_row_xml_even(M103.8.0.5) customised XML row layout for even rows. If not defined, gn:custom_row_xml will be used instead

Can be

  • hardcoded - the name of xml file
gn:disablePreloadActionsDuringListViewResize Disables loading beforeLoad and afterLoad actions on row during keyboard opening on list which is gn:lstExpandToFitChildren set to true. This avoids heavy load on lists with checkboxes but decreases performance on list with dropdowns.
gn:s_listSelector is used to highlight the currently selected item

Can be

  • hardcoded - e.g. "#00FF00"

Events

gn:act_setClick
gn:act_setLongClick
gn:act_setOnScrollEnd
gn:event_onRowCreated

Data types

Input
rows
Output
rows

Example

<com.ginstr.widgets.GnListView
  android:id="@+id/lstResidents"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:layout_gravity="center_horizontal"
  android:background="#e1e1e1"
  gn:data_columns_name="resident_nfcTagUid,resident_firstName,resident_lastName,resident_roomNo,resident_buildingCode"
  gn:data_columns_id="resident_nfcTagUid,resident_firstName,resident_lastName,resident_roomNo,resident_buildingCode"
  gn:data_columns_type="text,text,text,text,text"
  gn:serverTableGenerator="ignore"
  gn:lstRefreshNoFilter="true"
  gn:s_listSelector="#00000000"
  gn:custom_xml="customList_listview.xml"
  gn:custom_header_xml="residentsList_header.xml"
  gn:custom_row_xml="residentsList_row.xml"
  gn:complex_cell_layout="true" />

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 must 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 the example above, the filter chaining definition is:
[CHAIN WORD]|[FILTER],[CHAIN WORD]|[FILTER1]…
General filter [FILTER] definition is:
[VALUE]|[COMPARATOR]|[COLUMNID]
Filters behave differently depending on the content of the [VALUE] field.

[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

Filters

Filter Description
[VALUE]
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]
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]
[KEYWORD] filter compares values from list with special values that cannot be obtained by other means.
[#KEYWORD]|[COMPARATOR]|[COLUMNID]
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 dateTime datatype must be used.

pointer additional XML attributes

Attribute Description
gn:data_source_request id of query which will be used to get pointed value
Can be
  • hardcoded
gn:data_source_table name of table which will get queried
Can be
  • hardcoded
gn:data_source_field column of referenced table which we would like to display supported referencing columns of data type text
Can be
  • hardcoded
gn:data_source_keys
optional

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

Can be
  • hardcoded

Alternative layout

Alternative layout can be set into control folder.

Special widget which has multiple XML files defining multiple parts of this composite widget:

widget_en_listview_row_container.xml

defines how listview container appearance will look

widget_en_listview_header_container.xml

defines how header container appearance will look

widget_en_listview_column_string.xml

defines how column cell of type string will look
id Type
@+id/tvDisplayView TextView

widget_en_listview_column_pointer.xml

defines how column cell of type pointer will look
id Type
@+id/tvDisplayView TextView

widget_en_listview.xml

defines the appearance of the listview container
id Type
@+id/lstHeader FrameLayout
@+id/lstListView ListView