When Your Event Function Should Return an Action Code

If your event function does not wish to terminate the processing of the current panel, it should return a value of 1 on success and 0 on error. For example, if you write an event function for the form event table that causes the user to jump to a particular field on the form, your event function should call sfm_nextitem() to move the user to the new item, and return a value of 1.

However, if your event function will terminate processing, the function should return an action code that indicates why processing is being terminated. For example, if you write an event function that exits the current form, the event function should return the action code AC_EXIT. Action codes that can be returned from your event functions include:

• nAC_EXIT: To exit the current panel. If the panel is a data form, the data entered by the user will be validated, converted, and put into the underlying data variable. If the panel is a choice list attached to a data field, the data field will be updated with the current value selected in the choice list.
  
  
• nAC_QUIT: To quit from the current panel. If the panel is a data form, the data entered by the user will not be validated or saved. If the panel is a choice list attached to a data field, the data field will not be updated.
  
  
• nAC_NEXTFORM: To move the user to the next form. This action code should only be used if the current panel is a data form for which the next form was specified in the Designer or with the function sfm_link().
  
  
• nAC_PREVFORM: To move the user to the previous form. This action code should only be used if the current panel is a data form for which the previous form was specified in the Designer or with the function sfm_link().

If you are calling an existing Vermont Views function from your event function, the easiest way to ensure that you return the correct value from your event function is to return the value returned by the Vermont Views function. For example, if your event function calls kd_lftcsr(), you can use this function to set your return value in one of two ways. An example of the first way is:

int myfunc(dfmp, eventp)

DFORMPTR dfmp;

EVENTPTR eventp;

{

    int retval = 0;



    retval = kd_lftcsr(dfmp, eventp);

    ...        /* do additional processing */

    return(retval);

}

Alternatively, you could use this statement as your return statement:

return(kd_lftcsr(dfmp, eventp));