G-GUI documentation

G-GUI is a graphical user interface for DOS. It is written as a TSR driver
in real memory which, after being loaded, can be called via interrupt 64h by
any application in any computer language. Currently G-GUI requires 65k of
memory.

G-GUI supports all video modes from standard VGA to true color SVGA. It
offers a desktop, windows, buttons, menus, icons, BMP images, check-boxes,
radio buttons, message boxes, list boxes, scroll bars, progress bars,
edit boxes, multi-line edit boxes, text boxes, different fonts and cursors.

Programming concept

An application using G-GUI has to draw the objects, like windows, buttons,
text, list boxes, etc. on the screen first and save the handles of these
objects returned by G-GUI.

Then it calls gui_input (ah=59) to let G-GUI monitor the mouse movements
and clicks of the user. If the user clicks on an object, gui_input will
return and report the handle of the object clicked. The application then
does the required action depending on the object clicked and calls
gui_input again to wait for the next object the user clicks or terminate.

If there is a window with several objects, the user will usually click on
several objects and finish by clicking on an exit button. In this case the
application has to have a gui_input loop, so it will allow the user to do
the next click after he or she as clicked on one of the objects.
If the application detects a click on the exit button of the window, it will
usually terminate the loop.

If objects which can be clicked overlap, G-GUI will return in that
case the handle of the object which had been drawn last.

How does G-GUI redraw the screen?

G-GUI keeps a record of all commands which opened objects with handles. If
a object needs to be redrawn it will redraw the parent of this object, the
object itself and all the children of this object.
G-GUI will define the parent for each object by checking whether the middle
of this object is within which object. The object within which this middle
is becomes the parent of the object.
Only the parts of the object, which lie within the parent will be redrawn or,
if the object is closed, will be overwritten. So the objects should be
positioned within a parent object.
If an object is positioned on the desktop the entire screen will be redrawn
if this object is closed. This is the case when the Start-Menu is closed. If
the desktop is the parent, all objects are its children and therefore will be
redrawn.
A redraw command on the desktop handle will redraw the screen.

Plans for the next release

G-GUI was written in BASM to achive a small executable file. Currently there are
samples in BASM, Quickbasic and PowerBasic. Further samples in other languages
will be added.
The file g_gui.inc or g_gui.qlb provides wrapper functions to call the G-GUI
commands documented below.

G-GUI often does not check the input received by the application and return an erro
code yet. So if an ASCIIZ file is too long or corrupted, parameters contain values
which make no sense, G-GUI may be caused to crash.

If you design a user interface, G-GUI will work as intended by the developer, but
this may not be what you want to achive. Please use the samples provided as the
starting point for your development. If you start from scratch, you may combine
objects in a way which has not been tested before.

There are some issues left, e.g. sometimes the cursor background is not restored
properly, but any GUI can be improved.

List of supported commands by G-GUI
===================================

G-GUI can be used by any computer language, which can put values into the
registers and call interrupt 64h. The interface is very similar to DOS,
just int 64h is used instead of int 21h.

The input parameters are put into different registers depending on the object
which shall be put on the screen. Then int 64h is called to instruct G-GUI to
display the object.

Remarks:
G-GUI will only run, if it finds the cursor.f16 file in the fonts directory
or the current directory. This contains the cursor images.

'General output guidelines:
ax=error code
bx=handle-nr of object build
cx,dx optional further parameters
es:di = segment:offset of output string - asciiz

The 16 standard colors are:
0=black 1=blue 2=green 3=cyan 4=red 5=magenta 6=brown 7=white
8=grey  9=lt.blue 10=lt.green 11=lt.cyan 12=lt.red 13=lt.magenta
14=yellow 15=bright white
- 11 is transparent background in the writetext function

-----------------------------------
ah=10 - INITIALIZE
Sets the video adapter card into different modes
giving certain pixel widths and heigths as well
as color ranges.
Checks if mouse present.
G-GUI will not work in text mode. This shall be used to reset the
videomode at program end.

