GUI

Compatible with:
DOS Maximite CMM MM150 MM170 MM+ MMX Picromite ArmiteL4 Armite F4 ArmiteH7 Picomite CMM2

Syntax:
GUI option

Description:

Not all commands are available on all platforms. The MM170 only has limited support.

GUI BITMAP x, y, bits [, width] [, height] [, scale] [, c] [, bc]
Displays the bits in a bitmap on an LCD panel starting at 'x' and 'y' on an attached LCD panel.
'height' and 'width' are the dimensions of the bitmap as displayed on the LCD panel and default to 8x8.
'scale' is optional and defaults to that set by the FONT command. 
'c' is the drawing colour and 'bc' is the background colour. They are optional and default to the current foreground and background colours.
The bitmap can be an integer or a string variable or constant and is drawn using the first byte as the first bits of the top line (bit 7 first, then bit 6, etc) followed by the next byte, etc. 
When the top line has been filled the next line of the displayed bitmap will start with the next bit in the integer or string.

GUI CALIBRATE
GUI CALIBRATE c1,c2,c3,c4,c5
This command is used to calibrate the touch feature on an LCD panel. It will display a series of targets on the screen and wait for each one to be precisely touched.
The second version allows the calibration parameters to be entered directly without having to go through the manual calibration process. 
The parameters 'c1', 'c2', etc can be found by running a normal calibration process then using OPTION LIST which will list the parameters for that LCD panel. 
This is useful when the command is embedded in a program.

GUI RESET LCDPANEL 
Will reinitialise the configured LCD panel. Initialisation is automatically done when the Micromite starts up but in some circumstances it may be necessary to interrupt power to the LCD panel (eg, to save battery power) and this command can then be used to reinitialise the display.

GUI TEST LCDPANEL
GUI TEST TOUCH
Will test the display or touch feature on an LCD panel.
With GUI TEST LCDPANEL an animated display of colour circles will be rapidly drawn on top of each other.
With GUI TEST TOUCH the screen will blank and wait for a touch which will cause a white dot to be placed on the display marking the touch position on the screen.
Any character entered at the console will terminate the test.

The following are for the Micromite Plus and above

GUI AREA #ref, startX, startY, width, height
This will define an invisible area of the screen that is sensitive to touch and will generate touch down and touch up interrupts. It can be used as the basis for creating custom controls which are defined and managed by the program.
'#ref' is the control's reference number. 'startX' and 'startY' are the top left coordinates while 'width' and 'height' set the dimensions.

GUI BCOLOUR colour, #ref1 [, #ref2, #ref3, etc]
This will change the background colour of the specified controls to 'colour' which is an RGB value for the drawing colour.
'#ref' is the control's reference number.

GUI BEEP msec 
This will sound the pizeo buzzer if configured with the OPTION TOUCH command.
'msec' is the number of milliseconds that the buzzer should be driven. A time of 3ms produces a click while 100ms produces a short beep.

GUI BARGAUGE #ref, StartX, StartY, width, height, FColour, BColour, min, max, c1, ta, c2, tb, c3, tc, c4
Define either a horizontal or vertical analogue bar gauge. 
'#ref' is the control's reference number.
'StartX' and 'StartY' are the top left coordinates of the bar while 'width' is the horizontal width and 'height' the vertical height. If the width is less that the height the bar gauge will be drawn vertically with the graph growing from the bottom towards the top. Otherwise it will be drawn horizontally with the graph growing from the left towards the right.
'Fcolour' is the colour used for the gauge while 'Bcolour' is the background colour. 
'min' is the minimum value of the gauge and 'max' is the maximum value (both floating point).
A multi colour gauge can be created using 'c1' to 'c4' for the colours and 'ta' to 'tc' for the thresholds used to determine when the colour will change.
'width', 'height', 'FColour', 'BColour', 'min' and 'max' are optional and will default to the values used in the previous definition of a GUI BARGAUGE.
'c1', 'ta', 'c2', 'tb', 'c3', 'tc' and 'c4' are optional and if not specified the gauge will use less colours. If all are omitted the gauge will be drawn using 'Fcolour'.

