History of 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.)