Input:
al=1 - do not clear objects
bx=videomode
255= 80x25 text mode (screen 0)
  0= vga  640x480   16 color (screen 12)
  1= vga  320x200  256 color (screen 13)
  2=svga  640x480  256 color
  3=svga  800x600  256 color
  4=svga 1024x768  256 color
  5=svga 1280x1024 256 color
  6=svga 1600x1200 256 color
  7=svga  640x480  16M color
  8=svga  800x600  16M color
  9=svga 1024x768  16M color
 10=svga 1280x1024 16M color
 12=svga  640x480  64k color
 13=svga  800x600  64k color
 14=svga 1024x768  64k color
 15=svga 1280x1024 64k color
 16=svga 1600x1200 64k color
Output:
AL=0 - successful
AL=1 - unsupported mode
AL=2 - no mouse found
AL=3 - cursor.f16 file not found
AH=videomode set
CX=screen width in pixels
DX=screen height in pixels
-----------------------------------
ah=11 - PSET
Plots a dot on the screen in the color given.
Up to 256 colors use the color numbers in the
palette. For 64k or Truecolor specify red,green
blue as 16 or 32 bit value in es:si.
Set es to -1 to use the 16 standard color numbers.

Input:
bx=x-Position
cx=y-Position
es:si = color to write at position
Output:
no output

-----------------------------------
ah=12 - POINT
Reads the color of the pixel at the
given position.
Up to 256 colors the color numbers in the
palette are returned. For 64k or Truecolor
the 16 or 32 bit value specifying red,green
blue is returned.

Input:
bx=x-Position
cx=y-Position
Output:
dx:ax = color at position

-----------------------------------
ah=13 - SET PALETTE
Change the color in the palette entry
of the video adapter.
Works up to 256 colors

Input:
bx = red
cx = green
dx = blue
di = color number to set in the palette
Output:
no output

-----------------------------------
ah=14 - GET PALETTE
Reads the current color set in the
palette of the video adapter.
Works up to 256 colors

Input:
di = color number to read in palette
Output:
bx = red
cx = green
dx = blue

-----------------------------------
ah=15 - LINE
Draws a straight line from the bx,cx
position to the dx,di position.
Set es to -1 to use the 16 standard color numbers.

Input:
bx=x1-Position
cx=y1-Position
dx=x2-Position
di=y2-Position
es:si = 32 bit color number to use for line
Output:
no output

-----------------------------------
ah=16 - BOX
Draws a box or a filled box. In bx,cx
and dx,di the opposite corners of the
box are specified.
Set es to -1 to use the 16 standard color numbers.

Input:
al=0 = frame
al=1 = filled box
al=2 = dotted frame
al=3 = shaded frame
al=4 = shaded box
al=5 = recessed box
add 10 to al to make a box object which will be redrawn
bx=x1-Position
cx=y1-Position
dx=x2-Position
di=y2-Position
es:si = 32 bit color number to use for box
Output:
no output

-----------------------------------
ah=17 - Copy area
Copies the specified rectangle on the screen
to the new area specified by es,si as the
upper left corner of the new area

Input:
bx=x1-Position
cx=y1-Position
dx=x2-Position
di=y2-Position
es=new x1-position
si=new y1-poition
Output:
no output

-----------------------------------
ah=20 - Show window
Draws a window of the given size with
a title bar, a close button and an
optional title text.

Input:
al=0 = standard frame
bx=x1-Position
cx=y1-Position
dx=x2-Position
di=y2-Position
es:si = segment:offset of title asciiz string
bp=parent handle
Output:
AX=0 - successful
AX=1 - error
BX=object handle

-----------------------------------
ah=21 - Show messagebox
Displays a messagebox at the given position
with the specified text.
This box has either one OK button, two buttons
named YES and NO or three buttons named YES, NO
and CANCEL.

Input:
al=0 = just OK button
al=1 = YES / NO button
al=2 = YES / NO / CANCEL button
al=10,11,12 - shaded buttons
bx=x1-Position
cx=y1-Position
dh=color of buttontext
dl=buttoncolor
dx=0 - black on white colors
ds:di = segment:offset of title text asciiz string
es:si = segment:offset of message text asciiz string
bp=parent handle
Output:
AX=0 - successful
AX=1 - error
BX=object handle

-----------------------------------
ah=22 - Show button
Displays a button at the given position
with the specified text.

If this is clicked, the handle of the button is
returned to the application. If AL is set to one,
the parent is closed before this.

