GAMBAS BOOK 3.18.2

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:

tablelayout

Table 17.4.0.0.1.1: Selected properties of the ListView class

The ListView class has these selected methods:

tablelayout

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:

tablelayout

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.

tablelayout

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

tablelayout

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

Das Steuerelement ListView in gb.qt4 (→ gb.gui.base) implementiert eine Liste mit auswählbaren Elementen.

• Die einzelnen Elemente der Liste werden durch einen eindeutigen Schlüssel indiziert. Sie zeigen einen Text und optional ein Bild vor jedem Text.
• Das Steuerelement verfügt über einen internen Zeiger. Verwenden Sie die unterschiedlichen Move-Methoden, um den internen Zeiger zu bewegen und die Current-Eigenschaft, um auf das aktuelle Element zuzugreifen.
• Mit den verschiedenen Move-Methoden können Sie den internen Zeiger verschieben. Wenn Sie den internen Zeiger auf ein bestimmtes Element setzen wollen, dann müssen Sie die Methode MoveTo(Key) benutzen. Beachten Sie, dass diese Move-Methoden den Wert True zurück geben, wenn die Bewegung des internen Zeigers nicht ausgeführt werden kann.
• Um den sichtbaren Zeiger – als Auswahl eines bestimmten Elements der ListView – zu setzen, weisen Sie der Key-Eigenschaft eines Elements den Schlüssel des zu markierenden Elements zu.

Die Klasse ListView verfügt u.a. über diese Eigenschaften:

Tabelle 17.4.0.1.1 : Ausgewählte Eigenschaften der Klasse ListView

Die Klasse ListView besitzt diese ausgewählten Methoden:

Tabelle 17.4.0.2.1 : Ausgewählte Methoden der Klasse ListView

Die Add(…)-Methode fügt ein neues Element in die ListView ein:

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

• Key ist der Schlüssel für das neue Element.
• Text ist der angezeigte Text auf dem neuen Element.
• Picture ist das Bild, das vor dem Text angezeigt wird. Standardmäßig wird kein Bild angezeigt.
• After ist der Schlüssel von dem Element, nach dem das neue Element eingefügt wird. Ohne diesen (optionalen) Schlüssel wird das neue Element standardmäßig als letztes Element eingefügt.

Im folgenden Beispiel aus dem Projekt ListViewE werden die einzelnen Elemente in der ListView aus dem Inhalt einer Datei generiert:

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(...)

Die Klasse ListView besitzt unter anderem die folgenden Ereignisse:

Tabelle 17.4.0.3.1 : Ausgewählte Ereignisse der Klasse ListView

Im nächsten Abschnitt werden Ihnen wichtige Eigenschaften und Methoden der virtuellen Klasse _TreeView_Item vorgestellt, da die Eigenschaften Current und Item vom Typ _TreeView_Item sind.

Die virtuelle Klasse _TreeView_Item repräsentiert einen Eintrag in einer ListView.

Tabelle 17.4.0.5.1 : Ausgewählte Eigenschaften der virtuellen Klasse _ListView_Item

Seine Stärke als Steuerelement zur Anzeige von Daten zeigt die ListView erst dann so richtig, wenn Sie den Text als RichText erzeugen und zusammen mit einem Bild (Datentyp Picture) vor dem Text verwenden:

Abbildung 17.4.0.5.1: Verwendung von RichText in einer ListView

Tabelle 17.4.0.6.1 : Ausgewählte Methoden der virtuellen Klasse _TreeView_Item

Die Verwendung unterschiedlicher Methoden zeigt der folgende, ausführlich kommentierte Beispiel-Quelltext zum Löschen eines (markierten) Elements:

Public Sub btnDeleteElement_Click()
 
  ' Nur ein markiertes Element darf gelöscht werden 
    If Not ListView1.Key Then Return
  ' Zuerst den internen Cursor auf das markierte Element setzen (Start-Position)
    ListView1.MoveCurrent() 
  ' Dann den internen Cursor auf das nächste *sichtbare* - oberhalb liegenden - Element setzen
    ListView1.MoveAbove() ' ***
  ' Das markierte Element wird gelöscht
    ListView1.Remove(ListView1.Key)
  ' Der interne Cursor zeigt nach (***) auf das nach dem Löschen auszuwählende Element.
  ' Gibt es nach dem Löschen noch ein oberes Element, dann wird der externe Cursor darauf 
  ' gesetzt → es wird markiert.
    If ListView1.Item Then 
       ListView1.Key = ListView1.Item.Key
     ' Sonst wird der interne Cursor auf den ersten Eintrag gesetzt, 
     ' wenn er existiert und dann das oberste Element markiert.
    Else
       If Not ListView1.MoveFirst() Then ListView1.Key = ListView1.Item.Key
    Endif
 
End ' btnDeleteElement_Click()