GAMBAS BOOK 3.19.1

The ListView control in gb.qt4 (→ gb.gui.base) implements a list of selectable elements.

• The individual elements of the list are indexed by a unique key. They show a text and optionally an image in front of each text.
• The control has an internal pointer. Use the different Move methods to move the internal pointer and the Current property to access the current item.
• You can use the various Move methods to move the internal pointer. If you want to set the internal pointer to a specific element, you must use the MoveTo(Key) method. Note that these move methods return the value True if the internal pointer cannot move.

* To set the visible pointer - as a selection of a particular element in the ListView - assign the key of the element to be selected to the key property of an element.

The ListView class has these properties, among other things:

Table 17.4.0.0.1.1: Selected properties of the ListView class

The ListView class has these selected methods:

Table 17.4.0.2.1: Selected methods of the ListView class

The Add (…) method inserts a new element into the ListView:

Function Add ( Key As String, Text As String [ , Picture As Picture, After As String ] ) As _TreeView_Item 

• Key is the key for the new element.
• Text is the displayed text on the new element.
• Picture is the image displayed in front of the text. By default, no image is displayed.
• After is the key of the element after which the new element is inserted. Without this (optional) key, the new element is inserted as the last element by default.

In the following example from the ListViewE project, the individual elements in the ListView are generated from the contents of a file:

Private Sub ListViewImport(Path As String, hListView As ListView)
 
  Dim cJSONCollection As JSONCollection
  Dim cCollection As JSONCollection
  Dim sKey, sText As String
  Dim picPicture As Picture
 
  hListView.Clear  
  cJSONCollection = JSON.Decode(File.Load(Path), True)  
  For Each cCollection In cJSONCollection
    sKey = cCollection["KEY"]
    sText = cCollection["TEXT"]
    picPicture = Picture[cCollection["PICTURE"]]
    hListView.Add(sKey, sText, picPicture, Null) ' Null, weil die Reihenfolge feststeht
  Next    
End ' ListViewExport(...)

The ListView class has the following events, among others:

Table 17.4.0.3.1: Selected events of the ListView class

The next section introduces important properties and methods of the virtual class _TreeView_Item, since the properties Current and Item are of type _TreeView_Item.

The virtual class _TreeView_Item represents an entry in a ListView.

Table 17.4.0.5.1: Selected properties of the virtual class _ListView_Item

The ListView only really shows its strength as a control element for displaying data when you generate the text as RichText and use it together with an image (data type Picture) in front of the text:

Figure 17.4.0.5.1: Using RichText in a ListView

Table 17.4.0.6.1: Selected methods of the virtual class _TreeView_Item

The use of different methods is illustrated by the following, extensively commented sample source code for deleting an (selected) element:

Public Sub btnDeleteElement_Click()
 
  ' Only one selected element may be deleted. 
    If Not ListView1.Key Then Return
  ' First place the internal cursor on the selected element (start position)
    ListView1.MoveCurrent() 
  ' Then place the internal cursor on the next *visible* - higher lying - element.
    ListView1.MoveAbove() ' ***
  ' The selected element is deleted
    ListView1.Remove(ListView1.Key)
  ' The internal cursor points after (***) to the element to be selected after deletion.
  ' If there is still an upper element after deletion, the external cursor is placed on it -> it is marked.
    If ListView1.Item Then 
       ListView1.Key = ListView1.Item.Key
     ' Otherwise, the internal cursor is set to the first entry, if it exists and then marks the top element.
    Else
       If Not ListView1.MoveFirst() Then ListView1.Key = ListView1.Item.Key
    Endif
 
End