Object Definition

Define a table object.

[enabled|disabled] [visible|invisible]

[editable|readonly] [ [color] BG_COLOR]

table TABLE_NAME

size WIDTH HEIGHT at [position] X Y

[in PARENT_NAME1 [in PARENT_NAME2] ...]

[ [color] FG_COLOR foreground]

[parameter is PAR_STRING]

[helpid is HELP_ID]

[font FONT_NAME]

[horizontal scroll bar]

[vertical scroll bar]

[group is GROUP_NAME]

[edit key [is] ACCEL_KEY]

[column delimiter [is] {csv|tab|STRING} ]

[row delimiter [is] RD_STRING]

[column grid {visible|invisible}]

[column headings [blank|letters|numbers|text|hide] ]

[ [single|multiple|no] column selection]

[ [not] resizeable [columns] ]

[row grid {visible|invisible}]

[row headings [blank|numbers|hide] [width is NUM]]

[ [single|multiple|no] row selection]

# COLUMN_DEFINITION

[insert [visible|invisible] [editable|readonly]

{integer|float|boolean|string}

column [COL_NAME]

[width is COL_WIDTH]

[ [{after|before} column] COL_ID | at {beginning|end} ]

[text size LENGTH]

[parameter is PAR_STRING]

[ [not] resizeable]

[ [left|center|right] heading [ [is] HEADING_STRING] ]

[{left|center|right} align]

[format is FORMAT_STRING] ]

# ROW_DEFINITION

[insert row

[{after|before} row ROW_ID | at {beginning|end} ]

[{value|values} [column {COL_NAME|COL_POSITION} is] EXPRESSION

[, [column {COL_NAME|COL_POSITION} is] EXPRESSION ] ... ]

#OR#

file FILENAME ]

enabled | disabled

Enable or disable use of the table. Enabled tables can receive the cursor, be selected, and so on. The default is enabled.

Query using: selectability of

Modify using: enable, disable

visible | invisible

Make the table or a column visible (shown) or invisible (hidden). An invisible column still has a position number in the table, at the place it would be if it were visible. The default is visible.

Query using: visibility of, visibility of column

Modify using: make visible, make invisible, make column visible, make column invisible

editable | readonly

Make the table or a column editable or read-only. Values in editable tables may be edited. When a table is read-only, the end user may not modify any part of the table, although your ESL application can still change it directly. The default is editable.

Query using: is readonly, column is readonly

Modify using: make editable, make readonly, make column editable, make column readonly

color BG_COLOR

The background color of the table.

Query using: background of

Modify using: make background

TABLE_NAME

Either the actual table name or a string variable that contains the name. Using a string variable to hold the name is particularly useful when adding a table dynamically.

size WIDTH HEIGHT

Integer values indicating the size of the table in dialog units. This includes the size of scroll bars, when they are displayed.

Query using: xsize of, ysize of

Modify using: change size

at X Y

Integer values indicating the position of the table, in dialog units, in the parent region.

Query using: xposition of, yposition of

Modify using: change position

in PARENT_NAME1

in PARENT_NAME2

The ancestry of the table object.

Query using: ancestry of

Modify using: change position

color FG_COLOR foreground

The foreground color of the table.

Query using: foreground of

Modify using: make foreground

parameter is PAR_STRING

A parameter string, if any, for the table or column.

Query using: parameter of, parameter of column

Modify using: make parameter, make column parameter

helpid is HELP_ID

A string or integer value representing the help panel identifier. This should match the help panel defined in the library specified by the help library declaration. If your application will run under Windows, version 3.0, HELP_ID must be an integer.

Query using: helpid of

Modify using: make helpid

font FONT_NAME

The name of the font in which you want the headings and cell contents to appear. You can use either system or ESL fonts. (See the description of the font is Font Reference Definition.)

You cannot change the font of a control at runtime.

horizontal scroll bar

Enable the horizontal scroll bar.

vertical scroll bar

Enable the vertical scroll bar.

group is GROUP_NAME

A string value identifying the group to which the table belongs within the dialog box or region.

edit key is ACCEL_KEY

Any value defined in the header file ACCEL.INC that you want use in place of F2 as the key a user can press to start editing a cell for this table. Printable characters are not allowed. If the user presses the Shift or Ctrl key while pressing the edit key, they will be ignored. For example, if the edit key is F2, then F2, Shift+F2, Ctrl+F2 and Shift+Ctrl+F2 are all equivalent.

