From 14a20b8291ca3fcd0302e986e1e7c0b0dff93090 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Thu, 14 May 2026 19:45:31 +0200 Subject: [PATCH 1/2] Add a minimal style guide to the WIP. --- WIP.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 76 insertions(+), 1 deletion(-) diff --git a/WIP.md b/WIP.md index 3f581cd..a7fdb09 100644 --- a/WIP.md +++ b/WIP.md @@ -56,7 +56,7 @@ Per-package content-shape references live in sibling files. Open the relevant on - [tbIDE Package](WIP.tbIDE.md) — the addin SDK (type-only compiler package): 23 CoClasses + `AddinTimer` + the HTML/DOM `[COMExtensible]` surface + samples 10–15 idiom map. - [WinNativeCommonCtls Package](WIP.WinNativeCommonCtls.md) — VB6-compatible `MSCOMCTL.OCX` replacement: 8 controls + 8 sub-objects + per-control nested enums + 10 module-level enums. -The three "winlibs" packages — [WinServicesLib](WIP.WinServicesLib.md), [WinEventLogLib](WIP.WinEventLogLib.md), and [WinNamedPipesLib](WIP.WinNamedPipesLib.md) — share a load-bearing set of integration idioms: composition-delegation on `EventLog(Of …)`, the `ManualMessageLoopEnter` / `Leave` pattern coupling `NamedPipeServer` to a service's `ChangeState` handler, and `PropertyBag` as the canonical pipe payload. When working on any of the three, check the other two for cross-references. +The three "winlibs" packages — [WinServicesLib](WIP.WinServicesLib.md), [WinEventLogLib](WIP.WinEventLogLib.md), and [WinNamedPipesLib](WIP.WinNamedPipesLib.md) — share an essential set of integration idioms: composition-delegation on `EventLog(Of …)`, the `ManualMessageLoopEnter` / `Leave` pattern coupling `NamedPipeServer` to a service's `ChangeState` handler, and `PropertyBag` as the canonical pipe payload. When working on any of the three, check the other two for cross-references. ## Page template @@ -308,6 +308,81 @@ Add a `> [!NOTE]` callout or rewrite the affected section when source diverges. When in doubt about a tB-specific behavior, check `docs/Features/` and `docs/Reference/index.md` before assuming VBA semantics carry over. +## Plain-English prose + +The audience is international: standard-English readers worldwide, often non-native, who may not parse idiomatic software-developer jargon. Use plain English in reference and tutorial prose. + +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. + +### Replace + +| Term | Use instead | +|------|-------------| +| `at rest` (idle state) | idle, in its default state | +| `bake in` / `baked into` | embedded, stored, included | +| `broker` (as verb) | manages, handles | +| `carry` / `carries` (figurative) | has, contains, includes | +| `catches up` | resumes, processes the queue | +| `comes up` (a connection) | is established, becomes ready | +| `drive` / `driven` (figurative) | controlled by, determined by, powered by | +| `for free` (figurative) | as a side effect, without extra effort | +| `hand off` / `hand over` / `hand back` | returns, passes, delivers | +| `hand-rolled` | manually constructed, custom-built | +| `handful` / `handy` | a few; useful | +| `heavy hitter` / `heavy-hitter` (figurative) | main items, biggest items, most significant | +| `in flight` / `in-flight` | pending, in progress | +| `in one shot` | in a single call | +| `in order to` | to | +| `kick off` / `kicks off` | start, begin | +| `land` (figurative — "where the call lands") | appears, arrives, ends up at | +| `leverage` / `leveraging` | use, take advantage of | +| `load-bearing` (figurative) | essential, critical, central | +| `mid-call` | during the call | +| `on the wire` | transmitted, over the network | +| `orchestration` / `orchestrate` | coordination, manual handling | +| `picks up` (figurative) | receives, reads, captures, inherits | +| `pinned to` (UI layout) | attached to, fixed to | +| `reach for` / `reaching into` | use, access | +| `sensible defaults` | reasonable defaults, or list them inline | +| `spin up` / `spins up` | start, create | +| `stash` (as verb) | store, save | +| `sticks` (figurative — "the zoom sticks") | is preserved, is retained | +| `surface` (as verb) | expose, appear as, make available, raise | +| `surface area` (figurative API surface) | set of members, interface | +| `swallow` (a keystroke) | consume, discard | +| `taps into` | hooks into, intercepts | +| `tear down` (figurative) | destroy, unload | +| `twirling` (UI animation) | spinning, or describe concretely | +| `under the hood` | internally | +| `utilize` | use | +| `walk` (as verb — "walk the chain", "walks the children") | traverse, go through, iterate over | +| `walks through` (tutorials) | demonstrates, explains, describes step by step | +| `wire up` / `wired up` / `wired in` | connect, attach, link | + +### Delete outright + +Vague compliments that add no information. Be concrete instead — if a feature is fast, say what it is faster than; if an API is small, say how many members it has. + +- `powerful` +- `robust` +- `clean` (as a vague compliment — "clean architecture"; literal uses like "clean shutdown" stay) +- `rich` (vague — "rich information"; literal "Rich Text Format" stays) +- `easily` (filler — "easily share" → "share") + +### Keep as-is + +Don't over-correct these — they are precise technical vocabulary or otherwise pull their weight: + +- **Programming / Win32 / COM:** `no-op`, `round-trip` / `round-tripping`, `fire-and-forget`, `marshal` / `marshalled` (between threads), `pump` (messages) / `message pump`, `spawn` (a thread or process), `mixin`, `first-class` (type), `boilerplate`, `falls through`, `short-circuit`, `idiom` / `idiomatic`, `canonical`. +- **Standard prose:** `ends up`, `modern`, `lightweight`, `talk to` (interop), `out of the box`, `on the fly`, `work around` / `workaround`. +- **Vivid but tolerable:** `ship` / `ships with`, `bridge` (figurative), `cascade` (figurative), `fold in` (compile-time emit). +- **Audience-appropriate VB6 vocabulary:** `drop it onto a form`. +- **Marketing register (Videos section only — promotional copy):** `sneak peek`, `game-changing`, `drop-in`, `seamless`. + +### Anchors + +Some kept terms are referenced by in-doc anchors. The most prominent is `idiom` / `idiomatic` — `WIP.WinEventLogLib.md` and `WIP.WinServicesLib.md` reference anchors like `#service-host-idiom` and `#composition-delegation-idiom`. Don't rename these casually; if you do, add `redirect_from` aliases to preserve legacy links. + ## Scripts and tooling Any new helper script (content conversion, link checks beyond `check.bat`, etc.) should be written in **Python**. Do not add new Ruby code to this repo. The only Ruby allowed is the existing Jekyll/`just-the-docs` build chain (`Gemfile`, `Gemfile.lock`, `_plugins/`) — that stays as-is. From fae34ab67eb59eb193ccc231ec42bf3b6fcd8577 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Thu, 14 May 2026 20:30:53 +0200 Subject: [PATCH 2/2] Editorial work to de-colloquialise the docs. --- docs/Challenges/index.md | 2 +- .../self-contained_diagnostic_tool.md | 2 +- docs/Features/Advanced/API-Declarations.md | 2 +- docs/Features/Attributes-Intro.md | 4 +-- docs/Features/Compiler-IDE/CodeLens.md | 2 +- docs/Features/Compiler-IDE/Debugging.md | 2 +- docs/Features/Compiler-IDE/IDE-Features.md | 2 +- docs/Features/Fusion.md | 4 +-- docs/Features/GUI-Components/Windowless.md | 4 +-- docs/Features/Language/Inheritance.md | 2 +- .../Packages/Creating a TWINPACK package.md | 2 +- docs/Features/Packages/Updating a package.md | 2 +- docs/Features/Packages/index.md | 2 +- docs/Features/index.md | 2 +- docs/Miscellaneous/FAQs.md | 2 +- docs/Reference/Attributes.md | 4 +-- .../CEF/CefBrowser/EnvironmentOptions.md | 2 +- docs/Reference/CEF/CefBrowser/index.md | 32 +++++++++---------- docs/Reference/CEF/Enumerations/index.md | 2 +- docs/Reference/CEF/index.md | 10 +++--- docs/Reference/Compiler Constants.md | 2 +- docs/Reference/Controls.md | 4 +-- docs/Reference/Core/Comparison-Operators.md | 2 +- docs/Reference/Core/Delegate.md | 2 +- docs/Reference/Core/Handles.md | 2 +- docs/Reference/Core/New.md | 2 +- docs/Reference/Core/Open.md | 2 +- docs/Reference/Core/Type.md | 4 +-- .../CustomControls/Enumerations/ColorRGBA.md | 4 +-- .../CustomControls/Enumerations/Customtate.md | 2 +- .../CustomControls/Enumerations/DockMode.md | 18 +++++------ .../CustomControls/Enumerations/PixelCount.md | 2 +- .../CustomControls/Enumerations/PointSize.md | 2 +- .../CustomControls/Framework/Canvas.md | 2 +- .../Framework/CustomControlContext.md | 6 ++-- .../Framework/CustomControlsCollection.md | 2 +- .../Framework/CustomFormContext.md | 2 +- .../Framework/ICustomControl.md | 4 +-- .../CustomControls/Framework/index.md | 2 +- .../CustomControls/Styles/Anchors.md | 2 +- .../CustomControls/Styles/Borders.md | 4 +-- docs/Reference/CustomControls/Styles/Fill.md | 2 +- .../CustomControls/Styles/Padding.md | 2 +- .../CustomControls/Styles/TextRendering.md | 2 +- docs/Reference/CustomControls/Styles/index.md | 12 +++---- .../WaynesButton/WaynesButtonState.md | 2 +- .../CustomControls/WaynesButton/index.md | 6 ++-- .../CustomControls/WaynesForm/index.md | 6 ++-- docs/Reference/CustomControls/WaynesFrame.md | 6 ++-- .../WaynesGrid/CellRenderingOptions.md | 2 +- .../CustomControls/WaynesGrid/index.md | 8 ++--- docs/Reference/CustomControls/WaynesLabel.md | 2 +- .../WaynesSlider/WaynesSliderState.md | 2 +- .../CustomControls/WaynesSlider/index.md | 6 ++-- .../WaynesTextBox/WaynesTextBoxState.md | 4 +-- .../CustomControls/WaynesTextBox/index.md | 8 ++--- docs/Reference/CustomControls/WaynesTimer.md | 4 +-- docs/Reference/CustomControls/index.md | 8 ++--- docs/Reference/Glossary.md | 4 +-- docs/Reference/Packages.md | 2 +- docs/Reference/VB/App/index.md | 6 ++-- docs/Reference/VB/CheckMark/index.md | 2 +- docs/Reference/VB/Clipboard/index.md | 8 ++--- docs/Reference/VB/Data/index.md | 4 +-- docs/Reference/VB/DirListBox/index.md | 6 ++-- docs/Reference/VB/Form/index.md | 4 +-- docs/Reference/VB/Frame/index.md | 4 +-- docs/Reference/VB/HScrollBar/index.md | 4 +-- docs/Reference/VB/Image/index.md | 10 +++--- docs/Reference/VB/Label/index.md | 8 ++--- docs/Reference/VB/Line/index.md | 6 ++-- docs/Reference/VB/MDIForm/index.md | 4 +-- docs/Reference/VB/Menu/index.md | 2 +- docs/Reference/VB/OLE/index.md | 4 +-- docs/Reference/VB/Printer/index.md | 4 +-- docs/Reference/VB/Printers/index.md | 4 +-- docs/Reference/VB/PropertyPage/index.md | 10 +++--- docs/Reference/VB/QRCode/index.md | 12 +++---- docs/Reference/VB/Report/index.md | 8 ++--- docs/Reference/VB/Screen/index.md | 2 +- docs/Reference/VB/Shape/index.md | 4 +-- docs/Reference/VB/TextBox/index.md | 2 +- docs/Reference/VB/Timer/index.md | 4 +-- docs/Reference/VB/UserControl/index.md | 18 +++++------ docs/Reference/VB/VScrollBar/index.md | 4 +-- .../VBA/Compilation/CurrentComponentName.md | 2 +- .../VBA/Compilation/CurrentProjectName.md | 2 +- docs/Reference/VBA/Conversion/index.md | 2 +- docs/Reference/VBA/ErrObject/Clear.md | 2 +- docs/Reference/VBA/ErrObject/Raise.md | 2 +- docs/Reference/VBA/ErrObject/Source.md | 2 +- .../VBA/HiddenModule/GetDeclaredTypeClsid.md | 2 +- .../HiddenModule/GetDeclaredTypeEventIid.md | 2 +- .../VBA/HiddenModule/GetDeclaredTypeIid.md | 2 +- .../VBA/HiddenModule/GetDeclaredTypeProgId.md | 2 +- docs/Reference/VBA/HiddenModule/index.md | 6 ++-- docs/Reference/VBA/Interaction/CallByName.md | 2 +- .../Reference/VBA/Interaction/CreateObject.md | 2 +- docs/Reference/VBA/Interaction/GetObject.md | 2 +- docs/Reference/VBA/Interaction/SendKeys.md | 2 +- .../VBA/TbExpressionService/Compile.md | 2 +- .../VBA/TbExpressionService/index.md | 2 +- .../Reference/VBRUN/AsyncProperty/BytesMax.md | 2 +- .../VBRUN/AsyncProperty/StatusCode.md | 2 +- docs/Reference/VBRUN/AsyncProperty/index.md | 2 +- docs/Reference/VBRUN/DataObject/Files.md | 2 +- .../VBRUN/DataObject/GetDataByName.md | 2 +- docs/Reference/VBRUN/DataObject/index.md | 2 +- docs/Reference/VBRUN/ErrorContext/index.md | 4 +-- docs/Reference/VBRUN/index.md | 4 +-- docs/Reference/WebView2/Enumerations/index.md | 2 +- .../WebView2/Enumerations/wv2KeyEventKind.md | 2 +- .../WebView2/WebView2/EnvironmentOptions.md | 2 +- docs/Reference/WebView2/WebView2/index.md | 22 ++++++------- .../WebView2/WebView2RequestHeaders.md | 2 +- docs/Reference/WebView2/index.md | 16 +++++----- docs/Reference/WinEventLogLib/EventLog.md | 2 +- docs/Reference/WinEventLogLib/index.md | 10 +++--- .../NamedPipeClientConnection.md | 10 +++--- .../NamedPipeClientManager.md | 6 ++-- .../WinNamedPipesLib/NamedPipeServer.md | 12 +++---- .../NamedPipeServerConnection.md | 10 +++--- docs/Reference/WinNamedPipesLib/index.md | 10 +++--- .../Reference/WinNativeCommonCtls/DTPicker.md | 4 +-- .../Enumerations/DTPickerFormatConstants.md | 2 +- .../ImageList/ListImages.md | 2 +- .../WinNativeCommonCtls/ImageList/index.md | 2 +- .../WinNativeCommonCtls/ListView/index.md | 6 ++-- .../WinNativeCommonCtls/MonthView.md | 6 ++-- .../WinNativeCommonCtls/ProgressBar.md | 6 ++-- docs/Reference/WinNativeCommonCtls/Slider.md | 4 +-- .../WinNativeCommonCtls/TreeView/Node.md | 2 +- .../WinNativeCommonCtls/TreeView/Nodes.md | 2 +- .../WinNativeCommonCtls/TreeView/index.md | 4 +-- docs/Reference/WinNativeCommonCtls/UpDown.md | 2 +- docs/Reference/WinNativeCommonCtls/index.md | 16 +++++----- .../ServiceControlCodeConstants.md | 6 ++-- .../WinServicesLib/Enumerations/index.md | 2 +- docs/Reference/WinServicesLib/ITbService.md | 2 +- docs/Reference/WinServicesLib/Services.md | 4 +-- docs/Reference/WinServicesLib/index.md | 10 +++--- docs/Reference/tbIDE/CodeEditor.md | 6 ++-- docs/Reference/tbIDE/Editor.md | 2 +- docs/Reference/tbIDE/Editors.md | 2 +- docs/Reference/tbIDE/Host.md | 2 +- docs/Reference/tbIDE/HtmlElement.md | 4 +-- docs/Reference/tbIDE/HtmlElementProperties.md | 2 +- docs/Reference/tbIDE/HtmlElementProperty.md | 2 +- docs/Reference/tbIDE/HtmlEventProperties.md | 4 +-- docs/Reference/tbIDE/HtmlEventProperty.md | 2 +- docs/Reference/tbIDE/Project.md | 6 ++-- docs/Reference/tbIDE/Themes.md | 2 +- docs/Reference/tbIDE/Toolbars.md | 2 +- docs/Reference/tbIDE/index.md | 20 ++++++------ docs/Tutorials/Arrays.md | 2 +- .../Tutorials/CEF/Building a browser shell.md | 6 ++-- .../CEF/Customize the UserDataFolder.md | 2 +- docs/Tutorials/CEF/Driving Monaco.md | 6 ++-- docs/Tutorials/CEF/Getting started.md | 8 ++--- .../Tutorials/CEF/Hosting local web assets.md | 4 +-- docs/Tutorials/CEF/JavaScript interop.md | 4 +-- docs/Tutorials/CEF/Re-entrancy.md | 14 ++++---- docs/Tutorials/CEF/index.md | 4 +-- .../Defining a CustomControl.md | 4 +-- docs/Tutorials/CustomControls/index.md | 2 +- .../WebView2/Building a browser shell.md | 6 ++-- docs/Tutorials/WebView2/Driving Monaco.md | 4 +-- .../WebView2/Hosting local web assets.md | 4 +-- docs/Tutorials/WebView2/JavaScript interop.md | 2 +- docs/Tutorials/WebView2/index.md | 4 +-- 170 files changed, 384 insertions(+), 384 deletions(-) diff --git a/docs/Challenges/index.md b/docs/Challenges/index.md index 44ad798..5cee874 100644 --- a/docs/Challenges/index.md +++ b/docs/Challenges/index.md @@ -10,6 +10,6 @@ From **#general** on Discord: [From Wayne](https://discord.com/channels/927638153546829845/927638154192748606/1457062373465788671) in Discord: -> As we kick off 2026, we’re introducing monthly twinBASIC challenges, giving you the chance to win a £100 account credit redeemable against future twinBASIC licences. +> As we start 2026, we’re introducing monthly twinBASIC challenges, giving you the chance to win a £100 account credit redeemable against future twinBASIC licences. See this on [twinBASIC Update: January 6, 2026](https://nolongerset.com/twinbasic-update-january-6-2026/) from Mike Wolfe. diff --git a/docs/Challenges/self-contained_diagnostic_tool.md b/docs/Challenges/self-contained_diagnostic_tool.md index e802af1..bcd9248 100644 --- a/docs/Challenges/self-contained_diagnostic_tool.md +++ b/docs/Challenges/self-contained_diagnostic_tool.md @@ -63,7 +63,7 @@ Entries will be judged across multiple categories, including: Bonus points may be awarded for: - Use of newer twinBASIC features (e.g. delegates, generics) -- Particularly clean or insightful design +- Particularly clean or insightful design Winner selected at the **sole discretion of the twinBASIC team**. diff --git a/docs/Features/Advanced/API-Declarations.md b/docs/Features/Advanced/API-Declarations.md index 4b6d8a1..9d6d43a 100644 --- a/docs/Features/Advanced/API-Declarations.md +++ b/docs/Features/Advanced/API-Declarations.md @@ -132,7 +132,7 @@ For functions which contain the `va_list` type as part of their arguments the Pa ## PreserveSig -The `[PreserveSig]` attribute was described earlier for COM methods, but it can also be used on API declares. For APIs, the default is `True`. So therefore, you can specify `False` in order to rewrite the last parameter as a return. +The `[PreserveSig]` attribute was described earlier for COM methods, but it can also be used on API declares. For APIs, the default is `True`. So therefore, you can specify `False` to rewrite the last parameter as a return. ### Example diff --git a/docs/Features/Attributes-Intro.md b/docs/Features/Attributes-Intro.md index 67a2b77..5b0e42f 100644 --- a/docs/Features/Attributes-Intro.md +++ b/docs/Features/Attributes-Intro.md @@ -15,9 +15,9 @@ Attributes have two major functions: - to annotate Forms, Modules, Classes, Types, Enums, Declares, and [procedures](../tB/Gloss#procedure) i.e. Subs/Functions/Properties. -Previously in VBx, these attributes, such as procedure description, hidden, default member, and others, were set via hidden text the IDE's editor didn't show you, configured via the Procedure Attributes dialog or some other places. In tB, these are all visible in the code editor. The legacy ones from VBx are supported for compatibility, but new attributes utilize the following syntax: +Previously in VBx, these attributes, such as procedure description, hidden, default member, and others, were set via hidden text the IDE's editor didn't show you, configured via the Procedure Attributes dialog or some other places. In tB, these are all visible in the code editor. The legacy ones from VBx are supported for compatibility, but new attributes use the following syntax: `[Attribute]` or `[Attribute(value)]` -Many new attributes enable the powerful additional language features twinBASIC provides, so some of the following items have their associated attributes included in their description. +Many new attributes enable the additional language features twinBASIC provides, so some of the following items have their associated attributes included in their description. See also [the comprehensive reference for attributes](../tB/Core/Attributes). diff --git a/docs/Features/Compiler-IDE/CodeLens.md b/docs/Features/Compiler-IDE/CodeLens.md index cb8b7db..bb53af6 100644 --- a/docs/Features/Compiler-IDE/CodeLens.md +++ b/docs/Features/Compiler-IDE/CodeLens.md @@ -6,7 +6,7 @@ nav_order: 3 # Run Subs from the IDE -The CodeLens feature allows running Subs and Functions, with no arguments and in modules (but not classes/Forms/UserControls) right from the editor without starting the full program. It has robust access to your code; it can access constants, call other functions both instrinsic and user-define, call APIs, and print to the Debug Console. +The CodeLens feature allows running Subs and Functions, with no arguments and in modules (but not classes/Forms/UserControls) right from the editor without starting the full program. It has full access to your code; it can access constants, call other functions both intrinsic and user-defined, call APIs, and print to the Debug Console. Methods eligible to run with CodeLens (when enabled), have a bar above them that you can click to run: diff --git a/docs/Features/Compiler-IDE/Debugging.md b/docs/Features/Compiler-IDE/Debugging.md index 4928e66..25f87fe 100644 --- a/docs/Features/Compiler-IDE/Debugging.md +++ b/docs/Features/Compiler-IDE/Debugging.md @@ -11,7 +11,7 @@ twinBASIC includes several features to help with debugging. ## Debug Trace Logger -New to the debugging experience is a powerful trace logging feature that can automatically create detailed logs to either the debug console or a file. Messages can be output to the new system with `Debug.TracePrint`. The logger works both when running from the IDE and in compiled executables. +New to the debugging experience is a trace logging feature that automatically creates detailed logs to either the debug console or a file. Messages can be output with `Debug.TracePrint`. The logger works both when running from the IDE and in compiled executables. ![image](../Images/4fc2bf99-2bec-4943-837d-21038d791574.png) diff --git a/docs/Features/Compiler-IDE/IDE-Features.md b/docs/Features/Compiler-IDE/IDE-Features.md index 3537542..9b9c2fa 100644 --- a/docs/Features/Compiler-IDE/IDE-Features.md +++ b/docs/Features/Compiler-IDE/IDE-Features.md @@ -59,7 +59,7 @@ The classic file-based view is still used by default, you can activate the new v ## View Forms and Packages as JSON -Project forms and packages are stored as JSON format data, and you can view this by right-click in Project Explorer and selecting 'View as JSON'. This is particularly interesting for packages as it exposes the entire code in a much more easily parsed format. +Project forms and packages are stored as JSON format data, and you can view this by right-click in Project Explorer and selecting 'View as JSON'. This is particularly interesting for packages as it exposes the entire code in a more parseable format. ![image](../Images/22660f54-ff5d-4b21-93d3-39715f1f35ed.png) diff --git a/docs/Features/Fusion.md b/docs/Features/Fusion.md index bfc094a..344823b 100644 --- a/docs/Features/Fusion.md +++ b/docs/Features/Fusion.md @@ -153,7 +153,7 @@ This explicit path must be set **before** opening any Fusion-backed form or cont ## Current Limitations -Fusion is a powerful compatibility layer, but not all ActiveX controls are supported. +Fusion is a compatibility layer, but not all ActiveX controls are supported. #### Currently NOT supported: - Windowless controls @@ -181,4 +181,4 @@ Mouse events are not currently OLE-translated, therefore mouse event signatures *twinBASIC Fusion* provides a practical path for modernising applications while retaining compatibility with legacy ActiveX controls. -By leveraging an out-of-process architecture and fast IPC-based communication, *twinBASIC Fusion* enables cross-bitness interoperability while maintaining a familiar programming model. \ No newline at end of file +By using an out-of-process architecture and fast IPC-based communication, *twinBASIC Fusion* enables cross-bitness interoperability while maintaining a familiar programming model. \ No newline at end of file diff --git a/docs/Features/GUI-Components/Windowless.md b/docs/Features/GUI-Components/Windowless.md index 8a72788..80cf39d 100644 --- a/docs/Features/GUI-Components/Windowless.md +++ b/docs/Features/GUI-Components/Windowless.md @@ -101,7 +101,7 @@ redirect_from: 1. **Render the Entire Form to a Bitmap** * In VB6: Use `BitBlt` or `PaintPicture` to copy the form’s visible area. - * In TwinBASIC: Use the form’s [`Canvas`](../../tB/Packages/CustomControls/Framework/Canvas) or [`ICustomControl.Paint`](../../tB/Packages/CustomControls/Framework/ICustomControl#paint) logic to manually render windowless elements to a bitmap. See the [CustomControls package reference](../../tB/Packages/CustomControls/) for the full framework surface. + * In TwinBASIC: Use the form’s [`Canvas`](../../tB/Packages/CustomControls/Framework/Canvas) or [`ICustomControl.Paint`](../../tB/Packages/CustomControls/Framework/ICustomControl#paint) logic to manually render windowless elements to a bitmap. See the [CustomControls package reference](../../tB/Packages/CustomControls/) for the full framework API. 2. **Ensure Windowless Controls Are Painted** @@ -146,4 +146,4 @@ Printer.EndDoc ``` --- -For DPI-aware, multi-monitor layout work, windowless controls can be a powerful tool—especially for static or decorative elements—but they demand more orchestration when interactivity or layering is involved. If you're building a hybrid layout, a mix of both types might give you the best of both worlds. +For DPI-aware, multi-monitor layout work, windowless controls are useful—especially for static or decorative elements—but they demand more manual handling when interactivity or layering is involved. If you're building a hybrid layout, a mix of both types might give you the best of both worlds. diff --git a/docs/Features/Language/Inheritance.md b/docs/Features/Language/Inheritance.md index 12c5cff..4a9254b 100644 --- a/docs/Features/Language/Inheritance.md +++ b/docs/Features/Language/Inheritance.md @@ -53,7 +53,7 @@ You can see that the Honk method is only implemented by the parent class, then c ## **Inherits** for Complete OOP -This is a more robust option for full inheritance and OOP. It supports `Protected` methods and variables that are accessible to derived classes but not outside callers, `Overridable` and `Overrides` syntax, multiple inheritance, and explicit base class constructors. +This option supports full inheritance and OOP: `Protected` methods and variables accessible to derived classes (but not outside callers), `Overridable` and `Overrides` syntax, multiple inheritance, and explicit base class constructors. ### Example: Animal Class Hierarchy diff --git a/docs/Features/Packages/Creating a TWINPACK package.md b/docs/Features/Packages/Creating a TWINPACK package.md index 8e09079..b52a7ed 100644 --- a/docs/Features/Packages/Creating a TWINPACK package.md +++ b/docs/Features/Packages/Creating a TWINPACK package.md @@ -25,7 +25,7 @@ Once you've created the project, you should find the extra 'PACKAGE PUBLISHING' You should now edit the Namespace, Description, Licence and Visibility properties appropriately by using the package manager 'EDIT' links, which will take you to the individual settings in the `Settings` file. Once you've edited them, remember to close (and save) the `Settings` file in order for your changes to be reflected in the package manager panel. - **Namespace:** this is the symbol that will be used to group your components in projects that reference your package. For example, a package that provides a series of different dialog classes might use the namespace `Dialogs`. -- **Description:** this is the descriptive text that will appear in the `Settings`->`References` list. If you plan to share this package, it is wise to think carefully about the description so that others can find your package easily through TWINSERV. +- **Description:** this is the descriptive text that will appear in the `Settings`->`References` list. If you plan to share this package, think carefully about the description so that others can discover your package through TWINSERV. - **Licence:** this short text appears in the `Settings`->`References` list, alongside the Description. If you plan to share this package, it is important that you enter this field, and the value you enter here should appropriately match the content of the LICENCE.md file (e.g. 'MIT', 'LGPL' etc). - **Visibility:** determines whether the package is visible to only you (PRIVATE) or everyone (PUBLIC). The value set here only takes effect when you use the 'PUBLISH THIS PACKAGE' button to publish your package in the package manager service, TWINSERV. diff --git a/docs/Features/Packages/Updating a package.md b/docs/Features/Packages/Updating a package.md index 0af79b8..5f10eab 100644 --- a/docs/Features/Packages/Updating a package.md +++ b/docs/Features/Packages/Updating a package.md @@ -32,7 +32,7 @@ then it's done and ready to be saved when a second message saying `[PACKAGES] downloading package '{1FCDB98D-617D-4995-9736-2ED0E4746A10}/8/7/0/498' from the online database... [DONE]` -comes up. It will also go from the checkbox twirling to the entry being moved to the top (below built in packages) with `[IMPORTED]` prepended to it. +comes up. It will also go from the checkbox spinning to the entry being moved to the top (below built in packages) with `[IMPORTED]` prepended to it. Restart the compiler if it doesn't on its own after saving, but it usually does. diff --git a/docs/Features/Packages/index.md b/docs/Features/Packages/index.md index 73c4ce2..0f68ddf 100644 --- a/docs/Features/Packages/index.md +++ b/docs/Features/Packages/index.md @@ -16,6 +16,6 @@ A twinBASIC package is distributed as a TWINPACK file that contains everything n With TWINPACK packages you group common components together into their own namespace whilst allowing for convenient code reuse without any of the problems often associated with using external DLL libraries. -twinBASIC comes complete with a package manager service called TWINSERV, allowing you to easily share and distribute TWINPACK packages to other twinBASIC developers. +twinBASIC comes complete with a package manager service called TWINSERV, allowing you to share and distribute TWINPACK packages to other twinBASIC developers. Please be aware that TWINPACK files currently contain the full sourcecode of your packaged components. It is planned that we will in future allow for creating binary (compiled) TWINPACK files for developers that hold an Ultimate edition licence of twinBASIC. diff --git a/docs/Features/index.md b/docs/Features/index.md index 047c23d..ded0ffe 100644 --- a/docs/Features/index.md +++ b/docs/Features/index.md @@ -11,7 +11,7 @@ has_toc: false This section documents all the features and enhancements that twinBASIC brings compared to VBx and earlier BASIC dialects. -twinBASIC maintains backward compatibility with VBx syntax while providing these powerful new features. Most enhancements are opt-in, allowing you to gradually adopt them in your projects. +twinBASIC maintains backward compatibility with VBx syntax while providing these new features. Most enhancements are opt-in, allowing you to gradually adopt them in your projects. For detailed documentation on each feature, navigate to the specific category listed below. diff --git a/docs/Miscellaneous/FAQs.md b/docs/Miscellaneous/FAQs.md index bb68107..5e999d5 100644 --- a/docs/Miscellaneous/FAQs.md +++ b/docs/Miscellaneous/FAQs.md @@ -275,7 +275,7 @@ For an existing project, the Project Scope Option Explicit can be turned on or o Does twinBASIC support addins? {: #addins } -Addins for VB6 and VBA are not supported by the twinBASIC IDE. However, tB has its own powerful addin infrastructure based on modern web technologies. See Samples 10 through 16 in the 'Samples' tab of the New Project dialog: +Addins for VB6 and VBA are not supported by the twinBASIC IDE. However, tB has its own addin infrastructure based on modern web technologies. See Samples 10 through 16 in the 'Samples' tab of the New Project dialog: ![image](Images/0e24eb5c-c9af-49a9-a908-03968b211554.png) diff --git a/docs/Reference/Attributes.md b/docs/Reference/Attributes.md index 6ff5a74..bd7d11e 100644 --- a/docs/Reference/Attributes.md +++ b/docs/Reference/Attributes.md @@ -13,7 +13,7 @@ Attributes have two major functions: - they can act as instructions to compiler to influence how code is generated, or - to annotate Forms, Modules, Classes, Types, Enums, Declares, and [procedures](../Gloss#procedure) i.e. Subs/Functions/Properties. -Previously in VBx, these attributes, such as the procedure description, hidden, default member, and others, were set via hidden text the IDE's editor didn't show you, configured via the Procedure Attributes dialog or some other places. In tB, these are all visible in the code editor. The legacy ones from VBx are supported for compatibility, but new attributes utilize the following syntax: +Previously in VBx, these attributes, such as the procedure description, hidden, default member, and others, were set via hidden text the IDE's editor didn't show you, configured via the Procedure Attributes dialog or some other places. In tB, these are all visible in the code editor. The legacy ones from VBx are supported for compatibility, but new attributes use the following syntax: `[Attribute]` or `[Attribute(value)]` In attributes that take an optional boolean argument, the value of the argument is taken to be **True** if no value is provided. This does not mean that the default value of the attribute is True, just that if the attribute is specified within the braces with no value, its value will be set to True. Different boolean-valued attributes have different default values. Those values apply unless the user has explicitly provided the attribute. @@ -553,7 +553,7 @@ Default value: **False** in an Interface, **True** in an API Declare. In COM interfaces, the default value of this attribute is **False**, since normally methods return an HRESULT that the language hides from you. **[PreserveSig** [ **(True)** ] **]** overrides this behavior and defines the function exactly as you provide. This is necessary if you need to define it as returning something other than a 4-byte **Long**, or want to handle the result yourself, bypassing the normal runtime error raised if the return value is negative (this is helpful when a negative value indicates an expected, acceptable failure, rather than a true error, like when an enum interface is out of items). -In APIs, the default value of this attribute is `True`. So therefore, you can specify `False` in order to rewrite the last parameter as a return. Example: +In APIs, the default value of this attribute is `True`. So therefore, you can specify `False` to rewrite the last parameter as a return. Example: ```tb Public Declare PtrSafe Function SHGetDesktopFolder Lib "shell32" (ppshf As IShellFolder) As Long diff --git a/docs/Reference/CEF/CefBrowser/EnvironmentOptions.md b/docs/Reference/CEF/CefBrowser/EnvironmentOptions.md index 273bdfd..20e178c 100644 --- a/docs/Reference/CEF/CefBrowser/EnvironmentOptions.md +++ b/docs/Reference/CEF/CefBrowser/EnvironmentOptions.md @@ -62,7 +62,7 @@ Set to **CefLogWarning** or **CefLogError** when investigating runtime issues, a Path to the folder CEF uses for the user profile — cache, cookies, history, local storage, and so on. **String**. Default: empty (the runtime picks a folder under `%LocalAppData%\twinBASIC_CEF\\`). -Set a writable, application-specific path when the default would land in a read-only location, or when multiple deployments of the same application must keep their profiles separate. The same folder cannot be opened by two CEF processes simultaneously — if it's already locked, the [**Error**](.#error) event fires with *"CEF cache path already locked by another process"*. +Set a writable, application-specific path when the default would end up in a read-only location, or when multiple deployments of the same application must keep their profiles separate. The same folder cannot be opened by two CEF processes simultaneously — if it's already locked, the [**Error**](.#error) event fires with *"CEF cache path already locked by another process"*. ### See Also diff --git a/docs/Reference/CEF/CefBrowser/index.md b/docs/Reference/CEF/CefBrowser/index.md index b36c081..a0800d4 100644 --- a/docs/Reference/CEF/CefBrowser/index.md +++ b/docs/Reference/CEF/CefBrowser/index.md @@ -27,14 +27,14 @@ Private Sub CefBrowser1_NavigationComplete( _ End Sub ``` -The control inherits the rect-dockable surface (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 surface — 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 you might find on [**WebView2**](../../WebView2/WebView2/) are not part of its API — keystrokes go straight into the page once Chromium has focus. * TOC {:toc} ## Lifecycle -A **CefBrowser** control progresses through three distinct phases, each driven by an asynchronous step in the CEF runtime: +A **CefBrowser** control progresses through three distinct phases, each triggered by an asynchronous step in the CEF runtime: | Event | When | |--------------------------------|-------------------------------------------------------------------------------------------------------------------| @@ -54,7 +54,7 @@ By default the control launches the browser helper as soon as the form is loaded The control offers three families of BASIC ↔ JavaScript bridges: -- **Posting messages** — [**PostWebMessage**](#postwebmessage) sends a value to the page where it surfaces via `window.chrome.webview.addEventListener('message', …)`. The page replies with `window.chrome.webview.postMessage(…)`, which fires the [**JsMessage**](#jsmessage) event. +- **Posting messages** — [**PostWebMessage**](#postwebmessage) sends a value to the page where it arrives via `window.chrome.webview.addEventListener('message', …)`. The page replies with `window.chrome.webview.postMessage(…)`, which fires the [**JsMessage**](#jsmessage) event. - **Executing script** — [**JsRun**](#jsrun) calls a named JavaScript function and waits for the result, [**JsRunAsync**](#jsrunasync) calls one and fires [**JsAsyncResult**](#jsasyncresult) when the result arrives, and [**ExecuteScript**](#executescript) fires-and-forgets a snippet without awaiting a result. Synchronous [**JsRun**](#jsrun) blocks the BASIC thread until the renderer replies — which means that re-entrancy from the page (a JavaScript handler that posts back into BASIC during the call) can cause a UI freeze. Use [**JsRunAsync**](#jsrunasync) whenever the call is non-trivial. @@ -66,12 +66,12 @@ Synchronous [**JsRun**](#jsrun) blocks the BASIC thread until the renderer repli Properties ---------- -The control inherits the standard rect-dockable surface from `BaseControlRectDockable` — size, position, **Anchors**, **Dock**, **Container**, the design-time **Name** / **Index** / **Tag**. +The control inherits the standard rect-dockable members from `BaseControlRectDockable` — size, position, **Anchors**, **Dock**, **Container**, the design-time **Name** / **Index** / **Tag**. ### Anchors {: .no_toc } -The container-edge anchors that drive automatic resizing when the parent **Form** is resized. Inherited from `BaseControlRectDockable`. +The container-edge anchors that control automatic resizing when the parent **Form** is resized. Inherited from `BaseControlRectDockable`. ### CanGoBack {: .no_toc } @@ -156,7 +156,7 @@ The **Form** (or other container) that hosts this control. **Object**. Read-only ### Tag {: .no_toc } -A user-defined string carried by the control. **String**. Inherited. +A user-defined string stored on the control. **String**. Inherited. ### Top {: .no_toc } @@ -207,7 +207,7 @@ Syntax: *object*.**ClearVirtualHostNameToFolderMapping** *hostName* ### ExecuteScript {: .no_toc } -Evaluates JavaScript in the page without waiting for it to finish and without surfacing 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 you need the value. Syntax: *object*.**ExecuteScript** *jsCode* @@ -262,7 +262,7 @@ Debug.Print product ' 30 ### JsRunAsync {: .no_toc } -Calls a named JavaScript function asynchronously and returns immediately. When the result arrives, [**JsAsyncResult**](#jsasyncresult) fires carrying the result and an error string. +Calls a named JavaScript function asynchronously and returns immediately. When the result arrives, [**JsAsyncResult**](#jsasyncresult) fires with the result and an error string. Syntax: *object*.**JsRunAsync** *FuncName*, [ *args* ] @@ -287,7 +287,7 @@ Private Sub CefBrowser1_JsAsyncResult( _ End Sub ``` -If **JsRunAsync** is called before the renderer IPC has connected, the call is queued and dispatched once the connection comes up. +If **JsRunAsync** is called before the renderer IPC has connected, the call is queued and dispatched once the connection is established. ### Move {: .no_toc } @@ -326,14 +326,14 @@ Syntax: *object*.**OpenDevToolsWindow** ### PostWebMessage {: .no_toc } -Sends a value to the page; it surfaces via `window.chrome.webview.addEventListener('message', …)`. The page can reply with `window.chrome.webview.postMessage(…)`, which fires the [**JsMessage**](#jsmessage) event. +Sends a value to the page; it arrives via `window.chrome.webview.addEventListener('message', …)`. The page can reply with `window.chrome.webview.postMessage(…)`, which fires the [**JsMessage**](#jsmessage) event. Syntax: *object*.**PostWebMessage** *Message* *Message* -: *required* A **Variant** carrying the value to send. Strings, numbers, **Boolean**, **Null**, and **Empty** are JSON-encoded for the page; objects and arrays are not currently supported. +: *required* A **Variant** containing the value to send. Strings, numbers, **Boolean**, **Null**, and **Empty** are JSON-encoded for the page; objects and arrays are not currently supported. -If **PostWebMessage** is called before the renderer IPC has connected, the call is queued and dispatched once the connection comes up. +If **PostWebMessage** is called before the renderer IPC has connected, the call is queued and dispatched once the connection is established. ### PrintToPdf {: .no_toc } @@ -435,7 +435,7 @@ Syntax: *object*\_**DocumentTitleChanged**( ) ### DOMContentLoaded {: .no_toc } -Raised when the page reaches the `DOMContentLoaded` lifecycle event — the DOM tree is built and JavaScript can safely walk it, but external resources may still be loading. +Raised when the page reaches the `DOMContentLoaded` lifecycle event — the DOM tree is built and JavaScript can safely traverse it, but external resources may still be loading. Syntax: *object*\_**DOMContentLoaded**( ) @@ -481,7 +481,7 @@ Raised after a navigation initiated by [**Navigate**](#navigate), [**NavigateToS Syntax: *object*\_**NavigationComplete**( *IsSuccess* **As Boolean**, *WebErrorStatus* **As Long** ) > [!NOTE] -> *IsSuccess* and *WebErrorStatus* are part of the event signature but currently return placeholder values (`True` and `0`) — the underlying CEF callbacks that would populate them have not yet been wired in. Use the document state ([**DocumentURL**](#documenturl), [**CanGoBack**](#cangoback)) to determine the outcome. +> *IsSuccess* and *WebErrorStatus* are part of the event signature but currently return placeholder values (`True` and `0`) — the underlying CEF callbacks that would populate them have not yet been connected. Use the document state ([**DocumentURL**](#documenturl), [**CanGoBack**](#cangoback)) to determine the outcome. ### NavigationStarting {: .no_toc } @@ -553,8 +553,8 @@ End Sub ## See Also -- [CefEnvironmentOptions](EnvironmentOptions) -- pre-creation configuration carried by [**EnvironmentOptions**](#environmentoptions) +- [CefEnvironmentOptions](EnvironmentOptions) -- pre-creation configuration exposed through [**EnvironmentOptions**](#environmentoptions) - [CefLogSeverity](../Enumerations/CefLogSeverity), [cefPrintOrientation](../Enumerations/cefPrintOrientation) -- the package's two user-facing enumerations -- [WebView2](../../WebView2/WebView2/) -- the WebView2-runtime counterpart with a larger feature surface +- [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/Enumerations/index.md b/docs/Reference/CEF/Enumerations/index.md index 55a7933..7513ad6 100644 --- a/docs/Reference/CEF/Enumerations/index.md +++ b/docs/Reference/CEF/Enumerations/index.md @@ -7,7 +7,7 @@ has_toc: false # Enumerations -The two user-facing enumerations the **CEF** package exposes. The package's larger surface of internal `cef_*_t` enums (mirroring the CEF C API) lives in `Private Module` wrappers and is not part of the public API. +The two user-facing enumerations the **CEF** package exposes. The package's larger set of internal `cef_*_t` enums (mirroring the CEF C API) lives in `Private Module` wrappers and is not part of the public API. | Enumeration | Used by | |-------------|---------| diff --git a/docs/Reference/CEF/index.md b/docs/Reference/CEF/index.md index a8c9c40..1f9d2e0 100644 --- a/docs/Reference/CEF/index.md +++ b/docs/Reference/CEF/index.md @@ -32,7 +32,7 @@ Choose [**WebView2**](../WebView2/) when targeting only modern Windows and willi ## Supported runtimes -Three CEF versions are supported, each carrying a different Chromium baseline and different OS reach: +Three CEF versions are supported, each with a different Chromium baseline and different OS reach: | Runtime version | Supported OS | Notes | |-----------------|---------------|----------------------------------------------------------------| @@ -103,18 +103,18 @@ These [**WebView2**](../WebView2/) features are not yet exposed on **CefBrowser* - Methods: **OpenTaskManagerWindow**, **AddObject** (host-object publication for JavaScript), **AddWebResourceRequestedFilter** and the surrounding request-interception machinery. - Events: **AcceleratorKeyPressed**, **PermissionRequested**, **WebResourceRequested**, **ProcessFailed**, **ScriptDialogOpening**, **UserContextMenu**, **SuspendCompleted**, **SuspendFailed**, **DownloadStarting**, **NewWindowRequested**. -The [**NavigationComplete**](CefBrowser/#navigationcomplete) event carries **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 wired in. +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 surface 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; treat this list as a snapshot of the current beta and not a long-term limitation. ## Classes -- [CefBrowser](CefBrowser/) -- the control: navigation, scripting, virtual-host mapping, PDF printing, and lifecycle events driven by the matching CEF runtime +- [CefBrowser](CefBrowser/) -- the control: navigation, scripting, virtual-host mapping, PDF printing, and lifecycle events controlled by the matching CEF runtime - [CefEnvironmentOptions](CefBrowser/EnvironmentOptions) -- pre-creation configuration for the CEF environment (executable folder, user-data folder, log file, log severity); reached via the control's **EnvironmentOptions** property ## Enumerations -- [CefLogSeverity](Enumerations/CefLogSeverity) -- the verbosity threshold for the CEF debug log; carried by [**EnvironmentOptions.LogSeverity**](CefBrowser/EnvironmentOptions#logseverity) +- [CefLogSeverity](Enumerations/CefLogSeverity) -- the verbosity threshold for the CEF debug log; used by [**EnvironmentOptions.LogSeverity**](CefBrowser/EnvironmentOptions#logseverity) - [cefPrintOrientation](Enumerations/cefPrintOrientation) -- page orientation passed to [**PrintToPdf**](CefBrowser/#printtopdf) ## Tutorials diff --git a/docs/Reference/Compiler Constants.md b/docs/Reference/Compiler Constants.md index d191dcb..8e55b56 100644 --- a/docs/Reference/Compiler Constants.md +++ b/docs/Reference/Compiler Constants.md @@ -96,7 +96,7 @@ Or more simply, to determine whether to use `PtrSafe` then `DeclareWide` or othe ``` > [!IMPORTANT] -> Reminder: Compiler Constants are not `Boolean` values, so you shouuldn't use syntax like `#If Not Win64 Then` as the result may not be desired, for instance that example evaluates to `True` for both 32bit and 64bit modes when you likely used it expecting `False` under 64bit in order to use 32bit-only code.\ +> Reminder: Compiler Constants are not `Boolean` values, so you shouuldn't use syntax like `#If Not Win64 Then` as the result may not be desired, for instance that example evaluates to `True` for both 32bit and 64bit modes when you likely used it expecting `False` under 64bit to use 32bit-only code.\ If you wish to treat these as `Boolean`, you can use the `CBool()` function, e.g. `#If Not CBool(Win64) Then`. # Appearance diff --git a/docs/Reference/Controls.md b/docs/Reference/Controls.md index 6d17b65..dce3edb 100644 --- a/docs/Reference/Controls.md +++ b/docs/Reference/Controls.md @@ -36,7 +36,7 @@ These classes are *containers* rather than controls in the strict sense — they ## File-system browsing -These three controls are normally wired up together to build a complete file picker. +These three controls are normally connected together to build a complete file picker. - DriveListBox — drive picker. *Not yet documented.* - [DirListBox](Packages/VB/DirListBox/) — directory-tree picker for a single path. @@ -54,7 +54,7 @@ These three controls are normally wired up together to build a complete file pic - [Image](Packages/VB/Image/) — windowless lightweight picture display; the small, efficient alternative to [PictureBox](Packages/VB/PictureBox/). - [Line](Packages/VB/Line/) — windowless single straight line between two endpoints. - [Shape](Packages/VB/Shape/) — windowless geometric primitive (rectangle, oval, circle, star, arrow, …) with configurable border, fill, and rotation. -- [QRCode](Packages/VB/QRCode/) — windowless QR-code renderer driven by a text or byte-array payload. +- [QRCode](Packages/VB/QRCode/) — windowless QR-code renderer populated from a text or byte-array payload. ## Menus diff --git a/docs/Reference/Core/Comparison-Operators.md b/docs/Reference/Core/Comparison-Operators.md index a5f3e88..96ac9bc 100644 --- a/docs/Reference/Core/Comparison-Operators.md +++ b/docs/Reference/Core/Comparison-Operators.md @@ -49,7 +49,7 @@ The following table lists the comparison operators and the conditions that deter 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. -When comparing two expressions, you may not be able to easily determine whether the expressions are being compared as numbers or as strings. The following table shows how the expressions are compared, or the result when either expression is not a **Variant**: +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**: | If | Then | |:-----------------------------------------------------------------------------------------|:------------------------------------------------------| diff --git a/docs/Reference/Core/Delegate.md b/docs/Reference/Core/Delegate.md index 01880c9..e99ec28 100644 --- a/docs/Reference/Core/Delegate.md +++ b/docs/Reference/Core/Delegate.md @@ -9,7 +9,7 @@ permalink: /tB/Core/Delegate Declares a function-pointer type — a named signature that variables, parameters, and UDT members can hold a *reference* to a callable matching. A delegate value is bit-compatible with **LongPtr**, but adds compile-time signature checking when it is assigned, passed, or called. > [!NOTE] -> The **Delegate** statement is a twinBASIC extension. In classic VBA, function pointers are untyped **LongPtr** values produced by **AddressOf** and called indirectly through hand-rolled mechanisms (`DispCallFunc`, `CallWindowProc` shims, etc.). +> The **Delegate** statement is a twinBASIC extension. In classic VBA, function pointers are untyped **LongPtr** values produced by **AddressOf** and called indirectly through custom mechanisms (`DispCallFunc`, `CallWindowProc` shims, etc.). Syntax: > [ **Public** \| **Private** ] **Delegate Function** *name* [ **CDecl** ] **(** [ *arglist* ] **)** **As** *type* diff --git a/docs/Reference/Core/Handles.md b/docs/Reference/Core/Handles.md index 8a1d3cc..b0d09a4 100644 --- a/docs/Reference/Core/Handles.md +++ b/docs/Reference/Core/Handles.md @@ -9,7 +9,7 @@ permalink: /tB/Core/Handles A trailing clause on a procedure header that binds the procedure as an event handler for one or more specific events. > [!NOTE] -> The **Handles** clause is a twinBASIC extension. Classic VBA wires up event handlers solely by name: a `Sub` called `Form_Load` automatically handles the `Load` event of `Form`. twinBASIC still supports that pattern — **Handles** decouples the procedure name from the events it handles and lets one body handle several events at once. Whether the IDE inserts the new syntax when auto-generating event prototypes is controlled by the "IDE: Use new handles/implements syntax" option. +> The **Handles** clause is a twinBASIC extension. Classic VBA connects event handlers solely by name: a `Sub` called `Form_Load` automatically handles the `Load` event of `Form`. twinBASIC still supports that pattern — **Handles** decouples the procedure name from the events it handles and lets one body handle several events at once. Whether the IDE inserts the new syntax when auto-generating event prototypes is controlled by the "IDE: Use new handles/implements syntax" option. Syntax: > *procedure-header* **Handles** *object*.*event* [ **,** *object*.*event* ] … diff --git a/docs/Reference/Core/New.md b/docs/Reference/Core/New.md index 0abd6c8..2de23f4 100644 --- a/docs/Reference/Core/New.md +++ b/docs/Reference/Core/New.md @@ -30,7 +30,7 @@ When **New** is used in a declaration, no instance is created at the point of de When **New** is used with **Set**, an instance is created immediately, and the reference is assigned to *objectvar*. If *objectvar* previously held a reference to another object, that reference is released when the new one is assigned. > [!NOTE] -> **New** cannot be used together with **WithEvents** in a declaration. To wire up an event-aware object reference, declare the variable with **WithEvents** and assign it later with **Set**. +> **New** cannot be used together with **WithEvents** in a declaration. To connect an event-aware object reference, declare the variable with **WithEvents** and assign it later with **Set**. ### Example diff --git a/docs/Reference/Core/Open.md b/docs/Reference/Core/Open.md index dc9163c..69481ea 100644 --- a/docs/Reference/Core/Open.md +++ b/docs/Reference/Core/Open.md @@ -107,7 +107,7 @@ Close #1 ### Text Encodings -These identifier strings are accepted as the **Encoding** argument. The constants listed below name the well-known encodings; other system-supported encodings with similar identifier strings are also accepted at runtime. All members are marked **[Hidden, Restricted]** — they are omitted from general IntelliSense, but the IDE surfaces them automatically after the **Encoding** keyword. +These identifier strings are accepted as the **Encoding** argument. The constants listed below name the well-known encodings; other system-supported encodings with similar identifier strings are also accepted at runtime. All members are marked **[Hidden, Restricted]** — they are omitted from general IntelliSense, but the IDE shows them automatically after the **Encoding** keyword. #### Default and Unicode diff --git a/docs/Reference/Core/Type.md b/docs/Reference/Core/Type.md index 912fa62..7d06678 100644 --- a/docs/Reference/Core/Type.md +++ b/docs/Reference/Core/Type.md @@ -92,11 +92,11 @@ End Sub ### twinBASIC enhancements -twinBASIC extends classic VBA's **Type** in several ways. UDTs remain stack-allocated structs that can be passed to Win32 APIs, but they can also carry behaviour like a lightweight class. +twinBASIC extends classic VBA's **Type** in several ways. UDTs remain stack-allocated structs that can be passed to Win32 APIs, but they can also have behaviour like a lightweight class. **Member procedures.** [**Sub**](Sub), [**Function**](Function), and [**Property**](Property) procedures may appear inside `Type ... End Type`, and are called through any variable of the type. Inside a member procedure, other members of the same UDT must be accessed with the explicit `Me.` prefix. -**Lifecycle and operator hooks.** Well-known member names are wired up by the compiler: +**Lifecycle and operator hooks.** Well-known member names are connected by the compiler: | Member | Purpose | |:---|:---| diff --git a/docs/Reference/CustomControls/Enumerations/ColorRGBA.md b/docs/Reference/CustomControls/Enumerations/ColorRGBA.md index 061824e..7a8c057 100644 --- a/docs/Reference/CustomControls/Enumerations/ColorRGBA.md +++ b/docs/Reference/CustomControls/Enumerations/ColorRGBA.md @@ -8,9 +8,9 @@ permalink: /tB/Packages/CustomControls/Enumerations/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 carries 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. +> **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. Carried by [**FillColorPoint.Color**](../Styles/Fill#color) and by the **RGBA** parameter of [**FillColorPoints.SetSolidColorRGBA**](../Styles/Fill#setsolidcolorrgba) / [**Borders.SetSimpleBorderRGBA**](../Styles/Borders#setsimpleborderrgba). +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**. diff --git a/docs/Reference/CustomControls/Enumerations/Customtate.md b/docs/Reference/CustomControls/Enumerations/Customtate.md index 9e77cfc..9bf64f2 100644 --- a/docs/Reference/CustomControls/Enumerations/Customtate.md +++ b/docs/Reference/CustomControls/Enumerations/Customtate.md @@ -8,7 +8,7 @@ permalink: /tB/Packages/CustomControls/Enumerations/Customtate {: .no_toc } > [!NOTE] -> The name **Customtate** appears to be a typo for "CustomState" preserved from an early draft of the package. The enum is not referenced by any of the eight concrete `Waynes…` controls; the actual minimized / normal / maximized state of a [**WaynesForm**](../WaynesForm/) is driven by the parallel [**WindowState**](WindowState) enum, which carries identical members. Treat **Customtate** as reserved. +> The name **Customtate** appears to be a typo for "CustomState" preserved from an early draft of the package. The enum is not referenced by any of the eight concrete `Waynes…` controls; the actual minimized / normal / maximized state of a [**WaynesForm**](../WaynesForm/) is controlled by the parallel [**WindowState**](WindowState) enum, which has identical members. Treat **Customtate** as reserved. A reserved enumeration with the same three members as [**WindowState**](WindowState). Defined in `Module Constants` of the **CustomControls DESIGNER** library, exported as **Public**, but otherwise unused inside the package. diff --git a/docs/Reference/CustomControls/Enumerations/DockMode.md b/docs/Reference/CustomControls/Enumerations/DockMode.md index b35f237..2dd52c8 100644 --- a/docs/Reference/CustomControls/Enumerations/DockMode.md +++ b/docs/Reference/CustomControls/Enumerations/DockMode.md @@ -7,25 +7,25 @@ permalink: /tB/Packages/CustomControls/Enumerations/DockMode # DockMode {: .no_toc } -How a control is positioned relative to its container — pinned 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)). Carried by the **Dock** property that every concrete custom control inherits. | Constant | Value | Description | |----------|-------|-------------| | **tbDockNone**{: #tbDockNone } | 0 | Not docked. The control's **Left**, **Top**, **Width**, and **Height** are used directly, modulated by the control's [**Anchors**](../Styles/Anchors) when the container resizes. | -| **tbDockLeft**{: #tbDockLeft } | 1 | Pinned to the container's left edge. Width is preserved; height is stretched to the container's client area. | -| **tbDockTop**{: #tbDockTop } | 2 | Pinned to the container's top edge. Height is preserved; width is stretched. | -| **tbDockRight**{: #tbDockRight } | 3 | Pinned to the container's right edge. Width is preserved; height is stretched. | -| **tbDockBottom**{: #tbDockBottom } | 4 | Pinned to the container's bottom edge. Height is preserved; width is stretched. | +| **tbDockLeft**{: #tbDockLeft } | 1 | Attached to the container's left edge. Width is preserved; height is stretched to the container's client area. | +| **tbDockTop**{: #tbDockTop } | 2 | Attached to the container's top edge. Height is preserved; width is stretched. | +| **tbDockRight**{: #tbDockRight } | 3 | Attached to the container's right edge. Width is preserved; height is stretched. | +| **tbDockBottom**{: #tbDockBottom } | 4 | Attached to the container's bottom edge. Height is preserved; width is stretched. | | **tbDockFill**{: #tbDockFill } | 5 | Fills the entire remaining client area, after other docked siblings have claimed their edges. | Order matters when more than one sibling is docked inside the same container: each docked control claims its edge from whatever client area remains *after* its earlier-added siblings have claimed theirs. The control with **Dock = tbDockFill** is therefore added last so that it inherits the residual space: ```tb Private Sub Form_Load() - lblHeader.Dock = tbDockTop ' pinned to the top, full width - lblStatus.Dock = tbDockBottom ' pinned to the bottom, full width - pnlTree.Dock = tbDockLeft ' pinned to the left, between header and status - pnlAside.Dock = tbDockRight ' pinned to the right, between header and status + lblHeader.Dock = tbDockTop ' attached to the top, full width + lblStatus.Dock = tbDockBottom ' attached to the bottom, full width + pnlTree.Dock = tbDockLeft ' attached to the left, between header and status + pnlAside.Dock = tbDockRight ' attached to the right, between header and status pnlMain.Dock = tbDockFill ' fills whatever is left in the middle End Sub ``` diff --git a/docs/Reference/CustomControls/Enumerations/PixelCount.md b/docs/Reference/CustomControls/Enumerations/PixelCount.md index fafa96b..6f620f2 100644 --- a/docs/Reference/CustomControls/Enumerations/PixelCount.md +++ b/docs/Reference/CustomControls/Enumerations/PixelCount.md @@ -8,7 +8,7 @@ permalink: /tB/Packages/CustomControls/Enumerations/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 carries 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. +> **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. diff --git a/docs/Reference/CustomControls/Enumerations/PointSize.md b/docs/Reference/CustomControls/Enumerations/PointSize.md index c8bfe0c..db8e156 100644 --- a/docs/Reference/CustomControls/Enumerations/PointSize.md +++ b/docs/Reference/CustomControls/Enumerations/PointSize.md @@ -8,6 +8,6 @@ permalink: /tB/Packages/CustomControls/Enumerations/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 carries 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. +> **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. diff --git a/docs/Reference/CustomControls/Framework/Canvas.md b/docs/Reference/CustomControls/Framework/Canvas.md index 2353888..7bcd1a5 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 carrying 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 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. ```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 5afa1c9..16c8dec 100644 --- a/docs/Reference/CustomControls/Framework/CustomControlContext.md +++ b/docs/Reference/CustomControls/Framework/CustomControlContext.md @@ -11,7 +11,7 @@ has_toc: false 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. -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 surface with **Show** and **Close**. +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**. ```tb Private Sub OnInitialize(ByVal Ctx As CustomControls.CustomControlContext) _ @@ -32,7 +32,7 @@ End Sub ### ChangeFocusedElement {: .no_toc } -Asks the framework to move the keyboard focus to a particular `ElementTabIndex` value, as if the user had pressed **TAB** until it landed there. Used by [**WaynesGrid**](../WaynesGrid/) when a cell is selected programmatically — the grid changes its **SelectedCellX** / **SelectedCellY** and then calls this method so that the form-level focus tracking matches. +Asks the framework to move the keyboard focus to a particular `ElementTabIndex` value, as if the user had pressed **TAB** until reaching that point. Used by [**WaynesGrid**](../WaynesGrid/) when a cell is selected programmatically — the grid changes its **SelectedCellX** / **SelectedCellY** and then calls this method so that the form-level focus tracking matches. Syntax: *object*.**ChangeFocusedElement** *ElementTabIndex* @@ -51,7 +51,7 @@ The framework returns the timer typed as **stdole.IUnknown**; cast with `CType(O ### GetSerializer {: .no_toc } -Returns the [**SerializeInfo**](SerializeInfo) handle for this control instance. The serializer surfaces the deserialization entry point and the run-time / design-time mode flags. +Returns the [**SerializeInfo**](SerializeInfo) handle for this control instance. The serializer exposes the deserialization entry point and the run-time / design-time mode flags. Syntax: *object*.**GetSerializer** ( ) **As SerializeInfo** diff --git a/docs/Reference/CustomControls/Framework/CustomControlsCollection.md b/docs/Reference/CustomControls/Framework/CustomControlsCollection.md index 371ad4e..891f864 100644 --- a/docs/Reference/CustomControls/Framework/CustomControlsCollection.md +++ b/docs/Reference/CustomControls/Framework/CustomControlsCollection.md @@ -78,4 +78,4 @@ For Each ctl In MyForm.Controls Next ``` -The hidden member that drives this is `_NewEnum`; application code does not call it directly. +The hidden member that powers this is `_NewEnum`; application code does not call it directly. diff --git a/docs/Reference/CustomControls/Framework/CustomFormContext.md b/docs/Reference/CustomControls/Framework/CustomFormContext.md index d9952aa..21a09d0 100644 --- a/docs/Reference/CustomControls/Framework/CustomFormContext.md +++ b/docs/Reference/CustomControls/Framework/CustomFormContext.md @@ -23,7 +23,7 @@ End Sub ## Inherited -A **CustomFormContext** carries every member from [**CustomControlContext**](CustomControlContext) — [**ChangeFocusedElement**](CustomControlContext#changefocusedelement), [**CreateTimer**](CustomControlContext#createtimer), [**GetSerializer**](CustomControlContext#getserializer), and [**Repaint**](CustomControlContext#repaint) — and adds the two form-specific members below. +A **CustomFormContext** includes every member from [**CustomControlContext**](CustomControlContext) — [**ChangeFocusedElement**](CustomControlContext#changefocusedelement), [**CreateTimer**](CustomControlContext#createtimer), [**GetSerializer**](CustomControlContext#getserializer), and [**Repaint**](CustomControlContext#repaint) — and adds the two form-specific members below. ## Methods diff --git a/docs/Reference/CustomControls/Framework/ICustomControl.md b/docs/Reference/CustomControls/Framework/ICustomControl.md index d2fb56c..143c573 100644 --- a/docs/Reference/CustomControls/Framework/ICustomControl.md +++ b/docs/Reference/CustomControls/Framework/ICustomControl.md @@ -39,7 +39,7 @@ End Class ### Destroy {: .no_toc } -Called once when the control is being released. The implementation should drop any references it holds to objects that themselves hold references back to it, so that the reference graph can collapse cleanly. +Called once when the control is being released. The implementation should drop any references it holds to objects that themselves hold references back to it, so that the reference graph can collapse without cycles. Syntax: *object*.**Destroy** ( ) @@ -65,6 +65,6 @@ Syntax: *object*.**Paint** ( *Canvas* ) *Canvas* : *required* The [**Canvas**](Canvas) drawing surface for this paint pass. Its **RuntimeUICCGetWidth**, **RuntimeUICCGetHeight**, and **RuntimeUICCGetDpiScaleFactor** methods supply the size and DPI of the area being painted, in device pixels. -A descriptor may carry 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 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. diff --git a/docs/Reference/CustomControls/Framework/index.md b/docs/Reference/CustomControls/Framework/index.md index a215ecf..b0d2bf2 100644 --- a/docs/Reference/CustomControls/Framework/index.md +++ b/docs/Reference/CustomControls/Framework/index.md @@ -7,7 +7,7 @@ has_toc: false # Framework -The framework half of the [**CustomControls**](..) package — the interfaces, callback objects, and drawing primitives an *author* of a custom control writes against. The eight concrete `Waynes…` controls in the package are themselves built on this surface; the same pieces are available to user code that needs to implement an entirely new custom control. +The framework half of the [**CustomControls**](..) package — the interfaces, callback objects, and drawing primitives an *author* of a custom control writes against. The eight concrete `Waynes…` controls in the package are themselves built on this framework; the same pieces are available to user code that needs to implement an entirely new custom control. A custom control: diff --git a/docs/Reference/CustomControls/Styles/Anchors.md b/docs/Reference/CustomControls/Styles/Anchors.md index 7eb6ef3..973bc47 100644 --- a/docs/Reference/CustomControls/Styles/Anchors.md +++ b/docs/Reference/CustomControls/Styles/Anchors.md @@ -9,7 +9,7 @@ has_toc: false # Anchors class {: .no_toc } -Determines which sides of a control are pinned to its parent container when the container is resized. A control with both **Left** and **Right** set to **True**, for example, keeps its left and right edges at the same distance from the container's edges, stretching horizontally as the container grows. Controls receive this object through their inherited **Anchors** property. +Determines which sides of a control are attached to its parent container when the container is resized. A control with both **Left** and **Right** set to **True**, for example, keeps its left and right edges at the same distance from the container's edges, stretching horizontally as the container grows. Controls receive this object through their inherited **Anchors** property. The default is **Left**=**True**, **Top**=**True**, **Right**=**False**, **Bottom**=**False** — the control stays at the same offset from the upper-left corner of the container and does not resize. To make a control fill the bottom of its container as the form is resized, anchor it to **Left**, **Right**, and **Bottom**. diff --git a/docs/Reference/CustomControls/Styles/Borders.md b/docs/Reference/CustomControls/Styles/Borders.md index 0b8096d..1706090 100644 --- a/docs/Reference/CustomControls/Styles/Borders.md +++ b/docs/Reference/CustomControls/Styles/Borders.md @@ -33,7 +33,7 @@ elems(2).Fill.ColorPoints.SetSolidColor &H4D7AB4 ' deeper blue btnGo.NormalState.Borders.Elements = elems ``` -A single [**Border**](#border-class) can also carry a gradient instead of a solid colour — assign a multi-stop [**Fill**](Fill) to its [**Fill**](#fill) member. Set [**BlendWithBackgroundFill**](#blendwithbackgroundfill) to **True** on a translucent border to make it tint with the control's own **BackgroundFill** rather than with whatever lies under the control. +A single [**Border**](#border-class) can also display a gradient instead of a solid colour — assign a multi-stop [**Fill**](Fill) to its [**Fill**](#fill) member. Set [**BlendWithBackgroundFill**](#blendwithbackgroundfill) to **True** on a translucent border to make it tint with the control's own **BackgroundFill** rather than with whatever lies under the control. * TOC {:toc} @@ -87,7 +87,7 @@ A single border stroke. Elements of [**Borders.Elements**](#elements), and also ### BlendWithBackgroundFill {: .no_toc } -When **True**, the border's colour alpha-blends with the control's **BackgroundFill** rather than with whatever is painted underneath the control. Lets a translucent border colour pick up the background tint instead of the form's. **Boolean**. Default: **False**. +When **True**, the border's colour alpha-blends with the control's **BackgroundFill** rather than with whatever is painted underneath the control. Lets a translucent border colour use the background tint instead of the form's. **Boolean**. Default: **False**. ### Fill {: .no_toc } diff --git a/docs/Reference/CustomControls/Styles/Fill.md b/docs/Reference/CustomControls/Styles/Fill.md index 91eb4f1..4c7343d 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 drive 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. Reached as [**Fill.ColorPoints**](#colorpoints). Internally an array of **FillColorPoint** plus a [**Granularity**](#granularity) integer. ### Granularity {: .no_toc } diff --git a/docs/Reference/CustomControls/Styles/Padding.md b/docs/Reference/CustomControls/Styles/Padding.md index a4d89f9..4131c23 100644 --- a/docs/Reference/CustomControls/Styles/Padding.md +++ b/docs/Reference/CustomControls/Styles/Padding.md @@ -45,4 +45,4 @@ Padding inserted at the top edge, in pixels. [**PixelCount**](../Enumerations/Pi ### OnChanged {: .no_toc } -Raised whenever any of the four padding values is assigned. The containing [**TextRendering**](TextRendering) re-raises its own **OnChanged** in response, which in turn drives a repaint on the hosting control. +Raised whenever any of the four padding values is assigned. The containing [**TextRendering**](TextRendering) re-raises its own **OnChanged** in response, which in turn triggers a repaint on the hosting control. diff --git a/docs/Reference/CustomControls/Styles/TextRendering.md b/docs/Reference/CustomControls/Styles/TextRendering.md index 4b7fff4..8c7d3c3 100644 --- a/docs/Reference/CustomControls/Styles/TextRendering.md +++ b/docs/Reference/CustomControls/Styles/TextRendering.md @@ -85,7 +85,7 @@ Raised when [**Alignment**](#alignment) or [**OverflowMode**](#overflowmode) is ## FontStyle class -The font metrics that drive how [**TextRendering**](#) lays out text. Reached as [**TextRendering.Font**](#font). +The font metrics that control how [**TextRendering**](#) lays out text. Reached as [**TextRendering.Font**](#font). ### Italic {: .no_toc } diff --git a/docs/Reference/CustomControls/Styles/index.md b/docs/Reference/CustomControls/Styles/index.md index b313f85..771fb01 100644 --- a/docs/Reference/CustomControls/Styles/index.md +++ b/docs/Reference/CustomControls/Styles/index.md @@ -7,18 +7,18 @@ has_toc: false # Styles -The shared appearance helper classes used by the [**CustomControls**](..) package's concrete `Waynes…` controls. Each is a small container of related visual settings — a [**Fill**](Fill) is a colour or gradient, a [**Borders**](Borders) is an array of border strokes, a [**Corners**](Corners) is the shape and radius of each corner, and so on. Controls compose them through `Public WithEvents …` properties: a [**WaynesButton**](../WaynesButton/) holds four [**WaynesButtonState**](../WaynesButton/WaynesButtonState) sub-objects (Normal / Hover / Focused / Pressed), each of which carries its own [**BackgroundFill**](../WaynesButton/WaynesButtonState#backgroundfill), [**Borders**](../WaynesButton/WaynesButtonState#borders), [**Corners**](../WaynesButton/WaynesButtonState#corners), and [**TextRendering**](../WaynesButton/WaynesButtonState#textrendering). +The shared appearance helper classes used by the [**CustomControls**](..) package's concrete `Waynes…` controls. Each is a small container of related visual settings — a [**Fill**](Fill) is a colour or gradient, a [**Borders**](Borders) is an array of border strokes, a [**Corners**](Corners) is the shape and radius of each corner, and so on. Controls compose them through `Public WithEvents …` properties: a [**WaynesButton**](../WaynesButton/) holds four [**WaynesButtonState**](../WaynesButton/WaynesButtonState) sub-objects (Normal / Hover / Focused / Pressed), each of which has its own [**BackgroundFill**](../WaynesButton/WaynesButtonState#backgroundfill), [**Borders**](../WaynesButton/WaynesButtonState#borders), [**Corners**](../WaynesButton/WaynesButtonState#corners), and [**TextRendering**](../WaynesButton/WaynesButtonState#textrendering). Every style object raises an **OnChanged** event whenever any of its public fields is assigned. The hosting control listens for that event on each of its sub-objects and asks the framework to repaint, so style changes made at runtime are reflected immediately. | Class | Role | |-------|------| -| [Anchors](Anchors) | which sides of a control are pinned to the container when it resizes | -| [Borders](Borders) | an array of border strokes drawn around a region; carries the per-stroke `Border` sub-object | -| [Corners](Corners) | the four corner shapes / radii of a region; carries the per-corner `Corner` sub-object | -| [Fill](Fill) | the colour or gradient that paints a region; carries the `FillColorPoint` and `FillColorPoints` sub-objects that hold the gradient stops | +| [Anchors](Anchors) | which sides of a control are attached to the container when it resizes | +| [Borders](Borders) | an array of border strokes drawn around a region; contains the per-stroke `Border` sub-object | +| [Corners](Corners) | the four corner shapes / radii of a region; contains the per-corner `Corner` sub-object | +| [Fill](Fill) | the colour or gradient that paints a region; contains the `FillColorPoint` and `FillColorPoints` sub-objects that hold the gradient stops | | [Line](Line) | a single grid- or resizer-line stroke; a thinner shape than a full border | | [Padding](Padding) | per-side padding around text inside a [**TextRendering**](TextRendering) | -| [TextRendering](TextRendering) | font, padding, fill, outlines, alignment, and overflow for text; carries the `FontStyle` sub-object that holds the font metrics | +| [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. diff --git a/docs/Reference/CustomControls/WaynesButton/WaynesButtonState.md b/docs/Reference/CustomControls/WaynesButton/WaynesButtonState.md index c85d17f..682939e 100644 --- a/docs/Reference/CustomControls/WaynesButton/WaynesButtonState.md +++ b/docs/Reference/CustomControls/WaynesButton/WaynesButtonState.md @@ -9,7 +9,7 @@ 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 carries 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 reachable 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. diff --git a/docs/Reference/CustomControls/WaynesButton/index.md b/docs/Reference/CustomControls/WaynesButton/index.md index 2922d0d..938781e 100644 --- a/docs/Reference/CustomControls/WaynesButton/index.md +++ b/docs/Reference/CustomControls/WaynesButton/index.md @@ -8,7 +8,7 @@ has_toc: false # WaynesButton class {: .no_toc } -An owner-drawn push-button. Renders a configurable rectangle (with optional gradient fill, borders, rounded / notched / cut-out corners) and a centred [**Caption**](#caption), in one of four visual states — normal, hovered, focused, or pressed — driven by four parallel [**WaynesButtonState**](WaynesButtonState) sub-objects. +An owner-drawn push-button. Renders a configurable rectangle (with optional gradient fill, borders, rounded / notched / cut-out corners) and a centred [**Caption**](#caption), in one of four visual states — normal, hovered, focused, or pressed — controlled by four parallel [**WaynesButtonState**](WaynesButtonState) sub-objects. The button raises a [**Click**](#click) event when clicked, plus the standard set of mouse, focus, and keyboard events. By default the four state objects are pre-set with a solid mid-blue ([**WAYNESCOLOR_BLUE**](#) — `&HAC7220`) background and 15-pixel curved corners. @@ -46,7 +46,7 @@ Each state is a [**WaynesButtonState**](WaynesButtonState) — a small bundle of ### Anchors {: .no_toc } -Which sides of the control are pinned to its container during resize. [**Anchors**](../Styles/Anchors). Inherited. +Which sides of the control are attached to its container during resize. [**Anchors**](../Styles/Anchors). Inherited. ### Caption {: .no_toc } @@ -88,7 +88,7 @@ The unique design-time name of the control on its parent form. **String**. Inher ### NormalState {: .no_toc } -The [**WaynesButtonState**](WaynesButtonState) used when the button is at rest — not hovered, not focused, not pressed. +The [**WaynesButtonState**](WaynesButtonState) used when the button is idle — not hovered, not focused, not pressed. ### PressedState {: .no_toc } diff --git a/docs/Reference/CustomControls/WaynesForm/index.md b/docs/Reference/CustomControls/WaynesForm/index.md index da97ee3..1eb9d7d 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 drives 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. Showing the form is done by calling [**Show**](#show); closing it by [**Close**](#close). ```tb Private Sub Form_Load() @@ -26,7 +26,7 @@ Private Sub Form_Load() End Sub ``` -[**BackgroundFill**](#backgroundfill) is an ordinary [**Fill**](../Styles/Fill), so the form can carry a gradient backdrop just as easily as a solid colour — this is what the package's `HelloWorld` sample form uses to give itself a soft top-to-bottom wash: +[**BackgroundFill**](#backgroundfill) is an ordinary [**Fill**](../Styles/Fill), so the form can display a gradient backdrop or a solid colour — this is what the package's `HelloWorld` sample form uses to give itself a soft top-to-bottom wash: ```tb Private Sub Form_Load() @@ -94,7 +94,7 @@ The form's width in pixels. [**PixelCount**](../Enumerations/PixelCount). Inheri ### WindowsOptions {: .no_toc } -The [**WindowsFormOptions**](WindowsFormOptions) that drives the Win32 frame — border style, window state, taskbar visibility, minimize / maximize buttons, system menu. +The [**WindowsFormOptions**](WindowsFormOptions) that controls the Win32 frame — border style, window state, taskbar visibility, minimize / maximize buttons, system menu. ## Methods diff --git a/docs/Reference/CustomControls/WaynesFrame.md b/docs/Reference/CustomControls/WaynesFrame.md index cd9eb87..5f5a717 100644 --- a/docs/Reference/CustomControls/WaynesFrame.md +++ b/docs/Reference/CustomControls/WaynesFrame.md @@ -8,9 +8,9 @@ has_toc: false # WaynesFrame class {: .no_toc } -A rectangular container control whose entire area is painted with a configurable [**BackgroundFill**](#backgroundfill). Used to group other controls on a [**WaynesForm**](WaynesForm/), with the same layout / sizing surface as any other custom control. +A rectangular container control whose entire area is painted with a configurable [**BackgroundFill**](#backgroundfill). Used to group other controls on a [**WaynesForm**](WaynesForm/), with the same layout / sizing members as any other custom control. -The default fill is a solid mid-grey ([**WAYNESCOLOR_GREY**](#) — `&H808080`); change it by reaching into the **Fill.ColorPoints** collection. +The default fill is a solid mid-grey ([**WAYNESCOLOR_GREY**](#) — `&H808080`); change it by accessing the **Fill.ColorPoints** collection. ```tb Private Sub Form_Load() @@ -25,7 +25,7 @@ Frames work well as containers for [**Dock**](Enumerations/DockMode)-positioned ### Anchors {: .no_toc } -Which sides of the control are pinned to its container during resize. [**Anchors**](Styles/Anchors). Inherited. +Which sides of the control are attached to its container during resize. [**Anchors**](Styles/Anchors). Inherited. ### BackgroundFill {: .no_toc } diff --git a/docs/Reference/CustomControls/WaynesGrid/CellRenderingOptions.md b/docs/Reference/CustomControls/WaynesGrid/CellRenderingOptions.md index 31ada6b..1606afa 100644 --- a/docs/Reference/CustomControls/WaynesGrid/CellRenderingOptions.md +++ b/docs/Reference/CustomControls/WaynesGrid/CellRenderingOptions.md @@ -9,7 +9,7 @@ has_toc: false # CellRenderingOptions class {: .no_toc } -A bundle of the style objects that describe one *category* of cell in a [**WaynesGrid**](.). Each grid carries six parallel instances — one for column headers, one for row headers, one for normal cells, one for the hovered cell, one for the selected cell, and one for cells inside a full-row or full-column multi-selection — and the grid picks the appropriate instance per cell at paint time. +A bundle of the style objects that describe one *category* of cell in a [**WaynesGrid**](.). Each grid has six parallel instances — one for column headers, one for row headers, one for normal cells, one for the hovered cell, one for the selected cell, and one for cells inside a full-row or full-column multi-selection — and the grid picks the appropriate instance per cell at paint time. ```tb With Grid1.SelectedCellOptions diff --git a/docs/Reference/CustomControls/WaynesGrid/index.md b/docs/Reference/CustomControls/WaynesGrid/index.md index c28957d..4790929 100644 --- a/docs/Reference/CustomControls/WaynesGrid/index.md +++ b/docs/Reference/CustomControls/WaynesGrid/index.md @@ -10,7 +10,7 @@ has_toc: false A tabular data display — a grid of cells with column headers and row headers, resizable columns, optional grid lines, hover and selection highlighting, vertical and horizontal scrolling via the mouse wheel, and full keyboard navigation. The number of rows is set by [**RowCount**](#rowcount); the cells themselves are filled in by handling the [**GetCellText**](#getcelltext) event, which fires once per visible cell as the grid paints. -The grid carries an array of [**Column**](Column) objects giving each column its [**Caption**](Column#caption) and [**Width**](Column#width). Five distinct [**CellRenderingOptions**](CellRenderingOptions) sub-objects drive the appearance of column headers, row headers, normal cells, the hovered cell, the selected cell, and full-column / full-row multi-selection. +The grid has an array of [**Column**](Column) objects giving each column its [**Caption**](Column#caption) and [**Width**](Column#width). Five distinct [**CellRenderingOptions**](CellRenderingOptions) sub-objects control the appearance of column headers, row headers, normal cells, the hovered cell, the selected cell, and full-column / full-row multi-selection. ```tb Private Sub Form_Load() @@ -64,7 +64,7 @@ End With The grid exposes three separate selection states, each tracked through its own pair of properties: -- A single hover-highlight cell — the cell currently under the mouse — driven by [**HoverCellOptions**](#hovercelloptions). Internal to the grid; not exposed as a property. +- A single hover-highlight cell — the cell currently under the mouse — controlled by [**HoverCellOptions**](#hovercelloptions). Internal to the grid; not exposed as a property. - A single selected cell, with coordinates in [**SelectedCellX**](#selectedcellx) and [**SelectedCellY**](#selectedcelly), drawn using [**SelectedCellOptions**](#selectedcelloptions). - A full-row or full-column multi-selection, indicated by clicking the row header or column header. [**SelectedFullColumnX**](#selectedfullcolumnx) and [**SelectedFullRowY**](#selectedfullrowy) hold the indices; the affected cells render with [**MultiSelectCellOptions**](#multiselectcelloptions). @@ -75,7 +75,7 @@ A value of `-1` on any of the selection-coordinate properties means "no selectio ### Anchors {: .no_toc } -Which sides of the control are pinned to its container during resize. [**Anchors**](../Styles/Anchors). Inherited. +Which sides of the control are attached to its container during resize. [**Anchors**](../Styles/Anchors). Inherited. ### CellOptions {: .no_toc } @@ -212,7 +212,7 @@ The control's width in pixels. [**PixelCount**](../Enumerations/PixelCount). Inh ### Repaint {: .no_toc } -Asks the framework to redraw the grid. Equivalent to calling [**CustomControlContext.Repaint**](../Framework/CustomControlContext#repaint) on the control's stored context; exposed as a public method on the grid so an external observer (e.g. the form, after updating the data behind the grid) can trigger a redraw without reaching into the framework. +Asks the framework to redraw the grid. Equivalent to calling [**CustomControlContext.Repaint**](../Framework/CustomControlContext#repaint) on the control's stored context; exposed as a public method on the grid so an external observer (e.g. the form, after updating the data behind the grid) can trigger a redraw without accessing the framework directly. Syntax: *object*.**Repaint** diff --git a/docs/Reference/CustomControls/WaynesLabel.md b/docs/Reference/CustomControls/WaynesLabel.md index 0f1802c..6468feb 100644 --- a/docs/Reference/CustomControls/WaynesLabel.md +++ b/docs/Reference/CustomControls/WaynesLabel.md @@ -43,7 +43,7 @@ Label1.BackgroundFill.SetSimplePattern &H014C99, &H99CCFF, _ ### Anchors {: .no_toc } -Which sides of the control are pinned to its container during resize. [**Anchors**](Styles/Anchors). Inherited. +Which sides of the control are attached to its container during resize. [**Anchors**](Styles/Anchors). Inherited. ### BackgroundFill {: .no_toc } diff --git a/docs/Reference/CustomControls/WaynesSlider/WaynesSliderState.md b/docs/Reference/CustomControls/WaynesSlider/WaynesSliderState.md index a0dea8e..679c3e0 100644 --- a/docs/Reference/CustomControls/WaynesSlider/WaynesSliderState.md +++ b/docs/Reference/CustomControls/WaynesSlider/WaynesSliderState.md @@ -11,7 +11,7 @@ has_toc: false A bundle of the style objects that describe a single visual state of a [**WaynesSlider**](.). Each slider holds three parallel instances ([**NormalState**](.#normalstate), [**HoverState**](.#hoverstate), [**FocusedState**](.#focusedstate)); the slider picks one at each repaint depending on the mouse / focus state. -The state has two halves — the *background* (the full track behind the block) and the *block* (the draggable rectangle that indicates [**Value**](.#value)). Each half has its own [**Fill**](../Styles/Fill), [**Borders**](../Styles/Borders), and [**Corners**](../Styles/Corners). A [**TextRendering**](../Styles/TextRendering) on the state drives how the optional [**DisplayFormat**](.#displayformat) text is drawn on the block. +The state has two halves — the *background* (the full track behind the block) and the *block* (the draggable rectangle that indicates [**Value**](.#value)). Each half has its own [**Fill**](../Styles/Fill), [**Borders**](../Styles/Borders), and [**Corners**](../Styles/Corners). A [**TextRendering**](../Styles/TextRendering) on the state controls how the optional [**DisplayFormat**](.#displayformat) text is drawn on 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. diff --git a/docs/Reference/CustomControls/WaynesSlider/index.md b/docs/Reference/CustomControls/WaynesSlider/index.md index 42aff71..06fd07a 100644 --- a/docs/Reference/CustomControls/WaynesSlider/index.md +++ b/docs/Reference/CustomControls/WaynesSlider/index.md @@ -10,7 +10,7 @@ has_toc: false A horizontal or vertical slider control — a draggable block over a track — for editing an integer value within a range. The user can drag the block, click on the track to step the value by one page, or use the arrow keys when the control has focus; an optional auto-increment timer activates while a mouse button is held down on the track. -The control paints three visual states ([**NormalState**](#normalstate), [**HoverState**](#hoverstate), [**FocusedState**](#focusedstate)) driven by parallel [**WaynesSliderState**](WaynesSliderState) sub-objects, each of which carries independent fill / border / corner styling for the background and for the block. The current [**Value**](#value) is optionally rendered as text on the block — as a raw integer or as a formatted percentage — depending on [**DisplayFormat**](#displayformat). +The control paints three visual states ([**NormalState**](#normalstate), [**HoverState**](#hoverstate), [**FocusedState**](#focusedstate)) controlled by parallel [**WaynesSliderState**](WaynesSliderState) sub-objects, each of which has independent fill / border / corner styling for the background and for the block. The current [**Value**](#value) is optionally rendered as text on the block — as a raw integer or as a formatted percentage — depending on [**DisplayFormat**](#displayformat). If the control's [**Height**](#height) is greater than its [**Width**](#width) on first display, the slider defaults to [**Direction**](#direction) = **Vertical**; otherwise it defaults to **Horizontal**. @@ -71,7 +71,7 @@ How the [**Value**](#value) is rendered on the block, declared inside the **Wayn ### Anchors {: .no_toc } -Which sides of the control are pinned to its container during resize. [**Anchors**](../Styles/Anchors). Inherited. +Which sides of the control are attached to its container during resize. [**Anchors**](../Styles/Anchors). Inherited. ### Direction {: .no_toc } @@ -131,7 +131,7 @@ The unique design-time name of the control on its parent form. **String**. Inher ### NormalState {: .no_toc } -The [**WaynesSliderState**](WaynesSliderState) used when the slider is at rest — not hovered, not focused. +The [**WaynesSliderState**](WaynesSliderState) used when the slider is idle — not hovered, not focused. ### PagingStepValue {: .no_toc } diff --git a/docs/Reference/CustomControls/WaynesTextBox/WaynesTextBoxState.md b/docs/Reference/CustomControls/WaynesTextBox/WaynesTextBoxState.md index 122eac7..0a7ecad 100644 --- a/docs/Reference/CustomControls/WaynesTextBox/WaynesTextBoxState.md +++ b/docs/Reference/CustomControls/WaynesTextBox/WaynesTextBoxState.md @@ -11,9 +11,9 @@ has_toc: false A bundle of the style objects that describe a single visual state of a [**WaynesTextBox**](.). Each textbox holds three parallel instances ([**NormalState**](.#normalstate), [**HoverState**](.#hoverstate), [**FocusedState**](.#focusedstate)); the textbox picks one at each repaint depending on the focus / hover state. -In addition to the usual background / borders / corners / text-rendering quartet, a **WaynesTextBoxState** carries selection-highlight colours, a caret colour and width, and three decorator fills used for the *ERROR* / *WARNING* / *INFO* literal-substring decorations the textbox draws automatically. +In addition to the usual background / borders / corners / text-rendering quartet, a **WaynesTextBoxState** adds selection-highlight colours, a caret colour and width, and three decorator fills used for the *ERROR* / *WARNING* / *INFO* literal-substring decorations the textbox draws automatically. -[**InitializeDefaultValues**](#initializedefaultvalues) and [**InitializeDefaultValues_Focused**](#initializedefaultvalues_focused) populate the state with sensible defaults — the focused variant uses a different selection background and caret colour. +[**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. diff --git a/docs/Reference/CustomControls/WaynesTextBox/index.md b/docs/Reference/CustomControls/WaynesTextBox/index.md index 57a94f7..3e513b0 100644 --- a/docs/Reference/CustomControls/WaynesTextBox/index.md +++ b/docs/Reference/CustomControls/WaynesTextBox/index.md @@ -10,9 +10,9 @@ has_toc: false A single-line editable text field. The user can type, select with the mouse or with shift-modified cursor keys, jump word-by-word with **Ctrl+Left** / **Ctrl+Right**, double-click to select a word, and copy / cut / paste / select-all with the standard Windows shortcuts. The control draws its own caret, selection highlight, and inline text decorators (squiggle for *ERROR*, underline for *WARNING*, background highlight for *INFO*) on top of the configurable background. -The control paints three visual states ([**NormalState**](#normalstate), [**HoverState**](#hoverstate), [**FocusedState**](#focusedstate)) driven by parallel [**WaynesTextBoxState**](WaynesTextBoxState) sub-objects, each of which carries its own background fill, borders, corners, text rendering, selection colours, caret colour, and decorator colours. +The control paints three visual states ([**NormalState**](#normalstate), [**HoverState**](#hoverstate), [**FocusedState**](#focusedstate)) controlled by parallel [**WaynesTextBoxState**](WaynesTextBoxState) sub-objects, each of which has its own background fill, borders, corners, text rendering, selection colours, caret colour, and decorator colours. -The current text is held in [**Value**](#value). Surrogate-pair characters are handled correctly by the cursor / selection logic — the caret never lands between the high and low halves of a pair. +The current text is held in [**Value**](#value). Surrogate-pair characters are handled correctly by the cursor / selection logic — the caret never appears between the high and low halves of a pair. ```tb Private Sub Form_Load() @@ -62,7 +62,7 @@ The colours are configurable per visual state. The substrings themselves are har ### Anchors {: .no_toc } -Which sides of the control are pinned to its container during resize. [**Anchors**](../Styles/Anchors). Inherited. +Which sides of the control are attached to its container during resize. [**Anchors**](../Styles/Anchors). Inherited. ### Dock {: .no_toc } @@ -97,7 +97,7 @@ The unique design-time name of the control on its parent form. **String**. Inher ### NormalState {: .no_toc } -The [**WaynesTextBoxState**](WaynesTextBoxState) used when the textbox is at rest — not focused and not hovered. +The [**WaynesTextBoxState**](WaynesTextBoxState) used when the textbox is idle — not focused and not hovered. ### TabIndex {: .no_toc } diff --git a/docs/Reference/CustomControls/WaynesTimer.md b/docs/Reference/CustomControls/WaynesTimer.md index 23e7039..ffaecd0 100644 --- a/docs/Reference/CustomControls/WaynesTimer.md +++ b/docs/Reference/CustomControls/WaynesTimer.md @@ -8,7 +8,7 @@ has_toc: false # WaynesTimer class {: .no_toc } -A non-visual timer control. Wraps an internal [**CustomControlTimer**](Framework/CustomControlTimer) and surfaces its [**Interval**](#interval) / [**Enabled**](#enabled) as designer-visible properties — drop a **WaynesTimer** onto a [**WaynesForm**](WaynesForm/) at design time, set the interval, and handle the [**Timer**](#timer) event to run code on a repeating schedule. +A non-visual timer control. Wraps an internal [**CustomControlTimer**](Framework/CustomControlTimer) and exposes its [**Interval**](#interval) / [**Enabled**](#enabled) as designer-visible properties — drop a **WaynesTimer** onto a [**WaynesForm**](WaynesForm/) at design time, set the interval, and handle the [**Timer**](#timer) event to run code on a repeating schedule. At design time the control paints a 🕑 clock-face glyph centred in its rectangle, on a pale grey background, scaled to fit the control. At run time the control is invisible — its visible **Width** and **Height** are clamped to 32×32 on initialize but the control itself draws nothing. @@ -28,7 +28,7 @@ End Sub ### Anchors {: .no_toc } -Which sides of the control are pinned to its container during resize. [**Anchors**](Styles/Anchors). Inherited. (Has no visual effect at run time since the control draws nothing then.) +Which sides of the control are attached to its container during resize. [**Anchors**](Styles/Anchors). Inherited. (Has no visual effect at run time since the control draws nothing then.) ### Dock {: .no_toc } diff --git a/docs/Reference/CustomControls/index.md b/docs/Reference/CustomControls/index.md index 97ccbae..9456ffc 100644 --- a/docs/Reference/CustomControls/index.md +++ b/docs/Reference/CustomControls/index.md @@ -31,7 +31,7 @@ End Sub ## Controls - [WaynesButton](WaynesButton/) -- owner-drawn push-button with separate visual states for normal, hover, focused, and pressed -- [WaynesForm](WaynesForm/) -- top-level form for hosting custom controls; carries the **WindowsOptions** sub-object that drives the Win32 frame +- [WaynesForm](WaynesForm/) -- top-level form for hosting custom controls; exposes the **WindowsOptions** sub-object that controls the Win32 frame - [WaynesFrame](WaynesFrame) -- rectangular container that fills its area with a configurable background - [WaynesGrid](WaynesGrid/) -- tabular data display with column headers, row headers, hover / selection states, and resizable columns - [WaynesLabel](WaynesLabel) -- static text display with fill, text rendering, and caption @@ -49,9 +49,9 @@ These members are listed on each control's own page; their definitions are ident ## Style objects -The visual style of every control is driven by a handful of small helper classes, instantiated automatically through `Public WithEvents …` properties. They are nested arbitrarily — a [**TextRendering**](Styles/TextRendering) contains a [**Fill**](Styles/Fill) for the text colour, which contains a `Granularity` and an array of `FillColorPoint` gradient stops; an array of [**Border**](Styles/Borders#border-class) objects describes how the outline of a control is stroked; and so on. +The visual style of every control is controlled by a few small helper classes, instantiated automatically through `Public WithEvents …` properties. They are nested arbitrarily — a [**TextRendering**](Styles/TextRendering) contains a [**Fill**](Styles/Fill) for the text colour, which contains a `Granularity` and an array of `FillColorPoint` gradient stops; an array of [**Border**](Styles/Borders#border-class) objects describes how the outline of a control is stroked; and so on. -- [Anchors](Styles/Anchors) -- which sides of a control are pinned to its container when the container is resized +- [Anchors](Styles/Anchors) -- which sides of a control are attached to its container when the container is resized - [Borders](Styles/Borders) -- one or more border strokes drawn around a control (including the single-stroke `Border` sub-object) - [Corners](Styles/Corners) -- the four corner shapes and radii of a control (including the per-corner `Corner` sub-object) - [Fill](Styles/Fill) -- the colour or gradient that paints a region (including the `FillColorPoint` / `FillColorPoints` gradient-stop sub-objects) @@ -69,7 +69,7 @@ For authoring your own custom controls or forms, the **CustomControls DESIGNER** - [ICustomForm](Framework/ICustomForm) -- the analogous interface for custom form classes - [CustomControlContext](Framework/CustomControlContext) -- callback object passed to **Initialize**; offers serializer access, repaint requests, timer creation, and focus changes - [CustomFormContext](Framework/CustomFormContext) -- a **CustomControlContext** extended with **Show** and **Close** for form-class controls -- [CustomControlTimer](Framework/CustomControlTimer) -- the timer returned by **CustomControlContext.CreateTimer**; carries **Interval**, **Enabled**, and an **OnTimer** event +- [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 diff --git a/docs/Reference/Glossary.md b/docs/Reference/Glossary.md index 2acc075..d34c90b 100644 --- a/docs/Reference/Glossary.md +++ b/docs/Reference/Glossary.md @@ -44,7 +44,7 @@ The American Standard Code for Information Interchange (ASCII) 7-bit character s ## attribute -(twinBASIC) Metadata attached to a [module](#module), procedure, parameter, or other declaration, written in square brackets — for example, `[Documentation("...")]`. Some attributes drive compiler behaviour (such as `[PackingAlignment]` on a [user-defined type](#user-defined-type) or `[VB_UserMemId]` on a member); others are informational. Attributes are a twinBASIC addition; classic VBA exposes only a small fixed set via the `Attribute` directive. +(twinBASIC) Metadata attached to a [module](#module), procedure, parameter, or other declaration, written in square brackets — for example, `[Documentation("...")]`. Some attributes control compiler behaviour (such as `[PackingAlignment]` on a [user-defined type](#user-defined-type) or `[VB_UserMemId]` on a member); others are informational. Attributes are a twinBASIC addition; classic VBA exposes only a small fixed set via the `Attribute` directive. ## Automation object @@ -412,7 +412,7 @@ A 4-byte integer ranging in value from -2,147,483,648 to 2,147,483,647. The ampe ## LongPtr data type -(twinBASIC) A platform-dependent integer used to hold pointer or handle values. **LongPtr** is 4 bytes on 32-bit platforms and 8 bytes on 64-bit platforms. Use **LongPtr** rather than **Long** or **LongLong** when declaring DLL parameters that carry pointers or handles, so that the same source compiles correctly on both platforms. +(twinBASIC) A platform-dependent integer used to hold pointer or handle values. **LongPtr** is 4 bytes on 32-bit platforms and 8 bytes on 64-bit platforms. Use **LongPtr** rather than **Long** or **LongLong** when declaring DLL parameters that hold pointers or handles, so that the same source compiles correctly on both platforms. ## MDI child diff --git a/docs/Reference/Packages.md b/docs/Reference/Packages.md index 4493f3b..9b2d264 100644 --- a/docs/Reference/Packages.md +++ b/docs/Reference/Packages.md @@ -28,6 +28,6 @@ These packages are built into twinBASIC and are always available, even offline. - [WebView2 Package](WebView2/) -- the **WebView2** control wrapping the Microsoft Edge runtime, plus its surrounding wrapper objects (request / response / headers / environment options) and the `wv2…` enumerations - [WinEventLogLib Package](WinEventLogLib/) -- writes Windows Event Log entries from twinBASIC; the generic **EventLog**(*Of EventIds, Categories*) class handles registration, registry setup, and the per-event `ReportEventW` call, with message-table resources for *EventIds* and *Categories* synthesised into the EXE at compile time - [WinNamedPipesLib Package](WinNamedPipesLib/) -- Windows named pipes as twinBASIC objects with an asynchronous IOCP-driven I/O model; **NamedPipeServer** + **NamedPipeServerConnection** on the host side, **NamedPipeClientManager** + **NamedPipeClientConnection** on the client side, with message-boundary semantics and a cookie-based correlation pattern across `AsyncRead` / `AsyncWrite` and their matching events -- [WinServicesLib Package](WinServicesLib/) -- runs a twinBASIC EXE as one or more Windows services; the **Services** singleton coordinates configuration, install / uninstall, and the SCM dispatcher loop, while user-implemented [**ITbService**](WinServicesLib/ITbService) classes are surfaced through [**ServiceCreator**](WinServicesLib/ServiceCreator)`(Of T)` +- [WinServicesLib Package](WinServicesLib/) -- runs a twinBASIC EXE as one or more Windows services; the **Services** singleton coordinates configuration, install / uninstall, and the SCM dispatcher loop, while user-implemented [**ITbService**](WinServicesLib/ITbService) classes are instantiated through [**ServiceCreator**](WinServicesLib/ServiceCreator)`(Of T)` - [tbIDE Package](tbIDE/) -- the **addin SDK** for the twinBASIC IDE: every addin is a Standard DLL that exports `tbCreateCompilerAddin`, returns an object implementing the [**AddIn**](tbIDE/AddIn) contract, and from there reaches the IDE's toolbar, tool-window DOM, virtual file system, debug console, current project (and its `Evaluate` debug-console hook), keyboard shortcuts, and themes — all through the [**Host**](tbIDE/Host) object the IDE passes in - [WinNativeCommonCtls Package](WinNativeCommonCtls/) -- VB6-compatible replacement for **Microsoft Common Controls 6.0** (`MSCOMCTL.OCX`) built on top of the Win32 ComCtl32 controls: eight controls ([**DTPicker**](WinNativeCommonCtls/DTPicker), [**ImageList**](WinNativeCommonCtls/ImageList/), [**ListView**](WinNativeCommonCtls/ListView/), [**MonthView**](WinNativeCommonCtls/MonthView), [**ProgressBar**](WinNativeCommonCtls/ProgressBar), [**Slider**](WinNativeCommonCtls/Slider), [**TreeView**](WinNativeCommonCtls/TreeView/), [**UpDown**](WinNativeCommonCtls/UpDown)) with the original member names preserved, plus the collection sub-objects ([**ListItems**](WinNativeCommonCtls/ListView/ListItems), [**ColumnHeaders**](WinNativeCommonCtls/ListView/ColumnHeaders), [**Nodes**](WinNativeCommonCtls/TreeView/Nodes), [**ListImages**](WinNativeCommonCtls/ImageList/ListImages)) and the user-facing enumerations diff --git a/docs/Reference/VB/App/index.md b/docs/Reference/VB/App/index.md index 2031233..cce1f1a 100644 --- a/docs/Reference/VB/App/index.md +++ b/docs/Reference/VB/App/index.md @@ -22,7 +22,7 @@ End If App.HelpFile = App.Path & "\help.chm" ``` -Most properties are read-only and are populated from the project settings (compiled into the executable's Win32 `VERSIONINFO` resource) at build time. The handful of read/write properties — [**Title**](#title) and [**HelpFile**](#helpfile) — let code change a small amount of run-time state that other parts of the runtime (notably the form caption defaults and the **F1** help dispatcher) consult. +Most properties are read-only and are populated from the project settings (compiled into the executable's Win32 `VERSIONINFO` resource) at build time. The few read/write properties — [**Title**](#title) and [**HelpFile**](#helpfile) — let code change a small amount of run-time state that other parts of the runtime (notably the form caption defaults and the **F1** help dispatcher) consult. * TOC {:toc} @@ -41,7 +41,7 @@ Most properties are read-only and are populated from the project settings (compi When the project is running inside the twinBASIC IDE — `App.IsInIDE` is **True** — [**Path**](#path) is the folder of the *project file* rather than of a compiled EXE, so it remains useful as a "where the application is" anchor for opening relative resources at design time. -[**LastBuildPath**](#lastbuildpath) is a twinBASIC-specific extension that records the path the most recent IDE build wrote its EXE to — handy for build scripts that need to chain steps after an IDE build. +[**LastBuildPath**](#lastbuildpath) is a twinBASIC-specific extension that records the path the most recent IDE build wrote its EXE to — useful for build scripts that need to chain steps after an IDE build. ## Version metadata @@ -200,7 +200,7 @@ The folder containing the executable, with no trailing backslash. **String**, re ### PrevInstance {: .no_toc } -**True** if another instance of the application is already running, **False** otherwise. **Boolean**, read-only. Typically tested at startup so the second instance can bring the first to the foreground or exit cleanly. +**True** if another instance of the application is already running, **False** otherwise. **Boolean**, read-only. Typically tested at startup so the second instance can bring the first to the foreground or exit gracefully. ### ProductName {: .no_toc } diff --git a/docs/Reference/VB/CheckMark/index.md b/docs/Reference/VB/CheckMark/index.md index 2690360..f10b748 100644 --- a/docs/Reference/VB/CheckMark/index.md +++ b/docs/Reference/VB/CheckMark/index.md @@ -46,7 +46,7 @@ Check1.Value = vbGrayed ' show the indeterminate state [**VisualStyles**](#visualstyles) selects how the glyph is rendered: - **VisualStyles = False** (default) — drawn with the GDI **DrawFrameControl** primitive. Honours [**Appearance**](#appearance): **vbAppear3d** uses the classic raised/sunken look, **vbAppearFlat** uses a single-pixel outline. A disabled check, or one in the **vbGrayed** state, is drawn over the dotted three-state pattern. -- **VisualStyles = True** — drawn through the OS theme engine (UXTHEME), so the glyph picks up the current visual-style theme. **Appearance** is ignored in this mode. +- **VisualStyles = True** — drawn through the OS theme engine (UXTHEME), so the glyph uses the current visual-style theme. **Appearance** is ignored in this mode. ## Background diff --git a/docs/Reference/VB/Clipboard/index.md b/docs/Reference/VB/Clipboard/index.md index bb0f00a..ba670ed 100644 --- a/docs/Reference/VB/Clipboard/index.md +++ b/docs/Reference/VB/Clipboard/index.md @@ -8,7 +8,7 @@ has_toc: false # Clipboard class {: .no_toc } -The **Clipboard** class wraps the system clipboard — the Win32 inter-application copy-and-paste surface — and exposes it as a singleton object. Code reads and writes text, queries which formats are currently available, and (eventually — see [the picture caveat](#picture-data)) reads and writes pictures. +The **Clipboard** class wraps the system clipboard — the Win32 inter-application copy-and-paste API — and exposes it as a singleton object. Code reads and writes text, queries which formats are currently available, and (eventually — see [the picture caveat](#picture-data)) reads and writes pictures. **Clipboard** is not creatable: there is exactly one instance per process, owned by the runtime and exposed through the [**Clipboard**](../Global/#clipboard) property on the [**Global**](../Global/) app-object. Code reaches it without qualification: @@ -43,11 +43,11 @@ Clipboard contents are tagged with a *format* — text, bitmap, files, rich text | **vbCFLink** | `&HFFFFBF00` | DDE link (legacy OLE-1 link source). | | **vbCFRTF** | `&HFFFFBF01` | Rich Text Format. | -The [**GetText**](#gettext) / [**SetText**](#settext) methods take an optional *Format* argument constrained to the text-shaped subset (**vbCFText**, **vbCFUnicodeText**, **vbCFRTF**, **vbCFLink**). The [**GetData**](#getdata) / [**SetData**](#setdata) methods carry pictures, restricted to the bitmap and metafile formats. +The [**GetText**](#gettext) / [**SetText**](#settext) methods take an optional *Format* argument constrained to the text-shaped subset (**vbCFText**, **vbCFUnicodeText**, **vbCFRTF**, **vbCFLink**). The [**GetData**](#getdata) / [**SetData**](#setdata) methods handle pictures, restricted to the bitmap and metafile formats. ## Picture data -The picture methods — [**GetData**](#getdata) and [**SetData**](#setdata) — are declared but not yet wired up. +The picture methods — [**GetData**](#getdata) and [**SetData**](#setdata) — are declared but not yet connected. > [!NOTE] > [**GetData**](#getdata) and [**SetData**](#setdata) are reserved for compatibility with VB6; they are not currently implemented in twinBASIC. For picture-clipboard interop, use the Win32 clipboard API (`OpenClipboard`, `GetClipboardData`, `SetClipboardData`, `CloseClipboard`) directly until the implementation lands. @@ -117,7 +117,7 @@ Places picture data onto the clipboard. Syntax: *object*.**SetData** *Picture* [, *Format* ] *Picture* -: *required* A **stdole.StdPicture** carrying the picture to copy. +: *required* A **stdole.StdPicture** holding the picture to copy. *Format* : *optional* A member of [**ClipboardConstants**](../../VBRUN/Constants/ClipboardConstants) — which picture format to publish. When omitted, the format is inferred from the picture's underlying type. diff --git a/docs/Reference/VB/Data/index.md b/docs/Reference/VB/Data/index.md index 6ad5c19..ad7f748 100644 --- a/docs/Reference/VB/Data/index.md +++ b/docs/Reference/VB/Data/index.md @@ -226,7 +226,7 @@ When **True**, the database is opened read-only and edits to bound fields are pr ### Recordset {: .no_toc } -The DAO recordset currently driving the bound controls. **Object** (a `DAO.Recordset` at run time). +The DAO recordset currently populating the bound controls. **Object** (a `DAO.Recordset` at run time). Syntax: *object*.**Recordset** [ = *recordset* ] @@ -394,7 +394,7 @@ Syntax: *object*\_**DragOver**( *Source* **As Control**, *X* **As Single**, *Y* {: .no_toc } > [!NOTE] -> Reserved for compatibility with VB6; not currently raised in twinBASIC. In VB6 this event is raised when an asynchronous DAO operation fails outside of a code path the application can intercept; it is not needed for synchronous errors that surface through normal `On Error` handling. +> Reserved for compatibility with VB6; not currently raised in twinBASIC. In VB6 this event is raised when an asynchronous DAO operation fails outside of a code path the application can intercept; it is not needed for synchronous errors that arise through normal `On Error` handling. Syntax: *object*\_**Error**( *DataErr* **As Integer**, *Response* **As Integer** ) diff --git a/docs/Reference/VB/DirListBox/index.md b/docs/Reference/VB/DirListBox/index.md index 9dd64cb..7c7078c 100644 --- a/docs/Reference/VB/DirListBox/index.md +++ b/docs/Reference/VB/DirListBox/index.md @@ -35,13 +35,13 @@ The control is built around three closely-related properties: - [**Path**](#path) — the absolute path of the *current* directory. Set it from code (or by double-clicking an entry) to navigate the list. Defaults to [**App.Path**](../App/#path) when the control is first created. - [**ListIndex**](#listindex) — which entry the user has *selected*. `-1` selects the current folder itself (the deepest of the ancestor entries); `0` and up select successive subdirectories. Selecting an entry is independent of navigating to it — the selection just moves the highlight. -- [**PathSelected**](#pathselected) — the absolute path that would become **Path** if the selected entry were activated. For an ancestor entry it walks back up the tree; for a subdirectory it concatenates **Path** and the entry's name. +- [**PathSelected**](#pathselected) — the absolute path that would become **Path** if the selected entry were activated. For an ancestor entry it traverses back up the tree; for a subdirectory it concatenates **Path** and the entry's name. Activating an entry — by double-clicking, or by an external caller assigning **Path** — runs the navigation, repopulates the list, and raises [**Change**](#change). Setting **Path** to its current value is a no-op (no event). ## List, ListCount, and NewIndex -[**ListCount**](#listcount) is the number of subdirectories of the current folder (it does *not* include the ancestor entries shown above). [**List**](#list) is indexed from zero through `ListCount - 1` and returns the *full path* of the corresponding subdirectory — handy when iterating from code: +[**ListCount**](#listcount) is the number of subdirectories of the current folder (it does *not* include the ancestor entries shown above). [**List**](#list) is indexed from zero through `ListCount - 1` and returns the *full path* of the corresponding subdirectory — convenient when iterating from code: ```tb Dim i As Long @@ -211,7 +211,7 @@ The **DriveListBox** and **DirListBox** controls accept each other's "drive [vol ### PathSelected {: .no_toc } -The absolute path that the currently-selected entry refers to. **String**, read-only. For [**ListIndex**](#listindex) `-1` (the current folder) this is the same as [**Path**](#path); for an ancestor entry it walks back up the tree; for a subdirectory it returns **Path** plus the subdirectory's name. This is the value the control assigns to **Path** when the user double-clicks the selected entry. +The absolute path that the currently-selected entry refers to. **String**, read-only. For [**ListIndex**](#listindex) `-1` (the current folder) this is the same as [**Path**](#path); for an ancestor entry it traverses back up the tree; for a subdirectory it returns **Path** plus the subdirectory's name. This is the value the control assigns to **Path** when the user double-clicks the selected entry. ### TabIndex {: .no_toc } diff --git a/docs/Reference/VB/Form/index.md b/docs/Reference/VB/Form/index.md index c8ed9df..6a375cd 100644 --- a/docs/Reference/VB/Form/index.md +++ b/docs/Reference/VB/Form/index.md @@ -65,7 +65,7 @@ dlgOptions.Show vbModal, Me ' modal, owned by the calling form [**MinWidth**](#minwidth), [**MinHeight**](#minheight), [**MaxWidth**](#maxwidth), and [**MaxHeight**](#maxheight) constrain the *client area* in twips during interactive resizing. [**Moveable**](#moveable) decides whether the user can drag the form by its title bar; [**ShowInTaskbar**](#showintaskbar) decides whether the form shows up in the taskbar and Alt-Tab list. -[**Opacity**](#opacity) and [**TransparencyKey**](#transparencykey) drive Windows' layered-window features for translucent forms and cut-out shapes. +[**Opacity**](#opacity) and [**TransparencyKey**](#transparencykey) enable Windows' layered-window features for translucent forms and cut-out shapes. ## Drawing surface @@ -810,7 +810,7 @@ Syntax: *object*\_**Deactivate**( ) ### DPIChange {: .no_toc } -Raised when the form moves to a monitor with a different DPI scale, *but only* when the application is per-monitor DPI aware (`PROCESS_PER_MONITOR_DPI_AWARE`). The event's *NewDPI* argument carries the new effective DPI; child controls re-scale themselves automatically. New in twinBASIC. +Raised when the form moves to a monitor with a different DPI scale, *but only* when the application is per-monitor DPI aware (`PROCESS_PER_MONITOR_DPI_AWARE`). The event's *NewDPI* argument gives the new effective DPI; child controls re-scale themselves automatically. New in twinBASIC. Syntax: *object*\_**DPIChange**( *NewDPI* **As Long** ) diff --git a/docs/Reference/VB/Frame/index.md b/docs/Reference/VB/Frame/index.md index 08aef73..31c78a3 100644 --- a/docs/Reference/VB/Frame/index.md +++ b/docs/Reference/VB/Frame/index.md @@ -58,7 +58,7 @@ Each frame defines its own option-button group. When the user selects an [**Opti ## Transparency and opacity -[**Opacity**](#opacity) and [**TransparencyKey**](#transparencykey) drive Windows' layered-window features. Setting [**Opacity**](#opacity) below 100 makes the frame and its contained controls translucent; setting [**TransparencyKey**](#transparencykey) to a colour makes pixels of that colour fully transparent on screen. Both features require Windows 8 or later when the frame contains child controls — otherwise only the frame's own background is affected. +[**Opacity**](#opacity) and [**TransparencyKey**](#transparencykey) enable Windows' layered-window features. Setting [**Opacity**](#opacity) below 100 makes the frame and its contained controls translucent; setting [**TransparencyKey**](#transparencykey) to a colour makes pixels of that colour fully transparent on screen. Both features require Windows 8 or later when the frame contains child controls — otherwise only the frame's own background is affected. ## Properties @@ -330,7 +330,7 @@ Syntax: *object*.**Refresh** ### SetFocus {: .no_toc } -Attempts to move the input focus to the frame. Because a frame is not focusable, this call has no observable effect on which control holds the focus, but it is provided for parity with the rest of the control surface and for compatibility with code that calls **SetFocus** generically. +Attempts to move the input focus to the frame. Because a frame is not focusable, this call has no observable effect on which control holds the focus, but it is provided for parity with the rest of the control API and for compatibility with code that calls **SetFocus** generically. Syntax: *object*.**SetFocus** diff --git a/docs/Reference/VB/HScrollBar/index.md b/docs/Reference/VB/HScrollBar/index.md index eb6b71a..f7e9fa8 100644 --- a/docs/Reference/VB/HScrollBar/index.md +++ b/docs/Reference/VB/HScrollBar/index.md @@ -60,7 +60,7 @@ The scroll bar produces value changes through four kinds of user input: | Drag the thumb | continuous | [**Scroll**](#scroll) during drag, [**Change**](#change) on release | | Press **Home** / **End** | jumps to **Min** / **Max** | [**Change**](#change) | -Both [**SmallChange**](#smallchange) and [**LargeChange**](#largechange) default to `1`. [**LargeChange**](#largechange) also drives the visible width of the thumb relative to the track, so larger values produce a chunkier thumb. +Both [**SmallChange**](#smallchange) and [**LargeChange**](#largechange) default to `1`. [**LargeChange**](#largechange) also controls the visible width of the thumb relative to the track, so larger values produce a chunkier thumb. ## Change versus Scroll @@ -345,7 +345,7 @@ Syntax: *object*\_**GotFocus**( ) ### Initialize {: .no_toc } -Raised once, after the underlying window has been created and the scroll bar is wired up to its Win32 range, but before the scroll bar is first painted. Useful for last-minute setup that needs the underlying handle. +Raised once, after the underlying window has been created and the scroll bar is connected to its Win32 range, but before the scroll bar is first painted. Useful for last-minute setup that needs the underlying handle. Syntax: *object*\_**Initialize**( ) diff --git a/docs/Reference/VB/Image/index.md b/docs/Reference/VB/Image/index.md index 4447ca4..7c04226 100644 --- a/docs/Reference/VB/Image/index.md +++ b/docs/Reference/VB/Image/index.md @@ -60,7 +60,7 @@ Metafiles (`vbPicTypeMetafile`, `vbPicTypeEMetafile`) are vector — they always The **Image** control supports both ends of an OLE drag-drop operation: -- [**OLEDragMode**](#oledragmode) controls the source side. With **vbOLEDragAutomatic**, holding the mouse over the **Image** and beginning a drag automatically picks up the current [**Picture**](#picture) into the resulting **DataObject**. With **vbOLEDragManual** (default) drags must be initiated by calling [**OLEDrag**](#oledrag) from a [**MouseDown**](#mousedown) handler. +- [**OLEDragMode**](#oledragmode) controls the source side. With **vbOLEDragAutomatic**, holding the mouse over the **Image** and beginning a drag automatically copies the current [**Picture**](#picture) into the resulting **DataObject**. With **vbOLEDragManual** (default) drags must be initiated by calling [**OLEDrag**](#oledrag) from a [**MouseDown**](#mousedown) handler. - [**OLEDropMode**](#oledropmode) controls the destination side. With **vbOLEDropManual** the [**OLEDragOver**](#oledragover) and [**OLEDragDrop**](#oledragdrop) events fire and the application decides what to do. **vbOLEDropAutomatic** is not supported on an **Image** and assigning it raises run-time error 5. ## Data binding @@ -179,12 +179,12 @@ The unique design-time name of the control on its parent form. Read-only at run ### OLEDragMode {: .no_toc } -Whether an OLE drag is started automatically when the user begins dragging the **Image**. A member of [**OLEDragConstants**](../../VBRUN/Constants/OLEDragConstants): **vbOLEDragManual** (0, default — application calls [**OLEDrag**](#oledrag)) or **vbOLEDragAutomatic** (1 — the framework picks up the current [**Picture**](#picture) into the resulting **DataObject** automatically). +Whether an OLE drag is started automatically when the user begins dragging the **Image**. A member of [**OLEDragConstants**](../../VBRUN/Constants/OLEDragConstants): **vbOLEDragManual** (0, default — application calls [**OLEDrag**](#oledrag)) or **vbOLEDragAutomatic** (1 — the framework copies the current [**Picture**](#picture) into the resulting **DataObject** automatically). ### OLEDropMode {: .no_toc } -How the **Image** responds to OLE drops landing on it. A restricted member of [**OLEDropConstants**](../../VBRUN/Constants/OLEDropConstants): **vbOLEDropNone** (0, default) or **vbOLEDropManual** (1). Automatic drop is not supported on an **Image**; assigning **vbOLEDropAutomatic** raises run-time error 5 (*Invalid procedure call or argument*). +How the **Image** responds to OLE drops arriving on it. A restricted member of [**OLEDropConstants**](../../VBRUN/Constants/OLEDropConstants): **vbOLEDropNone** (0, default) or **vbOLEDropManual** (1). Automatic drop is not supported on an **Image**; assigning **vbOLEDropAutomatic** raises run-time error 5 (*Invalid procedure call or argument*). ### Parent {: .no_toc } @@ -285,7 +285,7 @@ Syntax: *object*.**Move** *Left* [, *Top* [, *Width* [, *Height* ] ] ] ### OLEDrag {: .no_toc } -Initiates an OLE drag operation from this **Image**, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject** (or, if the source has already been pre-populated, kicks off the drag immediately). +Initiates an OLE drag operation from this **Image**, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject** (or, if the source has already been pre-populated, begins the drag immediately). Syntax: *object*.**OLEDrag** @@ -347,7 +347,7 @@ Syntax: *object*\_**DragOver**( *Source* **As Control**, *X* **As Single**, *Y* ### Initialize {: .no_toc } -Raised once, after the control has been wired into its container's paint cycle but before it is first painted. Useful for last-minute setup that depends on container state. +Raised once, after the control has been connected to its container's paint cycle but before it is first painted. Useful for last-minute setup that depends on container state. Syntax: *object*\_**Initialize**( ) diff --git a/docs/Reference/VB/Label/index.md b/docs/Reference/VB/Label/index.md index bf34c6b..cf9df81 100644 --- a/docs/Reference/VB/Label/index.md +++ b/docs/Reference/VB/Label/index.md @@ -46,7 +46,7 @@ lblName.Caption = "&Name:" ' Alt+N → next control (typically txtName lblHelp.Caption = "Use && to escape" ' renders as: Use & to escape ``` -The convention is to place the **Label** immediately before the control it captions in tab order, so the mnemonic naturally lands on that control. +The convention is to place the **Label** immediately before the control it captions in tab order, so the mnemonic naturally targets that control. ## Caption layout @@ -75,7 +75,7 @@ The convention is to place the **Label** immediately before the control it capti | **vbFixedSingleBorder** | 1 | A sunken Win32-style border. [**Appearance**](#appearance) selects 3-D or flat. | | **vbCustomBorder** | 2 | Per-edge custom border configured through [**BorderCustomOptions**](#bordercustomoptions). | -With **vbCustomBorder**, [**BorderCustomOptions**](#bordercustomoptions) returns an object whose `.Left`, `.Top`, `.Right`, and `.Bottom` properties each carry independent **Size** (line thickness, in twips), **Padding** (inset between the border and the caption, in twips), and **Color** values: +With **vbCustomBorder**, [**BorderCustomOptions**](#bordercustomoptions) returns an object whose `.Left`, `.Top`, `.Right`, and `.Bottom` properties each have independent **Size** (line thickness, in twips), **Padding** (inset between the border and the caption, in twips), and **Color** values: ```tb lblBox.BorderStyle = vbCustomBorder @@ -342,7 +342,7 @@ A reference to the [**Form**](../Form/) (or **UserControl**) that ultimately con {: .no_toc } > [!NOTE] -> Reserved for compatibility with VB6; not currently implemented in twinBASIC. The label is non-focusable, so the value would only affect mnemonic-routing — that is currently driven by the design-time Z-order instead. +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. The label is non-focusable, so the value would only affect mnemonic-routing — that is currently controlled by the design-time Z-order instead. ### Tag {: .no_toc } @@ -519,7 +519,7 @@ Syntax: *object*\_**DragOver**( *Source* **As Control**, *X* **As Single**, *Y* ### Initialize {: .no_toc } -Raised once, after the label has been wired into its container's paint cycle but before it is first painted. Useful for last-minute setup that depends on container state. +Raised once, after the label has been connected to its container's paint cycle but before it is first painted. Useful for last-minute setup that depends on container state. Syntax: *object*\_**Initialize**( ) diff --git a/docs/Reference/VB/Line/index.md b/docs/Reference/VB/Line/index.md index e113b25..f85503a 100644 --- a/docs/Reference/VB/Line/index.md +++ b/docs/Reference/VB/Line/index.md @@ -8,7 +8,7 @@ has_toc: false # Line class {: .no_toc } -A **Line** is a windowless lightweight control that draws a single straight line segment from one point to another on its container. It exists purely for visual presentation — to divide regions of a form, underline a heading, draw a leader to an annotation — and has no interaction surface of its own: no mouse events, no focus, no caption. +A **Line** is a windowless lightweight control that draws a single straight line segment from one point to another on its container. It exists purely for visual presentation — to divide regions of a form, underline a heading, draw a leader to an annotation — and has no interactive elements of its own: no mouse events, no focus, no caption. A **Line** is positioned by its two endpoints, [**X1**](#x1) / [**Y1**](#y1) and [**X2**](#x2) / [**Y2**](#y2), rather than by a `Left` / `Top` / `Width` / `Height` rectangle. The default property is [**Visible**](#visible) and the default event is [**Initialize**](#initialize). @@ -44,7 +44,7 @@ GDI applies a hard limitation here: when [**BorderWidth**](#borderwidth) is grea [**DrawMode**](#drawmode) selects the raster operation that combines the pen with the destination pixels. A member of [**DrawModeConstants**](../../VBRUN/Constants/DrawModeConstants): **vbCopyPen** (default — opaque drawing) or one of the XOR / AND / NOT / merge variants. Non-default modes are mainly useful for "rubber-band" feedback drawn over an existing background — the same XOR you draw twice cancels itself out, restoring the original pixels. -## No interaction surface +## No interaction Unlike most other controls, a **Line** does not raise mouse, keyboard, or focus events of any kind, and has no [**Caption**](/tB/Packages/VB/Label#caption), [**Enabled**](/tB/Packages/VB/Label#enabled), or **ToolTipText**. To make a region clickable, place a transparent [**Label**](../Label/) on top. @@ -142,6 +142,6 @@ Syntax: *object*.**ZOrder** [ *Position* ] ### Initialize {: .no_toc } -Raised once, after the line has been wired into its container's paint cycle but before it is first painted. **Default event.** +Raised once, after the line has been connected to its container's paint cycle but before it is first painted. **Default event.** Syntax: *object*\_**Initialize**( ) diff --git a/docs/Reference/VB/MDIForm/index.md b/docs/Reference/VB/MDIForm/index.md index c8fedcb..48213e4 100644 --- a/docs/Reference/VB/MDIForm/index.md +++ b/docs/Reference/VB/MDIForm/index.md @@ -75,7 +75,7 @@ An MDIForm always uses the sizable border style — there is no [**BorderStyle** [**MinWidth**](#minwidth), [**MinHeight**](#minheight), [**MaxWidth**](#maxwidth), and [**MaxHeight**](#maxheight) constrain the *client area* in twips during interactive resizing. [**Moveable**](#moveable) decides whether the user can drag the form by its title bar. -[**Opacity**](#opacity) and [**TransparencyKey**](#transparencykey) drive Windows' layered-window features for translucent forms and cut-out shapes. +[**Opacity**](#opacity) and [**TransparencyKey**](#transparencykey) enable Windows' layered-window features for translucent forms and cut-out shapes. [**BackColor**](#backcolor) paints the MDI client area's background — defaults to the system **vbApplicationWorkspace** colour rather than 3-D face. [**Picture**](#picture), when set, is drawn over **BackColor** as the client-area backdrop, scaled to fill the area for metafiles and centred at its natural size for bitmaps. [**PictureDpiScaling**](#picturedpiscaling) scales bitmaps by the current DPI factor before drawing. There is no on-screen drawing API on an MDIForm — the [**Cls**](../Form/#cls), [**Circle**](../Form/#circle), [**Line**](../Form/#line), [**PSet**](../Form/#pset), [**PaintPicture**](../Form/#paintpicture), and **Print** members of the **Form** interface raise run-time error 438 (*Object doesn't support this property or method*) when called on an MDIForm. @@ -491,7 +491,7 @@ Syntax: *object*\_**Deactivate**( ) ### DPIChange {: .no_toc } -Raised when the form moves to a monitor with a different DPI scale, *but only* when the application is per-monitor DPI aware (`PROCESS_PER_MONITOR_DPI_AWARE`). The event's *NewDPI* argument carries the new effective DPI; child controls and MDI children re-scale themselves automatically. New in twinBASIC. +Raised when the form moves to a monitor with a different DPI scale, *but only* when the application is per-monitor DPI aware (`PROCESS_PER_MONITOR_DPI_AWARE`). The event's *NewDPI* argument gives the new effective DPI; child controls and MDI children re-scale themselves automatically. New in twinBASIC. Syntax: *object*\_**DPIChange**( *NewDPI* **As Long** ) diff --git a/docs/Reference/VB/Menu/index.md b/docs/Reference/VB/Menu/index.md index 9f68524..9b64fa3 100644 --- a/docs/Reference/VB/Menu/index.md +++ b/docs/Reference/VB/Menu/index.md @@ -196,7 +196,7 @@ When **True** on a menu hosted by an [**MDIForm**](../MDIForm/), turns this menu ### Container {: .no_toc } -Returns a reference to the **Control** that hosts this menu — typically the [**Form**](../Form/) or [**MDIForm**](../MDIForm/) that owns the menu structure. Equivalent to walking [**Parent**](#parent) for a top-level menu, but defined on every menu (including sub-items) so it can be called uniformly. +Returns a reference to the **Control** that hosts this menu — typically the [**Form**](../Form/) or [**MDIForm**](../MDIForm/) that owns the menu structure. Equivalent to traversing [**Parent**](#parent) for a top-level menu, but defined on every menu (including sub-items) so it can be called uniformly. Syntax: *object*.**Container** diff --git a/docs/Reference/VB/OLE/index.md b/docs/Reference/VB/OLE/index.md index abdca42..cefbc2b 100644 --- a/docs/Reference/VB/OLE/index.md +++ b/docs/Reference/VB/OLE/index.md @@ -11,7 +11,7 @@ has_toc: false An **OLE** *container* control hosts a linked or embedded OLE Automation object — typically a Word document, an Excel spreadsheet, or any other registered OLE server — directly on a form, and lets the user activate and edit the contained object in place via its registered verbs. > [!NOTE] -> The OLE container control is a **VB6 compatibility stub** in twinBASIC. Almost every OLE-specific property, method, and event is currently unimplemented (each is flagged below). The inherited base-control surface — positioning, sizing, anchoring, focus, drag, mouse cursor — does work normally, so a project ported from VB6 still parses and lays out the control on its form, but cannot create, embed, link, paste, save, or activate an actual OLE object through it. +> The OLE container control is a **VB6 compatibility stub** in twinBASIC. Almost every OLE-specific property, method, and event is currently unimplemented (each is flagged below). The inherited base-control members — positioning, sizing, anchoring, focus, drag, mouse cursor — do work normally, so a project ported from VB6 still parses and lays out the control on its form, but cannot create, embed, link, paste, save, or activate an actual OLE object through it. There is no default property. The default-designer event is [**Click**](#click). @@ -272,7 +272,7 @@ The horizontal distance from the left edge of the container to the left edge of > [!NOTE] > Reserved for VB6 compatibility; not currently implemented in twinBASIC. -A run-time-only **LongPtr** giving the raw `IOleObject` interface pointer of the contained object, for hand-off to native code. +A run-time-only **LongPtr** giving the raw `IOleObject` interface pointer of the contained object, for passing to native code. ### MiscFlags {: .no_toc } diff --git a/docs/Reference/VB/Printer/index.md b/docs/Reference/VB/Printer/index.md index 04d5744..2417818 100644 --- a/docs/Reference/VB/Printer/index.md +++ b/docs/Reference/VB/Printer/index.md @@ -36,7 +36,7 @@ For Each p In Printers Next ``` -By default the implicit **Printer** has [**TrackDefault**](#trackdefault) **True**: every property read consults the current system-default printer, so the application picks up changes the user makes in **Settings → Printers** without restarting. Writing to a settings property, calling **Set Printer = Printers(i)**, or starting a print job locks **TrackDefault** to **False** and pins the object to a specific device. +By default the implicit **Printer** has [**TrackDefault**](#trackdefault) **True**: every property read consults the current system-default printer, so the application reflects changes the user makes in **Settings → Printers** without restarting. Writing to a settings property, calling **Set Printer = Printers(i)**, or starting a print job locks **TrackDefault** to **False** and pins the object to a specific device. The entries returned by [**Printers**](../Printers/) are immutable — assigning to one of their properties raises run-time error 383 (*Property is read-only*), and the document-control methods raise error 438 (*Object doesn't support this property or method*). To print to one of them, copy it onto the implicit **Printer** with **Set**: @@ -322,7 +322,7 @@ Setting **TrackDefault** to **False** captures the current default device into t ### TwipsPerPixelX {: .no_toc } -The number of twips that correspond to one device pixel, horizontally — useful for hand-rolled DPI-aware sizing. **Double**, read-only. +The number of twips that correspond to one device pixel, horizontally — useful for custom DPI-aware sizing. **Double**, read-only. ### TwipsPerPixelY {: .no_toc } diff --git a/docs/Reference/VB/Printers/index.md b/docs/Reference/VB/Printers/index.md index 52155a7..74e7103 100644 --- a/docs/Reference/VB/Printers/index.md +++ b/docs/Reference/VB/Printers/index.md @@ -24,13 +24,13 @@ Set Printer = Printers("HP LaserJet") ' make this the active printer ## What the collection contains -Each entry is a [**Printer**](../Printer/) bound to the corresponding device. These instances are **immutable** descriptors — they are intended for identification and for handing to `Set Printer = …`, not for driving a print job directly. Assigning any of the settings properties on one raises run-time error 383 (*Property is read-only*); calling [**EndDoc**](../Printer/#enddoc), [**KillDoc**](../Printer/#killdoc), [**NewPage**](../Printer/#newpage), [**Print**](../Printer/#print), or the other document-control methods raises run-time error 438 (*Object doesn't support this property or method*). [**TrackDefault**](../Printer/#trackdefault) is always **False** on these instances. +Each entry is a [**Printer**](../Printer/) bound to the corresponding device. These instances are **immutable** descriptors — they are intended for identification and for handing to `Set Printer = …`, not for running a print job directly. Assigning any of the settings properties on one raises run-time error 383 (*Property is read-only*); calling [**EndDoc**](../Printer/#enddoc), [**KillDoc**](../Printer/#killdoc), [**NewPage**](../Printer/#newpage), [**Print**](../Printer/#print), or the other document-control methods raises run-time error 438 (*Object doesn't support this property or method*). [**TrackDefault**](../Printer/#trackdefault) is always **False** on these instances. A driver that advertises a single device over multiple ports produces one [**Printer**](../Printer/) entry per port; only the first such entry is keyed by **DeviceName**, the rest are accessible only by numeric index. ## Live enumeration -The collection is **not cached**. Every call to [**Count**](#count), [**Item**](#item), or `For Each` re-reads the system's installed-printers list from the Windows registry's profile section and reconstructs a fresh batch of [**Printer**](../Printer/) instances. A printer added or removed in **Settings → Printers** is therefore picked up the next time the collection is touched, with no need to refresh anything from code. The trade-off is that consecutive accesses are not cheap — when enumerating, cache the result if many lookups are needed: +The collection is **not cached**. Every call to [**Count**](#count), [**Item**](#item), or `For Each` re-reads the system's installed-printers list from the Windows registry's profile section and reconstructs a fresh batch of [**Printer**](../Printer/) instances. A printer added or removed in **Settings → Printers** therefore appears the next time the collection is touched, with no need to refresh anything from code. The trade-off is that consecutive accesses are not cheap — when enumerating, cache the result if many lookups are needed: ```tb Dim snapshot As Variant : snapshot = Array() ' or use a Collection diff --git a/docs/Reference/VB/PropertyPage/index.md b/docs/Reference/VB/PropertyPage/index.md index 27dcd0c..a54f3a4 100644 --- a/docs/Reference/VB/PropertyPage/index.md +++ b/docs/Reference/VB/PropertyPage/index.md @@ -8,12 +8,12 @@ has_toc: false # PropertyPage class {: .no_toc } -A **PropertyPage** is a container that backs a single tab of a COM property-page dialog — the popup invoked from the **(Custom)** entry on an ActiveX control's property browser. It exposes the **IPropertyPage2** COM interface so that any host that knows how to drive ActiveX property pages (the twinBASIC IDE, classic VB6, Office, …) can place it inside its own property-sheet frame, give it the controls the user is editing, and apply the page's changes back to them. +A **PropertyPage** is a container that backs a single tab of a COM property-page dialog — the popup invoked from the **(Custom)** entry on an ActiveX control's property browser. It exposes the **IPropertyPage2** COM interface so that any host that supports ActiveX property pages (the twinBASIC IDE, classic VB6, Office, …) can place it inside its own property-sheet frame, give it the controls the user is editing, and apply the page's changes back to them. -Designing a property page is much like designing a small dialog [**Form**](../Form): drop child controls onto it, write event handlers, and use its drawing surface freely. What sets it apart is the lifecycle, which is driven by the host rather than by the application: +Designing a property page is much like designing a small dialog [**Form**](../Form): drop child controls onto it, write event handlers, and use its drawing surface freely. What sets it apart is the lifecycle, which is controlled by the host rather than by the application: 1. The host instantiates the property-page class once per dialog. -2. The host calls **IPropertyPage2.SetObjects** to hand over the selected ActiveX controls. The framework stores them in [**SelectedControls**](#selectedcontrols) and raises [**SelectionChanged**](#selectionchanged). +2. The host calls **IPropertyPage2.SetObjects** to pass the selected ActiveX controls. The framework stores them in [**SelectedControls**](#selectedcontrols) and raises [**SelectionChanged**](#selectionchanged). 3. As the user edits values, the page handler sets [**Changed**](#changed) = **True** to enable the dialog's *Apply* button. 4. When the user clicks *OK* or *Apply*, the host raises [**ApplyChanges**](#applychanges) so the page can write the new values back to [**SelectedControls**](#selectedcontrols). 5. On dialog close the framework raises [**Terminate**](#terminate) and releases the class instance. @@ -363,7 +363,7 @@ The standard size of the page in the host's property-sheet frame. A member of ** Syntax: *object*.**StandardSize** [ = *value* ] -Reading **StandardSize** compares the page's current pixel size against the small/large presets and returns **StandardSizeCustom** when neither matches. Assigning **StandardSizeSmall** or **StandardSizeLarge** resizes the page accordingly; assigning **StandardSizeCustom** is a no-op (leave the size as it is). The property is exposed only in code — VB6 surfaced it on the design-time property sheet but never in the runtime object model. +Reading **StandardSize** compares the page's current pixel size against the small/large presets and returns **StandardSizeCustom** when neither matches. Assigning **StandardSizeSmall** or **StandardSizeLarge** resizes the page accordingly; assigning **StandardSizeCustom** is a no-op (leave the size as it is). The property is exposed only in code — VB6 exposed it on the design-time property sheet but never in the runtime object model. ### Tag {: .no_toc } @@ -601,7 +601,7 @@ Syntax: *object*\_**DblClick**( ) ### DPIChange {: .no_toc } -Raised when the page moves to a monitor with a different DPI scale, *but only* when the application is per-monitor DPI aware (`PROCESS_PER_MONITOR_DPI_AWARE`). The event's *NewDPI* argument carries the new effective DPI; child controls re-scale themselves automatically. +Raised when the page moves to a monitor with a different DPI scale, *but only* when the application is per-monitor DPI aware (`PROCESS_PER_MONITOR_DPI_AWARE`). The event's *NewDPI* argument gives the new effective DPI; child controls re-scale themselves automatically. Syntax: *object*\_**DPIChange**( *NewDPI* **As Long** ) diff --git a/docs/Reference/VB/QRCode/index.md b/docs/Reference/VB/QRCode/index.md index 2cdc92a..5423f4b 100644 --- a/docs/Reference/VB/QRCode/index.md +++ b/docs/Reference/VB/QRCode/index.md @@ -56,7 +56,7 @@ QR codes embed a Reed-Solomon parity stream that lets the decoder recover from d | **vbQRCodegenEccQuartile** | 2 | 25% | | **vbQRCodegenEccHigh** | 3 | 30% | -When [**EccBoost**](#eccboost) is **True** (default), the encoder raises the parity level beyond the configured minimum if doing so still fits the payload in the same QR version — getting better resilience for free. +When [**EccBoost**](#eccboost) is **True** (default), the encoder raises the parity level beyond the configured minimum if doing so still fits the payload in the same QR version — automatically achieving better resilience. ## Version and mask @@ -80,7 +80,7 @@ The QR-code *version* (1 to 40) sets the matrix size: version 1 is 21 × 21 modu A **QRCode** supports both ends of an OLE drag-drop operation: -- [**OLEDragMode**](#oledragmode) controls the source side. With **vbOLEDragAutomatic**, holding the mouse over the control and beginning a drag automatically picks up the current [**Picture**](#picture) into the resulting **DataObject** — handy for dragging the generated QR onto another picture display or out to a file in Explorer. With **vbOLEDragManual** (default) drags must be initiated by calling [**OLEDrag**](#oledrag) from a [**MouseDown**](#mousedown) handler. +- [**OLEDragMode**](#oledragmode) controls the source side. With **vbOLEDragAutomatic**, holding the mouse over the control and beginning a drag automatically copies the current [**Picture**](#picture) into the resulting **DataObject** — convenient for dragging the generated QR onto another picture display or out to a file in Explorer. With **vbOLEDragManual** (default) drags must be initiated by calling [**OLEDrag**](#oledrag) from a [**MouseDown**](#mousedown) handler. - [**OLEDropMode**](#oledropmode) controls the destination side. With **vbOLEDropManual** the [**OLEDragOver**](#oledragover) and [**OLEDragDrop**](#oledragdrop) events fire so the application can decide what to do — for example, set [**Payload**](#payload) to the dropped text. **vbOLEDropAutomatic** is not supported on a **QRCode** and assigning it raises run-time error 5 (*Invalid procedure call or argument*). ## Data binding @@ -125,7 +125,7 @@ Whether the bound [**Picture**](#picture) has been written to since the last sav ### DataField {: .no_toc } -The name of the field, in the recordset of the bound [**DataSource**](#datasource), whose value drives [**Payload**](#payload). **String**. +The name of the field, in the recordset of the bound [**DataSource**](#datasource), whose value sets [**Payload**](#payload). **String**. ### DataFormat {: .no_toc } @@ -239,12 +239,12 @@ The unique design-time name of the control on its parent form. Read-only at run ### OLEDragMode {: .no_toc } -Whether an OLE drag is started automatically when the user begins dragging the control. A member of [**OLEDragConstants**](../../VBRUN/Constants/OLEDragConstants): **vbOLEDragManual** (0, default — application calls [**OLEDrag**](#oledrag)) or **vbOLEDragAutomatic** (1 — the framework picks up the current [**Picture**](#picture) into the resulting **DataObject** automatically). +Whether an OLE drag is started automatically when the user begins dragging the control. A member of [**OLEDragConstants**](../../VBRUN/Constants/OLEDragConstants): **vbOLEDragManual** (0, default — application calls [**OLEDrag**](#oledrag)) or **vbOLEDragAutomatic** (1 — the framework copies the current [**Picture**](#picture) into the resulting **DataObject** automatically). ### OLEDropMode {: .no_toc } -How the control responds to OLE drops landing on it. A restricted member of [**OLEDropConstants**](../../VBRUN/Constants/OLEDropConstants): **vbOLEDropNone** (0, default) or **vbOLEDropManual** (1). Automatic drop is not supported on a **QRCode**; assigning **vbOLEDropAutomatic** raises run-time error 5 (*Invalid procedure call or argument*). +How the control responds to OLE drops arriving on it. A restricted member of [**OLEDropConstants**](../../VBRUN/Constants/OLEDropConstants): **vbOLEDropNone** (0, default) or **vbOLEDropManual** (1). Automatic drop is not supported on a **QRCode**; assigning **vbOLEDropAutomatic** raises run-time error 5 (*Invalid procedure call or argument*). ### Parent {: .no_toc } @@ -394,7 +394,7 @@ Syntax: *object*\_**DragOver**( *Source* **As Control**, *X* **As Single**, *Y* ### Initialize {: .no_toc } -Raised once, after the control has been wired into its container's paint cycle but before it is first painted. Useful for last-minute setup that depends on container state. +Raised once, after the control has been connected to its container's paint cycle but before it is first painted. Useful for last-minute setup that depends on container state. Syntax: *object*\_**Initialize**( ) diff --git a/docs/Reference/VB/Report/index.md b/docs/Reference/VB/Report/index.md index b12f330..b346bf2 100644 --- a/docs/Reference/VB/Report/index.md +++ b/docs/Reference/VB/Report/index.md @@ -42,7 +42,7 @@ Sections are designed in the IDE — each is a container that holds [**Label**]( ## Recordset binding -[**Recordset**](#recordset) accepts any object that exposes the classic ADO/DAO surface — `EOF`, `MoveNext`, and a `Fields` collection indexable by name. The framework wraps non-tB recordsets transparently. `Recordset` may also be left **Nothing**, in which case the detail section is rendered exactly once with no field data. +[**Recordset**](#recordset) accepts any object that exposes the classic ADO/DAO interface — `EOF`, `MoveNext`, and a `Fields` collection indexable by name. The framework wraps non-tB recordsets transparently. `Recordset` may also be left **Nothing**, in which case the detail section is rendered exactly once with no field data. A control in a section opts into binding by setting its `DataField` to a recordset field name; the framework reads that field for each detail row and writes it back into the control's value (or [**Caption**](../Label/#caption) for [**Label**](../Label/)s, **Payload** for [**QRCode**](../QRCode/)). For richer cases, prefix `DataField` with `=` to make it an *expression* — any twinBASIC expression that mixes recordset fields, the report's own [**Page**](#page) / [**Pages**](#pages) / [**Caption**](#caption), and standard library calls. A label whose **DataField** is `="Page " & Report.Page & " of " & Report.Pages` updates itself as each page is rendered. @@ -88,7 +88,7 @@ The toolbar always paints; it cannot be hidden. The plus and minus buttons step | **vbZoomAutoFitOnce** | 1 | Recalculate once, on the first paint, then leave [**ZoomPercent**](#zoompercent) alone. | | **vbZoomAutoFitNever** | 2 | Honour whatever [**ZoomPercent**](#zoompercent) is currently set to. | -Clicking the toolbar's plus or minus button automatically switches [**ZoomAutoFit**](#zoomautofit) to **vbZoomAutoFitNever** so the user's manual zoom sticks. +Clicking the toolbar's plus or minus button automatically switches [**ZoomAutoFit**](#zoomautofit) to **vbZoomAutoFitNever** so the user's manual zoom is preserved. ## Drawing inside sections @@ -629,7 +629,7 @@ Syntax: *object*.**PaintPicture** *Picture*, *X1*, *Y1* [, *Width1* [, *Height1* ### Print {: .no_toc } -Writes text to the current drawing surface using [**Font**](#font), starting at [**CurrentX**](#currentx) / [**CurrentY**](#currenty) and advancing them as it goes. Inside a [**BeforePaintSection**](#beforepaintsection) handler the text lands on the section being painted; outside it, the text is drawn directly on the report window. +Writes text to the current drawing surface using [**Font**](#font), starting at [**CurrentX**](#currentx) / [**CurrentY**](#currenty) and advancing them as it goes. Inside a [**BeforePaintSection**](#beforepaintsection) handler the text appears on the section being painted; outside it, the text is drawn directly on the report window. Syntax: *object*.**Print** \[ *expressionlist* ] \[ **;** \| **,** ] @@ -809,7 +809,7 @@ Syntax: *object*\_**Deactivate**( ) ### DPIChange {: .no_toc } -Raised when the report window moves to a monitor with a different DPI scale, *but only* when the application is per-monitor DPI aware (`PROCESS_PER_MONITOR_DPI_AWARE`). The event's *NewDPI* argument carries the new effective DPI. +Raised when the report window moves to a monitor with a different DPI scale, *but only* when the application is per-monitor DPI aware (`PROCESS_PER_MONITOR_DPI_AWARE`). The event's *NewDPI* argument gives the new effective DPI. Syntax: *object*\_**DPIChange**( *NewDPI* **As Long** ) diff --git a/docs/Reference/VB/Screen/index.md b/docs/Reference/VB/Screen/index.md index 5cfe09d..4647c78 100644 --- a/docs/Reference/VB/Screen/index.md +++ b/docs/Reference/VB/Screen/index.md @@ -40,7 +40,7 @@ On a 96-DPI display these are both `15` (1440 twips per logical inch ÷ 96 pixel [**ActiveForm**](#activeform) returns the [**Form**](../Form/) instance that is currently the foreground form in the application; [**ActiveControl**](#activecontrol) returns the control within that form that currently holds the focus. Both return **Nothing** if no form in the application is active. -The most common idiom is reaching into the active form from a global handler — for example, a toolbar button on an [**MDIForm**](../MDIForm/) that operates on whatever MDI child is in front: +The most common idiom is accessing the active form from a global handler — for example, a toolbar button on an [**MDIForm**](../MDIForm/) that operates on whatever MDI child is in front: ```tb Private Sub tbrEdit_ButtonClick(ByVal Button As MSComctlLib.Button) diff --git a/docs/Reference/VB/Shape/index.md b/docs/Reference/VB/Shape/index.md index 45bab32..f9e1f24 100644 --- a/docs/Reference/VB/Shape/index.md +++ b/docs/Reference/VB/Shape/index.md @@ -10,7 +10,7 @@ has_toc: false A **Shape** is a windowless lightweight control that draws one of a fixed set of geometric primitives — rectangle, square, oval, circle, rounded rectangle, rounded square, five-pointed star, or an arrow pointing in any of the four cardinal directions — directly on its container. It exists purely for visual presentation: backgrounds, decorative artwork, panel dividers, highlighting, and any other place where a heavy [**PictureBox**](../PictureBox/) would be overkill. -A **Shape** has no interaction surface — no focus, no caption, and no mouse, keyboard, or drag events. The shape kind and its appearance are chosen entirely through properties; the only event raised by the control is [**Initialize**](#initialize). The default property is [**Shape**](#shape) and the default event is [**Initialize**](#initialize). +A **Shape** has no interactive elements — no focus, no caption, and no mouse, keyboard, or drag events. The shape kind and its appearance are chosen entirely through properties; the only event raised by the control is [**Initialize**](#initialize). The default property is [**Shape**](#shape) and the default event is [**Initialize**](#initialize). ```tb Private Sub Form_Load() @@ -317,6 +317,6 @@ Syntax: *object*.**ZOrder** [ *Position* ] ### Initialize {: .no_toc } -Raised once, after the **Shape** has been wired into its container's paint cycle but before it is first painted. Useful for last-minute setup that depends on container state. **Default event.** +Raised once, after the **Shape** has been connected to its container's paint cycle but before it is first painted. Useful for last-minute setup that depends on container state. **Default event.** Syntax: *object*\_**Initialize**( ) diff --git a/docs/Reference/VB/TextBox/index.md b/docs/Reference/VB/TextBox/index.md index 00915f3..685de17 100644 --- a/docs/Reference/VB/TextBox/index.md +++ b/docs/Reference/VB/TextBox/index.md @@ -297,7 +297,7 @@ The unique design-time name of the control on its parent form. Read-only at run ### NumbersOnly {: .no_toc } -When **True**, the edit control rejects keystrokes other than the decimal digits **0**–**9**. **Boolean**, default **False**. Does not validate code-assigned values, sign characters, decimal points, or thousand separators — use a [**KeyPress**](#keypress) handler for richer filtering. +When **True**, the edit control rejects keystrokes other than the decimal digits **0**–**9**. **Boolean**, default **False**. Does not validate code-assigned values, sign characters, decimal points, or thousand separators — use a [**KeyPress**](#keypress) handler for additional validation. ### OLEDragMode {: .no_toc } diff --git a/docs/Reference/VB/Timer/index.md b/docs/Reference/VB/Timer/index.md index 9fc2881..ba900ac 100644 --- a/docs/Reference/VB/Timer/index.md +++ b/docs/Reference/VB/Timer/index.md @@ -46,10 +46,10 @@ Assigning a negative value to [**Interval**](#interval) raises run-time error 38 ## Accuracy and resolution -The control wraps Win32's per-window timer queue, which is driven by the standard message pump. Two consequences follow: +The control wraps Win32's per-window timer queue, which runs on the standard message pump. Two consequences follow: - **Resolution is coarse.** The OS quantises timer ticks to the system clock-tick period — typically ~15.6 ms on desktop Windows. Intervals shorter than that are silently rounded up. For sub-millisecond pacing use a multimedia timer or `QueryPerformanceCounter` directly. -- **Ticks can be skipped under load.** If the message pump is blocked when a tick is due, no events queue up — the runtime delivers a single [**Timer**](#timer) event when the pump catches up, *not* one for each missed period. Long-running work inside the handler therefore lengthens the next interval rather than producing a backlog. +- **Ticks can be skipped under load.** If the message pump is blocked when a tick is due, no events queue up — the runtime delivers a single [**Timer**](#timer) event when the pump resumes, *not* one for each missed period. Long-running work inside the handler therefore lengthens the next interval rather than producing a backlog. For periodic UI updates (a clock, a progress animation, a poll for external state) the **Timer** is exactly the right tool. For precise wall-clock pacing, audio scheduling, or anything that must keep up under heavy CPU load, it is not. diff --git a/docs/Reference/VB/UserControl/index.md b/docs/Reference/VB/UserControl/index.md index afdde73..e0bf701 100644 --- a/docs/Reference/VB/UserControl/index.md +++ b/docs/Reference/VB/UserControl/index.md @@ -46,7 +46,7 @@ End Property ## Lifecycle -A user control instance goes through up to seven distinct events from creation to destruction. The host drives the sequence: +A user control instance goes through up to seven distinct events from creation to destruction. The host controls the sequence: | Event | When | |----------------------------------------|-----------------------------------------------------------------------------------------------------| @@ -55,7 +55,7 @@ A user control instance goes through up to seven distinct events from creation t | [**ReadProperties**](#readproperties) | Once, for an instance reloaded from a property bag (every load after the first save). | | [**Resize**](#resize) | When the host first sizes the control, and on every subsequent size change. | | [**Show**](#show) / [**Hide**](#hide) | When the host changes the container's visibility — typically as the host's design view / run view changes. | -| [**WriteProperties**](#writeproperties)| When the host asks the control to persist its state — design-time saves, host-driven serialisation. | +| [**WriteProperties**](#writeproperties)| When the host asks the control to persist its state — design-time saves, host-initiated serialisation. | | [**Terminate**](#terminate) | After the window has been destroyed and the class instance is about to be released. | For each instance, exactly one of **InitProperties** or **ReadProperties** runs after [**Initialize**](#initialize), depending on whether the host had a saved property bag. [**WriteProperties**](#writeproperties) is only raised when [**PropertyChanged**](#propertychanged) has been called at least once since the last save, so handlers that never mark themselves dirty are never asked to write. @@ -175,7 +175,7 @@ The Win32 window handle of the host container that frames this **UserControl**, ### ControlContainer {: .no_toc } -Whether the **UserControl** acts as a container that can host other ActiveX controls dropped onto it at design time. **Boolean**, read-only at run time. Set at design time. Setting **ControlContainer** to **True** tells the host to enumerate this control's children when walking the form's control collection. +Whether the **UserControl** acts as a container that can host other ActiveX controls dropped onto it at design time. **Boolean**, read-only at run time. Set at design time. Setting **ControlContainer** to **True** tells the host to enumerate this control's children when iterating over the form's control collection. ### Controls {: .no_toc } @@ -622,7 +622,7 @@ Syntax: *object*.**DataMemberChanged** *DataMember* ### InternalEnumerator {: .no_toc } -Returns the `IUnknown` enumerator backing `For Each` over the **UserControl**'s [**Controls**](#controls). Read-only. Exposed as the [Enumerator] member so that `For Each ctl In UserControl` walks the children directly. +Returns the `IUnknown` enumerator backing `For Each` over the **UserControl**'s [**Controls**](#controls). Read-only. Exposed as the [Enumerator] member so that `For Each ctl In UserControl` iterates over the children directly. ### Line {: .no_toc } @@ -813,7 +813,7 @@ Syntax: *object*.**TextWidth**( *Str* ) {: .no_toc } > [!NOTE] -> Declared for VB6 compatibility; not currently implemented in twinBASIC. In VB6 this fired the focused child's **Validate** event from code; on a **UserControl** the host normally drives validation through the form-level [**ValidateControls**](../Form/#validatecontrols). +> Declared for VB6 compatibility; not currently implemented in twinBASIC. In VB6 this fired the focused child's **Validate** event from code; on a **UserControl** the host normally handles validation through the form-level [**ValidateControls**](../Form/#validatecontrols). Syntax: *object*.**ValidateControls** @@ -870,7 +870,7 @@ Syntax: *object*\_**DblClick**( ) ### DPIChange {: .no_toc } -Raised when the control moves to a monitor with a different DPI scale, *but only* when the application is per-monitor DPI aware (`PROCESS_PER_MONITOR_DPI_AWARE`). The event's *NewDPI* argument carries the new effective DPI; child controls re-scale themselves automatically. New in twinBASIC. +Raised when the control moves to a monitor with a different DPI scale, *but only* when the application is per-monitor DPI aware (`PROCESS_PER_MONITOR_DPI_AWARE`). The event's *NewDPI* argument gives the new effective DPI; child controls re-scale themselves automatically. New in twinBASIC. Syntax: *object*\_**DPIChange**( *NewDPI* **As Long** ) @@ -1055,7 +1055,7 @@ Syntax: *object*\_**Paint**( ) ### PreKeyDown {: .no_toc } -Raised for every key press anywhere on the **UserControl** or any of its descendants, *before* the focused child sees it — so handlers can swallow the keystroke. Requires [**PreKeyEvents**](#prekeyevents) **True**. Not raised when [**Windowless**](#windowless) is **True**. New in twinBASIC. +Raised for every key press anywhere on the **UserControl** or any of its descendants, *before* the focused child sees it — so handlers can consume the keystroke. Requires [**PreKeyEvents**](#prekeyevents) **True**. Not raised when [**Windowless**](#windowless) is **True**. New in twinBASIC. Syntax: *object*\_**PreKeyDown**( *KeyCode* **As Integer**, *Shift* **As Integer** ) @@ -1074,7 +1074,7 @@ Raised when the host hands the control a property bag containing previously save Syntax: *object*\_**ReadProperties**( *PropBag* **As PropertyBag** ) *PropBag* -: The host-supplied [**PropertyBag**](../../VBRUN/PropertyBag/) carrying the persisted values. +: The host-supplied [**PropertyBag**](../../VBRUN/PropertyBag/) containing the persisted values. ### Resize {: .no_toc } @@ -1110,7 +1110,7 @@ Syntax: *object*\_**VerbInvoked**( *Verb* **As String** ) ### WriteProperties {: .no_toc } -Raised when the host asks the control to persist its current state — design-time saves and host-driven serialisation. The handler writes each persistent value to *PropBag* through **WriteProperty**, which takes a key, the value, and (optionally) the same default the [**ReadProperties**](#readproperties) handler used so that round-trip defaults are not written. Only raised when at least one call to [**PropertyChanged**](#propertychanged) has happened since the last save. +Raised when the host asks the control to persist its current state — design-time saves and host-initiated serialisation. The handler writes each persistent value to *PropBag* through **WriteProperty**, which takes a key, the value, and (optionally) the same default the [**ReadProperties**](#readproperties) handler used so that round-trip defaults are not written. Only raised when at least one call to [**PropertyChanged**](#propertychanged) has happened since the last save. Syntax: *object*\_**WriteProperties**( *PropBag* **As PropertyBag** ) diff --git a/docs/Reference/VB/VScrollBar/index.md b/docs/Reference/VB/VScrollBar/index.md index 292bc20..17b6c1f 100644 --- a/docs/Reference/VB/VScrollBar/index.md +++ b/docs/Reference/VB/VScrollBar/index.md @@ -60,7 +60,7 @@ The scroll bar produces value changes through four kinds of user input: | Drag the thumb | continuous | [**Scroll**](#scroll) during drag, [**Change**](#change) on release | | Press **Home** / **End** | jumps to **Min** / **Max** | [**Change**](#change) | -Both [**SmallChange**](#smallchange) and [**LargeChange**](#largechange) default to `1`. [**LargeChange**](#largechange) also drives the visible height of the thumb relative to the track, so larger values produce a chunkier thumb. +Both [**SmallChange**](#smallchange) and [**LargeChange**](#largechange) default to `1`. [**LargeChange**](#largechange) also controls the visible height of the thumb relative to the track, so larger values produce a chunkier thumb. ## Change versus Scroll @@ -345,7 +345,7 @@ Syntax: *object*\_**GotFocus**( ) ### Initialize {: .no_toc } -Raised once, after the underlying window has been created and the scroll bar is wired up to its Win32 range, but before the scroll bar is first painted. Useful for last-minute setup that needs the underlying handle. +Raised once, after the underlying window has been created and the scroll bar is connected to its Win32 range, but before the scroll bar is first painted. Useful for last-minute setup that needs the underlying handle. Syntax: *object*\_**Initialize**( ) diff --git a/docs/Reference/VBA/Compilation/CurrentComponentName.md b/docs/Reference/VBA/Compilation/CurrentComponentName.md index ef1ae8a..b7c83cd 100644 --- a/docs/Reference/VBA/Compilation/CurrentComponentName.md +++ b/docs/Reference/VBA/Compilation/CurrentComponentName.md @@ -13,7 +13,7 @@ Syntax: **CurrentComponentName** [ **()** ] The value identifies the source unit — the **Module**, **Class**, **Form**, or other component — that lexically contains the call site. > [!NOTE] -> **CurrentComponentName** is a compile-time intrinsic: the literal string is baked into the compiled code at the point of the call. It does not change at run time, even when the call is reached through a forwarded or inherited member. +> **CurrentComponentName** is a compile-time intrinsic: the literal string is embedded in the compiled code at the point of the call. It does not change at run time, even when the call is reached through a forwarded or inherited member. ### Example diff --git a/docs/Reference/VBA/Compilation/CurrentProjectName.md b/docs/Reference/VBA/Compilation/CurrentProjectName.md index 9b28965..7c1e5e9 100644 --- a/docs/Reference/VBA/Compilation/CurrentProjectName.md +++ b/docs/Reference/VBA/Compilation/CurrentProjectName.md @@ -13,7 +13,7 @@ Syntax: **CurrentProjectName** [ **()** ] The value is the name of the project (executable or library) that owns the call site. > [!NOTE] -> **CurrentProjectName** is a compile-time intrinsic — the literal string is baked into the compiled code from the project's metadata at the point of the call. +> **CurrentProjectName** is a compile-time intrinsic — the literal string is embedded in the compiled code from the project's metadata at the point of the call. ### Example diff --git a/docs/Reference/VBA/Conversion/index.md b/docs/Reference/VBA/Conversion/index.md index efe2099..bde6525 100644 --- a/docs/Reference/VBA/Conversion/index.md +++ b/docs/Reference/VBA/Conversion/index.md @@ -20,7 +20,7 @@ Dim Amount As Currency Amount = CCur("1,234.56") ' parses with the local decimal separator ``` -Two further constructors return a **Variant** whose subtype is fixed: [**CVDate**](CVDate) builds a **Variant** of subtype **Date** (kept for compatibility with code written before **Date** became an intrinsic type), and [**CVErr**](CVErr) builds a **Variant** of subtype **Error** carrying a chosen error number — the canonical way for a **Variant**-returning function to signal "this call failed with this error code" without raising a run-time error. +Two further constructors return a **Variant** whose subtype is fixed: [**CVDate**](CVDate) builds a **Variant** of subtype **Date** (kept for compatibility with code written before **Date** became an intrinsic type), and [**CVErr**](CVErr) builds a **Variant** of subtype **Error** containing a chosen error number — the canonical way for a **Variant**-returning function to signal "this call failed with this error code" without raising a run-time error. ## Generic conversion diff --git a/docs/Reference/VBA/ErrObject/Clear.md b/docs/Reference/VBA/ErrObject/Clear.md index 7b00142..02943c5 100644 --- a/docs/Reference/VBA/ErrObject/Clear.md +++ b/docs/Reference/VBA/ErrObject/Clear.md @@ -27,7 +27,7 @@ This example uses **Err.Clear** to reset the **Err** object's numeric properties ```tb Dim result(10) As Integer ' Declare an array whose elements - ' will overflow easily. + ' will overflow. Dim idx As Long On Error Resume Next ' Defer error trapping. Do Until idx = 10 diff --git a/docs/Reference/VBA/ErrObject/Raise.md b/docs/Reference/VBA/ErrObject/Raise.md index 3c3ee97..635594f 100644 --- a/docs/Reference/VBA/ErrObject/Raise.md +++ b/docs/Reference/VBA/ErrObject/Raise.md @@ -28,7 +28,7 @@ Syntax: **Err**.**Raise** *number* [ **,** *source* [ **,** *description* [ **,* All of the arguments are optional except *number*. If you call **Raise** without specifying some arguments, and the corresponding properties of the **Err** object still hold values from an earlier error, those values serve as the values for your error. -**Raise** is preferred over the [**Error**](../../Core/Error) statement when generating run-time errors, particularly inside class modules: the **Err** object carries richer information than the **Error** statement can supply. With **Raise** the source that generated the error can be specified in the [**Source**](Source) property, online Help for the error can be referenced through [**HelpFile**](HelpFile) and [**HelpContext**](HelpContext), and so on. +**Raise** is preferred over the [**Error**](../../Core/Error) statement when generating run-time errors, particularly inside class modules: the **Err** object holds richer information than the **Error** statement can supply. With **Raise** the source that generated the error can be specified in the [**Source**](Source) property, online Help for the error can be referenced through [**HelpFile**](HelpFile) and [**HelpContext**](HelpContext), and so on. ### Example diff --git a/docs/Reference/VBA/ErrObject/Source.md b/docs/Reference/VBA/ErrObject/Source.md index d9498e8..08cc371 100644 --- a/docs/Reference/VBA/ErrObject/Source.md +++ b/docs/Reference/VBA/ErrObject/Source.md @@ -28,7 +28,7 @@ When an unexpected error occurs in your code, the **Source** property is automat This example assigns the programmatic ID of an Automation object to the variable `myObjectID`, and then assigns that to the **Source** property of the **Err** object when it generates an error with the [**Raise**](Raise) method. -When handling errors, you should not rely on the **Source** property (or any **Err** properties other than [**Number**](Number)) for control flow. The intended use of properties other than **Number** is to display rich information to an end user when you can't handle an error. +When handling errors, you should not rely on the **Source** property (or any **Err** properties other than [**Number**](Number)) for control flow. The intended use of properties other than **Number** is to display detailed information to an end user when you can't handle an error. ```tb Dim myObjectID As String, myHelpFile As String, myHelpContext As Long diff --git a/docs/Reference/VBA/HiddenModule/GetDeclaredTypeClsid.md b/docs/Reference/VBA/HiddenModule/GetDeclaredTypeClsid.md index ac83080..f75683e 100644 --- a/docs/Reference/VBA/HiddenModule/GetDeclaredTypeClsid.md +++ b/docs/Reference/VBA/HiddenModule/GetDeclaredTypeClsid.md @@ -13,7 +13,7 @@ Syntax: **GetDeclaredTypeClsid(Of** *T* **)()** **As String** *T* : *required* The type to query for. Typically a coclass declared with the **CoClassId** attribute or imported from a type library. -The CLSID is returned in registry format (`{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`). The lookup happens at compile time and the result is baked into the generated code as a string literal — there is no run-time call. +The CLSID is returned in registry format (`{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`). The lookup happens at compile time and the result is stored in the generated code as a string literal — there is no run-time call. Returns an empty string if the type has no associated CLSID. diff --git a/docs/Reference/VBA/HiddenModule/GetDeclaredTypeEventIid.md b/docs/Reference/VBA/HiddenModule/GetDeclaredTypeEventIid.md index 026ac6d..f93db4f 100644 --- a/docs/Reference/VBA/HiddenModule/GetDeclaredTypeEventIid.md +++ b/docs/Reference/VBA/HiddenModule/GetDeclaredTypeEventIid.md @@ -13,7 +13,7 @@ Syntax: **GetDeclaredTypeEventIid(Of** *T* **)()** **As String** *T* : *required* The type to query for. Typically a coclass that exposes events via the **EventInterfaceId** attribute or imported from a type library. -The IID is returned in registry format (`{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`). The lookup happens at compile time and the result is baked into the generated code as a string literal — there is no run-time call. +The IID is returned in registry format (`{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`). The lookup happens at compile time and the result is stored in the generated code as a string literal — there is no run-time call. Returns an empty string if the type has no associated event interface. diff --git a/docs/Reference/VBA/HiddenModule/GetDeclaredTypeIid.md b/docs/Reference/VBA/HiddenModule/GetDeclaredTypeIid.md index c80d5fd..8af2359 100644 --- a/docs/Reference/VBA/HiddenModule/GetDeclaredTypeIid.md +++ b/docs/Reference/VBA/HiddenModule/GetDeclaredTypeIid.md @@ -13,7 +13,7 @@ Syntax: **GetDeclaredTypeIid(Of** *T* **)()** **As String** *T* : *required* The type to query for. Typically an interface declared with the **InterfaceId** attribute or imported from a type library. -The IID is returned in registry format (`{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`). The lookup happens at compile time and the result is baked into the generated code as a string literal — there is no run-time call. +The IID is returned in registry format (`{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`). The lookup happens at compile time and the result is stored in the generated code as a string literal — there is no run-time call. Useful when calling [**vbaCastObj**](vbaCastObj) or any API that takes an interface IID as a string. diff --git a/docs/Reference/VBA/HiddenModule/GetDeclaredTypeProgId.md b/docs/Reference/VBA/HiddenModule/GetDeclaredTypeProgId.md index c04cebb..9ed619c 100644 --- a/docs/Reference/VBA/HiddenModule/GetDeclaredTypeProgId.md +++ b/docs/Reference/VBA/HiddenModule/GetDeclaredTypeProgId.md @@ -13,7 +13,7 @@ Syntax: **GetDeclaredTypeProgId(Of** *T* **)()** **As String** *T* : *required* The type to query for. Typically a coclass declared with the **CoClassId** attribute or imported from a type library. -The ProgID is the human-readable name (`Application.Object`, `Scripting.Dictionary`, ...) that matches *T*'s CLSID in the registry. The lookup happens at compile time and the result is baked into the generated code as a string literal — there is no run-time call. +The ProgID is the human-readable name (`Application.Object`, `Scripting.Dictionary`, ...) that matches *T*'s CLSID in the registry. The lookup happens at compile time and the result is stored in the generated code as a string literal — there is no run-time call. Returns an empty string if the type has no associated ProgID. diff --git a/docs/Reference/VBA/HiddenModule/index.md b/docs/Reference/VBA/HiddenModule/index.md index 7bed589..d4c7709 100644 --- a/docs/Reference/VBA/HiddenModule/index.md +++ b/docs/Reference/VBA/HiddenModule/index.md @@ -11,7 +11,7 @@ has_toc: false The **(Default)** module — known internally as **\_HiddenModule** — gathers together the unqualified intrinsic procedures that the compiler emits calls into and that are also callable directly: raw-memory helpers, atomic operations, compile-time reflection, codegen and stack-inspection primitives, and a long tail of runtime utilities. Members of this module are referenced without a qualifier, the same way **MsgBox** and **CStr** are. -Most of these procedures are deliberately hidden from IntelliSense and exist for advanced or low-level use; reach for them only when the higher-level alternatives in **[Math](../Math/)**, **[Strings](../Strings/)**, **[Information](../Information/)**, or **[Interaction](../Interaction/)** don't cover the case. Several have additional internal-only members that are not listed here at all. +Most of these procedures are deliberately hidden from IntelliSense and exist for advanced or low-level use; use them only when the higher-level alternatives in **[Math](../Math/)**, **[Strings](../Strings/)**, **[Information](../Information/)**, or **[Interaction](../Interaction/)** don't cover the case. Several have additional internal-only members that are not listed here at all. The pointer functions [**ObjPtr**](../Information/ObjPtr), [**StrPtr**](../Information/StrPtr), and [**VarPtr**](../Information/VarPtr) and the [**Array**](../Information/Array) constructor are documented under the [**Information**](../Information/) module; [**Input**](../FileSystem/Input), [**InputB**](../FileSystem/InputB), and [**Width**](../FileSystem/Width) under [**FileSystem**](../FileSystem/). @@ -108,7 +108,7 @@ A handful of intrinsics ask questions about the surrounding type without running ## IGetMessageHook interface -The **IGetMessageHook** interface taps into the Windows message stream for a chosen window — and optionally its descendants — and forwards messages of a chosen type to a user-supplied callback. Obtain an instance with [**RuntimeCreateGetMessageHook**](RuntimeCreateGetMessageHook); wire up callbacks with [**RegisterMessage**](RegisterMessage); then call [**Start**](Start) to activate every registered subscription, and [**Stop**](Stop) to remove them. +The **IGetMessageHook** interface taps into the Windows message stream for a chosen window — and optionally its descendants — and forwards messages of a chosen type to a user-supplied callback. Obtain an instance with [**RuntimeCreateGetMessageHook**](RuntimeCreateGetMessageHook); connect callbacks with [**RegisterMessage**](RegisterMessage); then call [**Start**](Start) to activate every registered subscription, and [**Stop**](Stop) to remove them. The interface inherits directly from **stdole.IUnknown** (it is not dispatch-based), and the callbacks supplied to **RegisterMessage** are typed as [**GetMessageHookHelper.GetMessageHandler**](#getmessagehandler). @@ -165,7 +165,7 @@ End Type ### HookPOINT -A 2D point with **Long** coordinates, used by [**HookMSG**](#hookmsg) to carry the cursor position. +A 2D point with **Long** coordinates, used by [**HookMSG**](#hookmsg) to hold the cursor position. ```tb Type HookPOINT diff --git a/docs/Reference/VBA/Interaction/CallByName.md b/docs/Reference/VBA/Interaction/CallByName.md index f5b3fbe..ddb8134 100644 --- a/docs/Reference/VBA/Interaction/CallByName.md +++ b/docs/Reference/VBA/Interaction/CallByName.md @@ -29,7 +29,7 @@ The return value is a **Variant** containing whatever the call returned. For met ### Example -These three calls drive a control by name. The first sets its **MousePointer** property to the crosshair cursor, the second reads the same property back out, and the third invokes the **Move** method to reposition the control. +These three calls use **CallByName** to operate on a control by name. The first sets its **MousePointer** property to the crosshair cursor, the second reads the same property back out, and the third invokes the **Move** method to reposition the control. ```tb CallByName Text1, "MousePointer", vbLet, vbCrosshair diff --git a/docs/Reference/VBA/Interaction/CreateObject.md b/docs/Reference/VBA/Interaction/CreateObject.md index a4c4507..9698384 100644 --- a/docs/Reference/VBA/Interaction/CreateObject.md +++ b/docs/Reference/VBA/Interaction/CreateObject.md @@ -40,7 +40,7 @@ This example creates a Microsoft Excel **Application** object, makes it visible, Dim XlApp As Object Set XlApp = CreateObject("Excel.Application") XlApp.Visible = True -' ... drive Excel through XlApp ... +' ... work with Excel through XlApp ... XlApp.Quit Set XlApp = Nothing ``` diff --git a/docs/Reference/VBA/Interaction/GetObject.md b/docs/Reference/VBA/Interaction/GetObject.md index d489ad0..e0810a7 100644 --- a/docs/Reference/VBA/Interaction/GetObject.md +++ b/docs/Reference/VBA/Interaction/GetObject.md @@ -65,7 +65,7 @@ On Error GoTo 0 Set MyXl = GetObject("C:\Reports\MyTest.xls") MyXl.Application.Visible = True MyXl.Parent.Windows(1).Visible = True -' ... drive the workbook through MyXl ... +' ... work with the workbook through MyXl ... If ExcelWasNotRunning Then MyXl.Application.Quit Set MyXl = Nothing diff --git a/docs/Reference/VBA/Interaction/SendKeys.md b/docs/Reference/VBA/Interaction/SendKeys.md index 05e2509..813508b 100644 --- a/docs/Reference/VBA/Interaction/SendKeys.md +++ b/docs/Reference/VBA/Interaction/SendKeys.md @@ -66,7 +66,7 @@ To repeat a key, use the form `{key number}` — for example, `"{LEFT 42}"` to p ### Example -This example uses [**Shell**](Shell) to launch the Windows Calculator and **SendKeys** to drive it: it adds the numbers 1 through 100, takes the running total, then closes Calculator with ALT+F4. Because [**AppActivate**](AppActivate) changes the focus, the example must be run, not single-stepped. +This example uses [**Shell**](Shell) to launch the Windows Calculator and **SendKeys** to control it: it adds the numbers 1 through 100, takes the running total, then closes Calculator with ALT+F4. Because [**AppActivate**](AppActivate) changes the focus, the example must be run, not single-stepped. ```tb Dim TaskId As Double, I As Long diff --git a/docs/Reference/VBA/TbExpressionService/Compile.md b/docs/Reference/VBA/TbExpressionService/Compile.md index 26375ae..904631a 100644 --- a/docs/Reference/VBA/TbExpressionService/Compile.md +++ b/docs/Reference/VBA/TbExpressionService/Compile.md @@ -22,7 +22,7 @@ The return value is an [**ITbExpression**](./#itbexpression-interface). Calling Symbols referenced in *expression* — function names, object members, properties — are resolved against the binders registered with *service* at the time of the call. At least one binder must be registered before **Compile** is called; the most common starting point is [**AddStdLibraryBinder**](AddStdLibraryBinder), which exposes the standard runtime library. -Compilation is the relatively expensive step; evaluation reuses the compiled form. When a piece of source text is going to drive repeated evaluation — a formula column refreshed every row, a watch expression sampled in a debugger — compile it once and keep the **ITbExpression** around. +Compilation is the relatively expensive step; evaluation reuses the compiled form. When a piece of source text will be used for repeated evaluation — a formula column refreshed every row, a watch expression sampled in a debugger — compile it once and keep the **ITbExpression** around. If *expression* is malformed, or references a symbol that no registered binder can resolve, **Compile** raises a run-time error. diff --git a/docs/Reference/VBA/TbExpressionService/index.md b/docs/Reference/VBA/TbExpressionService/index.md index 5042475..043386e 100644 --- a/docs/Reference/VBA/TbExpressionService/index.md +++ b/docs/Reference/VBA/TbExpressionService/index.md @@ -53,7 +53,7 @@ For full control over symbol resolution — for example, to look up names dynami ## TbExpressionService class -`New TbExpressionService` returns the default interface, **ITbExpressionService**. Multiple services can coexist; each carries its own list of binders and is independent of the others. +`New TbExpressionService` returns the default interface, **ITbExpressionService**. Multiple services can coexist; each has its own list of binders and is independent of the others. ### Members diff --git a/docs/Reference/VBRUN/AsyncProperty/BytesMax.md b/docs/Reference/VBRUN/AsyncProperty/BytesMax.md index 2233dd7..bb80028 100644 --- a/docs/Reference/VBRUN/AsyncProperty/BytesMax.md +++ b/docs/Reference/VBRUN/AsyncProperty/BytesMax.md @@ -13,7 +13,7 @@ Syntax: *object*.**BytesMax** *object* : *required* An object expression that evaluates to an **AsyncProperty** object. -Used together with [**BytesRead**](BytesRead) to drive a progress indicator during an **AsyncReadProgress** event. **BytesMax** can be zero when the server has not advertised a content length — for example with an HTTP chunked transfer — in which case the total size is not known until the read completes and a determinate progress bar cannot be shown. +Used together with [**BytesRead**](BytesRead) to update a progress indicator during an **AsyncReadProgress** event. **BytesMax** can be zero when the server has not advertised a content length — for example with an HTTP chunked transfer — in which case the total size is not known until the read completes and a determinate progress bar cannot be shown. ### See Also diff --git a/docs/Reference/VBRUN/AsyncProperty/StatusCode.md b/docs/Reference/VBRUN/AsyncProperty/StatusCode.md index 423bc0c..9c97b54 100644 --- a/docs/Reference/VBRUN/AsyncProperty/StatusCode.md +++ b/docs/Reference/VBRUN/AsyncProperty/StatusCode.md @@ -13,7 +13,7 @@ Syntax: *object*.**StatusCode** *object* : *required* An object expression that evaluates to an **AsyncProperty** object. -The value identifies the step the read is currently on — `vbAsyncStatusCodeFindingResource`, `vbAsyncStatusCodeConnecting`, `vbAsyncStatusCodeBeginDownloadData`, `vbAsyncStatusCodeEndDownloadData`, and so on. `vbAsyncStatusCodeError` (0) indicates that the read failed; the [**Status**](Status) property carries the matching human-readable description. +The value identifies the step the read is currently on — `vbAsyncStatusCodeFindingResource`, `vbAsyncStatusCodeConnecting`, `vbAsyncStatusCodeBeginDownloadData`, `vbAsyncStatusCodeEndDownloadData`, and so on. `vbAsyncStatusCodeError` (0) indicates that the read failed; the [**Status**](Status) property contains the matching human-readable description. ### See Also diff --git a/docs/Reference/VBRUN/AsyncProperty/index.md b/docs/Reference/VBRUN/AsyncProperty/index.md index 1777ec2..e5e3985 100644 --- a/docs/Reference/VBRUN/AsyncProperty/index.md +++ b/docs/Reference/VBRUN/AsyncProperty/index.md @@ -10,7 +10,7 @@ has_toc: false # AsyncProperty class -The **AsyncProperty** object carries the results of an asynchronous read started with **UserControl.AsyncRead**. It is passed to the **AsyncReadComplete** and **AsyncReadProgress** events, where it identifies which read this notification refers to, reports how far the download has got, and — once complete — supplies the downloaded value. Every property is read-only: the runtime fills the object in before raising the event. +The **AsyncProperty** object holds the results of an asynchronous read started with **UserControl.AsyncRead**. It is passed to the **AsyncReadComplete** and **AsyncReadProgress** events, where it identifies which read this notification refers to, reports how far the download has got, and — once complete — supplies the downloaded value. Every property is read-only: the runtime fills the object in before raising the event. ## Identifying the read diff --git a/docs/Reference/VBRUN/DataObject/Files.md b/docs/Reference/VBRUN/DataObject/Files.md index 152908d..e4b62e6 100644 --- a/docs/Reference/VBRUN/DataObject/Files.md +++ b/docs/Reference/VBRUN/DataObject/Files.md @@ -6,7 +6,7 @@ permalink: /tB/Packages/VBRUN/DataObject/Files # Files {: .no_toc } -Returns a [**DataObjectFiles**](DataObjectFiles) collection holding the file paths the **DataObject** carries. +Returns a [**DataObjectFiles**](DataObjectFiles) collection holding the file paths the **DataObject** contains. Syntax: *object*.**Files** diff --git a/docs/Reference/VBRUN/DataObject/GetDataByName.md b/docs/Reference/VBRUN/DataObject/GetDataByName.md index cda25e1..fa89654 100644 --- a/docs/Reference/VBRUN/DataObject/GetDataByName.md +++ b/docs/Reference/VBRUN/DataObject/GetDataByName.md @@ -17,7 +17,7 @@ Syntax: *object*.**GetDataByName(** *Format* **)** : *required* A **String** giving the name of the format to read back — typically the name a custom clipboard format was registered under with `RegisterClipboardFormat`. If the **DataObject** does not contain data in *Format*, the result is **Empty**; check first with [**GetFormatByName**](GetFormatByName) when the format may not be present. > [!NOTE] -> **GetDataByName** is a twinBASIC addition; it has no equivalent in VB6. Use it when the consumer side knows the format only by its registered name and does not have the corresponding numeric identifier handy. For the standard built-in formats, [**GetData**](GetData) with a **ClipboardConstants** value is more direct. +> **GetDataByName** is a twinBASIC addition; it has no equivalent in VB6. Use it when the consumer side knows the format only by its registered name and does not have the corresponding numeric identifier available. For the standard built-in formats, [**GetData**](GetData) with a **ClipboardConstants** value is more direct. ### Example diff --git a/docs/Reference/VBRUN/DataObject/index.md b/docs/Reference/VBRUN/DataObject/index.md index eb128fb..b2a8a2a 100644 --- a/docs/Reference/VBRUN/DataObject/index.md +++ b/docs/Reference/VBRUN/DataObject/index.md @@ -44,7 +44,7 @@ Next F ## Files -When a **DataObject** carries a list of file paths — for example, the payload of a Windows shell drag-and-drop — [**Files**](Files) returns a [**DataObjectFiles**](DataObjectFiles) collection holding each path as a **String**. +When a **DataObject** contains a list of file paths — for example, the payload of a Windows shell drag-and-drop — [**Files**](Files) returns a [**DataObjectFiles**](DataObjectFiles) collection holding each path as a **String**. ```tb Dim Path As Variant diff --git a/docs/Reference/VBRUN/ErrorContext/index.md b/docs/Reference/VBRUN/ErrorContext/index.md index 29b6d13..aaabc3b 100644 --- a/docs/Reference/VBRUN/ErrorContext/index.md +++ b/docs/Reference/VBRUN/ErrorContext/index.md @@ -12,7 +12,7 @@ has_toc: false An **ErrorContext** object captures everything the runtime knows about a run-time error: its identity ([**Number**](#number), [**Description**](#description), [**Source**](#source)), its help references ([**HelpFile**](#helpfile), [**HelpContext**](#helpcontext)), the operating-system error code at the time it was raised ([**LastDLLError**](#lastdllerror)), the [**State**](#state) of the error-handling machinery, and a snapshot of the [**Callstack**](#callstack) from the moment of the failure. It is twinBASIC's structured counterpart to the simpler [**Err**](../../../Modules/ErrObject) object. -The error-identity properties (**Number**, **Description**, **Source**, **HelpFile**, **HelpContext**, **LastDLLError**) carry the same meaning here as on the **Err** object — see the [**ErrObject**](../../../Modules/ErrObject) module for a discussion of each. **State** and **Callstack** are unique to **ErrorContext** and reflect the structured error-handling machinery that has no equivalent on the legacy **Err** object. +The error-identity properties (**Number**, **Description**, **Source**, **HelpFile**, **HelpContext**, **LastDLLError**) have the same meaning here as on the **Err** object — see the [**ErrObject**](../../../Modules/ErrObject) module for a discussion of each. **State** and **Callstack** are unique to **ErrorContext** and reflect the structured error-handling machinery that has no equivalent on the legacy **Err** object. ## Members @@ -102,7 +102,7 @@ Syntax: *object*.**State** [ **=** *value* ] *object* : *required* An object expression that evaluates to an **ErrorContext** object. -The runtime updates **State** as control flows through error handlers, **Try**/**Catch**/**Finally** blocks, and the various propagation paths. Reading the property tells diagnostic code which construct it is being invoked from. Assigning to it overrides the runtime's idea of what to do next — a deliberately advanced operation, useful mainly to diagnostic tools and to libraries that orchestrate their own error flow. +The runtime updates **State** as control flows through error handlers, **Try**/**Catch**/**Finally** blocks, and the various propagation paths. Reading the property tells diagnostic code which construct it is being invoked from. Assigning to it overrides the runtime's idea of what to do next — a deliberately advanced operation, useful mainly to diagnostic tools and to libraries that manage their own error flow. The **OnErrorStatus** enumeration values are: diff --git a/docs/Reference/VBRUN/index.md b/docs/Reference/VBRUN/index.md index 68d622a..0218bbe 100644 --- a/docs/Reference/VBRUN/index.md +++ b/docs/Reference/VBRUN/index.md @@ -14,14 +14,14 @@ The VBRUN built-in package collects twinBASIC's runtime-only types: the ambient, ## Classes - [AmbientProperties](AmbientProperties) -- read-only object describing the host container's appearance, locale, and design / run-time mode for an embedded control -- [AsyncProperty](AsyncProperty) -- event-argument object that identifies an asynchronous **UserControl.AsyncRead** request and carries the resulting value +- [AsyncProperty](AsyncProperty) -- event-argument object that identifies an asynchronous **UserControl.AsyncRead** request and delivers the resulting value - [ContainedControls](ContainedControls) -- read-only collection of the controls a consumer placed inside a control-container **UserControl** - [DataMembers](DataMembers) -- collection of named data-source members advertised at design time to data-binding consumers - [DataObject](DataObject) -- clipboard / OLE drag-and-drop container that holds one payload in multiple clipboard formats - [ErrorCallstack](ErrorCallstack) -- snapshot of the call stack at the moment a run-time error was raised, exposed as a sequence of [**ErrorStackFrame**](ErrorStackFrame) items - [ErrorContext](ErrorContext) -- structured error object — number, description, source, help, OS error, state, and call stack - [ErrorStackFrame](ErrorStackFrame) -- single procedure on an [**ErrorCallstack**](ErrorCallstack) — its project, module, and procedure names -- [Hyperlink](Hyperlink) -- runtime hand-off for browser-style navigation; controls call **UserControl.Hyperlink.NavigateTo** to ask the host to load a target +- [Hyperlink](Hyperlink) -- runtime bridge for browser-style navigation; controls call **UserControl.Hyperlink.NavigateTo** to ask the host to load a target - [ParentControls](ParentControls) -- collection of the **UserControl**'s siblings in its container, optionally wrapped in their host **Extender** - [PropertyBag](PropertyBag) -- creatable key / value store for persisting an object's state — used by **UserControl** save / load and serialisable as a single byte array diff --git a/docs/Reference/WebView2/Enumerations/index.md b/docs/Reference/WebView2/Enumerations/index.md index 0d57d46..8878113 100644 --- a/docs/Reference/WebView2/Enumerations/index.md +++ b/docs/Reference/WebView2/Enumerations/index.md @@ -7,7 +7,7 @@ has_toc: false # Enumerations -The `wv2…` enumerations used by the **WebView2** control's properties, methods, and event arguments. Their members carry the constant value defined by the underlying `COREWEBVIEW2_*` enumeration in the Edge WebView2 runtime — the comment beside each `Enum` in the source records the runtime name. +The `wv2…` enumerations used by the **WebView2** control's properties, methods, and event arguments. Their members have the constant value defined by the underlying `COREWEBVIEW2_*` enumeration in the Edge WebView2 runtime — the comment beside each `Enum` in the source records the runtime name. | Enumeration | Used by | |-------------|---------| diff --git a/docs/Reference/WebView2/Enumerations/wv2KeyEventKind.md b/docs/Reference/WebView2/Enumerations/wv2KeyEventKind.md index 1273bd9..dac90e1 100644 --- a/docs/Reference/WebView2/Enumerations/wv2KeyEventKind.md +++ b/docs/Reference/WebView2/Enumerations/wv2KeyEventKind.md @@ -7,7 +7,7 @@ permalink: /tB/Packages/WebView2/Enumerations/wv2KeyEventKind # wv2KeyEventKind {: .no_toc } -The kind of accelerator-key keyboard message that fired the [**AcceleratorKeyPressed**](../WebView2/#acceleratorkeypressed) event, carried as its **ByRef** `KeyState` argument. Mirrors the `COREWEBVIEW2_KEY_EVENT_KIND` enumeration. +The kind of accelerator-key keyboard message that fired the [**AcceleratorKeyPressed**](../WebView2/#acceleratorkeypressed) event, passed as its **ByRef** `KeyState` argument. Mirrors the `COREWEBVIEW2_KEY_EVENT_KIND` enumeration. | Constant | Value | Description | |----------|-------|-------------| diff --git a/docs/Reference/WebView2/WebView2/EnvironmentOptions.md b/docs/Reference/WebView2/WebView2/EnvironmentOptions.md index 3107a4b..1454d03 100644 --- a/docs/Reference/WebView2/WebView2/EnvironmentOptions.md +++ b/docs/Reference/WebView2/WebView2/EnvironmentOptions.md @@ -9,7 +9,7 @@ has_toc: false # WebView2EnvironmentOptions class {: .no_toc } -Carries the host's pre-creation configuration for the underlying WebView2 environment — folder layout, additional command-line arguments, locale, and a small handful of policy switches. Surfaces on every [**WebView2**](.) control as its **EnvironmentOptions** property; the control instantiates one automatically before raising the [**Create**](.#create) event. +Carries the host's pre-creation configuration for the underlying WebView2 environment — folder layout, additional command-line arguments, locale, and a few policy switches. Surfaces on every [**WebView2**](.) control as its **EnvironmentOptions** property; the control instantiates one automatically before raising the [**Create**](.#create) event. The fields below take effect only while the WebView2 environment is being constructed — that is, *before or during* the control's [**Create**](.#create) event. Assigning them after that point has no effect on the live environment. diff --git a/docs/Reference/WebView2/WebView2/index.md b/docs/Reference/WebView2/WebView2/index.md index 3255e76..63859af 100644 --- a/docs/Reference/WebView2/WebView2/index.md +++ b/docs/Reference/WebView2/WebView2/index.md @@ -10,7 +10,7 @@ has_toc: false A **WebView2** is a twinBASIC control that hosts the Microsoft Edge **WebView2** runtime — drop one onto a [**Form**](../../VB/Form/) and the running Edge engine renders web content inside its rectangle. Application code can navigate to URLs, run JavaScript, intercept HTTP requests, share BASIC objects with the page, post messages back and forth, and print the document to PDF. -The control wraps the underlying `ICoreWebView2*` COM interfaces and surfaces them as ordinary BASIC properties, methods, and events. Most of the work happens asynchronously inside the browser process — the control raises [**Ready**](#ready) once the WebView2 environment and controller have been created, and most members raise *"WebView2 control is not ready"* (run-time error 5) if called before then. +The control wraps the underlying `ICoreWebView2*` COM interfaces and exposes them as ordinary BASIC properties, methods, and events. Most of the work happens asynchronously inside the browser process — the control raises [**Ready**](#ready) once the WebView2 environment and controller have been created, and most members raise *"WebView2 control is not ready"* (run-time error 5) if called before then. ```tb Private Sub Form_Load() @@ -34,7 +34,7 @@ End Sub ## Lifecycle -A WebView2 control passes through three distinct phases between construction and use, each driven by an asynchronous step in the Edge runtime: +A WebView2 control passes through three distinct phases between construction and use, each triggered by an asynchronous step in the Edge runtime: | Event | When | |--------------------------------------|-------------------------------------------------------------------------------------------------------------------| @@ -69,7 +69,7 @@ To rewrite, mock, or simply observe HTTP traffic from the page, register a URL f Properties ---------- -The control inherits the standard size, layout, and focus surface from `BaseControlFocusableNoFont`. The bulk of the WebView2-specific surface is split between settings that map to the Edge runtime, capability-flags that probe the loaded runtime version, and runtime-only state. +The control inherits the standard size, layout, and focus members from `BaseControlFocusableNoFont`. The bulk of the WebView2-specific members are split between settings that map to the Edge runtime, capability-flags that probe the loaded runtime version, and runtime-only state. ### AdditionalAllowedFrameAncestors {: .no_toc } @@ -79,7 +79,7 @@ Additional `Content-Security-Policy: frame-ancestors` directives allowed when th ### Anchors {: .no_toc } -The container-edge anchors that drive automatic resizing when the parent **Form** is resized. Inherited from `BaseControlRectDockable`. +The container-edge anchors that control automatic resizing when the parent **Form** is resized. Inherited from `BaseControlRectDockable`. ### AreBrowserAcceleratorKeysEnabled {: .no_toc } @@ -455,7 +455,7 @@ Syntax: *object*.**AddWebResourceRequestedFilter** *sFilter*, *FilterContext* ### CallDevToolsProtocolMethod {: .no_toc } -Sends a Chrome DevTools Protocol message to the running Edge instance. When *CustomEventId* is provided, the runtime's reply fires the [**DevToolsProtocolResponse**](#devtoolsprotocolresponse) event carrying the same *CustomEventId* and the JSON response. +Sends a Chrome DevTools Protocol message to the running Edge instance. When *CustomEventId* is provided, the runtime's reply fires the [**DevToolsProtocolResponse**](#devtoolsprotocolresponse) event with the same *CustomEventId* and the JSON response. Syntax: *object*.**CallDevToolsProtocolMethod** *MethodName*, *ParamsAsJson* [, *CustomEventId* ] @@ -499,7 +499,7 @@ Syntax: *object*.**Drag** [ *Action* ] ### ExecuteScript {: .no_toc } -Evaluates JavaScript in the page without waiting for it to finish and without surfacing 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 you need the value. Syntax: *object*.**ExecuteScript** *jsCode* @@ -530,7 +530,7 @@ Syntax: *object*.**JsProp** ( *PropName* ) **As Variant** *PropName* : *required* A **String** containing the expression to evaluate. -Returns the result decoded from the JSON the runtime hands back — **Boolean**, **Double**, **String**, **Null**, or **Empty** (for `undefined`). Object and array results are not yet supported — accessing them raises run-time error 5. +Returns the result decoded from the JSON the runtime returns — **Boolean**, **Double**, **String**, **Null**, or **Empty** (for `undefined`). Object and array results are not yet supported — accessing them raises run-time error 5. ### JsRun {: .no_toc } @@ -554,7 +554,7 @@ Debug.Print product ' 30 ### JsRunAsync {: .no_toc } -Calls a named JavaScript function asynchronously and returns immediately with a token. When the result arrives, [**JsAsyncResult**](#jsasyncresult) fires carrying the same token. +Calls a named JavaScript function asynchronously and returns immediately with a token. When the result arrives, [**JsAsyncResult**](#jsasyncresult) fires with the same token. Syntax: *object*.**JsRunAsync** ( *FuncName*, [ *args* ] ) **As LongLong** @@ -632,7 +632,7 @@ Syntax: *object*.**NavigateCustom** *uri*, *method* [, *headers* [, *postData* [ : *optional* A **String** of `vbCrLf`-delimited `Header: value` lines. *postData* -: *optional* A **Variant** carrying the body — a **String** (encoded according to *postDataAsUTF8*) or a **Byte()** array (used verbatim). +: *optional* A **Variant** containing the body — a **String** (encoded according to *postDataAsUTF8*) or a **Byte()** array (used verbatim). *postDataAsUTF8* : *optional* A **Boolean**, default **True**. When **True** and *postData* is a **String**, the string is UTF-8-encoded before being sent. @@ -720,7 +720,7 @@ Requires [**IsWebMessageEnabled**](#iswebmessageenabled). ### PrintToPdf {: .no_toc } -Saves the current document to a PDF file. The work happens asynchronously — the result surfaces through [**PrintToPdfCompleted**](#printtopdfcompleted) or [**PrintToPdfFailed**](#printtopdffailed). Requires [**SupportsPdfFeatures**](#supportspdffeatures). +Saves the current document to a PDF file. The work happens asynchronously — the result arrives through [**PrintToPdfCompleted**](#printtopdfcompleted) or [**PrintToPdfFailed**](#printtopdffailed). Requires [**SupportsPdfFeatures**](#supportspdffeatures). Syntax: *object*.**PrintToPdf** *outputPath* [, *Orientation* [, *ScaleFactor* [, *PageWidth* [, *PageHeight* [, *MarginTop* [, *MarginBottom* [, *MarginLeft* [, *MarginRight* [, *ShouldPrintBackgrounds* [, *ShouldPrintSelectionOnly* [, *ShouldPrintHeaderAndFooter* [, *HeaderTitle* [, *FooterUri* ] ] ] ] ] ] ] ] ] ] ] ] ] @@ -855,7 +855,7 @@ Events ### AcceleratorKeyPressed {: .no_toc } -Raised when Edge detects an accelerator-style keystroke — e.g. **F1**, **Alt+**, **Ctrl+**. Set *IsHandled* to **True** to swallow the keystroke so Edge doesn't act on it. Always synchronous: cannot be deferred. +Raised when Edge detects an accelerator-style keystroke — e.g. **F1**, **Alt+**, **Ctrl+**. Set *IsHandled* to **True** to consume the keystroke so Edge doesn't act on it. Always synchronous: cannot be deferred. Syntax: *object*\_**AcceleratorKeyPressed**( *KeyState* **As** [**wv2KeyEventKind**](../Enumerations/wv2KeyEventKind), *IsExtendedKey* **As Boolean**, *WasKeyDown* **As Boolean**, *IsKeyReleased* **As Boolean**, *IsMenuKeyDown* **As Boolean**, *RepeatCount* **As Long**, *ScanCode* **As Long**, *IsHandled* **As Boolean** ) diff --git a/docs/Reference/WebView2/WebView2RequestHeaders.md b/docs/Reference/WebView2/WebView2RequestHeaders.md index dd58baf..d459237 100644 --- a/docs/Reference/WebView2/WebView2RequestHeaders.md +++ b/docs/Reference/WebView2/WebView2RequestHeaders.md @@ -10,7 +10,7 @@ has_toc: false The mutable HTTP-request-header collection for a navigation or a web-resource request. Reached two ways: -- As the **RequestHeaders** argument of the [**NavigationStarting**](WebView2/#navigationstarting) event — the headers that will be sent for the page navigation. Mutations made before the event handler returns are sent on the wire. +- As the **RequestHeaders** argument of the [**NavigationStarting**](WebView2/#navigationstarting) event — the headers that will be sent for the page navigation. Mutations made before the event handler returns are transmitted. - Through [**WebView2Request.Headers**](WebView2Request#headers) when handling a [**WebResourceRequested**](WebView2/#webresourcerequested) event. The collection is enumerable: a `For Each` loop yields one [**WebView2Header**](WebView2Header) per entry. diff --git a/docs/Reference/WebView2/index.md b/docs/Reference/WebView2/index.md index a1ddd4f..536a28d 100644 --- a/docs/Reference/WebView2/index.md +++ b/docs/Reference/WebView2/index.md @@ -13,11 +13,11 @@ The **WebView2Package** wraps the Microsoft Edge WebView2 runtime and exposes it The package is a built-in package shipped with twinBASIC. See the [WebView2 tutorials](../../../Tutorials/WebView2/) for how to reference it in your project, and worked samples. -Beyond the control itself, the package exposes a small set of wrapper objects that surface inside the control's event arguments — the request / response pair on **WebResourceRequested**, the request-header collection on **NavigationStarting**, the environment-options object configured before **Create** — together with the `wv2…` enumerations used to spell out option values. +Beyond the control itself, the package exposes a small set of wrapper objects that appear inside the control's event arguments — the request / response pair on **WebResourceRequested**, the request-header collection on **NavigationStarting**, the environment-options object configured before **Create** — together with the `wv2…` enumerations used to spell out option values. ## Classes -- [WebView2](WebView2/) -- the control: navigation, scripting, settings, deferral-aware events, and PDF / suspend / download / task-manager features driven by the underlying Edge runtime +- [WebView2](WebView2/) -- the control: navigation, scripting, settings, deferral-aware events, and PDF / suspend / download / task-manager features controlled by the underlying Edge runtime - [WebView2EnvironmentOptions](WebView2/EnvironmentOptions) -- pre-creation configuration for the WebView2 environment (user-data folder, executable folder, locale, tracking-prevention, …); reached via the control's **EnvironmentOptions** property - [WebView2Header](WebView2Header) -- one HTTP header (Name / Value); the element type yielded by header iteration - [WebView2HeadersCollection](WebView2HeadersCollection) -- enumerable wrapper used by `For Each` over request / response headers @@ -29,19 +29,19 @@ Beyond the control itself, the package exposes a small set of wrapper objects th ## Enumerations - [wv2DefaultDownloadCornerAlign](Enumerations/wv2DefaultDownloadCornerAlign) -- anchors the built-in download-progress dialog to one corner of the control -- [wv2ErrorStatus](Enumerations/wv2ErrorStatus) -- reason a navigation failed; carried by **NavigationComplete** +- [wv2ErrorStatus](Enumerations/wv2ErrorStatus) -- reason a navigation failed; reported by **NavigationComplete** - [wv2HostResourceAccessKind](Enumerations/wv2HostResourceAccessKind) -- access policy for a virtual hostname registered with **SetVirtualHostNameToFolderMapping** -- [wv2KeyEventKind](Enumerations/wv2KeyEventKind) -- the kind of accelerator-key keyboard message carried by **AcceleratorKeyPressed** -- [wv2PermissionKind](Enumerations/wv2PermissionKind) -- device or browser capability a page is asking permission to use; carried by **PermissionRequested** +- [wv2KeyEventKind](Enumerations/wv2KeyEventKind) -- the kind of accelerator-key keyboard message in **AcceleratorKeyPressed** +- [wv2PermissionKind](Enumerations/wv2PermissionKind) -- device or browser capability a page is asking permission to use; passed by **PermissionRequested** - [wv2PermissionState](Enumerations/wv2PermissionState) -- the host's decision (grant / deny / default) on a **PermissionRequested** event - [wv2PrintOrientation](Enumerations/wv2PrintOrientation) -- page orientation passed to **PrintToPdf** -- [wv2ProcessFailedKind](Enumerations/wv2ProcessFailedKind) -- which of the external WebView2 processes failed; carried by **ProcessFailed** -- [wv2ScriptDialogKind](Enumerations/wv2ScriptDialogKind) -- which JavaScript-dialog primitive is opening; carried by **ScriptDialogOpening** +- [wv2ProcessFailedKind](Enumerations/wv2ProcessFailedKind) -- which of the external WebView2 processes failed; reported by **ProcessFailed** +- [wv2ScriptDialogKind](Enumerations/wv2ScriptDialogKind) -- which JavaScript-dialog primitive is opening; passed by **ScriptDialogOpening** - [wv2WebResourceContext](Enumerations/wv2WebResourceContext) -- kind of HTTP request a filter registered with **AddWebResourceRequestedFilter** should match ## Types -- [COREWEBVIEW2_PHYSICAL_KEY_STATUS](Types/COREWEBVIEW2_PHYSICAL_KEY_STATUS) -- decoded `WM_KEYDOWN` / `WM_KEYUP` `lParam` bit-fields; surfaced via the **AcceleratorKeyPressed** event +- [COREWEBVIEW2_PHYSICAL_KEY_STATUS](Types/COREWEBVIEW2_PHYSICAL_KEY_STATUS) -- decoded `WM_KEYDOWN` / `WM_KEYUP` `lParam` bit-fields; delivered via the **AcceleratorKeyPressed** event ## Tutorials diff --git a/docs/Reference/WinEventLogLib/EventLog.md b/docs/Reference/WinEventLogLib/EventLog.md index b461d14..37284e7 100644 --- a/docs/Reference/WinEventLogLib/EventLog.md +++ b/docs/Reference/WinEventLogLib/EventLog.md @@ -37,7 +37,7 @@ Dim Log As New EventLog(Of MyEventIds, MyCategories)("MyService") Both type arguments are required at instantiation — twinBASIC does not deduce them from the *LogName* constructor argument. See the [Generics](../../../Features/Language/Generics) page for the general rules. -A class that needs to expose [**LogSuccess**](#logsuccess) / [**LogFailure**](#logfailure) / [**Register**](#register) as if those methods were its own can mix the **EventLog** surface in through [**Implements ... Via**](../../../Features/Language/Inheritance) composition — see the [composition-delegation idiom](.#composition-delegation-idiom) section on the package overview for the canonical service-class pattern. +A class that needs to expose [**LogSuccess**](#logsuccess) / [**LogFailure**](#logfailure) / [**Register**](#register) as if those methods were its own can mix the **EventLog** members in through [**Implements ... Via**](../../../Features/Language/Inheritance) composition — see the [composition-delegation idiom](.#composition-delegation-idiom) section on the package overview for the canonical service-class pattern. The package [overview](.) covers the install-then-log lifecycle, the [`[PopulateFrom("json", ...)]` message-resource convention](.#populatefrom-convention), registry layout, and the [composition-delegation idiom](.#composition-delegation-idiom). diff --git a/docs/Reference/WinEventLogLib/index.md b/docs/Reference/WinEventLogLib/index.md index 12b5f92..8e7ddc4 100644 --- a/docs/Reference/WinEventLogLib/index.md +++ b/docs/Reference/WinEventLogLib/index.md @@ -56,7 +56,7 @@ For service / long-running classes that should expose [**LogSuccess**](EventLog# ## Composition-delegation idiom -A class can mix [**EventLog**](EventLog)`(Of T1, T2)` in through twinBASIC's [`Implements ... Via`](../../../Features/Language/Inheritance) composition syntax and inherit its public surface unqualified: +A class can mix [**EventLog**](EventLog)`(Of T1, T2)` in through twinBASIC's [`Implements ... Via`](../../../Features/Language/Inheritance) composition syntax and inherit its public members unqualified: ```tb Class MyService @@ -78,9 +78,9 @@ Two things to remember: - The *T1* / *T2* type arguments must match between the `Implements` declaration and the constructor expression — the compiler enforces this. - Using `"Application\" & CurrentComponentName` as the *LogName* makes the log path automatically track the class name at compile time; renaming the class renames the source it logs to. -This is the canonical mix-in pattern for [**WinServicesLib**](../WinServicesLib/) service classes (every service class in a project that shares one set of event IDs picks up logging methods without per-class boilerplate). The same pattern works for any class that wants the [**EventLog**](EventLog) surface inline. +This is the canonical mix-in pattern for [**WinServicesLib**](../WinServicesLib/) service classes (every service class in a project that shares one set of event IDs inherits logging methods without per-class boilerplate). The same pattern works for any class that wants the [**EventLog**](EventLog) members available directly. -A class can use `Implements ... Via` on [**EventLog**](EventLog)`(Of T1, T2)` only **once**. When several classes in the same project need to share a logging surface, declare a single module with one event-ID enum and one category enum and `Implements ... Via` against that pair from every class. Multiple unrelated message tables are still possible — they just have to be reached through explicitly-named [**EventLog**](EventLog) fields rather than the `Implements ... Via` shortcut. +A class can use `Implements ... Via` on [**EventLog**](EventLog)`(Of T1, T2)` only **once**. When several classes in the same project need to share logging, declare a single module with one event-ID enum and one category enum and `Implements ... Via` against that pair from every class. Multiple unrelated message tables are still possible — they just have to be reached through explicitly-named [**EventLog**](EventLog) fields rather than the `Implements ... Via` shortcut. ## Message resources @@ -107,7 +107,7 @@ End Module The five [`[PopulateFrom]`](../../Core/Attributes#populatefrom) arguments are: the resource format (`"json"`), the project-relative path to the file, the JSON array to read entries from (`"events"` for the events stub, `"categories"` for the categories stub), the field name supplying each enum member's identifier, and the field name supplying its numeric value. -`Resources/MESSAGETABLE/Strings.json` carries one entry per event and one per category. Each entry has three fields — a numeric `id`, an enum-member `name`, and the per-locale message text under an `LCID_XXXX` key: +`Resources/MESSAGETABLE/Strings.json` has one entry per event and one per category. Each entry has three fields — a numeric `id`, an enum-member `name`, and the per-locale message text under an `LCID_XXXX` key: ```json { @@ -131,7 +131,7 @@ Dim Log As New EventLog(Of MESSAGETABLE.EVENTS, MESSAGETABLE.CATEGORIES)("Applic Log.LogSuccess service_started, status_changed, "MyService" ``` -writes an event the Event Viewer renders as *"MyService service started"* — the `%1` placeholder filled from the [**LogSuccess**](EventLog#logsuccess) *AdditionalStrings* `ParamArray`, the `status_changed` category resolved against the message table, both keyed by the numeric values the enums carry. +writes an event the Event Viewer renders as *"MyService service started"* — the `%1` placeholder filled from the [**LogSuccess**](EventLog#logsuccess) *AdditionalStrings* `ParamArray`, the `status_changed` category resolved against the message table, both keyed by the numeric values the enums define. The negative event-ID values in the JSON (`-1073610751` etc.) follow the Win32 documented event-ID bit layout — the high bits encode severity, facility, and customer-defined flags. See Microsoft's *"Event Identifiers"* reference for the encoding; pick fresh IDs for new events and don't reuse identifiers across products. diff --git a/docs/Reference/WinNamedPipesLib/NamedPipeClientConnection.md b/docs/Reference/WinNamedPipesLib/NamedPipeClientConnection.md index 7a0b6b1..4124b76 100644 --- a/docs/Reference/WinNamedPipesLib/NamedPipeClientConnection.md +++ b/docs/Reference/WinNamedPipesLib/NamedPipeClientConnection.md @@ -8,7 +8,7 @@ has_toc: false # NamedPipeClientConnection class {: .no_toc } -One client-side connection to a named pipe. Produced by [**NamedPipeClientManager.Connect**](NamedPipeClientManager#connect). Carries the connection-lifecycle events ([**Connected**](#connected), [**Disconnected**](#disconnected)) and the message events ([**MessageReceived**](#messagereceived), [**MessageSent**](#messagesent)), plus the [**AsyncRead**](#asyncread) / [**AsyncWrite**](#asyncwrite) / [**AsyncClose**](#asyncclose) methods that drive them. +One client-side connection to a named pipe. Produced by [**NamedPipeClientManager.Connect**](NamedPipeClientManager#connect). Carries the connection-lifecycle events ([**Connected**](#connected), [**Disconnected**](#disconnected)) and the message events ([**MessageReceived**](#messagereceived), [**MessageSent**](#messagesent)), plus the [**AsyncRead**](#asyncread) / [**AsyncWrite**](#asyncwrite) / [**AsyncClose**](#asyncclose) methods that trigger them. The class is tagged `[COMCreatable(False)]` and its constructor takes a package-private interface — reach instances only through [**NamedPipeClientManager.Connect**](NamedPipeClientManager#connect). @@ -83,7 +83,7 @@ Fires when a complete message has been read from the pipe. Syntax: *connection*_**MessageReceived**(**ByRef** *Cookie* **As Variant**, **ByRef** *Data*() **As Byte**) *Cookie* -: The opaque correlation value originally passed to the [**AsyncRead**](#asyncread) that produced this read — or **Empty** if the read came from the auto-issued reads driven by [**NamedPipeClientManager.ContinuouslyReadFromPipe**](NamedPipeClientManager#continuouslyreadfrompipe). +: The opaque correlation value originally passed to the [**AsyncRead**](#asyncread) that produced this read — or **Empty** if the read came from the auto-issued reads triggered by [**NamedPipeClientManager.ContinuouslyReadFromPipe**](NamedPipeClientManager#continuouslyreadfrompipe). *Data* : The message payload. See [Working with `Data() As Byte` in events](.#working-with-data-as-byte-in-events) on the package overview for the transient-buffer lifetime caveat — copy the bytes out before the handler returns if you need them. The [recommended capture mechanism](.#propertybag-carrier) is to assign *Data* to a fresh [**PropertyBag**](../VBRUN/PropertyBag/)'s **Contents**, which deep-copies the bytes and gives you typed multi-field access in one step. @@ -118,7 +118,7 @@ Manually issues an asynchronous read against this connection. Syntax: *connection*.**AsyncRead** [ *Cookie* [, *OverlappedStruct* ] ] *Cookie* -: *optional* A **Variant** correlation value, surfaced as the *Cookie* parameter of the matching [**MessageReceived**](#messagereceived) event. Default **Empty**. +: *optional* A **Variant** correlation value, passed back as the *Cookie* parameter of the matching [**MessageReceived**](#messagereceived) event. Default **Empty**. *OverlappedStruct* : *optional* A **LongPtr** to a pre-allocated `OVERLAPPED_CUSTOM` structure. **Internal use only** — the IOCP machinery passes this when re-issuing a read after `ERROR_MORE_DATA`. Consumer code should always omit this parameter. @@ -133,10 +133,10 @@ Sends a message to the server. Syntax: *connection*.**AsyncWrite** *Data*() [, *Cookie* ] *Data* -: *required* A **Byte()** array carrying the bytes to send. An uninitialised or zero-length array is a no-op. For typed multi-field payloads the recommended carrier is [**PropertyBag**](../VBRUN/PropertyBag/) — see [Recommended payload encoding: `PropertyBag`](.#propertybag-carrier) on the package overview. +: *required* A **Byte()** array containing the bytes to send. An uninitialised or zero-length array is a no-op. For typed multi-field payloads the recommended encoding is [**PropertyBag**](../VBRUN/PropertyBag/) — see [Recommended payload encoding: `PropertyBag`](.#propertybag-carrier) on the package overview. *Cookie* -: *optional* A **Variant** correlation value, surfaced as the *Cookie* parameter of the matching [**MessageSent**](#messagesent) event. Default **Empty**. +: *optional* A **Variant** correlation value, passed back as the *Cookie* parameter of the matching [**MessageSent**](#messagesent) event. Default **Empty**. Returns immediately; the actual transmission runs through the IOCP loop. The completion fires [**MessageSent**](#messagesent) on this connection. diff --git a/docs/Reference/WinNamedPipesLib/NamedPipeClientManager.md b/docs/Reference/WinNamedPipesLib/NamedPipeClientManager.md index 1c2b8bd..c3217a7 100644 --- a/docs/Reference/WinNamedPipesLib/NamedPipeClientManager.md +++ b/docs/Reference/WinNamedPipesLib/NamedPipeClientManager.md @@ -8,9 +8,9 @@ has_toc: false # NamedPipeClientManager class {: .no_toc } -The client-side coordinator. Owns a Windows I/O Completion Port and a pool of worker threads shared by every [**NamedPipeClientConnection**](NamedPipeClientConnection) it produces, and hands out connection objects through [**Connect**](#connect). One [**NamedPipeClientManager**](.) typically lives for the lifetime of the consuming process and brokers many connections — to one or several servers — through that shared IOCP infrastructure. Instantiate with **New**. +The client-side coordinator. Owns a Windows I/O Completion Port and a pool of worker threads shared by every [**NamedPipeClientConnection**](NamedPipeClientConnection) it produces, and returns them through [**Connect**](#connect). One [**NamedPipeClientManager**](.) typically lives for the lifetime of the consuming process and manages many connections — to one or several servers — through that shared IOCP infrastructure. Instantiate with **New**. -Configure the public fields (all four have sensible defaults), call [**Connect**](#connect) for each pipe the application wants to dial, and respond to the [**NamedPipeClientConnection**](NamedPipeClientConnection) events. The first [**Connect**](#connect) lazily creates the completion port and starts the worker threads; subsequent calls reuse them. +Configure the public fields (all four have reasonable defaults), call [**Connect**](#connect) for each pipe the application wants to dial, and respond to the [**NamedPipeClientConnection**](NamedPipeClientConnection) events. The first [**Connect**](#connect) lazily creates the completion port and starts the worker threads; subsequent calls reuse them. ```tb Private manager As NamedPipeClientManager @@ -102,7 +102,7 @@ The package does not publish an event when pipes appear or disappear, so dynamic ### Stop {: .no_toc } -Cancels every outstanding I/O on every connection produced by this manager, posts the IOCP shutdown sentinel to each worker, waits for the threads to exit, closes every pipe handle, and frees the completion port. Idempotent: calling [**Stop**](#stop) on a manager that has not connected anything — or has already been stopped — is a no-op. Automatically invoked from `Class_Terminate`, so a manager going out of scope cleans up implicitly. +Cancels every outstanding I/O on every connection produced by this manager, posts the IOCP shutdown sentinel to each worker, waits for the threads to exit, closes every pipe handle, and frees the completion port. Idempotent: calling [**Stop**](#stop) on a manager that has not connected anything — or has already been stopped — is a no-op. Automatically invoked from `Class_Terminate`, so a manager going out of scope closes resources implicitly. Syntax: *manager*.**Stop** diff --git a/docs/Reference/WinNamedPipesLib/NamedPipeServer.md b/docs/Reference/WinNamedPipesLib/NamedPipeServer.md index 28b1d26..10a1622 100644 --- a/docs/Reference/WinNamedPipesLib/NamedPipeServer.md +++ b/docs/Reference/WinNamedPipesLib/NamedPipeServer.md @@ -8,9 +8,9 @@ has_toc: false # NamedPipeServer class {: .no_toc } -Hosts one named pipe and accepts an unbounded number of concurrent client connections, each represented by a [**NamedPipeServerConnection**](NamedPipeServerConnection). The class owns a Windows I/O Completion Port and a configurable pool of worker threads that drive every connection's reads, writes, and connect notifications. Instantiate with **New**. +Hosts one named pipe and accepts an unbounded number of concurrent client connections, each represented by a [**NamedPipeServerConnection**](NamedPipeServerConnection). The class owns a Windows I/O Completion Port and a configurable pool of worker threads that handle every connection's reads, writes, and connect notifications. Instantiate with **New**. -Configure the public fields ([**PipeName**](#pipename) is required, the others have sensible defaults), call [**Start**](#start), and respond to the lifecycle events as clients arrive and exchange messages. The package opens the underlying pipe as **PIPE_TYPE_MESSAGE** / **PIPE_READMODE_MESSAGE** — message boundaries on the wire match message boundaries seen by the consumer. +Configure the public fields ([**PipeName**](#pipename) is required, the others have reasonable defaults), call [**Start**](#start), and respond to the lifecycle events as clients arrive and exchange messages. The package opens the underlying pipe as **PIPE_TYPE_MESSAGE** / **PIPE_READMODE_MESSAGE** — messages preserve their boundaries between sender and receiver. ```tb Private WithEvents server As NamedPipeServer @@ -103,7 +103,7 @@ Syntax: *server*_**ClientMessageReceived**(*Connection* **As NamedPipeServerConn : The connection the message came from. *Cookie* -: The opaque correlation value originally passed to the [**NamedPipeServerConnection.AsyncRead**](NamedPipeServerConnection#asyncread) that produced this read — or **Empty** if the read came from the auto-issued reads driven by [**ContinuouslyReadFromPipe**](#continuouslyreadfrompipe). +: The opaque correlation value originally passed to the [**NamedPipeServerConnection.AsyncRead**](NamedPipeServerConnection#asyncread) that produced this read — or **Empty** if the read came from the auto-issued reads triggered by [**ContinuouslyReadFromPipe**](#continuouslyreadfrompipe). *Data* : The message payload. See [Working with `Data() As Byte` in events](.#working-with-data-as-byte-in-events) on the package overview for the transient-buffer lifetime caveat — copy the bytes out before the handler returns if you need them. The [recommended capture mechanism](.#propertybag-carrier) is to assign *Data* to a fresh [**PropertyBag**](../VBRUN/PropertyBag/)'s **Contents**, which deep-copies the bytes and gives you typed multi-field access in one step. @@ -159,7 +159,7 @@ The canonical caller is a Windows service that owns this server: the service-thr ### ManualMessageLoopLeave {: .no_toc } -Posts a `WM_USER_QUITTING` message to the hidden marshalling window, causing the [**ManualMessageLoopEnter**](#manualmessageloopenter) loop on the other thread to break out cleanly. Safe to call from any thread. +Posts a `WM_USER_QUITTING` message to the hidden marshalling window, causing the [**ManualMessageLoopEnter**](#manualmessageloopenter) loop on the other thread to exit. Safe to call from any thread. Syntax: *server*.**ManualMessageLoopLeave** @@ -168,7 +168,7 @@ The intended caller is a thread *other* than the one inside [**ManualMessageLoop ### Start {: .no_toc } -Creates the I/O Completion Port, spins up [**NumThreadsIOCP**](#numthreadsiocp) worker threads, and publishes the first connection listener under `\\.\pipe\`. Fires [**ServerReady**](#serverready) when every worker has joined. +Creates the I/O Completion Port, starts [**NumThreadsIOCP**](#numthreadsiocp) worker threads, and publishes the first connection listener under `\\.\pipe\`. Fires [**ServerReady**](#serverready) when every worker has joined. Syntax: *server*.**Start** @@ -179,7 +179,7 @@ Idempotent: calling [**Start**](#start) while the server is already running is a ### Stop {: .no_toc } -Cancels every outstanding I/O on every connection, posts the IOCP shutdown sentinel to each worker, waits for the threads to exit, closes every pipe handle, and frees the completion port. Idempotent: calling [**Stop**](#stop) on a server that has not been started — or has already been stopped — is a no-op. Automatically invoked from `Class_Terminate`, so a server going out of scope cleans up implicitly. +Cancels every outstanding I/O on every connection, posts the IOCP shutdown sentinel to each worker, waits for the threads to exit, closes every pipe handle, and frees the completion port. Idempotent: calling [**Stop**](#stop) on a server that has not been started — or has already been stopped — is a no-op. Automatically invoked from `Class_Terminate`, so a server going out of scope closes resources implicitly. Syntax: *server*.**Stop** diff --git a/docs/Reference/WinNamedPipesLib/NamedPipeServerConnection.md b/docs/Reference/WinNamedPipesLib/NamedPipeServerConnection.md index c4af392..c01faef 100644 --- a/docs/Reference/WinNamedPipesLib/NamedPipeServerConnection.md +++ b/docs/Reference/WinNamedPipesLib/NamedPipeServerConnection.md @@ -8,9 +8,9 @@ has_toc: false # NamedPipeServerConnection class {: .no_toc } -One server-side per-client connection. A [**NamedPipeServer**](NamedPipeServer) creates one of these for every client that connects, and surfaces it as the *Connection* parameter of every server event. Use it to send messages to that specific client, to manually issue reads when [**NamedPipeServer.ContinuouslyReadFromPipe**](NamedPipeServer#continuouslyreadfrompipe) is **False**, and to close the connection from the server side. +One server-side per-client connection. A [**NamedPipeServer**](NamedPipeServer) creates one of these for every client that connects, and passes it as the *Connection* parameter of every server event. Use it to send messages to that specific client, to manually issue reads when [**NamedPipeServer.ContinuouslyReadFromPipe**](NamedPipeServer#continuouslyreadfrompipe) is **False**, and to close the connection from the server side. -The class is tagged `[COMCreatable(False)]` and its constructor takes a package-private interface — reach instances only through [**NamedPipeServer**](NamedPipeServer) events. Connection-lifecycle and message events come through the parent [**NamedPipeServer**](NamedPipeServer); this class carries the per-connection data and methods only. +The class is tagged `[COMCreatable(False)]` and its constructor takes a package-private interface — reach instances only through [**NamedPipeServer**](NamedPipeServer) events. Connection-lifecycle and message events come through the parent [**NamedPipeServer**](NamedPipeServer); this class holds the per-connection data and methods only. ```tb Private Sub server_ClientConnected(Connection As NamedPipeServerConnection) @@ -72,7 +72,7 @@ Manually issues an asynchronous read against this connection. Syntax: *connection*.**AsyncRead** [ *Cookie* [, *OverlappedStruct* ] ] *Cookie* -: *optional* A **Variant** correlation value, surfaced as the *Cookie* parameter of the matching [**ClientMessageReceived**](NamedPipeServer#clientmessagereceived) event. Default **Empty**. +: *optional* A **Variant** correlation value, passed back as the *Cookie* parameter of the matching [**ClientMessageReceived**](NamedPipeServer#clientmessagereceived) event. Default **Empty**. *OverlappedStruct* : *optional* A **LongPtr** to a pre-allocated `OVERLAPPED_CUSTOM` structure. **Internal use only** — the IOCP machinery passes this when re-issuing a read after `ERROR_MORE_DATA`. Consumer code should always omit this parameter. @@ -87,10 +87,10 @@ Sends a message back to this specific client. Syntax: *connection*.**AsyncWrite** *Data*() [, *Cookie* ] *Data* -: *required* A **Byte()** array carrying the bytes to send. An uninitialised or zero-length array is a no-op. For typed multi-field payloads the recommended carrier is [**PropertyBag**](../VBRUN/PropertyBag/) — see [Recommended payload encoding: `PropertyBag`](.#propertybag-carrier) on the package overview. +: *required* A **Byte()** array containing the bytes to send. An uninitialised or zero-length array is a no-op. For typed multi-field payloads the recommended encoding is [**PropertyBag**](../VBRUN/PropertyBag/) — see [Recommended payload encoding: `PropertyBag`](.#propertybag-carrier) on the package overview. *Cookie* -: *optional* A **Variant** correlation value, surfaced as the *Cookie* parameter of the matching [**ClientMessageSent**](NamedPipeServer#clientmessagesent) event. Default **Empty**. +: *optional* A **Variant** correlation value, passed back as the *Cookie* parameter of the matching [**ClientMessageSent**](NamedPipeServer#clientmessagesent) event. Default **Empty**. Returns immediately; the actual transmission runs through the IOCP loop. The completion fires [**ClientMessageSent**](NamedPipeServer#clientmessagesent) on the parent server. diff --git a/docs/Reference/WinNamedPipesLib/index.md b/docs/Reference/WinNamedPipesLib/index.md index 5408cd8..5f2d605 100644 --- a/docs/Reference/WinNamedPipesLib/index.md +++ b/docs/Reference/WinNamedPipesLib/index.md @@ -26,7 +26,7 @@ Two halves, each one user-instantiated coordinator class plus one per-connection | Server | [**NamedPipeServer**](NamedPipeServer) | [**NamedPipeServerConnection**](NamedPipeServerConnection) | | Client | [**NamedPipeClientManager**](NamedPipeClientManager) | [**NamedPipeClientConnection**](NamedPipeClientConnection) | -The server publishes a name (`PipeName = "MyService"` → Win32 path `\\.\pipe\MyService`) and hands out a [**NamedPipeServerConnection**](NamedPipeServerConnection) for every client that connects. The client manager dials by the same name (with [**Connect**](NamedPipeClientManager#connect)) and gets back a [**NamedPipeClientConnection**](NamedPipeClientConnection). The two ends are symmetric thereafter — both expose `AsyncRead`, `AsyncWrite`, and `AsyncClose` with the same signatures. +The server publishes a name (`PipeName = "MyService"` → Win32 path `\\.\pipe\MyService`) and returns a [**NamedPipeServerConnection**](NamedPipeServerConnection) for every client that connects. The client manager dials by the same name (with [**Connect**](NamedPipeClientManager#connect)) and gets back a [**NamedPipeClientConnection**](NamedPipeClientConnection). The two ends are symmetric thereafter — both expose `AsyncRead`, `AsyncWrite`, and `AsyncClose` with the same signatures. Reads, writes, and connection completion all run through the same Windows I/O Completion Port (IOCP) infrastructure. Each coordinator class owns its own completion port, a configurable pool of worker threads ([**NumThreadsIOCP**](NamedPipeServer#numthreadsiocp)), and a hidden message-only window used to marshal events back to the UI thread. @@ -100,7 +100,7 @@ End Sub ## Working with `Data() As Byte` in events -The *Data* parameter on [**ClientMessageReceived**](NamedPipeServer#clientmessagereceived) and [**MessageReceived**](NamedPipeClientConnection#messagereceived) is **not** a normal heap-allocated **Byte** array. The package constructs a hand-rolled `SAFEARRAY` whose backing memory points at the IOCP read buffer, then clears the array pointer at the end of the event handler so the buffer can be recycled. The values are valid *only* while the handler is on the stack. +The *Data* parameter on [**ClientMessageReceived**](NamedPipeServer#clientmessagereceived) and [**MessageReceived**](NamedPipeClientConnection#messagereceived) is **not** a normal heap-allocated **Byte** array. The package constructs a custom `SAFEARRAY` whose backing memory points at the IOCP read buffer, then clears the array pointer at the end of the event handler so the buffer can be recycled. The values are valid *only* while the handler is on the stack. > [!IMPORTANT] > Copy the bytes out before the event handler returns if you need them later. Storing the array reference in a module-level variable, a **Collection**, or a class field leaves a dangling pointer once the IOCP loop reuses the buffer for the next message. @@ -120,7 +120,7 @@ For a text payload, `StrConv(Data, vbUnicode)` (UTF-8) or `CStr` over a `vbUnico The package transports raw bytes; it is agnostic about what is inside them. For non-trivial protocols the recommended carrier is [**PropertyBag**](../VBRUN/PropertyBag/) — twinBASIC's built-in keyed-property serialiser. Two reasons: -1. **`PropertyBag.Contents` deep-copies the bytes**, which is the cleanest answer to the transient-`Data()` lifetime caveat above. Assigning *Data* to a fresh **PropertyBag**'s **Contents** captures the buffer in one step; the copy is safe to keep past the event handler. +1. **`PropertyBag.Contents` deep-copies the bytes**, which is the simplest answer to the transient-`Data()` lifetime caveat above. Assigning *Data* to a fresh **PropertyBag**'s **Contents** captures the buffer in one step; the copy is safe to keep past the event handler. 2. **`PropertyBag` provides typed multi-field payloads** without the consumer having to design a wire protocol. Both sides agree on property names (e.g. `"CommandID"`, `"ResponseCommandID"`, `"Data"`) and **PropertyBag** handles the byte-level encoding. ```tb @@ -143,7 +143,7 @@ Select Case cmd End Select ``` -Nothing in the package mandates **PropertyBag** — raw `Byte()` works too, and a custom wire format may be the right answer for very high-throughput scenarios. But the everyday case is well served by the **PropertyBag** convention and it solves the transient-`Data()` problem for free. +Nothing in the package mandates **PropertyBag** — raw `Byte()` works too, and a custom wire format may be the right answer for very high-throughput scenarios. But the everyday case is well served by the **PropertyBag** convention and it solves the transient-`Data()` problem without extra effort. ## Closing a client connection @@ -184,4 +184,4 @@ End Sub - [NamedPipeServer](NamedPipeServer) -- the server: publishes a pipe name, hosts an IOCP loop, raises events for the lifecycle of every accepted client - [NamedPipeServerConnection](NamedPipeServerConnection) -- one server-side per-client connection; the **Connection** parameter of every `NamedPipeServer` event, with its own `AsyncRead` / `AsyncWrite` / `AsyncClose` - [NamedPipeClientManager](NamedPipeClientManager) -- the client-side coordinator; owns the IOCP loop and the [**Connect**](NamedPipeClientManager#connect) / [**Stop**](NamedPipeClientManager#stop) / [**FindNamedPipes**](NamedPipeClientManager#findnamedpipes) methods -- [NamedPipeClientConnection](NamedPipeClientConnection) -- one client-side connection; carries the `Connected` / `Disconnected` / `MessageReceived` / `MessageSent` events and the matching `AsyncRead` / `AsyncWrite` / `AsyncClose` methods +- [NamedPipeClientConnection](NamedPipeClientConnection) -- one client-side connection; exposes the `Connected` / `Disconnected` / `MessageReceived` / `MessageSent` events and the matching `AsyncRead` / `AsyncWrite` / `AsyncClose` methods diff --git a/docs/Reference/WinNativeCommonCtls/DTPicker.md b/docs/Reference/WinNativeCommonCtls/DTPicker.md index 513fee3..76f3a47 100644 --- a/docs/Reference/WinNativeCommonCtls/DTPicker.md +++ b/docs/Reference/WinNativeCommonCtls/DTPicker.md @@ -23,7 +23,7 @@ Private Sub DTPicker1_Change() End Sub ``` -The control inherits the focusable rect-dockable surface from `BaseControlFocusable` — size, position, **Anchors**, **Dock**, **Font**, **BackColor** / **ForeColor**, **Appearance**, **MousePointer** / **MouseIcon**, **ToolTipText**, **DragMode** / **DragIcon**, **Drag**, **Refresh**, **SetFocus**, **TabIndex** / **TabStop**, **ZOrder**, **CausesValidation**, **VisualStyles**, **hWnd**, **HelpContextID** / **WhatsThisHelpID**. +The control inherits the focusable rect-dockable members from `BaseControlFocusable` — size, position, **Anchors**, **Dock**, **Font**, **BackColor** / **ForeColor**, **Appearance**, **MousePointer** / **MouseIcon**, **ToolTipText**, **DragMode** / **DragIcon**, **Drag**, **Refresh**, **SetFocus**, **TabIndex** / **TabStop**, **ZOrder**, **CausesValidation**, **VisualStyles**, **hWnd**, **HelpContextID** / **WhatsThisHelpID**. * TOC {:toc} @@ -36,7 +36,7 @@ The convenience accessors [**Year**](#year), [**Month**](#month), [**Week**](#we ## Custom format and callback events -When [**Format**](#format) is set to **dtpCustom**, the [**CustomFormat**](#customformat) string drives the display. The format syntax follows the Win32 `GetDateFormat` / `GetTimeFormat` picture string (e.g. `"dddd, MMMM dd, yyyy"`). Tokens enclosed in callback markers (`X` literals in the format) raise the [**Format**](#format-event), [**FormatSize**](#formatsize), and [**CallbackKeyDown**](#callbackkeydown) events so the application can render its own field content and respond to keyboard navigation across it. +When [**Format**](#format) is set to **dtpCustom**, the [**CustomFormat**](#customformat) string controls the display. The format syntax follows the Win32 `GetDateFormat` / `GetTimeFormat` picture string (e.g. `"dddd, MMMM dd, yyyy"`). Tokens enclosed in callback markers (`X` literals in the format) raise the [**Format**](#format-event), [**FormatSize**](#formatsize), and [**CallbackKeyDown**](#callbackkeydown) events so the application can render its own field content and respond to keyboard navigation across it. ## Calendar appearance diff --git a/docs/Reference/WinNativeCommonCtls/Enumerations/DTPickerFormatConstants.md b/docs/Reference/WinNativeCommonCtls/Enumerations/DTPickerFormatConstants.md index e877b55..a14dbc4 100644 --- a/docs/Reference/WinNativeCommonCtls/Enumerations/DTPickerFormatConstants.md +++ b/docs/Reference/WinNativeCommonCtls/Enumerations/DTPickerFormatConstants.md @@ -10,7 +10,7 @@ permalink: /tB/Packages/WinNativeCommonCtls/Enumerations/DTPickerFormatConstants Selects the display format used by a [**DTPicker**](../DTPicker) control. Carried by the [**DTPicker.Format**](../DTPicker#format) property. -When set to **dtpCustom**, the picker also reads [**DTPicker.CustomFormat**](../DTPicker#customformat) to drive the actual display. +When set to **dtpCustom**, the picker also reads [**DTPicker.CustomFormat**](../DTPicker#customformat) to control the actual display. | Member | Value | Description | |-------------------|-------|------------------------------------------------------------------------| diff --git a/docs/Reference/WinNativeCommonCtls/ImageList/ListImages.md b/docs/Reference/WinNativeCommonCtls/ImageList/ListImages.md index ef5b229..6b15b41 100644 --- a/docs/Reference/WinNativeCommonCtls/ImageList/ListImages.md +++ b/docs/Reference/WinNativeCommonCtls/ImageList/ListImages.md @@ -73,7 +73,7 @@ Syntax: *object*.**Add** ( [ *Index* ] [, *Key* ] [, *Picture* ] [, *Tag* ] ) ** : *required* A **StdPicture** to add. Bitmaps (`vbPicTypeBitmap`) are scaled and masked according to [**MaskColor**](.#maskcolor) / [**UseMaskColor**](.#usemaskcolor). Icons (`vbPicTypeIcon`) are added directly with their own alpha mask. Omitting *Picture* raises run-time error 35607. *Tag* -: *optional* Arbitrary data attached to the new image; surfaced as [**ListImage.Tag**](ListImage#tag). +: *optional* Arbitrary data attached to the new image; available as [**ListImage.Tag**](ListImage#tag). Returns the newly-created [**ListImage**](ListImage). diff --git a/docs/Reference/WinNativeCommonCtls/ImageList/index.md b/docs/Reference/WinNativeCommonCtls/ImageList/index.md index 555ef00..a9dff59 100644 --- a/docs/Reference/WinNativeCommonCtls/ImageList/index.md +++ b/docs/Reference/WinNativeCommonCtls/ImageList/index.md @@ -26,7 +26,7 @@ Private Sub Form_Load() End Sub ``` -The control inherits the rectangular non-focusable base surface from `BaseControlNotFocusable` — size and position (size is irrelevant at run time since the control isn't drawn), **Name**, **Tag**, **hWnd**. It does not surface **Visible**, **Anchors**, or **Dock** in any meaningful way, and never accepts focus. +The control inherits the rectangular non-focusable base members from `BaseControlNotFocusable` — size and position (size is irrelevant at run time since the control isn't drawn), **Name**, **Tag**, **hWnd**. It does not expose **Visible**, **Anchors**, or **Dock** in any meaningful way, and never accepts focus. * TOC {:toc} diff --git a/docs/Reference/WinNativeCommonCtls/ListView/index.md b/docs/Reference/WinNativeCommonCtls/ListView/index.md index 5574bba..bb40dc7 100644 --- a/docs/Reference/WinNativeCommonCtls/ListView/index.md +++ b/docs/Reference/WinNativeCommonCtls/ListView/index.md @@ -42,7 +42,7 @@ Private Sub ListView1_ItemClick(Item As ListItem) End Sub ``` -The control inherits the focusable rect-dockable surface from `BaseControlFocusable` — size, position, **Anchors**, **Dock**, **Font**, **Appearance**, **MousePointer** / **MouseIcon**, **ToolTipText**, **DragMode** / **DragIcon**, **Drag**, **Refresh**, **SetFocus**, **TabIndex** / **TabStop**, **ZOrder**, **CausesValidation**, **VisualStyles**, **hWnd**, **HelpContextID** / **WhatsThisHelpID**. +The control inherits the focusable rect-dockable members from `BaseControlFocusable` — size, position, **Anchors**, **Dock**, **Font**, **Appearance**, **MousePointer** / **MouseIcon**, **ToolTipText**, **DragMode** / **DragIcon**, **Drag**, **Refresh**, **SetFocus**, **TabIndex** / **TabStop**, **ZOrder**, **CausesValidation**, **VisualStyles**, **hWnd**, **HelpContextID** / **WhatsThisHelpID**. * TOC {:toc} @@ -231,7 +231,7 @@ Events ### AfterLabelEdit {: .no_toc } -Raised when an inline label edit completes. Set *Cancel* to **True** to revert; *NewString* carries the user's proposed new text. +Raised when an inline label edit completes. Set *Cancel* to **True** to revert; *NewString* holds the user's proposed new text. Syntax: *object*\_**AfterLabelEdit**( *Cancel* **As Boolean**, *NewString* **As String** ) @@ -245,7 +245,7 @@ Syntax: *object*\_**BeforeLabelEdit**( *Cancel* **As Boolean** ) ### Click {: .no_toc } -Raised on a mouse click inside the control. Distinct from [**ItemClick**](#itemclick), which fires only when the click lands on a row. +Raised on a mouse click inside the control. Distinct from [**ItemClick**](#itemclick), which fires only when the click hits a row. Syntax: *object*\_**Click**( ) diff --git a/docs/Reference/WinNativeCommonCtls/MonthView.md b/docs/Reference/WinNativeCommonCtls/MonthView.md index 2d90033..d5c476e 100644 --- a/docs/Reference/WinNativeCommonCtls/MonthView.md +++ b/docs/Reference/WinNativeCommonCtls/MonthView.md @@ -33,7 +33,7 @@ Private Sub MonthView1_GetDayBold( _ End Sub ``` -The control inherits the focusable rect-dockable surface from `BaseControlFocusable` — size, position, **Anchors**, **Dock**, **Font**, **Appearance**, **MousePointer** / **MouseIcon**, **ToolTipText**, **Drag**, **Refresh**, **SetFocus**, **TabIndex** / **TabStop**, **ZOrder**, **CausesValidation**, **VisualStyles**, **hWnd**, **HelpContextID** / **WhatsThisHelpID**. +The control inherits the focusable rect-dockable members from `BaseControlFocusable` — size, position, **Anchors**, **Dock**, **Font**, **Appearance**, **MousePointer** / **MouseIcon**, **ToolTipText**, **Drag**, **Refresh**, **SetFocus**, **TabIndex** / **TabStop**, **ZOrder**, **CausesValidation**, **VisualStyles**, **hWnd**, **HelpContextID** / **WhatsThisHelpID**. * TOC {:toc} @@ -269,7 +269,7 @@ Events ### Click {: .no_toc } -Raised on any mouse click that doesn't land on a date cell. +Raised on any mouse click that doesn't hit a date cell. Syntax: *object*\_**Click**( ) @@ -290,7 +290,7 @@ Syntax: *object*\_**DateDblClick**( **ByVal** *DateDblClicked* **As Date** ) ### DblClick {: .no_toc } -Raised on any double-click that doesn't land on a date cell. +Raised on any double-click that doesn't hit a date cell. Syntax: *object*\_**DblClick**( ) diff --git a/docs/Reference/WinNativeCommonCtls/ProgressBar.md b/docs/Reference/WinNativeCommonCtls/ProgressBar.md index 1f569ed..d902c87 100644 --- a/docs/Reference/WinNativeCommonCtls/ProgressBar.md +++ b/docs/Reference/WinNativeCommonCtls/ProgressBar.md @@ -35,7 +35,7 @@ ProgressBar1.MarqueeSpeed = 30 ' milliseconds per animation step ProgressBar1.MarqueeAnimation = True ' start animating ``` -The control inherits the non-focusable rect-dockable surface from `BaseControlNotFocusable2` — size, position, **Anchors**, **Dock**, **Appearance**, **MousePointer** / **MouseIcon**, **ToolTipText**, **DragMode** / **DragIcon**, **Drag**, **Refresh**, **ZOrder**, **CausesValidation**, **VisualStyles**, **hWnd**, **HelpContextID** / **WhatsThisHelpID**. +The control inherits the non-focusable rect-dockable members from `BaseControlNotFocusable2` — size, position, **Anchors**, **Dock**, **Appearance**, **MousePointer** / **MouseIcon**, **ToolTipText**, **DragMode** / **DragIcon**, **Drag**, **Refresh**, **ZOrder**, **CausesValidation**, **VisualStyles**, **hWnd**, **HelpContextID** / **WhatsThisHelpID**. * TOC {:toc} @@ -44,7 +44,7 @@ The control inherits the non-focusable rect-dockable surface from `BaseControlNo The visual is the cartesian product of three properties: -- **[Scrolling](#scrolling)** — *Standard* (the default, animated segmented bar), *Smooth* (a continuous block — combine with [**SmoothReverse**](#smoothreverse) to allow the bar to decrease), or *Marquee* (an indeterminate animated stripe; drive with [**MarqueeAnimation**](#marqueeanimation) + [**MarqueeSpeed**](#marqueespeed)). +- **[Scrolling](#scrolling)** — *Standard* (the default, animated segmented bar), *Smooth* (a continuous block — combine with [**SmoothReverse**](#smoothreverse) to allow the bar to decrease), or *Marquee* (an indeterminate animated stripe; control with [**MarqueeAnimation**](#marqueeanimation) + [**MarqueeSpeed**](#marqueespeed)). - **[State](#state)** — *Normal* (theme-default color, typically green), *Error* (typically red), or *Paused* (typically yellow). The OS chooses the actual colors based on its current theme. - **[Orientation](#orientation)** — *Horizontal* or *Vertical*. @@ -52,7 +52,7 @@ All three can be changed at run time; the underlying Win32 styles are re-applied ## Range, value, and stepping -[**Min**](#min) and [**Max**](#max) bracket the range. [**Value**](#value) is the current position. [**Step**](#step) is the amount [**StepIt**](#stepit) advances the bar by, used to drive the common loop pattern: +[**Min**](#min) and [**Max**](#max) bracket the range. [**Value**](#value) is the current position. [**Step**](#step) is the amount [**StepIt**](#stepit) advances the bar by, used to power the common loop pattern: ```tb ProgressBar1.Min = 0 diff --git a/docs/Reference/WinNativeCommonCtls/Slider.md b/docs/Reference/WinNativeCommonCtls/Slider.md index 2b32f5c..bb69530 100644 --- a/docs/Reference/WinNativeCommonCtls/Slider.md +++ b/docs/Reference/WinNativeCommonCtls/Slider.md @@ -8,7 +8,7 @@ has_toc: false # Slider class {: .no_toc } -A **Slider** is a trackbar control — a horizontal or vertical channel with a draggable thumb that lets the user pick a value between [**Min**](#min) and [**Max**](#max). Optional tick marks, a floating value tip, and a highlighted selection range round out the surface. +A **Slider** is a trackbar control — a horizontal or vertical channel with a draggable thumb that lets the user pick a value between [**Min**](#min) and [**Max**](#max). Optional tick marks, a floating value tip, and a highlighted selection range round out the control. ```tb Private Sub Form_Load() @@ -25,7 +25,7 @@ Private Sub Slider1_Change() End Sub ``` -The control inherits the focusable rect-dockable surface from `BaseControlFocusableNoFont` — size, position, **Anchors**, **Dock**, **Appearance**, **MousePointer** / **MouseIcon**, **ToolTipText**, **DragMode** / **DragIcon**, **Drag**, **Refresh**, **SetFocus**, **TabIndex** / **TabStop**, **ZOrder**, **CausesValidation**, **VisualStyles**, **hWnd**, **HelpContextID** / **WhatsThisHelpID**. Slider does not carry a [**Font**](../VB/CheckBox#font) property (its thumb and tick marks are drawn by the OS theme). +The control inherits the focusable rect-dockable members from `BaseControlFocusableNoFont` — size, position, **Anchors**, **Dock**, **Appearance**, **MousePointer** / **MouseIcon**, **ToolTipText**, **DragMode** / **DragIcon**, **Drag**, **Refresh**, **SetFocus**, **TabIndex** / **TabStop**, **ZOrder**, **CausesValidation**, **VisualStyles**, **hWnd**, **HelpContextID** / **WhatsThisHelpID**. Slider does not have a [**Font**](../VB/CheckBox#font) property (its thumb and tick marks are drawn by the OS theme). * TOC {:toc} diff --git a/docs/Reference/WinNativeCommonCtls/TreeView/Node.md b/docs/Reference/WinNativeCommonCtls/TreeView/Node.md index 726e992..cee82ac 100644 --- a/docs/Reference/WinNativeCommonCtls/TreeView/Node.md +++ b/docs/Reference/WinNativeCommonCtls/TreeView/Node.md @@ -9,7 +9,7 @@ has_toc: false # Node class {: .no_toc } -A **Node** is a single entry in a [**TreeView**](.)'s [**Nodes**](Nodes) collection. Returned from [**Nodes.Add**](Nodes#add) and from [**Nodes.Item**](Nodes#item). Each node carries its own text, icons, sort settings, check state, and sibling / parent / child relationships. +A **Node** is a single entry in a [**TreeView**](.)'s [**Nodes**](Nodes) collection. Returned from [**Nodes.Add**](Nodes#add) and from [**Nodes.Item**](Nodes#item). Each node has its own text, icons, sort settings, check state, and sibling / parent / child relationships. The class is tagged `[COMCreatable(False)]` — user code reaches **Node** instances through the parent [**TreeView**](.)'s [**Nodes**](Nodes) collection or through navigation properties on other nodes. diff --git a/docs/Reference/WinNativeCommonCtls/TreeView/Nodes.md b/docs/Reference/WinNativeCommonCtls/TreeView/Nodes.md index e730b88..bfeb9d2 100644 --- a/docs/Reference/WinNativeCommonCtls/TreeView/Nodes.md +++ b/docs/Reference/WinNativeCommonCtls/TreeView/Nodes.md @@ -27,7 +27,7 @@ For Each node In TreeView1.Nodes Next ``` -The `For Each` iteration walks **only the nodes in the order they were added** — not in tree order. For a depth-first or breadth-first traversal that follows the visual hierarchy, walk the parent-child links manually starting from a root [**Node**](Node) and using [**Node.Child**](Node#child) / [**Node.Next**](Node#next). +The `For Each` iteration visits **only the nodes in the order they were added** — not in tree order. For a depth-first or breadth-first traversal that follows the visual hierarchy, traverse the parent-child links manually starting from a root [**Node**](Node) and using [**Node.Child**](Node#child) / [**Node.Next**](Node#next). * TOC {:toc} diff --git a/docs/Reference/WinNativeCommonCtls/TreeView/index.md b/docs/Reference/WinNativeCommonCtls/TreeView/index.md index d7caff1..24875b7 100644 --- a/docs/Reference/WinNativeCommonCtls/TreeView/index.md +++ b/docs/Reference/WinNativeCommonCtls/TreeView/index.md @@ -27,7 +27,7 @@ Private Sub TreeView1_NodeClick(ByVal Node As Node) End Sub ``` -The control inherits the focusable rect-dockable surface from `BaseControlFocusable` — size, position, **Anchors**, **Dock**, **Font**, **Appearance**, **MousePointer** / **MouseIcon**, **ToolTipText**, **DragMode** / **DragIcon**, **Drag**, **Refresh**, **SetFocus**, **TabIndex** / **TabStop**, **ZOrder**, **CausesValidation**, **VisualStyles**, **hWnd**, **HelpContextID** / **WhatsThisHelpID**. +The control inherits the focusable rect-dockable members from `BaseControlFocusable` — size, position, **Anchors**, **Dock**, **Font**, **Appearance**, **MousePointer** / **MouseIcon**, **ToolTipText**, **DragMode** / **DragIcon**, **Drag**, **Refresh**, **SetFocus**, **TabIndex** / **TabStop**, **ZOrder**, **CausesValidation**, **VisualStyles**, **hWnd**, **HelpContextID** / **WhatsThisHelpID**. * TOC {:toc} @@ -248,7 +248,7 @@ Syntax: *object*\_**BeforeLabelEdit**( *Cancel* **As Boolean** ) ### Click {: .no_toc } -Raised on a mouse click inside the control. Distinct from [**NodeClick**](#nodeclick), which fires when the click lands on a node. +Raised on a mouse click inside the control. Distinct from [**NodeClick**](#nodeclick), which fires when the click hits a node. Syntax: *object*\_**Click**( ) diff --git a/docs/Reference/WinNativeCommonCtls/UpDown.md b/docs/Reference/WinNativeCommonCtls/UpDown.md index 00d2f44..246cb48 100644 --- a/docs/Reference/WinNativeCommonCtls/UpDown.md +++ b/docs/Reference/WinNativeCommonCtls/UpDown.md @@ -27,7 +27,7 @@ Private Sub Text1_Change() End Sub ``` -The control inherits the focusable rect-dockable surface from `BaseControlFocusableNoFont` — size, position, **Anchors**, **Dock**, **Appearance**, **MousePointer** / **MouseIcon**, **ToolTipText**, **DragMode** / **DragIcon**, **Drag**, **Refresh**, **SetFocus**, **TabIndex** / **TabStop**, **ZOrder**, **CausesValidation**, **VisualStyles**, **hWnd**, **HelpContextID** / **WhatsThisHelpID**. **UpDown** does not carry a [**Font**](../VB/CheckBox#font) property (the arrows are drawn by the OS theme). +The control inherits the focusable rect-dockable members from `BaseControlFocusableNoFont` — size, position, **Anchors**, **Dock**, **Appearance**, **MousePointer** / **MouseIcon**, **ToolTipText**, **DragMode** / **DragIcon**, **Drag**, **Refresh**, **SetFocus**, **TabIndex** / **TabStop**, **ZOrder**, **CausesValidation**, **VisualStyles**, **hWnd**, **HelpContextID** / **WhatsThisHelpID**. **UpDown** does not have a [**Font**](../VB/CheckBox#font) property (the arrows are drawn by the OS theme). * TOC {:toc} diff --git a/docs/Reference/WinNativeCommonCtls/index.md b/docs/Reference/WinNativeCommonCtls/index.md index 1814b61..7a89468 100644 --- a/docs/Reference/WinNativeCommonCtls/index.md +++ b/docs/Reference/WinNativeCommonCtls/index.md @@ -10,7 +10,7 @@ has_toc: false # WinNativeCommonCtls Package {: .no_toc } -The **WinNativeCommonCtls** built-in package is a VB6-compatible replacement for **Microsoft Common Controls 6.0** (the legacy `MSCOMCTL.OCX`), reimplemented on top of the Win32 ComCtl32 controls in `COMCTL32.DLL` and `MSFTEDIT.DLL`. It ships eight controls that mirror the MSCOMCTL surface name-for-name where possible, with the same property / method / event spellings VB6 developers will recognise. +The **WinNativeCommonCtls** built-in package is a VB6-compatible replacement for **Microsoft Common Controls 6.0** (the legacy `MSCOMCTL.OCX`), reimplemented on top of the Win32 ComCtl32 controls in `COMCTL32.DLL` and `MSFTEDIT.DLL`. It ships eight controls that mirror the MSCOMCTL member names where possible, with the same property / method / event spellings VB6 developers will recognise. The package is a built-in package shipped with twinBASIC. Add it through Project → References (**Ctrl-T**) → Available Packages. @@ -21,11 +21,11 @@ The package is a built-in package shipped with twinBASIC. Add it through Project VB6 projects that depend on `MSCOMCTL.OCX` cannot run unmodified in modern environments — the OCX is unsigned, requires per-machine registration with admin rights, ships with known security advisories, and is not available on non-Windows hosts at all. **WinNativeCommonCtls** removes the dependency: drop a [**ListView**](ListView/), [**TreeView**](TreeView/), [**ProgressBar**](ProgressBar), [**Slider**](Slider), [**ImageList**](ImageList/), [**DTPicker**](DTPicker), [**MonthView**](MonthView), or [**UpDown**](UpDown) onto a [**Form**](../VB/Form/) and twinBASIC creates the underlying Win32 ComCtl32 control directly, with no OCX involved. -The control names, property names, event signatures, and the `vb…` / `tvw…` / `lvw…` / `sld…` / `Prb…` member-name conventions all match the original `MSCOMCTL.OCX` surface, so VB6 code that uses the original controls usually compiles and runs unchanged once the package reference is in place. +The control names, property names, event signatures, and the `vb…` / `tvw…` / `lvw…` / `sld…` / `Prb…` member-name conventions all match the original `MSCOMCTL.OCX` API, so VB6 code that uses the original controls usually compiles and runs unchanged once the package reference is in place. ## Controls -Eight controls, each a leaf class that inherits from a `BaseCtl` where the entire surface is declared: +Eight controls, each a leaf class that inherits from a `BaseCtl` where the entire API is declared: - [DTPicker](DTPicker) -- date / time picker: dropdown calendar, single-date [**Value**](DTPicker#value), custom format strings, optional spin-button and checkbox variants - [ImageList](ImageList/) -- off-screen image collection that feeds icons to [**ListView**](ListView/) and [**TreeView**](TreeView/) through the [**Icons**](ListView/#icons) / [**SmallIcons**](ListView/#smallicons) / [**ImageList**](TreeView/#imagelist) properties; not visible at run time @@ -36,7 +36,7 @@ Eight controls, each a leaf class that inherits from a `BaseCtl` where the - [TreeView](TreeView/) -- hierarchical tree of [**Node**](TreeView/Node) objects with sorting, label-edit, checkboxes, image lists, and per-node bold / color overrides - [UpDown](UpDown) -- spin control with up / down arrows: pure [**Min**](UpDown#min) / [**Max**](UpDown#max) / [**Value**](UpDown#value) / [**Increment**](UpDown#increment) (no auto-buddy) -[**ListView**](ListView/), [**TreeView**](TreeView/), and [**ImageList**](ImageList/) carry collection sub-objects — see the folder index pages for the full hierarchy. +[**ListView**](ListView/), [**TreeView**](TreeView/), and [**ImageList**](ImageList/) include collection sub-objects — see the folder index pages for the full hierarchy. ## Enumerations @@ -44,9 +44,9 @@ Module-level enumerations shared across multiple controls live under [**Enumerat - [Enumerations](Enumerations/) -- the ten user-facing enumerations declared in shared modules -## Cross-control surface +## Cross-control members -Every control inherits the standard VB-package surface from `BaseControl` / `BaseControlRect` / `BaseControlRectDockable` / `BaseControlFocusable` (or `BaseControlNotFocusable`, where the control cannot take focus). Inherited members include: +Every control inherits the standard VB-package members from `BaseControl` / `BaseControlRect` / `BaseControlRectDockable` / `BaseControlFocusable` (or `BaseControlNotFocusable`, where the control cannot take focus). Inherited members include: - **Positioning and layout** — **Name**, **Left**, **Top**, **Width**, **Height**, **Anchors**, **Dock**, **Visible**, **Enabled**, **Move**, **Refresh**, **ZOrder**, **Container**, **Parent**, **Index**, **Tag**, **hWnd** - **Appearance** — **BackColor** / **ForeColor** / **Font** (where focusable), **Appearance**, **VisualStyles**, **MousePointer** / **MouseIcon** @@ -56,7 +56,7 @@ Every control inherits the standard VB-package surface from `BaseControl` / `Bas - **OLE drag-and-drop** — **OLEDropMode**, the **OLEDrag** method, and the **OLEStartDrag** / **OLEGiveFeedback** / **OLESetData** / **OLEDragOver** / **OLEDragDrop** / **OLECompleteDrag** events. See [**OLEDropConstants**](../VBRUN/Constants/OLEDropConstants) - **Transparency** — **Opacity** (`Double`, 0–100, percentage) and **TransparencyKey** (`OLE_COLOR`, `-1` to disable). Both require Windows 8 (target OS 6.2+) for child controls; on older OS versions they are silently no-ops -Each control's reference page lists the control-specific surface — own properties, methods, events, and nested enums — without re-enumerating the entire inherited base every time. +Each control's reference page lists the control-specific members — own properties, methods, events, and nested enums — without re-enumerating the entire inherited base every time. ## Control type constants @@ -78,6 +78,6 @@ Each control's **ControlType** property returns its constant at run time, allowi ## See also - [VB Package](../VB/) -- the standard control set: **CheckBox**, **CommandButton**, **TextBox**, **Frame**, **Form**, … -- [CustomControls Package](../CustomControls/) -- owner-drawn `Waynes…` custom controls when the Win32 surface is not enough +- [CustomControls Package](../CustomControls/) -- owner-drawn `Waynes…` custom controls when the Win32 API is not enough - [ControlTypeConstants](../VBRUN/Constants/ControlTypeConstants) -- the `vb…` discriminator constants used by the **ControlType** property on every control - [OLEDropConstants](../VBRUN/Constants/OLEDropConstants) -- the **OLEDropMode** values shared by every control in this package diff --git a/docs/Reference/WinServicesLib/Enumerations/ServiceControlCodeConstants.md b/docs/Reference/WinServicesLib/Enumerations/ServiceControlCodeConstants.md index aedbb6a..92187a1 100644 --- a/docs/Reference/WinServicesLib/Enumerations/ServiceControlCodeConstants.md +++ b/docs/Reference/WinServicesLib/Enumerations/ServiceControlCodeConstants.md @@ -23,10 +23,10 @@ The values mirror the Win32 `SERVICE_CONTROL_*` constants verbatim — the `vb` | **vbServiceControlNetBindRemove**{: #vbServiceControlNetBindRemove } | 0x08 | A network binding has been removed. | | **vbServiceControlNetBindEnable**{: #vbServiceControlNetBindEnable } | 0x09 | A previously disabled network binding has been enabled. | | **vbServiceControlNetBindDisable**{: #vbServiceControlNetBindDisable } | 0x0A | A network binding has been disabled. | -| **vbServiceControlDeviceEvent**{: #vbServiceControlDeviceEvent } | 0x0B | A device-arrival / -removal event. The *dwEventType* and *lpEventData* parameters of [**ChangeState**](../ITbService#changestate) carry the `DBT_*` sub-code and `DEV_BROADCAST_HDR` data. Only delivered when the service has accepted `SERVICE_ACCEPT_HARDWAREPROFILECHANGE`. | +| **vbServiceControlDeviceEvent**{: #vbServiceControlDeviceEvent } | 0x0B | A device-arrival / -removal event. The *dwEventType* and *lpEventData* parameters of [**ChangeState**](../ITbService#changestate) hold the `DBT_*` sub-code and `DEV_BROADCAST_HDR` data. Only delivered when the service has accepted `SERVICE_ACCEPT_HARDWAREPROFILECHANGE`. | | **vbServiceControlHardwareProfileChange**{: #vbServiceControlHardwareProfileChange } | 0x0C | A hardware-profile change (laptop docking, …). | -| **vbServiceControlPowerEvent**{: #vbServiceControlPowerEvent } | 0x0D | A system power event (suspend, resume, battery low, …). The *dwEventType* parameter carries the `PBT_*` sub-code. | -| **vbServiceControlSessionChange**{: #vbServiceControlSessionChange } | 0x0E | A session-change event (user logon, RDP connect / disconnect, …). The *dwEventType* parameter carries the `WTS_*` sub-code. | +| **vbServiceControlPowerEvent**{: #vbServiceControlPowerEvent } | 0x0D | A system power event (suspend, resume, battery low, …). The *dwEventType* parameter holds the `PBT_*` sub-code. | +| **vbServiceControlSessionChange**{: #vbServiceControlSessionChange } | 0x0E | A session-change event (user logon, RDP connect / disconnect, …). The *dwEventType* parameter holds the `WTS_*` sub-code. | | **vbServiceControlPreShutdown**{: #vbServiceControlPreShutdown } | 0x0F | The OS is about to shut down — sent before [**vbServiceControlShutdown**](#vbServiceControlShutdown) to services that have registered for the longer pre-shutdown notification window. | | **vbServiceControlTimeChange**{: #vbServiceControlTimeChange } | 0x10 | The system time has changed. | | **vbServiceControlTriggerEvent**{: #vbServiceControlTriggerEvent } | 0x20 | A registered trigger event has fired (typically used by trigger-started services). | diff --git a/docs/Reference/WinServicesLib/Enumerations/index.md b/docs/Reference/WinServicesLib/Enumerations/index.md index 231eb1c..40c8f9c 100644 --- a/docs/Reference/WinServicesLib/Enumerations/index.md +++ b/docs/Reference/WinServicesLib/Enumerations/index.md @@ -7,7 +7,7 @@ has_toc: false # Enumerations -The four user-facing enumerations the **WinServicesLib** package exposes. All four come from the public `ServicesConstantsPublic` module in the package source; the larger surface of internal `SERVICE_*` constants the source uses to call into `advapi32.dll` lives in a `Private Module` and is not part of the public API. +The four user-facing enumerations the **WinServicesLib** package exposes. All four come from the public `ServicesConstantsPublic` module in the package source; the larger set of internal `SERVICE_*` constants the source uses to call into `advapi32.dll` lives in a `Private Module` and is not part of the public API. | Enumeration | Used by | |-------------|---------| diff --git a/docs/Reference/WinServicesLib/ITbService.md b/docs/Reference/WinServicesLib/ITbService.md index f418676..c317af4 100644 --- a/docs/Reference/WinServicesLib/ITbService.md +++ b/docs/Reference/WinServicesLib/ITbService.md @@ -73,7 +73,7 @@ Syntax: *service*.**ChangeState** *ServiceManager*, *dwControl*, *dwEventType*, : A [**ServiceControlCodeConstants**](Enumerations/ServiceControlCodeConstants) value identifying the control. Standard codes the SCM may deliver include [**vbServiceControlStop**](Enumerations/ServiceControlCodeConstants#vbServiceControlStop), [**vbServiceControlShutdown**](Enumerations/ServiceControlCodeConstants#vbServiceControlShutdown), [**vbServiceControlPause**](Enumerations/ServiceControlCodeConstants#vbServiceControlPause), [**vbServiceControlContinue**](Enumerations/ServiceControlCodeConstants#vbServiceControlContinue), [**vbServiceControlInterrogate**](Enumerations/ServiceControlCodeConstants#vbServiceControlInterrogate), and the event-bearing codes ([**vbServiceControlSessionChange**](Enumerations/ServiceControlCodeConstants#vbServiceControlSessionChange), [**vbServiceControlPowerEvent**](Enumerations/ServiceControlCodeConstants#vbServiceControlPowerEvent), [**vbServiceControlDeviceEvent**](Enumerations/ServiceControlCodeConstants#vbServiceControlDeviceEvent), [**vbServiceControlHardwareProfileChange**](Enumerations/ServiceControlCodeConstants#vbServiceControlHardwareProfileChange)). User-defined codes in the range 128–255 can also be delivered through [**Services.ControlService**](Services#controlservice). *dwEventType* -: A **Long** carrying the event-type sub-code for the codes that have one. **0** otherwise. See Microsoft's `HandlerEx` documentation for the per-code interpretation. +: A **Long** holding the event-type sub-code for the codes that have one. **0** otherwise. See Microsoft's `HandlerEx` documentation for the per-code interpretation. *lpEventData* : A **LongPtr** to an event-specific data structure for the codes that have one. `vbNullPtr` otherwise. diff --git a/docs/Reference/WinServicesLib/Services.md b/docs/Reference/WinServicesLib/Services.md index 4df9feb..0abfc33 100644 --- a/docs/Reference/WinServicesLib/Services.md +++ b/docs/Reference/WinServicesLib/Services.md @@ -79,7 +79,7 @@ Syntax: **Services.GetConfiguredService**( *Name* ) **As** [**ServiceManager**]( *Name* : *required* A **String** matching the [**Name**](ServiceManager#name) of one of the [**ServiceManager**](ServiceManager) instances created with [**ConfigureNew**](#configurenew). -Raises run-time error 5 *"service not found"* if no configured service carries that name. Typical use is in the interactive / install branch of `Sub Main`, where a UI button needs to act on a single configured service: +Raises run-time error 5 *"service not found"* if no configured service has that name. Typical use is in the interactive / install branch of `Sub Main`, where a UI button needs to act on a single configured service: ```tb Private Sub btnInstallA_Click() @@ -93,7 +93,7 @@ Despite the `Property Get` syntax, the lookup is parameterised by name — it re ### InstallAll {: .no_toc } -Iterates every [**ServiceManager**](ServiceManager) created through [**ConfigureNew**](#configurenew) and calls its [**Install**](ServiceManager#install) method. Convenience for the typical case where the EXE registers every service it hosts in one shot. +Iterates every [**ServiceManager**](ServiceManager) created through [**ConfigureNew**](#configurenew) and calls its [**Install**](ServiceManager#install) method. Convenience for the typical case where the EXE registers every service it hosts in a single call. Syntax: **Services.InstallAll** diff --git a/docs/Reference/WinServicesLib/index.md b/docs/Reference/WinServicesLib/index.md index 67d5874..ebf2e32 100644 --- a/docs/Reference/WinServicesLib/index.md +++ b/docs/Reference/WinServicesLib/index.md @@ -60,7 +60,7 @@ The `-startService` discriminator is the conventional way for the EXE to know wh ## The two-thread split {: #two-thread-split } -When the SCM launches the EXE as a service host, twinBASIC's runtime ends up driving **two threads** for each service: +When the SCM launches the EXE as a service host, twinBASIC's runtime ends up running **two threads** for each service: - The **service thread** — the SCM-spawned thread that runs the user's [**ITbService.EntryPoint**](ITbService#entrypoint). This is where the service does its actual work. The thread is created by `StartServiceCtrlDispatcherW`'s machinery; it is *not* the main thread of the EXE. - The **dispatcher thread** — the EXE's main thread, which is what the SCM invokes when it has a control code to deliver (*Stop*, *Pause*, *Continue*, …). The package routes the control through `RegisterServiceCtrlHandlerExW` to a trampoline that calls the user's [**ITbService.ChangeState**](ITbService#changestate). @@ -101,13 +101,13 @@ Class MyService End Class ``` -The shared-flag pattern is the documented coordination mechanism — there is no built-in cancellation primitive. For services that host an inherently message-loop-driven object (a [**NamedPipeServer**](../WinNamedPipesLib/NamedPipeServer), a window-message handler, …) the loop-driven object's own *Stop*-signal method is usually called from [**ChangeState**](ITbService#changestate); see [the WinNamedPipesLib service-host idiom](../WinNamedPipesLib/#service-host-idiom) for a worked example. +The shared-flag pattern is the documented coordination mechanism — there is no built-in cancellation primitive. For services that host an inherently message-loop-driven object (a [**NamedPipeServer**](../WinNamedPipesLib/NamedPipeServer), a window-message handler, …) that object's own *Stop*-signal method is usually called from [**ChangeState**](ITbService#changestate); see [the WinNamedPipesLib service-host idiom](../WinNamedPipesLib/#service-host-idiom) for a worked example. ## Integration with the sister "winlibs" packages -`WinServicesLib` is most often used together with [**WinEventLogLib**](../WinEventLogLib/) and [**WinNamedPipesLib**](../WinNamedPipesLib/) — Windows services typically need a place to write diagnostic events (the Windows Event Log) and a way to communicate with non-service processes (named pipes). The three packages compose cleanly: +`WinServicesLib` is most often used together with [**WinEventLogLib**](../WinEventLogLib/) and [**WinNamedPipesLib**](../WinNamedPipesLib/) — Windows services typically need a place to write diagnostic events (the Windows Event Log) and a way to communicate with non-service processes (named pipes). The three packages integrate well: -- **Logging** — every service class can mix in the [**EventLog**](../WinEventLogLib/EventLog) surface through the [composition-delegation idiom](../WinEventLogLib/#composition-delegation-idiom) (`Implements EventLog(Of EVENTS, CATEGORIES) Via EventLog = New EventLog(...)`), so [**LogSuccess**](../WinEventLogLib/EventLog#logsuccess) / [**LogFailure**](../WinEventLogLib/EventLog#logfailure) read as plain method calls inside `EntryPoint` and `ChangeState`. The events fire under the service account (typically `LocalSystem`), which the Event Viewer renders against the message-table resource the EXE carries. +- **Logging** — every service class can mix in the [**EventLog**](../WinEventLogLib/EventLog) members through the [composition-delegation idiom](../WinEventLogLib/#composition-delegation-idiom) (`Implements EventLog(Of EVENTS, CATEGORIES) Via EventLog = New EventLog(...)`), so [**LogSuccess**](../WinEventLogLib/EventLog#logsuccess) / [**LogFailure**](../WinEventLogLib/EventLog#logfailure) read as plain method calls inside `EntryPoint` and `ChangeState`. The events fire under the service account (typically `LocalSystem`), which the Event Viewer renders against the message-table resource embedded in the EXE. - **IPC** — a [**NamedPipeServer**](../WinNamedPipesLib/NamedPipeServer) hosted inside the service uses [**ManualMessageLoopEnter**](../WinNamedPipesLib/NamedPipeServer#manualmessageloopenter) as the [**EntryPoint**](ITbService#entrypoint)'s blocking primitive, and [**ManualMessageLoopLeave**](../WinNamedPipesLib/NamedPipeServer#manualmessageloopleave) from [**ChangeState**](ITbService#changestate) becomes the *Stop*-signal mechanism. See [Hosting inside a Windows service](../WinNamedPipesLib/#service-host-idiom) for the complete pattern, including pause / continue and the dispatcher-thread / service-thread interaction. ## Installation and elevation @@ -123,7 +123,7 @@ Calling [**Install**](ServiceManager#install) while running inside the twinBASIC ## Classes and interface - [Services](Services) -- the predeclared singleton coordinator: [**ConfigureNew**](Services#configurenew), [**RunServiceDispatcher**](Services#runservicedispatcher), the bulk install / uninstall helpers, plus the runtime control methods ([**LaunchService**](Services#launchservice), [**ControlService**](Services#controlservice), [**QueryStateOfService**](Services#querystateofservice)) -- [ServiceManager](ServiceManager) -- one per configured service; carries the fields the SCM cares about (name, description, type, start-mode, command-line, dependencies, ...) plus the [**ReportStatus**](ServiceManager#reportstatus) call the service uses to inform the SCM of state transitions +- [ServiceManager](ServiceManager) -- one per configured service; holds the fields the SCM cares about (name, description, type, start-mode, command-line, dependencies, ...) plus the [**ReportStatus**](ServiceManager#reportstatus) call the service uses to inform the SCM of state transitions - [ServiceCreator](ServiceCreator) -- the generic [**ServiceCreator**](ServiceCreator)`(Of T)` factory the dispatcher uses to instantiate each service class on demand; *T* must implement [**ITbService**](ITbService) - [ServiceState](ServiceState) -- a read-only state snapshot returned by [**Services.QueryStateOfService**](Services#querystateofservice), giving the SCM-reported state and process ID of an installed service - [ITbService](ITbService) -- the interface every service class implements: [**EntryPoint**](ITbService#entrypoint), [**StartupFailed**](ITbService#startupfailed), [**ChangeState**](ITbService#changestate) diff --git a/docs/Reference/tbIDE/CodeEditor.md b/docs/Reference/tbIDE/CodeEditor.md index 12be842..68ee7b0 100644 --- a/docs/Reference/tbIDE/CodeEditor.md +++ b/docs/Reference/tbIDE/CodeEditor.md @@ -47,7 +47,7 @@ Replacing the entire text is heavyweight — both for the editor (it has to rebu ### AddMonacoWidget {: .no_toc } -Attaches an inline HTML overlay to a specific position in the editor — Monaco's *content widget* mechanism, surfaced as a familiar [**HtmlElement**](HtmlElement). +Attaches an inline HTML overlay to a specific position in the editor — Monaco's *content widget* mechanism, exposed as a familiar [**HtmlElement**](HtmlElement). Syntax: *codeEditor*.**AddMonacoWidget**( *LineNumber*, *ColumnNumber*, *Html* [, *Css* ] ) **As** [**HtmlElement**](HtmlElement) @@ -63,7 +63,7 @@ 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 surface 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. Use [**HtmlElement.Remove**](HtmlElement#remove) on the returned object to take the widget down. ### ExecuteMonacoCommand {: .no_toc } @@ -78,7 +78,7 @@ Syntax: *codeEditor*.**ExecuteMonacoCommand** *Command* [, *Arg1*, *Arg2*, … ] *Args* : *optional* A **ParamArray** of command-specific arguments. **Variant**. Forwarded verbatim to Monaco. -The reference does not enumerate Monaco's command surface — refer to Monaco's documentation for the full list and their per-command argument shapes. +The reference does not enumerate Monaco's command set — refer to Monaco's documentation for the full list and their per-command argument shapes. ```tb codeEditor.ExecuteMonacoCommand "actions.find" ' open Find widget diff --git a/docs/Reference/tbIDE/Editor.md b/docs/Reference/tbIDE/Editor.md index 9fa6984..25de8d2 100644 --- a/docs/Reference/tbIDE/Editor.md +++ b/docs/Reference/tbIDE/Editor.md @@ -8,7 +8,7 @@ has_toc: false # Editor class {: .no_toc } -The base interface every IDE editor presents. **Editor** itself carries only the universal members — [**Path**](#path), [**Type**](#type), [**SetFocus**](#setfocus), [**Close**](#close), [**Save**](#save), [**IsDirty**](#isdirty) — and an instance returned from [**Editors.Item**](Editors#item) or the [**Host.OnChangedActiveEditor**](Host#onchangedactiveeditor) event is normally a *specific* editor kind (e.g. [**CodeEditor**](CodeEditor) for code panes), reachable by casting. +The base interface every IDE editor presents. **Editor** itself exposes only the universal members — [**Path**](#path), [**Type**](#type), [**SetFocus**](#setfocus), [**Close**](#close), [**Save**](#save), [**IsDirty**](#isdirty) — and an instance returned from [**Editors.Item**](Editors#item) or the [**Host.OnChangedActiveEditor**](Host#onchangedactiveeditor) event is normally a *specific* editor kind (e.g. [**CodeEditor**](CodeEditor) for code panes), reachable by casting. ## Castability {: #castability } diff --git a/docs/Reference/tbIDE/Editors.md b/docs/Reference/tbIDE/Editors.md index cdebd34..07e4b1f 100644 --- a/docs/Reference/tbIDE/Editors.md +++ b/docs/Reference/tbIDE/Editors.md @@ -8,7 +8,7 @@ has_toc: false # Editors class {: .no_toc } -The collection of editors active in the IDE — accessible through [**Host.ActiveEditors**](Host#activeeditors). The IDE currently exposes exactly one active editor at a time, but the surface is collection-shaped so future versions can expose more. The most common operations are `Host.ActiveEditors(0)` (the active editor) and [**Open**](#open) (jump to a file at a given line / column). +The collection of editors active in the IDE — accessible through [**Host.ActiveEditors**](Host#activeeditors). The IDE currently exposes exactly one active editor at a time, but the collection interface allows future versions to expose more. The most common operations are `Host.ActiveEditors(0)` (the active editor) and [**Open**](#open) (jump to a file at a given line / column). ```tb ' Read the selection out of the currently-focused code pane: diff --git a/docs/Reference/tbIDE/Host.md b/docs/Reference/tbIDE/Host.md index d8e6874..9469f4a 100644 --- a/docs/Reference/tbIDE/Host.md +++ b/docs/Reference/tbIDE/Host.md @@ -174,7 +174,7 @@ Syntax: *host*_**OnChangedTheme**(*ThemeName* **As String**) ## DebuggerEvaluateOptions {: #debuggerevaluateoptions } -A flags enum declared inline on the **Host** interface; consumed by [**Project.Evaluate**](Project#evaluate) (and the future debugger-evaluation surface). Currently a single-value placeholder — additional flags may appear in later IDE versions. +A flags enum declared inline on the **Host** interface; consumed by [**Project.Evaluate**](Project#evaluate) (and any future debugger-evaluation API). Currently a single-value placeholder — additional flags may appear in later IDE versions. | Constant | Value | Description | |----------|-------|-------------| diff --git a/docs/Reference/tbIDE/HtmlElement.md b/docs/Reference/tbIDE/HtmlElement.md index e655df9..74fe1a7 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 surface 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 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. ```tb With myToolWindow.RootDomElement.ChildDomElements.Add("greeting", "h1") @@ -42,7 +42,7 @@ The unique ID assigned to the element when it was created via [**HtmlElements.Ad The element's dynamic property bag — every DOM property, every CSS-style property, every custom-widget extension lives here. **As** [**HtmlElementProperties**](HtmlElementProperties). **DefaultMember** — so `element.` is equivalent to `element.Properties.`. -The bag is [`[COMExtensible(True)]`](.#dynamic-dom-property-resolution): property names are resolved against the DOM element at run time, so the accepted set is everything the underlying tag supports — refer to MDN for standard DOM properties, and to the custom-widget documentation (Chart.js, Monaco, …) for the widget-specific surface. +The bag is [`[COMExtensible(True)]`](.#dynamic-dom-property-resolution): property names are resolved against the DOM element at run time, so the accepted set is everything the underlying tag supports — refer to MDN for standard DOM properties, and to the custom-widget documentation (Chart.js, Monaco, …) for the widget-specific properties. ## Methods diff --git a/docs/Reference/tbIDE/HtmlElementProperties.md b/docs/Reference/tbIDE/HtmlElementProperties.md index d26757f..833dc15 100644 --- a/docs/Reference/tbIDE/HtmlElementProperties.md +++ b/docs/Reference/tbIDE/HtmlElementProperties.md @@ -33,7 +33,7 @@ The interface's **DefaultMember** is [**Item**](#item) — so `properties("style ### Item {: .no_toc } -Looks up a property by name. Returns an [**HtmlElementProperty**](HtmlElementProperty), which carries the property's value plus a nested [**Properties**](HtmlElementProperty#properties) for further drill-down. +Looks up a property by name. Returns an [**HtmlElementProperty**](HtmlElementProperty), which includes the property's value plus a nested [**Properties**](HtmlElementProperty#properties) for further drill-down. Syntax: *properties*( *DomPropertyName* ) **As** [**HtmlElementProperty**](HtmlElementProperty) diff --git a/docs/Reference/tbIDE/HtmlElementProperty.md b/docs/Reference/tbIDE/HtmlElementProperty.md index 2b6a187..dc5a6be 100644 --- a/docs/Reference/tbIDE/HtmlElementProperty.md +++ b/docs/Reference/tbIDE/HtmlElementProperty.md @@ -29,7 +29,7 @@ element.style.color = "red" ### Properties {: .no_toc } -A nested [**HtmlElementProperties**](HtmlElementProperties) for properties that themselves carry sub-properties (the canonical example is `style`, whose sub-properties are the individual CSS-style names). Read-only at the accessor level; the inner bag is mutable. +A nested [**HtmlElementProperties**](HtmlElementProperties) for properties that themselves have sub-properties (the canonical example is `style`, whose sub-properties are the individual CSS-style names). Read-only at the accessor level; the inner bag is mutable. Syntax: *property*.**Properties** **As** [**HtmlElementProperties**](HtmlElementProperties) diff --git a/docs/Reference/tbIDE/HtmlEventProperties.md b/docs/Reference/tbIDE/HtmlEventProperties.md index 2f99bbc..a4453e8 100644 --- a/docs/Reference/tbIDE/HtmlEventProperties.md +++ b/docs/Reference/tbIDE/HtmlEventProperties.md @@ -21,7 +21,7 @@ End Sub ``` > [!IMPORTANT] -> This interface is **`[COMExtensible(True)]`**. Field names are resolved against the underlying event object at run time. The standard DOM event surface (`.target` → the element that fired the event; `.key`, `.code`, `.altKey`, `.ctrlKey`, `.shiftKey` for keyboard events; `.clientX`, `.clientY` for mouse events; `.index` for the IDE's listview events; …) is forwarded as-is to the JavaScript-side event object. See MDN's DOM Event documentation for the standard fields. +> This interface is **`[COMExtensible(True)]`**. Field names are resolved against the underlying event object at run time. The standard DOM event properties (`.target` → the element that fired the event; `.key`, `.code`, `.altKey`, `.ctrlKey`, `.shiftKey` for keyboard events; `.clientX`, `.clientY` for mouse events; `.index` for the IDE's listview events; …) are forwarded as-is to the JavaScript-side event object. See MDN's DOM Event documentation for the standard fields. * TOC {:toc} @@ -64,7 +64,7 @@ The interface's **DefaultMember** is [**Item**](#item) — so `eventInfo("target ### Item {: .no_toc } -Looks up a field by name. Returns an [**HtmlEventProperty**](HtmlEventProperty), which carries the field's value plus a nested [**Properties**](HtmlEventProperty#properties) for further drill-down. +Looks up a field by name. Returns an [**HtmlEventProperty**](HtmlEventProperty), which includes the field's value plus a nested [**Properties**](HtmlEventProperty#properties) for further drill-down. Syntax: *eventInfo*( *DomPropertyName* ) **As** [**HtmlEventProperty**](HtmlEventProperty) diff --git a/docs/Reference/tbIDE/HtmlEventProperty.md b/docs/Reference/tbIDE/HtmlEventProperty.md index 55898ef..e438e47 100644 --- a/docs/Reference/tbIDE/HtmlEventProperty.md +++ b/docs/Reference/tbIDE/HtmlEventProperty.md @@ -29,7 +29,7 @@ End Sub ### Properties {: .no_toc } -A nested [**HtmlEventProperties**](HtmlEventProperties) for fields that themselves carry sub-fields (the canonical example is `.target`, whose sub-fields are the target element's own properties — `id`, `value`, `name`, `tagName`, …). Read-only at the accessor level. +A nested [**HtmlEventProperties**](HtmlEventProperties) for fields that themselves have sub-fields (the canonical example is `.target`, whose sub-fields are the target element's own properties — `id`, `value`, `name`, `tagName`, …). Read-only at the accessor level. Syntax: *property*.**Properties** **As** [**HtmlEventProperties**](HtmlEventProperties) diff --git a/docs/Reference/tbIDE/Project.md b/docs/Reference/tbIDE/Project.md index 20d1fdd..ddcf57b 100644 --- a/docs/Reference/tbIDE/Project.md +++ b/docs/Reference/tbIDE/Project.md @@ -44,7 +44,7 @@ The folder containing the project's `.twinproj` file — i.e. the directory part ### BuildFileExtension {: .no_toc } -The file extension the build output will carry (`"exe"`, `"dll"`, `"ocx"`, `"twinpack"`). **String**, read-only. Implied by [**BuildType**](#buildtype). +The file extension of the build output (`"exe"`, `"dll"`, `"ocx"`, `"twinpack"`). **String**, read-only. Implied by [**BuildType**](#buildtype). ### BuildOutputPath {: .no_toc } @@ -86,7 +86,7 @@ The four components of the project's current version (`Major.Minor.Build.Revisio ### Build {: .no_toc } -Builds the project. Equivalent to the IDE's File → Make/Build… command. Writes the output to [**BuildOutputPath**](#buildoutputpath); errors raised during compilation surface in the DEBUG CONSOLE the same way they would for a user-initiated build. +Builds the project. Equivalent to the IDE's File → Make/Build… command. Writes the output to [**BuildOutputPath**](#buildoutputpath); errors raised during compilation appear in the DEBUG CONSOLE the same way they would for a user-initiated build. Syntax: *project*.**Build** @@ -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 surface 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` if the expression may raise. ### LoadMetaData {: .no_toc } diff --git a/docs/Reference/tbIDE/Themes.md b/docs/Reference/tbIDE/Themes.md index 5bfdfd4..3fdeb4a 100644 --- a/docs/Reference/tbIDE/Themes.md +++ b/docs/Reference/tbIDE/Themes.md @@ -44,4 +44,4 @@ Note that the set of available themes is determined by the IDE and may grow in f The high-level "family" the current theme belongs to. **String**, read-only — exactly `"dark"` or `"light"`. -Useful for an addin that just wants to flip its own colours between dark-on-light and light-on-dark; far more robust than parsing [**ActiveThemeName**](#activethemename). +Useful for an addin that wants to flip its own colours between dark-on-light and light-on-dark without parsing [**ActiveThemeName**](#activethemename). diff --git a/docs/Reference/tbIDE/Toolbars.md b/docs/Reference/tbIDE/Toolbars.md index 3d961a7..93b03c0 100644 --- a/docs/Reference/tbIDE/Toolbars.md +++ b/docs/Reference/tbIDE/Toolbars.md @@ -8,7 +8,7 @@ has_toc: false # Toolbars class {: .no_toc } -The collection of IDE toolbars. Reached through [**Host.Toolbars**](Host#toolbars). Currently there is only one toolbar — `Host.Toolbars(0)` — but the surface is collection-shaped so future IDE versions can add more. +The collection of IDE toolbars. Reached through [**Host.Toolbars**](Host#toolbars). Currently there is only one toolbar — `Host.Toolbars(0)` — but the collection interface allows future IDE versions to add more. ```tb With Host.Toolbars(0) diff --git a/docs/Reference/tbIDE/index.md b/docs/Reference/tbIDE/index.md index 2b02068..ec8ad7f 100644 --- a/docs/Reference/tbIDE/index.md +++ b/docs/Reference/tbIDE/index.md @@ -36,7 +36,7 @@ Module MainModule End Module ``` -The returned object must implement [**AddIn**](AddIn). The IDE releases the object when the addin is disabled or the IDE shuts down, which lets the addin clean up through `Class_Terminate`. +The returned object must implement [**AddIn**](AddIn). The IDE releases the object when the addin is disabled or the IDE shuts down, which lets the addin close resources through `Class_Terminate`. A minimal addin class: @@ -83,7 +83,7 @@ The package's twenty-four `.twin` files declare one interface-and-CoClass pair e - [**Folder**](Folder) — children enumeration (use **For Each** — see the warning on [**Count**](Folder#count) / [**Item**](Folder#item) — the IDE is multi-threaded and index-based iteration races), [**IsPackagesFolder**](Folder#ispackagesfolder). - [**File**](File) — virtual-FS file accessors: [**Data**](File#data) (raw bytes), [**Text**](File#text) (decoded text), [**ReadText**](File#readtext) (text with options like comment-stripping), [**IsDirty**](File#isdirty). -### IDE UI surface +### IDE UI - [**Toolbar**](Toolbar) — the IDE toolbar. [**AddSplitter**](Toolbar#addsplitter), [**AddButton**](Toolbar#addbutton). - [**Toolbars**](Toolbars) — the toolbar collection. Currently there is only one toolbar, addressable as `Toolbars(0)`. @@ -110,7 +110,7 @@ The four `Html*` classes are the addin's keyhole into the DOM inside a tool wind ## Dynamic DOM property resolution -The four `Html*` classes that carry the `[COMExtensible(True)]` attribute — [**HtmlElementProperties**](HtmlElementProperties), [**HtmlElementProperty**](HtmlElementProperty), [**HtmlEventProperties**](HtmlEventProperties), [**HtmlEventProperty**](HtmlEventProperty) — accept **arbitrary property names** that are resolved against the underlying DOM element (or event object) at run time. None of `style`, `innerText`, `chart`, `editor`, `listview`, `value`, `target`, `key`, `index`, …, are declared statically on the interfaces — they are all resolved dynamically through the COM-extensible `Item(name)` default member. +The four `Html*` classes that have the `[COMExtensible(True)]` attribute — [**HtmlElementProperties**](HtmlElementProperties), [**HtmlElementProperty**](HtmlElementProperty), [**HtmlEventProperties**](HtmlEventProperties), [**HtmlEventProperty**](HtmlEventProperty) — accept **arbitrary property names** that are resolved against the underlying DOM element (or event object) at run time. None of `style`, `innerText`, `chart`, `editor`, `listview`, `value`, `target`, `key`, `index`, …, are declared statically on the interfaces — they are all resolved dynamically through the COM-extensible `Item(name)` default member. So: @@ -130,18 +130,18 @@ reads at run time as: .Item("innerText").Value = "Section heading" ``` -The compiler does not validate the property names; they are forwarded as strings to the IDE's tool-window renderer. The accepted set is **every DOM property of the underlying tag** — standard HTML attributes, every CSS-style property under `.style.…`, plus any custom-widget-specific surface like `.chart.data.datasets(0).borderWidth` on a `"chartjs"` element or `.editor.setOption(...)` on a `"monaco"` element. The reference does not enumerate them — defer to MDN for standard DOM property names, to Chart.js for `chartjs` widgets, to Monaco's documentation for `monaco` widgets, and to the matching samples below for the IDE-specific `listview` / `virtuallistview` surface. +The compiler does not validate the property names; they are forwarded as strings to the IDE's tool-window renderer. The accepted set is **every DOM property of the underlying tag** — standard HTML attributes, every CSS-style property under `.style.…`, plus any custom-widget-specific properties like `.chart.data.datasets(0).borderWidth` on a `"chartjs"` element or `.editor.setOption(...)` on a `"monaco"` element. The reference does not enumerate them — defer to MDN for standard DOM property names, to Chart.js for `chartjs` widgets, to Monaco's documentation for `monaco` widgets, and to the matching samples below for the IDE-specific `listview` / `virtuallistview` properties. ## Tool-window DOM tags [**HtmlElements.Add**](HtmlElements#add) takes a *TagName* string. Standard HTML tags (`"div"`, `"span"`, `"input"`, `"h1"`, `"label"`, `"img"`, …) work as expected; in addition, the IDE provides four custom-widget tags: -- **`"chartjs"`** — wraps **Chart.js**. The element surfaces a `.chart` property whose sub-properties mirror Chart.js's `data` / `options` / `config` namespaces. See sample 11. -- **`"monaco"`** — embeds an instance of the **Monaco editor** (the same editor the IDE itself uses for code panes). The element surfaces an `.editor` property with `setOption`, `setValue`, `getValue`, and `AddEventListener` (note: event listeners attach to `.editor`, not to the DOM element). See sample 12. -- **`"listview"`** — the IDE's built-in listview widget. The element surfaces a `.listview` property with `addItem`, `removeItem`, `getItem`, `setShowScrollbarV` / `setShowScrollbarH`, and the events `onClickItem` / `onDblClickItem`. See sample 13. -- **`"virtuallistview"`** — a virtual variant of the listview suitable for huge data sets (millions of rows). The element surfaces the same `.listview` property plus `setItemCount` and the asynchronous `onAsyncGetItemHTML` event (the listener responds via `eventInfo.setAsyncResult("")`); call `.listview.notifyChangedItem(idx)` to invalidate the internal cache for one row when its underlying data changes. See sample 14. +- **`"chartjs"`** — wraps **Chart.js**. The element exposes a `.chart` property whose sub-properties mirror Chart.js's `data` / `options` / `config` namespaces. See sample 11. +- **`"monaco"`** — embeds an instance of the **Monaco editor** (the same editor the IDE itself uses for code panes). The element exposes an `.editor` property with `setOption`, `setValue`, `getValue`, and `AddEventListener` (note: event listeners attach to `.editor`, not to the DOM element). See sample 12. +- **`"listview"`** — the IDE's built-in listview widget. The element exposes a `.listview` property with `addItem`, `removeItem`, `getItem`, `setShowScrollbarV` / `setShowScrollbarH`, and the events `onClickItem` / `onDblClickItem`. See sample 13. +- **`"virtuallistview"`** — a virtual variant of the listview suitable for huge data sets (millions of rows). The element exposes the same `.listview` property plus `setItemCount` and the asynchronous `onAsyncGetItemHTML` event (the listener responds via `eventInfo.setAsyncResult("")`); call `.listview.notifyChangedItem(idx)` to invalidate the internal cache for one row when its underlying data changes. See sample 14. -The full per-widget property and method surface is documented by each widget's home project; this package wraps them through the same `[COMExtensible(True)]` mechanism described above. +The full per-widget properties and methods are documented by each widget's home project; this package wraps them through the same `[COMExtensible(True)]` mechanism described above. ## Where the samples live @@ -150,7 +150,7 @@ Six worked addins ship in the twinBASIC samples folder. They are the canonical r | Sample | Project | What it teaches | |--------|---------|-----------------| | 10 | `WaynesWorldAddInTest1` | The kitchen-sink walkthrough — toolbar setup, a single big tool window populated with 22 styled `div`-buttons that each exercise a different `Host.*` capability. Start here. | -| 11 | `WaynesWorldCPUMonitorTest1` | [**AddinTimer**](AddinTimer) + a `"chartjs"` custom-widget tool window driving a live line chart. | +| 11 | `WaynesWorldCPUMonitorTest1` | [**AddinTimer**](AddinTimer) + a `"chartjs"` custom-widget tool window powering a live line chart. | | 12 | `WaynesWorldMonacoEditorTest1` | A `"monaco"` custom-widget tool window: an in-window Monaco editor with `setValue` / `getValue` and a content-change listener. | | 13 | `WaynesListViewAddIn` | A `"listview"` custom-widget tool window with `ApplyCss`, double-click-to-remove behaviour, and inline-HTML `raiseEvent()` for custom event names. | | 14 | `WaynesVirtualListViewAddIn` | A `"virtuallistview"` with 5,000,000 rows backed by `onAsyncGetItemHTML` / `setAsyncResult` / `notifyChangedItem`. | diff --git a/docs/Tutorials/Arrays.md b/docs/Tutorials/Arrays.md index 99afb72..c3606ab 100644 --- a/docs/Tutorials/Arrays.md +++ b/docs/Tutorials/Arrays.md @@ -211,7 +211,7 @@ End Sub In twinBASIC, array types are implemented as pointers to a pointer to the Windows API **SAFEARRAY** structure. -This can be leveraged to efficiently access: +This can be used to efficiently access: - the count of elements in the 1st dimension - as the pointer to the data (to the 1st element in the array) diff --git a/docs/Tutorials/CEF/Building a browser shell.md b/docs/Tutorials/CEF/Building a browser shell.md index 4180334..a1d6a1f 100644 --- a/docs/Tutorials/CEF/Building a browser shell.md +++ b/docs/Tutorials/CEF/Building a browser shell.md @@ -10,7 +10,7 @@ permalink: /Tutorials/CEF/Building-A-Browser-Shell A short worked tutorial: turn a [**CefBrowser**](../../tB/Packages/CEF/CefBrowser/) control into a working browser with an address bar, back / forward / reload buttons, zoom, and a few helpers (DevTools, PDF export). -The complete project ships as *Sample 1b — Chromium Embedded Framework Examples* in the New-Project dialog (form *Example 1*). This tutorial walks through its key pieces. +The complete project ships as *Sample 1b — Chromium Embedded Framework Examples* in the New-Project dialog (form *Example 1*). This tutorial describes its key pieces. ## The form @@ -18,7 +18,7 @@ Drop a [**CefBrowser**](../../tB/Packages/CEF/CefBrowser/) control onto a Form a ## Navigating -The bare-bones navigation surface — [**Navigate**](../../tB/Packages/CEF/CefBrowser/#navigate), [**GoBack**](../../tB/Packages/CEF/CefBrowser/#goback), [**GoForward**](../../tB/Packages/CEF/CefBrowser/#goforward), [**Reload**](../../tB/Packages/CEF/CefBrowser/#reload) — is one-liners: +The bare-bones navigation methods — [**Navigate**](../../tB/Packages/CEF/CefBrowser/#navigate), [**GoBack**](../../tB/Packages/CEF/CefBrowser/#goback), [**GoForward**](../../tB/Packages/CEF/CefBrowser/#goforward), [**Reload**](../../tB/Packages/CEF/CefBrowser/#reload) — are one-liners: ```tb Private Sub btnBack_Click() Handles btnBack.Click @@ -88,7 +88,7 @@ The `On Error Resume Next` catches the "control not ready" error that fires when ## PDF export -[**PrintToPdf**](../../tB/Packages/CEF/CefBrowser/#printtopdf) saves the current document to disk asynchronously — the result surfaces as [**PrintToPdfCompleted**](../../tB/Packages/CEF/CefBrowser/#printtopdfcompleted) or [**PrintToPdfFailed**](../../tB/Packages/CEF/CefBrowser/#printtopdffailed): +[**PrintToPdf**](../../tB/Packages/CEF/CefBrowser/#printtopdf) saves the current document to disk asynchronously — the result arrives as [**PrintToPdfCompleted**](../../tB/Packages/CEF/CefBrowser/#printtopdfcompleted) or [**PrintToPdfFailed**](../../tB/Packages/CEF/CefBrowser/#printtopdffailed): ```tb Private Sub btnPDF_Click() Handles btnPDF.Click diff --git a/docs/Tutorials/CEF/Customize the UserDataFolder.md b/docs/Tutorials/CEF/Customize the UserDataFolder.md index a459fa5..aceb10c 100644 --- a/docs/Tutorials/CEF/Customize the UserDataFolder.md +++ b/docs/Tutorials/CEF/Customize the UserDataFolder.md @@ -36,7 +36,7 @@ CEF reads the environment options *once*, when the helper browser process is lau A single user-data folder cannot be opened by two CEF processes at once — the runtime takes an exclusive lock on it for the lifetime of the browser process. Two **CefBrowser** controls in the *same* application share the helper process and therefore the same lock, so they cooperate fine; two *separate* applications pointing at the same folder collide. -When a collision is detected and [**UserDataFolder**](../../tB/Packages/CEF/CefBrowser/EnvironmentOptions#userdatafolder) is left at its default, the control automatically retries with the next `instance-N` sub-folder. When the host has explicitly set a path, the lock failure instead surfaces as a CEF initialisation error (*"CEF cache path already locked by another process"*) — handle it in the [**Error**](../../tB/Packages/CEF/CefBrowser/#error) event: +When a collision is detected and [**UserDataFolder**](../../tB/Packages/CEF/CefBrowser/EnvironmentOptions#userdatafolder) is left at its default, the control automatically retries with the next `instance-N` sub-folder. When the host has explicitly set a path, the lock failure instead appears as a CEF initialisation error (*"CEF cache path already locked by another process"*) — handle it in the [**Error**](../../tB/Packages/CEF/CefBrowser/#error) event: ```tb Private Sub CefBrowser1_Error(ByVal code As Long, ByVal msg As String) diff --git a/docs/Tutorials/CEF/Driving Monaco.md b/docs/Tutorials/CEF/Driving Monaco.md index 36e7709..56b1e0b 100644 --- a/docs/Tutorials/CEF/Driving Monaco.md +++ b/docs/Tutorials/CEF/Driving Monaco.md @@ -28,7 +28,7 @@ If WebView.CefMajorVersion < 109 Then End If ``` -In practice this means **v109** or **v145** for this tutorial — **v49** lacks the JavaScript surface Monaco depends on. See [Getting started](Getting-Started) for picking the right package reference. +In practice this means **v109** or **v145** for this tutorial — **v49** lacks the JavaScript API Monaco depends on. See [Getting started](Getting-Started) for picking the right package reference. ## Setting up the editor's assets @@ -94,7 +94,7 @@ The two controls share a single helper browser process — the first **CefBrowse ## Pushing the initial content -Once Monaco has finished loading, the bootstrap script listens for a `message` event carrying the HTML to seed the editor with. Fire that message after the editor's [**NavigationComplete**](../../tB/Packages/CEF/CefBrowser/#navigationcomplete): +Once Monaco has finished loading, the bootstrap script listens for a `message` event containing the HTML to seed the editor with. Fire that message after the editor's [**NavigationComplete**](../../tB/Packages/CEF/CefBrowser/#navigationcomplete): ```tb Private Sub WebView_NavigationComplete( _ @@ -129,7 +129,7 @@ That's it — the preview pane re-renders on every edit. ## Detecting a missing runtime -A reasonable fraction of users will run the application on a machine where the CEF runtime ZIP has not been installed. The [**Error**](../../tB/Packages/CEF/CefBrowser/#error) event surfaces this case with the exact path the control searched: +A reasonable fraction of users will run the application on a machine where the CEF runtime ZIP has not been installed. The [**Error**](../../tB/Packages/CEF/CefBrowser/#error) event reports this case with the exact path the control searched: ```tb Private Sub WebView_Error(ByVal code As Long, ByVal msg As String) _ diff --git a/docs/Tutorials/CEF/Getting started.md b/docs/Tutorials/CEF/Getting started.md index f1b378a..290a6ae 100644 --- a/docs/Tutorials/CEF/Getting started.md +++ b/docs/Tutorials/CEF/Getting started.md @@ -18,7 +18,7 @@ To create a project that uses the CEF package, add the right compiler-package re | **twinBASIC - Chromium Embedded Framework Package v109** | Chromium 109 | Windows 7+ | | **twinBASIC - Chromium Embedded Framework Package v145** | Chromium 145 | Windows 10+ | -Use **v145** unless you specifically need to support older operating systems. The package source compiles against all three — picking the reference sets the `CEF_VERSION` compiler constant, which selects the matching API surface. +Use **v145** unless you specifically need to support older operating systems. The package source compiles against all three — picking the reference sets the `CEF_VERSION` compiler constant, which selects the matching API. Add the reference through **Project** → **References** (Ctrl-T) → **TWINPACK PACKAGES**. Tick the desired CEF package, close the dialog, and restart the compiler. Once added, **CefBrowser** appears in the form-designer toolbox. @@ -39,7 +39,7 @@ Download the runtime ZIP that matches both the CEF version and the application b See [CEF Runtime Releases](https://github.com/twinbasic/cef-runtimes/releases/) for the full version list and release notes. -Extract the ZIP into `%LocalAppData%\twinBASIC_CEF_Runtime\`. The version-stamped folder inside the ZIP — for example `145_0_7632_160_Win64` — must land directly under that path, containing `libcef.dll` and its sibling files: +Extract the ZIP into `%LocalAppData%\twinBASIC_CEF_Runtime\`. The version-stamped folder inside the ZIP — for example `145_0_7632_160_Win64` — must be placed directly under that path, containing `libcef.dll` and its sibling files: ```text %LocalAppData%\twinBASIC_CEF_Runtime\145_0_7632_160_Win64\libcef.dll @@ -60,7 +60,7 @@ End Sub ## Bitness must match -The runtime bitness must match the application bitness — a 32-bit twinBASIC build needs the Win32 runtime, a 64-bit build needs the Win64 runtime. Mixing them produces a `libcef.dll` load failure surfaced through the [**Error**](../../tB/Packages/CEF/CefBrowser/#error) event. +The runtime bitness must match the application bitness — a 32-bit twinBASIC build needs the Win32 runtime, a 64-bit build needs the Win64 runtime. Mixing them produces a `libcef.dll` load failure reported through the [**Error**](../../tB/Packages/CEF/CefBrowser/#error) event. ## Create a CefBrowser control on a form @@ -76,7 +76,7 @@ The control starts up asynchronously — the first user-visible event is [**Read ## CefBrowser control properties -Toggle the **Properties** pane to see the design-time-visible surface: [**DocumentURL**](../../tB/Packages/CEF/CefBrowser/#documenturl) (the initial URL the control auto-navigates to once **Ready** fires), [**ZoomFactor**](../../tB/Packages/CEF/CefBrowser/#zoomfactor), [**UserAgent**](../../tB/Packages/CEF/CefBrowser/#useragent), and the standard rect-dockable surface (size, **Anchors**, **Dock**). +Toggle the **Properties** pane to see the design-time-visible properties: [**DocumentURL**](../../tB/Packages/CEF/CefBrowser/#documenturl) (the initial URL the control auto-navigates to once **Ready** fires), [**ZoomFactor**](../../tB/Packages/CEF/CefBrowser/#zoomfactor), [**UserAgent**](../../tB/Packages/CEF/CefBrowser/#useragent), and the standard rect-dockable properties (size, **Anchors**, **Dock**). For the full reference, see the [**CefBrowser** class reference](../../tB/Packages/CEF/CefBrowser/); for what the underlying Chromium runtime supports, consult the [Chromium Embedded Framework documentation](https://bitbucket.org/chromiumembedded/cef/wiki/Home). diff --git a/docs/Tutorials/CEF/Hosting local web assets.md b/docs/Tutorials/CEF/Hosting local web assets.md index 0f1aa3a..2d91410 100644 --- a/docs/Tutorials/CEF/Hosting local web assets.md +++ b/docs/Tutorials/CEF/Hosting local web assets.md @@ -10,7 +10,7 @@ permalink: /Tutorials/CEF/Hosting-Local-Web-Assets A [**CefBrowser**](../../tB/Packages/CEF/CefBrowser/) control can serve HTML, JavaScript, CSS, and any other assets straight from a folder on disk — no embedded HTTP server required. Chromium's [**SetVirtualHostNameToFolderMapping**](../../tB/Packages/CEF/CefBrowser/#setvirtualhostnametofoldermapping) routes a virtual `https://` hostname to a local folder so that resources behave as if they came from a real origin: same-origin `fetch`, Content Security Policy, service workers, and so on all work as expected. -This tutorial walks through the pattern used by *Sample 1b — Chromium Embedded Framework Examples* (forms *Example 2*, *Example 3*, *Example 4*). +This tutorial demonstrates the pattern used by *Sample 1b — Chromium Embedded Framework Examples* (forms *Example 2*, *Example 3*, *Example 4*). ## The three-step pattern @@ -101,7 +101,7 @@ Module Files End Module ``` -[**LoadResIdList**](../../tB/Packages/VB/Global/#loadresidlist) returns every resource ID under the named sub-folder; [**LoadResData**](../../tB/Packages/VB/Global/#loadresdata) hands back the bytes. The helper splits each resource name on `~` to reconstruct the original sub-directory tree on disk — the twinBASIC IDE flattens nested folders by joining their names with `~` when the resources are compiled in. +[**LoadResIdList**](../../tB/Packages/VB/Global/#loadresidlist) returns every resource ID under the named sub-folder; [**LoadResData**](../../tB/Packages/VB/Global/#loadresdata) returns the bytes. The helper splits each resource name on `~` to reconstruct the original sub-directory tree on disk — the twinBASIC IDE flattens nested folders by joining their names with `~` when the resources are compiled in. ## Putting it together diff --git a/docs/Tutorials/CEF/JavaScript interop.md b/docs/Tutorials/CEF/JavaScript interop.md index 63fbcc8..84d0511 100644 --- a/docs/Tutorials/CEF/JavaScript interop.md +++ b/docs/Tutorials/CEF/JavaScript interop.md @@ -57,7 +57,7 @@ Private Sub WebView_JsMessage(ByVal Message As Variant) _ End Sub ``` -The two halves combine cleanly into a request / reply exchange — the page posts a query string, BASIC processes it and posts a result back: +The two halves form a request / reply exchange — the page posts a query string, BASIC processes it and posts a result back: ```tb Private Sub WebView_JsMessage(ByVal Message As Variant) _ @@ -118,7 +118,7 @@ Private Sub WebView_JsAsyncResult( _ End Sub ``` -The [**JsAsyncResult**](../../tB/Packages/CEF/CefBrowser/#jsasyncresult) event carries a *Token* parameter so a single handler can demultiplex multiple in-flight calls. *ErrString* is empty on success. +The [**JsAsyncResult**](../../tB/Packages/CEF/CefBrowser/#jsasyncresult) event includes a *Token* parameter so a single handler can demultiplex multiple in-flight calls. *ErrString* is empty on success. Calls made before the renderer IPC has connected are queued and dispatched once the connection comes up. diff --git a/docs/Tutorials/CEF/Re-entrancy.md b/docs/Tutorials/CEF/Re-entrancy.md index 1c49883..047ea8d 100644 --- a/docs/Tutorials/CEF/Re-entrancy.md +++ b/docs/Tutorials/CEF/Re-entrancy.md @@ -14,12 +14,12 @@ For the most part you don't have to think about any of this. The control raises ## How the control protects you -When the browser or renderer process raises a CEF callback that needs to surface in BASIC, the control: +When the browser or renderer process raises a CEF callback that needs to appear in BASIC, the control: 1. Captures the callback's arguments into a `Type` instance. 2. Calls `PostMessageW` to push a custom message onto the main thread's message queue. 3. Returns immediately — the browser process is unblocked. -4. Later, when the form's message loop picks up the posted message, the control raises the event on the BASIC side. +4. Later, when the form's message loop receives the posted message, the control raises the event on the BASIC side. The handler runs *outside* the original CEF callback. By the time it executes, the browser process has moved on; the handler is free to call any [**CefBrowser**](../../tB/Packages/CEF/CefBrowser/) method or property — [**Navigate**](../../tB/Packages/CEF/CefBrowser/#navigate), [**ExecuteScript**](../../tB/Packages/CEF/CefBrowser/#executescript), [**JsRunAsync**](../../tB/Packages/CEF/CefBrowser/#jsrunasync), even another [**JsRun**](../../tB/Packages/CEF/CefBrowser/#jsrun) — without any re-entrancy concern. @@ -32,7 +32,7 @@ This covers every event the control raises today: ## The NavigationStarting exception -[**NavigationStarting**](../../tB/Packages/CEF/CefBrowser/#navigationstarting) is the one event that *cannot* be fully deferred — its `Cancel` parameter is **ByRef**, so the BASIC handler has to set it *before* the browser process can decide whether to proceed with the navigation. The control still uses `SendMessageW` (synchronous) rather than `PostMessageW` to surface this event, which means the handler runs while the browser process is blocked waiting for the answer. +[**NavigationStarting**](../../tB/Packages/CEF/CefBrowser/#navigationstarting) is the one event that *cannot* be fully deferred — its `Cancel` parameter is **ByRef**, so the BASIC handler has to set it *before* the browser process can decide whether to proceed with the navigation. The control still uses `SendMessageW` (synchronous) rather than `PostMessageW` to deliver this event, which means the handler runs while the browser process is blocked waiting for the answer. The control adds an extra safety net for one specific case: if the renderer-IPC channel happens to be busy connecting at the same moment **NavigationStarting** fires (which can happen in older CEF versions during early page loads), a straight `SendMessageW` would deadlock — BASIC is waiting on the renderer; the renderer is waiting on BASIC. The control detects the situation and uses an interrupt-style mechanism to dispatch *just* the **NavigationStarting** handler on the UI thread without waiting for the renderer IPC. @@ -46,16 +46,16 @@ The practical consequence: **NavigationStarting** handlers should keep their wor Dim product As Long = CefBrowser1.JsRun("multiplyTheseNumbers", 5, 6) ``` -The call blocks the BASIC thread until the renderer process replies with the result. During that block, the renderer is running JavaScript; if that JavaScript calls back into BASIC — via `window.chrome.webview.postMessage(...)`, or via any host-object call that lands on the BASIC thread — there is no thread available to *receive* the call. The renderer waits on BASIC; BASIC waits on the renderer. Deadlock. +The call blocks the BASIC thread until the renderer process replies with the result. During that block, the renderer is running JavaScript; if that JavaScript calls back into BASIC — via `window.chrome.webview.postMessage(...)`, or via any host-object call that arrives on the BASIC thread — there is no thread available to *receive* the call. The renderer waits on BASIC; BASIC waits on the renderer. Deadlock. -The control's source carries this warning directly on the method: +The control's source includes this warning directly on the method: > **!!!WARNING!!!** be careful not to introduce re-entrancy when using this synchronous function, otherwise UI freezes can occur. The safe rule of thumb: - Use [**JsRun**](../../tB/Packages/CEF/CefBrowser/#jsrun) for **pure** JavaScript functions — ones that take inputs, compute, and return a value. No `postMessage`, no host-object calls, no `await` of anything that touches the host. -- Use [**JsRunAsync**](../../tB/Packages/CEF/CefBrowser/#jsrunasync) for anything else — anywhere the JavaScript side might end up wanting to talk to BASIC mid-call. +- Use [**JsRunAsync**](../../tB/Packages/CEF/CefBrowser/#jsrunasync) for anything else — anywhere the JavaScript side might end up wanting to talk to BASIC during the call. ```tb ' Safe — pure JavaScript: takes two numbers, returns one number. @@ -68,7 +68,7 @@ CefBrowser1.JsRunAsync "uploadAndReturnUrl", filePath ## Why the model is simpler than WebView2's -[**WebView2**](../../tB/Packages/WebView2/WebView2/) supports `AddObject` — publishing a BASIC COM object that JavaScript can call directly. That feature carries its own re-entrancy story ([**UseDeferredInvoke**](../../tB/Packages/WebView2/WebView2/#addobject)) because page-initiated host-object calls have to land somewhere. +[**WebView2**](../../tB/Packages/WebView2/WebView2/) supports `AddObject` — publishing a BASIC COM object that JavaScript can call directly. That feature has its own re-entrancy story ([**UseDeferredInvoke**](../../tB/Packages/WebView2/WebView2/#addobject)) because page-initiated host-object calls must end up somewhere. CEF's host-object equivalent isn't exposed yet — see the [WebView2 parity](../../tB/Packages/CEF/#webview2-parity) section of the reference. The only synchronous BASIC ↔ JavaScript boundary CEF currently offers is **JsRun**, so the entire re-entrancy story reduces to *"don't post messages back to BASIC from inside a **JsRun** target"*. diff --git a/docs/Tutorials/CEF/index.md b/docs/Tutorials/CEF/index.md index 6468a24..8acbd88 100644 --- a/docs/Tutorials/CEF/index.md +++ b/docs/Tutorials/CEF/index.md @@ -8,7 +8,7 @@ permalink: /Tutorials/CEF/ The [**CefBrowser**](../../tB/Packages/CEF/CefBrowser/) control hosts a Chromium browser inside a twinBASIC form — navigate to web pages, run local web apps, exchange messages and method calls with JavaScript, and print pages to PDF. Unlike [**WebView2**](../WebView2/), the Chromium runtime ships *alongside* the application rather than being a system component, so the browser version is under the developer's control and the same package works on machines without Edge installed. -These tutorials walk through the most common patterns: +These tutorials demonstrate the most common patterns: - [Getting started](Getting-Started) — adding the package reference, downloading the matching CEF runtime, and dropping a control onto a form. - [Customize the UserDataFolder](Customize-UserDataFolder) — relocating the runtime's working folder for hosted scenarios (Office add-ins, kiosk installs, portable deployments). @@ -23,4 +23,4 @@ The complete sample code for the last four tutorials ships as *Sample 1b — Chr > [!IMPORTANT] > The CEF package is currently in **BETA**. Several features available on [**WebView2**](../../tB/Packages/WebView2/WebView2/) are not yet exposed — see the [WebView2 parity](../../tB/Packages/CEF/#webview2-parity) section of the reference for the current gap list. -For the full surface area of the control itself, see the [**CefBrowser** class reference](../../tB/Packages/CEF/CefBrowser/). +For the full set of members on the control itself, see the [**CefBrowser** class reference](../../tB/Packages/CEF/CefBrowser/). diff --git a/docs/Tutorials/CustomControls/Defining a CustomControl.md b/docs/Tutorials/CustomControls/Defining a CustomControl.md index e53a573..03be45d 100644 --- a/docs/Tutorials/CustomControls/Defining a CustomControl.md +++ b/docs/Tutorials/CustomControls/Defining a CustomControl.md @@ -90,10 +90,10 @@ CustomControls *must* offer a serialization constructor: Public Sub New(Serializer As SerializationInfo) ``` -The passed in Serializer object offers a `Deserialize()` method that you call in order to load the properties that have been set for your control via the form designer. See [Property Sheet and Object Serialization](Properties) for further information. +The passed in Serializer object offers a `Deserialize()` method that you call to load the properties that have been set for your control via the form designer. See [Property Sheet and Object Serialization](Properties) for further information. > [!NOTE] -> The current framework names the serializer type [`SerializeInfo`](../../tB/Packages/CustomControls/Framework/SerializeInfo) (not `SerializationInfo`), and `Deserialize()` is exposed as `RuntimeUISrzDeserialize()`. See the reference page for the current member names and the design-mode / runtime-mode flags also carried on this object. +> The current framework names the serializer type [`SerializeInfo`](../../tB/Packages/CustomControls/Framework/SerializeInfo) (not `SerializationInfo`), and `Deserialize()` is exposed as `RuntimeUISrzDeserialize()`. See the reference page for the current member names and the design-mode / runtime-mode flags also available on this object. *** ## See also diff --git a/docs/Tutorials/CustomControls/index.md b/docs/Tutorials/CustomControls/index.md index 5b11110..8e2b37e 100644 --- a/docs/Tutorials/CustomControls/index.md +++ b/docs/Tutorials/CustomControls/index.md @@ -17,7 +17,7 @@ A few highlights; - support 32-bit RGBA for full alpha-transparency - support high-DPI modes (per-monitor), requiring little thought whilst designing new controls - full debugging support via the usual twinBASIC integrated debugger -- designed for efficiency so that supporting complex controls with hundreds of elements (e.g. a DataGrid with 100's of cells) is easily possible +- designed for efficiency to support complex controls with hundreds of elements (e.g. a DataGrid with 100's of cells) - designed for flexibility, allowing for curved corners, multiple borders, background gradients and much more - the form engine supports anchoring and docking without any considerations needed for CustomControl implementers - simple property sheet synchronization via the built-in form designer diff --git a/docs/Tutorials/WebView2/Building a browser shell.md b/docs/Tutorials/WebView2/Building a browser shell.md index a1d6bea..ccc1abc 100644 --- a/docs/Tutorials/WebView2/Building a browser shell.md +++ b/docs/Tutorials/WebView2/Building a browser shell.md @@ -10,7 +10,7 @@ permalink: /Tutorials/WebView2/Building-A-Browser-Shell A short worked tutorial: turn a [**WebView2**](../../tB/Packages/WebView2/WebView2/) control into a working browser with an address bar, back / forward / reload buttons, zoom, and a few helpers (DevTools, Task Manager, PDF export). -The complete project ships as *Sample 0 — WebView2 Examples* in the New-Project dialog (form *Example 1*). This tutorial walks through its key pieces. +The complete project ships as *Sample 0 — WebView2 Examples* in the New-Project dialog (form *Example 1*). This tutorial describes its key pieces. ## The form @@ -18,7 +18,7 @@ Drop a [**WebView2**](../../tB/Packages/WebView2/WebView2/) control onto a Form ## Navigating -The bare-bones navigation surface — [**Navigate**](../../tB/Packages/WebView2/WebView2/#navigate), [**GoBack**](../../tB/Packages/WebView2/WebView2/#goback), [**GoForward**](../../tB/Packages/WebView2/WebView2/#goforward), [**Reload**](../../tB/Packages/WebView2/WebView2/#reload) — is one-liners: +The bare-bones navigation methods — [**Navigate**](../../tB/Packages/WebView2/WebView2/#navigate), [**GoBack**](../../tB/Packages/WebView2/WebView2/#goback), [**GoForward**](../../tB/Packages/WebView2/WebView2/#goforward), [**Reload**](../../tB/Packages/WebView2/WebView2/#reload) — are one-liners: ```tb Private Sub btnBack_Click() Handles btnBack.Click @@ -81,7 +81,7 @@ End Sub ## PDF export -[**PrintToPdf**](../../tB/Packages/WebView2/WebView2/#printtopdf) saves the current document to disk asynchronously — the result surfaces as [**PrintToPdfCompleted**](../../tB/Packages/WebView2/WebView2/#printtopdfcompleted) or [**PrintToPdfFailed**](../../tB/Packages/WebView2/WebView2/#printtopdffailed): +[**PrintToPdf**](../../tB/Packages/WebView2/WebView2/#printtopdf) saves the current document to disk asynchronously — the result arrives as [**PrintToPdfCompleted**](../../tB/Packages/WebView2/WebView2/#printtopdfcompleted) or [**PrintToPdfFailed**](../../tB/Packages/WebView2/WebView2/#printtopdffailed): ```tb Private Sub btnPDF_Click() Handles btnPDF.Click diff --git a/docs/Tutorials/WebView2/Driving Monaco.md b/docs/Tutorials/WebView2/Driving Monaco.md index 53ca655..93b0453 100644 --- a/docs/Tutorials/WebView2/Driving Monaco.md +++ b/docs/Tutorials/WebView2/Driving Monaco.md @@ -80,7 +80,7 @@ End Sub ## Pushing the initial content -Once Monaco has finished loading, the bootstrap script listens for a `message` event carrying the HTML to seed the editor with. Fire that message after the editor's [**NavigationComplete**](../../tB/Packages/WebView2/WebView2/#navigationcomplete): +Once Monaco has finished loading, the bootstrap script listens for a `message` event containing the HTML to seed the editor with. Fire that message after the editor's [**NavigationComplete**](../../tB/Packages/WebView2/WebView2/#navigationcomplete): ```tb Private Sub WebView_NavigationComplete( _ @@ -111,7 +111,7 @@ That's it — the preview pane re-renders on every edit. ## Detecting a missing Edge runtime -A reasonable fraction of users will run the application on a machine where the WebView2 Evergreen runtime isn't installed. The [**Error**](../../tB/Packages/WebView2/WebView2/#error) event surfaces this case as Win32 error code `&H80070002` (`ERROR_FILE_NOT_FOUND`): +A reasonable fraction of users will run the application on a machine where the WebView2 Evergreen runtime isn't installed. The [**Error**](../../tB/Packages/WebView2/WebView2/#error) event reports this case as Win32 error code `&H80070002` (`ERROR_FILE_NOT_FOUND`): ```tb Private Sub WebView_Error(ByVal code As Long, ByVal msg As String) _ diff --git a/docs/Tutorials/WebView2/Hosting local web assets.md b/docs/Tutorials/WebView2/Hosting local web assets.md index 7cb6e93..67c72c0 100644 --- a/docs/Tutorials/WebView2/Hosting local web assets.md +++ b/docs/Tutorials/WebView2/Hosting local web assets.md @@ -10,7 +10,7 @@ permalink: /Tutorials/WebView2/Hosting-Local-Web-Assets A [**WebView2**](../../tB/Packages/WebView2/WebView2/) control can serve HTML, JavaScript, CSS, and any other assets straight from a folder on disk — no embedded HTTP server required. Edge's [**SetVirtualHostNameToFolderMapping**](../../tB/Packages/WebView2/WebView2/#setvirtualhostnametofoldermapping) routes a virtual `https://` hostname to a local folder so that resources behave as if they came from a real origin: same-origin `fetch`, Content Security Policy, service workers, and so on all work as expected. -This tutorial walks through the pattern used by *Sample 0 — WebView2 Examples* (forms *Example 2*, *Example 3*, *Example 4*). +This tutorial demonstrates the pattern used by *Sample 0 — WebView2 Examples* (forms *Example 2*, *Example 3*, *Example 4*). ## The three-step pattern @@ -99,7 +99,7 @@ Module Files End Module ``` -[**LoadResIdList**](../../tB/Packages/VB/Global/#loadresidlist) returns every resource ID under the named sub-folder; [**LoadResData**](../../tB/Packages/VB/Global/#loadresdata) hands back the bytes. The helper splits each resource name on `~` to reconstruct the original sub-directory tree on disk — the twinBASIC IDE flattens nested folders by joining their names with `~` when the resources are compiled in. +[**LoadResIdList**](../../tB/Packages/VB/Global/#loadresidlist) returns every resource ID under the named sub-folder; [**LoadResData**](../../tB/Packages/VB/Global/#loadresdata) returns the bytes. The helper splits each resource name on `~` to reconstruct the original sub-directory tree on disk — the twinBASIC IDE flattens nested folders by joining their names with `~` when the resources are compiled in. ## Putting it together diff --git a/docs/Tutorials/WebView2/JavaScript interop.md b/docs/Tutorials/WebView2/JavaScript interop.md index d7e47fe..e225ae0 100644 --- a/docs/Tutorials/WebView2/JavaScript interop.md +++ b/docs/Tutorials/WebView2/JavaScript interop.md @@ -142,7 +142,7 @@ Private Sub WebView_JsAsyncResult( _ End Sub ``` -The return value of [**JsRunAsync**](../../tB/Packages/WebView2/WebView2/#jsrunasync) is a token; the [**JsAsyncResult**](../../tB/Packages/WebView2/WebView2/#jsasyncresult) event carries the same token so a single handler can demultiplex multiple in-flight calls. +The return value of [**JsRunAsync**](../../tB/Packages/WebView2/WebView2/#jsrunasync) is a token; the [**JsAsyncResult**](../../tB/Packages/WebView2/WebView2/#jsasyncresult) event includes the same token so a single handler can demultiplex multiple in-flight calls. ### ExecuteScript (fire-and-forget) diff --git a/docs/Tutorials/WebView2/index.md b/docs/Tutorials/WebView2/index.md index a135610..e727b93 100644 --- a/docs/Tutorials/WebView2/index.md +++ b/docs/Tutorials/WebView2/index.md @@ -10,7 +10,7 @@ redirect_from: The [**WebView2**](../../tB/Packages/WebView2/WebView2/) control hosts the Microsoft Edge browser engine inside a twinBASIC form — navigate to web pages, run local web apps, exchange messages and method calls with JavaScript, intercept HTTP traffic, and print pages to PDF. -These tutorials walk through the most common patterns: +These tutorials demonstrate the most common patterns: - [Getting started](Getting-Started) — adding the package references and dropping a control onto a form. - [Customize the UserDataFolder](Customize-UserDataFolder) — relocating the runtime's working folder for hosted scenarios (Office add-ins, kiosk installs). @@ -22,4 +22,4 @@ These tutorials walk through the most common patterns: The complete sample code for the last four tutorials ships as *Sample 0 — WebView2 Examples* in the New-Project dialog. -For the full surface area of the control itself, see the [**WebView2** class reference](../../tB/Packages/WebView2/WebView2/). +For the full set of members on the control itself, see the [**WebView2** class reference](../../tB/Packages/WebView2/WebView2/).