PHYSICAL-COLUMNS (numeric)

The PHYSICAL-COLUMNS property enables programmers to move or hide grid columns on the screen without having to recode the program.

A grid with adjustable columns can present a significant programming challenge. To alleviate this, the grid control maintains two separate notions of the column order – one for the user and one for the program – as follows:

physical columns: These are what are seen on the screen by the user. The leftmost column is column 1, the next one to the right is column 2, and so on.
logical columns: These represent how the program understands the grid layout, and is the order in which data appears in the RECORD-DATA property for any given row. Again, this lays out left to right, but the order is based on the ordering in the record and not necessarily what appears on the screen.

Tip: Think of logical columns as "the way I laid out the grid" and physical columns as "what the user sees."

By default, the PHYSICAL-COLUMNS property is set to a value of 0 (zero), which indicates that both logical and physical columns are in the same order and are numbered sequentially starting with 1.

When you explicitly set PHYSICAL-COLUMNS to rearrange or hide columns, the grid control then creates a list that maps logical-to-physical column numbers. Every time you set this property, a new column number is appended to the list. Its position in the list is the logical column number, and the list value is the corresponding physical column number. To move a column using PHYSICAL-COLUMNS, simply switch the order of the columns in the list. For example:

PHYSICAL-COLUMNS = (1,2,4,5,3,6,7)

Places logical column 3 in physical column 5 and moves logical columns 4 and 5 to the left one position to fill in the gap.

To hide a column, set its physical column number to its own negative. For example:

PHYSICAL-COLUMNS = (1, 2, 3, -4, 5, 6, 7)

Hides logical column 4. A hidden column is still considered a physical column, and other columns need to be numbered as if they were visible. The physical column number of the hidden column helps the grid to paint the hidden-column mark that appears on the screen.

Like many grid properties, PHYSICAL-COLUMNS appends until reset with a 0. We recommend that you put 0 as the first entry in any new list-style setting of PHYSICAL-COLUMNS to reset the list. The initial 0 empties the existing list and does not count as a column itself. For example, the following clears PHYSICAL-COLUMNS of all existing values and also sets new values:

PHYSICAL-COLUMNS = (0, 1, 2, 3, -4, 5, 6, 7)

Important:

The number of entries in PHYSICAL-COLUMNS must match the number of physical columns in the grid
Each physical column number must appear exactly once, and can be either negative or positive
An initial 0 in a list serves to clear existing PHYSICAL-COLUMNS values, and does not represent a column
Other settings can make the grid unstable

Tips:

You can use PHYSICAL-COLUMNS to modify the grid, independent of the settings for the MOVEABLE-COLUMNS and ADJUSTABLE-COLUMNS styles, which limit what the user can do, but do not limit what the program can do. See Common Properties for more information.
Remember that the physical column numbers represented by the PHYSICAL-COLUMNS property, in their original order, are in the same order as they appear on the screen. When you use PHYSICAL-COLUMNS to move a column, think of moving a physical column to a "slot" as it appears on the screen. For example, in a five-column grid numbered from 1 through 5 from left to right, to move column 5 to column 3, you are essentially moving the fifth column to the third "slot" on the screen,. This necessarily bumps the third and fourth slots up by 1. Therefore, the specification is: PHYSICAL-COLUMNS=(1, 2, 5, 3, 4). Think through each item in the record, one by one, and ask yourself which screen column you want to see it in.
The grid control maintains the PHYSICAL-COLUMNS setting as needed to track user changes. You only need to set it if you want the program itself to make a change.

Important: Unless otherwise explicitly stated, this documentation references all column properties and events using logical column values, and list-style properties are listed in logical-column order.