Mobile Tutorial: Using ListBox Components to Display a Table View (iOS and Android)

From RAD Studio
Jump to: navigation, search

Go Up to Mobile Tutorials: Mobile Application Development (iOS and Android)


Using ListBox Components to Display a Table View in Mobile Platforms

On the mobile platform, FireMonkey uses the FMX.ListBox.TListBox component to present a Table View in a mobile style, like the following ListBoxes.

Note: FMX.ListBox.TListBox performance can be slow on mobile. Use TListView if you want to develop more complex applications, especially apps with large databases.

Plain List

iOS Android (LG E-612)

IOSListBoxPlain.PNG

Android ListBoxPlain.png



Grouped List

IOSListBoxGrouped.PNG


Search Box

You can add a search box to a ListBox. With a search box, users can easily narrow down a selection from a long list as in the following pictures.

AllStatesBeforeSearch.PNG AllStatesContainsC.PNG

This tutorial describes the basic steps to build items for a Table View in your multi-device applications for mobile platforms.

Create Items on the ListBox Component

  1. Select:
  2. Select the TListBox component in the Tool Palette, and drop it on the Form Designer. To find TListBox, enter a few characters (such as "TList") in the Search box of the Tool Palette:
    SelectTListBox.png

  3. Select the TListBox component on the Form Designer, go to the Object Inspector and select Client for the Align property.
  4. On the Form Designer, right-click the TListBox component, and select Items Editor:
    SelectListBoxItemsEditor.png

  5. On the Items Designer, click the Add Item button several times to add several items to the ListBox:
    AddListBoxItemsOnItemsDesigner.png

  6. Close the Items Designer. Now you can find your ListBox Items on the TListBox component. For example:
    ListBoxItemsOnTListBox.png

Add a Header

You can define a Header on the TListBox component by using the following steps:

A Header for a TListBox
  1. On the Form Designer, right-click the TListBox component, and select Add Item > TListBoxHeader:
    AddTListBoxHeader.png

  2. On the Tool Palette, select the TLabel component and drop it on top of the TListBoxHeader component you just added:
    AddLabelOnTListBoxHeader.png

  3. In the Object Inspector, change the properties of the TLabel component as follows:
Property Value
Align Client
StyleLookup toollabel
TextSettings.HorzAlign   Center
Text (Text value as you want)

Add a Group Header/Footer to the List

You can define a Group Header and a Group Footer for items on TListBox as follows:

ListBoxItemsWithGroupHeaderAndFooter.png

  1. On the Form Designer, right-click the TListBox component, and select Items Editor.
  2. On the Item Designer, select TListBoxGroupHeader from the drop-down list, and then select Add Item:
    SelectTListBoxGroupHeader.png

  3. Select TListBoxGroupFooter from the drop-down list, and then select Add Item.
  4. Select ListBoxGroupHeader1 in the list of items, and click the Up button several times until this item becomes the top item on the list:
    MoveListBoxGroupHeader.png

  5. Close the dialog box. Now you have a Group Header and a Group Footer on the TListBox component.

Show List Items as Separate Grouped Items

Items on a ListBox can be shown as either a Plain list or a Grouped list. This choice is controlled by the GroupingKind property and the StyleLookup property, as shown in the following graphic:

Show Items as Plain List Show Items as Grouped List
ListBoxItemsWithGroupHeaderAndFooter.png TListBoxgsGrouped.png
Plain = GroupingKind Property Value  Grouped = GroupingKind Property Value 
listboxstyle = StyleLookup Property Value  transparentlistboxstyle = StyleLookup Property Value

You can select the GroupingKind property and the StyleLookup property in the Object Inspector when the ListBox is selected in the Form Designer.

Add a Check Box or Other Accessory to a ListBox Item

Each item in a TListBox can use an Accessory such as Check Mark through the ItemData.Accessory property. The following picture shows the value you can assign to ItemData.Accessory and the Accessory assigned:

ValuesForItemDataAccessory.PNG

