cDialogInputBox class

A cDialogInputBox asks the user for one line of text, checks it against rules and asks again when the text fails, up to three times. The box is the InputBox of the run-time library, and the messages about a failed check are ordinary message boxes: the class has no window of its own.

A cDialogInputBox is made with New: Dim box As New cDialogInputBox. It cannot be made with CreateObject.

The properties Title, Prompt, DefaultValue and Placeholder decide what the box shows, and Validation, MinLength, MaxLength and AllowEmpty what it accepts. ShowDialog shows the box and puts the accepted text into Value. ShowSimple, ShowInteger, ShowNumeric, ShowEmail, ShowPhone and ShowURL set the rules for a kind of text and return the value in one call.

Dim box As New cDialogInputBox

box.Title = "New user"
box.Prompt = "Name of the user?"
box.MinLength = 3
box.MaxLength = 20
box.AllowEmpty = False

If box.ShowDialog() Then
    Debug.Print "Hello, " & box.Value
Else
    Debug.Print "No name given"
End If

How the box works

The text of the box is Prompt, followed by a blank line and (Hint: and Placeholder and ) when a placeholder is set, followed by a blank line and a line on the length when MinLength or MaxLength is above 0: Length: 3 to 8 characters, Length: At least 3 characters or Length: Maximum 8 characters. The edit box holds DefaultValue.

ShowDialog then works like this:

1. When the user cancels, Cancelled is set to True, Value to an empty string, and the result is False.
2. Otherwise ValidateInput checks the text. A text that passes becomes Value, and the result is True.
3. A text that fails is reported in a message box that shows the message of ValidateInput under the title of the box, and the box is shown again with DefaultValue in the edit box, not with the text that failed.
4. The third failure shows the message with Maximum attempts reached. after a blank line. The result is False, Cancelled is True, and Value keeps what it held before the call.

An empty string passes when AllowEmpty is True (the default) and no MinLength is set. The result of the call does not tell the user’s cancelling apart from a refusal; both give False and Cancelled True. The two differ only in Value.

Warning

In version 1.1.0.0 the properties Multiline, PasswordChar, OwnerHwnd and CustomPattern are stored but not used. The box is always a single line, it shows what is typed without masking it, it has no owner window and the owner stays usable while it is open, and the value Custom of Validation accepts any text that is not empty. A program that sets PasswordChar to hide a secret shows the secret on the screen. cDialogPassword masks its entry.

Properties

AllowEmpty

Whether an empty entry is accepted.

Syntax: object.AllowEmpty [ = value ]

value

A Boolean. The default is True.

With False, ValidateInput refuses an empty string with Input cannot be empty. ShowSimple sets it to True, and ShowInteger, ShowNumeric, ShowEmail, ShowPhone and ShowURL to False, and the setting stays.

Dim box As New cDialogInputBox

Debug.Print box.AllowEmpty    ' True
box.AllowEmpty = False
Debug.Print "[" & box.ValidateInput("") & "]"    ' [Input cannot be empty]

Cancelled

Whether the last call to ShowDialog ended without a value, read-only.

Syntax: object.Cancelled As Boolean

False in a new object, and at the start of every call to ShowDialog. True after the user cancelled, and after the third refused entry.

Dim box As New cDialogInputBox

Debug.Print box.Cancelled    ' False

CustomPattern

A pattern for the value Custom of Validation, which the class does not use.

Syntax: object.CustomPattern [ = value ]

value

A String. The default is an empty string.

With Validation set to Custom, ValidateInput never compares the text with the pattern. It refuses only an empty text when a pattern is set, with Input does not match required format; any other text passes. To check a text against a pattern, use ValidateInput as the first check and make the second one in the program, for instance with the tbRegExp package.

Dim box As New cDialogInputBox

box.Validation = InputValidation.Custom
box.CustomPattern = "[0-9]+"
Debug.Print "[" & box.ValidateInput("letters only") & "]"    ' []
Debug.Print "[" & box.ValidateInput("") & "]"                ' [Input does not match required format]

DefaultValue

The text that the edit box holds when it opens.

Syntax: object.DefaultValue [ = value ]

value

A String. The default is an empty string.

The box shows it again after a refused entry. ShowSimple, ShowInteger and ShowNumeric set it from their defaultValue argument, ShowEmail and ShowPhone to an empty string and ShowURL to https://.

