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 (see
How You Can Work with Attributes).
For an example of using the WhichTableField method, see
How You Can Sort Table Field Data Generically (see
How You Can Sort Table Field Data Generically).