Input Required

Last time around we looked at how to use message boxes to send the user informative messages and get simple yes/no input from the user. If you need information such as a quantity, part number, or a name; an input box may be more suitable to the task at hand. Similar to a message box, an input box is a predefined input form provided by the host environment (there is a version provided by the NXOpen API and a version provided by Windows) which we can invoke with a function call. The input box does have its limitations; multiple inputs would be better handled by a custom user form, and the input box won't win any awards for style or usability. That said, the input box does have its uses, even if only to make the programmer's life a bit easier during the prototyping and testing stage.

The NXOpen API supplies a few different methods to get user input, let's take a look at getting a string input. The .GetInputString method has three overloaded versions, you can pass it one, two, or three string arguments which will be interpreted as the prompt, title text, and initial text respectively. A short example is below:

Option Strict Off
Imports System
Imports NXOpen
Imports NXOpenUI

Module Module1

Sub Main()

Dim theSession As Session = Session.GetSession()
Dim workPart As Part = theSession.Parts.Work
Dim theUISession As UI = UI.GetUI
Dim answer As String = ""

'input box: prompt only
answer = NXInputBox.GetInputString("prompt only")

'input box: prompt and title
answer = NXInputBox.GetInputString("prompt", "title bar caption")

'input box: prompt, title, and initial text
answer = NXInputBox.GetInputString("prompt", "title bar caption", "initial text")
'echo the input
MsgBox("answer: """ & answer & """")

End Sub

Public Function GetUnloadOption(ByVal dummy As String) As Integer

'Unloads the image when the NX session terminates
GetUnloadOption = NXOpen.Session.LibraryUnloadOption.AtTermination

End Function

End Module

As you can see from the example, the NX input box shows the NX icon in the top left corner but otherwise looks like a generic window. Other than a few text strings, you have no control over the style, location, or functionality of the form. Given the single purpose and spartan design of the input box, the user is very limited in their interactions with it. The user may enter a value or not, then press OK or Cancel (ok, the user could also wait around for the input box to make the next move, but they would be in for a very long wait). The first item of interest to the programmer is: what button did the user press? If the user presses cancel, an empty string, "", is returned. When OK is pressed, the input from the user is returned. User input can take on two basic forms, either: 1) a string value, or 2) an empty string, "". Wait a minute, both OK and Cancel can return an empty string? Unfortunately, yes. If there is no input in the box (either the user presses OK before entering a string and no initial text was supplied, or the user deletes the initial text) an empty string will be returned when the user presses OK. So how do we differentiate between a user pressing cancel to get out of the program and one that accidentally pressed OK before entering input? As of this writing, we can only read the user's input, not the user's mind and intentions, but using the initial text option will help reduce the number of "false empty strings". If there is a commonly used response to the input you require, pass that as the initial text. The initial text will all be selected when the input box is shown; as soon as the user starts typing, the new input will overwrite the initial text. In other words, usability of initial text is pretty good, the user does not need to delete the default response before typing in a new one.

In the following code we take advantage of the input text to differentiate between the user pressing cancel or the user absent-mindedly pressing OK before entering input. Let's assume there is no obvious default choice to give the user, so for the default text we'll use a single space character. Unless you were looking for it, you probably wouldn't even notice it was there. We'll use a Do loop to continue prompting for input as long as the user enters invalid input (in this example, invalid input is any number of space characters) and presses OK. Within the loop, we check for the empty string, which indicates the user pressed cancel, and exit the journal when found.

Option Strict Off
Imports System
Imports NXOpen
Imports NXOpenUI

Module Module1

Sub Main()

Dim theSession As Session = Session.GetSession()
Dim workPart As Part = theSession.Parts.Work
Dim theUISession As UI = UI.GetUI
Dim answer As String = ""

'loop until there is valid input
Do
answer = NXInputBox.GetInputString("Enter your name", "Name?", " ")
'if cancel is pressed, exit sub
If answer = "" Then Exit Sub
Loop Until answer.Trim.Length > 0

theUISession.NXMessageBox.Show("Greetings", NXMessageBox.DialogType.Information, "Hello, " & answer)

End Sub

Public Function GetUnloadOption(ByVal dummy As String) As Integer

'Unloads the image when the NX session terminates
GetUnloadOption = NXOpen.Session.LibraryUnloadOption.AtTermination

End Function

End Module

The final NXInput box sample uses .NET's TryParse methods to validate numerical input. This example uses a simple version of TryParse, there is an overloaded version that offers more control over what input gets converted. This gets into culture specific formatting and is beyond the scope of this introductory article, but if you are interested, a good place to start is MSDN.

[vbnet]
Option Strict Off
Imports System
Imports NXOpen
Imports NXOpenUI

Module Module1

Sub Main()

Dim theSession As Session = Session.GetSession()
Dim workPart As Part = theSession.Parts.Work
Dim theUISession As UI = UI.GetUI
Dim answer As String = ""
Dim myInt As Integer
Dim myNumber As Double

answer = NXInputBox.GetInputString("prompt", "title bar caption", "initial text")
MsgBox("answer: """ & answer & """")

'loop until there is valid input
Do
answer = NXInputBox.GetInputString("Enter your name", "Name?", " ")
'if cancel is pressed, exit sub
If answer = "" Then Exit Sub
Loop Until answer.Trim.Length > 0

theUISession.NXMessageBox.Show("Greetings", NXMessageBox.DialogType.Information, "Hello, " & answer)

'loop until there is valid input
Do
answer = NXInputBox.GetInputString("Enter an integer", "Number of copies?", " ")
'if cancel is pressed, exit sub
If answer = "" Then Exit Sub
Loop Until Integer.TryParse(answer, myInt)

theUISession.NXMessageBox.Show("Valid input", NXMessageBox.DialogType.Information, "The input was successfully parsed as: " & myInt.ToString)

'loop until there is valid input
Do
answer = NXInputBox.GetInputString("Enter a number", "Length of line?", " ")
'if cancel is pressed, exit sub
If answer = "" Then Exit Sub
Loop Until Double.TryParse(answer, myNumber)

theUISession.NXMessageBox.Show("Valid input", NXMessageBox.DialogType.Information, "The input was successfully parsed as: " & myNumber.ToString)

End Sub

Public Function GetUnloadOption(ByVal dummy As String) As Integer

'Unloads the image when the NX session terminates
GetUnloadOption = NXOpen.Session.LibraryUnloadOption.AtTermination

End Function

End Module
[/vbnet]

Here is some code that uses the .NET input box instead of the NX one. The look of the input box is largely the same (there may be differences based on the version of Windows you have installed), the main difference is no NX icon appears on the input box. Take note of the added Imports System.Windows.Forms statement at the beginning of the code, this allows you to call the InputBox function directly; otherwise each call would look something like: System.Windows.Forms.InputBox(<parameters>). Control freaks take note: the second input box call uses optional parameters to specify where on the screen the input box should appear. The coordinates specified designate where the top left corner of the input box will be drawn. I've also included an example of how to determine the primary screen's resolution, so if you do want to specify the input box location you can keep it within bounds. Other than those minor differences, the look, feel, and response of the input boxes is the same; the one you choose will be based on personal preference.

[vbnet]
Option Strict Off
Imports System
Imports System.Windows.Forms
Imports NXOpen
Imports NXOpenUI

Module Module2

Sub Main()

Dim theSession As Session = Session.GetSession()
Dim workPart As Part = theSession.Parts.Work
Dim theUISession As UI = UI.GetUI
Dim answer As String = ""

'plain .NET input box
answer = InputBox("prompt", "title bar caption", "initial text")
MsgBox("answer: """ & answer & """")

Dim intX As Integer = Screen.PrimaryScreen.Bounds.Width
Dim intY As Integer = Screen.PrimaryScreen.Bounds.Height
answer = InputBox("This input box has been positioned at: (50,10)", "Input box with defined position", " ", 50, 10)

End Sub

Public Function GetUnloadOption(ByVal dummy As String) As Integer

'Unloads the image when the NX session terminates
GetUnloadOption = NXOpen.Session.LibraryUnloadOption.AtTermination

End Function

End Module
[/vbnet]

Summary

The input box can be used to get simple input from the user, or it can be used by the programmer to test different input before the user input form is created. Either the NX or .NET input box functions can be used, both are similar in look and features.