GAMBAS BOOK 3.18.0

The class ColumnView in gb.qt4 (→ gb.gui.base) implements a control that displays a TreeView with columns.

• The individual rows of a ColumnView are indexed by a unique key. You display a text in each column. Only in the first column an additional image can be inserted.
• Use the Columns property to change the number of columns and their layout.
• The control has an internal pointer to access its rows. Use the different Move methods to move the internal pointer and the Current-property to access the current (marked) row.
• If you want to set the internal pointer to a specific line, you must use the MoveTo (Key) method. Note that all Move methods return True if the internal pointer cannot move.To set the visible pointer - as a selection of a specific row in the ColumnView - assign the key of the row to be selected to the key property of a row.
• The ColumnView. Current property represents the user-selected entry in the ColumnView control, while ColumnView. item of the _TreeView_Item type is an internal, invisible and independent pointer.
• The ColumnView. Current property is used to evaluate user input in a ColumnView (scrolling in the ColumnView or clicking a line with the mouse) and the ColumnView. item property for all algorithms that read or describe a ColumnView.
• This class inherits _TreeView, can be created and behaves like a read-only array.

The ColumnView class has these properties, among other things:

tablelayout

Table 17.5.0.0.1.1: Selected properties of the ColumnView class

Class _ColumnView_Columns:

• This class is a collection of all columns in a ColumnView.
• This class is virtual.
• This class cannot be created.
• This class behaves like a read-only array.

The _ColumnView_Columns class has only these four properties:

Ascending As Boolean
Specifies whether the sorting is set to ascending or descending.

Count As Integer
Returns or sets the number of columns.

Max As Integer
Returns the largest column index.

Sort As Integer
Returns the column index used to sort the ColumnView row or determines this column using the index.
The value -1 indicates that the rows are not sorted.

In the following example, a column is returned - according to its index - whose 4 properties you can then query, for example:

Dim hColumnView As ColumnView
Dim hGridViewColumn As _ColumnView_Columns
 
hGridViewColumn = hColumnView.Columns[ Index As Integer ]
 
Print hGridViewColumn.Count	' hColumnView.Columns[Index As Integer].Count
Print hGridViewColumn.Max	' hColumnView.Columns[Index As Integer].Max
Print hGridViewColumn.Sort	' hColumnView.Columns[Index As Integer].Sort
Print hGridViewColumn.Ascending	' hColumnView.Columns[Index As Integer].Ascending

The ColumnView class has these selected methods:

tablelayout

Table 17.5.0.2.1: Selected methods of the ColumnView class

The Add (…) method inserts a new row into the ColumnView:

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

• Key is the key of type String for the new line.
• Text (optional) is the displayed text on the new line in the first column.
• Picture (optional) is the image displayed only in front of the text of column 1. By default, no image is displayed.
• Parent (optional) is the key of the parent line into which the line is inserted. By default, the new line is a root line.
• After (optional) is the key from the line after which the new line is inserted. Without this (optional) key, the new line is inserted as the last line by default.
• Note: The return value of the Add () method is a _TreeView_Item object.

To understand the properties, methods, and events of the ColumnView control, you need to understand the (virtual) _TreeView class, because the ColumnView is basically a _TreeView that has been added to the source code to manage columns that are already available in _TreeView. To increase confusion, _TreeView is internally a GridView - a grid of cells into which you can insert text and images. However, you cannot freely access these cells from a _TreeView. The reason for this is that a single _TreeView row is an entire *row* in the GridView.

Example: By calling the Add method:

ColumnView.Add("1", "Text erste Spalte", pibIcon1)

create a new line - identified by the key “1” - to which the text “Text first column” and a preceding icon are added in the only (first) column. Since the return value of the add method is a _TreeView_Item object, you can use this object to specify the texts of other ColumnView columns, but without an image of the type Picture, if required:

ColumnView.Add("1", "Text erste Spalte")[1] = "Text zweite Spalte der 1. Zeile"
ColumnView.Add("1", "Text erste Spalte")[2] = "Text dritte Spalte der 1. Zeile"

For example, an alternative to creating a row of a ColumnView with several columns is not to use the return value of the add method directly, but to save it in a variable of the data type _TreeView_Item and to continue working with this variable:

Dim hItem As _TreeView_Item
 
hItem = ColumnView.Add("1", "Text erste Spalte", pibIcon1)
hItem[1] = "Text zweite Spalte der 1. Zeile"
hItem[2] = "Text dritte Spalte der 1. Zeile"