Input:
al=0 - return handle only
al=1 - close parent object
al=2 - shaded button
al=3 - recessed button
bx=x1-Position
cx=y1-Position
dh=color of buttontext
dl=buttoncolor
dx=0 - black on white colors
es:si = segment:offset of button text asciiz string
bp=parent handle
Output:
AX=0 - successful
AX=1 - error
BX=object handle

-----------------------------------
ah=23 - Show checkbox
Displays a checkbox at the given position
with the specified text to the right of it.
It can be specified, wether the box is
initially checked or not.

Input:
bx=x1-Position
cx=y1-Position
dx=  0=empty,1=checked
es:si = segment:offset of checkbox text asciiz string
bp=parent handle

Output:
AX=0 - successful
AX=1 - error
BX=object handle

When the checkbox is closed, a 1 will be written at es:si
if the checkbox has been checked.

-----------------------------------
ah=24 - Show radiobutton group
Displays a group of radiobuttons at the given
position. The radio buttons have the texts
in the specified comma delimited list displayed to the right.

A radio button text cannot be longer than 40 characters.
A pointer to a string with the comma delimited list of button
texts to display is given is es:si.

Button number one is initially set.

Input:
al=0 with frame
al=1 without frame
bx=x1-Position
cx=y1-Position
dh=total number of buttons
dl=number of checked button
es:si = segment:offset of list of button texts separated by
commas. Each text entry in this list has a maximum length
of 40 characters.
ds:di = segment:offset of title asciiz string
bp=parent handle

Output:
AX=0 - successful
AX=1 - error
BX=object handle

When the radiobutton group is closed, the number of the selected
button will be written at es:si.

-----------------------------------
ah=25 - Show single line editbox
Shows a text entry field at the given position.
The length of the field is determined by the
maximum characters specified in the dx register.

Input:
al=font number
bx=x1-Position
cx=y1-Position
dx=max characters allowed
di=fontheight(8,14,16)
es:si = segment:offset of initial text asciiz string
bp=parent handle
Output:
AX=0 - successful
AX=1 - error
BX=object handle

-----------------------------------
ah=26 - Show multi line editbox
Shows a multi line text entry field at the given
position. The size of the field determines the
number of characters that can be entered.
The field may be up to 1000 characters
(e.g. 25 lines by 40 columns) and will be
truncated otherwise.
Leaving the editbox with TAB or a click outside it
saves the entered text, ESC leaves without change

Input:
al=1 draws frame around editbox
bx=x1-Position
cx=y1-Position
dx=max characters per line allowed
di=max lines allowed
es:si = segment:offset of initial text asciiz string
bp=parent handle
Output:
AX=0 - successful
AX=1 - error
BX=object handle

-----------------------------------
ah=27 - Show listbox
Displays a horizontal or vertical list box
at the given position. The list of items can
be scrolled through the visible item list in
the list box. The number of visible items is
determined in the dx register.

Combining a horizontal listbox without frame
with vertical listboxes without frame allows
to build a drop down menu system.

A single list box without a frame can be used
as a context menu.

The value for the dh register may be one to
display the list of items in a single line
list box just as in a drop down list which has
not been opened.

A pointer to a string with a comma delimited list
of items to display is given in es:si.
Each item has a maximum length of 40 characters.

If you add the value 16 to the al register, the list
box will be modal, so it expects input or being left by
clicking outside of it to let the program continue.

Input:
al=0 vertical with frame
al=1 vertical without frame
al=2 horizontal without frame
al=3 drop-down listbox
al+16=modal listbox
bx=x1-Position
cx=y1-Position
dh=number of rows displayed in list box concurrently
dl=number of elements in array
di=width of list box in characters
es:si = segment:offset of list of text items separated by
commas. Each text item in this list has a maximum length
of 40 characters.
bp=parent handle
Output:
AX=0 - successful
AX=1 - error
BX=object handle
CX=selected item
DX=1 - list box left due to click outside it/check this to force double click

-----------------------------------
ah=28 - Show textbox
Shows a multi line text field at the given
position. The text can be scrolled in this
field by pressing enter.

Input:
al=0 = standard frame
al=1 = without frame
bx=x1-Position
cx=y1-Position
dx=x2-Position
di=y2-Position
es:si = segment:offset of text asciiz string to display
Output:
AX=0 - successful
AX=1 - error
BX=object handle

-----------------------------------
ah=29 - Show scroll bar
Shows a scroll bar at the position given.

