OnCtl

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 coding style is to use these FME numerical values only for debugging and testing; in everyday code 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