BBj Object Syntax Code Completion

Overview

The BASIS IDE's BBj Source Editor and Debugger have a code completion feature that simplifies working with BBj Object syntax. This feature displays a popup window that lists the variables and methods belonging to a BBj Object whenever the editor senses they are needed to complete a program statement. Selecting an item from the popup window automatically pastes it into the line being edited. Code completion saves development time by offering convenient on-the-spot documentation for BBj Objects and quick, error-free entry of their needed parts.

At this writing, the Business BASIC programming language does not have a standard syntax for declaring variable types. It does not require the data type of a variable to be formally declared before the variable is used or assigned a value in a program statement. As a result, the data type of the variable can only be determined with certainty by the interpreter at run time. It is not possible in many cases for an editor to syntactically analyze a line of Business BASIC code and determine the data types of the variables it contains, yet this information is essential for code completion. If the data type of a BBj Object variable is unknown, the editor does not know which BBj Object's variables and methods to show in the completion popup window.

BBj Object syntax code completion is therefore a two-step process: First, declare the data type of the BBj Object, then select which of the Object's methods or member variables to place in the code. Both of these steps are documented below.

Step 1. Declare Object Variable Types

In order to use code completion with any given Object variable, it must first be declared an instance of some BBj API Object or Java class. There are three different ways to declare an Object variable's data type:

  • Dynamically declare the data type while writing program code in the editor.

  • Declare or import data types using the Edit/Import Dialog while the program code is loaded in the editor.

  • Place data type declarations in the BBjObjectTypes.txt file before starting to edit the program code.

Declare data type while editing code

BBj Object syntax requires the exclamation mark ('!') as the last character of an Object variable name. When the editor detects this character, it checks an internal map to find out if a variable of that name has already been declared. If not, the type declaration popup window appears. In the figure below, no type declaration was found for the variable sysgui! and the declaration popup window is offering choices from the BBj API or various Java packages.

 

source_editor_declaration1.png

 

To declare a variable's data type:

  1. Enter the name of a new Object variable, including the '!' at the end. The type declaration popup window will appear. (To abort the type declaration process and skip the remaining steps, simply continue typing the rest of the program statement. The type declaration popup window will disappear until the next time the variable name is entered.)

  2. Use the arrow keys or mouse to move through the scrollable list and find the desired selection.

  3. Press ENTER or double-click on the selection. If the selection is a Java package instead of a class, or if the selection represents a grouping of BBj Objects instead of a particular Object, the popup window will repaint with a new list of items from subdirectories or subclasses of the previous selection. It may be necessary to make several selections in order to arrive at the specific class or Object needed. If the selection is actually a BBj Object or Java class, the popup window will close.

After the variable's data type is declared, the code completion mechanism is enabled for that specific variable name. Subsequent use of that variable name will no longer trigger the declaration popup window.

When the file is saved to disk, all the accumulated variable type declarations will be stored in a file called BBjObjectTypes.txt, located in the defaultuser/system/Projects/<project name>/system/ParserDB directory. If the file is not saved, the variable declarations made during this editing session will be lost.

To add type declarations to variable names in already completed program code:

  1. Open the file in the Source Editor or Debugger.

  2. Position the text caret immediately after the '!' character at the end of a BBj Object variable name.

  3. Press <Backspace> to delete the character and then type '!' again. This opens the declaration popup window, allowing a data type to be selected as described above.

Declare data type using the Edit/Import Dialog

The Edit/Import Dialog adds more flexibility to the process of declaring BBj Object variable types during an editing session. Object variables and data types can be added, deleted or modified using the Edit Declarations tab of the dialog. Declarations that were previously made for other source files can be imported into the current file using the Import Declarations tab of the dialog.

 

source_editor_edit_import_dialog1.png

 

As shown above, the Edit Declarations tab presents an alphabetically sorted listing of all the BBj Object variables defined in the current file.