The position given also determines whether
it is a horizontal or vertical scroll bar.
So either x1/x2 or y1/y2 have to have the
same value.

In ES there can be entered a percentage number
which will determine the position of the scroll
box within the scroll bar.

If BX contains a valid handle, the scroll box is
updated according to the value in the ES register.
The size and position of the scroll bar
bar cannot be changed if a handle number greater
than zero is specified. So the size and position have
to be the same as on the initial call.

If AL is set to one, a progress bar is displayed using
the style of the scroll bar. The ES and SI registers
then have the same function as in the show progress bar
function.

Input:
al=0 = scroll bar
al=1 = progress bar
bx=x1-Position
cx=y1-Position
dx=x2-Position
di=y2-Position
es=position of scroll box - no box if zero
si=object handle of existing scroll bar to update position of scroll box
bp=parent handle
Output:
AX=0 - successful
AX=1 - error
BX=object handle
CX=1 - left arrow clicked
CX=2 - right arrow clicked
CX=3 - up arrow clicked
CX=4 - down arrow clicked

-----------------------------------
ah=30 - Show progress bar
Shows a progress bar at the position given.

The position given also determines whether
it is a horizontal or vertical progress bar.

In ES there can be entered a percentage number
which will determine the length of the bar
showing the level of completion.

If BX contains a valid handle, the completion bar is
updated according to the value in the ES register.
The size and position of the progress bar cannot be
changed if a handle number greater than zero is specified.

Input:
bx=x1-Position
cx=y1-Position
dx=x2-Position
di=y2-Position
es=percentage value to determine lenght of completion bar
si=object handle of existing progress bar to update percentage value
bp=parent handle
Output:
AX=0 - successful
AX=1 - error
BX=object handle

-------------------------------------------------------------------
ah=31 - Show group box
draws a box around a group of objects with an optional title
the objects have to be drawn after the box

Input:
bx=x1-Position
cx=y1-Position
dx=x2-Position
di=y2-Position
es:si = segment:offset of title asciiz string
bp=parent handle

Output:
AX=0 - successful
AX=1 - error
BX=object handle

-----------------------------------
ah=40 - Load font
Allows to load one of the enclosed bitmap fonts. In
the bx register the number of this font can be specified.
The application can then select this font by this number.
In the CX register the height of the loaded font has to be
specified, usually 8, 14 or 16 pixels. The length of the font
file has to be entered in the DI register.

If AL is set to one, in the es:si registers there is a pointer
to a string holding the file name of the font file which shall
be loaded from disk. If AL is zero, the font file will be read
from an asciiz string variable within the application programm.
The pointer to this variable is given in the es:si registers.

Input:
bx=font number (0-9)
cx=font height (8/16)
dx=font type (0=bitmap)
es:si=segment:offset of font file
Output:
AX=0 - successful
AX=1 - error

-----------------------------------
ah=41 - Write Text
Writes a text string at the specified position.
If al is set to one, a text object is created.
This can be removed with a ah=50 close object
call.
Otherwise the text will be removed, when the object
on which it is written is redrawn.
If al is set to two, a hyperlink is created. If this
is clicked, the handle of the textobject is returned
to the application.

The DH register is mapped as follows:
in the four high bits a factor can be specified by which
the bitmapped font will be enlarged. If 0 or 1 is entered,
the font will not be enlarged.
In the four low bits the fontheight can be specified for a
ROM font. Allowed values are 7,13 and 15. This is a zero
based height of 8, 14 and 16.
The DL register is mapped as follows:
in the four high bits the space between letters can be
entered. So a 2 will put 2 rows of pixels as a space between.
If the letters of the font touch each other, enter 2 here. You
can also enter 8, which will add a blank character in between.
In the four low bits of the DL part of the DX register the font
number can be specified. A ROM font is selected by font number 0.
If the number is one, the font loaded with function 40 is
used. In this case the font height is taken from the file name:
f08 is 8 bit high, f14 is 14 bit high and f16 is 16 bit high.
An easy way to define the DX register is using a hex number.
So 2F00hex will specify the ROM font with a height of 16 pixel
enlarged by factor 2. Or 0021hex will use the loaded font with
2 Pixel space between the letters.