Query using: edit key of

Modify using: change edit key

column delimiter is csv|tab|STRING

The column delimiter format you want to use when converting rows to and from text strings. The default is tab; this is commonly used for transferring column-oriented text on the clipboard or in files. Comma-separated value format (csv) is often used when storing column data in text files. Your application can also specify its own column delimiter with a single-character string.

If the delimiter is csv when converting a row to a string, column values are quoted, if necessary. In this case, if a column value contains either a comma, a newline, or a quote, then the value quoted, all quotes in the string will be doubled. For example, a column value of John said, "Hi!", when converted for csv format, would become "John said, ""Hi!""" Other delimiters do not use quotes.

Query using: column delimiter of

Modify using: change column delimiter

row delimiter is RD_STRING

The row delimiter format used when converting multiple rows to and from text strings. The csv and tab column delimiter formats automatically set the row delimiter to be newline, but your application can also define its own string for the row delimiter.

Query using: row delimiter of

Modify using: change row delimiter

column grid visible | invisible

Turn grid lines between columns on or off. The default is column grid visible.

Query using: column grid is visible

Modify using: make column grid

column headings

Set the format of the heading label at the top of all columns to one of the following values:

blank Empty headings. Use this to provide a blank selection button.

letters Headings of consecutive letters; that is, the same sequence used by many spreadsheets (A, B, ..., Z, AA, BB...).

numbers Headings of column numbers.

text Headings of the text defined in the heading attribute of each column. This is the default.

hide Do not show the headings. This prevents users from using column headings as push buttons to select columns.

Note that all column headings are centered over the column by default.

See the "Columns" section for information on setting the heading string for an individual column.

single | multiple | no column selection

Allow your application's users to select multiple columns, only a single column at a time, or no columns. You can specify either row selection or column selection for a table, but not both. The default is no selection for columns.

resizeable columns

Specify whether your users may directly change the size of any column. If this is set to resizeable, then you may also define specific columns as resizeable or not. The default for both tables and columns is resizeable.

Query using: is resizeable, column is resizeable

Modify using: make resizeable, make column resizeable

row grid visible | invisible

Turn grid lines between each row on or off. The default is row grid visible.

Query using: row grid is visible

Modify using: make row grid

row headings

Set the format of the heading label at the left of every row to one of the following values:

blank Empty headings. Use this to provide a blank selection button.

This is the default.

numbers Headings of row numbers.

hide Do not show the headings. This prevents users from using row headings as push buttons to select rows.

width is NUM

Set the width of the row heading to the number of dialog units indicated. The default is nine dialog units for row headings blank or 24 dialog units for row headings numbers.

single | multiple | no row selection

Allow your application's users to select multiple rows, only a single row at a time, or no columns/rows. You can specify either row selection or column selection for a table, but not both. The default is multiple selection for rows.

integer | float | boolean | string

The data type of the information stored in each row in the column you are defining.

Query using: type of

column COL_NAME

Either the column name, or a string variable that contains the column name. This is particularly useful when creating columns dynamically, so they can still be referred to by name, since names are position independent. Also, you may use a string variable when the column name is not a legal ESL identifier. If you omit the column name, then you may refer to the column only by position. Using no name or using a string variable to hold the name is particularly useful when adding a column dynamically.

Column names must conform to the following rules:

Every column name must be unique within its table.

You can reuse any column name in a different table.

You may not give a column the same name as an ESL variable. Conversely, you cannot use an ESL variable name as a column name.

Query using: name of

width is COL_WIDTH

The width of the column in dialog units. The default is a width of 50 dialog units. The maximum width is 120 characters (in any font). The maximum size of all column format and heading strings in a single table is 64K bytes.

Query using: column width

Modify using: change width

after | before column COL_ID

at beginning | end

The position where you want the column you are defining. You may place a column next to any other column already in the table. By default, columns are placed after all columns already defined for the table (at end). You may also place them after or before a named column, at the beginning of the table, or at a numbered position. When you insert a column into an existing table, the columns currently at or after the position of the new column are moved over.

Query using: position of

Modify using: change position

COL_ID

Either the name or the position of a column where you want this column placed.

text size LENGTH

