gui
CTRL
Clock
This is the flag used to create a clock, it is to be used in the following way:
[gui.CTRL_CLOCK, x, y, radius, disp_hand, hour_ticks, face_bckgnd, sec_pass]
Input Parameters:
x [int] = x coordinate of the centre
y [int] = y coordinate of the centre
radius [int] = radius in pixels of the clock
disp_hand [bool_int] = 0 - don’t display seconds hand, 1 - display seconds hand
hour_ticks [bool_int] = 0 - don’t display hour ticks, 1 - display hour ticks
face_bckgnd [bool_int] = 0 - don’t display face background, 1 - display face background
sec_pass [int] = the current time past midnight in seconds
Dial
This is the flag used to create a dial, it is to be used in the following way:
[gui.CTRL_DIAL, x, y, radius, val]
Input Parameters:
x [int] = x coordinate of the centre
y [int] = y coordinate of the centre
radius [int] = radius in pixels of the dial
val [list[int]] = the current value of the dial. 0 is at 12 O’Clock
Gauge
This is the flag used to create a gauge, it is to be used in the following way:
[gui.CTRL_GAUGE, x, y, radius, mjr_div, min_div, val, max],
Input Parameters:
x [int] = x coordinate of the centre
y [int] = y coordinate of the centre
radius [int] = radius in pixels of the dial
mjr_div [int] = Amount of major divisions. Can be any value from 0-9.
min_div [int] = Amount of minor divisions between major divisions. Can be any value from 0-9.
val [list[int]] = The current value of the gauge.
max [int] = The value of the point of the final division.
Hot text
This is the flag used to create hot text, it is to be used in the following way:
[gui.CTRL_HOT_TEXT, x, y, font_size, option, text, cb_func]
Input Parameters:
x [int] = x coordinate
y [int] = y coordinate
font [int] = font of the text.
option [int] = option for widget, see Options for more details
text [string] = string that will be displayed as the text widget. Can only use ASCII characters.
cb_func [func] = callback function to be triggered when a press has happened.
Keys
This is the flag used to create keys, it is to be used in the following way:
key_graphic1 = [gui.CTRL_KEYS, x, y, width, height, font, text, cb_func]
Input Parameters:
x [int] = x coordinate of the top left of the keys.
y [int] = y coordinate of the top left of the keys.
width [int] = width of each key.
height [int] = height of each key.
font [int] = font of each key.
text [string] = string in which it reads in each singular char as an individual key including spaces.
cb_func [func] = callback function to be triggered when a press has been released.
Number
This is the flag used to create a number, it is to be used in the following way:
[gui.CTRL_NUMBER, x, y, font_size, option, c_fmt_str, num]
Input Parameters:
x [int] = x coordinate
y [int] = y coordinate
font [int] = font of the text
option [int] = option for widget, see Options for more details
c_fmt_str [string] = format string in the C language format.
num [int] = The value of the num to be displayed
Progress bar
This is the flag used to create a progress bar, it is to be used in the following way:
[gui.CTRL_PROGRESS, x, y, width, height, num, scale]
Input Parameters:
x [int] = x coordinate
y [int] = y coordinate
width [int] = integer for the distance for x to draw to.
height [int] = integer for the distance for y to draw to.
num [int] = The value of the num to be scaled on the bar.
scale [int] = The scale for the bar.
Scrollbar
This is the flag used to create a scrollbar, it is to be used in the following way:
[gui.CTRL_SCROLLBAR, x, y, width, height, size, scale, val]
Input Parameters:
x [int] = x coordinate
y [int] = y coordinate
width [int] = integer for the distance for x to draw to.
height [int] = integer for the distance for y to draw to.
size [list[int]] = The value of the num to be scaled on the bar.
scale [int] = The scale for the bar.
val [list[int]] = The current value of the slider along the bar.
Slider
This is the flag used to create a slider, it is to be used in the following way:
[gui.CTRL_SLIDER, x, y, width, height, scale, val]
Input Parameters:
x [int] = x coordinate
y [int] = y coordinate
width [int] = integer for the distance for x to draw to.
height [int] = integer for the distance for y to draw to.
scale [int] = The scale for the bar.
val [list[int]] = The current value of the slider along the bar.
Text
This is the flag used to create text, it is to be used in the following way:
[gui.CTRL_TEXT, x, y, font_size, option, text]
Input Parameters:
x [int] = x coordinate
y [int] = y coordinate
font [int] = font of the text.
option [int] = option for widget, see Options for more details
text [string] = string that will be displayed as the text widget. Can only use ASCII characters.
Toggle Switch
This is the flag used to create a toggle switch, it is to be used in the following way:
[gui.CTRL_TOGGLE, x, y, width, font, state, display_text, cb_func]
Input Parameters:
x [int] = x coordinate
y [int] = y coordinate
width [int] = integer for the distance for x to draw to.
font [int] = font of the text.
state [bool_int] = 1 - left state, 0 - right state.
display_text[bytestring] = 2 pieces of text separated by xff.
cb_func [func] = callback function to be triggered when a press has been released.
Bitmaps
There is bitmap functionality that you can use on VBOX Touch however it is complicated to get working as you need to format your image correctly. Racelogic recommends that you use some of the frameworks we have created, the best being image.py. For details on using this see Creating an image on your VBOX Touch.
Possible formats
Number |
Name |
Format layout |
Byte Order |
|
Black and White |
||||
1 |
L1 |
Pixel 0 |
Bit 7 |
Byte 0 |
Pixel 1 |
Bit 6 |
|||
… |
||||
Pixel 7 |
Bit 0 |
|||
2 |
L4 |
Pixel 0 |
Bit 7-4 |
Byte 0 |
Pixel 1 |
Bit 3-0 |
|||
3 |
L8 |
Pixel 0 |
Bit 7-0 |
Byte 0 |
Pixel 1 |
Bit 15-8 |
Byte 1 |
||
Pixel 2 |
Bit 23-16 |
Byte 2 |
||
Paletted Formats |
||||
5 |
ARGB2 |
A |
Bit 7-6 |
Byte 0 |
R |
Bit 5-4 |
|||
G |
Bit 3-2 |
|||
B |
Bit 1-0 |
|||
0 |
ARGB1555 |
G |
Bit 9-5 |
Byte 1 Byte 0 |
A |
Bit 15 |
|||
R |
Bit 14-10 |
|||
B |
Bit 4-0 |
|||
6 |
ARGB4 |
A |
Bit 15-12 |
Byte 1 |
R |
Bit 11-8 |
|||
G |
Bit 7-4 |
Byte 0 |
||
B |
Bit 3-0 |
|||
4 |
RGB332 |
R |
Bit 7-5 |
Byte 0 |
G |
Bit 4-2 |
|||
B |
Bit 1-0 |
|||
7 |
RGB565 |
R |
Bit 15-11 |
Byte 1 Byte 0 |
G |
Bit 10-5 |
|||
B |
Bit 4-0 |
|||
8 |
Palette |
A |
Bit 31-24 |
Byte 3 |
R |
Bit 23-16 |
Byte 2 |
||
G |
Bit 15-8 |
Byte 1 |
||
B |
Bit 7-0 |
Byte 0 |
||
There are also 3 more formats that each have a different function:
11 - Bargraph – renders data given as a bar graph.
9 - Text 8X8 – Makes it so each character is in an 8X8 pixel grid format.
10 - TEXTVGA - Makes it so each character is in an 8X16 pixel grid format.
DL_BITMAP
HANDLE
Used to specify the bitmap handle
gui.DL_BITMAP_HANDLE(int)
The int is the bitmap handle value. The initial value is 0 and goes up to 31. However, by default, the bitmap handles 16-31 are used for built-in fonts already and 15 is used as the scratch handle for CMD_GRADIENT, CMD_BUTTONS and CMD_KEYS.
LAYOUT
Used to specify the bitmap memory format and the layout for the current bitmap handle.
gui.DL_BITMAP_LAYOUT(int, int, int)
The int inputs are: format, linestride, height Used to specify the format and layout for the current bitmap handle.
LAYOUT_H
This function is used to increase the 2 most significant bits of the linestride and height from DL_BITMAP_LAYOUT. It is not used very often as the default range of DL_BITMAP_LAYOUT is a linestride of 1024 and a height of 512 which is big enough to be off the screen in both directions
gui.DL_BITMAP_LAYOUT_H(int,int)
SIZE
This function is used to specify how bitmaps of the current handle will be drawn on the screen.
gui.DL_BITMAP_SIZE(bool, bool, bool, int, int)
The bool and int inputs are: filter, wrapx, wrapy, width, height. Bitmap filtering mode in either NEAREST [0] or BILINEAR[1]. Bitmap x wrap mode, BORDER [0] or REPEAT[1]. Bitmap y wrap mode, BORDER [0] or REPEAT[1] Bitmap width in pixels. The range of which is from 0-511 where 0 means 2048 pixels other than 0 pixel Used to specify the format and layout for the current bitmap handle.
SIZE_H
Is used to specify the 2 most significant bits of bitmaps dimension for the current handle.
gui.DL_BITMAP_SIZE_H(int, int)
The bits are used to create a bitmap bigger than 511x511 which isn’t very common as the screen size of the VBOX Touch is 800x480.
SOURCE
Is used to specify the source address of bitmap data in FT81X graphics memory RAM_G.
gui.DL_BITMAP_SOURCE(address)
BITMAP TRANSFORMS
TRANSFORM_A
gui.DL_BITMAP_TRANSFORM_A(int)
The initial value of the int is 256 which will cause no transformation. When the value 128 is given the bitmap’s width looks doubled. The opposite is the case when you up the value to 512 which appears to be half the width of the original bitmap. The program will still run when you enter a negative number into this transform although when done the image is deleted.
TRANSFORM_B
gui.DL_BITMAP_TRANSFORM_B(int)
The initial value of the int is 0 and will cause no transformation. The B transform will slant the bottom side; to the left (when > 0) and to the right (when < 0).
TRANSFORM_C
gui.DL_BITMAP_TRANSFORM_C(int)
Sets the C coefficient (horizontal translation) of the bitmap transform matrix. This is normally left at its default value of 0.
TRANSFORM_D
gui.DL_BITMAP_TRANSFORM_D(int)
The initial value of the int is 0 and will cause no transformation. The D transform will slant the right side; upward (when > 0) and downward (when < 0).
TRANSFORM_E
gui.DL_BITMAP_TRANSFORM_E(int)
The initial value of the int is 256 which will cause no transformation. When the value 128 is given the bitmap’s height looks doubled. The opposite is the case when you up the value to 512 which appears to be half the height of the original bitmap.
TRANSFORM_F
gui.DL_BITMAP_TRANSFORM_F(int)
Sets the F coefficient (vertical translation) of the bitmap transform matrix. This is normally left at its default value of 0.
Shapes
VERTEX2F
Needs to be used with a primitive
[gui.DL_VERTEX2F(x,y)]
Input Parameters:
x [int] = x coordinate
y [int] = y coordinate
VERTEX2II
Needs to be used with a primitive
[gui.DL_VERTEX2II(x,y,handle,cell)]
Input Parameters:
x [int] = x coordinate
y [int] = y coordinate
handle [int] = The bitmap handle
cell [int] = The cell number of the bitmap within the handle, for example, 0x45 in the 31 handle is ‘E’.
Primitives
Bitmaps
Used to create a bitmap
[gui.PRIM_BITMAPS,[gui.DL_VERTEX2II(50, 65,31,0x45)]]
Input Parameters:
1 (or more) gui.DL_VERTEX2II command(s)
Edge strip A
Used to create a fill from above to below.
[gui.PRIM_EDGE_STRIP_A,[gui.DL_VERTEX2F(100,100), gui.DL_VERTEX2F(700,380)]]
Input Parameters:
2 (or more) gui.DL_VERTEX2F commands that create a line/shape.
Edge strip B
Used to create a fill from below to above.
[gui.PRIM_EDGE_STRIP_B,[gui.DL_VERTEX2F(100,100), gui.DL_VERTEX2F(700,380)]]
Input Parameters:
2 (or more) gui.DL_VERTEX2F commands that create a line/shape.
Edge strip L
Used to create a fill from the left to right.
[gui.PRIM_EDGE_STRIP_L,[gui.DL_VERTEX2F(100,100), gui.DL_VERTEX2F(700,380)]]
Input Parameters:
2 (or more) gui.DL_VERTEX2F commands that create a line/shape.
Edge strip R
Used to create a fill from the right to left.
[gui.PRIM_EDGE_STRIP_R,[gui.DL_VERTEX2F(100,100), gui.DL_VERTEX2F(700,380)]]
Input Parameters:
2 (or more) gui.DL_VERTEX2F commands that create a line/shape.
Lines
[gui.PRIM_LINES,[gui.DL_VERTEX2F(100,100), gui.DL_VERTEX2F(700,380)]]
Input Parameters:
1 (or more) pairs of gui.DL_VERTEX2F commands that create individual lines.
Line strip
[gui.PRIM_LINE_STRIP,[gui.DL_VERTEX2F(100,100), gui.DL_VERTEX2F(700,380)]]
Input Parameters:
2 (or more) gui.DL_VERTEX2F commands that will create a continuous line.
Points
Used to create circular points on the screen.
[gui.PRIM_POINTS,[gui.DL_VERTEX2F(400, 240), gui.DL_VERTEX2F(100,100), gui.DL_VERTEX2F(700,380)]]
Input Parameters:
1 (or more) gui.DL_VERTEX2F commands that will create circles at each one.
Point size
Enlarges points
[[gui.DL_POINT_SIZE(size)], [gui.PRIM_POINTS,[gui.DL_VERTEX2F(400,240)]]]
Input Parameters:
size [int] = The diameter in pixels of the circle.
Rectangle
[gui.PRIM_RECTS,[gui.DL_VERTEX2F(100,100), gui.DL_VERTEX2F(700,380)]]
Input Parameters:
1 (or more) pairs of gui.DL_VERTEX2F commands that create rectangles where the top left is the first coordinate and the bottom right is the second coordinate.
Colour
Transparency
To set the transparency of an object use:
DL_COLOR_A(A)
Input Parameters:
A [int] = Alpha value, this is the transparency of the object. Defaults to 255.
This sets all following drawn primitives to have the transparency defined by A. This value ranges from 255 (opaque) to 0 (clear/invisible).
Masking
To mask the colouring of objects use:
DL_COLOR_MASK(R,G,B,A)
Input Parameters:
R [bool_int] = 0 - disable red, 1 - enable red
G [bool_int] = 0 - disable green, 1 - enable green
B [bool_int] = 0 - disable blue, 1 - enable blue
A [bool_int] = 0 - disable alpha, 1 - enable alpha
These bools are used to enable/disable the different colour buffers and the alpha channel buffer with the default state being 1 (enabled) and the other value being 0 (disabled).
Background colour
To set the background colour for the screen use the following:
DL_CLEAR_COLOR_RGB(R,G,B)
Input Parameters:
R [int] = Amount of Red of the objects that follow it. This defaults to 255.
G [int] = Amount of Green of the objects that follow it. This defaults to 255.
B [int] = Amount of Blue of the objects that follow it. This defaults to 255.
The initial values are (0,41,66) which is the light blue that you have on most VBOX Touch apps. To set the background transparency for the screen use the following:
DL_CLEAR_COLOR_A(A)
Input Parameters:
A [int] = Alpha value, this is the transparency of the background.
Note:
You need to set the values above using the function below
To set these values use:
DL_CLEAR(colour, stencil, tag)
Input Parameters:
colour [bool_int] = background colour
stencil [bool_int] = background stencil
tag [bool_int] = background tag value
These bools are used to decide what part of the background is being initialised. The values can be set to either 1, which will set the value, or 0, which will not.
Blending colours
DL_BLEND_FUNC(src=int,dst=int)
Sets how the colours blend based on the following equation: source × src + destination × dst
The following are the available blend factors and their values:
ZERO (0) — the term is not used (multiplied by zero).
ONE (1) — the term is used at full strength (multiplied by one).
SRC_ALPHA (2) — multiply by the source alpha.
DST_ALPHA (3) — multiply by the destination alpha.
ONE_MINUS_SRC_ALPHA (4) — multiply by (1 − source alpha).
ONE_MINUS_DST_ALPHA (5) — multiply by (1 − destination alpha).
Code example:
import gui
gui.show([
[gui.DL_BLEND_FUNC(0,0)], # <-- This decides how the 3 circles blend, currently they will all go black, change the numbers and see what happens.
# Creating 3 circles for you to see how it blends
[gui.DL_BEGIN(gui.PRIM_POINTS)],
[gui.DL_COLOR_A(200)],
[gui.DL_POINT_SIZE(100)],
[gui.DL_COLOR_RGB(255,0,0)],
[gui.DL_VERTEX2F(400,150)],
[gui.DL_COLOR_RGB(0,255,0)],
[gui.DL_VERTEX2F(460,270)],
[gui.DL_COLOR_RGB(0,0,255)],
[gui.DL_VERTEX2F(340,270)],
[gui.DL_END()],
])