TTMSFMXNativeUITableView

Usage

An instance of TMSFMXNativeUITableView is a means for displaying and editing hierarchical lists of information.

A table view is made up of at least one section, each with its own items. Sections are identified by their index number within the table view, and items are identified by their index number within a section. Any section can optionally be preceded by a section header.

Methods

Method name	Description
BeginUpdate / EndUpdate	Wrapping code to block direct updates to the TableView. This is done for performance when loading a large amount of items and content.
BeginRefreshing / EndRefreshing	Shows a refreshing indicator on the TableView to show that the TableView is currently refreshing / updating its contents. Always combine the two methods to make sure that the indicator is hidden when the refresh operation is finished.
Edit	Method used to set the TableView in edit mode, if the editing is enabled in the options through Options.Editing.Enabled.
EditDone	Method used to finish editing mode and put the TableView back to normal mode.
GetItem(ASection, ARow: Integer;ASearchFilterList: Boolean = True): TTMSFMXNativeUITableViewItem;	Function that returns an item for the current section and row in the collection and optionally searches in the filtered list when needed.
HideDetailView	Method to return the TableView back to the master view when a master-detail hierarchy is setup.
IsEditing: Boolean	Function that returns a Boolean whether the TableView is in edit mode or not.
IsFiltering: Boolean	Function that returns a Boolean whether the TableView is in filtering mode or not.
UpdateSelectionAtRow(ASection, ARow: Integer)	Updates a row at a section
UpdateTableView	Update the complete TableView.

Events

Event name	Description
OnAddItemToFilterList	Event called when an item is added to the filter list when filtering is enabled in the TableView and a text is entered in the SearchBar.
OnBeginRefreshing	Event called when refreshing begins, triggered when swiping down, or calling BeginRefreshing.
OnCanMoveItem	Event called to return a Boolean whether an item can be moved from and to a location or not.
OnEditEnd	Event called when editing ended.
OnEditStart	Event called when editing started.
OnEndRefreshing	Event called when refreshing ends, triggered when the refreshing operation is complete, or when calling EndRefreshing.
OnFilterItemsForText	Event called when filtering the TableView when a text is entered in the SearchBar.
OnGetItemAccessoryType	Event called to return an Accessory Type for an item in normal mode.
OnGetItemAccessoryView	Event called to return an Accessory View for an item in normal mode. The AccessoryView can be linked to another TMS FMX Native UI Control.
OnGetItemAppearance	Event called to customize text, description, background and selection colors and fonts.
OnGetItemBitmap	Event called to return a Bitmap for an item.
OnGetItemDescription	Event called to return a Description for an item.
OnGetItemDetailView	Event called to return a DetailView for an item. The DetailView can be linked to another TMS FMX Native UI Control.
OnGetItemEditingAccessoryType	Event called to return an Accessory Type for an item in edit mode.
OnGetItemEditingAccessoryView	Event called to return an Accessory View for an item in editing mode. The AccessoryView can be linked to another TMS FMX Native UI Control.
OnGetItemEditingStyle	Event called to return an editing style for an item.
OnGetItemFilterText	Event called that returns the filter text that is used to compare with the text entered in the SearchBar.
OnGetItemHeight	Event called that returns a height for an item.
OnGetItemStyle	Event called to return a style for an item.
OnGetItemSubDetailView	Event called to return a SubDetailView for anitem. The SubDetailView can be linked to another TMS FMX Native UI Control.
OnGetItemText	Event called to return the text of an item.
OnGetNumberOfRowsInSection	Event called that specifies the number of rows in a section.
OnGetNumberOfSections	Event called that specifies the number of sections in a TableView.
OnGetSectionForSectionIndexTitle	Event called that returns the section for a specific index title. The section index title is an equivalent for the lookup characters in the lookup bar.
OnGetSectionIndexTitles	Event called that returns an array of section index titles. The section index title is an equivalent for the lookup characters in the lookup bar.
OnGetTitleForHeaderInSection	Event called that returns a header title for a section.
OnIsItemInFilterCondition	Event called to know if an item matches a specific filter condition.
OnItemAccessoryButtonClick	Event called when clicking on the Accessory Button when the AccessoryType has been set to atTableViewCellAccessoryDetailDisclosureButton.
OnItemBeforeShowDetailView	Event called before navigating from the master to the detail when a master-detail hierarchy is setup.
OnItemCompare	Event called when comparing 2 items for sorting capabilities. Through this event, custom sorting can be applied.
OnItemDelete	Event called when an item will be deleted.
OnItemDeleted	Event called when an item is deleted
OnItemDeSelect	Event called when an item is deselected
OnItemInsert	Event called when an item will be inserted
OnItemInserted	Event called when an item is inserted.
OnItemMove	Event called when an item will be moved.
OnItemMoved	Event called when an item is moved.
OnItemSelect	Event called when an item is selected.
OnSearchEnd	Event called when searching has ended.
OnSearchStart	Event called when searching has started.
OnShouldShowEditMenuForItem	Event called that returns a Boolean whether a Copy edit menu should be shown for an item or not.

