PtAppAddWorkProc()

Add a WorkProc (background) function

Synopsis:

PtWorkProcId_t *PtAppAddWorkProc( 
                   PtAppContext_t app_context,
                   PtWorkProc_t work_func,
                   void *data );

Description:

This function adds a WorkProc entry to the WorkProc (background) process stack. The entry becomes the current WorkProc entry.

WorkProc functions don't run concurrently; only the one at the top of the stack runs.

When there are no events pending from Photon, the current WorkProc entry's function is invoked by PtMainLoop().

The app_context argument is the address of the application context, a structure that manages all the data associated with this application. This must be specified as NULL, so that the default context is used.

The work_func argument points to the WorkProc function to be invoked when no Photon events are pending. The function takes this form:

int (*work_func)(void *data)

You can declare the function to be of type PtWorkProcF_t to take advantage of the compiler's type-checking.

If the WorkProc function changes the display, it should call PtFlush() to make sure the display is updated.
If the WorkProc function pointed to by work_func returns Pt_CONTINUE, it stays on the WorkProc stack. If it returns Pt_END, it's removed from the WorkProc stack and the next WorkProc entry on the stack becomes the current entry.

Returns:

A pointer to a PtWorkProcId_t structure that identifies the specified WorkProc entry for the given application context. If an error occurs, the function returns NULL.

Examples:

This example comes from the Rebound demo. These are the callbacks that start and stop the rebounding work procedure, rebound_process().

// From src/start_rebound.c
int
start_rebound( PtWidget_t *widget, void *data, 
               PtCallbackInfo_t *cbinfo )
{
  PtArg_t args[2];

  if(stopped) {
    if ( delay_value == 0 ) {
      if ( !bkgd_id ) // is one running?
        bkgd_id = PtAppAddWorkProc( NULL, rebound_process, 
                                    ABW_rb_pane );
      PtSetArg( &args[0], Pt_ARG_TIMER_INITIAL, 0, 0 );
      PtSetResources( ABW_timer_wgt, 1, args );
    } else {
      if ( bkgd_id )
        PtAppRemoveWorkProc( NULL, bkgd_id );
      PtSetArg( &args[0], Pt_ARG_TIMER_INITIAL, 1, 0 );
      PtSetArg( &args[1], Pt_ARG_TIMER_REPEAT, 
                SPEED_MULTIPLY*delay_value, 0 );
      PtSetResources( ABW_timer_wgt, 2, args );
    }
    stopped = 0;
  }

  return( Pt_CONTINUE );
}

// From src/stop_rebound.c
int
stop_rebound( PtWidget_t *widget, void *data, 
              PtCallbackInfo_t *cbinfo )
{
  PtArg_t args[1];

  if ( bkgd_id ) {
    PtAppRemoveWorkProc( NULL, bkgd_id );
    bkgd_id = NULL;
  }
  PtSetArg( &args[0], Pt_ARG_TIMER_INITIAL, 0, 0 );
  PtSetResources( ABW_timer_wgt, 1, args );

  stopped = 1;

  return( Pt_CONTINUE );
}

Classification:

Photon

Safety:
Interrupt handler	No
Signal handler	No
Thread	No