Editing OnCtl - FilterMeisterWiki

When saving, enter the following:

 ##   ##  _____     ###  ##   ##   _   _ 
 ##   ## (  _  )     #   ##   ##  | | | |
 ##   ## | ( ) |     #   ##   ##  | | | |
 ####### | | | |     #   ## # ##  | | | |
 ##   ## | (_) |     #   #######  \ \_/ /
 ##   ## (_____) #   #   ### ###   \___/ 
 ##   ##          ###    ##   ##

Visit Preferences to set your user name

= 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:
<code>
  OnCtl(n): {
    if (n == ?? && e == ?? ) {
    // ***  code goes here  ***
    // ***   to do things   ***
    }
  return false;
  }  // end of OnCtl()
</code>

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:
*FME_UNKNOWN = 0
*FME_ZERODIVIDE = 1
*FME_DIVIDEOVERFLOW = 2
*FME_CLICKED = 3
*FME_DBLCLK = 4
*FME_PAGEUP = 5
*FME_PAGEDOWN = 6
*FME_LINEUP = 7
*FME_LINEDOWN = 8
*FME_MOUSEOVER = 9
*FME_MOUSEOUT = 10
*FME_MOUSEMOVE = 11
*FME_LEFTCLICKED_DOWN = 12
*FME_LEFTCLICKED_UP = 13
*FME_RIGHTCLICKED_DOWN = 14
*FME_RIGHTCLICKED_UP = 15
*FME_TIMER = 16
*FME_ZOOMCHANGED = 17 (not yet implemented)
*FME_KEYDOWN = 18
*FME_KEYUP = 19
*FME_VALUECHANGED = 20
*FME_SIZE = 21
*FME_ENTERSIZE = 22
*FME_EXITSIZE = 23
*FME_DRAWITEM = 24
*FME_CUSTOMEVENT[[Anchor FME_CUSTOMEVENT]] = 25
*FME_COMBO_DROPDOWN = 26
*FME_COMBO_CLOSEUP = 27
*FME_CONTEXTMENU = 28
*FME_SETEDITFOCUS = 29
*FME_KILLEDITFOCUS = 30
*FME_PREVIEWDRAG = 31

* 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:
<code>
  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;
  } 
</code>

== 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 FMML Yahoo Group message #256 for these.)

Summary of change:
Add document to category: