# Interaction module

The **Interaction** module groups together standalone procedures for everything that happens at the edges of a program --- talking to the user, branching on a value, launching another process, reading the environment or the registry, and creating, calling into, or raising events on COM objects.

## Asking the user something

[**MsgBox**](/tB/Modules/Interaction/MsgBox.md) shows a modal dialog with a message, an icon, and a chosen set of buttons; it returns a [**VbMsgBoxResult**](/tB/Modules/Constants/VbMsgBoxResult.md) value identifying the button that was clicked. [**InputBox**](/tB/Modules/Interaction/InputBox.md) shows a similar dialog with a text-entry field and returns the string the user typed (or an empty string if the user cancels). [**Beep**](/tB/Modules/Interaction/Beep.md) sounds the system alert tone --- useful as an audible cue when a long-running operation finishes.

```tb check_build
Dim Answer As VbMsgBoxResult
Answer = MsgBox("Save changes before closing?", vbYesNoCancel + vbQuestion, "Confirm")
```

## Choosing a value

The module offers four ways to pick one of several values inline:

- [**If**](/tB/Modules/Interaction/If.md) is the short-circuiting inline conditional -- a twinBASIC addition. Only the branch matching the condition is evaluated, so `If(Divisor <> 0, 100 / Divisor, "n/a")` is safe even when *Divisor* is zero.
- [**IIf**](/tB/Modules/Interaction/IIf.md) is the historical VBA inline conditional. Both *truepart* and *falsepart* are always evaluated, so it cannot guard against errors in the unused branch.
- [**Choose**](/tB/Modules/Interaction/Choose.md) returns the *index*-th item from a list of values -- a one-based equivalent of array indexing for a fixed-length argument list.
- [**Switch**](/tB/Modules/Interaction/Switch.md) iterates over pairs of *(condition, value)* arguments and returns the value paired with the first **True** condition -- a compact stand-in for an **If...ElseIf** ladder.

```tb check_build
Dim Age As Long
Dim Status As Variant
Status = Switch(Age < 13, "Child", _
                Age < 20, "Teenager", _
                Age < 65, "Adult", _
                True,     "Senior")
```

[**Partition**](/tB/Modules/Interaction/Partition.md) is a related utility: it returns a printable label identifying which of a series of equal-width numeric ranges a value falls into.

## Launching and steering other processes

[**Shell**](/tB/Modules/Interaction/Shell.md) starts another program asynchronously and returns the new process's task ID; [**AppActivate**](/tB/Modules/Interaction/AppActivate.md) brings an already-running application's window to the foreground, by title or by task ID. [**SendKeys**](/tB/Modules/Interaction/SendKeys.md) feeds keystrokes to whichever window currently has focus, and [**DoEvents**](/tB/Modules/Interaction/DoEvents.md) yields control back to the message loop so paint, input, and timer events can be dispatched in the middle of a long computation.

## The environment and the command line

[**Command$**](/tB/Modules/Interaction/Command.md) and [**Command**](/tB/Modules/Interaction/Command.md) return the command-line arguments passed to the program when it was started. [**Environ$**](/tB/Modules/Interaction/Environ.md) and [**Environ**](/tB/Modules/Interaction/Environ.md) return the value of a process environment variable, looked up either by name or by 1-based index in the environment block.

## Per-user application settings

The registry-setting helpers read and write per-user values under `HKEY_CURRENT_USER\Software\VB and VBA Program Settings`, mirroring the storage convention used by VB6. [**SaveSetting**](/tB/Modules/Interaction/SaveSetting.md) writes a single key, [**GetSetting**](/tB/Modules/Interaction/GetSetting.md) reads it back (with an optional default for missing keys), [**GetAllSettings**](/tB/Modules/Interaction/GetAllSettings.md) returns every key-value pair in a section as a two-column **Variant** array, and [**DeleteSetting**](/tB/Modules/Interaction/DeleteSetting.md) removes a key, an entire section, or every setting belonging to an application.

```tb check_build
SaveSetting    "MyApp", "Window", "Maximised", "True"
Debug.Print GetSetting("MyApp", "Window", "Maximised", "False")     ' "True"
DeleteSetting  "MyApp", "Window", "Maximised"
```