Public Events

Event name	Description
OnItemCustomizeCell	Event used to customize a cell after all properties are applied.
OnItemCreateCell	Event called when creating a cell. This event can be used to add additional native UI controls
and can be combined with the OnItemCustomizeCell to apply content.
OnItemPerformCopyAction	Event called when the Copy action is clicked
after the copy menu has been shown by tap-holding on the item.
OnTableViewLoadMore	Event called when the tableview reaches the end. This event can be used to load more items when scrolling.

Adding Sections and Items

The TableView consists of (optionally multiple) sections and items. To add a section at designtime, click on the TableView, select the sections collection and click on the add button:

Each section has a Header property that is empty by default. To visualize sections in the TableView, enter a value in this property such as “Cars”, “Nature”or “Sport”, … .

Sections can also be added programmatically:

var
  s: TTMSFMXNativeUITableViewSection;
begin
  s := TMSFMXNativeUITableView1.Sections.Add;
  s.Header := 'Cars';
  s := TMSFMXNativeUITableView1.Sections.Add;
  s.Header := 'Nature';

  s := TMSFMXNativeUITableView1.Sections.Add;
  s.Header := 'Sports';

Each section has a collection of items. To add an item to a section at designtime, click on the previously created section and double-click on the items collection. In the editor, click on the add button to add an item.

An item can also be added programmatically. If we take the previous snippet that creates sections, we can add items to those sections:

var
  s: TTMSFMXNativeUITableViewSection;
begin
  s := TMSFMXNativeUITableView1.Sections.Add;
  s.Header := 'Cars';
  s.Items.Add.Text := 'Mercedes';
  s.Items.Add.Text := 'Audi';
  s.Items.Add.Text := 'BMW';

  s := TMSFMXNativeUITableView1.Sections.Add;
  s.Header := 'Nature';
  s.Items.Add.Text := 'Birds';
  s.Items.Add.Text := 'Plants';

  s := TMSFMXNativeUITableView1.Sections.Add;
  s.Header := 'Sports';
  s.Items.Add.Text := 'Soccer';
  s.Items.Add.Text := 'Baseball';

Sorting

The TableView also supports built-in sorting. Sorting can be applied to sections and items. Call the procedure Sort on the section or items collection. Optional parameters can be passed for an ascending or descending order.

If we take the sample and apply sorting, the items will be sorted per section:

var
  s: TTMSFMXNativeUITableViewSection;
begin
  s := TMSFMXNativeUITableView1.Sections.Add;
  s.Header := 'Cars';
  s.Items.Add.Text := 'Mercedes';
  s.Items.Add.Text := 'Audi';
  s.Items.Add.Text := 'BMW';
  s.Items.Sort;

  s := TMSFMXNativeUITableView1.Sections.Add;
  s.Header := 'Nature';
  s.Items.Add.Text := 'Birds';
  s.Items.Add.Text := 'Plants';
  s.Items.Sort;

  s := TMSFMXNativeUITableView1.Sections.Add;
  s.Header := 'Sports';
  s.Items.Add.Text := 'Soccer';
  s.Items.Add.Text := 'Baseball';
  s.Items.Sort;

Toolbar

The TableView has built-in support for displaying a toolbar, that is used for Master-Detail navigation and/or editing. To display the toolbar, set Options.ToolBar to true.

TMSFMXNativeUITableView1.Options.ToolBar := True;

Editing

When the toolbar is enabled, an optional edit button can be displayed, that toggles the TableView between normal and edit mode. By default, the Options.Editing.EditButton property is true, but to enable editing, the Options.Editing.Enabled needs to be set to true. This gives the result below.

Clicking on the edit button sets the TableView in edit mode and modifies the button so the TableView can be reverted back to normal mode.

TMSFMXNativeUITableView1.Options.Editing.Enabled := True;

When clicking on the delete indicator next to the item, the item will be deleted from the collection. In normal modethere is also an ability to delete the item on a swipe gesture over the item. A Delete button appears that executes the same functionality as in editing mode.

Each item has a EditStyle property that is esTableViewCellEditingStyleDelete by default. The EditStyle can be set to esTableViewCellEditingStyleInsert to show a plus button, or set to esTableViewCellEditingStyleNone to disallow editing capabilities of an item.

Below is a sample code that adds an extra insertable item in the TableView. When the insert button is clicked, the OnItemInserted event is called which adds an additional item to the tableview. In this event, properties of the newly created item can be modified.

var
  s: TTMSFMXNativeUITableViewSection;
begin
  TMSFMXNativeUITableView1.Options.ToolBar := True;
  TMSFMXNativeUITableView1.Options.Editing.Enabled := True;

  s := TMSFMXNativeUITableView1.Sections.Add;
  s.Header := 'Cars';
  s.Items.Add.Text := 'Mercedes';
  s.Items.Add.Text := 'Audi';
  s.Items.Add.Text := 'BMW';

  s.Items.Sort;
  with s.Items.Add do
  begin
    Text := 'New Item ...';
    EditStyle := esTableViewCellEditingStyleInsert;
  end;

  s := TMSFMXNativeUITableView1.Sections.Add;
  s.Header := 'Nature';
  s.Items.Add.Text := 'Birds';
  s.Items.Add.Text := 'Plants';
  s.Items.Sort;
  with s.Items.Add do
  begin
    Text := 'New Item ...';
    EditStyle := esTableViewCellEditingStyleInsert;
  end;

  s := TMSFMXNativeUITableView1.Sections.Add;
  s.Header := 'Sports';
  s.Items.Add.Text := 'Soccer';
  s.Items.Add.Text := 'Baseball';
  s.Items.Sort;
  with s.Items.Add do
  begin
    Text := 'New Item ...';
    EditStyle := esTableViewCellEditingStyleInsert;
  end;
end;

procedure TForm1.TMSFMXNativeUITableView1ItemInserted(Sender: TObject;
  ASection, ARow: Integer);
var
  it: TTMSFMXNativeUITableViewItem;
begin
  it := TMSFMXNativeUITableView1.Sections[ASection].Items[ARow];
  it.Text := 'This is a new item';
end;

On the left side, there is a move item indicator that allows moving item within sections or to another section. With the CanMove property, this can optionally be controlled per item.

Searching / Filtering

The TableView has built-in support for searching / filtering. With the Options.Searching.Mode property a SearchBar can be enabled to allow searching or filtering. With filtering, the items that are listed in the TableView are based on the text entered in the SearchBar. Only the TableView items that match the filter condition are listed. Filtering can be modified with events that control the filter condition and the results list.

