From ba48587fa78fb338c457177e6259663019f4afb8 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Sun, 10 May 2026 23:13:22 +0200 Subject: [PATCH 1/7] Pin the existing Menu pages to IDE. --- docs/IDE/Menu/Add-Ins.md | 1 + docs/IDE/Menu/Debug.md | 1 + docs/IDE/Menu/Edit.md | 1 + docs/IDE/Menu/File.md | 1 + docs/IDE/Menu/Format.md | 1 + docs/IDE/Menu/Help.md | 1 + docs/IDE/Menu/Project.md | 1 + docs/IDE/Menu/Run.md | 1 + docs/IDE/Menu/Tools.md | 1 + docs/IDE/Menu/View.md | 1 + docs/IDE/Menu/Window.md | 1 + 11 files changed, 11 insertions(+) diff --git a/docs/IDE/Menu/Add-Ins.md b/docs/IDE/Menu/Add-Ins.md index 4c72814..fadae9b 100644 --- a/docs/IDE/Menu/Add-Ins.md +++ b/docs/IDE/Menu/Add-Ins.md @@ -1,6 +1,7 @@ --- title: Add-Ins parent: Menu +grand_parent: IDE nav_order: 9 permalink: /tB/IDE/Project/Menu/AddIns --- diff --git a/docs/IDE/Menu/Debug.md b/docs/IDE/Menu/Debug.md index bffcd1b..4857f04 100644 --- a/docs/IDE/Menu/Debug.md +++ b/docs/IDE/Menu/Debug.md @@ -1,6 +1,7 @@ --- title: Debug parent: Menu +grand_parent: IDE nav_order: 6 permalink: /tB/IDE/Project/Menu/Debug --- diff --git a/docs/IDE/Menu/Edit.md b/docs/IDE/Menu/Edit.md index 0008fd0..e881b0f 100644 --- a/docs/IDE/Menu/Edit.md +++ b/docs/IDE/Menu/Edit.md @@ -1,6 +1,7 @@ --- title: Edit parent: Menu +grand_parent: IDE nav_order: 2 permalink: /tB/IDE/Project/Menu/Edit --- diff --git a/docs/IDE/Menu/File.md b/docs/IDE/Menu/File.md index cb0dd98..f0b99ea 100644 --- a/docs/IDE/Menu/File.md +++ b/docs/IDE/Menu/File.md @@ -1,6 +1,7 @@ --- title: File parent: Menu +grand_parent: IDE nav_order: 1 permalink: /tB/IDE/Project/Menu/File --- diff --git a/docs/IDE/Menu/Format.md b/docs/IDE/Menu/Format.md index c0dedd7..998ceeb 100644 --- a/docs/IDE/Menu/Format.md +++ b/docs/IDE/Menu/Format.md @@ -1,6 +1,7 @@ --- title: Format parent: Menu +grand_parent: IDE nav_order: 5 permalink: /tB/IDE/Project/Menu/Format --- diff --git a/docs/IDE/Menu/Help.md b/docs/IDE/Menu/Help.md index 42f525a..92c4d3c 100644 --- a/docs/IDE/Menu/Help.md +++ b/docs/IDE/Menu/Help.md @@ -1,6 +1,7 @@ --- title: Help parent: Menu +grand_parent: IDE nav_order: 11 permalink: /tB/IDE/Project/Menu/Help --- diff --git a/docs/IDE/Menu/Project.md b/docs/IDE/Menu/Project.md index 448d107..7c36846 100644 --- a/docs/IDE/Menu/Project.md +++ b/docs/IDE/Menu/Project.md @@ -1,6 +1,7 @@ --- title: Project parent: Menu +grand_parent: IDE nav_order: 4 permalink: /tB/IDE/Project/Menu/Project --- diff --git a/docs/IDE/Menu/Run.md b/docs/IDE/Menu/Run.md index 113a2ad..57a4240 100644 --- a/docs/IDE/Menu/Run.md +++ b/docs/IDE/Menu/Run.md @@ -1,6 +1,7 @@ --- title: Run parent: Menu +grand_parent: IDE nav_order: 7 permalink: /tB/IDE/Project/Menu/Run --- diff --git a/docs/IDE/Menu/Tools.md b/docs/IDE/Menu/Tools.md index 2d6d923..3111eff 100644 --- a/docs/IDE/Menu/Tools.md +++ b/docs/IDE/Menu/Tools.md @@ -1,6 +1,7 @@ --- title: Tools parent: Menu +grand_parent: IDE nav_order: 8 permalink: /tB/IDE/Project/Menu/Tools --- diff --git a/docs/IDE/Menu/View.md b/docs/IDE/Menu/View.md index 14c5ab3..16fa4e0 100644 --- a/docs/IDE/Menu/View.md +++ b/docs/IDE/Menu/View.md @@ -1,6 +1,7 @@ --- title: View parent: Menu +grand_parent: IDE nav_order: 3 permalink: /tB/IDE/Project/Menu/View --- diff --git a/docs/IDE/Menu/Window.md b/docs/IDE/Menu/Window.md index baaba71..d4daa56 100644 --- a/docs/IDE/Menu/Window.md +++ b/docs/IDE/Menu/Window.md @@ -1,6 +1,7 @@ --- title: Window parent: Menu +grand_parent: IDE nav_order: 10 permalink: /tB/IDE/Project/Menu/Window --- From fa9d8715df6ed73737c1ea2facdb30bac1a6db71 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Sun, 10 May 2026 23:13:34 +0200 Subject: [PATCH 2/7] Document Menu. --- docs/Reference/VB/Menu/index.md | 214 ++++++++++++++++++++++++++++++++ docs/Reference/VB/todo.md | 1 - 2 files changed, 214 insertions(+), 1 deletion(-) create mode 100644 docs/Reference/VB/Menu/index.md diff --git a/docs/Reference/VB/Menu/index.md b/docs/Reference/VB/Menu/index.md new file mode 100644 index 0000000..9f68524 --- /dev/null +++ b/docs/Reference/VB/Menu/index.md @@ -0,0 +1,214 @@ +--- +title: Menu +parent: VB Package +permalink: /tB/Packages/VB/Menu/ +has_toc: false +--- + +# Menu class +{: .no_toc } + +A **Menu** is an item in a Win32 native menu — either a top-level entry on a [**Form**](../Form/)'s or [**MDIForm**](../MDIForm/)'s menu bar, an entry in a drop-down sub-menu, or a separator bar between groups of related commands. Menus are a non-windowed control: they have no [**Left**](#) / [**Top**](#) / [**Width**](#) / [**Height**](#), no font, and no mouse or keyboard events of their own — they are populated, structured, and bound to handlers at design time through the form's menu editor. + +The default property is [**Enabled**](#enabled) and the default event is [**Click**](#click). + +```tb +Private Sub Form_Load() + mnuFileSave.Enabled = False ' grey out until there is something to save +End Sub + +Private Sub mnuFileSave_Click() + SaveDocument +End Sub + +Private Sub mnuViewToolbar_Click() + mnuViewToolbar.Checked = Not mnuViewToolbar.Checked + Toolbar1.Visible = mnuViewToolbar.Checked +End Sub +``` + +* TOC +{:toc} + +## Caption and separators + +[**Caption**](#caption) supplies the text drawn for the menu item. Two Caption values have special meaning: + +- An ampersand (`&`) marks the next character as a keyboard mnemonic — pressing **Alt + that letter** while the menu is open invokes the item, and the letter is underlined in the rendered menu. Use `&&` to display a literal ampersand. +- A Caption consisting of a single hyphen (`"-"`) renders the item as a horizontal separator bar between the surrounding entries. Separator items still receive their own [**Click**](#click) events if invoked programmatically, but the user cannot reach them with the keyboard or mouse. + +```tb +mnuFileNew.Caption = "&New" ' Alt+N while File is open +mnuFileSep1.Caption = "-" ' separator bar +mnuFileSaveAs.Caption = "Save &As..." ' Alt+A +``` + +## Shortcut keys + +[**ShortcutId**](#shortcutid) binds a keyboard accelerator to the menu item. It is typed as [**ShortcutConstants**](../../VBRUN/Constants/ShortcutConstants) — **vbShortcutNone** disables the accelerator, **vbShortcutCtrlS** binds **Ctrl+S**, and so on across the function-key, **Shift+**, and **Ctrl+** ranges. When set, the Win32 runtime appends the corresponding text after a tab character in the rendered Caption — `Save\tCtrl+S` — so the shortcut appears right-aligned in the menu, the conventional way. + +```tb +mnuFileSave.ShortcutId = vbShortcutCtrlS +mnuFilePrint.ShortcutId = vbShortcutCtrlP +``` + +> [!NOTE] +> The hidden [**Shortcut**](#shortcut) **String** property exists only to round-trip the raw text imported from VB6 `.frm` files; it is not consulted at run time. New code should use [**ShortcutId**](#shortcutid). + +## Menu icons + +twinBASIC extends the classic VB6 menu with optional 16×16 (or arbitrary-sized) icons drawn beside the caption. Assign a **StdPicture** to [**Picture**](#picture) and the bitmap is rendered to the left of the caption text. When the supplied picture is a multi-resolution `.ico`, [**IconSizeX**](#iconsizex) and [**IconSizeY**](#iconsizey) pick which embedded image to use; left at `0` (the default), the picture is loaded at its natural size. + +```tb +Set mnuFileSave.Picture = LoadResPicture("MNU_SAVE", vbResBitmap) +mnuFileSave.IconSizeX = 16 +mnuFileSave.IconSizeY = 16 +``` + +## Control arrays + +A control array of menus is the standard way to build a *most-recently-used* file list, a dynamic *Window* sub-menu, or a list of plug-in commands. The array is declared at design time on the first item; further items are added at run time with **Load** and removed with **Unload**, exactly as for a windowed control. Inside a [**Click**](#click) handler shared by every item in the array, [**Index**](#index) identifies which one was picked. + +```tb +Private Sub mnuRecent_Click(Index As Integer) + OpenDocument mnuRecent(Index).Tag ' Tag holds the file path +End Sub +``` + +[**Index**](#index) raises run-time error 343 (*Object not an array*) when read on a menu that is not part of a control array. + +## Window list (MDI) + +When the form hosting the menu is an [**MDIForm**](../MDIForm/), setting [**WindowList**](#windowlist) to **True** at design time turns this menu into the application's *Window* sub-menu — the runtime auto-populates it with one entry per open MDI child, marks the active child with a checkmark, and routes a click on any of those entries to **SetFocus** on the corresponding child. The application typically combines this with an explicit *Cascade* / *Tile* sub-menu that calls [**Arrange**](../MDIForm/#arrange) on the parent. + +## Properties + +### Caption +{: .no_toc } + +The text drawn for the menu item. **String**. An ampersand marks the next character as a mnemonic; `&&` produces a literal ampersand. A Caption of `"-"` renders the item as a horizontal separator. Assignments are reflected immediately in any visible menu bar or pop-up. + +Syntax: *object*.**Caption** [ = *string* ] + +### Checked +{: .no_toc } + +Whether a checkmark is drawn next to the item. **Boolean**, default **False**. Setting it on a top-level (menu-bar) item is supported but visually unusual; the conventional use is on drop-down items that toggle a setting. + +Syntax: *object*.**Checked** [ = *boolean* ] + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a menu. Always **vbMenuControl**. + +### Enabled +{: .no_toc } + +Whether the user can pick the item. A disabled menu item is drawn greyed out and ignores mouse and keyboard activation, including its [**ShortcutId**](#shortcutid) accelerator. **Boolean**, default **True**. **Default property.** + +Syntax: *object*.**Enabled** [ = *boolean* ] + +Disabling a top-level menu-bar item disables its entire drop-down. The runtime rebuilds the menu state when **Enabled** changes, so the change is visible immediately. + +### HelpContextID +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +A **Long** that, in VB6, identified a topic in the application's help file shown when the user pressed **F1** with the menu item highlighted. + +### IconSizeX +{: .no_toc } + +When [**Picture**](#picture) is a multi-resolution `.ico`, the horizontal size in pixels of the embedded image to load. **Long**, default `0` (use the picture's natural size). Pair with [**IconSizeY**](#iconsizey). + +### IconSizeY +{: .no_toc } + +The vertical counterpart to [**IconSizeX**](#iconsizex). **Long**, default `0`. + +### Index +{: .no_toc } + +When the menu is part of a control array, the **Long** zero-based index of this instance within the array. Read-only at run time. Raises run-time error 343 (*Object not an array*) on a menu that is not part of an array. + +### Name +{: .no_toc } + +The unique design-time name of the menu on its parent form. **String**, read-only at run time. Inherited from the base control class. + +### NegotiatePosition +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's ActiveX-document menu negotiation feature; not currently implemented in twinBASIC. + +Typed as [**NegotiatePositionConstants**](../../VBRUN/Constants/NegotiatePositionConstants) (**vbNoNegotiate**, **vbLeft**, **vbMiddle**, **vbRight**) — VB6 used this to decide where a top-level menu should appear in the host application's menu bar when an ActiveX document was activated. + +### Parent +{: .no_toc } + +A reference to the [**Form**](../Form/) (or [**MDIForm**](../MDIForm/) / **UserControl**) that contains this menu. Read-only. + +### Picture +{: .no_toc } + +A **StdPicture** drawn to the left of the caption. **twinBASIC extension** — VB6 menus could not display icons. Assigning **Nothing** removes the icon. Icons are converted to bitmaps internally; pass a bitmap directly to skip the conversion. Pair with [**IconSizeX**](#iconsizex) / [**IconSizeY**](#iconsizey) for multi-resolution `.ico` files. + +Syntax: +- *object*.**Picture** [ = *picture* ] +- **Set** *object*.**Picture** = *picture* + +### Shortcut +{: .no_toc } + +> [!NOTE] +> Hidden, read-only, and unused at run time — exists only to round-trip the raw shortcut text imported from VB6 `.frm` files. Use [**ShortcutId**](#shortcutid) to bind an accelerator. + +### ShortcutId +{: .no_toc } + +The keyboard accelerator bound to this menu item. A member of [**ShortcutConstants**](../../VBRUN/Constants/ShortcutConstants) — **vbShortcutNone** (no accelerator, default), **vbShortcutCtrlA** through **vbShortcutCtrlZ**, **vbShortcutF1** through **vbShortcutF12**, and the **Shift+**, **Ctrl+**, and **Shift+Ctrl+** function-key variants. When set, the matching shortcut text is appended to [**Caption**](#caption) (after a tab) when the menu is rendered. + +Syntax: *object*.**ShortcutId** [ = *value* ] + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the menu item. Ignored by the framework. Inherited from the base control class. Useful for control arrays — e.g. holding the file path that an MRU-list entry should open. + +### Visible +{: .no_toc } + +Whether the menu item is shown. **Boolean**, default **True**. Setting it to **False** removes the entry from the menu without unloading it; setting it back to **True** restores it in its original position. Hiding a top-level menu-bar item rebuilds the menu bar so the surrounding items close the gap. + +Syntax: *object*.**Visible** [ = *boolean* ] + +### WindowList +{: .no_toc } + +When **True** on a menu hosted by an [**MDIForm**](../MDIForm/), turns this menu into the application's *Window* sub-menu — the runtime auto-populates it with one entry per open MDI child and routes the resulting click to **SetFocus** on the corresponding child. **Boolean**, read-only at run time — set at design time. At most one menu per MDI form should have **WindowList** set. + +## Methods + +### 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. + +Syntax: *object*.**Container** + +## Events + +### Click +{: .no_toc } + +Raised when the user picks the menu item — by clicking it, pressing its mnemonic while the menu is open, or pressing its [**ShortcutId**](#shortcutid) accelerator. Also raised when [**PopUpMenu**](../Form/#popupmenu) selects an item. **Default event.** + +Syntax: *object*\_**Click**( ) + +For a menu that is part of a control array, the handler receives the array [**Index**](#index) of the picked item: + +Syntax: *object*\_**Click**( *Index* **As Integer** ) diff --git a/docs/Reference/VB/todo.md b/docs/Reference/VB/todo.md index c78aff0..9d27ee0 100644 --- a/docs/Reference/VB/todo.md +++ b/docs/Reference/VB/todo.md @@ -3,7 +3,6 @@ title: General TODO List for /tB/Packages/VB/ nav_exclude: true redirect_from: - /tB/Packages/VB/DriveListBox - - /tB/Packages/VB/Menu - /tB/Packages/VB/OptionButton - /tB/Packages/VB/PictureBox - /tB/Packages/VB/Printer From 7f0babe6a16553529c8bde73398cc27725f73713 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Sun, 10 May 2026 23:20:52 +0200 Subject: [PATCH 3/7] Document MultiFrame. --- docs/Reference/VB/Frame/index.md | 6 +- docs/Reference/VB/MultiFrame/index.md | 207 ++++++++++++++++++++++++++ 2 files changed, 210 insertions(+), 3 deletions(-) create mode 100644 docs/Reference/VB/MultiFrame/index.md diff --git a/docs/Reference/VB/Frame/index.md b/docs/Reference/VB/Frame/index.md index 4955047..08aef73 100644 --- a/docs/Reference/VB/Frame/index.md +++ b/docs/Reference/VB/Frame/index.md @@ -204,12 +204,12 @@ The mouse cursor shown when the pointer is over the frame (and not over a child ### MultiFramePosition {: .no_toc } -When the frame is hosted inside a **MultiFrame** layout container, the **Long** zero-based position of this frame in the **MultiFrame**'s ordered sequence. Default `-1` (no position assigned). Outside of a **MultiFrame** the value is ignored. +When the frame is hosted inside a [**MultiFrame**](../MultiFrame) layout container, the **Long** zero-based position of this frame in the **MultiFrame**'s ordered sequence. Default `-1` (no position assigned). Outside of a **MultiFrame** the value is ignored. ### MultiFrameSize {: .no_toc } -When the frame is hosted inside a **MultiFrame**, its size as a percentage of the **MultiFrame**'s usable extent (`0` for "share evenly"). **Double**. Outside of a **MultiFrame** the value is ignored. +When the frame is hosted inside a [**MultiFrame**](../MultiFrame), its size as a percentage of the **MultiFrame**'s usable extent (`0` for "share evenly"). **Double**. Outside of a **MultiFrame** the value is ignored. ### Name {: .no_toc } @@ -229,7 +229,7 @@ The frame's opacity as a percentage (0–100, default 100). Values outside the r ### OriginalMultiFramePosition {: .no_toc } -The frame's [**MultiFramePosition**](#multiframeposition) at the moment the **MultiFrame** was last reflowed. **Long**, default `-1`. Used internally by the **MultiFrame** layout engine to compact positions after a frame is moved; not normally written from user code. +The frame's [**MultiFramePosition**](#multiframeposition) at the moment the [**MultiFrame**](../MultiFrame) was last reflowed. **Long**, default `-1`. Used internally by the **MultiFrame** layout engine to compact positions after a frame is moved; not normally written from user code. ### Parent {: .no_toc } diff --git a/docs/Reference/VB/MultiFrame/index.md b/docs/Reference/VB/MultiFrame/index.md new file mode 100644 index 0000000..d93e162 --- /dev/null +++ b/docs/Reference/VB/MultiFrame/index.md @@ -0,0 +1,207 @@ +--- +title: MultiFrame +parent: VB Package +permalink: /tB/Packages/VB/MultiFrame/ +has_toc: false +--- + +# MultiFrame class +{: .no_toc } + +A **MultiFrame** is a layout container that arranges a set of [**Frame**](../Frame) controls in a single horizontal or vertical strip and resizes them whenever the **MultiFrame** itself is resized. Each contained frame keeps its own border, caption, and child controls; the **MultiFrame** decides only where each frame is placed and how wide (or tall) it is. + +A frame is associated with a **MultiFrame** by setting the frame's [**Container**](../Frame#container) to point at the **MultiFrame**. The frame's [**MultiFramePosition**](../Frame#multiframeposition) chooses its place in the sequence and [**MultiFrameSize**](../Frame#multiframesize) gives its size as a percentage of the **MultiFrame**'s usable extent. Frames whose **MultiFrameSize** is `0` share whatever extent remains after the fixed-size frames have been laid out. + +The default event is [**Initialize**](#initialize). There is no default property. + +```tb +Private Sub Form_Load() + mfPanels.Direction = vbDirectionHorizontal + + Set fraLeft.Container = mfPanels + fraLeft.MultiFramePosition = 0 + fraLeft.MultiFrameSize = 30 ' fixed 30% of the strip + + Set fraCenter.Container = mfPanels + fraCenter.MultiFramePosition = 1 + fraCenter.MultiFrameSize = 0 ' shares the remaining space + + Set fraRight.Container = mfPanels + fraRight.MultiFramePosition = 2 + fraRight.MultiFrameSize = 0 ' shares the remaining space +End Sub +``` + +* TOC +{:toc} + +## Direction and sizing + +[**Direction**](#direction) chooses between **vbDirectionHorizontal** (the default — frames laid out left-to-right) and **vbDirectionVertical** (frames stacked top-to-bottom). Changing **Direction** at run time triggers an immediate re-layout. + +For each contained frame, [**MultiFrameSize**](../Frame#multiframesize) gives its extent as a percentage of the **MultiFrame**'s width (horizontal) or height (vertical). Frames whose **MultiFrameSize** is `0` share the leftover extent equally — so a typical pattern is to give the edge panels fixed percentages and leave one centre panel at `0` so it absorbs window resizes. Percentages are not clamped; if the fixed-size frames already exceed the **MultiFrame**'s extent the auto-sized frames collapse to zero. + +## Position and shuffling + +Each contained frame is anchored to a sequential position via its [**MultiFramePosition**](../Frame#multiframeposition) property (zero-based). Positions are kept contiguous: assigning a frame a new **MultiFramePosition** at run time makes the **MultiFrame** shuffle the remaining frames up or down so that the old slot closes and the new slot opens at the requested index. Duplicate or out-of-range positions are normalised at the next layout pass — the **MultiFrame** falls back to the original control order on the parent form, renumbering the frames sequentially from `0`. + +A frame whose [**Container**](../Frame#container) is the **MultiFrame** but whose **MultiFramePosition** is `-1` is appended at the next free slot the first time the layout is built. + +## Adopting frames at run time + +The mapping from frame to **MultiFrame** is discovered from the parent form's control collection on each layout pass: a frame appears in the strip exactly when its [**Container**](../Frame#container) property points at the **MultiFrame**. The discovered set is then cached. To force the cache to be rebuilt — for example after re-parenting a frame at run time — assign any value to [**FramesCount**](#framescount): + +```tb +Set fraExtra.Container = mfPanels +mfPanels.FramesCount = 0 ' assigned value is ignored; the layout cache is rebuilt +``` + +The **MultiFrame** repositions the frame's existing window in place; it does not change the frame's Win32 parent, so the frame remains a child of the form and continues to raise its events normally. + +## Properties + +### Anchors +{: .no_toc } + +The set of edges of the parent that the **MultiFrame**'s corresponding edges follow when the parent resizes. Read-only — assign individual `.Left`, `.Top`, `.Right`, `.Bottom` flags through the returned **Anchors** object. + +### BackColor +{: .no_toc } + +The background colour of the **MultiFrame**'s drawing surface, as an **OLE_COLOR**. Defaults to the system window-background colour. Visible only where the contained frames do not fully cover the extent — e.g. when their **MultiFrameSize**s sum to less than 100%. + +### Container +{: .no_toc } + +The control that hosts this **MultiFrame** — typically the form. Read with **Get**, change with **Set**. Setting **Container** re-parents the **MultiFrame** to a different container at run time. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control. Always **vbShape**. + +### Direction +{: .no_toc } + +The orientation in which contained frames are laid out. A member of **MultiFrameDirectionConstants**: **vbDirectionHorizontal** (0, default — frames laid out left-to-right) or **vbDirectionVertical** (1 — frames stacked top-to-bottom). Changing **Direction** triggers an immediate re-layout of the contained frames. + +### Dock +{: .no_toc } + +Where the **MultiFrame** is docked within its container. A member of [**DockModeConstants**](../../VBRUN/Constants/DockModeConstants): **vbDockNone** (default), **vbDockLeft**, **vbDockTop**, **vbDockRight**, **vbDockBottom**, or **vbDockFill**. Docked **MultiFrame**s ignore [**Anchors**](#anchors). + +### FramesCount +{: .no_toc } + +The number of [**Frame**](../Frame) controls currently in the **MultiFrame**'s layout. **Long**. + +Syntax: *object*.**FramesCount** [ = *value* ] + +Reading **FramesCount** returns the size of the current layout cache. Assigning *any* value discards the cache so it is rebuilt on the next layout pass — the assigned number itself is ignored. Use the assignment as a manual refresh after re-parenting a frame at run time. + +### Height +{: .no_toc } + +The **MultiFrame**'s height, in twips by default (or in the container's **ScaleMode** units). **Double**. + +### hWnd +{: .no_toc } + +The Win32 window handle for the **MultiFrame**'s drawing surface, as a **LongPtr**. Read-only. Useful for passing to API functions. + +### Index +{: .no_toc } + +When the **MultiFrame** is part of a control array, the **Long** zero-based index of this instance within the array. Reading **Index** on a non-array instance raises run-time error 343 (*Object not an array*). Read-only at run time. + +### Left +{: .no_toc } + +The horizontal distance from the left edge of the container to the left edge of the **MultiFrame**. **Double**. + +### Name +{: .no_toc } + +The unique design-time name of the **MultiFrame** on its parent form. Read-only at run time. + +### Parent +{: .no_toc } + +A reference to the [**Form**](../Form) that ultimately contains the **MultiFrame**. Read-only. Distinct from [**Container**](#container), which returns the immediate parent. + +### TabIndex +{: .no_toc } + +The position of the **MultiFrame** in the form's TAB-key navigation order. **Long**. + +> [!NOTE] +> A **MultiFrame** never takes the focus itself — **TabIndex** is preserved for compatibility but has no observable effect on the user. + +### TabStop +{: .no_toc } + +Whether the **MultiFrame** participates in TAB-key navigation. **Boolean**, default **True**. + +> [!NOTE] +> A **MultiFrame** never takes the focus itself — **TabStop** is preserved for compatibility but has no observable effect on the user. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the **MultiFrame**. Ignored by the framework. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the **MultiFrame**. **Double**. + +### Visible +{: .no_toc } + +Whether the **MultiFrame** is shown. **Boolean**, default **True**. The contained frames' own visibility is independent of this setting; hiding the **MultiFrame** hides its drawing surface but does not directly hide the frames. + +### Width +{: .no_toc } + +The **MultiFrame**'s width. **Double**. + +## Methods + +### Move +{: .no_toc } + +Repositions and optionally resizes the **MultiFrame** in a single call. Contained frames are re-laid out to match the new extent. + +Syntax: *object*.**Move** *Left* [, *Top* [, *Width* [, *Height* ] ] ] + +*Left* +: *required* A **Single** giving the new horizontal position. + +*Top*, *Width*, *Height* +: *optional* New values for the corresponding properties. Omitted values are left unchanged. + +### Refresh +{: .no_toc } + +Forces an immediate repaint of the **MultiFrame**'s drawing surface. + +Syntax: *object*.**Refresh** + +### ZOrder +{: .no_toc } + +Brings the **MultiFrame** to the front or back of its sibling stack within the container. + +Syntax: *object*.**ZOrder** [ *Position* ] + +*Position* +: *optional* A member of [**ZOrderConstants**](../../VBRUN/Constants/ZOrderConstants): **vbBringToFront** (0, default) or **vbSendToBack** (1). + +## Events + +### Initialize +{: .no_toc } + +Raised once, after the **MultiFrame**'s underlying window has been created but before the first layout pass has run. Useful for adjusting [**Direction**](#direction) or contained-frame sizes from code at start-up so that the very first layout reflects them. **Default event.** + +Syntax: *object*\_**Initialize**( ) From 348e2e89394203d97db4c957a10d131cf0201894 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Sun, 10 May 2026 23:33:42 +0200 Subject: [PATCH 4/7] Document OLE. --- docs/Reference/VB/OLE/index.md | 864 +++++++++++++++++++++++++++++++++ 1 file changed, 864 insertions(+) create mode 100644 docs/Reference/VB/OLE/index.md diff --git a/docs/Reference/VB/OLE/index.md b/docs/Reference/VB/OLE/index.md new file mode 100644 index 0000000..abdca42 --- /dev/null +++ b/docs/Reference/VB/OLE/index.md @@ -0,0 +1,864 @@ +--- +title: OLE +parent: VB Package +permalink: /tB/Packages/VB/OLE/ +has_toc: false +--- + +# OLE class +{: .no_toc } + +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. + +There is no default property. The default-designer event is [**Click**](#click). + +```tb +' The OLE-specific calls below are not currently functional +' in twinBASIC; the example is given for reference only. +Private Sub Form_Load() + OLE1.CreateEmbed vbNullString, "Excel.Sheet" ' [Unimplemented] +End Sub + +Private Sub OLE1_Click() + OLE1.DoVerb vbOLEPrimary ' [Unimplemented] +End Sub +``` + +* TOC +{:toc} + +## Linked vs embedded objects + +An OLE container holds either a *linked* object — a reference to a document on disk that opens in its registered server when activated — or an *embedded* object whose data is stored inside the host form's data stream. [**CreateLink**](#createlink) creates a linked object from an existing file; [**CreateEmbed**](#createembed) creates a fresh embedded object of a given class. [**OLEType**](#oletype) reports which form the current contents take, and [**OLETypeAllowed**](#oletypeallowed) restricts which forms the container will accept at design or run time. + +[**SourceDoc**](#sourcedoc) and [**SourceItem**](#sourceitem) identify the linked file (and, for partial links, the item within it). [**Class**](#class) holds the ProgID of the embedded server (e.g. `"Word.Document"`, `"Excel.Sheet"`). + +## Verbs + +Each OLE server registers a set of *verbs* — labelled actions like *Open*, *Edit*, or *Play*. [**FetchVerbs**](#fetchverbs) populates the per-instance verb list, exposed as the indexed [**ObjectVerbs**](#objectverbs), [**ObjectVerbFlags**](#objectverbflags), and [**ObjectVerbsCount**](#objectverbscount) properties. [**DoVerb**](#doverb) executes a verb by index — passing **vbOLEPrimary** runs the server's primary verb, which is the action invoked by a double-click. [**AutoVerbMenu**](#autoverbmenu) controls whether right-clicking the control automatically pops up the verb menu. + +## Activation and display + +[**AutoActivate**](#autoactivate) chooses when the embedded object is activated for in-place editing — manually, on focus, or on a double-click. [**DisplayType**](#displaytype) selects between rendering the object's content directly and rendering a registered icon. [**SizeMode**](#sizemode) chooses how the object's bitmap is fitted into the container (clipped, stretched, auto-sized, or zoomed). + +## Updates and storage + +A linked object's last-cached presentation can be re-fetched from its server with [**Update**](#update); [**UpdateOptions**](#updateoptions) decides whether updates happen automatically or only on demand. The container can be persisted out of an open file with [**SaveToFile**](#savetofile) (or [**SaveToOle1File**](#savetoole1file) for the legacy OLE1 stream format) and re-loaded with [**ReadFromFile**](#readfromfile), in each case using a Basic file number opened with **Open**. [**InsertObjDlg**](#insertobjdlg) and [**PasteSpecialDlg**](#pastespecialdlg) raise the standard Windows OLE dialogs for picking an object class or a clipboard format. + +## Data binding + +Setting [**DataSource**](#datasource) and [**DataField**](#datafield) connects the container's contents to a binary field on a [**Data**](../Data) control's recordset, so the embedded object is loaded from and saved back into the row. [**DataChanged**](#datachanged) reports whether the contained object differs from the bound row's stored value. + +## Properties + +### Action +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +A run-time-only **Integer** that, when assigned, performs one of the predefined OLE actions such as *create*, *delete*, *paste*, or *update*. Modern code uses the equivalent named methods ([**CreateEmbed**](#createembed), [**Delete**](#delete), [**Paste**](#paste), [**Update**](#update), …) instead. + +### Anchors +{: .no_toc } + +The set of edges of the parent that the OLE control's corresponding edges follow when the parent resizes. Read-only — assign individual `.Left`, `.Top`, `.Right`, `.Bottom` flags through the returned **Anchors** object. + +### Appearance +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Determines how the container's border is drawn. A member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). + +### AppIsRunning +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +A run-time-only **Boolean**: **True** while the OLE server hosting the embedded object is running. Assigning **True** starts the server; assigning **False** shuts it down. + +### AutoActivate +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Selects when the embedded object is activated for in-place editing. A member of [**OLEContainerActivateConstants**](../../VBRUN/Constants/OLEContainerActivateConstants): **vbOLE_ActivateManual**, **vbOLE_ActivateGetFocus**, **vbOLE_ActivateDoubleclick** (default), or **vbOLE_ActivateAuto**. + +### AutoVerbMenu +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +When **True** (default), right-clicking the container automatically pops up a menu of the contained object's registered verbs. **Boolean**. + +### BackColor +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +The background colour, as an **OLE_COLOR**. Defaults to the system window-background colour. + +### BackStyle +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Selects between an opaque and transparent background ([**BackFillStyleConstants**](../../VBRUN/Constants/BackFillStyleConstants)): **vbBFTransparent** or **vbBFOpaque** (default). + +### BorderStyle +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Whether the container is drawn with a border. A member of [**ControlBorderStyleConstants**](../../VBRUN/Constants/ControlBorderStyleConstants): **vbNoBorder** or **vbFixedSingleBorder** (default). + +### CausesValidation +{: .no_toc } + +Determines whether the previously focused control's [**Validate**](#validate) event runs before this control receives the focus. **Boolean**, default **True**. + +### Class +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +The ProgID of the OLE server class for the contained object — for example `"Word.Document"` or `"Excel.Sheet"`. **String**. Used together with [**SourceDoc**](#sourcedoc) and [**SourceItem**](#sourceitem) when populating the container at design time, or as the default class for [**InsertObjDlg**](#insertobjdlg). + +### Container +{: .no_toc } + +The control that hosts this OLE control — typically the form. Read with **Get**, change with **Set**. Setting **Container** re-parents the control to a different container at run time. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as an OLE container. Always **vbOLEControl**. + +### Data +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +A run-time-only **Long** handle to the data block returned for the format named in [**Format**](#format). Used together with the [**ObjectAcceptFormats**](#objectacceptformats) / [**ObjectGetFormats**](#objectgetformats) machinery to round-trip raw OLE data. + +### DataChanged +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +A run-time-only **Boolean**: **True** if the bound recordset field has changed since the container last loaded it. Cleared after a successful save. + +### DataField +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +The name of the binary field, in the recordset of the bound [**DataSource**](#datasource), whose contents are stored and retrieved by the OLE container. **String**. + +### DataSource +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +A reference to a [**Data**](../Data) control (or other **DataSource** provider) whose recordset supplies the value for [**DataField**](#datafield). Set with **Set**. + +### DataText +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +A run-time-only **String** alias for transferring text-format data into and out of the contained object's clipboard equivalent. + +### DisplayType +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Whether the container shows the object's content or its registered icon. A member of [**OLEContainerDisplayTypeConstants**](../../VBRUN/Constants/OLEContainerDisplayTypeConstants): **vbOLE_DisplayContent** (default) or **vbOLE_DisplayIcon**. + +### Dock +{: .no_toc } + +Where the OLE control is docked within its container. A member of [**DockModeConstants**](../../VBRUN/Constants/DockModeConstants): **vbDockNone** (default), **vbDockLeft**, **vbDockTop**, **vbDockRight**, **vbDockBottom**, or **vbDockFill**. Docked controls ignore [**Anchors**](#anchors). + +### DragIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor while the control is being drag-and-dropped (see [**Drag**](#drag) and [**DragMode**](#dragmode)). + +### DragMode +{: .no_toc } + +Whether the control should drag itself when the user holds the mouse over it. A member of [**DragModeConstants**](../../VBRUN/Constants/DragModeConstants): **vbManual** (0, default — call [**Drag**](#drag) from code) or **vbAutomatic** (1). + +### Enabled +{: .no_toc } + +Determines whether the control accepts user input. **Boolean**, default **True**. + +### FileNumber +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +A run-time-only **Integer** giving the Basic file number passed to the most recent [**ReadFromFile**](#readfromfile), [**SaveToFile**](#savetofile), or [**SaveToOle1File**](#savetoole1file) call. + +### Format +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +The clipboard format identifier currently associated with the [**Data**](#data) handle. **String**. + +### Height +{: .no_toc } + +The control's height, in twips by default (or in the container's **ScaleMode** units). **Single**. + +### HelpContextID +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. Available only when the host build defines `FEATURE_HELP`. + +A **Long** identifying a topic in the application's help file, retrieved when the user presses **F1** while the control has focus. + +### HostName +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +The friendly name the OLE server should display for the host application — e.g. shown in Word's title bar while editing the embedded document in place. **String**. + +### hWnd +{: .no_toc } + +The Win32 window handle for the underlying control, as a **LongPtr**. Read-only. Useful for passing to API functions. + +### Index +{: .no_toc } + +When the control is part of a control array, the **Long** zero-based index of this instance within the array. Reading **Index** on a non-array instance raises run-time error 343 (*Object not an array*). Read-only at run time. + +### Left +{: .no_toc } + +The horizontal distance from the left edge of the container to the left edge of the control. **Single**. + +### LpOleObject +{: .no_toc } + +> [!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. + +### MiscFlags +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +A bit-mask of miscellaneous container behaviours (see [**OLEContainerConstants**](../../VBRUN/Constants/OLEContainerConstants) — **vbOLEMiscFlagMemStorage**, **vbOLEMiscFlagDisableInPlace**). **Long**. + +### MouseIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor when [**MousePointer**](#mousepointer) is **vbCustom** and the pointer is over the control. + +### MousePointer +{: .no_toc } + +The mouse cursor shown when the pointer is over the control. A member of [**MousePointerConstants**](../../VBRUN/Constants/MousePointerConstants). + +### Name +{: .no_toc } + +The unique design-time name of the control on its parent form. Read-only at run time. + +### object +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +A run-time-only **Object** reference to the OLE Automation interface of the contained object — the late-bound entry point for scripting it. **Read-only**. + +### ObjectAcceptFormats +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +An indexed **String** property listing the clipboard formats that the contained object can accept on a paste. Use [**ObjectAcceptFormatsCount**](#objectacceptformatscount) to bound the index. + +### ObjectAcceptFormatsCount +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +The number of entries in [**ObjectAcceptFormats**](#objectacceptformats). **Integer**. + +### ObjectGetFormats +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +An indexed **String** property listing the clipboard formats that the contained object can produce on a copy. Use [**ObjectGetFormatsCount**](#objectgetformatscount) to bound the index. + +### ObjectGetFormatsCount +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +The number of entries in [**ObjectGetFormats**](#objectgetformats). **Integer**. + +### ObjectVerbFlags +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +An indexed **Long** property giving the menu-flag bit-mask for each entry in [**ObjectVerbs**](#objectverbs). The flag values match the Win32 `MF_*` menu constants and indicate whether the verb item is greyed, checked, etc. + +### ObjectVerbs +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +An indexed **String** property listing the names of the verbs registered for the contained object — populated by [**FetchVerbs**](#fetchverbs). Pass an index to [**DoVerb**](#doverb) to invoke a verb. + +### ObjectVerbsCount +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +The number of entries in [**ObjectVerbs**](#objectverbs). **Long**. + +### OLEDropAllowed +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +When **True**, the container accepts OLE objects dragged onto it from outside the application. **Boolean**, default **False**. + +### OLEType +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +A run-time-only **Integer** reporting whether the contained object is currently linked, embedded, or empty (see [**OLEContainerConstants**](../../VBRUN/Constants/OLEContainerConstants) — **vbOLELinked**, **vbOLEEmbedded**, **vbOLEEither**, **vbOLENone**). + +### OLETypeAllowed +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Restricts which kinds of contained object the container will accept. A member of [**OLEContainerTypesAllowedConstants**](../../VBRUN/Constants/OLEContainerTypesAllowedConstants): **vbOLE_Linked**, **vbOLE_Embedded**, or **vbOLE_Either** (default). + +### Parent +{: .no_toc } + +A reference to the [**Form**](../Form) (or **UserControl**) that contains this control. Read-only. + +### PasteOK +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +A run-time-only, read-only **Boolean**: **True** if the current clipboard contents are in a format the contained object would accept via [**Paste**](#paste). + +### Picture +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +A run-time-only, read-only **IPictureDisp** giving the contained object's current presentation as a picture, suitable for printing or copying onto a [**PictureBox**](../PictureBox). + +### SizeMode +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +How the contained object's bitmap is fitted into the container. A member of [**OLEContainerSizeModeConstants**](../../VBRUN/Constants/OLEContainerSizeModeConstants): **vbOLE_SizeClip** (default), **vbOLE_SizeStretch**, **vbOLE_SizeAutoSize**, or **vbOLE_SizeZoom**. + +### SourceDoc +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +The full path of the source file used by [**CreateLink**](#createlink) (and the default value for [**InsertObjDlg**](#insertobjdlg)). **String**. + +### SourceItem +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +The named item within [**SourceDoc**](#sourcedoc) that the link refers to — for example, an Excel range name. **String**. + +### TabIndex +{: .no_toc } + +The position of the control in the form's TAB-key navigation order. **Long**. + +### TabStop +{: .no_toc } + +Whether the user can reach the control by pressing the **TAB** key. **Boolean**, default **True**. A disabled control is skipped regardless of this setting. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the control. Ignored by the framework. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the control. **Single**. + +### UpdateOptions +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +How a linked object's cached presentation is refreshed. A member of [**OLEContainerUpdateOptionsConstants**](../../VBRUN/Constants/OLEContainerUpdateOptionsConstants): **vbOLE_UpdateAutomatic** (default), **vbOLE_UpdateFrozen**, or **vbOLE_UpdateManual**. + +### Verb +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +A **Long** verb index used by the legacy [**Action**](#action) property when performing the *do verb* action. New code should call [**DoVerb**](#doverb) directly. + +### Visible +{: .no_toc } + +Whether the control is shown. **Boolean**, default **True**. + +### WhatsThisHelpID +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. Available only when the host build defines `FEATURE_HELP`. + +A **Long** identifying a "What's This?" help-pop-up topic in the application's help file. See [**ShowWhatsThis**](#showwhatsthis). + +### Width +{: .no_toc } + +The control's width. **Single**. + +## Methods + +### Close +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Closes the contained object, ending the running server session if one is open. The container's data is preserved; only the live editing connection is dropped. + +Syntax: *object*.**Close** + +### Copy +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Copies the contained object to the system clipboard. + +Syntax: *object*.**Copy** + +### CreateEmbed +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Creates a new embedded object of the given class, optionally pre-filled from a template file. + +Syntax: *object*.**CreateEmbed** *SourceDoc* [, *Class* ] + +*SourceDoc* +: *required* A **String**. Path of a file to use as a template for the new object, or `vbNullString` to create a blank object. + +*Class* +: *optional* A **Variant** **String** ProgID identifying the OLE server class to instantiate (e.g. `"Word.Document"`). Required when *SourceDoc* is empty. + +### CreateLink +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Creates a linked object that references an existing file on disk. + +Syntax: *object*.**CreateLink** *SourceDoc* [, *SourceItem* ] + +*SourceDoc* +: *required* A **String** giving the full path of the source file. + +*SourceItem* +: *optional* A **Variant** **String** identifying a named item within the source file (e.g. an Excel range name) to link to a fragment rather than the whole document. + +### Delete +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Removes the contained object from the container. Releases all resources associated with it. + +Syntax: *object*.**Delete** + +### DoVerb +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Invokes a registered verb on the contained object. The standard verb constants are defined in [**OLEContainerConstants**](../../VBRUN/Constants/OLEContainerConstants) — **vbOLEPrimary** (0), **vbOLEShow** (-1), **vbOLEOpen** (-2), **vbOLEHide** (-3), **vbOLEUIActivate** (-4), **vbOLEInPlaceActivate** (-5), **vbOLEDiscardUndoState** (-6); positive indices refer to the per-server entries in [**ObjectVerbs**](#objectverbs). + +Syntax: *object*.**DoVerb** [ *Verb* ] + +*Verb* +: *optional* A **Variant** **Long**. Defaults to **vbOLEPrimary** if omitted. + +### Drag +{: .no_toc } + +Begins, completes, or cancels a manual drag-and-drop operation. Typically called from a [**MouseDown**](#mousedown) handler when [**DragMode**](#dragmode) is **vbManual**. + +Syntax: *object*.**Drag** [ *Action* ] + +*Action* +: *optional* A member of [**DragConstants**](../../VBRUN/Constants/DragConstants): **vbCancel** (0), **vbBeginDrag** (1, default), or **vbEndDrag** (2). + +### FetchVerbs +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Re-reads the verb list from the contained object's server and refreshes [**ObjectVerbs**](#objectverbs), [**ObjectVerbFlags**](#objectverbflags), and [**ObjectVerbsCount**](#objectverbscount). + +Syntax: *object*.**FetchVerbs** + +### InsertObjDlg +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Displays the standard Windows *Insert Object* dialog so the user can choose between a new embedded object, an existing file (linked or embedded), or an icon. + +Syntax: *object*.**InsertObjDlg** + +### Move +{: .no_toc } + +Repositions and optionally resizes the control in a single call. + +Syntax: *object*.**Move** *Left* [, *Top* [, *Width* [, *Height* ] ] ] + +*Left* +: *required* A **Single** giving the new horizontal position. + +*Top*, *Width*, *Height* +: *optional* New values for the corresponding properties. Omitted values are left unchanged. + +### Paste +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Pastes the current clipboard contents into the container, if [**PasteOK**](#pasteok) reports the format is acceptable. + +Syntax: *object*.**Paste** + +### PasteSpecialDlg +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Displays the standard Windows *Paste Special* dialog so the user can choose how the current clipboard contents are pasted (link, embed, or as a specific format). + +Syntax: *object*.**PasteSpecialDlg** + +### ReadFromFile +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Reads the container's contents from a Basic-style binary file previously written with [**SaveToFile**](#savetofile). + +Syntax: *object*.**ReadFromFile** *FileNumber* + +*FileNumber* +: *required* An **Integer**. The file number returned by the **Open** statement, on a stream opened **For Binary**. + +### SaveToFile +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Writes the container's contents — including the linked or embedded object's data and any presentation cache — to a Basic-style binary file in the current OLE2 stream format. + +Syntax: *object*.**SaveToFile** *FileNumber* + +*FileNumber* +: *required* An **Integer** opened **For Binary**. + +### SaveToOle1File +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Writes the container's contents in the legacy OLE1 stream format. Provided for round-tripping data files produced by very old applications; new code should use [**SaveToFile**](#savetofile). + +Syntax: *object*.**SaveToOle1File** *FileNumber* + +*FileNumber* +: *required* An **Integer** opened **For Binary**. + +### SetFocus +{: .no_toc } + +Moves the input focus to the control. The control must be both [**Visible**](#visible) and [**Enabled**](#enabled), or run-time error 5 (*Invalid procedure call or argument*) is raised. + +Syntax: *object*.**SetFocus** + +### ShowWhatsThis +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. Available only when the host build defines `FEATURE_HELP`. + +Displays the topic identified by [**WhatsThisHelpID**](#whatsthishelpid) as a "What's This?" pop-up. + +Syntax: *object*.**ShowWhatsThis** + +### Update +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +For a linked object, retrieves the latest data from the source file and refreshes the cached presentation. For an embedded object whose server is running, asks the server to commit any pending changes back into the container. + +Syntax: *object*.**Update** + +### ZOrder +{: .no_toc } + +Brings the control to the front or back of its sibling stack. + +Syntax: *object*.**ZOrder** [ *Position* ] + +*Position* +: *optional* A member of [**ZOrderConstants**](../../VBRUN/Constants/ZOrderConstants): **vbBringToFront** (0, default) or **vbSendToBack** (1). + +## Events + +### Click +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Raised when the user clicks the container with any mouse button. **Default-designer event.** + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Raised when the user double-clicks the container. With the default [**AutoActivate**](#autoactivate) setting **vbOLE_ActivateDoubleclick**, this is the same gesture that activates the contained object for in-place editing. + +Syntax: *object*\_**DblClick**( ) + +### DragDrop +{: .no_toc } + +Raised on the destination control when a manual drag operation ends over it. + +Syntax: *object*\_**DragDrop**( *Source* **As Control**, *X* **As Single**, *Y* **As Single** ) + +### DragOver +{: .no_toc } + +Raised on the control under the cursor while a manual drag operation is in progress. + +Syntax: *object*\_**DragOver**( *Source* **As Control**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### GotFocus +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Raised when the control receives the input focus. + +Syntax: *object*\_**GotFocus**( ) + +### Initialize +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Raised once, after the control's underlying window has been created. + +Syntax: *object*\_**Initialize**( ) + +### KeyDown +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Raised when the user presses any key while the control has focus. + +Syntax: *object*\_**KeyDown**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### KeyPress +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Raised when the user types a character that produces an ANSI keystroke. + +Syntax: *object*\_**KeyPress**( *KeyAscii* **As Integer** ) + +### KeyUp +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Raised when the user releases a key while the control has focus. + +Syntax: *object*\_**KeyUp**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### LostFocus +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Raised when the control loses the input focus. + +Syntax: *object*\_**LostFocus**( ) + +### MouseDown +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Raised when the user presses any mouse button over the control. + +Syntax: *object*\_**MouseDown**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseMove +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Raised when the cursor moves over the control. + +Syntax: *object*\_**MouseMove**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseUp +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Raised when the user releases a mouse button over the control. + +Syntax: *object*\_**MouseUp**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### ObjectMove +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Raised when the contained object asks the container to relocate or resize itself — typically in response to in-place editing changes. + +Syntax: *object*\_**ObjectMove**( *Left* **As Single**, *Top* **As Single**, *Width* **As Single**, *Height* **As Single** ) + +### Resize +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Raised when the contained object reports a new natural size — for example, after an embedded image is replaced with one of different dimensions. + +Syntax: *object*\_**Resize**( *HeightNew* **As Single**, *WidthNew* **As Single** ) + +### Updated +{: .no_toc } + +> [!NOTE] +> Reserved for VB6 compatibility; not currently implemented in twinBASIC. + +Raised after the contained object has been modified, so the host can flag itself as dirty. *Code* is one of the status values in [**OLEContainerConstants**](../../VBRUN/Constants/OLEContainerConstants): **vbOLEChanged**, **vbOLESaved**, **vbOLEClosed**, or **vbOLERenamed**. + +Syntax: *object*\_**Updated**( *Code* **As Integer** ) + +### Validate +{: .no_toc } + +Raised when the focus is moving to another control whose [**CausesValidation**](#causesvalidation) is **True**. Setting *Cancel* to **True** keeps the focus on this control. + +Syntax: *object*\_**Validate**( *Cancel* **As Boolean** ) From 05773dcff3681b5ef8cd97060eb4b1fa81ab2536 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Sun, 10 May 2026 23:40:11 +0200 Subject: [PATCH 5/7] Document OptionButton. --- docs/Reference/VB/OptionButton/index.md | 512 ++++++++++++++++++++++++ docs/Reference/VB/todo.md | 1 - 2 files changed, 512 insertions(+), 1 deletion(-) create mode 100644 docs/Reference/VB/OptionButton/index.md diff --git a/docs/Reference/VB/OptionButton/index.md b/docs/Reference/VB/OptionButton/index.md new file mode 100644 index 0000000..869ac20 --- /dev/null +++ b/docs/Reference/VB/OptionButton/index.md @@ -0,0 +1,512 @@ +--- +title: OptionButton +parent: VB Package +permalink: /tB/Packages/VB/OptionButton/ +has_toc: false +--- + +# OptionButton class +{: .no_toc } + +An **OptionButton** is a Win32 native control that displays a small round selector, optionally followed by a text caption, used to give the user a single choice within a group of related options. Option buttons that share a [**Container**](#container) form a *mutually exclusive group*: selecting one automatically clears every other option button in the same container. + +The control is normally placed on a [**Form**](../Form), [**Frame**](../Frame), or **UserControl** at design time. The default property is [**Value**](#value) and the default event is [**Click**](#click). + +```tb +Private Sub Form_Load() + optHTML.Caption = "&HTML" + optMarkdown.Caption = "&Markdown" + optPlain.Caption = "&Plain text" + optHTML.Value = True ' default selection +End Sub + +Private Sub optHTML_Click() + Debug.Print "Output format: HTML" +End Sub +``` + +* TOC +{:toc} + +## Mutual exclusion + +Setting [**Value**](#value) to **True** on one option button clears every other option button whose [**Container**](#container) is the same control — typically the parent form or a [**Frame**](../Frame). Option buttons in sibling frames are not affected, so a single form can host any number of independent groups: drop the buttons that belong to one group onto a frame, and the buttons that belong to a different group onto another frame (or directly onto the form). + +```tb +' Two independent groups on one form: +' fraSize: optSmall, optMedium, optLarge (children of fraSize) +' fraColour: optRed, optGreen, optBlue (children of fraColour) +``` + +Setting [**Value**](#value) to **False** never deselects another button — there is no automatic *fallback* to a different option, so applications normally guarantee that exactly one button in each group is selected by setting one of them to **True** at start-up. Assigning **False** to the currently selected button leaves the group with no selection until the user (or code) selects another one. + +## Click semantics + +[**Click**](#click) is raised only when [**Value**](#value) transitions from **False** to **True** — whether the user clicked the button, pressed its access key, or assigned **True** in code. Re-clicking an already selected option button does nothing, and assigning **False** to a selected button does *not* raise [**Click**](#click). The event also does not fire while the form is loading; it starts firing once the control's [**Initialize**](#initialize) event has run. + +## Caption and mnemonics + +The text shown next to (or, with [**Alignment**](#alignment) `tbRightJustify`, before) the selector comes from [**Caption**](#caption). An ampersand in the caption marks the next character as a keyboard mnemonic: pressing **Alt+** that character moves the focus to the option button and selects it. Use `&&` to display a literal ampersand. + +```tb +optTerms.Caption = "I &agree to the terms" +optTerms.Caption = "Use && in folder names" ' renders as: Use & in folder names +``` + +## Graphical style + +When [**Style**](#style) is **vbButtonGraphical**, the option button is owner-drawn and displays the bitmaps assigned to [**Picture**](#picture), [**DownPicture**](#downpicture), and [**DisabledPicture**](#disabledpicture) instead of the standard round selector. [**PictureAlignment**](#picturealignment), [**Padding**](#padding), and [**PictureDpiScaling**](#picturedpiscaling) control how the picture is positioned relative to the caption. + +## Properties + +### Alignment +{: .no_toc } + +Specifies the side of the selector on which the [**Caption**](#caption) text appears. + +Syntax: *object*.**Alignment** [ = *value* ] + +*value* +: A member of [**AlignmentConstantsNoCenter**](../../VBRUN/Constants/AlignmentConstantsNoCenter): **tbLeftJustify** (0, default — caption to the right of the selector) or **tbRightJustify** (1 — caption to the left of the selector). + +### Anchors +{: .no_toc } + +The set of edges of the parent that the option button's corresponding edges follow when the parent resizes. Read-only — assign individual `.Left`, `.Top`, `.Right`, `.Bottom` flags through the returned **Anchors** object. + +### Appearance +{: .no_toc } + +Determines how the control's border is drawn by the OS. A member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). + +### BackColor +{: .no_toc } + +The background colour, as an **OLE_COLOR**. Defaults to the system 3-D face colour. + +### Caption +{: .no_toc } + +The text displayed next to the option button. An ampersand marks the next character as a mnemonic; `&&` produces a literal ampersand. The string is read directly from the underlying window — assigning to **Caption** is reflected immediately. + +Syntax: *object*.**Caption** [ = *string* ] + +### CausesValidation +{: .no_toc } + +Determines whether the previously focused control's [**Validate**](#validate) event runs before this control receives the focus. **Boolean**, default **True**. + +### Container +{: .no_toc } + +The control that hosts this option button — typically a [**Frame**](../Frame) or the parent form. Read with **Get**, change with **Set**. Setting **Container** at run time re-parents the option button into a different group; it is automatically excluded from the old group's mutual-exclusion set and included in the new one. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as an option button. Always **vbOptionButton**. + +### DisabledPicture +{: .no_toc } + +A **StdPicture** drawn instead of [**Picture**](#picture) when the control is disabled and [**Style**](#style) is **vbButtonGraphical**. + +### Dock +{: .no_toc } + +Where the option button is docked within its container. A member of [**DockModeConstants**](../../VBRUN/Constants/DockModeConstants): **vbDockNone** (default), **vbDockLeft**, **vbDockTop**, **vbDockRight**, **vbDockBottom**, or **vbDockFill**. Docked controls ignore [**Anchors**](#anchors). + +### DownPicture +{: .no_toc } + +A **StdPicture** drawn instead of [**Picture**](#picture) while the control is in the depressed/selected state, when [**Style**](#style) is **vbButtonGraphical**. + +### DragIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor while the control is being drag-and-dropped (see [**Drag**](#drag) and [**DragMode**](#dragmode)). + +### DragMode +{: .no_toc } + +Whether the control should drag itself when the user holds the mouse over it. A member of [**DragModeConstants**](../../VBRUN/Constants/DragModeConstants): **vbManual** (0, default — call [**Drag**](#drag) from code) or **vbAutomatic** (1). + +### Enabled +{: .no_toc } + +Determines whether the control accepts user input. A disabled option button shows its current value but is dimmed and ignores keyboard and mouse interaction. **Boolean**, default **True**. + +### Font +{: .no_toc } + +The **StdFont** used to render [**Caption**](#caption). The convenience properties **FontName**, **FontSize**, **FontBold**, **FontItalic**, **FontStrikethru**, and **FontUnderline** read or write the corresponding members of this object. + +### ForeColor +{: .no_toc } + +The text colour for the caption, as an **OLE_COLOR**. Defaults to the system button-text colour. + +### Height +{: .no_toc } + +The control's height, in twips by default (or in the container's **ScaleMode** units). **Single**. + +### HelpContextID +{: .no_toc } + +A **Long** identifying a topic in the application's help file, retrieved when the user presses **F1** while the control has focus. + +### hWnd +{: .no_toc } + +The Win32 window handle for the underlying button, as a **LongPtr**. Read-only. Useful for passing to API functions. + +### Index +{: .no_toc } + +When the control is part of a control array, the **Long** zero-based index of this instance within the array. Reading **Index** on a non-array instance raises run-time error 343 (*Object not an array*). Read-only at run time. + +### Left +{: .no_toc } + +The horizontal distance from the left edge of the container to the left edge of the control. **Single**. + +### MaskColor +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### MouseIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor when [**MousePointer**](#mousepointer) is **vbCustom** and the pointer is over the control. + +### MousePointer +{: .no_toc } + +The mouse cursor shown when the pointer is over the control. A member of [**MousePointerConstants**](../../VBRUN/Constants/MousePointerConstants). + +### Name +{: .no_toc } + +The unique design-time name of the control on its parent form. Read-only at run time. + +### OLEDropMode +{: .no_toc } + +How the control responds to OLE drops. A restricted member of [**OLEDropConstants**](../../VBRUN/Constants/OLEDropConstants): **vbOLEDropNone** or **vbOLEDropManual**. Automatic-drop mode is not supported on an OptionButton. + +### Opacity +{: .no_toc } + +The control's opacity as a percentage (0–100, default 100). Values outside the range are clamped on **Initialize**. Requires Windows 8 or later for child controls. + +### Padding +{: .no_toc } + +The number of pixels of empty space inserted between the picture and the caption (when [**PictureAlignment**](#picturealignment) is **vbAlignLeft** or **vbAlignRight**) or between the caption and the corresponding edge (when **vbAlignTop** or **vbAlignBottom**). **Long**, default 2. Only meaningful when [**Style**](#style) is **vbButtonGraphical**. + +### Parent +{: .no_toc } + +A reference to the [**Form**](../Form) (or **UserControl**) that ultimately contains this control. Read-only. Distinct from [**Container**](#container), which returns the immediate parent — for an option button placed inside a [**Frame**](../Frame), **Container** returns the frame and **Parent** returns the form. + +### Picture +{: .no_toc } + +A **StdPicture** drawn on the control when [**Style**](#style) is **vbButtonGraphical**. Assigning **Nothing** restores an empty picture rather than removing the bitmap surface. + +### PictureAlignment +{: .no_toc } + +How [**Picture**](#picture) is positioned relative to the caption when [**Style**](#style) is **vbButtonGraphical**. A member of [**AlignConstants**](../../VBRUN/Constants/AlignConstants): **vbAlignNone**, **vbAlignTop** (default), **vbAlignBottom**, **vbAlignLeft**, **vbAlignRight**. + +### PictureDpiScaling +{: .no_toc } + +When **True**, scales [**Picture**](#picture), [**DownPicture**](#downpicture), and [**DisabledPicture**](#disabledpicture) by the current DPI factor before drawing. **Boolean**, default **False**. + +### RightToLeft +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. Use [**Alignment**](#alignment) to flip the caption to the left of the selector. + +### Style +{: .no_toc } + +Selects between the standard Win32 option-button appearance and an owner-drawn graphical button. A member of [**ButtonConstants**](../../VBRUN/Constants/ButtonConstants): **vbButtonStandard** (0, default) or **vbButtonGraphical** (1). Changing **Style** at run time recreates the underlying window. + +### TabIndex +{: .no_toc } + +The position of the control in the form's TAB-key navigation order. **Long**. + +### TabStop +{: .no_toc } + +Whether the user can reach the control by pressing the **TAB** key. **Boolean**, default **True**. The TAB-key navigation also follows the option-button group convention: once the focus enters a group, the arrow keys move it (and the selection) between the group's members rather than between unrelated controls. A disabled control is skipped regardless of this setting. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the control. Ignored by the framework. + +### ToolTipText +{: .no_toc } + +A multi-line **String** displayed as a tooltip when the user hovers over the control. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the control. **Single**. + +### TransparencyKey +{: .no_toc } + +An **OLE_COLOR** that, when set, becomes fully transparent in the rendered control. Default `-1` disables the effect. Requires Windows 8 or later for child controls. + +### UseMaskColor +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### Value +{: .no_toc } + +The current state of the option button. **Default property.** + +Syntax: *object*.**Value** [ = *value* ] + +*value* +: A **Boolean**: **True** if the option button is selected, **False** if cleared. + +Assigning **True** clears every other option button in the same [**Container**](#container) and raises [**Click**](#click). Assigning **False** clears just this button without affecting any other and does not raise [**Click**](#click). Assigning the value the button already holds does nothing. + +### Visible +{: .no_toc } + +Whether the control is shown. **Boolean**, default **True**. + +### VisualStyles +{: .no_toc } + +Whether the OS theme engine should be used when drawing the control. **Boolean**. + +### WhatsThisHelpID +{: .no_toc } + +A **Long** identifying a "What's This?" help-pop-up topic in the application's help file. See [**ShowWhatsThis**](#showwhatsthis). + +### Width +{: .no_toc } + +The control's width. **Single**. + +## Methods + +### Drag +{: .no_toc } + +Begins, completes, or cancels a manual drag-and-drop operation. Typically called from a [**MouseDown**](#mousedown) handler when [**DragMode**](#dragmode) is **vbManual**. + +Syntax: *object*.**Drag** [ *Action* ] + +*Action* +: *optional* A member of [**DragConstants**](../../VBRUN/Constants/DragConstants): **vbCancel** (0), **vbBeginDrag** (1, default), or **vbEndDrag** (2). + +### Move +{: .no_toc } + +Repositions and optionally resizes the control in a single call. + +Syntax: *object*.**Move** *Left* [, *Top* [, *Width* [, *Height* ] ] ] + +*Left* +: *required* A **Single** giving the new horizontal position. + +*Top*, *Width*, *Height* +: *optional* New values for the corresponding properties. Omitted values are left unchanged. + +### OLEDrag +{: .no_toc } + +Initiates an OLE drag operation from the control, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject**. + +Syntax: *object*.**OLEDrag** + +### Refresh +{: .no_toc } + +Forces an immediate repaint of the control. + +Syntax: *object*.**Refresh** + +### SetFocus +{: .no_toc } + +Moves the input focus to the control. The control must be both [**Visible**](#visible) and [**Enabled**](#enabled), or run-time error 5 (*Invalid procedure call or argument*) is raised. + +Syntax: *object*.**SetFocus** + +### ShowWhatsThis +{: .no_toc } + +Displays the topic identified by [**WhatsThisHelpID**](#whatsthishelpid) as a "What's This?" pop-up. + +Syntax: *object*.**ShowWhatsThis** + +### ZOrder +{: .no_toc } + +Brings the control to the front or back of its sibling stack. + +Syntax: *object*.**ZOrder** [ *Position* ] + +*Position* +: *optional* A member of [**ZOrderConstants**](../../VBRUN/Constants/ZOrderConstants): **vbBringToFront** (0, default) or **vbSendToBack** (1). + +## Events + +### Click +{: .no_toc } + +Raised when [**Value**](#value) transitions from **False** to **True** — whether the user clicked the selector, pressed the access key, or assigned **True** in code. Not raised on the form's first display, on a click that doesn't change the value, or when **Value** is set to **False**. **Default event.** + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks the option button. The first click of the pair also raises [**Click**](#click) if it changes [**Value**](#value); the second is delivered here. + +Syntax: *object*\_**DblClick**( ) + +### DragDrop +{: .no_toc } + +Raised on the destination control when a manual drag operation ends over it. + +Syntax: *object*\_**DragDrop**( *Source* **As Control**, *X* **As Single**, *Y* **As Single** ) + +### DragOver +{: .no_toc } + +Raised on the control under the cursor while a manual drag operation is in progress. + +Syntax: *object*\_**DragOver**( *Source* **As Control**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### GotFocus +{: .no_toc } + +Raised when the control receives the input focus. + +Syntax: *object*\_**GotFocus**( ) + +### Initialize +{: .no_toc } + +Raised once, after the control's underlying window has been created and its design-time [**Value**](#value) has been applied. [**Click**](#click) does not fire until **Initialize** has run, so the design-time selection does not raise a spurious event. + +Syntax: *object*\_**Initialize**( ) + +### KeyDown +{: .no_toc } + +Raised when the user presses any key while the control has focus. + +Syntax: *object*\_**KeyDown**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### KeyPress +{: .no_toc } + +Raised when the user types a character that produces an ANSI keystroke. + +Syntax: *object*\_**KeyPress**( *KeyAscii* **As Integer** ) + +### KeyUp +{: .no_toc } + +Raised when the user releases a key while the control has focus. + +Syntax: *object*\_**KeyUp**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### LostFocus +{: .no_toc } + +Raised when the control loses the input focus. + +Syntax: *object*\_**LostFocus**( ) + +### MouseDown +{: .no_toc } + +Raised when the user presses any mouse button over the control. + +Syntax: *object*\_**MouseDown**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseMove +{: .no_toc } + +Raised when the cursor moves over the control. + +Syntax: *object*\_**MouseMove**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseUp +{: .no_toc } + +Raised when the user releases a mouse button over the control. + +Syntax: *object*\_**MouseUp**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### OLECompleteDrag +{: .no_toc } + +Raised on the source control when the OLE drag operation finishes, indicating which effect (copy, move, none) the destination accepted. + +Syntax: *object*\_**OLECompleteDrag**( *Effect* **As Long** ) + +### OLEDragDrop +{: .no_toc } + +Raised on the destination control when the user drops data on it. + +Syntax: *object*\_**OLEDragDrop**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### OLEDragOver +{: .no_toc } + +Raised on the destination control while an OLE drag passes over it. + +Syntax: *object*\_**OLEDragOver**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### OLEGiveFeedback +{: .no_toc } + +Raised on the source control during a drag so the application can adjust the cursor or other visual feedback. + +Syntax: *object*\_**OLEGiveFeedback**( *Effect* **As Long**, *DefaultCursors* **As Boolean** ) + +### OLESetData +{: .no_toc } + +Raised on the source control when the destination requests data in a format that was registered but not yet supplied. + +Syntax: *object*\_**OLESetData**( *Data* **As DataObject**, *DataFormat* **As Integer** ) + +### OLEStartDrag +{: .no_toc } + +Raised on the source control at the start of an OLE drag, so the application can populate the **DataObject** and choose the allowed effects. + +Syntax: *object*\_**OLEStartDrag**( *Data* **As DataObject**, *AllowedEffects* **As Long** ) + +### Validate +{: .no_toc } + +Raised when the focus is moving to another control whose [**CausesValidation**](#causesvalidation) is **True**. Setting *Cancel* to **True** keeps the focus on this control. + +Syntax: *object*\_**Validate**( *Cancel* **As Boolean** ) diff --git a/docs/Reference/VB/todo.md b/docs/Reference/VB/todo.md index 9d27ee0..0c5782f 100644 --- a/docs/Reference/VB/todo.md +++ b/docs/Reference/VB/todo.md @@ -3,7 +3,6 @@ title: General TODO List for /tB/Packages/VB/ nav_exclude: true redirect_from: - /tB/Packages/VB/DriveListBox - - /tB/Packages/VB/OptionButton - /tB/Packages/VB/PictureBox - /tB/Packages/VB/Printer - /tB/Packages/VB/Report From ad606f33707f80b474fcc747a91ef709003e6c70 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Mon, 11 May 2026 13:31:22 +0200 Subject: [PATCH 6/7] Document the Print method of the Form class. --- docs/Reference/VB/Form/index.md | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/docs/Reference/VB/Form/index.md b/docs/Reference/VB/Form/index.md index 528a143..c8ed9df 100644 --- a/docs/Reference/VB/Form/index.md +++ b/docs/Reference/VB/Form/index.md @@ -71,7 +71,7 @@ dlgOptions.Show vbModal, Me ' modal, owned by the calling form A **Form** is itself a graphics surface — code can draw lines, shapes, and text directly on it. The coordinate system is governed by [**ScaleMode**](#scalemode) (default **vbTwips** — the classic VB6 behaviour) and the [**ScaleLeft**](#scaleleft) / [**ScaleTop**](#scaletop) / [**ScaleWidth**](#scalewidth) / [**ScaleHeight**](#scaleheight) properties, which together describe the form's logical drawing rectangle. Setting **ScaleMode** to **vbUser** lets the four **Scale\*** properties define an arbitrary rectangle; the [**Scale**](#scale) method does this in a single call. -The drawing primitives are [**Cls**](#cls), [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), [**PaintPicture**](#paintpicture), and the **Print** statement (`Form1.Print "Hello"`) — all use [**ForeColor**](#forecolor), [**FillColor**](#fillcolor), [**FillStyle**](#fillstyle), [**DrawWidth**](#drawwidth), [**DrawMode**](#drawmode), and [**DrawStyle**](#drawstyle) for their pen and fill, and the form's [**Font**](#font) for text. The current pen position is tracked by [**CurrentX**](#currentx) and [**CurrentY**](#currenty); [**TextWidth**](#textwidth) and [**TextHeight**](#textheight) measure a string in the current font. [**ScaleX**](#scalex) and [**ScaleY**](#scaley) convert single coordinates between scale modes. +The drawing primitives are [**Cls**](#cls), [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), [**PaintPicture**](#paintpicture), and the [**Print**](#print) statement (`Form1.Print "Hello"`) — all use [**ForeColor**](#forecolor), [**FillColor**](#fillcolor), [**FillStyle**](#fillstyle), [**DrawWidth**](#drawwidth), [**DrawMode**](#drawmode), and [**DrawStyle**](#drawstyle) for their pen and fill, and the form's [**Font**](#font) for text. The current pen position is tracked by [**CurrentX**](#currentx) and [**CurrentY**](#currenty); [**TextWidth**](#textwidth) and [**TextHeight**](#textheight) measure a string in the current font. [**ScaleX**](#scalex) and [**ScaleY**](#scaley) convert single coordinates between scale modes. [**AutoRedraw**](#autoredraw) controls whether drawn output persists across paints: when **False** (default), the [**Paint**](#paint) event must redraw on every invalidation; when **True**, the form keeps an off-screen buffer that survives invalidations and the **Paint** event is suppressed. Setting [**Picture**](#picture) puts a bitmap behind the drawing layer; [**Image**](#image) returns the rendered combined surface as a **StdPicture**. @@ -127,7 +127,7 @@ Determines how the control's border is drawn by the OS. A member of [**Appearanc Whether drawing performed on the form persists across invalidations. **Boolean**, default **False**. -When **False**, drawing primitives — [**Cls**](#cls), [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), [**PaintPicture**](#paintpicture), and **Print** — paint directly to the screen and the form must redraw them in its [**Paint**](#paint) event whenever the affected area is invalidated. When **True**, the form keeps an off-screen bitmap, drawing primitives paint into it (and immediately to the screen), the bitmap survives invalidations, and the **Paint** event is suppressed. Reading [**Image**](#image) returns this bitmap. +When **False**, drawing primitives — [**Cls**](#cls), [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), [**PaintPicture**](#paintpicture), and [**Print**](#print) — paint directly to the screen and the form must redraw them in its [**Paint**](#paint) event whenever the affected area is invalidated. When **True**, the form keeps an off-screen bitmap, drawing primitives paint into it (and immediately to the screen), the bitmap survives invalidations, and the **Paint** event is suppressed. Reading [**Image**](#image) returns this bitmap. ### BackColor {: .no_toc } @@ -183,7 +183,7 @@ A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstant ### CurrentX {: .no_toc } -The horizontal pen position, in [**ScaleMode**](#scalemode) units, used by drawing primitives that omit a starting coordinate (for example, **Print** and the rectangle form of [**Line**](#line)). **Double**. +The horizontal pen position, in [**ScaleMode**](#scalemode) units, used by drawing primitives that omit a starting coordinate (for example, [**Print**](#print) and the rectangle form of [**Line**](#line)). **Double**. ### CurrentY {: .no_toc } @@ -233,7 +233,7 @@ The fill pattern for closed shapes. A member of [**FillStyleConstants**](../../V ### Font {: .no_toc } -The **StdFont** used by the **Print** statement and other text drawing on this form. The convenience properties **FontName**, **FontSize**, **FontBold**, **FontItalic**, **FontStrikethru**, and **FontUnderline** read or write the corresponding members of this object. +The **StdFont** used by the [**Print**](#print) statement and other text drawing on this form. The convenience properties **FontName**, **FontSize**, **FontBold**, **FontItalic**, **FontStrikethru**, and **FontUnderline** read or write the corresponding members of this object. ### FontTransparent {: .no_toc } @@ -243,7 +243,7 @@ When **True** (default), text drawn on the form has a transparent background, le ### ForeColor {: .no_toc } -The pen colour used by [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), and the text drawn by **Print**. **OLE_COLOR**. +The pen colour used by [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), and the text drawn by [**Print**](#print). **OLE_COLOR**. ### hDC {: .no_toc } @@ -513,7 +513,7 @@ Syntax: *object*.**Circle** [ **Step** ] ( *X*, *Y* ), *Radius* [, [ *Color* ] [ ### Cls {: .no_toc } -Clears any drawing performed by [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), [**PaintPicture**](#paintpicture), and **Print**, repaints [**BackColor**](#backcolor), and resets [**CurrentX**](#currentx) / [**CurrentY**](#currenty) to `0`. Does not affect the [**Picture**](#picture) backdrop or child controls. +Clears any drawing performed by [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), [**PaintPicture**](#paintpicture), and [**Print**](#print), repaints [**BackColor**](#backcolor), and resets [**CurrentX**](#currentx) / [**CurrentY**](#currenty) to `0`. Does not affect the [**Picture**](#picture) backdrop or child controls. Syntax: *object*.**Cls** @@ -625,6 +625,22 @@ Syntax: *object*.**PopUpMenu** *Menu* [, *Flags* [, *X* [, *Y* [, *DefaultMenu* Syntax: *object*.**Point**( *X*, *Y* ) +### Print +{: .no_toc } + +Writes text to the form's drawing surface using [**Font**](#font), starting at [**CurrentX**](#currentx) / [**CurrentY**](#currenty) and advancing them as it goes. Dispatched through the VB6 **Print** statement so multiple expressions can be separated by `;` (no spacing) or `,` (tab to the next print zone). **Spc(n)** inserts *n* spaces and **Tab(n)** moves to print column *n*. Output honours [**Font**](#font), [**ForeColor**](#forecolor), and [**FontTransparent**](#fonttransparent), and — when [**AutoRedraw**](#autoredraw) is **True** — is recorded into the persistent off-screen bitmap so it survives invalidations. + +Syntax: *object*.**Print** \[ *expressionlist* ] \[ **;** \| **,** ] + +A trailing `;` or `,` suppresses the newline so the next **Print** call continues on the same line; without a trailing separator, the pen advances to the start of the next line. + +```tb +Me.CurrentX = 10 : Me.CurrentY = 10 +Me.Print "Name: "; sName, "Age: "; nAge ' two fields, tab-separated +Me.Print ' blank line +Me.Print "Total: " & Format$(Total, "0.00") +``` + ### PrintForm {: .no_toc } From 1f263cd3b6b8d7cf4fc7cdfdc200b633661f70f0 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Mon, 11 May 2026 13:31:42 +0200 Subject: [PATCH 7/7] Document PictureBox. --- docs/Reference/VB/PictureBox/index.md | 893 ++++++++++++++++++++++++++ docs/Reference/VB/todo.md | 1 - 2 files changed, 893 insertions(+), 1 deletion(-) create mode 100644 docs/Reference/VB/PictureBox/index.md diff --git a/docs/Reference/VB/PictureBox/index.md b/docs/Reference/VB/PictureBox/index.md new file mode 100644 index 0000000..2656b4b --- /dev/null +++ b/docs/Reference/VB/PictureBox/index.md @@ -0,0 +1,893 @@ +--- +title: PictureBox +parent: VB Package +permalink: /tB/Packages/VB/PictureBox/ +has_toc: false +--- + +# PictureBox class +{: .no_toc } + +A **PictureBox** is a Win32 native control that combines three roles in one: + +1. A **picture display** — it can show a bitmap, GIF, JPEG, icon, cursor, or metafile loaded into its [**Picture**](#picture) property. +2. A **drawing surface** — it exposes the VB6 graphics methods ([**Line**](#line), [**Circle**](#circle), [**PSet**](#pset), [**Print**](#print), [**PaintPicture**](#paintpicture), …) that write into the control's device context. +3. A **container** — it can host child controls dropped onto it at design time, much like a [**Frame**](../Frame), and can be docked or aligned within its parent. + +The control is normally placed on a [**Form**](../Form), [**Frame**](../Frame), or **UserControl** at design time. The default property is [**Picture**](#picture); the default-designer event is [**Click**](#click). + +```tb +Private Sub Form_Load() + Set picLogo.Picture = LoadPicture(App.Path & "\logo.png") + picLogo.AutoSize = True + + picCanvas.AutoRedraw = True + picCanvas.ScaleMode = vbPixels + picCanvas.Line (0, 0)-(picCanvas.ScaleWidth, picCanvas.ScaleHeight), vbRed, B + picCanvas.Print "Hello, world!" +End Sub +``` + +* TOC +{:toc} + +## Picture display + +Setting [**Picture**](#picture) assigns a **StdPicture** to the control. When [**AutoSize**](#autosize) is **True** the control resizes itself in its container's **ScaleMode** units to fit the picture exactly (plus a 1- or 2-pixel border, depending on [**Appearance**](#appearance)); otherwise the picture is drawn at its natural size, anchored at the top-left, and clipped to the control's bounds. Assigning **Nothing** to **Picture** clears the displayed image but does not erase anything drawn through the graphics methods. + +The picture is read directly from the file passed to **LoadPicture**, or — when [**DataField**](#datafield) / [**DataSource**](#datasource) are set — from the bound recordset field. Anything assigned to **\_Default** (the control's default property) is forwarded to **Picture**. + +## Drawing surface + +A **PictureBox** owns its own device context, addressable through [**hDC**](#hdc), and supports the full VB6 vector-drawing surface: [**Cls**](#cls), [**Line**](#line), [**Circle**](#circle), [**PSet**](#pset), [**Print**](#print), and [**PaintPicture**](#paintpicture). Pen and brush attributes come from [**ForeColor**](#forecolor), [**BackColor**](#backcolor), [**FillColor**](#fillcolor), [**FillStyle**](#fillstyle), [**DrawWidth**](#drawwidth), [**DrawMode**](#drawmode), and [**DrawStyle**](#drawstyle). [**CurrentX**](#currentx) and [**CurrentY**](#currenty) track the current "graphics pen" position so that subsequent calls can omit the starting coordinates. + +```tb +picCanvas.Line (10, 10)-Step(100, 50), vbBlue, BF ' filled rectangle +picCanvas.Circle (200, 100), 40, vbGreen ' circle +picCanvas.CurrentX = 10 : picCanvas.CurrentY = 100 +picCanvas.Print "Drawn over a Picture" ' text at the pen +``` + +[**Print**](#print) is dispatched through the IDispatch interface using the VB6 *Print* statement syntax (`pic.Print expr [, ;] expr …`), with **Spc(n)** and **Tab(n)** for whitespace and column control. Calls advance [**CurrentX**](#currentx) / [**CurrentY**](#currenty) and honour [**Font**](#font), [**ForeColor**](#forecolor), and [**FontTransparent**](#fonttransparent). + +## AutoRedraw and the persistent image + +When [**AutoRedraw**](#autoredraw) is **False** (default) the graphics methods write directly into the visible device context, and the OS may erase that drawing whenever the control is uncovered, resized, or redrawn — typically the application redraws it from a [**Paint**](#paint) handler. + +When [**AutoRedraw**](#autoredraw) is **True**, the graphics methods are recorded into an off-screen persistent bitmap that is automatically blitted onto the control whenever it needs repainting. The control no longer raises [**Paint**](#paint) events; the bitmap is exposed read-only through [**Image**](#image), suitable for saving with **SavePicture** or for assigning to another **PictureBox** or [**Image**](../Image) control. Toggling **AutoRedraw** from **False** to **True** preserves the current contents; toggling it back to **False** discards the persistent bitmap. + +## Coordinate system + +A **PictureBox** has its own coordinate system, independent of its parent. [**ScaleMode**](#scalemode) selects a built-in unit ([**ScaleModeConstants**](../../VBRUN/Constants/ScaleModeConstants) — **vbTwips**, **vbPoints**, **vbPixels**, **vbCharacters**, **vbInches**, **vbMillimeters**, **vbCentimeters**); assigning [**ScaleLeft**](#scaleleft), [**ScaleTop**](#scaletop), [**ScaleWidth**](#scalewidth), or [**ScaleHeight**](#scaleheight) (or calling [**Scale**](#scale) with two corner points) switches to **vbUser** and remaps the surface so the assigned values address the corners directly — useful for mathematical plots where the natural axes don't match pixel coordinates. + +[**ScaleX**](#scalex) and [**ScaleY**](#scaley) convert distances between any two scale modes without changing the active one. + +## Container behaviour + +Controls dropped onto a **PictureBox** at design time become its children: their coordinates are relative to its client area, and they move and hide with it. [**Container**](#container) returns the immediate parent (a form, frame, or another picture box); [**Parent**](#parent) returns the form that ultimately hosts it. [**ClipControls**](#clipcontrols) decides whether child controls are clipped out of paint regions before the [**Paint**](#paint) handler runs; turning it off can speed up graphics-heavy paint code that touches only areas the child controls don't cover. + +## Data binding + +Setting [**DataSource**](#datasource) and [**DataField**](#datafield) binds the control's [**Picture**](#picture) to a binary field of a [**Data**](../Data) control's recordset: the field is read on each row change and **LoadPicture** is called on it, and the round-trip byte representation of the current **Picture** is written back when the row is saved. [**DataChanged**](#datachanged) is set whenever the user modifies the displayed picture. + +## Properties + +### Align +{: .no_toc } + +> [!NOTE] +> Hidden. Provided for compatibility with VB6 forms that anchored a picture box to one edge of the form. Use [**Dock**](#dock) and [**Anchors**](#anchors) instead. + +### Anchors +{: .no_toc } + +The set of edges of the parent that the picture box's corresponding edges follow when the parent resizes. Read-only — assign individual `.Left`, `.Top`, `.Right`, `.Bottom` flags through the returned **Anchors** object. + +### Appearance +{: .no_toc } + +Determines how the border is drawn by the OS. A member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). Only meaningful when [**BorderStyle**](#borderstyle) is **vbFixedSingleBorder**. + +### AutoRedraw +{: .no_toc } + +Controls whether graphics output is recorded into a persistent bitmap. **Boolean**, default **False**. See [AutoRedraw and the persistent image](#autoredraw-and-the-persistent-image). + +### AutoSize +{: .no_toc } + +When **True**, the control resizes itself to fit the assigned [**Picture**](#picture). **Boolean**, default **False**. Has no effect when [**Picture**](#picture) is **Nothing**. + +### BackColor +{: .no_toc } + +The background colour of the control's drawing surface, as an **OLE_COLOR**. Defaults to the system 3-D face colour. Assigning a new value invalidates the surface and triggers a repaint. + +### BorderStyle +{: .no_toc } + +Whether the picture box is drawn with a border. A member of [**ControlBorderStyleConstants**](../../VBRUN/Constants/ControlBorderStyleConstants): **vbNoBorder** (0) or **vbFixedSingleBorder** (1, default). The exact appearance of the border depends on [**Appearance**](#appearance). + +### CausesValidation +{: .no_toc } + +Determines whether the previously focused control's [**Validate**](#validate) event runs before this control receives the focus. **Boolean**, default **True**. + +### ClipControls +{: .no_toc } + +When **True** (default), child controls are clipped out of the picture box's painting region before the [**Paint**](#paint) event fires, so drawing commands cannot overpaint them. Setting **False** allows the [**Paint**](#paint) handler to draw across the entire client area, which is faster when the application knows the contained controls do not overlap the drawn region. + +### Container +{: .no_toc } + +The control that hosts this picture box — typically the form, a [**Frame**](../Frame), or another picture box. Read with **Get**, change with **Set**. Setting **Container** at run time re-parents the picture box. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a picture box. Always **vbPictureBox**. + +### CurrentX +{: .no_toc } + +The horizontal coordinate, in [**ScaleMode**](#scalemode) units, at which the next graphics call will start unless it overrides it. **Single**. Updated automatically by [**Line**](#line), [**Circle**](#circle), [**PSet**](#pset), [**Print**](#print), and [**Cls**](#cls) (which resets it to 0). + +### CurrentY +{: .no_toc } + +The vertical coordinate, in [**ScaleMode**](#scalemode) units, at which the next graphics call will start. **Single**. See [**CurrentX**](#currentx). + +### DataChanged +{: .no_toc } + +A run-time-only **Boolean** that becomes **True** when the bound picture has been modified since the last save, and is cleared once the change has been written back to the recordset. + +### DataField +{: .no_toc } + +The name of the binary field, in the recordset of the bound [**DataSource**](#datasource), whose contents are loaded into [**Picture**](#picture). **String**. + +### DataFormat +{: .no_toc } + +A **StdDataFormat** that converts between the raw recordset value and the displayed picture, when the application needs custom handling. **Object**. Set with **Set**. + +### DataMember +{: .no_toc } + +When the [**DataSource**](#datasource) exposes more than one recordset, the name of the member to bind to. **String**. + +### DataSource +{: .no_toc } + +A reference to a [**Data**](../Data) control (or other **DataSource** provider) whose recordset supplies the value for [**DataField**](#datafield). Set with **Set**. + +### Dock +{: .no_toc } + +Where the picture box is docked within its container. A member of [**DockModeConstants**](../../VBRUN/Constants/DockModeConstants): **vbDockNone** (default), **vbDockLeft**, **vbDockTop**, **vbDockRight**, **vbDockBottom**, or **vbDockFill**. Docked picture boxes ignore [**Anchors**](#anchors). + +### DragIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor while the control is being drag-and-dropped (see [**Drag**](#drag) and [**DragMode**](#dragmode)). + +### DragMode +{: .no_toc } + +Whether the control should drag itself when the user holds the mouse over it. A member of [**DragModeConstants**](../../VBRUN/Constants/DragModeConstants): **vbManual** (0, default — call [**Drag**](#drag) from code) or **vbAutomatic** (1). + +### DrawMode +{: .no_toc } + +The raster operation used when drawing through the graphics methods. A member of [**DrawModeConstants**](../../VBRUN/Constants/DrawModeConstants), default **vbCopyPen** (13 — opaque overwrite). + +### DrawStyle +{: .no_toc } + +The pen style used for line-drawing methods. A member of [**DrawStyleConstants**](../../VBRUN/Constants/DrawStyleConstants): **vbSolid** (0, default), **vbDash**, **vbDot**, **vbDashDot**, **vbDashDotDot**, **vbInvisible**, or **vbInsideSolid**. Solid is forced when [**DrawWidth**](#drawwidth) is greater than 1. + +### DrawWidth +{: .no_toc } + +The thickness, in pixels, of the pen used by [**Line**](#line), [**Circle**](#circle), and [**PSet**](#pset). **Long**, default 1. Values greater than 1 force [**DrawStyle**](#drawstyle) to **vbSolid**. + +### Enabled +{: .no_toc } + +Determines whether the control accepts user input. **Boolean**, default **True**. Disabled picture boxes still draw and display their picture, but do not raise mouse, keyboard, or focus events. + +### FillColor +{: .no_toc } + +The colour used to fill closed shapes drawn by [**Line**](#line) (with the `F` flag) and [**Circle**](#circle), as an **OLE_COLOR**. Default **0** (black). Honoured only when [**FillStyle**](#fillstyle) is not **vbFSTransparent**. + +### FillStyle +{: .no_toc } + +The pattern used to fill closed shapes. A member of [**FillStyleConstants**](../../VBRUN/Constants/FillStyleConstants): **vbFSTransparent** (1, default), **vbFSSolid** (0), or one of the hatched styles. **Transparent** suppresses fill entirely, so only the outline is drawn. + +### Font +{: .no_toc } + +The **StdFont** used to render text drawn by [**Print**](#print) and measured by [**TextWidth**](#textwidth) / [**TextHeight**](#textheight). The convenience properties [**FontName**](#fontname), [**FontSize**](#fontsize), [**FontBold**](#fontbold), [**FontItalic**](#fontitalic), [**FontStrikethru**](#fontstrikethru), and [**FontUnderline**](#fontunderline) read or write the corresponding members of this object. + +### FontBold +{: .no_toc } + +Shortcut for [**Font**](#font)`.Bold`. **Boolean**. + +### FontItalic +{: .no_toc } + +Shortcut for [**Font**](#font)`.Italic`. **Boolean**. + +### FontName +{: .no_toc } + +Shortcut for [**Font**](#font)`.Name`. **String**. + +### FontSize +{: .no_toc } + +Shortcut for [**Font**](#font)`.Size` — the point size. **Single**. + +### FontStrikethru +{: .no_toc } + +Shortcut for [**Font**](#font)`.Strikethrough`. **Boolean**. + +### FontTransparent +{: .no_toc } + +When **True** (default), text drawn by [**Print**](#print) leaves the background pixels untouched between glyphs; when **False**, the glyphs' background is filled with [**BackColor**](#backcolor). **Boolean**. + +### FontUnderline +{: .no_toc } + +Shortcut for [**Font**](#font)`.Underline`. **Boolean**. + +### ForeColor +{: .no_toc } + +The colour used by the graphics-method pen (lines, circles, points) and by [**Print**](#print) text, as an **OLE_COLOR**. Defaults to the system button-text colour. + +### HasDC +{: .no_toc } + +When **True** (default), the control owns a persistent device context that survives between paints, making [**hDC**](#hdc) stable across calls. When **False**, the device context is fetched on demand and released after each operation; this is more memory-efficient but precludes drawing methods that rely on a stable [**hDC**](#hdc) value. + +### hDC +{: .no_toc } + +A **LongPtr** giving the Win32 device-context handle for the picture box's drawing surface. Read-only. Suitable for passing to GDI API calls. + +### Height +{: .no_toc } + +The control's height, in twips by default (or in the container's **ScaleMode** units). **Single**. + +### HelpContextID +{: .no_toc } + +A **Long** identifying a topic in the application's help file, retrieved when the user presses **F1** while the control has focus. + +### hWnd +{: .no_toc } + +The Win32 window handle for the picture box, as a **LongPtr**. Read-only. Useful for passing to API functions. + +### Image +{: .no_toc } + +A read-only **StdPicture** giving the current contents of the picture box — both the assigned [**Picture**](#picture) *and* anything drawn into the surface — as a single bitmap, suitable for saving with **SavePicture**, copying to the clipboard, or assigning to another picture display. Available only when [**AutoRedraw**](#autoredraw) is **True**, or when the persistent bitmap is otherwise present. + +### Index +{: .no_toc } + +When the control is part of a control array, the **Long** zero-based index of this instance within the array. Reading **Index** on a non-array instance raises run-time error 343 (*Object not an array*). Read-only at run time. + +### Left +{: .no_toc } + +The horizontal distance from the left edge of the container to the left edge of the control. **Single**. + +### LinkItem +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkMode +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +A member of [**LinkModeConstants**](../../VBRUN/Constants/LinkModeConstants). + +### LinkTimeout +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkTopic +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### MouseIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor when [**MousePointer**](#mousepointer) is **vbCustom** and the pointer is over the control. + +### MousePointer +{: .no_toc } + +The mouse cursor shown when the pointer is over the control. A member of [**MousePointerConstants**](../../VBRUN/Constants/MousePointerConstants). + +### Name +{: .no_toc } + +The unique design-time name of the control on its parent form. Read-only at run time. + +### Negotiate +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### OLEDragMode +{: .no_toc } + +How the picture box initiates OLE drag operations. A member of [**OLEDragConstants**](../../VBRUN/Constants/OLEDragConstants): **vbOLEDragManual** (0, default — call [**OLEDrag**](#oledrag) from code) or **vbOLEDragAutomatic** (1, which starts a drag with the current [**Picture**](#picture) as the payload as soon as the user begins a drag with the mouse). + +### Opacity +{: .no_toc } + +The control's opacity as a percentage (0–100, default 100). Values outside the range are clamped on **Initialize**. Requires Windows 8 or later for child controls. + +### Parent +{: .no_toc } + +A reference to the [**Form**](../Form) (or **UserControl**) that ultimately contains this control. Read-only. Distinct from [**Container**](#container), which returns the immediate parent. + +### Picture +{: .no_toc } + +The picture displayed in the control's client area. **StdPicture**. **Default property.** Use **Set** to assign a new picture, **Nothing** to clear it. Assigning when [**AutoSize**](#autosize) is **True** resizes the control to fit. + +### PictureDpiScaling +{: .no_toc } + +When **True**, [**Picture**](#picture) and the graphics-method outputs are scaled by the current DPI factor before drawing, so a 96-dpi-authored picture is presented at its physical size on high-DPI monitors. **Boolean**, default **False**. + +### RightToLeft +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### ScaleHeight +{: .no_toc } + +The height of the drawing surface in [**ScaleMode**](#scalemode) units. **Double**. Read-write — assigning a value switches [**ScaleMode**](#scalemode) to **vbUser** and rescales the vertical axis so the control's client area spans the new value. + +### ScaleLeft +{: .no_toc } + +The X coordinate that maps to the left edge of the drawing surface. **Double**, default 0. Assigning switches [**ScaleMode**](#scalemode) to **vbUser**. + +### ScaleMode +{: .no_toc } + +The unit used by [**Left**](#left), [**Top**](#top), [**Width**](#width), [**Height**](#height), [**CurrentX**](#currentx), [**CurrentY**](#currenty), and every graphics method. A member of [**ScaleModeConstants**](../../VBRUN/Constants/ScaleModeConstants): **vbUser** (0), **vbTwips** (1, default), **vbPoints**, **vbPixels**, **vbCharacters**, **vbInches**, **vbMillimeters**, or **vbCentimeters**. + +### ScaleTop +{: .no_toc } + +The Y coordinate that maps to the top edge of the drawing surface. **Double**, default 0. Assigning switches [**ScaleMode**](#scalemode) to **vbUser**. + +### ScaleWidth +{: .no_toc } + +The width of the drawing surface in [**ScaleMode**](#scalemode) units. **Double**. Read-write — assigning a value switches [**ScaleMode**](#scalemode) to **vbUser**. + +### TabIndex +{: .no_toc } + +The position of the control in the form's TAB-key navigation order. **Long**. + +### TabStop +{: .no_toc } + +Whether the user can reach the control by pressing the **TAB** key. **Boolean**, default **True**. A disabled control is skipped regardless of this setting. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the control. Ignored by the framework. + +### ToolTipText +{: .no_toc } + +A multi-line **String** displayed as a tooltip when the user hovers over the control. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the control. **Single**. + +### TransparencyKey +{: .no_toc } + +An **OLE_COLOR** that, when set, becomes fully transparent in the rendered control. Default `-1` disables the effect. Requires Windows 8 or later for child controls. + +### Visible +{: .no_toc } + +Whether the control is shown. **Boolean**, default **True**. + +### WhatsThisHelpID +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +A **Long** identifying a "What's This?" help-pop-up topic. See [**ShowWhatsThis**](#showwhatsthis). + +### Width +{: .no_toc } + +The control's width. **Single**. + +## Methods + +### Circle +{: .no_toc } + +Draws a circle, ellipse, or elliptical arc on the drawing surface. + +Syntax: *object*.**Circle** [ **Step** ] ( *X*, *Y* ), *Radius* [, *Color* [, *Start* [, *End* [, *Aspect* ] ] ] ] + +*X*, *Y* +: *required* Coordinates of the centre in [**ScaleMode**](#scalemode) units. **Single**. When prefixed with **Step**, they are interpreted relative to [**CurrentX**](#currentx) / [**CurrentY**](#currenty). + +*Radius* +: *required* The radius along the X axis. **Single**. + +*Color* +: *optional* An **OLE_COLOR** for the outline. Defaults to [**ForeColor**](#forecolor). + +*Start*, *End* +: *optional* Start and end angles in radians (0 to 2π). Negative values are interpreted as full radians and connect the arc end-point to the centre with a chord. Omitted draws a full circle. + +*Aspect* +: *optional* The Y/X aspect ratio. **1.0** for a circle (default); other values give an ellipse. + +[**CurrentX**](#currentx) and [**CurrentY**](#currenty) are left at the centre. + +### Cls +{: .no_toc } + +Clears the drawing surface to [**BackColor**](#backcolor), discards everything drawn through the graphics methods (and the persistent bitmap if [**AutoRedraw**](#autoredraw) is **True**), and resets [**CurrentX**](#currentx) / [**CurrentY**](#currenty) to **0**. The assigned [**Picture**](#picture) is not affected. + +Syntax: *object*.**Cls** + +### Drag +{: .no_toc } + +Begins, completes, or cancels a manual drag-and-drop operation. Typically called from a [**MouseDown**](#mousedown) handler when [**DragMode**](#dragmode) is **vbManual**. + +Syntax: *object*.**Drag** [ *Action* ] + +*Action* +: *optional* A member of [**DragConstants**](../../VBRUN/Constants/DragConstants): **vbCancel** (0), **vbBeginDrag** (1, default), or **vbEndDrag** (2). + +### Line +{: .no_toc } + +Draws a straight line, a rectangle outline, or a filled rectangle. + +Syntax: *object*.**Line** [ [ **Step** ] ( *X1*, *Y1* ) ] **-** [ **Step** ] ( *X2*, *Y2* ) [, *Color* [, **B** [**F**] ] ] + +*X1*, *Y1* +: *optional* Start coordinates. **Single**. If omitted, the line starts at [**CurrentX**](#currentx) / [**CurrentY**](#currenty). **Step** makes them relative to the current pen position. + +*X2*, *Y2* +: *required* End coordinates. **Single**. **Step** makes them relative to the start point. + +*Color* +: *optional* An **OLE_COLOR** for the line. Defaults to [**ForeColor**](#forecolor). + +*B* +: *optional* When present, draws a rectangle whose opposite corners are *(X1, Y1)* and *(X2, Y2)* instead of a line. + +*F* +: *optional* Only valid with **B**. Fills the rectangle with [**FillColor**](#fillcolor) at the current [**FillStyle**](#fillstyle). + +[**CurrentX**](#currentx) / [**CurrentY**](#currenty) are left at *(X2, Y2)*. + +### Move +{: .no_toc } + +Repositions and optionally resizes the control in a single call. + +Syntax: *object*.**Move** *Left* [, *Top* [, *Width* [, *Height* ] ] ] + +*Left* +: *required* A **Single** giving the new horizontal position. + +*Top*, *Width*, *Height* +: *optional* New values for the corresponding properties. Omitted values are left unchanged. + +### OLEDrag +{: .no_toc } + +Initiates an OLE drag operation from the control, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject**. + +Syntax: *object*.**OLEDrag** + +### PaintPicture +{: .no_toc } + +Draws a picture onto the surface, optionally scaling, clipping, or applying a raster operation. + +Syntax: *object*.**PaintPicture** *Picture*, *X1*, *Y1* [, *Width1* [, *Height1* [, *X2* [, *Y2* [, *Width2* [, *Height2* [, *Opcode* [, *StretchQuality* ] ] ] ] ] ] ] ] + +*Picture* +: *required* An **IPictureDisp** to paint — typically the [**Picture**](#picture) or [**Image**](#image) of another picture display. + +*X1*, *Y1* +: *required* Destination top-left in [**ScaleMode**](#scalemode) units. + +*Width1*, *Height1* +: *optional* Destination size. Defaults to the picture's natural size. + +*X2*, *Y2*, *Width2*, *Height2* +: *optional* Source rectangle within *Picture*. Defaults to the whole picture. + +*Opcode* +: *optional* A raster-operation code passed through to **BitBlt** — for example **&HCC0020** (`vbSrcCopy`, default) or **&H660046** (`vbSrcInvert`). + +*StretchQuality* +: *optional* `vbStretchQuality` value: **vbQualityNormal** (default) or **vbQualityHigh** (uses half-tone stretching for nicer downscales). + +### Point +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +In VB6, returns the colour of the pixel at the given coordinates as a **Long**, or **-1** if the point is outside the drawing surface. + +Syntax: *object*.**Point**( *X* **As Single**, *Y* **As Single** ) **As Long** + +### Print +{: .no_toc } + +Writes text to the drawing surface using [**Font**](#font), starting at [**CurrentX**](#currentx) / [**CurrentY**](#currenty) and advancing them as it goes. Dispatched through the **Print** statement so multiple expressions can be separated by `;` (no spacing) or `,` (tab to next print zone). **Spc(n)** inserts *n* spaces and **Tab(n)** moves to print column *n*. + +Syntax: *object*.**Print** \[ *expressionlist* ] \[ **;** \| **,** ] + +A trailing `;` or `,` suppresses the newline so the next [**Print**](#print) call continues on the same line. + +### PSet +{: .no_toc } + +Sets a single pixel. + +Syntax: *object*.**PSet** [ **Step** ] ( *X*, *Y* ) [, *Color* ] + +*X*, *Y* +: *required* Coordinates in [**ScaleMode**](#scalemode) units. **Step** makes them relative to [**CurrentX**](#currentx) / [**CurrentY**](#currenty). + +*Color* +: *optional* An **OLE_COLOR**. Defaults to [**ForeColor**](#forecolor). + +[**CurrentX**](#currentx) / [**CurrentY**](#currenty) are left at the set point. + +### Refresh +{: .no_toc } + +Forces an immediate repaint. When [**AutoRedraw**](#autoredraw) is **True**, copies the persistent bitmap to the visible surface; otherwise invalidates the control and triggers a [**Paint**](#paint) event. + +Syntax: *object*.**Refresh** + +### Scale +{: .no_toc } + +Defines a user coordinate system for the surface. Calling **Scale** with no arguments resets [**ScaleMode**](#scalemode) to **vbTwips**. + +Syntax: *object*.**Scale** [ ( *X1*, *Y1* ) **-** ( *X2*, *Y2* ) ] + +*X1*, *Y1* +: *required* (with the second pair) The coordinate that maps to the top-left corner — sets [**ScaleLeft**](#scaleleft) and [**ScaleTop**](#scaletop). + +*X2*, *Y2* +: *required* The coordinate that maps to the bottom-right corner — sets [**ScaleWidth**](#scalewidth) = `X2 - X1` and [**ScaleHeight**](#scaleheight) = `Y2 - Y1`. [**ScaleMode**](#scalemode) is switched to **vbUser**. + +### ScaleX +{: .no_toc } + +Converts a horizontal distance from one scale mode to another without changing [**ScaleMode**](#scalemode). + +Syntax: *object*.**ScaleX**( *Width* [, *FromScale* [, *ToScale* ] ] ) **As Single** + +*Width* +: *required* The value to convert. **Single**. + +*FromScale*, *ToScale* +: *optional* [**ScaleModeConstants**](../../VBRUN/Constants/ScaleModeConstants) members. *FromScale* defaults to the control's current [**ScaleMode**](#scalemode); *ToScale* defaults to **vbTwips**. + +### ScaleY +{: .no_toc } + +The vertical counterpart of [**ScaleX**](#scalex), for converting heights. + +Syntax: *object*.**ScaleY**( *Height* [, *FromScale* [, *ToScale* ] ] ) **As Single** + +### SetFocus +{: .no_toc } + +Moves the input focus to the control. The control must be both [**Visible**](#visible) and [**Enabled**](#enabled), or run-time error 5 (*Invalid procedure call or argument*) is raised. + +Syntax: *object*.**SetFocus** + +### ShowWhatsThis +{: .no_toc } + +Displays the topic identified by [**WhatsThisHelpID**](#whatsthishelpid) as a "What's This?" pop-up. + +Syntax: *object*.**ShowWhatsThis** + +### TextHeight +{: .no_toc } + +Measures the height, in [**ScaleMode**](#scalemode) units, of the given string when rendered in the current [**Font**](#font) — including the line-spacing leading, so the result is suitable for advancing [**CurrentY**](#currenty) between rows of text. Embedded line breaks are honoured. + +Syntax: *object*.**TextHeight**( *Str* **As String** ) **As Single** + +### TextWidth +{: .no_toc } + +Measures the width, in [**ScaleMode**](#scalemode) units, of the given string when rendered in the current [**Font**](#font). Returns the longest line width when *Str* contains embedded line breaks. + +Syntax: *object*.**TextWidth**( *Str* **As String** ) **As Single** + +### ZOrder +{: .no_toc } + +Brings the control to the front or back of its sibling stack. + +Syntax: *object*.**ZOrder** [ *Position* ] + +*Position* +: *optional* A member of [**ZOrderConstants**](../../VBRUN/Constants/ZOrderConstants): **vbBringToFront** (0, default) or **vbSendToBack** (1). + +### LinkExecute +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkPoke +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkRequest +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkSend +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +## Events + +### Change +{: .no_toc } + +Raised when [**Picture**](#picture) is assigned a new value — either from code or from the bound recordset. + +Syntax: *object*\_**Change**( ) + +### Click +{: .no_toc } + +Raised when the user clicks the control with any mouse button. **Default-designer event.** + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks the control. + +Syntax: *object*\_**DblClick**( ) + +### DragDrop +{: .no_toc } + +Raised on the destination control when a manual drag operation ends over it. + +Syntax: *object*\_**DragDrop**( *Source* **As Control**, *X* **As Single**, *Y* **As Single** ) + +### DragOver +{: .no_toc } + +Raised on the control under the cursor while a manual drag operation is in progress. + +Syntax: *object*\_**DragOver**( *Source* **As Control**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### GotFocus +{: .no_toc } + +Raised when the control receives the input focus. + +Syntax: *object*\_**GotFocus**( ) + +### Initialize +{: .no_toc } + +Raised once, after the underlying window has been created and [**Picture**](#picture) has been loaded from the serialized data. + +Syntax: *object*\_**Initialize**( ) + +### KeyDown +{: .no_toc } + +Raised when the user presses any key while the control has focus. + +Syntax: *object*\_**KeyDown**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### KeyPress +{: .no_toc } + +Raised when the user types a character that produces an ANSI keystroke. + +Syntax: *object*\_**KeyPress**( *KeyAscii* **As Integer** ) + +### KeyUp +{: .no_toc } + +Raised when the user releases a key while the control has focus. + +Syntax: *object*\_**KeyUp**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### LinkClose +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkError +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkNotify +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkOpen +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LostFocus +{: .no_toc } + +Raised when the control loses the input focus. + +Syntax: *object*\_**LostFocus**( ) + +### MouseDown +{: .no_toc } + +Raised when the user presses any mouse button over the control. + +Syntax: *object*\_**MouseDown**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseMove +{: .no_toc } + +Raised when the cursor moves over the control. + +Syntax: *object*\_**MouseMove**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseUp +{: .no_toc } + +Raised when the user releases a mouse button over the control. + +Syntax: *object*\_**MouseUp**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseWheel +{: .no_toc } + +Raised when the user rotates the mouse wheel while the control has focus or the cursor is over it. New in twinBASIC — there is no equivalent VB6 event. + +Syntax: *object*\_**MouseWheel**( *Delta* **As Integer**, *Horizontal* **As Boolean** ) + +*Delta* +: A positive or negative scroll delta in units of `WHEEL_DELTA` (120). + +*Horizontal* +: **True** for a horizontal-wheel rotation, **False** for the standard vertical wheel. + +### OLECompleteDrag +{: .no_toc } + +Raised on the source control when the OLE drag operation finishes, indicating which effect (copy, move, none) the destination accepted. + +Syntax: *object*\_**OLECompleteDrag**( *Effect* **As Long** ) + +### OLEDragDrop +{: .no_toc } + +Raised on the destination control when the user drops data on it. + +Syntax: *object*\_**OLEDragDrop**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### OLEDragOver +{: .no_toc } + +Raised on the destination control while an OLE drag passes over it. + +Syntax: *object*\_**OLEDragOver**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### OLEGiveFeedback +{: .no_toc } + +Raised on the source control during a drag so the application can adjust the cursor or other visual feedback. + +Syntax: *object*\_**OLEGiveFeedback**( *Effect* **As Long**, *DefaultCursors* **As Boolean** ) + +### OLESetData +{: .no_toc } + +Raised on the source control when the destination requests data in a format that was registered but not yet supplied. + +Syntax: *object*\_**OLESetData**( *Data* **As DataObject**, *DataFormat* **As Integer** ) + +### OLEStartDrag +{: .no_toc } + +Raised on the source control at the start of an OLE drag, so the application can populate the **DataObject** and choose the allowed effects. Also raised automatically when [**OLEDragMode**](#oledragmode) is **vbOLEDragAutomatic** and the user begins a drag. + +Syntax: *object*\_**OLEStartDrag**( *Data* **As DataObject**, *AllowedEffects* **As Long** ) + +### Paint +{: .no_toc } + +Raised when the control needs to redraw its client area — typically because it was uncovered, resized, or [**Refresh**](#refresh) was called. Not raised while [**AutoRedraw**](#autoredraw) is **True**; the persistent bitmap is blitted instead. + +Syntax: *object*\_**Paint**( ) + +### Resize +{: .no_toc } + +Raised after the control's [**Height**](#height) or [**Width**](#width) changes. Useful for re-flowing child controls or rescaling drawn content. + +Syntax: *object*\_**Resize**( ) + +### Validate +{: .no_toc } + +Raised when the focus is moving to another control whose [**CausesValidation**](#causesvalidation) is **True**. Setting *Cancel* to **True** keeps the focus on this control. + +Syntax: *object*\_**Validate**( *Cancel* **As Boolean** ) diff --git a/docs/Reference/VB/todo.md b/docs/Reference/VB/todo.md index 0c5782f..f29dec5 100644 --- a/docs/Reference/VB/todo.md +++ b/docs/Reference/VB/todo.md @@ -3,7 +3,6 @@ title: General TODO List for /tB/Packages/VB/ nav_exclude: true redirect_from: - /tB/Packages/VB/DriveListBox - - /tB/Packages/VB/PictureBox - /tB/Packages/VB/Printer - /tB/Packages/VB/Report - /tB/Packages/VB/Shape