Document the Interaction module.

docs/Reference/Categories.md

@@ -45,6 +45,13 @@ Statements:
 * [On ... GoTo](../tB/Core/On-GoTo), [On ... GoSub](../tB/Core/On-GoSub) - transfer execution to a location selected by an expression
 * [Stop](../tB/Core/Stop) - interrupt execution
 
+Inline conditional functions — expression-level alternatives to the **If...Then...Else** and **Select Case** statements above:
+
+* [If](../tB/Modules/Interaction/If) - evaluate an expression and return one of two values; only the chosen branch is evaluated (twinBASIC addition)
+* [IIf](../tB/Modules/Interaction/IIf) - evaluate an expression and return one of two values; both branches are always evaluated
+* [Choose](../tB/Modules/Interaction/Choose) - return one value from a list, selected by 1-based index
+* [Switch](../tB/Modules/Interaction/Switch) - return the value paired with the first **True** condition in a list of (condition, value) pairs
+
 See also: 
 
 * [End](../tB/Core/End) - terminate execution.
@@ -132,24 +139,57 @@ Procedures:
 Procedures:
 
 * [Load](../tB/Core/Load), [Unload](../tB/Core/Unload) - load/unload a form or control into memory
-* [GetSetting](../tB/Core/GetSetting), [SaveSetting](../tB/Core/SaveSetting) - retrieve/store a string value from/to the system registry
-* [DeleteSetting](../tB/Core/DeleteSetting) - remove value from the system registry
+* [GetSetting](../tB/Modules/Interaction/GetSetting), [SaveSetting](../tB/Modules/Interaction/SaveSetting) - retrieve/store a string value from/to the system registry
+* [GetAllSettings](../tB/Modules/Interaction/GetAllSettings) - retrieve every key/value pair in a section of an application's registry entry
+* [DeleteSetting](../tB/Modules/Interaction/DeleteSetting) - remove value from the system registry
 
-## Events and Interaction
+## Events
 
 Statements:
 
 * [RaiseEvent](../tB/Core/RaiseEvent) - raise an event that may be handled by event handlers
 
+Procedures:
+
+* [RaiseEventByName](../tB/Modules/Interaction/RaiseEventByName) - raise an event by name on an object, taking arguments as a **Variant** array
+* [RaiseEventByName2](../tB/Modules/Interaction/RaiseEventByName2) - raise an event by name on an object, taking a variable-length argument list
+
 See also
 
 * [Event](../tB/Core/Event) - declare an event
 
+## User Dialogs
+
+Procedures:
+
+* [MsgBox](../tB/Modules/Interaction/MsgBox) - display a modal message dialog and return the button the user clicked
+* [InputBox](../tB/Modules/Interaction/InputBox) - prompt the user for a line of text and return what was entered
+* [Beep](../tB/Modules/Interaction/Beep) - sound a system beep
+
+## Process Control
+
+Procedures:
+
+* [Shell](../tB/Modules/Interaction/Shell) - run another program asynchronously and return its task ID
+* [AppActivate](../tB/Modules/Interaction/AppActivate) - change the focus to, or activate, a named window
+* [SendKeys](../tB/Modules/Interaction/SendKeys) - send keystrokes to the active window
+* [DoEvents](../tB/Modules/Interaction/DoEvents) - yield control to the message loop so pending events can be processed
+
+## COM and Automation
+
+Procedures:
+
+* [CreateObject](../tB/Modules/Interaction/CreateObject) - create a new instance of a COM/Automation object
+* [GetObject](../tB/Modules/Interaction/GetObject) - obtain a reference to an Automation object loaded from a file or already running
+* [CallByName](../tB/Modules/Interaction/CallByName) - invoke a method or property on an object dynamically by name
+* [CallByDispId](../tB/Modules/Interaction/CallByDispId) - invoke a method or property on an object dynamically by IDispatch dispatch ID (twinBASIC addition)
+
+## Command Line and Environment
+
 Procedures:
 
-* [AppActivate](../tB/Core/AppActivate) - change the focus to, or activate, a named window
-* [Beep](../tB/Core/Beep) - sound a system beep
-* [SendKeys](../tB/Core/SendKeys) - send keystrokes to the active window
+* [Command$, Command](../tB/Modules/Interaction/Command) - return the command-line arguments passed to the program
+* [Environ$, Environ](../tB/Modules/Interaction/Environ) - return the value of a process environment variable
 
 ## Colours
 
