The NewBASIC Language

To customize the behavior of your program, you write routines in a BASIC-like language. When the program is running, components experience events when the user interacts with them. You can create BASIC routines which are executed in response to these events. In this manner, you can define the effects of the user's interactions with your program's UI gadgetry.

In the Builder, you can double-click on any component to bring up the Code Editor window. The Code Editor allows you to select, edit, and create BASIC routines. The rest of this chapter covers the organization of these BASIC routines, interactions with the Code Editor window, and the syntax of the BASIC flow-control constructs and built-in routines.

• Organization of BASIC Code
• The Editor Window
• The Language

Organization of BASIC Code

BASIC Code is organized into routines.

Let us look at the parts of a routine, using a simple example:

FUNCTION Squared( x AS float )
Squared = x * x
END FUNCTION

This routine, as do all others, consists of a name, a set of arguments, and one or more BASIC expressions.

A routine's name identifies it. In the above example, the routine's name is "Squared." Routine names may be up to 128 characters long; the first character must be an alphabetic character, and all other characters must be either alphanumeric characters or underlines.

A BASIC expression calling the Squared( ) function would consist of the name "Squared" followed by a parenthesized list of arguments:

area = Squared( sideLength )

Here the return value of the Squared( ) function is assigned to the area variable.

Within routines, BASIC code is organized into lines. As you learn more about program syntax, pay attention to how syntax elements are arranged into lines. If you don't, you might get into trouble. For instance:

IF foo THEN
REM This works...
x = bar
END IF

IF foo
REM ...but this is a syntax error
THEN x = bar
END IF