Dim box As New cDialogInputBox

box.DefaultValue = "Guest"
Debug.Print box.DefaultValue    ' Guest

MaxLength

The longest text that is accepted.

Syntax: object.MaxLength [ = value ]

value

A Long. 0, the default, means no limit.

ValidateInput refuses a longer text with Input must not exceed N characters. The edit box itself does not stop the typing.

Dim box As New cDialogInputBox

box.MaxLength = 5
Debug.Print "[" & box.ValidateInput("abcdef") & "]"    ' [Input must not exceed 5 characters]
Debug.Print "[" & box.ValidateInput("abcde") & "]"     ' []

MinLength

The shortest text that is accepted.

Syntax: object.MinLength [ = value ]

value

A Long. 0, the default, means no minimum.

ValidateInput refuses a shorter text, an empty one too, with Input must be at least N characters. This check comes first, so an empty text with a minimum gets this message and not the one of AllowEmpty.

Dim box As New cDialogInputBox

box.MinLength = 3
Debug.Print "[" & box.ValidateInput("ab") & "]"    ' [Input must be at least 3 characters]
Debug.Print "[" & box.ValidateInput("abc") & "]"   ' []

Multiline

A property that has no effect.

Syntax: object.Multiline [ = value ]

value

A Boolean. The default is False.

The value is stored. The box has one line whatever it is; see the warning above.

Dim box As New cDialogInputBox

Debug.Print box.Multiline    ' False

OwnerHwnd

A property that has no effect.

Syntax: object.OwnerHwnd [ = value ]

value

A LongPtr. The default is 0.

The value is stored. The box has no owner whatever it is; see the warning above. Reset sets it to 0.

Dim box As New cDialogInputBox

Debug.Print box.OwnerHwnd    ' 0

PasswordChar

A property that has no effect.

Syntax: object.PasswordChar [ = value ]

value

A String. The default is an empty string.

The value is stored. The box does not mask the text, whatever it is; see the warning above.

Dim box As New cDialogInputBox

box.PasswordChar = "*"
Debug.Print box.PasswordChar    ' *

Placeholder

A hint that the box shows under the prompt.

Syntax: object.Placeholder [ = value ]

value

A String. The default is an empty string.

The hint is not shown in the edit box. When it is not empty, the prompt gets the line (Hint: followed by the placeholder and ). ShowEmail, ShowPhone and ShowURL set it to a sample value, and it stays set for the later calls of other methods, ShowSimple included. Set it to an empty string to remove the hint.

Dim box As New cDialogInputBox

box.Placeholder = "like ABC"
Debug.Print box.Placeholder    ' like ABC

Prompt

The text above the edit box.

Syntax: object.Prompt [ = value ]

value

A String. The default is Please enter a value:.

Dim box As New cDialogInputBox

Debug.Print box.Prompt    ' Please enter a value:

Title

The title of the box and of the messages about a refused entry.

Syntax: object.Title [ = value ]

value

A String. The default is Input.

Dim box As New cDialogInputBox

Debug.Print box.Title    ' Input

Validation

The kind of text that is accepted.

Syntax: object.Validation [ = value ]

value

An InputValidation member. The default is None.

ValidateInput applies the rule after the checks of MinLength, MaxLength and AllowEmpty. The Show* methods other than ShowDialog set it, and it stays set.

Dim box As New cDialogInputBox

Debug.Print box.Validation = InputValidation.None    ' True
box.Validation = InputValidation.Email
Debug.Print box.Validation                           ' 5

Value

The text that ShowDialog accepted last, read-only.

Syntax: object.Value As String

An empty string in a new object, after a cancel, and after Reset. A call that ends with three refusals leaves it as it was.

Dim box As New cDialogInputBox

Debug.Print Len(box.Value)    ' 0

Methods

GetValueAsInteger

Returns Value as a Long.

Syntax: object.GetValueAsInteger ( ) As Long

Returns 0 when Value is not a number, and otherwise the CLng of it, which rounds: 3.5 gives 4. A value that a Long cannot hold raises error 6.

Dim box As New cDialogInputBox

box.Validation = InputValidation.Numeric
If box.ShowDialog() Then Debug.Print box.GetValueAsInteger()

GetValueAsNumber

Returns Value as a Double.

Syntax: object.GetValueAsNumber ( ) As Double

Returns 0 when Value is not a number, and otherwise the CDbl of it.