@@ -174,6 +214,7 @@ Procedures:
 * [Round](../tB/Modules/Math/Round) - round the number to a given number of decimal places
 * [Rnd](../tB/Modules/Math/Rnd) - generate a random number in the range [0.0, 1.0)
 * [Randomize](../tB/Modules/Math/Randomize) - seed the random number generator
+* [Partition](../tB/Modules/Interaction/Partition) - return a string label identifying which of a series of equal-width numeric ranges a value falls into (histogram-style bucketing)
 
 See also:
 

docs/Reference/Core/todo.md

@@ -42,7 +42,6 @@ redirect_from:
   - /tB/Core/RSet
   - /tB/Core/SavePicture
   - /tB/Core/Select-Case
-  - /tB/Core/SendKeys
   - /tB/Core/Set
   - /tB/Core/Static
   - /tB/Core/Sub

docs/Reference/Modules/Interaction/CallByDispId.md

@@ -0,0 +1,43 @@
+---
+title: CallByDispId
+parent: Interaction Module
+permalink: /tB/Modules/Interaction/CallByDispId
+---
+# CallByDispId
+{: .no_toc }
+
+Calls a method, or reads or writes a property, on an object — looked up by raw IDispatch dispatch ID at run time. **CallByDispId** is a twinBASIC addition; the by-name variant, [**CallByName**](CallByName), exists in VBA as well.
+
+Syntax: **CallByDispId(** *object* **,** *dispid* **,** *calltype* [ **,** *args* ... ] **)**
+
+*object*
+: *required* **Object**. The object whose member is to be invoked.
+
+*dispid*
+: *required* **Long**. The IDispatch dispatch ID (`DISPID`) of the method or property to invoke.
+
+*calltype*
+: *required* A [**VbCallType**](../Constants/VbCallType) value indicating the kind of member: `vbMethod`, `vbGet`, `vbLet`, or `vbSet`.
+
+*args*
+: *optional* The arguments to pass to the method, **Property Get**, **Property Let**, or **Property Set**.
+
+The return value is a **Variant** containing whatever the call returned. For methods that return nothing, or for property assignments, the result is **Empty**.
+
+**CallByDispId** skips the name lookup that [**CallByName**](CallByName) performs, which is useful in two situations: when you already know the dispatch ID and want to avoid the cost of a `GetIDsOfNames` round trip, and when the target member is not exposed by name (e.g. a default member with `DISPID_VALUE = 0`, an explicit-DISPID extension, or a hidden/restricted member).
+
+### Example
+
+This example invokes the default member of an object — `DISPID_VALUE`, defined as 0 — by dispatch ID.
+
+```tb
+Const DISPID_VALUE As Long = 0
+
+Dim Result As Variant
+Result = CallByDispId(SomeObject, DISPID_VALUE, vbGet)
+```
+
+### See Also
+
+- [CallByName](CallByName) function
+- [VbCallType](../Constants/VbCallType) enumeration

docs/Reference/Modules/Interaction/CallByName.md

@@ -0,0 +1,44 @@
+---
+title: CallByName
+parent: Interaction Module
+permalink: /tB/Modules/Interaction/CallByName
+redirect_from:
+-  /tB/Core/CallByName
+---
+# CallByName
+{: .no_toc }
+
+Calls a method, or reads or writes a property, on an object — looked up by name at run time.
+
+Syntax: **CallByName(** *object* **,** *procname* **,** *calltype* [ **,** *args* ... ] **)**
+
+*object*
+: *required* **Object**. The object whose member is to be invoked.
+
+*procname*
+: *required* **String**. The name of the method or property to invoke on *object*.
+
+*calltype*
+: *required* A [**VbCallType**](../Constants/VbCallType) value indicating the kind of member: `vbMethod`, `vbGet`, `vbLet`, or `vbSet`.
+
+*args*
+: *optional* The arguments to pass to the method, **Property Get**, **Property Let**, or **Property Set**.
+
+The return value is a **Variant** containing whatever the call returned. For methods that return nothing, or for property assignments, the result is **Empty**.
+
+### Example
+
+These three calls drive a control by name. The first sets its **MousePointer** property to the crosshair cursor, the second reads the same property back out, and the third invokes the **Move** method to reposition the control.
+
+```tb
+CallByName Text1, "MousePointer", vbLet, vbCrosshair
+Result = CallByName(Text1, "MousePointer", vbGet)
+CallByName Text1, "Move", vbMethod, 100, 100
+```
+
+### See Also
+
+- [CallByDispId](CallByDispId) function
+- [VbCallType](../Constants/VbCallType) enumeration
+
+{% include VBA-Attribution.md %}

