CrystalBall Lite User Input Prompting FAQ

CrystalBall Lite allows for powerful user input requests. Prompting uses several types of inputs in order to get data easily from the user. The following documentation explains the controls, features, and manner to get input from a user to be used with your scripts.

Overview:

Overview

Prompter Example

Prompting uses the PrompterClass to communicate with the user. Controls are added to a prompter and shown to the user. The results are then taken from the prompter and used in the script. Controls are added to a prompter and given a "key" so that more than one control of the same type can be added. The script then gets the value of the control using this key. Add controls, show the prompt, and get values from this class. The following is a brief example, more detailed examples follow including a full example at the bottom of this document:

// Prepare a variable to hold the prompter
Dim prompter As PrompterClass
// Create the prompter
prompter = New PrompterClass

// Add an edit field to the prompter that asks for a name, and starts with Vuma as its text
prompter.AddEditField("EditField", "Enter your name:", "Vuma")

// Shows the prompter to the user and waits for
// the user to click cancel or ok to return back to the script
prompter.Show()

// The prompter knows if the user clicked ok or cancel
If prompter.OkPressed() Then
   // Prepare a variable to hold the edit field's text
   Dim name As String
   
   // Gets the text from the edit field and puts it in the name variable
   name = prompter.GetControlResult("EditField")

   // Outputs a message to the user stating the entered name
   MessageBox("Hello, " + name)
Else
   // If not ok pressed, then the prompter was cancelled
   MessageBox("Why did you cancel me?")
End If
	
Controls:

EditField

An editfield displays a prompt above it and has a text box for entering text.

// Adds an edit field to the prompter with a prompt above the edit field asking "What is your name?" 
// and having "Sandaran" as the default start value
prompter.AddEditFIeld("Name", "What is your name?", "Sandaran")
myVariable = prompter.GetControlResult("Name") // This will return the value of the edit field as a string

CheckBox

A checkBox is a toggleable box that shows a check when selected and empty when not selected. It uses Boolean values to determine if it is checked or not.

// Adds a checkbox to the prompter with a prompt above the edit field asking "Are you happy?" and 
// having the checkbox checked with a check mark by default
prompter.AddCheckBox("checkbox", "Are you happy?", True)
myVariable = prompter.GetControlResult("checkbox") // This will return the value of the checkbox as a boolean

Color

The color picker shows a box filled with the selected color. Clicking the box opens a color picker where the user can pick the color to return. Colors use Red, Green, and Blue components to specify the color. RBScript supplies the RGB method to create a color. Color is also an RBScript class. A color object has red, green, and blue properties that can have a value between 0 and 225.

Dim c As Color // This will allow holding a color in the variable 'c'
c = RGB(100, 150, 225) // Creates a color with red = 100, blue = 150, and green = 225
// Adds a color picker to the prompter with the prompt above it "What color are you?"
prompter.AddColor("color", "What color are you?", c)
c = prompter.GetControlResult("color") // This will return the value of the color picker as a color

A menu lets the user pick from a list of options. Clicking the menu shows the possibilities and picking one sets the shown menu to the picked value.

// Adds a menu with the prompt above it "What is your path?".  The menu is filled with the colon separated 
// values of the string and the default value is set to "Weak"
prompter.AddMenu("menu", "What is your path?", "Strong:Wise:Weak:Logic", "Weak") 
myVariable = prompter.GetControlResult("menu") // This will return the value of the menu as a string

Prompter:

CancelPressed

Returns true if the Cancel button was pressed to close the prompter, False otherwise.

OkPressed

Returns true if the Ok button was pressed to close the prompter, False otherwise.

SetCancelButtonName

Allows setting the Cancel button to show text different than Cancel. Changing the text does not change that the button is the Cancel button for determing which button was pressed.

SetMessage

Sets the message to be displayed at the top of the prompter above all the controls.

SetOkButtonName

Allows setting the Ok button to show text different than Ok. Changing the text does not change that the button is the Ok button for determing which button was pressed.

Show

Shows the prompter to the user. This call blocks the flow of the script until the prompter is closed. The prompter shows modal so that the user must respond to it.

Dim prompter As PrompterClass // Set up the prompter variable for constructing a prompt
prompter = New PrompterClass() // Create the prompter
[Put Custom Prompter Creation Code Here] // Add controls and configure prompter as desired
prompter.Show() // Show the prompter to gather user information
Full Example:

This example sets up a prompter with one of each of the possible types of controls. It then shows the prompt. When the prompt is closed, the fields' data are collected and a combined message outputted to the user. The code below will produce the following image:

Prompter Example
Dim prompter As PrompterClass
prompter = New PrompterClass

// set the explanation message
prompter.SetMessage("Please be truthful")

// add an edit field
prompter.AddEditFIeld("control1", "Enter your name", "Roble")

// add a color picker
prompter.AddColor("control2", "Pick your color", RGB(100, 150, 225))

// add a check box
prompter.AddCheckBox("control3", "Pick your checkbox", True)

// add a menu from a separated string
prompter.AddMenu("control4", "Pick your path", "Strong:Wise:Weak:Logic", "Weak")

// change the ok button to say "sure"
prompter.SetOkButtonName("Sure")

// change the cancel button to say "no way"
prompter.SetCancelButtonName("No Way")

// show the prompter
prompter.Show()

// collect the data and show the user what they entered
Dim output As String
output = ""

If prompter.OkPressed() Then
    output = "OK!" + EndOfLine
Else
    output = "Cancelled" + EndOfLine
End If

// show what was inputted
// notice that when cancelling, the values don't change
Dim v As Variant
v = prompter.GetControlResult("control1")
output = output + "control1 = " + v + EndOfLine


v = prompter.GetControlResult("control2")
Dim c As Color
c = v
output = output + "control2 = " + Str(c.Red) + ", " + Str(c.Green) + ", " + Str(c.Blue) + EndOfLine


v = prompter.GetControlResult("control3")
If v Then
    output = output + "control3 checked" + EndOfLine
Else
    output = output + "control3 not checked" + EndOfLine
End If


v = prompter.GetControlResult("control4")
output = output + "control4 = " + v + EndOfLine


MessageBox(output)