You can select the Accessory property in the Object Inspector when ListBox Item is selected in the Form Designer.

SetItemDataAccessory.png

Add an Icon to a ListBox Item

Each Item on a ListBox component can contain Bitmap data, as an Icon, through the ItemData.Bitmap property:

SetItemDataBitmapProperty.png

You can select the Bitmap property in the Object Inspector when the ListBoxItem is selected in the Form Designer.

In order to view the Icon, you must select a StyleLookup which supports the Bitmap property. Change the StyleLookup property to listboxitemleftdetail.

Add Detail Information to an Item

You can add additional text information to each item on the ListBox component.

Specify additional text in the ItemData.Detail property, and select the location of the Detail Text through the StyleLookup property, as shown in the following table:

StyleLookup property Look & Feel
listboxitemnodetail ListBoxItemlistboxitemnodetail.PNG
listboxitembottomdetail ListBoxItemlistboxitembottomdetail.PNG
listboxitemrightdetail ListBoxItemlistboxitemrightdetail.PNG
listboxitemleftdetail ListBoxItemlistboxitemleftdetail.PNG

Running Your Application

Run the application either by choosing Run > Run or by pressing F9.

Create Your ListBox Application

  1. Select:
  2. Select the TListBox component in the Tool Palette, and drop it on the Form Designer.
  3. Select the TListBox component on the Form Designer, go to the Object Inspector and select Client for the Align property.

Add Items to a ListBox from Your Code

To add regular items to a ListBox, you can simply call the Items.Add method as shown in the following code snippet:

  • Delphi:
  ListBox1.Items.Add('Text to add');
  • C++:
  ListBox1->Items->Add("Text to add");

If you want to create items other than a simple item, or control other properties, you can create an instance of the item first, and then add it to the list box.

The following sample codes add items to a ListBox, as shown in the picture:

iOS Android (LG E-612)

ListBoxItemAddedByCode.PNG

Android ListBoxItemAddedByCode.png



Delphi:

procedure TForm1.FormCreate(Sender: TObject);
var
  c: Char;
  i: Integer;
  Buffer: String;
  ListBoxItem : TListBoxItem;
  ListBoxGroupHeader : TListBoxGroupHeader;
begin
  ListBox1.BeginUpdate;
  for c := 'a' to 'z' do
  begin
    // Add header ('A' to 'Z') to the List
    ListBoxGroupHeader := TListBoxGroupHeader.Create(ListBox1);
    ListBoxGroupHeader.Text := UpperCase(c);
    ListBox1.AddObject(ListBoxGroupHeader);

    // Add items ('a', 'aa', 'aaa', 'b', 'bb', 'bbb', 'c', ...) to the list
    for i := 1 to 3 do
    begin
      // StringOfChar returns a string with a specified number of repeating characters.
      Buffer := StringOfChar(c, i);
      // Simply add item
      // ListBox1.Items.Add(Buffer);

      // or, you can add items by creating an instance of TListBoxItem by yourself
      ListBoxItem := TListBoxItem.Create(ListBox1);
      ListBoxItem.Text := Buffer;
      // (aNone=0, aMore=1, aDetail=2, aCheckmark=3)
      ListBoxItem.ItemData.Accessory := TListBoxItemData.TAccessory(i);
      ListBox1.AddObject(ListBoxItem);
    end;
  end;
  ListBox1.EndUpdate;
end;

C++:

