History of OnFilterStart

== Syntax ==

:OnFilterStart: (<compound-statement>)?

== Return ==

:false if filter processing is to continue with the ForEveryTile handler, or true to abort further filter processing (though this latter option is currently ignored in FM 0.4.20).

== Description ==

:The OnFilterStart handler is invoked at the start of each filter run, just before the ForEveryTile, ForEveryRow, ForEveryPixel, and (R, G, B, A)? handlers are called. The OnFilterStart handler is a good place to perform one-time calculations at the start of a filter run, check for valid control inputs, valid image mode, etc.

== Default handler ==

:The default OnFilterStart handler simply returns false, passing control to the ForEveryTile handler for every tile in the image or preview.

== Example ==

:You can test the current image mode in the OnFilterStart handler, and abort the invocation if the image mode is inappropriate. For example:

<code>

OnFilterStart:{

if (imageMode != RGBMode) {

ErrorOk("Not an RGB image.");

doAction(CA_CANCEL); /* for now, until return true works correctly */

return true; /* abort filter processing */

}

return false; /* continue with ForEveryTile */

</code>

:Note that we added a call to doAction to explicitly cancel the filter run, since return true does not yet correctly abort the filter run. Once this is fixed, the call to doAction can be removed.

== Also see ==

:handlers, ForEveryTile, ForEveryRow, ForEveryPixel, OnFilterEnd

== Comments ==

:Everyone can add his/her comments about this handler here. Tips for using it are welcome, too.