The SubForm class represents a group of fields, contained in a fixed bounding box, that you can move on the form as a unit. The bounding box constrains the locations of the fields. You cannot move the fields to outside the box.

A field once positioned within a SubForm will remain at that position (XLeft, YTop) relative to the SubForm’s topleft permanently, unless you move it during editing or at runtime. Similarly, if you set its Gravity (or the SubForm’s ChildGravity), the field will stay at the gravity-defined location (topright, for example) even if the SubForm changes size.

SubForms themselves can be fixed in both position and size relative to their parent field by using either or both of their Gravity and SizeToFit attributes. The SizeToFit attribute is particularly useful in situations where frame right-alignment is important, as it is for certain toolbars, for example.

Using SubForms can provide a number of powerful programming advantages. When a SubForm has an associated variable, you can use that variable to reference all fields on the SubForm at once. If you map that SubForm to a user class by setting its datatype, you can pass all of the data displayed within it as an object to other frames or procedures. If instead that object is assigned as the SubForm’s value, the data for the object’s attributes is automatically displayed in the correspondingly-named fields within the SubForm. Any fields in the SubForm that do not map to the user class are ignored when you do this, whether or not they are named, so your SubForm can also contain named buttons and other control fields.

If you do not associate the SubForm with a user class by setting its datatype, but do give it a variable name, OpenROAD creates an unnamed class for the subform, based on the fields it find within the SubForm. You can use this class only within the frame that contains the subform.

You can use a SubForm as a convenience in editing, as a fixed set of fields that can be manipulated as one field. If so, you need not associate the SubForm with a variable. In such cases, OpenROAD considers the SubForm's component fields as part of the form as a whole (or as part of the composite field that contains the SubForm, if that field is named).

A SubForm can have a label (GroupBoxLabel) which is positioned at the SubForm's topleft, appearing halfway on and halfway off the field. Like other ActiveField types, it can have a bitmapped background that paints the field's edges and corners, enabling you to display SubForms with rounded corners and complex outlines. These are powerful features, but they affect how you position fields within the SubForm because they impinge on the background area inside the field's outline. So, for example, a field whose Gravity is AP_TOPLEFT will overlap a GroupBoxLabel, or a topleft rounded corner. In such cases, you should make use of the child margin settings (ChildLeftMargin, ChildRightMargin, ChildTopMargin, ChildBottomMargin), to ensure that all fields within the SubForm are inset enough to avoid these overlaps.