void __fastcall TForm1::FormCreate(TObject *Sender)
{

  char c;
  int i;
  String Buffer ;
  TListBoxItem *ListBoxItem  ;
  TListBoxGroupHeader *ListBoxGroupHeader  ;

  ListBox1->BeginUpdate();
  for (c = 'a'; c <= 'z'; c++)
  {
        // Add header ('A' to 'Z') to the List
        ListBoxGroupHeader = new TListBoxGroupHeader(ListBox1);
        ListBoxGroupHeader->Text = UpperCase(c);
        ListBox1->AddObject(ListBoxGroupHeader);

        // Add items ('a', 'aa', 'aaa', 'b', 'bb', 'bbb', 'c', ->->->) to the list
        for (i = 1; i < 4; i++)
        {
          // StringOfChar returns a string with a specified number of repeating characters->
          Buffer = StringOfChar(c, i);
          // Simply add item
          // ListBox1->Items->Add(Buffer);

          // or, you can add items by creating an instance of TListBoxItem by yourself
          ListBoxItem = new TListBoxItem(ListBox1);
          ListBoxItem->Text = Buffer;
          // (aNone=0, aMore=1, aDetail=2, aCheckmark=3)
          ListBoxItem->ItemData->Accessory = static_cast<TListBoxItemData::TAccessory>(i);
          ListBox1->AddObject(ListBoxItem);
        };
  };
  ListBox1->EndUpdate();
}

Create an Overflow Menu

An overflow popup menu is accessed via the Action Bar and is used to provide access to additional items or items that are used less often.

In FireMonkey, you can easily implement an overflow menu using TListBox:

  1. Add a TToolBar component on the form and set the alignment to Top.
  2. Place three TSpeedButton components on the TToolBar component:
    Actionbar.png
  3. Drop a TListBox to the form.
  4. For the first four TListBoxItem components in TListBox go to Object Inspector, expand ItemData:
    • Define the Bitmap property.
    • Change the Text property to the text value that you want.
    • Select listboxitemleftdetail for the StyleLookup property.
  5. For the last TListBoxItem, in the Object Inspector expand ItemData:
  6. Add a TShadowEffect component to the overflow menu.
Structure View Android LG-E612

Structure.png

Overflow.png

Creating the Event Handler for the Overflow Button

In the Form Designer, double-click the OverflowButton component. Add the following code to this event handler:

  • Delphi:
procedure TForm1.OverflowButtonClick(Sender: TObject);
begin
OverflowMenu.Visible := not OverflowMenu.Visible; //change the visibility status
  if OverflowMenu.Visible then // the Overflow Menu is displayed
  begin
    OverflowMenu.BringToFront;
    OverflowMenu.ItemIndex := -1; //  the ItemIndex property specifies the currently selected item(default value is -1 that means that no item is selected)
    OverflowMenu.ApplyStyleLookup;
    OverflowMenu.RealignContent; // realigns the children TListBoxItem controls of the OverflowMenu TListBox
  end;
end;
  • C++:
void __fastcall TForm1::OverflowButtonClick(TObject *Sender)
{
        OverflowMenu->Visible = !(OverflowMenu->Visible); //change the visibility status
		if (OverflowMenu->Visible) {   // the Overflow Menu is displayed
                OverflowMenu->BringToFront();
                OverflowMenu->ItemIndex = -1; //  the ItemIndex property specifies the currently selected item(default value is -1 that means that no item is selected)
                OverflowMenu->ApplyStyleLookup();
                OverflowMenu->RealignContent(); // realigns the children TListBoxItem controls of the OverflowMenu TListBox
        }
}

Add a Search Box

  • To add a Search Box to the ListBox component, right-click the TListBox component and simply select Add Item > TSearchBox from the context menu:

AddSearchBox.png

  • To add it to the Action Bar:
    • Set the Visible property to False.
    • To create the event handler for the SearchButton, double-click it and add the following code:

Delphi:

procedure TForm1.SearchButtonClick(Sender: TObject);
begin
  SearchBox1.Visible := not SearchBox1.Visible; //change the visibility status
end;

C++:

void __fastcall TForm1::SearchButtonClick(TObject *Sender) {
        SearchBox1->Visible = !(SearchBox1->Visible); //change the visibility status
}

Running Your Application

  1. Select either:
    • Run > Run
    • Run > Run Without Debugging
  2. To invoke the overflow menu, click the vertical ellipsis on the Action bar.
  3. To view the search box, click the SearchButton.
Android (Samsung Tab 2.0) Android (Samsung Tab 2.0)

Actionbar-overflowMenu.png

Android-search.png

Displaying the overflow menu

Displaying the search box

See Also