GUI BUTTON #ref, caption$, startX, startY, width, height [, FColour] [,BColour]
This will draw a momentary button which is a square switch with the caption on its face.
When touched the visual image of the button will appear to be depressed and the control's value will be 1. When the touch is removed the value will revert to zero.
#ref' is the control's reference (a number from 1 to 100).
'caption$' is the string to display on the face of the button. It can be a single string with two captions separated by a | character (eg, "UP|DOWN"). When the button is up the first string will be used and when pressed the second will be used.
'startX' and 'startY' are the top left coordinates while 'width' and 'height' set the dimensions. ' FColour and 'BColour' are RGB values for the foreground and background colours.
'width', 'height', FColour and 'BColour' are optional and default to that used in previous controls or set with the COLOUR command.

GUI CAPTION #ref, text$, startX, startY [,align$] [, FColour] [, BColour]
This will draw a text string on the screen.
'#ref' is the control's reference number.
'text$' is the string to display. 'startX' and 'startY' are the top left coordinates.
'align$' is zero to three characters (a string expression or variable is also allowed) where the first letter is the horizontal alignment around X and can be L, C or R for LEFT, CENTER, RIGHT and the second letter is the vertical alignment around Y and can be T, M or B for TOP, MIDDLE, BOTTOM. 
A third character can be used in the string to indicate the rotation of the text. This can be 'N' for normal orientation, 'V' for vertical text with each character under the previous running from top to bottom, 'I' the text will be inverted (ie, upside down), 'U' the text will be rotated counter clockwise by 90º and 'D' the text will be rotated clockwise by 90º. 
The default alignment is left/top with no rotation.
'FColour and 'BColour' are RGB values for the foreground and background colours. On a display that supports transparent text BColour can be -1 which means that the background will show through the gaps in the characters.
FColour and 'BColour' are optional and default to the colours set by the COLOUR command.

GUI CHECKBOX #ref, caption$, startX, startY [, size] [, colour]
This will draw a check box which is a small box with a caption. When touched an X will be drawn inside the box to indicate that this option has been selected and the control's value will be set to 1. When touched a second time the check mark will be removed and the control's value will be zero.
'#ref' is the control's reference number.
The string 'caption$' will be drawn to the right of the control using the colours set by the COLOUR command.
'startX' and 'startY' are the top left coordinates while 'size' set the height and width (the bix is square). 'colour' is an RGB value for the drawing colour. 'size' and 'colour' are optional and default to that used in previous controls.

GUI DELETE #ref1 [,#ref2, #ref3, etc]
GUI DELETE ALL
This will delete the controls in the list. This includes removing the image of the control from the screen using the current background colour and freeing the memory used by the control.
'#ref' is the control's reference number. The keyword ALL can be used as the argument and that will disable all controls.

GUI DISABLE #ref1 [,#ref2, #ref3, etc]
GUI DISABLE ALL
This will disable the controls in the list. Disabled controls do not respond to touch and will be displayed dimmed.
'#ref' is the control's reference number. The keyword ALL can be used as the argument and that will disable all controls.
GUI ENABLE can be used to restore the controls.

GUI DISPLAYBOX #ref, startX, startY, width, height, FColour, BColour
This will draw a box with rounded corners that can be used to display a string '#ref' is the control's reference number.
'startX' and 'startY' are the top left coordinates while 'width' and 'height' set the dimensions. 
' FColour and 'BColour' are RGB values for the foreground and background colours. 
'width', 'height', FColour and 'BColour' are optional and default to that used in previous controls.
Any text can be displayed in the box by using the CtrlVal(r) = command. This is useful for displaying text, numbers and messages. This control does not respond to touch.

GUI ENABLE #ref1 [,#ref2, #ref3, etc]
GUI ENABLE ALL
This will undo the effects of GUI DISABLE and restore the control(s) to normal operation.
'#ref' is the control's reference number. The keyword ALL can be used as the argument and that will disable all controls.

GUI FCOLOUR colour, #ref1 [, #ref2, #ref3, etc]
This will change the foreground colour of the specified controls to 'colour' which is an RGB value for the drawing colour.
'#ref' is the control's reference number.