Dim box As New cDialogInputBox

Debug.Print box.GetValueAsNumber()    ' 0

Reset

Restores every property to its starting value.

Syntax: object.Reset

Sets Title to Input, Prompt to Please enter a value:, Value, DefaultValue, Placeholder, CustomPattern and PasswordChar to empty strings, MinLength, MaxLength and OwnerHwnd to 0, Validation to None, AllowEmpty to True and Multiline and Cancelled to False.

Dim box As New cDialogInputBox

box.Title = "Age"
box.Validation = InputValidation.Integer
box.Reset
Debug.Print box.Title                                  ' Input
Debug.Print box.Validation = InputValidation.None      ' True

ShowDialog

Shows the box and checks the entry.

Syntax: object.ShowDialog ( ) As Boolean

Returns True when the user entered a text that passed the checks, and then Value holds it. Returns False when the user cancelled or the third attempt failed, with Cancelled True. How the box works lists the steps.

Dim box As New cDialogInputBox

box.Title = "Product code"
box.Prompt = "Enter the product code:"
box.Validation = InputValidation.AlphaNumeric
box.MinLength = 4
box.MaxLength = 8
box.DefaultValue = "AB12"

If box.ShowDialog() Then
    Debug.Print "Code: " & box.Value
Else
    Debug.Print "Cancelled"
End If

ShowEmail

Asks for an email address.

Syntax: object.ShowEmail ( prompt [ , title ] ) As String

prompt

required The text above the edit box.

title

optional The title. The default is Enter Email.

Sets Prompt, Title, DefaultValue (empty), Validation (Email), AllowEmpty (False) and Placeholder (example@domain.com), calls ShowDialog and returns Value. Returns an empty string when ShowDialog returned False. An address passes when it has exactly one @ and at least one . anywhere.

Dim box As New cDialogInputBox
Dim address As String

address = box.ShowEmail("Where should the report be sent?")
If Not box.Cancelled Then Debug.Print "Send to " & address

ShowInteger

Asks for a whole number.

Syntax: object.ShowInteger ( prompt [ , title [ , defaultValue ] ] ) As Long

prompt

required The text above the edit box.

title

optional The title. The default is Enter Integer.

defaultValue

optional The text in the edit box. The default is an empty string.

Sets the three properties that correspond to the arguments, Validation (Integer) and AllowEmpty (False), calls ShowDialog and returns Value as a Long. A cancelled box returns 0, which is also a possible entry, so test Cancelled. The text 1e3 passes and returns 1000.

Note

A text that passes the check but that a Long cannot hold, such as 99999999999, raises error 6 after the box has closed. Value then holds the text.

Dim box As New cDialogInputBox
Dim copies As Long

copies = box.ShowInteger("How many copies?", "Print", "1")
If Not box.Cancelled Then Debug.Print copies & " copies"

ShowNumeric

Asks for a number.

Syntax: object.ShowNumeric ( prompt [ , title [ , defaultValue ] ] ) As Double

prompt

required The text above the edit box.

title

optional The title. The default is Enter Number.

defaultValue

optional The text in the edit box. The default is an empty string.

As ShowInteger, with Validation Numeric and a Double as the result: 3.5 returns 3.5. A cancelled box returns 0, so test Cancelled.

Dim box As New cDialogInputBox
Dim price As Double

price = box.ShowNumeric("Price?", "New article", "9.99")
If Not box.Cancelled Then Debug.Print price

ShowPhone

Asks for a telephone number.

Syntax: object.ShowPhone ( prompt [ , title ] ) As String

prompt

required The text above the edit box.

title

optional The title. The default is Enter Phone.

Sets Prompt, Title, DefaultValue (empty), Validation (Phone), AllowEmpty (False) and Placeholder (+1 (555) 123-4567), calls ShowDialog and returns Value, or an empty string for False. Digits, spaces and -, (, ), + and . are accepted.

Dim box As New cDialogInputBox
Dim number As String

number = box.ShowPhone("Telephone number?")
If Not box.Cancelled Then Debug.Print number

ShowSimple

Asks for a text without rules.

Syntax: object.ShowSimple ( prompt [ , title [ , defaultValue ] ] ) As String

prompt

required The text above the edit box.

title

optional The title. The default is Input.

defaultValue

optional The text in the edit box. The default is an empty string.

