ColdFrame: Event translation

Events

Each event is mapped to a distinct type, derived from ColdFrame.Project.Events.Event_Base, in the package for the class to which the event is directed. Instance events are derived from Instance_Event_Base, a child of Event_Base which is constrained by an access to the instance to which the event is directed.

For a class event, this results in

type Button_Event
is new ColdFrame.Project.Events.Event_Base with record
   Payload : Button_Name;
end record;

(all class events have payloads), and for an instance event, in

type Button_Push (For_The_Instance : access Instance)
is new ColdFrame.Project.Events.Instance_Event_Base (For_The_Instance)
with null record;

States

The states in the state model are translated as a private enumeration type, State_Machine_State_T. The initial state (by default Initial) is the first literal.

In the example, the type would be

type State_Machine_State_T is
  (Initial,
   Idle,
   Lit);

The instance state is represented by a created instance variable

State_Machine_State : State_Machine_State_T := Initial;

This is not intended to be made directly visible outside the class. Instead, it's expected that you'll test it within operations and return an appropriate result:

function Is_On (This : Handle) return Boolean is
begin
   return This.State_Machine_State = Lit;
end Is_On;

Another instance variable Old_State_Machine_State is available if you really need an action to know which state the instance was in before the event. It's normally better to use different states.

Transitions

When an event is dispatched to a state machine, there are three possible outcomes, depending on what the state model says about the event occurring in the current state:

• If the transition is marked «ignore», the event is thrown away.
• If the transition isn't in the model, the exception ColdFrame.Exceptions.Cant_Happen is raised.
• Otherwise, it's a legal transition:
  1. The instance variable Old_State_Machine_State is set to the current state;
  2. the instance variable State_Machine_State is set to the target state;
  3. the transition action and the entry actions are executed in order.
  so you can write your action operation to behave differently according to what state you're now in (or have come from, or both). Please don't alter these variables yourself.
  In general, it's better to show behaviour in the state machine rather than embedded in code.

It is legal to use the instance Delete operation as an entry action (ColdFrame doesn't check that it's in a final state). Of course, it needs to be the last action.