A Domain Specific Language for Android touch events: Part 2: Construction and inner workings

I would like to start with a disclaimer: the following description is how I came to this specific DSL. It is by no means my intention to provide any guidance on constructing a DSL in general, although I hope that some of the ideas presented here can be useful for implementing other but similar DSLs.

In an attempt to get some structure into our language we write down the sentences we would like to be able to write, hoping this will reveal this structure in our language:

• on touchup show a menu of options
• on move draw a line
• if touchdown on rectangle and next move, drag the rectangle

1. Some kind of touch event happening
2. Do some action

1. Some kind of touch event happening
2. Check if a condition is fulfilled
3. If so, do some action
4. If not, do some other action

1. On touchdown followed by any of the constructions above
2. And next on move, again followed by any of the constructions above
3. And next touchup, yes, also followed by any of the above

This sequence can of course be repeated several times, think about a double click gesture for example: it will have twice the above event sequence.

Remember that our domain specific language is a Fluent API. It is not a completely new programming language but is built on top of an existing language. In our case it is built on top of the Java language and thus we can only use language constructs supported by the Java language like method calls and arguments to these methods.

Our basic event sequence becomes:

touchdown().andnext().move().andnext().touchup()

The action sequence becomes:

touchdown().do(action)

In this, action is a parameter telling what to do on the touchdown event. Of course, while the example shows this connected to the touchdown event, you can do the same for the move or touchup event.

The conditional sequence becomes:

touchdown.if(condition).do(trueAction).else().do(falseAction)

In this, condition is a parameter telling what needs to be checked, trueAction is the action performed when the condition is met, and falseAction what needs to be done when the result of the condition is false. The separation of the else() and do() methods is a matter of taste, you can also choose to just provide a method elsedo(). Again, the if sequence can be connected to each of the events touchdown, move and touchup.

We now got the sentences "methodified" and thus, according to how Java is implemented, each method call must return an object of a type which has the next possible methods which can be called from that point on.

To make this a bit more visual, I created the following tables which aligns the methods that should be created by a single type.

(Due to the restricted width available on this page I split the table in 3: the second table is the continuation of the first, and the third is the continuation of the second)

Table 1

Table 2

Table 3

You may ask yourself: what are those numbers doing after those do-methods? They are technically not really necessary, but I found them handy for debugging purposes.

As we could already see when we wrote down our sentences and is apparent again in the above table, the conditional sequence and the action sequence are generic for each motion event. As a result of this, after any of these sequence are ended, we must be able to switch to different motion events. I did this by using generics: the types implementing the sequence have a generic type parameter representing the next motion event and which is then the result type of the method allowing us to move on to the next event. In this case this is the andnext() method.

All this results in following classes:

public interface INextGestureAfterCreate {
    IActionAfterGestureOrConditional<INextGestureAfterTouchDown> TouchDown();
}

public interface INextGestureAfterTouchDown {
    IActionAfterGestureOrConditional<INextGestureAfterMove> Move();
    IActionAfterGestureOrConditional<INextGestureAfterMove> CanMove();
}

public interface INextGestureAfterMove {
    IActionAfterGestureOrConditional<INextGestureAfterTouchUp> TouchUp();
}

public interface INextGestureAfterTouchUp {
    IActionAfterGestureOrConditional<INextGestureAfterTouchDown> TouchDown();
}
                        
public interface IActionAfterGestureOrConditional<NextGesture> {
    INextGestureOrConditional<NextGesture> Do1(IGestureAction action);
    INextGestureOrConditional<NextGesture> Do1(IGestureAction action1, IGestureAction action2);
    INextGestureOrConditional<NextGesture> Do1(IGestureAction action1, 
                IGestureAction action2, IGestureAction action3);
    IAfterConditional<NextGesture> If(IGestureCondition condition);
}

public interface INextGestureOrConditional<NextGesture> {
    NextGesture AndNext();
    IAfterConditional<NextGesture> AndIf();
}

public interface IAfterConditional<NextGesture> {
    NextGesture AndNext();
    public IAfterConditionalContinuation<NextGesture> Do2(IGestureAction action);
    public IAfterConditionalContinuation<NextGesture> Do2(IGestureAction action1, IGestureAction action2);
    public IAfterConditionalContinuation<NextGesture> Do2(IGestureAction action1, 
           IGestureAction action2, IGestureAction action3);
    public IAfterConditionalContinuation<NextGesture> Do2(IGestureAction action1, 
           IGestureAction action2, IGestureAction action3, IGestureAction action4);

}