When enabling searching mode, the items remain listed but are scrolled to when the search condition is matched and the search button on the keyboard is pressed.

Below is a sample on how to enable filtering and a sample of a filter result.

var
  s: TTMSFMXNativeUITableViewSection;
begin
  TMSFMXNativeUITableView1.Options.ToolBar := True;
  TMSFMXNativeUITableView1.Options.Editing.Enabled := True;
  TMSFMXNativeUITableView1.Options.Searching.Mode := smFiltering;

  s := TMSFMXNativeUITableView1.Sections.Add;
  s.Header := 'Cars';
  s.Items.Add.Text := 'Mercedes';
  s.Items.Add.Text := 'Audi';
  s.Items.Add.Text := 'BMW';
  s.Items.Sort;

  s := TMSFMXNativeUITableView1.Sections.Add;
  s.Header := 'Nature';
  s.Items.Add.Text := 'Birds';
  s.Items.Add.Text := 'Plants';
  s.Items.Sort;

  s := TMSFMXNativeUITableView1.Sections.Add;
  s.Header := 'Sports';
  s.Items.Add.Text := 'Soccer';
  s.Items.Add.Text := 'Baseball';
  s.Items.Sort;

More information on events is explained in the events table overview.

Lookup

Lookup enables the ability to show a list of characters or indexes that are linked to the section header. When clicking or swiping over the lookup bar, the TableView scrolls to the correct section. This is particularly helpful if there are multiple sections and items that extend the height of the TableView.

To enable lookup, set Options.Lookup.Mode to lmAlphaBetic to enable an AlphaBetic list of lookup indexes in the TableView. The Mode can be changed to allow AlphaNumeric, Numeric or custom. When choosing the last options, the Options.Lookup.Items collection is used to fill up the lookup list with custom indexes that are linked to a section through the ID. Sections have a LookupID that needs to match one of the custom items in the Lookup.

Below is a sample screenshot that shows the lookup bar on the right of the TableView.

DetailView and SubDetailView

Each item in the TableView has a DetailView and SubDetailView property. With the DetailView property, another TMS FMX Native UI control can be linked and displayed when clicking on the item. On TableView level there is also a DetailView property that needs to be set in order to have the DetailView displayed on item level. This hierarchy can be compared to a PageControl. A page control has various pages (Item DetailView) that are shown when clicking on the Tab (Item). The container control that is responsible for displaying the DetailView is assigned to the TableView.

In the sample below when have dropped a TableView (TMSFMXNativeUITableView1) on the form along with a container view (TMSFMXNativeUIView1) and 3 addition controls that will be linked to the items (TMSFMXNativeUIDatePicker1, TMSFMXNativeUISlider1 and TMSFMXNativeUIButton1).

At designtime, this look similar as the image below.

The code that links the items to the DetailView is shown below.

TMSFMXNativeUIDatePicker1.Visible := False;
TMSFMXNativeUIButton1.Visible := False;
TMSFMXNativeUISlider1.Visible := False;
TMSFMXNativeUITableView1.DetailView := TMSFMXNativeUIView1;
with TMSFMXNativeUITableView1.Sections.Add do
begin
  with Items.Add do
  begin
    Text := 'Button';
    DetailView := TMSFMXNativeUIButton1;
  end;
  with Items.Add do
  begin
    Text := 'DatePicker';
    DetailView := TMSFMXNativeUIDatePicker1;
  end;
  with Items.Add do
  begin
    Text := 'Slider';
    DetailView := TMSFMXNativeUISlider1;
  end;
end;

The container view is the TMSFMXNativeUIView1 and is linked to the DetailView property of the TMSFMXNativeUITableView1. The 3 children of the view each need to be assigned to the item’s DetailView property and need to be set Visible false.

When running, the application will display an empty view and a TableView with 3 items. Clicking the items will display the correct DetailView in the container view.