To use the Edit/Import Dialog:

  1. Open a program file in the Source Editor or Debugger.

  2. Select Tools ->Edit/Import BBj Object Declarations from the main menu to open the dialog. Note that the edit window of the Source Editor or Debugger must have keyboard focus, or the Edit/Import BBj Object Declarations menu item will be disabled.

To edit an existing variable type declaration:

  1. Select the Edit Declarations tab of the dialog.

  2. Place the mouse pointer over the variable name or variable type of the declaration and double click the left mouse button, which activates editing in the text field.

  3. Enter the new name or data type.

  4. Press ENTER or right click in another field to finalize the editing.

  5. Press the Save Variable Declarations button to store the edited declaration in the BBjObjectTypes.txt file. The Source Editor and Debugger will not recognize any changes made in the dialog until this button is pushed.

  6. Press the OK button to exit the dialog.

To delete an existing variable type declaration:

  1. Select the Edit Declarations tab of the dialog.

  2. Place the mouse pointer over the variable name or variable type of the declaration and click the left mouse button, which selects the row. (Hold down the CTRL key to select multiple rows.)

  3. Press the Delete Selected Rows button to delete the declaration(s).

  4. Press the Save Variable Declarations button to save the changes.

  5. Press the OK button to exit the dialog.

To add a new variable type declaration:

  1. Select the Edit Declarations tab of the dialog.

  2. Press the Add New Row button. A new empty row will appear at the bottom of the list.

  3. Place the mouse pointer over the variable name cell of the empty row and double click the left mouse button to activate text editing.

  4. Enter the variable name. Do not include the '!' at the end of the name.

  5. Repeat steps 3 and 4 with the empty variable type cell. Note that data types representing Java classes require the complete package hierarchy and class name in this field (such as java.util.HashMap). BBj API data types require entering only the formal Object name.

  6. Press the Save Variable Declarations button to save the changes.

  7. Press the OK button to exit the dialog.

 

source_editor_edit_import_dialog2.png

 

As pictured above, the Import Declarations tab shows a tree of folders representing all the other files in the project which contain BBj Object variable declarations. Any or all of these declarations can be imported into the file currently being edited.

To import variable type declarations from other files:

  1. Select the Import Declarations tab of the dialog.

  2. Expand the folders representing other program files as required to see the available declarations. Left click on the plus or minus symbol to the immediate left of the folder icon to expand or contract a folder's contents.

  3. Select any combination of declarations by clicking the left mouse button in their checkboxes. If the checkbox of a file is selected, every declaration in that file will be imported regardless of the status of the checkboxes of individual declarations. Likewise, if the checkbox at the top of the list representing BBjObjectTypes is selected, every declaration from every file will be imported, regardless of the status of any other checkboxes in the list.

  4. Press the Import Selected Variables button to perform the import.

  5. Select the Edit Declarations tab of the dialog. Note that the list of declarations now includes everything that was selected in the Import Declarations tab.

  6. Press the Save Variable Declarations button to save the changes. Remember that changes will not become effective in the Source Editor or Debugger until this button is pressed. Forgetting this step means that all imports are unrecognized and discarded.

  7. Press the OK button to exit the dialog.

If the BBjObjectTypes.txt file itself is edited or modified at the same time that a program file is being edited, it may be desirable to reload it in order to take advantage of new information. Simply press the Reload Variable Declaration File button to reload the BBjObjectTypes.txt file into the Import Declarations tab.

Declare data type by editing the BBjObjectTypes.txt file

The BBjObjectTypes.txt file serves as a central repository for all the variable type declarations in all the program files belonging to a NetBeans Project. Each file containing declared Object variables has its own entry in this file, as shown below:

 

#BBj Object Type Declarations for project C:\netbeans36\user\system\Projects\BBj Tests
#Wed Apr 6 15:20:09 MDT 2005

