TableField Methods
This section describes the methods defined for the TableField object. For more information about these methods, see the Language Reference Guide.
InsertColumn and DeleteColumn Methods
These methods are used by the Frame Editor for constructing table fields dynamically. The InsertColumn method inserts a new column into a table field, while the DeleteColumn method removes an existing column.
Do not use the DeleteColumn method to make a column invisible. For more information about hiding a column, see
How You Can Use Hidden Columns.
WhichRow Method
A table field generally displays a subset of the rows in its associated array. For example, the table field may display only four rows at a time, although the underlying array contains 20 rows. Therefore, a data item currently displayed in the third row of the table field might actually belong to the thirteenth row of the array.
To determine which array row contains the value in a specific cell in a table field, use the WhichRow method. The syntax for WhichRow is:
integer = tablefield.WhichRow(cellfield = FormField)
The return value identifies the array row that contains the data displayed in the specified cell field. If the specified cell field is not part of the table field or is part of an empty row, this method returns zero.
One common use of this method is in ChildExit event processing, to determine whether the user has exited a row within a table field rather than moved to another column within the same row:
if field(custtable).currow !=
field(custtable).whichrow(cellfield=
curframe.targetfield)
then
/* The row is being exited */
endif;
This expression on the left side of the if statement:
field(cust_table).currow
returns the number of the array row that last had the input focus. The expression on the right side, because the specified cell field is the target field, returns the array row number of the row that gets the input focus next. If the row numbers returned by these two expressions are not the same, then the user has moved the cursor up or down a row.
WhichTableField Method
WhichTableField, a method of the FormField class, indicates if a field is in a table field, and if so, which one.
Because a single control button can manipulate the data in more than one table field, it is important to be able to determine which table field is to be manipulated. You can use the WhichTableField method to determine whether a field is in a table field and, if it is, to return the table field object to a variable. Using this method, you can access all the information about a specific table field, such as its name, column names, and data, without knowing at development time which field is to be accessed.
The syntax for WhichTableField is:
table_field_var = formfield.WhichTableField()
This method returns one of the following values:
• Null if the field is not in a table field
• The table field in which the form field resides
• The innermost table field if the field is in a nested table field
When a control button is part of a table field and the user invokes one of its menu operations, OpenROAD uses the WhichTableField method to identify the table field. The control button's script invokes the WhichTableField on the TriggerField. Because the control button's menu field triggers the event, and because the control button is directly associated with the table field, OpenROAD can identify the table field.
However, if the control button is independent (not attached to a specific field or table field), you must write your own code to determine which field triggered the control button invocation. If you are dealing with non-nested table fields, you can use FrameExec's InputFocusField attribute in conjunction with the WhichTableField method to determine the table field to be handled.
For example, the following code first checks whether the cursor is on a form field. If it is, the code checks whether the current field is a table field. If the current field is not a table field, the code sends an appropriate message to the user.
table_field = null;
if CurFrame.InputFocusField is not null then
table_field =
CurFrame.InputFocusField.WhichTableField();
endif;
if table_field is null then
message 'You must be in a table field to
sort it.';
resume;
endif;
If the input focus is not on any field when the WhichTableField method is invoked, an error message is written to the trace window and the log file.
This code checks that the field is not null before proceeding, thus preventing the trace window message.
If the field is a table field, the WhichTableField method returns the table field to the user-defined variable table_field. You can obtain information about this table field using attributes and methods provided by the OpenROAD system classes. For example, you can:
• Access array values
To manipulate values in the underlying array, you need a reference variable that points to it. To load values from the underlying array into the array reference variable, use the GetFieldValue method of the FieldObject system class, for example:
...
tf_array = ArrayObject default null;
...
table_field.GetFieldValue
(value = byref(tf_array));
• Get information about table field and array attributes
The InputFocusField attribute makes it easy to determine the name of the column from which the user invoked a control button operation (provided the column does not display a nested CompositeField). The following code gets the name of the current column into the col_name variable:
col_name = CurFrame.InputFocusField.Name;
To obtain information about all of the table field's columns, such as their names, data types, and current biases, you must loop through the table field's column fields. For example, the following code obtains and displays the names and data types of all the columns in table_field:
i = 1;
while i <= table_field.TableBody.ChildFields.LastRow do
message 'column name:' +
table_field.TableBody.ChildFields[i].Name;
message 'col_title:' +
columnfield(table_field.TableBody.ChildFields
[i]).Title;
i = i + 1;
endwhile;
The TableBody attribute of the TableField system class contains the set of column fields for the table field. Because TableBody is of type StackField, it has access to the ChildFields attribute defined for its parent, CompositeField.
To iterate through the columns of a table field, use the following syntax:
tablefield_refvar.TableBody.ChildFields[x]
To apply ColumnField attributes (such as ProtoField and Title) to the value returned by this iteration process requires casting the returned value to an object of the ColumnField data type.
For more information about using the TableBody attribute, see the
Language Reference Guide. For more information about casting, see
How You Can Work with Attributes.
For an example of using the WhichTableField method, see
How You Can Sort Table Field Data Generically.