4D v14.3

EXECUTE METHOD IN SUBFORM

Home

 
4D v14.3
EXECUTE METHOD IN SUBFORM

EXECUTE METHOD IN SUBFORM 


 

EXECUTE METHOD IN SUBFORM ( subformObject ; methodName {; return {; param} {; param2 ; ... ; paramN}} ) 
Parameter Type   Description
subformObject  Text in Name of subform object
methodName  Text in Name of project method to be executed
return  Operator, Variable in * if method does not return a value
in Value returned by method
param  Variable in Parameter(s) to pass to method

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 from the form method of the parent form (containing the subformObject object).

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

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

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

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!)

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

 
PROPERTIES 

Product: 4D
Theme: Language
Number: 1085

The OK variable is changed by the command

 
HISTORY 

Created: 4D v12

 
ARTICLE USAGE

4D Language Reference ( 4D v12.4)
4D Language Reference ( 4D v14 R2)
4D Language Reference ( 4D v14 R3)
4D Language Reference ( 4D v13.5)
4D Language Reference ( 4D v14.3)
4D Language Reference ( 4D v14 R4)