The New Deal IDE

The New Deal Integrated Development Environment (IDE) consists of a number of New Deal programs which allow you to develop NewBASIC Applications.

As you create NewBASIC programs, you will spend most of your time using the NewBASIC Builder application. The Builder allows you to put together a NewBASIC application: visually arranging UI gadgetry, writing custom BASIC code, and running your program in the emulator. This chapter introduces you to the features of the Builder.


Getting Started

This documentation assumes that the IDE currently exists on your computer. Please consult the Installation Guide if this is not the case. To enter the IDE, within New Deal launch the NewBASIC Builder icon.


Welcome To The NewBASIC Builder

When you first start up the Builder, it should look something like the picture to the left.

Before we discuss how you can get things done with the Builder, let's take a quick look at its user interface. Once you are familiar with the main window and the palettes, you will be ready to begin.

The Main Builder Window

This contains special window buttons, some menus, and some buttons which you will use when debugging your programs. These are described in more detail in this chapter.

Special buttons:

Menus:

Debugging Buttons:

The Component Palette

The Component Palette contains buttons which allow you to add new "components" to your application. Components are objects which may appear on screen as part of your program, which can respond to user or system input, and which may alert your program to certain events. A button is a simple component--it detects when the user clicks it, and alerts your program.

To add a component to your program, you click on the button with the component's type name on it, then click on your form. There are many component types to choose from, and not all will appear on the component palette at once--the palette would never fit on your screen! There is a special button in the palette captioned Basic UI -, which, when pressed, allows you to make another set of component types appear in the component palette. If the Palette is ever hidden, you may force it to appear by choosing Toolbox from the Window menu in the main window.

The Form

When you first open a new program, you start with just a form. This is a component which acts as a New Deal primary window. In general, you will add components (such as buttons, text entries, and labels) to this form. In this documentation, you will often read about adding components to the form, selecting components on the form and such. Your program may contain multiple forms and other windows. Most operations which involve adding components to the form and selecting components on the form, may in fact may be applied to components on any of your program's forms or windows.

Properties Box

The Properties box, does not appear when you first start the Builder but is worth mentioning. It allows you to set the starting values for the properties of your program's components.

Editor Window

The Editor window, also does not appear when you first start the Builder but is worth mentioning. It allows you to edit your program's BASIC code.


Adding a Component to the Form

To add a new component to your program, you will press the appropriate button on the component palette, then click on your program's form to place the component.
For example, to add a button component to the form, you would carry out the following steps:

  1. Find the Component Palette. If it's not visible, then choose Toolbox from the Window menu in the main window.
  2. Find the button button in the Component Palette. If the button button is not showing, then choose Basic UI from the popout list at the top of the Palette.
  3. Press the button button in the Component Palette. Move the pointer over to the form. The arrow pointer picture should change to a bent arrow.
  4. Click in the middle of the form. A button called button1 should appear in the middle of the form.

Depending on the type of the component that you're adding, you might not need to place it on the form. When you create a new form, dialog, or floater, the component might just appear. Some components are never visible; you might not need to add them to the form, and when added, they might not "appear"--because they are never visible.

If you press one of the palette buttons, and then--before you add the new component to your form--decide that you don't really want to add the component to your program, press the + button in the palette to clear your selection.


Moving and Re-sizing the Component

Once a component is on the form, you may


Changing the Component's Properties

Components have several properties. For a complete list of the properties supported by each component type, see the documentation for that component type in the Component Type reference section, which begins on Component Types. Some properties common to many component types are:

visible
You can turn off this property to make a component invisible--it won't appear on-screen, nor will its children, the components it contains. Turn the property back on to make the component visible again.
enabled
By turning off this property, you can cause a component to appear grayed-out and to ignore user input. Also, its children will be grayed out and will ignore user input. Turn the property back on to enable the component to receive user input again.
name
The name by which BASIC code may refer to the component. The name should be a proper BASIC name.
caption
The component's caption is text that appears on the component when it appears on-screen, text by which the user may identify the component. The captions of OK and Cancel buttons are "OK" and "Cancel."

Depending on the type of the component you've selected, the properties box will contain different sets of properties. After all, different types of components have different properties.

How to change the starting properties

To change a component's starting properties take the following steps:

  1. Select the component whose properties you want to change. If it is visible, you can select it by clicking on it with the mouse. You may also select it by choosing its name from the Components list in the Editor window.
  2. Find the Component Properties dialog box; if it is not visible, then choose Component Properties from the Window menu. The Component Properties box should appear.
  3. There are three "areas" of the Component Properties box: General, Children, and Specific. Each of these areas allows you to change some of the properties for a component--to view a different area of the box, you can click one of the buttons towards the top of the Properties dialog box.
  4. Each area of the Properties box contains settings which allow you to define one or more of the selected component's properties. Work with the components. To make your changes take effect, you press the Apply button.

For example, let's change the caption of the button you created earlier.

  1. Click on the button to select it.
  2. Choose Component Properties from the Window menu. In a few seconds, the Component Properties box should appear.
  3. To work with the caption property, we want to be in the General area of the Properties box. Press the General button.
  4. Find the entry called Caption--the entry's text probably says button1 now.
  5. Change the text in the Caption entry to Make Funky.
  6. Press the Apply button, found at the bottom of the Properties box. The button on the Form should now appear with the text "Make Funky."

About the component properties box

The top-left corner of the Properties box contains a button which you may press to close the Properties box, ridding your screen of clutter.

If you select a different component while the Properties box is showing, after a few seconds, the Properties box will show you the properties of that component--and allow you to change the properties of that component.

Components which don't have children won't allow you access to the Children area of the Properties box. The Specific area of the Properties box contains properties special to that component's type.