Another approach with a double indexing offers alternative 2:

ColumnView.Add("1", "Text erste Spalte", pibIcon1)
ColumnView[1][1] = "Text zweite Spalte der 1. Zeile"
ColumnView[1][2] = "Text dritte Spalte der 1. Zeile"

The special treatment of the first column in a row (row) of a ColumnView compared to the other columns requires getting used to, especially since only the first column can be assigned an image.

The ColumnView class has the following events, among others:

tablelayout

Table 17.5.0.3.1: Selected events of the ColumnView class

The following table contains some information about selected properties of the GridView, TableView and ColumnsView controls to help you select the grid for your projects:

The ColumnView class has the following events, among others:

tablelayout

Table 17.5.0.4.1: Selected properties of GridView, TableView and ColumnsView

Die Klasse ColumnView in gb.qt4 (→ gb.gui.base) implementiert ein Steuerelement, das eine TreeView mit Spalten anzeigt.

• Die einzelnen Zeilen einer ColumnView werden durch einen eindeutigen Schlüssel indiziert. Sie zeigen einen Text in jeder Spalte an. Nur in der ersten Spalte kann zusätzlich ein Bild eingefügt werden.
• Nutzen Sie die Columns-Eigenschaft, um die Anzahl der Spalten und ihr Layout zu ändern.
• Das Steuerelement verfügt über einen internen Zeiger für den Zugriff auf seine Zeilen.
• Verwenden Sie die unterschiedlichen Move-Methoden, um den internen Zeiger zu bewegen und die Current-Eigenschaft, um auf das aktuelle (markierte) Zeile zuzugreifen.
• Wenn Sie den internen Zeiger auf eine bestimmte Zeile setzen wollen, dann müssen Sie die Methode MoveTo(Key) benutzen. Beachten Sie, dass alle 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 einer bestimmten Zeile der ColumnView – zu setzen, weisen Sie der Key-Eigenschaft einer Zeile den Schlüssel der zu markierenden Zeile zu.
• Die Eigenschaft ColumnView.Current repräsentiert den vom Benutzer markierten Eintrag im Steuerelement ColumnView, während ColumnView.Item vom Typ _TreeView_Item ein interner, unsichtbarer und von der Eigenschaft ColumnView.Current unabhängiger Zeiger ist.
• Die Eigenschaft ColumnView.Current verwendet man zur Auswertung von Benutzereingaben in einer ColumnView (Scrollen in der ColumnView oder Maus-Klick auf ein Zeile) und die Eigenschaft ColumnView.Item für alle Algorithmen, welche eine ColumnView lesen oder beschreiben.
• Diese Klasse beerbt _TreeView, kann erzeugt werden und verhält sich wie ein Nur-Lesen-Array.

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

Tabelle 17.5.0.1.1 : Ausgewählte Eigenschaften der Klasse ColumnView

Klasse _ColumnView_Columns:

• Diese Klasse ist eine Sammlung aller Spalten in einer ColumnView.
• Diese Klasse ist virtuell.
• Diese Klasse kann nicht erzeugt werden.
• Diese Klasse verhält sich wie ein Nur-Lese-Array.

Die Klasse _ColumnView_Columns verfügt nur über diese vier Eigenschaften:

Ascending As Boolean
Gibt an, ob die Sortierung auf aufsteigend oder absteigend eingestellt ist.

Count As Integer
Gibt die Anzahl der Spalten zurück oder legt sie fest.

Max As Integer
Gib den größten Spaltenindex zurück.

Sort As Integer
Gibt den Spalten-Index zurück, der zum Sortieren der ColumnView-Zeile verwendet wird oder legt diese Spalte über den Index fest.
Der Wert -1 gibt an, dass die Zeile nicht sortiert sind.

Im folgenden Beispiel wird eine Spalte – entsprechend ihrem Index – zurück gegeben, deren 4 Eigenschaften Sie anschließend zum Beispiel abfragen können:

Dim hColumnView As ColumnView
Dim hGridViewColumn As _ColumnView_Columns
 
hGridViewColumn = hColumnView.Columns[ Index As Integer ]
 
Print hGridViewColumn.Count	' hColumnView.Columns[Index As Integer].Count
Print hGridViewColumn.Max	' hColumnView.Columns[Index As Integer].Max
Print hGridViewColumn.Sort	' hColumnView.Columns[Index As Integer].Sort
Print hGridViewColumn.Ascending	' hColumnView.Columns[Index As Integer].Ascending

