Tutorial 05: Using a Function in a Module

April 17, 2008

© NSB Corporation. All rights reserved.

Contributed by Tom Newman, Mission Peak Designs

Introduction

The purpose of this tutorial is to demonstrate using NS Basic/CE to create a function in a stand-alone module that can be accessed from any point in your application. You can create modules of code that have been tested and can be reused from one project to the next. The advantage of creating a separate module is that it can then easily be added to new projects. To add an existing module, click on the Project menu, and then click on Add Existing Module.

You should have completed Tutorial #1 before beginning this tutorial. It's also a good idea to review the previous tutorials for information about creating forms, controls, and testing your project.

This program will convert a temperature value to Fahrenheit. The user enters a value in a text box and selects the unit (Celsius, Kelvin, or Rankine). Pressing the Convert button calls the Convert function located in an external module to perform the conversion. The answer is displayed in a text box.

Setting up the Form

Before we create the new function, we first need to create some controls to let us select the information the function will need.

Start a new "Standard" project and save it as TempConversion.nsb.

Add a text box for entering the value

Add a TextBox on the form
In the Properties window, change Name to "txtValue"
In the Properties window, delete the value of Text
Expand and reposition the TextBox on the form

Add a label above the value text box

Add a Label on the form after the previous text box
In the Properties window, change Name to "lblValue"
In the Properties window, change Caption to "Enter Value"
Expand and reposition the Label on the form

Add a combo box for selecting conversion units

Add a ComboBox on the form
In the Properties window, change Name to "cboUnits"
In the Properties window, set ExpandedHeight to 100 (this determines the how much the combo box will expand)
Expand and reposition the ComboBox on the form

Add a label above the units combo box

Add a Label on the form above the combo box
In the Properties window, change Name to "lblUnits"
In the Properties window, change Caption to "Units"
Expand and reposition the Label on the form

Add a text box for displaying the conversion answer

Add a TextBox on the form
In the Properties window, change Name to "txtFahrenheit"
In the Properties window, delete the value of Text
In the Properties window, change the value of Locked to True (this makes the field read-only)
Expand and reposition the TextBox on the form

Add a label above the conversion answer text box

Add a Label on the form above the previous text box
In the Properties window, change Name to "lblFahrenheit"
In the Properties window, change Caption to "Value in Fahrenheit"
Expand and reposition the Label on the form

Add a button to start the conversion

Add a CommandButton on the form
In the Properties window, change Name to "cmdButton"
In the Properties window, change Caption to "Convert"
Expand and reposition the Label on the form

Note: The Name of Labels do not need to be renamed but I find it helps with the design if the label Name matches the label Caption. Otherwise your labels will be called Label1, Label2, etc., which makes it more difficult to determine the location of the label on the form.

Press F5 to save and execute the program. Your form should look like this:

Adding Code to the Form

Now that we have our form, we can begin to add code. In the Project Explorer pane, double click on an empty area on the form. In the code window add the following lines between the Sub Form1_Load and End Sub lines:

    cboUnits.AddItem "Celsius",0
    cboUnits.AddItem "Kelvin",1
    cboUnits.AddItem "Rankine",2
    cboUnits.ListIndex = 0

The above code initializes our Combo box list and sets Celsius as the selected item. This code will execute after our form and controls have loaded

Add these lines at the top of the Code Window:

    Option Explicit
    ShowOKButton True

See the NS Basic manual if you need more information on what these commands do.

Navigate back to the form and double click on the Convert button to open it's code window. Add the following lines between the Sub cmdConvert_Click and End Sub lines:

    Dim result
    result = Convert(CSng(txtValue.text), cboUnits.ListIndex)
    txtFahrenheit.Text = CStr(result)

These lines creates an variable that stores the answer when we call the Convert function (located in an external module). The Convert function is called with the number entered by the user in the Value text box after it's converted into a single precision number. The Units index is retrieved from the Units combo box. This will be either 0, 1, or 2 depending on which unit was selected (Celsius, Kelvin, or Rankine). After the Convert function returns, the value is placed in the Fahrenheit text box as a string.

Many programmers actually treat the function name as a variable, placing it directly into the equation with it's necessary arguments. The program will perform the function, calculate the results and place it into the equation as it is calculating the answer.

Your Code Window should look like this:

Option Explicit
ShowOKButton True

Sub Form1_Load
   cboUnits.AddItem "Celsius",0
   cboUnits.AddItem "Kelvin",1
   cboUnits.AddItem "Rankine",2
   cboUnits.ListIndex = 0
End Sub

Sub cmdConvert_Click
   Dim result
   result = Convert(CSng(txtValue.text), cboUnits.ListIndex)
   txtFahrenheit.Text = CStr(result)
End Sub

Adding a New Module

To add a module to the project click on "Project" in IDE menu. Select "Add New Module".

This will open a new Code Window and a new module also appears in the Project Explorer.

Function Basics

In the new code window we will add the following Function to the module:

	Function Convert (Value, Units)

This line defines a function with the name Convert. It is helpful to think of this as also creating a variable named Convert. In our example it also creates two other variables, Value and Units. These variables receive the values from the arguments in the calling statement. You can have as many additional values here as needed provided you supply the values in your calling statement. The function always assigns the values to these variables in the order they are listed. A function can only return one value (if you need to return more than one value you should consider using global variables instead).

So in our example using the lines of code from the Convert button, Value is assigned the first parameter, and Units is assigned to the second parameter.

Add Code to the Function

Now that we have the values, we need to add some code to calculate the converted temperature. Add the following lines to the code window:

    Function Convert(Value, Units)
		Dim ConvtUnits

		' Units is the number from the combo box that tells us which formula to use
		Select Case Units
   
		Case 0
			' This formula for Celsius to Fahrenheit
			ConvtUnits  = (Value * 1.8) + 32
        
		Case 1
			' This formula for Kelvin to Fahrenheit
			ConvtUnits = (Value * 1.8) - 459.67
        
		Case 2
			' This is formula for Rankine to Fahrenheit
			ConvtUnits = Value - 459.67
           
		End Select

		Convert = ConvtUnits    ' Assign the return value

	End Function

The final code window then should look like this.

Save your project. First NS Basic will ask you to give a name to the function module. Give it a descriptive name like TempConv_mod.bas. You can use this function in other projects by adding it to the project. To add an existing module select "Project" from the IDE menu, and select "Add Existing Module" from the drop down menu. The modules are stored by default in the projects folder of NS Basic with .bas extensions.

Press F5 to save and start your program. You should be able to select a temperature scale and value and get the correct Fahrenheit conversion when you tap the Convert button.