Adding BASIC Code

There's more to a program than just components. Programs don't just consist of buttons on a form. What makes a program useful is how it reacts when the user presses a button on a form. You will specify how your program responds to user and system input by writing routines in a BASIC-like programming language.

Your program detects user and system input through its components: buttons can tell when the user clicks them, text entries can tell when the user enters text in them, timers detect ticks of the system clock. Components generate events, and you can write BASIC routines that will execute when an event is generated. These routines are known as event handlers.

How to edit an event handler

Editor To edit an event handler, follow these steps:

  1. Open the Editor window. If it's not visible, then choose Editor from the Window menu. The Editor window will look something like the window pictured to the right.
  2. In the Editor window, there's a list called Components. Select the name of the component whose event you want to handle.
  3. There's another list in the Editor window, a list called Events. This contains the names of the events that the selected component can generate. Depending on a component's type, it might generate just one kind of event, several kinds of events, or no events. Choose the name of the event you want to handle.
  4. In a few seconds, the text entry area that takes up most of the space of the Editor window will show you the BASIC code for that event handler. By typing BASIC code in the routine, you edit the event handler.
  5. If you do something else in the Builder--select another handler to edit, run your program, save your program--the Builder will parse the routine you've been editing to check its BASIC syntax and look out for other errors. If it detects errors, it will display an error dialog box and highlight the line of BASIC code that seems wrong.

For example, let's make an event handler for the Make Funky button we've been working on:

  1. Choose Editor from the Window menu. After a few seconds, the Editor window should appear.
  2. In the Components list in the Editor window, select the button1 item.
  3. After a couple of seconds, the Events list should contain one item, called pressed. Select it.
  4. After a couple of seconds, the text area of the Editor window should contain the text
    SUB button1_pressed( self AS button )
    END SUB
  5. Click on the blank text line between the "SUB..." and "END SUB" lines to position the text cursor. Enter text so that the event handler reads
    SUB button1_pressed( self AS button )
    form1.caption = "Funky"
    END SUB
  6. We want the Editor to check your routine to make sure you haven't made any syntax errors. Choose module_init( ) from the Routines list in the Editor window. At this point, two things can happen: either the module_init( ) subroutine will appear in the Editor's text window, or else an error dialog box will appear telling you that there was a syntax error in the button1_pressed(  ) routine. If there's no error, then you're done. But...
  7. If there was an error
  8. Note the error message in the error dialog box. It might give you a hint about what went wrong.
  9. Press OK in the error dialog box.
  10. Look at the Editor text area. There should be a line of BASIC code highlighted. There is a good chance that the syntax error is on this line.
  11. Check over the BASIC code you wrote. Does it appear as shown in step 5, above? It should read form1<period>caption<space><equals-sign><space><double-quote>Funky<double-quote>. It should all be on the same line of text.

About the edit window

You may also create and edit routines that are not event handlers--as you will see, routines can call other routines. To edit an existing routine, you may choose its name from the Routines list in the Editor window. To create a new routine, press the New Sub or New Function button.

The chapter of this manual which describes the BASIC programming language, starts on The NewBASIC Language.


Testing the Program with the Builder

You can use the Builder to give your program a test run. Eventually, you'll want to test your program on the device it is to run on; however, by using the Builder's own emulation, you can shorten your testing/coding cycle.

How to test your program with the Builder

To test your program

  1. Press the Run button in the main Builder window. After a few seconds, your program will start running. You will be able to interact with your program's windows and buttons.
  2. While your program is running, you may press the Pause button in the main Builder window to pause it. The Builder continues execution of the program when you press the Continue button.0

If your program encounters any errors, it will pause, and an error dialog box will appear. If you press the error dialog box's OK button, the Editor window will appear, showing you the line of BASIC code that generated the error.

This is a fairly simple introduction to debugging. You'll probably want more information about debugging as the programs you write get more complicated. For more information, see Debugging.


Saving Your Work

How to save your work

To save your work follow these steps:

  1. Choose Save or Save As... from the File menu.
  2. Save As... allows you to choose a file name and location at which to save.
  3. Save saves your work in the current file. If this is a new program, which you've never saved before, then you'll need to use Save As, since your file doesn't have a name yet.
  4. Verify the syntax is correct. As mentioned before, if you save your work after editing a BASIC routine, the Builder checks that routine to make sure that its syntax is good. If the syntax isn't good, then it will complain; you either save now and deal with the error later, or fix the error before saving.
  5. Choose a location for your file. The file suffix should be .BAS.
  6. For projects you're working on by yourself, it's common to keep files in your local DOCUMENT directory.
  7. If your workgroup is storing files in some common place on a network, you may wish to save your work there, instead.

About your Basic files

When you save your work, it will be saved to a format readable by your text editor. If your program contains any complex data, the complex data will be stored to a separate file, a file with a .RSC suffix.

Your program's .BAS file is viewable with an ordinary text editor program. You can even edit your program with an editor; but be careful. When it comes time to load your program into the Builder, if it contains any syntax errors, you will have a tough time loading your program.


Compiling

Under special circumstances, you may need to build the compiled version of your program.

How to compile a program

To build a compiled version your program, complete the following steps:

  1. Save your program, if you haven't already. You can't build a compiled version of your program if your program doesn't have a file name and location.
  2. Choose Build from the File menu.
  3. In the submenu that appears, choose Compile for.

The name of the compiled module will be the name of your .BAS file, but without the .BAS suffix. For example, if you saved your program in the DOCUMENT directory with the name FUNKY.BAS, then your module will be created in the DOCUMENT directory and will have the name FUNKY.

If you access your compiled program directly through DOS, the file name of the module will be FUNKY.000.