User Tools

Site Tools


k17:k17.4:start

17.4.0 ListView

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.

17.4.0.1 Properties ListView

The ListView class has these properties, among other things:

PropertyData typeDescription
Current _TreeView_ItemReturns the current element. In general, it is the element that has the focus or is selected (single selection mode).
Item_TreeView_ItemReturns the item to which the internal pointer points or NULL if the internal pointer cannot be reached.
CountIntegerReturns the number of all elements in the ListView.
EditableBooleanSpecifies whether the elements are editable by default. This means whether they can be renamed by the user when he clicks on them.
KeyStringReturns the key of the current element.
ModeIntegerSets the selection mode or returns the selection mode. The constants used are: Single, None or Multiple.
SelectionString[]Returns the keys of all selected elements in a string array (multi-selection mode).
SortedBooleanDisplays or determines whether the elements are displayed sorted in the ListView.

Table 17.4.0.0.1.1: Selected properties of the ListView class

17.4.0.2 Methods ListView

The ListView class has these selected methods:

MethodReturn typeDescription
Exist (Key As String)BooleanReturns the value True if the element exists with the specified key.
Add (Key As String, Text As String[, Picture As Picture, After As String]) _TreeView_ItemInserts an element into the ListView.
MoveBack ()BooleanIf one of the other Move methods returns the value True, you can use this method to move the internal pointer to its original position. True is returned if the internal pointer was not at a valid position.
MoveBelow ()BooleanMoves the internal pointer to a visible element below the current one. True is returned if the move cannot be executed.
MoveTo ([ Key As String])BooleanSets the internal cursor to the element in the ListView with the specified key.
MoveBelow ()BooleanMoves the internal pointer to a visible element below the current one. True is returned if the move cannot be executed.
MoveCurrent ()BooleanSets the internal cursor to the selected element in the ListView. True is returned if the move cannot be executed.
MoveFirst ()BooleanSets the internal cursor to the first element in the ListView. True is returned if the list is empty.
MoveLast ()BooleanSets the internal cursor to the last element in the ListView. True is returned if the list is empty.
Rename ()BooleanStarts renaming the selected element.

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

17.4.0.3 Events ListView

The ListView class has the following events, among others:

PropertyDescription
Click ()The event is triggered when an element in the ListView is clicked.
Select ()The event is triggered when the selection in the ListView changes.
Compare (Key As String, OtherKey As String)This event is triggered when comparing two elements in the ListView. The result of the comparison is stored in the Compare property.

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.

17.4.0.4 Properties and methods of the class _TreeView_Item

The virtual class _TreeView_Item represents an entry in a ListView.

17.4.0.5 Properties of the class _TreeView_Item

PropertyData typeDescription
CountIntegerReturns the number of elements.
EditableBooleanSpecifies whether this element can be edited. This means whether it can be renamed by the user when he clicks on it.
KeyStringReturns the key.
PicturePictureReturns the image or sets the image displayed next to the element.
RichTextStringReturns the RichText or sets the RichText.
SelectedBooleanSpecifies whether the element is selected.
TextStringReturns the displayed text on the element or sets the text to be displayed.

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:

b1

b2

Figure 17.4.0.5.1: Using RichText in a ListView

17.4.0.6 Methods of the class _TreeView_Item

MethodDescription
Delete()Deletes the (current) element from the ListView.
Ensurevisibl ()Saves the (visible) display of the element in the ListView (scroll effect).
Renam ()Starts renaming the selected element.

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

Download

Articles

Download


17.4.0 ListView

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.

17.4.0.1 Eigenschaften ListView

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

EigenschaftDatentypBeschreibung
Current _TreeView_ItemGibt das aktuelle Element zurück. Im Allgemeinen ist es das Element, das den Fokus hat oder das markiert ist (Single-Selection-Modus).
Item_TreeView_ItemGibt das Element zurück, auf das der interne Zeiger zeigt oder NULL, wenn der interne Zeiger nicht erreichbar ist.
CountIntegerGibt die Anzahl aller Elemente in der ListView zurück.
EditableBooleanGibt an, ob die Elemente standardmäßig editierbar sind. Das heißt, ob sie vom Benutzer umbenannt werden können, wenn er auf sie klickt.
KeyStringGibt den Key des aktuellen Elements zurück.
ModeIntegerSetzt den Auswahlmodus oder gibt den Auswahlmodus zurück. Die verwendeten Konstanten sind: Single, None oder Multiple.
SelectionString[ ]Zurückgegeben werden die Keys aller markierten Elemente in einem String-Array (Multi-Selection-Modus).
SortedBooleanZeigt an oder legt fest, ob die Elemente in der ListView sortiert angezeigt werden.

