OnCtl() is one of the most useful handlers which doesn't do anything to the image pixels. It allows you to trap any event involving a user control and take appropriate action. It's commonly used to change the controls themselves, making for a dynamic user interface which adjusts itself depending on actions taken by the filter's user.

The basic format is:

  OnCtl(n): {
    if (n == ?? && e == ?? ) {
    // ***  code goes here  ***
    // ***   to do things   ***
    }
  return false;
  }  // end of OnCtl()

Where...

-- n specifies the number of the control which was acted upon to generate the event that sent the program into OnCtl(); i.e., if something happened with ctl[4] then n will be 4.

-- e is a global system variable which describes the type of event; the following FilterMeister Events (FME's) with their numerical values are recognized by the system:

* Proper etiquette is to use the FME numerical values only for debugging and testing; otherwise the symbolic constants should be used so the code is easier to read.

* While almost all of these are user actions, you can see that OnCtl() is also where you can trap for divide-by-zero and overflow problems. (Wrong -- use (OnZeroDivide)? or (OnDivideOverflow)? instead. -Alex)

* It's important to specify a value to test e against so you really do the correct thing(s) rather than make possibly invalid assumptions about what is happening; you can use logical operators to simultaneously test for several events which might be occurring with a given control.

Return Value

Use false as the return value if you want to process the image or preview as a result of the changes made in onCtl(). Otherwise return true. (Not yet implemented; the return value, although required, is ignored for now.)

Example:

  OnCtl(n): {
    if (n == CTL_HELP ) {
      // ... open helpfile
      return true;
    else if (n == CTL_DO_FUNKY_STUFF){
      /* ... */
    else if (n == CTL_DO_MORE_FUNKY_STUFF){
      /* ... */
    }
  return false;
  } 

Other notes

* Because the code in OnCtl() is executed when something is done with one of the controls, it appears in the program after the controls have been defined. (Not necessarily true. -Alex)

* Variables can be defined which are local to the handler; these typically go right after the first line. Follow C conventions. Use the pre-declared global variables (or user-defined global variables, once they are implemented) for values needed outside OnCtl() or for values which are saved across filter invocations within a single host session. (See yahoo group message #256 for these.)

* At the FilterMeister yahoo group you can also search through the messages ( http://groups.yahoo.com/group/FMML/messages ) for references to OnCtl and come up with many discussions and coding examples to learn more about the virtually unlimited possibilities.