docs/Reference/Modules/Interaction/Choose.md

@@ -0,0 +1,42 @@
+---
+title: Choose
+parent: Interaction Module
+permalink: /tB/Modules/Interaction/Choose
+redirect_from:
+-  /tB/Core/Choose
+---
+# Choose
+{: .no_toc }
+
+Selects and returns a value from a list of arguments by 1-based index.
+
+Syntax: **Choose(** *index* **,** *choice-1* [ **,** *choice-2* **, ...** [ **,** *choice-n* ] ] **)**
+
+*index*
+: *required* Numeric expression that evaluates to a value between 1 and the number of available choices.
+
+*choice*
+: *required* **Variant** expression containing one of the possible choices.
+
+If *index* is 1, **Choose** returns *choice-1*; if *index* is 2, it returns *choice-2*; and so on. If *index* is less than 1 or greater than the number of choices listed, **Choose** returns **Null**. Non-integer values of *index* are rounded to the nearest whole number before being evaluated.
+
+> [!NOTE]
+> **Choose** evaluates *every* choice in the list, not only the one it returns. Watch for side effects: a [**MsgBox**](MsgBox) call inside any of the choices is invoked once per choice, not just for the selected one. To avoid this — for example, when one of the branches would error out — use the short-circuiting [**If**](If) function instead.
+
+### Example
+
+This example uses **Choose** to map a 1-based option index to a name.
+
+```tb
+Function GetChoice(Ind As Integer) As String
+    GetChoice = Choose(Ind, "Speedy", "United", "Federal")
+End Function
+```
+
+### See Also
+
+- [If](If) function
+- [IIf](IIf) function
+- [Switch](Switch) function
+
+{% include VBA-Attribution.md %}

docs/Reference/Modules/Interaction/Command.md

@@ -0,0 +1,64 @@
+---
+title: Command
+parent: Interaction Module
+permalink: /tB/Modules/Interaction/Command
+redirect_from:
+-  /tB/Core/Command
+---
+# Command, Command$
+{: .no_toc }
+
+Returns the argument portion of the command line used to launch the program.
+
+Syntax:
+
+- **Command$()**
+- **Command()**
+
+The `$`-suffixed form returns a **String**; the unsuffixed form returns a **Variant** (**String**).
+
+For applications compiled to an executable, **Command** returns any arguments that appear after the name of the application on the command line. For example, with the command line:
+
+```
+MyApp /switch arg1 arg2
+```
+
+**Command** returns `"/switch arg1 arg2"`.
+
+### Example
+
+This example uses **Command** to retrieve the command-line arguments and split them into an array.
+
+```tb
+Function GetCommandLine(Optional MaxArgs As Variant) As Variant
+    Dim Ch As String, CmdLine As String, CmdLnLen As Long
+    Dim InArg As Boolean, I As Long, NumArgs As Long
+
+    If IsMissing(MaxArgs) Then MaxArgs = 10
+    ReDim ArgArray(MaxArgs)
+
+    NumArgs = 0
+    InArg = False
+    CmdLine = Command()
+    CmdLnLen = Len(CmdLine)
+
+    For I = 1 To CmdLnLen
+        Ch = Mid(CmdLine, I, 1)
+        If Ch <> " " And Ch <> vbTab Then
+            If Not InArg Then
+                If NumArgs = MaxArgs Then Exit For
+                NumArgs = NumArgs + 1
+                InArg = True
+            End If
+            ArgArray(NumArgs) = ArgArray(NumArgs) & Ch
+        Else
+            InArg = False
+        End If
+    Next I
+
+    ReDim Preserve ArgArray(NumArgs)
+    GetCommandLine = ArgArray()
+End Function
+```
+
+{% include VBA-Attribution.md %}

