EXECUTE METHOD IN SUBFORM

Home

4D v16.3


EXECUTE METHOD IN SUBFORM ( subformObject ; methodName {; return {; param} {; param2 ; ... ; paramN}} )

Parameter	Type	Description
subformObject	Text	Name of subform object
methodName	Text	Name of project method to be executed
return	Operator, Variable	* if method does not return a value
		Value returned by method
param	Expression	Parameter(s) to pass to method

Description

The EXECUTE METHOD IN SUBFORM command can be used to execute the methodName project method in the context of the subformObject subform object.

The project method called can receive from 1 to X parameters in param and return a value in return. Pass * in the return parameter if the method does not return parameters.

You can pass the name of any project method that is accessible from the database or the component executing the command in methodName. The execution context is preserved in the method called, which means that the current form and current form event remain specified. If the subform comes from a component, the method must belong to the component and have the "Shared by components and host database" property.

This command must be called in the context of the parent form (containing the subformObject object), for example via the form method.

Note: The methodName method is not executed if the subformObject is not found in the current page or is not yet instantiated.

Example 1

Given the "ContactDetail" form used as subform in the parent form "Company". The subform object that contains the ContactDetail form is named "ContactSubform". Imagine that we want to modify the appearance of certain elements of the subform according to the value of the field(s) of the company (for example, "contactname" must switch to red when [Company]City="New York" and to blue when [Company]City="San Diego"). This mechanism is implemented via the SetToColor method. To be able to get this result, the SetToColor method cannot be called directly from the process of the "On Load" form event of the Company parent form because the "contactname" object does not belong to the current form, but to the form displayed in the "ContactSubform" subform object. The method must therefore be executed using the EXECUTE METHOD IN SUBFORM command in order to function correctly.

 Case of

    :(Form event=On Load)

       Case of

          :([Company]City="New York")

             $Color:=$Red

          :([Company]City="San Diego")

             $Color:=$Blue

          Else

             $Color:=$Black

       End case

       EXECUTE METHOD IN SUBFORM("ContactSubform";"SetToColor";*;$Color)

 End case

Example 2

You are developing a database that will be used as a component. It includes a shared project form (named, for instance, Calendar) that contains dynamic variables as well as a public project method that is used to adjust the calendar: SetCalendarDate(varDate).
If this method was used directly in the Calendar form method, you could call it directly in the "On Load" event:

SetCalendarDate(Current date)

But, in the context of the host database, imagine that a project form contains two "Calendar" subforms, in subform objects called "Cal1" and "Cal2". You must set the date of Cal1 to 01/01/10 and the date of Cal2 to 05/05/10. You cannot call SetCalendarDate directly because the method will not "know" which forms and variables it should apply. Therefore, you must call it via the following code:

 EXECUTE METHOD IN SUBFORM("Cal1";"SetCalendarDate";*;!01/01/10!)

 EXECUTE METHOD IN SUBFORM("Cal2";"SetCalendarDate";*;!05/05/10!)

Example 3

Advanced example: in the same context as previously, this example provides a generic method:

  // Contents of the SetCalendarDate method

 C_DATE($1)

 C_TEXT($2)

 Case of

    :(Count parameters=1)

  // Standard execution of method (as if it was executed from

  // the form itself) or specifically for a context (see case 2)

 

    :(Count parameters=2)

  // External call, needs a context

  // Recursive call with only one parameter

       EXECUTE METHOD IN SUBFORM($2;"SetCalendarDate";*;$1)

 End case

System variables and sets

If this command is executed correctly, the system variable OK is set to 1; otherwise, it is set to 0.