History of testAbort

== Syntax ==

bool testAbort()

== Return ==

Returns true if the user has pressed the Esc key, false otherwise.

== Description ==

The testAbort() function tests for a user-requested abort.

Since we often want to call testAbort() and updateProgress() at the same place in our filter program, FM provides a shortcut by calling testAbort() implicitly within updateProgress(), and returning the result of testAbort() as the result of updateProgress(). So we can kill two birds with one stone and replace the separate calls to testAbort() and updateProgress() with the following single call:

<code>

// Update the progress indicator

// and check for user abort on

// each new row...

if (updateProgress(y - y_start, y_end - y_start)) break;

</code>

Also note that the following lines are equivalent:

<code>

if(testAbort()) break;

</code>

<code>

if( getAsyncKeyState(VK_ESCAPE)<0 ) break;

</code>

== Example ==

<code>

%ffp

// If processing takes too much

// time, user can abort at any

// time. Instead of using break,

// I chose to integrate testAbort

// directly in the test of the

// first "for loop", which is a

// cleaner solution.

ForEveryTile:

// row by row, included testAbort here

for ( y = 0; y < Y && !testAbort(); y++ )

{

// column by column

for ( x = 0; x < X; x++ )

{

// channel by channel

for ( z = 0; z < Z; z++ )

{

// draw something

if((x%8)==(y%8)) pset(x,y,z,0);

// update the preview

// (only in active filter dialog)

updatePreview( 0 );

}

}

}

return true;

</code>

== See Also ==

updateProgress, getAsyncKeyState

== Comments ==

Everyone can add his comments about his experiences with this function here. Tips for using it are welcome, too.