(String columns only.) The maximum number of characters in a string in a string column. The default value is 32 characters, the same as for entry fields. The maximum is 1000 characters. ESL allocates memory for this size string in each row.

Query using: text size of column

left | center | right heading

The alignment of the heading for this column:

left Left-justify the heading.

center Center the heading. This is the default.

right Right-justify the heading.

HEADING_STRING

The string that is displayed at the top of the column. This does not move when the data is scrolled vertically. You can set column headings only if the column headings attribute for the table is text. The maximum width for a heading is 200 characters. The maximum size of all column format and heading strings in a single table is 64K bytes. The heading text is displayed only when the column headings attribute is text.

Query using: heading of

Modify using: column change heading

left | center | right align

The alignment for data in the cells in this column:

left Left-align the data displayed in the cell. This is the default for text and boolean columns.

center Center the data displayed in the cell.

right Right-align the data displayed in the cell. This is the default for integer and float columns.

format is FORMAT_STRING

The format definition you want used when displaying integer, float, or boolean columns. See "Numeric and Boolean Formatting" in the "Description" section.

after | before row ROW_ID

at beginning | end

The position where you want the new row(s) inserted. The default is at end. All rows after those inserted will have their position numbers increased.

value | values

Starts the list of one or more cell values to be used in the row being inserted. There is no difference in using either word.

COL_NAME | COL_POSITION

One of the columns that has already been defined in the table. If you omit COL_NAME or COL_POSITION, then the value will be used for the next column, or the first one, in position order. If there are not enough values to fill in all columns, default values (blank, 0, or null) are placed in the remaining columns.

EXPRESSION

The value for a column in the row. Static columns are defined before rows in the table definition. If a column is added dynamically, then all existing rows will have null values for that column.

ESL evaluates the expression when it adds the row and puts the result value in the proper columns in the new row. If the expression is not the same type as the column, it is converted to that of the destination column.

If there are more expressions than there are columns, the extras are ignored and a compiler warning or runtime log message is generated.

file FILENAME

The name of a file containing the values you want placed in the table. The values in the file must be in the same order as the position of the columns. ESL reads and parses the file (according to the delimiters defined with column and row delimiter is), inserting as many rows as necessary.

As when inserting a single row, values are converted to the required type. If there are not enough values, then default values are used for the remaining columns. If there are too many values for a row, the extra values are ignored.

The file is read at compile-time for static definitions and at runtime for dynamic definitions.

Description

Use the table definition to create and specify the characteristics of a table object. You can use table objects to show any textual data that is organized by rows and columns. A table object is a control and may be a child of a dialog region or dialog box.

To define a table, first specify the basic table attributes, then define the columns in the table, and, finally, define the data in the rows. The only parts of the definition that are required are the table keyword, the table name, and the table's size and position. Attributes before the table keyword must be in the order shown. Attributes after the parent's name and before COLUMN_DEFINITION may be in any order. You must define all columns before defining any rows. You can dynamically change the specifications for any column or row.

To add a table at runtime, use the add action with the same kind of definition as for a statically defined table. You can then use add to table ... insert actions dynamically to put columns and rows into the table.

Columns

You can define columns as part of the table definition or you can dynamically add them to or remove them from a table. By default, new columns are placed after the last defined column.

Only the keyword insert, the type, and the keyword column are required in the definition. Attributes after the column name may be in any order. Specify all other attributes in the order shown.

If you name a column, the name only needs to be unique among the other columns in the same table (similar to elements in a structure). If you do not specify column names, then you can only refer to them by position.

To add a column to a table at runtime, use the add to table ... insert column action. It uses the same kind of definition as statically defined columns. You may add or remove columns from a table dynamically, except when the table's parent is permanent and/or visible and there is more than 64K bytes of row data currently in the table. The built-in function column modifiability of returns true if insert (column), remove (column), and change column position are currently allowed.

A table may contain up to 250 columns. The maximum size of the data in all columns in a single row is 65,534 bytes. Columns use memory in each row according to their type, as follows:

Type Memory Used

integer 4 bytes

float 8 bytes

boolean 1 byte

string text size of column + 1

If the table allows multiple row selection, add one byte.

Numeric and Boolean Formatting

The FORMAT_STRING determines how the values in integer, float, and boolean columns are displayed.

For boolean columns, specify FORMAT_STRING as a value you want used for false, then a vertical bar, and then the value you want used for true; for example, "false|true" or "female|male".

