Tutorial 01: A Simple Program

February 01, 2010

© NSB Corporation. All rights reserved.

Contributed by Tom Newman, Mission Peak Designs

Purpose

The purpose of this tutorial is to demonstrate how a simple program is created using NS Basic/CE. You should have NS Basic/CE installed before beginning this tutorial.

Description of the Program

The program to be developed will display a form with a button on it. When the user taps the button, the program responds with the message "Hello--Welcome to NS Basic/CE"

Program Development

1. Startup

Start NS Basic/CE from the Start menu.
At the initial screen select Standard in the New Project dialog box and click OK

2. Modify Form Properties

You should now see a blank screen with the title "Form1"
Select the form in the Project Explorer by clicking on it.
In Properties, change Name to "Hello"

3. Add a button to the form

Select the CommandButton object in the ToolBox (blank rectangle box)
Move the cursor to the desired location on the Form screen
Click the left mouse button to place the button object on the form

Change the button's text:

Click on the button to select it
In the Properties window, change Caption to "Tap Here"

Resize the button:

Position the mouse cursor over the button and notice the resize marker around the button
Press the left mouse button and drag one of the resize markers to change the size in that direction
Release the left mouse button when the size is correct

Relocate the button on the screen:

Select the button with the left mouse button
Position the mouse cursor to the middle of the button
Press the left mouse button and drag the button to the desired position on the form
Release the left mouse button when in the proper position

5. Add commands to be executed when the button is tapped

Double click on the button
A code window will appear with some code statements already supplied for you
Position the cursor to the line below the SUB statement

Enter the following line:

  MsgBox "Hello -- Welcome to NS Basic/CE",0,"NS Basic"

At the top of the code window enter the following lines:
```
  Option Explicit
  ShowOKButton TRUE 
```

The last two lines are not required but recommended in all your programs. Option Explicit ensures that all variables are defined first (using the DIM statement). ShowOKButton places an OK button on the output screen of CE devices so the program can be closed (the default X button only minimizes the program).

Option Explicit
ShowOKButton True    ' Used for /CE, no-op for desktop
Sub CommandButton1_Click
   MsgBox "Hello -- Welcome to NS Basic/CE",0,"NS Basic"
End Sub

Close the code window.

6. Save the Project

Select "File" from the top main menu
Select "Save project" and save your program as HelloPgm
This will save your project in the selected directory as HelloPgm.nsb and HelloPgm.nsp
All form definitions, form objects, all code, and other project info are saved into the one project file.

Testing The Project

Now we are ready to test the project. You can either download and run the program on a CE device or on the Microsoft Microsoft Device Emulator. Please refer to the instructions in Tech Note 23: Using the Microsoft Device Emulator, for information about installing and running the Microsoft Device Emulator. If you plan to run on an actual device, skip this step.

Starting the Microsoft Device Emulator

If you plan to test the program on the Microsoft Device Emulator it needs to be installed and running before it can be used.

Install the Microsoft Device Emulator (see Tech Note 23)
Install and verify ActiveSync is running
Start the Microsoft Device Emulator from the Start->Programs menu
Start the Device Emulator Manager from Start->Programs menu
In the Device Emulator Manager, right click on the device under the Others line (click Refresh if empty)
Click on Cradle from the drop-down menu
ActiveSync should now connect to the Microsoft Device Emulator

Running the Program

Start ActiveSync if it's not already running
Select Start from the Run menu.

Note: By default, the project is saved every time the program is run. As a shortcut you can press F5 to save and start the program.

Any errors will appear in a message box on the CE device/emulator. The message box displays the error and line number where the error occurred. Errors must be corrected and Start repeated until there are no more errors.

Congratulations !! You have now written your first NS Basic/CE program.

Extending the Tutorial

Let's explore some further features of NS Basic/CE. We'll do this by modifying your first program to be more complicated. Exit NS Basic/CE by choosing File and Exit from the menu.

Restart

Restart NS Basic/CE from the Start menu.
The first screen (Open) allows you to start a new project or open an existing project.
Click on Recent; select HelloPgm.nsb; and click Open.
The project will load into the IDE.

Revision: Change the Message

Double click on the "Tap Here" button to bring up the code window.
Enter the following code after the SUB statement:

	Dim s
	s = date

Change the MsgBox statement to:

  	MsgBox "Today is " & s,0,"NS Basic"

Close the code window.
Press F5 (Start) to test using the Microsoft Device Emulator or download to a CE device.
When run, the message displayed should be "Today is dd/mm/yy" (today's date replaces the Hello message).

Revision: Add Code at Program Startup

This change will add a message box that's displayed when the program first starts.

Make the Code Window visible
Before the SUB line, enter this line:

  	msgbox "HelloPgm will continue when you tap on OK",0,"NS Basic"

Close the code window.
Press F5 (Start) to download and test the change.
When the program starts the message box is displayed and waits until the user taps the OK button

Revision: Add Code at Form Display Time

This change will add a label which shows the time-of-day. Another button will be added to update the label with the latest time.

Add a field where the Time of Day will be shown:

Select label object in the Toolbox ("A" icon)
Place it on the form and select it
In the Properties window, change the Name to "lblTimeField"
In the Properties window, change the Caption to "Time Of Day"
Resize the label as needed to hold the time

Add a button to refresh the Time of Day field:

Select the CommandButton object in the Toolbox (blank rectangle box)
Place it on the form and select it
In the Properties window, change the Name to "cmdRefreshTime"
In the Properties window, change the Caption to "Refresh Time"
Resize and reposition the button on the form

Note: You can press F5 (Start) after you added or changed a visual design and before you add the code to support the visual changes. The program will download and execute and the new objects will be displayed (but not useable). This can be useful for prototyping a new design or getting the visual design right before adding the code.

Add code to fill in the time-of-day when the form displays

Double click on an empty area of the form
The Code Window will open with the cursor in the Hello_Load subroutine
Enter the following code after the SUB line:

	lblTimeField.Caption = Time

Make the form visible again and double click on the "Refresh Time" button
The Code Window will open with the cursor in the cmdRefreshTime_Click subroutine
Enter the following code after the SUB line:

	lblTimeField.Caption = Time

Your code should look like the following:

Option Explicit
ShowOKButton True    ' Used for /CE, no-op for desktop

MsgBox "HelloPgm will continue when you tap on OK",0,"NS Basic"

Sub CommandButton1_Click
   Dim s
   s = Date
   MsgBox "Today is " & s,0,"NS Basic"
End Sub

Sub Hello_Load
   lblTimeField.Caption = Time
End Sub

Sub cmdRefreshTime_Click
   lblTimeField.Caption = Time
End Sub

Close the code window.
Press F5 (Start) to download and test the change.
The above code executes when the form loads and when the user presses the Refresh Time button. The Time() function returns the current time and displays it in the Time of Day field on the form.