Liberty Basic is develeopped by Carl Gundel Original Newsletter compiled by Alyce Watson and Brosco Translation to HTML: Raymond Roumeas
In this issue:
Writing a Liberty BASIC Editor - Part One
In future issues:
This series will present a step-by-step tutorial on writing a program in Liberty BASIC. Part One will focus on getting a minimal editor up and running, while later parts will add features such as a toolbar and tooltips.
The methods used here will apply to other types of program creation as well, of course.
The code here is to be considered Open Source, in the public domain. It is free for anyone to modify, and the publishing of permutations is ENCOURAGED! If you publish a modification of this code, please be sure to include your name.
Well, let's call them guidelines, shall we? There will only be a few!
1. No extra files. This code will not rely on additional data files, bitmaps, wavs, etc. It will not use any add-on DLLs or other executables.
2. Do it with LB commands, when possible. If there is an LB way to do something, do not use an api call. For instance, we will use the NOTICE command, rather than the MessageBox API call.
3. Keep it modular. Make all additions into routines that either end with RETURN (a GOSUB routine) or a return to the input loop - GOTO [loop].
4. Document variables. There is a variable list at the head of the code. Document all variables here, please.
We need a clear idea of what our program should do before we begin. Here is a list of functions:
The minimum editor program needs a texteditor! We could use a Text Window, but that does not provide the flexibility we need, so we will use a plain window containing a texteditor control. We will also want to trap the close event that happens when a user closes with the system close box (X). We will also provide instructions for a resize event. It is true that we could send the textedit control a message to resize itself automatically, but we probably want to add other things to the window later, so we will need a resize routine anyway. We also need to set the input focus on the texteditor, so that when a user types on the keyboard, the input will be displayed in the texteditor. Don't forget that commands are sent to a text editor preceeded by the "!" character.
This informs Liberty BASIC that you are issuing a command. Otherwise, the string within the quote marks will be displayed in the texteditor.
texteditor #1.t, 0,40,600,400 'edit window open "Open Source LB Editor" for window as #1 print #1, "trapclose [quit]" print #1, "resizehandler [resize]" print #1.t, "!setfocus";
It really doesn't matter what size and placement we give our texteditor within the window initially. We have used the RESIZEHANDLER command, so the program will automatically execute the resize routine at startup. The texteditor will appear within the window according to the values we place into the "!locate" command. Don't forget to issue a "refresh" command to show the new look of the window. The refresh command goes to the window, not to the texteditor. Note also that after a resize event, the dimensions of the windows CLIENT AREA are contained in the variables WindowWidth and WindowHeight.
[resize]'** LOCATE TEXT EDITOR print #1.t, "!locate 0 0 ";WindowWidth-1;" ";WindowHeight-1 print #1.t, "!origin?"; input #1.t, rowVar,columnVar '** UPDATE WINDOW print #1, "refresh" print #1.t, "!origin ";rowVar;" ";columnVar;""; goto [loop]
We will not need a mainwindow, but we will need to call on USER DLL, so we will open it at startup. We will also need the handle of the window for api function calls, so we'll get that at startup as well. We can set a width and height, and placement for our window at startup, or we can maximize the window at startup. Let's maximize it with the ShowWindow api call.
nomainwin open "user" for dll as #user h=HWND(#1) calldll #user, "ShowWindow",h as word,_ _SW_MAXIMIZE as ushort,result As word
We need a menu! The commands to create all controls and menus must be listed before the window is opened, so place these menu commands before the OPEN command. Here are menu items for each of the functions we listed in our specifications.
menu #1, "&File",_ "&New",[new],_ "&Open",[open],_ "&Save",[save],_ "Save &As",[saveas],|,_ "&Print",[print],_ "E&xit",[quit] menu #1, "&Edit" 'LB supplies the Edit Menu menu #1, "&Run",_ "Ru&n", [run],_ "&Debug",[debug],_ "&Make TKN",[maketkn],_ "Run &TKN",[runtkn] menu #1, "E&xternals",_ "&Paintbrush",[paint],_ "&File Manager",[winfile],_ "&Notepad",[notepad],_ "&Calculator",[calculator] menu #1, "&Help",_ "&Liberty BASIC Help",[help],_ "LB &Tutorial",[tutorial]
Have a look at the branch labels referenced in the menus. They are descriptive. There is no doubt of what a routine called [save] will do, or one called [run]. We can choose labels that are a manageable size, but still readable. Please follow this pattern if you add to this code!
Notice that the Edit Menu has NO ITEMS! Liberty BASIC automatically supplies a complete edit menu with a texteditor control. We don't need to list an Edit menu at all. We have listed it here, so that we can guarantee that it is placed in the proper spot on the menu bar. If we did not, it might appear in an awkward location, and most applications have the Edit menu just to the right of the File menu. If we had listed menu items for our Edit menu, the program would have used them instead of the default Edit menu items. AND WOW! did you know that you get the same Edit menu when you right click within a texteditor?
Many languages require the programmer to declare all variables. Liberty BASIC does not make that necessary. You create new variables on demand, just by using them This makes programming EASY, but it also gives us the opportunity to goof up BIG TIME. Let's make a habit of keeping a variable list at the top of the code. Any time we introduce a new variable, we will first check for a variable already in use with the same name. If the name checks out okay, we'll add it to our list and describe its function briefly. Here is a start on the variable list:
'variables: 'file$ name of file to open 'title$ titlebar caption 'h is window handle
If there is nothing contained in the texteditor, we can start typing to make a file. If another file is loaded into the editor, we'll need to clear the texteditor and change the loaded filename to "untitled.bas". We clear the texteditor with the "!CLS" command. WAIT A MINUTE! I FORGOT TO SAVE MY WORK! OH NO!
Obviously, we had better check to see if the loaded file has been modified, and offer the user a chance to save. We'll soon create a routine called [isModified] that will accomplish that. It is also pretty common to display the loaded filename on the window's titlebar.
We'll make a routine called [settext] to do that.
[new]'** CLEAR EDITOR CONTENTS, RESET VARIABLES gosub [isModified] print #1.t, "!cls" file$="untitled.bas" filePath$="" gosub [settext] goto [loop]
Clearly, we need those two subroutines now! If we want to find out if the contents of a texteditor have been modified, we use the "!modified?" command. We get the answer to our question by using an input statement. The receiver variable (we are calling ours modflag$) will contain "true" if it has been modified, and "false" if it has not been modified. If the file has not been changed, then we need do nothing. Notice that the previous sentence contained an IF...THEN? We'll also need that in our code.
If our modflag$ is "true" we'll need to ask the user if he would like to save his work. Liberty BASIC has a special dialog for us to use. We will CONFIRM with the user whether or not he would like to save. The answer to our question will be in the variable, answer$ It can be either "yes" or "no". If it is "yes" we will need to call on our subroutine to save the file. Although it is not yet written, we know we will call it [savesub].
Wow, what a lot of words to describe such a small routine! See if it makes sense, and if you can follow the nested IF...THEN conditional statements:
[isModified]'** CHECK TO SEE IF FILE HAS BEEN MODIFIED print #1.t, "!modified?":input #1.t, modflag$ if modflag$="true" then confirm "This file has been modified. Save?";answer$ if answer$="yes" then gosub [savesub] end if RETURN
Our [new] routine also refers to the routine to add the filename to the titlebar. For this, we need to give a value to the title$ variable, and make the api call to SetWindowText, with "h as word" as the handle of the window, and "title$ as ptr" as the text to place on the titlebar:
[settext]'** ADD FILENAME TO TITLEBAR title$="Open Source LB Editor "+file$ calldll #user, "SetWindowText", h as word, title$ as ptr, result as void return
HEY, WHY MAKE [isModified] and [settext] SEPARATE ROUTINES? Why not just include the code in the [new] routine? There is a good reason to make these separate routines. We will need to check to see if the contents of the editor have changed when we want to open a file, and when we want to quit. By making it a subroutine, we only need to code it once. We'll change the titlebar text in our [open] routine also, so it is coded as a subroutine, or GOSUB.
When we allow the user to open a new file, we will first check to see if the current contents have been changed Then, we use a file dialog to get the name of the file that should be used. Be sure to trap the possiblity that no file was chosen, and send the program to the input loop if that is the case.
[open] gosub [isModified] filedialog "Open file..",filePath$+"*.bas",file$ if file$="" then [loop]
By default, a filedialog will always open in the program's DefaultDir$. If you look at most commercial applications, you will see that a file dialog opens in the same directory as the last chosen file. We can do that, also. We must parse the string containing the path and filename, to separate them from one another and place them within variables. We do this by starting at the end of the filename string and checking for a "\" character. We move one space to the left each time until we find the backslash. That is the spot that separates the path from the filename.
fileindex=len(file$) 'separate path and filename filelength=len(file$) while mid$(file$, fileindex,1)<>"\" fileindex=fileindex-1 wend
Once we know the location of the rightmost backslash, we can place the right side of the string into the shortFile$ variable, that contains just the filename, and the left side of the string into the filePath$ variable, that contains the path alone.
shortFile$=right$(file$,filelength-fileindex) filePath$=left$(file$,fileindex)
This allows us to open the filedialog in the previously accessed directory. Note that if filePath$ = "", the filedialog will open in the program's default directory.
filedialog "Open file..",filePath$+"*.bas",file$
Did you know that attempting to open a file that does not exist for INPUT will crash your program? We can trap that error by using the FILES statement. If the file does not exist, we do not attempt to open it!
We must DIM an array to hold our file/directory information. It must be a double-dimensioned array. We can DIM to any values we want because the FILES function will REDIM the array as needed:
dim info$(10,10)
Then we use the FILES statment, checking the value of our array element (0,0). If it is < 1, the file does not exist, so we'll give the user an error notice and return to the input loop.
'** USE FILES STATEMENT TO CHECK FOR FILE'S EXISTENCE
files filePath$,shortFile$,info$( if val(info$(0,0))<1 then notice "Error"+chr$(13)+"File does not exist." goto [loop] end if
If the file exists, we next open it for input, and overwrite any existing contents of the texteditor with the contents of the file, with the "!contents #file" command. Be sure to close the file! We can then place the filename on the titlebar. Let's also place the texteditor at the beginning of the file with an "!origin 1 1" command, which causes the upper right corner of the texteditor to display row one and column one of the file.
[loadFile]'** OPEN FILE AND LOAD INTO TEXTEDITOR cursor hourglass open file$ for input as #file print #1.t, "!contents #file" close #file gosub [settext] print #1.t, "!origin 1 1"; cursor normal goto [loop]
It is easy to save the contents of a texteditor to a file on disk with the "!contents?" command. We must follow this command with an input command, which places the contents of the texteditor into the string variable we specify. Here, we are calling that variable "saveit$"
[savesub] cursor hourglass print #1.t, "!contents?"; input #1.t, saveit$
Once we have the contents in a string variable, we can open the file for OUTPUT and print the string variable, saveit$ to the file. Be sure to close the file. It is a good idea to give the user a notice that the file was, indeed, saved. Be advised that a file opened for OUTPUT will have its previous contents erased and replaced with the new contents.
open file$ for output as #file print #file, saveit$ close #file cursor normal notice "File saved as "+ file$ RETURN
We have given files a default name of "untitled.bas", so we should check the filename, and if it is null, or if it is "untitled.bas", we'll ask the user to choose a name.
'** IF THERE IS NO CURRENT FILENAME, ASK USER FOR ONE if (right$(file$,12)="untitled.bas") or (file$="") then filedialog "Save file as...",filepath$+"*.bas",file$ if file$="" then notice "You must choose a file name." RETURN end if end if
Here, we allow the user to choose a different name for the file and save as that name. After the filename choice has been made, we save the file exactly as before.
[saveas]'** SAVES CONTENTS AS file$ filedialog "Save file as..",filePath$+"*.bas",file$ if file$="" then notice "You must choose a file name." goto [loop] end if gosub [settext] [save]'** SAVES CURRENT FILE gosub [savesub] goto [loop]
We start our print routine by retrieving the current location of the texteditor upper left corner within the file, so we can return it to that spot after our routine finishes. Then, we place the contents of the texteditor into a string variable in just the same way as we did in our save routine. We then simply issue an LPRINT command: lprint saveit$. We use the DUMP command to send the job to the printer for immediate printing. Without DUMP, the printing would still happen, but there might be a delay.
[print] cursor hourglass print #1.t, "!origin?"; input #1.t, rowVar,columnVar print #1.t, "!contents?"; input #1.t, saveit$ lprint saveit$ dump print #1.t, "!origin ";rowVar;" ";columnVar;""; cursor normal goto [loop]
We don't have to do any coding for this. Liberty BASIC automatically gives us a full Edit menu!
Liberty.exe can be run from another program by using command line switches. More about these later. The first thing we need to do in order to run the code in our texteditor is to write the contents to a temporary file. We get the contents just as we did when we wanted to save the file. We need to be sure the temporary file is placed in the same directory as the opened file, so that it can find any associated files, such as bmps. We'll give our temporary file the path we have saved in filePath$ plus the filename "tempfile.bas", then open that file for output and write the contents to the temporary file on disk, then close the temp file.
It is proper etiquette to clean up after ourselves, not leaving a bunch of temporary files on the user's system!
Before we write a new temp file, we check for the existence of a previous temp file. If there is one, we KILL it. We'll do this same KILL procedure when we exit.
[readyRun]'** MAKE A TEMP FILE TO RUN IN LIBERTY BASIC '** GET CURRENT TEXTEDIT ORIGIN print #1.t, "!origin?"; input #1.t, rowVar,columnVar '** GET CONTENTS OF TEXTEDITOR AND SAVE TO TEMPFILE if tempfilename$<>"" then kill tempfilename$ print #1.t, "!contents?" input #1.t, saveit$ tempfilename$=filePath$+"tempfile.bas" open tempfilename$ for output as #temp print #temp, saveit$ close #temp if libertyexe$="" then gosub [findLiberty] RETURN
Now that we have a temporary file on disk, we are ALMOST ready to run it with LB. Our program must know where Liberty.exe is located in order to run it. We've set up a variable that holds the location of liberty.exe. We've called it "libertyexe$" so it is easy to remember We'll check to see if libertyexe$ has a value. If it does, we can continue. If it does not, we must ask the user to find the path to liberty.exe. The user will only need to do this once, of course, placing the path into the liberyexe$ variable for all later uses.
[findLiberty]'** FIND LIBERTY.EXE filedialog "Find Liberty.exe","liberty.exe",libertyexe$ RETURN
COMMAND LINE SWITCHES - here they are, as listed in the file new14.txt:
-R Run a BAS file on startup -D Debug a BAS file on startup --------the following three are in the registered version only-------- -T Make a TKN file from a BAS file on startup -A Automatically Exit LB on completion of BAS file -M Minimize the Liberty BASIC editor on startup
Examples:
LIBERTY -R -M PROG.BAS 'run PROG.BAS with editor minimized LIBERTY -T -A PROG.BAS 'create a TKN file from PROG.BAS then exit LIBERTY -D PROG.BAS 'run the debugger on PROG.BAS
A simple example might be:
RUN "LIBERTY.EXE -R boxes.bas"
Of course, we'll use the path in libertyexe$ in our command, plus our temporary filename. Here it is:
[run] gosub [readyRun] run libertyexe$+" -R -A -M "+tempfilename$ print #1.t, "!origin ";rowVar;" ";columnVar;""; goto [loop]
Everything is just the same when running the debugger on the contents of our texteditor, except we use the -D switch instead of the -R switch!
[debug] gosub [readyRun] run libertyexe$+" -D -A -M "+tempfilename$ print #1.t, "!origin ";rowVar;" ";columnVar;""; goto [loop]
Again, we follow the same routine when we want to make a tokenized version of the contents of our texteditor, except we use the -T switch instead of the -R switch!
[maketkn] gosub [readyRun] run libertyexe$+" -T "+tempfilename$ print #1.t, "!origin ";rowVar;" ";columnVar;""; goto [loop]
Liberty BASIC will run any tokenized program with the RUN command, like so:
[runtkn] filedialog "Choose TKN..","*.TKN",tknfile$ run tknfile$ goto [loop]
These functions are incredibly easy to code! We just need LB's RUN command. We can specify the manner as SHOWNORMAL, but that is optional, since it is the default. We can call "pbrush.exe" and it will run PaintBrush in Win3.1 and Paint in Win95+. Notepad.exe is available on all systems and so is File Manager, or winfile.exe. Yep, it's there on Win95+ also! Calculator is called "calc.exe". Windows knows where to find these applications, so you do not need to code a path to them. Pretty handy!
[paint] run "pbrush.exe",SHOWNORMAL goto [loop] [notepad] run "notepad.exe",SHOWNORMAL goto [loop] [winfile] run "winfile.exe",SHOWNORMAL goto [loop] [calculator] run "calc.exe" ,SHOWNORMAL goto [loop]
Windows has a machine to run helpfiles, called Winhelp. We could parse the filePath$ variable to run the two LB helpfiles:
helpPath$=left$(filePath$,len(filePath$)-11) run "winhelp "+helpPath$+" liberty.help" run "winhelp "+helpPath$+" tutorial.help"
We don't really need to do this, however. Once Winhelp has run a helpfile, it will remember the location! If we run liberty.hlp once, Winhelp will thereafter be able to find it, unless of course we move it. If Winhelp does not know the location of a help file, it will ask the user to find the helpfile, and in future Winhelp remembers that location. Let's be just a little lazy and let Winhelp do some of our work for us:
[help] run "winhelp liberty.hlp" goto [loop] [tutorial] run "winhelp tutorial.hlp" goto [loop]
'** Liberty BASIC Newsletter '** Open Source Editor '** Please add your name to '** the list of authors: '** '** Authors: '** '** Alyce Watson '** nomainwin open "user" for dll as #user dim info$(10,10) 'for file exist check cursor hourglass 'variables: 'file$ name of file to open 'title$ titlebar caption 'h is window handle 'modflag$ is answer to modified query 'answer$ receiver variable for confirm messages 'tempfilename$ name to use when running and debugging code 'rowVar,columnVar location of texteditor origin 'fileindex used for counter in path/file separation 'filelength used for counter in path/file separation 'shortFile$ just filename without path 'filePath$ path without filename 'saveit$ receiver for input from texteditor 'libertyexe$ path to Liberty.exe for running/tokenizing/debugging 'tknfile$ name of tkn to run menu #1, "&File",_ "&New",[new],_ "&Open",[open],_ "&Save",[save],_ "Save &As",[saveas],|,_ "&Print",[print],_ "E&xit",[quit] menu #1, "&Edit" 'LB supplies the Edit Menu menu #1, "&Run",_ "Ru&n", [run],_ "&Debug",[debug],_ "&Make TKN",[maketkn],_ "Run &TKN",[runtkn] menu #1, "E&xternals",_ "&Paintbrush",[paint],_ "&File Manager",[winfile],_ "&Notepad",[notepad],_ "&Calculator",[calculator] menu #1, "&Help",_ "&Liberty BASIC Help",[help],_ "LB &Tutorial",[tutorial] texteditor #1.t, 0,40,600,400 'edit window open "Open Source LB Editor" for window as #1 h=HWND(#1) print #1, "trapclose [quit]" print #1, "resizehandler [resize]" calldll #user, "ShowWindow",h as word,_SW_MAXIMIZE as ushort,result As word print #1.t, "!setfocus"; cursor normal [loop] input a$ [quit] gosub [isModified] close #user: close #1 if tempfilename$<>"" then kill tempfilename$ END [isModified]'** CHECK TO SEE IF FILE HAS BEEN MODIFIED print #1.t, "!modified?":input #1.t, modflag$ if modflag$="true" then confirm "This file has been modified. Save?";answer$ if answer$="yes" then gosub [savesub] end if RETURN [resize]'** LOCATE TEXT EDITOR print #1.t, "!locate 0 0 ";WindowWidth-1;" ";WindowHeight-1 print #1.t, "!origin?"; input #1.t, rowVar,columnVar '** UPDATE WINDOW print #1, "refresh" print #1.t, "!origin ";rowVar;" ";columnVar;""; goto [loop] [new]'** CLEAR EDITOR CONTENTS, RESET VARIABLES gosub [isModified] print #1.t, "!cls" file$="untitled.bas" filePath$="" gosub [settext] goto [loop] [open] gosub [isModified] filedialog "Open file..",filePath$+"*.bas",file$ if file$="" then [loop] fileindex=len(file$) 'separate path and filename filelength=len(file$) while mid$(file$, fileindex,1)<>"\" fileindex=fileindex-1 wend '** USE FILES STATEMENT TO CHECK FOR FILE'S EXISTENCE shortFile$=right$(file$,filelength-fileindex) filePath$=left$(file$,fileindex) files filePath$,shortFile$,info$( if val(info$(0,0))<1 then notice "Error"+chr$(13)+"File does not exist." goto [loop] end if [loadFile]'** OPEN FILE AND LOAD INTO TEXTEDITOR cursor hourglass open file$ for input as #file print #1.t, "!contents #file" close #file gosub [settext] print #1.t, "!origin 1 1"; cursor normal goto [loop] [settext]'** ADD FILENAME TO TITLEBAR title$="Open Source LB Editor "+file$ calldll #user, "SetWindowText", h as word, title$ as ptr, result as void return [saveas]'** SAVES CONTENTS AS file$ filedialog "Save file as..",filePath$+"*.bas",file$ if file$="" then notice "You must choose a file name." goto [loop] end if gosub [settext] [save]'** SAVES CURRENT FILE gosub [savesub] goto [loop] [savesub] cursor hourglass print #1.t, "!contents?"; input #1.t, saveit$ '** IF THERE IS NO CURRENT FILENAME, ASK USER FOR ONE if (right$(file$,12)="untitled.bas") or (file$="") then filedialog "Save file as...",filePath$+"*.bas",file$ if file$="" then notice "You must choose a file name." RETURN end if end if open file$ for output as #file print #file, saveit$ close #file cursor normal notice "File saved as "+ file$ RETURN [print] cursor hourglass print #1.t, "!origin?"; input #1.t, rowVar,columnVar print #1.t, "!contents?"; input #1.t, saveit$ lprint saveit$ dump print #1.t, "!origin ";rowVar;" ";columnVar;""; cursor normal goto [loop] [readyRun]'** MAKE A TEMP FILE TO RUN IN LIBERTY BASIC '** GET CURRENT TEXTEDIT ORIGIN print #1.t, "!origin?"; input #1.t, rowVar,columnVar '** GET CONTENTS OF TEXTEDITOR AND SAVE TO TEMPFILE if tempfilename$<>"" then kill tempfilename$ print #1.t, "!contents?" input #1.t, saveit$ tempfilename$=filePath$+"tempfile.bas" open tempfilename$ for output as #temp print #temp, saveit$ close #temp if libertyexe$="" then gosub [findLiberty] RETURN [findLiberty]'** FIND LIBERTY.EXE filedialog "Find Liberty.exe","liberty.exe",libertyexe$ RETURN [run] gosub [readyRun] run libertyexe$+" -R -A -M "+tempfilename$ print #1.t, "!origin ";rowVar;" ";columnVar;""; goto [loop] [debug] gosub [readyRun] run libertyexe$+" -D -A -M "+tempfilename$ print #1.t, "!origin ";rowVar;" ";columnVar;""; goto [loop] [runtkn] filedialog "Choose TKN..","*.TKN",tknfile$ run tknfile$ goto [loop] [maketkn] gosub [readyRun] run libertyexe$+" -T "+tempfilename$ print #1.t, "!origin ";rowVar;" ";columnVar;""; goto [loop] [paint] run "pbrush.exe",SHOWNORMAL goto [loop] [notepad] run "notepad.exe",SHOWNORMAL goto [loop] [winfile] run "winfile.exe",SHOWNORMAL goto [loop] [calculator] run "calc.exe" ,SHOWNORMAL goto [loop] [help] run "winhelp liberty.hlp" goto [loop] [tutorial] run "winhelp tutorial.hlp" goto [loop]
Comments, requests or corrections: Hit 'REPLY' now!
mailto:brosc-@orac.net.au or mailto:awatso-@wctc.net