The default is "false|true". When inputting values, pressing the spacebar toggles between the two values specified.

A FORMAT_STRING for numeric columns consists of a series of the following characters.

Note the following points concerning format characters:

The actual decimal and thousands separators displayed are those currently set at the operating system level. The period (.) and comma (,) format characters only indicate the position of the separator, not necessarily the characters used.

If there are more significant digits in the number to the left of the decimal separator than there are format characters, the extra digits will be put in. Thousands separators will be inserted only if they are used in the format.

You can use only one of the sign characters in a format string, but you can place it anywhere in the string.

If no sign character is in the string, ESL treats the string as if there was a minus sign (-) before the first digit.

If there are more fractional digits in the value than in the format string, then the value will be rounded (for example, 1.235 will be formatted as "1.24").

Number Input

When editing an integer or float column, a user must use the decimal separator that has been specified at the operating system level. This is the same character that is used when the number is displayed.

Alternate positive and negative signs are supported for editing integer and float columns. A user may enter a leading sign, trailing sign, or parentheses as the sign for a number. For example, the following positive and negative numbers are valid. Positive numbers: 5, +99.5, 500+. Negative numbers: -6.3, 62-, (640.5). Only a single sign character or a single set of parentheses is allowed.

Rows

You can place initial values in rows of data when you create a table, or you can dynamically define rows by using the add to table ... insert row action. Each insert row statement adds one or more rows to the table. The maximum number of rows in a table is limited primarily by available memory.

You can update or fill in the values of an existing row with actions such as copy to a cell, copy to a row, or read.

Note that rows do not have names; rather, you refer to them by position.

Cells

Cells are the intersection of rows and columns. Most of the attributes of a cell are determined by the column it is in. The only attribute that an individual cell has is the data value stored in it.

Removing Selected Rows

You may find it useful to remove all the selected rows in the table Object using a for each selected row loop. When doing so, it is necessary to update the row variable (Row_ID) as each row is removed. Because the loop decreases the number of rows in the table Object by one each time it executes, the row variable also needs to be decreased by one each time through the loop. The following code shows an example:

response to...

for each selected row Row_IV in Table_TBL loop

    remove row Row_IV from Table_TBL

    copy (Row_IV - 1) to Row_IV

end loop

This code produces the desired result and deletes each selected row from the table Object.

Row and Column Selection

When a table object has no editable columns, the cursor is drawn around a row if row selection is enabled, or around a column if column selection is enabled.

The "multiple row selection" attribute allows you to select one or more rows. If the table has no editable columns, then when clicking the mouse in a cell or pressing the space bar, the row is selected. If the table does have editable columns, rows are selected by clicking on the row heading or by pressing the key combination Shift+Space bar.

The "multiple column selection" attribute allows you to select one or more columnss. If the table has no editable columns, then when clicking the mouse in a cell or pressing the space bar, the column is selected. If the table does have editable columns, columns are selected by clicking on the column heading or by pressing the key combination Shift+Space bar.

Example

# Minimal Table

table Simple_Tbl size 150 50 at 0 0 in Parent_DR

    insert string column

    insert integer column

    insert row values "Simple Table", 1

    insert row values "Another Row", 2

# Car Lot Table

visible editable table CarLot_TBL

    size 250 100 at 0 50 in LotParent_DR

    parameter is "Sales"

    helpid is CarHelp

    horizontal scroll bar

    vertical scroll bar

    column headings text

    no column selection

    not resizeable columns

    row headings hide

    multiple row selection

    insert string column Make

    text size 15

    left align

    heading "Make of car"

    insert string column Model

    text size 20

    left align

    heading "Model"

    insert integer column Year

    left align

    heading "Year"

    format is "00"

    insert float column Price

    right align

    heading "Asking Price"

    format is "($#,##0.00)"

The following table contains examples of format strings and the resulting values, assuming that the user's computer has set the period (.) for decimals and a comma (,) for thousands.

The character "~" is used to indicate blanks in the result:

The following shows how the decimal and thousands separators will appear if they are set to comma (,) for decimals and a period (.) for thousands on the user's computer:

See Also

"Table Objects," in the Programming Guide.

insert Drawing Statement

make column readonly and make column editable Action Statement

read Action Statement

textual row of Object Inquiry Built-in Function

write Action Statement

for each selected row/column loop Action Statement