Characteristics of Table controls in a window

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Help / Developing an application or website / Controls, windows and pages / Controls: Available types / Table control

Overview
Initial state of the Table control
Display options
Selection mode
Column display options
Populate Table controls programmatically
Displaying the details of a row in an internal window
Scrollbars in a Table control
Options kept for backward compatibility with the earlier versions
Forcing the title to be single-line
5.5-compatible input mode

WINDEV

WEBDEV

WINDEV Mobile

Others

Characteristics of Table controls in a window

Overview

Table controls allow you to display and/or enter data. This data can be retrieved from a data source, a WLanguage variable or be defined programmatically.

This help page presents the main characteristics that can be defined for a Table control in a window:

Initial state of the Table control.
Table control display options.
- Selection mode in the Table control.
- Column display options.
Populate Table controls programmatically.
Display the details of a row in an internal window.
Manage scrollbars in a Table control.
Options kept for backward compatibility.
- Single-line column titles.
- Management of 5.5-compatible mode.

You can also define the data source displayed in the control. For more details, see Content of the Table control.

Initial state of the Table control

The initial state of a Table control can be as follows:

This initial state can be defined when creating the control and be changed at any time in the "UI" tab of the Table control description window.

The different options are as follows:

Visible: The Table control can be visible. This option can be modified using the Visible property.
Editable: Users will be able to enter data in the different columns of the control if they are in edit mode.
The Table control is not available in edit mode. It is available in read-only.
Selection (non-editable): Users will not be able to enter data in the columns of the control. However, they can select rows in the control:
- by clicking the desired row.
- by calling the TableSelectPlus function.
  The row will be selected with the selection bar.
  Remark: The value of the Table control corresponds to the selected row. The row selection code is executed each time a row is selected.
No edit, no selection: Users will not be able to enter data in the columns of the control. A row can only be selected using TableSelectPlus. This row will be selected with the selection bar. The user will not be able to change the position of the selection bar.
Remark: The value of the Table control corresponds to the selected row.
Tip: This option is recommended to highlight a row with the selection bar.
Grayed: The Table control and its columns will be grayed out. The user will not be able to enter data in the control.

Display options

Selection mode

The selection modes define how the different elements of the Table control (rows, columns, cells, etc.) can be selected by the user or programmatically. The selection mode is defined when creating the control. It can be modified at any time in the "UI" tab of the Table control description window.

The available selection modes are as follows:

No selection: No selection bar will be displayed, however the selected row, column or cell will have focus (it will be bordered by dots). A row, column or cell can be selected by clicking on it or programmatically.
Single selection: The selected row, column or cell will be displayed behind the selection bar. A row, column or cell can be selected by clicking on it or programmatically.
Multi-selection: Several rows, columns or cells of the Table control can be selected at the same time:
- with the Shift key if the rows, columns or cells are consecutive or with the Ctrl key if they are not consecutive.
- programmatically.
  In this case, there will be as many selection bars as there are selected elements.

Remarks:

A WLanguage error will occur if you try to select multiple rows programmatically and the selection mode is set to "Single selection".
During a multiple selection by cell, to select a row, all the cells found in the row must be selected. To make this operation easier, you can define a row selector ("Style" tab, "Row selector" element, "Selector" option, "Left arrow").

The selected elements are retrieved:

with the TableSelect function. You can use the tsRow, tsColumn, tsCellRow and tsCellColumn constants to retrieve information on the selected rows, columns and cells.
with the TableSelectCount function. You can use the tsRow, tsColumn, tsCellRow and tsCellColumn constants to retrieve the number of rows, columns and cells selected.

Example: The following example shows how to get the row and column number for the selected cells in the Table control.

// Retrieve the number of selected cells
NbSelected is int
NbSelected = TableSelectCount(TABLE_DetailedStats, tsCell)
// Loop through the selected cells
FOR i = 1 _TO_ NbSelected
// Retrieve the row and the column
nRow = TableSelect(TABLE_DetailedStats, i, tsCellRow)
nColumn = TableSelect(TABLE_DetailedStats, i, tsCellColumn)
// Process
...
END

