Working with Events

Working with Free OperationsWorking with Diagrams

Events are objects specifically designed for communication. They consist of event-signals and event-parameters. In the QP Frameworks underlying QM, events are subclasses of the QEvt base class. QM incorporates such events by recognizing that a given class is a (direct or indirect) subclass of QEvt and by providing the event stereotype for those classes. Additionally, event classes can be placed in packages with the event stereotype

Event Signals

The event-signal provides information about the occurrence conveyed by the event. In QM, event-signals are used as transition triggers. Event-signals are typically enumerated in a header file, as illustrated in the following screen shot:

Event-signals enumerated in a header file

Attention

By the QM convention, the event signals must have the _SIG suffix. To avoid clutter, the _SIG suffix is omitted in the state diagrams. For example, the MISSILE_FIRE_SIG enumerated in the game.hpp header file appears as the MISSILE_FIRE trigger in a state diagram, but the QM code generator will add the _SIG suffix in the generating code. See also: transition trigger.

Note

The event-signals cannot start at zero, but must start with the Q_USER_SIG offset.

Currently, QM does not provide any more support for handling event-signals. In the future, QM will add support for partitioning the signal space and for associating event-signals with custom event classes.

Event Parameters

The purpose of subclassing QEvt is to create events with parameters. These parameters are added in subclasses of QEvt as attributes of the event classes.

Event classes (subclasses of QEvt) in an events package

For example, the event class ObjectImageEvt in the screen shot above specifies the following event parameters:

x : uint8_t
y : int8_t
bmp : uint8_t

Note

When adding event parameters you should keep in mind the size of the event class. The instances of event classes are stored in the QP event pools, which then must be sized accordingly. Also, you typically should keep event classes simple PODs (Plain Old Datatypes), meaning that you should not provide constructors, destructors, virtual functions (in C++), etc.

Declaring Event Classes

Once the event classes are specified in the QM model, you typically need to provide the declaration of these classes in a header file. A header file is the right place, because events are shared among components, so they typically need to be included in multiple modules (.c or .cpp files).

You can declare event classes in a header file either one at a time:

Declaring individual event classes

Alternatively, if you placed all your events in a dedicated package, you can simply generate declaration of the whole package:

Declaring the whole event package

The latter declaration (the whole event package) results in the following generated code:

/*.$file${.::game.h} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv*/
. . .
/*.$declare${Events} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv*/
/*.${Events::ObjectPosEvt} .................................................*/
typedef struct {
/* protected: */
    QEvt super;
 
/* public: */
    uint8_t x;
    uint8_t y;
} ObjectPosEvt;
/*.${Events::ObjectImageEvt} ...............................................*/
typedef struct {
/* protected: */
    QEvt super;
 
/* public: */
    uint8_t x;
    int8_t y;
    uint8_t bmp;
} ObjectImageEvt;
/*.${Events::MineEvt} ......................................................*/
typedef struct {
/* protected: */
    QEvt super;
 
/* public: */
    uint8_t id;
} MineEvt;
/*.${Events::ScoreEvt} .....................................................*/
typedef
 struct {
/* protected: */
 QEvt super;
 
/* public: */
 uint16_t score;
} ScoreEvt;
/*.$enddecl${Events} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*/
. . .

Using Event Classes in the Code

As mentioned before, the purpose of custom event classes is to represent events with parameters. So now, in the code you need to access the event parameters. The QP/C and QP/C++ frameworks provide a special macro Q_EVT_CAST() to encapsulate down-casting the current event e to the specific subclass of QEvt and then to conveniently access the event parameters. This is illustrated in the screen shot below:

Using custom event in a transition action

Note

The macro Q_EVT_CAST() encapsulates the deviation from MISRA-C/C++ rules of casting pointers.

Working with Free OperationsWorking with Diagrams