/* $DOC$
   $TEMPLATE$
      Document
   $NAME$
      The idle states
   $CATEGORY$
      Document
   $ONELINER$
      Readme file for Idle States
   $DESCRIPTION$
      The idle state is the state of the Harbour virtual machine when it
      waits for the user input from the keyboard or the mouse. The idle
      state is entered during Inkey() calls currently. All applications
      that don't use Inkey() function call can signal the idle states with
      the call of hb_idleState() function (or hb_idleState() on C level).

      During idle states the virtual machine calls the garbage collector and
      it can call user defined actions (background tasks). It also releases
      the CPU time slices for some poor platforms that are not smart enough
      to detect it automatically.

      For defining the background tasks see the hb_idleAdd() and hb_idleDel()
      functions.

      For direct call for background actions see hb_idleState() function.

      For signaling the idle state from C code see the hb_idleState()
      API function.
   $SEEALSO$
      hb_idleAdd(), hb_idleDel()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      hb_idleAdd()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Idle states
   $ONELINER$
      Adds the background task.
   $SYNTAX$
      hb_idleAdd( <bAction> ) --> nHandle
   $ARGUMENTS$
      <bAction> is a codeblock that will be executed during idle states.
      There are no arguments passed to this codeblock during evaluation.
   $RETURNS$
      <nHandle> The handle (an integer value) that identifies the task. This
      handle can be used for deleting the task.
   $DESCRIPTION$
      hb_idleAdd() adds a passed codeblock to the list of background
      tasks that will be evaluated during the idle states. There is no
      limit for the number of tasks.
   $EXAMPLES$
      nTask := hb_idleAdd( {|| SayTime() } )
   $STATUS$
      R
   $COMPLIANCE$
      Harbour extension similar to ft_OnTick() function available
      in NanForum library.
   $PLATFORMS$
      All
   $SEEALSO$
      hb_idleDel(), hb_idleState()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      hb_idleDel()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Idle states
   $ONELINER$
      Removes the background task from the list of tasks.
   $SYNTAX$
      hb_idleDel( <nHandle> ) --> bAction
   $ARGUMENTS$
      <nHandle> is the identifier of the task returned by the
      hb_idleAdd() function.
   $RETURNS$
      <bAction> NIL if invalid handle is passed or a codeblock that was
      passed to hb_idleAdd() function
   $DESCRIPTION$
      hb_idleDel() removes the action associated with passed identifier
      from the list of background tasks. The identifier should be the
      value returned by the previous call of hb_idleAdd() function.

      If specified task is defined then the codeblock is returned
      otherwise the NIL value is returned.
   $EXAMPLES$
      nTask := hb_idleAdd( {|| SayTime() } )
      Inkey( 10 )
      bAction := hb_idleDel( nTask )
   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$
      All
   $SEEALSO$
      hb_idleAdd(), hb_idleState()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Procedure
   $NAME$
      hb_idleState()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Idle states
   $ONELINER$
      Evaluates a single background task and calls the garbage collector.
   $SYNTAX$
      hb_idleState()
   $ARGUMENTS$
      None
   $DESCRIPTION$
      hb_idleState() requests the garbage collection and executes a
      single background task defined by the codeblock passed with
      hb_idleAdd() function. Every call to this function evaluates a
      different task in the order of task creation. There are no
      arguments passed during a codeblock evaluation.

      This function can be safely called even if there are no background
      tasks defined.
   $EXAMPLES$
      nTask1 := hb_idleAdd( {|| SayTime() } )
      nTask2 := hb_idleAdd( {|| SaveScreen() } )
      DO WHILE ! bFinished
         bFinished := DoSomethingVeryImportant()
         hb_idleState()
      ENDDO
      cbAction := hb_idleDel( nTask1 )
      hb_idleDel( nTask2 )
   $STATUS$
      R
   $COMPLIANCE$
      Harbour extension similar to ft_IAmIdle() function available
      in NanForum library.
   $PLATFORMS$
      All
   $SEEALSO$
      hb_idleAdd(), hb_idleDel()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      C Function
   $NAME$
      hb_idleState()
   $CATEGORY$
      C level API
   $SUBCATEGORY$
      Idle states
   $ONELINER$
      Evaluates a single background task and calls the garbage collector.
   $SYNTAX$
      void hb_idleState( void );
   $ARGUMENTS$
      None
   $DESCRIPTION$
      hb_idleState() is a C function that requests garbage collection and
      executes a single background task defined by the codeblock passed
      with hb_idleAdd() function. It also releases the CPU time slices for
      platforms that require it.

      Every call for this function evaluates different task in the
      order of task creation. There are no arguments passed during
      codeblock evaluation.

      This function can be safely called even if there are no background
      tasks defined.

      This function is automatically called from the Inkey() function.
   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$
      All
   $SEEALSO$
      hb_idleAdd(), hb_idleDel(), hb_idleState()
   $END$
 */