From e6e703099da304db471c287f03b35ffe35055750 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Thu, 14 May 2026 20:50:40 +0200 Subject: [PATCH 01/19] Add a minimal language style guide. --- WIP.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/WIP.md b/WIP.md index a7fdb09..113e552 100644 --- a/WIP.md +++ b/WIP.md @@ -314,6 +314,29 @@ The audience is international: standard-English readers worldwide, often non-nat The guiding principle: **replace metaphors imported from outside programming; keep vocabulary with a specific technical meaning inside Win32 / COM / event-driven programming.** If a phrase is the kind of thing a reader would have to look up in a tech blog, it doesn't belong in reference prose. +### Sentence and structure + +The vocabulary tables further down cover word choice. The rules in this subsection cover sentence shape and voice — the structural side of writing for an international audience. + +1. **Page opening.** One-sentence verb-phrase summary directly under the H1, in present tense, no preamble. *Good:* "Activates an application window." / "Writes an **Error**-type entry to the log." *Avoid:* "The **Const** statement is used to declare constants in place of literal values." + +2. **Voice and tense.** Active voice by default. Passive only for subjectless operations where there is no obvious agent — "the entry is written", "the constant is private by default". Present tense for behavior — `returns`, not `will return`. Don't give the class human traits: it doesn't "decide", "want", or "know" — it returns, raises, contains. + +3. **Sentence shape.** One idea per sentence. Prefer two short sentences over one compound sentence with nested clauses. Em-dash (`—`) for parenthetical asides; reserve parentheses for code-ish notation like `(default)`. + +4. **Person and pronouns.** Reference prose uses third-person impersonal — "the constant", "the source", "the entry". "You" is acceptable inside `Example` lead-ins and in tutorial prose. Existing "you" in VBA-derived pages stays in place; new prose written from scratch prefers the impersonal form. Avoid first-person ("we", "I"). + +5. **Parameter descriptions.** Italic `*required*` / `*optional*` flag, then a short prose description. Lead with the type when it matters — "A **String** naming the source...", "A *T1* value naming the event...". Don't restate the parameter's name inside its own definition. + +6. **Callout severity.** Three severity levels, used distinctly: + - `> [!NOTE]` — twinBASIC-vs-VBA deviations, behavior clarifications, useful caveats. + - `> [!IMPORTANT]` — requirements that affect correctness: admin rights, threading constraints, ordering. + - `> [!WARNING]` — operations that can corrupt state or lose data. + + One callout per concern; don't stack a NOTE and an IMPORTANT for the same point. + +7. **See Also.** Last section on the page, after `Example`. Format: `- [Symbol](Symbol) ` where `` is the kind: statement, function, property, method, class, module, package. Pages with annotations use `- [Symbol](Symbol) — short description` (em-dash separator). Order by conceptual proximity, not strict alphabetical. + ### Replace | Term | Use instead | From 6a08084ba5d99481f6b144ff930e91caa8155ffb Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Thu, 14 May 2026 21:13:01 +0200 Subject: [PATCH 02/19] Add Plain-English structural style rules; apply pilot pass on five pages. --- WIP.md | 15 +++++++-------- docs/Reference/Core/Const.md | 6 +++--- docs/Reference/VBA/DateTime/Date.md | 17 ++++++++--------- docs/Reference/VBA/Interaction/AppActivate.md | 18 +++++++++--------- docs/Reference/WinEventLogLib/EventLog.md | 8 ++++---- 5 files changed, 31 insertions(+), 33 deletions(-) diff --git a/WIP.md b/WIP.md index 113e552..2fd30e4 100644 --- a/WIP.md +++ b/WIP.md @@ -28,8 +28,8 @@ The rest of this file is the maintenance guide for updating existing pages or ad - `docs/Reference/Core/` — language statements/keywords (`Dim`, `For-Next`, `Sub`, ...). - `docs/Reference///` — runtime library (VBA, VBRUN), grouped by modules. - `docs/Reference///index.md` — module landing page listing its members. -- `docs/Reference/VB/.md` — single-file class page (e.g. [`CheckBox.md`](docs/Reference/VB/CheckBox.md)). -- `docs/Reference/VB//index.md` — folder-style class page when sub-pages may follow (e.g. [`CheckMark/index.md`](docs/Reference/VB/CheckMark/index.md)). +- `docs/Reference/VB/.md` — single-file class page. No current VB class uses this shape; all VB classes are folder-style. +- `docs/Reference/VB//index.md` — folder-style class page (e.g. [`CheckBox/index.md`](docs/Reference/VB/CheckBox/index.md), [`CheckMark/index.md`](docs/Reference/VB/CheckMark/index.md)). - `docs/Reference/WebView2/` — WebView2 package: the **WebView2** control class plus its small wrapper classes (request / response / headers / environment options) and the `wv2…` enumerations. - `docs/Reference/CustomControls/` — CustomControls package: the eight **Waynes…** custom controls, their shared `Styles/` helper classes (`Fill`, `Borders`, `Corners`, `TextRendering`, …), the `Framework/` DESIGNER surface (interfaces, CoClasses, the `Canvas` / `SerializeInfo` UDTs), and the `Enumerations/` (`CornerShape`, `FillPattern`, `DockMode`, …). - `docs/Reference/CEF/` — CEF (Chromium Embedded Framework) package: the **CefBrowser** control, its `EnvironmentOptions` sub-page, and the two user-facing enumerations (`CefLogSeverity`, `cefPrintOrientation`). This is a much smaller surface than WebView2 — the package is currently BETA and many WebView2-equivalent features are not yet exposed. @@ -66,8 +66,7 @@ Match the existing style. Worked examples to imitate: - VBA module function: `docs/Reference/VBA/Interaction/AppActivate.md`, `docs/Reference/VBA/Interaction/Beep.md`. - VBA property with `Core/` redirect: `docs/Reference/VBA/DateTime/Date.md`. - VBRUN module member: `docs/Reference/VBRUN/AmbientProperties/BackColor.md`, `docs/Reference/VBRUN/PropertyBag/index.md`. -- VB control class (single-file): `docs/Reference/VB/CheckBox.md`. -- VB control class (folder-style): `docs/Reference/VB/CheckMark/index.md`. +- VB control class (folder-style; all current VB classes): `docs/Reference/VB/CheckBox/index.md`, `docs/Reference/VB/CheckMark/index.md`. - Assert module page (single-file, all members inline): `docs/Reference/Assert/Exact.md`. - CEF control class (folder-style with a sub-page): `docs/Reference/CEF/CefBrowser/index.md` + `docs/Reference/CEF/CefBrowser/EnvironmentOptions.md`. - Generic class (single-file, `(Of T1, T2)`): `docs/Reference/WinEventLogLib/EventLog.md`. @@ -318,18 +317,18 @@ The guiding principle: **replace metaphors imported from outside programming; ke The vocabulary tables further down cover word choice. The rules in this subsection cover sentence shape and voice — the structural side of writing for an international audience. -1. **Page opening.** One-sentence verb-phrase summary directly under the H1, in present tense, no preamble. *Good:* "Activates an application window." / "Writes an **Error**-type entry to the log." *Avoid:* "The **Const** statement is used to declare constants in place of literal values." +1. **Page opening.** One-sentence verb-phrase summary directly under the H1, in present tense, no preamble. *Good:* "Activates an application window." / "Writes an **Error**-type entry to the log." *Avoid:* "The **Const** statement is used to declare constants in place of literal values." For class pages, a noun-phrase descriptor is acceptable — *"A **CheckBox** is a Win32 native control that displays..."* 2. **Voice and tense.** Active voice by default. Passive only for subjectless operations where there is no obvious agent — "the entry is written", "the constant is private by default". Present tense for behavior — `returns`, not `will return`. Don't give the class human traits: it doesn't "decide", "want", or "know" — it returns, raises, contains. 3. **Sentence shape.** One idea per sentence. Prefer two short sentences over one compound sentence with nested clauses. Em-dash (`—`) for parenthetical asides; reserve parentheses for code-ish notation like `(default)`. -4. **Person and pronouns.** Reference prose uses third-person impersonal — "the constant", "the source", "the entry". "You" is acceptable inside `Example` lead-ins and in tutorial prose. Existing "you" in VBA-derived pages stays in place; new prose written from scratch prefers the impersonal form. Avoid first-person ("we", "I"). +4. **Person and pronouns.** Reference body prose uses third-person impersonal — "the constant", "the source", "the entry". Rewrite "you" to the impersonal form even in VBA-derived pages. "You" is acceptable inside `Example` lead-ins and in tutorial prose. Avoid first-person ("we", "I"). -5. **Parameter descriptions.** Italic `*required*` / `*optional*` flag, then a short prose description. Lead with the type when it matters — "A **String** naming the source...", "A *T1* value naming the event...". Don't restate the parameter's name inside its own definition. +5. **Parameter descriptions.** Italic `*required*` / `*optional*` flag, then a short prose description. Lead with the type when it matters — "A **String** naming the source...", "A *T1* value naming the event...". Don't restate the parameter's name inside its own definition. Property setters omit the flag — the `[ = *value* ]` brackets on the syntax line carry that information. 6. **Callout severity.** Three severity levels, used distinctly: - - `> [!NOTE]` — twinBASIC-vs-VBA deviations, behavior clarifications, useful caveats. + - `> [!NOTE]` — twinBASIC-vs-VBA deviations, behavior clarifications, useful caveats. Not for marketing/why-bother prose — that should be a plain paragraph. - `> [!IMPORTANT]` — requirements that affect correctness: admin rights, threading constraints, ordering. - `> [!WARNING]` — operations that can corrupt state or lose data. diff --git a/docs/Reference/Core/Const.md b/docs/Reference/Core/Const.md index 4a40d12..9e8662f 100644 --- a/docs/Reference/Core/Const.md +++ b/docs/Reference/Core/Const.md @@ -28,7 +28,7 @@ Syntax: *constname* -: Name of the constant; follows standard variable naming conventions. +: *required* Name of the constant; follows standard variable naming conventions. *type* @@ -36,9 +36,9 @@ Syntax: *expression* -: Required. Literal, other constant, or any combination that includes all arithmetic or logical operators except **Is**. +: *required* Literal, other constant, or any combination that includes all arithmetic or logical operators except **Is**. -Constants are private by default. Within procedures, constants are always private; their visibility can't be changed. In standard modules, the default visibility of module-level constants can be changed by using the **Public** keyword. In class modules, however, constants can only be private and their visibility can't be changed by using the **Public** keyword. +Constants are private by default. Within procedures, constants are always private; their visibility can't be changed. In standard modules, the **Public** keyword can change the default visibility of module-level constants. In class modules, constants are always private; the **Public** keyword has no effect. To combine several constant declarations on the same line, separate each constant assignment with a comma. When constant declarations are combined in this way, the **Public** or **Private** keyword, if used, applies to all of them. diff --git a/docs/Reference/VBA/DateTime/Date.md b/docs/Reference/VBA/DateTime/Date.md index 64283b6..9dabffb 100644 --- a/docs/Reference/VBA/DateTime/Date.md +++ b/docs/Reference/VBA/DateTime/Date.md @@ -43,11 +43,10 @@ Sets the current system date from a value with a Variant or Date type. Syntax: **Date** **=** *date* -date +*date* +: *required* For systems running Microsoft Windows 95, the *date* specification must be a date from January 1, 1980, through December 31, 2099. For systems running Microsoft Windows NT, *date* must be a date from January 1, 1980, through December 31, 2079. For the Macintosh, *date* must be a date from January 1, 1904, through February 5, 2040. -: For systems running Microsoft Windows 95, the required *date* specification must be a date from January 1, 1980, through December 31, 2099. For systems running Microsoft Windows NT, *date* must be a date from January 1, 1980, through December 31, 2079. For the Macintosh, *date* must be a date from January 1, 1904, through February 5, 2040. - -> [!NOTE] +> [!IMPORTANT] > > In some versions of Microsoft Windows, including Windows 10 and 11, setting the system date is a privileged operation that requires the process to have relevant permissions. Without those permissions, assignment to **Date** results in a Permission Denied runtime error. @@ -89,11 +88,10 @@ Sets the current system date from a string. Syntax: **Date$** **=** *date* -date +*date* +: *required* For systems running Microsoft Windows 95, the *date* specification must be a date from January 1, 1980, through December 31, 2099. For systems running Microsoft Windows NT, *date* must be a date from January 1, 1980, through December 31, 2079. For the Macintosh, *date* must be a date from January 1, 1904, through February 5, 2040. -: For systems running Microsoft Windows 95, the required *date* specification must be a date from January 1, 1980, through December 31, 2099. For systems running Microsoft Windows NT, *date* must be a date from January 1, 1980, through December 31, 2079. For the Macintosh, *date* must be a date from January 1, 1904, through February 5, 2040. - -> [!NOTE] +> [!IMPORTANT] > > In some versions of Microsoft Windows, including Windows 10 and 11, setting the system date is a privileged operation that requires the process to have relevant permissions. Without those permissions, assignment to **Date**$ results in a Permission Denied runtime error. @@ -110,4 +108,5 @@ Date$ = MyDate ' Change the system date. ### See Also - [Time](Time) property -- [Format](../Strings/Format) and [Now](Now) functions \ No newline at end of file +- [Format](../Strings/Format) function +- [Now](Now) function \ No newline at end of file diff --git a/docs/Reference/VBA/Interaction/AppActivate.md b/docs/Reference/VBA/Interaction/AppActivate.md index 9f2331d..2c85293 100644 --- a/docs/Reference/VBA/Interaction/AppActivate.md +++ b/docs/Reference/VBA/Interaction/AppActivate.md @@ -14,13 +14,13 @@ Activates an application window. Syntax: - **AppActivate** *title* [ **,** *wait* ] - title + *title* : *required* A string expression specifying the title in the title bar of the application window you want to activate. - wait + *wait* : *optional* A Boolean value specifying whether the calling application has the focus before activating another. If **False** (default), the specified application is immediately activated, even if the calling application does not have the focus. If **True**, the calling application waits until it has the focus, then activates the specified application. -- **AppActivate** *taskId* [ **,** *wait ] +- **AppActivate** *taskId* [ **,** *wait* ] *taskId* : *required* The task ID returned by the [**Shell**](Shell) function can be used in place of *title* to activate an application. @@ -29,11 +29,6 @@ The **AppActivate** statement changes the focus to the named application or win In determining which application to activate, *title* is compared to the title string of each running application. If there is no exact match, any application whose title string begins with *title* is activated. If there is more than one instance of the application named by *title*, one instance is arbitrarily activated. -### See Also - -- [SendKeys](SendKeys) statement -- [Shell](Shell) function - ### Example This example illustrates various uses of the **AppActivate** statement to activate an application window. The **Shell** statements assume the applications are in the paths specified. @@ -53,4 +48,9 @@ AppActivate MyAppID ' Activate Microsoft ReturnValue = Shell("c:\EXCEL\EXCEL.EXE",1) ' Run Microsoft Excel. AppActivate ReturnValue ' Activate Microsoft ' Excel. -``` \ No newline at end of file +``` + +### See Also + +- [SendKeys](SendKeys) statement +- [Shell](Shell) function \ No newline at end of file diff --git a/docs/Reference/WinEventLogLib/EventLog.md b/docs/Reference/WinEventLogLib/EventLog.md index 37284e7..094c883 100644 --- a/docs/Reference/WinEventLogLib/EventLog.md +++ b/docs/Reference/WinEventLogLib/EventLog.md @@ -118,10 +118,10 @@ The Event Viewer renders message strings by loading **EventMessageFile** and loo If the registry key cannot be opened for write, **Register** raises run-time error 5 *"Failed to register event log source (\)"*. Typical causes are insufficient privileges and a *LogPath* that points at a non-existent parent log. -The lower-level [**EventLogHelperPublic.RegisterEventLogInternal**](EventLogHelperPublic#registereventloginternal) is what **Register** delegates to; use it directly only if you need to register a source without binding it to a generic *T2* (and so without using **GetDeclaredMaxEnumValue** to derive the category count). +The lower-level [**EventLogHelperPublic.RegisterEventLogInternal**](EventLogHelperPublic#registereventloginternal) is what **Register** delegates to; use it directly only when registering a source without binding it to a generic *T2* (and so without using **GetDeclaredMaxEnumValue** to derive the category count). ## See Also -- [WinEventLogLib package](.) -- overview, lifecycle, message-resource generation -- [EventLogHelperPublic module](EventLogHelperPublic) -- the lower-level registration helper -- [Generics feature](../../../Features/Language/Generics) -- syntax rules for generic class instantiation +- [WinEventLogLib](.) package — overview, lifecycle, message-resource generation +- [EventLogHelperPublic](EventLogHelperPublic) module — the lower-level registration helper +- [Generics](../../../Features/Language/Generics) feature — syntax rules for generic class instantiation From 1e9c3fa7ebcc3af8f6ceed344e65be43c16091a0 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Thu, 14 May 2026 21:57:30 +0200 Subject: [PATCH 03/19] Apply structural style rules to Assert package --- docs/Reference/Assert/Permissive.md | 2 +- docs/Reference/Assert/Strict.md | 2 +- docs/Reference/Assert/index.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/Reference/Assert/Permissive.md b/docs/Reference/Assert/Permissive.md index 1f0cbc5..1ab61bd 100644 --- a/docs/Reference/Assert/Permissive.md +++ b/docs/Reference/Assert/Permissive.md @@ -8,7 +8,7 @@ has_toc: false # Permissive module {: .no_toc } -The **Permissive** module of the [**Assert**](.) package supplies assertions that compare values as if the comparison had been written directly in twinBASIC code, with case-insensitive string comparison. Object default members are evaluated. Use **Permissive** for tests where you don't care about case differences in strings — for example, asserting that an error message contains a particular phrase regardless of capitalisation — and you want object comparison to use the same default-member rules as `=`. +The **Permissive** module of the [**Assert**](.) package supplies assertions that compare values as if the comparison had been written directly in twinBASIC code, with case-insensitive string comparison. Object default members are evaluated. Use **Permissive** for tests that should ignore case differences in strings — for example, asserting that an error message contains a particular phrase regardless of capitalisation — and that need object comparison to use the same default-member rules as `=`. * TOC {:toc} diff --git a/docs/Reference/Assert/Strict.md b/docs/Reference/Assert/Strict.md index b3cf763..914f6fd 100644 --- a/docs/Reference/Assert/Strict.md +++ b/docs/Reference/Assert/Strict.md @@ -8,7 +8,7 @@ has_toc: false # Strict module {: .no_toc } -The **Strict** module of the [**Assert**](.) package supplies assertions that compare values as if the comparison had been written directly in twinBASIC code, with two exceptions: string comparisons are case-sensitive (regardless of the project's `Option Compare` setting), and object default members are not evaluated. Use **Strict** for tests that should match the language's normal equality semantics for numbers and primitives but want a guaranteed case-sensitive string compare and reference-style equality on objects. +The **Strict** module of the [**Assert**](.) package supplies assertions that compare values as if the comparison had been written directly in twinBASIC code, with two exceptions: string comparisons are case-sensitive (regardless of the project's `Option Compare` setting), and object default members are not evaluated. Use **Strict** for tests that should match the language's normal equality semantics for numbers and primitives but also need a guaranteed case-sensitive string compare and reference-style equality on objects. * TOC {:toc} diff --git a/docs/Reference/Assert/index.md b/docs/Reference/Assert/index.md index 4051e4f..2e1a55c 100644 --- a/docs/Reference/Assert/index.md +++ b/docs/Reference/Assert/index.md @@ -11,7 +11,7 @@ has_toc: false The **Assert** built-in package supplies the assertion functions used to write unit tests for twinBASIC code. Each assertion checks an expected condition; on failure, it records a test failure with the call site and an optional message. The test runner — the twinBASIC IDE's Test Explorer, or any equivalent harness — collects those results, decides which tests passed, failed, or were skipped, and reports them. -The package's three modules — [**Exact**](Exact), [**Strict**](Strict), and [**Permissive**](Permissive) — expose the same fifteen assertion functions; only the *comparison semantics* differ. Pick the flavour that matches how strictly you want equality to be evaluated. +The package's three modules — [**Exact**](Exact), [**Strict**](Strict), and [**Permissive**](Permissive) — expose the same fifteen assertion functions; only the *comparison semantics* differ. Pick the flavour that matches how strictly equality should be evaluated. | Module | String comparisons | Numeric and other comparisons | |------------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| From 18ce7c9faa38a41007c265e50a66d0b4194086fe Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Thu, 14 May 2026 21:57:30 +0200 Subject: [PATCH 04/19] Apply structural style rules to CEF package --- docs/Reference/CEF/CefBrowser/EnvironmentOptions.md | 4 ++-- docs/Reference/CEF/CefBrowser/index.md | 9 +++++---- docs/Reference/CEF/index.md | 12 ++++++------ 3 files changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/Reference/CEF/CefBrowser/EnvironmentOptions.md b/docs/Reference/CEF/CefBrowser/EnvironmentOptions.md index 20e178c..2012ee1 100644 --- a/docs/Reference/CEF/CefBrowser/EnvironmentOptions.md +++ b/docs/Reference/CEF/CefBrowser/EnvironmentOptions.md @@ -9,7 +9,7 @@ has_toc: false # CefEnvironmentOptions class {: .no_toc } -Carries the host's pre-creation configuration for the CEF environment — runtime folder, user-data folder, and the optional debug-log destination. Surfaces on every [**CefBrowser**](.) control as its **EnvironmentOptions** property; the control instantiates one automatically before raising the [**Create**](.#create) event. +Pre-creation configuration for the CEF environment — runtime folder, user-data folder, and the optional debug-log destination. Available on every [**CefBrowser**](.) control as its **EnvironmentOptions** property; the control instantiates one automatically before raising the [**Create**](.#create) event. The fields below take effect only while the CEF runtime is being launched — that is, *before or during* the control's [**Create**](.#create) event. Assigning them after that point has no effect on the live environment. @@ -23,7 +23,7 @@ Private Sub CefBrowser1_Create() End Sub ``` -The type itself is `Private Class` — you reach instances only through the control's **EnvironmentOptions** property and cannot declare a variable typed as **CefEnvironmentOptions** from outside the package. +The type itself is `Private Class` — instances are reachable only through the control's **EnvironmentOptions** property, and a variable typed as **CefEnvironmentOptions** cannot be declared from outside the package. ## Properties diff --git a/docs/Reference/CEF/CefBrowser/index.md b/docs/Reference/CEF/CefBrowser/index.md index a0800d4..114f32b 100644 --- a/docs/Reference/CEF/CefBrowser/index.md +++ b/docs/Reference/CEF/CefBrowser/index.md @@ -27,7 +27,7 @@ Private Sub CefBrowser1_NavigationComplete( _ End Sub ``` -The control inherits the rect-dockable members (size, layout, **Anchors**, **Dock**) from `BaseControlRectDockable`. It does *not* inherit a focusable layer, so the keyboard / mouse / focus events you might find on [**WebView2**](../../WebView2/WebView2/) are not part of its API — keystrokes go straight into the page once Chromium has focus. +The control inherits the rect-dockable members (size, layout, **Anchors**, **Dock**) from `BaseControlRectDockable`. It does *not* inherit a focusable layer, so the keyboard / mouse / focus events available on [**WebView2**](../../WebView2/WebView2/) are not part of its API — keystrokes go straight into the page once Chromium has focus. * TOC {:toc} @@ -48,7 +48,7 @@ The first **CefBrowser** to initialise in a process launches the shared browser ## Deferred startup -By default the control launches the browser helper as soon as the form is loaded (the `WS_VISIBLE` style is set on the host window and the first resize event triggers the helper). Set [**CreateInitialized**](#createinitialized) to **False** before the form loads, then call [**Initialize**](#initialize) at the moment you want the browser to start — useful when several **CefBrowser** controls live on tabs and you want to defer the cost until the tab is shown. +By default the control launches the browser helper as soon as the form is loaded (the `WS_VISIBLE` style is set on the host window and the first resize event triggers the helper). Set [**CreateInitialized**](#createinitialized) to **False** before the form loads, then call [**Initialize**](#initialize) when the browser should start — useful when several **CefBrowser** controls live on tabs and the cost of launching the helper should be deferred until the tab is shown. ## JavaScript interop @@ -207,7 +207,7 @@ Syntax: *object*.**ClearVirtualHostNameToFolderMapping** *hostName* ### ExecuteScript {: .no_toc } -Evaluates JavaScript in the page without waiting for it to finish and without returning its result. Use [**JsRun**](#jsrun) or [**JsRunAsync**](#jsrunasync) when you need the value. +Evaluates JavaScript in the page without waiting for it to finish and without returning its result. Use [**JsRun**](#jsrun) or [**JsRunAsync**](#jsrunasync) when the return value is needed. Syntax: *object*.**ExecuteScript** *jsCode* @@ -554,7 +554,8 @@ End Sub ## See Also - [CefEnvironmentOptions](EnvironmentOptions) -- pre-creation configuration exposed through [**EnvironmentOptions**](#environmentoptions) -- [CefLogSeverity](../Enumerations/CefLogSeverity), [cefPrintOrientation](../Enumerations/cefPrintOrientation) -- the package's two user-facing enumerations +- [CefLogSeverity](../Enumerations/CefLogSeverity) -- the verbosity threshold for the CEF debug log +- [cefPrintOrientation](../Enumerations/cefPrintOrientation) -- page orientation passed to [**PrintToPdf**](#printtopdf) - [WebView2](../../WebView2/WebView2/) -- the WebView2-runtime counterpart with a larger feature set - [WebView2 parity](../#webview2-parity) -- features available on **WebView2** that are not yet exposed on **CefBrowser** - [ControlTypeConstants](../../VBRUN/Constants/ControlTypeConstants) -- where **vbCefBrowser** lives diff --git a/docs/Reference/CEF/index.md b/docs/Reference/CEF/index.md index 1f9d2e0..75a7bfb 100644 --- a/docs/Reference/CEF/index.md +++ b/docs/Reference/CEF/index.md @@ -25,10 +25,10 @@ The package is a built-in package shipped with twinBASIC, but the CEF runtime it CEF and [**WebView2**](../WebView2/) both wrap a Chromium-based browser inside a twinBASIC control. CEF brings advantages that matter for some applications: - **Cross-platform ready.** CEF runs on Windows, Linux, and macOS. [**WebView2**](../WebView2/) is Windows-only. -- **Full control over the runtime stack.** The application targets a specific Chromium build and distributes it alongside the software. There is no runtime auto-update behind the developer's back, so behavior stays consistent across deployments. -- **Deeper runtime integration.** CEF allows hosting twinBASIC code inside the renderer / JavaScript process — something the locked-down WebView2 object model cannot do. +- **Full control over the runtime stack.** The application targets a specific Chromium build and distributes it alongside the software. There is no automatic runtime update outside the application's control, so behavior stays consistent across deployments. +- **Deeper runtime integration.** CEF allows hosting twinBASIC code inside the renderer / JavaScript process — something the more restricted WebView2 object model cannot do. -Choose [**WebView2**](../WebView2/) when targeting only modern Windows and willing to rely on the system-installed Edge runtime; choose **CEF** when control over the Chromium version or cross-platform readiness matters. +Choose [**WebView2**](../WebView2/) when targeting only modern Windows and the system-installed Edge runtime is acceptable; choose **CEF** when control over the Chromium version or cross-platform readiness matters. ## Supported runtimes @@ -41,7 +41,7 @@ Three CEF versions are supported, each with a different Chromium baseline and di | **v145** | Windows 10+ | Recommended modern runtime. | > [!WARNING] -> Older Chromium versions should not generally be used for unrestricted internet browsing — they carry unpatched security vulnerabilities. They remain appropriate for tightly controlled environments where the browser loads only trusted local or internal content. +> Older Chromium versions should not generally be used for unrestricted internet browsing — they have unpatched security vulnerabilities. They remain appropriate for tightly controlled environments where the browser loads only trusted local or internal content. The user picks a runtime in two places that must agree: @@ -105,7 +105,7 @@ These [**WebView2**](../WebView2/) features are not yet exposed on **CefBrowser* The [**NavigationComplete**](CefBrowser/#navigationcomplete) event has **IsSuccess** and **WebErrorStatus** parameters in its signature but currently returns placeholder values (`True` and `0`) — the underlying CEF callbacks that would populate them have not yet been connected. -The API will continue to grow; treat this list as a snapshot of the current beta and not a long-term limitation. +The API will continue to grow; this list is a snapshot of the current beta, not a long-term limitation. ## Classes @@ -121,7 +121,7 @@ The API will continue to grow; treat this list as a snapshot of the current beta - [Getting started](../../../Tutorials/CEF/Getting-Started) -- package reference, runtime download, install path - [Customize the UserDataFolder](../../../Tutorials/CEF/Customize-UserDataFolder) -- relocating the runtime's working folder -- [Re-entrancy](../../../Tutorials/CEF/Re-entrancy) -- the deferred-event model and the one place ([**JsRun**](CefBrowser/#jsrun)) you still have to think about it +- [Re-entrancy](../../../Tutorials/CEF/Re-entrancy) -- the deferred-event model and the one place ([**JsRun**](CefBrowser/#jsrun)) that still requires attention - [Building a browser shell](../../../Tutorials/CEF/Building-A-Browser-Shell) -- back / forward / reload / zoom / PDF - [Hosting local web assets](../../../Tutorials/CEF/Hosting-Local-Web-Assets) -- virtual-host folder mappings - [JavaScript interop](../../../Tutorials/CEF/JavaScript-Interop) -- messages and scripted calls between BASIC and the page From 6b2df0d9a8ec460e28d27f452c0e8770f4fe1dfc Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Thu, 14 May 2026 21:57:30 +0200 Subject: [PATCH 05/19] Apply structural style rules to Core --- docs/Reference/Core/AddressOf.md | 8 ++-- docs/Reference/Core/Alias.md | 4 +- docs/Reference/Core/And.md | 2 +- docs/Reference/Core/Call.md | 6 +-- docs/Reference/Core/Class.md | 12 +++--- docs/Reference/Core/Close.md | 10 ++--- docs/Reference/Core/CoClass.md | 6 +-- docs/Reference/Core/Comparison-Operators.md | 2 +- docs/Reference/Core/Const.md | 13 +++--- docs/Reference/Core/Continue.md | 2 +- docs/Reference/Core/Declare.md | 19 +++++---- docs/Reference/Core/Deftype.md | 4 +- docs/Reference/Core/Delegate.md | 8 ++-- docs/Reference/Core/Dim.md | 20 ++++----- docs/Reference/Core/Do-Loop.md | 10 ++--- docs/Reference/Core/End.md | 10 ++--- docs/Reference/Core/Enum.md | 10 ++--- docs/Reference/Core/Erase.md | 4 +- docs/Reference/Core/Event.md | 12 +++--- docs/Reference/Core/Exit.md | 2 +- docs/Reference/Core/For-Each-Next.md | 8 ++-- docs/Reference/Core/For-Next.md | 6 +-- docs/Reference/Core/Function.md | 26 ++++++------ docs/Reference/Core/Get.md | 6 +-- docs/Reference/Core/GoSub-Return.md | 4 +- docs/Reference/Core/Handles.md | 6 +-- docs/Reference/Core/If-Then-Else.md | 8 ++-- docs/Reference/Core/Implements.md | 8 ++-- docs/Reference/Core/Input.md | 6 +-- docs/Reference/Core/Interface.md | 6 +-- docs/Reference/Core/LSet.md | 2 +- docs/Reference/Core/Let.md | 4 +- docs/Reference/Core/Like.md | 2 +- docs/Reference/Core/Load.md | 2 +- docs/Reference/Core/Lock.md | 6 +-- docs/Reference/Core/Mid-equals.md | 2 +- docs/Reference/Core/MidB-equals.md | 2 +- docs/Reference/Core/Module.md | 10 ++--- docs/Reference/Core/Name.md | 2 +- docs/Reference/Core/On-Error.md | 10 ++--- docs/Reference/Core/On-GoTo.md | 2 +- docs/Reference/Core/Open.md | 12 +++--- docs/Reference/Core/Option.md | 10 ++--- docs/Reference/Core/Or.md | 2 +- docs/Reference/Core/ParamArray.md | 4 +- docs/Reference/Core/Plus.md | 4 +- docs/Reference/Core/Print.md | 10 ++--- docs/Reference/Core/Private.md | 14 +++---- docs/Reference/Core/Property.md | 44 ++++++++++---------- docs/Reference/Core/Public.md | 12 +++--- docs/Reference/Core/Put.md | 6 +-- docs/Reference/Core/RaiseEvent.md | 4 +- docs/Reference/Core/ReDim.md | 18 ++++---- docs/Reference/Core/Resume.md | 2 +- docs/Reference/Core/Select-Case.md | 12 +++--- docs/Reference/Core/Set.md | 8 ++-- docs/Reference/Core/Static.md | 15 ++++--- docs/Reference/Core/Stop.md | 2 +- docs/Reference/Core/Sub.md | 46 ++++++++++----------- docs/Reference/Core/Type.md | 16 +++---- docs/Reference/Core/Unlock.md | 2 +- docs/Reference/Core/While-Wend.md | 2 +- docs/Reference/Core/With.md | 12 +++--- docs/Reference/Core/Write.md | 10 ++--- 64 files changed, 277 insertions(+), 282 deletions(-) diff --git a/docs/Reference/Core/AddressOf.md b/docs/Reference/Core/AddressOf.md index f9bd06e..1f4cb35 100644 --- a/docs/Reference/Core/AddressOf.md +++ b/docs/Reference/Core/AddressOf.md @@ -18,16 +18,16 @@ Syntax: : The name of a [**Sub**](Sub), [**Function**](Function), or [**Property**](Property) procedure whose address is taken. *instance* -: *optional* (twinBASIC) An object reference whose member *procedurename* is targeted. The resulting pointer is bound to *instance*, so calling through it invokes the method on that specific object. +: *optional* (twinBASIC) An object reference whose member *procedurename* is targeted. The resulting pointer is bound to *instance*, so calling through it invokes the method on that specific object. -When a procedure name appears in an argument list, normally the procedure is *called* and the procedure's return value is passed. **AddressOf** suppresses the call and substitutes the procedure's address instead. The most common use is to install a callback in a Windows API — the API then invokes the procedure from outside your code, in a process known as a *callback*. +When a procedure name appears in an argument list, normally the procedure is *called* and the procedure's return value is passed. **AddressOf** suppresses the call and substitutes the procedure's address instead. The most common use is to install a callback in a Windows API — the API then invokes the procedure from outside the project's code, in a process known as a *callback*. The value **AddressOf** produces is bit-compatible with **LongPtr**, so it can be passed wherever a function pointer is expected — including legacy [**Declare**](Declare) parameters typed **As Long** or **As LongPtr**. When the destination type is a [**Delegate**](Delegate), the compiler additionally checks that the operand's signature matches the delegate's. In classic VBA, *procedurename* must name a procedure in a standard [**Module**](Module) of the current project; the destination parameter must be typed **As Long**; and the resulting pointer can only be invoked by code outside Basic (e.g. a DLL). twinBASIC lifts each of these restrictions — see [twinBASIC enhancements](#twinbasic-enhancements) below. -> [!NOTE] -> Errors raised inside a callback cannot propagate back to the foreign caller — the API runs outside your project's error-handling chain. Place `On Error Resume Next` (or an explicit handler) at the top of any procedure used as an **AddressOf** target. +> [!IMPORTANT] +> Errors raised inside a callback cannot propagate back to the foreign caller — the API runs outside the project's error-handling chain. Place `On Error Resume Next` (or an explicit handler) at the top of any procedure used as an **AddressOf** target. ### twinBASIC enhancements diff --git a/docs/Reference/Core/Alias.md b/docs/Reference/Core/Alias.md index 21c83dd..c3a883f 100644 --- a/docs/Reference/Core/Alias.md +++ b/docs/Reference/Core/Alias.md @@ -15,10 +15,10 @@ Syntax: > [ **Public** \| **Private** ] **Alias** *aliasname* **As** *type* **Public** -: *optional* The alias is exported to the type library of an ActiveX DLL or control, so consumers in other projects see *aliasname* itself. +: *optional* The alias is exported to the type library of an ActiveX DLL or control, so consumers in other projects see *aliasname* itself. **Private** -: *optional* The alias is visible only within the project. Usages of a **Private** alias are replaced with the underlying *type* during compilation, so *aliasname* never appears in the project's type library. +: *optional* The alias is visible only within the project. Usages of a **Private** alias are replaced with the underlying *type* during compilation, so *aliasname* never appears in the project's type library. *aliasname* : The name of the alias. Must be a valid twinBASIC identifier. diff --git a/docs/Reference/Core/And.md b/docs/Reference/Core/And.md index ba6b038..4c70982 100644 --- a/docs/Reference/Core/And.md +++ b/docs/Reference/Core/And.md @@ -43,7 +43,7 @@ The **And** operator performs a bitwise comparison of identically positioned bit | 1 | 1 | 1 | > [!NOTE] -> **And** evaluates *both* operands every time, even when *expression1* alone determines the result. Use [**AndAlso**](AndAlso) when you want short-circuit evaluation — for example, when *expression2* is expensive, has side effects, or would fail without the guard provided by *expression1*. +> **And** evaluates *both* operands every time, even when *expression1* alone determines the result. Use [**AndAlso**](AndAlso) for short-circuit evaluation — for example, when *expression2* is expensive, has side effects, or would fail without the guard provided by *expression1*. ### Example diff --git a/docs/Reference/Core/Call.md b/docs/Reference/Core/Call.md index 124ee9b..485f295 100644 --- a/docs/Reference/Core/Call.md +++ b/docs/Reference/Core/Call.md @@ -7,7 +7,7 @@ vba_attribution: true # Call -{: no_toc } +{: .no_toc } Transfers control to a **Sub** [procedure](../Gloss#procedure), **Function** procedure, or dynamic-link library (DLL) procedure. @@ -25,9 +25,9 @@ Syntax: : The name of the procedure to call *argumentlist* -: *optional* A comma-delimited list of variables, arrays or expressions to pass to the procedure. Components of *argumentlist* may include the keywords **ByVal** or **ByRef** to describe how the arguments are to be passed to the called procedure. +: *optional* A comma-delimited list of variables, arrays or expressions to pass to the procedure. Components of *argumentlist* may include the keywords **ByVal** or **ByRef** to describe how the arguments are to be passed to the called procedure. -You are not required to use the **Call** keyword when calling a procedure. However, if you use the **Call** keyword to call a procedure that requires arguments, *argumentlist* must be enclosed in parentheses. If you omit the **Call** keyword, you also must omit the parentheses around *argumentlist*. If you use either **Call** syntax to call any intrinsic or user-defined function, the function's return value is discarded. +The **Call** keyword is not required when calling a procedure. However, when the **Call** keyword is used to call a procedure that requires arguments, *argumentlist* must be enclosed in parentheses. When the **Call** keyword is omitted, the parentheses around *argumentlist* must also be omitted. When either **Call** syntax is used to call any intrinsic or user-defined function, the function's return value is discarded. To pass a whole array to a procedure, use the array name followed by empty parentheses. diff --git a/docs/Reference/Core/Class.md b/docs/Reference/Core/Class.md index 4e81716..51e98d8 100644 --- a/docs/Reference/Core/Class.md +++ b/docs/Reference/Core/Class.md @@ -6,9 +6,9 @@ permalink: /tB/Core/Class # Class -{: no_toc } +{: .no_toc } -Used to define a class. Classes are templates from which objects are created -- classes are object types, as opposed to value types. Objects are held by reference and are reference-counted. The memory an object occupies is freed when there are no more references to it -- when no variables in the process refer to them. +Defines a class. Classes are templates from which objects are created — classes are object types, as opposed to value types. Objects are held by reference and are reference-counted. The memory an object occupies is freed when there are no more references to it — when no variables in the process refer to them. Syntax: @@ -24,19 +24,19 @@ Syntax: [ArrayBoundsChecks](Attributes#arrayboundschecks), [ClassId](Attributes#classid), [COMCreatable](Attributes#comcreatable), [CustomControl](Attributes#customcontrol), [Description](Attributes#description), [FloatingPointErrorChecks](Attributes#floatingpointerrorchecks), [FormDesignerId](Attributes#formdesignerid), [Hidden](Attributes#hidden), [IntegerOverflowChecks](Attributes#integeroverflowchecks), [PredeclaredID](Attributes#predeclaredid) **Public** -: *optional* (twinBASIC) In an ActiveX project, marks the class as exported into the type library so that consumers in other projects can create and use it. +: *optional* (twinBASIC) In an ActiveX project, marks the class as exported into the type library so that consumers in other projects can create and use it. **Private** -: *optional* (twinBASIC) In an ActiveX project, withholds the class from the type library: it remains usable within the project but is not exported. The conventional pairing with [**CoClass**](CoClass) — a public **CoClass** as the consumer-visible contract paired with a `Private Class` as the hidden implementation — relies on this modifier. +: *optional* (twinBASIC) In an ActiveX project, withholds the class from the type library: it remains usable within the project but is not exported. The conventional pairing with [**CoClass**](CoClass) — a public **CoClass** as the consumer-visible contract paired with a `Private Class` as the hidden implementation — relies on this modifier. *name* : The identifier naming the class. **Of** *typevars* -: *optional* (twinBASIC) One or more type variable names, separated by commas, that make the class a *generic class*. Each type variable can be referenced in member declarations as if it were a regular type. See [Generics](../../Features/Language/Generics). +: *optional* (twinBASIC) One or more type variable names, separated by commas, that make the class a *generic class*. Each type variable can be referenced in member declarations as if it were a regular type. See [Generics](../../Features/Language/Generics). **Inherits** *baseclass* -: *optional* (twinBASIC) Names a single base class whose **Public** and [**Protected**](Protected) members are inherited by *name*. The **Inherits** line, when present, must appear immediately after the **Class** header and before any other member. **Inherits** enables [**Overridable**](Sub) / **Overrides** members, explicit `*baseclass*.New(...)` chained constructor calls from inside `Sub New`, and **Protected** member visibility. See [Inheritance](../../Features/Language/Inheritance). +: *optional* (twinBASIC) Names a single base class whose **Public** and [**Protected**](Protected) members are inherited by *name*. The **Inherits** line, when present, must appear immediately after the **Class** header and before any other member. **Inherits** enables [**Overridable**](Sub) / **Overrides** members, explicit `*baseclass*.New(...)` chained constructor calls from inside `Sub New`, and **Protected** member visibility. See [Inheritance](../../Features/Language/Inheritance). *classmember* : *optional* Any of the following: diff --git a/docs/Reference/Core/Close.md b/docs/Reference/Core/Close.md index ca8ac84..5ef8ce9 100644 --- a/docs/Reference/Core/Close.md +++ b/docs/Reference/Core/Close.md @@ -8,7 +8,7 @@ vba_attribution: true # Close {: .no_toc } -Concludes input/output (I/O) to a file opened using the **Open** statement. +Concludes input/output (I/O) to a file opened using the **Open** statement. Syntax: @@ -16,15 +16,15 @@ Syntax: The *filenumber* is any valid file number, given as an expression evaluating to an integer. The file numbers do not have to be constant. The **#** prefixes are optional. - **Close** - If you omit *filenumber* list, all active files opened by the **Open** statement are closed. + When the *filenumber* list is omitted, all active files opened by the **Open** statement are closed. > [!WARNING] > -> The parameterless form should be used only when shutting down/exiting the program, since it will close *all* open files that were opened elsewhere in the program. +> The parameterless form should be used only when shutting down/exiting the program, since it closes *all* open files that were opened elsewhere in the program. -When you close files that were opened for **Output** or **Append**, the final buffer of output is written to the operating system buffer for that file. All buffer space associated with the closed file is released. +When files opened for **Output** or **Append** are closed, the final buffer of output is written to the operating system buffer for that file. All buffer space associated with the closed file is released. -When the **Close** statement is executed, the association of a file with its file number ends. +When the **Close** statement is executed, the association of a file with its file number ends. ### Example diff --git a/docs/Reference/Core/CoClass.md b/docs/Reference/Core/CoClass.md index 50578af..13b68c6 100644 --- a/docs/Reference/Core/CoClass.md +++ b/docs/Reference/Core/CoClass.md @@ -19,7 +19,7 @@ Syntax: > **End CoClass** *attributes* -: *optional* Coclass-level attributes. See [Available attributes](#available-attributes) below. +: *optional* Coclass-level attributes. See [Available attributes](#available-attributes) below. *name* : The identifier naming the coclass. @@ -28,7 +28,7 @@ Syntax: : An [**Interface**](Interface) defined in the project (or imported from a referenced type library) that the coclass exposes. A coclass must list at least one interface and may list several. *member-attributes* -: *optional* Per-interface markers, principally: +: *optional* Per-interface markers, principally: - `[Default]` — marks an interface as the default interface of the coclass. It is conventional and highly recommended to mark exactly one interface as `[Default]`. - `[Source]` — marks an interface as a source interface (an outgoing/event interface). Combine with `[Default]` (`[Default, Source]`) to mark the default event interface. @@ -40,7 +40,7 @@ Syntax: - `[CoClassId("...")]` — fixes the CLSID for the coclass (a string GUID). Set this on any public/exported coclass so consumers in other projects bind to a stable identity. - `[Description("text")]` — exposed as the `helpstring` in the type library. - `[ComCreatable(True/False)]` — indicates whether the coclass can be created with **New**. `True` by default. -- `[AppObject]` — marks the class as part of the global namespace. Use only when you fully understand the implication. +- `[AppObject]` — marks the class as part of the global namespace. Use only when the implications are fully understood. - `[Hidden]` — hides the coclass from IntelliSense and similar lists. - `[CoClassCustomConstructor("ModuleName.FunctionName")]` — names a factory function (returning `HRESULT` and producing the new instance via an out parameter) used in place of the default `New` behavior. The factory may construct any private class that implements the coclass's interfaces. diff --git a/docs/Reference/Core/Comparison-Operators.md b/docs/Reference/Core/Comparison-Operators.md index 96ac9bc..190cbee 100644 --- a/docs/Reference/Core/Comparison-Operators.md +++ b/docs/Reference/Core/Comparison-Operators.md @@ -47,7 +47,7 @@ The following table lists the comparison operators and the conditions that deter > [!NOTE] > The [**Is**](Is) and [**Like**](Like) operators have their own dedicated comparison semantics and are documented separately. -The `=` symbol is also the assignment operator (`*variable* = *expression*`). The context — whether `=` appears in an expression or at the top of a statement — determines which meaning applies; you do not need to choose between them explicitly. +The `=` symbol is also the assignment operator (`*variable* = *expression*`). The context — whether `=` appears in an expression or at the top of a statement — determines which meaning applies; no explicit choice between them is required. When comparing two expressions, determining whether they are being compared as numbers or as strings can be non-obvious. The following table shows how the expressions are compared, or the result when either expression is not a **Variant**: diff --git a/docs/Reference/Core/Const.md b/docs/Reference/Core/Const.md index 9e8662f..23eb6ef 100644 --- a/docs/Reference/Core/Const.md +++ b/docs/Reference/Core/Const.md @@ -7,7 +7,7 @@ vba_attribution: true # Const -{: no_toc } +{: .no_toc } Declares constants for use in place of literal values. @@ -24,7 +24,7 @@ Syntax: : *optional* Keyword used at the module level to declare constants that are available to all procedures in all modules. Not allowed in procedures. **Private** -: *optional* Keyword used at the class or module level to declare constants that are available only within the class or module where the declaration is made. Not allowed in procedures. +: *optional* Keyword used at the class or module level to declare constants that are available only within the class or module where the declaration is made. Not allowed in procedures. *constname* @@ -42,14 +42,13 @@ Constants are private by default. Within procedures, constants are always privat To combine several constant declarations on the same line, separate each constant assignment with a comma. When constant declarations are combined in this way, the **Public** or **Private** keyword, if used, applies to all of them. -You can't use variables, user-defined functions, or intrinsic Visual Basic functions (such as **Chr**) in expressions assigned to constants. +Variables, user-defined functions, and intrinsic Visual Basic functions (such as **Chr**) cannot be used in expressions assigned to constants. -> [!NOTE] -> Constants can make your programs self-documenting and easy to modify. Unlike variables, constants can't be inadvertently changed while your program is running. +Constants can make programs self-documenting and easy to modify. Unlike variables, constants can't be inadvertently changed while the program is running. -If you don't explicitly declare the constant type by using **As** *type*, the constant has the data type that is most appropriate for *expression*. +When the constant type is not explicitly declared by using **As** *type*, the constant has the data type that is most appropriate for *expression*. -Constants declared in a **Sub**, **Function**, or **Property** procedure are local to that procedure. A constant declared outside a procedure is defined throughout the module in which it is declared. Use constants anywhere you can use an expression. +Constants declared in a **Sub**, **Function**, or **Property** procedure are local to that procedure. A constant declared outside a procedure is defined throughout the module in which it is declared. Constants can be used anywhere an expression is allowed. ### Example diff --git a/docs/Reference/Core/Continue.md b/docs/Reference/Core/Continue.md index 0504de6..21f5051 100644 --- a/docs/Reference/Core/Continue.md +++ b/docs/Reference/Core/Continue.md @@ -6,7 +6,7 @@ permalink: /tB/Core/Continue # Continue -{: no_toc } +{: .no_toc } Immediately begins the next iteration of the enclosing loop. diff --git a/docs/Reference/Core/Declare.md b/docs/Reference/Core/Declare.md index 4d52354..85fb2ab 100644 --- a/docs/Reference/Core/Declare.md +++ b/docs/Reference/Core/Declare.md @@ -6,8 +6,9 @@ vba_attribution: true --- # Declare +{: .no_toc } -Used at the module level to declare references to external procedures in a dynamic-link library (DLL). +Declares references to external procedures in a dynamic-link library (DLL) at the module level. > [!NOTE] > @@ -30,9 +31,9 @@ Declare Sub... Syntax: - > [ *attributes* ] - > [ **Public** \| **Private** ] **Declare** [ **PtrSafe** ] **Sub** *name* **Lib** "*libname*" [ **(** [ *arglist* ] **)** ] + > [ **Public** \| **Private** ] **Declare** [ **PtrSafe** ] **Sub** *name* **Lib** "*libname*" [ **(** [ *arglist* ] **)** ] - > [ *attributes* ] - > [ **Public** \| **Private** ] **Declare** [ **PtrSafe** ] **Sub** *name* **Lib** "*libname*" **Alias** "*aliasname*" [ **(** [ *arglist* ] **)** ] + > [ **Public** \| **Private** ] **Declare** [ **PtrSafe** ] **Sub** *name* **Lib** "*libname*" **Alias** "*aliasname*" [ **(** [ *arglist* ] **)** ] - > [ *attributes* ] > [ **Public** \| **Private** ] **Declare** [ **PtrSafe** ] **Function** *name* **Lib** "*libname*" [ **(** [ *arglist* ] **)** ] [ **As** *type* ] - > [ *attributes* ] @@ -62,7 +63,7 @@ Syntax: : Name of the DLL or code resource that contains the declared procedure. **Alias** *aliasname* -: *optional* Indicates that the procedure being called has another name in the DLL. This is useful when the external procedure name is the same as a keyword. You can also use Alias when a DLL procedure has the same name as a public variable, constant, or any other procedure in the same scope. Alias is also useful if any characters in the DLL procedure name aren't allowed by the DLL naming convention. +: *optional* Indicates that the procedure being called has another name in the DLL. This is useful when the external procedure name is the same as a keyword. Alias also applies when a DLL procedure has the same name as a public variable, constant, or any other procedure in the same scope. Alias is also useful when any characters in the DLL procedure name aren't allowed by the DLL naming convention. *aliasname* names the procedure in the DLL or code resource. If the first character is not a number sign (**#**), *aliasname* is the name of the procedure's entry point in the DLL. If (**#**) is the first character, all characters that follow must indicate the ordinal number of the procedure's entry point. *arglist* @@ -87,18 +88,18 @@ Syntax: [ **Optional** ] [ **ByVal** \| **ByRef** ] [ **ParamArray** ] *varname* : *optional* Indicates that the argument is passed by reference. **ByRef** is the default unlike in Visual Basic .NET. **ParamArray** -: *optional* Used only as the last argument in arglist to indicate that the final argument is an **Optional** array of **Variant** elements. The **ParamArray** keyword allows you to provide an arbitrary number of arguments. The ParamArray keyword can't be used with **ByVal**, **ByRef**, or **Optional**. +: *optional* Used only as the last argument in arglist to indicate that the final argument is an **Optional** array of **Variant** elements. The **ParamArray** keyword permits passing an arbitrary number of arguments. The ParamArray keyword can't be used with **ByVal**, **ByRef**, or **Optional**. *varname* : Name of the variable representing the argument being passed to the procedure; follows standard variable naming conventions. **( )** -: Required for array variables. Indicates that *varname* is an array. +: Required for array variables. Indicates that *varname* is an array. *type* : *optional* Data type of the argument passed to the procedure; may be **Byte**, **Boolean**, **Integer**, **Long**, **LongLong**, **LongPtr**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (variable length only), **Object**, **Variant**, a user-defined type (UDT), or an object type. (**LongLong** is a valid declared type only on 64-bit platforms.) -If you include an argument list, the number and type of arguments are checked each time the procedure is called. The First sub in the following example takes one **Long** argument, wherease the Second sub takes no arguments: +When an argument list is included, the number and type of arguments are checked each time the procedure is called. The First sub in the following example takes one **Long** argument, whereas the Second sub takes no arguments: ```tb Declare Sub First Lib "MyLib" (X As Long) @@ -107,12 +108,12 @@ Declare Sub Second Lib "MyLib" () > [!NOTE] > -> - You can't have fixed-length strings in the argument list of a **Declare** statement; only variable-length strings can be passed to procedures. Fixed-length strings can appear as procedure arguments, but they are converted to variable-length strings before being passed. +> - Fixed-length strings cannot appear in the argument list of a **Declare** statement; only variable-length strings can be passed to procedures. Fixed-length strings can appear as procedure arguments, but they are converted to variable-length strings before being passed. > - The **vbNullString** constant is used when calling external procedures, where the external procedure requires a string whose value is zero. This is not the same thing as a zero-length string (""). ### Example -This example shows how the **Declare** statement is used at the module level of a standard module to declare a reference to an external procedure in a dynamic-link library (DLL). You can place the **Declare** statements in class modules if the **Declare** statements are **Private**. +This example shows how the **Declare** statement is used at the module level of a standard module to declare a reference to an external procedure in a dynamic-link library (DLL). **Declare** statements can be placed in class modules when they are **Private**. ```tb ' In 32-bit Microsoft Windows systems, specify the library USER32.DLL. diff --git a/docs/Reference/Core/Deftype.md b/docs/Reference/Core/Deftype.md index 2b177c0..efc07c5 100644 --- a/docs/Reference/Core/Deftype.md +++ b/docs/Reference/Core/Deftype.md @@ -61,9 +61,9 @@ Message = "Out of stack space." A **Def**_type_ statement affects only the module where it is used. The default data type for variables, arguments, and return types of items not declared explicitly and not covered by a **Def**_type_ statement is **Variant**. -When you specify a letter range, it usually defines the data type for variables that begin with letters in the first 128 characters of the character set. However, when you specify the range A-Z, you set the default to the specified data type for *all* names, including those starting with characters from the extended part of the character set (128-255). +A letter range usually defines the data type for variables that begin with letters in the first 128 characters of the character set. However, the range A-Z sets the default to the specified data type for *all* names, including those starting with characters from the extended part of the character set (128-255). -After the range A-Z has been specified, you can't further redefine subranges by using **Def**_type_ statements. Once a range has been specified, including a previously defined letter in another **Def**_type_ statement is an error. You can, however, explicitly specify the data type of any variable — defined or not — by using a [**Dim**](Dim) statement with an **As** *type* clause: +After the range A-Z has been specified, subranges cannot be further redefined by using **Def**_type_ statements. Once a range has been specified, including a previously defined letter in another **Def**_type_ statement is an error. The data type of any variable — defined or not — can still be explicitly specified by using a [**Dim**](Dim) statement with an **As** *type* clause: ```tb DefInt A-Z diff --git a/docs/Reference/Core/Delegate.md b/docs/Reference/Core/Delegate.md index e99ec28..0bb962c 100644 --- a/docs/Reference/Core/Delegate.md +++ b/docs/Reference/Core/Delegate.md @@ -15,19 +15,19 @@ Syntax: > [ **Public** \| **Private** ] **Delegate Function** *name* [ **CDecl** ] **(** [ *arglist* ] **)** **As** *type* **Public** -: *optional* In an ActiveX project, exports the delegate type to the type library so consumers in other projects see *name*. +: *optional* In an ActiveX project, exports the delegate type to the type library so consumers in other projects see *name*. **Private** -: *optional* Withholds the delegate from the type library; usable only within the project. +: *optional* Withholds the delegate from the type library; usable only within the project. *name* : The identifier naming the delegate type. Must be a valid twinBASIC identifier. **CDecl** -: *optional* Marks the delegate as using the C calling convention (`cdecl` — caller cleans the stack), used to model callbacks expected by C-runtime APIs such as `qsort`. The default is `stdcall`. See [API Declarations](../../Features/Advanced/API-Declarations#cdecl-callbacks). +: *optional* Marks the delegate as using the C calling convention (`cdecl` — caller cleans the stack), used to model callbacks expected by C-runtime APIs such as `qsort`. The default is `stdcall`. See [API Declarations](../../Features/Advanced/API-Declarations#cdecl-callbacks). *arglist* -: *optional* Parameter signature, written exactly as for a [**Sub**](Sub) or [**Function**](Function) — comma-separated `[ ByVal | ByRef ] [ Optional ] *varname* [ As *type* ]` parts. +: *optional* Parameter signature, written exactly as for a [**Sub**](Sub) or [**Function**](Function) — comma-separated `[ ByVal | ByRef ] [ Optional ] *varname* [ As *type* ]` parts. *type* : Return type of the delegate's signature. diff --git a/docs/Reference/Core/Dim.md b/docs/Reference/Core/Dim.md index e49cbce..a45100f 100644 --- a/docs/Reference/Core/Dim.md +++ b/docs/Reference/Core/Dim.md @@ -6,7 +6,7 @@ vba_attribution: true --- # Dim -{: no_toc } +{: .no_toc } Declares variables and allocates storage space. @@ -14,23 +14,23 @@ Syntax: **Dim** [ **WithEvents** ] *varname* [ **(** [ *subscripts* ] **)** ] [ **WithEvents** -: *optional* Keyword that specifies that *varname* is an object variable used to respond to events triggered by an ActiveX object. **WithEvents** is valid only in class modules. You can declare as many individual variables as you like by using **WithEvents**, but you can't create arrays with **WithEvents**. You can't use **New** with **WithEvents**. +: *optional* Keyword that specifies that *varname* is an object variable used to respond to events triggered by an ActiveX object. **WithEvents** is valid only in class modules. Any number of individual variables may be declared by using **WithEvents**, but arrays cannot be declared with **WithEvents**. **New** cannot be combined with **WithEvents**. *varname* -: Name of the variable; follows standard variable naming conventions. +: Name of the variable; follows standard variable naming conventions. *subscripts* -: *optional* Dimensions of an array variable; up to 60 multiple dimensions may be declared. The *subscripts* argument uses the following syntax: [ *lower* **To** ] *upper* [ , [ *lower* **To** ] *upper* ] **. . .**. When not explicitly stated in *lower*, the lower bound of an array is controlled by the [**Option Base**](Option#Base) statement. The lower bound is zero if no **Option Base** statement is present. +: *optional* Dimensions of an array variable; up to 60 multiple dimensions may be declared. The *subscripts* argument uses the following syntax: [ *lower* **To** ] *upper* [ , [ *lower* **To** ] *upper* ] **. . .**. When not explicitly stated in *lower*, the lower bound of an array is controlled by the [**Option Base**](Option#Base) statement. The lower bound is zero if no **Option Base** statement is present. **New** -: *optional* Keyword that enables implicit creation of an object. If you use **New** when declaring the object variable, a new instance of the object is created on first reference to it, so you don't have to use the **Set** statement to assign the object reference. The **New** keyword can't be used to declare variables of any intrinsic data type or to declare instances of dependent objects, and it can't be used with **WithEvents**. +: *optional* Keyword that enables implicit creation of an object. When **New** is used to declare the object variable, a new instance of the object is created on first reference to it, so the **Set** statement is not required to assign the object reference. The **New** keyword can't be used to declare variables of any intrinsic data type or to declare instances of dependent objects, and it can't be used with **WithEvents**. *type* -: *optional*. Data type of the variable; may be **Byte**, **Boolean**, **Integer**, **Long**, **LongLong**, **LongPtr**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (for variable-length strings), **String** *length* (for fixed-length strings), **Object**, **Variant**, a user-defined type (UDT), an object type, or **Any** (twinBASIC; type is inferred from *expression* — see [Type Inference](../../Features/Language/Type-Inference)). Use a separate **As** *type* clause for each variable you declare. +: *optional*. Data type of the variable; may be **Byte**, **Boolean**, **Integer**, **Long**, **LongLong**, **LongPtr**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (for variable-length strings), **String** *length* (for fixed-length strings), **Object**, **Variant**, a user-defined type (UDT), an object type, or **Any** (twinBASIC; type is inferred from *expression* — see [Type Inference](../../Features/Language/Type-Inference)). Use a separate **As** *type* clause for each declared variable. *expression* @@ -52,13 +52,11 @@ Dim X As New Worksheet If the **New** keyword is not used when declaring an object variable, the variable that refers to the object must be assigned an existing object by using the **Set** statement before it can be used. Until it is assigned an object, the declared object variable has the special value **Nothing**, which indicates that it doesn't refer to any particular instance of an object. -You can also use the **Dim** statement with empty parentheses to declare a dynamic array. After declaring a dynamic array, use the [**ReDim**](ReDim) statement within a procedure to define the number of dimensions and elements in the array. If you try to redeclare a dimension for an array variable whose size was explicitly specified in a [**Private**](Private), [**Public**](Public), or **Dim** statement, an error occurs. +The **Dim** statement with empty parentheses also declares a dynamic array. After declaring a dynamic array, use the [**ReDim**](ReDim) statement within a procedure to define the number of dimensions and elements in the array. Redeclaring a dimension for an array variable whose size was explicitly specified in a [**Private**](Private), [**Public**](Public), or **Dim** statement raises an error. -If you don't specify a data type or object type, and there is no [**Deftype**](Deftype) statement in the module, the variable is **Variant** by default. When variables are initialized, a numeric variable is initialized to 0, a variable-length string is initialized to a zero-length string (""), and a fixed-length string is filled with zeros. **Variant** variables are initialized to Empty. Each element of a user-defined type variable is initialized as if it were a separate variable. +When no data type or object type is specified, and there is no [**Deftype**](Deftype) statement in the module, the variable is **Variant** by default. When variables are initialized, a numeric variable is initialized to 0, a variable-length string is initialized to a zero-length string (""), and a fixed-length string is filled with zeros. **Variant** variables are initialized to Empty. Each element of a user-defined type variable is initialized as if it were a separate variable. -> [!NOTE] -> -> When you use the **Dim** statement in a procedure, you generally put the **Dim** statement at the beginning of the procedure. +By convention, a **Dim** statement inside a procedure is placed at the beginning of the procedure. ### Example diff --git a/docs/Reference/Core/Do-Loop.md b/docs/Reference/Core/Do-Loop.md index 278b4c9..0a029c9 100644 --- a/docs/Reference/Core/Do-Loop.md +++ b/docs/Reference/Core/Do-Loop.md @@ -23,7 +23,7 @@ Syntax: > **Loop** [{ **While** \| **Until** } *condition* ] *condition* -: *optional* Numeric expression or string expression that is **True** or **False**. If *condition* is Null, *condition* is treated as **False**. +: *optional* Numeric expression or string expression that is **True** or **False**. If *condition* is Null, *condition* is treated as **False**. *statements* : One or more statements that are repeated while, or until, *condition* is **True**. @@ -63,9 +63,9 @@ Use **Do...Loop** statements to run a block of statements an indefinite number o ### Repeating statements while a condition is True -There are two ways to use the **While** keyword to check a condition in a **Do...Loop** statement. You can check the condition before you enter the loop, or you can check it after the loop has run at least once. +There are two ways to use the **While** keyword to check a condition in a **Do...Loop** statement. The condition can be checked before entering the loop, or after the loop has run at least once. -In the following `ChkFirstWhile` procedure, you check the condition before you enter the loop. If `myNum` is set to 9 instead of 20, the statements inside the loop will never run. In the `ChkLastWhile` procedure, the statements inside the loop run only once before the condition becomes **False**. +In the following `ChkFirstWhile` procedure, the condition is checked before entering the loop. If `myNum` is set to 9 instead of 20, the statements inside the loop will never run. In the `ChkLastWhile` procedure, the statements inside the loop run only once before the condition becomes **False**. ```tb Sub ChkFirstWhile() @@ -91,7 +91,7 @@ End Sub ### Repeating statements until a condition becomes True -There are two ways to use the **Until** keyword to check a condition in a **Do...Loop** statement. You can check the condition before you enter the loop (as shown in the `ChkFirstUntil` procedure), or you can check it after the loop has run at least once (as shown in the `ChkLastUntil` procedure). Looping continues while the condition remains **False**. +There are two ways to use the **Until** keyword to check a condition in a **Do...Loop** statement. The condition can be checked before entering the loop (as shown in the `ChkFirstUntil` procedure), or after the loop has run at least once (as shown in the `ChkLastUntil` procedure). Looping continues while the condition remains **False**. ```tb Sub ChkFirstUntil() @@ -117,7 +117,7 @@ End Sub ### Exiting a Do...Loop statement from inside the loop -You can exit a **Do...Loop** by using the [**Exit Do**](Exit) statement. For example, to exit an endless loop, use the **Exit Do** statement in the **True** statement block of either an [**If...Then...Else**](If-Then-Else) statement or a [**Select Case**](Select-Case) statement. If the condition is **False**, the loop will run as usual. +The [**Exit Do**](Exit) statement exits a **Do...Loop** from inside. For example, to exit an endless loop, use the **Exit Do** statement in the **True** statement block of either an [**If...Then...Else**](If-Then-Else) statement or a [**Select Case**](Select-Case) statement. If the condition is **False**, the loop will run as usual. In the following example `myNum` is assigned a value that creates an endless loop. The **If...Then...Else** statement checks for this condition, and then exits, preventing endless looping. diff --git a/docs/Reference/Core/End.md b/docs/Reference/Core/End.md index 5aeae3f..62a24a3 100644 --- a/docs/Reference/Core/End.md +++ b/docs/Reference/Core/End.md @@ -34,15 +34,15 @@ Syntax: Required to end a user-defined type (UDT) definition ([**Type**](Type) statement). - **End With** - Required to end a [**With**](With) statement. + Required to end a [**With**](With) statement. -When executed, the **End** statement resets all module-level variables and all static local variables in all modules. To preserve the value of these variables, use the [**Stop**](Stop) statement instead. You can then resume execution while preserving the value of those variables. +When executed, the **End** statement resets all module-level variables and all static local variables in all modules. To preserve the value of these variables, use the [**Stop**](Stop) statement instead — execution can then resume while preserving the value of those variables. -> [!NOTE] +> [!IMPORTANT] > -> The **End** statement stops code execution abruptly, without invoking the Unload, QueryUnload, or Terminate event, or any other Visual Basic code. Code you have placed in the Unload, QueryUnload, and Terminate events of forms and class modules is not executed. Objects created from class modules are destroyed, files opened by using the **Open** statement are closed, and memory used by your program is freed. Object references held by other programs are invalidated. +> The **End** statement stops code execution abruptly, without invoking the Unload, QueryUnload, or Terminate event, or any other Visual Basic code. Code placed in the Unload, QueryUnload, and Terminate events of forms and class modules is not executed. Objects created from class modules are destroyed, files opened by using the **Open** statement are closed, and memory used by the program is freed. Object references held by other programs are invalidated. -The **End** statement provides a way to force your program to halt. For normal termination of a Visual Basic program, you should unload all forms. Your program closes as soon as there are no other programs holding references to objects created from your public class modules and no code executing. +The **End** statement provides a way to force the program to halt. For normal termination of a Visual Basic program, all forms should be unloaded. The program closes as soon as there are no other programs holding references to objects created from public class modules and no code executing. ### Example diff --git a/docs/Reference/Core/Enum.md b/docs/Reference/Core/Enum.md index 202269e..b9e371d 100644 --- a/docs/Reference/Core/Enum.md +++ b/docs/Reference/Core/Enum.md @@ -29,10 +29,10 @@ Syntax: : *optional* Specifies that the **Enum** type is visible only within the module in which it appears. *name* -: The name of the **Enum** type. The *name* must be a valid Visual Basic identifier and is specified as the type when declaring variables or parameters of the **Enum** type. +: The name of the **Enum** type. The *name* must be a valid Visual Basic identifier and is specified as the type when declaring variables or parameters of the **Enum** type. *membername* -: A valid Visual Basic identifier specifying the name by which a constituent element of the **Enum** type will be known. +: A valid Visual Basic identifier specifying the name by which a constituent element of the **Enum** type will be known. *constantexpression* : *optional* Value of the element (evaluates to a **Long**). If no *constantexpression* is specified, the value assigned is either zero (if it is the first *membername* ), or 1 greater than the value of the immediately preceding *membername*. @@ -47,15 +47,15 @@ Enum SecurityLevel End Enum ``` -An **Enum** statement can appear only at the module level. After the **Enum** type is defined, it can be used to declare variables, parameters, or procedures returning its type. You can't qualify an **Enum** type name with a module name. +An **Enum** statement can appear only at the module level. After the **Enum** type is defined, it can be used to declare variables, parameters, or procedures returning its type. An **Enum** type name cannot be qualified with a module name. **Public Enum** types in a class module are not members of the class; however, they are written to the type library. **Enum** types defined in standard modules aren't written to type libraries. **Public Enum** types of the same name can't be defined in both standard modules and class modules because they share the same name space. When two **Enum** types in different type libraries have the same name, but different elements, a reference to a variable of the type depends on which type library has higher priority in the **References**. -You can't use an **Enum** type as the target in a **With** block. +An **Enum** type cannot be used as the target in a **With** block. ### Example -The following example shows the **Enum** statement used to define a collection of named constants. In this case, the constants are colors you might choose to design data entry forms for a database. +The following example shows the **Enum** statement used to define a collection of named constants. In this case, the constants are colors that might be used to design data entry forms for a database. ```tb Public Enum InterfaceColors diff --git a/docs/Reference/Core/Erase.md b/docs/Reference/Core/Erase.md index 2c21a03..6ef0caa 100644 --- a/docs/Reference/Core/Erase.md +++ b/docs/Reference/Core/Erase.md @@ -13,7 +13,7 @@ Reinitializes the elements of fixed-size arrays, or releases dynamic-array stora Syntax: **Erase** *arraylist* *arraylist* -: one or more comma-delimited array variables to be erased +: one or more comma-delimited array variables to be erased **Erase** behaves differently depending on whether an array is fixed-size (ordinary) or dynamic. **Erase** recovers no memory for fixed-size arrays. Erase sets the elements of a fixed array as follows: @@ -26,7 +26,7 @@ Syntax: **Erase** *arraylist* | Array of user-defined types | Sets each element as if it were a separate variable. | | Array of objects | Sets each element to the special value **Nothing**. | -**Erase** frees the memory used by dynamic arrays. Before your program can refer to the dynamic array again, it must redeclare the array variable's dimensions by using a ReDim statement. +**Erase** frees the memory used by dynamic arrays. Before the program can refer to the dynamic array again, it must redeclare the array variable's dimensions by using a ReDim statement. ### Example This example uses the **Erase** statement to reinitialize the elements of fixed-size arrays and deallocate dynamic-array storage space. diff --git a/docs/Reference/Core/Event.md b/docs/Reference/Core/Event.md index c6c85a4..84d8b74 100644 --- a/docs/Reference/Core/Event.md +++ b/docs/Reference/Core/Event.md @@ -15,16 +15,16 @@ Syntax: [ **Public** ] **Event** *procedurename* [ (*arglist*) ] : Name of the event; follows standard variable naming conventions. *arglist* -: [ **ByVal** \| **ByRef** ] *varname* \[ **()** ] [ **As** *type* ] +: [ **ByVal** \| **ByRef** ] *varname* \[ **()** ] [ **As** *type* ] **ByVal** : *optional* Indicates that the argument is passed by value. **ByRef** - : *optional* Indicates that the argument is passed by reference. **ByRef** is the default in unlike in Visual Basic .NET. + : *optional* Indicates that the argument is passed by reference. **ByRef** is the default, unlike in Visual Basic .NET. *varname* - : Name of the variable representing the argument being passed to the procedure; follows standard variable naming conventions. + : Name of the variable representing the argument being passed to the procedure; follows standard variable naming conventions. *type* : *optional* Data type of the argument passed to the procedure; may be Byte, Boolean, Integer, Long, Currency, Single, Double, Decimal, Date, String (variable length only), Object, Variant, a user-defined type (UDT), or an object type. @@ -41,9 +41,7 @@ Sub End Sub ``` -> [!NOTE] -> -> You can declare event arguments just as you do arguments of procedures, with the following exceptions: events cannot have named arguments, **Optional** arguments, or **ParamArray** arguments. Events don't have return values. +Event arguments are declared the same way as procedure arguments, with the following exceptions: events cannot have named arguments, **Optional** arguments, or **ParamArray** arguments. Events don't have return values. ### Example @@ -51,7 +49,7 @@ The following example uses events to count off seconds during a demonstration of The class that raises an event is the event source, and the classes that implement the event are the sinks. An event source can have multiple sinks for the events it generates. When the class raises the event, that event is fired on every class that has elected to sink events for that instance of the object. -The example also uses a form (`Form1`) with a button (`Command1`), a label (`Label1`), and two text boxes (`Text1` and `Text2`). When you click the button, the first text box displays "From Now" and the second starts to count seconds. When the full time (9.84 seconds) has elapsed, the first text box displays "Until Now" and the second displays "9.84". +The example also uses a form (`Form1`) with a button (`Command1`), a label (`Label1`), and two text boxes (`Text1` and `Text2`). When the button is clicked, the first text box displays "From Now" and the second starts to count seconds. When the full time (9.84 seconds) has elapsed, the first text box displays "Until Now" and the second displays "9.84". The code specifies the initial and terminal states of the form. It also contains the code executed when events are raised. diff --git a/docs/Reference/Core/Exit.md b/docs/Reference/Core/Exit.md index f010fe4..48abadb 100644 --- a/docs/Reference/Core/Exit.md +++ b/docs/Reference/Core/Exit.md @@ -7,7 +7,7 @@ vba_attribution: true # Exit {: .no_toc } -Exits a block of **Do…Loop**, **For…Next**, **While...Wend**, **Function**, **Sub**, or **Property** code. +Exits a block of **Do…Loop**, **For…Next**, **While...Wend**, **Function**, **Sub**, or **Property** code. Syntax: diff --git a/docs/Reference/Core/For-Each-Next.md b/docs/Reference/Core/For-Each-Next.md index 29897f4..f3b593c 100644 --- a/docs/Reference/Core/For-Each-Next.md +++ b/docs/Reference/Core/For-Each-Next.md @@ -25,7 +25,7 @@ Syntax: When present it is equivalent to placing `Dim element As type` immediately before the **For Each** statement. *group* -: Name of an object collection or array (except an array of user-defined types (UDTs)). +: Name of an object collection or array (except an array of user-defined types (UDTs)). *statements* : *optional* One or more statements that are executed on each item in *group*. @@ -40,13 +40,13 @@ Syntax: The **For…Each** block is entered if there is at least one element in *group*. After the loop has been entered, all the statements in the loop are executed for the first element in *group*. If there are more elements in *group*, the statements in the loop continue to execute for each element. When there are no more elements in *group*, the loop is exited and execution continues with the statement following the **Next** statement. -You can nest **For...Each...Next** loops by placing one **For…Each…Next** loop within another. However, each loop *element* must be unique. +**For...Each...Next** loops can be nested by placing one **For…Each…Next** loop within another. However, each loop *element* must be unique. > [!NOTE] > -> If you omit *element* in a **Next** statement, execution continues as if *element* is included. If a **Next** statement is encountered before its corresponding **For** statement, an error occurs. +> When *element* is omitted in a **Next** statement, execution continues as if *element* is included. If a **Next** statement is encountered before its corresponding **For** statement, an error occurs. -You can't use the **For...Each...Next** statement with an array of user-defined types because a **Variant** can't contain a user-defined type. +The **For...Each...Next** statement cannot be used with an array of user-defined types because a **Variant** can't contain a user-defined type. ### Example diff --git a/docs/Reference/Core/For-Next.md b/docs/Reference/Core/For-Next.md index 1d63350..4e5e6b0 100644 --- a/docs/Reference/Core/For-Next.md +++ b/docs/Reference/Core/For-Next.md @@ -56,9 +56,9 @@ After all statements in the loop have executed, *step* is added to *counter*. At > [!TIP] > -> Changing the value of *counter* while inside a loop can make it more difficult to read and debug your code. +> Changing the value of *counter* while inside a loop can make code harder to read and debug. -You can nest **For...Next** loops by placing one **For...Next** loop within another. Give each loop a unique variable name as its *counter*. The following construction is correct: +**For...Next** loops can be nested by placing one **For...Next** loop within another. Give each loop a unique variable name as its *counter*. The following construction is correct: ```tb For I = 1 To 10 @@ -72,7 +72,7 @@ Next I > [!NOTE] > -> If you omit *counter* in a **Next** statement, execution continues as if *counter* is included. If a **Next** statement is encountered before its corresponding **For** statement, an error occurs. +> When *counter* is omitted in a **Next** statement, execution continues as if *counter* is included. If a **Next** statement is encountered before its corresponding **For** statement, an error occurs. ### Example diff --git a/docs/Reference/Core/Function.md b/docs/Reference/Core/Function.md index 897e07a..8d103fe 100644 --- a/docs/Reference/Core/Function.md +++ b/docs/Reference/Core/Function.md @@ -34,16 +34,16 @@ Syntax: : *optional* Used only in a class module. Indicates that the **Function** procedure is visible throughout the project, but not visible to a controller of an instance of an object. **[Protected](Protected)** -: *optional* (twinBASIC) Used only in a class. Indicates that the **Function** procedure is accessible from inside the declaring class and from classes that derive from it via [**Inherits**](../../Features/Language/Inheritance#inherits-for-complete-oop), but not from outside callers. +: *optional* (twinBASIC) Used only in a class. Indicates that the **Function** procedure is accessible from inside the declaring class and from classes that derive from it via [**Inherits**](../../Features/Language/Inheritance#inherits-for-complete-oop), but not from outside callers. **Static** : *optional* Indicates that the **Function** procedure's local variables are preserved between calls. The **Static** attribute doesn't affect variables that are declared outside the **Function**, even if they are used in the procedure. **Overridable** -: *optional* (twinBASIC) Marks the **Function** as an inheritance hook that classes derived via [**Inherits**](../../Features/Language/Inheritance#inherits-for-complete-oop) may replace with an **Overrides** clause. Meaningful only on a member of a class that participates in an **Inherits** hierarchy. +: *optional* (twinBASIC) Marks the **Function** as an inheritance hook that classes derived via [**Inherits**](../../Features/Language/Inheritance#inherits-for-complete-oop) may replace with an **Overrides** clause. Meaningful only on a member of a class that participates in an **Inherits** hierarchy. *name* -: Name of the **Function**; follows standard variable naming conventions. +: Name of the **Function**; follows standard variable naming conventions. **Of** *typevars* : *optional* One or more type variable names; following standard variable naming conventions. The names are separated by commas. Causes the function to be a generic function. @@ -55,10 +55,10 @@ Syntax: : *optional* Data type of the value returned by the **Function** procedure; may be Byte, Boolean, Integer, Long, Currency, Single, Double, Decimal, Date, String (except fixed length), Object, Variant, or any user-defined type (UDT). *binding-clause* -: *optional* (twinBASIC) One of three trailing clauses that bind this body to a member declared elsewhere: +: *optional* (twinBASIC) One of three trailing clauses that bind this body to a member declared elsewhere: - - **Handles** *object*.*event* [ **,** *object*.*event* … ] — wires this **Function** up as a handler for the named event(s), replacing the traditional `Object_Event` naming convention. See [**Handles** statement](Handles). - - **Implements** *iface*.*member* [ **,** *iface2*.*member2* … ] — provides the body for the named [**Interface**](Interface) (or [**Class**](Class)) member, replacing the traditional `Iface_Member` naming convention. A comma-separated list lets one body satisfy several interfaces' members at once. See [**Implements** statement](Implements). + - **Handles** *object*.*event* [ **,** *object*.*event* … ] — connects this **Function** as a handler for the named event(s), replacing the traditional `Object_Event` naming convention. See [**Handles** statement](Handles). + - **Implements** *iface*.*member* [ **,** *iface2*.*member2* … ] — provides the body for the named [**Interface**](Interface) (or [**Class**](Class)) member, replacing the traditional `Iface_Member` naming convention. A comma-separated list permits one body to satisfy several interfaces' members at once. See [**Implements** statement](Implements). - **Overrides** *base*.*member* — supplies the body for an **Overridable** *member* inherited via [**Inherits**](../../Features/Language/Inheritance#inherits-for-complete-oop). Combine with **Overridable** on the same header to allow further-derived classes to override again. *statements* @@ -74,7 +74,7 @@ Syntax: : *optional* Immediately returns from the function with *expression* as the return value. The *expression* is required in this form; a bare **Return** is reserved for the [**GoSub...Return**](GoSub-Return) construct and does not exit a **Function**. **[Exit Function](Exit)** -: *optional* Immediately returns from the function without setting a return value. Use this to leave a function early when no value needs to be returned (the function will yield its default return value: 0 for numeric types, `""` for strings, **Empty** for **Variant**, **Nothing** for object references). +: *optional* Immediately returns from the function without setting a return value. Used to leave a function early when no value needs to be returned (the function will yield its default return value: 0 for numeric types, `""` for strings, **Empty** for **Variant**, **Nothing** for object references). *expression* : *optional* Return value of the **Function**. @@ -94,7 +94,7 @@ Syntax: One or more of : *optional* Indicates that the argument is passed by reference. **ByRef** is the default unlike in Visual Basic .NET. **ParamArray** -: *optional* Used only as the last argument in *arglist* to indicate that the final argument is an **Optional** array of **Variant** elements. The **ParamArray** keyword allows you to provide an arbitrary number of arguments. It may not be used with **ByVal**, **ByRef**, or **Optional**. +: *optional* Used only as the last argument in *arglist* to indicate that the final argument is an **Optional** array of **Variant** elements. The **ParamArray** keyword permits passing an arbitrary number of arguments. It may not be used with **ByVal**, **ByRef**, or **Optional**. *varname* : Name of the variable representing the argument; follows standard variable naming conventions. @@ -114,13 +114,13 @@ The **Friend** keyword can only be used in class modules. However, **Friend** pr **Function** procedures can be recursive; that is, they can call themselves to perform a given task. However, recursion can lead to stack overflow. The **Static** keyword usually isn't used with recursive **Function** procedures. -All executable code must be in procedures. You can't define a **Function** procedure inside another **Function**, **[Sub](Sub)**, or **[Property](Property)** procedure. +All executable code must be in procedures. A **Function** procedure cannot be defined inside another **Function**, **[Sub](Sub)**, or **[Property](Property)** procedure. -The **[Exit Function](Exit)** statement and the **[Return](Return)** *expression* statement both cause an immediate exit from a **Function** procedure. Program execution continues with the statement following the statement that called the **Function** procedure. Any number of these statements can appear anywhere in a **Function** procedure. Use **Exit Function** when you've already assigned the return value (or want the default), and **Return** *expression* when you want to set the return value and exit in a single step. +The **[Exit Function](Exit)** statement and the **[Return](Return)** *expression* statement both cause an immediate exit from a **Function** procedure. Program execution continues with the statement following the statement that called the **Function** procedure. Any number of these statements can appear anywhere in a **Function** procedure. Use **Exit Function** when the return value has already been assigned (or the default is wanted), and **Return** *expression* to set the return value and exit in a single step. -Like a **Sub** procedure, a **Function** procedure is a separate procedure that can take arguments, perform a series of statements, and change the values of its arguments. However, unlike a **Sub** procedure, you can use a **Function** procedure on the right side of an expression in the same way you use any intrinsic function, such as **Sqr**, **Cos**, or **Chr**, when you want to use the value returned by the function. +Like a **Sub** procedure, a **Function** procedure is a separate procedure that can take arguments, perform a series of statements, and change the values of its arguments. However, unlike a **Sub** procedure, a **Function** procedure can appear on the right side of an expression in the same way as any intrinsic function — such as **Sqr**, **Cos**, or **Chr** — when the value returned by the function is needed. -You call a **Function** procedure by using the function name, followed by the argument list in parentheses, in an expression. See the **[Call](Call)** statement for specific information about how to call **Function** procedures. +A **Function** procedure is called by using the function name, followed by the argument list in parentheses, in an expression. See the **[Call](Call)** statement for specific information about how to call **Function** procedures. To return a value from a function, assign the value to the function name, or provide it as an argument to the **Return** statement. Any number of such assignments and **Return** statements can appear anywhere within the procedure. If no value is assigned to *name*, the procedure returns a default value: a numeric function returns 0, a string function returns a zero-length string (""), and a **Variant** function returns **Empty**. A function that returns an object reference returns **Nothing** if no object reference is assigned to *name* (using **Set** or **Return**) within the **Function**. @@ -142,7 +142,7 @@ Variables used in **Function** procedures fall into two categories: those that a Variables that are explicitly declared in a procedure (using **Dim** or the equivalent) are always local to the procedure. Variables that are used but not explicitly declared in a procedure are also local unless they are explicitly declared at some higher level outside the procedure. -A procedure can use a variable that is not explicitly declared in the procedure, but a naming conflict can occur if anything you defined at the module level has the same name. If your procedure refers to an undeclared variable that has the same name as another procedure, constant, or variable, it is assumed that your procedure refers to that module-level name. Explicitly declare variables to avoid this kind of conflict. Use an **[Option Explicit](Option#Explicit)** statement to force explicit declaration of variables. +A procedure can use a variable that is not explicitly declared in the procedure, but a naming conflict can occur if anything defined at the module level has the same name. When a procedure refers to an undeclared variable that has the same name as another procedure, constant, or variable, it is assumed that the procedure refers to that module-level name. Explicitly declare variables to avoid this kind of conflict. Use an **[Option Explicit](Option#Explicit)** statement to force explicit declaration of variables. Visual Basic may rearrange arithmetic expressions to increase internal efficiency. Avoid using a **Function** procedure in an arithmetic expression when the function changes the value of variables in the same expression. For more information about arithmetic operators, see Operators. diff --git a/docs/Reference/Core/Get.md b/docs/Reference/Core/Get.md index e9ea92f..f1f7c20 100644 --- a/docs/Reference/Core/Get.md +++ b/docs/Reference/Core/Get.md @@ -19,12 +19,12 @@ Syntax: : Any valid file number. *recnumber* -: *optional* **Variant** (**Long**). Record number (**Random** mode files) or byte number (**Binary** mode files) at which reading begins. +: *optional* **Variant** (**Long**). Record number (**Random** mode files) or byte number (**Binary** mode files) at which reading begins. *varname* : Valid variable name into which data is read. -Data read with **Get** is usually written to a file with [**Put**](Put). The first record or byte in a file is at position 1, the second record or byte is at position 2, and so on. If you omit *recnumber*, the next record or byte following the last **Get** or **Put** statement (or pointed to by the last [**Seek**](../Modules/FileSystem/Seek) function) is read. You must include the delimiting commas: +Data read with **Get** is usually written to a file with [**Put**](Put). The first record or byte in a file is at position 1, the second record or byte is at position 2, and so on. When *recnumber* is omitted, the next record or byte following the last **Get** or **Put** statement (or pointed to by the last [**Seek**](../Modules/FileSystem/Seek) function) is read. The delimiting commas must be included: ```tb Get #4, , FileBuffer @@ -39,7 +39,7 @@ For files opened in **Random** mode, the following rules apply: - If the variable being read into is a **Variant** of numeric type, **Get** reads 2 bytes identifying the **VarType** of the **Variant** and then the data that goes into the variable. For example, when reading a **Variant** of **VarType** 3, **Get** reads 6 bytes: 2 bytes identifying the **Variant** as **VarType** 3 (**Long**) and 4 bytes containing the **Long** data. The record length specified by the **Len** clause in the **Open** statement must be at least 2 bytes greater than the actual number of bytes required to store the variable. > [!NOTE] - > Use the **Get** statement to read a **Variant** array from disk, but you can't use **Get** to read a scalar **Variant** containing an array. You also can't use **Get** to read objects from disk. + > Use the **Get** statement to read a **Variant** array from disk; **Get** cannot read a scalar **Variant** containing an array. **Get** also cannot read objects from disk. - If the variable being read into is a **Variant** of **VarType** 8 (**String**), **Get** reads 2 bytes identifying the **VarType**, 2 bytes indicating the length of the string, and then reads the string data. The record length specified by the **Len** clause in the **Open** statement must be at least 4 bytes greater than the actual length of the string. diff --git a/docs/Reference/Core/GoSub-Return.md b/docs/Reference/Core/GoSub-Return.md index 3ca1d14..8d8a519 100644 --- a/docs/Reference/Core/GoSub-Return.md +++ b/docs/Reference/Core/GoSub-Return.md @@ -22,10 +22,10 @@ Syntax: Use **GoSub** and **Return** anywhere in a procedure, but **GoSub** and the corresponding **Return** statement must be in the same procedure. A subroutine can contain more than one **Return** statement, but the first **Return** statement encountered causes the flow of execution to branch back to the statement immediately following the most recently executed **GoSub** statement. > [!NOTE] -> You can't enter or exit [**Sub**](Sub) procedures with **GoSub...Return**. +> **GoSub...Return** cannot enter or exit [**Sub**](Sub) procedures. > [!TIP] -> Creating separate procedures that you can call may provide a more structured alternative to using **GoSub...Return**. +> Creating separate callable procedures may provide a more structured alternative to using **GoSub...Return**. ### Example diff --git a/docs/Reference/Core/Handles.md b/docs/Reference/Core/Handles.md index b0d09a4..d8abba3 100644 --- a/docs/Reference/Core/Handles.md +++ b/docs/Reference/Core/Handles.md @@ -25,9 +25,9 @@ Syntax: The procedure's parameter list must match the signatures of every event it handles. When several events are listed they must all share the same signature, so one body can service them interchangeably. -Because **Handles** decouples the procedure's name from the events it handles, you can: +Because **Handles** decouples the procedure's name from the events it handles, the procedure can: -- give the procedure a descriptive name (`OnLoad`, `SyncOpacity`) instead of the compound `_` form; +- have a descriptive name (`OnLoad`, `SyncOpacity`) instead of the compound `_` form; - factor several related event handlers into a single body without duplicating code; and - handle an event from a procedure whose name happens to collide with the implicit naming pattern. @@ -63,7 +63,7 @@ Private Sub BackColor_OnPropertyLet() End Sub ``` -— and you would need a separate procedure body per event. +— a separate procedure body would be required per event. ### See Also diff --git a/docs/Reference/Core/If-Then-Else.md b/docs/Reference/Core/If-Then-Else.md index 98bd9f8..cf12f14 100644 --- a/docs/Reference/Core/If-Then-Else.md +++ b/docs/Reference/Core/If-Then-Else.md @@ -30,13 +30,13 @@ Syntax: : Optional in block form; required in single-line form that has no **Else** clause. One or more statements separated by colons; executed if *condition* is **True**. *condition-n* -: *optional* Same as *condition*. +: *optional* Same as *condition*. *elseifstatements* -: *optional* One or more statements executed if the associated *condition-n* is **True**. +: *optional* One or more statements executed if the associated *condition-n* is **True**. *elsestatements* -: *optional* One or more statements executed if no previous *condition* or *condition-n* expression is **True**. +: *optional* One or more statements executed if no previous *condition* or *condition-n* expression is **True**. Use the single-line form (first syntax) for short, simple tests. The block form (second syntax) provides more structure and flexibility than the single-line form and is usually easier to read, maintain, and debug. @@ -51,7 +51,7 @@ A block form **If** statement must be the first statement on a line. The **Else* To determine whether or not a statement is a block **If**, examine what follows the **Then** keyword. If anything other than a comment appears after **Then** on the same line, the statement is treated as a single-line **If** statement. -The **Else** and **ElseIf** clauses are both optional. You can have as many **ElseIf** clauses as you want in a block **If**, but none can appear after an **Else** clause. Block **If** statements can be nested; that is, contained within one another. +The **Else** and **ElseIf** clauses are both optional. A block **If** can have any number of **ElseIf** clauses, but none can appear after an **Else** clause. Block **If** statements can be nested; that is, contained within one another. When executing a block **If** (second syntax), *condition* is tested. If *condition* is **True**, the statements following **Then** are executed. If *condition* is **False**, each **ElseIf** condition (if any) is evaluated in turn. When a **True** condition is found, the statements immediately following the associated **Then** are executed. If none of the **ElseIf** conditions are **True** (or if there are no **ElseIf** clauses), the statements following **Else** are executed. After executing the statements following **Then** or **Else**, execution continues with the statement following **End If**. diff --git a/docs/Reference/Core/Implements.md b/docs/Reference/Core/Implements.md index d6f4543..9462803 100644 --- a/docs/Reference/Core/Implements.md +++ b/docs/Reference/Core/Implements.md @@ -22,9 +22,9 @@ A single **Implements** statement can list several interfaces or classes separat An *interface* is a collection of prototypes representing the members (methods and properties) that the interface encapsulates; that is, it contains only the declarations for the member procedures. A *class* provides an implementation of all the methods and properties of one or more interfaces. Classes provide the code used when each function is called by a controller of the class. All classes implement at least one interface, which is considered the default interface of the class. Any member that isn't explicitly a member of an implemented interface is implicitly a member of the default interface. -When a class implements an interface, the class provides its own versions of all the **Public** procedures specified in the interface. In addition to providing a mapping between the interface prototypes and your procedures, the **Implements** statement causes the class to accept COM `QueryInterface` calls for the specified interface ID. +When a class implements an interface, the class provides its own versions of all the **Public** procedures specified in the interface. In addition to providing a mapping between the interface prototypes and the implementing procedures, the **Implements** statement causes the class to accept COM `QueryInterface` calls for the specified interface ID. -When you implement an interface or class, you must include all the **Public** procedures involved. A missing member in an implementation of an interface or class causes an error. If you don't place code in one of the procedures in a class you are implementing, you can raise the appropriate error (`Const E_NOTIMPL = &H80004001`) so a user of the implementation understands that a member is not implemented. +When implementing an interface or class, all the **Public** procedures involved must be included. A missing member in an implementation of an interface or class causes an error. When code is not placed in one of the implemented procedures, raise the appropriate error (`Const E_NOTIMPL = &H80004001`) so a user of the implementation understands that a member is not implemented. The **Implements** statement can't appear in a standard module — it is valid only in a [**Class**](Class) block. @@ -34,7 +34,7 @@ twinBASIC extends classic VBA's **Implements** in several ways. See [Inheritance - **Comma-separated list** — one **Implements** statement can name multiple interfaces or classes, e.g. `Implements IFoo, IBar, IBaz`. Classic VBA requires a separate **Implements** statement for each. - **Inherited interfaces** — `Implements` works directly on a derived interface (e.g. `Implements IFoo2` where `Interface IFoo2 Extends IFoo`). The class need not name `IFoo` separately; `QueryInterface` for the base is satisfied automatically. Classic VBA does not support implementing derived interfaces. -- **Multiple-implementation form** — a single member can implement methods on several interfaces at once via `Implements ., ., …` after the procedure header. This is useful when several interfaces declare the same member and you want one body to satisfy all of them. +- **Multiple-implementation form** — a single member can implement methods on several interfaces at once via `Implements ., ., …` after the procedure header. This is useful when several interfaces declare the same member and one body should satisfy all of them. - **`As Any` parameters** — interfaces declared with `As Any` parameters can be implemented (substituting `As LongPtr` for `As Any` in the implementing class). Classic VBA rejects this. > [!NOTE] @@ -42,7 +42,7 @@ twinBASIC extends classic VBA's **Implements** in several ways. See [Inheritance ### Example -The following example shows how to use the **Implements** statement to make a set of declarations available to multiple classes. By sharing the declarations through the **Implements** statement, neither class has to make any declarations itself. The example also shows how use of an interface allows abstraction: a strongly-typed variable can be declared by using the interface type. It can then be assigned objects of different class types that implement the interface. +The following example shows how to use the **Implements** statement to make a set of declarations available to multiple classes. By sharing the declarations through the **Implements** statement, neither class has to make any declarations itself. The example also shows how use of an interface supports abstraction: a strongly-typed variable can be declared by using the interface type. It can then be assigned objects of different class types that implement the interface. The interface declarations are in a class called `PersonalData`: diff --git a/docs/Reference/Core/Input.md b/docs/Reference/Core/Input.md index 97e75a2..e487865 100644 --- a/docs/Reference/Core/Input.md +++ b/docs/Reference/Core/Input.md @@ -35,12 +35,12 @@ The following table illustrates how other input data is treated: Double quotation marks (`"`) within input data are ignored. -> [!NOTE] -> You should not write strings that contain embedded quotation marks (for example, `"1,2""X"`) for use with the **Input #** statement; **Input #** parses this string as two complete and separate strings. +> [!IMPORTANT] +> Do not write strings that contain embedded quotation marks (for example, `"1,2""X"`) for use with the **Input #** statement; **Input #** parses this string as two complete and separate strings. Data items in a file must appear in the same order as the variables in *varlist* and match variables of the same data type. If a variable is numeric and the data is not numeric, a value of zero is assigned to the variable. -If you reach the end of the file while you are inputting a data item, the input is terminated and an error occurs. +If the end of the file is reached while a data item is being read, the input is terminated and an error occurs. > [!NOTE] > To be able to correctly read data from a file into variables by using **Input #**, use the [**Write #**](Write) statement instead of the [**Print #**](Print) statement to write the data to the files. Using **Write #** ensures that each separate data field is properly delimited. diff --git a/docs/Reference/Core/Interface.md b/docs/Reference/Core/Interface.md index a33608d..38879b5 100644 --- a/docs/Reference/Core/Interface.md +++ b/docs/Reference/Core/Interface.md @@ -20,13 +20,13 @@ Syntax: > **End Interface** *attributes* -: *optional* Interface- and member-level attributes. See [Available attributes](#available-attributes) below. +: *optional* Interface- and member-level attributes. See [Available attributes](#available-attributes) below. *name* : The identifier naming the interface. By convention an interface name begins with an uppercase `I` (`IFoo`, `ICalculator`, ...). *baseinterface* -: *optional* One or more interfaces that *name* extends. An implementing class is required to provide bodies for the inherited methods as well; in twinBASIC, you can `Implements` *name* and rely on the inherited interfaces being satisfied automatically. +: *optional* One or more interfaces that *name* extends. An implementing class is required to provide bodies for the inherited methods as well; in twinBASIC, a class can `Implements` *name* and rely on the inherited interfaces being satisfied automatically. *member-prototype* : A header-only declaration. May be a [**Sub**](Sub), [**Function**](Function), [**Property Get**](Property), [**Property Let**](Property), or [**Property Set**](Property) signature, with arguments and return type. **Public**/**Private**/**Friend** modifiers are *not* allowed on members. There is no `End Sub` / `End Function` / `End Property` — the prototype ends at end of line. @@ -48,7 +48,7 @@ Interface-level attributes: Member-level attributes: - `[Description("text")]` -- `[PreserveSig]` — keeps the raw COM signature (returning `HRESULT`) instead of having the runtime translate negative results into errors. Use this when you need the literal return value, or when negative values mean *acceptable failure* (e.g. an enumerator running out of items). +- `[PreserveSig]` — keeps the raw COM signature (returning `HRESULT`) instead of having the runtime translate negative results into errors. Use this when the literal return value is required, or when negative values mean *acceptable failure* (e.g. an enumerator running out of items). - `[DispId(number)]` — fixes the dispatch ID associated with the member. ### Example diff --git a/docs/Reference/Core/LSet.md b/docs/Reference/Core/LSet.md index dd71bd0..149375e 100644 --- a/docs/Reference/Core/LSet.md +++ b/docs/Reference/Core/LSet.md @@ -30,7 +30,7 @@ Syntax: If *string* is longer than *stringvar*, **LSet** places only the leftmost characters, up to the length of the *stringvar*, in *stringvar*. > [!WARNING] -> Using **LSet** to copy a variable of one user-defined type into a variable of a different user-defined type is not recommended. Copying data of one data type into space reserved for a different data type can cause unpredictable results. When you copy a variable from one user-defined type to another, the binary data from one variable is copied into the memory space of the other, without regard for the data types specified for the elements. +> Using **LSet** to copy a variable of one user-defined type into a variable of a different user-defined type is not recommended. Copying data of one data type into space reserved for a different data type can cause unpredictable results. When a variable is copied from one user-defined type to another, the binary data from one variable is copied into the memory space of the other, without regard for the data types specified for the elements. ### Example diff --git a/docs/Reference/Core/Let.md b/docs/Reference/Core/Let.md index 7dd332c..ca80e2b 100644 --- a/docs/Reference/Core/Let.md +++ b/docs/Reference/Core/Let.md @@ -13,7 +13,7 @@ Syntax: > [ **Let** ] *varname* **=** *expression* **Let** -: *optional* Explicit use of the **Let** keyword is a matter of style; it is usually omitted. +: *optional* Explicit use of the **Let** keyword is a matter of style; it is usually omitted. *varname* : Name of the variable or property; follows standard variable naming conventions. @@ -21,7 +21,7 @@ Syntax: *expression* : Value assigned to the variable or property. -A value expression can be assigned to a variable or property only if it is of a data type that is compatible with the variable. You can't assign string expressions to numeric variables, and you can't assign numeric expressions to string variables. If you do, an error occurs at compile time. +A value expression can be assigned to a variable or property only if it is of a data type that is compatible with the variable. String expressions cannot be assigned to numeric variables, and numeric expressions cannot be assigned to string variables. Such an assignment raises an error at compile time. **Variant** variables can be assigned to either string or numeric expressions. However, the reverse is not always true. Any **Variant** except a **Null** can be assigned to a string variable, but only a **Variant** whose value can be interpreted as a number can be assigned to a numeric variable. Use the **IsNumeric** function to determine if the **Variant** can be converted to a number. diff --git a/docs/Reference/Core/Like.md b/docs/Reference/Core/Like.md index 198bcdb..e2b11de 100644 --- a/docs/Reference/Core/Like.md +++ b/docs/Reference/Core/Like.md @@ -34,7 +34,7 @@ Under **Option Compare Text** the same characters compare equal up to case and a `(A=a) < (À=à) < (B=b) < (E=e) < (Ê=ê) < (Z=z) < (Ø=ø)` -The pattern-matching syntax allows wildcards, character lists, and character ranges. The following characters in *pattern* have special meaning: +The pattern-matching syntax supports wildcards, character lists, and character ranges. The following characters in *pattern* have special meaning: | In *pattern* | Matches in *string* | |:-------------------|:-----------------------------------------------------| diff --git a/docs/Reference/Core/Load.md b/docs/Reference/Core/Load.md index 21c9b6c..791f89b 100644 --- a/docs/Reference/Core/Load.md +++ b/docs/Reference/Core/Load.md @@ -17,7 +17,7 @@ Syntax: When an object is loaded, it is placed in memory but is not visible. Use the **Show** method to make it visible. Until an object is visible, the user can't interact with it; the object can be manipulated programmatically inside its **Initialize** event handler. -Use [**Unload**](Unload) to remove the object from memory once you are done with it. +Use [**Unload**](Unload) to remove the object from memory once it is no longer needed. ### Example diff --git a/docs/Reference/Core/Lock.md b/docs/Reference/Core/Lock.md index 16c68be..0abc56b 100644 --- a/docs/Reference/Core/Lock.md +++ b/docs/Reference/Core/Lock.md @@ -17,7 +17,7 @@ Syntax: : Any valid file number. *recordrange* -: *optional* The range of records to lock or unlock. The *recordrange* settings are: +: *optional* The range of records to lock or unlock. The *recordrange* settings are: > *recnumber* \| [ *start* ] **To** *end* @@ -34,12 +34,12 @@ The **Lock** and **Unlock** statements are used in environments where several pr **Lock** and **Unlock** statements are always used in pairs. The arguments to **Lock** and **Unlock** must match exactly. -The first record or byte in a file is at position 1, the second record or byte is at position 2, and so on. If you specify just one record, only that record is locked or unlocked. If you specify a range of records and omit a starting record (*start*), all records from the first record to the end of the range (*end*) are locked or unlocked. Using **Lock** without *recnumber* locks the entire file; using **Unlock** without *recnumber* unlocks the entire file. +The first record or byte in a file is at position 1, the second record or byte is at position 2, and so on. When just one record is specified, only that record is locked or unlocked. When a range of records is specified and a starting record (*start*) is omitted, all records from the first record to the end of the range (*end*) are locked or unlocked. Using **Lock** without *recnumber* locks the entire file; using **Unlock** without *recnumber* unlocks the entire file. If the file has been opened for sequential input or output, **Lock** and **Unlock** affect the entire file, regardless of the range specified by *start* and *end*. > [!IMPORTANT] -> Be sure to remove all locks with an **Unlock** statement before closing a file or quitting your program. Failure to remove locks produces unpredictable results. +> Be sure to remove all locks with an **Unlock** statement before closing a file or quitting the program. Failure to remove locks produces unpredictable results. ### Example diff --git a/docs/Reference/Core/Mid-equals.md b/docs/Reference/Core/Mid-equals.md index 6020cc6..8a45457 100644 --- a/docs/Reference/Core/Mid-equals.md +++ b/docs/Reference/Core/Mid-equals.md @@ -22,7 +22,7 @@ Syntax: : **Variant** (**Long**). Character position in *stringvar* where the replacement of text begins. *length* -: *optional* **Variant** (**Long**). Number of characters to replace. If omitted, all of *string* is used. +: *optional* **Variant** (**Long**). Number of characters to replace. If omitted, all of *string* is used. *string* : String expression that replaces part of *stringvar*. diff --git a/docs/Reference/Core/MidB-equals.md b/docs/Reference/Core/MidB-equals.md index 218ac35..38f6a3f 100644 --- a/docs/Reference/Core/MidB-equals.md +++ b/docs/Reference/Core/MidB-equals.md @@ -19,7 +19,7 @@ Syntax: : **Variant** (**Long**). Byte position in *stringvar* where the replacement of bytes begins. *length* -: *optional* **Variant** (**Long**). Number of bytes to replace. If omitted, all of *string* is used. +: *optional* **Variant** (**Long**). Number of bytes to replace. If omitted, all of *string* is used. *string* : String expression whose bytes replace part of *stringvar*. diff --git a/docs/Reference/Core/Module.md b/docs/Reference/Core/Module.md index 88e5c53..5ff0caf 100644 --- a/docs/Reference/Core/Module.md +++ b/docs/Reference/Core/Module.md @@ -9,7 +9,7 @@ permalink: /tB/Core/Module Defines a module — a non-instantiable container for procedures, constants, types, enums, and module-level variables. A module's members are accessed through the module name (or, for **Public** members in a non-private module, directly). > [!NOTE] -> The explicit **Module** ... **End Module** block is a twinBASIC extension. Classic VBA distinguishes "standard modules" from "class modules" purely by file type (`.bas` vs. `.cls`); the source has no enclosing keyword. In `.twin` files twinBASIC requires (and supports) the explicit block, which lets you put a class and a module in the same file and apply attributes to the module as a whole. +> The explicit **Module** ... **End Module** block is a twinBASIC extension. Classic VBA distinguishes "standard modules" from "class modules" purely by file type (`.bas` vs. `.cls`); the source has no enclosing keyword. In `.twin` files twinBASIC requires (and supports) the explicit block, which permits a class and a module in the same file and allows attributes to apply to the module as a whole. Syntax: > [ *attributes* ] @@ -19,19 +19,19 @@ Syntax: > **End Module** *attributes* -: *optional* One or more attributes applicable to a module. +: *optional* One or more attributes applicable to a module. **Public** -: *optional* In an ActiveX project, marks the module as exported into the type library so that consumers in other projects can see its **Public** members. +: *optional* In an ActiveX project, marks the module as exported into the type library so that consumers in other projects can see its **Public** members. **Private** -: *optional* In an ActiveX project, withholds the module from the type library: its members remain usable within the project, but are not exported. Equivalent to placing [**Option Private Module**](Option) at the top of a classic standard module. +: *optional* In an ActiveX project, withholds the module from the type library: its members remain usable within the project, but are not exported. Equivalent to placing [**Option Private Module**](Option) at the top of a classic standard module. *name* : The identifier naming the module. *modulemember* -: *optional* Any of the following: +: *optional* Any of the following: - constants defined using [**Const**](Const) - module-level variables defined using [**Public**](Public), [**Private**](Private), or [**Dim**](Dim) (modules don't take part in inheritance, so [**Protected**](Protected) is not allowed) diff --git a/docs/Reference/Core/Name.md b/docs/Reference/Core/Name.md index fc3037c..ba67316 100644 --- a/docs/Reference/Core/Name.md +++ b/docs/Reference/Core/Name.md @@ -20,7 +20,7 @@ Syntax: The **Name** statement renames a file and moves it to a different directory or folder, if necessary. **Name** can move a file across drives, but it can only rename an existing directory or folder when both *newpathname* and *oldpathname* are located on the same drive. **Name** cannot create a new file, directory, or folder. -Using **Name** on an open file produces an error. You must close an open file before renaming it. **Name** arguments cannot include multiple-character (`*`) and single-character (`?`) wildcards. +Using **Name** on an open file produces an error. An open file must be closed before renaming it. **Name** arguments cannot include multiple-character (`*`) and single-character (`?`) wildcards. ### Example diff --git a/docs/Reference/Core/On-Error.md b/docs/Reference/Core/On-Error.md index 2b23b87..e526dcb 100644 --- a/docs/Reference/Core/On-Error.md +++ b/docs/Reference/Core/On-Error.md @@ -23,7 +23,7 @@ Syntax: **On Error GoTo 0** : Disables any enabled error handler in the current procedure. -If you don't use an **On Error** statement, any run-time error that occurs is fatal; that is, an error message is displayed and execution stops. +Without an **On Error** statement, any run-time error that occurs is fatal; that is, an error message is displayed and execution stops. An "enabled" error handler is one that is turned on by an **On Error** statement; an "active" error handler is an enabled handler that is in the process of handling an error. If an error occurs while an error handler is active (between the occurrence of the error and a [**Resume**](Resume), [**Exit Sub**](Exit), **Exit Function**, or **Exit Property** statement), the current procedure's error handler can't handle the error. Control returns to the calling procedure. @@ -36,10 +36,10 @@ Each time the error handler passes control back to a calling procedure, that pro Error-handling routines rely on the value in the **Number** property of the **Err** object to determine the cause of the error. The error-handling routine should test or save relevant property values in the **Err** object before any other error can occur or before a procedure that might cause an error is called. The property values in the **Err** object reflect only the most recent error. The error message associated with **Err.Number** is contained in **Err.Description**. -**On Error Resume Next** causes execution to continue with the statement immediately following the statement that caused the run-time error, or with the statement immediately following the most recent call out of the procedure containing the **On Error Resume Next** statement. This statement allows execution to continue despite a run-time error. You can place the error-handling routine where the error would occur, rather than transferring control to another location within the procedure. An **On Error Resume Next** statement becomes inactive when another procedure is called, so you should execute an **On Error Resume Next** statement in each called routine if you want inline error handling within that routine. +**On Error Resume Next** causes execution to continue with the statement immediately following the statement that caused the run-time error, or with the statement immediately following the most recent call out of the procedure containing the **On Error Resume Next** statement. This statement allows execution to continue despite a run-time error. The error-handling routine can be placed where the error would occur, rather than transferring control to another location within the procedure. An **On Error Resume Next** statement becomes inactive when another procedure is called, so an **On Error Resume Next** statement must be executed in each called routine that requires inline error handling. > [!NOTE] -> The **On Error Resume Next** construct may be preferable to **On Error GoTo** when handling errors generated during access to other objects. Checking **Err** after each interaction with an object removes ambiguity about which object was accessed by the code. You can be sure which object placed the error code in **Err.Number**, as well as which object originally generated the error (the object specified in **Err.Source**). +> The **On Error Resume Next** construct may be preferable to **On Error GoTo** when handling errors generated during access to other objects. Checking **Err** after each interaction with an object removes ambiguity about which object was accessed by the code. It is then clear which object placed the error code in **Err.Number**, as well as which object originally generated the error (the object specified in **Err.Source**). **On Error GoTo 0** disables error handling in the current procedure. It doesn't specify line 0 as the start of the error-handling code, even if the procedure contains a line numbered 0. Without an **On Error GoTo 0** statement, an error handler is automatically disabled when a procedure is exited. @@ -58,14 +58,14 @@ End Sub Here, the error-handling code follows the **Exit Sub** statement and precedes the [**End Sub**](End) statement to separate it from the procedure flow. Error-handling code can be placed anywhere in a procedure. -If you create an object that accesses other objects, you should try to handle errors passed back from them unhandled. If you cannot handle such errors, map the error code in **Err.Number** to one of your own errors, and then pass them back to the caller of your object. You should specify your error by adding your error code to the **vbObjectError** constant. For example, if your error code is 1052, assign it as follows: +When creating an object that accesses other objects, try to handle errors passed back from them unhandled. When such errors cannot be handled, map the error code in **Err.Number** to a project-specific error, and then pass it back to the caller of the object. Specify the error by adding the project error code to the **vbObjectError** constant. For example, if the error code is 1052, assign it as follows: ```tb Err.Number = vbObjectError + 1052 ``` > [!NOTE] -> System errors during calls to Windows dynamic-link libraries (DLLs) don't raise exceptions and cannot be trapped with twinBASIC error trapping. When calling DLL functions, you should check each return value for success or failure (according to the API specifications), and in the event of a failure, check the value in the **Err** object's **LastDLLError** property. +> System errors during calls to Windows dynamic-link libraries (DLLs) don't raise exceptions and cannot be trapped with twinBASIC error trapping. When calling DLL functions, check each return value for success or failure (according to the API specifications), and in the event of a failure, check the value in the **Err** object's **LastDLLError** property. ### Example diff --git a/docs/Reference/Core/On-GoTo.md b/docs/Reference/Core/On-GoTo.md index 6953068..e71fb1a 100644 --- a/docs/Reference/Core/On-GoTo.md +++ b/docs/Reference/Core/On-GoTo.md @@ -28,7 +28,7 @@ The value of *expression* determines which line is branched to in *destinationli | Negative | An error occurs. | | Greater than 255 | An error occurs. | -You can mix line numbers and line labels in the same list. Use as many line labels and line numbers as you like with **On...GoSub** and **On...GoTo**. However, if you use more labels or numbers than fit on a single line, you must use the line-continuation character to continue the logical line onto the next physical line. +Line numbers and line labels can be mixed in the same list. Any number of line labels and line numbers can be used with **On...GoSub** and **On...GoTo**. However, when more labels or numbers are present than fit on a single line, the line-continuation character must be used to continue the logical line onto the next physical line. > [!TIP] > [**Select Case**](Select-Case) provides a more structured and flexible way to perform multiple branching. diff --git a/docs/Reference/Core/Open.md b/docs/Reference/Core/Open.md index 69481ea..52a457e 100644 --- a/docs/Reference/Core/Open.md +++ b/docs/Reference/Core/Open.md @@ -21,21 +21,21 @@ Syntax: : Keyword specifying the file mode: **Append**, **Binary**, **Input**, **Output**, or **Random**. If unspecified, the file is opened for **Random** access. *access* -: *optional* Keyword specifying the operations permitted on the open file: **Read**, **Write**, or **Read Write**. +: *optional* Keyword specifying the operations permitted on the open file: **Read**, **Write**, or **Read Write**. *lock* -: *optional* Keyword specifying the operations restricted on the open file by other processes: **Shared**, **Lock Read**, **Lock Write**, or **Lock Read Write**. +: *optional* Keyword specifying the operations restricted on the open file by other processes: **Shared**, **Lock Read**, **Lock Write**, or **Lock Read Write**. *encoding* -: *optional* An encoding identifier — for example **utf_8**, **utf_16**, **windows_1252_western**, or **default_system_ansi**. See [Text Encodings](#text-encodings) below for the full list. The **Encoding** clause applies to text-mode I/O (**Input**, **Output**, **Append**); it has no effect on **Binary** or **Random** mode files. +: *optional* An encoding identifier — for example **utf_8**, **utf_16**, **windows_1252_western**, or **default_system_ansi**. See [Text Encodings](#text-encodings) below for the full list. The **Encoding** clause applies to text-mode I/O (**Input**, **Output**, **Append**); it has no effect on **Binary** or **Random** mode files. *filenumber* : A valid file number in the range 1 to 511, inclusive. Use the [**FreeFile**](../Modules/FileSystem/FreeFile) function to obtain the next available file number. *reclength* -: *optional* Number less than or equal to 32,767 (bytes). For files opened for random access, this value is the record length. For sequential files, this value is the number of characters buffered. +: *optional* Number less than or equal to 32,767 (bytes). For files opened for random access, this value is the record length. For sequential files, this value is the number of characters buffered. -You must open a file before any I/O operation can be performed on it. **Open** allocates a buffer for I/O to the file and determines the mode of access to use with the buffer. +A file must be opened before any I/O operation can be performed on it. **Open** allocates a buffer for I/O to the file and determines the mode of access to use with the buffer. If the file specified by *pathname* doesn't exist, it is created when a file is opened for **Append**, **Binary**, **Output**, or **Random** modes. @@ -44,7 +44,7 @@ If the file is already opened by another process, and the specified type of acce The **Len** clause is ignored if *mode* is **Binary**. > [!IMPORTANT] -> In **Binary**, **Input**, and **Random** modes, you can open a file by using a different file number without first closing the file. In **Append** and **Output** modes, you must close a file before opening it with a different file number. +> In **Binary**, **Input**, and **Random** modes, a file can be opened with a different file number without first closing the file. In **Append** and **Output** modes, a file must be closed before opening it with a different file number. > [!NOTE] > The **Encoding** clause is a twinBASIC extension. Classic VBA has no equivalent and reads or writes text using the system ANSI code page only. diff --git a/docs/Reference/Core/Option.md b/docs/Reference/Core/Option.md index 53f47b3..bf12cf1 100644 --- a/docs/Reference/Core/Option.md +++ b/docs/Reference/Core/Option.md @@ -24,7 +24,7 @@ Because the default base is **0**, the **Option Base** statement is never requir If used, the statement must appear in a [module](../Gloss#module) or [class](../Gloss#class) before any procedures, functions, or properties. **Option Base** can appear only once in a module and must precede array [declarations](../Gloss#declaration) that include dimensions. > [!NOTE] -> The **To** clause in the [**Dim**](Dim), [**Private**](Private), [**Public**](Public), [**ReDim**](ReDim), and [**Static**](Static) statements provides a more flexible way to control the range of an array's subscripts. However, if you don't explicitly set the lower bound with a **To** clause, you can use **Option Base** to change the default lower bound to 1. The base of an array created with the [**ParamArray**](ParamArray) keyword is zero; **Option Base** does not affect [**ParamArray**](ParamArray) (or the [**Array**](../../tB/Core/Array) function). +> The **To** clause in the [**Dim**](Dim), [**Private**](Private), [**Public**](Public), [**ReDim**](ReDim), and [**Static**](Static) statements provides a more flexible way to control the range of an array's subscripts. However, when the lower bound is not explicitly set with a **To** clause, **Option Base** can change the default lower bound to 1. The base of an array created with the [**ParamArray**](ParamArray) keyword is zero; **Option Base** does not affect [**ParamArray**](ParamArray) (or the [**Array**](../../tB/Core/Array) function). The **Option Base** statement only affects the lower bound of arrays in the module where the statement is located. @@ -87,9 +87,9 @@ If used, the **Option Explicit** statement must appear in a module before any [p This option makes it mandatory to require variable declarations. There is no complementary option to make the declarations optional. -When **Option Explicit** appears in a module, you must explicitly declare all variables by using the [**Dim**](Dim), [**Private**](Private), [**Public**](Public), [**ReDim**](ReDim), and [**Static**](Static) **Static** statements. If you attempt to use an undeclared variable name, an error occurs at [compile time](../Gloss#compile-time). +When **Option Explicit** appears in a module, all variables must be explicitly declared by using the [**Dim**](Dim), [**Private**](Private), [**Public**](Public), [**ReDim**](ReDim), and [**Static**](Static) **Static** statements. Attempting to use an undeclared variable name raises an error at [compile time](../Gloss#compile-time). -If you don't use the **Option Explicit** statement, and when the [**Option Explicit On**](../IDE/Project/Settings#option-explicit-on) project setting is changed to its non-default value of *No*, all undeclared variables are of **Variant** type unless the default type is otherwise specified with a [**Def**_type_](Deftype) statement. +Without the **Option Explicit** statement, and when the [**Option Explicit On**](../IDE/Project/Settings#option-explicit-on) project setting is changed to its non-default value of *No*, all undeclared variables are of **Variant** type unless the default type is otherwise specified with a [**Def**_type_](Deftype) statement. > [!NOTE] > The **Option Explicit On** project setting is *Yes* by default in new projects. @@ -122,7 +122,7 @@ Syntax: **Option Compare** { **Binary** \| **Text** \| **Database** } If used, the **Option Compare** statement must appear in a [module](../Gloss#module) before any [procedures](../Gloss#procedure). -The **Option Compare** statement specifies the [string comparison](../Gloss#string-comparison) method (**Binary**, **Text**, or** Database**) for a module. If a module doesn't include an **Option Compare** statement, the default text comparison method is **Binary**. +The **Option Compare** statement specifies the [string comparison](../Gloss#string-comparison) method (**Binary**, **Text**, or **Database**) for a module. If a module doesn't include an **Option Compare** statement, the default text comparison method is **Binary**. * **Option Compare Binary** results in string comparisons based on a [sort order](../Gloss#sort-order) derived from the internal binary representations of the characters. In Microsoft Windows, sort order is determined by the code page. A typical binary sort order is shown in the following example: @@ -130,7 +130,7 @@ The **Option Compare** statement specifies the [string comparison](../Gloss#stri A < B < E < Z < a < b < e < z < À < Ê < Ø < à < ê < ø ``` -* **Option Compare Text** results in string comparisons based on a case-insensitive text sort order determined by your system's [locale](../Gloss#locale). When the same characters are sorted by using **Option Compare Text**, the following text sort order is produced: +* **Option Compare Text** results in string comparisons based on a case-insensitive text sort order determined by the system's [locale](../Gloss#locale). When the same characters are sorted by using **Option Compare Text**, the following text sort order is produced: ```tb (A=a) < ( À=à) < (B=b) < (E=e) < (Ê=ê) < (Z=z) < (Ø=ø) diff --git a/docs/Reference/Core/Or.md b/docs/Reference/Core/Or.md index 5de5119..4382683 100644 --- a/docs/Reference/Core/Or.md +++ b/docs/Reference/Core/Or.md @@ -43,7 +43,7 @@ The **Or** operator performs a bitwise comparison of identically positioned bits | 1 | 1 | 1 | > [!NOTE] -> **Or** evaluates *both* operands every time, even when *expression1* alone determines the result. Use [**OrElse**](OrElse) when you want short-circuit evaluation — for example, when *expression2* is expensive, has side effects, or only matters when *expression1* is **False**. +> **Or** evaluates *both* operands every time, even when *expression1* alone determines the result. Use [**OrElse**](OrElse) for short-circuit evaluation — for example, when *expression2* is expensive, has side effects, or only matters when *expression1* is **False**. ### Example diff --git a/docs/Reference/Core/ParamArray.md b/docs/Reference/Core/ParamArray.md index 1d7efaf..29f3532 100644 --- a/docs/Reference/Core/ParamArray.md +++ b/docs/Reference/Core/ParamArray.md @@ -7,7 +7,7 @@ vba_attribution: true # ParamArray {: .no_toc } -Used in the argument list of a [**Sub**](Sub), [**Function**](Function), or [**Property**](Property) procedure to indicate that the final parameter is an open-ended list of arguments. The **ParamArray** keyword allows the procedure to accept an arbitrary number of arguments at the call site. +Used in the argument list of a [**Sub**](Sub), [**Function**](Function), or [**Property**](Property) procedure to indicate that the final parameter is an open-ended list of arguments. The **ParamArray** keyword permits the procedure to accept an arbitrary number of arguments at the call site. Syntax: > [ **Public** \| **Private** \| **Friend** ] [ **Static** ] **Sub** \| **Function** \| **Property Get** \| **Property Let** \| **Property Set** *name* **(** [ *arglist*, ] **ParamArray** *varname*[ **()** ] [ **As** *type* ] **)** @@ -16,7 +16,7 @@ Syntax: : Name of the variable representing the **ParamArray**; follows standard variable naming conventions. *type* -: *optional* Must be **Variant** (explicitly or by default). Each argument supplied at the call site can be of a different data type, so **ParamArray** must always be an array of **Variant** elements. +: *optional* Must be **Variant** (explicitly or by default). Each argument supplied at the call site can be of a different data type, so **ParamArray** must always be an array of **Variant** elements. **ParamArray** must be the last parameter in the argument list of a **Sub**, **Function**, or **Property Get** procedure. In a **Property Let** or **Property Set** procedure it must precede the *value*/*reference* parameter and so cannot be the only parameter. diff --git a/docs/Reference/Core/Plus.md b/docs/Reference/Core/Plus.md index 9b6ce54..30abe18 100644 --- a/docs/Reference/Core/Plus.md +++ b/docs/Reference/Core/Plus.md @@ -23,7 +23,7 @@ Syntax: *expression*, *expression1*, *expression2* : Any expressions. -When you use the **+** operator, you may not be able to determine whether addition or string concatenation will occur. Use the [**&**](Concat) operator for concatenation to eliminate ambiguity and produce self-documenting code. +When the **+** operator is used, it may not be obvious whether addition or string concatenation will occur. Use the [**&**](Concat) operator for concatenation to eliminate ambiguity and produce self-documenting code. If at least one expression is not a **Variant**, the following rules apply: @@ -75,7 +75,7 @@ Greeting += ", world" ' Greeting is now "Hello, world". ### Example -This example uses the **+** operator to sum numbers. The **+** operator can also be used to concatenate strings, but to eliminate ambiguity you should use the [**&**](Concat) operator instead. +This example uses the **+** operator to sum numbers. The **+** operator can also be used to concatenate strings, but to eliminate ambiguity use the [**&**](Concat) operator instead. ```tb Dim MyNumber, Var1, Var2 diff --git a/docs/Reference/Core/Print.md b/docs/Reference/Core/Print.md index 53d6786..e52512c 100644 --- a/docs/Reference/Core/Print.md +++ b/docs/Reference/Core/Print.md @@ -19,7 +19,7 @@ Syntax: : Any valid file number. *outputlist* -: *optional* Expression or list of expressions to print. The *outputlist* settings are: +: *optional* Expression or list of expressions to print. The *outputlist* settings are: > [ { **Spc(***n***)** \| **Tab** [ **(***n***)** ] } ] [ *expression* ] [ *charpos* ] @@ -37,13 +37,13 @@ Syntax: Data written with **Print #** is usually read from a file with [**Line Input #**](Line-Input) or [**Input #**](Input). -If you omit *outputlist* and include only a list separator after *filenumber*, a blank line is printed to the file. +When *outputlist* is omitted and only a list separator follows *filenumber*, a blank line is printed to the file. Multiple expressions can be separated with either a space or a semicolon. A space has the same effect as a semicolon. For **Boolean** data, either `True` or `False` is printed. The **True** and **False** keywords are not translated, regardless of the locale. -**Date** data is written to the file by using the standard short date format recognized by your system. When either the date or the time component is missing or zero, only the part provided gets written to the file. +**Date** data is written to the file by using the standard short date format recognized by the system. When either the date or the time component is missing or zero, only the part provided gets written to the file. Nothing is written to the file if *outputlist* data is **Empty**. However, if *outputlist* data is **Null**, `Null` is written to the file. @@ -51,10 +51,10 @@ For **Error** data, the output appears as `Error `*errorcode*. The **Error** key All data written to the file by using **Print #** is internationally-aware; that is, the data is properly formatted by using the appropriate decimal separator. -Because **Print #** writes an image of the data to the file, you must delimit the data so that it prints correctly. If you use **Tab** with no arguments to move the print position to the next print zone, **Print #** also writes the spaces between print fields to the file. +Because **Print #** writes an image of the data to the file, the data must be delimited so that it prints correctly. When **Tab** is used with no arguments to move the print position to the next print zone, **Print #** also writes the spaces between print fields to the file. > [!NOTE] -> If, at some future time, you want to read the data from a file by using the **Input #** statement, use the [**Write #**](Write) statement instead of the **Print #** statement to write the data to the file. Using **Write #** ensures the integrity of each separate data field by properly delimiting it, so that it can be read back in by using **Input #**. Using **Write #** also ensures that it can be correctly read in any locale. +> When the data is later read from a file by using the **Input #** statement, use the [**Write #**](Write) statement instead of the **Print #** statement to write the data to the file. Using **Write #** ensures the integrity of each separate data field by properly delimiting it, so that it can be read back in by using **Input #**. Using **Write #** also ensures that it can be correctly read in any locale. ### Example diff --git a/docs/Reference/Core/Private.md b/docs/Reference/Core/Private.md index 5418f0d..1684602 100644 --- a/docs/Reference/Core/Private.md +++ b/docs/Reference/Core/Private.md @@ -13,19 +13,19 @@ Syntax: > **Private** [ **WithEvents** ] *varname* [ **(** [ *subscripts* ] **)** ] [ **As** [ **New** ] *type* ] [ **,** [ **WithEvents** ] *varname* [ **(** [ *subscripts* ] **)** ] [ **As** [ **New** ] *type* ]] **. . .** **WithEvents** -: *optional* Keyword that specifies that *varname* is an object variable used to respond to events triggered by an ActiveX object. **WithEvents** is valid only in class modules. You can declare as many individual variables as you like by using **WithEvents**, but you can't create arrays with **WithEvents**, nor can you use **New** with **WithEvents**. +: *optional* Keyword that specifies that *varname* is an object variable used to respond to events triggered by an ActiveX object. **WithEvents** is valid only in class modules. Any number of individual variables may be declared by using **WithEvents**, but arrays cannot be declared with **WithEvents**, nor can **New** be combined with **WithEvents**. *varname* : Name of the variable; follows standard variable naming conventions. *subscripts* -: *optional* Dimensions of an array variable; up to 60 multiple dimensions may be declared. The *subscripts* argument uses the following syntax: [ *lower* **To** ] *upper* [ , [ *lower* **To** ] *upper* ] **. . .**. When not explicitly stated in *lower*, the lower bound of an array is controlled by the [**Option Base**](Option#Base) statement. The lower bound is zero if no **Option Base** statement is present. +: *optional* Dimensions of an array variable; up to 60 multiple dimensions may be declared. The *subscripts* argument uses the following syntax: [ *lower* **To** ] *upper* [ , [ *lower* **To** ] *upper* ] **. . .**. When not explicitly stated in *lower*, the lower bound of an array is controlled by the [**Option Base**](Option#Base) statement. The lower bound is zero if no **Option Base** statement is present. **New** -: *optional* Keyword that enables implicit creation of an object. If you use **New** when declaring the object variable, a new instance of the object is created on first reference to it, so you don't have to use the **[Set](Set)** statement to assign the object reference. The **New** keyword can't be used to declare variables of any intrinsic data type or to declare instances of dependent objects, and it can't be used with **WithEvents**. +: *optional* Keyword that enables implicit creation of an object. When **New** is used to declare the object variable, a new instance of the object is created on first reference to it, so the **[Set](Set)** statement is not required to assign the object reference. The **New** keyword can't be used to declare variables of any intrinsic data type or to declare instances of dependent objects, and it can't be used with **WithEvents**. *type* -: *optional* Data type of the variable; may be **Byte**, **Boolean**, **Integer**, **Long**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (for variable-length strings), **String** *length* (for fixed-length strings), **Object**, **Variant**, a user-defined type, or an object type. Use a separate **As** *type* clause for each variable being defined. +: *optional* Data type of the variable; may be **Byte**, **Boolean**, **Integer**, **Long**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (for variable-length strings), **String** *length* (for fixed-length strings), **Object**, **Variant**, a user-defined type, or an object type. Use a separate **As** *type* clause for each variable being defined. **Private** variables are available only to the module in which they are declared. @@ -35,7 +35,7 @@ Use the **Private** statement to declare the data type of a variable. For exampl Private NumberOfEmployees As Integer ``` -You can also use a **Private** statement to declare the object type of a variable. The following statement declares a variable for a new instance of a worksheet: +A **Private** statement can also declare the object type of a variable. The following statement declares a variable for a new instance of a worksheet: ```tb Private X As New Worksheet @@ -43,9 +43,9 @@ Private X As New Worksheet If the **New** keyword isn't used when declaring an object variable, the variable that refers to the object must be assigned an existing object by using the **Set** statement before it can be used. Until it is assigned an object, the declared object variable has the special value **Nothing**, which indicates that it doesn't refer to any particular instance of an object. -If you don't specify a data type or object type, and there is no [**Deftype**](Deftype) statement in the module, the variable is **Variant** by default. +When no data type or object type is specified, and there is no [**Deftype**](Deftype) statement in the module, the variable is **Variant** by default. -You can also use the **Private** statement with empty parentheses to declare a dynamic array. After declaring a dynamic array, use the **[ReDim](ReDim)** statement within a procedure to define the number of dimensions and elements in the array. If you try to redeclare a dimension for an array variable whose size was explicitly specified in a **Private**, [**Public**](Public), or [**Dim**](Dim) statement, an error occurs. +The **Private** statement with empty parentheses also declares a dynamic array. After declaring a dynamic array, use the **[ReDim](ReDim)** statement within a procedure to define the number of dimensions and elements in the array. Redeclaring a dimension for an array variable whose size was explicitly specified in a **Private**, [**Public**](Public), or [**Dim**](Dim) statement raises an error. When variables are initialized, a numeric variable is initialized to 0, a variable-length string is initialized to a zero-length string (""), and a fixed-length string is filled with zeros. **Variant** variables are initialized to **Empty**. Each element of a user-defined type variable is initialized as if it were a separate variable. diff --git a/docs/Reference/Core/Property.md b/docs/Reference/Core/Property.md index 76d7fc8..1442013 100644 --- a/docs/Reference/Core/Property.md +++ b/docs/Reference/Core/Property.md @@ -45,40 +45,40 @@ Syntax: : *optional* One or more of the [supported attributes](Attributes) for procedures. **Public** -: *optional* Indicates that the **Property** procedure is accessible to all other procedures in all modules. If used in a module that contains an **Option Private** statement, the procedure is not available outside the project. +: *optional* Indicates that the **Property** procedure is accessible to all other procedures in all modules. If used in a module that contains an **Option Private** statement, the procedure is not available outside the project. **Private** -: *optional* Indicates that the **Property** procedure is accessible only to other procedures in the module where it is declared. +: *optional* Indicates that the **Property** procedure is accessible only to other procedures in the module where it is declared. **Friend** -: *optional* Used only in a class module. Indicates that the **Property** procedure is visible throughout the project, but not visible to a controller of an instance of an object. +: *optional* Used only in a class module. Indicates that the **Property** procedure is visible throughout the project, but not visible to a controller of an instance of an object. **[Protected](Protected)** -: *optional* (twinBASIC) Used only in a class. Indicates that the **Property** procedure is accessible from inside the declaring class and from classes that derive from it via [**Inherits**](../../Features/Language/Inheritance#inherits-for-complete-oop), but not from outside callers. All three accessor forms of the same property (**Get**, **Let**, **Set**) should agree on the access modifier. +: *optional* (twinBASIC) Used only in a class. Indicates that the **Property** procedure is accessible from inside the declaring class and from classes that derive from it via [**Inherits**](../../Features/Language/Inheritance#inherits-for-complete-oop), but not from outside callers. All three accessor forms of the same property (**Get**, **Let**, **Set**) should agree on the access modifier. **[Static](Static)** -: *optional* Indicates that the **Property** procedure's local variables are preserved between calls. The **Static** attribute doesn't affect variables that are declared outside the **Property** procedure, even if they are used in the procedure. +: *optional* Indicates that the **Property** procedure's local variables are preserved between calls. The **Static** attribute doesn't affect variables that are declared outside the **Property** procedure, even if they are used in the procedure. **Overridable** -: *optional* (twinBASIC) Marks the **Property** as an inheritance hook that classes derived via [**Inherits**](../../Features/Language/Inheritance#inherits-for-complete-oop) may replace with an **Overrides** clause. Meaningful only on a member of a class that participates in an **Inherits** hierarchy. +: *optional* (twinBASIC) Marks the **Property** as an inheritance hook that classes derived via [**Inherits**](../../Features/Language/Inheritance#inherits-for-complete-oop) may replace with an **Overrides** clause. Meaningful only on a member of a class that participates in an **Inherits** hierarchy. *name* : Name of the **Property** procedure; follows standard variable naming conventions, except that the same name is shared by the matching **Property Get**, **Property Let**, and **Property Set** procedures in the same module. **Of** *typevars* -: *optional* One or more type variable names, following standard variable naming conventions. The names are separated by commas. Causes the procedure to be a generic **Property** procedure. The matching **Property Get**, **Property Let**, and **Property Set** procedures must declare the same generic parameters. +: *optional* One or more type variable names, following standard variable naming conventions. The names are separated by commas. Causes the procedure to be a generic **Property** procedure. The matching **Property Get**, **Property Let**, and **Property Set** procedures must declare the same generic parameters. *arglist* : List of variables representing arguments that are passed to the **Property** procedure when it is called. Multiple arguments are separated by commas. The name and data type of each argument in a **Property Let** or **Property Set** procedure must be the same as the corresponding argument in the matching **Property Get** procedure. See [*arglist*](#arglist) below for syntax. *arglist* is optional for **Property Get**; for **Property Let** and **Property Set** at least the *value*/*reference* parameter is required. **As** *type* -: *optional* Data type of the value returned by the **Property Get** procedure; may be **Byte**, **Boolean**, **Integer**, **Long**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (except fixed length), **Object**, **Variant**, a user-defined type, or an array. The return *type* of a **Property Get** procedure must be the same data type as the *value* parameter of the corresponding **Property Let** procedure (if one exists), or compatible with the *reference* parameter of the corresponding **Property Set** procedure. +: *optional* Data type of the value returned by the **Property Get** procedure; may be **Byte**, **Boolean**, **Integer**, **Long**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (except fixed length), **Object**, **Variant**, a user-defined type, or an array. The return *type* of a **Property Get** procedure must be the same data type as the *value* parameter of the corresponding **Property Let** procedure (if one exists), or compatible with the *reference* parameter of the corresponding **Property Set** procedure. *statements* -: *optional* Any group of statements to be executed within the body of the **Property** procedure. +: *optional* Any group of statements to be executed within the body of the **Property** procedure. *expression* -: *optional* In **Property Get**, the value (or reference, when assigned with **Set**) returned by the procedure. +: *optional* In **Property Get**, the value (or reference, when assigned with **Set**) returned by the procedure. *value* : In **Property Let**, the variable that contains the value to be assigned to the property. When the procedure is called, this argument appears on the right side of the calling expression. The data type of *value* must be the same as the return type of the corresponding **Property Get** procedure. *value* cannot be **Optional** or a **ParamArray**. @@ -87,17 +87,17 @@ Syntax: : In **Property Set**, the variable containing the object reference used on the right side of the object reference assignment. *reference* cannot be **Optional**. *binding-clause* -: *optional* (twinBASIC) One of three trailing clauses that bind this accessor to a member declared elsewhere: +: *optional* (twinBASIC) One of three trailing clauses that bind this accessor to a member declared elsewhere: - - **Handles** *object*.*event* [ **,** *object*.*event* … ] — wires the property up as a handler for the named event(s), replacing the traditional `Object_Event` naming convention. See [**Handles** statement](Handles). - - **Implements** *iface*.*member* [ **,** *iface2*.*member2* … ] — provides the body for the named [**Interface**](Interface) (or [**Class**](Class)) member, replacing the traditional `Iface_Member` naming convention. A comma-separated list lets one body satisfy several interfaces' members at once. See [**Implements** statement](Implements). + - **Handles** *object*.*event* [ **,** *object*.*event* … ] — connects the property as a handler for the named event(s), replacing the traditional `Object_Event` naming convention. See [**Handles** statement](Handles). + - **Implements** *iface*.*member* [ **,** *iface2*.*member2* … ] — provides the body for the named [**Interface**](Interface) (or [**Class**](Class)) member, replacing the traditional `Iface_Member` naming convention. A comma-separated list permits one body to satisfy several interfaces' members at once. See [**Implements** statement](Implements). - **Overrides** *base*.*member* — supplies the body for an **Overridable** *member* inherited via [**Inherits**](../../Features/Language/Inheritance#inherits-for-complete-oop). Combine with **Overridable** on the same header to allow further-derived classes to override again. **[Exit Property](Exit)** -: *optional* Immediately returns from the **Property** procedure without setting a return value. Valid in **Property Get**, **Property Let**, and **Property Set**. +: *optional* Immediately returns from the **Property** procedure without setting a return value. Valid in **Property Get**, **Property Let**, and **Property Set**. **[Return](Return)** *expression* -: *optional* Valid only in a **Property Get** procedure. Immediately returns from the procedure with *expression* as the property's value. The *expression* is required in this form; a bare **Return** is reserved for the [**GoSub...Return**](GoSub-Return) construct and does not exit a **Property** procedure. +: *optional* Valid only in a **Property Get** procedure. Immediately returns from the procedure with *expression* as the property's value. The *expression* is required in this form; a bare **Return** is reserved for the [**GoSub...Return**](GoSub-Return) construct and does not exit a **Property** procedure. ### *arglist* @@ -105,32 +105,32 @@ Syntax: One or more of [ **Optional** ] [ **ByVal** \| **ByRef** ] [ **[ParamArray](ParamArray)** ] *varname* [ **()** ] [ **As** *type* ] [ **=** *defaultvalue* ] **Optional** -: *optional* Indicates that an argument is not required. If used, all subsequent arguments in *arglist* must also be optional and declared by using the **Optional** keyword. The right side of a **Property Let** or **Property Set** call (the *value* or *reference* parameter) cannot be **Optional**. +: *optional* Indicates that an argument is not required. If used, all subsequent arguments in *arglist* must also be optional and declared by using the **Optional** keyword. The right side of a **Property Let** or **Property Set** call (the *value* or *reference* parameter) cannot be **Optional**. **ByVal** -: *optional* Indicates that the argument is passed by value. +: *optional* Indicates that the argument is passed by value. **ByRef** -: *optional* Indicates that the argument is passed by reference. **ByRef** is the default unlike in Visual Basic .NET. +: *optional* Indicates that the argument is passed by reference. **ByRef** is the default unlike in Visual Basic .NET. **[ParamArray](ParamArray)** -: *optional* Indicates that the argument is an **Optional** array of **Variant** elements. The **ParamArray** keyword allows you to provide an arbitrary number of arguments. It may not be used with **ByVal**, **ByRef**, or **Optional**, and it may not be the *value*/*reference* parameter of a **Property Let** or **Property Set** procedure. +: *optional* Indicates that the argument is an **Optional** array of **Variant** elements. The **ParamArray** keyword permits passing an arbitrary number of arguments. It may not be used with **ByVal**, **ByRef**, or **Optional**, and it may not be the *value*/*reference* parameter of a **Property Let** or **Property Set** procedure. *varname* : Name of the variable representing the argument; follows standard variable naming conventions. *type* -: *optional* Data type of the argument passed to the procedure; may be **Byte**, **Boolean**, **Integer**, **Long**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (variable length only), **Object**, **Variant**, a specific object type, or the name of a generic type argument. If the parameter is not **Optional**, a user-defined type may also be specified. +: *optional* Data type of the argument passed to the procedure; may be **Byte**, **Boolean**, **Integer**, **Long**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (variable length only), **Object**, **Variant**, a specific object type, or the name of a generic type argument. If the parameter is not **Optional**, a user-defined type may also be specified. If the name of a generic type parameter is used, it becomes bound to the concrete type of the argument passed to the procedure. The name binding has the scope of the body of the procedure. *defaultvalue* -: *optional* Any constant or constant expression. Valid for **Optional** parameters only. If the type is an **Object**, an explicit default value can only be **Nothing**. +: *optional* Any constant or constant expression. Valid for **Optional** parameters only. If the type is an **Object**, an explicit default value can only be **Nothing**. If not explicitly specified by using **Public**, **Private**, or **Friend**, **Property** procedures are public by default. If **Static** isn't used, the value of local variables is not preserved between calls. The **Friend** keyword can only be used in class modules. However, **Friend** procedures can be accessed by procedures in any module of a project. A **Friend** procedure doesn't appear in the type library of its parent class, nor can a **Friend** procedure be late bound. -All executable code must be in procedures. You can't define a **Property** procedure inside another **[Property](Property)**, **[Sub](Sub)**, or **[Function](Function)** procedure. +All executable code must be in procedures. A **Property** procedure cannot be defined inside another **[Property](Property)**, **[Sub](Sub)**, or **[Function](Function)** procedure. The **[Exit Property](Exit)** statement, and the **[Return](Return)** *expression* statement (in **Property Get** only), cause an immediate exit from a **Property** procedure. Program execution continues with the statement following the statement that called the **Property** procedure. Any number of these statements can appear anywhere in a **Property** procedure. diff --git a/docs/Reference/Core/Public.md b/docs/Reference/Core/Public.md index b560a03..2880bc5 100644 --- a/docs/Reference/Core/Public.md +++ b/docs/Reference/Core/Public.md @@ -13,19 +13,19 @@ Syntax: > **Public** [ **WithEvents** ] *varname* [ **(** [ *subscripts* ] **)** ] [ **As** [ **New** ] *type* ] [ **,** [ **WithEvents** ] *varname* [ **(** [ *subscripts* ] **)** ] [ **As** [ **New** ] *type* ]] **. . .** **WithEvents** -: *optional* Keyword specifying that *varname* is an object variable used to respond to events triggered by an ActiveX object. **WithEvents** is valid only in class modules. You can declare as many individual variables as you like by using **WithEvents**, but you can't create arrays with **WithEvents**, nor can you use **New** with **WithEvents**. +: *optional* Keyword specifying that *varname* is an object variable used to respond to events triggered by an ActiveX object. **WithEvents** is valid only in class modules. Any number of individual variables may be declared by using **WithEvents**, but arrays cannot be declared with **WithEvents**, nor can **New** be combined with **WithEvents**. *varname* : Name of the variable; follows standard naming conventions. *subscripts* -: *optional* Dimensions of an array variable; up to 60 multiple dimensions may be declared. The *subscripts* argument uses the following syntax: [ *lower* **To** ] *upper* [ , [ *lower* **To** ] *upper* ] **. . .**. When not explicitly stated in *lower*, the lower bound of an array is controlled by the [**Option Base**](Option#Base) statement. The lower bound is zero if no **Option Base** statement is present. +: *optional* Dimensions of an array variable; up to 60 multiple dimensions may be declared. The *subscripts* argument uses the following syntax: [ *lower* **To** ] *upper* [ , [ *lower* **To** ] *upper* ] **. . .**. When not explicitly stated in *lower*, the lower bound of an array is controlled by the [**Option Base**](Option#Base) statement. The lower bound is zero if no **Option Base** statement is present. **New** -: *optional* Keyword that enables implicit creation of an object. If you use **New** when declaring the object variable, a new instance of the object is created on first reference to it, so you don't have to use the **[Set](Set)** statement to assign the object reference. The **New** keyword can't be used to declare variables of any intrinsic data type or to declare instances of dependent objects, and it can't be used with **WithEvents**. +: *optional* Keyword that enables implicit creation of an object. When **New** is used to declare the object variable, a new instance of the object is created on first reference to it, so the **[Set](Set)** statement is not required to assign the object reference. The **New** keyword can't be used to declare variables of any intrinsic data type or to declare instances of dependent objects, and it can't be used with **WithEvents**. *type* -: *optional* Data type of the variable; may be **Byte**, **Boolean**, **Integer**, **Long**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (for variable-length strings), **String** *length* (for fixed-length strings), **Object**, **Variant**, a user-defined type, or an object type. Use a separate **As** *type* clause for each variable being defined. +: *optional* Data type of the variable; may be **Byte**, **Boolean**, **Integer**, **Long**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (for variable-length strings), **String** *length* (for fixed-length strings), **Object**, **Variant**, a user-defined type, or an object type. Use a separate **As** *type* clause for each variable being defined. Variables declared by using the **Public** statement are available to all procedures in all modules in all applications, unless **[Option Private Module](Option)** is in effect; in which case, the variables are public only within the project in which they reside. @@ -45,9 +45,9 @@ Public X As New Worksheet If the **New** keyword is not used when declaring an object variable, the variable that refers to the object must be assigned an existing object by using the **Set** statement before it can be used. Until it is assigned an object, the declared object variable has the special value **Nothing**, which indicates that it doesn't refer to any particular instance of an object. -You can also use the **Public** statement with empty parentheses to declare a dynamic array. After declaring a dynamic array, use the **[ReDim](ReDim)** statement within a procedure to define the number of dimensions and elements in the array. If you try to redeclare a dimension for an array variable whose size was explicitly specified in a [**Private**](Private), **Public**, or [**Dim**](Dim) statement, an error occurs. +The **Public** statement with empty parentheses also declares a dynamic array. After declaring a dynamic array, use the **[ReDim](ReDim)** statement within a procedure to define the number of dimensions and elements in the array. Redeclaring a dimension for an array variable whose size was explicitly specified in a [**Private**](Private), **Public**, or [**Dim**](Dim) statement raises an error. -If you don't specify a data type or object type, and there is no [**Deftype**](Deftype) statement in the module, the variable is **Variant** by default. +When no data type or object type is specified, and there is no [**Deftype**](Deftype) statement in the module, the variable is **Variant** by default. When variables are initialized, a numeric variable is initialized to 0, a variable-length string is initialized to a zero-length string (""), and a fixed-length string is filled with zeros. **Variant** variables are initialized to **Empty**. Each element of a user-defined type variable is initialized as if it were a separate variable. diff --git a/docs/Reference/Core/Put.md b/docs/Reference/Core/Put.md index db35355..71681fd 100644 --- a/docs/Reference/Core/Put.md +++ b/docs/Reference/Core/Put.md @@ -16,14 +16,14 @@ Syntax: : Any valid file number. *recnumber* -: *optional* **Variant** (**Long**). Record number (**Random** mode files) or byte number (**Binary** mode files) at which writing begins. +: *optional* **Variant** (**Long**). Record number (**Random** mode files) or byte number (**Binary** mode files) at which writing begins. *varname* : Name of the variable containing data to be written to disk. Data written with **Put** is usually read from a file with [**Get**](Get). -The first record or byte in a file is at position 1, the second record or byte is at position 2, and so on. If you omit *recnumber*, the next record or byte after the last **Get** or **Put** statement, or pointed to by the last [**Seek**](../Modules/FileSystem/Seek) function, is written. You must include the delimiting commas: +The first record or byte in a file is at position 1, the second record or byte is at position 2, and so on. When *recnumber* is omitted, the next record or byte after the last **Get** or **Put** statement, or pointed to by the last [**Seek**](../Modules/FileSystem/Seek) function, is written. The delimiting commas must be included: ```tb Put #4, , FileBuffer @@ -38,7 +38,7 @@ For files opened in **Random** mode, the following rules apply: - If the variable being written is a **Variant** of a numeric type, **Put** writes 2 bytes identifying the **VarType** of the **Variant** and then writes the variable. For example, when writing a **Variant** of **VarType** 3, **Put** writes 6 bytes: 2 bytes identifying the **Variant** as **VarType** 3 (**Long**) and 4 bytes containing the **Long** data. The record length specified by the **Len** clause in the **Open** statement must be at least 2 bytes greater than the actual number of bytes required to store the variable. > [!NOTE] - > Use the **Put** statement to write a **Variant** array to disk, but you can't use **Put** to write a scalar **Variant** containing an array to disk. You also can't use **Put** to write objects to disk. + > Use the **Put** statement to write a **Variant** array to disk; **Put** cannot write a scalar **Variant** containing an array to disk. **Put** also cannot write objects to disk. - If the variable being written is a **Variant** of **VarType** 8 (**String**), **Put** writes 2 bytes identifying the **VarType**, 2 bytes indicating the length of the string, and then writes the string data. The record length specified by the **Len** clause in the **Open** statement must be at least 4 bytes greater than the actual length of the string. diff --git a/docs/Reference/Core/RaiseEvent.md b/docs/Reference/Core/RaiseEvent.md index c9e434f..6b84318 100644 --- a/docs/Reference/Core/RaiseEvent.md +++ b/docs/Reference/Core/RaiseEvent.md @@ -16,11 +16,11 @@ Syntax: : Name of the event to fire. Must be the name of an [**Event**](Event) declared in the same module. *argumentlist* -: *optional* Comma-delimited list of variables, arrays, or expressions to pass as event arguments. The *argumentlist* must be enclosed by parentheses. If the event has no arguments, the parentheses must be omitted. +: *optional* Comma-delimited list of variables, arrays, or expressions to pass as event arguments. The *argumentlist* must be enclosed by parentheses. If the event has no arguments, the parentheses must be omitted. If the event has not been declared within the module in which it is raised, an error occurs. If the event has no arguments, including empty parentheses in the **RaiseEvent** invocation causes an error. -You can't use **RaiseEvent** to fire events that are not explicitly declared in the module. For example, if a form has a built-in **Click** event, you can't fire its **Click** event by using **RaiseEvent**. If you declare a **Click** event in the form module, it shadows the form's own **Click** event. +**RaiseEvent** cannot fire events that are not explicitly declared in the module. For example, even if a form has a built-in **Click** event, **RaiseEvent** cannot fire it. Declaring a **Click** event in the form module shadows the form's own **Click** event. Event firing is done in the order that connections were established. Because events can have **ByRef** parameters, a process that connects late may receive parameters that have been changed by an earlier event handler. diff --git a/docs/Reference/Core/ReDim.md b/docs/Reference/Core/ReDim.md index 752733b..4aea6e0 100644 --- a/docs/Reference/Core/ReDim.md +++ b/docs/Reference/Core/ReDim.md @@ -13,25 +13,25 @@ Syntax: > **ReDim** [ **Preserve** ] *varname* **(** *subscripts* **)** [ **As** *type* ] [ **,** *varname* **(** *subscripts* **)** [ **As** *type* ] ] **. . .** **Preserve** -: *optional* Keyword used to preserve the data in an existing array when you change the size of the last dimension. +: *optional* Keyword used to preserve the data in an existing array when the size of the last dimension changes. *varname* : Name of the variable; follows standard variable naming conventions. *subscripts* -: Dimensions of an array variable; up to 60 multiple dimensions may be declared. The *subscripts* argument uses the following syntax: [ *lower* **To** ] *upper* [ , [ *lower* **To** ] *upper* ] **. . .**. When not explicitly stated in *lower*, the lower bound of an array is controlled by the [**Option Base**](Option#Base) statement. The lower bound is zero if no **Option Base** statement is present. +: Dimensions of an array variable; up to 60 multiple dimensions may be declared. The *subscripts* argument uses the following syntax: [ *lower* **To** ] *upper* [ , [ *lower* **To** ] *upper* ] **. . .**. When not explicitly stated in *lower*, the lower bound of an array is controlled by the [**Option Base**](Option#Base) statement. The lower bound is zero if no **Option Base** statement is present. *type* -: *optional* Data type of the variable; may be **Byte**, **Boolean**, **Integer**, **Long**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (for variable-length strings), **String** *length* (for fixed-length strings), **Object**, **Variant**, a user-defined type, or an object type. +: *optional* Data type of the variable; may be **Byte**, **Boolean**, **Integer**, **Long**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (for variable-length strings), **String** *length* (for fixed-length strings), **Object**, **Variant**, a user-defined type, or an object type. Use a separate **As** *type* clause for each variable being defined. For a **Variant** containing an array, *type* describes the type of each element of the array, but doesn't change the **Variant** to some other type. The **ReDim** statement is used to size or resize a dynamic array that has already been formally declared by using a [**Private**](Private), [**Public**](Public), or [**Dim**](Dim) statement with empty parentheses (without dimension subscripts). -Use the **ReDim** statement repeatedly to change the number of elements and dimensions in an array. However, you can't declare an array of one data type and later use **ReDim** to change the array to another data type, unless the array is contained in a **Variant**. If the array is contained in a **Variant**, the type of the elements can be changed by using an **As** *type* clause, unless you are using the **Preserve** keyword, in which case no changes of data type are permitted. +Use the **ReDim** statement repeatedly to change the number of elements and dimensions in an array. However, an array declared with one data type cannot later be changed to another data type by **ReDim**, unless the array is contained in a **Variant**. If the array is contained in a **Variant**, the type of the elements can be changed by using an **As** *type* clause, unless the **Preserve** keyword is used, in which case no changes of data type are permitted. -If you use the **Preserve** keyword, you can resize only the last array dimension and you can't change the number of dimensions at all. For example, if your array has only one dimension, you can resize that dimension because it is the last and only dimension. However, if your array has two or more dimensions, you can change the size of only the last dimension and still preserve the contents of the array. +With the **Preserve** keyword, only the last array dimension can be resized, and the number of dimensions cannot change. For example, when the array has only one dimension, that dimension can be resized because it is the last and only dimension. However, when the array has two or more dimensions, only the size of the last dimension can change while still preserving the contents of the array. -The following example shows how you can increase the size of the last dimension of a dynamic array without erasing any existing data contained in the array. +The following example shows how to increase the size of the last dimension of a dynamic array without erasing any existing data contained in the array. ```tb ReDim X(10, 10, 10) @@ -39,9 +39,9 @@ ReDim X(10, 10, 10) ReDim Preserve X(10, 10, 15) ``` -Similarly, when you use **Preserve**, you can change the size of the array only by changing the upper bound; changing the lower bound causes an error. +Similarly, with **Preserve**, the size of the array can only change by changing the upper bound; changing the lower bound causes an error. -If you make an array smaller than it was, data in the eliminated elements will be lost. +When an array becomes smaller than it was, data in the eliminated elements will be lost. When variables are initialized, a numeric variable is initialized to 0, a variable-length string is initialized to a zero-length string (""), and a fixed-length string is filled with zeros. **Variant** variables are initialized to **Empty**. Each element of a user-defined type variable is initialized as if it were a separate variable. @@ -50,7 +50,7 @@ A variable that refers to an object must be assigned an existing object by using The **ReDim** statement acts as a declarative statement if the variable it declares doesn't exist at the module level or procedure level. If another variable with the same name is created later, even in a wider scope, **ReDim** will refer to the later variable and won't necessarily cause a compilation error, even if **Option Explicit** is in effect. To avoid such conflicts, **ReDim** should not be used as a declarative statement, but simply for redimensioning arrays. > [!NOTE] -> To resize an array contained in a **Variant**, you must explicitly declare the **Variant** variable before attempting to resize its array. +> To resize an array contained in a **Variant**, the **Variant** variable must be explicitly declared before attempting to resize its array. ### Example diff --git a/docs/Reference/Core/Resume.md b/docs/Reference/Core/Resume.md index 03e1677..929ebfc 100644 --- a/docs/Reference/Core/Resume.md +++ b/docs/Reference/Core/Resume.md @@ -23,7 +23,7 @@ Syntax: **Resume** *line* : Execution resumes at the *line* specified. The *line* argument is a line label or line number, and must be in the same procedure as the error handler. -If you use a **Resume** statement anywhere except in an error-handling routine, an error occurs. +Using a **Resume** statement anywhere except in an error-handling routine raises an error. ### Example diff --git a/docs/Reference/Core/Select-Case.md b/docs/Reference/Core/Select-Case.md index d57f1f1..cb374c1 100644 --- a/docs/Reference/Core/Select-Case.md +++ b/docs/Reference/Core/Select-Case.md @@ -28,21 +28,21 @@ Syntax: - *expression* **To** *expression* - **Is** *comparisonoperator* *expression* - The **To** keyword specifies a range of values. If you use the **To** keyword, the smaller value must appear before **To**. + The **To** keyword specifies a range of values. When the **To** keyword is used, the smaller value must appear before **To**. Use the **Is** keyword with comparison operators (except **Is** and **Like**) to specify a range of values. If not supplied, the **Is** keyword is automatically inserted. *statements-n* -: *optional* One or more statements executed if *testexpression* matches any part of *expressionlist-n*. +: *optional* One or more statements executed if *testexpression* matches any part of *expressionlist-n*. *elsestatements* -: *optional* One or more statements executed if *testexpression* doesn't match any of the **Case** clauses. +: *optional* One or more statements executed if *testexpression* doesn't match any of the **Case** clauses. If *testexpression* matches any **Case** *expressionlist* expression, the *statements* following that **Case** clause are executed up to the next **Case** clause, or, for the last clause, up to **End Select**. Control then passes to the statement following **End Select**. If *testexpression* matches an *expressionlist* expression in more than one **Case** clause, only the statements following the first match are executed. -The **Case Else** clause is used to indicate the *elsestatements* to be executed if no match is found between the *testexpression* and an *expressionlist* in any of the other **Case** selections. Although not required, it is a good idea to have a **Case Else** statement in your **Select Case** block to handle unforeseen *testexpression* values. If no **Case** *expressionlist* matches *testexpression* and there is no **Case Else** statement, execution continues at the statement following **End Select**. +The **Case Else** clause is used to indicate the *elsestatements* to be executed if no match is found between the *testexpression* and an *expressionlist* in any of the other **Case** selections. Although not required, it is a good idea to have a **Case Else** statement in a **Select Case** block to handle unforeseen *testexpression* values. If no **Case** *expressionlist* matches *testexpression* and there is no **Case Else** statement, execution continues at the statement following **End Select**. -You can use multiple expressions or ranges in each **Case** clause. For example, the following line is valid: +Multiple expressions or ranges can appear in each **Case** clause. For example, the following line is valid: ```tb Case 1 To 4, 7 To 9, 11, 13, Is > MaxNumber @@ -51,7 +51,7 @@ Case 1 To 4, 7 To 9, 11, 13, Is > MaxNumber > [!NOTE] > The **Is** comparison operator is not the same as the **Is** keyword used in the **Select Case** statement. -You can also specify ranges and multiple expressions for character strings. In the following example, **Case** matches strings that are exactly equal to `everything`, strings that fall between `nuts` and `soup` in alphabetic order, and the current value of `TestItem`: +Ranges and multiple expressions can also be specified for character strings. In the following example, **Case** matches strings that are exactly equal to `everything`, strings that fall between `nuts` and `soup` in alphabetic order, and the current value of `TestItem`: ```tb Case "everything", "nuts" To "soup", TestItem diff --git a/docs/Reference/Core/Set.md b/docs/Reference/Core/Set.md index 2d1c495..c7f8dc3 100644 --- a/docs/Reference/Core/Set.md +++ b/docs/Reference/Core/Set.md @@ -16,17 +16,17 @@ Syntax: : Name of the variable or property; follows standard variable naming conventions. **[New](New)** -: *optional* **New** is usually used during declaration to enable implicit object creation. When **New** is used with **Set**, it creates a new instance of the class. If *objectvar* contained a reference to an object, that reference is released when the new one is assigned. The **New** keyword can't be used to create new instances of any intrinsic data type and can't be used to create dependent objects. +: *optional* **New** is usually used during declaration to enable implicit object creation. When **New** is used with **Set**, it creates a new instance of the class. If *objectvar* contained a reference to an object, that reference is released when the new one is assigned. The **New** keyword can't be used to create new instances of any intrinsic data type and can't be used to create dependent objects. *objectexpression* : Expression consisting of the name of an object, another declared variable of the same object type, or a function or method that returns an object of the same object type. **Nothing** -: *optional* Discontinues association of *objectvar* with any specific object. Assigning **Nothing** to *objectvar* releases all the system and memory resources associated with the previously referenced object when no other variable refers to it. +: *optional* Discontinues association of *objectvar* with any specific object. Assigning **Nothing** to *objectvar* releases all the system and memory resources associated with the previously referenced object when no other variable refers to it. To be valid, *objectvar* must be an object type consistent with the object being assigned to it. -The [**Dim**](Dim), [**Private**](Private), [**Public**](Public), [**ReDim**](ReDim), and [**Static**](Static) statements only declare a variable that refers to an object. No actual object is referred to until you use the **Set** statement to assign a specific object. +The [**Dim**](Dim), [**Private**](Private), [**Public**](Public), [**ReDim**](ReDim), and [**Static**](Static) statements only declare a variable that refers to an object. No actual object is referred to until the **Set** statement assigns a specific object. The following example illustrates how **Dim** is used to declare an array with the type `Form1`. No instance of `Form1` actually exists. **Set** then assigns references to new instances of `Form1` to the `myChildForms` variable. Such code might be used to create child forms in an MDI application. @@ -38,7 +38,7 @@ Set myChildForms(3) = New Form1 Set myChildForms(4) = New Form1 ``` -Generally, when you use **Set** to assign an object reference to a variable, no copy of the object is created for that variable. Instead, a reference to the object is created. More than one object variable can refer to the same object. Because such variables are references to the object rather than copies of the object, any change in the object is reflected in all variables that refer to it. However, when you use the **New** keyword in the **Set** statement, you are actually creating an instance of the object. +Generally, when **Set** is used to assign an object reference to a variable, no copy of the object is created for that variable. Instead, a reference to the object is created. More than one object variable can refer to the same object. Because such variables are references to the object rather than copies of the object, any change in the object is reflected in all variables that refer to it. However, when the **New** keyword is used in the **Set** statement, an instance of the object is actually created. ### Example diff --git a/docs/Reference/Core/Static.md b/docs/Reference/Core/Static.md index c659777..8ca9bee 100644 --- a/docs/Reference/Core/Static.md +++ b/docs/Reference/Core/Static.md @@ -16,13 +16,13 @@ Syntax: : Name of the variable; follows standard variable naming conventions. *subscripts* -: *optional* Dimensions of an array variable; up to 60 multiple dimensions may be declared. The *subscripts* argument uses the following syntax: [ *lower* **To** ] *upper* [ , [ *lower* **To** ] *upper* ] **. . .**. When not explicitly stated in *lower*, the lower bound of an array is controlled by the [**Option Base**](Option#Base) statement. The lower bound is zero if no **Option Base** statement is present. +: *optional* Dimensions of an array variable; up to 60 multiple dimensions may be declared. The *subscripts* argument uses the following syntax: [ *lower* **To** ] *upper* [ , [ *lower* **To** ] *upper* ] **. . .**. When not explicitly stated in *lower*, the lower bound of an array is controlled by the [**Option Base**](Option#Base) statement. The lower bound is zero if no **Option Base** statement is present. **New** -: *optional* Keyword that enables implicit creation of an object. If you use **New** when declaring the object variable, a new instance of the object is created on first reference to it, so you don't have to use the **[Set](Set)** statement to assign the object reference. The **New** keyword can't be used to declare variables of any intrinsic data type or to declare instances of dependent objects. +: *optional* Keyword that enables implicit creation of an object. When **New** is used to declare the object variable, a new instance of the object is created on first reference to it, so the **[Set](Set)** statement is not required to assign the object reference. The **New** keyword can't be used to declare variables of any intrinsic data type or to declare instances of dependent objects. *type* -: *optional* Data type of the variable; may be **Byte**, **Boolean**, **Integer**, **Long**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (for variable-length strings), **String** *length* (for fixed-length strings), **Object**, **Variant**, a user-defined type, or an object type. Use a separate **As** *type* clause for each variable being defined. +: *optional* Data type of the variable; may be **Byte**, **Boolean**, **Integer**, **Long**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (for variable-length strings), **String** *length* (for fixed-length strings), **Object**, **Variant**, a user-defined type, or an object type. Use a separate **As** *type* clause for each variable being defined. After module code is running, variables declared with the **Static** statement retain their value until the module is reset or restarted. In class modules, variables declared with the **Static** statement retain their value in each class instance until that instance is destroyed. In form modules, static variables retain their value until the form is closed. @@ -40,17 +40,16 @@ The following statement declares a variable for a new instance of a worksheet: Static X As New Worksheet ``` -If the **New** keyword isn't used when declaring an object variable, the variable that refers to the object must be assigned an existing object by using the **Set** statement before it can be used. Until it is assigned an object, the declared object variable has the special value **Nothing**, which indicates that it doesn't refer to any particular instance of an object. When you use the **New** keyword in the declaration, an instance of the object is created on the first reference to the object. +If the **New** keyword isn't used when declaring an object variable, the variable that refers to the object must be assigned an existing object by using the **Set** statement before it can be used. Until it is assigned an object, the declared object variable has the special value **Nothing**, which indicates that it doesn't refer to any particular instance of an object. When the **New** keyword is used in the declaration, an instance of the object is created on the first reference to the object. -If you don't specify a data type or object type, and there is no [**Deftype**](Deftype) statement in the module, the variable is **Variant** by default. +When no data type or object type is specified, and there is no [**Deftype**](Deftype) statement in the module, the variable is **Variant** by default. > [!NOTE] -> The **Static** statement and the **Static** keyword are similar, but used for different effects. If you declare a procedure by using the **Static** keyword (as in `Static Sub CountSales()`), the storage space for all local variables within the procedure is allocated once, and the value of the variables is preserved for the entire time the program is running. For nonstatic procedures, storage space for variables is allocated each time the procedure is called and released when the procedure is exited. The **Static** statement is used to declare specific variables within nonstatic procedures to preserve their value for as long as the program is running. +> The **Static** statement and the **Static** keyword are similar, but used for different effects. When a procedure is declared by using the **Static** keyword (as in `Static Sub CountSales()`), the storage space for all local variables within the procedure is allocated once, and the value of the variables is preserved for the entire time the program is running. For nonstatic procedures, storage space for variables is allocated each time the procedure is called and released when the procedure is exited. The **Static** statement is used to declare specific variables within nonstatic procedures to preserve their value for as long as the program is running. When variables are initialized, a numeric variable is initialized to 0, a variable-length string is initialized to a zero-length string (""), and a fixed-length string is filled with zeros. **Variant** variables are initialized to **Empty**. Each element of a user-defined type variable is initialized as if it were a separate variable. -> [!NOTE] -> When you use **Static** statements within a procedure, put them at the beginning of the procedure with other declarative statements such as **[Dim](Dim)**. +By convention, **Static** statements within a procedure are placed at the beginning of the procedure with other declarative statements such as **[Dim](Dim)**. ### Example diff --git a/docs/Reference/Core/Stop.md b/docs/Reference/Core/Stop.md index 7c5c39b..2602d23 100644 --- a/docs/Reference/Core/Stop.md +++ b/docs/Reference/Core/Stop.md @@ -14,7 +14,7 @@ Syntax: > **Stop** -You can place **Stop** statements anywhere in procedures to suspend execution. Using the **Stop** statement is similar to setting a breakpoint in the code. +**Stop** statements can be placed anywhere in procedures to suspend execution. Using the **Stop** statement is similar to setting a breakpoint in the code. The **Stop** statement suspends execution, but unlike [**End**](End), it doesn't close any files or clear variables, unless it is in a compiled executable (.exe) file. diff --git a/docs/Reference/Core/Sub.md b/docs/Reference/Core/Sub.md index ad828a6..be6031e 100644 --- a/docs/Reference/Core/Sub.md +++ b/docs/Reference/Core/Sub.md @@ -21,44 +21,44 @@ Syntax: : *optional* One or more of the [supported attributes](Attributes) for procedures. **Public** -: *optional* Indicates that the **Sub** procedure is accessible to all other procedures in all modules. If used in a module that contains an **Option Private**, the procedure is not available outside the project. +: *optional* Indicates that the **Sub** procedure is accessible to all other procedures in all modules. If used in a module that contains an **Option Private**, the procedure is not available outside the project. **Private** -: *optional* Indicates that the **Sub** procedure is accessible only to other procedures in the module where it is declared. +: *optional* Indicates that the **Sub** procedure is accessible only to other procedures in the module where it is declared. **Friend** -: *optional* Used only in a class module. Indicates that the **Sub** procedure is visible throughout the project, but not visible to a controller of an instance of an object. +: *optional* Used only in a class module. Indicates that the **Sub** procedure is visible throughout the project, but not visible to a controller of an instance of an object. **[Protected](Protected)** -: *optional* (twinBASIC) Used only in a class. Indicates that the **Sub** procedure is accessible from inside the declaring class and from classes that derive from it via [**Inherits**](../../Features/Language/Inheritance#inherits-for-complete-oop), but not from outside callers. +: *optional* (twinBASIC) Used only in a class. Indicates that the **Sub** procedure is accessible from inside the declaring class and from classes that derive from it via [**Inherits**](../../Features/Language/Inheritance#inherits-for-complete-oop), but not from outside callers. **[Static](Static)** -: *optional* Indicates that the **Sub** procedure's local variables are preserved between calls. The **Static** attribute doesn't affect variables that are declared outside the **Sub**, even if they are used in the procedure. +: *optional* Indicates that the **Sub** procedure's local variables are preserved between calls. The **Static** attribute doesn't affect variables that are declared outside the **Sub**, even if they are used in the procedure. **Overridable** -: *optional* (twinBASIC) Marks the **Sub** as an inheritance hook that classes derived via [**Inherits**](../../Features/Language/Inheritance#inherits-for-complete-oop) may replace with an **Overrides** clause. Meaningful only on a member of a class that participates in an **Inherits** hierarchy. +: *optional* (twinBASIC) Marks the **Sub** as an inheritance hook that classes derived via [**Inherits**](../../Features/Language/Inheritance#inherits-for-complete-oop) may replace with an **Overrides** clause. Meaningful only on a member of a class that participates in an **Inherits** hierarchy. *name* : Name of the **Sub**; follows standard variable naming conventions. The special name `New` declares an instance constructor — see [Inheritance](../../Features/Language/Inheritance) for chained construction with `*baseclass*.New(...)`. **Of** *typevars* -: *optional* One or more type variable names, following standard variable naming conventions. The names are separated by commas. Causes the procedure to be a generic **Sub**. +: *optional* One or more type variable names, following standard variable naming conventions. The names are separated by commas. Causes the procedure to be a generic **Sub**. *arglist* -: *optional* List of variables representing arguments that are passed to the **Sub** procedure when it is called. Multiple variables are separated by commas. See [*arglist*](#arglist) below for syntax. +: *optional* List of variables representing arguments that are passed to the **Sub** procedure when it is called. Multiple variables are separated by commas. See [*arglist*](#arglist) below for syntax. *binding-clause* -: *optional* (twinBASIC) One of three trailing clauses that bind this body to a member declared elsewhere: +: *optional* (twinBASIC) One of three trailing clauses that bind this body to a member declared elsewhere: - - **Handles** *object*.*event* [ **,** *object*.*event* … ] — wires this **Sub** up as a handler for the named event(s), replacing the traditional `Object_Event` naming convention. See [**Handles** statement](Handles). - - **Implements** *iface*.*member* [ **,** *iface2*.*member2* … ] — provides the body for the named [**Interface**](Interface) (or [**Class**](Class)) member, replacing the traditional `Iface_Member` naming convention. A comma-separated list lets one body satisfy several interfaces' members at once. See [**Implements** statement](Implements). + - **Handles** *object*.*event* [ **,** *object*.*event* … ] — connects this **Sub** as a handler for the named event(s), replacing the traditional `Object_Event` naming convention. See [**Handles** statement](Handles). + - **Implements** *iface*.*member* [ **,** *iface2*.*member2* … ] — provides the body for the named [**Interface**](Interface) (or [**Class**](Class)) member, replacing the traditional `Iface_Member` naming convention. A comma-separated list permits one body to satisfy several interfaces' members at once. See [**Implements** statement](Implements). - **Overrides** *base*.*member* — supplies the body for an **Overridable** *member* inherited via [**Inherits**](../../Features/Language/Inheritance#inherits-for-complete-oop). Combine with **Overridable** on the same header to allow further-derived classes to override again. *statements* -: *optional* Any group of statements to be executed within the **Sub** procedure. +: *optional* Any group of statements to be executed within the **Sub** procedure. **[Exit Sub](Exit)** -: *optional* Immediately returns from the **Sub** procedure. (A bare [**Return**](Return) statement does *not* exit a **Sub** — it is reserved for the [**GoSub...Return**](GoSub-Return) construct.) +: *optional* Immediately returns from the **Sub** procedure. (A bare [**Return**](Return) statement does *not* exit a **Sub** — it is reserved for the [**GoSub...Return**](GoSub-Return) construct.) ### *arglist* @@ -66,26 +66,26 @@ Syntax: One or more of [ **Optional** ] [ **ByVal** \| **ByRef** ] [ **[ParamArray](ParamArray)** ] *varname* [ **()** ] [ **As** *type* ] [ **=** *defaultvalue* ] **Optional** -: *optional* Indicates that an argument is not required. If used, all subsequent arguments in *arglist* must also be optional and declared by using the **Optional** keyword. **Optional** can't be used for any argument if **ParamArray** is used. +: *optional* Indicates that an argument is not required. If used, all subsequent arguments in *arglist* must also be optional and declared by using the **Optional** keyword. **Optional** can't be used for any argument if **ParamArray** is used. **ByVal** -: *optional* Indicates that the argument is passed by value. +: *optional* Indicates that the argument is passed by value. **ByRef** -: *optional* Indicates that the argument is passed by reference. **ByRef** is the default unlike in Visual Basic .NET. +: *optional* Indicates that the argument is passed by reference. **ByRef** is the default unlike in Visual Basic .NET. **[ParamArray](ParamArray)** -: *optional* Used only as the last argument in *arglist* to indicate that the final argument is an **Optional** array of **Variant** elements. The **ParamArray** keyword allows you to provide an arbitrary number of arguments. It may not be used with **ByVal**, **ByRef**, or **Optional**. +: *optional* Used only as the last argument in *arglist* to indicate that the final argument is an **Optional** array of **Variant** elements. The **ParamArray** keyword permits passing an arbitrary number of arguments. It may not be used with **ByVal**, **ByRef**, or **Optional**. *varname* : Name of the variable representing the argument; follows standard variable naming conventions. *type* -: *optional* Data type of the argument passed to the procedure; may be **Byte**, **Boolean**, **Integer**, **Long**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (variable length only), **Object**, **Variant**, a specific object type, or the name of a generic type argument. If the parameter is not **Optional**, a user-defined type may also be specified. +: *optional* Data type of the argument passed to the procedure; may be **Byte**, **Boolean**, **Integer**, **Long**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (variable length only), **Object**, **Variant**, a specific object type, or the name of a generic type argument. If the parameter is not **Optional**, a user-defined type may also be specified. If the name of a generic type parameter is used, it becomes bound to the concrete type of the argument passed to the procedure. The name binding has the scope of the body of the procedure. *defaultvalue* -: *optional* Any constant or constant expression. Valid for **Optional** parameters only. If the type is an **Object**, an explicit default value can only be **Nothing**. +: *optional* Any constant or constant expression. Valid for **Optional** parameters only. If the type is an **Object**, an explicit default value can only be **Nothing**. If not explicitly specified by using **Public**, **Private**, or **Friend**, **Sub** procedures are public by default. @@ -95,20 +95,20 @@ The **Friend** keyword can only be used in class modules. However, **Friend** pr **Sub** procedures can be recursive; that is, they can call themselves to perform a given task. However, recursion can lead to stack overflow. The **Static** keyword usually is not used with recursive **Sub** procedures. -All executable code must be in procedures. You can't define a **Sub** procedure inside another **[Sub](Sub)**, **[Function](Function)**, or **[Property](Property)** procedure. +All executable code must be in procedures. A **Sub** procedure cannot be defined inside another **[Sub](Sub)**, **[Function](Function)**, or **[Property](Property)** procedure. The **[Exit Sub](Exit)** statement causes an immediate exit from a **Sub** procedure. Program execution continues with the statement following the statement that called the **Sub** procedure. Any number of **Exit Sub** statements can appear anywhere in a **Sub** procedure. Like a **Function** procedure, a **Sub** procedure is a separate procedure that can take arguments, perform a series of statements, and change the value of its arguments. However, unlike a **Function** procedure, which returns a value, a **Sub** procedure can't be used in an expression. -You call a **Sub** procedure by using the procedure name followed by the argument list. See the **[Call](Call)** statement for specific information about how to call **Sub** procedures. +A **Sub** procedure is called by using the procedure name followed by the argument list. See the **[Call](Call)** statement for specific information about how to call **Sub** procedures. Variables used in **Sub** procedures fall into two categories: those that are explicitly declared within the procedure and those that are not. Variables that are explicitly declared in a procedure (using **Dim** or the equivalent) are always local to the procedure. Variables that are used but not explicitly declared in a procedure are also local unless they are explicitly declared at some higher level outside the procedure. -A procedure can use a variable that is not explicitly declared in the procedure, but a naming conflict can occur if anything you defined at the module level has the same name. If your procedure refers to an undeclared variable that has the same name as another procedure, constant, or variable, it is assumed that your procedure is referring to that module-level name. To avoid this kind of conflict, explicitly declare variables. Use an **[Option Explicit](Option#Explicit)** statement to force explicit declaration of variables. +A procedure can use a variable that is not explicitly declared in the procedure, but a naming conflict can occur if anything defined at the module level has the same name. When a procedure refers to an undeclared variable that has the same name as another procedure, constant, or variable, it is assumed that the procedure is referring to that module-level name. To avoid this kind of conflict, explicitly declare variables. Use an **[Option Explicit](Option#Explicit)** statement to force explicit declaration of variables. > [!NOTE] -> You can't use **GoSub**, **GoTo**, or **Return** to enter or exit a **Sub** procedure. Use [**Exit Sub**](Exit) to leave a **Sub** early. +> **GoSub**, **GoTo**, and **Return** cannot enter or exit a **Sub** procedure. Use [**Exit Sub**](Exit) to leave a **Sub** early. ### Example diff --git a/docs/Reference/Core/Type.md b/docs/Reference/Core/Type.md index 7d06678..ab162c2 100644 --- a/docs/Reference/Core/Type.md +++ b/docs/Reference/Core/Type.md @@ -20,13 +20,13 @@ Syntax: > **End Type** *attributes* -: *optional* (twinBASIC) Type-level attributes. Most notably [**PackingAlignment**](Attributes#packingalignment), which sets the field-alignment value used when laying out the UDT in memory — useful for interop with C structs declared under `#pragma pack` or `#include `. +: *optional* (twinBASIC) Type-level attributes. Most notably [**PackingAlignment**](Attributes#packingalignment), which sets the field-alignment value used when laying out the UDT in memory — useful for interop with C structs declared under `#pragma pack` or `#include `. **Public** -: *optional* Used to declare user-defined types that are available to all procedures in all modules in all projects. +: *optional* Used to declare user-defined types that are available to all procedures in all modules in all projects. **Private** -: *optional* Used to declare user-defined types that are available only within the module where the declaration is made. +: *optional* Used to declare user-defined types that are available only within the module where the declaration is made. *varname* : Name of the user-defined type; follows standard variable naming conventions. @@ -35,18 +35,18 @@ Syntax: : Name of an element of the user-defined type. Element names also follow standard variable naming conventions, except that keywords can be used. *subscripts* -: *optional* Dimensions of an array element. When not explicitly stated in *lower*, the lower bound of an array is controlled by the [**Option Base**](Option#Base) statement. The lower bound is zero if no **Option Base** statement is present. +: *optional* Dimensions of an array element. When not explicitly stated in *lower*, the lower bound of an array is controlled by the [**Option Base**](Option#Base) statement. The lower bound is zero if no **Option Base** statement is present. *type* : Data type of the element; may be **Byte**, **Boolean**, **Integer**, **Long**, **LongLong**, **LongPtr**, **Currency**, **Single**, **Double**, **Decimal**, **Date**, **String** (for variable-length strings), **String** *length* (for fixed-length strings), **Object**, **Variant**, another user-defined type, or an object type. In a generic **Type** (see below), *type* may also be one of the *typevars* introduced in the **Of** clause. **Of** *typevars* -: *optional* (twinBASIC) One or more type variable names, separated by commas, that make the **Type** a *generic UDT*. Each type variable can be referenced as the *type* of an element. See [Generics](../../Features/Language/Generics). Generic UDTs do not yet support member procedures. +: *optional* (twinBASIC) One or more type variable names, separated by commas, that make the **Type** a *generic UDT*. Each type variable can be referenced as the *type* of an element. See [Generics](../../Features/Language/Generics). Generic UDTs do not yet support member procedures. *member-procedure* -: *optional* (twinBASIC) A [**Sub**](Sub), [**Function**](Function), or [**Property**](Property) procedure, or a [**Declare**](Declare) external procedure, written inside the **Type** body and callable through any variable of that type. See [twinBASIC enhancements](#twinbasic-enhancements) below. +: *optional* (twinBASIC) A [**Sub**](Sub), [**Function**](Function), or [**Property**](Property) procedure, or a [**Declare**](Declare) external procedure, written inside the **Type** body and callable through any variable of that type. See [twinBASIC enhancements](#twinbasic-enhancements) below. -The **Type** statement can be used only at the module level. After you have declared a user-defined type by using the **Type** statement, you can declare a variable of that type anywhere within the scope of the declaration. Use [**Dim**](Dim), [**Private**](Private), [**Public**](Public), [**ReDim**](ReDim), or [**Static**](Static) to declare a variable of a user-defined type. +The **Type** statement can be used only at the module level. After a user-defined type has been declared by using the **Type** statement, a variable of that type can be declared anywhere within the scope of the declaration. Use [**Dim**](Dim), [**Private**](Private), [**Public**](Public), [**ReDim**](ReDim), or [**Static**](Static) to declare a variable of a user-defined type. In standard modules and class modules, user-defined types are public by default. This visibility can be changed by using the **Private** keyword. @@ -67,7 +67,7 @@ Dim Washington(1 To 100) As StateData In the preceding example, `StateData` includes the `CityCode` static array, and the record `Washington` has the same structure as `StateData`. -When you declare a fixed-size array within a user-defined type, its dimensions must be declared with numeric literals or constants rather than variables. +When a fixed-size array is declared within a user-defined type, its dimensions must be declared with numeric literals or constants rather than variables. ### Example diff --git a/docs/Reference/Core/Unlock.md b/docs/Reference/Core/Unlock.md index 6002935..341c044 100644 --- a/docs/Reference/Core/Unlock.md +++ b/docs/Reference/Core/Unlock.md @@ -17,7 +17,7 @@ Syntax: The arguments to **Unlock** must match exactly the arguments of the corresponding **Lock** statement. See [**Lock, Unlock**](Lock) for full details. > [!IMPORTANT] -> Be sure to remove all locks with an **Unlock** statement before closing a file or quitting your program. Failure to remove locks produces unpredictable results. +> Be sure to remove all locks with an **Unlock** statement before closing a file or quitting the program. Failure to remove locks produces unpredictable results. ### See Also diff --git a/docs/Reference/Core/While-Wend.md b/docs/Reference/Core/While-Wend.md index 209898d..4b0b1a0 100644 --- a/docs/Reference/Core/While-Wend.md +++ b/docs/Reference/Core/While-Wend.md @@ -20,7 +20,7 @@ Syntax: : Numeric expression or string expression that evaluates to **True** or **False**. If *condition* is Null, *condition* is treated as **False**. *statements* -: *optional* One or more statements executed while *condition* is **True**. +: *optional* One or more statements executed while *condition* is **True**. If *condition* is **True**, all *statements* are executed until the **Wend** statement is encountered. Control then returns to the **While** statement and *condition* is again checked. If *condition* is still **True**, the process is repeated. If it is not **True**, execution resumes with the statement following the **Wend** statement. diff --git a/docs/Reference/Core/With.md b/docs/Reference/Core/With.md index 29f7f74..b825238 100644 --- a/docs/Reference/Core/With.md +++ b/docs/Reference/Core/With.md @@ -20,9 +20,9 @@ Syntax: : Name of an object or a user-defined type. *statements* -: *optional* One or more statements to be executed on *object*. +: *optional* One or more statements to be executed on *object*. -The **With** statement allows you to perform a series of statements on a specified object without requalifying the name of the object. For example, to change a number of different properties on a single object, place the property assignment statements within the **With** control structure, referring to the object once instead of referring to it with each property assignment. +The **With** statement permits a series of statements on a specified object without requalifying the name of the object. For example, to change a number of different properties on a single object, place the property assignment statements within the **With** control structure, referring to the object once instead of referring to it with each property assignment. The following example illustrates use of the **With** statement to assign values to several properties of the same object. @@ -35,12 +35,12 @@ End With ``` > [!NOTE] -> Once a **With** block is entered, *object* can't be changed. As a result, you can't use a single **With** statement to affect a number of different objects. +> Once a **With** block is entered, *object* can't be changed. As a result, a single **With** statement cannot affect a number of different objects. -You can nest **With** statements by placing one **With** block within another. However, because members of outer **With** blocks are masked within the inner **With** blocks, you must provide a fully qualified object reference in an inner **With** block to any member of an object in an outer **With** block. +**With** statements can be nested by placing one **With** block within another. However, because members of outer **With** blocks are masked within the inner **With** blocks, a fully qualified object reference must be supplied in an inner **With** block to any member of an object in an outer **With** block. -> [!NOTE] -> In general, it's recommended that you don't jump into or out of **With** blocks. If statements in a **With** block are executed, but either the **With** or **End With** statement is not executed, a temporary variable containing a reference to the object remains in memory until you exit the procedure. +> [!IMPORTANT] +> Jumping into or out of **With** blocks is not recommended. If statements in a **With** block are executed, but either the **With** or **End With** statement is not executed, a temporary variable containing a reference to the object remains in memory until the procedure exits. ### Example diff --git a/docs/Reference/Core/Write.md b/docs/Reference/Core/Write.md index 625927b..123166f 100644 --- a/docs/Reference/Core/Write.md +++ b/docs/Reference/Core/Write.md @@ -16,11 +16,11 @@ Syntax: : Any valid file number. *outputlist* -: *optional* One or more comma-delimited numeric expressions or string expressions to write to a file. +: *optional* One or more comma-delimited numeric expressions or string expressions to write to a file. Data written with **Write #** is usually read from a file with [**Input #**](Input). -If you omit *outputlist* and include a comma after *filenumber*, a blank line is printed to the file. Multiple expressions can be separated with a space, a semicolon, or a comma. A space has the same effect as a semicolon. +When *outputlist* is omitted and a comma follows *filenumber*, a blank line is printed to the file. Multiple expressions can be separated with a space, a semicolon, or a comma. A space has the same effect as a semicolon. When **Write #** is used to write data to a file, several universal assumptions are followed so that the data can always be read and correctly interpreted by using **Input #**, regardless of locale: @@ -30,10 +30,10 @@ When **Write #** is used to write data to a file, several universal assumptions - Nothing is written to the file if *outputlist* data is **Empty**. However, for **Null** data, `#NULL#` is written. - For **Error** data, the output appears as `#ERROR `*errorcode*`#`. The **Error** keyword is not translated, regardless of locale. -Unlike the [**Print #**](Print) statement, the **Write #** statement inserts commas between items and quotation marks around strings as they are written to the file. You don't have to put explicit delimiters in the list. **Write #** inserts a newline character — that is, a carriage return-linefeed (**Chr**(13) + **Chr**(10)) — after it has written the final character in *outputlist* to the file. +Unlike the [**Print #**](Print) statement, the **Write #** statement inserts commas between items and quotation marks around strings as they are written to the file. Explicit delimiters in the list are not required. **Write #** inserts a newline character — that is, a carriage return-linefeed (**Chr**(13) + **Chr**(10)) — after it has written the final character in *outputlist* to the file. -> [!NOTE] -> You should not write strings that contain embedded quotation marks (for example, `"1,2""X"`) for use with the **Input #** statement; **Input #** parses this string as two complete and separate strings. +> [!IMPORTANT] +> Do not write strings that contain embedded quotation marks (for example, `"1,2""X"`) for use with the **Input #** statement; **Input #** parses this string as two complete and separate strings. ### Example From c0912dfb6f000b749ddbadcf5253e9309d33877b Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Thu, 14 May 2026 21:57:31 +0200 Subject: [PATCH 06/19] Apply structural style rules to CustomControls package --- docs/Reference/CustomControls/Enumerations/BorderStyle.md | 2 +- docs/Reference/CustomControls/Enumerations/ColorRGBA.md | 7 +++---- docs/Reference/CustomControls/Enumerations/CornerShape.md | 2 +- docs/Reference/CustomControls/Enumerations/DockMode.md | 2 +- docs/Reference/CustomControls/Enumerations/FillPattern.md | 2 +- docs/Reference/CustomControls/Enumerations/FontWeight.md | 2 +- docs/Reference/CustomControls/Enumerations/PixelCount.md | 5 ++--- docs/Reference/CustomControls/Enumerations/PointSize.md | 5 ++--- .../CustomControls/Enumerations/StartupPosition.md | 2 +- .../Reference/CustomControls/Enumerations/TextAlignment.md | 2 +- .../CustomControls/Enumerations/TextOverflowMode.md | 2 +- docs/Reference/CustomControls/Enumerations/WindowState.md | 2 +- docs/Reference/CustomControls/Framework/Canvas.md | 2 +- .../CustomControls/Framework/CustomControlContext.md | 2 +- .../CustomControls/Framework/CustomControlsCollection.md | 2 +- docs/Reference/CustomControls/Framework/ICustomControl.md | 4 ++-- docs/Reference/CustomControls/Framework/index.md | 6 +++--- docs/Reference/CustomControls/Styles/Borders.md | 2 +- docs/Reference/CustomControls/Styles/Corners.md | 2 +- docs/Reference/CustomControls/Styles/Fill.md | 4 ++-- docs/Reference/CustomControls/Styles/Line.md | 4 ++-- docs/Reference/CustomControls/Styles/Padding.md | 2 +- docs/Reference/CustomControls/Styles/TextRendering.md | 4 ++-- docs/Reference/CustomControls/Styles/index.md | 2 +- .../CustomControls/WaynesButton/WaynesButtonState.md | 4 ++-- .../CustomControls/WaynesForm/WindowsFormOptions.md | 4 ++-- docs/Reference/CustomControls/WaynesForm/index.md | 4 ++-- docs/Reference/CustomControls/WaynesFrame.md | 2 +- docs/Reference/CustomControls/WaynesGrid/Column.md | 2 +- docs/Reference/CustomControls/WaynesGrid/index.md | 2 +- .../CustomControls/WaynesSlider/WaynesSliderState.md | 2 +- .../CustomControls/WaynesTextBox/WaynesTextBoxState.md | 2 +- docs/Reference/CustomControls/index.md | 6 +++--- 33 files changed, 48 insertions(+), 51 deletions(-) diff --git a/docs/Reference/CustomControls/Enumerations/BorderStyle.md b/docs/Reference/CustomControls/Enumerations/BorderStyle.md index 5c3720b..e485fcb 100644 --- a/docs/Reference/CustomControls/Enumerations/BorderStyle.md +++ b/docs/Reference/CustomControls/Enumerations/BorderStyle.md @@ -7,7 +7,7 @@ permalink: /tB/Packages/CustomControls/Enumerations/BorderStyle # BorderStyle {: .no_toc } -The Win32 frame style used by a [**WaynesForm**](../WaynesForm/) window. Determines whether the window has a thick or thin border, whether it can be resized by dragging an edge, and whether it shows a normal title bar or the smaller tool-window title bar. Carried by [**WindowsFormOptions.BorderStyle**](../WaynesForm/WindowsFormOptions#borderstyle). +The Win32 frame style used by a [**WaynesForm**](../WaynesForm/) window. Determines whether the window has a thick or thin border, whether it can be resized by dragging an edge, and whether it shows a normal title bar or the smaller tool-window title bar. Used by [**WindowsFormOptions.BorderStyle**](../WaynesForm/WindowsFormOptions#borderstyle). | Constant | Value | Description | |----------|-------|-------------| diff --git a/docs/Reference/CustomControls/Enumerations/ColorRGBA.md b/docs/Reference/CustomControls/Enumerations/ColorRGBA.md index 7a8c057..734caf9 100644 --- a/docs/Reference/CustomControls/Enumerations/ColorRGBA.md +++ b/docs/Reference/CustomControls/Enumerations/ColorRGBA.md @@ -7,12 +7,11 @@ permalink: /tB/Packages/CustomControls/Enumerations/ColorRGBA # ColorRGBA {: .no_toc } -> [!NOTE] -> **ColorRGBA** is declared as an empty `Enum` block (with a placeholder `[_MAX] = 0` member) only because twinBASIC has not yet exposed a type-alias syntax such as `Type ColorRGBA = Long`. The source has a `FIXME` comment noting the stand-in. Treat **ColorRGBA** as a **Long**-compatible type alias rather than as an enumeration with named members; when alias syntax becomes available, the enum stand-in will be replaced. - A **Long**-compatible type alias used wherever a 32-bit ABGR colour value is expected. The high byte is the alpha channel — `&HFF000000` is fully opaque, `&H00000000` is fully transparent — and the low three bytes follow the standard `vbBlue`/`vbGreen`/`vbRed` order used by the [**ColorConstants**](../../VBRUN/Constants/ColorConstants) `Long`-coloured constants. Used by [**FillColorPoint.Color**](../Styles/Fill#color) and by the **RGBA** parameter of [**FillColorPoints.SetSolidColorRGBA**](../Styles/Fill#setsolidcolorrgba) / [**Borders.SetSimpleBorderRGBA**](../Styles/Borders#setsimpleborderrgba). -To write a fully-opaque colour, OR-in the opaque alpha mask: `&HFF000000 Or vbBlue`. The convenience setters [**FillColorPoints.SetSolidColor**](../Styles/Fill#setsolidcolor) and [**Borders.SetSimpleBorder**](../Styles/Borders#setsimpleborder) take a normal three-byte **Long** colour and apply the opaque mask for you; only the `*RGBA` variants take a raw **ColorRGBA**. +**ColorRGBA** is declared as an empty `Enum` block (with a placeholder `[_MAX] = 0` member) only because twinBASIC has not yet exposed a type-alias syntax such as `Type ColorRGBA = Long`. The source has a `FIXME` comment noting the stand-in. Treat **ColorRGBA** as a **Long**-compatible type alias rather than as an enumeration with named members; when alias syntax becomes available, the enum stand-in will be replaced. + +To write a fully-opaque colour, OR-in the opaque alpha mask: `&HFF000000 Or vbBlue`. The convenience setters [**FillColorPoints.SetSolidColor**](../Styles/Fill#setsolidcolor) and [**Borders.SetSimpleBorder**](../Styles/Borders#setsimpleborder) take a normal three-byte **Long** colour and apply the opaque mask automatically; only the `*RGBA` variants take a raw **ColorRGBA**. ```tb Dim translucentRed As ColorRGBA = &H800000FF& ' 50% alpha, full red diff --git a/docs/Reference/CustomControls/Enumerations/CornerShape.md b/docs/Reference/CustomControls/Enumerations/CornerShape.md index 3fc0d1b..0c02af2 100644 --- a/docs/Reference/CustomControls/Enumerations/CornerShape.md +++ b/docs/Reference/CustomControls/Enumerations/CornerShape.md @@ -7,7 +7,7 @@ permalink: /tB/Packages/CustomControls/Enumerations/CornerShape # CornerShape {: .no_toc } -Determines how a single corner of a control is shaped. Carried by [**Corner.Shape**](../Styles/Corners#shape), which is set independently for each of the four corners of any control that exposes a [**Corners**](../Styles/Corners) style object. The numeric value of the radius is supplied separately by [**Corner.Radius**](../Styles/Corners#radius). +Determines how a single corner of a control is shaped. Used by [**Corner.Shape**](../Styles/Corners#shape), which is set independently for each of the four corners of any control that exposes a [**Corners**](../Styles/Corners) style object. The numeric value of the radius is supplied separately by [**Corner.Radius**](../Styles/Corners#radius). | Constant | Value | Description | |----------|-------|-------------| diff --git a/docs/Reference/CustomControls/Enumerations/DockMode.md b/docs/Reference/CustomControls/Enumerations/DockMode.md index 2dd52c8..21ee02b 100644 --- a/docs/Reference/CustomControls/Enumerations/DockMode.md +++ b/docs/Reference/CustomControls/Enumerations/DockMode.md @@ -7,7 +7,7 @@ permalink: /tB/Packages/CustomControls/Enumerations/DockMode # DockMode {: .no_toc } -How a control is positioned relative to its container — attached to one edge, filling the whole client area, or not docked at all (positioned absolutely by [**Left**](../#controls) / [**Top**](../#controls) / [**Width**](../#controls) / [**Height**](../#controls)). Carried by the **Dock** property that every concrete custom control inherits. +How a control is positioned relative to its container — attached to one edge, filling the whole client area, or not docked at all (positioned absolutely by [**Left**](../#controls) / [**Top**](../#controls) / [**Width**](../#controls) / [**Height**](../#controls)). Used by the **Dock** property that every concrete custom control inherits. | Constant | Value | Description | |----------|-------|-------------| diff --git a/docs/Reference/CustomControls/Enumerations/FillPattern.md b/docs/Reference/CustomControls/Enumerations/FillPattern.md index 2004ddb..6f8e59b 100644 --- a/docs/Reference/CustomControls/Enumerations/FillPattern.md +++ b/docs/Reference/CustomControls/Enumerations/FillPattern.md @@ -7,7 +7,7 @@ permalink: /tB/Packages/CustomControls/Enumerations/FillPattern # FillPattern {: .no_toc } -Identifies how the colour table held by a [**Fill**](../Styles/Fill) is applied across the area being painted. The same colour stops produce very different results depending on the pattern — a north-to-south gradient with two stops paints a top-to-bottom transition, while a corner gradient with the same stops paints from one corner outward. Carried by [**Fill.Pattern**](../Styles/Fill#pattern). +Identifies how the colour table held by a [**Fill**](../Styles/Fill) is applied across the area being painted. The same colour stops produce very different results depending on the pattern — a north-to-south gradient with two stops paints a top-to-bottom transition, while a corner gradient with the same stops paints from one corner outward. Used by [**Fill.Pattern**](../Styles/Fill#pattern). | Constant | Value | Description | |----------|-------|-------------| diff --git a/docs/Reference/CustomControls/Enumerations/FontWeight.md b/docs/Reference/CustomControls/Enumerations/FontWeight.md index ed2fb50..f41e4e0 100644 --- a/docs/Reference/CustomControls/Enumerations/FontWeight.md +++ b/docs/Reference/CustomControls/Enumerations/FontWeight.md @@ -7,7 +7,7 @@ permalink: /tB/Packages/CustomControls/Enumerations/FontWeight # FontWeight {: .no_toc } -The weight of a font face, on the standard 100 – 900 scale used by OpenType's `wght` axis and by CSS's `font-weight`. Carried by [**FontStyle.Weight**](../Styles/TextRendering#weight); availability of each weight depends on which faces are installed for the chosen font family. +The weight of a font face, on the standard 100 – 900 scale used by OpenType's `wght` axis and by CSS's `font-weight`. Assigned to [**FontStyle.Weight**](../Styles/TextRendering#weight); availability of each weight depends on which faces are installed for the chosen font family. | Constant | Value | Description | |----------|-------|-------------| diff --git a/docs/Reference/CustomControls/Enumerations/PixelCount.md b/docs/Reference/CustomControls/Enumerations/PixelCount.md index 6f620f2..2eaa51e 100644 --- a/docs/Reference/CustomControls/Enumerations/PixelCount.md +++ b/docs/Reference/CustomControls/Enumerations/PixelCount.md @@ -7,9 +7,8 @@ permalink: /tB/Packages/CustomControls/Enumerations/PixelCount # PixelCount {: .no_toc } -> [!NOTE] -> **PixelCount** is declared as an empty `Enum` block (with a placeholder `[_MAX] = 0` member) only because twinBASIC has not yet exposed a type-alias syntax such as `Type PixelCount = Long`. The source has a `FIXME` comment noting the stand-in. Treat **PixelCount** as a **Long**-compatible type alias rather than as an enumeration with named members; when alias syntax becomes available, the enum stand-in will be replaced. - A **Long**-compatible type alias used wherever a measurement in pixels is expected. Used pervasively across the package — every control's inherited **Left**, **Top**, **Width**, **Height** are typed as **PixelCount**, as are [**Corner.Radius**](../Styles/Corners#radius), [**Padding**](../Styles/Padding) fields, [**Border.StrokeSize**](../Styles/Borders#strokesize), and many more. +**PixelCount** is declared as an empty `Enum` block (with a placeholder `[_MAX] = 0` member) only because twinBASIC has not yet exposed a type-alias syntax such as `Type PixelCount = Long`. The source has a `FIXME` comment noting the stand-in. Treat **PixelCount** as a **Long**-compatible type alias rather than as an enumeration with named members; when alias syntax becomes available, the enum stand-in will be replaced. + The package treats one **PixelCount** as one *unscaled* pixel; the design-time canvas is at 96 DPI. The runtime scales the value for the active monitor's DPI when painting, so a 15-pixel corner radius looks the same on a 96-DPI and a 192-DPI display. Inside an [**ICustomControl.Paint**](../Framework/ICustomControl#paint) implementation, the scale factor is available through [**Canvas.RuntimeUICCGetDpiScaleFactor**](../Framework/Canvas#runtimeuiccgetdpiscalefactor). diff --git a/docs/Reference/CustomControls/Enumerations/PointSize.md b/docs/Reference/CustomControls/Enumerations/PointSize.md index db8e156..41717f8 100644 --- a/docs/Reference/CustomControls/Enumerations/PointSize.md +++ b/docs/Reference/CustomControls/Enumerations/PointSize.md @@ -7,7 +7,6 @@ permalink: /tB/Packages/CustomControls/Enumerations/PointSize # PointSize {: .no_toc } -> [!NOTE] -> **PointSize** is declared as an empty `Enum` block (with a placeholder `[_MAX] = 0` member) only because twinBASIC has not yet exposed a type-alias syntax such as `Type PointSize = Long`. The source contains a `FIXME` comment noting the stand-in. Treat **PointSize** as a **Long**-compatible type alias rather than as an enumeration with named members; when alias syntax becomes available, the enum stand-in will be replaced. - A **Long**-compatible type alias for a font size, expressed in *typographic points* (a point is 1⁄72 of an inch). Used by [**FontStyle.Size**](../Styles/TextRendering#size). New [**FontStyle**](../Styles/TextRendering) objects default to 12 points. + +**PointSize** is declared as an empty `Enum` block (with a placeholder `[_MAX] = 0` member) only because twinBASIC has not yet exposed a type-alias syntax such as `Type PointSize = Long`. The source contains a `FIXME` comment noting the stand-in. Treat **PointSize** as a **Long**-compatible type alias rather than as an enumeration with named members; when alias syntax becomes available, the enum stand-in will be replaced. diff --git a/docs/Reference/CustomControls/Enumerations/StartupPosition.md b/docs/Reference/CustomControls/Enumerations/StartupPosition.md index 435ca2f..5479fec 100644 --- a/docs/Reference/CustomControls/Enumerations/StartupPosition.md +++ b/docs/Reference/CustomControls/Enumerations/StartupPosition.md @@ -7,7 +7,7 @@ permalink: /tB/Packages/CustomControls/Enumerations/StartupPosition # StartupPosition {: .no_toc } -The initial position of a form's window when it is first shown. Carried by [**WindowsFormOptions.StartUpPosition**](../WaynesForm/WindowsFormOptions#startupposition). Honoured once, at the form's first display; subsequent moves are at the user's discretion or controlled by code. +The initial position of a form's window when it is first shown. Used by [**WindowsFormOptions.StartUpPosition**](../WaynesForm/WindowsFormOptions#startupposition). Honoured once, at the form's first display; subsequent moves are at the user's discretion or controlled by code. | Constant | Value | Description | |----------|-------|-------------| diff --git a/docs/Reference/CustomControls/Enumerations/TextAlignment.md b/docs/Reference/CustomControls/Enumerations/TextAlignment.md index 57bbdf8..91907b1 100644 --- a/docs/Reference/CustomControls/Enumerations/TextAlignment.md +++ b/docs/Reference/CustomControls/Enumerations/TextAlignment.md @@ -7,7 +7,7 @@ permalink: /tB/Packages/CustomControls/Enumerations/TextAlignment # TextAlignment {: .no_toc } -Horizontal and vertical alignment of text drawn inside a control's bounding rectangle. Carried by [**TextRendering.Alignment**](../Styles/TextRendering#alignment); each member combines one of three vertical positions (top, middle, bottom) with one of three horizontal positions (left, centre, right). +Horizontal and vertical alignment of text drawn inside a control's bounding rectangle. Used by [**TextRendering.Alignment**](../Styles/TextRendering#alignment); each member combines one of three vertical positions (top, middle, bottom) with one of three horizontal positions (left, centre, right). | Constant | Value | Description | |----------|-------|-------------| diff --git a/docs/Reference/CustomControls/Enumerations/TextOverflowMode.md b/docs/Reference/CustomControls/Enumerations/TextOverflowMode.md index 7f394ba..1262bf4 100644 --- a/docs/Reference/CustomControls/Enumerations/TextOverflowMode.md +++ b/docs/Reference/CustomControls/Enumerations/TextOverflowMode.md @@ -7,7 +7,7 @@ permalink: /tB/Packages/CustomControls/Enumerations/TextOverflowMode # TextOverflowMode {: .no_toc } -Controls how text that does not fit inside the available rectangle is truncated. Carried by [**TextRendering.OverflowMode**](../Styles/TextRendering#overflowmode). +Controls how text that does not fit inside the available rectangle is truncated. Used by [**TextRendering.OverflowMode**](../Styles/TextRendering#overflowmode). | Constant | Value | Description | |----------|-------|-------------| diff --git a/docs/Reference/CustomControls/Enumerations/WindowState.md b/docs/Reference/CustomControls/Enumerations/WindowState.md index f7b396e..3c7ed12 100644 --- a/docs/Reference/CustomControls/Enumerations/WindowState.md +++ b/docs/Reference/CustomControls/Enumerations/WindowState.md @@ -7,7 +7,7 @@ permalink: /tB/Packages/CustomControls/Enumerations/WindowState # WindowState {: .no_toc } -The window state of a [**WaynesForm**](../WaynesForm/) — minimized, restored to normal size, or maximized to fill its monitor. Carried by [**WindowsFormOptions.WindowState**](../WaynesForm/WindowsFormOptions#windowstate); honoured once when the form is first shown. +The window state of a [**WaynesForm**](../WaynesForm/) — minimized, restored to normal size, or maximized to fill its monitor. Used by [**WindowsFormOptions.WindowState**](../WaynesForm/WindowsFormOptions#windowstate); honoured once when the form is first shown. | Constant | Value | Description | |----------|-------|-------------| diff --git a/docs/Reference/CustomControls/Framework/Canvas.md b/docs/Reference/CustomControls/Framework/Canvas.md index 7bcd1a5..61b479d 100644 --- a/docs/Reference/CustomControls/Framework/Canvas.md +++ b/docs/Reference/CustomControls/Framework/Canvas.md @@ -11,7 +11,7 @@ has_toc: false The drawing surface a custom control paints onto. Passed to [**ICustomControl.Paint**](ICustomControl#paint) on every redraw pass and used exclusively from inside that method — its lifetime is the duration of the single paint pass. -A custom control builds up one or more `ElementDescriptor` records describing the rectangles it wants to draw — each with a position, size, fill, borders, corners, text, cursor, tab-index, and a set of `AddressOf`-registered input callbacks — and hands each descriptor to [**RuntimeUICCCanvasAddElement**](#runtimeuicccanvasaddelement). The framework rasterises the descriptor, routes hit-testing to the registered callbacks, and (where the descriptor opts in) tracks keyboard tab order and focus. +A custom control builds up one or more `ElementDescriptor` records describing the rectangles to draw — each with a position, size, fill, borders, corners, text, cursor, tab-index, and a set of `AddressOf`-registered input callbacks — and passes each descriptor to [**RuntimeUICCCanvasAddElement**](#runtimeuicccanvasaddelement). The framework rasterises the descriptor, routes hit-testing to the registered callbacks, and (where the descriptor opts in) tracks keyboard tab order and focus. ```tb Private Sub OnPaint(ByVal Canvas As CustomControls.Canvas) _ diff --git a/docs/Reference/CustomControls/Framework/CustomControlContext.md b/docs/Reference/CustomControls/Framework/CustomControlContext.md index 16c8dec..ded67dd 100644 --- a/docs/Reference/CustomControls/Framework/CustomControlContext.md +++ b/docs/Reference/CustomControls/Framework/CustomControlContext.md @@ -9,7 +9,7 @@ has_toc: false # CustomControlContext class {: .no_toc } -The callback object handed to a custom control's [**Initialize**](ICustomControl#initialize). Holds the connection back into the framework — used to deserialize designer-set property values, request repaints, create timers, and move the keyboard focus between elements the control has drawn. +The callback object passed to a custom control's [**Initialize**](ICustomControl#initialize). Holds the connection back into the framework — used to deserialize designer-set property values, request repaints, create timers, and move the keyboard focus between elements the control has drawn. Custom controls store the **CustomControlContext** in a private field (typically called **ControlContext**) so that they can call back into the framework at any point after **Initialize** has returned. The form-class counterpart [**CustomFormContext**](CustomFormContext) extends this with **Show** and **Close**. diff --git a/docs/Reference/CustomControls/Framework/CustomControlsCollection.md b/docs/Reference/CustomControls/Framework/CustomControlsCollection.md index 891f864..979b0b0 100644 --- a/docs/Reference/CustomControls/Framework/CustomControlsCollection.md +++ b/docs/Reference/CustomControls/Framework/CustomControlsCollection.md @@ -9,7 +9,7 @@ has_toc: false # CustomControlsCollection class {: .no_toc } -The collection of controls hosted on a custom form. Reached as the **Controls** property of a [**WaynesForm**](../WaynesForm/). Supports indexed access by integer or name, enumeration with **For Each**, and runtime add / remove of controls. +The collection of controls hosted on a custom form. Accessed as the **Controls** property of a [**WaynesForm**](../WaynesForm/). Supports indexed access by integer or name, enumeration with **For Each**, and runtime add / remove of controls. ```tb Dim ctl As Object diff --git a/docs/Reference/CustomControls/Framework/ICustomControl.md b/docs/Reference/CustomControls/Framework/ICustomControl.md index 143c573..2b0a1b0 100644 --- a/docs/Reference/CustomControls/Framework/ICustomControl.md +++ b/docs/Reference/CustomControls/Framework/ICustomControl.md @@ -58,7 +58,7 @@ A common implementation calls **Context.GetSerializer().RuntimeUISrzDeserialize( ### Paint {: .no_toc } -Called every time the framework needs to redraw the control's client area. The implementation builds one or more `ElementDescriptor` records describing the rectangles to draw and hands each to *Canvas*. **RuntimeUICCCanvasAddElement**. +Called every time the framework needs to redraw the control's client area. The implementation builds one or more `ElementDescriptor` records describing the rectangles to draw and passes each to *Canvas*. **RuntimeUICCCanvasAddElement**. Syntax: *object*.**Paint** ( *Canvas* ) @@ -67,4 +67,4 @@ Syntax: *object*.**Paint** ( *Canvas* ) A descriptor may include event callbacks (`OnClick`, `OnMouseDown`, …) as `AddressOf` pointers; the framework dispatches input back through those pointers without the control needing to subscribe explicitly to anything. -A control should request additional repaints by calling [**CustomControlContext.Repaint**](CustomControlContext#repaint), not by calling **Paint** directly — the framework decides when to issue the actual paint pass. +A control should request additional repaints by calling [**CustomControlContext.Repaint**](CustomControlContext#repaint), not by calling **Paint** directly — the framework controls when to issue the actual paint pass. diff --git a/docs/Reference/CustomControls/Framework/index.md b/docs/Reference/CustomControls/Framework/index.md index b0d2bf2..d005cfe 100644 --- a/docs/Reference/CustomControls/Framework/index.md +++ b/docs/Reference/CustomControls/Framework/index.md @@ -12,8 +12,8 @@ The framework half of the [**CustomControls**](..) package — the interfaces, c A custom control: 1. Implements [**ICustomControl**](ICustomControl) (or [**ICustomForm**](ICustomForm) for a form-class custom control). -2. Stores the [**CustomControlContext**](CustomControlContext) handed to it on **Initialize** and uses it to request repaints, create timers, or change the focused element. -3. Inside **Paint**, builds one or more `ElementDescriptor` records and hands them to the [**Canvas**](Canvas) via **RuntimeUICCCanvasAddElement** — the framework rasterises them, handles input routing, and dispatches events back through the descriptor's `AddressOf`-registered callbacks. +2. Stores the [**CustomControlContext**](CustomControlContext) passed to it on **Initialize** and uses it to request repaints, create timers, or change the focused element. +3. Inside **Paint**, builds one or more `ElementDescriptor` records and passes them to the [**Canvas**](Canvas) via **RuntimeUICCCanvasAddElement** — the framework rasterises them, handles input routing, and dispatches events back through the descriptor's `AddressOf`-registered callbacks. ```tb Class MyControl @@ -52,4 +52,4 @@ End Class ## Drawing primitives - [Canvas](Canvas) -- the drawing surface passed to **Paint**; **RuntimeUICCCanvasAddElement**, plus size and DPI accessors -- [SerializeInfo](SerializeInfo) -- the per-instance serializer reached via **CustomControlContext.GetSerializer**; **RuntimeUISrzDeserialize**, design-mode flags, owner handle, runtime mode +- [SerializeInfo](SerializeInfo) -- the per-instance serializer returned by **CustomControlContext.GetSerializer**; **RuntimeUISrzDeserialize**, design-mode flags, owner handle, runtime mode diff --git a/docs/Reference/CustomControls/Styles/Borders.md b/docs/Reference/CustomControls/Styles/Borders.md index 1706090..ba93dbe 100644 --- a/docs/Reference/CustomControls/Styles/Borders.md +++ b/docs/Reference/CustomControls/Styles/Borders.md @@ -11,7 +11,7 @@ has_toc: false The collection of border strokes drawn around a region. Each stroke is an independent [**Border**](#border-class) sub-object with its own thickness, fill, and blending behaviour, layered in source order. A single thin black outline is a one-element collection — easiest constructed by calling [**SetSimpleBorder**](#setsimpleborder). -Reached as `.Borders`, [**CellRenderingOptions.Borders**](../WaynesGrid/CellRenderingOptions#borders), and the slider's `.BackgroundBorders` / `BlockBorders`. The array of [**Border**](#border-class) sub-objects on a [**TextRendering**](TextRendering)'s **Outlines** member uses the same element type. +Accessed as `.Borders`, [**CellRenderingOptions.Borders**](../WaynesGrid/CellRenderingOptions#borders), and the slider's `.BackgroundBorders` / `BlockBorders`. The array of [**Border**](#border-class) sub-objects on a [**TextRendering**](TextRendering)'s **Outlines** member uses the same element type. ```tb btnGo.NormalState.Borders.SetSimpleBorder StrokeSize:=1, ColorRGB:=vbBlack diff --git a/docs/Reference/CustomControls/Styles/Corners.md b/docs/Reference/CustomControls/Styles/Corners.md index 648db0a..f21cd72 100644 --- a/docs/Reference/CustomControls/Styles/Corners.md +++ b/docs/Reference/CustomControls/Styles/Corners.md @@ -9,7 +9,7 @@ has_toc: false # Corners class {: .no_toc } -The four corners of a rendered region. Each corner is an independent [**Corner**](#corner-class) sub-object — the shape and radius can vary corner by corner — letting a control round one corner while notching another. Reached as `.Corners`, [**CellRenderingOptions.Corners**](../WaynesGrid/CellRenderingOptions#corners), and the slider's `.BackgroundCorners` / `BlockCorners`. +The four corners of a rendered region. Each corner is an independent [**Corner**](#corner-class) sub-object — the shape and radius can vary corner by corner — letting a control round one corner while notching another. Accessed as `.Corners`, [**CellRenderingOptions.Corners**](../WaynesGrid/CellRenderingOptions#corners), and the slider's `.BackgroundCorners` / `BlockCorners`. ```tb With btnGo.NormalState.Corners diff --git a/docs/Reference/CustomControls/Styles/Fill.md b/docs/Reference/CustomControls/Styles/Fill.md index 4c7343d..fe4d963 100644 --- a/docs/Reference/CustomControls/Styles/Fill.md +++ b/docs/Reference/CustomControls/Styles/Fill.md @@ -95,7 +95,7 @@ Raised whenever [**Pattern**](#pattern) is assigned or the [**ColorPoints**](#co ## FillColorPoints class -The collection of [**FillColorPoint**](#fillcolorpoint-class) stops that define a [**Fill**](#)'s colour gradient. Reached as [**Fill.ColorPoints**](#colorpoints). Internally an array of **FillColorPoint** plus a [**Granularity**](#granularity) integer. +The collection of [**FillColorPoint**](#fillcolorpoint-class) stops that define a [**Fill**](#)'s colour gradient. Accessed as [**Fill.ColorPoints**](#colorpoints). Internally an array of **FillColorPoint** plus a [**Granularity**](#granularity) integer. ### Granularity {: .no_toc } @@ -105,7 +105,7 @@ The size of the generated colour table that interpolates the stops. Higher value ### Values {: .no_toc } -The array of [**FillColorPoint**](#fillcolorpoint-class) gradient stops. Read-write, but in practice you populate it through the [**SetSolidColor**](#setsolidcolor), [**SetSolidColorRGBA**](#setsolidcolorrgba), [**SetColorPoints**](#setcolorpoints), or [**SetColorPointsArray**](#setcolorpointsarray) methods rather than assigning the array directly. +The array of [**FillColorPoint**](#fillcolorpoint-class) gradient stops. Read-write, but in practice populated through the [**SetSolidColor**](#setsolidcolor), [**SetSolidColorRGBA**](#setsolidcolorrgba), [**SetColorPoints**](#setcolorpoints), or [**SetColorPointsArray**](#setcolorpointsarray) methods rather than by assigning the array directly. ### SetSolidColor {: .no_toc } diff --git a/docs/Reference/CustomControls/Styles/Line.md b/docs/Reference/CustomControls/Styles/Line.md index c801630..f7fe0aa 100644 --- a/docs/Reference/CustomControls/Styles/Line.md +++ b/docs/Reference/CustomControls/Styles/Line.md @@ -9,7 +9,7 @@ has_toc: false # Line class {: .no_toc } -A single stroke used to draw a grid line, divider, or resizer bar — simpler than a full [**Border**](Borders#border-class) (no blend-with-background flag, no surrounding **Elements** array). Reached as [**WaynesGrid.VerticalLineOptions**](../WaynesGrid/#verticallineoptions), [**HorizontalLineOptions**](../WaynesGrid/#horizontallineoptions), and [**ResizerBar**](../WaynesGrid/#resizerbar). +A single stroke used to draw a grid line, divider, or resizer bar — simpler than a full [**Border**](Borders#border-class) (no blend-with-background flag, no surrounding **Elements** array). Accessed as [**WaynesGrid.VerticalLineOptions**](../WaynesGrid/#verticallineoptions), [**HorizontalLineOptions**](../WaynesGrid/#horizontallineoptions), and [**ResizerBar**](../WaynesGrid/#resizerbar). ```tb With WaynesGrid1.VerticalLineOptions @@ -28,7 +28,7 @@ The [**Fill**](Fill) that supplies the colour or gradient used to draw the line. ### StrokeSize {: .no_toc } -The stroke thickness in pixels. [**PixelCount**](../Enumerations/PixelCount). Default: 0 (the line is not drawn until you assign a non-zero size). +The stroke thickness in pixels. [**PixelCount**](../Enumerations/PixelCount). Default: 0 (the line is not drawn until a non-zero size is assigned). ## Events diff --git a/docs/Reference/CustomControls/Styles/Padding.md b/docs/Reference/CustomControls/Styles/Padding.md index 4131c23..9fc46bd 100644 --- a/docs/Reference/CustomControls/Styles/Padding.md +++ b/docs/Reference/CustomControls/Styles/Padding.md @@ -9,7 +9,7 @@ has_toc: false # Padding class {: .no_toc } -Per-side padding, in pixels, applied around the text inside a [**TextRendering**](TextRendering). Reached as [**TextRendering.Padding**](TextRendering#padding). The padded region is what the text [**Alignment**](TextRendering#alignment) is applied to — adding 5 pixels of left padding moves left-aligned text 5 pixels to the right, and shrinks the available area by 5 pixels at the left edge. +Per-side padding, in pixels, applied around the text inside a [**TextRendering**](TextRendering). Accessed as [**TextRendering.Padding**](TextRendering#padding). The padded region is what the text [**Alignment**](TextRendering#alignment) is applied to — adding 5 pixels of left padding moves left-aligned text 5 pixels to the right, and shrinks the available area by 5 pixels at the left edge. ```tb With txtNotes.NormalState.TextRendering.Padding diff --git a/docs/Reference/CustomControls/Styles/TextRendering.md b/docs/Reference/CustomControls/Styles/TextRendering.md index 8c7d3c3..258ac62 100644 --- a/docs/Reference/CustomControls/Styles/TextRendering.md +++ b/docs/Reference/CustomControls/Styles/TextRendering.md @@ -9,7 +9,7 @@ has_toc: false # TextRendering class {: .no_toc } -Aggregates everything needed to draw a piece of text inside a control: the font, the padding, the fill that supplies the text colour, an optional array of outlines, the alignment within the available area, and the overflow behaviour. Reached as `.TextRendering`, [**WaynesLabel.TextRendering**](../WaynesLabel#textrendering), and [**CellRenderingOptions.TextRendering**](../WaynesGrid/CellRenderingOptions#textrendering). +Aggregates everything needed to draw a piece of text inside a control: the font, the padding, the fill that supplies the text colour, an optional array of outlines, the alignment within the available area, and the overflow behaviour. Accessed as `.TextRendering`, [**WaynesLabel.TextRendering**](../WaynesLabel#textrendering), and [**CellRenderingOptions.TextRendering**](../WaynesGrid/CellRenderingOptions#textrendering). A newly-constructed **TextRendering** pre-sets its [**Fill**](#fill) to solid black so that text is immediately visible. @@ -85,7 +85,7 @@ Raised when [**Alignment**](#alignment) or [**OverflowMode**](#overflowmode) is ## FontStyle class -The font metrics that control how [**TextRendering**](#) lays out text. Reached as [**TextRendering.Font**](#font). +The font metrics that control how [**TextRendering**](#) lays out text. Accessed as [**TextRendering.Font**](#font). ### Italic {: .no_toc } diff --git a/docs/Reference/CustomControls/Styles/index.md b/docs/Reference/CustomControls/Styles/index.md index 771fb01..61d00c1 100644 --- a/docs/Reference/CustomControls/Styles/index.md +++ b/docs/Reference/CustomControls/Styles/index.md @@ -21,4 +21,4 @@ Every style object raises an **OnChanged** event whenever any of its public fiel | [Padding](Padding) | per-side padding around text inside a [**TextRendering**](TextRendering) | | [TextRendering](TextRendering) | font, padding, fill, outlines, alignment, and overflow for text; contains the `FontStyle` sub-object that holds the font metrics | -The style classes are declared `Private Class` in the **CustomControlsPackage** source — they cannot be created with `New` from outside the package, and a variable cannot be typed as e.g. `Dim x As Fill` from a referencing project. Application code reaches every style object exclusively through the property chain that hangs off a concrete control. +The style classes are declared `Private Class` in the **CustomControlsPackage** source — they cannot be created with `New` from outside the package, and a variable cannot be typed as e.g. `Dim x As Fill` from a referencing project. Application code accesses every style object exclusively through the property chain that hangs off a concrete control. diff --git a/docs/Reference/CustomControls/WaynesButton/WaynesButtonState.md b/docs/Reference/CustomControls/WaynesButton/WaynesButtonState.md index 682939e..b596f20 100644 --- a/docs/Reference/CustomControls/WaynesButton/WaynesButtonState.md +++ b/docs/Reference/CustomControls/WaynesButton/WaynesButtonState.md @@ -9,11 +9,11 @@ has_toc: false # WaynesButtonState class {: .no_toc } -A bundle of the four style objects that describe a single visual state of a [**WaynesButton**](.) — its corners, background fill, borders, and text rendering. Each button has four parallel instances reachable as [**NormalState**](.#normalstate), [**HoverState**](.#hoverstate), [**FocusedState**](.#focusedstate), and [**PressedState**](.#pressedstate); the button picks one at each repaint depending on the mouse / focus state. +A bundle of the four style objects that describe a single visual state of a [**WaynesButton**](.) — its corners, background fill, borders, and text rendering. Each button has four parallel instances accessed as [**NormalState**](.#normalstate), [**HoverState**](.#hoverstate), [**FocusedState**](.#focusedstate), and [**PressedState**](.#pressedstate); the button picks one at each repaint depending on the mouse / focus state. Newly-constructed **WaynesButtonState** objects pre-set their **BackgroundFill** to a solid mid-blue and all four corners to a 15-pixel curve. Override per-state to give the button a different look in each state. -The type itself is `Private Class` — you reach instances only through the **WaynesButton.…State** properties and cannot declare a variable typed as **WaynesButtonState** from outside the package. +The type itself is `Private Class` — instances are accessed only through the **WaynesButton.…State** properties, and a variable typed as **WaynesButtonState** cannot be declared from outside the package. ```tb With btnGo.NormalState diff --git a/docs/Reference/CustomControls/WaynesForm/WindowsFormOptions.md b/docs/Reference/CustomControls/WaynesForm/WindowsFormOptions.md index 0a0d4b4..f04e375 100644 --- a/docs/Reference/CustomControls/WaynesForm/WindowsFormOptions.md +++ b/docs/Reference/CustomControls/WaynesForm/WindowsFormOptions.md @@ -9,11 +9,11 @@ has_toc: false # WindowsFormOptions class {: .no_toc } -The Win32-frame settings of a [**WaynesForm**](.) — border style, initial window state, startup position, taskbar visibility, and the title-bar buttons. Surfaces as [**WaynesForm.WindowsOptions**](.#windowsoptions); a single instance per form, created automatically. +The Win32-frame settings of a [**WaynesForm**](.) — border style, initial window state, startup position, taskbar visibility, and the title-bar buttons. Exposed as [**WaynesForm.WindowsOptions**](.#windowsoptions); a single instance per form, created automatically. Most of the fields take effect *once*, when the form is first shown — changing [**StartUpPosition**](#startupposition) or [**WindowState**](#windowstate) on a form that is already visible has no effect. The exception is the title-bar buttons; whether they have a visible effect depends on whether [**BorderStyle**](#borderstyle) is one of the styles that include those buttons in the first place. -The type itself is `Private Class` — you reach the instance only through the form's **WindowsOptions** property and cannot declare a variable typed as **WindowsFormOptions** from outside the package. +The type itself is `Private Class` — the instance is accessed only through the form's **WindowsOptions** property, and a variable typed as **WindowsFormOptions** cannot be declared from outside the package. ```tb Private Sub Form_Load() diff --git a/docs/Reference/CustomControls/WaynesForm/index.md b/docs/Reference/CustomControls/WaynesForm/index.md index 1eb9d7d..aa7feef 100644 --- a/docs/Reference/CustomControls/WaynesForm/index.md +++ b/docs/Reference/CustomControls/WaynesForm/index.md @@ -12,7 +12,7 @@ The top-level form class that hosts the package's custom controls. A **WaynesFor Within the current release of the package every form created with the designer is hard-coded to use **WaynesForm** as its root class; other base form classes are planned but not yet supported. -A form has a [**Caption**](#caption) (shown in the Win32 title bar), a [**BackgroundFill**](#backgroundfill) (painted across its entire client area), and a [**WindowsOptions**](#windowsoptions) sub-object that controls the surrounding Win32 frame — border style, window state, taskbar visibility, minimize / maximize buttons, and so on. Showing the form is done by calling [**Show**](#show); closing it by [**Close**](#close). +A form has a [**Caption**](#caption) (shown in the Win32 title bar), a [**BackgroundFill**](#backgroundfill) (painted across its entire client area), and a [**WindowsOptions**](#windowsoptions) sub-object that controls the surrounding Win32 frame — border style, window state, taskbar visibility, minimize / maximize buttons, and so on. Call [**Show**](#show) to display the form; call [**Close**](#close) to close it. ```tb Private Sub Form_Load() @@ -59,7 +59,7 @@ Syntax: *object*.**Caption** [ = *string* ] ### Controls {: .no_toc } -The [**CustomControlsCollection**](../Framework/CustomControlsCollection) of every control hosted on the form. Inherited from the form base. Read-only — iterate or look up by index / name to reach individual controls. +The [**CustomControlsCollection**](../Framework/CustomControlsCollection) of every control hosted on the form. Inherited from the form base. Read-only — iterate or look up by index / name to access individual controls. ### FormDesignerId {: .no_toc } diff --git a/docs/Reference/CustomControls/WaynesFrame.md b/docs/Reference/CustomControls/WaynesFrame.md index 5f5a717..cb07b61 100644 --- a/docs/Reference/CustomControls/WaynesFrame.md +++ b/docs/Reference/CustomControls/WaynesFrame.md @@ -18,7 +18,7 @@ Private Sub Form_Load() End Sub ``` -Frames work well as containers for [**Dock**](Enumerations/DockMode)-positioned children. Set the frame's own **Dock** to **tbDockFill** so it claims the form's body, then dock its children to **tbDockTop** / **tbDockLeft** / **tbDockFill** / etc. — the docking calculation walks the container tree, so children dock to the frame's client area rather than to the form. The order in which the children are added still determines which edges they claim first. +Frames work well as containers for [**Dock**](Enumerations/DockMode)-positioned children. Set the frame's own **Dock** to **tbDockFill** so it claims the form's body, then dock its children to **tbDockTop** / **tbDockLeft** / **tbDockFill** / etc. — the docking calculation traverses the container tree, so children dock to the frame's client area rather than to the form. The order in which the children are added still determines which edges they claim first. ## Properties diff --git a/docs/Reference/CustomControls/WaynesGrid/Column.md b/docs/Reference/CustomControls/WaynesGrid/Column.md index e2028d7..98b9fad 100644 --- a/docs/Reference/CustomControls/WaynesGrid/Column.md +++ b/docs/Reference/CustomControls/WaynesGrid/Column.md @@ -9,7 +9,7 @@ has_toc: false # Column class {: .no_toc } -One column of a [**WaynesGrid**](.). Carries a [**Caption**](#caption) that is shown in the column-header row and a [**Width**](#width) that the user can drag at run time. Elements of [**WaynesGrid.Columns**](.#columns). +One column of a [**WaynesGrid**](.). Has a [**Caption**](#caption) that is shown in the column-header row and a [**Width**](#width) that the user can drag at run time. Elements of [**WaynesGrid.Columns**](.#columns). ```tb ReDim Grid1.Columns(2) diff --git a/docs/Reference/CustomControls/WaynesGrid/index.md b/docs/Reference/CustomControls/WaynesGrid/index.md index 4790929..545545e 100644 --- a/docs/Reference/CustomControls/WaynesGrid/index.md +++ b/docs/Reference/CustomControls/WaynesGrid/index.md @@ -35,7 +35,7 @@ Private Sub Grid1_GetCellText( _ End Sub ``` -The six [**CellRenderingOptions**](CellRenderingOptions) sub-objects ([**ColumnHeaderOptions**](#columnheaderoptions), [**RowHeaderOptions**](#rowheaderoptions), [**CellOptions**](#celloptions), [**HoverCellOptions**](#hovercelloptions), [**SelectedCellOptions**](#selectedcelloptions), [**MultiSelectCellOptions**](#multiselectcelloptions)) give the grid its visual personality. A typical setup gives headers a gradient, body cells left-aligned text with a small left-padding indent, and the selected cell a contrasting border: +The six [**CellRenderingOptions**](CellRenderingOptions) sub-objects ([**ColumnHeaderOptions**](#columnheaderoptions), [**RowHeaderOptions**](#rowheaderoptions), [**CellOptions**](#celloptions), [**HoverCellOptions**](#hovercelloptions), [**SelectedCellOptions**](#selectedcelloptions), [**MultiSelectCellOptions**](#multiselectcelloptions)) control the grid's visual style. A typical setup gives headers a gradient, body cells left-aligned text with a small left-padding indent, and the selected cell a contrasting border: ```tb With Grid1.ColumnHeaderOptions diff --git a/docs/Reference/CustomControls/WaynesSlider/WaynesSliderState.md b/docs/Reference/CustomControls/WaynesSlider/WaynesSliderState.md index 679c3e0..e494191 100644 --- a/docs/Reference/CustomControls/WaynesSlider/WaynesSliderState.md +++ b/docs/Reference/CustomControls/WaynesSlider/WaynesSliderState.md @@ -15,7 +15,7 @@ The state has two halves — the *background* (the full track behind the block) [**InitializeDefaultValues**](#initializedefaultvalues) pre-sets the block to a solid mid-blue ([**WAYNESCOLOR_BLUE**](#) — `&HAC7220`) fill, a 2-pixel black background border, and a transparent block border that acts as inner padding inside the background. -The type itself is `Public Class` but cannot be instantiated from outside the package — reach instances only through the slider's **NormalState** / **HoverState** / **FocusedState** properties. +The type itself is `Public Class` but cannot be instantiated from outside the package — instances are accessed only through the slider's **NormalState** / **HoverState** / **FocusedState** properties. ## Properties diff --git a/docs/Reference/CustomControls/WaynesTextBox/WaynesTextBoxState.md b/docs/Reference/CustomControls/WaynesTextBox/WaynesTextBoxState.md index 0a7ecad..ef56e76 100644 --- a/docs/Reference/CustomControls/WaynesTextBox/WaynesTextBoxState.md +++ b/docs/Reference/CustomControls/WaynesTextBox/WaynesTextBoxState.md @@ -15,7 +15,7 @@ In addition to the usual background / borders / corners / text-rendering quartet [**InitializeDefaultValues**](#initializedefaultvalues) and [**InitializeDefaultValues_Focused**](#initializedefaultvalues_focused) populate the state with reasonable defaults — the focused variant uses a different selection background and caret colour. -The type itself is `Public Class` but is `[COMCreatable(False)]` — reach instances only through the textbox's **NormalState** / **HoverState** / **FocusedState** properties. +The type itself is `Public Class` but is `[COMCreatable(False)]` — instances are accessed only through the textbox's **NormalState** / **HoverState** / **FocusedState** properties. ## Properties diff --git a/docs/Reference/CustomControls/index.md b/docs/Reference/CustomControls/index.md index 9456ffc..475a5ec 100644 --- a/docs/Reference/CustomControls/index.md +++ b/docs/Reference/CustomControls/index.md @@ -13,7 +13,7 @@ The **CustomControls** built-in package supplies a set of fully owner-drawn cont The package ships as two paired components: a **CustomControls DESIGNER** library — the framework half, source-side project `CustomControls` — that defines the rendering surface and the interface every custom control implements; and the **Custom Controls** package — source-side project `CustomControlsPackage` — that supplies the eight concrete `Waynes…` controls. The two are co-versioned with twinBASIC and always ship together; both are MIT-licensed. -Beyond providing ready-to-use controls, the package doubles as a worked example for authoring your own custom controls. The `Waynes…` classes implement the same [**ICustomControl**](Framework/ICustomControl) interface that a hand-written control would, against the same [**CustomControlContext**](Framework/CustomControlContext) callback object and [**Canvas**](Framework/Canvas) drawing surface — see the [Framework](Framework/) page for the host-side contract. +Beyond providing ready-to-use controls, the package doubles as a worked example for authoring new custom controls. The `Waynes…` classes implement the same [**ICustomControl**](Framework/ICustomControl) interface that a hand-written control would, against the same [**CustomControlContext**](Framework/CustomControlContext) callback object and [**Canvas**](Framework/Canvas) drawing surface — see the [Framework](Framework/) page for the host-side contract. ```tb Private Sub Form_Load() @@ -63,7 +63,7 @@ Every style object raises an **OnChanged** event whenever one of its fields is s ## Framework -For authoring your own custom controls or forms, the **CustomControls DESIGNER** half of the package supplies: +For authoring new custom controls or forms, the **CustomControls DESIGNER** half of the package supplies: - [ICustomControl](Framework/ICustomControl) -- the interface every custom control implements: **Initialize**, **Destroy**, **Paint** - [ICustomForm](Framework/ICustomForm) -- the analogous interface for custom form classes @@ -72,7 +72,7 @@ For authoring your own custom controls or forms, the **CustomControls DESIGNER** - [CustomControlTimer](Framework/CustomControlTimer) -- the timer returned by **CustomControlContext.CreateTimer**; has **Interval**, **Enabled**, and an **OnTimer** event - [CustomControlsCollection](Framework/CustomControlsCollection) -- the **Controls** collection on a form - [Canvas](Framework/Canvas) -- the drawing surface passed to **Paint**; the only way to put pixels into a custom control -- [SerializeInfo](Framework/SerializeInfo) -- the per-instance serializer reached via **CustomControlContext.GetSerializer**; used to deserialize designer-set property values and to query the runtime mode +- [SerializeInfo](Framework/SerializeInfo) -- the per-instance serializer returned by **CustomControlContext.GetSerializer**; used to deserialize designer-set property values and to query the runtime mode ## Enumerations From 73eb11d296f09b43bf6f90eff87bfff3306c3747 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Thu, 14 May 2026 21:57:31 +0200 Subject: [PATCH 07/19] Apply structural style rules to tbIDE package --- docs/Reference/tbIDE/AddIn.md | 2 +- docs/Reference/tbIDE/AddinTimer.md | 6 +++--- docs/Reference/tbIDE/Button.md | 2 +- docs/Reference/tbIDE/CodeEditor.md | 8 ++++---- docs/Reference/tbIDE/DebugConsole.md | 2 +- docs/Reference/tbIDE/Editor.md | 3 +-- docs/Reference/tbIDE/File.md | 2 +- docs/Reference/tbIDE/FileSystem.md | 4 ++-- docs/Reference/tbIDE/FileSystemItem.md | 2 +- docs/Reference/tbIDE/Folder.md | 6 +++--- docs/Reference/tbIDE/Host.md | 12 ++++++------ docs/Reference/tbIDE/HtmlElement.md | 4 ++-- docs/Reference/tbIDE/KeyboardShortcuts.md | 4 ++-- docs/Reference/tbIDE/Project.md | 4 ++-- docs/Reference/tbIDE/Themes.md | 2 +- docs/Reference/tbIDE/ToolWindow.md | 11 ++++------- docs/Reference/tbIDE/ToolWindows.md | 2 +- docs/Reference/tbIDE/Toolbar.md | 4 ++-- docs/Reference/tbIDE/Toolbars.md | 2 +- docs/Reference/tbIDE/index.md | 16 ++++++++-------- 20 files changed, 47 insertions(+), 51 deletions(-) diff --git a/docs/Reference/tbIDE/AddIn.md b/docs/Reference/tbIDE/AddIn.md index ea7b783..8ca3113 100644 --- a/docs/Reference/tbIDE/AddIn.md +++ b/docs/Reference/tbIDE/AddIn.md @@ -8,7 +8,7 @@ has_toc: false # AddIn class {: .no_toc } -The contract every addin's main class must implement. One read-only property — [**Name**](#name) — that the IDE reads to label the addin in error messages, log lines, and (eventually) any addin-management UI. The IDE never creates an **AddIn** itself; the addin DLL constructs the object inside [`tbCreateCompilerAddin`](.#building-and-loading-an-addin) and returns it. +The contract every addin's main class must implement. One read-only property — [**Name**](#name) — that the IDE reads to label the addin in error messages, log lines, and any addin-management UI added later. The IDE never creates an **AddIn** itself; the addin DLL constructs the object inside [`tbCreateCompilerAddin`](.#building-and-loading-an-addin) and returns it. ```tb Private Class MyAddIn diff --git a/docs/Reference/tbIDE/AddinTimer.md b/docs/Reference/tbIDE/AddinTimer.md index 0656baf..f78b2d1 100644 --- a/docs/Reference/tbIDE/AddinTimer.md +++ b/docs/Reference/tbIDE/AddinTimer.md @@ -8,7 +8,7 @@ has_toc: false # AddinTimer class {: .no_toc } -A simple periodic-callback helper. **AddinTimer** is the **only user-instantiable class** in the package — every other CoClass is handed to the addin by the IDE; this one the addin creates with `New`. Internally it wraps the Win32 `SetTimer` / `KillTimer` pair against `hwnd = 0` and fires its [**Timer**](#timer) event from the IDE's UI thread. +A simple periodic-callback helper. **AddinTimer** is the **only user-instantiable class** in the package — every other CoClass is supplied to the addin by the IDE; this one the addin creates with `New`. Internally it wraps the Win32 `SetTimer` / `KillTimer` pair against `hwnd = 0` and fires its [**Timer**](#timer) event from the IDE's UI thread. ```tb Private WithEvents Timer As AddinTimer @@ -26,7 +26,7 @@ End Sub Stop the timer by setting [**Enabled**](#enabled) = **False**, or simply by dropping the last reference — `Class_Terminate` cancels the underlying Win32 timer automatically. Both [**Enabled**](#enabled) and [**Interval**](#interval) are live: assigning to either re-arms the underlying Win32 timer using the new values, so changing the interval while the timer is running takes effect immediately. -Nothing in the package *requires* this helper — a direct `SetTimer` / `KillTimer` pair (or any other periodic mechanism) works just as well; sample 15's dwell-time pattern uses raw Win32 calls. Use **AddinTimer** when the convenience of an event-bound class is preferable to managing the Win32 plumbing yourself. +Nothing in the package *requires* this helper — a direct `SetTimer` / `KillTimer` pair (or any other periodic mechanism) works just as well; sample 15's dwell-time pattern uses raw Win32 calls. Use **AddinTimer** when the convenience of an event-bound class is preferable to managing the Win32 plumbing directly. * TOC {:toc} @@ -56,4 +56,4 @@ Fires every [**Interval**](#interval) milliseconds while [**Enabled**](#enabled) Syntax: *timer*_**Timer**() -Long-running work inside the handler will block the UI thread until it returns — keep the handler short and offload heavy work to a background mechanism if needed. +Long-running work inside the handler will block the UI thread until it returns — keep the handler short and offload heavy work to a background mechanism when needed. diff --git a/docs/Reference/tbIDE/Button.md b/docs/Reference/tbIDE/Button.md index 311ae4a..b8345c1 100644 --- a/docs/Reference/tbIDE/Button.md +++ b/docs/Reference/tbIDE/Button.md @@ -8,7 +8,7 @@ has_toc: false # Button class {: .no_toc } -An addin-created toolbar button. Returned by [**Toolbar.AddButton**](Toolbar#addbutton); hold it via `WithEvents` to receive [**OnClick**](#onclick) notifications. The button's [**Caption**](#caption) and [**IconData**](#icondata) are mutable at run time — change the caption to reflect a state, or swap the icon to reflect a toggle. +An addin-created toolbar button. Returned by [**Toolbar.AddButton**](Toolbar#addbutton); held via `WithEvents` to receive [**OnClick**](#onclick) notifications. The button's [**Caption**](#caption) and [**IconData**](#icondata) are mutable at run time — change the caption to reflect a state, or swap the icon to reflect a toggle. ```tb Private WithEvents RefreshButton As Button diff --git a/docs/Reference/tbIDE/CodeEditor.md b/docs/Reference/tbIDE/CodeEditor.md index 68ee7b0..95a0528 100644 --- a/docs/Reference/tbIDE/CodeEditor.md +++ b/docs/Reference/tbIDE/CodeEditor.md @@ -10,7 +10,7 @@ has_toc: false A code-pane editor — the specific [**Editor**](Editor) kind the IDE returns when the active editor is a source-code pane. Adds selection / text / scrolling control, an inline-widget API, and a raw passthrough into the underlying Monaco editor that powers code panes. -Reach a **CodeEditor** by casting an [**Editor**](Editor) — `Host.ActiveEditors(0)` returns an [**Editor**](Editor) that, for a code pane, is also a **CodeEditor**: +A **CodeEditor** is reached by casting an [**Editor**](Editor) — `Host.ActiveEditors(0)` returns an [**Editor**](Editor) that, for a code pane, is also a **CodeEditor**: ```tb If TypeOf Host.ActiveEditors(0) Is CodeEditor Then @@ -40,7 +40,7 @@ The full text of the code pane. Reading returns the entire document; assigning r Syntax: *codeEditor*.**Text** [ = *value* ] -Replacing the entire text is heavyweight — both for the editor (it has to rebuild every Monaco data structure) and for the user (the undo stack collapses to a single step). For surgical edits, prefer [**SelectedText**](#selectedtext) over [**Text**](#text). +Replacing the entire text is heavy — both for the editor (it has to rebuild every Monaco data structure) and for the user (the undo stack collapses to a single step). For targeted edits, prefer [**SelectedText**](#selectedtext) over [**Text**](#text). ## Methods @@ -63,12 +63,12 @@ Syntax: *codeEditor*.**AddMonacoWidget**( *LineNumber*, *ColumnNumber*, *Html* [ *Css* : *optional* Per-widget CSS as a **String**. Use this for widget-local styles that should not bleed into the rest of the code pane. -The returned [**HtmlElement**](HtmlElement) has the same dynamic-DOM properties as elements inside a tool window — see [Dynamic DOM property resolution](.#dynamic-dom-property-resolution) on the package overview. Use [**HtmlElement.Remove**](HtmlElement#remove) on the returned object to take the widget down. +The returned [**HtmlElement**](HtmlElement) has the same dynamic-DOM properties as elements inside a tool window — see [Dynamic DOM property resolution](.#dynamic-dom-property-resolution) on the package overview. Call [**HtmlElement.Remove**](HtmlElement#remove) on the returned object to remove the widget. ### ExecuteMonacoCommand {: .no_toc } -Sends a direct command to the underlying Monaco editor instance. Useful for triggering Monaco's built-in commands (Find, Go-to-Line, Format, Toggle Comment, …) without writing equivalent twinBASIC code. +Sends a direct command to the underlying Monaco editor instance. Useful for triggering Monaco's built-in commands (Find, Go-to-Line, Format, Toggle Comment, …) without writing the equivalent twinBASIC code. Syntax: *codeEditor*.**ExecuteMonacoCommand** *Command* [, *Arg1*, *Arg2*, … ] diff --git a/docs/Reference/tbIDE/DebugConsole.md b/docs/Reference/tbIDE/DebugConsole.md index 92ce955..82273a2 100644 --- a/docs/Reference/tbIDE/DebugConsole.md +++ b/docs/Reference/tbIDE/DebugConsole.md @@ -18,7 +18,7 @@ With Host.DebugConsole End With ``` -The pane is shared across the IDE's own output and every addin's output — prefix log lines with an addin tag (e.g. `"[MyAddIn] "`) so users can tell sources apart. +The pane is shared across the IDE's own output and every addin's output — prefix log lines with an addin tag (e.g. `"[MyAddIn] "`) so users can distinguish the sources. * TOC {:toc} diff --git a/docs/Reference/tbIDE/Editor.md b/docs/Reference/tbIDE/Editor.md index 25de8d2..0f36668 100644 --- a/docs/Reference/tbIDE/Editor.md +++ b/docs/Reference/tbIDE/Editor.md @@ -13,8 +13,7 @@ The base interface every IDE editor presents. **Editor** itself exposes only the ## Castability {: #castability } -> [!NOTE] -> An **Editor** returned by the IDE is castable to the specific editor kind for the underlying pane. For a code pane the cast target is [**CodeEditor**](CodeEditor); other editor kinds may be added in future IDE versions and will follow the same pattern. +An **Editor** returned by the IDE is castable to the specific editor kind for the underlying pane. For a code pane the cast target is [**CodeEditor**](CodeEditor); other editor kinds may be added in future IDE versions and will follow the same pattern. Use `TypeOf` to test before casting: diff --git a/docs/Reference/tbIDE/File.md b/docs/Reference/tbIDE/File.md index 084da42..4c6ff54 100644 --- a/docs/Reference/tbIDE/File.md +++ b/docs/Reference/tbIDE/File.md @@ -77,7 +77,7 @@ Syntax: *file*.**ReadText**( *Options* ) **As String** Valid on every text file kind ([**FileTWIN**](FileSystemItem#FileSystemItemType_FileTWIN), [**FileBAS**](FileSystemItem#FileSystemItemType_FileBAS), [**FileCLS**](FileSystemItem#FileSystemItemType_FileCLS), [**FileVIRTUALDOC**](FileSystemItem#FileSystemItemType_FileVIRTUALDOC), [**FileUIDESIGNER**](FileSystemItem#FileSystemItemType_FileUIDESIGNER), [**FileJSON**](FileSystemItem#FileSystemItemType_FileJSON)); calling on a [**FileOTHER**](FileSystemItem#FileSystemItemType_FileOTHER) is not supported. -The line and column structure of the returned text matches the original file — `CommentsToWhitespace` only blanks the comment characters, never moves the surrounding code. That makes the option suitable for indexers / search tools that need both "find non-comment occurrences" and "report the position in the original file". +The line and column structure of the returned text matches the original file — `CommentsToWhitespace` only blanks the comment characters, never moves the surrounding code. The option is therefore suitable for indexers / search tools that need both "find non-comment occurrences" and "report the position in the original file". ## ReadTextFlags {: #readtextflags } diff --git a/docs/Reference/tbIDE/FileSystem.md b/docs/Reference/tbIDE/FileSystem.md index 6a7c816..2025fd6 100644 --- a/docs/Reference/tbIDE/FileSystem.md +++ b/docs/Reference/tbIDE/FileSystem.md @@ -8,7 +8,7 @@ has_toc: false # FileSystem class {: .no_toc } -A handle into the IDE's virtual file system — the abstraction that lets an addin walk and read source files without touching the on-disk paths. Reach the **FileSystem** through [**Host.FileSystem**](Host#filesystem). For the more common per-project case, [**Host.CurrentProject.RootFolder**](Project#rootfolder) is also a [**Folder**](Folder) and is usually the right entry point — the global **FileSystem** matters when an addin needs to address files outside the project's own root. +A handle into the IDE's virtual file system — the abstraction that lets an addin traverse and read source files without touching the on-disk paths. The **FileSystem** is reached through [**Host.FileSystem**](Host#filesystem). For the more common per-project case, [**Host.CurrentProject.RootFolder**](Project#rootfolder) is also a [**Folder**](Folder) and is usually the right entry point — the global **FileSystem** matters when an addin needs to address files outside the project's own root. ```tb Dim item As FileSystemItem = Host.FileSystem.ResolvePath("twinbasic:/Sources/MainModule.twin") @@ -33,4 +33,4 @@ Syntax: *fileSystem*.**ResolvePath**( *Path* ) **As** [**FileSystemItem**](FileS *Path* : *required* A virtual-FS path. **String**. Must include the `twinbasic:/` prefix. -The returned object is a [**FileSystemItem**](FileSystemItem) but is usually castable to its specific kind — a [**File**](File) for regular files, a [**Folder**](Folder) for folders. Test with `TypeOf … Is Folder` before casting if the path's kind is not known statically. +The returned object is a [**FileSystemItem**](FileSystemItem) but is usually castable to its specific kind — a [**File**](File) for regular files, a [**Folder**](Folder) for folders. Test with `TypeOf … Is Folder` before casting when the path's kind is not known statically. diff --git a/docs/Reference/tbIDE/FileSystemItem.md b/docs/Reference/tbIDE/FileSystemItem.md index 329b33e..054f213 100644 --- a/docs/Reference/tbIDE/FileSystemItem.md +++ b/docs/Reference/tbIDE/FileSystemItem.md @@ -8,7 +8,7 @@ has_toc: false # FileSystemItem class {: .no_toc } -The base interface for everything inside the IDE's virtual file system. Both [**File**](File) and [**Folder**](Folder) extend **FileSystemItem** and inherit its four universal members ([**Name**](#name), [**Path**](#path), [**Type**](#type), [**Parent**](#parent)). An item returned from a [**Folder**](Folder) enumeration or from [**FileSystem.ResolvePath**](FileSystem#resolvepath) is normally castable to its specific kind — use the [**Type**](#type) property or `TypeOf` to discriminate. +The base interface for everything inside the IDE's virtual file system. Both [**File**](File) and [**Folder**](Folder) extend **FileSystemItem** and inherit its four universal members ([**Name**](#name), [**Path**](#path), [**Type**](#type), [**Parent**](#parent)). An item returned from a [**Folder**](Folder) enumeration or from [**FileSystem.ResolvePath**](FileSystem#resolvepath) is normally castable to its specific kind — the [**Type**](#type) property or `TypeOf` discriminates between them. ```tb Dim item As FileSystemItem diff --git a/docs/Reference/tbIDE/Folder.md b/docs/Reference/tbIDE/Folder.md index ff58276..d72b3b0 100644 --- a/docs/Reference/tbIDE/Folder.md +++ b/docs/Reference/tbIDE/Folder.md @@ -10,7 +10,7 @@ has_toc: false A folder inside the IDE's virtual file system. Extends [**FileSystemItem**](FileSystemItem) with child-enumeration capability — [**Count**](#count), [**Item**](#item), and standard **For Each** iteration that yields each child as a [**FileSystemItem**](FileSystemItem) (use `TypeOf` to discriminate folders from files). -A **Folder** also inherits the universal [**FileSystemItem**](FileSystemItem) members — [**Name**](FileSystemItem#name), [**Path**](FileSystemItem#path), [**Type**](FileSystemItem#type), [**Parent**](FileSystemItem#parent). The most common entry point is [**Host.CurrentProject.RootFolder**](Project#rootfolder), and the most common operation is a **For Each** recursive walk. +A **Folder** also inherits the universal [**FileSystemItem**](FileSystemItem) members — [**Name**](FileSystemItem#name), [**Path**](FileSystemItem#path), [**Type**](FileSystemItem#type), [**Parent**](FileSystemItem#parent). The most common entry point is [**Host.CurrentProject.RootFolder**](Project#rootfolder), and the most common operation is a **For Each** recursive traversal. ```tb Private Sub WalkAllFiles(ByVal folder As Folder) @@ -27,7 +27,7 @@ End Sub ``` > [!IMPORTANT] -> The twinBASIC IDE is multi-threaded. The same folder can change while an addin holds a reference to it — files arrive, files disappear, indices renumber. The supported way to walk a folder is **For Each**; index-based access through [**Count**](#count) / [**Item**](#item) races against the IDE's own threads and will sometimes miss or duplicate entries. Always prefer **For Each** for traversal. +> The twinBASIC IDE is multi-threaded. The same folder can change while an addin holds a reference to it — files arrive, files disappear, indices renumber. The supported way to traverse a folder is **For Each**; index-based access through [**Count**](#count) / [**Item**](#item) races against the IDE's own threads and will sometimes miss or duplicate entries. Always prefer **For Each** for traversal. * TOC {:toc} @@ -47,7 +47,7 @@ Number of items currently in the folder. **Long**, read-only. **True** if this folder is the project's special `Packages` folder (the one that contains every referenced package's source tree). **Boolean**, read-only. -Useful when walking the project for source-search purposes — an addin that searches user code will usually want to *skip* the package sources: +Useful when traversing the project for source-search purposes — an addin that searches user code will usually want to *skip* the package sources: ```tb If folder.IsPackagesFolder And Not searchInsidePackages Then Exit Sub diff --git a/docs/Reference/tbIDE/Host.md b/docs/Reference/tbIDE/Host.md index 9469f4a..827e58b 100644 --- a/docs/Reference/tbIDE/Host.md +++ b/docs/Reference/tbIDE/Host.md @@ -8,7 +8,7 @@ has_toc: false # Host class {: .no_toc } -The root API the IDE passes to every addin. The DLL receives a **Host** as the argument to its [`tbCreateCompilerAddin`](.#building-and-loading-an-addin) factory; the addin holds onto that reference for its lifetime and reaches every other capability through it — the currently-loaded [**CurrentProject**](#currentproject), the [**ActiveEditors**](#activeeditors), the [**Toolbars**](#toolbars) for adding buttons, the [**ToolWindows**](#toolwindows) for adding HTML-rendered panels, the [**DebugConsole**](#debugconsole) for log output, the virtual [**FileSystem**](#filesystem), the [**KeyboardShortcuts**](#keyboardshortcuts) registry, the [**Themes**](#themes) state, plus the dialog helpers [**ShowMessageBox**](#showmessagebox) / [**ShowNotification**](#shownotification). +The root API the IDE passes to every addin. The DLL receives a **Host** as the argument to its [`tbCreateCompilerAddin`](.#building-and-loading-an-addin) factory; the addin retains that reference for its lifetime and reaches every other capability through it — the currently-loaded [**CurrentProject**](#currentproject), the [**ActiveEditors**](#activeeditors), the [**Toolbars**](#toolbars) for adding buttons, the [**ToolWindows**](#toolwindows) for adding HTML-rendered panels, the [**DebugConsole**](#debugconsole) for log output, the virtual [**FileSystem**](#filesystem), the [**KeyboardShortcuts**](#keyboardshortcuts) registry, the [**Themes**](#themes) state, plus the dialog helpers [**ShowMessageBox**](#showmessagebox) / [**ShowNotification**](#shownotification). Typically held via `WithEvents` so the addin can subscribe to lifecycle events: @@ -57,7 +57,7 @@ The IDE's DEBUG CONSOLE pane. Print, clear, or set focus. **As** [**DebugConsole ### FileSystem {: .no_toc } -The IDE's virtual file system — the abstraction that lets the addin walk and read source files without touching the on-disk paths. **As** [**FileSystem**](FileSystem). Read-only. +The IDE's virtual file system — the abstraction that lets the addin traverse and read source files without touching the on-disk paths. **As** [**FileSystem**](FileSystem). Read-only. ### IDEProcessID {: .no_toc } @@ -72,7 +72,7 @@ The Win32 `HWND` of the IDE's main window. **LongPtr**, read-only. Pass to Win32 ### KeyboardShortcuts {: .no_toc } -The keyboard-shortcut registry. Use [**KeyboardShortcuts.Add**](KeyboardShortcuts#add) to bind a key combination to a callback. **As** [**KeyboardShortcuts**](KeyboardShortcuts). Read-only. +The keyboard-shortcut registry. Call [**KeyboardShortcuts.Add**](KeyboardShortcuts#add) to bind a key combination to a callback. **As** [**KeyboardShortcuts**](KeyboardShortcuts). Read-only. ### Themes {: .no_toc } @@ -87,7 +87,7 @@ The collection of IDE toolbars. Currently a one-element collection — `Host.Too ### ToolWindows {: .no_toc } -Factory for HTML-rendered tool windows. Use [**ToolWindows.Add**](ToolWindows#add) to create one. **As** [**ToolWindows**](ToolWindows). Read-only. +Factory for HTML-rendered tool windows. Call [**ToolWindows.Add**](ToolWindows#add) to create one. **As** [**ToolWindows**](ToolWindows). Read-only. ## Methods @@ -130,7 +130,7 @@ Use [**ShowMessageBox**](#showmessagebox) when the user has to answer something; ## Events -The **Host** CoClass exposes three events. The third (and any future addition) is tagged with the compile-time `[AllowUnpopulatedVtableEntry]` attribute, which lets a newer addin compile against the newer events interface and still load against an older IDE that does not yet fire the newer event — older IDEs simply leave the slot empty and the addin never receives that particular event. +The **Host** CoClass exposes three events. The third (and any future addition) is tagged with the compile-time `[AllowUnpopulatedVtableEntry]` attribute, which lets a newer addin compile against the newer events interface and still load against an older IDE that does not yet fire the newer event — older IDEs leave the slot empty and the addin never receives that particular event. ### OnProjectLoaded {: .no_toc } @@ -151,7 +151,7 @@ End Sub ### OnChangedActiveEditor {: .no_toc } -Fires when the user switches the focused editor. Use this to refresh any addin UI that depends on the current editor (e.g. a context-aware tool window). Available since IDE BETA 504+; older IDEs simply do not fire it. +Fires when the user switches the focused editor. Use this to refresh any addin UI that depends on the current editor (e.g. a context-aware tool window). Available since IDE BETA 504+; older IDEs do not fire it. Syntax: *host*_**OnChangedActiveEditor**(*EditorIdx* **As Long**, *Editor* **As** [**Editor**](Editor)) diff --git a/docs/Reference/tbIDE/HtmlElement.md b/docs/Reference/tbIDE/HtmlElement.md index 74fe1a7..85f3aa1 100644 --- a/docs/Reference/tbIDE/HtmlElement.md +++ b/docs/Reference/tbIDE/HtmlElement.md @@ -8,7 +8,7 @@ has_toc: false # HtmlElement class {: .no_toc } -One DOM element inside a tool window — every node in the rendered HTML tree is reachable as an **HtmlElement**, starting from [**ToolWindow.RootDomElement**](ToolWindow#rootdomelement) and walking down through [**ChildDomElements**](#childdomelements). Inline overlays inside a code pane (created with [**CodeEditor.AddMonacoWidget**](CodeEditor#addmonacowidget)) also appear as **HtmlElement** instances and behave identically. +One DOM element inside a tool window — every node in the rendered HTML tree is reachable as an **HtmlElement**, starting from [**ToolWindow.RootDomElement**](ToolWindow#rootdomelement) and traversing down through [**ChildDomElements**](#childdomelements). Inline overlays inside a code pane (created with [**CodeEditor.AddMonacoWidget**](CodeEditor#addmonacowidget)) also appear as **HtmlElement** instances and behave identically. ```tb With myToolWindow.RootDomElement.ChildDomElements.Add("greeting", "h1") @@ -30,7 +30,7 @@ The element's *properties* — every CSS-style property, every DOM attribute, ev ### ChildDomElements {: .no_toc } -The element's child-element collection. Use [**HtmlElements.Add**](HtmlElements#add) to add new children, [**Item**](HtmlElements#item) to look one up by ID. **As** [**HtmlElements**](HtmlElements). Read-only. +The element's child-element collection. Call [**HtmlElements.Add**](HtmlElements#add) to add new children, [**Item**](HtmlElements#item) to look one up by ID. **As** [**HtmlElements**](HtmlElements). Read-only. ### Name {: .no_toc } diff --git a/docs/Reference/tbIDE/KeyboardShortcuts.md b/docs/Reference/tbIDE/KeyboardShortcuts.md index c148051..63e5111 100644 --- a/docs/Reference/tbIDE/KeyboardShortcuts.md +++ b/docs/Reference/tbIDE/KeyboardShortcuts.md @@ -8,7 +8,7 @@ has_toc: false # KeyboardShortcuts class {: .no_toc } -The IDE's keyboard-shortcut registry — reached through [**Host.KeyboardShortcuts**](Host#keyboardshortcuts). Use [**Add**](#add) to bind a key combination to a callback. There is no removal API; the registration is released when the addin is unloaded. +The IDE's keyboard-shortcut registry — reached through [**Host.KeyboardShortcuts**](Host#keyboardshortcuts). Call [**Add**](#add) to bind a key combination to a callback. There is no removal API; the registration is released when the addin is unloaded. ```tb Private Sub Host_OnProjectLoaded() @@ -45,4 +45,4 @@ Syntax: *keyboardShortcuts*.**Add** *keyString*, *Callback* *Callback* : *required* The callback. Pass `AddressOf` a sub of signature `Sub()` (no arguments). **LongPtr**. -The callback runs on the IDE's UI thread. Long-running work inside the callback will block the IDE until it returns — keep the callback short and offload heavy work to a background mechanism if needed. +The callback runs on the IDE's UI thread. Long-running work inside the callback will block the IDE until it returns — keep the callback short and offload heavy work to a background mechanism when needed. diff --git a/docs/Reference/tbIDE/Project.md b/docs/Reference/tbIDE/Project.md index ddcf57b..b60b748 100644 --- a/docs/Reference/tbIDE/Project.md +++ b/docs/Reference/tbIDE/Project.md @@ -74,7 +74,7 @@ The project's GUID as a string — e.g. `"{99DEC38C-75F6-4488-8EE7-2D52D83881D2} ### RootFolder {: .no_toc } -The root of the project's virtual file system — the entry point for walking sources, resources, packages, and other project contents. **As** [**Folder**](Folder). Read-only. +The root of the project's virtual file system — the entry point for traversing sources, resources, packages, and other project contents. **As** [**Folder**](Folder). Read-only. ### VersionBuild, VersionMajor, VersionMinor, VersionRevision {: .no_toc } @@ -127,7 +127,7 @@ Else End If ``` -Same engine the DEBUG CONSOLE uses, so the same set of identifiers, the same accessibility rules, and the same error semantics apply — including the run-time errors that arise from inside the evaluated expression. Wrap in `On Error Resume Next` if the expression may raise. +Same engine the DEBUG CONSOLE uses, so the same set of identifiers, the same accessibility rules, and the same error semantics apply — including the run-time errors that arise from inside the evaluated expression. Wrap in `On Error Resume Next` when the expression may raise. ### LoadMetaData {: .no_toc } diff --git a/docs/Reference/tbIDE/Themes.md b/docs/Reference/tbIDE/Themes.md index 3fdeb4a..f5db8ac 100644 --- a/docs/Reference/tbIDE/Themes.md +++ b/docs/Reference/tbIDE/Themes.md @@ -37,7 +37,7 @@ End Sub The name of the current IDE theme — e.g. `"Classic"`, `"Dark"`, `"Light"`. **String**, read-only. -Note that the set of available themes is determined by the IDE and may grow in future versions; do not switch on this value with an exhaustive `Select Case`. For binary light-vs-dark colour decisions, use [**ActiveThemeNameGroup**](#activethemenamegroup) instead. +The set of available themes is determined by the IDE and may grow in future versions; do not switch on this value with an exhaustive `Select Case`. For binary light-vs-dark colour decisions, use [**ActiveThemeNameGroup**](#activethemenamegroup) instead. ### ActiveThemeNameGroup {: .no_toc } diff --git a/docs/Reference/tbIDE/ToolWindow.md b/docs/Reference/tbIDE/ToolWindow.md index 894814d..013f033 100644 --- a/docs/Reference/tbIDE/ToolWindow.md +++ b/docs/Reference/tbIDE/ToolWindow.md @@ -29,21 +29,21 @@ Private Sub Button1_OnClick() End Sub ``` -Use the `WithEvents` reference to receive [**OnClose**](#onclose) when the user dismisses the pane — typically the addin uses that event to release any per-window state (timers, references to DOM elements …). +A `WithEvents` reference receives [**OnClose**](#onclose) when the user dismisses the pane — typically the addin uses that event to release any per-window state (timers, references to DOM elements …). * TOC {:toc} ## Tool-window default member — jQuery-style child lookup -[**RootDomElement**](#rootdomelement) is the **DefaultMember** of the **ToolWindow** interface — so `myToolWindow.(...)` is equivalent to `myToolWindow.RootDomElement.Properties.(...)`. Because [**HtmlElementProperties**](HtmlElementProperties) is `[COMExtensible(True)]`, a string passed in parenthesis-syntax is resolved against the DOM at run time. The IDE treats CSS-style selectors specially, so: +[**RootDomElement**](#rootdomelement) is the **DefaultMember** of the **ToolWindow** interface — so `myToolWindow(...)` is equivalent to `myToolWindow.RootDomElement.Properties(...)`. Because [**HtmlElementProperties**](HtmlElementProperties) is `[COMExtensible(True)]`, a string passed in parenthesis-syntax is resolved against the DOM at run time. The IDE treats CSS-style selectors specially, so: ```tb ' Find the descendant element whose id is "dataEntry" and read its .Value: Dim entered As String = myToolWindow("#dataEntry").Value ``` -Useful for grabbing a single child element by ID without holding a separate `As HtmlElement` reference for it. +Useful for accessing a single child element by ID without holding a separate `As HtmlElement` reference for it. ## Suggested initial size @@ -52,9 +52,6 @@ Useful for grabbing a single child element by ID without holding a separate `As > [!NOTE] > Set `suggestedWidth` / `suggestedHeight` before the first time the pane becomes visible. If the pane has previously been opened by this user (and a persistence ID was supplied to [**ToolWindows.Add**](ToolWindows#add)), the IDE-remembered size wins. -* TOC -{:toc} - ## Properties ### Name @@ -95,7 +92,7 @@ Syntax: *toolWindow*.**Visible** [ = *value* ] ### ApplyCss {: .no_toc } -Injects a `