[C:\bbjtests\workbench.src]
myFont=BBjFont
exitMenuItem=BBjMenuItem
menuBar=BBjMenuBar
wbNameSpace=BBjNamespace
appTreeMap=java.util.TreeMap
api=BBjAPI
fileMenu=BBjMenu
sysgui=BBjSysGui
mdi=BBjMDI

[C:\bbjtests\workbenchTree.src]
curFont=BBjFont
viewSourceMenuItem=BBjMenuItem
appTree=BBjTree
wbNameSpace=BBjNamespace
newFont=BBjFont
api=BBjAPI
northBorder=BBjMDIBorder
executeMenuItem=BBjMenuItem
toolBarWindow=BBjWindow
westBorder=BBjMDIBorder
mdi=BBjMDI
techConLabel=BBjStaticText
myFont=BBjFont
pinButton=BBjButton
sysgui=BBjSysGui
popupMenu=BBjPopupMenu
window=BBjWindow
activeCaptionColor=java.awt.SystemColor

[Some generally useful declarations]
api=BBjAPI
sysgui=BBjSysGui
mdi=BBjMDI
popupMenu=BBjPopupMenu
menuBar=BBjMenuBar

 

The BBjObjectTypes.txt file is text data and may be edited with any text editor. Manual editing of this file could result in runtime errors if mistakes are made with the syntax, but the IDE does attempt to ignore incorrectly formatted declarations when the file is scanned. Whenever a program file is loaded in the Source Editor or Debugger, the BBjObjectTypes.txt file is scanned for an entry that corresponds to the path/filename of the program file. If an entry is found, the declarations belonging to that file are loaded so the code completion system is immediately ready to use. File entries made in the BBjObjectTypes.txt file do not have to correspond to actual program files on the disk. Note the section called "Some generally useful declarations". An entry such as this could serve as a convenient place to store declarations that are commonly imported into many different files.

Step 2. Use Code Completion

The code completion popup window automatically appears after a short delay when the decimal ('.') character is typed at the end of a declared BBj Object variable name.

source_editor_completion1.png

In the above image, the variable api! was declared to be an instance of BBjAPI. One of its methods or member variables is needed to complete the current statement, and the code completion popup window is displaying the choices associated with the BBjAPI Object.

 

source_editor_completion2.png

 

The BBjAPI.newBBjSession(BBjCommandLineObject) method was selected and pasted into the code. This method takes a single parameter, a BBjCommandLineObject, so the code completion system is prompting for it.

 

To complete a BBj Object statement:

  1. Type the name of an Object variable that has already been declared.

  2. Type the '.' and pause, or press Ctrl+<Space> or Ctrl+\ (backslash). The code completion popup window appears.

  3. Do one of the following to select an item from the list and paste it into the code:

  • Continue typing to narrow down the selection of items in the list.

  • Use the mouse or navigation keys (Up Arrow and Down Arrow, Page Up, Page Down, Home, and End) to scroll through the list and select an expression.

  • Double click the left mouse button or press ENTER to paste the selection into the code and close the window.

  • Press ESCAPE to close the code completion popup window without pasting the selection into the code.

Two options that affect the code completion system are included with the editor settings in the Options window. To adjust these settings:

      1. Select Tools ->Options from the main menu to open the Options window.

      2. Expand the Editing ->Editor Settings ->BBj Source Editor/Debugger folders.

      3. Deactivate the automatic popup of the type declaration and code completion windows by clicking on the checkbox of the Auto Popup Completion property. When the box is unchecked, typing Ctrl+Space or Ctrl+/ will still bring up the code completion window.

      4. Adjust the delay for showing the code completion popup window by editing the Delay of Completion Window Auto Popup property. The delay is measured in milliseconds. Note that this delay has no effect on the type declaration popup window, which always appears immediately unless deactivated.

 

Automatic code completion is actually more complex than what has been described here. Other useful tips and techniques can be found in the Java code completion section of the NetBeans online help by expanding Editing Source Files ->Using Code Completion.