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:

// Update the progress indicator
// and check for user abort on
// each new row...

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

Also note that the following lines are equivalent:

if(testAbort()) break;
if( getAsyncKeyState(VK_ESCAPE)<0 ) break;

Example

%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;
}

See Also

updateProgress, getAsyncKeyState

Comments

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