PIECRUST ROUTINES AND PARAMETERS 1/12/96 -------------------------------- These routines are available within PIECRUST.BAS for QBasic ziDragging This sets the SHARED variable "Response", returning zero if the mouse is not being dragged. ziDrawBank( From, To ) This draws (or redraws) the selected consecutive buttons, using specifications within the SHARED array "Bank()". Each entry within "Bank()" (up to 20)defines the appearance, location and state of a button. The TYPE construct "Buttons" is used to access each of the features of a button: Buttons(i).Xloc = "X" graphic coordinate of top left corner Buttons(i).Yloc = "Y" graphic coordinate of top left corner Buttons(i).Wide = width in pixels of the button (horizontal) Buttons(i).Deep = depth in pixels of the button (vertical) (using HORIZONTAL pixel unit size) NOTE: 0 defines a check button (round) 1 defines a square "sculpted" button Buttons(i).State = 0 for OFF, i for ON Buttons(i).Active = 0 for not used, 1 for used Using the "Active" component you can vary which buttons are displayable, apart from whether they are already defined. ziExhaust This sets the SHARED variable "Response" to zero if the mouse has not been clicked since last checked. ziLoadFont( Font$ ) This loads as a font (used by "ziPublish") an OVL file with a specified name. The file can be in the current directory or anywhere in the PATH. Only one font can be loaded at any one time. This loads the font via "zzInPath" ziLocateMCursor( X, Y ) This sets the mouse cursor to the prescribed X and Y coordinates, and makes it visible (which renders the mouse "active"). ziMouseOnButton( From, To ) This sets the SHARED variable "FoundButton" to the number of a button between "From" and "To", on which the mouse cursor is found. If the mouse cursor is not within the area of a button, the value returned is zero. The buttons are the active ones in the range which have been defined within the SHARED array "Bank()" (up to 20). ziPublish( Phrase$, size, slope ) This writes to the screen in the loaded font (see "ziLoadFont") characters from the string "Phrase$" in the colours specified by the SHARED variables "fg" (foreground, or ink) and "bg" (background, or paper), and at the location of the graphics cursor (top left corner of the first character). Note that the graphics cursor is then advanced. "Size" governs the size of each character: 1 = 8 x 8 pixels. and 2 = 16 x 16 pixels, and so on. (Zero will work as if it were size 1). "Slope" defines two other characteristics: +1 will write an ITALIC character +2 will write the foreground of the character only (so if "Slope" = 3 the routine will print italic form, foreground only). Setting "foreground only" condition allows you to write characters over any background without it checking the colour of pixels. Example: LOCATE 10,45 Call zsAlignGCursor Call ziPublish( "This appears at (10,45)", 1, 0) Note: the graphics cursor is advanced to the next appropriate character position following the printed string, but you should beware that you leave more space if you decide to follow italicised characters with non-italicised characters with two consecutive calls to "ziPublish". ziPublishHere( row, column, Phrase$, size, slope) This is identical to "ziPublish", except that it takes as input the row and column numbers (text notation). If both are set to zero, the current text position will be used. On exit both the text and graphic cursors will be set at the position following the last character. ziRadio ( Button, From, To ) This sets the ".State" component of the specified "Button" ON (=1) and of all the other buttons in the range between "From" and "To" OFF (=0). In effect this links the buttons in the range like the buttons on a pushbutton radio: only one button will be ON at a time. This can be used along with "ziMouseOnButton" to simulate the operation of "radio" buttons.. Example: CALL ziMouseOnButton IF FoundButton > 0 THEN CALL ziRadio( FoundButton, 1, 20) END IF ziReadField( Minimum, Maximum, Permitted$ ) Reads a field at the current text cursor location, with "Maximum" as its maximum size and "Minimum" as its minimum number of significant characters. The "Permitted$" string specifies what kind of characters are permitted within the field: "*" = any characters "." = ensure no more than one full-stop (useful for fields intended to be numeric) "A" = auto-enter when "Maximum" reached (instead of insisting on "Enter" to finish the field) "C" = capitalise any letters "E" = "Esc" allowed - which sets field empty "J" = justify output on the right (especially for numbers) "N" = numbers allowed "P" = password-type display (you can count characters, but they are not recognisable) "S" = space allowed "X" = alphabetic characters allowed "Y" = Y or N allowed regardless of case (useful to get Yes or No answers) You can use several letters in combination: for example.. CALL ziReadField( 3, 7, "NJ.") - obtain a field from input with between 3 and 7 significant figures, permitting decimal. CALL ziReadField( 1, 1, "CYA") - obtain a single character "Y" or "N" without waiting for an Enter key to finish (return as a capital letter) The result is returned in the SHARED variable "Field$" ziSetMCursorVis( Status ) This routine sets the visibility status of the Mouse cursor: 0 = set the mouse cursor OFF 1 = set the mouse cursor ON 2 = request the current status of the mouse cursor 10 = set the mouse cursor OFF temporarily 11 = restore the previous status of the mouse cursor Many screen-drawing functions are diverted by the mouse cursor if it is visible, so you should take care to turn it off temporarily while changing the screen, using "Status" set to 10, and then restore it (if it were on) using "Status" set to 11. Those PIECRUST routines that alter the screen do this automatically. The resulting status is returned in any case is returned in the SHARED variable "MCursorVis", with 0 = invisible and 1 = visible. ziWander( Timeout! ) This routine returns mouse or keyboard events in the SHARED variable "Response" as follows.. &H100 -Enter key &H101 -left arrow &H102 -right arrow &H103 -up arrow &H104 -down arrow &H105 -backspace &H106 -Home &H107 -End &H108 -Page up &H109 -Page down &H10A -Tab &H10B -Escape If the Ctrl key is held down, this adds &H100 to these values (except Ctrl/up arrow, Ctrl/down arrow and Ctrl/Tab, which do not return any value). &H40A is returned for shift/Tab Function keys are returned in the following way: &H10nn -Function key "nn" (00 to 09, 0A, 0B, 0C) &H20nn -Function key "nn" with Ctrl held down &H40nn -Function key "nn" with shift held down In addition the following mouse events are detected: &H800 -double-click &H801 -left click &H802 -right click &H803 -both click &H804 -left click and drag &H805 -right click and drag &H806 -both click and drag Note that double-click (&H800) will not be reported unless the SHARED variable "DClick" is set to 1; this slows down event-checking, and may not be desirable. "DClick" is initially set to OFF. Note that two other SHARED variables are returned: "HResponse" and "LResponse". If, for example, "Response" is &H208 (Ctrl/Page down), "HResponse" (H for HIGH) is set to &H2, while "LResponse" is set to &H8. The SHARED string variable "Allowed$" contains any other characters you wish to detect with ziWander: if a character that appears within this string is keyed, "HResponse" will be set to zero, and.. MID$(Allowed$, Response) ..will indicate which character was keyed. The "Timout!" parameter indicates a timeout (in seconds) to terminate this routine. If the routine is terminated by such a timeout, the "Response" passed back is zero. If you do not wish a timeout, pass the value zero in the parameter. zsAlignGCursor This routine aligns the graphic cursor (which is determined by pixel displacements) with the current location of the text cursor. Example: LOCATE 10,22 CALL zsAlignGCursor This is particularly handy for determining where to place graphic images (which includes 8x8 font characters via "ziPublish"), LINE or DRAW graphics, and even setting the location of the mouse cursor by following this with "CALL ziLocateMCursor( GXloc, GYloc )". zsAlignTCursor This routine does the reverse of zsAlignGCursor, setting the text cursor to the character position containing the current pixel indicated by the graphics cursor. zsLocateGCursor( xcoordinate, ycoordinate ) This routine places the graphics cursor at a particular point. This in effect does what the "LOCATE" command accomplishes for the text cursor. zsPastel( xcoord, ycoord, wide, deep, colour1, colour2 ) This creates an oblong (rectangle) starting at the named graphic point, creating a pastel mixture of the two colours. Note that if you create a background with this function you should, when using the "ziPublish" routine, use the "+2" from of the "slope" paramater so that the background is left as is, and only the positive part of each character overwrites the background. zsSetScrnMode( mode, highrows, highcolumns) This sets the screen with the colours indicated in the SHARED parameters "bg" and "fg". The mode parameter must be 9 or 12, and each of the other parameters should be 0 or 1: they indicate the number of rows and columns for which the screen will be configured: The number of rows and columns available obtained are as follows.. mode highrows=0 highrows=1 highcols=0 highcols=1 9 25 43 40 80 12 30 60 40 80 13 25 25 40 40 This routine also sets values into the SHARED variables Xmax and Ymax (giving the number of the rightmost X coordinate and the bottommost Y coordinate); also the SHARED value XYratio! is calculated and set. This aids in the determination of distances on the screen; since the X and Y increments are not the same, XYratio! will help you find the equivalence. zsSubstitute( xcoord, ycoord, wide, deep, colour1, colour2) This routine substitutes each pixel of colour1 with colour2 within a defined oblong (rectangle) starting at the named graphic point. This is useful for changing either the foreground or the background (for example) without disturbing other pixels. zzAlphaSort( Sortdata$() ) The routine sorts the items in the specified STRING ARRAY; note that the parameter MUST be a string array. The SHARED variable "SortCount" indicates how many items in the array will be sorted. Note that the "0" entry of the array is used as a work area, and should be ignored. zzBasicInt( interrupt ) This routine executes a system interrupt, using registers as defined and set in the SHARED "Regs" construct. The only parameter is an integer specifying the interrupt number: &H10 (or 16) for BIOS and &H21 (or 33) for DOS are by far the most commonly used. Many interrupts return new information in the registers, and indicate success or failure of their task with the setting of the "carry" flag. The state of the "carry" flag can be determined by the following expression.. (Regs.FL AND 256) ..which will be 0 if not set, or 256 if it is set. On first execution this routine calls "zzInPath" to load the machine code stored in "BASICINT.OVL". zzChangeDir( directory$ ) This routine makes the directory specified in the string the current directory associated with the drive on which it is found. If the directory or drive is invalid or nonexistent, there is no change and the directory$ string is replaced with a single question mark ("?"). If the change is successful the full directory path is placed in the string, even if only a partial or "shortcut" path was specified. If the directory$ string is empty, or has only a drive specification, there is no change to the "current directory" status. Instead, the path of the current directory associated with the specified (or default) drive is placed in the string. If you have two logical drives sharing a full physical unit (as A: and B: do when there is no physical second floppy drive) and you select a directory from the non-active logical drive letter, this routine will automatically substitute the active logical drive letter, and you will not get a "change drive" message. zzChangeDrive( drive$ ) This routine makes the drive specified in the string the current drive. If the drive is invalid or nonexistent, there is no change and the drive$ string is replaced with a single question mark ("?"). If the change is successful the drive letter (followed by a colon ":") is placed in the string. If the drive$ string is empty, there is no change to the "current drive" status. Instead, the letter (plus a colon ":") of the current drive is placed in the string. If you have two logical drives sharing a full physical unit (as A: and B: do when there is no physical second floppy drive) and you select the non-active logical drive letter, this routine will automatically substitute the active logical drive letter, and you will not get a "change drive" message. zzFileSelectBox( pattern$ ) This routine operates a full-screen File Select Box, based on the path and/or pattern passed as a string parameter. It offers the ability to browse around all available drives on the system, and from them select a file that matches the pattern. If no pattern is supplied, all files will be shown on the screen. This routine utilises several other routines, and makes use of the SHARED arrays "FileNames$()" and "Directories$()" and their associated counts, "FileNames" and "Directories". The string used to pass the pattern to the routine will, on exit, contain the selected file's full path (including drive), or "?" if the dialog was aborted without a selection (usually by "Esc" key). zzInPath( filename$ ) This routine verifies whether the specified file is in the current directory, or otherwise within a directory in the PATH. If it is, it substitutes the string with the full path to the file. If it is not, it sets the string to null (zero length). zzSearchD( pattern$ ) This pattern searches a specified directory for a particular pattern of subdirectory names; if no path is named, the current path is assumed. If no pattern is named, "*.*" (which means "any name") will be assumed. The results will be placed in the SHARED array "Directories$()", and the number of such resulting matches will be placed in the SHARED variable "Directories". Note that the results in the array will be sorted into alphabetic sequence. If the pattern is incorrectly formatted, or if it contains an invalid or nonexistent path, it will be replaced by "?". Otherwise the full path, including the drive, will be added to the beginning of the "wildcard" part of the pattern string. replaced by the full path, including the drive letter. zzSearchF( pattern$ ) This pattern searches a specified directory for a particular pattern of file names; if no path is named, the current path is assumed. If no pattern is named, "*.*" (which means "any name") will be assumed. The results will be placed in the SHARED array "FileNames$()", and the number of such resulting matches will be placed in the SHARED variable "FileNames". Note that the results in the array will be sorted into alphabetic sequence. If the pattern is incorrectly formatted, or if it contains an invalid or nonexistent path, it will be replaced by "?". Otherwise the full path, including the drive, will be added to the beginning of the "wildcard" part of the pattern string. zzValidate( path$ ) This routine will validate that the drive and path specified is correctly formatted, and exists. The full drive and path will be returned if it is valid, and "?" will be returned if it is not. PIECRUST SHARED VARIABLES ------------------------- Allowed$ - string of other allowed keystrokes (passed back directly) during the running of "ziWander". Bad - transferred value of trapped ERR Bank() - integer array for describing Buttons, as used by various routines (ziDrawBank, ziMouseOnButton, ziRadio) It is described by the "Buttons" TYPE construct. See the desciption of routine "ziDrawBank". bg - background colour Col - current column number (after zsAlignGCursor and zsAlignTCursor) Cols - number of columns in text mode: set by "ziSetScrnMode" and used by the "zsAlign" cursor routines. Dclick - set to tell whether double-clicks are to be specific events captured by "ziWander" (whcih can slow down general operation). 0 = no detection, 1 = detection Directories - integer count of entries within "Directories$" Directories$() - string array of directories found by zzSearchD fg - foreground colour Field$ - response area for the ziReadField routine FileNames - integer count of entries within "FileNames$"" FileNames$() - string array of filenames found by zzSearchF Font() - two-dimensional integer array containing loaded font information related to ziLoadFont and ziPublish. FoundButton - number of button on which the mouse cursor has clicked (see ziMouseOnButton routine) GXloc - X (horizontal) component of the location of the graphics cursor GYloc - Y (vertical) component of the location of the graphics cursor HResponse - the isolated high portion of "Response" LResponse - the isolated low portion of "Response" MCursorVis - visibility flag for mouse cursor; 0 = invisible, 1= visible Module$ - name of module to load via "ziLoadFont" MXloc - X (horizontal) component of the location of the mouse cursor MYloc - Y (vertical) component of the location of the mouse cursor Response - integer response to "ziWander" routine, indicating mouse and keyboard events Row - current row number (after zsAlignGCursor and zsAlignTCursor) Rows - number of rows in text mode: set by "ziSetScrnMode" and used by the "zsAlign" cursor routines. SortCount - integer count of the number of items input to "zzAlphaSort" Xmax - maximum pixel number for X (horizontal), set by zsSetScrnMode XYRatio! - ration between size of X and Y pixel increments, set by zsSetScrnMode Ymax - maximum pixel number for Y (vertical), set by zsSetScrnMode Note also the SHARED variables for registers, used in zzBasicInt: Regs.AX, Regs.BX, Regs.CX, Regs.DX, Regs.DS, Regs.SI, Regs.ES, Regs.DI, Regs.FL These are used for interfacing to DOS and BIOS interrupts. PIECRUST CONSTANTS ------------------ DegToRad! = .0174533 (the multiplication factor to convert degrees to radians) Ex! = 2.71828 (e - the exponential constant) Pi! = 3.14159 (pi) RadToDeg! = 57.2958 (the multiplication factor to convert radians to degrees) NOTE: the following all apply to the interpretation of the results from "ziWander" ziBoth = 3 (match with LResponse to determine "both buttons") ziBothDrag = 6 (match with LResponse to determine "both drag") ziBS = 5 (match with LResponse to determine "backspace") ziCTRL = &H2 (match with HResponse to determine Ctrl shift) ziCTRLFn = &H20 (match with HResponse to determine Ctrl/Function) ziDbl = 0 (match with LResponse to determine "double-click") ziDn = 4 (match with LResponse to determine "down") ziEnd = 7 (match with LResponse to determine "end") ziEsc = 11 (match with LResponse to determine "escape") ziFn = &H10 (match with HResponse to determine Function key) ziHome = 6 (match with LResponse to determine "home") ziL = 1 (match with LResponse to determine "left") ziLDrag = 4 (match with LResponse to determine "left drag") ziMouse = &H8 (match with HResponse to determine a mouse event) ziNoShift = &H1 (match with HResponse to determine no shift) ziPgDn = 9 (match with LResponse to determine "page down") ziPgUp = 8 (match with LResponse to determine "page up") ziR = 2 (match with LResponse to determine "right") ziRDrag = 5 (match with LResponse to determine "right drag") ziShiftFn = &H40 (match with HResponse to determine Shift/Function) ziTab = 10 (match with LResponse to determine "tab") ziUp = 3 (match with LResponse to determine "up") Also an array named "Shades" is available, each entry being a "tile" constant for a PAINT directive, instead of a colour. The entries are in the form: Shades(m, n) ..where m is a colour number 1 to 7 (1 = blue; 2 = green; 3 = cyan; 4 = red; 5 = magenta; 6 = yellow; 7 = white) ..and n is a shade number 0 to 4 (0 = darkest, 4 = brightest) Note that although entries in "Shades" are all strings, you do NOT use the "$" notation on the word "Shades". OTHER NOTES ABOUT PIECRUST OPERATION ------------------------------------ Two modules with the extension "OVL" are required as Piecrust is normally presented: one facilitates a font for the "ziPublish" routine, and the other furnishes the code for the "zzBasicInt" routine. These are called "ASCII8X8.OVL" and "BASICINT.OVL". They must be present, but not necessarily in the current directory: they may be in any directory in the PATH. Piecrust starts by seeding the random-number generator and testing for the presence of a mouse. This itself activates the "zzBasicInt" routine, loading its "OVL" module. If there is a mouse present the local variable "Mouse" is set to 1, but the mouse is NOT activated. If you want the mouse activated, execute the command: CALL ziSetMCursorVis( 1 ) ------------------------- Piecrust then loads the ASCII 8 x 8 font (from an "OVL"). There is a special error trap within Piecrust code needed when a specified "OVL" module cannot be found. This is left in place and active for the convenience of the programmer, though you may turn it off if you desire by executing "ON ERROR GOTO". The installed trap will pass back control normally, but set the SHARED variable "Bad" to the value of ERR when the error occurred (which itself is lost). After sensitive instructions - or after arithmetic instructions that are susceptible to overflow - you may wish to inspect and reset "Bad". SUB Function Crossreference Table for PIECRUST ---------------------------------------------- SUB Called by.. Calls.. --- ----------- ------- base ziLoadFont ziSetMCursorVis zzBasicInt ziDrawBank ziRadio ziSetMCursorVis ziDragging ziExhaust zzBasicInt ziExhaust ziDragging zzBasicInt ziWander ziLoadFont base zzInPath ziLocateMCursor ziSetMCursorVis zzBasicInt ziPublish ziPublishHere ziSetMCursorVis zsLocateGCursor ziPublishHere zzFileSelectBox ziPublish zsAlignGCursor zsAlignTCursor ziRadio ziDrawBank ziReadField ziSetMCursorVis ziSetMCursorVis base zzBasicInt ziDrawBank ziLocateMCursor ziPublish ziReadField zsPastel zsSetScrnMode zsSubstitute ziWander ziExhaust zzBasicInt zsAlignGCursor zsAlignTCursor zsLocateGCursor zzFileSelectBox zsAlignTCursor zsAlignGCursor zsLocateGCursor ziPublish zsAlignGCursor zsPastel ziSetMCursorVis zsSetScrnMode zzFileSelectBox ziSetMCursorVis zsSubstitute ziSetMCursorVis zzAlphaSort zzSearchD zzSearchF zzBasicInt base zzInPath ziDragging ziExhaust ziLocateMCursor ziSetMCursorVis ziWander zzChangeDir zzChangeDrive zzCritOff zzCritOn zzFileSelectBox zzSearchD zzSearchF zzValidate zzChangeDir zzFileSelectBox zzBasicInt zzValidate zzChangeDrive zzValidate zzBasicInt zzCritOff zzCritOn zzCritOff zzChangeDrive zzBasicInt zzFileSelectBox zzSearchD zzSearchF zzValidate zzCritOn zzChangeDrive zzBasicInt zzFileSelectBox zzSearchD zzSearchF zzValidate zzFIleSelectBox ziPublish zsAlignGCursor zsSetScrnMode zzBasicInt zzChangeDir zzCritOff zzCritOn zzSearchD zzSearchF zzValidate zzInPath ziLoadFont zzBasicInt zzSearchD zzFileSelectBox zzAlphaSort zzBasicInt zzCritOff zzCritOn zzValidate zzSearchF zzFileSelectBox zzAlphaSort zzBasicInt zzCritOff zzCritOn zzValidate zzValidate zzFileSelectBox zzBasicInt zzSearchD zzChangeDir zzSearchF zzChangeDrive zzCritOff zzCritOn Digest of BIOS and DOS INTERRUPTS used within "PIECRUST" -------------------------------------------------------- Int Function --- -------- 21 0Exx Set current drive input: AX 0Exx DX xxNN where NN=drive-1 (A=0, B=1 etc) output: AX xxNN where NN=LASTDRIVE value 21 19xx Get current drive input: AX 19xx output: AX xxNN where NN=drive-1 (A=0, B=1 etc) 21 1Cxx Get drive data input: AX 1Cxx DX xxNN where NN=drive (A=1, B=2, etc) or 00 (current drive) output: AX xxNN where NN=sectors/cluster, or FF if invalid BX ptr to Media Descriptor CX bytes/sector DX clusters DS seg to Media Descriptor 21 25xx Set interrupt vector input: AX 25NN where NN=interrupt to be revectored DX ptr to new interrupt handler routine DS seg to new interrupt handler routine 21 2Fxx Get DTA (Disk Transfer Address) input: AX 2Fxx output: BX ptr to DTA ES seg to DTA 21 35xx Get interrupt vector input: AX 35NN where NN=interrupt wanted output: BX ptr to current interrupt handler routine ES seg to current interrupt handler routine 21 3B00 Change current directory input: AX 3Bxx DX ptr to ASCIIZ string of new directory name DS seg to ASCIIZ string of new directory name 21 440E Get logical drive map entry input: AX 440E BX xxNN where NN=drive number (A=1, B=2, etc) or NN=0 (current drive) output: if carry flag=0 AX xxNN where NN = 0 if device unshared or NN = current logical if carry flag=1 AX error code For example if BX=1 on input but 2 was returned in AX, then the drive exists, but is currently being called "B:" rather than "A:" 21 47xx Get current directory input: AX 47xx DX xxNN where NN=drive number (A=1, B=2, etc) or NN=0 (current drive) SI ptr to 64-byte buffer DS seg to 64-byte buffer output: if carry flag=0 buffer contains ASZIIZ path (no base "\") if carry flag=1 AX error code 21 4Exx Find first match input: AX 4Exx CX 00NN where NN=additional attributes 01=readonly 02=hidden 04=system 08=volume ID 10=directory (this is "additive": eg 07 will count readonly, hidden and system files as candidates) DX ptr to ASCIIZ string containing pattern DS seg to ASCIIZ stromg containing pattern output: AX error code if carry set DTA contains results if carry not set Note: the following information is in the DTA disp length &H15 BYTE Attributes of matched element &H16 INTEGER TIME as HHHHHMMM MMMSSSSS where SSSSS is HALF the seconds &H18 INTEGER DATE as YYYYYYYM MMMDDDDD where YYYYYYY is added to 1980 &H1A LONG Size of file &H1E STRING ASCIIZ string (up to 13 long) containing the element name 21 4Fxx Find next match (following function 4E repeatedly) input: AX 4Fxx DTA must be left as output by preceding 4E output: as for 4E 33 0000 Reset mouse and provide status input: AX 0000 output: AX status (0=no mouse) BX number of buttons 33 0001 Show mouse cursor input: AX 0001 33 0002 Hide mouse cursor input: AX 0002 33 0003 Get mouse cursor position and button status input: AX 0003 output: BX status (0=no button down; 1=left down; 2=right down; 3=both down) CX horizontal position DX vertical position 33 0004 Set mouse cursor position input: AX 0004 CX = horizontal position DX = vertical position 33 002A Get mouse cursor hotspot input: AX 002A output: BX cursor hotspot column CX cursor hotspot row DX mouse type (0=none; 1=bus; 2=serial; 3=InPort; 4=IBM; 5=HP)