You can work around this behavior by means of the backslash ("\") character. If you put this character at the end of a line of code, then the next line of code will be treated as a continuation. Note that the backslash must appear at the very end of the line, and may not be followed by any other characters, not even spaces. For example,

IF foo \
REM This works...
THEN
x = bar
END IF

Do not use a backslash to break up a name (a routine name, variable name, property name, etc.), because it won't work. Backslashes used as line continuators in string constants cause bugs.

IF f\
REM Don't do this!
oo THEN
s = "b\
ar"
REM Don't do this, either!
END IF

Event Handler Routines

Routines with special names are executed under certain pre-defined circumstances. Event handlers are just routines with special names identifying them as such. NewBASIC knows to execute the button1_pressed( )routine when the user clicks on the button1 component. For information about the pass and return values to use when writing event handler routines, see the Component type reference material in Component Types.

In general, names of event handlers are of the form

componentName eventName

To change the component name used in the construction of a component's event handler names, change its proto property. If you set button1's proto property to "FunButton," then it will generate FunButton_pressed( ) events instead of button1_pressed( ) events. Be careful, however.

Components created via the MakeComponent( ) function don't have their proto property set by default; you must set it yourself. A simple example:

DIM FunButton AS component
FunButton = MakeComponent("button", form1)
FunButton.caption = "Press for More Fun"
FunButton.proto = "FunButton"

Some Special Routines

module_init( )

is called when your program is first loaded. This routine is useful for initializing global variables which are used by event handlers.

module_goTo( )

is called when the Application Launcher wants your application to go to a specific context.

module_show( )

is called when the Application Launcher wants your program to appear; this is a good routine in which to make your window components visible.

module_hide( )

is called when the Application Launcher wants your program to disappear. Your program will continue to run in the background. Normally, this routine should make your program's windows invisible.

module_getContext( )

is called when the Application Launcher wants to remember your application's current context, so that it can go to that context later. Specify the context by means of the return value of this function.

module_exit( )

is called when your program is about to be unloaded.

Functions and Subroutines: The Distinction

There are two types of routines:

• functions, which return values, and
• subroutines, which do not.

Thus, function calls normally appear within the body of assignment expressions:

area = Squared( sideLength )

whereas routine calls appear on their own:

Update( )

When calling a function, you must make sure that the return value is used within an expression. If it isn't, then an error will result when NewBASIC tries to execute that line of code. If you won't use a function's return value, just use a "dummy" variable to hold the return value:

ignore = Squared( 2 )

The Editor Window

The Editor allows you to edit BASIC code. The gadgetry in the upper part of the window allows you to select a routine to edit, create a new routine, or set a breakpoint in a routine. The white area in the lower part of the window is a text editing window where you may edit a routine's BASIC code.

Choosing an Event Handler or Routine to Edit

If you wish to edit the contents of one of a component's event handler, choose

1. the component's name from the Editor window's Components list.
2. the appropriate event name from the Events list.

The appropriate event handler routine will appear in the text editing area. For instance, suppose your program has a button with the name "button1." If you choose button1 from the Editor window's Components list, then choose clicked from the Events list, the button1_pressed( ) subroutine should appear. Assuming you haven't entered any BASIC code for that handler yet, it will look like

SUB button1_pressed( self AS integer )
END SUB

To edit an existing routine that is not an event handler, select its name in the Editor window's Routines list. You can also select previously edited event handlers from this list.

Creating a New Routine

As discussed in Organization of BASIC Code, there are two types of routines: functions, which return values; and subroutines, which do not.

To create a new function

1. Press the Editor window's New Function button. The Editor's text edit area will be updated to show an empty function:

   FUNCTION
END FUNCTION

2. Add the function's name, arguments, and return value to the function declaration.

For example:

FUNCTION Squared( x AS float ) AS float
END FUNCTION

To create a new subroutine

1. Press the Editor window's New Subroutine button. The Editor's text edit area will be updated to show an empty subroutine:

   SUB
END SUB

2. Add the subroutine's name and arguments to sub declaration:

SUB UpdateButtonCaptions( baseText AS string )
END SUB

Deleting and Renaming Routines

To delete a routine, select its name in the Routines list and press the Delete Routine button.

To rename a routine, complete the following steps:

1. Select its name in the Routines list and wait for its text to appear in the text window.
2. Change the routine's name on the top line of the Routine.
3. Choose another routine's name in the Routines list.
4. Delete the old routine name.

Setting and Un-setting Breakpoints

Breakpoints are used when debugging; we will not discuss them in depth here. For information about using breakpoints, see Breakpoints: Pausing in Routines.

Pressing the Toggle Breakpoint button causes the selected line (if any) in the Editor window's text edit area to set a breakpoint on that line, or to un-set an existing breakpoint on that line.

If a line of BASIC code has a breakpoint set upon it, it will appear with a red background (dithered black and white in black-and-white mode) in the Editor window text area.

Editing and Reading a Routine's BASIC Code

Once you've selected (or created) a routine, its BASIC code appears in the Editor window's text edit area.

When you view routines, some lines of BASIC code may be drawn with a colored background.

• If a line of BASIC code appears with a red background, that means there's a breakpoint set on that line. You can use the Editor window's Toggle Breakpoint button to set and un-set these breakpoints.
• If your program is running and paused, then there might be a line of BASIC code drawn with a blue or purple background.
  • If it's drawn with a blue background, then that's the line that the program is paused on: if you resume program execution, the blue line will be the next line executed.
  • If the line is drawn with a purple background , that means that execution is paused on that line and there's a breakpoint set on that line.
• If NewBASIC program editing is done in black-and-white mode, all the colors show up as dithered black and white.

If you are running your program from the Builder, you won't be able to edit any routines until you stop it by pressing the Stop button. However, you can still look at routines and set breakpoints.

When you edit routines, only the text between the first and last lines of the routine will be preserved; other text will be lost.

SUB button1_pressed( self AS component )
   REM User has clicked the "Go!" button.
   REM Reset the score value.
   number1.value = 0
END SUB
   REM This comment will be lost; it's not inside a routine.

Keyboard shortcuts

There are some keyboard shortcuts to quicken some common editing tasks:

Keystroke	Resulting Action
Ctrl+A	Position cursor at stArt of line.
Ctrl+D	Delete the character after cursor.
Ctrl+E	Position cursor at End of line.
Ctrl+K	Kill text between the cursor and the next carriage return.
Ctrl+N	Move cursor down one line (to the Next line).
Ctrl+P	Move cursor up one line (to the Previous line).