In the DI register the upper 8 bits specify the background
color of the text while the lower 8 bits specify the foreground
color of the text. If the background color is 11 (transparent),
just the text is printed in the specified foreground color.

Input:
al=0 = write text
al=1 = write text object and return handle
al=2 = write text object and return handle plus return handle if clicked
bx=x1-Position
cx=y1-Position
dl=font number (0-1)
dh=zoom factor/font height
di=text bg/fg color from 16 color palette
es:si = segment:offset of text asciiz string
bp=parent handle
Output:
AX=0 - successful
AX=1 - error
BX=object handle if al=1

-----------------------------------
ah=45 - Show cursor and change cursor style
Displays the cursor at the current mouse position
in the specified style

Input:
dxreg=cursor style
0=arrow
1=hourglass
2=hand
3=move-cross
4=crosshair

Output:
AX=0 - successful
AX=1 - error

-----------------------------------
ah=46 - Hide cursor
Hides the cursor and makes it inactive

Input:
nothing

Output:
AX=0 - successful
AX=1 - error

-----------------------------------
ah=47 - Set cursor
Moves the cursor to the given position

Input:
bx=x1-Position
cx=y1-Position

Output:
AX=0 - successful
AX=1 - error

-----------------------------------
ah=50 - Close object
Most functions return a handle of the
object created by the function. These
objects can be removed with this function
and the screen will be redrawn accordingly.

Input:
di=object-handle
Output:
AX=0 - successful
AX=1 - error

-----------------------------------
ah=51 - Redraw object
Most functions return a handle of the
object created by the function. These
objects can be redrawn with this function.

Input:
di=object-handle
Output:
AX=0 - successful
AX=1 - error

-----------------------------------
ah=52 - Move object
Most functions return a handle of the
object created by the function. These
objects can be moved with this function.
Just the new position of the upper left corner
of the object has to be specified to
move the entire object and its child
objects to the new position

Input:
di=object-handle
bx=new x1-Position
cx=new y1-Position

Output:
AX=0 - successful
AX=1 - error

-----------------------------------
ah=59 - GUI input
This function instructs G-GUI to wait for
a mouse click by the user. If the user clicks
on an object, the function will return with
the handle of the object clicked in BX.

Input:
no input

Output:
AX=0 - successful
AX=1 - error
BX - handle of object clicked
CX - return value depending on object clicked
DX - return value depending on object clicked

-----------------------------------
ah=60 - Show Icon
Displays a 16 color windows icon at the position
specified. The colors have to be the standard 16 color
windows palette. This type of icon file always has a
size of 766 bytes.

The text to be displayed below the Icon can be specified as a
pointer in the ds:dx registers.

Input:
al=0 = draw icon object and return handle
al=1 = draw icon only
bx=x1-Position
cx=y1-Position
es:si=segment:offset of icon file
ds:di=segment:offset of icon text as asciiz string
bp=parent handle
Output:
AX=0 - successful
AX=1 - error
BX=object handle

-----------------------------------
ah=61 - Show BMP file
Displays an uncompressed Windows BMP file at the position
specified. The Windows explorer will display whether it is
compressed under file properties.

Input:
bx=x1-Position
cx=y1-Position
es:si=segment:offset of BMP file
bp=parent handle
Output:
AX=0 - successful
AX=1 - error
BX=object handle

If you use a 16 or 256 color videomode, the displayed image may
change the palette of G-GUI. In this case the windows and other
objects will be displayed in different colors.
A 16 or 256 color image should use the standard windows color
palette. Then several images can be displayed simultaneously.
To make such an image, save any image as a 16 or 256 color bmp
file with MS paint. If you then insert your image from the
clipboard, the colors will be changed to the standard palette.
The image will look different, but this is the way G-GUI will
be able to display it.

-----------------------------------
ah=62 - Draw desktop background
Draws the initial desktop background in a single color, a wall
paper combined from an Icon file or a BMP file. At the bottom
there can be drawn a status line.

If a bmp file name is specified at es:si, this image is used as
wallpaper. If an icon file is specified, this is repeated so this
results in a wallpaper. If es:si point to a NULL character, the
color in dx:di is used.

Input:
al=0 - no status line
al=1 = status line
dx:di - 32 bit color number
es:si=segment:offset of icon/bmp file
Output:
AX=0 - successful
AX=1 - error
BX=object handle