BasicBasic is copyright (c) 1992, 1993 by Mark Davidsaver. All rights reserved. LICENSE INFORMATION ------------------------------------------------------- This shareware version of BasicBasic may be distributed to others subject to the following 2 conditions: 1) Only a nominal fee, not to exceed $5.00, may be charged for distribution. 2) The following files must ALL be distributed UNALTERED. ORDER.DOC BB.DOC BBE.EXE BB.EXE BB150.STB BBL150.EXE WBBE.EXE WBB.EXE WBBL150.EXE WBB.FON BBICON.EXE SAMPLE1.BAS SAMPLE2.BAS SAMPLE3.BAS SAMPLE4.BAS SAMPLE5.BAS SAMPLE6.BAS SAMPLE7.BAS SAMPLE8.BAS SAMPLE9.BAS SAMPLE10.BAS SAMPLE11.BAS SAMPLE12.BAS SAMPLE13.BAS SAMPLE14.BAS SAMPLE15.BAS SAMPLEW1.BAS SAMPLEW2.BAS SAMPLEw3.BAS SAMPLE14.ICO SAMPLE15.WAV SAMPLE14.BMP The software and accompanying documentation are provided "as is" without warranty of any kind. The entire risk as to the results and performance of the software is assumed by you. This special shareware version limits the size of the program you can compile. Copyright (c) 1992, 1993 by Mark Davidsaver TABLE OF CONTENTS Summary ................................ 2 Getting Started Quickly ................ 5 DOS Instructions ..... ................. 7 Windows Instructions ..... ............. 11 Statement and Function Reference ....... 15 Graphics Programming for Beginners ..... 57 Programming Buttons .................... 60 Programming Menus ...................... 62 Programming Windows(for DOS or Windows). 64 Programming Dialog Boxes ............... 66 Windows Graphics Printing .............. 72 Program Icon ........................... 75 Communications Programming ............. 77 Windows and Graphics ................... 78 Bitmaps ................................ 82 Creating Fonts ......................... 86 Chaining and Common .................... 90 BasicBasic Technical ................... 91 Windows Metacommands ................... 93 Metacommands ........................... 94 Seperate Compilation ................... 95 Default Windows Font.................... 97 (386 Enhanced Mode Font information) Errors ................................. 99 Keyboard codes ........................ 101 1 Copyright (c) 1992, 1993 by Mark Davidsaver SUMMARY ------------------------------------------------------- BasicBasic is an easy to use program development system for DOS or Windows. You can use BasicBasic to make your own programs. BasicBasic creates EXE files which can be run under DOS or Windows. BasicBasic supports both graphics and text screens. BasicBasic supports many commands common to other Basic compilers, as well as, many new commands unique to BasicBasic. For example, BasicBasic can output high quality sound files under Windows or DOS (if sound board present). Programs written using BasicBasic can run under either DOS or Windows. The BasicBasic development system, itself, may run under either DOS or Windows. Here is a list of statements and functions the BasicBasic compiler recognizes. Refer to the detailed description later on for the exact syntax recognized. PROGRAM CONTROL CALL FUNCTION...END FUNCTION DECLARE GOSUB...RETURN DO...LOOP GOTO EXIT DO IF...THEN...ELSE...ENDIF EXIT FUNCTION STOP EXIT SUB SUB...END SUB FOR...NEXT SYSTEM SCREEN OUTPUT CLS PRINT CSRLIN PRINT USING LOCATE SCROLLAREA POS TAB KEYBOARD AND MOUSE INPUT INKEY$ MOUSEON INPUT MOUSEX MOUSEB MOUSEY GRAPHICS BITMAPC PALETTE BITMAPH POINT CIRCLE PRESET COLOR PSET GET PUT LINE SCREEN LOADBITMAP STOREBITMAP PAINT 2 Copyright (c) 1992, 1993 by Mark Davidsaver STRING CHR$ RIGHT$ INSTR SPACE$ LEFT$ STR$ LEN STRING$ MID$ UCASE$ SOUND BEEP SOUND PLAYSOUND SNDDEV DIALOG DIALOG OPENFILEREAD DIALOG$ OPENFILESAVE MESSAGEBOX MENU ADDSUBMENU MENUITEMON MAINMENU MENUITEMGRAY BUTTON CBUTTON DBUTTON CHECKOFF RADIOON CHECKON RADIOOFF PRINTER COMMANDS LPRINT LPRINT USING FILE INPUT/OUTPUT CHDIR LINE INPUT # CHDRIVE LOC CLOSE # LOCK DIR$ LSET CURDIR$ MKDIR EOF OPEN FIELD PRINT # GET # PUT # INPUT$ RMDIR INPUT # UNLOCK KILL WRITE # DATA DEFINITION COMMON READ DATA RESTORE DIM ARITHMETIC ABS RAMDOMIZE ASC RND ATN SIN COS SQR FIX TAN 3 Copyright (c) 1992, 1993 by Mark Davidsaver INT VAL IRND DOS AND EXTERNAL COMMANDS CHAIN OSTYPE COMMAND$ SHELL DATE$ TIME$ FREEMEM TIMER SCREEN WINDOW COMMANDS CREATEWINDOW SELECTWINDOW DESTROYWINDOW FONTS CREATEFONT FONT DLEN SELECTFONT FONT$ SERIAL COMMUNICATIONS COMSTATI OPEN "COMn" SPECIAL MICROSOFT WINDOWS COMMANDS CREATEBITMAP PRINTCONTROL COPYBITS SELECTBITMAP ON CLOSE SELECTDISPLAY ON PAINT SELECTPRINT POSITION SELECTWINDOW STRETCHBITS MISCELLANEOUS LET REM SETERRLEVEL and the operators + - / * \ ^ AND OR MOD 4 Copyright (c) 1992, 1993 by Mark Davidsaver GETTING STARTED QUICKLY ------------------------------------------------------- The easiest way to run BasicBasic is to have all required files in one directory. Create a directory and copy the supplied files into the directory. BasicBasic files required for each operating environment are: FILE USE _____ __________________________________ BBE.EXE \ BB.EXE |- required under DOS BB150.STB | BBL150.EXE / WBBE.EXE \ WBB.EXE |- required under Windows BB150.STB | WBBL150.EXE | BBICON.EXE | WBB.FON / In addition many sample programs are provided to let you get started quickly. The sample programs have file names of the format SAMPLEnn.BAS. In addition an Icon (.ICO) and Bitmap (.BMP) file are provided for use by the sample programs. The best way to install BasisBasic is to copy ALL supplied files to your BasicBasic directory. If you are new to programming, or new to BasicBasic, it is a good idea to start out by compiling and running these sample programs. If you are new to Basic programming a good second step is to try modifying the sample programs to operate differently. SAMPLE1.BAS SAMPLE2.BAS\__ Examples applicable to DOS and Windows SAMPLE3.BAS/ . . SAMPLEW1.BAS SAMPLEW2.BAS __ Examples For Windows Only . . DOS Startup: To start the BasicBasic development system under DOS you 5 Copyright (c) 1992, 1993 by Mark Davidsaver must first be in the directory you placed the BasicBasic files in; then type 'BBE' at the DOS prompt. WINDOWS Startup: To start the BasicBasic developement system under Windows you must run the program WBBE. You can do this from the Program Manager File menu. Alternately you can install WBBE in a program group using the Program Manager and then start it by double clicking on it's icon. Once started you are in the BasicBasic edit mode and can type in programs from the keyboard or read them in from disk. When ready you can tell BasicBasic to run the program. The program will run and then control will be returned to the BasicBasic editor. The following sections provide a more detailed description of how to operate in the BasicBasic development system. 6 Copyright (c) 1992, 1993 by Mark Davidsaver DOS INSTRUCTIONS ------------------------------------------------------- BasicBasic allows you to write programs using the BASIC programming language. This programming language works the same in DOS or Windows. The BasicBasic editor which allows you to enter your program is slightly different in DOS and Windows. This section contains specific instructions on using the DOS version of BasicBasic. The next section contains similar instructions for Windows. (Note: If you do not want to use the BasicBasic editor, you do not have to. See the section on Seperate Compilation for instructions on compiling programs entered with another editor) This section assumes you have installed all required files in one directory as described in the preceding section 'Getting Started Quickly'. It also assumes that you have Changed Directories so that the BasicBasic directory is the current directory. To start BasicBasic you type BBE< (< means Enter) BasicBasic will then setup the screen in the following format: --------------------------------------------- 1 | file name line | 2 | Function summary line | 3 | | . . . . . . . . . 25 | Error line | --------------------------------------------- The top line (line 1) displays the name of the currently opened file. When you first start BasicBasic no file will be opened so the top line displays the name of the program. The second line contains a list of the most commonly used funtion keys. The bottom line (line 25) displays any errors which occur during compilation. Lines 3 through 24 are used for display/editing of your program. The DOS version of BasicBasic does not use a mouse for editing functions (though, if you have a mouse, you can use it in the programs you write). All editor operations are available with a combination of keyboard keys. The best way to learn to use any editor is to use it. The BasicBasic editor is fairly straight-forward. F1 will 7 Copyright (c) 1992, 1993 by Mark Davidsaver bring up a list of all special key combinations. F3 opens a file for editing or compiling. F8 compiles a program. F9 runs a program (and compiles, if necessary). These are the most common special keys you will use. At this point open and compile or run some of the supplied sample programs (e.g. SAMPLE1.BAS). F3-OPEN will ask you to enter the name of the program you want to open. You can either type in the file name, including the extension, or use the TAB key to select a file from the file list box. You use the up and down arrow keys to scroll through the file list box. Remember that if you type in the file name you MUST supply the complete name, including extension (e.g. SAMPLE1.BAS). Here is a description of the editor special keys: Insert Toggles between Overtype/Insert modes F1 Help Displays a list of editor special keys F2 New Closes any currently open file and clears the screen. You will be prompted to save any changes. F3 Open Displays a box to allow you to open a file. You may either type in the complete file name or TAB to a file list box and select file with the arrow keys. After highlighting the file you want press ENTER. F4 SaveAs Allows you to save the text you are editing and specify a file name. Ctrl-F4 Save Saves the text you are editing to the same name you originally opened. F5 Exit Exits the program. You will be prompted to save any changes. F6 Find Displays a box to allow you to enter text to find. Upper/lower case are ignored. The search is from the current position in the file. To search the entire file you must have the start of the file displayed on the screen. The found string will be highlighted and the display altered to show the highlighted item on the first display line. If no match is found a 'BEEP' will be sounded. Ctrl-F6 Find Next Searches for the next occurence of the 8 Copyright (c) 1992, 1993 by Mark Davidsaver last search string you entered. F7 Next Error If you have compiled a program and there were errors in the compilation, then the bottom line of the display will display the error message. If there is more than one error pressing F7 will go to the next error message. When an error message is displayed, the corresponding source line will be moved to the first display position if applicable. F8 Compile Compiles your current source and makes an EXE file if there are no errors. F9 Compile & Run Compiles your current source(only if required) and then executes the program. When your program terminates you will return to the editor. F10 About Tells about BasicBasic. Up arrow Down arrow Left arrow Right arrow Moves cursor around the screen. Insert Changes between insert mode(small cursor) and overwrite move (large cursor) Delete Deletes current character Ctrl-PgUp Goes to first line of file. Ctrl-PgDn Goes to last line of file. Shift-arrow key Holding down the shift key while pressing an arrow key will select text for copying or cutting. Shift-Delete Copies currently selected text to clipboard. Ctrl-F1 If text is selected deletes all of selected text and transfers to clipboard. Shift-insert Pastes from clipboard to screen. Home Moves to beginning of line. End Moves past last character in line. 9 Copyright (c) 1992, 1993 by Mark Davidsaver RUNTIME ERRORS While executing a program you have entered you may receive a runtime error message. The message will have two numbers; the first being an error number and the second being a runtime error address. This manual contains a list of error numbers. The runtime error address will show you what line had the error. Each time you compile your program BasicBasic creates a file which shows the runtime address for each line. You can examine this file with the BasicBasic editor to find which line contains the address the address at which the runtime error occurs. The file BasicBasic creates has the extension .TMP. For example if you compile the program SAMPLE1.BAS, then BasicBasic will create the file SAMPLE1.TMP, which will have the runtime addresses. (Occasionaly you might want to delete all .TMP files from your BasicBasic directory to conserve disk space.) TOO BIG If you write very large programs there may not be room in memory to compile your program while the editor is running. If you receive an error message saying not enough memory to compile you may need to exit the editor and compile seperately. See the section on Seperate Compilation for instructions. IMPORTANT: To run programs compiled with BasicBasic the runtime module must be present. For DOS this is the file BBL150.EXE. 10 Copyright (c) 1992, 1993 by Mark Davidsaver WINDOWS INSTRUCTIONS ------------------------------------------------------- BasicBasic allows you to write programs using the BASIC programming language. This programming language works the same in DOS or Windows. The BasicBasic editor which allows you to enter your program is slightly different in DOS and Windows. This section contains specific instructions on using the Windows version of BasicBasic. The preceding section contains similar instructions for DOS. (Note: If you do not want to use the BasicBasic editor, you do not have to. See the section on Seperate Compilation for instructions on compiling programs entered with another editor) You may install the BasicBasic program in a program group. The file you want to install is WBBE.EXE. Alternately you can select RUN from the program manager and execute WBBE.EXE. Once started you will see a standard Windows editing screen. There is a menu bar at the top with available choices. To compile and run a program (such as SAMPLE1.BAS) you would need to select OPEN from the file menu and then COMPILE & RUN from the Build menu. Remember that you must enter the complete file name, including extension (e.g. SAMPLE1.BAS). The best way to learn any editor is to use it. The BasicBasic editor is fairly straight-forward. The FILE menu contains an Open command. The MAKE menu contains commands to compile and run your program. Here is a complete list of the Windows BasicBasic editor functions.: Insert Key Toggles between Overtype/Insert modes FILE MENU New Closes any currently open file and clears the screen. You will be prompted to save any changes. Open Displays a box to allow you to open a file. You may either type in the complete file name or TAB to a file list box and select file with the 11 Copyright (c) 1992, 1993 by Mark Davidsaver arrow keys. After highlighting the file you want press ENTER. SaveAs Allows you to save the text you are editing and specify a file name. Save Saves the text you are editing to the same name you originally opened. Exit Exits the program. You will be prompted to save any changes. EDIT MENU The edit menu allows you to manipulate text you have selected. You select text in the usual Windows fashion by holding down the mouse button as you move over the text you want to select. Alternately you can use the arrow keys with the SHIFT key held down. Copy Copies currently selected text to clipboard. Cut If text is selected deletes all of selected text and transfers to clipboard. Paste Pastes from clipboard to screen. SEARCH MENU Find Displays a box to allow you to enter text to find. Upper/lower case are ignored. The search is from the current position in the file. To search the entire file you must have the start of the file displayed on the screen. The found string will be highlighted and the display altered to show the highlighted item on the first display line. If no match is found a 'BEEP' will be sounded. Find Next Searches for the next occurence of the last search string you entered. MAKE MENU Compile Compiles your current source and makes an EXE file if there are no errors. 12 Copyright (c) 1992, 1993 by Mark Davidsaver Control is returned to BasicBasic when the compilation is complete. Compile & Run Compiles your current source(only if required) and then executes the program. If there are compilation errors the program will not be executed. When your compiled program is run it's window will be made the top window, but the BasicBasic editor will continue to run. OPTIONS MENU In there are errors in compilation BasicBasic will display an error windows at the bottom of the edit windows. You can scroll through this window to examine errors. Selecting an error in the error window will cause the corresponding source line to become the first line in the edit window. The Options Menu contains an item, 'Error Window' which will remove the error window when you no longer need the errors displayed. TRANSFER MENU The transfer menu contains one entry. This is the 'Icon Editor'. Using the $ICON metacommand you can assign a Windows Icon to your program. The icon editor allows you to create the icon. See the section on 'Program Icon' for more information. RUNTIME ERRORS While executing a program you have entered you may receive a runtime error message. The message will have two numbers; the first being an error number and the second being a runtime error address. This manual contains a list of error numbers. The runtime error address will show you what line had the error. Each time you compile your program BasicBasic creates a file which shows the runtime address for each line. You can examine this file with the BasicBasic editor to find which line contains the address the address at which the runtime error occurs. The file BasicBasic creates has the extension .TMP. For example if you compile the program SAMPLE1.BAS, then BasicBasic will create the file SAMPLE1.TMP, which will have the runtime addresses. (Occasionaly you might want to delete all .TMP files from your BasicBasic directory to conserve disk space.) 13 Copyright (c) 1992, 1993 by Mark Davidsaver TOO BIG If you write very large programs there may not be room in memory to compile your program while the editor is running. If you receive an error message saying not enough memory to compile you may need to exit the editor and compile seperately. See the section of Seperate Compilation for instructions. IMPORTANT: To run programs compiled with BasicBasic the runtime module must be present. For Windows this is the file WBBL150.EXE. 14 Copyright (c) 1992, 1993 by Mark Davidsaver STATEMENT AND FUNCTION REFERENCE ------------------------------------------------------- Here is a brief description of available functions and statements. More detailed information on those not unique to BasicBasic can be found in standard Basic reference books. ABS(numericexpression) This function returns the absolute value of the numeric expression. ADDSUBMENU menunumber,stringexpression,keycode Addsubmenu adds an item to a pull down menu with the text stringexpression. When the user selects this menu item the keycode will be returned at the next INKEY$ function call. See the section 'Programming Menus' for more details ASC(string expression) This function returns a numerical value which is the ASCII code for the first character of string expression. ATN(numeric expression) This function returns the arctangent of a numeric expression. BEEP This statement sounds the ASCII bell character. BITMAPC(filename,longinteger array) This function returns colors values for a disk file device independent bitmap. e.g. A=BITMAPC("C:\WINDOWS\CARS.BMP",COLORS&(0)) 15 Copyright (c) 1992, 1993 by Mark Davidsaver Each element of the array COLORS& will contain one RGB color value up to the total colors available (see BITMAPH). See the section BITMAPS for further information. BITMAPH(filename,longinteger array) This function returns the bitmap header from a file device independent bitmap. e.g. A=BITMAPC("C:\WINDOWS\CARS.BMP",HEADER&(0)) The data returned are: 0 - size of bitmapinfoheader 1 - width in pixels 2 - height in pixels 3 - always 1 4 - color bits per pixel 5 - compression flag 6 - total bytes in image See the section BITMAPS for further information. CALL name [arguments] This statement transfers control to a BASIC SUB procedure. Arguments may be any valid BasicBasic data type. Arrays are specified with empty parenthesis. here is an example of a CALL statement. a=2 b=3 call sum(a,b) stop sub sum(x,y) print x+y end sub The EXIT SUB statement may be used to exit a procedure at any time. You may not transfer control out of the prodecure except with the END SUB or EXIT SUB statements. In this version of BasicBasic procedures do not have access to common variables. 16 Copyright (c) 1992, 1993 by Mark Davidsaver CBUTTON "name",keycode,0,"type",0,left,top,xsize,ysize, forecolor,backcolor This command defines and creates a button on screen. This command is DOS and Windows compatible. In screen mode 0 left,top,xsize,ysize are in character units. In graphics screen modes these must be supplied in pixel units. The name is the text which will be displayed in the button. When you define a button you must define the keycode which will be returned when that button is pressed by the user. Legal button types are "Radio", "Push" or "Invisible". Left, top, xsize, ysize define the position and size of the button(in character position). Radio buttons may have a foreground and background color defined. If these are left 0 then the default colors will be used. In DOS the colors are also used for Pushbuttons. When the user presses the button the indicated keycode will be returned to the INKEY$ function. If a button is pressed while executing the INPUT command the input will be ended, but the keycode will not be returned until a subsequent INKEY$ function is called. Instead of using the mouse to press the indicated button, the user can also press the keyboard key which returns the indicated keycode. Any key may be defined for a button. See the section "Keyboard codes" for a list of codes recognized by BasicBasic. As an example the uppercase letter 'A' would be the keycode 65. Extended keycodes are indicated by adding 1000 to the second part of the code. For example F1 would be 1059, or F10 would be 1068. e.g. CBUTTON "Exit",1068,"Push",0,1,1,8,1,7,4 Creates a push button on the top line. Because it is a Push button the color values are ignored in windows, but used in DOS. See RADIOON and RADIOOFF and CHECKON and CHECKOFF for instructions on checking/unchecking radio and check buttons. See the section "Programming Buttons" for more detail on programming buttons. Note that while CBUTTON creates a button it will not respond to the mouse button until the function MOUSEON 17 Copyright (c) 1992, 1993 by Mark Davidsaver has been issued. SAMPLE5.BAS and SAMPLE6.BAS use the CBUTTON command. CHAIN filespec This command transfers control from the current program to another program. COMMON may be used to pass variables between programs. Files are left open when transfering to another program. See the section 'Chaining and Common' for more details. e.g. CHAIN "TEST2.EXE" CHDIR drive$ This statement changes the default directory for the specified drive. CHDIR statement changes the default directory, but not the default drive. CHDRIVE drive$ This statement changes the current drive to that given in the string expression drive$ CHECKON keycode This command 'checks' the indicated Check button. See the section "Programming Buttons" for more information. CHECKOFF keycode This command 'unchecks' the indicated Check button. See the section "Programming Buttons" for more information. CHR$(numeric expression) This function returns the ASCII code for the numeric expression. The returned code is one character. CIRCLE [STEP](x1,y),radius,[color],[start],[end],[aspect] 18 Copyright (c) 1992, 1993 by Mark Davidsaver This statement draws a circle, ellipse, or pie section on the graphics screen. (x,y) are the screen coordinates of the center of the figure. Radius is the radius in pixels. Start and End are angles in radians. Omiting these results in a complete circle or ellipse. You may use Start,End to draw arcs or pie sections. A complete circle has a start randian of 0 and an end radian of 6.2832. If start or end are negative the value is converted to a positive number for purposes of drawing the arc, but then a line is drawn from the center of the figure to the end point of the arc. PIE figures may be draw in this way. Example of a complete circle, radius 50, color blue SCREEN 8 CIRCLE (100,100),50,1 Example of pie figure, filled in SCREEN 8 CIRCLE (100,100),50,1,-.01,-2 PAINT (102,98),1,1 Aspect can be used to adjust the ratio of y radius to the x radius. By default BasicBasic sets aspect to a number to create round circles for the type of screen being used. CLOSE #filenumber This statement terminates I/O to the indicated filenumber. Only one number allowed for each CLOSE command. CLS This statement clears the screen. If a scrollable area has been define the entire screen is still cleared. COLOR foreground,background The format of this statement varies depending on the screen mode you are in. 19 Copyright (c) 1992, 1993 by Mark Davidsaver MODE 0 This statement sets the screen colors to the indicated foreground and background colors. Color values are: 0 - Black 1 - Blue 2 - Green 3 - Cyan 4 - Red 5 - Magenta 6 - Brown 7 - White 8 - Gray 9 - Light Blue 10 - LIght Green 11 - Light Cyan 12 - Light Red 13 - Light Magenta 14 - Yellow 15 - High intensity white Foreground values can be 0 through 15 and background values can be 0 through 15. MODE 8,9 The first argument (foreground color) is a color attribute. The second argument(background color) is a screen color. For Windows programs see the section WINDOWS AND GRAPHICS for additional information on the COLOR statement. MODE 12 Only one argument is used. The first argument (foreground) color is a color attribute. In this mode to change the background color for the entire screen use the PALETTE command to change the definition of color attribute 0. MODE 1000 This mode is only supported under Windows. The first argument (foreground) is a color attribute. The second arguement (background) is a color attribute. In this mode to change a palette color you must use the PALETTE command. COMMAND$ This function returns the command line used to start the 20 Copyright (c) 1992, 1993 by Mark Davidsaver program. e.g. TEST myfile.dat COMMAND$ would return: myfile.dat COMMON variablelist Common passes variables to a chained program. Variablelist is a list of variables and arrays whose contents will be preserved when Chaining to a new program. Only 'blank' common is supported. A blockname is not allowed. the SHARED attribute is not allowed. Arrays are indicated by blank parenthesis. See the section 'Chaining and Common' for more details. e.g. COMMON A,B,A$,B$() COMSTATI(comnum) This function returns the status of a communications port. 8 bits of data are returned. These are defined as follows: bit 7 = Data Carrier Detect 6 = Ring Indicator 5 - Data Set Ready 4 - Clear to Sent 3 - Break Detect 2 - Framing Error 1 - Parity Error 0 - Overrun Error e.g. a=COMSTATI(1) COPYBITS sbm,sx,sy,xlen,ylen,dbm,dx,dy,0 This command is ignored under DOS. This command copies the contents of a memory bitmap to another bitmap, display or printer. The parameter sbm is the source bitmap number and may be either 1 or 2, where 1 and 2 are memory bitmaps previously created with the CREATEBITMAP command. Similarly dbm is the destination bitmap number. It may be either 1,2 or PRINTER or DISPLAY. Sx, sy are the coordinates of the upper left corner of the source bitmap to be transfered. Xlen, and ylen are the number of pixels to copy. Dx, dy are the coordinates of the upper left corner of the destination. 21 Copyright (c) 1992, 1993 by Mark Davidsaver The following example copies a 100 by 100 pixel rectangle starting at 0,0 from a memory bitmap to the screen at x=200 and y=0. sx=0 sy=0 dx=200 dy=0 copybits 1,sx,sy,100,100,0,dx,dy,0 When copying to a printer from a bitmap the copy starts from the lower left corner instead of the upper left corner as is true when copying to the display. COS(n) This function returns the cosine of an angle expressed in radians. CREATEBITMAP n,0,xsize,ysize This command is ignored under DOS. Under Windows it creates a memory bitmap of the given size. The first argument, n, may be either 1 or 2. The second argument must always be a 0. You can create a maximum of 2 memory bitmaps. Using the SELECTBITMAP command you can tell BasicBasic to route all screen output to a bitmap instead. Then you can use the COPYBIT command to quickly place a complex graphic on the screen. If a SCREEN command is used in the program always use CREATEBITMAP after the SCREEN command! Here is an example of a createbitmap command: pxsize=100 pysize=50 CREATEBITMAP 1,0,pxsize,pysize SAMPLEW3.BAS uses the CREATEBITMAP command. CREATEWINDOW number,0,fc,bc,leftx,topy,xlen,ylen This command creates a child window. The background is saved and will be restored when you destroy the window. Number is a window number (1 through 9). Fc is foreground color, bc is background color. For more 22 Copyright (c) 1992, 1993 by Mark Davidsaver information see the section 'Programming Windows'. CREATEFONT Allows creation of fonts in DOS or Windows. See section CREATING FONTS for a description of this command. SAMPLEW1.BAS and SAMPLE14.BAS use the CREATE FONT command. CSRLIN This function gets the current line position of the cursor(starting with 1). In graphics mode 1000 the pixel line position is returned (starting with 0). CURDIR$[(drive$)] This function returns the path currently is use for the specified drive. If the optional parameter is omitted then the path for the currently selected drive is returned. DATA This statement is used in conjuction with the READ statement to input numeric or string constants. DATE$ This function returns a string of ten characters corresponding to the current computer date. DBUTTON keycode This statement erases a button from the screen (using currently define colors) and disables input from it. The keycode should be the same as that used in the CBUTTON command. See the section "Programming Buttons" for more information on buttons. 23 Copyright (c) 1992, 1993 by Mark Davidsaver DECLARE function name[(parameters)] The DECLARE statement defines a function before the actual function is created. Before you can use a user function in your program you must either create the function (using the FUNCTION, END FUNCTION statements) or declare it with the DECLARE statement. The DECLARE statement, therefore, allows you to put your user functions someplace else other than the start of our program. The name of the function, type and number of parameters must the the same in the DECLARE statement as in the FUNCTION statement. DECLARE ADD%(A%,B%0 I%=2 J%=3 PRINT ADD%(I%,J%) STOP FUNCTION ADD%(X%,Y%) ADD%=X%+Y% END FUNCTION DESTROYWINDOW number Destroys an existing child window and restores the background. For more information see the section 'Programming Windows'. DEVICE(number) This function is ignored in DOS. This function returns the capabilities of the output device. This could be the display or, if selected, the graphics printer. The value returns depends on the number passed to the function. number function returns ------ ------------------------------ 0 Driver version number 4 width of display in millimeters 6 height of display in millimeters 8 number of horizontal pixels 10 number of vertical pixels 12 number of color bits per pixel 14 number of color planes per pixel 22 number of device fonts 24 number of supported colors 24 Copyright (c) 1992, 1993 by Mark Davidsaver 40 aspectx 42 aspecty 44 aspectxy 104 number of system palette entries 108 number of color bits/pixel DIALOG A$(),numitems,x,y,xlen,ylen,id,Header String This statement executes a Dialog. See the section "Programming Dialog Boxes" for details. The array a$() contains text which defines the dialog box. Numitems tells how many items are defined in A$(). X, y, xlen, ylen are in pixel units in graphics screen modes and character units in screen mode 0. Header String will be displayed at the top of the dialog. DIALOG$() This function returns information on a Dialog Control. See the section "Programming Dialog Boxes" for details. SAMPLE11.BAS uses the DIALOG$ command. DIM variable(subscripts),... Defines arrays. There is no default array size of 10 in BasicBasic; every array must be defined. SHARED is not supported. Arrays may not be used as subscripts in a Dimension statement. LEGAL Dimension DIM A$(10,5) DIM B%(A%) ILLEGAL Dimension DIM A$(B%(1,2),5) DIR$(path,[type]) or DIR$ This function returns file names. If no type is specified or type is set to 0 then file names not 25 Copyright (c) 1992, 1993 by Mark Davidsaver including system and hidden will be returned. If no path is specified then the next name using the previous search path will be returned. Type may be set to a non-zero value to return the names of special classes of files. type file type 1 Read Only files 2 Hidden files 3 System files 5 Directories 6 Archive bit set SAMPLE10.BAS uses the DIR$ command. DLEN (string) This function returns the length in pixels of a string. It is intended for use in Windows graphics mode but also works in DOS graphics mode. DO [UNTIL condition][UNTIL condition] This statement incombination with the LOOP statement repeats a series of statements while/until the condition is true. A LOOP command must terminate the series of statements. Alternately the while/until condition may be placed after the LOOP command. In this case the true/false checking of the condition occurs AFTER the series of statements has been executed once. Here are some examples: I=0 DO WHILE I<5 PRINT I I=I+1 LOOP I=0 DO UNTIL I>4 PRINT I I=I+1 LOOP I=0 DO PRINT I I=I+1 LOOP WHILE I<6 26 Copyright (c) 1992, 1993 by Mark Davidsaver I=0 DO PRINT I I=I+1 LOOP UNTIL I>3 The EXIT DO statement may be used to exit from a DO..LOOP series of statements. Here is an example: I=0 DO WHILE I<20000 IF INKEY$<>"" THEN EXIT DO PRINT I I=I+1 LOOP END SUB This statement is used at the end of a SUB procedure. See the CALL statement for an example. EOF(filenumber) This function tests for end-of-file. EXIT DO Statement allows exit of a DO..LOOP series. See the description of the DO statement for an explanation. EXIT FUNCTION Statement allows exit of a user Function. See the description of the FUNCTION statement for more details. EXIT SUB Statement allows exit of a user Procedure. See the description of the SUB statement for more details. FIELD #filenumber,fieldwidth AS stringvariable... 27 Copyright (c) 1992, 1993 by Mark Davidsaver This statement allocates space for variables in random-access file buffer. The filenumber is the number under which the file was opened. Fieldwidth is a number indicating the length of the field and string variable is the name of the field. Multiple fields can be defined at once. e.g. OPEN "TEST.DAT" FOR RANDOM AS #1 FIELD #1,18 AS NAME$,18 AS ADDRESS$ LSET NAME$="FRED SMITH" LSET ADDRESS$="1 MAIN STREET" PUT #1,1 CLOSE #1 FIX(numeric expression) This function returns the integer representation of the value in numeric expression. -n.x returns n-1 if x>0. FONT(n) This function returns information about a Windows font. See the section CREATING FONTS for a complete description of this function FONT$(n) This function returns information about a Windows font. See the section CREATING FONTS for a complete description of this function. FOR..NEXT FOR counter=start TO end [STEP increment] Defines a program loop. FOR I%=1 TO 100 PRINT I% NEXT I% FREEMEM 28 Copyright (c) 1992, 1993 by Mark Davidsaver This function returns the amount of global memory available to other programs. FUNCTION name,[(Paramenter list)] This statement starts a user defined function. User defined functions can perform a series of instructions and then return a single value of type String, Float, Integer, or Long Integer. A user defined function is used in an expression in the same way that a BasicBasic function is used. Functions must be defined before they can be used. Typically all functions are defined at the start of a program. They are not executed until called in an expression. name: The name of the function. The name defines what type of value is returned from the function. This name is assigned a value somewhere in the the function. parameter list: The list of variables that will be passed to the User Function. Any changes to the parameters are not returned to the calling expression. Here is an example of a function which makes all characters in a string upper case. FUNCTION UPPER$(A$) FOR I%=1 TO LEN(A$) A%=ASC(MID$(A$,I%,1)) IF A%>=96 AND A%<=96+26 THEN A%=A%-32 MID$(A$,I%,1)=CHR$(A%) END IF NEXT I% UPPER$=A$ END FUNCTION PRINT UPPER$("This will display in upper case.") The EXIT FUNCTION statement may be used to exit a function at any time. You may not transfer control out of the function except with the END FUNCTION or EXIT FUNCTION statements. In this version of BasicBasic functions do not have access to common variables. GET (x1,y1)-(x2,y2),arrayname 29 Copyright (c) 1992, 1993 by Mark Davidsaver This statement gets a range of pixels from the graphics screen and puts them into an array. The may be placed back on the screen using the PUT statement. In BasicBasic only one set of pixels may be stored in each array and storing begins with the first element of the array. e.g. DIM A%(100) GET (100,100)-(109,109),A% It is important that you dimension the array large enough to hold the pixel data. You can calculate the space required as follows: size=int(((totalpixels*bits/pixel)+1)/8)+100 Where size is in bytes. Each element of an integer array takes up 2 bytes. GET #filenumber,recordnumber,variable$ This statement allows input of data from RANDOM or BINARY files. For random files the record format and input/output buffer must previously have been assigned with a FIELD statement. The following example would read in the first record of an existing random file which is defined to have a record length of 512 bytes, of which the first 32 bytes are the first name and the second 32 bytes are the last name. After the GET statement in the example is executed the data will be in the input buffer variables FIRST$ and LAST$. After the file is closed the input buffer is cleared so data must be retrieved from the input buffer variables before closing the file. OPEN "test.dat" FOR RANDOM AS #1 LEN = 512 FIELD #1,32 AS FIRST$,32 AS LAST$ TOPREC = 1 GET #1, TOPREC IF EOF(1) THEN PRINT "NO DATA IN FILE" ELSE SAVEFIRST$=FIRST$ SAVELAST$=LAST$ END IF CLOSE #1 30 Copyright (c) 1992, 1993 by Mark Davidsaver For binary files recordnumber is an absolute byte position in the file. Data will be input to variable$. Variable$ must be set up before an INPUT to be the same size as the desired number of characters to read. The first byte of the file is number 1. OPEN "test.dat" FOR BINARY AS #1 FIRSTBYTE=1 FIRST$=SPACE$(32) LAST$=SPACE$(32) GET #1, FIRSTBYTE,FIRST$ FIRSTBYTE=FIRSTBYTE+32 GET #1, FIRSTBYTE,LAST$ CLOSE #1 GOSUB label This statement causes a branch to a subroutine. GOTO label This statement causes a jump to another program location. IF...THEN...ELSE Permits conditional execution depending on evaluation of expression. INKEY$ This function returns a character from the keyboard. INPUT[;]["promptstring"{;|,}] variablelist Executing this statement causes the program to pause and wait for input. A promptstring may optionally be printed before pausing for input. If a comma is used after the promptstring or if no prompt string is specified a question mark is displayed before waiting for input. If INPUT is followed by a semicolon, then no carriage return line feed is performed after the Enter key is pressed. 31 Copyright (c) 1992, 1993 by Mark Davidsaver INPUT #filenumber,variablelist This statement reads items from an open file to the given variables. When inputting data leading spaces will be ignored. INPUT$(n,port) This function returns a string of n characters from a communications port. If n characters are not available the function will WAIT for that many characters to arrive. To avoid 'hanging up' your program use the LOC function to find how many characters are waiting. If a communications error occurs the number of characters returned may be less than what you requested. In this case use the function COMSTATI to determine what error occured. See the section "Communications Programming" for more details. INSTR([start],expressiontosearch,searchforexpression) This function searches for the first occurence of searchforexpression in expressiontosearch and returns the position at which the match is found. If no match is found then 0 is returned. INT(numericexpression) This function returns the largest integer less than or equal to numericexpression. IRND(ilow,ihigh) This function returns a random number greater than or equal to ilow and less than or equal to high. Where ilow is less than ihigh and both are integer values less than 32769. See RANDOMIZE for resetting the random number generator or RND for another random generator function. KILL stringexpression 32 Copyright (c) 1992, 1993 by Mark Davidsaver This command deletes the file whose name is in stringexpression. LEFT$(stringexpression,n) This function returns a string of length n from the left part of stringexpression LEN(stringexpression) This function returns the number of characters in stringexpression. LET May optionally be used before assignment statements. e.g. LET I=3 LINE [STEP](x1,y1)-[STEP](x2,y2),[color],[B],[BF] This command draws a line, box, or filled box on the graphics screen. The (x1,y1), (x2,y2) arguments are the end points of the line. If a color is not specified the current foreground color will be used. The 'B' option draws a box. BF draws the box and paints the interior. LINE INPUT #,filenumber,stringvariable This statement inputs an entire line from a file. Input continues until the next carriage return. LOADBITMAP filename,0,dx,dy,sx,sy,xsize,ysize,cv,xm,ym This statement loads and displays a bitmap. The bitmap is displayed with the upper left screen coordinates at dx,dy. sx,sy are the upper left bitmap coordinates. Xsize, ysize are the length in pixels of each dimension. If cv is set to 0 then all colors in the bitmap are converted to the closest defined color for the display. If set to 1 no conversion takes place. Xm is an optional scaling factor in the x direction. A positive number is used as a multiplier for the number of x bits; 33 Copyright (c) 1992, 1993 by Mark Davidsaver a negative number is used as a divider. Xy is an optional scaling factor in the y direction. A positive number is used as a multiplier and a negative number is used as a divider. See the section BITMAPS for further information. LOC(filenumber) This function returns the current absolute byte position within a file. For a communications port it returns the number of received characters waiting in the receive buffer. LOCATE row,column,[cursor] Positions the cursor on the screen. If cursor is set to 0 then the cursor is turned off. In graphics mode 1000 row, column are pixel positions (starting with 0) rather than character positions (starting with 1). LOCK #filenumber,start,end This command allows you deny other programs access to a particular area of a file. When finished with the area of the file you MUST unlock using the UNLOCK command with the identical parameters. For random files, start and end are record numbers inclusive. For binary files, start and end are byte values starting with 1. For sequenction files the entire file is lock, regardless of any start or end values supplied. To use file locking you must have a network operating system installed or the DOS program SHARE. LOOP [WHILE condition][UNTIL condition] Statement terminates a DO..LOOP series. See the description of the DO statement for an explanation. 34 Copyright (c) 1992, 1993 by Mark Davidsaver LPRINT expressionlist [,|;] Prints the items in expression list. See PRINT for a more complete description. LPRINT USING formatstring; expressionlist[,|;] The formatstring tells how to print the items in expressionlist. See PRINT USING for a description of format string items. LSET stringvariable=string expression This command puts data into a random access file buffer. The buffer must be previously defined by a FIELD statement. The data is left justified in the field. e.g. OPEN "TEST.DAT" FOR RANDOM AS #1 FIELD #1,18 AS NAME$,18 AS ADDRESS$ LSET NAME$="FRED SMITH" LSET ADDRESS$="1 MAIN STRING" PUT #1,4 CLOSE #1 MAINMENU string1,string2...,string6,[bc,fc,gc,mc] This command defines the main menu bar. Up to six menu names may be specified. If less than six are defined, blank strings must be present. See the section 'Programming menus' for more detail. Under DOS, the optional numeric values bc,fc,gc,mc represent background color, foreground color, graycolor, and the character code of the key which calls the menu bar respectively. Under DOS if you use menus there are only 24 text lines remaining for use(lines 1-24). e.g. MAINMENU "File","Color","Options","","","" MAINMENU "File","Color","","","","",7,1,4,1067 Defines a menu bar which under DOS would have a background color of 7 and foreground color of 1 and which could be summoned by pressing F9. SAMPLE4.BAS uses the MAINMENU command. 35 Copyright (c) 1992, 1993 by Mark Davidsaver MENUITEMGRAY keycode DOS. This command 'grays' a submenu item. While gray the item cannot be selected by the user. See the section 'Programming menus' for more detail. MENUITEMON keycode This command enables a submenu item. When enable a user may select this menu item. MESSAGEBOX text,header,commandcode This command creates and displays a special type of Dialog Box. This is a very useful command. It can be used for getting yes/no type of information from the operator or displaying special information to them. The first argument (text) can be any character string and will appear inside the dialog box. The second argument (header) can be any text and appears as the caption of the dialog box. The last argument (command code) can be one of the following: commandcode result 0 0 1 button labeled "OK" will appear in the dialog box. 1 2 buttons labeled "OK" and "Cancel" appear 2 2 buttons labeled "Retry" and "Cancel" appear 3 3 buttons labeled "Yes", "No" and "Cancel" appear 4 2 buttons labeled "Yes" and "No" appear In addition you can add the following value to command code to have a special character appear. 32 ? in circle 48 ! in circle 64 i in circle Upon completion of the MessageBox you retrieve the result by accessing the function DIALOG$. The DIALOG$ function corresponding to the pressed messagebox button will be set to 1. 36 Copyright (c) 1992, 1993 by Mark Davidsaver 1 "Ok" button 2 "Cancel" button 3 "Abort" button 4 "Retry" button 5 "Ignore" button 6 "Yes" button 7 "No" button Example: MESSAGEBOX "Do you want to quit?","Exit Options",1+32 IF DIALOG$(1)="1" THEN PRINT "They pressed OK" ELSEIF DIALOG$(2)="1" THEN PRINT "They pressed CANCEL" END IF MID$(stringexpression,n,length) This function returns a string composed of length characters starting with character n in stringexpression. MKDIR stringexpression This command creates a directory specified by stringexpression MOUSEB This function returns information on whether mouse buttons are pressed. Bit 0 is 1 if left button is pressed. Bit 1 is 1 if right button is pressed. Bit 2 is 1 if middle button is pressed. e.g. b=mouseb b=b and 2 if b<>0 then print "right button is pressed." end if SAMPLE8.BAS uses the MOUSEB command MOUSEON This function intializes the mouse. It returns a -1 37 Copyright (c) 1992, 1993 by Mark Davidsaver (true) if a mouse is present. It returns 0 if no mouse is present. This function must be issued before the mouse can be used in both DOS and Windows. e.g. mouseflag=mouseon MOUSEX This function returns the x position of the mouse in character units (1 through 80) for screen mode 0 and in pixel units (0 through top) in all other screen modes. e.g. x=mousex MOUSEY This function returns the y position of the mouse in character units (1 through 25) for screen mode 0 and in pixel units (0 through top) in all other screen modes.. e.g. y=mousey ON CLOSE GOSUB line number This command is ignored under DOS. This statement defines a subroutine which will be called if the user selects CLOSE from the system menu. Most programs will not need to use this statement. However, if you keep important data in in program variables, you may want to prevent the user from terminating your program without giving them an option to save the data. When you receive control because of a close command you can either save important data and stop or execute RETURN and your program will continue running. Normally you should terminate as soon as possible after receiving control in your close routine. Here is a simple example of how this statement could be used: ON CLOSE GOSUB 1000 PRINT "Test of ON CLOSE statement..."; input z stop 38 Copyright (c) 1992, 1993 by Mark Davidsaver 1000 INPUT "Do you want to quit ";a$ IF A$="Y" OR A$="y" THEN STOP END IF RETURN It is important to be aware that Windows can call your ON CLOSE subroutine AT ANY TIME. Be very careful about using global variables in an ON CLOSE subroutine. Your main program may not expect them to be changed. ON PAINT GOSUB line number This statement defines a subroutine which handles screen updates. This statement is ignored in DOS. This statement is optional in Windows. See the section on Windows and Graphics for more detail. OPEN name FOR mode [access] [lock] AS # [LEN=reclen] This command prepares the file filename for access as number #. The filename can be a file name with or without a pathname. Modes supported are INPUT, OUTPUT, APPEND, BINARY, RANDOM. INPUT, OUTPUT, APPEND are for sequential files. RANDOM is for random-access files with fixed length records. BINARY can be used to access any byte of any file. Access types supported are READ, WRITE, or READ WRITE. This argument is optional and is only valid for BINARY and RANDOM files. READ WRITE is the default. If you specify WRITE you will get an error if you try to access a file marked as read-only by DOS. Lock parameter allows you to specify how you want to share this file with any other programs trying to use it. Allow values are: Shared Any other program may read from or write to this file. Lock Read No other program can read from this file. Lock Write No other program can write to this file. Lock Read Write No other program can rea or write to this file. 39 Copyright (c) 1992, 1993 by Mark Davidsaver If you attempt to open a file and another program already has the file opened with a contradictory lock you will get a runtime error 1052. See the SETERLEVEL statement for information on how to recover from runtime errors. To use file locking you must have a network operating system installed or the DOS program SHARE. LEN is used for random access files. It is the record length. This argument is optional. 128 is the default. e.g. OPEN "TEST.DAT" FOR INPUT AS #1 e.g. OPEN "TEST.DAT" FOR RANDOM ACCESS READ AS #1 e.g. OPEN "TEST.DAT" FOR RANDOM ACCESS READ WRITE AS #1 e.g. OPEN "T.DAT" FOR RANDOM AS #1 LEN=128 e.g. OPEN "T.DAT" FOR INPUT SHARED AS #1 e.g. OPEN "T.DAT" FOR OUTPUT LOCK READ WRITE AS #1 OPEN "COMn: speed,parity,data,stop" FOR RANDOM AS #n LEN=n This statement opens and initializes a communications port. COM1 and COM2 are supported. Supported speeds are 9600, 4800,2400,1200,and 300. Parity may be either E,O,N, or M. Data may be either 5,6,7, or 8. Stop may be either 1, 1.5, or 2. LEN is used to specify the size of the input buffer. The default is 128 bytes. For Windows programs a minimum of 2048 is suggested. Only PRINT # will output characters to an open communications port. Only INPUT$ will receive characters from a port. Communications parameters may be omitted; however, their position must be marked by commas. Default parameters are 300 baud, No parity, 8 data bits, and 1 stop bit. e.g. OPEN "COM1: 2400,E,7,1" for random as #1 len=2048 See the section "Communications Programming" for more details. SAMPLE6.BAS use the OPEN COM command. OPENFILEREAD filterstr,namestr,directorystr,titlestr 40 Copyright (c) 1992, 1993 by Mark Davidsaver This statement executes a special Dialog which allows the user to input a file name for input. See the section "Programming Dialog Boxes" for details. SAMPLE12.BAS and SAMPLEW1.BAS use the OPENFILEREAD command. OPENFILESAVE filterstr,namestr,directorystr,titlestr This statement executes a special Dialog which allows the user to input a file name for writing. See the section "Programming Dialog Boxes" for details. OSTYPE This function returns a number indicating what operating system the program is running under. 1 - DOS 2 - Windows 3.x 3 - ? PAINT [STEP](x,y),[paint],[border] This statement fills a graphics area with the color selected. (x,y) is the first point filled. It will be filled with the color specified by the attribute 'paint', if supplied. If not supplied the foreground color is used. Coloring in all directions continues until the 'border' color is encountered. If border color is not supplied the paint color is used. PALETTE attribute,color This statement allows you to change the default graphic colors provided by BasicBasic. The usage of the attribute and color arguments depends on the screen mode you are in. You can always find out your current screen mode using the SYSTEM function. For Windows programs see the section on WINDOWS AND GRAPHICS for additional information on the PALETTE statement. Here are the definition of the arguments for various screen modes: screen color. 41 Copyright (c) 1992, 1993 by Mark Davidsaver MODE 8 Attribute determines which one of the 16 color attributes you want to redefine. It is the attribute you select with the COLOR statement. In this mode you have 16 colors to choose from (0 to 15). See the COLOR statement for a listing of the colors. MODE 9 Attribute determines which one of the 16 color attributes you want to redefine. In this mode you have 64 colors to choose from (0 to 63). MODE 12 In this mode attribute determines which one of the 16 color attributes you want to redefine. In this mode the color value reflects an exact RGB definition of the color you want. If you use a variable for color it must be of type long integer. color= 65536 * blue + 256 * green + red Where blue, green, red can be from 0 to 255. PLAYSOUND filename,flag This command functions under Windows if a sound device is present and under DOS if a Soundblaster or Soundblaster compatible device is present. Under Windows this command will play the .WAV file whose name is given in filename. Under DOS this command will play the .WAV or .VOC file given in the file name. Flag can have the following values: 0 -Program execute stops until play completed. 16-Same as 0, except error returned if a sound already playing. 1 -Execution of program continues while sound is played. 17-Same as 1, except error returned if a sound is already playing. PLAYSOUND "C:\WINDOWS\TADA.WAV",1 The function SNDDEV can be used to obtain current information on the sound device present (if any). DOS information: VOC files are produced by the sound recording software provided with the Soundblaster. 42 Copyright (c) 1992, 1993 by Mark Davidsaver BasicBasic will NOT play compressed .VOC files. Only 8 bit, monaural WAV files are playable. Sound duration is limited to 65535 samples. POINT (x,y) This function returns the color of the specified graphics pixel. POS(0) This function returns the current column position of the cursor(starting with 1). In graphics mode 1000 this function returns the pixel column (starting with 0). POSITION x1,y2,xlen,ylen This statement sizes and positions a window. x1,y1 are the upper left of the window. This statement is ignored in DOS. PRESET [STEP](x,y),[color] This command sets one pixel on the screen to the specified color. By using the STEP prefix you can specify that the x,y coordinates are relative to the current position. If no color is supplied the pixel is set to the background color. PRINT expressionlist [,|;] Prints the items in expression list. PRINT with no expression results in a blank line being printed. If the expression is followed by a semi-colon (;) the next print starts immediately following this one. If the expression ends in a comma (,) the next print starts at the next print position. Print positions are at columns 1, 15, 29, etc. PRINT USING formatstring; expressionlist[,|;] 43 Copyright (c) 1992, 1993 by Mark Davidsaver The formatstring tells how to print the items in expressionlist. Any text may be in formatstring. BasicBasic only recognizes three format characters. These are pound sign (#) comma (,) and period (.). Each time a number character is found (#) one item from the expression list will be printed. e.g. PRINT USING "The answer is: ###,###.##";number PRINT #filenumber,expressonlist Prints to a file or communications port the items in expression list. PRINTCONTROL command,[parameters] This command is ignored under DOS. This command controls graphics printing under Windows. Commands are: 0 - Open Printer 1 - Open Printer and prompt operator for setup 2 - End frame 3 - End document Only command=1 has any parameters. They are parameter 1 = variable to return result of open in parameter 2 = default print from page parameter 3 = default print to page parameter 4 = minimum print from page parameter 5 = maximum print to page parameter 6 = default number of copies to print Here is an example which can print only one page, returns the result of the operation into i% and suggests 2 copies as the default printcontrol 1,i%,1,1,1,1,2 Here is an example of printing to the graphics printer under Windows: printcontrol 0 selectprint print "This will appear on printer" selectdisplay selectprint 2 selectprint 3 For more information on graphics printing see the section 44 Copyright (c) 1992, 1993 by Mark Davidsaver 'Windows Graphics Printing'. PRTJOB(n) This function returns information about an open Windows printer. The information returned is as follows: n value return 0 1 if printer open, 0 else 3 Minimum page to print 4 Maximum page to print 5 Number of copies to print PSET [STEP](x,y),[color] This command sets one pixel on the screen to the specified color. By using the STEP prefix you can specify that the x,y coordinates are relative to the current position. If no color is supplied the pixel is set to the foreground color. PUT (x,y),arrayname,action This statement places pixels stored in an array onto the screen. (x,y) is the upper left position. The x and y length placed on the screen depends on the GET statement which stored the data into the array. The action may be one of the following: XOR - Combines the pixels in the array and those on the screen using the XOR operator. This is the most common action used for motion since this automatically restores the background when done twice. XOR is the default. PSET - Transfers data erasing what is already on the screen. PRESET - Inverts data and transfers to screen erasing what is already on the screen. AND - Masks screen image with data in array. OR - Superimposes data on existing screen. 45 Copyright (c) 1992, 1993 by Mark Davidsaver For Windows use see the section WINDOWS AND GRAPHICS for more information. PUT #filenumber,recordnumber,stringexpression PUT #filenumber,recordnumber This statement is used to output data to a file opened in either BINARY or RANDOM mode. In BINARY mode the string expression will be written to the file at the byte location given by recordnumber. Recordnumber is the absolute byte number to be written, where the first byte of the file is 1. e.g. A$=SPACE$(20) PUT #1,100,A$ (writes 20 bytes starting at 100) In RANDOM mode the data in the output buffer will be written to the record number indicated. e.g. PUT #1,1 (writes to record 1) RADIOON keycode This command 'checks' the indicated Radio button. See the section "Programming Buttons" for more information. RADIOOFF keycode This command 'unchecks' the indicated Radio button. See the section "Programming Buttons" for more information. RANDOMIZE This statement initializes the random number generator. If you use the RND function you probably want to preceed it's use with the RANDOMIZE statement. Otherwise everytime your program runs you will get the same sequence of 'random' numbers. This statement has no arguments. READ variablelist 46 Copyright (c) 1992, 1993 by Mark Davidsaver Inputs a value from a DATA statement. REM Denotes a comment line and is ignored by the compiler. RESTORE label Sets position that next READ statement will input data from. RETURN Returns program execution to location immediately after last GOSUB. RIGHT$(stringexpression,n) This function returns a string of length n from the right part of stringexpression RMDIR stringexpression This command removes the directory given by stringexpression. RND This function returns one in a sequence of random numbers between 0 and 1. See IRND for a function which returns integer random numbers and RANDOMIZE for a statement to initialize the random number generator. SCREEN mode[,palette][,peflag] This statement selects the screen mode. The actual screen mode available depends on your hardware. The modes available in this version of BasicBasic are: 0 - Text Only. This is the default. 47 Copyright (c) 1992, 1993 by Mark Davidsaver 2 - 640-200 Graphics. Black and white only. 80 x 25 text format. (CGA, EGA, VGA) 8 - 640-200 Graphics. 16 colors and 16 attributes 80 x 25 text format (EGA,VGA) 9 - 640-350 Graphics. 16 colors and 16 attributes 80 x 25 text format (EGA,VGA) 12 - 640-480 Graphics. 256,000 colors and 16 attributes 80 x 30 text format (VGA) 1000 - Special mode. Supports whatever graphics resolution Windows supports or, under DOS, the highest resolution the monitor supports. Under Windows supports font generation Issueing a SCREEN 1000 under DOS results in selection of the highest available graphics mode (2, 8, 9 or 12). The Palette argument is ignored under DOS. Under Windows it allows you to select the special BasicBasic palette if set to 16, or to select the 'system palette' if set to 0. If the Palette argument is omitted then the default is 0, use the system palette. If hardware supports you can also set up to 256 for 256 color selection. See the section WINDOWS AND GRAPHICS for more detail. The peflag argument is ignored under DOS. Under Windows this flag can be set to 1 to prevent other programs from using palette entries supplied by your logical palette or 4 to specify that you do not want to use any palette entries supplied by other programs. The default value is 0 and there is seldom a reason to change this. Here are examples of how the SCREEN command might be used under Windows. SCREEN 8 -- system palette SCREEN 8,0 -- system palette SCREEN 8,16 -- special BasicBasic palette SCREEN 1000,256 -- special BasicBasic palette Under Windows if you select 256 color mode on a machine with a palette size of 256, then Windows only allows you to change 236 of the palette entries. Entries 0->9 and 246->255 are fixed and may not be changed. The fixed windows colors are different from the standard, default Basic Colors If you do not know the output capabilites of the machine your program is going to run on, use the SETERRLEVEL command to determine if a screen mode has been successful. Here is an example: 48 Copyright (c) 1992, 1993 by Mark Davidsaver SETERRLEVEL 5 ERR=0 SCREEN 12 IF ERR>0 THEN ERR=0 SCREEN 9 IF ERR>0 THEN ERR=0 SCREEN 8 IF ERR>0 THEN PRINT "GRAPHICS NOT AVAILABLE." STOP END IF END IF END IF The SCREEN command resets SCROLLAREA to entire screen. SAMPLE7.BAS uses the SCREEN command SCROLLAREA leftx,topy,rightx,bottomy This statement defines an area of the screen which is used for scrolling. This allows you to create fixed text or buttons in one area of the screen while scrolling another area. In screen modes less than 1000 Leftx, topy, rightx, bottomy are in character units and are inclusive(starting with 1). In screen mode 1000 leftx, topy, rightx, bottomy are pixel units(starting with 0). Executing the CLS command will clear the entire screen, not just the scrollable area. PRINT CHR$(12); will only clear the scrollable area. SELECTBITMAP bitmapnumber This command is ignored under DOS. Under Windows this command assigns screen output to a memory bitmap or back to the screen again. A bitmapnumber=0 signifies the screen; 1 or 2 signify one of the two possible memory bitmaps previously created with the CREATEBITMAP command. DO NOT perform input operations, define buttons, or call Dialogs while a memory bitmap is selected! The following example draws and fills rectangles on a memory bitmap and then copies it to the screen. 49 Copyright (c) 1992, 1993 by Mark Davidsaver pxsize=100 pysize=100 createbitmap 1,0,pxsize,pysize selectbitmap 1 c=1 for i=0 to 90 step 10 line (i,0)-(i+10,100),c,bf c=c+1 next i selectbitmap 0 copybits 0,0,0,100,100,1,0,0,0 SELECTDISPLAY For windows use only returns the screen as the output device. Ignored in DOS. SELECTFONT number This statement allows you to change the selected font. Valid numbers are 0 through 10. Font 0 is the default font provided by BasicBasic. Font's 1 through 10 must first be created by the user using the CREATEFONT command. SELECTPRINT Ignored under DOS. Under Windows this command selects the graphics printer as the output device. Scrolling is not active when the printer is selected. See the section 'Windows Graphics Printing' for more information. SELECTWINDOW number Makes a window the current active window. The window must already exist. All screen output will go to the selected window. You can only change from one window to another if the display is selected as the output device. For more information see the section 'Programming Windows'. 50 Copyright (c) 1992, 1993 by Mark Davidsaver SETCOM comnum,"Speed,Parity,Databits,Stopbits,dtr,rts" This statement allows you to change communications parameters for an already opened communications port. Speed, Parity, Databits, and Stopbits are described in OPEN COM. DTR may be either ON or OFF. If ON then the output data terminal ready signal will be set high. ON is the default. RTS may be either 1 or 0. If 1 then the output request to send is high. 1 is the default. Communications parameters not present will not be changed; however, a comma must mark their positions. e.g. SETCOM 1,",,7" Sets number of data bits to 7. e.g. SETCOM 1,",,,,OFF" Turns Data terminal read;y off. See the section "Communications Programming" for more information. SETERRLEVEL level This command defines what BasicBasic should do in case of runtime errors. Level must be a number (not an expression or variable). Level 7 causes execution to halted for all errors. Level 5 causes execution to continue for recoverable errors. In the latter case the global variable ERR is set to the error number. ERR may be reset with the statement: ERR=0. ERR will be reset each time an error occurs so the program must check ERR immediately after statements which may produce errors. SHELL [string] This command runs another program. String may contain an optional command string to pass to the called program. e.g. SHELL "WRITE MYFILE.WRI" Would call the application WRITE and pass it the command string MYFILE.WRI. SIN(x) 51 Copyright (c) 1992, 1993 by Mark Davidsaver This function returns the sine of an angle expressed in radians. SNDDEV(parameter) This function returns information about any sound system installed. parameter return values 0 0 = No sound system present 1 = Sound system present 1 0 = No sound playing 1 = Sound currently playing -1 0 = No sound system present 1 = Sound system present Usually you should do a SNDDEV(0) function call before attempting to do a PLAYSOUND command. The BasicBasic sound driver will look for the DOS Environment variables normally present when a Soundblaster type device is present (e.g. SET BLASTER=A220 I5). If the environment variables are not present the BasicBasic sound driver will then go look at each port address for a device which responds like a Soundblaster. If one is found it will then intialize that port for use by BasicBasic. You can tell BasicBasic to ONLY use the Soundblaster if the DOS Environment variables are present. This prevents BasicBasic from searching through the available I/O ports. To this this you use the SNDDEV(-1) call instead of SNDDEV(0). SOUND frequency,duration This command issues tones through the computer speaker. The frequency is the desired frequency in cycles per second(cps). The duration is the multiple of the clock frequency (i.e. 18.2). SPACE$(N) Returns a string of n spaces. 52 Copyright (c) 1992, 1993 by Mark Davidsaver SQR(N) This function returns the square root of N. STOP Causes the program to cease execution. STOREBITMAP 0,filename,x,y,xsize,ysize,cv,0 This statement stores the designated portion of the display to a bitmap file with the designated name. X,y are the upper left screen coordinates. If cv is set to 1 then the file will be stored in run-length-encoded compressed format if possible. See the section BITMAPS for further information. STR$(numericexpression) This function returns a string representation of the numbericexpression. STRETCHBITS sbm,sx,sy,xlen,ylen,dbm,dx,dy,dxlen,dylen,0 This command is ignored under DOS. This command copies the contents of a memory bitmap to another bitmap, display or printer. This command is similar to COPYBITS except with STRETCHBITS the image can be expanded or shrunk at the destination. You do this by making the destination size dxlen,dylen different from the source length, xlen,ylen. The parameter sbm is the source bitmap number and may be either 1 or 2, where 1 and 2 are memory bitmaps previously created with the CREATEBITMAP command. Similarly dbm is the destination bitmap number. It may be either 1,2 or PRINTER or DISPLAY. Sx, sy are the coordinates of the upper left corner of the source bitmap to be transfered. Xlen, and ylen are the source number of pixels to copy. Dx, dy are the coordinates of the upper left corner of the destination. Dxlen, Dylen are the destination number of pixels to fill. The image copied will be adjusted in size to fit the destination rectangle. 53 Copyright (c) 1992, 1993 by Mark Davidsaver The following example copies a 100 by 100 pixel rectangle starting at 0,0 from a memory bitmap to the screen at x=200 and y=0 and expands it to fill a 200 by 200 pixel area. sx=0 sy=0 dx=200 dy=0 stretchbits 1,sx,sy,100,100,0,dx,dy,200,200,0 When copying to a printer from a bitmap the copy starts from the lower left corner instead of the upper left corner as is true when copying to the display. STRING$(m,stringexpression) This function returns a string of length n. This string is composed of the first character in stringexpression. SUB This statement is used at the beginning of a SUB procedure. See the CALL statement for an example. SYSTEM (n) This function returns information on the screen depending on the value of n passed to it. This information is of most use to Windows programs. n function returns --- ---------------------------------- 1 Maximum x allowed in a graphics program 2 Maximum y allowed in a graphics program 3 Actual maximum screen size x 4 Actual maximum screen size y 5 Maximum color attribute 6 Maximum 'background color' in COLOR statement 7 Current screen mode 8 Window left position 9 Window top position 10 Window x size 11 Window y size 12 Returns 1 if window is Active Window, 0 otherwise. See WINDOWS AND GRAPHICS for more information on uses of this value. 54 Copyright (c) 1992, 1993 by Mark Davidsaver 13 DOS major version number (e.g. 5) 14 DOS minor version number (e.g. 0) 15 Windows major version number (e.g. 3) 16 Windows minor version number (e.g. 1) 17 Hardware Palette Size 18 Under Windows tells currently selected Window. TAB(numericexpression) In PRINT or LPRINT statements positions output at column position given in numericexpression. TAN(x) This function returns the tangent of an angle expressed in radians. TIME$ This function returns a string representation of the current system time. TIMER This function returns the number of seconds since midnight. UCASE$(stringexpression) This function converts all lower case characters in stringexpression to upper case and returns as new string. VAL(stringexpression) This function returns the numeric value of string stringexpression. WRITE #filenumber,expression list Write is performs the same way as Print with these 55 Copyright (c) 1992, 1993 by Mark Davidsaver exceptions: 1) Commas are inserted between all items; 2) Strings are bracketed by quotation marks. BasicBasic does not support using the Write statement to display on the screen. 56 Copyright (c) 1992, 1993 by Mark Davidsaver GRAPHICS PROGRAMMING FOR BEGINNERS ------------------------------------------------------- This section will show you the basics of graphics programming in BasicBasic. The examples given will work equally well running under DOS or Windows. Now here is your first graphics program: SCREEN 2 LINE (0,0)-(400,100) INPUT Z This program draws one diagonal line on the screen. The key to graphics programming is the SCREEN command. You must issue a SCREEN command to tell BasicBasic that you are going to do graphics. Screen 2 puts your screen into a graphics mode with 640 dots (pixels) across and 200 dots down. Each dot is either white or black. Most of our examples will use SCREEN 8, which has the same number of dots, but 16 colors. If you are running on a CGA display, SCREEN 2 is the only graphics mode available, so you will have to adjust these examples. The second line in our example contains the LINE statement. The LINE statement will do much more than make lines. It will also create boxes and fill them with a color if you want. Here is another program: SCREEN 8 LINE (0,0)-(400,100),4,B INPUT Z This program puts the hardware into a 16 color mode and then creates a box with red lines. The 'B' at the end of the statement is what tells it to make a box. Notice that the diagonal line is not drawn on the screen. Instead the end points in the statement are used as the opposing corners of the box. The 4 specifies the color red. You could also do the following: SCREEN 8 LINE (0,0)-(400,100),4,BF INPUT Z This program has 'BF' instead of 'B' in the LINE statement. The 'BF' says to draw a box and then fill it with the same color. Of course you can also use a variable in place of the numeric constants we have used so far: SCREEN 8 FOR I=0 TO 15 57 Copyright (c) 1992, 1993 by Mark Davidsaver X=I*10 Y=I*5 MYCOLOR=I LINE (X,Y)-(X+10,Y+10),MYCOLOR,B NEXT I INPUT Z This creates a series of boxes. If you are tired of sharp corners try this: SCREEN 8 CIRCLE (100,100),50,4 INPUT Z As you might expect this draws a circle. The center of the circle is at 100,100; it has a radius of 50 and is drawn in red(the 4). The CIRCLE statement will do much more than draw circles; it will also draw arcs and pie sections. Try this: SCREEN 8 CIRCLE (100,100),50,4,0,3.1416/2 INPUT Z This draws a quarter circle (an arc) starting to the right and finishing up at the top. To do this we are added 2 more arguments to the CIRCLE statement; 0 and 3.1416/2. These are the start and end angles in radians of the arc. There are 2pi radians in a circle. Don't remember this from high school? Just remember that 0 is to the right; 3.1416/2 is up, 3.1416 is left, and 4.7124 is down. Putting a minus sign before the start and end angles cause BasicBasic to draw a pie section. SCREEN 8 CIRCLE (100,100),50,4,-.01,-2 INPUT Z This draws a pie section slightly greater than a quarter circle. The CIRCLE statement does not have a fill option like the LINE statement. If you want to fill your pie section with a color you should use the PAINT statement. This is a very versatile statement. You use it like this: SCREEN 8 CIRCLE (100,100),50,4,-.01,-2 PAINT (102,98),4,4 INPUT Z Now we have a red pie section. Paint starts filling the screen with color starting with the center point given and proceeding to the border color. Notice that we made our 58 Copyright (c) 1992, 1993 by Mark Davidsaver center point different than 100,100 to make sure it was inside the pie section we previously drew with the CIRCLE command. We could have a blue pie section with red border with the following: SCREEN 8 CIRCLE (100,100),50,4,-.01,-2 PAINT (102,98),1,4 We will mention one last statement in this introductory discussion. This is the PSET statement. It allows you set individula pixels on the screen. SCREEN 8 FOR I=1 TO 100 MYCOLOR=INT(RND*16) X=INT(RND*640) Y=INT(RND*200) PSET (X,Y),MYCOLOR NEXT I INPUT Z The preceeding program 'splatters' 100 randomly placed pixels on the screen. They also have random color. We won't discuss them here but other statements useful in graphics programming are: PRESET GET PUT COLOR PALETTE These commands are used in several of the Sample programs. 59 Copyright (c) 1992, 1993 by Mark Davidsaver PROGRAMMING BUTTONS ------------------------------------------------------- Buttons can be used in either DOS or Windows. Buttons do not require the presence of a mouse. Here is an example of a valid create button command: CBUTTON "EXIT",1068,0,"Push",0,1,1,8,1,7,4 Here is a description of each parameter: EXIT - This is the name displayed in the button 1068 - This is keycode for F10 (User can either use mouse to push button or press F10. 0 - Reserved Push - Type of button. 'Radio' and 'Check' are the other types. 0 - Reserved 1 - Left position 1 - Y position 8 - x size (in characters) 1 - y size (in characters) 7 - foreground color (In Windows only used for Radio buttons). 4 - background color (In Windows only used for Radio buttons). In DOS a push button will have text centered and if the defined text size is at least 2 characters smaller than the button size a line will be drawn around the outside. In graphics modes button position and size is given in pixel units rather than character units. Remember that if a mouse is going to be used it MUST be turned on with the MOUSEON function before it can be used to press a button. Here is an example of a small program which uses buttons: A=MOUSEON IF A=-1 THEN CBUTTON "EXIT",1068,0,"PUSH",0,70,1,8,1,0,0 60 Copyright (c) 1992, 1993 by Mark Davidsaver ELSE CBUTTON "F10-Exit",1068,0,"PUSH",0,70,1,10,1,0,0 END IF INPUT Z a$=INKEY$ PRINT LEN(A$) This program displays different text in the button depending on whether a mouse is present or not. Assuming there is a mouse this program will end under the following conditions: - User presses EXIT button with mouse - User presses F10 on keyboard - User presses ENTER key on keyboard. In the first two cases the print will show a length of 2 for the length of A$ since the button keycode will be returned on the next INKEY$ after the INPUT is terminated. Once you have created a button you are responsible for NOT writing anything to that area of the screen. If you do the button will be erased. If you are using buttons and scrolling text on the screen make sure you use the SCROLLAREA command to protect the button area of the screen. INVISIBLE buttons can be particularly useful. An invisible button does not appear on the screen, but a button push inside it's defined area will return it's keycode just as if it were. This allows you to create your own special color buttons or input areas. For instance you could have a series of INPUT statements in a program and each could be defined as an invisible button. When the user clicked on that input area you would get a unique keycode which would direct your program to the section of code which handles that input. Since buttons end INPUT commands you can also use invisible buttons to define any keys you want to end INPUT commands (e.g. UP ARROW or DOWN ARROW). 61 Copyright (c) 1992, 1993 by Mark Davidsaver PROGRAMMING MENUS ------------------------------------------------------- Under DOS menus may be either accessed by using the mouse (if present) or pressing the F10 key. (F10 is changeable, see the definition of MAINMENU command) When using menus in DOS, always define menus BEFORE creating buttons. Also, be aware that using the PALETTE command when a menu bar is displayed may change the color of the menu bar or may it invisible. Menus support in BasicBasic is much like button support. When the user selects a menu item a defined keycode is returned to the Basic program. Menu keycodes are returned only using the INKEY$ function call. However, if the user selects a menu item while the program is waiting for input in an INPUT command the input command will be terminated just as if the user had pressed Enter. Then on the next INKEY$ call the keycode for the menu item will be returned. KEYCODES: Just as in buttons keycodes can be regular or extend keys. Extended keys are indicated by adding 1000 to the regular keycode. F10 would be 1068. See the Appendix 'Keyboard codes' for a complete list. The mouse must be enable with the MOUSEON command before any menu items will be recognized. Here is an example of a simple Windows program which utilizes menus. y=mouseon mainmenu "Color","","","","","" addsubmenu 1,"Black",1059 addsubmenu 1,"White",1061 backcolor=0 menuitemgray 1059 50 cls color 1,backcolor locate 10,30 print "Sample text.."; 100 a$=inkey$ if a$="" then goto 100 if len(a$)=1 then goto 100 if right$(a$,1)=chr$(59) menuitemon 1060 menuitemgray 1059 backcolor=7 goto 50 elseif right$(a$,1)=chr$(60) 62 Copyright (c) 1992, 1993 by Mark Davidsaver menuitemon 1059 menuitemgray 1060 backcolor=0 goto 50 end if goto 100 This program defines one menu and then adds two items to it. These menu items allow the user to clear the screen to either black or white. The program disables the menu item for whatever color the screen currently is. The menu could be defined in the following way also. mainmenu "&Color","","","","","" addsubmenu 1,"&Black",1059 addsubmenu 1,"&White",1061 The apersand (&) allows you to define which character in the menu will be underlined which allows the user to select this item by pressing the ALT key and this letter. This IS NOT the keycode which will be returned to your program. This keycode will always be the one given as the last parameter of the addsubmenu command. We could also define the menu like this: mainmenu "&Color","","","","","" addsubmenu 1,"&Black",1059 addsubmenu 1,"",0 addsubmenu 1,"&White",1061 The 3rd line (addsubmenu 1,"",0) creates a line seperator in the menu bar. It can not be selected by the user. 63 Copyright (c) 1992, 1993 by Mark Davidsaver PROGRAMMING WINDOWS ------------------------------------------------------- BasicBasic allows you to create special windows on the screen. These windows are called child windows. You can display whatever you want in these windows. When you destroy the window the original background is restored. This makes child windows convenient for displaying information which is only temporarily needed. For getting special input a dialog box is usually more appropriate. You create a child window with the CREATEWINDOW command. Here is the syntax of this command: CREATEWINDOW number,0,fc,bc,leftx,topy,xlen,ylen where: number = Window number (1 through 9) fc = foreground color (only applicable in DOS) bc = background color to inialize window to leftx = left column (or pixel in graphics mode) topy = top row (or pixel in graphics mode) xlen = total columns (or pixels in graphics mode) ylen = total rows (or pixels in graphics mode) Here is an example: CREATEWINDOW 1,0,7,1,5,10,40,5 This command creates a window with a blue background, starting at column 5 and line 10. Note that the window is actually made bigger than column 5 through 10 since the border occupies some space. Here is an example of a complete program which creates 2 windows and then destroys them: COLOR 7,1 CLS CREATEWINDOW 1,0,7,4,5,7,40,5 CREATEWINDOW 2,0,7,14,2,14,20,10 SELECTWINDOW 1 COLOR 7,4 PRINT "DISPLAY IN WINDOW 1"; SELECTWINDOW 2 COLOR 7,14 64 Copyright (c) 1992, 1993 by Mark Davidsaver FOR I=1 TO 20 PRINT I NEXT I INPUT Z SELECTWINDOW 0 DESTROYWINDOW 1 DESTORYWINDOW 2 INPUT Z Notice that once a window is created you must use SELECTWINDOW to make this window the active window. To erase a window from the screen use the DESTROYWINDOW command. You CANNOT destroy the active window. To return to the main screen use SELECTWINDOW 0. Some fine print: - Under DOS you (the programmer) are responsible for not writing outside the bounds of the selected window. Under Windows the operating system will not display anything written outside the bounds of the window. - Under DOS you cannot select the primary window (SELECTWINDOW 0) and then write behind of child window. Under Windows you can. - All existing buttons remain active; whether they are on the active window or not. - All mouse x and y information is relative to the existing active window. - Cursor position is not necessarily retained when you select or create a window. Be sure to do a locate after either of these operations. - In graphics mode all x and y parameters in the CREATEWINDOW command are pixels. 65 Copyright (c) 1992, 1993 by Mark Davidsaver PROGRAMMING DIALOG BOXES ------------------------------------------------------- Dialog Boxes are 'pop-up' boxes used to get information from the user. Dialog Boxes are made up of one or more 'Controls'. A Control may be a pushbutton, radio button, check box, edit field or various other items. BasicBasic contains 3 types of Dialogs boxes: 1) File open for read; 2) File open for save; 3) User defined. Dialogs automatically preserve the original screen over which they are place. The original screen is restored when the dialog closes. Under both DOS and Windows a user can selected and enter items in a Dialog box without a mouse. Use the TAB key to move from item to item. Arrow keys select items in a list. Space bar sets/resets radio buttons and checkboxes. Pressing Enter exists the dialog box if on a pushbutton. FILE OPEN FOR READ DIALOG BOX: This dialog box is available under any version of DOS, but if running under Windows it is only available under Windows Version 3.1 or later. (See the SYSTEM function for information on determining Windows version.) This is a very easy to use dialog box which prompts the operator to select a file to be read from. The format of the command is as follows: OPENFILEREAD filterstr,filenamestr,directorystr,title An example would be: filter$="document"+chr$(0)+"*.doc"+chr$(0)+chr$(0) filename$="readme.doc" directory$="c:\windows" title$="My open dialog" OPENFILEREAD FILTER$,FILENAME$,DIRECTORY$,TITLE$ Filter defines which file names will be display for the user. Each filter is a pair of text strings seperated by a chr$(0) character. The first string of the pair is a description of the filter and the second part is the filter (e.g. *.BAT). You may have more than one filter; however, in DOS, only the first filter is used. Filename defines the default file (if any). Directory defines the default pathname (if any). 66 Copyright (c) 1992, 1993 by Mark Davidsaver Title is an optional title for the dialog box. Upon leaving the dialog box the following functions return the result: DIALOG$(100) has the file name DIALOG$(101) has the pathname DIALOG$(102) is set to 1 if successful, 0 else DIALOG$(103) is set to 1 if Cancel button pressed 102 and 103 will both be zero if an error occurs. If the dialog was successful then the default disk and directory will have been changed to the pathname returned in DIALOG$(101). The path is returned for informational purposes only. FILE OPEN FOR WRITE DIALOG BOX: This dialog box is available under any version of DOS, but if running under Windows it is available only under Windows 3.1 or later. This dialog box is similar to OPENFILEREAD. The primary difference is that OPENFILEREAD requires that the file exist, while OPENFILEWRITE does not. OPENFILESAVE filterstr,filenamestr,directorystr,title An example would be: filter$="document"+chr$(0)+"*.doc"+chr$(0)+chr$(0) filename$="readme.doc" directory$="c:\windows" title$="My open dialog" OPENFILEREAD FILTER$,FILENAME$,DIRECTORY$,TITLE$ USER DEFINED DIALOG BOXES: To create and use a dialog box you must do the following steps: 1) Create a string array to hold Control information; 2) Define one control in each string array element; 3) Execute the dialog using the DIALOG statement; 4) Use information acquired in Dialog. The DIALOG statement looks like this: DIALOG, a$(),x,y,xlen,ylen,id,string name where: a$() = a string array x = x position of upper left corner 67 Copyright (c) 1992, 1993 by Mark Davidsaver y = y position of upper left corner xlen = x length ylen = y length id = unique identifier for control (1 -> 255) string name = Text to put at top of Dialog box X, y, xlen, ylen are in pixels in graphics mode or in character locations in text mode (SCREEN 0). An example would be: DIALOG A$(0),10,10,200,100,100,"GET INFO" Each Control is then defined in one element of the string array. The general format for controls is: controltype,x,y,xlen,ylen,id,text Commas between each element are required. An example would be: a$(0)="pushbutton,5,40,100,30,100,Exit" This would define a pushbutton labeled "Exit" which would be 100 units wide and 30 high. It's origin would be 5 units from the left and 40 units from the top of the Dialog Box. It would have identifier number 100. We could not use this identifier for any other Control. Controls defined in BasicBasic are: pushbutton radiobutton checkbox edit ltext group ok filename filelist filepath All Controls have the general format shown above for Pushbutton. What follows is a description of each Control recognized and any special format needed to define it or any special way it is used. PUSHBUTTON: Pushbuttons cause the Dialog to end. You can use the DIALOG$ function to determine which pushbutton ended the Dialog. RADIOBUTTON: Radio buttons can be used to allow the user 68 Copyright (c) 1992, 1993 by Mark Davidsaver to supply additional information. Radiobuttons DO NOT end the dialog. You can optionally set the state of a pushbutton when defining it: a$(1)="RADIOBUTTON,10,10,200,30,101,YES,1" This defines a radio button at 10,10 with width 200 and height 30. The control identifier is 101 and the text YES will be display in it. The '1' at the end specifies that this button will be enabled at start. Omitting this number or making it '0' means the button is NOT enabled at start. Radio Buttons may be grouped. In a group if one button is pushed all the rest are cleared. BasicBasic considers Radiobuttons with consecutive id's to be part of a group. The following three buttons are part of a group: a$(1)="RADIOBUTTON,10,10,200,30,101,BLACK" a$(2)="RADIOBUTTON,10,50,200,30,102,RED,1" a$(3)="RADIOBUTTON,10,90,200,30,103,WHITE" In this group RED will be enabled at start. CHECKBOX: Check buttons are similar to Radio buttons except they may not be grouped and hence do not clear any other Checkbox when one is checked. EDIT: Edit fields allow the operator to input text. The text string at the end of the definition is the default text entry. To provide a label for an EDIT control you will have to use LTEXT defined later. LTEXT: Ltext displays static text left justified. You may display text anywhere in the Dialog box and this is particulary used for providing a header for an Edit Control. Here is an example: A$(1)="LTEXT,10,10,200,30,103,Enter Name" GROUP: Group draws a box on the screen and provides a label at the top of the box. It is particularly useful for providing a visual indicator of Radio button groups. An example to draw a box at 10,10 100 units wide by 50 high would be: A$(1)="GROUP,10,10,100,50,101,Colors" OK: OK is a special pushbutton. It is defined the same way as any pushbutton. If you have an OK control defined then the dialog will end if the user presses 'Enter' at any Edit field. It is required when using the following file controls. Only one OK control may be in a Dialog. 69 Copyright (c) 1992, 1993 by Mark Davidsaver FILENAME: This is a special Edit field used for getting a file name. It is used in conjuction with OK, FILELIST, and FILEPATH controls. The text element is the default file name. The presence of a FILENAME control means that the Dialog box will not terminate until a name of an existing file is entered or a pushbutton other than the OK control is pushed. a$(1)="filename,10,10,200,30,101,CONFIG.SYS" FILENAMEW: This functions just like FILENAME, except if this control is used no check to see if the file exists is made before the Dialog terminates. Only one FILENAME/FILENAMEW may be used in a Dialog. FILELIST: This defines a box which will contain a display of files. It is used in conjuction with OK, FILENAME, and FILEPATH controls. The text element contains the DOS file search string. The user may use the mouse to select files which will automatically be placed in the FILENAME (or FILENAMEW) control. Only one FILELIST may be in a Dialog. a$(1)="filelist,10,10,200,200,101,*.bmp" FILEPATH: This defines a string which will DISPLAY the current directory path being accessed. It is used in conjuction with OK, FILENAME, and FILELIST. The text element is the default path. Only one FILEPATH may be in a Dialog. a$(1)="filepath,10,10,200,30,101,c:\windows" COLOR: This can be used to change the default dialog colors in DOS only! The order of the colors is: dialog background color, dialog foreground color, dialog selected color, button foreground color, radio button background color, push button background color. a$(1)="COLOR,0,1,4,5,6,7" The following example shows a dialog box: rem go into graphics mode screen 2 dim control$(100) rem define controls control$(0)="ltext,10,10,100,30,100,Name:" 70 Copyright (c) 1992, 1993 by Mark Davidsaver control$(1)="edit,110,10,200,30,101," control$(2)="ltext,10,50,100,30,102,Address:" control$(3)="edit,110,50,200,30,103," control$(4)="pushbutton,10,110,50,30,104,Done" control$(5)="radiobutton,130,110,110,25,105,Type A,1" control$(6)="radiobutton,130,134,110,25,106,Type B" control$(7)="group,118,80,180,90,107,Personality Type" control$(8)="checkbox,10,174,100,30,108,Widgets" control$(9)="checkbox,130,174,100,30,109,Gadgets,1" control$(10)="checkbox,250,174,100,30,110,Doodads" rem call dialog dialog control$(0),11,10,10,350,210,"Client Info" rem display results of dialog print "name=";dialog$(101) print "address=";dialog$(103) print "done=";dialog$(104) print "radio 1=";dialog$(105) print "radio 2=";dialog$(106) print "widgets=";dialog$(108) print "gadgets=";dialog$(109) print "doodads=";dialog$(110) input z 71 Copyright (c) 1992, 1993 by Mark Davidsaver WINDOWS GRAPHICS PRINTING ------------------------------------------------------- This section is for Windows programs only. Under Windows BasicBasic support two ways of accessing printers. The first way is the standard Basic printer supported by the LPRINT command. To do graphics with this method requires that the programmer have knowledge of exactly what printer is being used. In addition BasicBasic provides a way to access the Windows printer driver. The advantage to this is that you can print graphics without requiring any knowledge of the printer, since Windows takes care of the interface. This section shows how to access the Windows printer driver. To access the Windows printer you must perform the following steps: 1 Open the Printer 2 Select the Printer 3 Display something to the Printer 4 Deselect the Printer 5 Close the Printer 1. To open the printer you use the PRINTCONTROL command. example: PRINTCONTROL 0 Alternately you can open the printer and display the Windows standard print dialog box which allows the user to define the printer setup or cancel the print. example PRINTCONTROL 1,i%,1,2,1,3,1 The first parameter is a 1 which tells BasicBasic to use the print dialog box. Upon return i% will contain the results of the dialog box. A 2 means cancel, a 1 means OK. The 1,2 which follow the i% are your supplied suggest page print ranges. The 1,3 which follow that are the maximum possible page print ranges. The final 1 is the number of copies to print. You can use the function PRTJOB to return information about how many copies and what pages the operator has selected to print. 2. To select the printer you use the SELECTPRINT command. After this command is executed ALL output 72 Copyright (c) 1992, 1993 by Mark Davidsaver will be sent to the printer. To return output to the screen you must use the SELECTDISPLAY command. 3. As indicated once you have issued the SELECTPRINT command all output which would normally go to the screen is redirected to the printer. You can do text or graphics. Once you have issued the SELECTPRINT command you can use the DEVICE function to find out information about the size of the print area which will normally be much larger than the screen. 4. Once you are done writing to the printer you need to redirect output back to the screen. You do this with the SELECTDISPLAY COMMAND. 5. When finally ready to print a page close the printer by using the following PRINTCONTROL commands. PRINTCONTROL 2 : REM End Frame PRINTCONTROL 3 : REM End Document command You can use COPYBITS to copy images to the printer just as you would to the display. Instead of putting DISPLAY as the source destination you would put PRINT. You may not use LOADBITMAP to load bitmap files directly to the printer. Instead, you must create a memory bitmap, load the image into that and then use the COPYBITS command to copy to the printer. When using COPYBITS to copy from a memory bitmap to the Printer, copying starts at the LOWER LEFT corner of the bitmap. When copying to the display copying starts at the UPPER LEFT corner of the bitmap. The size of pixels on the printer and their relative width versus height will be different than the screen. Therefore, graphics which look fine on the screen, may appear different on the printer. You can expand graphics to match the aspect ratio of the printer by using STRETCHBITS instead of COPYBITS. You can use the DEVICE function to compare screen to printer pixel sizes and aspects. Here is a sample print program: SCREEN 12 XS=167 YS=126 CREATEBITMAP 2,0,XS,YS SELECTBITMAP 2 LOADBITMAP "TEST.BMP",0,0,0,0,0,XS,YS,0,0,0 SELECTDISPLAY 73 Copyright (c) 1992, 1993 by Mark Davidsaver COPYBITS 2,0,0,XS,YS,DISPLAY,0,0,0 PRINTCONTROL 0 SELECTPRINT LINE (0,400)-(400,400),15 FOR I%=0 TO 15 LINE (0,I%*10)-(200,(I%*10)+8),I%,BF NEXT I% PIXELSWIDE=DEVICE(8) PIXELSDOWN=DEVICE(10) COPYBITS 2,0,0,XS,YS,PRINT,PIXELSWIDE-200,600,0 COPYBITS 2,0,0,XS,63,PRINT,100,600,0 STRETCHBITS 2,0,0,XS,YS+30,PRINT,100,800,XS,YS,0 PRINTCONTROL 2 PRINTCONTROL 3 SELECTDISPLAY This program reads in a bitmap file and displays it on the screen. Then it does the following to the printer. - Sets to white a 400 x 400 pixel area on the printer and then writes 16 horizontal color bars to it - Using information on the number of pixels on the printer displays the bitmap file graphic on the right side of the printer. - Displays the bottom 1/2 of the bitmap file image. This illustrates how the COPYBITS copies starting at the lower left corner when talking to the printer. - Copies the bitmap file image and stretches it in the y direction. 74 Copyright (c) 1992, 1993 by Mark Davidsaver PROGRAM ICON ------------------------------------------------------- Windows programs may have an 'icon' associated with them. An icon is the little picture which is placed in a folder when a program is installed or which is displayed when a program is minimized. BasicBasic programs have a default icon; but you may want to make your own. Icons are ignored in DOS. To add an icon to a program you must do two things: 1. Create an icon. In Windows you can do this by selecting 'Icon Editor' from the Transfer menu. In DOS you can execute the icon editor by running the program BBICON.EXE. The editor requires a mouse. 2. Tell the compiler to use your icon with the $ICON metacommand: REM #ICON: 'MYFILE.ICO' BasicBasic contains a simple icon editor which allows you to create icons for use in your program. The icons created will always be 32 by 32 pixels in size and have up to 16 colors. When first started the icon editor displays a white icon. You change the color of a pixel by putting the pointer over it and pressing the mouse button. You select the color to use from the palette at the right of the screen. Pixel by pixel you create your icon until you are ready to save it using the File menu. It is standard practice (though not required) to give an icon file the extension .ICO. Advanced Users: A Windows icon actually contains two 32 by 32 pixel bitmaps. The primary bitmap tells the colors of the pixels. This bitmap is the default bitmap displayed by the BasicBasic icon editor. The second bitmap tells Windows which pixels in the bitmap are transparent and which ones are opaque. The default for a BasicBasic icon is all opaque. You can access this second bitmap from the View menu. The second bitmap is called the 'Mask' bitmap. When viewing the mask bitmap each pixel may be either black (opaque) or white 75 Copyright (c) 1992, 1993 by Mark Davidsaver (transparent). Keep in mind that if you make a transparent mask that the background will show through your icon. If there is a color other than black in the corresponding color bitmap pixel, the color actually displayed will be a blend of the background color and the color you selected. 76 Copyright (c) 1992, 1993 by Mark Davidsaver COMMUNICATIONS PROGRAMMING ------------------------------------------------------- Here is a brief example of using a communications port. rem rem open communications port rem OPEN "COM1: 2400,N,8" FOR RANDOM AS #1 LEN=2048 100 rem rem get input from communications port rem t = LOC(1) IF t > 0 THEN a$=input$(t,1) if len(a$)>0 then rem come here to display received characters PRINT a$; ELSE rem come here if some kind of comm error that kept rem us from getting the waiting character. end if END IF rem rem get input from keyboard rem b$ = INKEY$ IF b$ <> "" THEN PRINT #1, b$; END IF GOTO 100 77 Copyright (c) 1992, 1993 by Mark Davidsaver WINDOWS AND GRAPHICS ------------------------------------------------------- In general programming graphics under Windows is the same as programming graphics under DOS. However, because Windows mediates hardware access among different programs there are a few differences. COLORS Under DOS or Windows, BasicBasic provides a palette of 16 colors. Under DOS this palette is the hardware palette and you have full control to change them (depending on mode using either the COLOR or PALETTE statements). Under Windows the palette is a 'logical' palette and only Windows controls where in the physical palette the logical palette entries are placed. In addition, if you are running under standard VGA or less, Windows will not let you change the colors in the palette. You are restricted to the 16 colors Windows defines. BasicBasic defaults to using the system palette. This is a palette of 16 colors which Windows never changes. This also means that your program cannot change them with the PALETTE or COLOR(in mode 8) commands. If you want to change the standard colors you will have to use a 'logical' palette. In BasicBasic you do this using the SCREEN command. Using a logical palette has benefits and drawbacks. As mentioned you can change the colors display. This may be of use in animation. However, there are serious drawbacks. The PUT with any option except PSET will not work correctly. This is explained below. Also, when your program is not the 'active' window, Windows may remove your colors from the hardware palette resulting in some strange looking displays. In addition, if this happens, the PAINT command may have completely unforseen consequences. You can use the SYSTEM function to determine if your program is the active program. When your program is active your colors will all be available for your use. Logical palettes do not support using the PUT graphics statement with the XOR, OR, or AND options. If you use XOR the colors will not be as expected (though, as usual if you do 2 PUT statements with XOR the background will be restored). The reason for this is that Windows may 'map' the logical palette entries to the physical palette anyway it likes. If you must use XOR, use the default BasicBasic palette which is the system palette. 78 Copyright (c) 1992, 1993 by Mark Davidsaver SCREEN MODES Under Windows you have access to the same screen modes as under DOS. The COLOR and PALETTE statements work the same under DOS as under Windows. In addition under Windows you have access to an additional screen mode: mode 1000. In mode 1000 you are able to create new fonts. Mode 1000 gives you the highest possible graphics resolution. Also the COLOR command is somewhat more flexible than under DOS screen modes. The LOCATE and SCROLLAREA statements and functions POS, CSRLIN work differently in this mode. Also under Windows you have the option of specifying the size of the logical palette your program will have access to. This is limited by the physical palette supported by your hardware. Standard VGA supports only 16 palette entries. Super VGA may (depending on memory) support up to 256 palette entries. You could select 256 palette entires by using this command: SCREEN 1000,256 Windows actually only allows you to change 236 of the palette entries. The other entries are defined by Windows as follows: 0 - black 246 - cream 1 - dark red 247 - lightish gray 2 - dark green 248 - medium gray 3 - dark yellow 249 - red 4 - dark blue 250 - green 5 - dark magenta 251 - yellow 6 - dark cyan 252 - blue 7 - light gray 253 - magenta 8 - money green 254 - cyan 9 - sky blue 255 - white NAKED WINDOWS When running under Windows you do not have exclusive access to the screen. At any time your window may be hidden by another window appearing on the screen. At some future time the operator may make your window reappear with the click of the mouse button. When your window has been hidden and is then called to the front, Windows DOES NOT handle putting the contents of the window back in! All windows privides is the outline of the window. This 'naked' window must be filled in by either BasicBasic or your program. By default BasicBasic handles all window 'repainting'. BasicBasic remembers everything that your program sends to 79 Copyright (c) 1992, 1993 by Mark Davidsaver the screen and when necessary repaints the window with this information. In text mode (screen mode 0) a small buffer remembers each character on the screen. In graphics mode BasicBasic maintains a larger buffer containing a duplicate of each pixel on the screen. This buffer can take up quite a bit of space.(On a 640 x 200 16 color display this requires 128,000 bytes). Ordinarily you don't need to worry about this. If your program isn't going to be in memory very long, or has a small window, who cares? If you are short of memory or have a very large window which is going to stay around all day you may not like this arrangement. In this case you should use the ON PAINT statement. This statement tells BasicBasic to NOT keep a copy of the display; that you are going to handle repainting when necessary. Here is an example: ON PAINT GOSUB 1000 SCREEN 8 sc=8 gosub drawmyscreen 50 if inkey$="" then goto 50 STOP 1000 gosub drawmyscreen RETURN drawmyscreen: if sc=0 then return locate 1,1 print "Now is the time to draw circles..." circle (50,50),25,4 circle (75,75),50,1 circle (400,50),40,2 circle (500,100),75,3 return Here are some rules to remember about using the ON PAINT statement: - Use it before your SCREEN statement. BasicBasic creates the screen duplicate during the SCREEN statement. It will, if necessary, erase it during the ON PAINT statement, but why go to the bother. - NEVER use any input commands, file commands, com commands, etc in you ON PAINT handler. - Don't change variables in your ON PAINT handler that are used elsewhere in your program. Remember that Windows ALWAYS calls your ON PAINT handler at the 80 Copyright (c) 1992, 1993 by Mark Davidsaver WORST POSSIBLE TIME! - When using multiple windows you will be notified seperately to repaint each window. In you ON PAINT routine do a system function call (SYSTEM(18)) to find out which window to repaint. You DO NOT need to do a SELECTWINDOW in your paint subroutine. - It is wise not to use the INPUT command in a program that has it's own ON PAINT handler. BasicBasic will not rewrite what has been input so far. - Your ON PAINT handler may be called IMMEDIATELY after you issue the ON PAINT command. Make sure you are ready. Note the line IF SC=0 THEN RETURN in our example. Try running this program without this line. 81 Copyright (c) 1992, 1993 by Mark Davidsaver BITMAPS ------------------------------------------------------- BasicBasic supports the loading and storing of device independent bitmap files as defined in Windows 3. BasicBasic supports bitmaps under EITHER DOS or Windows. You must be in graphics mode to load or store bitmaps. Windows (and SOME Windows applications) support a compressed bitmap format to save space. BasicBasic also supports loading and store compressed bitmap files. A simple program to load a bitmap could be as follows (the file CARS.BMP is a standard bitmap file supplied with Windows). screen 8 x=100 y=100 ffname$="c:\windows\cars.bmp" loadbitmap ffname$,0,x,y,0,0,16,16,0,0,0 input z This example loads the upper left most 16 by 16 pixels of the bitmap and puts in on the screen starting at 100,100. If we had wanted to double the size of the graphic in the x direction we could have done the following load: loadbitmap ffname$,0,x,y,0,0,16,16,0,2,0 If we had wanted to skip every other line of pixels we could have done the following load: loadbitmap ffname$,0,x,y,0,0,16,16,0,0,-2 This would have loaded 16 lines of the bitmap, but only displayed every other one. BITMAPS AND COLORS With each device independent bitmap is stored information about the colors defined for that bitmap. There may be information about 2 colors, 16 colors, 256 colors or 16,777,216 colors. BasicBasic supports the first 3 types of bitmaps. The colors in the bitmap may or may not be the same as those defined in your current palette. When you load a bitmap you might want to make sure that your palette has the colors necessary to correctly display the bitmap. Alternately you can tell BasicBasic to attempt to match bitmap colors to your currently defined palette colors. This is the easiest thing to do, though, it may not result in the best rendering of the graphic. In the examples we have used so far we have let BasicBasic 82 Copyright (c) 1992, 1993 by Mark Davidsaver match colors for us. We do this by setting the ninth parameter to 0. cv=0 loadbitmap ffname$,0,x,y,0,0,16,16,cv,0,0 We could also set cv to 1; in which case, BasicBasic would make no color correction and the existing palette colors would be used to display the bitmap. For maximum color compatibility you will want to load the colors from the bitmap and assign them you your logical palette. The first step in this process is to determine how many colors the bitmap has defined. You do this using the BITMAPH function. e.g. dim a&(256) a=bitmaph("C:\windows\cars.bmp",a&(0)) numcolorbits=a&(4) if numcolorbits=2 print "2 colors defined" elseif numcolorbits=4 print "16 colors defined" elseif numcolorbits=8 print "256 colors defined" else print "colors explicitly defined for each bit" end if You can determine how many colors can be displayed on your screen by using the SYSTEM function maxcolors=system(5) If the bitmap has more colors than your screen can display then the best course to follow is to allow BasicBasic to convert colors for you. If, on the other, hand you have enough room in your palette to display all the colors defined in the bitmap then you can load them using the BITMAPC function and assign them using the PALETTE command. screen 8 dim a&(256) ffname$="c:\windows\cars.bmp" a=bitmaph(ffname$,a&(0)) x=0 y=0 pxsize=a&(1) 83 Copyright (c) 1992, 1993 by Mark Davidsaver pysize=a&(2) colorbits=a&(4) if colorbits=2 colors=2 elseif colorbits=4 colors=16 elseif colorbits=8 colors=256 else print "bitmap not supported.." stop end if maxcolors=system(5) if (colors<=maxcolors) a=bitmapc(ffname$,a&(0)) if colors>236 then for i=10 to 246 palette i,a&(i) next i else for i=0 to colors palette i,a&(i) next i end if cv=0 else cv=1 end if x=100 y=100 ymult=2 loadbitmap ffname$,0,x,y,0,0,16,16,cv,0,0 input z Note to Windows Users: With a 256 color palette, Windows only allows 236 to be changed by the user. The first 10 and and last 10 are fixed. This is why we only assign 236 colors in the example above. STORING BITMAPS If you have a graphic displayed on the screen you can save it to a bitmap file using the STOREBITMAP command. It will be saved in the same color resolution as your screen. You can optionally tell BasicBasic to store the file in compressed format to save space. Note, however, that a complex picture with much fine detail may compress to a LARGER file than the original! Also it will take longer to store a bitmap using compression, than without. 84 Copyright (c) 1992, 1993 by Mark Davidsaver screen 8 line (0,0)-(100,100),1 x=0 y=0 pxsize=100 pysize=100 cp=1 : rem compress it storebitmap 0,ffname$,x,y,pxsize,pysize,cp,0 input z 85 Copyright (c) 1992, 1993 by Mark Davidsaver CREATING FONTS ------------------------------------------------------- To create fonts in DOS or Windows you must have selected Screen mode 1000. In this mode some statements and commands work differently. LOCATE x,y now position by dot position, rather than character position. POS and CSRLIN return the corresponding pixel position rather than character position. See the sample program SAMPLE14.BAS for some examples of font creation. Windows users should note that if you are going to create fonts you should NOT use the WINDOWS SIZE metacommand. Instead use POSITION as necessary to adjust the size ofyour window. You may create up to 10 fonts, number 1 through 10. Font number 0 is reserved for BasicBasic's default font. You create a font using the CREATEFONT command. Once you have created a font you must select it with the SELECTFONT command. You may get information on the currently selected font using the FONT and FONT$ functions. The CREATEFONT statement has a lot of arguments. However, it is not as complex to use as it looks. Usually you are only interested in specifying one or two things about the font; such as height. In this case you can set all other arguments to 0. Below is a complete description of the CREATEFONT command. Not all arguments are used in creating DOS fonts. Only those marked by and asterisk (*) are used by DOS. Argument P10 must be set to 3 (OEM Font) to use most of the built in Windows fonts! CREATEFONT p1,p2,p3,p4,p5,p6,p7,p8.p9.p10,p11.p12,p13,p14,p15$ * p1 = Font number to be created. A number from 1 to 10. * p2 = Font height (in pixels). Desired height of characters. This specifies the line spacing. * p3 = Font width Desired width of characters. Usually set to 0 p4 = escapement Which way the text goes. 0 - right 900 - up 1800 - right to left 86 Copyright (c) 1992, 1993 by Mark Davidsaver 2700 - down p5 = orientation 0 = Normal 900 = tipped 90 degrees to the left 1800 = upside down 2700 = tipped 90 degrees to the right p6 = weight 0 = don't care 100 = thin 200 = extralight 300 = light 400 = normal 500 = medium 600 = semibold 700 = boldface 800 = extra bold 900 = heavy p7 = italic When nonzero this specifies italics p8 = underline When nonzero this specifies underlining p9 = strikeout p10 = character set 0 = ANSI character set 1 = SYMBOL character set 2 = Japanese Kanji 3 = OEM character set -> Most Windows fonts are OEM fonts (e.g. script) p11 = output precision Specifies how Windows should attempt to match desired font sizes and characters with actual fonts. Not currently defined. Make 0 p12 = clip precision Not currently defined. Make 0. p13 = quality Instruction to Windows on how to match fonts. 0 - Default Quality. Don't make bigger that desired. 1 - Draft Quality. 2 - Proof Quality. This is the best quality, but size may be smaller than desired. * p14 = pitch and family The two low order bits specify the pitch of the font. 0 = Default 1 = Fixed pitch 2 = Variable The four high order bits specify the font family. 0 = don't care &H10 = Roman &H20 = Swiss &H30 = Modern &H40 = Script &H50 = Decorative 87 Copyright (c) 1992, 1993 by Mark Davidsaver * p15$ = "face name" This is the name of the typeface. You do not need to specify this. If you do it takes priority over any other options you specify (such as height). Examples of face names are COURIER, TMS RMN, etc. Here is an example of a CREATEFONT command which creates a font 60 pixels high. All other parameters are left at default. CREATEFONT 1,60,0,0,0,0,0,0,0,0,0,0,0,0,"" To print with this font you would first have to select it. SELECTFONT 1 When you create a font BasicBasic tries to match the characteristics you specify in the CREATEFONT command. It may not be able to in all cases. Perhaps you specify an incompatible height and width. In these cases BasicBasic gets as close as it can. If some parameter is important to your application you should check to make sure the font you created meets your requirements. Using the FONT function you can examine the selected font. For DOS fonts only the items marked with an asterisk are valid. FONT(n) n returns --- ---------------------------------------------- * 1 character height 2 Ascent 3 Descent 4 Internal Leading 5 Extern Leading * 6 Average Character Width * 7 Maximum Character Width 8 Weight 9 Italic 10 Underline 11 Strikeout 12 First character 13 Last character 14 Default character 15 Break character 16 Pitch and Family 17 Character set 18 Overhang 19 Digitized Aspect x 20 Digitized Aspect y There is another function which will return the face name. 88 Copyright (c) 1992, 1993 by Mark Davidsaver FONT$(n) n returns --- ---------------------------------------- 1 face name If you need additional information on fonts (or Windows programming in general), a useful reference is 'Windows API Bible' by James L. Conger. 89 Copyright (c) 1992, 1993 by Mark Davidsaver CHAINING AND COMMON ------------------------------------------------------- Here are examples of two programs, CHAIN1 and CHAIN2, which pass variables back and forth in common. CHAIN1 common a,b,c,d$(),c() if a=0 then cls a=1 dim d$(10) dim c(20) d$(5)="This is d$(5)" end if print "press any key to go to chain 2" 100 a$=inkey$ if a$="" then goto 100 chain "chain2.exe" CHAIN2 common a,b,c,d$(),c() b=b+1 print "this is chain 2" print "b=";b; print d$(5) input z chain "chain1.exe" 90 Copyright (c) 1992, 1993 by Mark Davidsaver BasicBasic Technical ------------------------------------------------------- BasicBasic is intended to be a subset of Microsoft Basic. More statements and functions will be added with each release. Depending on your religion you may or may not be happy to see that GOTO is supported. BasicBasic's syntax is 'almost' the same as Microsoft's Basic. Here are some known syntax differences: BasicBasic scans expressions from left to right the same as Microsoft Basic, however, BasicBasic checks all multiplies before divides and all minus signs before addition. BasicBasic does not support the underscore (_) line extension character. Most functions and statements have the same syntax as Microsoft Basic. You should check the Statement and Function Reference section for details on syntax. Date types supported are integer (% suffix), long integer (& suffix), single precision (no suffix), and string ($ suffix). Double precision numbers are not supported in this version. BasicBasic does not support a standard array of size 10. Every array must be explicitly dimensioned with a DIM statement. CAPACITIES General limits: Maximum number of arrays: 100 Total open files: 10 Total string space: approx. 47000 chars. Maximum character string size: 2048 Maximum Buttons: 40 Windows only limits: Maximum menus: 6 Maximum Items in a menu: 10 Maximum Fonts Defined: 10 RESERVED WORDS All names of statements and functions are reserved words and may not be used as variable names. ERR is a special 91 Copyright (c) 1992, 1993 by Mark Davidsaver case. This is a system wide variable used to return error information to BasicBasic programs. See the command SETERRLEVEL for more complete information. 92 Copyright (c) 1992, 1993 by Mark Davidsaver WINDOWS METACOMMANDS ------------------------------------------------------- BasicBasic contains several Metacommands to set Windows environment parameters. These commands have no affect on execution of the program. All Windows Metacommands have the following format: REM WINDOWS command REM WINDOWS NAME name The window name which the program will display can be supplied. The default is the same as the file name of the program. e.g. REM WINDOWS NAME investments SAMPLE3.BAS uses the WINDOWS NAME metacommand. REM WINDOWS size x1,y1,x2,y2 This command allows you to define a portion of the normal DOS screen size as the area to be displayed in the Windows window. This is useful if you have a program centered in the standard 80x25 DOS screen, but do not use much of the border area. Regular scrolling may not work in windows if you define the window size as less than 80x25. X1 is the left column, y1 is the top row, x2 is the right column, and y2 is the bottom row. e.g. Do NOT use this command if your are using the CREATEFONT command. e.g. REM WINDOWS SIZE 10,10,70,15 SAMPLE2.BAS uses the WINDOWS SIZE metacommand. 93 Copyright (c) 1992, 1993 by Mark Davidsaver METACOMMANDS ------------------------------------------------------- metacommands are preceded by REM and a dollar sign. INCLUDE: 'filename' This metacommand allows you to include source from another file in the currently compiling file. files may be nexted up to 10 levels deep. File name MUST be enclosed in single quotes as shown. e.g. REM $INCLUDE: 'moretext.asc' ICON: 'iconfilename' This metacommand allows you in specify a special ICON which will be attached to your application. This icon will be used in Windows when your application is installed. e.g. REM $ICON: 'SAMPLEW3.ICO' SAMPLE14.BAS use the $ICON metacommand. 94 Copyright (c) 1992, 1993 by Mark Davidsaver SEPERATE COMPILATION ------------------------------------------------------- You may decide to compile your program outside the BasicBasic program development system environment. Here are instructions for doing this. DOS To compile a program under DOS type BB. When requested enter the file name you want to compile. If no extension is given the compiler will assume .BAS. You can also enter the file name you want to compile as part of the start command. e.g. BB SAMPLE1.BAS. The executable file created will have the same name as the source file. You may also tell BasicBasic to create a file with a list of runtime addresses. This can be useful for debugging since an error during runtime will return a runtime address followed by an error number. You do this by putting a /D on the command line. e.g. BB SAMPLE1.BAS /D This will create a file SAMPLE1.TMP which will have a runtime address in front of each source line. WINDOWS Under Windows you must compile using the program WBB.EXE. You may install this in a group with the Program Manager or run WBB seperately. When compile is completed you may either execute the program or restart to compile another program. IMPORTANT! Whether you are compiling under DOS or Windows only one EXE file will be created. This file will have the same name as the source file with an extension of .EXE. This EXE file can be executed under either DOS or Windows as long as the appropriate runtime module is present (BBL150.EXE for DOS or WBBL150.EXE for Windows). If you are using graphics screens running under Windows you will also need the file WBB.FON. If you are running Windows 3.1 in 386 Enhanced Mode and using text only screens see the section on Default Windows 95 Copyright (c) 1992, 1993 by Mark Davidsaver Font for important information on using different font sizes. 96 Copyright (c) 1992, 1993 by Mark Davidsaver DEFAULT WINDOWS FONT ------------------------------------------------------- The following discussion is current for Windows Version 3.1. The concepts discussed are applicable for Version 3.0, however, font file names are different for that version. This section is only relevant when running in screen MODE 0 (the default). BasicBasic selects the OEM Fixed font closest in size to the system font size used in menus, buttons, etc. If you desire a different font size when running a BasicBasic program you can select from available fonts in the System Menu. You may also mark a given font size to be the new default for that program. Depending on how you configured your system there may be only one OEM font installed. Windows 3.1 comes with an assortment of OEM fonts. The file DOSAPP.FON contains the fonts used by Windows to run DOS in a window and are good for use with BasicBasic. If this file is not in you windows system directory (e.g. WINDOWS\SYSTEM) then your can copy it from your distributions disks and then use the Control Panel Fonts accessory to install them (These fonts have the name 'MS-DOS CP 437'). IMPORTANT INFORMATION FOR 386 ENHANCED MODE: If you use the MS-DOS prompt in 386 Enhanced mode you will need to make a change in your SYSTEM.INI file to use multiple size fonts in BasicBasic. As mentioned previously Windows does not normally permanently install the fonts from DOSAPP.FON. As was indicated you can do this from the Control Panel Fonts accessory. HOWEVER, you will find that each time you EXIT the MS-DOS prompt these fonts will be REMOVED from the system. This is because Windows does not expect these fonts to be present and there is a control line in SYSTEM.INI which explicitly tells it to load and unload them when running the MS-DOS prompt. Once you have installed these fonts you can keep Windows from un-installing them by removing the following line from the [386Enh] section of SYSTEM.INI: WOAFONT=DOSAPP.FON FONTS AND BUTTONS: This discussion applies only to buttons which are defined by the user to be one line high. If you select a font smaller than the system font for use in a BasicBasic program the text in any buttons you have would be too crowded in the button space available. BasicBasic corrects this problem in one of two ways. 1) If you system font is only slightly larger than the font selected in BasicBasic then any text in the buttons will be made 97 Copyright (c) 1992, 1993 by Mark Davidsaver all upper case so no 'descenders' will be outside the button area. 2) If the system font is quite a bit larger than the selected font then BasicBasic will not use the standard Windows button design. Instead it will draw a 'simplified' button which can hold the small text of the font. 98 Copyright (c) 1992, 1993 by Mark Davidsaver ERROR MESSAGES ------------------------------------------------------- Compile errors will give a description of the problem and display the line where the error occurred. Runtime errors are divided into two classes. Fatal errors always cause execution of the program to cease. Recoverable errors cause program execution to cease if SETERRLEVEL is 7, overwise execution continues and the error number is placed in the system variable ERR. SETERRLEVEL 7 is the default. When runtime errors are displayed they are accompanied by a runtime address. BasicBasic will output a list of runtime addresses for each statement. These addresses will be contained in a file with the same name as the source file and an extension of .TMP. Fatal Errors: error number description ------------ ----------- 236 Out of memory 503 READ is attempting to read wrong kind of data. 501 Out of string variable space 516 Out of string variable space 517 ... 522 Internal runtime errors. 523 Wrong number of array elements or array not dimensioned. 524 Out of free space. 525 Out of string space. 526 Return without gosub 527 Not enough memory for menu 528 SUB without CALL 529 END SUB without CALL 530 Out of space for functions 531 SUB/CALL have different # of parms Recoverable Errors: 1000 Error attempting to open file 1001 Attempt to read past end of file 1002 File not open 1003 File read error (probably hardware) 1004 ASC function on empty string 1005 Divide by zero 1006 Out of data during READ 99 Copyright (c) 1992, 1993 by Mark Davidsaver 1007 File already open 1008 No available file control block 1009 Error attempting to open file 1010 File mode error on read 1011 File mode error on write 1012 Bad file number 1013 Path not found 1014 RMDIR error 1015 MKDIR error 1016 KILL error 1017 FILE BUFFER ERROR 1018 INVALID FIELD DATA 1019 FIELD OVERFLOW 1020 FILE ERROR 1021 COMMUNICATIONS OPEN ERROR 1022 CREATE BUTTON ERROR 1023 BAD SCREEN MODE IN SCREEN COMMAND 1025 GRAPHICS GET ARRAY ERROR 1026 GRAPHICS PUT ARRAY ERROR 1027 CREATE FONT ERROR 1028 NOT IN CORRECT SCREEN MODE 1029 INVALID COLOR/COLOR ATTRIBUTE 1030 ILLEGAL FONT NUMBER 1031 FONT NOT DEFINE 1032 PALETTE NOT DEFINED 1033 BITMAP COMPRESS ERROR 1034 NOT ENOUGH MEMORY TO LOAD BITMAP 1035 UNKNOWN ERROR READING BITMAP 1036 UNKNOWN BITMAP TYPE 1037 ERROR STORING BITMAP FILE 1038 BITMAPH FAILURE 1039 NOT A BITMAP FILE 1040 CREATEBITMAP-NOT ENOUGH MEMORY 1041 SELECTBITMAP ERROR 1042 COPYBITS ERROR 1043 INVALID CONTROL IN DIALOG 1044 NOT ENOUGH MEMORY FOR DIALOG 1045 CHDIR ERROR 1046 CHDRIVE ERROR 1047 CREATEBITMAP DATA INVALID 1048 STRING TOO SHORT 1049 INVALID CREATE WINDOW COMMAND 1050 NOT ENOUGH SPACE TO CREATE WINDOW 1051 INVALID WINDOW NUMBER 1052 FILE ACCESS ERROR 1053 LOCK FAILURE 1054 SOUND DEVICE NOT FOUND 1055 INVALID SOUND FILE FORMAT 1056 SOUND NOT PLAYED 100 Copyright (c) 1992, 1993 by Mark Davidsaver KEYBOARD CODES ------------------------------------------------------- The following table shows the key codes returned by the INKEY$ function. These key codes are returned as 1 byte. KEY DECIMAL KEY DECIMAL KEY DECIMAL KEY CODE KEY CODE KEY CODE ESC 27 BKSP 8 1 49 ! 33 TAB 9 2 50 @ 64 ENTER 13 3 51 # 35 SPACE 32 4 52 $ 36 5 53 % 37 6 54 ^ 94 7 55 & 38 8 56 * 42 9 57 ( 40 0 48 ) 41 - 45 _ 95 = 61 + 43 KEY DECIMAL KEY DECIMAL KEY DECIMAL KEY CODE KEY CODE KEY CODE A 65 a 97 B 66 b 98 C 67 c 99 D 68 d 100 E 69 e 101 F 70 f 102 G 71 g 103 H 72 h 104 I 73 i 105 J 74 j 106 K 75 k 107 L 76 l 108 M 77 m 109 N 78 n 110 O 79 o 111 P 80 p 112 Q 81 q 113 R 82 r 114 S 83 s 115 T 84 t 116 U 85 u 117 V 86 v 118 W 87 w 119 X 88 x 120 Y 89 y 121 Z 90 z 122 101 Copyright (c) 1992, 1993 by Mark Davidsaver The following table shows the extended key codes returned by the INKEY$ function. These key codes are returned as 2 characters. In this case the first character will be 0. KEY DECIMAL KEY CODE ---- ------ F1 0 59 F2 0 60 F3 0 61 F4 0 62 F5 0 63 F6 0 64 F7 0 65 F8 0 66 F9 0 67 F10 0 68 CTRL-F1 0 94 CTRL-F2 0 95 CTRL-F3 0 96 CTRL-F4 0 97 CTRL-F5 0 98 CTRL-F6 0 99 CTRL-F7 0 100 CTRL-F8 0 101 CTRL-F9 0 102 CTRL-F10 0 103 SHIFT-F1 0 84 SHIFT-F2 0 85 SHIFT-F3 0 86 SHIFT-F4 0 87 SHIFT-F5 0 88 SHIFT-F6 0 89 SHIFT-F7 0 90 SHIFT-F8 0 91 SHIFT-F9 0 92 SHIFT-F10 0 93 HOME 0 71 UP ARROW 0 72 PGUP 0 73 LEFT ARROW 0 75 RIGHT ARR 0 77 END 0 79 DOWN ARROW 0 80 PGDN 0 81 INS 0 82 DEL 0 83 CTRL-HOME 0 119 CTRL-PGUP 0 132 CTRL-LEFT 0 115 CTRL-RIGHT 0 116 CTRL-END 0 117 CTRL-PGDN 0 118 102 Copyright (c) 1992, 1993 by Mark Davidsaver Windows is a registered trademark of Microsoft Corporation. 103