The SubDetailView property has a similar purpose but this way of linking does not require an additional DetailView linked to the TableView. The SubDetailView is shown as a pushed detail from the main TableView. This is called Master-Detail. When changing the above sample so that the 3 children are set as SubDetailView, the container view can be removed. Each control is put in a TMSFMXNativeUIView instance as the view is stretched when it is pushed in the TableView.

At designtime this looks similar like the image below.

The code for initialization:

TMSFMXNativeUIDatePicker1.Visible := False;
TMSFMXNativeUIView1.Visible := False;
TMSFMXNativeUIView2.Visible := False;
TMSFMXNativeUIView3.Visible := False;
TMSFMXNativeUITableView1.Options.ToolBar := True;
with TMSFMXNativeUITableView1.Sections.Add do
begin
  with Items.Add do
  begin
    Text := 'Button';
    SubDetailView := TMSFMXNativeUIView2;
  end;
  with Items.Add do
  begin
    Text := 'DatePicker';
    SubDetailView := TMSFMXNativeUIView3;
  end;
  with Items.Add do
  begin
    Text := 'Slider';
    SubDetailView := TMSFMXNativeUIView1;
  end;
end;

When clicking an item the correct DetailView is pushed in the TableView. To return to the main view, the ToolBar is enabled and automatically shows a back button.

Master-Detail

Each TMS FMX Native UI Control can be used as a DetailView or SubDetailView of an item, so another instance of the TMSFMXNativeUITableView can be used and linked to the item. The second TableView also supports this type of linked thus the Master-Detail hierarchy can have multiple TMSFMXNativeUITableView instances linked to eachother and thus have multiple “levels” of detail.

This setup is similar as the one in the DetailView and SubDetailView chapter but requires an additional property to be set. This sample shows how to link 3 instances of TMSFMXNativeUITableView to eachother by means of a SubDetailView and shows the purpose of the MasterTableView property.

At designtime, we simply drop 3 instances of TMSFMXNativeUITableView on the form. The linking can be done at designtime, but is easier in code.

The code that accompanies this sample is shown below.

var
  s: TTMSFMXNativeUITableViewSection;
  it: TTMSFMXNativeUITableViewItem;
begin
  TMSFMXNativeUITableView1.Options.Header := 'Level 1';
  TMSFMXNativeUITableView2.Options.Header := 'Level 2';
  TMSFMXNativeUITableView3.Options.Header := 'Level 3';

  TMSFMXNativeUITableView1.Options.ToolBar := True;
  TMSFMXNativeUITableView2.MasterTableView := TMSFMXNativeUITableView1;
  TMSFMXNativeUITableView3.MasterTableView := TMSFMXNativeUITableView1;
  TMSFMXNativeUITableView2.Visible := False;
  TMSFMXNativeUITableView3.Visible := False;

  s := TMSFMXNativeUITableView1.Sections.Add;
  it := s.Items.Add;
  it.Text := 'Item on Level 1';
  it.SubDetailView := TMSFMXNativeUITableView2;

  s := TMSFMXNativeUITableView2.Sections.Add;
  it := s.Items.Add;
  it.Text := 'Item on Level 2';
  it.SubDetailView := TMSFMXNativeUITableView3;

  s := TMSFMXNativeUITableView3.Sections.Add;
  it := s.Items.Add;
  it.Text := 'Item on Level 3';

When starting the application, only the first TableView is visible, when clicking on the item, the second TableView is shown and clicking on the item of the second TableView shows the third TableView. Notice that we have only enabled the ToolBar on the first TableView as this takes care of displaying the position in the hierarchy. Therefore the MasterTableView property is necessary as the first TableView needs to know which sub-TableView instances are linked.

When navigating, the back button is automatically updated and the header of the TableView is set. Clicking on the back button returns one step in the hierarchy.

