Copyright: This helpfile copyright 1992-2000 Shoptalk Systems


Command Reference
Command Reference A-C

Jump to Liberty BASIC Help Document

   A-C D-F G-K L-M N-P R-S T-W

ABS( n )	absolute value

ACS( n )	arc-cosine of n

ASC( s$ )	ascii value of s$

ASN( n )	arc-sine of n

ATN( n )	arc-tangent of n

BEEP	play the default system wave file

BMPBUTTON	add a bitmap button to a window

BMPSAVE	save a bitmap to a disk file

BUTTON	add a button to a window

CALL	call a user defined subprogram

CALLDLL	call an API or DLL function

CHECKBOX   	add a checkbox to a window

CHR$( n )	return character of ascii value n

CLOSE #h	close a file or window with handle #h

CLS	clear a program's mainwindow

COMBOBOX	add a combobox to a window

CommandLine$	contains any command line switches used on startup

CONFIRM	opens a confirm dialog box

COS( n )	cosine of n

CURSOR	changes the mouse cursor

  more...


more (skip to next page) - Command Reference part 2
Command Reference - Part 2

    Back to Command Reference - Part 1

TAN( n )	tangent of n

Text Commands	a detailed summary of text window commands in Liberty BASIC

TEXTBOX	add a textbox (entryfield) to a window

TEXTEDITOR	add a texteditor widget to a window

TIME$( )	returns current time as string

TIMER	manage a Windows timer

TITLEBAR	sets the title bar of the main window

TRACE n	sets debug trace level to n

TRIM$( s$ )	returns s$ without leading/trailing spaces

UNLOADBMP	unloads a bitmap from memory

UPPER$( s$ )	s$ converted to all uppercase

USING( )	performs numeric formatting

UpperLeftX	specifies the x part of the position where the next window will open

UpperLeftY                 specifies the y part of the position where the next window will open

VAL( s$ )	returns numeric equivalent of s$

Version$	special variable containing LB version info

WAIT	stop and wait for user interaction

WHILE...WEND	performs looping action

WindowWidth	specifies the width of the next window to open

WindowHeight	specifies the height of the next window to open

WORD$( s$, n )	returns nth word from s$


ABS( n )

Description:

  This function returns  | n |  (the absolute value of n).

Usage:

  print abs( -5)                   produces:  5

  print abs( 6 - 13 )            produces: 7


ACS( n )

Description:

  Returns the arc-cosine of the number n.

Usage:

  for c = 0 to 1 step 0.01

    print "The arc-cosine of "; c; " is "; acs(c)

  next c

Note:  See also COS( )


ASC( s$ )

Description:

  This function returns the ASCII value of the first character of string s$.

Usage:

  print asc( "A" )              produces:  65

  let name$ = "Tim"

  firstLetter = asc(name$)

  print firstLetter             produces:  84

  print asc( "" )               produces:  0


ASN( n )

Description:

  Returns the arcsine of the number n.

Usage:

  for c = 0 to 1 step 0.01

    print "The arcsine of "; c; " is "; asn(c)

  next c

Note:  See also SIN( )


ATN( n )

Description:

  Returns the arc-tangent of the number n.

Usage:

  for c = 1 to 45

    print "The arctangent of "; c; " is "; atn(c)

  next c

Note:  See also TAN( )


BEEP

Description:

Play the default system wave file.  This is usually set to a sound best described as a 'ding'. Processing will stop until the wave file is done playing.

Usage:

  if warning = 1 then beep

Note:  See also PLAYWAVE


BMPBUTTON

BMPBUTTON #handle.ext, filespec, return, corner, posx, posy

Description:

This statement lets you add bitmapped buttons to windows that you open. The main program window cannot have buttons added, but any window that you create via the OPEN command can have as many buttons as you want.

Usage:

Before you actually OPEN the window, each bitmapped  button must be declared with a BMPBUTTON statement.  Here is a brief description for each parameter as listed above:

#handle.ext - You must use the same handle that will be used for the window that

 the button will belong to, plus an optional unique extension.

filespec   - The full pathname of the *.bmp file containing the bitmap for the

  button you are creating.  The button will be the same size as the

  bitmap.

return  - Again, use only one word and do not bound it with quotes or use a

  string variable.  If return is set to a valid branch label, then when

  the button is pressed, execution will restart there (just as with

  GOTO or GOSUB), but if return is not a valid branch label, then the

  value of return is used as input to a specified variable (as in

  input a$).

corner  - UL, UR, LL, or LR specifies which corner of the window to anchor

  the button to.  For example, if LR is used, then the button will

  appear in the lower right corner.  UL = upper left, UR = upper

  right, LL = lower left, and LR = lower right

posx, posy - These parameters determine how to place the button relative

  to  the corner it has been anchored to.  For example if corner is LR,

  posx is 5, and posy is 5, then the button will be 5 pixels up and

  left of the lower right corner.  Another way to use posx & posy is

  to use values less than one.  For example, if corner is UL, posx

  is .9, and posy is .9, then the button will be positioned 9/10th of

  the distance of the window in both x and y from the upper left

  corner (and thus appear to be anchored to the lower right corner).

A collection of button *.bmp has been included with Liberty BASIC, including blanks.  Windows Paint can be used to edit and make buttons for Liberty BASIC.

Program execution must be halted at an input statement in order for a button press to be read and acted upon.

A Bmpbutton is a pushbutton that displays itself as a bitmap that you can specify.  Bmpbuttons are easily added to Liberty BASIC windows.  The format is simple:

    bmpbutton #handle.ext, "filename.bmp", [branchLabel], corner, distX, distY

    open "A Window!" for windowtype as #handle

Try this example:

    bmpbutton #main.arrow, "bmp\arrwbttn.bmp", [arrowClicked], UL, 10, 10

    open "Arrow" for window as #main

[loop]

    input r$

    goto [loop]

[arrowClicked]

    message "The arrow button was clicked.  Bye."

    close #main

    end

By placing at least one bmpbutton statement before  the open statement, we can add bmpbutton(s) to the window.  Let's examine each part of the button statement:

    #handle.ext - This needs to be the same as the handle of the window, with

                                 an optional unique extension.

    "filespec" -  The full pathname of the *.bmp file containing the bitmap for the

                               button you are creating.  The button will be the same size as the

                                  bitmap.

    [branchLabel] - This controls what the button does.  When the user clicks

                                  on the button, then program execution continues at

                                  [branchLabel] as if the program had encountered a

                                  goto [branchLabel] statement.

    corner, distX, distY - Corner is used to indicate which corner of the

                                   window to anchor the button to.  DistX and distY

                                   specify how far from that corner in x and y to place

                                   the button.  The following values are permitted for

                                   corner:

                      UL - Upper Left Corner

                      UR - Upper Right Corner

                      LL - Lower Left Corner

                      LR - Lower Right Corner

  print #handle.ext, "bitmap bitmapname"

    Set the bitmap of the control to be the bitmap named bitmapname (not

    the filename of the bitmap).  See the included BITMAP.BAS program for

    a demonstration.

  print #handle.ext, "locate x y width height"

    Reposition the control in its window.  This is effective when the control

    is placed inside window of type window or dialog.  The control will not

    update its size and location until a refresh command is sent to the

    window.  See the included RESIZER.BAS example program.

  print #handle.ext, "setfocus"

    This will cause the bmpbutton to receive the input focus.  This means that any

    keypresses will be directed to the bmpbutton.

See also: BUTTON, MENU


BUTTON

BUTTON #handle.ext, "label", [clickHandler], corner, x, y

or...

BUTTON #handle.ext, "label", [branch], corner, x, y, wide, high

Description:

Add a button that has a text label as specified by the string expression "label".  When the user clicks on the button, transfer the flow of execution to the event handler code at [clickHandler].  The corner parameter specifies where to anchor position from.  This is either the upper-left, upper-right, lower-left or lower-right corner of the window (UL, UR, LL, LR).  The x and y parameters position the button relative to the specified corner.  Finally, the wide and high parameters are optional.  These allow you to specify the size of the button instead of letting Liberty BASIC autosize the buttons for you.

Usage:

Before you actually OPEN the window, each button must be declared with a BUTTON statement.  Here is a brief description for each parameter as listed above:

#handle.ext - You must use the same handle that will be used for the window that

  the button will belong to, plus an optional unique extension.

"label"   - Type the label desired for the button here.  This may be a string literial

  or any valid string expression.

[clickHandler]  - Specify a branch label here where the button's event handler code is.

corner  - UL, UR, LL, or LR specifies which corner of the window to anchor

  the button to.  For example, if LR is used, then the button will

  appear in the lower right corner.  UL = upper left, UR = upper

  right, LL = lower left, and LR = lower right

x, y - These parameters determine how to place the button relative

  to the corner it has been anchored to.

wide, high - These optional parameters determine how wide and high the button

  will be in pixels.

Here are the commands (in alphabetical order):

  print #handle.ext, "!string"

    Change the text displayed in the field part of the combobox to the string after !.

  print #handle.ext, "!locate x y width height"

    Reposition the button control in its window.  This only works if the control

    is placed inside window of type window or dialog.  The control will not

    update its size and location until a refresh command is sent to the window.

    See the included RESIZER.BAS example program.

  print #handle.ext, "!font facename pointSize"

    Set the button's font to the specified face and point size.  If an

    exact match cannot be found, then Liberty BASIC will try to find a

    close match, with size being of more prominance than face.

    For more on specifying fonts read How to Specify Fonts

    Example:

      print #handle.ext, "!font times_new_roman 10"


CALLDLL

CALLDLL #handle, "function", parm1 as type1 [, parm2 as type2 ], return as returnType

Description:

CALLDLL is used to call functions from the Windows API or from a third party DLL (or one you might write yourself).

Usage:

