THE BASIC LANGUAGE REFERENCE. BASIC 7.1
PART 2. ADD-ON-LIBRARY REFERENCE
USER INTERFACE TOOLBOX. MENU.BAS
S U B T I T L E S :
MENUCHECK FUNCTION
MENUCOLOR SUB
MENUDO SUB
MENUEVENT SUB
MENUINIT SUB
MENUINKEY$ FUNCTION
MENUITEMTOGGLE SUB
MENUOFF SUB
MENUON SUB
MENUPREPROCESS SUB
MENUSET SUB
MENUSETSTATE SUB
MENUSHOW SUB
SHORTCUTKEYDELETE SUB
SHORTCUTKEYEVENT SUB
SHORTCUTKEYSET SUB
USING THE PROCEDURES IN MENU.BAS IS STRAIGHTFORWARD. IN MOST CASES, THE DEMONSTRATION PROGRAM UIDEMO.BAS PROVIDES ENOUGH INFORMATION FOR A BASIC PROGRAMMER OF SOME EXPERIENCE TO GET
STARTED. HOWEVER, A FEW NOTES OF INTRODUCTION ARE IN ORDER.
WHEN YOU USE THE PROCEDURES IN MENU.BAS, YOU MUST PROVIDE THE FOLLOWING GLOBAL ARRAY DECLARATIONS IN YOUR PROGRAM, IN THE ORDER SHOWN:
COMMON SHARED /UITOOLS/GLOMENU AS MENUMISCTYPE
COMMON SHARED /UITOOLS/GLOTITLE() AS MENUTITLETYPE
COMMON SHARED /UITOOLS/GLOITEM() AS MENUITEMTYPE
DIM GLOTITLE(MAXMENU) AS MENUTITLETYPE
DIM GLOITEM(MAXMENU, MAXITEM) AS MENUITEMTYPE
THE ORDER IS IMPORTANT BECAUSE THE BLOCK DEFINED BY COMMON IN THE QBASIC LIBRARY MUST AGREE WITH THE BLOCK DEFINED BY COMMON IN THE PROGRAMMING ENVIRONMENT. THESE GLOBAL ARRAYS ARE USED TO
STORE INFORMATION ABOUT THE MENUS YOU DEFINE.
AS PREVIOUSLY MENTIONED, THE MENUS IN THE USER INTERFACE TOOLBOX WORK LIKE THOSE IN THE QBX PROGRAMMING ENVIRONMENT. MENU TITLES ARE DISPLAYED ON A MENU BAR THAT EXTENDS ACROSS THE TOP OF THE SCREEN IN ROW 1. ASSOCIATED WITH EACH MENU ARE ONE OR MORE MENU ITEMS.
FROM THE PROGRAMMER'S STANDPOINT, MENUS ARE NUMBERED FROM LEFT TO RIGHT, BEGINNING AT 1. MENU ITEMS, THAT IS, THOSE CHOICES ASSOCIATED WITH EACH MENU, ARE NUMBERED FROM TOP TO BOTTOM, ALSO BEGINNING AT 1. FOR ANY GIVEN MENU, MENU ITEM 0 IS ALWAYS THE MENU TITLE.
THE MENUCOLOR PROCEDURE LETS YOU SELECT THE COLOR SCHEME FOR YOUR MENUS. A SINGLE MENUSET STATEMENT IS ALL THAT IS REQUIRED TO SET UP EACH MENU TITLE ON THE MENU BAR OR EACH MENU ITEM ASSOCIATED WITH A MENU.
MENUS CAN BE SELECTED WITH THE MOUSE, BY POINTING AND CLICKING, OR WITH THE KEYBOARD, BY PRESSING THE ALT KEY AND THE HIGHLIGHTED LETTER IN THE DESIRED MENU TITLE. WHEN A MENU IS SELECTED, THE CHOICES ASSOCIATED WITH THAT MENU WILL PULL DOWN, OR DROP, FROM THE MENU BAR SO THAT YOU CAN SEE THE CHOICES AVAILABLE.
WHEN A PULL-DOWN MENU IS DISPLAYED, MENU ITEMS CAN BE CHOSEN BY POINTING AND CLICKING WITH THE MOUSE, OR PRESSING THE HIGHLIGHTED KEY ASSOCIATED WITH THAT CHOICE. THE KEY COMBINATIONS USED IN THE LATTER SELECTION TECHNIQUE ARE CALLED ACCESS KEYS.
ACCESS KEYS CONSIST OF A SERIES OF MENU-ITEM-SELECTION KEYSTROKES; EACH SERIES BEGINS BY PRESSING THE ALT KEY. YOU ALSO CAN SET UP SHORTCUT KEYS TO USE IN LIEU OF THE MOUSE OR THE REGULAR ACCESS KEYS. SHORTCUT KEYS CAN USE ANY CHARACTER OR EXTENDED CHARACTER, EXCEPT THOSE THAT USE THE ALT KEY.
FOR EXAMPLE, YOU CAN USE CTRL+X, CTRL+F10, OR SIMPLY F3). TO ENABLE A SHORTCUT KEY, USE A SHORTCUTKEYSET STATEMENT TO IDENTIFY THE MENU AND MENU ITEM WITH THE DEFINITION OF THE SHORT-CUT KEY. BEFORE ACTUALLY BUILDING YOUR MENUS, YOU NEED TO INITIALIZE GLOBAL ARRAYS TO SPEED UP MENU RESPONSE.
USE THE MENUINIT PROCEDURE TO INITIALIZE THE ARRAYS YOU DECLARED AND INITIALIZE THE MOUSE. THE FOLLOWING CODE FRAGMENT ILLUSTRATES HOW TO PUT TOGETHER A SHORT MENU WITH ONE TITLE, TWO ITEM CHOICES AND A MEANS OF EXITING THE MENU:
MENUINIT 'INITIALIZE EVERYTHING, INCLUDING THE MOUSE.
MENUSET 1, 0, 1, "MENU TITLE", 1 'SET UP MENU TITLE.
MENUSET 1, 1, 1, "SELECTION 1 F1", 11 'SET UP FIRST SELECTION.
'LAST PARAMETER DETERMINES HIGHLIGHT.
MENUSET 1, 2, 1, "SELECTION 2 F2", 11
MENUSET 1, 3, 1, "-", 1 'MAKE A LINE ACROSS THE MENU.
MENUSET 1, 4, 1, "EXIT CTRL-X", 2 'SET UP WAY TO GET OUT.
'SET F1 AS SHORTCUT KEY FOR 1.
SHORTCUTKEYSET 1, 1, CHR$(0) + CHR$(59)
SHORTCUTKEYSET 1, 2, CHR$(0) + CHR$(60)
SHORTCUTKEYSET 1, 4, CHR$(24) 'SET CTRL-X FOR EXIT.
MENUCOLOR 14, 1, 12, 8, 14, 3, 12 'SPECIFY COLOR SCHEME
MENUPREPROCESS 'DO ALL NECESSARY CALCULATIONS.
MENUSHOW 'DISPLAY THE MENU.
MOUSESHOW 'MAKE MOUSE CURSOR VISIBLE.
NOTICE THAT THE MENU TITLE IS DESCRIBED AS MENU 1, ITEM 0. ITEM 0 MEANS THAT THE MENUSET STATEMENT SPECIFIES A MENU TITLE, NOT A MENU ITEM. NUMBERS FROM 1 THROUGH 4 ARE THE REMAINING SELECTIONS. ITEM 3 IS SPECIAL. IT'S NOT REALLY A SELECTION ITEM. THE HYPHEN CHARACTER (–) CAUSES A BAR TO BE PLACED ACROSS THE PULL-DOWN MENU.
IT IS USEFUL FOR BREAKING UP FUNCTIONAL GROUPINGS OF MENU SELECTIONS. YOU CAN'T SELECT IT, SO YOU SHOULD REMEMBER TO USE A SELECT CASE STATEMENT THAT EXCLUDES THAT ITEM NUMBER WHEN PROCESSING THE SELECTIONS. SEE THE DEMONSTRATION PROGRAM UIDEMO.BAS FOR A WORKING EXAMPLE.
ALSO NOTICE THAT WITHIN THE TEXT FOR SELECTION
1, F1 IS SHOWN TO THE RIGHT. F1 IS THE SHORTCUT KEY FOR SELECTION 1 THAT IS PROGRAMMED USING THE FIRST SHORTCUTKEYSET STATEMENT. THE EXTENDED KEYBOARD CODE FOR THE F1 KEY IS CHR$(0)+ CHR$(59).
USE MENUCOLOR TO SET UP THE COLORS FOR YOUR MENUS, THE HIGHLIGHTED COLORS TO USE WHEN AN ITEM IS SELECTED, AND THE HIGHLIGHTED CHARACTERS TO USE WHEN CHOOSING A MENU ITEM FROM THE KEYBOARD. MENUPREPROCESS PERFORMS THE NECESSARY ALCULATIONS AND BUILDS INDEXES THAT HELP SPEED UP MENU EXECUTION.
MENUSHOW ACTUALLY DISPLAYS THE MENU BAR ON THE SCREEN. THE THREE-DIMENSIONAL SHADOW AND OTHER PROGRAMMING CHORES ARE HANDLED FOR YOU
AUTOMATICALLY. ONCE THE MENU BAR IS DISPLAYED, THE CALL TO MOUSESHOW MAKES THE MOUSE CURSOR VISIBLE.
AFTER YOU'VE DISPLAYED YOUR MENUS, YOU WANT TO BE ABLE TO HAVE THE PROGRAM TRANSLATE THE AVAILABLE CHOICES INTO ACTION. PROCESSING MENU SELECTIONS IS ALSO VERY STRAIGHTFORWARD.
THE MENUINKEY$ PROCEDURE WITHIN A WHILE...WEND CONTROL-FLOW STRUCTURE SERVES WELL TO POLL USER INPUT. THE FOLLOWING CODE FRAGMENT ILLUSTRATES HOW TO PROCESS USER INPUT AND TRANSLATE A USER'S CHOICE TO A DESIRED ACTION:
FINISHED = FALSE
WHILE NOT FINISHED
KBD$ = MENUINKEY$ 'MONITOR ALL USER INPUT.
SELECT CASE KBD$ 'SEE WHAT THE USER ENTERED.
CASE "MENU" 'IF KBD$ = "MENU".
MENU = MENUCHECK(0) 'GET MENU NUMBER.
ITEM = MENUCHECK(1) 'GET ITEM NUMBER.
GOSUB HANDLEMENUEVENT 'HANDLE SELECTION.
CASE ELSE
... 'IF KBD$ = ANYTHING ELSE.
END SELECT
WEND
HANDLEMENUEVENT:
SELECT CASE MENU
CASE 1 'HANDLES MENU 1.
SELECT CASE ITEM
CASE 1
SELECTION1ROUTINE 'HANDLE SELECTION 1.
CASE 2
SELECTION2ROUTINE 'HANDLE SELECTION 2.
CASE 4
FINISHED = TRUE 'HANDLE EXIT.
END SELECT
END SELECT
RETURN
THE CODE SHOWN ABOVE PROCESSES KEYBOARD INPUT AND MOUSE INPUT WITH MENUINKEY$. IF YOU WANTED TO PRECLUDE ANY KEYBOARD INPUT, YOU COULD USE MENUEVENT INSTEAD OF MENUINKEY$, AS FOLLOWS:
WHILE NOT FINISHED
MENUEVENT 'MONITOR MENU EVENTS ONLY.
IF MENUCHECK(2) THEN
MENU = MENUCHECK(0) 'GET MENU NUMBER.
ITEM = MENUCHECK(1) 'GET ITEM NUMBER.
GOSUB HANDLEMENUEVENT 'DETERMINE WHICH ITEM.
END IF
... 'WHAT TO DO IF MENUCHECK(2) HASN'T CHANGED.
WEND
THE PRECEDING INFORMATION IS INTENDED TO GIVE YOU AN OVERVIEW OF HOW THE MENUS WORK. WITH THIS INFORMATION AND THE DETAILED INFORMATION PROVIDED FOR EACH PROCEDURE, YOU SHOULD BE ABLE TO INCORPORATE MENUS INTO YOUR BASIC APPLICATIONS.
BE SURE TO SEE THE EXAMPLE CODE IN UIDEMO.BAS THAT DEMONSTRATES HOW MOST OF THE PROCEDURES ARE USED. A DESCRIPTION OF EACH PROCEDURE THAT
COMPRISES MENU.BAS IS NEXT.
ACTION: RETURNS AN INTEGER THAT INDICATES WHICH MENU SELECTION, IF ANY, WAS MADE FOLLOWING A MENU OR SHORTCUT-KEY EVENT.
SYNTAX: VARIABLENAME% = MENUCHECK(ACTION%)
REMARKS: THE MENUCHECK PROCEDURE USES THE FOLLOWING ARGUMENTS:
VARIABLENAME%: ANY BASIC VARIABLE NAME, INCLUDING THE NAME OF A RECORD VARIABLE OR RECORD ELEMENT.
ACTION%: AN INTEGER THAT IDENTIFIES THE SPECIFIC INFORMATION REQUESTED.
THE VALUES ARE AS FOLLOWS:
0
CHECKS TO SEE IF A MENU ITEM WAS SELECTED SINCE MENUCHECK WAS LAST CALLED. IF A MENU ITEM WAS SELECTED, MENUCHECK RETURNS THE NUMBER OF THE MENU AND SETS THE GLOBAL VARIABLES SO THAT WHEN MENUCHECK(1) IS CALLED, THE APPROPRIATE MENU ITEM NUMBER IS RETURNED. IF NO MENU ITEM WAS SELECTED, RETURNS 0.
1
RETURNS THE MATCHING MENU ITEM OF THE LAST MENU SELECTION. MENUCHECK(1) IS RESET EACH AFTER EACH CALL TO MENUCHECK(0).
2
RETURNS TRUE (-1) IF MENU ITEM HAS BEEN SELECTED AS OF THE LAST MENUCHECK(0) CALL, OR FALSE (0) IF NOT. IF A SELECTION HAS OCCURRED, USE MENUCHECK(0) AND MENUCHECK(1) TO DETERMINE WHAT SELECTION WAS MADE. MENUCHECK(2) CHANGES NO VALUES.
THE MENUCHECK PROCEDURE SIMULATES POLLING FOR A MENU EVENT. WHEN A MENU EVENT OCCURS, GLOBAL VARIABLES ARE SET TO THEIR APPROPRIATE VALUES. MENUCHECK(0) THEN RETURNS THE MENU NUMBER,
OR 0 IF NO MENU WAS SELECTED SINCE THE LAST CALL TO MENUCHECK. YOU CAN USE MENUCHECK TO PROVIDE INFORMATION ABOUT MENU SELECTION AS FOLLOWS:
KBD$ = MENUINKEY$
SELECT CASE KBD$
CASE "MENU"
MENU = MENUCHECK(0)
ITEM = MENUCHECK(1)
MOUSEHIDE
PRINT MENU, ITEM
MOUSESHOW
CASE ELSE
PRINT KBD$
END SELECT
OR
MENUEVENT
IF MENUCHECK(2) THEN
MENU = MENUCHECK(0)
ITEM = MENUCHECK(1)
MOUSEHIDE
PRINT MENU, ITEM
MOUSESHOW
END IF
SEE ALSO: MENUEVENT, MENUINKEY$, SHORTCUTKEYEVENT
EXAMPLE: SEE THE MAIN LOOP OF THE CODE EXAMPLE UIDEMO.BAS FOR A PRACTICAL IMPLEMENTATION OF THE MENUCHECK PROCEDURE.
ACTION: ASSIGNS COLORS TO THE COMPONENTS OF A MENU.
SYNTAX: MENUCOLOR FORE%, BACK%, HIGHLIGHT%, DISABLED%,
CURSORFORE%, CURSORBACK%, CURSORHI%
REMARKS: THE MENUCOLOR PROCEDURE USES THE FOLLOWING ARGUMENTS:
FORE%: AN INTEGER THAT DEFINES MENU FOREGROUND COLOR (0-15).
BACK%: AN INTEGER THAT DEFINES MENU BACKGROUND COLOR (0-7).
HIGHLIGHT%: AN INTEGER THAT DEFINES TEXT COLOR (0-15) OF THE ACCESS KEY CHARACTER.
DISABLED%: AN INTEGER THAT DEFINES TEXT COLOR OF DISABLED ITEMS (0-15).
CURSORFORE%: AN INTEGER THAT DEFINES THE MENU CURSOR FOREGROUND COLOR (0-15).
CURSORBACK%: AN INTEGER THAT DEFINES THE MENU CURSOR BACKGROUND COLOR (0-7).
CURSORHI%: AN INTEGER THAT DEFINES TEXT COLOR (0-15) OF THE ACCESS KEY CHARACTER WHEN THE MENU CURSOR IS ON THAT MENU ITEM.
THE VALUES SPECIFIED ARE PLACED INTO GLOBAL VARIABLES. YOU CAN USE ANY COLOR SCHEME YOU CHOOSE WITHIN THE RANGE OF AVAILABLE COLORS. SHADOWS THAT APPEAR BENEATH MENU WINDOWS ARE ALWAYS BLACK. USE MENUCOLOR IN YOUR PROGRAM TO SET UP MENU COLORS.
COLORS SHOULD BE INITIALIZED BEFORE THE MENU IS DISPLAYED THE FIRST TIME. IF COLORS ARE NOT INITIALIZED, THE DEFAULT MONOCHROME COLOR SCHEME PLACES THE FOLLOWING INTEGERS INTO THE ARGUMENT LIST (IN ORDER): 0, 7, 15, 8, 7, 0, 15. THIS RESULTS IN A
MONOCHROME DISPLAY.
IF YOU CHANGE COLORS WHILE YOUR PROGRAM IS RUNNING, USE MENUSHOW TO SHOW THE CHANGES.
SEE ALSO: MENUSHOW
EXAMPLE: SEE THE SETUPMENU PROCEDURE IN THE CODE EXAMPLE UIDEMO.BAS FOR THE SPECIFIC IMPLEMENTATION OF THE MENUCOLOR PROCEDURE.
ACTION: USED INTERNALLY BY OTHER PROCEDURES IN MENU.BAS.
DO NOT USE OR ALTER THIS PROCEDURE.
SYNTAX: MENUDO
REMARKS: THE MENUDO PROCEDURE IS USED ONLY WITHIN MENU.BAS TO PROCESS MENU SELECTION USING THE MOUSE AND KEYBOARD. TO PROCESS MENU SELECTIONS IN YOUR PROGRAM, YOU SHOULD USE MENUINKEY$ OR MENUEVENT, BOTH OF WHICH USE THIS PROCEDURE.
IF MENUS ARE ENABLED (USING MENUON), MENUDO TAKES CONTROL OF THE PROGRAM WHEN THE USER IS SELECTING A MENU ITEM BY ANY MEANS. MENUDO CONTROLS THE DISPLAY AND RESPONDS TO USER INPUT UNTIL A
SELECTION HAS BEEN MADE. ONCE A SELECTION HAS BEEN MADE, USE THE MENUCHECK PROCEDURE TO DETERMINE WHICH MENU ITEM WAS SELECTED.
WARNING: DO NOT USE OR ALTER THIS PROCEDURE UNLESS YOU ARE CUSTOMIZING THE USER INTERFACE TOOLBOX AND YOU KNOW HOW THE USE OR ALTERATION OF THIS PROCEDURE WILL AFFECT THE OPERATION OF ALL
OTHER PROCEDURES IN THE TOOLBOX.
SEE ALSO: MENUEVENT, MENUINKEY$
ACTION: MONITORS USER INPUT TO DETERMINE IF A MENU ITEM IS BEING CHOSEN, WITH EITHER THE MOUSE OR THE KEYBOARD.
SYNTAX: MENUEVENT
REMARKS: IF MENUEVENT DETECTS EITHER A PRESSED ALT KEY OR A MOUSE BUTTON PRESS WHILE THE MOUSE CURSOR IS ON THE TOP ROW, PROGRAM CONTROL IS TRANSFERRED TO MENUDO. MENUDO RETAINS PROGRAM CONTROL UNTIL AN ITEM IS SELECTED OR THE USER ABORTS THE MENU PROCESS EITHER BY RELEASING THE MOUSE BUTTON SOMEWHERE OTHER THAN THE TOP ROW OR BY PRESSING THE ESC KEY.
ONCE AN ITEM IS SELECTED, USE MENUCHECK TO EVALUATE THE SELECTION. MENUEVENT IS USED BY THE MENUINKEY$ PROCEDURE TO DETERMINE WHEN A USER HAS PRESSED THE ALT KEY IN CONJUNCTION WITH A KEYBOARD SELECTION OR HAS SELECTED A MENU BY MOVING THE MOUSE CURSOR TO THE TOP ROW AND PRESSING THE LEFT MOUSE BUTTON.
SEE ALSO: MENUINKEY$, SHORTCUTKEYEVENT
ACTION: INITIALIZES GLOBAL MENU ARRAYS AND THE MOUSE DRIVER-SERVICING ROUTINES.
SYNTAX: MENUINIT
REMARKS: TO ENABLE MOUSE DRIVER SERVICING, MENUINIT CALLS MOUSEINIT IN MOUSE.BAS.
USE MENUINIT AT OR NEAR THE BEGINNING OF ANY PROGRAM THAT USES THE MENU PROCEDURES PROVIDED IN THE USER INTERFACE TOOLBOX. YOU MUST CALL MENUINIT BEFORE ANY OTHER MENU PROCEDURES ARE USED.
SEE ALSO: MENUPREPROCESS
EXAMPLE: SEE THE INITIALIZATION SECTION IN THE CODE EXAMPLE UIDEMO.BAS FOR A SPECIFIC IMPLEMENTATION.
ACTION: PERFORMS A BASIC INKEY$ PROCEDURE, AS WELL AS BOTH A MENUEVENT PROCEDURE AND A SHORTCUTKEYEVENT PROCEDURE, RETURNING A STRING.
SYNTAX: VARIABLENAME$ = MENUINKEY$
REMARKS: THE MENUINKEY$ PROCEDURE OPERATES EXACTLY LIKE THE STANDARD BASIC INKEY$ PROCEDURE, BUT ADDITIONALLY PERFORMS MENUEVENT AND SHORTCUTKEYEVENT PROCEDURES. IF EITHER A MENU
EVENT OR A SHORTCUT-KEY EVENT OCCURS, MENUINKEY$ RETURNS THE WORD "MENU" INSTEAD OF THE NORMALLY EXPECTED INKEY$ VALUE. WHEN MENUINKEY$ RETURNS THE WORD "MENU," USE MENUCHECK TO DETERMINE WHICH MENU AND MENU ITEM WAS SELECTED.
SEE ALSO: MENUDO, MENUEVENT, SHORTCUTKEYEVENT
EXAMPLE: SEE THE MAIN LOOP IN THE CODE EXAMPLE UIDEMO.BAS FOR A SPECIFIC IMPLEMENTATION.
ACTION: TOGGLES THE STATE OF OF THE SELECTED MENU ITEM BETWEEN 1 (ENABLED) AND 2 (ENABLED WITH A CHECK MARK) TO INDICATE SELECTION OF THE MENU ITEM.
SYNTAX: MENUITEMTOGGLE MENU%, ITEM%
REMARKS: THE MENUITEMTOGGLE PROCEDURE USES THE FOLLOWING ARGUMENTS:
MENU%: AN INTEGER THAT IDENTIFIES THE POSITION (FROM LEFT TO
RIGHT) OF THE AFFECTED MENU.
ITEM%: AN INTEGER THAT IDENTIFIES THE NUMBER (FROM TOP TO
BOTTOM) OF THE MENU ITEM WITHIN THE MENU.
USE MENUITEMTOGGLE WHENEVER YOU WANT TO INDICATE THAT A PARTICULAR MENU ITEM HAS BEEN SELECTED. IT IS NOT NECESSARY TO RE-EXECUTE MENUPREPROCESS AFTER PERFORMING A MENUITEMTOGGLE OPERATION.
SEE ALSO: MENUPREPROCESS, MENUSETSTATE
ACTION: TURNS OFF MENU AND SHORTCUT-KEY EVENT PROCESSING.
SYNTAX: MENUOFF
REMARKS: MENU AND SHORTCUT-KEY EVENT PROCESSING IS DISABLED BY SETTING THE GLOBAL VARIABLE GLOMENU.MENUON TO FALSE (0). WHEN MENU EVENT PROCESSING IS OFF, MENUDO IGNORES ANY MOUSE OR KEYBOARD ACTIVITY THAT WOULD NORMALLY TRIGGER A MENU EVENT. USE MENUOFF ANYTIME YOU WANT TO TURN MENU EVENT PROCESSING OFF.
SEE ALSO: MENUON
ACTION: TURNS ON MENU AND SHORTCUT-KEY EVENT PROCESSING.
SYNTAX: MENUON
REMARKS: MENU AND SHORTCUT-KEY EVENT PROCESSING IS ENABLED BY SETTING THE GLOBAL VARIABLE GLOMENU.MENUON TO TRUE (-1). WHEN MENU EVENT PROCESSING IS ON, MENUDO TAKES CONTROL OF THE DISPLAY AND THE PROGRAM WHEN ANY MOUSE OR KEYBOARD ACTIVITY OCCURS TO TRIGGER A MENU EVENT.
USE MENUON ANYTIME YOU WANT TO TURN MENU EVENT PROCESSING BACK
ON AFTER DISABLING WITH MENUOFF.
SEE ALSO: MENUOFF
ACTION: PERFORMS CALCULATIONS AND BUILDS INDEXES SO THE MENU PROCEDURES RUN FASTER.
SYNTAX: MENUPREPROCESS
REMARKS: USE MENUPREPROCESS ANYTIME MENUSET IS PERFORMED ONE OR MORE TIMES, AND ANY TIME THE STATE OF A MENU ITEM IS CHANGED USING MENUSETSTATE TO CHANGE TO OR FROM THE EMPTY (-1) OR NOT DISPLAYED STATE. YOU MUST CALL MENUPREPROCESS ANYTIME CHANGES OTHER THAN ITEM SELECTION CHANGES ARE MADE TO THE MENUS.
SEE ALSO: MENUSET, MENUSETSTATE
EXAMPLE: SEE THE SETUPMENU PROCEDURE IN THE CODE EXAMPLE UIDEMO.BAS FOR A SPECIFIC IMPLEMENTATION.
ACTION: DEFINES THE STRUCTURE OF YOUR MENUS AND DEFINES THE ACCESS KEYS ASSOCIATED WITH INDIVIDUAL MENU SELECTIONS.
SYNTAX: MENUSET MENU%, ITEM%, STATE%, TEXT$, ACCESSKEY%
REMARKS: THE MENUSET PROCEDURE USES THE FOLLOWING ARGUMENTS:
MENU%: AN INTEGER THAT IDENTIFIES THE POSITION (FROM LEFT TO RIGHT) OF A MENU ON THE MENU BAR.
ITEM%: AN INTEGER THAT IDENTIFIES THE POSITION (FROM TOP TO
BOTTOM) OF THE MENU ITEM WITHIN THE MENU. IF ITEM% IS 0, THEN TEXT$ IS THE MENU TITLE. OTHER NUMBERS INDICATE CONSECUTIVE MENU SELECTIONS.
STATE%: AN INTEGER THAT INDICATES THE STATE OF THE MENU ITEM:
0 DISABLED, APPEARS IN COLOR DEFINED BY THE DISABLED% VARIABLE SET WITH MENUCOLOR.
1 ENABLED, THIS IS THE NORMAL STATE.
2 ENABLED WITH A CHECK MARK.
TEXT$: A STRING THAT IS THE NAME OF THE MENU ITEM. MENU TITLES ARE LIMITED TO 15 CHARACTERS; INDIVIDUAL MENU ITEMS ARE LIMITED TO 30 CHARACTERS.
ACCESSKEY%: AN INTEGER THAT INDICATES THE POSITION, WITHIN TEXT$, OF THE CHARACTER THAT IS USED TO CHOOSE THE MENU ITEM. THIS ACCESS KEY IS HIGHLIGHTED IN COLOR DEFINED BY THE HIGHLIGHT%
VARIABLE SET WITH MENUCOLOR.
USE MENUSET TO INITIALIZE THE CONTENTS OF YOUR MENUS. A SEPARATE MENUSET ENTRY IS REQUIRED FOR EACH ITEM, INCLUDING THE TITLE ON EACH MENU. EACH MENUSET ENTRY DEFINES EITHER A MENU TITLE OR A
MENU ITEM THAT IS TO BE DISPLAYED AND THE STATE OF INDIVIDUAL
MENU ITEMS.
MENU ITEMS CAN BE ENABLED, DISABLED, CHECKED, OR EVEN MADE INVISIBLE. YOU ALSO CAN SPECIFY ACCESS KEYS FOR MENU ITEMS TO ALLOW ONE-STROKE SELECTION.
MENUPREPROCESS MUST BE EXECUTED AFTER A SERIES OF MENUSET STATEMENTS OR ANY TIME THE STATE OF A MENU ITEM IS CHANGED USING MENUSETSTATE. MENUSHOW MUST BE RE-EXECUTED IF ANY CHANGE TO THE MENU TITLE HAS OCCURRED.
SEE ALSO: MENUPREPROCESS, MENUSETSTATE, MENUSHOW
EXAMPLE: SEE THE SETUPMENU PROCEDURE IN THE CODE EXAMPLE UIDEMO.BAS FOR A SPECIFIC IMPLEMENTATION.
ACTION: EXPLICITLY ASSIGNS THE STATE OF A MENU ITEM.
SYNTAX: MENUSETSTATE MENU%, ITEM%, STATE%
REMARKS: THE MENUSETSTATE PROCEDURE USES THE FOLLOWING ARGUMENTS:
MENU%: AN INTEGER THAT IDENTIFIES THE POSITION (FROM LEFT TO RIGHT) OF THE AFFECTED MENU.
ITEM%: AN INTEGER THAT IDENTIFIES THE NUMBER OF THE MENU ITEM WITHIN THE MENU.
STATE%: AN INTEGER THAT INDICATES THE STATE OF THE MENU ITEM:
<BR> -1 EMPTY, DOES NOT APPEAR ON MENU.
0 DISABLED, APPEARS IN COLOR DEFINED BY THE DISABLED% VARIABLE SET WITH MENUCOLOR.
1 ENABLED, THIS IS THE NORMAL STATE.
2 ENABLED WITH A CHECK MARK.
USE MENUSETSTATE WHENEVER YOU WANT TO CHANGE THE STATE OF A PARTICULAR MENU ITEM. YOU MUST RE-EXECUTE MENUPREPROCESS IF THE STATE OF THE MENU ITEM CHANGES TO OR FROM THE EMPTY OR NOT DISPLAYED STATE.
SEE ALSO: MENUPREPROCESS
ACTION: DRAWS THE MENU BAR ACROSS THE TOP OF THE SCREEN.
SYNTAX: MENUSHOW
REMARKS: ALL MENU TITLES THAT HAVE BEEN ESTABLISHED WITH MENUSET ARE DISPLAYED. USE MENUSHOW TO INITIALLY DISPLAY YOUR MENU BAR ONCE IT HAS BEEN DEFINED WITH MENUSET, AND USE IT EACH TIME YOU CHANGE THE MENU BAR.
SEE ALSO: MENUPREPROCESS
EXAMPLE: SEE THE INITIALIZATION SECTION IN THE CODE EXAMPLE UIDEMO.BAS FOR A SPECIFIC IMPLEMENTATION.
ACTION: DELETES THE SHORTCUT KEY ASSOCIATED WITH A PARTICULAR
MENU ITEM.
SYNTAX: SHORTCUTKEYDELETE MENU%, ITEM%
REMARKS: THE SHORTCUTKEYDELETE PROCEDURE USES THE FOLLOWING
ARGUMENTS:
MENU%: AN INTEGER THAT IDENTIFIES THE POSITION (FROM LEFT TO RIGHT) OF THE AFFECTED MENU.
ITEM%: AN INTEGER THAT IDENTIFIES THE NUMBER OF THE MENU ITEM WITHIN THE MENU. USE SHORTCUTKEYDELETE ANYTIME YOU WANT TO VOID SHORTCUT KEYS THAT WERE PREVIOUSLY ESTABLISHED WITH SHORTCUTKEYSET.
SEE ALSO: SHORTCUTKEYEVENT, SHORTCUTKEYSET
ACTION: POLLS USER INPUT TO DETERMINE IF A MENU ITEM IS BEING SELECTED BY USING ONE OF THE SHORTCUT KEYS.
SYNTAX: SHORTCUTKEYEVENT KBD$
REMARKS: THE ARGUMENT KBD$ IS A STRING THAT CONTAINS A CHARACTER ENTERED AT THE KEYBOARD. SHORTCUTKEYEVENT CHECKS KBD$ AGAINST A LIST OF SHORTCUT KEYS DEFINED USING SHORTCUTKEYSET. IF A MATCH IS FOUND, THE PROPER MENU AND ITEM ARE SELECTED. THIS DUPLICATES EXACTLY THE FUNCTIONALITY OF THE MENUEVENT PROCEDURE.
USE MENUCHECK TO DETERMINE WHICH MENU AND ITEM WERE SELECTED. IF YOU USE MENUINKEY$ IN YOUR PROGRAM, SHORTCUTKEYEVENT IS AUTOMATICALLY PERFORMED; IF YOU USE THE BASIC INKEY$ PROCEDURE, YOU MUST EXPLICITLY CALL SHORTCUTKEYEVENT TO PROCESS SHORTCUT-KEY EVENTS.
SEE ALSO: MENUCHECK, SHORTCUTKEYDELETE, SHORTCUTKEYSET
ACTION: ASSIGNS SHORTCUT KEYS TO INDIVIDUAL MENU ITEMS.
SYNTAX: SHORTCUTKEYSET MENU%, ITEM%, KBD$
REMARKS: THE SHORTCUTKEYSET PROCEDURE USES THE FOLLOWING
ARGUMENTS:
MENU%: AN INTEGER THAT IDENTIFIES THE POSITION (FROM LEFT TO RIGHT) OF THE AFFECTED MENU.
ITEM%: AN INTEGER THAT IDENTIFIES THE NUMBER OF THE MENU ITEM WITHIN THE MENU.
KBD$: A STRING THAT INDICATES WHICH CHARACTER IS ALLOWED AS A SHORTCUT KEY FOR SELECTION OF THE MENU ITEM. THE STRING ARGUMENT KBD$ CAN BE ANY SINGLE CHARACTER, OR ANY EXTENDED CHARACTERS,
EXCEPT THOSE THAT USE THE ALT KEY.
WITHOUT SHORTCUT KEYS, EACH MENU ITEM CAN BE SELECTED BY PRESSING THE ALT KEY AND THE HIGHLIGHTED CHARACTER IN THE MENU NAME, FOLLOWED BY THE HIGHLIGHTED LETTER IN THE MENU ITEM. COMMANDKEYSET PROVIDES ADDITIONAL FUNCTIONALITY BY ALLOWING YOU TO SPECIFY A SINGLE CHARACTER, SUCH AS SHIFT+F1 OR F1, AS A SHORTCUT TO MENU ITEM SELECTION.
A SEPARATE SHORTCUTKEYSET ENTRY IS REQUIRED FOR EACH SHORTCUT KEY YOU ASSIGN. USE SHORTCUTKEYSET STATEMENTS DURING MENU INITIALIZATION AT THE SAME PLACE WHERE MENUSET IS USED.
SEE ALSO: MENUSET, SHORTCUTKEYDELETE, SHORTCUTKEYEVENT
EXAMPLE: SEE THE SETUPMENU PROCEDURE IN THE CODE EXAMPLE UIDEMO.BAS FOR A SPECIFIC IMPLEMENTATION.
( TOP )