Only the row selection mode is available.

Column display options

There are multiple options to configure the display mode of the columns. These options are available in the "Details" tab of the description window of the Table control.

These options are as follows:

Remember column configuration: This option allows you to save the configuration of the columns (size, order, etc.) when the window or application is closed.
'Select columns...' menu: This option enables a context menu so that the user can select which columns to show or hide in the Table control.
Multiline text columns: This option enables line wrapping in a column. Thus, the entire text is displayed in the cell, regardless of how long it is.
Maximum number of lines displayed in a row: Table control rows can contain multiple lines. This option sets the maximum number of lines a cell can display, to prevent content from spreading over too many lines, making the row unnecessarily high.
Number of columns fixed to the left: This option allows you to specify the number of columns fixed on the left. These columns will remain visible on the left side of the control and cannot be moved. The user will not be able to hide these columns using the horizontal scrollbar.
The user can also freeze or unfreeze columns via the "Padlock" cursor or the "Freeze columns on the left" option in the context menu of the column title. For more details, see Freezing columns in Table controls.
You can also freeze a column programmatically with TableFixColumn.
Angle for the title of columns: If the titles of the columns are wider than the content in the columns, you can angle the titles (or write them vertically, for example). To do so, specify the desired angle in the "Details" tab of the control description. This option can be modified using the OrientationTitle property.
Edit column title-headers: You can define title-headers in the columns. A column title-header is an additional title displayed above the title of one or more columns. For more details, see Managing titles of columns in a Table control.

Remark: The column titles are multiline by default. The height of the header fits automatically to the number of lines. The titles of the columns support RTF.

Populate Table controls programmatically

When a Table control is populated programmatically, some specific information can be displayed:

Progress Bar,
Information window, etc.

To display information when populating a Table or TreeView Table control programmatically:

Open the description window of the Table or TreeView Table control.
In the "UI" tab of the control description window, check "Display an internal window over the rows".
If necessary, specify the internal window to be used. You can:
- use the WINDEV default window ("None" option).
- import the preset window into the project and customize it ("Preset window" option).
  If this option is selected, the WDAAF internal component is immediately added to the current project. The "IW_TableLoadStatus" internal window is automatically associated with the "Display an internal window over the rows" option.
  Remark: If the WDAAF component already exists, only the window is added to the component.
If necessary, validate the control description window.
To enable this mechanism, call TableStartFilling and TableEndFilling to frame the code used to populate the Table control.

Remarks:

By default, the "No available data" message is displayed in the empty Table control. During the fill operation, an infinite progress bar is displayed at the bottom of the Table control.
The default internal window has 3 planes:
- Plane 1 containing an infinite progress bar.
- Plane 2 containing the caption displayed if the Table control is empty. The caption "No available data" is displayed by default.
- Plane 3 containing the caption displayed before the call to TableStartFilling.
The "IW_TableLoadStatus" internal window can also be used to programmatically populate Looper controls.

Displaying the details of a row in an internal window

A table row displays various information in its different columns. However, to get a more readable interface, why not display this information in a popup window?

To display a window corresponding to the details of a row found in a Table/TreeView Table control:

Open the description window of the Table or TreeView Table control.
In the "UI" tab of the control description window, in the "Internal window for row details" section, specify:
- the internal window that will be used to display the row details. This internal window is an internal window of your project.
- the left indent of the internal window (in relation to the control).
- whether the internal window must be displayed when the row is hovered. In this case, the internal window will be displayed after a 1-second rollover.
Validate the description window.
A "+" sign is displayed in the first column of the Table/TreeView Table control.

At runtime:

A "+"/"-" sign allows the user to display/close the row details. This element can be customized via the table style ("Style" tab, "Image +/- IW for row details" element).
The row is enlarged in height to display the internal window. The internal window is displayed below the data found in the row.

