Managing Tags

All graphics on the VBOX Touch have a tag. This tag is how the VBOX Touch manages the program for things such as callbacks.

For example: A basic rectangle has a tag of 0. A CTRL_BUTTON has a tag value that is automatically assigned to it in the low level and can be found using the press event.

def press_cb(press_info):
    # print(press_info)
    print("TAG VALUE: {}".format(press_info[1]))

gui.show([
    [gui.EVT_PRESS, press_cb]
])

The above code snippet demonstrates how you can see the tag value of the item you pressed on the screen.

Note:

The tag value ‘255’ is automatically assigned as the background. Do not overwrite this!!!

Assigning Tags

As mentioned earlier, many graphical objects will not have a tag value by default, however you can set this manually. This could be used if you wanted a button that isn’t a square shape.

To do this you can use the DL_TAG() function. The DL_TAG() function works by setting all drawn values after the function to be equal to the tag specified as the parameter. Because of this you need to reset it back to the background tag after you have assigned all the values you wish to. The background tag is the default and hence is managed differently in the low-level C code.

As an example you may want to create a circle that has a callback that outputs a value:

from micropython import const
PRESS_RELEASE = const(1)
CIRCLE_TAG = const(70) # This will assign a constant micropython object to this variable. This is an optimisation and should also mean it cannot be reassigned.
BACKGROUND_TAG = const(255)

def circle_cb():
    print("CIRCLE HAS BEEN PRESSED!")

def press_cb(press_info):
    press_type = press_info[0]
    tag = press_info[1]
    if press_type == PRESS_RELEASE:
        if tag == CIRCLE_TAG:
            circle_cb()
        elif tag == BACKGROUND_TAG:
            print("BACKGROUND HAS BEEN PRESSED!")

gui.show([
    [gui.EVT_PRESS, press_cb],
    [gui.DL_TAG(CIRCLE_TAG)], # ASSIGNS THE TAG
    [gui.DL_POINT_SIZE(100)], # BIG CIRCLE
    [gui.DL_COLOR_RGB(0,128,0)], # DARK GREEN
    [gui.PRIM_POINTS,
        [gui.DL_VERTEX2F(400,240)]
    ],
    [gui.DL_TAG(BACKGROUND_TAG)], # RESETS THE TAG
])

This code will generate a dark green circle in the centre of the screen that when pressed prints “CIRCLE HAS BEEN PRESSED!”.

Note:

When a tag is manually assigned the low-level code does not recognise it as one it has assigned and so it will print ‘decode_gui_press failed with tag “int here”’. You can ignore this print, it will not cause the program to throw an error.

Adding text to a custom tag

You may have developed the example above further by adding some text to prompt a user about the press. From this you probably ran into the issue that when you press on the area the text is in then it no longer prints anything. This is because the text has a different tag value to that of the circle.

To fix this you need to manually assign the tag value for the text to be the same as that of the circle. Luckily this means just drawing the text before reseting the tag value.

gui.show([
    [gui.EVT_PRESS, press_cb],
    [gui.DL_TAG(CIRCLE_TAG)], # ASSIGNS THE TAG
    [gui.DL_POINT_SIZE(100)], # BIG CIRCLE
    [gui.DL_COLOR_RGB(0,128,0)], # DARK GREEN
    [gui.PRIM_POINTS,
        [gui.DL_VERTEX2F(400,240)]
    ],
    [gui.DL_COLOR_RGB(255,255,255)], # WHITE TEXT
    [gui.CTRL_TEXT, 400, 240, 29, gui.OPT_CENTER, 'PRESS ME'],
    [gui.DL_TAG(BACKGROUND_TAG)], # RESETS THE TAG
])