Workbench User Guide : Creating and Using Basic Fields : Composite Fields : Matrix Fields
 
Share this page          
Matrix Fields
A matrix field appears as a rectangle that contains fields arranged in rows and columns. The component fields stay aligned even if you rearrange or reorder them. The matrix field can include any combination of fields.
A matrix field is useful for forms that you intend to port to other systems, because the individual fields stay aligned when you port the form. For more information about using matrix fields to create portable forms, see the Programming Guide.
A matrix field is made up of cells, some of which can be empty. After creating a matrix field, you can add fields, move fields between cells, and remove fields. You can expand the matrix field by adding rows or columns or shrink the matrix field by deleting rows or columns.
By default, fields within a matrix field are centered in their respective fields. You can change the position of fields within the cells by using the Property Inspector to change the ChildGravity property of the matrix field. To change the position of an individual field within its matrix field cell, set the field's Gravity property. (You may use either the Property Inspector or the Gravity command on the Layout menu to change a field's gravity setting.)
Note:  For more detailed information about the Gravity and ChildGravity properties, see the Gravity section under Common Field Properties.
Create a Matrix Field
You can create a matrix field to align multiple fields. You can either group existing fields, or insert new fields. See the appropriate procedure, following.
To create a matrix field by grouping existing fields
1. Open your frame in the Frame Editor (see Open an Existing Frame).
2. Select the fields to be included in the matrix field.
Note:  For information about selecting fields, see How You Can Select Fields.
3. Click Group, Matrix Field.
Workbench moves the individual fields into a matrix field, keeping the fields in similar relative positions.
4. Set the properties and style for the matrix field.
Note:  For complete descriptions of each field property, see Matrix Field Properties and Common Field Properties.
To create a new matrix field
1. Open your frame in the Frame Editor (see Open an Existing Frame).
2. Click Insert, Field, Matrix Field.
3. Click to place the field on the form.
Workbench places the field on the form with some placeholder child fields to prevent the collapse of the matrix field.
4. Add your own fields to the matrix field and then delete the placeholder fields.
5. Set the properties and style for the matrix field.
Note:  For complete descriptions of each field property, see Matrix Field Properties and Common Field Properties.
Matrix Field Properties
All the properties for matrix fields are described under Common Field Properties, with the exception of the following properties or values that are specific to the matrix field type:
ChildBottomMargin
Specifies the bottom margin (in 1000ths of an inch) around each child field within the composite field and between the child field and the bottom boundary of the composite field
ChildGravity
Specifies the default position of each child field relative to its cell in the composite field. Valid alignment options are:
FA_DEFAULT (system default value)
FA_NONE
FA_TOPCENTER
FA_TOPLEFT
FA_TOPRIGHT
FA_CENTERLEFT
FA_CENTER
FA_CENTERRIGHT
FA_BOTTOMCENTER
FA_BOTTOMLEFT
FA_BOTTOMRIGHT
For more information about the Gravity and ChildGravity properties, see the Gravity section under Common Field Properties.
ChildLeftMargin
Specifies the left margin (in 1000ths of an inch) around each child field within the composite field and between the child field and the left boundary of the composite field
ChildRightMargin
Specifies the right margin (in 1000ths of an inch) around each child field within the composite field and between the child field and the right boundary of the composite field
ChildTopMargin
Specifies the top margin (in 1000ths of an inch) around each child field within the composite field and between the child field and the top boundary of the composite field
CollapsePolicy
Specifies what happens when an entire row or column in the matrix is empty. Valid options are:
CP_NONE
Specifies that empty rows and columns are allowed and maintained. If you set the Rows and Columns properties, the settings are enforced.
CP_BOTH
Specifies that empty rows and columns are removed automatically, as soon as the last field is removed from the row or column. Setting either the Rows or Columns property has no effect.
CP_ROWS
Specifies that empty rows are removed automatically, as soon as the last field in the row is removed. Setting the Rows property has no effect. However, empty columns are maintained, and you can set the Columns property.
CP_COLUMNS
Specifies that empty columns are removed automatically, as soon as the last field in the column is removed. Setting the Columns property has no effect. However, empty rows are maintained, and you can set the Rows property.
Default: CP_BOTH
Columns
May let you specify the number of columns within the matrix field, depending on the CollapsePolicy property setting
Rows
May let you specify the number of rows within the matrix field, depending on the CollapsePolicy property setting
Note:  The number of rows and columns should be consistent with the total number of child fields in the matrix field.