Sets the three properties that correspond to the arguments, sets Validation to None, AllowEmpty to True and MinLength and MaxLength to 0, calls ShowDialog and returns Value, or an empty string for False. An empty result does not tell a cancel from an empty entry: test Cancelled. A Placeholder that an earlier call set is still shown.

Dim box As New cDialogInputBox
Dim answer As String

answer = box.ShowSimple("Your name?", "Welcome", "Guest")
If Not box.Cancelled Then Debug.Print "Hello, " & answer

ShowURL

Asks for an address on the web.

Syntax: object.ShowURL ( prompt [ , title ] ) As String

prompt

required The text above the edit box.

title

optional The title. The default is Enter URL.

Sets Prompt, Title, DefaultValue (https://), Validation (URL), AllowEmpty (False) and Placeholder (https://example.com), calls ShowDialog and returns Value, or an empty string for False. A text passes when it contains ://, so the offered https:// passes unchanged.

Dim box As New cDialogInputBox
Dim address As String

address = box.ShowURL("Address of the site?")
If Not box.Cancelled Then Debug.Print address

ValidateInput

Checks a text against the rules and returns the reason for a refusal.

Syntax: object.ValidateInput ( input ) As String

input

required The text to check.

Returns an empty string when the text passes, and otherwise the message that ShowDialog shows. The checks run in this order, and the first that fails decides:

Check	Message
Fewer characters than MinLength	Input must be at least N characters
More characters than MaxLength (above 0)	Input must not exceed N characters
Empty, with AllowEmpty False	Input cannot be empty
Numeric: IsNumeric is False	Input must be a valid number
Integer: IsNumeric is False, or the text has a . or a ,	Input must be a valid integer
Alpha: a character that is not a letter A to Z or a space	Input must contain only letters
AlphaNumeric: a character that is not a letter A to Z, a digit, a space or _	Input must contain only letters and numbers
Email: no @, no ., or more than one @	Input must be a valid email address
Phone: a character that is not a digit, a space, -, (, ), + or .	Input must be a valid phone number
URL: no ://	Input must be a valid URL (e.g., https://example.com)
Custom: empty, with a CustomPattern set	Input does not match required format

A rule of Numeric to URL is not applied to an empty text, which passes it. The method changes nothing in the object.

Dim box As New cDialogInputBox

box.Validation = InputValidation.Integer
Debug.Print "[" & box.ValidateInput("42") & "]"     ' []
Debug.Print "[" & box.ValidateInput("4.2") & "]"    ' [Input must be a valid integer]
Debug.Print "[" & box.ValidateInput("abc") & "]"    ' [Input must be a valid integer]

box.Validation = InputValidation.Email
Debug.Print "[" & box.ValidateInput("ann@example.com") & "]"    ' []
Debug.Print "[" & box.ValidateInput("ann@@example.com") & "]"   ' [Input must be a valid email address]

box.Validation = InputValidation.AlphaNumeric
Debug.Print "[" & box.ValidateInput("Item_42") & "]"    ' []
Debug.Print "[" & box.ValidateInput("Item-42") & "]"    ' [Input must contain only letters and numbers]

Enumerations

InputValidation

The kinds of text for Validation.

Member	Value	Accepts
None	0	Any text
Numeric	1	What IsNumeric accepts
Integer	2	What IsNumeric accepts, without . and ,
Alpha	3	Letters A to Z and spaces
AlphaNumeric	4	Letters A to Z, digits, spaces and _
Email	5	Text with one @ and a .
Phone	6	Digits, spaces and -, (, ), +, .
URL	7	Text that contains ://
Custom	99	Any text; see CustomPattern

Example

This example asks for a quantity between 1 and 99 and repeats the question until the user has entered one or cancelled.

Dim box As New cDialogInputBox
Dim quantity As Long

box.Title = "Order"
box.Prompt = "Quantity (1 to 99)?"
box.Validation = InputValidation.Integer
box.AllowEmpty = False
box.MaxLength = 2
box.DefaultValue = "1"

If box.ShowDialog() Then
    quantity = box.GetValueAsInteger()
    If quantity >= 1 Then Debug.Print "Ordering " & quantity
Else
    Debug.Print "No order"
End If

See Also

• cDialogPassword class – asks for a password with a masked entry
• cDialogDateTime class – asks for a date and a time
• TBMANLIB_Dialog package – overview