___________ ___ ___
__________
/
________/ / / / /
/___ ___/
/
/ / / / /
/ / GUI
/
/ / / / /
/ / The ultimate graphic library
/
/ _____ /
/ / / / /
Version 0.1
/
/ /_ / / /
/ / / / By Geoff Lywood aka KrYpT
/
/____/ / /
/___/ / ____/
/___
<glywood@yahoo.com>
/__________/ /_________/
/__________/
If the below information is not enough to satisfy, please don't hesitate to contact me.
A quick note on color-coding: blue = I/O, gray = functions, yellow = code, green = flags, purple = comments.
The GUI library is roughly divided into two sections:
We'll basically be following the include file through the documentation, go ahead and read it too.
First of all, the most important thing to know is that routines are not accessed in any normal way. In order to run a GUI routine, you do not call it, you do not bcall it, you “gcall” it. This is a special macro designed to work like bcall, but works especially for GUI. Example:
gcall(guiDrawForm)
The next thing you need to know is how to initialize the library. To do this you need the file called LoadGUI.asm. Simply include this file somewhere in your code, and before you use any GUI routines make a (direct) call to guiInit. It will look up the appvar and call the code inside the appvar. The appvar then reads what page GUI is on, makes sure that it really is GUI, then calls guiInitialize. This will load up the gcall script into a safe ram area in the middle of ramcode, and return control back to you, with the flash page reset to what it was before the whole process began. If you wish to specify a minimum version (which is pointless at this time) you may do so (see the LoadGUI file). Should the routine fail to detect GUI or fail the version test, the carry flag will be set upon return. It is the responsibility of the calling program to make sure that the user is notified of what is wrong (okay, so if the program quits upon entry, that's good enough, as long as it's in the docs). In summary:
call guiInit
ret c
...
#include "LoadGUI.asm"
Now to dive right into the real routines.
Misc. + Window Routines:
Form Objects:
This routine is used by guiInit; you need not worry yourself with it.
Gets the version of the application.
Inputs: None
Outputs: A = Version number
Destroyed: None
Displays multiple lines of text, left aligned. Uses vputs.
Inputs: hl -> MultiLineText Structure (see below)
de = Penrow/Pencol to start display at.
Set whatever text flags you want before this routine.
Outputs: hl -> Byte after structure
Destroys: AF,BC,DE,IX
MultiLineText Structure:
.db num_lines
.db "Line 1",0
.db "Line 2",0
...
Displays multiple lines of text, center aligned. Uses vputs.
Inputs: hl -> MultiLineText Structure (see above)
d = Penrow to start at
e = Pencol to center around
Outputs: hl -> Byte after structure
Destroys: AF,BC,DE,IX
Displays a line of text centered on the current pencol/penrow coordinates.
Inputs: hl -> Zero-terminated string
Outputs: hl -> Byte after string
Destroys: AF,BC,DE,IX
Moves hl to the byte after the terminating zero of the current string it points to.
Inputs: hl -> Zero-terminated string
Outputs: hl -> Byte after string
Destroys: None
A non-interactive notification window.
Inputs: hl -> MessageBox Structure
Outputs: hl -> Byte after MessageBox structure
MessageBox Structure:
.db "Title",0 ; The title (inverse text)
.db num_lines ; The number of lines of text to be displayed (not including the title)
.db "Line 1",0 ; The text to display
.db "Line 2",0 ; ...
.db "Line 3",0 ; ...
.db "Line 4",0 ; ...
Comments:
Num_lines can be zero.
No matter what num_lines is, the rectangle will be 4 lines high, and about 12 capital letters wide.
Everything is displayed using the small font.
This routine resets textwrite automatically.
The title is centered, and the text is left aligned.
Nothing is saved to the graph buffer.
A semi-interactive notification window with extra options.
Inputs: hl -> MessageBoxEX Structure
Outputs: hl -> Byte after MessageBoxEX structure, or hl -> animateroutine if it exists
a = keycode if MB_Waitkey was used.
MessageBoxEX Structure:
.db flags ; see below
.db height,width,titleheight ; height of entire box, width of entire box, height of dark region
.db num_titles ; number of lines of text in the title
.db "Title Line 1",0 ; the actual lines of text for the title
.db "Title Line 2",0 ; ...
.db num_lines ; number of lines of text in the box (not including title)
.db "Line 1",0 ; the actual lines of text
.db "Line 2",0 ; ...
.db "Line 3",0 ; ...
.db "Line 4",0 ; ...
[.db delaytime] ; the length of the delay (if used)
[.dw animateroutine] ; a pointer to a routine in ram to be called during delay/waitkey
flags: SET (nz) RESET (z)
Bit 0: MB_Buffer Display to buffer and screen Display to screen (not buffer)
Bit 1: MB_CenterTitle Center title Left align title
Bit 2: MB_CenterText Center text Left align text
Bit 3: MB_BigTitle Title in large font Title in small font
Bit 4: MB_BigText Text in large font Text in small font
Bit 5: MB_Delay Execute delaytime halts Just return without a delay
Bit 6: MB_Waitkey Wait until 2nd or Enter pressed Just return without keypress
Bit 7: MB_Animate Run a callback during delay/waitkey No callback
Comments:
The box will be centered on the screen.
If both delay and waitkey are used, the delay will come first.
The callback will be run repeatedly with one halt and a couple of lines of code in between calls.
Do not use any MirageOS calls during the callback routine. The flash page is NOT reset.
Delaytime and animateroutine should be there ONLY if their respective flags are set. If you are using
an animation routine but no delay, do not include a dummy value for delaytime.
If MB_Buffer is set, a grbufcpy will be executed.
The standard MessageBox has values 2,33,52,7,1 for the first 5 bytes.
A window that prompts to choose one of several choices.
Inputs: hl -> OptionBox structure
Outputs: a = Index of chosen option
e = Index of chosen option
OptionBox Structure:
.db "Title",0 ; Title
.db num_lines ; Number of text lines
.db "Text line 1",0 ; Text lines
.db "Text line 2",0 ; ...
.db "Text line 3",0 ; ...
.db num_choices ; Number of choices
.db "Choice 0",0 ; Choices
.db "Choice 1",0 ; ...
.db "Choice 2",0 ; ...
Comments:
Output value is zero for the leftmost choice, and incremented to the right.
This window is vertically two pixels (one up, one down) larger than a MessageBox.
Title text is centered, the rest is left aligned.
Each option has one space between it and the next.
You may have zero lines of text, but you are not allowed to have zero options.
A window that prompts for one of several choices, with extra options.
Inputs: hl -> OptionBoxEX structure
Outputs: a = Option chosen
OptionBoxEX structure:
.db flags ; see below
.db height,width,titleheight ; height of entire box, width of entire box, height of dark region
.db num_choices ; number of choices
.db defaultchoice ; choice highlighted at the beginning (0=first)
.db rowlength ; Amount to move if up/down is pressed
.db num_titles ; number of lines of text in the title
.db "Title Line 1",0 ; the actual lines of text for the title
.db "Title Line 2",0 ; ...
.db num_lines ; number of lines of text in the box (not including title)
.db "Line 1",0 ; the actual lines of text
.db "Line 2",0 ; ...
.db "Line 3",0 ; ...
.db "Line 4",0 ; ...
.db c1Index ; Return value if this choice is picked
.db c1col,c1row ; pencol/penrow to display choice at
.db "Choice One",0 ; Text for the choice
.db c2Index,c2col,c2row ; ...
.db "Choice Two",0 ; ...
.db c3Index,c3col,c3row ; ...
.db "Choice Three",0 ; ...
[.dw callback] ; Custom text routine
Flags: SET (nz) RESET (z)
Bit 0: OB_Buffer Copy to screen + buffer Copy to screen only
Bit 1: OB_CenterTitle Center title horizontally Left align title in box
Bit 2: OB_CenterText Center text horizontally Left align text in box
Bit 3: OB_CustomText Custom callback routine exists No custom callback routine
Bit 4: OB_BigTitle Display title in large font Display title in small font
Bit 5: OB_BigText Display text in large font Display text in small font
Bit 6: OB_BigChoices Display choices in large font Display choices in small font
Bit 7: OB_UpDownOnly See below Normal cursor operation
Comments:
The box will be centered on the screen.
Rowlength should be zero unless the options are arranged in a gridlike pattern.
If OB_UpDownOnly is set, pressing left or right will do nothing, and pressing
up or down will move one choice backward or forward, regardless of rowlength.
TextEraseBelow is set, so don't put the choices too close together.
The customtext callback is called after the choices are redrawn. This occurs
every time the user changes highlighted selections. The current selection is
stored in register "e". You can use this for such things as popup
explanations of the choices. The flash page is not reset, so you cannot use
MirageOS calls during any callbacks (and you don't need the macro for gcalls)
You do not need to preserve any registers in the callback.
A window that prompts for a string.
Inputs: hl -> InputBox structure
InputBox Structure:
.db "Title",0 ; Title
.db num_lines ; Number of text lines
.db "Text line 1",0 ; The text itself
.db "Text line 2",0 ; ...
.db "Text line 3",0 ; ...
.dw wheretostore ; Pointer to ram area for string
A window that prompts for a string with extra options.
Inputs: hl -> InputBoxEX structure
InputBoxEX Structure:
.db flags ; See below
.db height,width,titleheight ; See MessageBoxEX
.db num_titles ; Ditto
.db "Title 1",0
.db "Title 2",0
.db num_lines ; Ditto
.db "Line 1",0
.db "Line 2",0
.db "Line 3",0
[.dw callback] ; Custom text routine pointer
.db inputflags ; See StringInput
.db maxchars
.db col,row
.dw wheretostore
Flags: SET (nz) RESET (z)
Bit 0: IB_Buffer Draw to screen + buffer Draw to screen only
Bit 1: IB_CenterTitle Center title Left align title
Bit 2: IB_CenterText Center text Left align text
Bit 3: IB_BigTitle Use large font for title Use small font for title
Bit 4: IB_BigText Use large font for text use small font for text
Bit 5: IB_CustomText Run a callback after drawing No callback
Comments:
This is just a simplified messagebox and a stringinput. See the respective documentation
for better explanations. Remember to use only IB (and SI) prefixed flags though.
Regardless of the buffer setting, the typed in text will only be displayed to the screen.
Standard values for inputflags, maxchars, col, and row are 0,12,24,39 respectively.
The flash page is not reset during the callback. It is called after the inputbox is drawn,
and before text is inputted.
Inputs a string to (hl).
Inputs: hl -> Location to store the string to
de = penrow/pencol to start display at
b = maximum number of characters
c = inputflags (see below)
Runs guiStringInput, but uses a structure instead of register inputs.
Inputs: hl -> StringInput structure
StringInput Structure:
.db inputflags
.db maxchars
.db col,row
.dw wheretostore
inputflags: SET (nz) RESET (z)
Bit 0: SI_BigFont Use the large font Use the small font
Bit 1: SI_NoCursor Do not display cursor Display cursor
Bit 2: SI_NoDisp Do not display typed in text Display text
Bit 3: SI_NumbersDef Numbers are input by default Letters are input by default
Bit 4: SI_NoAlpha Alpha does nothing Alpha switches between letters/numbers
Bit 5: SI_NoClearDel Clear/delete do nothing Clear/Delete work normally
Bit 6: SI_NullAllowed Allow zero-length strings Do not allow zero-length strings
Bit 7: SI_UseDefault Default string is at (hl) No default string
Comments:
You may set textinverse or texterasebelow before running this routine if you wish.
A box with a centered title.
Inputs: hl -> Window structure
Window Structure:
.db top ; Top pixel row
.db left ; Left pixel column
.db bottom ; Bottom pixel row
.db right ; Right pixel column
.db "Title",0 ; Title
Comments:
Writes to buffer and screen.
A box with a title, and extra options.
Inputs: hl -> WindowEX structure
WindowEX Structure:
.db flags
.db top
.db left
.db bottom
.db right
.db titleheight
.db num_titles
.db "Title 1",0
.db "Title 2",0
Flags: SET (nz) RESET (z)
Bit 0: WI_Buffer Write to buffer + screen Screen only
Bit 1: WI_CenterTitle Center title Left align title
Bit 2: WI_BigTitle Title is in large font Title is in small font
Title and list of choices.
Inputs: hl -> Menu structure
Outputs: a = Chosen option, first = 0, second = 1, etc
Menu Structure:
.db "Title",0
.db num_choices
.db "Choice 0",0
.db "Choice 1",0
.db "Choice 2",0
.db "Choice 3",0
Comments:
You may have no more than nine choices. There is no scrolling.
The routine clears the screen before executing.
The buffer is unchanged by this routine.
Title and list of choices, with options.
Inputs: hl -> MenuEX structure
Outputs: a = chosen option's value
MenuEX Structure:
.db flags ; See below
.db titleheight ; Height of the title bar
.db num_titles ; Number of lines in the title
.db "Title 1",0 ; First line of the title
.db "Title 2",0 ; Second line of the title
.db defaultchoice ; Choice that is highlighted by default
.db num_choices ; Total number of choices
.db Choice1Val ; Return value of the first choice
.db "Choice 1",0 ; The first choice text
.db Choice2Val ; The return value of the second choice
.db "Choice 2",0 ; The second choice text
.db Choice3Val ; ...
.db "Choice 3",0 ; ...
[.dw textroutine] ; Optional callback text routine
Flags: SET (nz) RESET (z)
Bit 0: ME_Buffer Copied to screen and buffer Just Displayed to screen
Bit 1: ME_CenterTitle Title is centered Title is left aligned
Bit 2: ME_BigTitle Title is in large font Title is in small font
Bit 3: ME_BigText Text is in large font Text is in small font
Bit 4: ME_CustomText A callback routine exists No callback
Bit 5: ME_ClearQuit Clear returns a value of -1 Clear does nothing
Comments:
There is no scrolling. Do not use more items than will fit on the screen.
The custom text routine is called after every time the choices are redrawn. The current
selection is in register "e". You do not need to preserve any registers or flags, but
text flags are not generally in a normal state when this call is made.
A collection of objects.
Input for all functions: hl -> Form Structure
Functions:
1. guiDrawForm Either draws all objects in the collection or clears screen, based on FO_Showing.
2. guiShowForm Sets FO_Showing, then calls
guiDrawForm
3. guiHideForm Resets FO_Showing, then calls guiDrawForm
4. guiHandleClick Handles a mouse click on the form. Must also input de = mouse cords.
Structure:
.db num_items
.db flags
.db col,row
.db width,height
.db ItemType
.dw ItemPointer
.db ItemType
.dw ItemPointer
...and so on...
Flags:
Bit 0: FO_Showing
Bit 1: FO_Inverse
A single line of text.
Input for all functions: hl -> Label Structure
Functions:
1. guiDrawLabel Checks the LA_Showing bit, and
either draws the text or clears it accordingly.
2. guiShowLabel Sets the LA_Showing bit, then
calls guiDrawLabel
3. guiHideLabel Resets the LA_Showing bit, then
calls guiDrawLabel
Structure:
.db col,row
.db flags
.db "String",0
Flags:
Bit 0: LA_BigFont
Bit 1: LA_Inverse
Bit 2: LA_Showing
Comments:
If the LA_Inverse flag is set, then hiding the label will
make it black, otherwise
it will clear to white.
Multiple lines of text.
Input for all functions: hl -> Paragraph Structure
Functions:
1. guiDrawPara Checks the PA_Showing bit, and
either draws the text or clears it accordingly.
2. guiShowPara Sets the PA_Showing bit, then
calls guiDrawLabel
3. guiHidePara Resets the PA_Showing bit, then
calls guiDrawLabel
Structure:
.db col,row
.db flags
.db num_lines
.db "Line 1",0
.db "Line 2",0
.db "Line 3",0
...and so on...
Flags:
Bit 0: PA_BigFont
Bit 1: PA_Inverse
Bit 2: PA_Centered
Bit 3: PA_Showing
Comments:
If the PA_Inverse flag is set, then hiding the label will
make it black, otherwise
it will clear to white.
A push button with rounded corners.
Input for all functions: hl -> Button Structure
Functions:
1. guiDrawButton Checks the BU_Showing bit and
either displays or clears button accordingly
2. guiShowButton Sets the BU_Showing bit then calls
guiDrawButton
3. guiHideButton Resets the BU_Showing bit then calls guiDrawButton
Structure:
.db col,row
.db width,height
.db flags
.db "String",0
Flags:
Bit 0: BU_BigFont
Bit 1: BU_Inverse
Bit 2: BU_Showing
A box, either checked or unchecked, next to a single line
of text.
Input for all functions: hl -> Checkbox Structure
Functions:
1. guiDrawCheckBox
2. guiShowCheckBox
3. guiHideCheckBox
4. guiCheckCheckBox Checks a checkbox
5. guiUnCheckBox Unchecks a checkbox
Structure:
.db col,row
.db flags
.db "String",0
Flags:
Bit 0: CH_BigFont
Bit 1: CH_Inverse
Bit 2: CH_BoxOnRight
Bit 3: CH_Checked
Bit 4: CH_Showing
Multiple pieces of text, in rectangles, only one
highlighted.
Inputs for all functions: hl -> Options Structure
Functions:
1. guiDrawOptions
2. guiShowOptions
3. guiHideOptions
4. guiSetOption Options are redrawn, and option
specified by register "a" is now selected.
Structure:
.db flags
.db num_opitons
.db selected
.db Opt1Col,Opt1Row
.db Opt1Width,Opt1Height
.db "Option
1",0
.db Opt2Col,Opt2Row
.db Opt2Width,Opt2Height
.db "Option
2",0
Flags:
Bit 0: OP_BigFont
Bit 1: OP_Inverse
Bit 2: OP_Showing
Comments:
For guiSetOption, zero is the first option, one is the second, etc.
A rectangle housing a stringinput.
Inputs for all functions: hl -> Textbox Structure
Functions:
1. guiDrawTextBox
2. guiShowTextBox
3. guiHideTextBox
4. guiInputTextBox Input text to the textbox.
Structure:
.db width,height
.db flags
.db inputflags
.db maxchars
.db col,row
.dw wheretostore
Flags:
Bit 0: TB_Inverse
Bit 1: TB_NoBorder
Bit 2: TB_Showing
Bit 3: TB_Focusable
InputFlags:
Bit 0: SI_BigFont
Bit 1: SI_NoCursor
Bit 2: SI_NoDisp
Bit 3: SI_NumbersDef
Bit 4: SI_NoAlpha
Bit 5: SI_NoClearDel
Bit 6: SI_NullAllowed
Bit 7: SI_UseDefault
Comments:
The reason for the
strange layout of the structure is because
the end exactly
matches the StringInputST structure. This is
also why SI_ flags
are used.
The default string
will be drawn when guiDrawTextBox is called
no matter what
SI_UseDefault is.
The rectangle is
drawn one pixel up and two left of the row/col coordinates,
so that the text is exactly on the coordinates.
A sprite.
Inputs: hl -> Bitmap Structure
Functions:
1. guiDrawBitmap Draw the sprite to plotsscreen,
then grbufcpy.
Structure:
.db col,row
.db width,height
.db imagetype
.db %10011010
.db %01100100
.db %00000100
ImageType:
Bits 0 and 1:
Compression
0 - None BM_NoComp
1 - RLE BM_RLE
2 - Vertical RLE BM_VRLE
Bits 2 and 3: Draw
method
0 - Xor BM_Xor
4 - Or BM_Or
8 - And BM_And
C - Ld BM_Ld
Comments:
Width is in bytes, height is in pixels.
A highlighting bordered paragraph.
Inputs for all functions: hl -> List Structure
Functions:
1. guiDrawList
2. guiShowList
3. guiHideList
4. guiSetList Set the currently selected
list element to the value in register “a”
Structure:
.db col,row
.db width
.db flags
.db selection ; 0 = “Element 1”
.db items
.db "Element
1",0
.db "Element
2",0
.db "Element
3",0
Flags:
Bit 0: LI_BigFont
Bit 1: LI_Inverse
Bit 2: LI_Centered
Bit 3: LI_NoBorder
Bit 4: LI_Showing
Bit 5: LI_Dropped
Comments:
LI_Dropped is used solely
for "save-behind" when using droplists. Never
use it in a form, as
all normal form elements are drawn to the buffer, and
some draw routines
automatically copy the buffer (ex. checkbox/bitmap).
There cannot be 0
items in the list.
The list is fitted to
the number of elements, so that proper spacing is
maintained above and
below. However, no checks are made to see if it will fit
on the screen.
Horizontal size is the responsibility of the calling program.
When specifying a list element, 0 is the first, 1 is the second, and so on.
A trigger to call up a list.
Inputs for all functions: hl -> Droplist Structure
Functions:
1. guiDrawDrop
2. guiShowDrop
3. guiHideDrop
Structure:
.db col,row
.db flags
.dw listpointer ; Holds a pointer to the list that
pops up
.dw stringpointer ; Holds a pointer to the string
which is displayed by the arrow
Flags:
Bit 0: DL_BigFont
Bit 1: DL_Inverse
Bit 2: DL_DropOnR
Bit 3: DL_Showing
Comments:
The little arrow is ld'd to the buffer, so the three pixels to the right will be cleared.