Page subforms

Page subforms can display the data of the current subrecord or any type of pertinent value depending on the context (variables, pictures, and so on). One of the main advantages of using page subforms is that they can include advanced functionalities and can interact directly with the parent form (widgets). Page subforms also have their own specific properties and events; you can manage them entirely by programming.

Note: You can generate components providing additional functionalities through subforms. For more information about this, refer to Developing and installing 4D components.

To activate the page mode for a subform, simply uncheck the Output subform option in the Property List. In this case, the properties related to the configuration of list subforms (Selection Mode, Double-click on Line, and so on) are no longer displayed:

The page subform uses the input form indicated by the “Detail Form” property. Unlike a list subform, the form used can come from the same table as the parent form. It is also possible to use a project form. When it is executed, a page subform has the same standard display characteristics as an input form. The output form mechanisms (related more particularly to the management of markers) are not activated.

You manage page subforms using specific properties that facilitate their integration and interaction with the parent form.

You can bind a variable with a subform object. By default, this variable is named "Subform" like the object itself. It has a type (see following section) and can be shown as a standard variable in the parent form. Modifying this variable triggers form events which let you synchronize the parent form and subform values:

• Use the On Data Change form event to indicate to the subform container that the variable value was modified in the subform.
• Use the On bound variable change form event to indicate to the subform (form method of subform) that the variable was modified in the parent form.

You use this property to set the type for the variable bound with the subform object. By default, the type is Alpha. The variable type determines the nature of the values exchanged between the parent form and the subform through this variable.
You can set the type to "None" and in this case, 4D types the variable automatically during execution (see the "Dynamic variables" section of Variables in the Language Reference manual).

This property lets you choose different types of sources:

• <None>: Choose this type of source if you want to use a project form or a component form as the subform. You only use these subforms as page subforms; they cannot work if the the "Output subform" option is checked.
  A component form appears in the "Detail Form" list when it is published in the component (see Publishing a subform (component)).
• Table Name: Choose this source type when you want to use a table form.

A subform object can have an object method which lets you control its functioning, in particular when events are triggered. For a description of the events managed by page subforms, refer to the documentation for the Form event command. 

Note that you have to manage interactions between the contents of the subform object and the parent form through specific mechanisms (see Advanced inter-form programming).

The variable bound to the subform lets you link the two contexts (form and subform) to put the finishing touches on sophisticated interfaces. For example, imagine a subform representing a dynamic clock, inserted into a parent form containing an enterable variable of the Time type:

Both objects (time variable and subform container) have the same variable name. In this case, when you open the parent form, 4D synchronizes both values automatically. If the variable value is set at several locations, 4D uses the value that was loaded last. It applies the following loading order:
1-Object methods of subform
2-Form method of subform
3-Object methods of parent form
4-Form method of parent form

When the parent form is executed, the developer must take care to synchronize the variables using appropriate form events. Two types of interactions can occur: form to subform and vice versa.

Case 1: The value of the parent form variable is modified and this modification must be passed on to the subform. In our example, the time of ParisTime changes to 12:15:00, either because the user entered it, or because it was updated dynamically (via the Current time command for example).

In this case, you must use the On bound variable change form event. This event must be selected in the subform properties; it is generated in the form method of the subform.

The On bound variable change form event is generated:

• as soon as a value is assigned to the variable of the parent form, even if the same value is reassigned,
• if the subform belongs to the current form page or to page 0.

Note that, as in the above example, it is preferable to use the OBJECT Get pointer command which returns a pointer to the subform container rather than its variable because it is possible to insert several subforms in the same parent form (for example, a window displaying different time zones contains several clocks). In this case, only a pointer lets you know which subform container is at the origin of the event.

Case 2: The contents of the subform are modified and this modification must be passed on to the parent form. In our example, imagine that the subform interface lets the user to "manually" move the hands of the clock. 

In this case, from the subform, you must assign the object value to the variable of the parent subform container. As in the previous example, we recommend that you use the OBJECT Get pointer command with the Object subform container selector which returns a pointer to the subform container. 

Assigning the value to the variable generates the On Data Change form event in the object method of the parent subform container, which lets you perform any type of action. The event must be selected in the properties of the subform container.

Note: If you "manually" move the hands of the clock, this also generates the On Data Change form event in the object method of the clockValue variable in the subform.

Communication between the parent form and the instances of the subform may require going beyond the exchange of a value through the bound variable. In fact, you may want to update variables in subforms according to the actions carried out in the parent form and vice versa. If we use the previous example of the "dynamic clock" type subform, we may want to set one or more alarm times for each clock. 

4D has implemented the following mechanisms to meet these needs:

• Use of the "subform" parameter with the OBJECT Get name command to specify the subform object and the OBJECT Get pointer command.
• Calling of a container object from the subform using the CALL SUBFORM CONTAINER command,
• Execution of a method in the context of the subform via the EXECUTE METHOD IN SUBFORM command.

In addition to the Object subform container selector, the OBJECT Get pointer command accepts a parameter that indicates in which subform to search for the object whose name is specified in the second parameter. This syntax can only be used when the Object named selector is passed. 

For example, the following statement:

... retrieves a pointer to the "MyButton" variable that is located in the "MySubForm" subform object. This syntax can be used to access from the parent form any object found in a subform.
Also note the OBJECT Get name command which can be used to retrieve the name of the object that has the focus.

The CALL SUBFORM CONTAINER command lets a subform instance send an event to the subform container object, which can then process it in the context of the parent form. The event is received in the container object method. It may be at the origin of any event detected by the subform (click, drag-and-drop, etc.). 

The code of the event is unrestricted (for example, 20000 or -100). You can use a code that corresponds to an existing event (for example, 3 for On Validate), or use a custom code. In the first case, you can only use events that you have checked in the Property List for subform containers. In the second case, the code must not correspond to any existing form event. It is recommended to use a negative value to be sure that this code will not be used by 4D in future versions.

For more information, refer to the description of the CALL SUBFORM CONTAINER command.

The  EXECUTE METHOD IN SUBFORM command lets a form or one of its object request the execution of a method in the context of the subform instance, which gives it access to the subform variables, objects, etc. This method can also receive parameters.

This mechanism is illustrated in the following diagram:

For more information, refer to the description of the EXECUTE METHOD IN SUBFORM command.

The GOTO OBJECT command looks for the destination object in the parent form even if it is executed from a subform.