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.
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
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"
There are two types of routines:
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 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.
If you wish to edit the contents of one of a component's event handler, choose
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.
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
FUNCTION
END FUNCTION
For example:
FUNCTION Squared( x AS float ) AS float
END FUNCTION
To create a new subroutine
SUB
END SUB
SUB UpdateButtonCaptions( baseText AS string )
END SUB
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:
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.
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 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.
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). |