Characteristics of internal window:

To get information about the Table/TreeView Table control that displays the details, the internal window must use the following prototype:
PROCEDURE <Name of Internal Window>(<Parent table>, <Row number>)
where:
- Parent Table: corresponds to the name of the Table or TreeView Table control that displayed the internal window.
- Row number: corresponds to the number of the row that displayed the internal window.
These parameters are automatically filled at runtime.
The internal window can contain all types of controls (including a Table control).
The internal window can be used to modify the information displayed in the Table control. In this case, you have the ability to use a button in the internal window allowing you to validate the modified data. The code of this button can be:
ScreenToFile()
HSave()
TableDisplay(TableName, taCurrentSelection)
TableCollapse(TableName)
In the internal window, you have the ability to access the control of the parent table. For example, to access a control found in a Container column:
gCTable[gnRowNum].BTN_Modify.State = Grayed
The controls found in the internal window can be anchored: resizing the table in width or resizing the current row in height affects these anchors.
The captions of controls found in the internal window can have the "Text" color in order to adapt the color of these captions in row selection.

Remarks:

To display/close the internal window through programming, use TableExpand/TableCollapse.
The height of the row that displays the internal window corresponds to the initial height of the row plus the height of the internal window in edit mode (InitialHeight property).
The background image defined for the row is enlarged to correspond to the size of the expanded row.

Several properties are used to manage the characteristics of the internal window through programming:


IndentLineDetails	The IndentLineDetails property is used to get or change the value of the left indent of the internal window that shows the details of a row of a Table control.
WinLineDetails	The WinLineDetails property allows you to get and change the name of the internal window used to display the details of a row in a Table control.

Special cases
- This feature is not available for the Horizontal Table controls.
- The interface of internal window cannot be modified by the end user.

Scrollbars in a Table control

By default, scrollbars adapt to the contents of Table controls (based on a data file, populated programmatically or based on a variable). The size of the scrollbar varies based on the number of elements to be displayed.

Caution: if a filter is used with this type of scrollbar, the data source is read in the background. The "end of initialization" code will be executed at the end of the iteration. This process may take relatively long after opening the window, depending on the data source to loop through.

The scrollbar options are grouped in the "Details" tab of the Table control description:

Parameters of the scrollbar in a Table control

The option "Move by pixel" allows for a soft move of the rows: instead of "jumping" from a row to another one, the move is performed pixel by pixel: a "multiline" row of a Table control can be truncated if necessary when it is displayed.

Remark: Disabling the proportional scrollbar disables the multi-selection of rows.

The "Move with finger" option is used to specify that the Table control accepts the scrolling with finger (if the display device is touch-enabled). This option is enabled by default in WINDEV Mobile for the new Table controls. In WINDEV, it is disabled by default.

Options kept for backward compatibility with the earlier versions

Forcing the title to be single-line

By default, the title of columns found in a Table control is multiline. The option "Force title in a singleline (8)" allows you to go back to the default behavior of version 8.

On the Table controls created with version 8 (or earlier), this option must be unchecked in order to get a multiline column title.

5.5-compatible input mode

With this mode, Table controls behave like in version 5.5. This option is automatically checked if the Table control comes from a migrated WINDEV 5.5 application. This option is available in the "Details" tab of the description of the Table control.

This option must not be used for Table controls created with version 7 (or later) of WINDEV.

All the features of the Table controls will be accessible if this option is unchecked. To go back to the behavior of Table controls in WINDEV 5.5, the code of the control must be adapted.

Two types of Table controls are available if this option is checked:

editable Table control without selection.
non-editable Table control with selection and input (if no column is in edit mode or if the Table control is in selection mode without edit mode).

Reminder: in version 5.5, if the Table control was defined:

as "editable" and if at least one control column was in edit, the selection band was not displayed and it was possible to perform an input in the Table control.
as "editable" (or "inactive") and with no column in edit, the user could not perform any input in the Table control but he could modify the position of the selection bar.