GAMBAS BOOK 3.19.5

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:

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:

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:

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:

Table 17.5.0.4.1: Selected properties of GridView, TableView and ColumnsView