GUI FRAME #ref, caption$, startX, startY, width, height, colour
This will draw a frame which is a box with round corners and a caption.
'#ref' is the control's reference number.
'caption$' is a string to display as the caption. 
'startX' and 'startY' are the top left coordinates while 'width' and 'height' set the dimensions. 
'colour' is an RGB value for the drawing colour. 
'width', 'height' and 'colour' are optional and default to that used in previous controls.
A frame is useful when a group of controls need to be visually brought together.
It is also used to surround a group of radio buttons and MMBasic will arrange for the radio buttons surrounded by the frame to be exclusive. ie, when one radio button is selected any other button that was selected and within the frame will be automatically deselected.
A frame does not respond to touch.

GUI FORMATBOX #ref, Format, startX, startY, width, height, FColour, BColour
This will draw a box with rounded corners that can be used to create a virtual keypad for entry of data using a specific format.
'#ref' is the control's reference number.
'startX' and 'startY' are the top left coordinates while 'width' and 'height' set the dimensions. 
' FColour and 'BColour' are RGB values for the foreground and background colours. 
'width', 'height', FColour and 'BColour' are optional and default to that used in previous controls.
The 'Format' argument specifies the format of the entry as follows:
DATE1 Date in UK/Aust/NZ format (dd/mm/yy)
DATE2 Date in USA format (mm/dd/yy)
DATE3 Date in international format (yyyy/mm/dd)
TIME1 Time in 24 hour notation (hh:mm)
TIME2 Time in 24 hour notation with seconds (hh:mm:ss)
TIME3 Time in 12 hour notation (hh:mm AM/PM)
TIME4 Time in 12 hour notation with seconds (hh:mm:ss AM/PM)
DATETIME1 Date (UK fmt) and time (12 hour) (dd/mm/yy hh:mm AM/PM)
DATETIME2 Date (UK fmt) and time (24 hour) (dd/mm/yy hh:mm)
DATETIME3 Date (USA fmt) and time (12 hour) (mm/dd/yy hh:mm AM/PM)
DATETIME4 Date (USA fmt) and time (24 hour) (mm/dd/yy hh:mm)
LAT1 Latitude in degrees, minutes and seconds (dd° mm' ss" N/S)
LAT2 Latitude with seconds to one decimal place (dd° mm' ss.s" N/S)
LONG1 Longitude in degrees, minutes and seconds (ddd° mm' ss" E/W)
LONG2 Longitude seconds to one decimal place (ddd° mm' ss.s" E/W)
ANGLE1 Angle in degrees and minutes (ddd° mm')
For example, this command:
GUI FORMATBOX #1, LAT1, 50, 50, 300, 50
would create a format box which would accept the entry of latitude in the format of dd° mm' ss" N/S. 
The value of CtrlVal(#1) would be a string which includes the numbers and separating characters. For example an entry of 17 degrees, 32 minutes and 1 second south would result in the string 17° 32' 01" S
MMBasic will try to position the virtual keypad on the screen so as to not obscure the format box that caused it to appear. A pen down interrupt will be generated just before the keypad is deployed and a key up interrupt will be generated when the entry is complete and the keypad is hidden.

GUI FORMATBOX CANCEL
This will dismiss a virtual keypad if it is displayed on the screen. It is the same as if the user touched the cancel key except that the touch up interrupt is not generated. If a keypad is not displayed this command will do nothing.

GUI GAUGE #ref, StartX, StartY, Radius, FColour, BColour, min, max, nbrdec, units$, c1, ta, c2, tb, c3, tc, c4
Define a graphical circular analogue gauge with a digital display in the centre.
'#ref' is the control's reference number.
'StartX' and 'StartY' are the coordinates of the centre of the gauge, 
'Radius' is the distance from the centre to the outer edge.
'min' is the minimum value of the gauge and 'max' is the maximum value (both floating point).
'nbrdec' specifies the number of decimal places to be used when drawing the digital value in the centre of the gauge. Under this 'units$' will be displayed.
'Fcolour' is the colour used for the gauge while 'Bcolour' is the background colour. A multi colour gauge can be created using 'c1' to 'c4' for the colours and
'ta' to 'tc' for the thresholds used to determine when the colour will change. When colours and thresholds are specified the background of the gauge will be drawn with a dull version of the colour at that level. Also the digital value will change to the colour specified by the current value.
'Radius', 'FColour', 'BColour', 'min', 'max', 'nbrdec' and 'units$' are optional and will default to the values used in the previous definition of a GUI GAUGE.
'c1', 'ta', 'c2', 'tb', 'c3', 'tc' and 'c4' are optional and if not specified the gauge will use less colours. If all are omitted the gauge will be drawn using 'Fcolour'.
The section Advanced Graphics has a more detailed description.

GUI HIDE #ref1 [,#ref2, #ref3, etc]
GUI HIDE ALL
This will hide the controls in the list. Hidden controls do not respond to touch and will not be visible.
'#ref' is the control's reference number. The keyword ALL can be used as the argument and that will hide all controls.
GUI SHOW can be used to restore the controls.

GUI INTERRUPT down [, up]
This command will setup an interrupt that will be triggered on a touch on the LCD panel and optionally if the touch is released.
'down' is the subroutine to call when a touch down has been detected. 
'up' is the subroutine to call when the touch has been lifted from the screen ('up' and 'down' can point to the same subroutine if required).
Specifying the number zero (single digit) as the argument will cancel both of these interrupts. ie:
GUI INTERRUPT 0

GUI LED #ref, caption$, centerX, centerY, radius, colour
This will draw an indicator light which looks like a panel mounted LED. A LED does not respond to touch.
'#ref' is the control's reference number.
The string 'caption$' will be drawn to the right of the control using the colours set by the COLOUR command.
'centerX' and 'centerY' are the coordinates of the centre of the LED and 'radius' is the radius of the LED. 'colour' is an RGB value for the drawing colour.
'radius' and 'colour' are optional and default to that used in previous controls.
When a LED's value is set to a value of one it will be illuminated and when it is set to zero it will be off (a dull version of its colour attribute). 
The LED can be made to flash on then off by setting the value of the LED to a number greater than one which is the time in milliseconds that it should remain on.
The colour can be changed with the GUI FCOLOUR command.

GUI NUMBERBOX #ref, startX, startY, width, height, FColour, BColour
This will draw a box with rounded corners that can be used to create a virtual numeric keypad for data entry.
'#ref' is the control's reference number.
'startX' and 'startY' are the top left coordinates while 'width' and 'height' set the dimensions. 
' FColour and 'BColour' are RGB values for the foreground and background colours. 'width', 'height', FColour and 'BColour' are optional and default to that used in previous controls.
When the box is touched a numeric keypad will appear on the screen. Using this virtual keypad any number can be entered into the box including a floating point number in exponential format. The new number will replace the number previously in the box.
The value of the control can set to a literal string (not an expression) starting with two hash characters. For example:
CtrlVal(nnn) = "##Enter Number"
and in that case the string (without the leading two hash characters) will be displayed in the box with reduced brightness. This can be used to give the user a hint as to what should be entered (called "ghost text"). Reading the value of the control displaying ghost text will return zero. When the control is used normally the ghost text will vanish.
MMBasic will try to position the virtual keypad on the screen so as to not obscure the number box that caused it to appear. A pen down interrupt will be generated just before the keypad is deployed and a key up interrupt will be generated when the Enter key is touched and the keypad is hidden. Also, when the Enter key is touched the entered number will be evaluated as a number and the NUMBERBOX control redrawn to display this number.

GUI NUMBERBOX CANCEL
This will dismiss a virtual keypad if it is displayed on the screen. It is the same as if the user touched the cancel key except that the touch up interrupt is not generated. If a keypad is not displayed this command will do nothing.

GUI RADIO #ref, caption$, centerX, centerY, radius, colour
This will draw a radio button with a caption.
'#ref' is the control's reference number.
The string 'caption$' will be drawn to the right of the control using the colours set by the COLOUR command.
'centerX' and 'centerY' are the coordinates of the centre of the button and 'radius' is the radius of the button. 'colour' is an RGB value for the drawing colour. 'radius' and 'colour' are optional and default to that used in previous controls.
When touched the centre of the button will be illuminated to indicate that this option has been selected and the control's value will be 1. When another radio button is selected the mark on this button will be removed and its value will be zero. Radio buttons are grouped together when surrounded by a frame and when one button in the group is selected all others in the group will be deselected. If a frame is not used all buttons on the screen will be grouped together.

GUI REDRAW #ref1 [,#ref2, #ref3, etc]
GUI REDRAW ALL
This will redraw the controls on the screen. It is useful if the screen image has somehow been corrupted.
'#ref' is the control's reference number. The keyword ALL can be used as the argument and that will first clear the screen then redraw all controls. This is useful if the whole screen needs to be refreshed.

GUI SETUP #n 
This will allocate any new controls created to the page '#n'.
This command can be used as many times as needed while GUI controls are being defined. The default when a program starts running is GUI SETUP 1.
See also the GUI PAGE command.

GUI SHOW #ref1 [,#ref2, #ref3, etc]
GUI SHOW ALL
This will undo the effects of GUI HIDE and restore the control(s) to being visible and capable of normal operation.
'#ref' is the control's reference number. The keyword ALL can be used as the argument and that will disable all controls.

GUI SPINBOX #ref, startX, startY, width, height, FColour, BColour, Step, Minimum, Maximum
This will draw a box with up/down icons on either end. When these icons are touched the number in the box will be incremented or decremented. Holding down the up/down icons will repeat the step at a fast rate.
'#ref' is the control's reference number.
'startX' and 'startY' are the top left coordinates while 'width' and 'height' set the dimensions. ' FColour and 'BColour' are RGB values for the foreground and background colours.
'width', 'height', FColour and 'BColour' are optional and default to that used in previous controls.
'Step' sets the amount to increment/decrement the number with each touch. 'Minimum' and 'Maximum' set limits on the number that can be entered. All three parameters can be floating point numbers and are optional. The default for 'Step' is 1 and 'Minimum' and 'Maximum' if omitted will default to no limit.

GUI SWITCH #ref, caption$, startX, startY, width, height, FColour, BColour
This will draw a latching switch which is a square switch that latches when touched.
'#ref' is the control's reference number.
'caption$' is a string to display as the caption on the face of the switch. 
'startX' and 'startY' are the top left coordinates while 'width' and 'height' set the dimensions. 
' FColour and 'BColour' are RGB values for the foreground and background colours. 
'width', 'height', FColour and 'BColour' are optional and default to that used in previous controls.
When touched the visual image of the button will appear to be depressed and the control's value will be 1. When touched a second time the switch will be released and the value will revert to zero. Caption can consist of two captions separated by a | character (eg, "ON|OFF"). 
When this is used the switch will appear to be a toggle switch with each half of the caption used to label each half of the toggle switch.

GUI TEXTBOX #ref, startX, startY, width, height, FColour, BColour
This will draw a box with rounded corners that can be used to create a virtual keyboard for data entry
'#ref' is the control's reference number.
'startX' and 'startY' are the top left coordinates while 'width' and 'height' set the dimensions. 
' FColour and 'BColour' are RGB values for the foreground and background colours. 'width', 'height', FColour and 'BColour' are optional and default to that used in previous controls. On a display that supports transparent text BColour can be -1 which means that the background will show through the gaps in the characters.
When the box is touched a QWERTY keyboard will appear on the screen. Using this virtual keyboard any text can be entered into the box including upper/lower case letters, numbers and any other characters in the ASCII character set. The new text will replace any text previously in the box. 
The value of the control can set to a string starting with two hash characters.
For example:
CtrlVal(nnn) = "##Enter Filename"
and in that case the string (without the leading two hash characters) will be displayed in the box with reduced brightness. This can be used to give the user a hint as to what should be entered (called "ghost text"). Reading the value of the control displaying ghost text will return an empty string. When the control is used normally the ghost text will vanish.
MMBasic will try to position the virtual keyboard on the screen so as to not obscure the text box that caused it to appear. A pen down interrupt will be generated just before the keyboard is deployed and a key up interrupt will be generated when the Enter key is touched and the keyboard is hidden.

GUI TEXTBOX CANCEL 
This will dismiss a virtual keyboard if it is displayed on the screen. It is the same as if the user touched the cancel key except that the touch up interrupt is not generated. 
If a keyboard is not displayed this command will do nothing.

Last edited: 09 June, 2021