Tabelle 17.4.0.1.1 : Ausgewählte Eigenschaften der Klasse ListView

17.4.0.2 Methoden ListView

Die Klasse ListView besitzt diese ausgewählten Methoden:

MethodeRückgabetypBeschreibung
Exist ( Key As String )BooleanZurückgegeben wird der Wert True, wenn das Element mit dem angegebenen Key existiert.
Add ( Key As String, Text As String [ , Picture As Picture, After As String ] ) _TreeView_ItemFügt ein Element in die ListView ein.
MoveBack()BooleanWenn eine der anderen Move-Methoden den Wert True zurück gibt, so können Sie diese Methode benutzen, um den internen Zeiger an seine ursprüngliche Position zu bewegen. Es wird True zurück gegeben, wenn der interne Zeiger nicht auf einer gültigen Position war.
MoveBelow()BooleanBewegt den internen Zeiger auf ein sichtbares Element unterhalb des aktuellen. Es wird True zurückgegeben, wenn die Verschiebung nicht ausgeführt werden kann.
MoveTo ([ Key As String ])BooleanSetzt den internen Cursor auf das Element in der ListView mit dem angegebenen Key.
MoveBelow()BooleanBewegt den internen Zeiger auf ein sichtbares Element unterhalb des aktuellen. Es wird True zurückgegeben, wenn die Verschiebung nicht ausgeführt werden kann.
MoveCurrent()BooleanSetzt den internen Cursor auf das markierte Element in der ListView. Es wird True zurückgegeben, wenn die Verschiebung nicht ausgeführt werden kann.
MoveFirst()BooleanSetzt den internen Cursor auf das erste Element in der ListView. Es wird True zurückgegeben, wenn die Liste leer ist.
MoveLast()BooleanSetzt den internen Cursor auf das letzte Element in der ListView. Es wird True zurückgegeben, wenn die Liste leer ist.
Rename()BooleanStartet das Umbenennen des markierten Elements.

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

17.4.0.3 Ereignisse ListView

Die Klasse ListView besitzt unter anderem die folgenden Ereignisse:

EreignisBeschreibung
Click()Das Ereignis wird ausgelöst, wenn auf ein Element in der ListView geklickt wird.
Select()Das Ereignis wird ausgelöst, wenn sich die Auswahl in der ListView ändert.
Compare ( Key As String, OtherKey As String )Dieses Ereignis wird ausgelöst, wenn zwei Elemente in der ListView verglichen werden. Das Ergebnis des Vergleichs wird in der Compare-Eigenschaft gespeichert.

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.

17.4.0.4 Eigenschaften und Methoden der Klasse _TreeView_Item

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

17.4.0.5 Eigenschaften der Klasse _TreeView_Item

EigenschaftDatentypBeschreibung
CountIntegerGibt die Anzahl der Elemente zurück.
EditableBooleanGibt an, ob dieses Element editierbar ist. Das bedeutet, ob es vom Anwender umbenannt werden kann, wenn er darauf klickt.
KeyStringGibt den Key zurück.
PicturePictureGibt das Bild zurück oder setzt das Bild, das neben dem Element angezeigt wird.
RichTextStringGibt den RichText zurück oder setzt den RichText.
SelectedBooleanGibt an, ob das Element ausgewählt ist.
TextStringGibt den angezeigten Text auf dem Element zurück oder setzt den anzuzeigenden Text.

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:

b1

b2

Abbildung 17.4.0.5.1: Verwendung von RichText in einer ListView

17.4.0.6 Methoden der Klasse _TreeView_Item

MethodeBeschreibung
Delete()Löscht das (aktuelle) Element aus der ListView.
Ensurevisible()Sichert die (sichtbare) Anzeige des Elements in der ListView (Scroll-Effekt).
Rename()Startet das Umbenennen des markierten Elements.

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

Download

The website uses a temporary session cookie. This technically necessary cookie is deleted when the browser is closed. You can find information on cookies in our privacy policy.
k17/k17.4/start.txt · Last modified: 02.07.2018 (external edit)

Page Tools