_CoreTask.h

Go to the documentation of this file.

/*******************************************************************************
*
* E M B E D D E D   W I Z A R D   P R O J E C T
*
*                                                Copyright (c) TARA Systems GmbH
*                                    written by Paul Banach and Manfred Schweyer
*
********************************************************************************
*
* This file was generated automatically by Embedded Wizard Studio.
*
* Please do not make any modifications of this file! The modifications are lost
* when the file is generated again by Embedded Wizard Studio!
*
* The template of this heading text can be found in the file 'head.ewt' in the
* directory 'Platforms' of your Embedded Wizard installation directory. If you
* wish to adapt this text, please copy the template file 'head.ewt' into your
* project directory and edit the copy only. Please avoid any modifications of
* the original template file!
*
* Version  : 10.00
* Profile  : STM32H747
* Platform : STM.STM32.RGB565
*
*******************************************************************************/
 
#ifndef _CoreTask_H
#define _CoreTask_H
 
#ifdef __cplusplus
  extern "C"
  {
#endif
 
#include "ewrte.h"
#if EW_RTE_VERSION != 0x000A0000
  #error Wrong version of Embedded Wizard Runtime Environment.
#endif
 
#include "ewgfx.h"
#if EW_GFX_VERSION != 0x000A0000
  #error Wrong version of Embedded Wizard Graphics Engine.
#endif
 
/* Forward declaration of the class Core::Task */
#ifndef _CoreTask_
  EW_DECLARE_CLASS( CoreTask )
#define _CoreTask_
#endif
 
/* Forward declaration of the class Core::TaskQueue */
#ifndef _CoreTaskQueue_
  EW_DECLARE_CLASS( CoreTaskQueue )
#define _CoreTaskQueue_
#endif
 
 
/* The class Core::Task provides the basic functionality for implementing tasks 
   which then can be scheduled for later execution. The execution of tasks is controlled 
   by instances of the class Core::TaskQueue.
   Usually you will use this class to derive your own task class. In your task class 
   you can implement what to do when the task is started, canceled or completed. 
   For this purpose you can override the methods @OnStart(), @OnCancel(), @OnComplete() 
   and @OnContinue().
   It is essential to understand, that the entire 'task' functionality has nothing 
   to do with multi-threading or multi-tasking features known from operating systems. 
   Applications developed with Chora are limited to a single-thread environment. 
   There is no real background thread activity. Accordingly your implementation 
   of a task should behave cooperatively. A well designed task should perform its 
   job quickly, use timers or effects to delay execution and when the job is done 
   reports its completion by calling the method @Complete(). */
EW_DEFINE_FIELDS( CoreTask, XObject )
  EW_VARIABLE( queue,           CoreTaskQueue )
  EW_VARIABLE( prev,            CoreTask )
  EW_VARIABLE( next,            CoreTask )
EW_END_OF_FIELDS( CoreTask )
 
/* Virtual Method Table (VMT) for the class : 'Core::Task' */
EW_DEFINE_METHODS( CoreTask, XObject )
  EW_METHOD( OnComplete,        void )( CoreTask _this, CoreTaskQueue aQueue )
  EW_METHOD( OnCancel,          void )( CoreTask _this, CoreTaskQueue aQueue )
  EW_METHOD( OnStart,           void )( CoreTask _this, CoreTaskQueue aQueue )
  EW_METHOD( Complete,          void )( CoreTask _this )
EW_END_OF_METHODS( CoreTask )
 
/* The method OnComplete() is called when the task is done with its work. The default 
   implementation of this method does nothing. You can override this method in derived 
   task classes and implement what to do when the task is finished. For example, 
   you can release resources used temporarily during animations.
   To complete a task you should call explicitly the method @Complete(). The parameter 
   aQueue refers to the queue this task belonged to. It can be used e.g. to schedule 
   again a task to the same queue, etc. */
void CoreTask_OnComplete( CoreTask _this, CoreTaskQueue aQueue );
 
/* Wrapper function for the virtual method : 'Core::Task.OnComplete()' */
void CoreTask__OnComplete( void* _this, CoreTaskQueue aQueue );
 
/* The method OnCancel() is called when the task is canceled after being started. 
   The default implementation of this method does nothing. You can override this 
   method in derived task classes and implement what to do when the task is prematurely 
   aborted. For example, you can stop running timers and effects started in the 
   preceding @OnStart() method.
   To cancel a task you should call explicitly the method @Cancel(). The parameter 
   aQueue refers to the queue this task belonged to. It can be used e.g. to schedule 
   again a task to the same queue, etc. */
void CoreTask_OnCancel( CoreTask _this, CoreTaskQueue aQueue );
 
/* Wrapper function for the virtual method : 'Core::Task.OnCancel()' */
void CoreTask__OnCancel( void* _this, CoreTaskQueue aQueue );
 
/* The method OnStart() is called at the begin of the execution of this task. The 
   default implementation of the method simply cancels the task causing the next 
   available task in the task queue to be started. You should override this method 
   in derived task classes to implement what the task should do.
   There are three typical application cases how to implement the OnStart() method:
   - In its simplest case the entire task algorithm is implemented in the OnStart() 
   method. In this case the method @Complete() should be called before leaving OnStart().
   - If the task does take long time for execution by using timers or effects, you 
   should put in OnStart() the code necessary to start the timers/effects. Don't 
   forget to call @Complete() when all timers/effects are done.
   - If the task is divided in many small execution steps, the OnStart() method 
   should call @Continue() to request the @OnContinue() method to be executed after 
   a short delay (usually after the next screen update). In @OnContinue() you can 
   perform the next step of the task. If necessary, @OnContinue() can also request 
   to be called again after a short delay. At the end of the task, after the last 
   step is terminated, don't forget to call @Complete().
   The parameter aQueue refers to the queue this task belongs to. It can be used 
   to schedule more task to execute later. */
void CoreTask_OnStart( CoreTask _this, CoreTaskQueue aQueue );
 
/* Wrapper function for the virtual method : 'Core::Task.OnStart()' */
void CoreTask__OnStart( void* _this, CoreTaskQueue aQueue );
 
/* The method Complete() informs the task queue about the completion of this task. 
   Thereupon the next available task in the queue can be executed. This method is 
   usually called in context of the @OnStart() or @OnContinue() method when the 
   task has finalized its work. Calling the method for a not current task has no 
   effect. */
void CoreTask_Complete( CoreTask _this );
 
/* Wrapper function for the virtual method : 'Core::Task.Complete()' */
void CoreTask__Complete( void* _this );
 
/* The method Cancel() removes this task from the task queue where the task has 
   been previously scheduled. In the case the task is already in progress, the queue 
   will advise the task to abort its work immediately before the task is removed 
   from the queue (see @OnCancel()).
   Whether a task is waiting for execution can be determined by @IsScheduled(). 
   Whether a task is in progress can be determined by @IsCurrent().
   Canceling a running task will cause the task queue to start the next available 
   task. */
void CoreTask_Cancel( CoreTask _this );
 
/* The method IsCurrent() returns 'true' if the affected task is currently performed. 
   The method returns 'false' if the task is done, waiting for execution or it simply 
   doesn't belong to any task queue. */
XBool CoreTask_IsCurrent( CoreTask _this );
 
#ifdef __cplusplus
  }
#endif
 
#endif /* _CoreTask_H */
 
/* Embedded Wizard */