## COM objects and dynamic dispatch

[**CreateObject**](/tB/Modules/Interaction/CreateObject.md) instantiates a new COM/Automation object given its ProgID or CLSID --- optionally on a remote machine when a *servername* is supplied. [**GetObject**](/tB/Modules/Interaction/GetObject.md) is the dual: it either binds to a file (loading the application that owns it) or attaches to an already-running instance of an object class.

Once an object reference is in hand, [**CallByName**](/tB/Modules/Interaction/CallByName.md) and [**CallByDispId**](/tB/Modules/Interaction/CallByDispId.md) invoke a method or property on it dynamically, when the member to call is only known at run time --- by name in the first case, or by raw IDispatch dispatch ID in the second. [**RaiseEventByName**](/tB/Modules/Interaction/RaiseEventByName.md) and [**RaiseEventByName2**](/tB/Modules/Interaction/RaiseEventByName2.md) raise an event on an object by event-name string --- the run-time equivalent of the **RaiseEvent** statement, useful when the event being raised isn't known at compile time. The two forms differ only in how the event arguments are supplied: as a packed **Variant** array, or as a variable-length argument list.

## Members

- [AppActivate](/tB/Modules/Interaction/AppActivate.md) -- activates an application window
- [Beep](/tB/Modules/Interaction/Beep.md) -- sounds a tone through the computer's speaker
- [CallByDispId](/tB/Modules/Interaction/CallByDispId.md) -- invokes a method or property on an object dynamically by IDispatch dispatch ID
- [CallByName](/tB/Modules/Interaction/CallByName.md) -- invokes a method or property on an object dynamically by name
- [Choose](/tB/Modules/Interaction/Choose.md) -- returns one value from a list, selected by 1-based index
- [Command$, Command](/tB/Modules/Interaction/Command.md) -- returns the command-line arguments passed to the program
- [CreateObject](/tB/Modules/Interaction/CreateObject.md) -- creates a new instance of a COM/Automation object
- [DeleteSetting](/tB/Modules/Interaction/DeleteSetting.md) -- deletes a section or key setting from an application's entry in the Windows registry
- [DoEvents](/tB/Modules/Interaction/DoEvents.md) -- yields control to the message loop so pending events can be processed
- [Environ$, Environ](/tB/Modules/Interaction/Environ.md) -- returns the value of a process environment variable
- [GetAllSettings](/tB/Modules/Interaction/GetAllSettings.md) -- returns every key/value pair in a section of an application's registry entry
- [GetObject](/tB/Modules/Interaction/GetObject.md) -- returns a reference to an Automation object loaded from a file or already running
- [GetSetting](/tB/Modules/Interaction/GetSetting.md) -- returns a key setting value from an application's entry in the Windows registry
- [If](/tB/Modules/Interaction/If.md) -- evaluates an expression and returns one of two values, with short-circuit evaluation
- [IIf](/tB/Modules/Interaction/IIf.md) -- evaluates an expression and returns one of two values; both branches are always evaluated
- [InputBox](/tB/Modules/Interaction/InputBox.md) -- prompts the user for a line of text and returns what was entered
- [MsgBox](/tB/Modules/Interaction/MsgBox.md) -- displays a modal message dialog and returns the button the user clicked
- [Partition](/tB/Modules/Interaction/Partition.md) -- returns a string identifying the range a number falls into
- [RaiseEventByName](/tB/Modules/Interaction/RaiseEventByName.md) -- raises an event by name on an object, taking arguments as a **Variant** array
- [RaiseEventByName2](/tB/Modules/Interaction/RaiseEventByName2.md) -- raises an event by name on an object, taking a variable-length argument list
- [SaveSetting](/tB/Modules/Interaction/SaveSetting.md) -- saves or creates a key setting in an application's entry in the Windows registry
- [SendKeys](/tB/Modules/Interaction/SendKeys.md) -- sends keystrokes to the active window
- [Shell](/tB/Modules/Interaction/Shell.md) -- runs another program asynchronously and returns its task ID
- [Switch](/tB/Modules/Interaction/Switch.md) -- returns the value paired with the first **True** condition in a list of (condition, value) pairs
