TouchControls

The buttons that are used in the Android HUD are only there to give a visual indication of where to press. The actual work of detecting and processing the touch presses is handled by touch regions which have the exact same dimensions and placement as the buttons.

In order to make this work, the buttons are created inside of an iup.cbox(), which requires specific coordinates for each of the controls within it. When creating your cbox, you'll probably want to set it's size to "HUDSize(1,1)". You then use the function gkinterface.CreateTouchRegion() to create the actual element that processes the touch. Alternatively, you can create your touch interface using other methods, and then read the X and Y attributes of the IUP controls that will have regions associated with them.

CreateTouchRegion() has lots of arguments it can receive and one return value. The return value is merely an auto-incremented number value identifying the region. The arguments as described by raybondo in a post below are:

1. X-drag Event = (string) (like +LookX or Turn, same bind commands as for joystick axes)
   
2. Y-drag Event = (string) (like +LookY or Pitch)
3. Press Event = (string) (any bindable command, commonly set to "+LookPress" for turrets to snap back to center when released)
4. Invert X = (boolean)
5. Invert Y = (boolean)
6. MouseLook X = (boolean) (Old mouselook/delta argument. Not sure yet how it corresponds to new mouselook and delta features recently added with 1.8.567)
7. MouseLook Y = (boolean) (Old mouselook/delta argument. Not sure yet how it corresponds to new mouselook and delta features recently added with 1.8.567)
8. Relative = (boolean)
9. Nonlinear = (number) (0-4 Filtered | 256-260 Unfiltered) Linear, Cube Root, Vector Linear, Vector Cube Root, Vector Gamepad
10. Rect Left = (number) (x)
11. Rect Top = (number) (y)
12. Rect Right = (number) (x+w-1)
13. Rect Bottom = (number) (y+h-1)
14. Z-order = (number) (defaults to 0)
15. Sensitivity (number) (defaults to 1)
16. Unknown (boolean) (Most likely related to the new mouselook feature added in 1.8.567)

Invert X/Y, MouseLook x/y, Relative and Nonlinear are all for drag regions like the look region in the lower right of the HUD. Mouselook means to use delta values instead of absolute values. Nonlinear does a x*x*x*0.75 rescaling. Relative means to use the initial touch position as the center-point instead of the center of the touch region.

If you choose to not specify a value for any of arguments 1-3, then you'll need to register the events TOUCH_PRESSED and TOUCH_RELEASED and perform your actions there. Specifying either of arguments 1 or 2 will make the region a drag region, otherwise arguments 4-9 have no effect on the region. Argument 3 can be specified in conjunction with arguments 1 and 2 and will be executed when the touch is released.

Arguments 10 and 11 indicate the location of the upper-left corner of the region. Arguments 12 and 13 indicate the location of the lower-right corner of the region. These values are in pixels with 0,0 being in the upper-left corner of the screen.

Argument 14 allows you to specify the z-order of the region. The default value is 0, but any int32 value can be used here. Positive values put the region towards the bottom of the stack and negative values put the region towards the top of the stack.

              +-----------------------+
              |     z-order = 1       |
         +------------------------+   |
         |     z-order = 0        |---+
    +-------------------------+   |
    |     z-order = -1        |---+
    |                         |
    +-------------------------+

The events TOUCH_PRESSED and TOUCH_RELEASED receive three arguments: the id number associated with the region that was pressed, and a decimal number corresponding to the percent of the region's width (%w) and height (%h) at which the event took place. TOUCH_RELEASED can return values greater-than 1 if the touch was released below or right of the region, and values less-than 0 if the touch was released above or left of the region. If you want to have a region where the effect is not tied to an existing command then this is where you will handle that.

                         %h < 0
             +-----------------------------+
    %w < 0   |       0 < %w||%h < 1        |   %w > 1
             +-----------------------------+
                         %h > 1

If you create a stack of overlapping regions, there are some things to keep in mind.

• Regions in the lowest z-order will be triggered first.
• One touch can trigger only one region.
• Subsequent touches can trigger other regions in the stack.

It is very important that you clean up your touch regions before using ReloadInterface(). They will persist through a reload.

Below I have included some data from DevKit showing the comparison of buttons to regions. Obviously since the buttons are merely visual indicators, you can use any type of control you want, even images that you might include with your plugin or no indicator at all.

vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
iup.stationbutton() Arguments:
1: (table) title="Turbo", font=18, cy=792, cx=0, bgcolor="255 255 255 100 *", active="YES", fgcolor="255 255 255 100 *", size="72x64"
iup.stationbutton() Runtime: 2ms
iup.stationbutton() Returns:
1: (userdata) userdata: 0x14175488
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
gkinterface.CreateTouchRegion() Arguments:
1: (nil) nil
2: (nil) nil
3: (string) "+Turbo"
4: (boolean) false
5: (boolean) false
6: (boolean) false
7: (boolean) false
8: (boolean) false
9: (boolean) false
10: (number) 0
11: (number) 792
12: (number) 71
13: (number) 855
gkinterface.CreateTouchRegion() Runtime: 0ms
gkinterface.CreateTouchRegion() Returns:
1: (number) 25
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
iup.stationbutton() Arguments:
1: (table) title="Activate",font=23,cy=776,cx=480,bgcolor="255 255 255 100 *", active="YES", fgcolor="255 255 255 100 *", size="192x64"
iup.stationbutton() Runtime: 0ms
iup.stationbutton() Returns:
1: (userdata) userdata: 0xee44d68
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
gkinterface.CreateTouchRegion() Arguments:
1: (nil) nil
2: (nil) nil
3: (nil) nil
4: (boolean) false
5: (boolean) false
6: (boolean) false
7: (boolean) false
8: (boolean) false
9: (boolean) false
10: (number) 480
11: (number) 776
12: (number) 671
13: (number) 839
gkinterface.CreateTouchRegion() Runtime: 0ms
gkinterface.CreateTouchRegion() Returns:
1: (number) 33
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^