docs/Reference/Modules/Interaction/CreateObject.md

@@ -0,0 +1,51 @@
+---
+title: CreateObject
+parent: Interaction Module
+permalink: /tB/Modules/Interaction/CreateObject
+redirect_from:
+-  /tB/Core/CreateObject
+---
+# CreateObject
+{: .no_toc }
+
+Creates and returns a reference to a new instance of a COM/Automation object.
+
+Syntax: **CreateObject(** *class* [ **,** *servername* ] **)**
+
+*class*
+: *required* **Variant** (**String**). The application name and class of the object to create, in the form *appname*.*objecttype* — for example, `"Excel.Application"`. A CLSID may also be supplied in the form `"new:{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"`.
+
+*servername*
+: *optional* **Variant** (**String**). The name of the network server on which to create the object — the same as the *Machine Name* portion of a UNC share name. For a share named `\\MyServer\Public`, *servername* is `"MyServer"`. If *servername* is omitted or supplied as a zero-length string (`""`), the object is created on the local machine.
+
+To use the returned object, assign it to an object variable. Declaring the variable `As Object` causes late binding (binding occurs at run time); declaring it with a specific class type produces early binding (binding occurs at compile time), which is faster and gives access to IntelliSense for the object's members but limits the variable to that one type.
+
+```tb
+Dim ExcelApp As Object
+Set ExcelApp = CreateObject("Excel.Application")
+ExcelApp.Visible = True
+```
+
+If a remote *servername* is supplied but the remote machine doesn't exist or is unreachable, a run-time error occurs. If an object has registered itself as single-instance, only one instance is ever created, no matter how many times **CreateObject** is invoked.
+
+> [!NOTE]
+> Use **CreateObject** when you want a new instance of the object. To attach to an *already-running* instance — or to start the object's application with a particular file loaded — use [**GetObject**](GetObject) instead.
+
+### Example
+
+This example creates a Microsoft Excel **Application** object, makes it visible, and then closes it via **Quit**, releasing the reference at the end.
+
+```tb
+Dim XlApp As Object
+Set XlApp = CreateObject("Excel.Application")
+XlApp.Visible = True
+' ... drive Excel through XlApp ...
+XlApp.Quit
+Set XlApp = Nothing
+```
+
+### See Also
+
+- [GetObject](GetObject) function
+
+{% include VBA-Attribution.md %}

docs/Reference/Modules/Interaction/DoEvents.md

@@ -0,0 +1,41 @@
+---
+title: DoEvents
+parent: Interaction Module
+permalink: /tB/Modules/Interaction/DoEvents
+redirect_from:
+-  /tB/Core/DoEvents
+---
+# DoEvents
+{: .no_toc }
+
+Yields execution so the operating system can dispatch pending window messages and other events.
+
+Syntax: **DoEvents()**
+
+Returns an **Integer** indicating the number of open forms in the application; returns 0 in hosts that do not maintain a forms collection.
+
+**DoEvents** passes control to the operating system. Control is returned to the caller after the operating system has finished processing the events in its queue and after any keystrokes pending in the [**SendKeys**](SendKeys) queue have been delivered.
+
+**DoEvents** is most useful for simple things like keeping a UI responsive during a tight loop, or letting the user cancel a long-running operation. For genuinely long-running work, prefer a timer or a background worker (e.g. an out-of-process ActiveX EXE) so the operating system handles the multitasking.
+
+> [!NOTE]
+> Whenever you yield the processor inside an event procedure, make sure that procedure cannot be re-entered from a different code path before the original call returns; otherwise the program may behave unpredictably. Likewise, avoid **DoEvents** when other applications might interact with your procedure in unforeseen ways during the time you have yielded control.
+
+### Example
+
+This example yields to the operating system once every 1000 iterations of a loop.
+
+```tb
+Dim I As Long, OpenForms As Long
+For I = 1 To 150000
+    If I Mod 1000 = 0 Then
+        OpenForms = DoEvents()
+    End If
+Next I
+```
+
+### See Also
+
+- [SendKeys](SendKeys) statement
+
+{% include VBA-Attribution.md %}