Die Klasse ColumnView besitzt diese ausgewählten Methoden:

tablelayout

Tabelle 17.5.0.2.1 : Ausgewählte Methoden der Klasse ColumnView

Die Add(…)-Methode fügt eine neue Zeile in die ColumnView ein:

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

• Key ist der Schlüssel vom Typ String für die neue Zeile.
• Text (optional) ist der angezeigte Text auf der neuen Zeile in der 1. Spalte.
• Picture (optional) ist das Bild, das nur vor dem Text der 1. Spalte angezeigt wird. Standardmäßig wird kein Bild angezeigt.
• Parent (optional) ist der Schlüssel der übergeordneten Zeile, in den die Zeile eingefügt wird. Standardmäßig ist die neue Zeile ein Root-Zeile.
• After (optional) ist der Schlüssel von der Zeile, nach der die neue Zeile eingefügt wird. Ohne diesen (optionalen) Schlüssel wird die neue Zeile standardmäßig als letzte Zeile eingefügt.
• Beachten Sie: Der Rückgabewert der Add()-Methode ist ein _TreeView_Item-Objekt.

Um die Eigenschaften, Methoden und Ereignisse des Steuerelements ColumnView zu verstehen, müssen Sie die (virtuelle) Klasse _TreeView verstehen, denn die ColumnView ist im Grunde eine _TreeView, der Quelltext hinzugefügt wurde, um Spalten zu verwalten, die bereits in _TreeView verfügbar sind. Um die Verwirrung zu steigern sei angemerkt, dass ein _TreeView seinerseits intern ein GridView ist – ein Gitter aus Zellen, in die Sie Text und Bilder einfügen können. Sie können aber von einem _TreeView nicht auf diese Zellen frei zugreifen. Der Grund liegt darin, dass ein einzelnes _TreeView-Zeile eine ganze *Zeile* in der GridView ist.

Beispiel: Durch den Aufruf der Add-Methode:

ColumnView.Add("1", "Text erste Spalte", pibIcon1)

erzeugen Sie eine neue Zeile – identifiziert durch den Schlüssel “1” – der in der einzigen (ersten) Spalte der Text “Text erste Spalte” und ein vorangestelltes Icon hinzugefügt wird. Da der Rückgabewert der Add-Methode ein _TreeView_Item-Objekt ist, können Sie die Texte von weiteren ColumnView Spalten – jedoch ohne ein Bild vom Typ Picture – über dieses Objekt festlegen, wenn das erforderlich wird:

ColumnView.Add("1", "Text erste Spalte")[1] = "Text zweite Spalte der 1. Zeile"
ColumnView.Add("1", "Text erste Spalte")[2] = "Text dritte Spalte der 1. Zeile"

Eine Alternative zum Erzeugen einer Zeile einer ColumnView mit mehreren Spalten besteht zum Beispiel darin, den Rückgabewert der Add-Methode nicht direkt zu nutzen, sondern in einer Variablen vom Datentyp _TreeView_Item zu speichern und mit dieser Variablen weiter zu arbeiten:

Dim hItem As _TreeView_Item
 
hItem = ColumnView.Add("1", "Text erste Spalte", pibIcon1)
hItem[1] = "Text zweite Spalte der 1. Zeile"
hItem[2] = "Text dritte Spalte der 1. Zeile"

Ein anderen Ansatz mit einer Doppel-Indizierung bietet Alternative 2:

ColumnView.Add("1", "Text erste Spalte", pibIcon1)
ColumnView[1][1] = "Text zweite Spalte der 1. Zeile"
ColumnView[1][2] = "Text dritte Spalte der 1. Zeile"

Die besondere Behandlung der ersten Spalte in einem Zeile (Zeile) einer ColumnView gegenüber den weiteren Spalten ist gewöhnungsbedürftig, zumal man nur der ersten Spalte ein Bild zuweisen kann.

Die Klasse ColumnView besitzt unter anderem die folgenden Ereignisse:

Tabelle 17.5.0.3.1 : Ausgewählte Ereignisse der Klasse ColumnView

Die folgende Tabelle enthält einige Angaben zu ausgewählten Eigenschaften der drei Steuerelemente GridView, TableView und ColumnsView, die Ihnen die Auswahl des Gitters für Ihre Projekte erleichtern sollen:

Die Klasse ColumnView besitzt unter anderem die folgenden Ereignisse:

tablelayout

Tabelle 17.5.0.4.1 : Ausgewählte Eigenschaften der Steuerelemente GridView, TableView und ColumnsView