example.md

We want to merge the Calabash Android and iOS gesture APIs.

Calabash Android has a three options that can be passed to a gesture:

1. x => a percentage; how far away from the top-left corner on the x-axis to perform the gesture
2. y => a percentage; how far away from the top-right corner on the y-axis to perform the gesture
3. offset => {:x, :y} - how many points from the center of the view to perform the gesture

The x and y relative percentage is applied first and then from that point, the offset is calculated.

Calabash iOS has the offset option, but no the x and y option.

We would like to keep the :offset option; it is well understood and common to both APIs.

We want to keep the percentage based option as well and implement it in Calabash iOS. We also think that x and y should be combined in a Hash (to match the existing :offset option).

The problem is that we are struggling with what name to give to this option.

Here are some options we came up with:

1. :gesture_position                                                                                                                                                               
2. :relative_position                                                                                                                                                              
3. :at                                                                                                                                                                             
4. :at_intercept                                                                                                                                                                   
5. :at_position                                                                                                                                                                    

To illustrate the behavior, we included this ASCII representation of a view and dropped some (numbered) touches onto it.

In our example queries, we used ???: as a stand-in for this new option that combines the x and y options.

                                                                                                                                                                                  
                                                                                                                                                                                        
          ├────────────── 400 px ───────────────┤                                                                                                                                 
                                                                                                                                                                                        
     ┬    ╔═════════════════════════════════════╗                                                                                                                                 
     |    ║2                                   3║                                                                                                                                 
     |    ║                  4                  ║                                                                                                                                 
     |    ║                                     ║                                                                                                                                 
  200 px  ║                  1                  ║                                                                                                                                 
     |    ║                                     ║                                                                                                                                 
     |    ║              7     5                ║   6                                                                                                                             
     |    ║                                     ║                                                                                                                                 
     ┴    ╚═════════════════════════════════════╝                                                                                                                                 
                                                                                                                                                                                  
  1. tap("view marked:'email'")                                                                                                                                                   
  2. tap("view marked:'email'", ???:  {x: 0, y: 0})                                                                                                                            
  3. tap("view marked:'email'", ???:  {x: 100, y: 0})                                                                                                                          
  4. tap("* marked:'email'", offset: {y: -40})                                                                                                                                    
  5. tap("* marked:'email'", offset: {x: 20, y: 40})                                                                                                                              
  6. tap("* marked:'email'", ???: {x: 100, y: 75}, offset: {x: 80})                                                                                                            
  7. tap("* marked:'email'", ???: {x: 50, y: 100}, offset: {x: -80, y: -40})