Here is an example of calling an API that minimizes a window and changes its label text.

    open "An Example" for window as #main

    h = hwnd(#main)

    open "user" for dll as #user

    calldll #user, "CloseWindow", _

        h as word, _

        result as void

    calldll #user, "SetWindowText", _

        h as word, _

        "I was minimized!" as ptr, _

        result as void

    close #user

Here is an example of CALLDLL that uses a struct built using the STRUCT statement.  This demonstrates how to get the corner positions of a window.

    struct winRect, _

        orgX as uShort, _

        orgY as uShort, _

        cornerX as uShort, _

        cornerY as uShort

    open "An Example" for window as #main

    hMain = hwnd(#main)

    open "user.dll" for dll as #user

    calldll #user, "GetWindowRect", _

        hMain as word, _

        winRect as struct, _

        result as void

    close #user

    close #main

    print "Window position upperLeft: "; _

        winRect.orgX.struct; ", "; winRect.orgY.struct

    print "Window position lowerRight: "; _

        winRect.cornerX.struct; " x "; winRect.cornerY.struct

Using Types

The CALLDLL statement requires that each parameter passed be typed.  Simple data types in Windows programming are often just renamed versions of the types below, so just substitute the correct ones.

Here they are:

        double	(a double float)

        dword, ulong	(4 bytes)

        handle	(2 bytes)

        long	(4 bytes)

        short	(2 bytes)

        ushort, word	(2 bytes, substitute this for boolean)

        ptr	(4 bytes, long pointer, for passing strings)

        struct	(4 bytes, long pointer, for passing structs)

        void, none	(a return type only)

Notice:  If you know you will be passing a negative number as a parameter, first convert the number to a unsigned integer value.  This can be done in Liberty BASIC using the OR operator like so:

    variableName  =  -1 or 0    'convert -1 to an unsigned value


CHECKBOX

CHECKBOX #handle.ext, "label", [set], [reset], x, y, wide, high

Description:

Adds a checkbox control to the window referenced by #handle.ext.  Checkboxes have two states, set and reset.  They are useful for getting input of on/off  type information.

  Here is a description of the parameters of the CHECKBOX statement:

    #handle.ext - Specify handle for this control.  The #handle part should be the same

as the handle of the window you're adding the radiobutton to, and the

ext part names the radiobutton uniquely in the window.

    	"label" - This contains the visible text of the checkbox

[set]	- This is the branch label to goto when the user sets the

checkbox by clicking on it.

[reset]	- This is the branch label to goto when the user resets the

checkbox by clicking on it.

x - This is the x position of the checkbox relative to the

upper left corner of the window it belongs to.

y - This is the y position of the checkbox relative to the upper left

corner of the window it belongs to.

wide - This is the width of the checkbox control

high - This is the height of the checkbox control

Usage:  See the included program checkbox.bas for an example of how to use checkboxes

Checkboxes  understand these commands:

    print #handle.ext, "set"

      This sets the checkbox.

    print #handle.ext, "reset"

      This resets the checkbox.

    print #handle.ext, "value? result$"

      The result$ variable will be set to the status of the checkbox (either "set" or "reset").

    print #handle.ext, "setfocus"

      This will cause the combobox to receive the input focus.  This means

      that any keypresses will be directed to the combobox.

    print #handle,ext, "locate x y width height"

      Reposition the burron in its window.  This is effective when the button

      is placed inside window of type window or dialog.  The button will not

      update its size and location until a refresh command is sent to the

      window.  See the included RESIZER.BAS example program.

    print #handle, "font facename pointSize"

      Set the pen's font to the specified face and point size.  If an

      exact match cannot be found, then Liberty BASIC will try to find a

      close match, with size being of more prominance than face.

      For more on specifying fonts read How to Specify Fonts

      Example:

        print #handle.ext, "font times_new_roman 10"


CHR$( n )

Description:

Returns a one character long string, consisting of the character represented on the ASCII table by the value n (0 - 255).

Usage:

  ' print each seperate word in text$ on its own line

  text$ = "now is the time for all great men to rise"

  for index = 1 to len(text$)

      c$ = mid$(text$, index, 1)

      ' if c$ is a space, change it to a carraige return

      if c$ = chr$(32) then c$ = chr$(13)

      print c$ ;

  next index

Produces:

now

is

the

time

for

all

great

men

to

rise


CLOSE #h

Description:

This command is used to close files and devices.  This is the last step of a file read and/or write, or to close windows when finished with them.  If when execution of a program is complete there are any files or devices left open, Liberty BASIC will display a dialog informing you that it found it necessary to close the opened files or devices.  This is designed as an aid for you so that you will be able to correct the problem.  If on the other hand you choose to terminate the program early (this is done by closing the program's main window before the program finishes), then Liberty BASIC will close any open files or devices without posting a notice to that effect.

Usage:

  open "Graphic" for graphics as #gWin  ' open a graphics window

  print #gWin, "home"                   ' center the pen

  print #gWin, "down"                   ' put the pen down

  for index = 1 to 100                  ' loop 100 times

    print #gWin, "go "; index           ' move the pen foreward

    print #gWin, "turn 63"              ' turn 63 degrees

  next index

  input "Press 'Return'."; r$           ' this appears in main window

  close #gWin                           ' close graphic window


CLS

Description:

Clears the main program window of text and sets the cursor back at the upper left hand corner.  Useful  for providing a break to seperate different sections of a program functionally.  Additionally, since the main window doesn't actually discard past information on its own, the CLS command can be used to reclaim memory from your program by forcing the main window to dump old text.

Usage:

  print "The total is: "; grandTotal

  input "Press 'Return' to continue."; r$

  cls

  print "*** Enter Next Round of Figures ***"


CONFIRM

CONFIRM

CONFIRM string; responseVar

Description:

This statement opens a dialog box displaying the contents of string and presenting two buttons marked 'Yes' and 'No'.  When the selection is made, the string "yes" is returned if 'Yes' is pressed, and the string "no" is returned if 'No' is pressed.  The result is placed in responseVar.

Usage:

[quit]

  ' bring up a confirmation box to be sure that

  ' the user wants to quit

  confirm "Are you sure you want to QUIT?"; answer$

  if answer$ = "no" then [mainLoop]

  end


COS( n )

COS( n )

Description:

Returns the cosine of the number n.

Usage:

  for c = 1 to 45

    print "The cosine of "; c; " is "; cos(c)

  next c

Note:  See also SIN( ) and TAN( )


DATE$( )

Description:

Instead of adopting the date$ variable from QBasic, we decided to use a function instead.  This approach gives some additional flexibility.  See also TIME$( )

Usage:

  'This form of date$()       produces this format

  print date$()             ' Nov 30, 1999

  print date$("mm/dd/yyyy") ' 11/30/1999

  print date$("mm/dd/yy")   ' 11/30/99

  print date$("yyyy/mm/dd") ' 1999/11/30    for sorting

  print date$("days")       ' 36127         days since Jan 1, 1900

Or you can assign a variable the result:

  d$ = date$( )

NOTE:  All the above forms return a string except for date$("days")


DefaultDir$

Description:

A string variable that contains the default directory for the running Liberty BASIC program.  The format is "drive:\dir1", or "drive:\dir1\dir2" etc.

Usage:

    print DefaultDir$

Or you might use it with a FILES statement:

    files DefaultDir$, "*.txt", info$(


DIM array( )

DIM array(size)       -or-      DIM array(size, size)

Description:

DIM sets the maximum size of an array.  Any array can be dimensioned to have as many elements as memory allows.  If an array is not DIMensioned explicitly, then the array will be limited to 10 elements, 0 to 9.  Non DIMensioned double subscript arrays will be limited to 100 elements 0 to 9 by 0 to 9.

Usage:

  print "Please enter 10 names."

  for index = 0 to 9

    input names$ : name$(index) = name$

  next index

The FOR . . . NEXT loop in this example is limited to a maximum value of 9 because the array names$( ) is not dimensioned, and therefore is limited to 10 elements.  To remedy this problem, we can add a DIM statement, like so:

  dim names$(20)

  print "Please enter 20 names."

  for index = 0 to 19

    input names$ : names$(index) = name$

  next index

Double subscripted arrays can store information more flexibly, like so:

  dim customerInfo$(10, 5)

  print "Please enter information for 10 customers."

  for index = 0 to 9

    input "Customer name >"; info$ : customerInfo$(index, 0) = info$

    input "Address >"; info$ : customerInfo$(index, 1) = info$

    input "City >"; info$ : customerInfo$(index, 2) = info$

    input "State >"; info$ : customerInfo$(index, 3) = info$

    input "Zip >"; info$ : customerInfo$(index, 4) = info$

  next index


Drive$

Description:

Drives$ is a system variable.  You can operate on it like any other variable.  Use it in expressions, print it, perform functions on it, etc.  It's special in that it contains the drive letters for all the drives installed on in the computer in use.

For example:

    print Drives$

  Would in many cases produce:

    a: b: c:

Or you could use it to provide a way to select a drive like this:

    'a simple example illustrating the use of the Drives$ variable

    dim letters$(25)

    index = 0

    while word$(Drives$, index + 1) <> ""

        letters$(index) = word$(Drives$, index + 1)

        index = index + 1

    wend

    statictext #select, "Double-click to pick a drive:", 10, 10, 200, 20

    listbox #select.list, letters$(, [selectionMade], 10, 35, 100, 150

    open "Scan drive" for dialog as #select

    input r$

[selectionMade]

    close #select

    end


DUMP

Description:

Forces anything that has been LPRINTed to be sent to the Print Manager.

Usage:

  'sample program using LPRINT and DUMP

  open "c:\autoexec.bat" for input as #source

  while eof( #source ) = 0

    line input #source, text$        'print each line

    lprint text$

  wend

  close #source

  dump         'force the print job

  end

Note: see also LPRINT


EOF( #h )

Description:

Used to determine when reading from a sequential file whether the end of the file has been reached.  If so, -1 is returned, otherwise 0 is returned.

Usage:

  open "testfile" for input as #1

  if eof(#1) < 0 then [skipIt]

[loop]

  input #1, text$

  print text$

  if eof(#1) = 0 then [loop]

[skipIt]

  close #1


END

Description:

Used to immediately terminate execution of a program.  If any files or devices are still open (see CLOSE) when execution is terminated, then Liberty BASIC will close them for you and present you with a dialog expressing this fact.  It is good programming practice to close files and devices before terminating execution.

Note:  The STOP statement is functionally identical to END and is interchangable.  Also, make sure that when your program is finished running that it terminates properly with an END statement.  Otherwise your program's windows may all be closed, giving the illusion that it has stopped running, but it will still be resident in memory and may still consume processor resources.

Usage:

  .

  .

  print "Preliminary Tests Complete."

[askAgain]

  input "Would you like to continue (Y/N) ?"; yesOrNo$

  yesOrNo$ = left$(yesOrNo$, 1)

  if yesOrNo$ = "y" or yesOrNo$ = "Y" then [continueA]

  ifYesOrNo$ = 'n" or yesOrNo$ = "N" then end

  print "Please answer Y or N."

  goto [askAgain]

[continueA]

...some more code here...

end  'more than one end is allowed (see above)


EXP( n )

Description:

  This function returns e ^ n,   e being 2.7182818 . . .

Usage:

  print exp( 5 )              produces:  148.41315


FIELD #h, list...

FIELD #handle, # as varName, # as varName, . . .

Description:

FIELD is used with an OPEN "filename.ext" for random as #handle statement to specify the fields of data in each record of the opened file.  For example in this program FIELD sets up 6 fields of data, each with an appropriate length, and associates each with a string variable that holds the data to be stored in that field:

  open "custdata.001" for random as #cust len = 70   ' open as random access

  field #cust, 20 as name$, 20 as street$, 15 as city$, 2 as state$, 10 as zip$, 3 as age

[inputLoop]

  input "Name >"; name$

  input "Street >"; street$

  input "City >"; city$

  input "State >"; state$

  input "Zip Code >"; zip$

  input "Age >"; age

  confirm "Is this entry correct?"; yesNo$   ' ask if the data is entered correctly

  if  yesNo$ = "no" then [inputLoop]

  recNumber = recNumber + 1   ' add 1 to the record # and put the record

  put #cust, recNumber

  confirm "Enter more records?"; yesNo$   ' ask whether to enter more records

  if yesNo$ = "yes" then [inputLoop]

  close #cust   ' end of program, close file

  end

Notice that Liberty BASIC permits the use of numeric variables in FIELD (eg. age), and it allows you to PUT and GET with both string and numeric variables, automatically, without needing LSET, RSET, MKI$, MKS$, MKD$, CVI, CVS, & CVD that are required with Microsoft BASICs.

Note: See also PUT and GET


FILEDIALOG

FILEDIALOG titleString, templateString, receiverVar$

Description:

This command opens a file dialog box.  The titleString is used to label the dialog box.  The templateString is used as a filter to list only files matching a wildcard, or to place a full suggested filename.

The box lets you navigate around the directory structure, looking at files that have a specific extension.  You can then select one, and the resulting full path specification will be placed into receiverVar$, above.

The following example would produce a dialog box asking the user to select a text file to open:

    filedialog "Open text file", "*.txt", fileName$

If then summary.txt were selected, and OK clicked, then program execution would resume after placing the string "c:\liberty\summary.txt" into fileName$.

If on the other hand Cancel were clicked, then an empty string would be placed into fileName$.  Program execution would then resume.

Look at the program grapher1.bas for a practical application of this command.


FILES

Description:

  The FILES statement collects file and directory information from any disk and or directory and fills a double-dimensioned array with the information.  Also good for determining if a specific file exists (see below).

Usage:

    'you must predimension info$(, even though FILES will

    'redimension it to fit the information it provides.

    dim info$(10, 10)

    files "c:\", info$(

The above FILES statement will fill info$( ) in this fashion:

    info$(0, 0) - a string specifying the qty of files found

    info$(0, 1) - a string specifying the qty of subdirectories found

    info$(0, 2) - the drive spec

    info$(0, 3) -  the directory path

Starting at info$(1, x) you will have file information like so:

    info$(1, 0) - the file name

    info$(1, 1) - the file size

    info$(1, 2) - the file date/time stamp

Knowing from info$(0, 0) how many files we have (call it n), we know that our subdirectory information starts at n + 1, so:

    info$(n + 1, 0) - the complete path of a directory entry (ie. \work\math)

    info$(n + 1, 1) - the name of the directory in specified (ie. math)

You can optionally specify a wildcard.  This lets you get a list of all *.ini files, for example.  This is how you do it:

    files DefaultDir$, "*.ini", info$(

This also makes it practical to use to check for file existance.  If you want to know if a file c:\config.bak exists, you could try...

    files "c:\", "config.bak", info$(

    If val(info$(0, 0)) > 0, then the file exists.

See the dir.bas example included.


FOR...NEXT

FOR...NEXT

Description:

The FOR . . . NEXT looping construct provides a way to execute code a specific amount of times.  A starting and ending value are specified like so:

    for var = 1 to 10

      {BASIC code}

    next var

In this case, the {BASIC code} is executed 10 times, with var being 1 the first time, 2 the second, and on through 10 the tenth time.  Optionally (and usually) var is used in some calculation(s) in the {BASIC code}. For example if the {BASIC code} is  print var ^ 2, then a list of squares for var will be displayed upon execution.

The specified range could just as easily be 2 TO 20, instead of 1 TO 10, but since the loop always counts +1 at a time, the first number must be less than the second.  The way around this limitation is to place STEP n at the end of for FOR statement like so:

    for index = 20 to 2 step -1

      {BASIC code}

    next index

This would loop 19 times returning values for index that start with 20 and end with 2.  STEP can be used with both positive and and negative numbers and it is not limited to integer values.  For example:

    for x = 0 to 1 step .01

      print "The sine of "; x; " is "; sin(x)

    next x

NOTE:  It is not recommended to pass control of a program out of a   FOR  . . . NEXT loop using GOTO (GOSUB is acceptable).  Liberty BASIC may behave unpredictably.  For example:

  for index = 1 to 10

    print "Enter Customer # "; index

    input customer$

    if customer$ = "" then [quitEntry]   ' <- don't cut out of a for ... next loop like this

    cust$(index) = customer$

  next index

  [quitEntry]

 . . . is not allowed!  Rather use while ... wend:

  index = 1

  while customer$ <> "" and index <= 10

    print "Enter Customer # "; index

    input customer$

    cust$(index) = customer$

    index = index + 1

  wend


GET #h, n

GET #handle, recordNumber

Description:

GET is used after a random access file is opened to get a record of information (see FIELD) out of the file from a specified position.

Usage:

  open "custdata.001" for random as #cust len = 70   ' open random access file

  field #cust, 20 as name$, 20 as street$, 15 as city$, 2 as state$, 10 as zip$, 3 as age

  ' get the data from record 1

  get #cust, 1

  print name$

  print street$

  print city$

  print state$

  print zip$

  print age

  close #cust

  end

Note:  See also PUT, FIELD


GETTRIM #h, n

GETTRIM #handle, recordNumber

Description:

The GETTRIM command is exactly like the GET command, but when data is retrieved, all leading and trailing blank space is removed from all data fields before being committed to variables.

Note: see also GET


GOSUB label

Description:

GOSUB causes execution to proceed to the program code following the label if it exists,  using the form 'GOSUB label'.  The label can be either a traditional line number or a branch label in the     format [???????] where the ?'s can be any upper/lowercase letter combination.  Spaces and numbers are not allowed.

Here are some valid branch labels:  [mainMenu]  [enterLimits]  [repeatHere]

Here are some invalid branch labels:  [enter limits]  mainMenu  [1moreTime]

After execution is transferred to the point of the branch label, then each statement will be executed in normal fashion until a RETURN is encountered. When this happens, execution is transferred back to the statement immediately after the GOSUB.  The section of code between a GOSUB and its RETURN is known as a 'subroutine.'  One purpose of a subroutine is to save memory by having only one copy of code that is used many times throughout a program.

Usage:

  .

  .

  print "Do you want to continue?"

  gosub [yesOrNo]

  if answer$ = "N" then [quit]

  print "Would you like to repeat the last sequence?"

  gosub [yesOrNo]

  if answer$ = "Y" then [repeat]

  goto [generateNew]

[yesOrNo]

  input answer$

  answer$ = left$(answer$, 1)

  if answer$ = "y" then answer$ = "Y"

  if answer$ = "n" then answer$ = "N"

  if answer$ = "Y" or answer$ = "N" then return

  print "Please answer Y or N."

  goto [yesOrNo]

  .

  .

You can see how using GOSUB [yesOrNo] in this case saves many lines of code in this example.  The subroutine [yesOrNo] could easily be used many other times in such a hypothetical program, saving memory and reducing typing time and effort.  This reduces errors and increases productivity.

Note: see also GOTO


GOTO label

Description:

GOTO causes Liberty BASIC to proceed to the program code following the label if one exists,  using the form 'GOTO label'.  The label can be either a traditional line number or a branch label in the format [???????] where the ?'s can be any upper/lowercase letter combination.  Spaces and digits are not allowed.

Here are some valid branch labels:  [mainMenu]  [enterLimits]  [repeatHere]

Here are some invalid branch labels:  [enter limits]  mainMenu  [1moreTime]

Usage:

  .

  .

[repeat]

  .

  .

[askAgain]

  print "Make your selection (m, r, x)."

  input selection$

  if selection$ = "M" then goto [menu]

  if selection$ = "R" then goto [repeat]

  if selection$ = "X" then goto [exit]

  goto [askAgain]

  .

  .

[menu]

  print "Here is the main menu."

  .

  .

[exit]

  print "Okay, bye."

  end

Notes:

  In the lines containing IF . . . THEN GOTO, the GOTO is optional.

  The expression IF . . . THEN [menu]  is just as valid as

  IF . . . THEN GOTO [menu].  But in the line GOTO [askAgain], the GOTO

  is required.

  See also GOSUB


HWND( #handle)

Description:

Returns the value of the Windows handle for the window referred to by the Liberty BASIC #handle.  This is very useful for making many different kinds of Windows API calls, and many third-party DLL will require that this value be provided for their own purposes.

Usage:

    open "Example" for window as #1

    h1 = hwnd(#1)


IF...THEN

IF test expression THEN expression(s)

IF test expression THEN expression(s)1 ELSE expression(s)2

IF test expression THEN expression(s)1 END IF

IF test expression THEN expression(s)1 ELSE expression(s)2 END IF

Description:

The IF...THEN statement provides a way to change program flow based on a test expression.  For example, the following line would direct program execution to branch label [soundAlarm] if fuel runs low.

if fuel < 5 then [soundAlarm]

Another way to control program flow is to use the IF...THEN...ELSE statement.  This extended form of IF...THEN adds expressiveness and simplifies coding of some logical decision-making software.  Here is an example of its usefulness.

Consider:

[retry]

  input"Please choose mode, (N)ovice or e(X)pert?"; mode$

  if len(mode$) = 0 then print "Invalid entry! Retry" : goto [retry]

  mode$ = left$(mode$, 1)

  if instr("NnXx", mode$) = 0 then print "Invalid entry! Retry" : goto [retry]

  if instr("Nn", mode$) > 0 then print "Novice mode" : goto [main]

  print "eXpert mode"

[main]

  print "Main Selection Menu"

Look at the two lines before the [main] branch label.  The first of these two lines is required to branch over the next line.  These lines can be shortened to one line as follows:

  if instr("Nn",mode$)> 0 then print "Novice mode" else print "eXpert mode"

Some permitted forms are as follows:

  if a < b then statement else statement

  if a < b then [label] else statement

  if a < b then statement else [label]

  if a < b then statement : statement else statement

  if a < b then statement else statement : statement

  if a < b then statement : goto [label] else statement

  if a < b then gosub [label1] else gosub [label2]

Any number of variations on these formats are permissible.  The a < b boolean expression is of course only a simple example chosen for convenience.

You must replace it with the correct expression to suit your problem.

IF...THEN...END IF is another form using what are called conditional blocks.  This allows great control over the flow of program decision making.  Here is an example of code using blocks.

    if qtySubdirs = 0 then

        print "None."

        goto [noSubs]

    end if

A block is merely one or more lines of code that are executed as a result of a conditional test.  There is one block in the example above, and it is executed  if qtySubdirs = 0.

We can use the else keyword as well with blocks, like so:

    if qtySubdirs = 0 then

        print "None."

      else

        print "Count of subdirectories: "; qtySubdirs

    end if

You can see how neat and clean this is.  There are two blocks in this example.  One is executed  if qtySubdirs = 0, and one is executed if qtySubdirs is not equal to 0.  Only one of the two blocks will be executed (never both as a result of the same test).

You can even nest these conditional blocks inside of each other, like so:

    if verbose = 1 then

        if qtySubdirs = 0 then

            print "None."

          else

            print "Count of subdirectories: "; qtySubdirs

        end if

    end if

So, in the example above, if the verbose flag is set to 1 (true), then display something, or else skip the display code entirely.


INPUT

 INPUT  #handle  "string expression";  variableName

Description:

This command has several possible forms:

  input var

- stop and wait for user to enter data in the program's

main window and press the 'Return' key, then assign

the data entered to var.

  input "enter data"; var

- display the string "enter data" and then stop

and wait for user to enter data in the program's main window

and press 'Return', then assign the data entered to var.

  input #name, var

- Get the next data item from the open file or device using handle

named #handle and assign the data to var.  If no device or file exists

that uses the handle named #handle, then return an error.

  input #name, var1, var2

- The next two data items are fetched and assigned to var1 and var2.

  line input #name, var$

 - The line input statement will read from the file, ignoring commas in the

input stream and completing the data item only at the next carraige

return or at the end of file.  This is useful for reading text with embedded

commas

Usage:

  'Display a text file

  input "Please type a filename >";  filename$

  open filename$ for input as #text

[loop]

  if eof(#text) <> 0 then [quit]

  input #text, item$

  print item$

  goto [loop]

[quit]

  close #text

  print "Done."

  end

Note:  In Liberty BASIC, INPUT cannot be used to input data directly into arrays, only into the simpler variables.

  input a$(1)                   - is illegal

  input string$ : a$(1) = string$       - use this instead

Most versions of Microsoft BASIC implement INPUT to automatically place a question mark on the display in front of the cursor when the user is prompted for information like so:

  input "Please enter the upper limit"; limit

  produces:

    Please enter the upper limit ? |

Liberty BASIC permits you the luxury of deciding for yourself whether the question mark appears at all.

  input "Please enter the upper limit :"; limit

  produces:

    Please enter the upper limit: |

  and:    input limit    produces simply:

    ? |

In the simple form input limit, the question mark is inserted automatically, but if you do specify a prompt, as in the above example, only the contents of the prompt are displayed, and nothing more.  If for some reason you wish to input without a prompt and without a question mark, then the following will achieve the desired effect:

  input ""; limit

Additionally, in most Microsoft BASICs, if INPUT expects a numeric value and a non numeric or string value is entered, the user will be faced with a comment something like 'Redo From Start', and be expected to reenter.  Liberty BASIC does not automatically do this, but converts the entry to a zero value and sets the variable accordingly.  This is not considered a problem but rather a language feature, allowing you to decide for yourself how your program will respond to the situation.

One last note:  In Liberty BASIC input prompt$; limit is also valid. Try:

  prompt$ = "Please enter the upper limit:"

  input prompt$; limit


INPUT$( #h, n )

INPUT$(#handle, items)

Description:

Permits the retrieval of a specified number of items from an open file or device using #handle.  If #handle does not refer to an open file or device then an error will be reported.  Also can be used to read a character at a time from the mainwindow (see example below).

Usage:

  'read and display a file one character at a time

  open "c:\autoexec.bat" for input as #1

[loop]

    if eof(#1) <> 0 then [quit]

    print input$(#1, 1);

    goto [loop]

[quit]

    close #1

    end

For most devices (unlike disk files), one item does not refer a single character, but INPUT$( ) may return items more than one character in length.  In most cases, use of INPUT #handle, varName works just as well or better for reading devices.

Here is another example which shows reading keypresses in the mainwindow.

'accept characters and display them until Enter is pressed

text$ = ""

while c$ <> chr$(13)

  c$ = input$(1)

  print c$;

  if c$ <> chr$(13) then text$ = text$ + c$

wend

print "You typed:"; text$

end


INSTR(a$,b$,n)

INSTR(string1, string2, starting)

Description:

This function returns the position of string2 within string1.  If string2 occurs more than once in string 1, then only the position of the leftmost occurance will be returned.  If starting is included, then the search for string2 will begin at the position specified by starting.

Usage:

  print instr("hello there", "lo")

  produces:    4

  print instr("greetings and meetings", "eetin")

  produces:    3

  print instr("greetings and meetings", "eetin", 5)

  produces:    16

If string2 is not found in string1, or if string2 is not found after starting, then INSTR( ) will return 0.

  print instr("hello", "el", 3)

  produces:    0

  and so does:

  print instr("hello", "bye")


INT( n )

Description:

This function removes the fractional part of number, leaving only the whole number part behind.

Usage:

[retry]

  input "Enter an integer number>"; i

  if i<>int(i) then bell: print i; " isn't an integer! Re-enter.": goto [retry]


KILL s$

KILL "filename.ext"

Description:

This command deletes the file specified by filename.ext.  The filename can include a complete path specification.


LEFT$( s$, n )

LEFT$(string, number)

Description:

This function returns from string the specified number of characters starting from the left.  So if  string is "hello there", and number is 5, then "hello" would be the result.

Usage:

[retry]

  input "Please enter a sentence>"; sentence$

  if sentence$ = "" then [retry]

  for i = 1 to len(sentence$)

    print left$(sentence$, i)

  next i

Produces:

  Please enter a sentence>That's all folks!

  T

  Th

  Tha

  That

  That'

  That's

  That's_

  That's a

  That's al

  That's all

  That's all_

  That's all f

  That's all fo

  That's all fol

  That's all folk

  That's all folks

  That's all folks!

Note:  If number is zero or less, then "" (an empty string) will be returned.  If the number is greater than or equal to the number of characters in string, then string will be returned.

  See also MID$( ) and RIGHT$( )


LEN( s$ )

LEN( string )

Description:

This function returns the length in characters of string, which can be any valid string expression.

Usage:

  prompt "What is your name?"; yourName$

  print "Your name is "; len(yourName$); " letters long"


LET var = expr

 Description:

LET is an optional prefix for any BASIC assignment expression.  Most do leave the word out of their programs, but some prefer to use it.

Usage:

  Either is acceptable:

  let name$ = "John"

or

  name$ = "John"

  Or yet again:

  let c = sqr(a^2 + b^2)

or

  c = sqr(a^2 + b^2)


LINE INPUT

See INPUT


LOADBMP

LOADBMP "name", "filename.bmp"

Description:

This command loads standard Windows *.BMP bitmap file into Liberty BASIC (see also SAVEBMP).  The "name" is a string you would choose to describe the bitmap you're loading, and the "filename.bmp" is the actual name of the bitmap file.  Once loaded, the bitmap can then be displayed in a graphics window type using the drawbmp command (see help file GUI Programming/Window Types/View Graphics Window Commands).

Usage:

  See the sample program ttt.bas for an example using LOADBMP.


LOF( #h )

LOF(#handle)

Description:

  Returns the # of bytes contained in the file referenced by #handle.

Usage:

    open "\autoexec.bat" for input as #1

    qtyBytes = lof(#1)

    for x = 1 to qtyBytes

        print input$(#1, 1) ;

    next x

    close #1

    end


LOG( n )

Description:

  This function returns the natural log of  n.

Usage:

  print log( 7 )              produces:  1.9459101


LOWER$( s$ )

Description:

  This function returns a copy of the contents of a$, but with all letters converted to  lowercase.

Usage:

  print lower$( "The Taj Mahal" )

Produces:

  the taj mahal


LPRINT

LPRINT expr

Description:

This statement is used to send data to the default printer (as determined by the Windows Print Manager).  A series of expressions can follow LPRINT (there does not  need to be any expression at all), each seperated by a semicolon.  Each expression is sent in sequence.  When you are finished sending data to the printer, you should commit the print job by using the DUMP statement.  Liberty BASIC will eventually send your print job, but DUMP forces the job to finish.

Usage:

  lprint "hello world"        'This prints hello world

  dump

  lprint "hello ";               'This also prints hello world

  lprint "world"

  dump

  age = 23

  lprint "Ed is "; age; " years old"     'This prints Ed is 23 years old

  dump

Note: see also PRINT, DUMP


MENU

MENU #handle, "title", "text", [branchLabel], "text2", [branchLabel2],  |  , . . .

Description:

Adds a pull down menu to the window at #handle.  The item "title" specifies the title of the menu, as seen on the menu bar of the window, and each "text", [branchLabel] pair after the title adds a menu item to the menu, and tells Liberty BASIC where to branch to when the menu item is chosen.  The  | character can optionally be placed between menu items, to cause a separating line to be added between the items with the menu is pulled down.

As an example, if you wanted to have a graphics window opened, and then be able to pull down some menus to control color and geometric objects, our opening code might look like this:

  menu #geo, "&Colors", "&Red", [setRed], "&Green", [setGreen], "&Blue", [setBlue]

  menu #geo, "&Shapes", "&Rectangle", [asRect], "&Triangle", [asCircle], "&Line", [asLine]

  open "Geometric wite-board" for graphics_nsb as #geo

  wait  ' stop and wait for a menu item to be chosen

Notice that the MENU lines must go before the OPEN statement, and must use the same handle as the window that it will be associated with (#geo in this case).

Also notice that the & character placed in the title and text items for the menu determines the accelerator placement for each menu.

See also POPUPMENU


MID$( )

MID$(string, index, number)

Description:

Permits the extraction of a sequence of characters from string starting at index.  If number is not specified, then all the characters from index to the end of the string are returned.  If number is specified, then only as many characters as number specifies will be returned, starting from index.

Usage:

  print mid$("greeting Earth creature", 10, 5)

Produces:

  Earth

And:

  string = "The quick brown fox jumped over the lazy dog"

  for i = 1 to len(string$) step 5

    print mid$(string$, i, 5)

  next i

Produces:

  The_q

  uick_

  brown

  _fox_

  jumpe

  d_ove

  r_the

  _lazy

  _dog

Note:

  See also LEFT$( ) and RIGHT$( )


MKDIR( )

Description:

The MKDIR( ) function attempts to create the directory specified.  If the directory creation is successful the returned value will be 0.  If the directory creation was unsuccessful, a value indicating a DOS error will be returned.

Usage:

    'create a subdirectory named temp in the current directory

    result = mkdir( "temp")

    if result <> 0 then notice "Temporary directory not created!"

Note: See also RMDIR( )


NAME a$ AS b$

NAME stringExpr1 AS stringExpr2

Description:

This command renames the file specified in the string expression stringExpr1 to stringExpr2.  StringExpr1 can represent any valid filename that is not a read-only file, and stringExpr2 can be any valid filename as long as it doesn't specify a file that already exists.

Usage:

  'rename the old file as a backup

  name rootFileName$ + ".fre" as rootFileName$ + ".bak"

  'open a new file and write data

  open rootFileName$ + ".fre" for output as #disk


NOMAINWIN

Description:

This command instructs Liberty BASIC not to open a main window for the program that includes this statement.  Some simple programs which do not use seperate windows for graphics, spreadsheet, or text may use only the main window.  Other programs may not need the main window to do their thing, and so simply including NOMAINWIN  somewhere in your program source will prevent the window from opening.

If NOMAINWIN is used, when all other windows owned by that program are closed, then the program terminates execution automatically.

It is often better to place a NOMAINWIN statement in your program after it is completed and debugged, so that you can easily terminate an errant program just by closing its main window.

For examples of the usage of NOMAINWIN, examine the included Liberty BASIC programs (buttons1.bas for example).


NOTICE

Description:

This command pops up a dialog box which displays "string expression" and which has a button OK which the user presses after the message is read. Pressing Enter also closes the dialog box.

Two forms are allowed.  If "string expression" has no Cr character (ASCII 13), then the title of the dialog box will be 'Notice' and "string expression" will be the message displayed inside the dialog box.  If "string expression" does have a Cr character, then the part of "string expression" before Cr will be used as the title for the dialog box, and the part of "string expression" after Cr will be displayed as the message inside.

Usage:

    notice "Super Stats is Copyright 1992, Mathware"

Or:

    notice "Fatal Error!" + chr$(13) + "The entry buffer is full!"


OPEN

OPEN string FOR purpose AS #handle {LEN = #}

Description:

This statement has many functions.  It can be used to open disk files, DLLs, or to open windows of several kinds.

Using OPEN with Disk files:

A typical OPEN used in disk I/O looks like this:

  OPEN "\autoexec.bat" for input as #read

This example illustrates how we would open the autoexec.bat file for reading.  As you can see, string in this case is "\autoexec.bat", purpose is input, and #handle is read.

  string 	- this must be a valid pathname.  If the file does not exist, it will

   be created.

  purpose 	- must be input, output, or random

  #handle 	- use a unique descriptive word, but must start with a #.

  This special handle is used to identify the open file in later

  program statements

  LEN = # 	- this is an optional addition for use only when opening a random

  access file.  The # determines how many characters long each

  record in the file is.  If this is not specified, the default length is

  128 characters.  See FIELD, GET, and PUT.

Using OPEN with windows:

A typical OPEN used in windows looks like this:

  OPEN "Customer Statistics Chart" for graphics as #csc

This example illustrates how we would open a window for graphics.  Once the window is open, there are a wide range of commands that can be given to it.   As you can see, string in this case is "Customer Statistics Chart", which is used as the title of the window, purpose is graphics (open a window for graphics), and the #handle is #csc (derived from Customer Statistics Chart), which will be used as an identifier when sending commands to the window.

  string  	 - can be any valid BASIC string.  used to label the window

  purpose 	- there are a several possibilities here: graphics, text, window, or dialog

  #handle 	- as above, must be a unique, descriptive word starting with #

Using OPEN with DLLs:

To call functions that reside in a DLL, you must open the DLL first.  Additionally, if you want to make a Windows API function call, you must first open the DLL it is contained in.  See CALLDLL.

Note:  Any opened file or window must be closed before program execution is

finished.  See CLOSE


Platform$

Description:

This variable holds the string "Windows".  When programming with Liberty BASIC for OS/2, the same variable holds "OS/2".

This is useful so that you can take advantage of whatever differences there are between the two platforms and between the versions of Liberty BASIC.

Note: see also Version$


PLAYWAVE

PLAYWAVE "filename" [, mode ]

Description:

  Plays a *.wav sound file as specified in filename.  If mode is specified, it must be one of the modes specifed below:

sync	 (or synch)	- wait for the wave file to finish playing (the default)

async (or asynch) 	- don't wait for the wave file to finish playing

loop	- play the wave file over and over (cancel with: playwave "")


PRINT

PRINT #handle, pression ; expression(s) ;

Description:

This statement is used to send data to the main window, to a disk file, or to other windows.  A series of expressions can follow PRINT (there does not need to be any expression at all), each seperated by a semicolon.  Each expression is displayed in sequence.  If the data is being sent to a disk file, or to a window, then #handle must be present.

PRINTing to a the main window:

When the expressions are displayed, then the cursor (that blinking vertical bar | ) will move down to the next line, and the next time information is sent to the window, it will be placed on the next line down.  If you do not want the cursor to move immediately to the next line, then add an additional semicolor to the end of the list of expressions.  This prevents the cursor from being moved down a line when the expressions are displayed.  The next time data is displayed, it will be added onto the end of the line of data displayed previously.

Usage:                  Produces:

  print "hello world"           hello world

  print "hello ";               hello world

  print "world"

  age = 23

  print "Ed is "; age; " years old"     Ed is 23 years old

When sending to a disk file and in regard to the use of the semicolon at the end of the expression list, the rules are similar (only you don't see it happen on the screen).  When printing to a window, the expressions sent are usually commands to the window (or requests for information from the window).  For more information, see help file GUI Programming.


PROMPT

PROMPT string; responseVar

Description:

The PROMPT statement opens a dialog box, displays string, and waits for the user to type a response and press 'Return' (or press the OK or Cancel button).  The entered information is placed in responseVar.  If Cancel is pressed, then a string of zero length is returned.  If responseVar is set to some string value before PROMPT is executed, then that value will become the 'default' or suggested response.  This means that when the dialog is opened, the contents of responseVar will already be entered as a response for the user, who then has the option to either type over that 'default' response, or to press 'Return' and accept it.

Usage:

  .

  .

  response$ = "C:"

  prompt "Search on which Drive? A:, B:, or C:"; response$

[testResponse]

  if response$ = "" then [cancelSearch]

  if len(response$) = 2 and instr("A:B:C:", response$) > 0 then [search]

  prompt "Unacceptable response.  Please try again. A:, B:, or C:"; again$

  goto [testResponse]

[search]

  print "Starting search . . . "

  .

  .


PUT #h, n

PUT #handle, n

Description:

PUT is used after a random access file is opened to place a record of information (see FIELD) into the file #handle at record n.  For example:

  open "custdata.001" for random as #cust len = 70   ' open a random access file

  field #cust, 20 as name$, 20 as street$, 15 as city$, 2 as state$, 10 as zip$, 3 as age

  ' enter data into customer variables

  input name$

  .

  .

  ' put the data into record 1

  put #cust, 1

  close #cust

  end

Note:  See also GET, FIELD


RADIOBUTTON

Adds a radiobutton control to the window referenced by #handle.  Radiobuttons have two states, set and reset.  They are useful for getting input of on/off  type information.

The syntax of this command is:

  RADIOBUTTON #handle.ext, "label", [set], [reset], x, y, wide, high

All radiobuttons on a given window are linked together, so that if you set one by clicking on it, all the others will be reset.

Here is a description of the parameters of the RADIOBUTTON statement:

    #handle.ext - Specify handle for this control.  The #handle part should be the same

as the handle of the window you're adding the radiobutton to, and the

ext part names the radiobutton uniquely in the window.

    "label"	- This contains the visible text of the radiobutton

    [set]	- This is the branch label to goto when the user sets the radiobutton

by clicking on it.

    [reset]	- This is the branch label to goto when the user resets the

radiobutton by clicking on it. (this doesn't actually do anything

because radiobuttons can't be reset by clicking on them).

    xOrigin	- This is the x position of the radiobutton relative to the upper left

corner of the window it belongs to.

    yOrigin	- This is the y position of the radiobutton relative to the upper left

corner of the window it belongs to.

    width	- This is the width of the radiobutton control

    height	- This is the height of the radiobutton control

Radiobuttons understand these commands:

    print #handle.ext, "set"

      This sets the checkbox.

    print #handle.ext, "reset"

      This resets the checkbox.

    print #handle.ext, "value? result$"

      The result$ variable will be set to the status of the checkbox (either "set" or "reset").

    print #handle.ext, "setfocus"

      This will cause the combobox to receive the input focus.  This means

      that any keypresses will be directed to the combobox.

    print #handle,ext, "locate x y width height"

      Reposition the burron in its window.  This is effective when the button

      is placed inside window of type window or dialog.  The button will not

      update its size and location until a refresh command is sent to the

      window.  See the included RESIZER.BAS example program.

    print #handle, "font facename pointSize"

      Set the pen's font to the specified face and point size.  If an

      exact match cannot be found, then Liberty BASIC will try to find a

      close match, with size being of more prominance than face.

      For more on specifying fonts read How to Specify Fonts

      Example:

        print #handle.ext, "font times_new_roman 10"

Usage:

  See the included program radiobtn.bas for an example of how to use radiobuttons.

Note: see also CHECKBOX


REDIM

Description:

Redimensions an already dimensioned array and clears all elements to zero (or to an empty string in the case of string arrays).  This can be very useful for writing applications that have data sets of unknown size.  If you dimension arrays that are extra large to make sure you can hold data, but then only have a small set of data, then all the space you reserved is wasted.  This hurts performance.

Usage:

    dim cust$(10)  'dimension the array

    .

    .

    .

    'now we know there are 510 customers on file

    redim cust$(510)

    'now read in the customer records


REM

REM comment

Description:

The REM statement is used to place comments inside of code to clearly explain the purpose of each section of code.  This is useful to both the programmer who writes the code or to anyone who might later need to modify the program.  Use REM statements liberally.  There is a shorthand way of using REM, which is to use the ' (apostrophe) character in place of the word REM.  This is cleaner to look at, but use whichever you prefer.  Unlike other BASIC statements, with REM you cannot add another statement after it on the same line using a colon ( : ) to seperate the statements.  The rest of the line becomes part of the REM statement.

Usage:

  rem  let's pretend that this is a comment for the next line

  print "The mean average is "; meanAverage

Or:

  ' let's pretend that this is a comment for the next line

  print "The strength of the quake was "; magnitude

This doesn't work:

  rem  thank the user : print "Thank you for using Super Stats!"

    (even the print statement becomes part of the REM statement)

Note:

When using ' instead of REM at the end of a line, the statement seperator :

is not required to seperate the statement on that line from its comment.

For example:

  print "Total dollar value: "; dollarValue : rem  print the dollar value

Can also be stated:

  print "Total dollar value: "; dollarValue  ' print the dollar value

Notice that the : is not required in the second form.


RETURN

RETURN

See  GOSUB


RIGHT$( s$, n )

RIGHT$(string, number)

Description:

Returns a sequence of characters from the right hand side of string using number to determine how many characters to return.  If  number is 0, then "" (an empty string) is returned.  If number is greater than or equal to the number of characters in string, then string will itself be returned.

Usage:

  print right$("I'm right handed", 12)

Produces:

  right handed

And:

  print right$("hello world", 50)

Produces:

  hello world

Note:  See also LEFT$( ) and MID$( )


RND( n )

RND(number)

Description:

This function returns a pseudo random number between 0 and 1.  This can be useful in writing games and some simulations.  The particular formula used in this release might more accurately be called an arbitrary number generator (instead of random number generator), since if a distribution curve of the output of this function were plotted, the results would be quite uneven.  Nevertheless, this function should prove more than adequate (especially for game play).

In MBASIC it makes a difference what the value of parameter number is, but in Liberty BASIC, it makes no difference.  The function will always return an arbitrary number between 0 and 1.

Usage:

  ' print ten numbers between one and ten

  for a = 1 to 10

      print int(rnd(1)*10) + 1

  next a


RUN s$, mode

RUN stringExpr1 [, mode ]

Description:

This command runs external programs.  StringExpr1 should represent the full path and filename of a Windows or DOS executable program, a Liberty BASIC *.TKN file, or a *.BAT file.  This is not a SHELL command, so you must provide the name of a program or batch file, not a DOS command (like DIR, for example).  Execution of an external program does not cause the calling Liberty BASIC program to cease executing.

Here are two examples:

    RUN "QBASIC.EXE"    ' run Microsoft's QBASIC

    RUN "WINFILE.EXE", SHOWMAXIMIZED  ' run the File Manager maximized

Notice in the second example we can include an additional parameter.  This is because we are running a Windows program.  Here is a list of the valid parameters we can include when running Windows programs:

HIDE

SHOWNORMAL  (this is the default)

SHOWMINIMIZED

SHOWMAXIMIZED

SHOWNOACTIVE

SHOW

MINIMIZE

SHOWMINNOACTIVE

SHOWNA

RESTORE


SCAN

Description:

The SCAN statement causes Liberty BASIC to stop what it is doing for a moment and process Windows keyboard and mouse messages.  This is useful for any kind of routine that needs to run continuously but which still needs to process button clicks and other actions.  In this way, SCAN can be used as an INPUT statement that doesn't stop and wait.

Example:

    'scan example - digital clock

    nomainwin

    WindowWidth = 120

    WindowHeight = 95

    statictext #clock.time, "xx:xx:xx", 15, 10, 90, 20

    button #clock.12hour, "12 Hour", [twelveHour], UL, 15, 40, 40, 20

    button #clock.24hour, "24 Hour", [twentyfourHour], UL, 60, 40, 40, 20

    open "Clock" for window_nf as #clock

    print #clock, "trapclose [quit]"

    print #clock.time, "!font courier_new 8 15"

    print #clock.12hour, "!font ariel 5 11"

    print #clock.24hour, "!font ariel 5 11"

    goto [twelveHour]

[timeLoop]

    if time$ <> time$() then

        time$ = time$()

        gosub [formatTime]

        print #clock.time, formattedTime$

    end if

    scan    'check for user input

    goto [timeLoop]

[formatTime]

    hours = val(left$(time$, 2))

    if twelveHourFormat = 1 then

        if hours > 12 then

            hours = hours - 12

            suffix$ = " PM"

        else

            if hours = 0 then hours = 12

            suffix$ = " AM"

        end if

    else

        suffix$ = ""

    end if

    formattedTime$ = prefix$+right$("0"+str$(hours), 2)+mid$(time$, 3)+suffix$

    return

[twelveHour]  'set up twelve-hour mode

    twelveHourFormat = 1

    time$ = ""

    prefix$ = ""

    goto [timeLoop]

[twentyfourHour]  'set up twentyfour-hour mode

    twelveHourFormat = 0

    time$ = ""

    prefix$ = " "

    goto [timeLoop]

[quit]  'exit our clock

    close #clock

    end


SIN( n )

Description:

  This function return the sine of n.

Usage:

  .

  .

  for t = 1 to 45

    print "The sine of "; t; " is "; sin(t)

  next t

  .

  .

Note:  See also COS( ) and TAN( )


SORT

SORT arrayName(), start, end, [column]

Description:

This command sorts both doubleand single dimensioned arrays.  Arrays can be sorted in part or in whole, and with double dimensioned arrays, the specific column to sort by can be declared.  When this option is used, all the rows are sorted against each other according to the items in the specified column.

Usage:

Here is the syntax for the sort command:

    sort arrayName(), i, j, [,n]

This sorts the array named arrayName( starting with element i, and ending with element j.  If it is a double dimensioned array then the column parameter tells which nth element to use as a sort key.  Each WHOLE row moves with its corresponding key as it moves during the sort.  So let's say you have a double dimensioned array holding sales rep activity:

    repActivity(x, y)

So you're holding data, one record per x position, and your record keys are in y.  So for example:

    repActivity(1,1) = "Tom Maloney" : repActivity(1,2) = "01-09-93"

    repActivity(2,1) = "Mary Burns" : repActivity(2,2) = "01-10-93"

     .

     .

     .

    repActivity(100,1) = "Ed Dole" : repActivity(100,2) = "01-08-93"

So you want to sort the whole 100 items by the date field.  This is how the command would look:

    sort repActivity(), 1, 100, 2

If you wanted to sort by name instead, then change the 2 to a 1, like this:

    sort repActivity(), 1, 100, 1


STR$( n )

Description:

This function returns a string expressing the result of  numericExpression.  In MBASIC, this function would always return a string representation of the expression and it would add a space in front of that string.  For example in MBASIC:

  print len(str$(3.14))

Would produce the number 5 (a space followed by 3.14 for a total of 5 characters).

Liberty BASIC leaves it to you to decide whether you want that space or not.  If you don't want it, then you need not do anything at all, and if you do want it, then this expression will produce the same result under Liberty BASIC:

  print len(" " + str$(3.14))

Usage:

  .

  .

[kids]

  ' use str$( ) to validate entry

  input "How many children do you have?"; qtyKids

  qtyKids$ = str$(qtyKids)

  ' if the entry contains a decimal point, then the response is no good

  if instr(qtyKids$, ".") > 0 then print "Bad response. Reenter." : goto [kids]


TAN( n )

Description:

  This function returns the tangent of n.

Usage:

  .

  .

  for t = 1 to 45

    print "The tangent of "; t; " is "; tan(t)

  next t

  .

  .

Note:  See also SIN( ) and COS( )


TIME$( )

Description:

This function returns a string representing the current time of the system clock in 24 hour format.  This function replaces the time$ variable used in QBasic.  See also DATE$( ).

  'this form of time$()        produces this format

  print time$()               'time now as string "16:21:44"

  print time$("seconds")      'seconds since midnight as number 32314

  print time$("milliseconds") 'milliseconds since midnight as number 33221342

Usage:

  ' display the opening screen

  print "Main selection screen             Time now: "; time$()

  print

  print "1. Add new record"

  print "2. Modify existing record"

  print "3. Delete record"


TRACE n

TRACE number

Description:

This statement sets the trace level for its application program.  This is only effective if the program is run using the Debug menu selection (instead of RUN).  If Run is used, then any TRACE statements are ignored.

There are three trace levels: 0, 1, and 2.  Here are the effects of these levels:

  0 = full speed no trace or RUN

  1 = animated trace or WALK

  2 = single step mode or STEP

When any Liberty BASIC program first starts under Debug mode, the trace level is always initially 2 (STEP).  You can then click on any of the three buttons (STEP, WALK, RUN) to determine what mode to continue in.   When a TRACE statement is encountered, the trace level is set accordingly, but you can recover from this new trace level by clicking again on the desired button.

If you are having trouble debugging code at a certain spot, then you can add a TRACE statement (usually level 2) just before that location, run in Debug mode and then click on RUN.  When the TRACE statement is reached, then the debugger will kick in at that point.

Usage:

  open "wave" for graphics as #graph

  print #graph, "down"

  for index = 1 to 200

      if index = 20 then trace 2  'Here is the trouble spot

    print #graph, "goto "; index ; " "; 100+int(100*sin(index/20))

  next index

  wait


TRIM$( s$ )

TRIM$(stringExpression)

Description:

This function removes any spaces from the start and end of the string in stringExpression.  This can be useful for cleaning up data entry among other things.

Usage:

  sentence$ = "  Greetings  "

  print len(trim$(sentence$))

Produces:  9


UPPER$( s$ )

Description:

  This function returns a copy of the contents of a$, but with all letters converted to uppercase.

Usage:

  print upper$( "The Taj Mahal" )

Produces:

  THE TAJ MAHAL


USING( )

USING(templateString, numericExpression)

Description:

This function formats numericExpression as a string using templateString.  The rules for the format are like those in Microsoft BASIC's PRINT USING statement,  but since using( ) is a function, it can be used as part of a larger BASIC  expression instead of being useful only for output directly.

Unlike PRINT USING, the using( ) function does not round numbers.

Usage:

  ' print a column of ten justified numbers

  for a = 1 to 10

      print using("####.##",  rnd(1)*1000)

  next a


VAL( s$ )

VAL(stringExpression)

Description:

This function returns a numeric value for stringExpression is stringExpression represents a valid numeric value or if it starts out as one.  If not, then zero is returned.  This function lets your program take string input from the user and carefully analyze it before turning it into a numeric value if and when appropriate.

Usage:

  print 2 * val("3.14")         Produces:       6.28

  print val("hello")            Produces:       0

  print val("3 blind mice")     Produces:       3


Version$

Version$

Description:

This variable holds the version of Liberty BASIC, in this case "2.0".

This is useful so that you can take advantage of whatever differences there are between the different  versions of Liberty BASIC.

Note: see also Platform$


WHILE...WEND

WHILE expression

  {some code}

WEND

Description:

These two statements comprise the start and end of a control loop.  Between the WHILE and WEND statements place code (optionally) that will be executed repeatedly while expression evaluates to true.  The code between any WHILE statement and its associated WEND statement will not execute even once if the WHILE expression initially evaluates to false.  Once execution reaches the WEND statement, for as long as the WHILE expression evaluates to true, then execution will jump back to the WHILE statement.  Expression can be a boolean, numeric, or string expression.

Usage:

  ' loop until midnight (go read a good book)

  while time$ <> "00:00:00"

      ' some action performing code might be placed here

  wend

Or:

  ' loop until a valid response is solicited

  while val(age$) = 0

     input "How old are you?"; age$

     if val(age$) = 0 then print "Invalid response.  Try again."

  wend

Note: DO NOT break out of a WHILE...WEND loop using GOTO.  If you do, then your Liberty BASIC program may behave unpredictably.

You may GOSUB out of a WHILE...WEND loop, because when your subroutine finishes, it will RETURN to the loop.  The following example is an illustration of what you SHOULD NOT DO.

  while count < 10

    input "Enter a name (or a blank line to quit) ?"; n$

    if n$ = "" then [exitLoop]

    list$(count) = n$

    count = count + 1

  wend

[exitLoop]

Instead, you might do this:

  while count < 10

    input "Enter a name (or a blank line to quit) ?"; n$

    if n$ = "" then

        count = 10

      else

        list$(count) = n$

        count = count + 1

      end if

  wend


WORD$( s$, n )

WORD$( stringExpression, n )

Description:

This function returns the nth word in stringExpression.  The leading and trailing spaces are stripped from stringExpression and then it is broken down into 'words' at the remaining spaces inside.  If n is less than 1 or greater than the number of words in stringExpression, then "" is returned.

Usage:

  print word$("The quick brown fox jumped over the lazy dog", 5)

Produces:

  jumped

And:

  ' display each word of sentence$ on its own line

  sentence$ = "and many miles to go before I sleep."

  token$ = "?"

  while token$ <> ""

      index = index + 1

      tokens$ = word$(sentence$, index)

      print token$

  wend

Produces:

  and

  many

  miles

  to

  go

  before

  I

  sleep.


RMDIR( )

Description:

The RMDIR( ) function attempts to remove the directory specified.  If the directory removal is successful the returned value will be 0.  If the directory removal was unsuccessful, a value indicating a DOS error will be returned.

Usage:

    'remove a subdirectory named "pigseye" in the current root directory

    result = rmdir( "\pigseye")

    if result <> 0 then notice "Temporary directory not removed!"

Note: See also MKDIR( )


CURSOR

Description:

The CURSOR command was added to make it easy to change mouse pointers one of 5 predefined shapes.

    NORMAL	= the default pointer

    ARROW	= the standard Windows arrow

    CROSSHAIR	= a + shaped pointer

    HOURGLASS	= the Windows hourglass

    TEXT	= the text insertion I-beam

Example:

    cursor hourglass

    for i = 1 to n

        'perform some work

    next i

    cursor normal

    Your program's code is responsible to setting the cursor back to

    the default (normal) when appropriate.  If a runtime error halts

    your program, the cursor will automatically revert to normal.


(View Graphics Window Commands)
Graphics Window Commands

Most of these commands work only with windows of type graphics and with the graphicbox control.

IMPORTANT NOTE: In order to draw, you must make sure that the drawing pen in down, and not up.  See below for more information.

Here is an example using a graphics window:

    open "Drawing" for graphics as #handle

    print #handle, "home"       'center the pen

    print #handle, "down"       'ready to draw

    print #handle, "fill red"   'fill the window with red

    print #handle, "circle 50"  'draw a circle

    print #handle, "flush"      'make the graphics stick

    wait

And here is an example using a graphicbox:

    graphicbox #handle.gbox, 10, 10, 150, 150

    open "Drawing" for window as #handle

    print #handle.gbox, "home"       'center the pen

    print #handle.gbox, "down"       'ready to draw

    print #handle.gbox, "fill red"   'fill the graphics area red

    print #handle.gbox, "circle 50"  'draw a circle

    print #handle.gbox, "flush"      'make the graphics stick

    wait

Because graphics can involve many detailed drawing operations, Liberty

BASIC does not force you to use just one print # statement for each drawing

task.  If you want to perform several operations you can use a single line for

each as such:

    print #handle, "up"

    print #handle, "home"

    print #handle, "down"

    print #handle, "north"

    print #handle, "go 50"

  Or if you prefer:

    print #handle, "up ; home ; down ; north ; go 50"

  will work just as well, and executes slightly faster.

Important: When drawing to a graphics window or graphic box, the operations that are performed are remembered by Liberty BASIC so that lightning fast redraws can be performed.  This remembering consumes memory.  If you write an application which continually draws graphics, you will eventually run out of memory  Because there are operating system resources, this can potentially crash your computer.  To prevent this, your application should only remember those drawing operations which are needed to display the current state of your application.  Pay special attention to the cls, delsegment, discard and flush commands.

Liberty BASIC supports sprites in graphic windows and in graphicbox controls.  To learn more about using sprites, click here Sprites.

Here are the commands (in alphabetical order):

  print #handle, "autoresize"

    This causes the edges of the control to maintain their distance from

    the edges of the overall window.  If the user resizes the window, the

    texteditor control also resizes.

  print #handle, "backcolor COLOR"

    This command sets the color used when drawn figures are filled with a

    color.  The same colors are available as with the color command above.

  print #handle, "backcolor red(0-255)  green(0-255) blue(0-255)"

    The second form of backcolor lets you specify a  pure RGB color.  This

    only works with display modes greater than  256 colors.  To create a

    green blue color for example, mix green and blue like so:

    print #handle, "backcolor 0 127 200"

  print #handle, "box x y"

    Draw a box using the pen position as one corner, and x, y as the

    other corner.

  print #handle, "boxfilled x y"

    Draw a box  using the pen position as one corner, and x, y as the other corner.

    Fill the box with the color specified using the command backcolor (see above).

  print #handle, "circle r"

    Draw a circle with radius r at the current pen position.

  print #handle, "circlefilled r"

    Draw a circle with radius r, and filled with the color specified using

    the command backcolor (see above).

  print #handle, "cls"

    Clear the graphics window to white, erasing all drawn elements and flushed

    segments (and releasing all the memory they consumed).

  print #handle, "color COLOR"

    Set the pen's color to be COLOR

    Here is a list of valid colors (in alphabetical order):

      black, blue, brown, cyan, darkblue, darkcyan, darkgray,

      darkgreen, darkpink, darkred, green, lightgray, palegray,

      pink, red, white, yellow

  print #handle, "color red(0-255)  green(0-255) blue(0-255)"

    The second form of color lets you specify a  pure RGB color.  This

    only works with display modes greater than  256 colors.  To create a

    violet color for example, mix red and blue like so:

    print #handle, "color 127 0 127"

  print #handle, "delsegment n"

    This causes the drawn segment identified as n to be removed from

    the window's list of drawn items.  The memory that was consumed by the

    drawn segment is reclaimed by the operating system.  Then when the

    window is redrawn the deleted segment will not be included in the redraw.

  print #handle, "discard"

    This causes all drawn items since the last flush to be discarded (this also

    reclaims memory consumed by the discarded drawn items).  Discard does

    not force an immediate redraw, so the items that have been discarded will

    still be displayed until a redraw (see above).

  print #handle, "down"

    Just the opposite of up.  This command reactivates the drawing

    process.

  print #handle, "drawbmp bmpname x y"

    This will draw a bitmap named bmpname (loaded beforehand with the LOADBMP

    statement, see command reference) at the location x y.

  print #handle, "ellipse w h"

    Draw an ellipse at the pen position of width w and height h.

  print #handle, "ellipsefilled  w h"

    Draw an ellipse at the pen position of width w and height h.  Fill the ellipse

    with the color specified using the command backcolor (see above).

  print #handle, "fill COLOR"

  or...          print #handle, "color red(0-255)  green(0-255) blue(0-255)"

    Fill the window with COLOR.  For a list of accepted colors see

    the color command below.  The second form lets you specify a

    pure RGB color.  This only works with

  print #handle, "flush"

    This ensures that drawn graphics 'stick'.  Each time you flush after one

    or more drawing operations, you make a new group (called a segment).

    Each segment of drawn items has an ID number.  Use the segment

    command to get the ID number of the current segment.  Each time you

    flush a segment, a new empty segment is created, and the ID number

    increases by one.  See also the commands cls, delsegment, discard,

    redraw, and segment.

  print #handle, "font facename pointSize"

    Set the pen's font to the specified face and point size.  If an

    exact match cannot be found, then Liberty BASIC will try to find a

    close match, with size being of more prominance than face.

    For more on specifying fonts read How to Specify Fonts

    Example:

      print #handle, "font Times_New_Roman 10"

  print #handle, "go D"

    Go foreward D distance from the current position, and going in the

    current direction.

  print #handle, "getbmp bmpName x y width height"

    Make a bitmap copied from the graphics window at x, y and using width and height.

  print #handle, "goto X Y"

    Move the pen to position X Y.  Draw if the pen is down.

  print #handle, "home"

    This command centers the pen in the graphics window.

  print #handle, "line X1 Y1 X2 Y2"

    Draw a line from point X1 Y1 to point X2 Y2.  If the pen is up, then

    no line will be drawn, but the pen will be positioned at X2 Y2.

  print #handle, "locate x y width height"

    Reposition the control in its window.  This is effective when the control

    is placed inside window of type window or dialog.  The control will not

    update its size and location until a refresh command is sent to the

    window.  See the included RESIZER.BAS example program.

  print #handle, "north"

    Set the current direction to 270 (north).  Zero degrees points to the

    right (east), 90 points down (south), and 180 points left (west).

  print #handle, "pie w h angle1 angle2"

    Draw a pie slice inside of an ellipse of width w and height h.  Start the pie

    slice at angle1, and then sweep clockwise angle2 degrees if angle2 is

    positive, or sweep counter-clockwise angle2 degrees if angle2 is negative.

  print #handle, "piefilled w h angle1 angle2"

    Draw a pie slice inside of an ellipse of width w and height h.  Start the slice

    at angle1, and then sweep clockwise angle2 degrees if angle2 is positive,

    or sweep counter-clockwise angle2 degrees if angle2 is negative.  Fill the

    pie slice with the color specified using the command backcolor (see above).

  print #handle, "place X Y"

    Position the pen at X Y.  Do not draw even if the pen is down.

  print #handle, "posxy xVar yVar"

    Return the position of the pen in x, y.  This command will assign the

    pen's position to xVar & yVar

  print #handle, "print"

    Send the plotted image to the Windows Print Manager for output.

  print #handle, "redraw"

or

  print #handle, "redraw "; idNum

    This will cause the window to redraw all flushed drawn segments, or a

    specific drawn segment.  Any deleted segments will not be redrawn

    (see delsegment above).  Any items drawn since the last flush will not be

    redrawn either, and will be lost.

  print #handle, "rule rulename"

or

  print #handle, "rule "; _R2_NOTXORPEN

    This command specifies whether drawing overwrites (rulename OVER) on the

    screen or uses the exclusive-OR technique (rulename XOR).  You can also use

    Windows constants to select a drawing rule (as shown above).  Here are the

    constants that Windows defines:

  _R2_BLACK

  _R2_WHITE

  _R2_NOP

  _R2_NOT

  _R2_COPYPEN           <- the default LB drawing rule

  _R2_NOTCOPYPEN

  _R2_MERGEPENNOT

  _R2_MASKPENNOT

  _R2_MERGENOTPEN

  _R2_MASKNOTPEN

  _R2_MERGEPEN

  _R2_NOTMERGEPEN

  _R2_MASKPEN

  _R2_NOTMASKPEN

  _R2_XORPEN

  _R2_NOTXORPEN         <- the xor LB drawing rule

  print #handle, "segment variableName"

    This causes the window to set variable name to the segment ID of the

    currently open drawing segment.  To get the segment ID of the last segment

    flushed, just subtract one.  Segment ID numbers are useful for manipulating

    different parts of a drawing.  For an example, see delsegment below.

  print #handle, "set x y"

    Draw a point at x, y using the current color and size.

  print #handle, "setfocus"

    This causes Windows to give input focus to this control.  This means

    that if some other control in the same windows was highlighted and

    active, that this control now becomes the highlighted and active

    control, receiving keyboard input.

  print #handle, "size S"

    Set the size of the pen to S.  The default is 1.  This will affect the

    thickness of lines and figures plotted with most of the commands

    listed in this section.

 print #handle, "stringwidth? varToMeasure$ widthInPixels"

    Get the width in pixels of a string, based on the

    current font of the graphicbox or graphic window.

    open "my stringwidth" for graphics as #g

    name$ = "Carl Gundel"

    print #g, "stringwidth? name$ width"

    print width

    print #g, "font courier_new 30"

    print #g, "stringwidth? name$ width"

    print width

    close #g

    end

  print #handle, "\text"

    Display text at the current pen position.  Each additional \ in the

    text will cause a carraige return and line feed.  Take for example,

    print #handle, "\text1\text2" will cause text1 to be printed at the

    pen position, and then text2 will be displayed directly under text1.

also...  print #handle, "|text"

    Works like print #handle, "\text" above, but let's you use the |

    character instead of the \ character, in case you need to print a \.

  print #handle, "trapclose branchLabel"

    This will tell Liberty BASIC to continue execution of the program at

    branchLabel if the user double clicks on the system menu box

    or pulls down the system menu and selects close (this command does

    not work with graphicsbox controls).

  print #handle, "turn A"

    Turn from the current direction using angle A and adding it to the

    current direction.  A can be positive or negative.

  print #handle, "up"

    Lift the pen up.  All go or goto commands will now only move the

    pen to its new position without drawing.  Any other drawing

    commands will simply be ignored until the pen is put back down.

  print #handle, "when event branchLabel"

    This tells the window to process mouse events.  These events occur

    when someone clicks, double-clicks, drags, or just moves the mouse

    inside of the graphics window.  An event can also be the user pressing

    a key while the graphics window or graphicbox has the input focus (see

    the setfocus command, above).  This provides a really simple mechanism

    for controlling flow of a program which uses the graphics window.  For

    an example, see the program draw1.bas.

    Sending print #handle, "when leftButtonDown [startDraw]" to any

    graphics window will tell that window to force a goto [startDraw] when

    the mouse points inside of that window and someone press the left mouse

    button down.

    Whenever a mouse event does occur, Liberty BASIC places the x and y

    position of the mouse in the variables MouseX, and MouseY.  The

    values will represent the number of pixels in x and y the mouse was from

    the upper left corner of the graphic window display pane.

    If the expression print #handle, "when event" is used, then trapping

    for that event is discontinued.  It can however be reinstated at any time.

    Events that can be trapped:

      leftButtonDown	- the left mouse button is now down

      leftButtonUp       	- the left  mouse button has been released

      leftButtonMove	- the mouse moved while the left button is down

      leftButtonDouble	- the left button has been double-clicked

      rightButtonDown	- the right mouse button is now down

      rightButtonUp	- the right  mouse button has been released

      rightButtonMove	- the mouse moved while the right button is down

      rightButtonDouble	- the right button has been double-clicked

      mouseMove	- the mouse moved when no button was down

      characterInput	- a key was pressed while the graphics window has

  input focus (see the setfocus command, above)


(View Text Window Commands)
Text Window Commands

The commands in this topic work with the text window and texteditor control.  Whatever you print to a text window is displayed exactly as sent.  The way to send commands to a text window is to make the ! character the first character in the string.  It is also important to add a semicolon to the end of command line (a print #handle line with text window commands) as in the example below.  If you don't, the print statement will force a carraige return into the text window each time you print a command to the window if you don't.

For example:

    open "Example" for text as #1      'open a text window

    print #1, "Hello World"            'print Hello World in the window

    print #1, "!font helv 16 37" ;     'change the text window's font

    print #1, "!line 1" ;              'read line 1

    input #1, string$

    print "The first line is:"

    print string$

    input "Press 'Return'"; r$

    close #1                           'close the window

Note: Most of the commands listed below work with windows of type text and also with the texteditor control except where noted.

Here are the text window commands:

  print #handle, "!autoresize";

    This works with texteditor controls, but not with textbox controls.

    This causes the edges of the control to maintain their distance from

    the edges of the overall window.  If the user resizes the window, the

    texteditor control also resizes.

  print #handle, "!cls" ;

    Clears the text window of all text.

  print #handle, "!contents varname$";

  print #handle, "!contents #handle";

    This has two forms as described above.  The first form causes the

    contents of the text window to be replaced with the contents of varname$,

    and the second form causes the contents of the text window to be

    replaced with the contents of the stream referenced by #handle.  This

    second form is useful for reading large text files quickly into the window.

    Here is an example of the second form:

      open "Contents of AUTOEXEC.BAT" for text as #aetext

      open "C:\AUTOEXEC.BAT" for input as #autoexec

      print #aetext, "!contents #autoexec";

      close #autoexec

      'stop here

      input a$

  print #handle, "!contents?";

    Returns the entire text of the window.  After this command is issued, it

    must be followed by:

    input #handle, string$

  print #handle, "!copy" ;

    This causes the currently selected text to be copied to the

    WINDOWS clipboard.

  print #handle, "!cut" ;

    This causes the currently selected text to be cut out of the

    text window and copied to the WINDOWS clipboard.

  print #handle, "!font fontName pointsize" ;

    Sets the font of the text window to the specified name and size.

    If an exact match cannot be found, then Liberty BASIC will

    try to match as closely as possible, with size figuring more

    prominently than name in the match.

    Note that a font with more than one word in its name is specified by

    joining each word with an underscore _ character.  For example, the

    font Times New Roman becomes Times_New_Roman, and the font

    Courier New becomes Courier_New.

    Example:

      print #handle, "!font Times_New_Roman 10";

  For more on specifying fonts read How to Specify Fonts

  print #handle, "!line #" ;

    Returns the text at line #.  If # is less than 1 or greater than the

    number of lines the text window contains, then "" (an empty string)

    is returned.  After this command is issued, it must be followed by:

    input #handle, string$

    which will assign the line's text to string$

  print #handle, "!lines" ;

    Returns the number of lines in the text window.  After this command

    is issued, it must be followed by:

    input #handle, countVar

    which will assign the line count to countVar

  print #handle, "!modified?" ;

    This returns a string (either "true" or "false") that indicates whether any

    data in the text window has been modified.  This is useful for checking

    to see whether to save the contents of the window before closing it.

    To read the result, an input #handle, varName$, must be performed

    after.

  print #handle, "!origin?" ;

    This causes the current text window origin to be returned.  When a text

    window is first opened, the result would be row 1, column 1.  To read the

    result an input #handle, rowVar, columnVar must be performed after.

  print #handle, "!origin row column" ;

    This forces the origin of the window to be row and column.

  print #handle, "!paste" ;

    This causes the text in the WINDOWS clipboard (if there is any) to be

    pasted into the text window at the current cursor position.

  print #handle, "!selectall" ;

    This causes everything in the text window to be selected.

  print #handle, "!selection?" ;

    This returns the highlighted text from the window.  To read the result

    an input #handle, varName$ must be performed after.

  print #handle, "!setfocus";

    This causes Windows to give input focus to this control.  This means

    that if some other control in the same windows was highlighted and

    active, that this control now becomes the highlighted and active

    control, receiving keyboard input.

  print #handle, "!trapclose branchLabel" ;

    This will tell Liberty BASIC to continue execution of the program at

    branchLabel if the user double clicks on the system menu box

    or pulls down the system menu and selects close (see ROLODEX1.BAS).

  print #handle, "!select column row" ;

    This will put the blinking cursor at column row.


Listbox

Listboxes in Liberty BASIC can be added to any windows that are of type graphics, window, and dialog.  They provide a list selection capability to your Liberty BASIC programs.  You can control the contents, position, and size of the listbox, as well as where to transfer execution when an item is selected.  The listbox is loaded with a collection of strings from a specified string array, and a reload command updates the contents of the listbox from the array when your program code changes the array.

Here is the syntax:

  LISTBOX #handle.ext, array$(), [branchLabel], x, y, wide, high

    #handle.ext  -  The #handle part of this item needs to be the same as the

handle of the window you are adding the listbox to.  The .ext

part needs to be unique so that you can send commands to the

listbox and get information from it later.

    array$()  -  This is the name of the array (must be a string array) that contains

the contents of the listbox.  Be sure to load the array with

strings before you open the window.  If some time later you

decide to change the contents of the listbox, simply change

the contents of the array and send a reload command.

    [branchLabel]  -  This is the branch label where execution begins when

the user selects an item from the listbox by double-clicking.

Selection by only single clicking does not cause branching

to occur.

    x, y -  This is the distance in x and y (in pixels) of the listbox from

the upper-left corner of the window.

    wide, high  -  This determines just how wide and high (in pixels) the

listbox is.

Here are the commands for listbox:

  print #handle.ext, "select string"

    Select the item the same as string and update the display.

  print #handle.ext, "selectindex i"

    Select the item at index position i and update the display.

  print #handle.ext, "selection? selected$"

    This will place the selected string into selected$.  If there is no selected

    item, then selected$ will be a string of zero length (a null string).

  print #handle.ext, "selectionindex? index"

    This will place the index of the selected string into index.  If there is no

    selected item, then index will be set to 0.

  print #handle.ext, "reload"

    This will reload the listbox with the current contents of its array and will

    update the display.

  print #handle.ext, "locate x y width height"

    Reposition the listbox control in its window.  This only works if the control

    is placed inside window of type window or dialog.  The control will not

    update its size and location until a refresh command is sent to the window.

    See the included RESIZER.BAS example program.

  print #handle.ext, "font facename pointSize"

    Set the listbox's font to the specified face and point size.  If an

    exact match cannot be found, then Liberty BASIC will try to find a

    close match, with size being of more prominance than face.

    For more on specifying fonts read How to Specify Fonts

    Example:

      print #handle.ext, "font times_new_roman 10"

  print #handle.ext, "singleclickselect"

    This tells Liberty BASIC to jump to the control's branch label on a single

    click, instead of the default double click.

  print #handle.ext, "setfocus"

    This will cause the listbox to receive the input focus.  This means that any

    keypresses will be directed to the listbox.

        ' Sample program.  Pick a contact status

        options$(0) = "Cold Contact Phone Call"

        options$(1) = "Send Literature"

        options$(2) = "Follow Up Call"

        options$(3) = "Send Promotional"

        options$(4) = "Final Call"

        listbox #status.list, options$(), [selectionMade], 5, 35, 250, 90

        button #status, Continue, [selectionMade], UL, 5, 5

        button #status, Cancel, [cancelStatusSelection], UR, 15, 5

        WindowWidth = 270 : WindowHeight = 180

        open "Select a contact status" for window as #status

      input r$

  [selectionMade]

      print #status.list, "selection? selection$"

      notice selection$ + " was chosen"

      close #status

      end

  [cancelStatusSelection]

      notice "Status selection cancelled"

      close #status

      end

Control of the listbox in the sample program above is provided by printing commands to the listbox, just as with general window types in Liberty BASIC.  We gave the listbox the handle #status.list, so to find out what was selected, we use the statement print #status.list, "selection? selection$".  If the result is a string of length zero (a null string), this means that there is no item selected.


Combobox

Comboboxes are a lot like listboxes, but they are designed to save space.  Instead of showing an entire list of items, they show only the selected one.  If you don't like the selection, then you click on its button (to the right), and a list appears.  Then you can browse the possible selections, and pick one if so desired.  When the selection is made, the new selection is displayed in place of the old.  If you don't want to make a new selection, just click on the combobox's button again, and the list will disappear.

Another thing you can do with a combobox is just type what you want into the textbox part on top if you don't like what's in the list.  Then you can get the contents of this field.

The combobox is loaded with a collection of strings from a specified string array,  and a reload command updates the contents of the combobox from the array when your program code changes the array.

  COMBOBOX #handle.ext, array$(), [branchLabel], xPos, yPos, wide, high

    #handle.ext  -  The #handle part of this item needs to be the same as the

handle of the window you are adding the listbox to.  The .ext

part needs to be unique so that you can send commands to the

listbox and get information from it later.

    array$()  -  This is the name of the array (must be a string array) that contains

the contents of the listbox.  Be sure to load the array with

strings before you open the window.  If some time later you

decide to change the contents of the listbox, simply change

the contents of the array and send a reload command.

    [branchLabel]  -  This is the branch label where execution begins when

the user selects an item from the listbox by double-clicking.

Selection by only single clicking does not cause branching

to occur.

    xPos & yPos  -  This is the distance in x and y (in pixels) of the listbox from

the upper-left corner of the window.

    wide & high  -  This determines just how wide and high (in pixels) the

listbox is.  Height refers to how far down the selection list

reaches when the combobox's button is clicked, not to the

size of the initial selection window.

Here are the commands for combobox:

  print #handle.ext, "!contents"

    Set the contents of the field part of the combobox to the string after the !.

  print #handle.ext, "locate x y width height"

    Reposition the burron in its window.  This is effective when the button

    is placed inside window of type window or dialog.  The button will not

    update its size and location until a refresh command is sent to the

    window.  See the included RESIZER.BAS example program.

  print #handle.ext, "font facename pointSize"

    Set the pen's font to the specified face and point size.  If an

    exact match cannot be found, then Liberty BASIC will try to find a

    close match, with size being of more prominance than face.

    For more on specifying fonts read How to Specify Fonts

    Example:

      print #handle.ext, "font times_new_roman 10"

  print #handle.ext, "select string"

    Select the item the same as string and update the display.

  print #handle.ext, "selectindex i"

    Select the item at index position i and update the display.

  print #handle.ext, "selection? selected$"

    This will place the selected string into selected$.  If there is no selected

    item, then selected$ will be a string of zero length (a null string).

  print #handle.ext, "selectionindex? index"

    This will place the index of the selected string into index.  If there is no

    selected item, then index will be set to 0.

  print #handle.ext, "reload"

    This will reload the combobox with the current contents of its array and will

    update the display.

  print #handle.ext, "setfocus"

    This will cause the combobox to receive the input focus.  This means that

    any keypresses will be directed to the combobox.

  print #handle,ext, "locate x y width height"

    Reposition the combobox control in its window.  This only works if the control

    is placed inside window of type window or dialog.  The control will not

    update its size and location until a refresh command is sent to the window.

    See the included RESIZER.BAS example program.

  print #handle.ext, "font facename pointSize"

    Set the combox's font to the specified face and point size.  If an

    exact match cannot be found, then Liberty BASIC will try to find a

    close match, with size being of more prominance than face.

    For more on specifying fonts read How to Specify Fonts

    Example:

      print #handle.ext, "!font times_new_roman 10"

For a sample program, see the included file dialog3.bas.


TEXTBOX

The textbox command lets you add a single item, single line text entry/editor box to your windows.  It is useful for generating forms in particular.

The syntax for textbox is simply:

  TEXTBOX #handle.ext, xpos, ypos, wide, high

  #handle.ext  -  The #handle part must be the same as for the window you

are adding the textbox to.  The .ext part must be unique for

the textbox.

  xpos & ypos  -  This is the position of the textbox in x and y from the upper-

left corner of the window.

  wide & high  -  This is the width and height of the textbox in pixels.

Textbox  understands these commands:

    print #handle.ext, "a string"

      This sets the contents of the textbox to be "a string".

    print #handle.ext, "!contents?"

      This fetches the contents of the textbox.  This must be followed by:

    input #handle.ext, varName$

      The contents will be placed into varName$

  print #handle.ext, "setfocus"

    This will cause the textbox to receive the input focus.  This means that any

    keypresses will be directed to the textbox.

  ' sample program

    textbox #name.txt, 20, 10, 260, 25

    button #name, "OK", [titleGraph], LR, 5, 0

    WindowWidth = 350 : WindowHeight = 90

    open "What do you want to name this graph?" for window_nf as #name

    print #name.txt, "untitled"

[mainLoop]

    input wait$

[titleGraph]

    print #name.txt, "!contents?"

    input #name.txt, graphTitle$

    notice "The title for your graph is: "; graphTitle$

    close #name

    end


Texteditor

Texteditor is a control that like Textbox, but with scroll bars, and with an enhanced command set.  The commands are essentially the same as that of a window of type text.  NOTICE that all of these commands start with an exclamation point, because the control will simple display anything printed to it if it doesn't start with an exclamation point.

Here is the syntax for texteditor:

  TEXTEDITOR #handle.ext, xpos, ypos, wide, high

Here are the texteditor commands:

  print #handle, "!cls" ;

    Clears the text window of all text.

  print #handle, "!font faceName width height" ;

    Sets the font of the text window to the specified face of width and

    height.  If an exact match cannot be found, then Liberty BASIC will

    try to match as closely as possible, with size figuring more

    prominently than face in the match.

  print #handle, "!line #" ;

    Returns the text at line #.  If # is less than 1 or greater than the

    number of lines the text window contains, then "" (an empty string)

    is returned.  After this command is issued, it must be followed by:

    input #handle, string$

    which will assign the line's text to string$

  print #handle, "!lines" ;

    Returns the number of lines in the text window.  After this command

    is issued, it must be followed by:

    input #handle, countVar

    which will assign the line count to countVar

  print #handle, "!modified?" ;

    This returns a string (either "true" or "false") that indicates whether any

    data in the text window has been modified.  This is useful for checking

    to see whether to save the contents of the window before closing it.

    To read the result, an input #handle, varName$, must be performed

    after.

  print #handle, "!selection?" ;

    This returns the highlighted text from the window.  To read the result

    an input #handle, varName$ must be performed after.

  print #handle, "!selectall" ;

    This causes everything in the text window to be selected.

  print #handle, "!copy" ;

    This causes the currently selected text to be copied to the

    WINDOWS clipboard.

  print #handle, "!cut" ;

    This causes the currently selected text to be cut out of the

    text window and copied to the WINDOWS clipboard.

  print #handle, "!paste" ;

    This causes the text in the WINDOWS clipboard (if there is any) to be

    pasted into the text window at the current cursor position.

  print #handle, "!origin?" ;

    This causes the current text window origin to be returned.  When a text

    window is first opened, the result would be row 1, column 1.  To read the

    result an input #handle, rowVar, columnVar must be performed after.

  print #handle, "!origin row column" ;

    This forces the origin of the window to be row and column.


STATICTEXT

Statictext lets you place instructions or labels into your windows.  This is most often used with a textbox to describe what to type into it.

The syntax of this command is:

  STATICTEXT #handle, "string", xpos, ypos, wide, high

    or

  STATICTEXT #handle.ext, "string", xpos, ypos, wide, high

  #handle  -  This must be the same as the #handle of the window you are

adding the statictext to.  If #handle.ext is used, this

allows your program to print commands to the

statictext control (otherwise all you'll be able to do is

set it and forget it).

  "string"  -  This is the text component of the statictext.

  xpos & ypos  -  This is the distance of the statictext in x and y (in pixels) from

the upper-left corner of the screen.

  wide & high  -  This is the width and height of the statictext.  You must specify

enough width and height to accomodate the text in "string".

Statictext understands only this command:

    print #handle.ext, "a string"

This sets the contents (the visible label) of the statictext to be "a string".  The handle must be of form #handle.ext so that you can print to the control.

    'sample program

    statictext #member, "Name", 10, 10, 40, 18

    statictext #member, "Address", 10, 40, 70, 18

    statictext #member, "City", 10, 70, 60, 18

    statictext #member, "State", 10, 100, 50, 18

    statictext #member, "Zip", 10, 130, 30, 18

    textbox #member.name, 90, 10, 180, 25

    textbox #member.address, 90, 40, 180, 25

    textbox #member.city, 90, 70, 180, 25

    textbox #member.state, 90, 100, 30, 25

    textbox #member.zip, 90, 130, 100, 25

    button #member, "&OK", [memberOK], UL, 10, 160

    WindowWidth = 300 : WindowHeight = 230

    open "Enter Member Info" for dialog as #member

    print #member, "trapclose [quit]"

    wait

[memberOK]

    print #member.name, "!contents? name$"

    print #member.address, "!contents? address$"

    print #member.city, "!contents? city$"

    print #member.state, "!contents? state$"

    print #member.zip, "!contents? zip$"

    cr$ = chr$(13)

    note$ = name$ + cr$ + address$ + cr$ + city$ + cr$ + state$ + cr$ + zip$

    notice "Member Info" + cr$ + note$

[quit]

    close #member

    end


STRUCT

STRUCT name, field1 as type1 [, field2 as type2, ... ]

Description:

This statement builds an single instance of a specified structure that might be required when making some kinds of API/DLL calls.  This does not declare a type of structure, but it creates a single structure.

Here is an example STRUCT statement that builds a Windows rect structure, used in many Windows API calls:

    'create the structure winRect

    struct winRect, _

        orgX as ushort, _

        orgY as ushort, _

        extentX as ushort, _

        extentY as ushort

To assign a field of a structure some value, treat it much as you would treat a variable, like so:

    winRect.orgX.struct = 100

And you can use any structure's field like any other variable, like so:

    print winRect.orgX.struct

  or:

   newOriginX = offsetX + winRect.orgX.struct

When passing a structure in a CALLDLL statement, specify type struct, like in this example:

  'WINRECT.BAS - show how to get window position and size

  'and demonstrate how to use the struct statement

  struct winRect, _

      orgX as uShort, _

      orgY as uShort, _

      crnrX as uShort, _

      crnrY as uShort

  open "test me" for window as #win

  open "user.dll" for dll as #user

  hndl =  hwnd(#win)

  calldll #user, "GetWindowRect", _

      hndl as word, _

      winRect as struct, _

      result as void

  print "Upper Left of 'test me': "; winRect.orgX.struct; ", "; winRect.orgY.struct

  print "Lower Right of 'test me': "; winRect.crnrX.struct; ", "; winRect.crnrY.struct

  close #user

  input r$

  end


OUT port, byte
OUT

OUT port, byte

Description:

This command sends a byte value to the specified machine I/O port.  The use of this command inside of Windows is considered to be only for those in the know.  Windows provides no method of ensuring that more than one application will not access any I/O port at a time, so use this command with care (you know who you are).

See also:  INP( )


INP( )

returnedByte = INP(port)

Description:  This function polls the specified machine I/O port for its byte value.

See also: OUT


HEXDEC( "value" )
HEXDEC( )

HEXDEC( "value" )

Description:

Returns a numeric decimal from a hexadecimal expressed in a string

Usage:

    print hexdec( "FF" )

or if preferred:

    print hexdec( "&HFF")

See also: DECHEX$( )


SPACE$( n )

Description:

This function will a return a string of n space characters (ASCII 32).  It is useful when producing formatted output to file or printer.

Usage:

    for x = 1 to 10

        print space$(x); "*"

    next x


OPEN "COMn:..."
OPEN "COMn:baud,parity,data stop{,options}" for random as #handle

Description:

The OPEN "COMn:" statement opens a serial communications port for reading and writing.  This feature uses Microsoft Windows' own built-in communications API, so if you have a multiport communications card and a WIndows driver to support that card, you should be able to use any port on the card.

The simplest form for this command is:

    OPEN "COMn:baud,parity,data,stop" for random as #handle

Allowable choices for baud are:

    75 110 150 300 600 1200 2400 1800 2400 4800 9600 19200 38400 57600 115200

Allowable choices are parity are:

    N	No parity

    E	Even parity

    O	Odd parity

    S	Space parity

    M	Mark parity

Allowable choices for data are:

    5	bits long

    6	bits long

    7	bits long

    8	bits long

Allowable choices for stop are:

    1	stop bit

    2	stop bits

Additional optional parameters can be included after the baud, parity, data and stop information:

    CSn	Set CTS timeout in milliseconds (default 1000 milliseconds)

    DSn	Set DSR timeout in milliseconds (default 1000 milliseconds)

    PE	Enable parity checking

    RS	Disable detection of RTS (request to send)

Other defaults:

    DTR detection is disabled

    XON/XOFF is disabled

    binary mode is the default

To set the in and out communications buffers (each port has its own), set the variable Com (notice the uppercase C) to the desired size before opening the port.  Changing the variable after opening a port does not affect the size of the buffers for that port while it is open.

    'set the size of the communications buffers (in and out) to 16K each

    Com = 16384

Usage Notes:

To open com port 2 at 9600 baud, 8 data bits, 1 stop bit, and no parity, use this line of code:

    open "com2:9600,n,8,1" for random as #commHandle

It is recommended that you set the the timeout on the DSR line to 0 so that your program doesn't just freeze when waiting for data to come in.  To do this, we can add a ds0 (for DSR 0 timeout) as below.  Notice we use a different communications speed in this example.

    open "com2:19200,n,8,1,ds0" for random as #commHandle

Remember that when a modem dials and connects to another modem, it negotiates a speed to connect at.  In the case of 14400 speed modems, you need to specify 19200 as the connection speed and let the

modems work it out between themselves during the connect.  This is because 14400 is not a baud rate supported by Windows (and you'll find that QBASIC doesn't directly support 14400 baud either).

Once the port is open, sending data is accomplished by printing to the port, like so (ATZ resets modems that understand the Hayes command set):

    print #commHandle, "ATZ"

To read from the port you should first check to see if there is anything to read.  This is accomplished in this fashion:

    numBytes = lof(#commHandle)

Then read the data using the input$() function.

    dataRead$ = input$(#commHandle, numBytes)

Putting the lof( ) and input$( ) functions together on one line, it looks like this:

    dataRead$ = input$(#commHandle, lof(#commHandle))

When you're all done, close the port like so:

    close #commHandle


UpperLeftX and UpperLeftY

Description:

The special variables UpperLeftX and UpperLeftY specify the distance from the top-left of the display that the next opened window will be.  For example, the following will open a graphics window 50 pixels from the left of the display, and 25 pixels from the top of the display:

    UpperLeftX = 50

    UpperLeftY = 25

    open "test window" for graphics as #testHandle

    input r$

See also: WindowWidth and WindowHeight


WindowWidth and WindowHeight

Description:

The special variables WindowWidth and WindowHeight specify the width and height of the next window to be opened.  If your program's code does not specify the values for these special variables, their defaults will be 320 and 360 respectively.  The following will open a graphics window 250 pixels wide and 100 pixels high.

    WindowWidth = 250

    WindowHeight = 100

    open "test window" for graphics as #testHandle

    input r$

See also: UpperLeftX and UpperLeftY


Command$
CommandLine$

Description:

This special variable contains any switches that were added when Liberty BASIC was started.  This is especially useful in applications executing under the runtime engine.


DisplayWidth and DisplayHeight

Description:

The special variables DisplayWidth and DisplayHeight contain the width and height respectively of the display screen.


UNLOADBMP

UNLOADBMP "name"

Description:

This command removes from Liberty BASIC the bitmap specified by "name".  It also frees the Windows memory resources associated with that bitmap.  This is useful for freeing bitmap resources when many bitmaps are used in a program.

See also:  LOADBMP, HBMP( )


Inkey$

Description: This special variable holds either a single typed character or Windows virtual keycode.  At this time, only the graphics window and graphicbox controls can scan for keyboard input.  The virtual keycodes are standard Windows constants, and include arrow keys, function keys, the ALT, SHIFT, and CTRL keys, etc.

See the included example program inkey.bas


HBMP( "name" )
HBMP( string expression )

Description:  Returns the Windows handle (a numeric value) for the bitmap whose name is specified by string expression.  This is often useful in different kinds of Windows API function calls and for use with third party DLLs.

Usage:

    loadbmp "title", "bmp\titlettt.bmp"

    tttHandle = hbmp("title")

    print tttHandle

See also: LOADBMP, UNLOADBMP


Graphicbox

The graphicbox is a control that can be added to any window type and that understands all of the commands of a graphics window type.

The syntax for this command is:

    graphicbox #handle.ext, xOrg, yOrg, width, height

  #handle.ext  -  The #handle part must be the same as for the window you

are adding the graphicbox to.  The .ext part must be unique for

the graphicbox.

  xOrg & yOrg  -  This is the position of the textbox in x and y from the upper-

left corner of the window.

  width & height  -  This is the width and height of the textbox in pixels.

Jump to commands for graphicbox


Titlebar

Description:  This command changes the titlebar of the main window.  It doesn't change the title of any other window.

Here's a real small clock program!

    'ittyclok

[loop]

    if time$ <> time$() then

        time$ = time$()

        titlebar time$

    end if

    scan

    goto [loop]


SQR( n )
Square root

Liberty BASIC does not have a built-in square root function.  Instead, simply raise a number to the power of 0.5 as follows:

  print "The square root of 2 is: ";

  print 2 ^ 0.5

Alternatively you could just define a squareroot function to your Liberty BASIC programs:

  print "The square root of 2 is: ";

  print squareroot(2)

  function squareroot(number)

      squareroot = number ^ 0.5

  end function


ONCOMERROR
ONCOMERROR [branchLabel]

Description:

Set or clear a branch label for handling errors when doing serial communications.

    'to set a branch label for error handling

    oncomerror [myComErrorHandler]

    'to disable com error handling

    oncomerror

When an error does occur, two special variables will be set:

    ComError$      This holds a description of the error

    ComPortNumber  This holds the port number of the error

See file erhandler.bas for an example program.


MIN( )

MIN( expr1, expr2 )

Description:

This function returns the smaller of two numeric values.

Usage:

input "Enter a number?"; a

input "Enter another number?"; b

print "The smaller value is "; min(a, b)

See also: MIN

Usage:


MAX( )

MAX( expr1, expr2 )

Description:

This function returns the greater of two numeric values.

Usage:

input "Enter a number?"; a

input "Enter another number?"; b

print "The greater value is "; max(a, b)

See also: MIN( )


MAINWIN

MAINWIN columns rows

Description:

Sets the width or width and height of a program's main window.  This is specified in colums and rows according the font of the mainwindow.  This is usually placed at the beginning of the program code.

Usage:

'set a width of 40 columns

mainwin 40

or...

'set the width to 40 columns and height to 12 lines

mainwin 40 12

See also: NOMAINWIN


FUNCTION

function functionName(zero or more parameter variable names)

  'code for the function goes in here

  functionName = returnValueExpression

end function

Description:

Define a function.  The function can return a string value, or a numeric value.  Zero or more parameters may be passed into the function.  To return a value from the function, set the value of the variable of the same name of the function.  The variables names inside a function are scoped locally, meaning that the value of any variable is different from variables of the same name outside of the function.  Arrays and handles of files and windows are global to a Liberty BASIC program, and visible inside of a function without needing to be passed in.

Branch labels are also locally scoped.  Code inside a sub cannot see branch labels outside of the sub, and code outside a sub cannot see branch labels inside any sub.

A function cannot contain another function definition, nor a sub definition.

The function definition must end with the expression: end function

Usage:

'count the words

input "Type a sentence>"; sentence$

print "There are "; wordCount(sentence$); " words in the sentence."

end

function wordCount(aString$)

  index = 1

  while word$(aString$, index) <> ""

    index = index + 1

  wend

  wordCount = index - 1

end function

See also: SUB


SUB

sub subName zero or more comma separated parameter variable names

  'code for the sub goes in here

end sub

Description:

Define a subprogram.  Zero or more parameters may be passed into the subprogram.  The variables names inside a subprogram are scoped locally, meaning that the value of any variable is different from variables of the same name outside of the subprogram.  Arrays and handles of files and windows are global to a Liberty BASIC program, and visible inside of a subprogram without needing to be passed in.

Branch labels are also locally scoped.  Code inside a sub cannot see branch labels outside of the sub, and code outside a sub cannot see branch labels inside any sub.

To use a subprogram, use the call statement to pass values into the subprogram.  The values you pass in must be the same type as the sub statement defines them to be.  So the following example:

  sub mySubName string$, number, string2$

might be called like this:

  call mySubName "string value", 123, str$("321")

A sub cannot contain another sub definition, nor a function definition.

The function definition must end with the expression: end function

Usage:

'copy two files into one

fileOne$ = "first.txt"

fileTwo$ = "second.txt"

combined$ = "together.txt"

call mergeFiles fileOne$, fileTwo$, combined$

end

sub mergeFiles firstFile$, secondFile$, merged$

  open merged$ for output as #merged

  open firstFile$ for input as #first

    print #merged, input$(#first, lof(#first));

  close #first

  open secondFile$ for input as #second

    print #merged, input$(#second, lof(#second));

  close #second

  close #merged

end sub

See also: FUNCTION


CALL

call subprogramName list of zero or more comma separated values

Description:

Invoke a user defined subprogram.  Call is followed by the name of the subprogram and by zero or more string and/or numeric expressions.

For more information see SUB


TIMER

TIMER milliseconds, [branchLabel]

Description: This commands manages a Windows timer.  This is useful for controlling the rate of software execution (games or animation perhaps), or for creating a program or program feature which activates periodically (a clock perhaps, or an email client which checks for new messages).

Usage:

    'set a timer to fire in 3 seconds

    timer 3000, [itHappened]

    'wait here

    wait

[itHappened]

    'deactivate the timer

    timer 0

    confirm "It happened!  Do it again?"; answer

    if answer then

        'reactivate the timer

        timer 3000, [itHappened]

        wait

    end if

    end


FONTDIALOG

FONTDIALOG fontSpec, fontSpecVar$

Description: Opens a Windows font dialog.  The fontSpec (see How to Specify Fonts) describes a font by name, size and other attributes.  The font dialog opens with a best fit to this spec.  The user can then accept or adjust the font selection.  The fontSpecVar$ holds a font specification the user chooses.

Usage:

    'open a font dialog

    fontdialog "arial 10 italic", chosenFont$

    if chosenFont$ <> "" then

        open "Font sample" for graphics as #font

        print #font, "down ; font "; chosenFont$

        print #font, "\\AaBbCcDdEeFfGgHhIiJj"

        print #font, "trapclose [closeFont]"

        wait

    end if

    end

[closeFont]

    close #font

    end


How to Specify Fonts

In Liberty BASIC there are many places where you can specify a font that you want to use in your programs.  This is done using a string with:

  The font name

  The size of the font

  Optional modifiers: italic, bold, strikeout, underscore

Here is an example:

  'Draw in a graphics window using the font Arial 14 point italic

  open "Font example" for graphics as #fontExample

  print #fontExample, "trapclose [quit]"

  print #fontExample, "down"

  print #fontExample, "font arial 14 italic"

  print #fontExample, "\\This is Arial 14 point italic"

  wait

[quit]

  close #fontExample

  end

In the above example, the line print #fontExample, "font arial 14 italic" contains a font specification,  everything after the word font is the specifier: arial 14 italic.

When you need to specify a font which has spaces in its name, use underscores like this:

  Courier New

becomes...

  Courier_New  (or you can ignore the uppercase letters and say courier_new).

You can specify a point size like we did above, or you can say how many pixels wide and high you want the font to be.  For example:

  'specify just a point size

  print #fontExample, "font Arial 14"

  'specify a width and height

  print #fontExample, "font Arial 8 15"

  'specify a height, and let Windows pick the width

  '(for compatibility with earlier versions of Liberty BASIC)

  print #fontExample, "font Arial 0 15"

You can optionally add modifiers like italic, bold, etc.:

  'go nuts and add ALL the modifiers

  print #fontExample, "font ms_sans_serif 8 italic bold strikeout underscore"


PRINTERDIALOG

Description: Opens the standard Windows printer selection dialog.  If the user chooses a printer and accepts, the next print job will go to this printer.  Accepting a printer also sets the global variables PrinterName$, PrintCollate and PrintCopies to reflect what the user chose for Collate and Copies.  If no printer is accepted, then PrinterName$ will be set to an empty string.

Usage:

    'choose a file to print

    filedialog "Print a BAS file", "*.bas", fileToPrint$

    if fileToPrint$ <> "" then

        printerdialog

        if PrinterName$ <> "" then

            open fileToPrint$ for input as #read

            while not(eof(#read))

                line input #read, line$

                lprint line$

            wend

            close #read

            dump

        end if

    end if

    end


DECHEX$( )

DECHEX$( number )

Description:

Returns a string representation of a numeric decimal converted to hexadecimal (base 16)

Usage:

    print dechex$( 255 )

prints...

    FF

See also: HEXDEC( )


GROUPBOX

GROUPBOX #handle.ext, "label", x, y, wide, high

Description:

Add a groupbox to a window or dialog box.  Other controls added to the owning window, and which overlap the displayed area of the groupbox will be nested inside the groupbox.  This is particularly useful for radiobuttons.  Only one of all radiobuttons in a groupbox will be allowed to be in a set state.  Click on one to set it, and all the others will be reset.

#handle.ext - You must use the same handle that will be used for the window that

  the groupbox will belong to, plus an optional unique extension (the .ext part of the handle).

"label"   - Type the label desired for the groupbox here.

x, y - These parameters determine where to position the groupbox.

wide, high - These optional parameters determine how wide and high the groupbox

  will be in pixels.

For an example of usage see the example program dialog3.bas.


POPUPMENU

POPUPMENU "text", [branchLabel], "text2", [branchLabel2],  |  , . . .

Description:

Pops up a Windows menu.  Each "text", [branchLabel] pair after the title adds a menu item to the menu, and tells Liberty BASIC where to branch to when the menu item is chosen.  The  | character can optionally be placed between menu items, to cause a separating line to be added between the items with the menu is popped up.

As an example, you might want to have a graphics window opened, and then be able to a menu to control drawing geometric objects.  Here is an example:

  nomainwin

  open "Geometric wite-board" for graphics_nsb as #geo

  print #geo, "trapclose [quit]"

  print #geo, "when rightButtonUp [popupMenu]"

  wait  ' stop and wait for a menu item to be chosen

[popupMenu]

  popupmenu "&Square Spiral", [asSquare], "&Triangular Spiral", [asTriangle]

  wait

[asSquare]

  print #geo, "cls ; home ; down ; color red"

  for x = 1 to 120

    print #geo, "go "; x; " ; turn 87"

  next x

  wait

[asTriangle]

  print #geo, "cls ; home ; down ; color blue"

  for x = 1 to 120

    print #geo, "go "; x; " ; turn 117"

  next x

  wait

[quit]

  close #geo

  end

Notice that the & character placed in the title and text items for the menu determines the accelerator placement for each menu item.

   See also MENU


WAIT

Description:

This simple statement causes program execution to stop and wait.  When the user interacts with a window or other control owned by the program and generates an event, program execution resumes at the event handler appropriate for their interaction.

Usage:

  'demonstrate the wait command (in three places)

  nomainwin

  open "Geometric wite-board" for graphics_nsb as #geo

  print #geo, "trapclose [quit]"

  print #geo, "when rightButtonUp [popupMenu]"

  wait  ' stop and wait for a menu item to be chosen

[popupMenu]

  popupmenu "&Square Spiral", [asSquare], "&Triangular Spiral", [asTriangle]

  wait

[asSquare]

  print #geo, "cls ; home ; down ; color red"

  for x = 1 to 120

    print #geo, "go "; x; " ; turn 87"

  next x

  wait

[asTriangle]

  print #geo, "cls ; home ; down ; color blue"

  for x = 1 to 120

    print #geo, "go "; x; " ; turn 117"

  next x

  wait

[quit]

  close #geo

  end

Note: In general, we encourage the use of wait over the previous practice of using input.


BMPSAVE

bmpsave "bmpName", "filename.bmp"

Description: Save a named bitmap to the specified filename.

Usage:

    'generate some graphics and save them to disk

    nomainwin

    open "Ellipses" for graphics as #1

        print #1, "trapclose [quit]"

        print #1, "down"

        print #1, "place 130 130"

        for x = 30 to 230 step 10

            print #1, "ellipse "; x ; " "; 260 - x

        next x

        print #1, "flush"

        print #1, "getbmp drawing 1 1 250 250"

        bmpsave "drawing", "ellipses.bmp"

    close #1

    end


DATA

Description:

The DATA statement provides a convenient way to insert data into your programs, which can be read once or many times using the READ statement.  A DATA statement doesn't actually perform an action when it is encountered in the program's code.

Example:

  'read the numbers and their descriptions

  while desc$ <> "end"

    read desc$, value

    print desc$; " is the name for "; value

  wend

  'here is our data

  data "one", 1, "two", 2, "three", 3, "end", 0

  end

One or more DATA statements form the whole set of data elements.  For example, the data represented in the example above could also be in more than one DATA statement, like so:

  'here is our data in two lines instead of one

  data "one", 1, "two", 2

  data "three", 3, "end", 0

See also: READ, RESTORE


READ

Description:

Fetches the next strings and/or numeric values from DATA statements in a program.  The READ statement will fetch enough items to fill the variable names the programmer specifies.  The values fetched will be converted to fit the variables listed (string or numeric).

Example:

  'read the numbers and their descriptions

  while desc$ <> "end"

    read desc$, value

    print desc$; " is the name for "; value

  wend

  'here is our data

  data "one hundred", 100, "two", 2, "three", 3, "end", 0

  end

You can also read items which are not expressed as strings (because they don't have double quotes) as numbers, like so:

  'read the numbers and their descriptions

  while desc$ <> "end"

    read desc$, value$

    print desc$; " is the name for "; value$; ", length="; len(value$)

  wend

  'here is our data

  data "one hundred", 100, "two", 2, "three", 3, "end", 0

  end

See also DATA, RESTORE


RESTORE

Description:

RESTORE will reset the reading of DATA statements so that the next READ will get information from the first DATA statement in the program (or the first DATA statement in a function or subprogram, if this is where the RESTORE is executed).

Example:

  'show me my data in all uppercase

  while string$ <> "end"

    read string$

    print upper$(string$)

  wend

  string$ = ""  'clear this for next while/wend loop

  'now reset the data reading to the beginning

  restore

  'show me my data in all lowercase

  while string$ <> "end"

    read string$

    print lower$(string$)

  wend

  data "The", "Quick", "Brown", "Fox", "Jumped"

  data "Over", "The", "Lazy", "Dog", "end"

  end

Optionally, you can choose to include a branch label, like so:

  'show me my data in all uppercase

  while string$ <> "end"

    read string$

    print upper$(string$)

  wend

  string$ = ""  'clear this for next while/wend loop

  'now reset the data reading to the second part

  restore [partTwo]

  'show me my data in all lowercase

  while string$ <> "end"

    read string$

    print lower$(string$)

  wend

  data "Sally", "Sells", "Sea", "Shells", "By", "The", "Sea", "Shore"

[partTwo]

  data "Let's", "Do", "Only", "This", "A", "Second", "Time", "end"

  end

See also DATA, READ


D-F
Commands Reference D-F

Jump to Liberty BASIC Help Document

   A-C D-F G-K L-M N-P R-S T-W

DATA	adds data to a program that can be read with the READ statement

DATE$( )	return string with today's date

DECHEX$( )	return a decimal number converted to a hexadecimal string

DefaultDir$	a variable containing the default directory

DIM array( )   	dimension array( )

DisplayWidth	a variable containing the width of the display

DisplayHeight	a variable containing the height of the display

Drive$	special variable, holds drive letters

DUMP	force the LPRINT buffer to print

EOF( #h )	end-of-file status for #h

END	marks end of program execution

EXP( n )	returns e^n logarithm

FIELD #h, list...	sets random access fields for #h

FILEDIALOG	opens a file selection dialog box

FILES	returns file and subdirectory info

FONTDIALOG	opens a font selection dialog box

FOR...NEXT   	performs looping action

FUNCTION	define a user function


G-K
Commands Reference G-K

Jump to Liberty BASIC Help Document

   A-C D-F G-K L-M N-P R-S T-W

GET #h, n	get random access record n for #h

GETTRIM #h, n	get r/a record n for #h, blanks trimmed

GOSUB label	call subroutine label

GOTO label  	branch to label

GRAPHICBOX	add a graphics region to a window

GROUPBOX	add a groupbox to a window

Graphics Commands	a detailed summary of graphics commands in Liberty BASIC

HEXDEC( "value" )	convert a hexadecimal string to a decimal value

HWND( #handle)	return the Windows handle for a window

HBMP( "name" )	return the Windows handle for a bitmap

IF THEN	perform conditional action(s)

Inkey$	contains a character or keycode from a graphics window

INP(port)	get a byte value from an I/O port

INPUT	get data from keyboard, file or button

INPUT$( #h, n )	get n chars from handle #h, or from the keyboard

INSTR(a$,b$,n)	search for b$ in a$, with optional start n

INT( n )	integer portion of n

KILL s$	delete file named s$


L-M
Commands Reference L-M

Jump to Liberty BASIC Help Document

   A-C D-F G-K L-M N-P R-S T-W

LEFT$( s$, n )	first n characters of s$

LEN( s$ )	length of s$

LET var = expr	assign value of expr to var

LINE INPUT   	get next line of text from file

LISTBOX	add a listbox to a window

LOADBMP	load a bitmap into memory

LOF( #h )	return length of open file #h or bytes in serial buffer

LOG( n )	natural log of n

LOWER$( s$ )	s$ converted to all lowercase

LPRINT	print to hard copy

MAINWIN	set the width of the main window in columns and rows

MAX( )	return the greater of two values

MENU	adds a pull-down menu to a window

MID$( )	return a substring from a string

MIN( )	return the smaller of two values

MKDIR( )	make a new subdirectory


N-P
Commands Reference N-P

Jump to Liberty BASIC Help Document

   A-C D-F G-K L-M N-P R-S T-W

NAME a$ AS b$	rename file named a$ to b$

NOMAINWIN	keep a program's main window from opening

NOTICE	open a notice dialog box

ONCOMERROR	set an error handler for serial communications

OPEN	open a file or window

OPEN "COMn:..."	open a communications port for reading/writing

OUT port, byte	send a byte to a port

Platform$	special variable containing platform name

PLAYWAVE  	plays a *.wav sound file

POPUPMENU	pops up a menu

PRINT	print to a file or window

PRINTERDIALOG	open a printer selection dialog box

PROMPT	open a prompter dialog box

PUT #h, n	puts a random access record n for #h


R-S
Commands Reference R-S

Jump to Liberty BASIC Help Document

   A-C D-F G-K L-M N-P R-S T-W

RADIOBUTTON	adds a radiobutton to a window

READ	reads information from DATA statements

REDIM	redimensions an array and resets it contents

REM	adds a remark to a program

RESTORE	sets the position of the next DATA statement to read

RETURN	return from a subroutine call

RIGHT$( s$, n )	n rightmost characters of s$

RMDIR( )	remove a  subdirectory

RND( n )	return pseudo-random seed

RUN s$, mode	run external program s$, with optional mode

SCAN	checks for and dispatches user actions

SIN( n )	sine of n

SORT	sorts single and double dim'd arrays

SPACE$( n )	returns a string of n spaces

Sprites	all about using sprites in Liberty BASIC

Square root	details about getting the square root of a number

STATICTEXT	add a statictext control to a window

STR$( n )	returns string equivalent of n

STRUCT	builds a structure used in calling of APIs and DLL functions

SUB	defines a subprogram


T-W
Commands Reference T-W

Jump to Liberty BASIC Help Document

   A-C D-F G-K L-M N-P R-S T-W

TAN( n )	tangent of n

Text Commands	a detailed summary of text window commands in Liberty BASIC

TEXTBOX	add a textbox (entryfield) to a window

TEXTEDITOR	add a texteditor widget to a window

TIME$( )	returns current time as string

TIMER	manage a Windows timer

TITLEBAR	sets the title bar of the main window

TRACE n	sets debug trace level to n

TRIM$( s$ )	returns s$ without leading/trailing spaces

UNLOADBMP	unloads a bitmap from memory

UPPER$( s$ )	s$ converted to all uppercase

USING( )	performs numeric formatting

UpperLeftX	specifies the x part of the position where the next window will open

UpperLeftY                 specifies the y part of the position where the next window will open

VAL( s$ )	returns numeric equivalent of s$

Version$	special variable containing LB version info

WAIT	stop and wait for user interaction

WHILE...WEND	performs looping action

WindowWidth	specifies the width of the next window to open

WindowHeight	specifies the height of the next window to open

WORD$( s$, n )	returns nth word from s$