As the items are fixed, the items on each TableView will remain the same even if there are multiple items on the first level that all link to the same sub-TableView. When clicking on an item, the OnBeforeShowDetailView is called. This event can be used to customize the items that are displayed per level, based on the previous level. This event is available per TableView.

Virtual Mode

The previous samples are all based on a collection that needs to be filled with sections and items. The TableView also supports a virtual mode where items can be displayed without a collection. This can be of use when fetching data from a Database, a custom collection or list that is maintained in the application and there is no need to map data to the properties of the built-in section and items collection. The 4 events for minimal implementation in virtual mode are the OnGetNumberOfSections, the OnGetNumberOfRowsInSection, the OnGetTitleForHeaderInSection and the OnGetItemText. Below is a sample that implements these events and shows 2 sections with a couple of items.

procedure TForm1.TMSFMXNativeUITableView1GetItemText(Sender: TObject;
  ASection, ARow: Integer; var AText: string);
begin
  AText := 'S ' + inttostr(ASection) + ' Item ' + inttostr(ARow);
end;

procedure TForm1.TMSFMXNativeUITableView1GetNumberOfRowsInSection(
  Sender: TObject; ASection: Integer; var ANumberOfRows: Integer);
begin
  case ASection of
    0: ANumberOfRows := 3;
    1: ANumberOfRows := 5;
  end;
end;

procedure TForm1.TMSFMXNativeUITableView1GetNumberOfSections(Sender: TObject;
  var ANumberOfSections: Integer);
begin
  ANumberOfSections := 2;
end;

procedure TForm1.TMSFMXNativeUITableView1GetTitleForHeaderInSection(
  Sender: TObject; ASection: Integer; var ATitle: string);
begin
  ATitle := 'Section ' + inttostr(ASection);
end;

Custom Collection

If the data structure of your application contains extra properties that needs to be displayed in the item and the properties of the base collection are not sufficient, the TableView exposes 2 virtual functions that can be overridden to add additional properties. The CustomCells demo that is included in the distribution makes use of a TMSFMXNativeUITableViewMail instance that inherits from the TMSFMXNativeUITableView and overrides the virtual functions that create the section and item collection. When examining the code of this class, you will notice that the TMSFMXNativeUITableViewMailItem collection item class is used to add additional properties such as Sender, Date, Title, Description and Unread.

The TMSFMXNativeUITableViewMail inherits from TMSFMXNativeUITableView and overrides the CreateSections function that returns the custom section collection TMSFMXNativeUITableViewMailSections. As each section has an items collection, the CreateItems function needs to be overridden to return the TMSFMXNativeUITableViewMailItems collection that holds the customized items.

The creation of a custom collection can be sufficient to persist non-visual data in your application. If you need additional visual representation in an item, then the Custom Items chapter will explain how you can override the default layout of a TableView item and display custom data.

The Source of the TMSFMXNativeUITableView can be found below in the Resources chapter

Custom Items

The TableView has a few predefined styles for an item that position the image, title and description on fixed positions. Using the default or changing the style of an item can be sufficient for your application. If the style of an item is not sufficient for your application, the TableView exposes 2 additional public procedures and events that can be implemented to customize your TableView item layout.

As mentioned in the chapter Custom Collection, the TMSFMXNativeUITableViewMail implementation overrides the default collection and provides properties to persist additional data in your application.

The TMSFMXNativeUITableViewMail implementation also demonstrates how to use the 2 virtual procedures that are called when an item is being created and displayed. The DoCreateCell is called when a new item (cell) is being created. This procedure, and the event OnCreateCell, can be used to add additional controls to your item layout that can linked to the properties in the customcollection. These events can also be used to customize your application with the default collection as well, but in this sample the combination of a custom collection and a custom item layout is a typical scenario in real application.

When investigating the source of the TMSFMXNativeUITableViewMail (found in the Resources chapter) you will notice that custom label instances are added and customized linking to the custom collection.