public interface IAfterConditionalContinuation<NextGesture> {
    NextGesture AndNext();
    IActionAfterGestureOrConditionalContinuation<NextGesture> Else();
}

public interface IActionAfterGestureOrConditionalContinuation<NextGesture>  {
    public INextGestureOrConditional<NextGesture> Do3(IGestureAction action);
    public INextGestureOrConditional<NextGesture> Do3(IGestureAction action1, IGestureAction action2);
    public INextGestureOrConditional<NextGesture> Do3(IGestureAction action1, 
           IGestureAction action2, IGestureAction action3);
    public IAfterConditional<NextGesture> If(IGestureCondition condition);
}

Now we got our sentences implemented, we now have to pass the action and condition parameters to the methods in our sentences.

I have chosen to use a base class to be able to pass these fluently to our methods. For this we implement methods in this base class which either return actions or conditions directly, or return contexts (thus classes implementing interfaces) which eventually result in the returning of actions or conditions.

These interfaces are constructed in a similar way as explained above

We now got our language. The next step is of course make it do something.

There is one thing I haven't discussed yet and that is how to eventually return the sequence of events we have defined with our language. There are some possibilities here, like for example ending our sentences with something like AndCreate().

I didn't do this however, instead I opted to start with a Create method and pas to it the sequence it has to fill. Thus, by calling methods from the DSL, the sequence is being filled with gestures it has to detect, conditions which need to be fulfilled and actions to execute.

This results in two classes:

1. TouchGesture which represents the sequence which has to be executed
2. TouchEvent which represents a touch event with its conditions and actions

The following code listing only shows the code which is important for the event sequencing. To see the complete source you should consult the source code:

public class TouchGesture implements IResetable  {

    public TouchGesture(String id) 
    {
        this.id = id;
    }
    
    public String getId()
    {
        return id;
    }
    
    public void addEvent(TouchEvent event)
    {
        TouchEventExecution eventExecution = new TouchEventExecution();
        eventExecution.touchEvent = event;
        eventExecution.isExecuted = false;
        eventList.add(eventExecution);
    }
    
    public TouchEvent getEvent(int index)
    {
        return eventList.get(index).touchEvent;
    }
    
    public int size()
    {
        return eventList.size();
    }
    
    public void reset()
    {        
        for(IResetable resetable:resetableList)
        {
            resetable.reset();
        }
        
        if(onResetAction != null)
        {
            onResetAction.executeAction(null, this);
        }
        
        isValid = true;
        index = 0;
        context = new Hashtable<String, Object>();
    }
    
    public void invalidate()
    {
        isValid = false;
    }
    
    public boolean isValid()
    {
        return ((index < eventList.size()) && isValid);
    }
    
    public TouchEvent current()
    {
        return eventList.get(index).touchEvent;
    }
    
    public boolean isCurrentExecuted()
    {
        return eventList.get(index).isExecuted;
    }
    
    public void currentIsExecuted()
    {
        eventList.get(index).isExecuted = true;
    }
    
    public void moveNext()
    {
        index++;
    }
    
    public boolean isCompleted()
    {
        if(!isValid)
            return false;
        
        return (index >= eventList.size());
    }
    
    public void setAllEventsProcessed()
    {
        index = eventList.size();
    }

    private String id;
    private List<TouchEventExecution> eventList = new ArrayList<TouchEventExecution>();    
    private List<IResetable> resetableList = new ArrayList<IResetable>();    
    private boolean isValid = true;
    private int index = 0;
    
    private class TouchEventExecution
    {
        TouchEvent touchEvent;
        boolean isExecuted;
    }
}    

public class TouchEvent {
    public static final int TOUCH_DOWN = 1;
    public static final int TOUCH_MOVE = 2;
    public static final int TOUCH_UP = 3;
    
    public int event;
    public boolean isOptional = false;
    public ArrayList<IfThenClause> conditionList = new ArrayList<IfThenClause>();
}

To build a gesture, we create an instance of the TouchGesture class and give it to the GestureBuilder class whose Create method returns the initiating context of our DSL.

public class GestureBuilder<V> {
    
    public GestureBuilder(V view)
    {
        this.view = view;
    }
    
    public INextGestureAfterCreate Create(TouchGesture gesture)
    {
        return new NextGestureAfterCreate(gesture);
    }

    V view;
}

Now that we have our gesture, we need something to check the incoming gesture events to see if they conform with the defined gesture-sequence. For this, we have the class TouchHandler.

But before we continue, I would like to discuss a little bit more on the general idea behind this "gesture-engine".

Although this post is somewhat theoretical I hope it helps you to get a picture of what went on inside my head when writing this DSL.