diff --git a/.gitignore b/.gitignore index 2f7f63e..118e8e0 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ .claude/ CLAUDE.md +/.htmltest.yml diff --git a/docs/Reference/VB/CheckBox/index.md b/docs/Reference/VB/CheckBox/index.md index fbe4cf1..17f2aaf 100644 --- a/docs/Reference/VB/CheckBox/index.md +++ b/docs/Reference/VB/CheckBox/index.md @@ -1,7 +1,7 @@ --- title: CheckBox parent: VB Package -permalink: /tB/Packages/VB/CheckBox +permalink: /tB/Packages/VB/CheckBox/ has_toc: false --- @@ -28,7 +28,7 @@ End Sub ## Three-state behaviour -[**Value**](#value) is typed as [**CheckBoxConstants**](../VBRUN/Constants/CheckBoxConstants): +[**Value**](#value) is typed as [**CheckBoxConstants**](../../VBRUN/Constants/CheckBoxConstants): | Constant | Value | Meaning | |------------------|-------|--------------------------------------------------------| @@ -68,12 +68,12 @@ Specifies the side of the box 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 box) or **tbRightJustify** (1 — caption to the left of the box). +: A member of [**AlignmentConstantsNoCenter**](../../VBRUN/Constants/AlignmentConstantsNoCenter): **tbLeftJustify** (0, default — caption to the right of the box) or **tbRightJustify** (1 — caption to the left of the box). ### 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). +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 } @@ -95,7 +95,7 @@ Determines whether the previously focused control's [**Validate**](#validate) ev ### ControlType {: .no_toc } -A read-only [**ControlTypeConstants**](../VBRUN/Constants/ControlTypeConstants) value identifying this control as a check box. Always **vbCheckBox**. +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a check box. Always **vbCheckBox**. ### DataField {: .no_toc } @@ -125,7 +125,7 @@ A **StdPicture** used as the mouse cursor while the control is being drag-and-dr ### 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). +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 } @@ -181,7 +181,7 @@ A **StdPicture** used as the mouse cursor when [**MousePointer**](#mousepointer) ### MousePointer {: .no_toc } -The mouse cursor shown when the pointer is over the control. A member of [**MousePointerConstants**](../VBRUN/Constants/MousePointerConstants). +The mouse cursor shown when the pointer is over the control. A member of [**MousePointerConstants**](../../VBRUN/Constants/MousePointerConstants). ### Name {: .no_toc } @@ -191,7 +191,7 @@ The unique design-time name of the control on its parent form. Read-only at run ### 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 a CheckBox. +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 a CheckBox. ### Opacity {: .no_toc } @@ -206,7 +206,7 @@ The number of pixels of empty space inserted between the picture and the caption ### Parent {: .no_toc } -A reference to the [**Form**](Form) (or **UserControl**) that contains this control. Read-only. +A reference to the [**Form**](../Form) (or **UserControl**) that contains this control. Read-only. ### Picture {: .no_toc } @@ -216,7 +216,7 @@ A **StdPicture** drawn on the control when [**Style**](#style) is **vbButtonGrap ### 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**. +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 } @@ -232,7 +232,7 @@ When **True**, scales [**Picture**](#picture), [**DownPicture**](#downpicture), ### Style {: .no_toc } -Selects between the standard Win32 check-box 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. +Selects between the standard Win32 check-box 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 } @@ -278,7 +278,7 @@ The current state of the check box. **Default property.** Syntax: *object*.**Value** [ = *value* ] *value* -: A member of [**CheckBoxConstants**](../VBRUN/Constants/CheckBoxConstants): **vbUnchecked** (0), **vbChecked** (1), or **vbGrayed** (2). Negative numbers raise run-time error 380. +: A member of [**CheckBoxConstants**](../../VBRUN/Constants/CheckBoxConstants): **vbUnchecked** (0), **vbChecked** (1), or **vbGrayed** (2). Negative numbers raise run-time error 380. Assigning a value that differs from the current one raises a [**Click**](#click) event. @@ -312,7 +312,7 @@ Begins, completes, or cancels a manual drag-and-drop operation. Typically called Syntax: *object*.**Drag** [ *Action* ] *Action* -: *optional* A member of [**DragConstants**](../VBRUN/Constants/DragConstants): **vbCancel** (0), **vbBeginDrag** (1, default), or **vbEndDrag** (2). +: *optional* A member of [**DragConstants**](../../VBRUN/Constants/DragConstants): **vbCancel** (0), **vbBeginDrag** (1, default), or **vbEndDrag** (2). ### Move {: .no_toc } @@ -363,7 +363,7 @@ 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). +: *optional* A member of [**ZOrderConstants**](../../VBRUN/Constants/ZOrderConstants): **vbBringToFront** (0, default) or **vbSendToBack** (1). ## Events diff --git a/docs/Reference/VB/Form/index.md b/docs/Reference/VB/Form/index.md index 688cb37..528a143 100644 --- a/docs/Reference/VB/Form/index.md +++ b/docs/Reference/VB/Form/index.md @@ -3,8 +3,6 @@ title: Form parent: VB Package permalink: /tB/Packages/VB/Form/ has_toc: false -redirect_from: - - /tB/Packages/VB/Form --- # Form class diff --git a/docs/Reference/VB/Frame/index.md b/docs/Reference/VB/Frame/index.md new file mode 100644 index 0000000..4955047 --- /dev/null +++ b/docs/Reference/VB/Frame/index.md @@ -0,0 +1,460 @@ +--- +title: Frame +parent: VB Package +permalink: /tB/Packages/VB/Frame/ +has_toc: false +--- + +# Frame class +{: .no_toc } + +A **Frame** is a Win32 native container control that groups a set of related controls inside a captioned border. It serves two distinct purposes — a visual cue that the enclosed controls belong together, and a logical grouping for [**OptionButton**](../OptionButton) controls: option buttons inside the same frame are mutually exclusive of one another but independent of option buttons elsewhere on the form. Controls dropped onto a frame at design time become its children, and moving, hiding, disabling, or destroying the frame moves, hides, disables, or destroys the entire group with it. + +A frame cannot itself receive the input focus. The mnemonic marker (`&`) in its [**Caption**](#caption) is honoured, but pressing **Alt+** that character moves the focus to the next control in tab order rather than to the frame itself — exactly like a [**Label**](../Label). + +The default property is [**Caption**](#caption) and the default event is [**Click**](#click). + +```tb +Private Sub Form_Load() + fraOutput.Caption = "&Output format" + optHTML.Caption = "&HTML" + optMarkdown.Caption = "&Markdown" + optPlain.Caption = "&Plain text" + optHTML.Value = True ' default selection within fraOutput +End Sub + +Private Sub fraOutput_Click() + Debug.Print "Frame clicked (between the option buttons)" +End Sub +``` + +* TOC +{:toc} + +## Container behaviour + +A frame is a true container: each control inside it has the frame's `hWnd` as its Win32 parent and its coordinates are relative to the frame's client area, not the form. As a result: + +- Toggling [**Visible**](#visible) or [**Enabled**](#enabled) affects every contained control. +- Calling [**Move**](#move) re-positions the frame and the children move with it without each child raising its own resize. +- The frame's [**Anchors**](#anchors) and [**Dock**](#dock) settings let it stretch with its parent so the whole group resizes together. +- A control's [**Container**](#container) property returns the frame it lives in (and the frame's own [**Container**](#container) returns the form, or another frame, that hosts it). + +## Caption, mnemonics, and the border + +The text in [**Caption**](#caption) is rendered along the top edge of the border by the standard Win32 group-box style. An ampersand in the caption marks the next character as a keyboard mnemonic; use `&&` to display a literal ampersand. Pressing **Alt+** the marked character moves the focus to the next control in tab order — the frame does not take focus itself. + +[**BorderStyle**](#borderstyle) chooses between the standard captioned single-line border (**vbFixedSingleBorder**, the default) and a borderless mode (**vbNoBorder**). In **vbNoBorder** mode the standard group-box rendering is bypassed entirely — neither the line nor the caption text is drawn — and the frame becomes a plain rectangular region. [**Appearance**](#appearance) further selects between the 3-D and flat variant of the standard border. + +## OptionButton groups + +Each frame defines its own option-button group. When the user selects an [**OptionButton**](../OptionButton) whose parent is this frame, every other option button on the same frame is automatically cleared, but option buttons on the form (or in sibling frames) are not affected. Use frames to present multiple independent radio-style choices on the same form: + +```tb +' Two independent option-button groups on one form: +' fraSize: optSmall, optMedium, optLarge +' fraColour: optRed, optGreen, optBlue +``` + +## Transparency and opacity + +[**Opacity**](#opacity) and [**TransparencyKey**](#transparencykey) drive Windows' layered-window features. Setting [**Opacity**](#opacity) below 100 makes the frame and its contained controls translucent; setting [**TransparencyKey**](#transparencykey) to a colour makes pixels of that colour fully transparent on screen. Both features require Windows 8 or later when the frame contains child controls — otherwise only the frame's own background is affected. + +## Properties + +### Anchors +{: .no_toc } + +The set of edges of the parent that the frame'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 frame's border is drawn by the OS. A member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). + +### BackColor +{: .no_toc } + +The background colour of the frame's client area, as an **OLE_COLOR**. Defaults to the system 3-D face colour. Painted behind contained controls. + +### BorderStyle +{: .no_toc } + +The style of the frame's border. A member of [**ControlBorderStyleConstants**](../../VBRUN/Constants/ControlBorderStyleConstants): **vbFixedSingleBorder** (1, default — the captioned group-box line) or **vbNoBorder** (0). With **vbNoBorder** the caption is also suppressed and the frame becomes a borderless background panel. + +### Caption +{: .no_toc } + +The text rendered along the top edge of the frame's border. **String**. **Default property.** + +Syntax: *object*.**Caption** [ = *string* ] + +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** updates the rendering immediately. + +### ClipControls +{: .no_toc } + +Whether child controls are clipped out of the frame's drawing region during paint. **Boolean**, default **True**. Changing **ClipControls** at run time recreates the underlying window. + +### Container +{: .no_toc } + +The control that hosts this frame — typically the form, or another frame. Read with **Get**, change with **Set**. Setting **Container** re-parents the frame to a different container at run time. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a frame. Always **vbFrame**. + +### Dock +{: .no_toc } + +Where the frame is docked within its container. A member of [**DockModeConstants**](../../VBRUN/Constants/DockModeConstants): **vbDockNone** (default), **vbDockLeft**, **vbDockTop**, **vbDockRight**, **vbDockBottom**, or **vbDockFill**. Docked frames ignore [**Anchors**](#anchors). + +### DragIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor while the frame is being drag-and-dropped (see [**Drag**](#drag) and [**DragMode**](#dragmode)). + +### DragMode +{: .no_toc } + +Whether the frame 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 frame and its contained controls accept user input. A disabled frame dims its contents and ignores mouse and keyboard interaction. **Boolean**, default **True**. Changing **Enabled** triggers an immediate repaint so the border reflects the new state. + +### Font +{: .no_toc } + +The **StdFont** used to render [**Caption**](#caption). The convenience properties **FontBold**, **FontItalic**, **FontName**, **FontSize**, **FontStrikethru**, and **FontUnderline** read or write the corresponding members of this object. + +### FontBold +{: .no_toc } + +Shortcut for `Font.Bold`. **Boolean**. + +### FontItalic +{: .no_toc } + +Shortcut for `Font.Italic`. **Boolean**. + +### FontName +{: .no_toc } + +Shortcut for `Font.Name`. **String**. + +### FontSize +{: .no_toc } + +Shortcut for `Font.Size`. **Single**, in points. + +### FontStrikethru +{: .no_toc } + +Shortcut for `Font.Strikethrough`. **Boolean**. + +### FontUnderline +{: .no_toc } + +Shortcut for `Font.Underline`. **Boolean**. + +### ForeColor +{: .no_toc } + +The colour used to draw [**Caption**](#caption), as an **OLE_COLOR**. Defaults to the system button-text colour. + +### Height +{: .no_toc } + +The frame's height, in twips by default (or in the container's **ScaleMode** units). **Double**. + +### HelpContextID +{: .no_toc } + +A **Long** identifying a topic in the application's help file, retrieved when the user invokes context help while the frame has the active control underneath it. + +### hWnd +{: .no_toc } + +The Win32 window handle for the frame, as a **LongPtr**. Read-only. Useful for passing to API functions. + +### Index +{: .no_toc } + +When the frame 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 frame. **Double**. + +### MouseIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor when [**MousePointer**](#mousepointer) is **vbCustom** and the pointer is over the frame. + +### MousePointer +{: .no_toc } + +The mouse cursor shown when the pointer is over the frame (and not over a child control with its own setting). A member of [**MousePointerConstants**](../../VBRUN/Constants/MousePointerConstants). + +### 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. + +### 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. + +### Name +{: .no_toc } + +The unique design-time name of the frame on its parent form. Read-only at run time. + +### OLEDropMode +{: .no_toc } + +How the frame responds to OLE drops. A restricted member of [**OLEDropConstants**](../../VBRUN/Constants/OLEDropConstants): **vbOLEDropNone** or **vbOLEDropManual**. Automatic-drop mode is not supported on a Frame; assigning **vbOLEDropAutomatic** raises run-time error 5. + +### Opacity +{: .no_toc } + +The frame's opacity as a percentage (0–100, default 100). Values outside the range are clamped on **Initialize**. Values below 100 require Windows 8 or later when the frame has child controls; out-of-process child windows are not affected. + +### 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. + +### Parent +{: .no_toc } + +A reference to the [**Form**](../Form/) (or **UserControl**) that ultimately contains the frame. Read-only. Distinct from [**Container**](#container), which returns the immediate parent (form *or* enclosing frame). + +### RightToLeft +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### TabIndex +{: .no_toc } + +The position of the frame in the form's TAB-key navigation order. **Long**. The frame itself does not receive focus, but **TabIndex** controls where the frame's mnemonic forwards focus to: **Alt+** the marked character moves to the next focusable control whose **TabIndex** is greater than this one. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the frame. Ignored by the framework. + +### ToolTipText +{: .no_toc } + +A multi-line **String** displayed as a tooltip when the user hovers over the frame's border or background. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the frame. **Double**. + +### TransparencyKey +{: .no_toc } + +An **OLE_COLOR** that, when set, becomes fully transparent in the rendered frame — clicks pass through to whatever is underneath, and the corresponding pixels do not paint. Default `-1` disables the effect. Requires Windows 8 or later when the frame has child controls. + +### Visible +{: .no_toc } + +Whether the frame and its contained controls are shown. **Boolean**, default **True**. + +### VisualStyles +{: .no_toc } + +Whether the OS theme engine should be used when drawing the frame border and caption. **Boolean**, default **True**. + +### WhatsThisHelpID +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. See [**ShowWhatsThis**](#showwhatsthis). + +### Width +{: .no_toc } + +The frame's width. **Double**. + +## 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 frame in a single call. Contained controls are repositioned with it. + +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 frame, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject**. + +Syntax: *object*.**OLEDrag** + +### Refresh +{: .no_toc } + +Forces an immediate repaint of the frame and its border. + +Syntax: *object*.**Refresh** + +### SetFocus +{: .no_toc } + +Attempts to move the input focus to the frame. Because a frame is not focusable, this call has no observable effect on which control holds the focus, but it is provided for parity with the rest of the control surface and for compatibility with code that calls **SetFocus** generically. + +Syntax: *object*.**SetFocus** + +### ShowWhatsThis +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +Syntax: *object*.**ShowWhatsThis** + +### ZOrder +{: .no_toc } + +Brings the frame 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 + +### Click +{: .no_toc } + +Raised when the user single-clicks the frame's client area or border (i.e. not over any contained control). **Default event.** + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks the frame's client area or border. + +Syntax: *object*\_**DblClick**( ) + +### DragDrop +{: .no_toc } + +Raised on the destination control when a manual drag operation ends over this frame. + +Syntax: *object*\_**DragDrop**( *Source* **As Control**, *X* **As Single**, *Y* **As Single** ) + +### DragOver +{: .no_toc } + +Raised on the frame while a manual drag operation is in progress over it. + +Syntax: *object*\_**DragOver**( *Source* **As Control**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### Initialize +{: .no_toc } + +Raised once, after the frame's underlying window has been created but before any contained controls are populated. Useful for setting initial values that the frame's children will read on their own initialisation. + +Syntax: *object*\_**Initialize**( ) + +### MouseDown +{: .no_toc } + +Raised when the user presses any mouse button over the frame's client area or border. + +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 frame's client area or border. + +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 frame's client area or border. + +Syntax: *object*\_**MouseUp**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseWheel +{: .no_toc } + +Raised when the mouse wheel turns over the frame. New in twinBASIC. + +Syntax: *object*\_**MouseWheel**( *Delta* **As Integer**, *Horizontal* **As Boolean** ) + +### 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 frame 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 frame 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** ) diff --git a/docs/Reference/VB/HScrollBar/index.md b/docs/Reference/VB/HScrollBar/index.md new file mode 100644 index 0000000..eb6b71a --- /dev/null +++ b/docs/Reference/VB/HScrollBar/index.md @@ -0,0 +1,392 @@ +--- +title: HScrollBar +parent: VB Package +permalink: /tB/Packages/VB/HScrollBar/ +has_toc: false +--- + +# HScrollBar class +{: .no_toc } + +An **HScrollBar** is a Win32 native horizontal scroll bar exposed as a stand-alone control. Unlike the scroll bars that automatically appear inside a [**ListBox**](../ListBox), [**ComboBox**](../ComboBox), or [**TextBox**](../TextBox), an **HScrollBar** is independent of any other control — its [**Value**](#value) is whatever your code reads or writes. The typical use is to drive a numeric setting (a volume level, a paginator, a colour channel, the offset of a custom-drawn surface) by binding the **HScrollBar**'s [**Change**](#change) and [**Scroll**](#scroll) events to whatever the value represents. + +[**VScrollBar**](../VScrollBar) is the vertical counterpart; the two classes are identical apart from orientation. + +The default property is [**Value**](#value) and the default event is [**Change**](#change). + +```tb +Private Sub Form_Load() + hsbVolume.Min = 0 + hsbVolume.Max = 100 + hsbVolume.SmallChange = 1 + hsbVolume.LargeChange = 10 + hsbVolume.Value = 50 +End Sub + +Private Sub hsbVolume_Change() + lblVolume.Caption = "Volume: " & hsbVolume.Value & "%" +End Sub + +Private Sub hsbVolume_Scroll() + lblVolume.Caption = "Volume: " & hsbVolume.Value & "%" ' live update during drag +End Sub +``` + +* TOC +{:toc} + +## Range and value + +[**Min**](#min) and [**Max**](#max) define the closed range of integer values the scroll bar can represent, and [**Value**](#value) is the position within that range. Defaults are `0`, `32767`, and `0`. Assigning a [**Value**](#value) outside the current `[Min, Max]` interval raises run-time error 380 (*Invalid property value*); assigning the current value is a no-op (no [**Change**](#change) is raised). + +The two endpoints may be supplied in either order. When **Min** is greater than **Max** the scroll bar runs *inverted* — moving the thumb to the right decreases [**Value**](#value), and **Max** is the lower bound of the legal range. This is convenient for, for example, a "high-on-the-left" colour or zoom slider: + +```tb +hsbZoom.Min = 400 ' leftmost == 4.00x +hsbZoom.Max = 100 ' rightmost == 1.00x +hsbZoom.Value = 100 +``` + +Changing **Min** or **Max** at run time clips the current [**Value**](#value) into the new range silently — no [**Change**](#change) event is raised for the implicit clip. + +## Increment sizes + +The scroll bar produces value changes through four kinds of user input: + +| Input | Increment per step | Event raised | +|-------------------------------------|------------------------------|------------------| +| Click an end-arrow | [**SmallChange**](#smallchange) | [**Change**](#change) | +| Click the track on either side of the thumb | [**LargeChange**](#largechange) | [**Change**](#change) | +| Drag the thumb | continuous | [**Scroll**](#scroll) during drag, [**Change**](#change) on release | +| Press **Home** / **End** | jumps to **Min** / **Max** | [**Change**](#change) | + +Both [**SmallChange**](#smallchange) and [**LargeChange**](#largechange) default to `1`. [**LargeChange**](#largechange) also drives the visible width of the thumb relative to the track, so larger values produce a chunkier thumb. + +## Change versus Scroll + +The split between the two events lets the application choose how often it reacts to user input. [**Scroll**](#scroll) fires repeatedly while the user is dragging the thumb, so a handler can update a live preview as the thumb moves. [**Change**](#change) fires once each time the value settles — after the user releases the thumb, after a click on an arrow or the track, or whenever code assigns a different [**Value**](#value). Many applications wire both events to the same handler so that the bound display updates both during dragging and after. + +## Properties + +### Anchors +{: .no_toc } + +The set of edges of the parent that the scroll bar's corresponding edges follow when the parent resizes. Read-only — assign individual `.Left`, `.Top`, `.Right`, `.Bottom` flags through the returned **Anchors** object. + +### 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 scroll bar — typically the form, a [**Frame**](../Frame/), or a **UserControl**. Read with **Get**, change with **Set**. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a horizontal scroll bar. Always **vbHScrollBar**. + +### Dock +{: .no_toc } + +Where the scroll bar is docked within its container. A member of [**DockModeConstants**](../../VBRUN/Constants/DockModeConstants): **vbDockNone** (default), **vbDockLeft**, **vbDockTop**, **vbDockRight**, **vbDockBottom**, or **vbDockFill**. Docked scroll bars 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 scroll bar accepts user input. A disabled scroll bar is greyed out and does not respond to mouse or keyboard interaction. **Boolean**, default **True**. + +### Height +{: .no_toc } + +The scroll bar's height in twips (or in the container's **ScaleMode** units). **Double**. For a horizontal scroll bar this is the small dimension — typically the OS standard scroll-bar thickness; values larger than that simply enlarge the surrounding hit area. + +### 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 scroll bar, as a **LongPtr**. Read-only. Useful for passing to API functions. + +### Index +{: .no_toc } + +When the scroll bar 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. + +### LargeChange +{: .no_toc } + +The amount [**Value**](#value) is adjusted when the user clicks the track on either side of the thumb (or presses **Page Up** / **Page Down** while the scroll bar has focus). **Long**, default `1`. Also influences the visible width of the thumb: bigger values produce a wider thumb relative to the track. + +### Left +{: .no_toc } + +The horizontal distance from the left edge of the container to the left edge of the scroll bar. **Double**. + +### Max +{: .no_toc } + +The upper end of the scroll bar's value range. **Long**, default `32767`. May be set lower than [**Min**](#min) to invert the direction of travel — see [Range and value](#range-and-value). + +Syntax: *object*.**Max** [ = *value* ] + +Changing **Max** clips the current [**Value**](#value) into the new range silently if it now falls outside. + +### Min +{: .no_toc } + +The lower end of the scroll bar's value range. **Long**, default `0`. May be set higher than [**Max**](#max) to invert the direction of travel. + +Syntax: *object*.**Min** [ = *value* ] + +Changing **Min** clips the current [**Value**](#value) into the new range silently if it now falls outside. + +### 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. + +### 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 scroll bar. Read-only. + +### RightToLeft +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. To run the scroll bar in reverse, swap [**Min**](#min) and [**Max**](#max). + +### SmallChange +{: .no_toc } + +The amount [**Value**](#value) is adjusted when the user clicks one of the end-arrows (or presses an arrow key while the scroll bar has focus). **Long**, default `1`. + +### 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 scroll bar. **Double**. + +### 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. + +### Value +{: .no_toc } + +The scroll bar's current position within `[Min, Max]`. **Long**, default `0`. **Default property.** + +Syntax: *object*.**Value** [ = *value* ] + +*value* +: A **Long** in the closed interval `[Min, Max]` (or `[Max, Min]` for an inverted scroll bar). Values outside that interval raise run-time error 380 (*Invalid property value*). + +Assigning a value that differs from the current one moves the thumb and raises a single [**Change**](#change) event. Assigning the current value is a silent no-op. + +### Visible +{: .no_toc } + +Whether the scroll bar is shown. **Boolean**, default **True**. + +### VisualStyles +{: .no_toc } + +Whether the OS theme engine should be used when drawing the scroll bar. **Boolean**, default **True**. + +### 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 scroll bar's width — i.e., the length of the track. **Double**. + +## Methods + +### Drag +{: .no_toc } + +Begins, completes, or cancels a manual drag-and-drop operation. Typically called from code 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 scroll bar 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. + +### Refresh +{: .no_toc } + +Forces an immediate repaint of the scroll bar. + +Syntax: *object*.**Refresh** + +### SetFocus +{: .no_toc } + +Moves the input focus to the scroll bar. 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** + +### SyncScrollBar +{: .no_toc } + +Re-applies the current [**Min**](#min), [**Max**](#max), [**LargeChange**](#largechange), and [**Value**](#value) to the underlying Win32 scroll bar. Property assignments already do this implicitly — call **SyncScrollBar** only when external code (typically a Win32 API call) has reached around the control and changed its native state. + +Syntax: *object*.**SyncScrollBar** + +### 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 + +### Change +{: .no_toc } + +Raised after [**Value**](#value) settles on a new value — when the user releases the thumb after a drag, when the user clicks an arrow or the track, when the user presses **Home**, **End**, or an arrow key with focus on the scroll bar, or when code assigns a different [**Value**](#value). Not raised for the continuous updates that happen during a drag — see [**Scroll**](#scroll) for that. **Default event.** + +Syntax: *object*\_**Change**( ) + +### 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 scroll bar receives the input focus. + +Syntax: *object*\_**GotFocus**( ) + +### Initialize +{: .no_toc } + +Raised once, after the underlying window has been created and the scroll bar is wired up to its Win32 range, but before the scroll bar is first painted. Useful for last-minute setup that needs the underlying handle. + +Syntax: *object*\_**Initialize**( ) + +### KeyDown +{: .no_toc } + +Raised when the user presses any key while the control has focus. Note that the scroll bar already handles the arrow keys, **Page Up** / **Page Down**, and **Home** / **End** internally — but **KeyDown** still fires for them in addition to the resulting [**Change**](#change). + +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 scroll bar loses the input focus. + +Syntax: *object*\_**LostFocus**( ) + +### Scroll +{: .no_toc } + +Raised continuously while the user is dragging the thumb, once for each tick that produces a different [**Value**](#value). After the user releases the thumb, a single [**Change**](#change) event fires with the final value. Use **Scroll** when you want a live preview while the thumb is moving; use [**Change**](#change) when you want to react only to the final value. + +Syntax: *object*\_**Scroll**( ) + +### 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/Image/index.md b/docs/Reference/VB/Image/index.md new file mode 100644 index 0000000..4447ca4 --- /dev/null +++ b/docs/Reference/VB/Image/index.md @@ -0,0 +1,415 @@ +--- +title: Image +parent: VB Package +permalink: /tB/Packages/VB/Image/ +has_toc: false +--- + +# Image class +{: .no_toc } + +An **Image** is a windowless lightweight control for displaying a picture — a bitmap, JPEG, GIF, PNG, icon, cursor, or Windows metafile. It is the small, efficient alternative to [**PictureBox**](../PictureBox): no underlying Win32 window, no drawing surface, no child controls, no focus — just a rectangle on the parent that paints whatever is in [**Picture**](#picture). Image controls are ideal for logos, decorative artwork, custom-drawn buttons, glyph rows, and any other place where a heavy **PictureBox** would be overkill. + +The default property is [**Picture**](#picture) and the default event is [**Click**](#click). + +```tb +Private Sub Form_Load() + Set imgLogo.Picture = LoadPicture(App.Path & "\logo.png") + imgLogo.Stretch = True + imgLogo.BorderStyle = vbFixedSingleBorder +End Sub + +Private Sub imgLogo_Click() + MsgBox "Logo clicked" +End Sub +``` + +* TOC +{:toc} + +## Windowless rendering + +An **Image** has no `hWnd`. The framework paints it directly onto its parent's drawing surface during the parent's paint cycle, so the control is much cheaper than a [**PictureBox**](../PictureBox) and adds no Win32 window of its own. The trade-offs are the same as for any windowless control: + +- No focus, no keyboard input, no `KeyDown` / `KeyPress` / `KeyUp` / `GotFocus` / `LostFocus` / `Validate`. +- No `hWnd` to pass to API functions, and no `SetFocus`. +- Cannot host child controls. + +For anything that needs those, use [**PictureBox**](../PictureBox) instead. + +## Stretch and auto-sizing + +[**Stretch**](#stretch) is the master switch for sizing behaviour: + +- **Stretch = False** (default): the picture is drawn at its natural pixel size and the **Image** auto-resizes itself to match every time a new [**Picture**](#picture) is assigned. The user may still resize the control manually — once that happens the picture is clipped or padded around the natural bounds (it is *not* re-stretched). +- **Stretch = True**: the picture is scaled to fill the **Image**'s rectangle. The resampling algorithm is chosen by [**StretchMode**](#stretchmode); aspect ratio is *not* preserved. + +Metafiles (`vbPicTypeMetafile`, `vbPicTypeEMetafile`) are vector — they always scale to fit and the aspect ratio is preserved regardless of [**Stretch**](#stretch). + +[**PictureDpiScaling**](#picturedpiscaling), when **True**, multiplies the natural pixel dimensions by the current DPI scale factor before drawing — useful for keeping a logo the same physical size on a high-DPI monitor as on a 96-DPI one. + +## Rotation + +[**Angle**](#angle) rotates the rendered picture, in degrees, anti-clockwise around the top-left corner of the control's rectangle. `0` is the natural orientation; `90` is a quarter turn anti-clockwise; values between `0` and `360` give arbitrary rotations. The control's bounding rectangle does not change — large rotation angles can therefore push the visible picture outside the rectangle. Hit-testing for [**Click**](#click), [**MouseDown**](#mousedown), and the other mouse events still uses the unrotated rectangle. + +## Border + +[**BorderStyle**](#borderstyle) chooses between no border (the default) and a single sunken border drawn around the rectangle. When a border is present, [**Appearance**](#appearance) selects between a 3-D and a flat (monochrome) version of it. + +## Source-side and destination-side OLE drag-drop + +The **Image** control supports both ends of an OLE drag-drop operation: + +- [**OLEDragMode**](#oledragmode) controls the source side. With **vbOLEDragAutomatic**, holding the mouse over the **Image** and beginning a drag automatically picks up the current [**Picture**](#picture) into the resulting **DataObject**. With **vbOLEDragManual** (default) drags must be initiated by calling [**OLEDrag**](#oledrag) from a [**MouseDown**](#mousedown) handler. +- [**OLEDropMode**](#oledropmode) controls the destination side. With **vbOLEDropManual** the [**OLEDragOver**](#oledragover) and [**OLEDragDrop**](#oledragdrop) events fire and the application decides what to do. **vbOLEDropAutomatic** is not supported on an **Image** and assigning it raises run-time error 5. + +## Data binding + +Setting [**DataSource**](#datasource) and [**DataField**](#datafield) connects the [**Picture**](#picture) to a field of a [**Data**](../Data/) control's recordset. The bound field is read as binary picture data on each move; assigning **Nothing** to **Picture** writes a null-equivalent back to the recordset, and any other assignment serialises the picture's bytes back through the bound field. + +## Properties + +### Anchors +{: .no_toc } + +The set of edges of the parent that the **Image**'s corresponding edges follow when the parent resizes. Read-only — assign individual `.Left`, `.Top`, `.Right`, `.Bottom` flags through the returned **Anchors** object. + +### Angle +{: .no_toc } + +The rotation of the rendered picture, in degrees, anti-clockwise around the top-left of the control's rectangle. **Double**, default `0`. + +### Appearance +{: .no_toc } + +The style of the border, as a member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). Only meaningful when [**BorderStyle**](#borderstyle) is **vbFixedSingleBorder**. + +### BorderStyle +{: .no_toc } + +The style of border drawn around the rectangle. A member of [**ControlBorderStyleConstants**](../../VBRUN/Constants/ControlBorderStyleConstants): **vbNoBorder** (0, default) or **vbFixedSingleBorder** (1). + +### Container +{: .no_toc } + +The control that hosts this **Image** — typically the form, a [**Frame**](../Frame/), or a **UserControl**. Read with **Get**, change with **Set**. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as an image. Always **vbImage**. + +### DataChanged +{: .no_toc } + +Whether the bound [**Picture**](#picture) has been written to since the last save or refresh from the [**DataSource**](#datasource). **Boolean**. Setting **DataChanged** = **True** also marks the bound recordset as dirty. + +### DataField +{: .no_toc } + +The name of the field, in the recordset of the bound [**DataSource**](#datasource), whose binary value is mirrored by [**Picture**](#picture). **String**. + +### DataFormat +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### DataMember +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### 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 **Image** is docked within its container. A member of [**DockModeConstants**](../../VBRUN/Constants/DockModeConstants): **vbDockNone** (default), **vbDockLeft**, **vbDockTop**, **vbDockRight**, **vbDockBottom**, or **vbDockFill**. Docked images 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 (the manual VB-drag form, distinct from OLE drag) 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 mouse input. A disabled **Image** still paints normally but ignores mouse events. **Boolean**, default **True**. + +### Height +{: .no_toc } + +The control's height, in twips by default (or in the container's **ScaleMode** units). **Double**. When [**Stretch**](#stretch) is **False** and a new [**Picture**](#picture) is assigned, the height auto-resizes to the picture's natural pixel height. + +### 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. **Double**. + +### 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. + +### OLEDragMode +{: .no_toc } + +Whether an OLE drag is started automatically when the user begins dragging the **Image**. A member of [**OLEDragConstants**](../../VBRUN/Constants/OLEDragConstants): **vbOLEDragManual** (0, default — application calls [**OLEDrag**](#oledrag)) or **vbOLEDragAutomatic** (1 — the framework picks up the current [**Picture**](#picture) into the resulting **DataObject** automatically). + +### OLEDropMode +{: .no_toc } + +How the **Image** responds to OLE drops landing on it. A restricted member of [**OLEDropConstants**](../../VBRUN/Constants/OLEDropConstants): **vbOLEDropNone** (0, default) or **vbOLEDropManual** (1). Automatic drop is not supported on an **Image**; assigning **vbOLEDropAutomatic** raises run-time error 5 (*Invalid procedure call or argument*). + +### Parent +{: .no_toc } + +A reference to the [**Form**](../Form/) (or **UserControl**) that ultimately contains the control. Read-only. + +### Picture +{: .no_toc } + +The **StdPicture** rendered by the control. **Default property.** + +Syntax: `Set` *object*.**Picture** = *picture* + +Assigning **Nothing** restores an empty picture rather than removing the surface. Assigning a new picture while [**Stretch**](#stretch) is **False** auto-resizes the control to the picture's natural pixel dimensions; while [**Stretch**](#stretch) is **True** the existing rectangle is preserved and the new picture is scaled to fit. + +### PictureDpiScaling +{: .no_toc } + +When **True**, the picture's natural pixel dimensions are multiplied by the current DPI scale factor before being drawn (and used by the auto-size logic). **Boolean**, default **False**. + +### Stretch +{: .no_toc } + +Whether the picture is scaled to fill the control's rectangle (**True**) or rendered at its natural size with the control auto-sized to fit (**False**, default). See [Stretch and auto-sizing](#stretch-and-auto-sizing) for the full rules. Metafiles always scale regardless of this setting. + +### StretchMode +{: .no_toc } + +The resampling algorithm used when [**Stretch**](#stretch) is **True** and the picture is scaled. A member of `Image.StretchModeConstants`: + +| Constant | Value | Algorithm | +|---------------------------|-------|--------------------------------------------------------------------------| +| **vbStretchHalftone** | 0 | GDI `STRETCH_HALFTONE` (default — good general-purpose quality). | +| **vbStretchColorOnColor** | 1 | GDI `STRETCH_COLORONCOLOR` (fastest, lowest quality — nearest neighbour). | +| **vbStretchLanczos8** | 2 | Custom Lanczos resampler with an 8-lobe kernel (highest quality, slowest). | +| **vbStretchLanczos3** | 3 | Custom Lanczos resampler with a 3-lobe kernel (high quality). | +| **vbStretchBicubic** | 4 | Custom bicubic resampler. | +| **vbStretchBilinear** | 5 | Custom bilinear resampler. | + +The Lanczos, bicubic, and bilinear modes only apply to bitmaps that actually need resizing — metafiles and unscaled bitmaps fall back to the GDI mode. + +### 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. **Double**. + +### 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. See [**ShowWhatsThis**](#showwhatsthis). + +### Width +{: .no_toc } + +The control's width, in twips by default (or in the container's **ScaleMode** units). **Double**. When [**Stretch**](#stretch) is **False** and a new [**Picture**](#picture) is assigned, the width auto-resizes to the picture's natural pixel width. + +## Methods + +### Drag +{: .no_toc } + +Begins, completes, or cancels a manual VB-style drag operation. Distinct from OLE drag — see [**OLEDrag**](#oledrag). + +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 this **Image**, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject** (or, if the source has already been pre-populated, kicks off the drag immediately). + +Syntax: *object*.**OLEDrag** + +### Refresh +{: .no_toc } + +Forces an immediate repaint of the **Image**'s rectangle on the parent's drawing surface. + +Syntax: *object*.**Refresh** + +### ShowWhatsThis +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +Syntax: *object*.**ShowWhatsThis** + +### ZOrder +{: .no_toc } + +Brings the **Image** to the front or back of the windowless-sibling stack within its container. + +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 the user single-clicks the control's rectangle. **Default event.** + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks the control's rectangle. + +Syntax: *object*\_**DblClick**( ) + +### DragDrop +{: .no_toc } + +Raised on the destination control when a manual VB-style 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 VB-style drag operation is in progress. + +Syntax: *object*\_**DragOver**( *Source* **As Control**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### Initialize +{: .no_toc } + +Raised once, after the control has been wired into its container's paint cycle but before it is first painted. Useful for last-minute setup that depends on container state. + +Syntax: *object*\_**Initialize**( ) + +### 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** ) diff --git a/docs/Reference/VB/Label/index.md b/docs/Reference/VB/Label/index.md new file mode 100644 index 0000000..bf34c6b --- /dev/null +++ b/docs/Reference/VB/Label/index.md @@ -0,0 +1,611 @@ +--- +title: Label +parent: VB Package +permalink: /tB/Packages/VB/Label/ +has_toc: false +--- + +# Label class +{: .no_toc } + +A **Label** is a windowless lightweight control for displaying read-only text. Labels are typically used as static captions next to input controls ("Name:", "Email:"), as status displays that code keeps up to date, or as keyboard-mnemonic anchors that route **Alt+** keystrokes to the next focusable control. Because the **Label** has no `hWnd` of its own, it is much cheaper than a [**TextBox**](../TextBox) configured to be read-only — but it is also non-interactive in the keyboard sense: it cannot take focus, raise key events, or be selected with the **TAB** key. + +The default property is [**Caption**](#caption) and the default event is [**Click**](#click). + +```tb +Private Sub Form_Load() + lblName.Caption = "&Name:" ' Alt+N forwards focus to the next control + lblName.AutoSize = True + txtName.Text = "" ' the TextBox that receives Alt+N +End Sub + +Private Sub Timer1_Timer() + lblClock.Caption = Format$(Now, "hh:mm:ss") +End Sub +``` + +* TOC +{:toc} + +## Windowless rendering + +Like [**Image**](../Image/), a **Label** has no `hWnd`. The framework paints it directly onto its parent's drawing surface during the parent's paint cycle. The trade-offs are the same: + +- No focus, no keyboard input, no `KeyDown` / `KeyPress` / `KeyUp` / `GotFocus` / `LostFocus` / `Validate`. +- No `hWnd` to pass to API functions, and no `SetFocus`. +- Cannot host child controls. + +For text the user can edit (or that needs to take focus), use [**TextBox**](../TextBox) with `Locked = True` instead. + +## Mnemonics and access keys + +Labels do not take focus themselves, but they participate in keyboard-mnemonic routing. With [**UseMnemonic**](#usemnemonic) **True** (the default), an ampersand in [**Caption**](#caption) marks the next character as a mnemonic — pressing **Alt+** that character moves the focus to the *next focusable control in tab order* after the label. Use `&&` to display a literal ampersand. Set [**UseMnemonic**](#usemnemonic) to **False** to disable the special handling and have ampersands rendered verbatim. + +```tb +lblName.Caption = "&Name:" ' Alt+N → next control (typically txtName) +lblHelp.Caption = "Use && to escape" ' renders as: Use & to escape +``` + +The convention is to place the **Label** immediately before the control it captions in tab order, so the mnemonic naturally lands on that control. + +## Caption layout + +[**Alignment**](#alignment) and [**VerticalAlignment**](#verticalalignment) together position the caption within the label's rectangle: + +| Property | Members | +|------------------------------------------|------------------------------------------------------------------------------------------------------------------| +| [**Alignment**](#alignment) | **vbLeftJustify** (0, default), **vbRightJustify** (1), **vbCenter** (2) | +| [**VerticalAlignment**](#verticalalignment) | **vbVerticalAlignTop** (0, default), **vbVerticalAlignMiddle** (1), **vbVerticalAlignBottom** (2) | + +[**WordWrap**](#wordwrap), when **True**, breaks the caption into multiple lines at white-space whenever it would otherwise exceed [**Width**](#width). [**LineSpacing**](#linespacing) inserts extra vertical gap (in twips) between lines. + +[**AutoSize**](#autosize), when **True**, resizes the label to fit its caption every time the caption, font, border, or word-wrap setting changes. Auto-sizing measures the current font in the parent's device context, so it produces correct results on high-DPI displays. When **AutoSize** is **False**, the caption is clipped to the label's rectangle (still respecting [**WordWrap**](#wordwrap) and the alignment settings). + +## Rotation + +[**Angle**](#angle) rotates the rendered caption, in degrees, anti-clockwise around the top-left of the control's rectangle. `0` is the natural orientation, `90` is a quarter-turn anti-clockwise, and so on. The control's bounding rectangle does not change — large rotation angles can therefore push the visible text outside the rectangle. Hit-testing for [**Click**](#click) and the mouse events still uses the unrotated rectangle. + +## Border styles + +[**BorderStyle**](#borderstyle) chooses between three styles: + +| Constant | Value | Description | +|---------------------------|-------|--------------------------------------------------------------------------------------------| +| **vbNoBorder** | 0 | No border (default). | +| **vbFixedSingleBorder** | 1 | A sunken Win32-style border. [**Appearance**](#appearance) selects 3-D or flat. | +| **vbCustomBorder** | 2 | Per-edge custom border configured through [**BorderCustomOptions**](#bordercustomoptions). | + +With **vbCustomBorder**, [**BorderCustomOptions**](#bordercustomoptions) returns an object whose `.Left`, `.Top`, `.Right`, and `.Bottom` properties each carry independent **Size** (line thickness, in twips), **Padding** (inset between the border and the caption, in twips), and **Color** values: + +```tb +lblBox.BorderStyle = vbCustomBorder +With lblBox.BorderCustomOptions + .Top.Size = 30 : .Top.Color = vbRed : .Top.Padding = 60 + .Bottom.Size = 30 : .Bottom.Color = vbRed : .Bottom.Padding = 60 +End With +``` + +## Background + +[**BackStyle**](#backstyle) chooses between **vbBFOpaque** (default — paint [**BackColor**](#backcolor) under the caption) and **vbBFTransparent** (don't paint a background — whatever the parent has drawn shows through). Transparent labels are essential when overlaying captions on a [**PictureBox**](../PictureBox), an [**Image**](../Image/), or a custom-painted form background. New labels created in *report mode* default to **vbBFTransparent**. + +## Data binding + +Setting [**DataSource**](#datasource) and [**DataField**](#datafield) connects [**Caption**](#caption) to a field of a [**Data**](../Data/) control's recordset. The bound field is read as a string on each move, and assigning to [**Caption**](#caption) marks the recordset as dirty. [**DataFieldAggregate**](#datafieldaggregate) and [**DataFieldAggregateValue**](#datafieldaggregatevalue) are used by the report engine to display running totals. + +## Properties + +### Alignment +{: .no_toc } + +The horizontal placement of [**Caption**](#caption) within the label's rectangle. A member of [**AlignmentConstants**](../../VBRUN/Constants/AlignmentConstants): **vbLeftJustify** (0, default), **vbRightJustify** (1), or **vbCenter** (2). + +### Anchors +{: .no_toc } + +The set of edges of the parent that the label's corresponding edges follow when the parent resizes. Read-only — assign individual `.Left`, `.Top`, `.Right`, `.Bottom` flags through the returned **Anchors** object. + +### Angle +{: .no_toc } + +The rotation of the rendered caption, in degrees, anti-clockwise around the top-left of the control's rectangle. **Double**, default `0`. + +### Appearance +{: .no_toc } + +The style of the border, as a member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). Only meaningful when [**BorderStyle**](#borderstyle) is **vbFixedSingleBorder**. + +### AutoSize +{: .no_toc } + +Whether the label resizes itself to fit its [**Caption**](#caption), [**Font**](#font), border, and word-wrap settings. **Boolean**, default **False**. When **True**, the resize happens whenever any of those inputs change. + +### BackColor +{: .no_toc } + +The colour painted behind the caption when [**BackStyle**](#backstyle) is **vbBFOpaque**. **OLE_COLOR**, defaults to the system 3-D face colour. + +### BackStyle +{: .no_toc } + +Whether the label paints a background. A member of [**BackFillStyleConstants**](../../VBRUN/Constants/BackFillStyleConstants): **vbBFOpaque** (1, default — paint [**BackColor**](#backcolor)) or **vbBFTransparent** (0 — let whatever the parent has drawn show through). + +### BorderCustomOptions +{: .no_toc } + +Per-edge configuration for the **vbCustomBorder** style. Read-only; the returned object exposes `.Left`, `.Top`, `.Right`, `.Bottom` sub-objects, each with `Size`, `Padding`, and `Color` properties. See [Border styles](#border-styles). + +### BorderStyle +{: .no_toc } + +The style of border drawn around the label. A member of [**ControlBorderStyleConstantsCustom**](../../VBRUN/Constants/ControlBorderStyleConstantsCustom): **vbNoBorder** (0, default), **vbFixedSingleBorder** (1), or **vbCustomBorder** (2). See [Border styles](#border-styles). + +### Caption +{: .no_toc } + +The text rendered by the label. **String**. **Default property.** + +Syntax: *object*.**Caption** [ = *string* ] + +An ampersand marks the next character as a mnemonic when [**UseMnemonic**](#usemnemonic) is **True**; `&&` produces a literal ampersand. Assigning a value that differs from the current one raises a [**Change**](#change) event; assigning the current value is a silent no-op. + +### Container +{: .no_toc } + +The control that hosts this label — typically the form, a [**Frame**](../Frame/), or a **UserControl**. Read with **Get**, change with **Set**. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a label. Always **vbLabel**. + +### DataChanged +{: .no_toc } + +Whether the bound [**Caption**](#caption) has been written to since the last save or refresh from the [**DataSource**](#datasource). **Boolean**. Setting **DataChanged** = **True** also marks the bound recordset as dirty. + +### DataField +{: .no_toc } + +The name of the field, in the recordset of the bound [**DataSource**](#datasource), whose value is mirrored by [**Caption**](#caption). **String**. + +### DataFieldAggregate +{: .no_toc } + +The kind of running aggregate the report engine should accumulate into [**DataFieldAggregateValue**](#datafieldaggregatevalue). A member of `Label.AggregateConstants`: + +| Constant | Value | Description | +|---------------------|-------|----------------------------------------------------------------------| +| **vbAggregateNone** | 0 | No aggregation (default). | +| **vbAggregateSum** | 1 | Sum the bound numeric value across the rows visited by the report. | + +Used only when the label is rendered inside a [**Report**](../Report) section. + +### DataFieldAggregateValue +{: .no_toc } + +The accumulated aggregate value computed by the report engine, exposed as a **Decimal**. Updated by the engine while a report is being generated; user code can read it from event handlers but does not normally write to it. + +### DataFormat +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### DataMember +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### 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 label is docked within its container. A member of [**DockModeConstants**](../../VBRUN/Constants/DockModeConstants): **vbDockNone** (default), **vbDockLeft**, **vbDockTop**, **vbDockRight**, **vbDockBottom**, or **vbDockFill**. Docked labels 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 } + +Whether the label accepts mouse input and renders [**Caption**](#caption) in the normal text colour. A disabled label still paints, but in the system grey-text colour, and ignores mouse events. **Boolean**, default **True**. + +### Font +{: .no_toc } + +The **StdFont** used to render [**Caption**](#caption). The convenience properties **FontBold**, **FontItalic**, **FontName**, **FontSize**, **FontStrikethru**, and **FontUnderline** read or write the corresponding members of this object. Defaults to Segoe UI, 8 pt. + +### FontBold +{: .no_toc } + +Shortcut for `Font.Bold`. **Boolean**. + +### FontItalic +{: .no_toc } + +Shortcut for `Font.Italic`. **Boolean**. + +### FontName +{: .no_toc } + +Shortcut for `Font.Name`. **String**, default `"Segoe UI"`. + +### FontSize +{: .no_toc } + +Shortcut for `Font.Size`. **Single**, in points. Default `8`. + +### FontStrikethru +{: .no_toc } + +Shortcut for `Font.Strikethrough`. **Boolean**. + +### FontUnderline +{: .no_toc } + +Shortcut for `Font.Underline`. **Boolean**. + +### ForeColor +{: .no_toc } + +The text colour for [**Caption**](#caption), as an **OLE_COLOR**. Defaults to the system button-text colour. Replaced with the system grey-text colour when [**Enabled**](#enabled) is **False**. + +### Height +{: .no_toc } + +The control's height, in twips by default (or in the container's **ScaleMode** units). **Double**. Computed automatically while [**AutoSize**](#autosize) is **True**. + +### Index +{: .no_toc } + +When the label 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 label. **Double**. + +### LineSpacing +{: .no_toc } + +Extra vertical space inserted between lines of a wrapped or multi-line caption, in twips. **Long**, default `0`. + +### LinkItem +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently implemented in twinBASIC. + +### LinkMode +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently implemented in twinBASIC. + +### LinkTimeout +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently implemented in twinBASIC. + +### LinkTopic +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; 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 label responds to OLE drops. A restricted member of [**OLEDropConstants**](../../VBRUN/Constants/OLEDropConstants): **vbOLEDropNone** (0, default) or **vbOLEDropManual** (1). Automatic drop is not supported on a Label; assigning **vbOLEDropAutomatic** raises run-time error 5 (*Invalid procedure call or argument*). + +### Parent +{: .no_toc } + +A reference to the [**Form**](../Form/) (or **UserControl**) that ultimately contains the control. Read-only. + +### RightToLeft +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. Use [**Alignment**](#alignment) `vbRightJustify` to right-align the caption. + +### TabIndex +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. The label is non-focusable, so the value would only affect mnemonic-routing — that is currently driven by the design-time Z-order instead. + +### 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 label. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the label. **Double**. + +### UseMnemonic +{: .no_toc } + +Whether `&` in [**Caption**](#caption) marks the next character as a keyboard mnemonic. **Boolean**, default **True**. With **False**, ampersands are rendered verbatim. + +### VerticalAlignment +{: .no_toc } + +The vertical placement of the caption within the label's rectangle. A member of [**VerticalAlignmentConstants**](../../VBRUN/Constants/VerticalAlignmentConstants): **vbVerticalAlignTop** (0, default), **vbVerticalAlignMiddle** (1), or **vbVerticalAlignBottom** (2). + +### Visible +{: .no_toc } + +Whether the label is shown. **Boolean**, default **True**. + +### WhatsThisHelpID +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. See [**ShowWhatsThis**](#showwhatsthis). + +### Width +{: .no_toc } + +The control's width, in twips by default (or in the container's **ScaleMode** units). **Double**. Computed automatically while [**AutoSize**](#autosize) is **True**. + +### WordWrap +{: .no_toc } + +Whether the caption breaks into multiple lines at white-space when it would otherwise exceed [**Width**](#width). **Boolean**, default **False**. + +## Methods + +### Drag +{: .no_toc } + +Begins, completes, or cancels a manual VB-style drag operation. Distinct from OLE drag — see [**OLEDrag**](#oledrag). + +Syntax: *object*.**Drag** [ *Action* ] + +*Action* +: *optional* A member of [**DragConstants**](../../VBRUN/Constants/DragConstants): **vbCancel** (0), **vbBeginDrag** (1, default), or **vbEndDrag** (2). + +### LinkExecute +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently implemented in twinBASIC. + +Syntax: *object*.**LinkExecute** *Command* + +### LinkPoke +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently implemented in twinBASIC. + +Syntax: *object*.**LinkPoke** + +### LinkRequest +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently implemented in twinBASIC. + +Syntax: *object*.**LinkRequest** + +### LinkSend +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently implemented in twinBASIC. + +Syntax: *object*.**LinkSend** + +### Move +{: .no_toc } + +Repositions and optionally resizes the label 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 label, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject**. + +Syntax: *object*.**OLEDrag** + +### Refresh +{: .no_toc } + +Forces an immediate repaint of the label's rectangle on the parent's drawing surface. + +Syntax: *object*.**Refresh** + +### ShowWhatsThis +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +Syntax: *object*.**ShowWhatsThis** + +### ZOrder +{: .no_toc } + +Brings the label to the front or back of the windowless-sibling stack within its container. + +Syntax: *object*.**ZOrder** [ *Position* ] + +*Position* +: *optional* A member of [**ZOrderConstants**](../../VBRUN/Constants/ZOrderConstants): **vbBringToFront** (0, default) or **vbSendToBack** (1). + +## Events + +### Change +{: .no_toc } + +Raised when [**Caption**](#caption) is assigned a value that differs from its current contents. + +Syntax: *object*\_**Change**( ) + +### Click +{: .no_toc } + +Raised when the user single-clicks the label's rectangle. **Default event.** + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks the label's rectangle. + +Syntax: *object*\_**DblClick**( ) + +### DragDrop +{: .no_toc } + +Raised on the destination control when a manual VB-style 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 VB-style drag operation is in progress. + +Syntax: *object*\_**DragOver**( *Source* **As Control**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### Initialize +{: .no_toc } + +Raised once, after the label has been wired into its container's paint cycle but before it is first painted. Useful for last-minute setup that depends on container state. + +Syntax: *object*\_**Initialize**( ) + +### LinkClose +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently raised in twinBASIC. + +### LinkError +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently raised in twinBASIC. + +### LinkNotify +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently raised in twinBASIC. + +### LinkOpen +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently raised in twinBASIC. + +### MouseDown +{: .no_toc } + +Raised when the user presses any mouse button over the label. + +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 label. + +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 label. + +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** ) diff --git a/docs/Reference/VB/Line/index.md b/docs/Reference/VB/Line/index.md new file mode 100644 index 0000000..e113b25 --- /dev/null +++ b/docs/Reference/VB/Line/index.md @@ -0,0 +1,147 @@ +--- +title: Line +parent: VB Package +permalink: /tB/Packages/VB/Line/ +has_toc: false +--- + +# Line class +{: .no_toc } + +A **Line** is a windowless lightweight control that draws a single straight line segment from one point to another on its container. It exists purely for visual presentation — to divide regions of a form, underline a heading, draw a leader to an annotation — and has no interaction surface of its own: no mouse events, no focus, no caption. + +A **Line** is positioned by its two endpoints, [**X1**](#x1) / [**Y1**](#y1) and [**X2**](#x2) / [**Y2**](#y2), rather than by a `Left` / `Top` / `Width` / `Height` rectangle. The default property is [**Visible**](#visible) and the default event is [**Initialize**](#initialize). + +```tb +Private Sub Form_Load() + linUnderHeading.X1 = 120 : linUnderHeading.Y1 = 320 + linUnderHeading.X2 = 4800 : linUnderHeading.Y2 = 320 + linUnderHeading.BorderColor = vbBlue + linUnderHeading.BorderWidth = 2 +End Sub +``` + +* TOC +{:toc} + +## Endpoints + +[**X1**](#x1) / [**Y1**](#y1) is one endpoint of the line; [**X2**](#x2) / [**Y2**](#y2) is the other. Coordinates are in the container's **ScaleMode** units (twips by default) and are measured from the top-left corner of the container's client area. The line is drawn between the two points regardless of which is "earlier" — swapping the endpoints does not change the result. + +The control has no `Width` or `Height` of its own; the bounding rectangle is derived from the two endpoints. Resizing a **Line** at design time moves whichever endpoint is being dragged. + +## Pen + +The line is drawn with a Win32 GDI pen whose appearance is controlled by: + +- [**BorderColor**](#bordercolor) — the colour of the pen (defaults to the system window-text colour). +- [**BorderWidth**](#borderwidth) — the pen width in pixels (default `1`). +- [**BorderStyle**](#borderstyle) — the pen pattern, as a member of [**BorderStyleConstants**](../../VBRUN/Constants/BorderStyleConstants): **vbTransparent** (0), **vbBSSolid** (1, default), **vbBSDash** (2), **vbBSDot** (3), **vbBSDashDot** (4), **vbBSDashDotDot** (5), or **vbBSInsideSolid** (6). + +GDI applies a hard limitation here: when [**BorderWidth**](#borderwidth) is greater than `1`, the OS forces a solid pen even if [**BorderStyle**](#borderstyle) requests a dashed or dotted pattern. Use width `1` if the pattern matters. + +## Draw mode + +[**DrawMode**](#drawmode) selects the raster operation that combines the pen with the destination pixels. A member of [**DrawModeConstants**](../../VBRUN/Constants/DrawModeConstants): **vbCopyPen** (default — opaque drawing) or one of the XOR / AND / NOT / merge variants. Non-default modes are mainly useful for "rubber-band" feedback drawn over an existing background — the same XOR you draw twice cancels itself out, restoring the original pixels. + +## No interaction surface + +Unlike most other controls, a **Line** does not raise mouse, keyboard, or focus events of any kind, and has no [**Caption**](/tB/Packages/VB/Label#caption), [**Enabled**](/tB/Packages/VB/Label#enabled), or **ToolTipText**. To make a region clickable, place a transparent [**Label**](../Label/) on top. + +## Properties + +### BorderColor +{: .no_toc } + +The colour of the line, as an **OLE_COLOR**. Defaults to the system window-text colour. + +### BorderStyle +{: .no_toc } + +The pen pattern. A member of [**BorderStyleConstants**](../../VBRUN/Constants/BorderStyleConstants): **vbTransparent** (0), **vbBSSolid** (1, default), **vbBSDash** (2), **vbBSDot** (3), **vbBSDashDot** (4), **vbBSDashDotDot** (5), or **vbBSInsideSolid** (6). Forced to **vbBSSolid** by Win32 whenever [**BorderWidth**](#borderwidth) is greater than `1`. + +### BorderWidth +{: .no_toc } + +The pen width, in pixels. **Long**, default `1`. Widths greater than `1` ignore [**BorderStyle**](#borderstyle) and always draw solid. + +### Container +{: .no_toc } + +The control that hosts this line — typically the form, a [**Frame**](../Frame/), or a **UserControl**. Read with **Get**, change with **Set**. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control. The **Line** shares the **vbShape** constant with the [**Shape**](../Shape) control — both are windowless, points-based geometric primitives with no dedicated control-type identifier. + +### DrawMode +{: .no_toc } + +The raster operation that the line drawing applies when combining the pen with the destination. A member of [**DrawModeConstants**](../../VBRUN/Constants/DrawModeConstants): **vbCopyPen** (default) is normal opaque drawing; other values produce XOR, AND, NOT, and other pixel-mixing effects. + +### Index +{: .no_toc } + +When the line 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. + +### Name +{: .no_toc } + +The unique design-time name of the control on its parent. Read-only at run time. + +### Parent +{: .no_toc } + +A reference to the [**Form**](../Form/) (or **UserControl**) that ultimately contains the line. Read-only. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the line. Ignored by the framework. + +### Visible +{: .no_toc } + +Whether the line is shown. **Boolean**, default **True**. **Default property.** + +### X1 +{: .no_toc } + +The horizontal position of the first endpoint, in the container's **ScaleMode** units. **Double**. + +### X2 +{: .no_toc } + +The horizontal position of the second endpoint, in the container's **ScaleMode** units. **Double**. + +### Y1 +{: .no_toc } + +The vertical position of the first endpoint, in the container's **ScaleMode** units. **Double**. + +### Y2 +{: .no_toc } + +The vertical position of the second endpoint, in the container's **ScaleMode** units. **Double**. + +## Methods + +### ZOrder +{: .no_toc } + +Brings the line to the front or back of the windowless-sibling stack within its 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 line has been wired into its container's paint cycle but before it is first painted. **Default event.** + +Syntax: *object*\_**Initialize**( ) diff --git a/docs/Reference/VB/ListBox/index.md b/docs/Reference/VB/ListBox/index.md new file mode 100644 index 0000000..12ca6ab --- /dev/null +++ b/docs/Reference/VB/ListBox/index.md @@ -0,0 +1,694 @@ +--- +title: ListBox +parent: VB Package +permalink: /tB/Packages/VB/ListBox/ +has_toc: false +--- + +# ListBox class +{: .no_toc } + +A **ListBox** is a Win32 native control that displays a vertically-scrolling list of items, optionally laid out in multiple columns, from which the user picks one item — or any number of items, when [**MultiSelect**](#multiselect) is non-zero. Each item is a string, with an optional **LongPtr** value the application can store alongside it through [**ItemData**](#itemdata). The control is normally placed on a **Form** or **UserControl** at design time. The default property is [**Text**](#text) and the default event is [**Click**](#click). + +```tb +Private Sub Form_Load() + With List1 + .AddItem "Apple" + .AddItem "Banana" + .AddItem "Cherry" + .ItemData(0) = 100 + .ItemData(1) = 200 + .ItemData(2) = 300 + .ListIndex = 0 + End With +End Sub + +Private Sub List1_Click() + Debug.Print "Picked: " & List1.Text & " (data = " & List1.ItemData(List1.ListIndex) & ")" +End Sub +``` + +* TOC +{:toc} + +## Style + +[**Style**](#style) selects one of three rendering modes ([**ListBoxConstants**](../../VBRUN/Constants/ListBoxConstants)): + +| Constant | Value | Layout | +|---------------------------|-------|----------------------------------------------------------------------------------------------| +| **vbListBoxStandard** | 0 | Plain text items, the default. | +| **vbListBoxCheckbox** | 1 | Each item shows an independent check box that the user can toggle without changing the selection. | +| **vbListBoxColorSwatch** | 2 | Each item shows a colour swatch in front of its text, drawn in the colour stored in [**ItemData**](#itemdata). | + +Changing **Style** at run time recreates the underlying window, preserving the items, [**ItemData**](#itemdata) values, current selection, scroll position, and (in checkbox mode) check states. [**Sorted**](#sorted), [**MultiSelect**](#multiselect), [**IntegralHeight**](#integralheight), and [**UseTabStops**](#usetabstops) recreate the window the same way. + +[**MultiSelect**](#multiselect) is meaningful only with **vbListBoxStandard**. The other styles always behave as if **MultiSelect** were **vbMultiSelectNone** — the per-item toggle of **vbListBoxCheckbox** replaces the multi-selection feature, and the colour swatch is purely a display variant. + +## Editing the list + +Items are held inside the OS list-box control; the [**List**](#list) and [**ItemData**](#itemdata) arrays are projections onto that storage. Items are added with [**AddItem**](#additem), removed with [**RemoveItem**](#removeitem), and the whole list is cleared with [**Clear**](#clear). After each [**AddItem**](#additem) call, [**NewIndex**](#newindex) reports the position the item was inserted at — useful when [**Sorted**](#sorted) is **True** and the position is not predictable from the call. + +```tb +List1.Sorted = True +List1.AddItem "Cherry" +List1.AddItem "Apple" ' Inserted at index 0 — List1.NewIndex = 0 +List1.ItemData(List1.NewIndex) = 42 +``` + +Indexing past the end of the list raises run-time error 5 (*Invalid procedure call or argument*). Out of range or otherwise rejected calls to [**AddItem**](#additem) and [**RemoveItem**](#removeitem) raise the same error. + +## Selection + +[**ListIndex**](#listindex) is the zero-based index of the focused item, or `-1` when nothing is focused. [**Text**](#text) returns the text at that index. In single-select mode (**vbMultiSelectNone**) the focused item is also the selected item, and assigning to [**ListIndex**](#listindex) selects it and raises [**Click**](#click) if the value actually changes. In **vbMultiSelectSimple** and **vbMultiSelectExtended** the focused item is independent of the selection set; use [**Selected**](#selected) to read or write the selection state of any individual item, and [**SelCount**](#selcount) to count them. [**SelectedIndices**](#selectedindices) returns the selected indices as a **Collection** for convenient iteration. + +```tb +Dim idx As Variant +For Each idx In List1.SelectedIndices() + Debug.Print List1.List(idx) +Next +``` + +Assigning a string to [**Text**](#text) searches the list with an exact, case-insensitive match (using `LB_FINDSTRINGEXACT`) and selects that entry if found; if no entry matches, [**ListIndex**](#listindex) is set to `-1` and the current selection is cleared. Reading [**Text**](#text) when [**ListIndex**](#listindex) is `-1` raises run-time error 5. + +## Multi-column display + +When [**Columns**](#columns) is greater than zero, the OS lays the items out in that many side-by-side columns and gives the control a horizontal scroll bar instead of the usual vertical one. The column width is automatically set to the control's pixel width divided by [**Columns**](#columns) — assigning a new [**Width**](#width) does not re-divide the columns; you must reassign [**Columns**](#columns) to refresh the layout. + +The single-column / multi-column distinction is fixed at the moment the underlying window is created. At run time, [**Columns**](#columns) can be raised or lowered between non-zero values to re-divide the same control, but switching between zero and non-zero raises run-time error 380 (*Invalid property value*). Set [**Columns**](#columns) to its desired non-zero value at design time when a multi-column layout is wanted. + +## Checkbox style + +In **vbListBoxCheckbox** mode each item draws a small check box in front of its text, sized from [**MaxCheckboxSize**](#maxcheckboxsize) (in pixels at 96 DPI; scaled by the system DPI). The user toggles a check box by clicking it, by clicking the item and pressing **Space**, or by clicking the item itself when it is already the focused item. Each toggle raises [**ItemCheck**](#itemcheck) with the affected index. [**Selected**](#selected) reads or writes the per-item check state in this mode (instead of the selection state). The focused item is still tracked through [**ListIndex**](#listindex), and the standard [**Click**](#click) event still fires when the focus moves between items. + +The check states are kept in an internal array that is preserved across [**AddItem**](#additem) and [**RemoveItem**](#removeitem) calls (existing items keep their state; new items start unchecked). + +## Data binding + +Setting [**DataSource**](#datasource) and [**DataField**](#datafield) connects the control's [**Text**](#text) to a field of a [**Data**](../Data/) control's recordset. The bound field is read as a string on each move, and assigning to [**Text**](#text) marks the recordset as dirty by setting [**DataChanged**](#datachanged) to **True**. A field whose value cannot be coerced to a string is treated as an empty string rather than raising. + +## OLE drag and drop + +When [**OLEDragMode**](#oledragmode) is set to **vbOLEDragAutomatic**, dragging an item from the list starts an OLE drag whose **Text** data is either the dragged item's string (in single-select mode) or every selected item's text concatenated, separated by **vbCrLf** (in **vbMultiSelectSimple** or **vbMultiSelectExtended**). [**OLEDropMode**](#oledropmode) controls drop-target behaviour and is restricted to **vbOLEDropNone** or **vbOLEDropManual**. + +## Properties + +### Anchors +{: .no_toc } + +The set of edges of the parent that the list 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 control's border is drawn by the OS. A member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). Combined with [**BorderStyle**](#borderstyle): a 3-D appearance plus single border yields the standard sunken client edge; flat appearance plus single border yields a one-pixel outline. + +### BackColor +{: .no_toc } + +The background colour of the list area, as an **OLE_COLOR**. Defaults to the system window-background colour. Items drawn in the selected state ignore **BackColor** in favour of the system highlight colour. + +### BorderStyle +{: .no_toc } + +A member of [**ControlBorderStyleConstants**](../../VBRUN/Constants/ControlBorderStyleConstants): **vbNoBorder** (0) or **vbFixedSingleBorder** (1, default). Changing it at run time re-syncs the border without recreating the window. + +### CausesValidation +{: .no_toc } + +Determines whether the previously focused control's [**Validate**](#validate) event runs before this control receives the focus. **Boolean**, default **True**. + +### Columns +{: .no_toc } + +The number of columns in a multi-column layout, or `0` for a single-column list with a vertical scroll bar. **Long**, default `0`. See [Multi-column display](#multi-column-display). + +Syntax: *object*.**Columns** [ = *value* ] + +Switching between zero and non-zero at run time raises run-time error 380 (*Invalid property value*). Re-assigning between two non-zero values is allowed and re-divides the visible area. + +### Container +{: .no_toc } + +The control that hosts this list box — typically the form, a [**Frame**](../Frame/), or a **UserControl**. Read with **Get**, change with **Set**. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a list box. Always **vbListBox**. + +### DataChanged +{: .no_toc } + +Whether the bound [**Text**](#text) has been written to since the last save or refresh from the [**DataSource**](#datasource). **Boolean**. Setting **DataChanged** = **True** also marks the bound recordset as dirty. + +### DataField +{: .no_toc } + +The name of the field, in the recordset of the bound [**DataSource**](#datasource), whose value is mirrored by [**Text**](#text). **String**. + +### DataFormat +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### DataMember +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### 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 list box is docked within its container. A member of [**DockModeConstants**](../../VBRUN/Constants/DockModeConstants): **vbDockNone** (default), **vbDockLeft**, **vbDockTop**, **vbDockRight**, **vbDockBottom**, or **vbDockFill**. Docked list 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). + +### Enabled +{: .no_toc } + +Determines whether the control accepts user input. A disabled list box still shows its contents but is dimmed and ignores keyboard and mouse interaction. **Boolean**, default **True**. + +### Font +{: .no_toc } + +The **StdFont** used to render item text. The convenience properties **FontName**, **FontSize**, **FontBold**, **FontItalic**, **FontStrikethru**, and **FontUnderline** read or write the corresponding members of this object. Changing the font rescales each item's row height when [**IntegralHeight**](#integralheight) is **True**, and forces a recalculation of the row height in **vbListBoxCheckbox** and **vbListBoxColorSwatch** modes. + +### ForeColor +{: .no_toc } + +The text colour for entries that are not currently selected, as an **OLE_COLOR**. Defaults to the system window-text colour. Disabled entries draw in the system grey-text colour, and selected entries draw in the system highlight-text colour, regardless of this setting. + +### Height +{: .no_toc } + +The control's height, in twips by default (or in the container's **ScaleMode** units). When [**IntegralHeight**](#integralheight) is **True**, the OS quantises this on **Initialize** to a whole number of rows. **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 list box, 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. + +### IntegralHeight +{: .no_toc } + +When **True** (default), the OS adjusts the control's height so that the visible portion shows whole rows rather than partial ones. When **False**, the control honours [**Height**](#height) exactly and the bottom row may be clipped. **Boolean**. Changing this at run time recreates the underlying window. + +### ItemData +{: .no_toc } + +A **LongPtr** that the application can associate with each item. Indexed by the same zero-based position used by [**List**](#list). + +Syntax: *object*.**ItemData**( *Index* ) [ = *value* ] + +*Index* +: *required* A **Long** zero-based item position. + +In **vbListBoxColorSwatch** mode, **ItemData** is read by the painting code as the **OLE_COLOR** to draw in the swatch — a typical use is to fill it with a list of palette colours and let the user pick one. In the other styles **ItemData** is purely application-defined. + +```tb +List1.AddItem "Highlight" +List1.ItemData(List1.NewIndex) = vbYellow +``` + +Values stored at design time through the form designer are kept as **Long** rather than **LongPtr** so that designed forms remain platform-agnostic; at run time the property is **LongPtr**, sign-extending the design-time value where necessary. + +### Left +{: .no_toc } + +The horizontal distance from the left edge of the container to the left edge of the control. **Single**. + +### List +{: .no_toc } + +The text of an item, indexed by zero-based position. Setting **List(*Index*)** removes the existing item at that position and reinserts the new value at the same index — note that this can change the resulting position when [**Sorted**](#sorted) is **True**. + +Syntax: *object*.**List**( *Index* ) [ = *string* ] + +*Index* +: *required* A **Long** zero-based item position. Out-of-range indices raise run-time error 5. + +### ListCount +{: .no_toc } + +The number of items in the list, as a **Long**. Read-only. + +### ListIndex +{: .no_toc } + +The zero-based index of the focused item, or `-1` if no item is focused. **Long**. In multi-select modes the focused item and the selected items are independent — see [**Selected**](#selected). Assigning a value that differs from the current one focuses that item and raises [**Click**](#click). + +### MaxCheckboxSize +{: .no_toc } + +The maximum size of the per-item check box drawn in **vbListBoxCheckbox** mode, in pixels at 96 DPI. **Long**, default `15`. The actual size used is the smaller of this value (scaled by the system DPI) and the row height computed from the current font, so the box never exceeds a row. + +### 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). + +### MultiSelect +{: .no_toc } + +The selection mode. A member of [**MultiSelectConstants**](../../VBRUN/Constants/MultiSelectConstants): **vbMultiSelectNone** (0, default — single selection), **vbMultiSelectSimple** (1 — each click toggles), or **vbMultiSelectExtended** (2 — **Shift** for ranges, **Ctrl** for individual toggles). Changing this at run time recreates the underlying window; the items, [**ItemData**](#itemdata) values, focused item, and (in **vbListBoxCheckbox** mode) check states are restored, but multi-item selections are not. Effective only in **vbListBoxStandard** mode — see [Style](#style). + +### Name +{: .no_toc } + +The unique design-time name of the control on its parent form. Read-only at run time. + +### NewIndex +{: .no_toc } + +The zero-based index at which the most recent [**AddItem**](#additem) call inserted its item, or `-1` if no item has been added since the control was created. Particularly useful when [**Sorted**](#sorted) is **True** and the resulting position cannot be predicted from the call. **Long**, read-only. + +### OLEDragMode +{: .no_toc } + +Whether the control acts as an automatic OLE drag source. A member of [**OLEDragConstants**](../../VBRUN/Constants/OLEDragConstants): **vbOLEDragManual** (0, default — call [**OLEDrag**](#oledrag) from code) or **vbOLEDragAutomatic** (1 — dragging an item starts an OLE drag whose **Text** data is the dragged item's text in single-select mode, or every selected item's text separated by **vbCrLf** in multi-select mode). + +### 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 a ListBox. + +### 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 list box. Read-only. + +### RightToLeft +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### SelCount +{: .no_toc } + +The number of items currently selected, as a **Long**. Read-only. Always `0` or `1` when [**MultiSelect**](#multiselect) is **vbMultiSelectNone** or when [**Style**](#style) is non-standard. + +### Selected +{: .no_toc } + +The selection state of an individual item — or, in **vbListBoxCheckbox** mode, the check state. + +Syntax: *object*.**Selected**( *Index* ) [ = *boolean* ] + +*Index* +: *required* A **Long** zero-based item position. + +In **vbListBoxStandard** mode, reading **Selected(*Index*)** returns **True** when that item is selected, and assigning a value updates the selection. In single-select mode (**vbMultiSelectNone**), assigning **True** selects that item; assigning **False** has no observable effect. In multi-select modes, assignments toggle the corresponding item's membership in the selection set independently of the focused item. Each assignment that changes the state raises [**Click**](#click). + +In **vbListBoxCheckbox** mode, **Selected(*Index*)** reads or writes the per-item check state. Each assignment that changes the state raises [**ItemCheck**](#itemcheck). + +In **vbListBoxColorSwatch** mode, **Selected(*Index*)** behaves as in single-select standard mode (the swatch styling is purely a display variant). + +### Sorted +{: .no_toc } + +When **True**, items added with [**AddItem**](#additem) are inserted in alphabetical order regardless of the *Index* argument; when **False** (default), they are inserted at the requested position (or appended). **Boolean**. Changing this at run time recreates the underlying window with the existing items re-added. + +### Style +{: .no_toc } + +Selects one of the three rendering modes. A member of [**ListBoxConstants**](../../VBRUN/Constants/ListBoxConstants): **vbListBoxStandard** (0, default), **vbListBoxCheckbox** (1), or **vbListBoxColorSwatch** (2). See [Style](#style) above for the layout and behaviour differences. 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**. 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. + +### Text +{: .no_toc } + +The text of the focused item, or an empty string when [**ListIndex**](#listindex) is `-1`. **Default property.** + +Syntax: *object*.**Text** [ = *string* ] + +Reading **Text** returns `List(ListIndex)` — reading it when no item is focused raises run-time error 5 (*Invalid procedure call or argument*). Setting **Text** searches the list for an exact, case-insensitive match (using `LB_FINDSTRINGEXACT`) and selects the matching item if found; if no item matches, [**ListIndex**](#listindex) is set to `-1` and the current selection is cleared. + +### 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**. + +### TopIndex +{: .no_toc } + +The zero-based index of the item shown at the top of the visible area. **Long**. Assigning a value scrolls the list so that item is at the top; the [**Scroll**](#scroll) event is raised when the value actually changes. + +### 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. + +### UseTabStops +{: .no_toc } + +When **True** (default), `vbTab` characters embedded in item text are expanded to the OS's standard list-box tab stops, so multi-column-aligned text can be rendered in a single-column list. When **False**, tab characters are drawn literally. **Boolean**. Changing this at run time recreates the underlying window. + +### 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**, default **True**. Affects the rendering of the per-item check box in **vbListBoxCheckbox** mode (themed vs. classic flat-style box). + +### WhatsThisHelpID +{: .no_toc } + +A **Long** identifying a "What's This?" help-pop-up topic in the application's help file. See [**ShowWhatsThis**](#showwhatsthis). + +### WheelScrollEvent +{: .no_toc } + +When **True** (default), mouse-wheel notifications over the control raise the [**Scroll**](#scroll) event; when **False**, the wheel still scrolls the list but [**Scroll**](#scroll) is suppressed. **Boolean**. VB6 never raised **Scroll** for wheel events; set this to **False** to match that behaviour exactly. + +### Width +{: .no_toc } + +The control's width. **Single**. In a multi-column layout, also determines the column width — see [Multi-column display](#multi-column-display). + +## Methods + +### AddItem +{: .no_toc } + +Inserts a new item into the list and stores the resulting position in [**NewIndex**](#newindex). In **vbListBoxCheckbox** mode the new item is unchecked; existing items keep their check state. + +Syntax: *object*.**AddItem** *Value* [, *Index* ] + +*Value* +: *required* A **String** giving the text of the new item. + +*Index* +: *optional* A **Long** zero-based position to insert at. Omit to append to the end. Out-of-range indices raise run-time error 5. Ignored when [**Sorted**](#sorted) is **True**. + +### Clear +{: .no_toc } + +Removes every item from the list, including any associated [**ItemData**](#itemdata) values and check states. + +Syntax: *object*.**Clear** + +### 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** + +### RemoveItem +{: .no_toc } + +Removes the item at the given zero-based position, along with its [**ItemData**](#itemdata) value. Items below it shift up by one, and (in **vbListBoxCheckbox** mode) their check states shift up with them. + +Syntax: *object*.**RemoveItem** *Index* + +*Index* +: *required* A **Long** zero-based position. + +### SelectedIndices +{: .no_toc } + +Returns the zero-based indices of every currently-selected item as a **Collection** of **Long** values, in ascending order. Useful for iterating multi-selections without scanning [**Selected**](#selected) for every index. + +Syntax: *object*.**SelectedIndices** + +```tb +Dim idx As Variant +For Each idx In List1.SelectedIndices() + Debug.Print idx & ": " & List1.List(idx) +Next +``` + +### 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 after the focused item changes — whether the user clicked a different entry, used the keyboard to move the focus, or code assigned a different value to [**ListIndex**](#listindex) or [**Selected**](#selected). Also raised when the previously selected item is cancelled (`LBN_SELCANCEL`). **Default event.** + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks an entry. Typically used to act on the highlighted item — for example, opening it. + +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, immediately after the underlying window is created and the design-time items have been added. New in twinBASIC — VB6 had no equivalent on this control. + +Syntax: *object*\_**Initialize**( ) + +### ItemCheck +{: .no_toc } + +Raised in **vbListBoxCheckbox** mode each time the check state of an item changes — whether the user clicked its check box, pressed **Space**, or code assigned to [**Selected**](#selected). Not raised in the other styles. + +Syntax: *object*\_**ItemCheck**( *Item* **As Integer** ) + +*Item* +: The zero-based index of the toggled item. + +> [!NOTE] +> Items beyond index 32768 do not raise **ItemCheck** because the event signature uses **Integer**. Read [**Selected**](#selected) directly to inspect higher-indexed items. + +### 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. Fires whether the drag was initiated automatically (with [**OLEDragMode**](#oledragmode) set to **vbOLEDragAutomatic**) or by an explicit [**OLEDrag**](#oledrag) call. + +Syntax: *object*\_**OLEStartDrag**( *Data* **As DataObject**, *AllowedEffects* **As Long** ) + +### Scroll +{: .no_toc } + +Raised when the visible portion of the list scrolls — by the scroll bar, the keyboard, or (when [**WheelScrollEvent**](#wheelscrollevent) is **True**) the mouse wheel. The new offset can be read from [**TopIndex**](#topindex). + +Syntax: *object*\_**Scroll**( ) + +### 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/MDIForm/index.md b/docs/Reference/VB/MDIForm/index.md new file mode 100644 index 0000000..c8fedcb --- /dev/null +++ b/docs/Reference/VB/MDIForm/index.md @@ -0,0 +1,655 @@ +--- +title: MDIForm +parent: VB Package +permalink: /tB/Packages/VB/MDIForm/ +has_toc: false +--- + +# MDIForm class +{: .no_toc } + +An **MDIForm** is a top-level Win32 window that hosts an *MDI client area* — a recessed working surface in which one or more [**Form**](../Form/) instances marked as MDI children appear, each with its own caption bar inside the parent. A twinBASIC project may contain at most one MDI form. Unlike an ordinary [**Form**](../Form/), an MDIForm has no drawing surface, no font properties, and no graphics primitives — it is purely a frame for its children, plus a host for menus, toolbars, and (optionally) a single background [**Picture**](#picture) drawn behind the children. + +The default property is [**Controls**](#controls) and the default event is [**Load**](#load). + +```tb +' In MDIForm1's code-behind: +Private Sub MDIForm_Load() + Caption = "Editor" + AutoShowChildren = True +End Sub + +Private Sub mnuWindowCascade_Click() + Arrange vbCascade +End Sub + +' In a child form (Form1) marked MDIChild = True: +Private Sub Form_Load() + Caption = "Untitled" +End Sub + +' In a startup module: +Sub Main() + MDIForm1.Show + Form1.Show ' opens inside MDIForm1's client area +End Sub +``` + +* TOC +{:toc} + +## Lifecycle + +The MDIForm goes through the same six events as a regular [**Form**](../Form/) from creation to destruction: + +| Event | When | +|----------------------------------|-------------------------------------------------------------------------------------| +| [**Initialize**](#initialize) | Before the underlying window exists. The form's children and controls do not yet exist. | +| [**Load**](#load) | After the window has been created and the child controls (toolbar bands, status bars, menus) have been instantiated, before the form first appears. | +| [**Activate**](#activate) | When the MDI parent or one of its child forms becomes active. | +| [**Deactivate**](#deactivate) | When activation moves to another window outside the MDI group. | +| [**QueryUnload**](#queryunload) | Before unload. Setting *Cancel* to non-zero keeps the form open. Closing the MDI parent first runs **QueryUnload** on every open MDI child, then on the parent itself. | +| [**Unload**](#unload) | After **QueryUnload** approves. Setting *Cancel* to non-zero keeps the form open. | +| [**Terminate**](#terminate) | After the window has been destroyed and the class instance is released. | + +## MDI children + +An MDI child is any [**Form**](../Form/) whose **MDIChild** property is **True** (set at design time). Showing or unhiding such a form parents it to the MDI client area: its [**Left**](../Form/#left) and [**Top**](../Form/#top) become relative to the client area's upper-left corner, its title bar is drawn inside the parent rather than on the desktop, and maximising it merges its system menu and minimise/maximise buttons into the parent's title bar. + +[**ActiveForm**](#activeform) returns the currently focused child, or **Nothing** when no child is open. [**Activate**](#activate) and [**Deactivate**](#deactivate) on the MDI parent fire only when activation crosses the MDI group's outer boundary; activation moves *within* the group fire **Activate** / **Deactivate** on the affected child forms instead. + +[**AutoShowChildren**](#autoshowchildren) decides what happens when an MDI child class is loaded but not explicitly shown — when **True** (default), the child is made visible automatically; when **False**, the child stays hidden until code calls **Show** on it. + +[**Arrange**](#arrange) lays the open children out in a single call: cascade, tile horizontally, tile vertically, or arrange the icons of minimised children along the bottom edge. + +```tb +mnuWindowCascade.Click => Me.Arrange vbCascade +mnuWindowTileH.Click => Me.Arrange vbTileHorizontal +mnuWindowTileV.Click => Me.Arrange vbTileVertical +mnuWindowArrangeIcons.Click => Me.Arrange vbArrangeIcons +``` + +## Window appearance + +An MDIForm always uses the sizable border style — there is no [**BorderStyle**](../Form/#borderstyle) property, the title bar is always present, the system menu and minimise / maximise buttons are always shown, and the form always appears in the taskbar. [**Caption**](#caption) sets the title-bar text. [**Icon**](#icon) supplies the small/large icon used by the system menu, the taskbar, and Alt-Tab. [**WindowState**](#windowstate) ([**FormWindowStateConstants**](../../VBRUN/Constants/FormWindowStateConstants)) reads or sets normal / minimised / maximised state at run time. + +[**MinWidth**](#minwidth), [**MinHeight**](#minheight), [**MaxWidth**](#maxwidth), and [**MaxHeight**](#maxheight) constrain the *client area* in twips during interactive resizing. [**Moveable**](#moveable) decides whether the user can drag the form by its title bar. + +[**Opacity**](#opacity) and [**TransparencyKey**](#transparencykey) drive Windows' layered-window features for translucent forms and cut-out shapes. + +[**BackColor**](#backcolor) paints the MDI client area's background — defaults to the system **vbApplicationWorkspace** colour rather than 3-D face. [**Picture**](#picture), when set, is drawn over **BackColor** as the client-area backdrop, scaled to fill the area for metafiles and centred at its natural size for bitmaps. [**PictureDpiScaling**](#picturedpiscaling) scales bitmaps by the current DPI factor before drawing. There is no on-screen drawing API on an MDIForm — the [**Cls**](../Form/#cls), [**Circle**](../Form/#circle), [**Line**](../Form/#line), [**PSet**](../Form/#pset), [**PaintPicture**](../Form/#paintpicture), and **Print** members of the **Form** interface raise run-time error 438 (*Object doesn't support this property or method*) when called on an MDIForm. + +A vertical and a horizontal scroll bar appear automatically when an MDI child is moved or sized so that its rectangle extends beyond the visible client area; this is fixed at design time through the **ScrollBars** property of the MDI parent and is not exposed at run time. + +## Menus and pop-ups + +Menu structures designed at form-design time appear automatically in the MDIForm's title bar. When an MDI child is maximised, the child's own menu (if any) is merged into the parent's menu bar, replacing it for as long as the child stays maximised. The classic VB6 *window-list* feature — a menu sub-tree that lists every open MDI child for quick switching — is supported automatically when a [**Menu**](../Menu) on the MDIForm has its **WindowList** property set. + +[**PopUpMenu**](#popupmenu) displays one of the form's menus as a context-menu pop-up at a specified location, raising the menu's **Click** event when the user picks an item. + +```tb +Private Sub MDIForm_MouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single) + If Button = vbRightButton Then PopUpMenu mnuContext +End Sub +``` + +## Differences from Form + +Because the MDIForm is a frame, not a drawing surface, the following members of the **Form** interface are *not* supported on it — accessing them raises run-time error 380 (properties) or 438 (methods): + +| Category | Members | +|------------------------------|--------------------------------------------------------------------------------------| +| Drawing | **AutoRedraw**, **ClipControls**, **HasDC**, **hDC**, **Image**, **CurrentX**, **CurrentY**, **DrawMode**, **DrawStyle**, **DrawWidth**, **FillColor**, **FillStyle**, **ForeColor**, **FontTransparent**, **Cls**, **Circle**, **Line**, **PSet**, **PaintPicture** | +| Font | **Font**, **FontName**, **FontSize**, **FontBold**, **FontItalic**, **FontStrikethru**, **FontUnderline**, **TextWidth** | +| Geometry | **ScaleLeft**, **ScaleTop**, **ScaleMode**, **Scale**, **ScaleX**, **ScaleY** ([**ScaleWidth**](#scalewidth) and [**ScaleHeight**](#scaleheight) are supported but read-only) | +| Window chrome | **BorderStyle**, **ControlBox**, **MaxButton**, **MinButton**, **ShowInTaskbar**, **WhatsThisButton** | +| Other | **KeyPreview** (and the [**Form**](../Form/)'s **KeyDown** / **KeyUp** / **KeyPress** events do not exist on **MDIForm**), **MDIChild**, **NegotiateMenus**, **Palette**, **PaletteMode**, **PrintForm**, **Point**, **Refresh** (raises 438 on an MDIForm even though it works on a regular Form) | +| Behaviour quirk | **TextHeight** returns `0` instead of raising. (VB6 bug retained for compatibility.) | + +## Properties + +### ActiveControl +{: .no_toc } + +The control on the active MDI child that currently has the input focus, as a **Control** object, or **Nothing** when no child is focused. Read-only. + +### ActiveForm +{: .no_toc } + +The currently active MDI child form, as an **Object**, or **Nothing** when no child is open. Read-only. Updated each time activation moves between children, just before the corresponding [**Activate**](#activate) and [**Deactivate**](#deactivate) events fire on the child forms. + +### AlwaysShowKeyboardCues +{: .no_toc } + +When **True**, the form always shows underlines on access-key characters in [**Caption**](#caption)s and menu items, instead of only displaying them after the user presses **Alt**. **Boolean**, read-only at run time. Set at design time. + +### Appearance +{: .no_toc } + +A member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). + +> [!NOTE] +> Retained for VB6 compatibility; the property has no observable effect on an MDI form. + +### AutoShowChildren +{: .no_toc } + +When **True** (default), loading an MDI child class also shows it; when **False**, child classes can be loaded into memory without becoming visible until code calls **Show** on them. **Boolean**. + +### BackColor +{: .no_toc } + +The colour painted in the MDI client area, as an **OLE_COLOR**. Defaults to the system **vbApplicationWorkspace** colour. Used as the canvas behind [**Picture**](#picture) and behind every MDI child's title bar and outer border. + +### Caption +{: .no_toc } + +The title-bar text. **String**. + +Syntax: *object*.**Caption** [ = *string* ] + +When an MDI child is maximised, Windows decorates **Caption** with the child's caption in square brackets — `Editor - [Untitled]` — and the application normally lets that decoration stay automatic by leaving **Caption** alone. + +### Controls +{: .no_toc } + +The collection of every control hosted by this form, indexable by control name or zero-based position. **Default property.** Read-only — controls are added to the collection by the runtime, not by user code. The collection contains the form's menus, toolbars, status bars, and any aligned controls; MDI children are *not* members of this collection (they are independent top-level forms hosted in the MDI client area, accessible through [**ActiveForm**](#activeform) and the runtime's **Forms** collection). + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a form. Always **vbForm**. + +### Count +{: .no_toc } + +The number of controls in [**Controls**](#controls), as a **Long**. Read-only. Equivalent to `Me.Controls.Count`. + +### DpiScaleFactorX +{: .no_toc } + +The horizontal DPI scale factor of the monitor the form is currently on, as a **Double**. `1.0` at 96 DPI, `1.25` at 120 DPI, `1.5` at 144 DPI, and so on. Read-only. + +### DpiScaleFactorY +{: .no_toc } + +The vertical DPI scale factor of the monitor the form is currently on. Currently always equal to [**DpiScaleFactorX**](#dpiscalefactorx). Read-only. + +### Enabled +{: .no_toc } + +Determines whether the form accepts user input. A disabled MDI parent ignores keyboard and mouse input, dims its title bar, and disables every open MDI child. **Boolean**, default **True**. + +### Height +{: .no_toc } + +The form's outer height, in twips (or in the calling code's **ScaleMode** units). **Double**. Constrained at run time by [**MinHeight**](#minheight) and [**MaxHeight**](#maxheight) when those are non-zero. + +### HelpContextID +{: .no_toc } + +A **Long** identifying a topic in the application's help file, retrieved when the user presses **F1** while the form has focus. + +### hWnd +{: .no_toc } + +The Win32 window handle for the MDI parent frame, as a **LongPtr**. Read-only. Useful for passing to API functions. The MDI client area is a separate child window with its own handle, accessible through Win32 calls only. + +### Icon +{: .no_toc } + +The icon shown on the title bar, in the taskbar, and in Alt-Tab. A **StdPicture** of type **vbPicTypeIcon**. Assigning a non-icon picture leaves the icon unchanged. + +### Left +{: .no_toc } + +The horizontal position of the form's outer rectangle, in twips (or the calling code's **ScaleMode** units), measured from the left edge of the screen. **Double**. + +### LinkMode +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently implemented in twinBASIC. + +### LinkTopic +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently implemented in twinBASIC. + +### MaxHeight +{: .no_toc } + +The maximum height of the form's *client area*, in twips. **Double**, default `0` (no limit). Honoured during interactive resizing. + +### MaxWidth +{: .no_toc } + +The maximum width of the form's *client area*, in twips. **Double**, default `0` (no limit). Honoured during interactive resizing. + +### MinHeight +{: .no_toc } + +The minimum height of the form's *client area*, in twips. **Double**, default `0` (no limit). Honoured during interactive resizing. + +### MinWidth +{: .no_toc } + +The minimum width of the form's *client area*, in twips. **Double**, default `0` (no limit). Honoured during interactive resizing. + +### MouseIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor when [**MousePointer**](#mousepointer) is **vbCustom** and the pointer is over the form's frame or client area (and not over a child form's own surface). + +### MousePointer +{: .no_toc } + +The mouse cursor shown when the pointer is over the form's frame or client area. A member of [**MousePointerConstants**](../../VBRUN/Constants/MousePointerConstants). + +### Moveable +{: .no_toc } + +Whether the user can drag the form by its title bar. **Boolean**, default **True**. + +### Name +{: .no_toc } + +The unique design-time name of the form. Read-only at run time. Also the class name of the generated form class. + +### NegotiateToolbars +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's ActiveX-document menu negotiation feature; not currently implemented in twinBASIC. + +### OLEDropMode +{: .no_toc } + +How the form responds to OLE drops over its frame and client area. A restricted member of [**OLEDropConstants**](../../VBRUN/Constants/OLEDropConstants): **vbOLEDropNone** or **vbOLEDropManual**. Automatic-drop mode is not supported on an MDIForm. + +### Opacity +{: .no_toc } + +The form's opacity as a percentage (0–100, default 100). Values outside the range are clamped on **Initialize**. Values below 100 cause the form to become a layered window; the open MDI children become translucent along with the parent. + +### Picture +{: .no_toc } + +A **StdPicture** drawn as the MDI client area's background. Painted over [**BackColor**](#backcolor), behind every MDI child. Bitmaps are drawn at their natural size from the upper-left corner; metafiles are stretched to fill the entire client area. Assigning **Nothing** removes the background. + +### PictureDpiScaling +{: .no_toc } + +When **True**, [**Picture**](#picture) is scaled by the current DPI factor before drawing. **Boolean**, default **False**. Has no effect on metafile pictures (they are stretched regardless). + +### RightToLeft +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### ScaleHeight +{: .no_toc } + +The height of the MDI *client area* (the inset region that hosts the children), in twips. **Double**, read-only — assigning to it raises run-time error 383 (*'ScaleHeight' property is read-only*). + +### ScaleWidth +{: .no_toc } + +The width of the MDI *client area*, in twips. **Double**, read-only — assigning to it raises run-time error 383. + +### StartUpPosition +{: .no_toc } + +How the form's initial position is determined the first time it is shown. A member of [**StartUpPositionConstants**](../../VBRUN/Constants/StartUpPositionConstants): **vbStartUpManual**, **vbStartUpOwner**, **vbStartUpScreen**, or **vbStartUpWindowsDefault** (default). Read-only at run time — set at design time. + +### TabFocusAutoSelect +{: .no_toc } + +When **True**, a [**TextBox**](../TextBox) on this form (or on any of its MDI children) whose own **TabFocusAutoSelect** is also **True** auto-selects its content when the focus enters it via the **TAB** key. **Boolean**, default **False**. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the form. Ignored by the framework. + +### Top +{: .no_toc } + +The vertical position of the form's outer rectangle, in twips (or the calling code's **ScaleMode** units), measured from the top edge of the screen. **Double**. + +### TopMost +{: .no_toc } + +Whether the form sits in the always-on-top z-order layer. **Boolean**, read-only at run time. Set at design time. + +### TransparencyKey +{: .no_toc } + +An **OLE_COLOR** that, when set, becomes fully transparent in the rendered form — clicks pass through to whatever is underneath, and the corresponding pixels do not paint. Default `-1` disables the effect. + +### Visible +{: .no_toc } + +Whether the form is shown. **Boolean**, default **True**. Setting **Visible** to **True** when the form was hidden is equivalent to calling [**Show**](#show) **vbModeless**; setting it to **False** is equivalent to calling [**Hide**](#hide). MDI children remain bound to the parent regardless of visibility — hiding the parent hides every child as well. + +### WhatsThisHelp +{: .no_toc } + +When **True**, [**WhatsThisMode**](#whatsthismode) enters Windows' "What's This?" cursor mode. **Boolean**, default **False**. The title-bar help-button feature is not available on an MDIForm. + +### Width +{: .no_toc } + +The form's outer width, in twips (or in the calling code's **ScaleMode** units). **Double**. Constrained at run time by [**MinWidth**](#minwidth) and [**MaxWidth**](#maxwidth) when those are non-zero. + +### WindowState +{: .no_toc } + +The window's normal/minimised/maximised state. A member of [**FormWindowStateConstants**](../../VBRUN/Constants/FormWindowStateConstants): **vbNormal** (0, default), **vbMinimized** (1), or **vbMaximized** (2). Setting it at run time updates the window placement immediately if the form is visible. + +## Methods + +### Arrange +{: .no_toc } + +Lays the open MDI children out in a single call. + +Syntax: *object*.**Arrange** *Arrangement* + +*Arrangement* +: *required* A member of [**FormArrangeConstants**](../../VBRUN/Constants/FormArrangeConstants): **vbCascade** (0), **vbTileHorizontal** (1), **vbTileVertical** (2), or **vbArrangeIcons** (3 — line up the icons of minimised children along the bottom of the client area). Other values raise run-time error 5 (*Invalid procedure call or argument*). + +### Close +{: .no_toc } + +Initiates the form's unload sequence — [**QueryUnload**](#queryunload), then [**Unload**](#unload), then [**Terminate**](#terminate) — preceded by the same sequence on every open MDI child. Either of the first two events on either the parent or any child can cancel the close by setting *Cancel* to non-zero. Equivalent to the language statement `Unload Me`. + +Syntax: *object*.**Close** + +### Hide +{: .no_toc } + +Hides the form without unloading it. The class instance, its children, and its controls are preserved; calling [**Show**](#show) (or assigning [**Visible**](#visible) = **True**) brings it back. Equivalent to assigning **Visible** = **False**. + +Syntax: *object*.**Hide** + +### Move +{: .no_toc } + +Repositions and optionally resizes the form 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 form, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject**. + +Syntax: *object*.**OLEDrag** + +### PopUpMenu +{: .no_toc } + +Displays a [**Menu**](../Menu) as a context-menu pop-up at the specified location. + +Syntax: *object*.**PopUpMenu** *Menu* [, *Flags* [, *X* [, *Y* [, *DefaultMenu* ] ] ] ] + +*Menu* +: *required* The **Menu** control to display. The menu must already exist on the form. + +*Flags* +: *optional* A combination of [**MenuControlConstants**](../../VBRUN/Constants/MenuControlConstants) controlling alignment and which mouse buttons trigger the menu items. + +*X*, *Y* +: *optional* The screen-relative position to anchor the menu at, in twips. Defaults to the current mouse position. + +*DefaultMenu* +: *optional* The **Menu** sub-item to render in bold as the default action. + +### SetFocus +{: .no_toc } + +Activates the form. If an MDI child is open, focus moves to whichever control on that child last held it; otherwise focus moves to the parent's frame. + +Syntax: *object*.**SetFocus** + +### Show +{: .no_toc } + +Makes the form visible. Triggers [**Load**](#load) on the first call. + +Syntax: *object*.**Show** [ *Modal* [, *OwnerForm* ] ] + +*Modal* +: *optional* A member of [**FormShowConstants**](../../VBRUN/Constants/FormShowConstants): **vbModeless** (0, default — the call returns immediately) or **vbModal** (1). MDI parents are normally shown modeless; modal display is accepted but unusual. + +*OwnerForm* +: *optional* For modal shows, the form that is disabled while this form is up; defaults to the currently active form. + +### ValidateControls +{: .no_toc } + +Fires the **Validate** event of the currently active control on the active MDI child. If the handler sets *Cancel* to **True**, **ValidateControls** raises run-time error 380 (*Invalid property value*); the caller can wrap this with `On Error` to detect a failed validation. + +Syntax: *object*.**ValidateControls** + +### WhatsThisMode +{: .no_toc } + +Enters Windows' "What's This?" cursor mode — the next click on a control raises that control's help instead of activating it. [**WhatsThisHelp**](#whatsthishelp) must be **True**. + +Syntax: *object*.**WhatsThisMode** + +### ZOrder +{: .no_toc } + +Brings the form to the front or back of the top-level z-order. + +Syntax: *object*.**ZOrder** [ *Position* ] + +*Position* +: *optional* A member of [**ZOrderConstants**](../../VBRUN/Constants/ZOrderConstants): **vbBringToFront** (0, default) or **vbSendToBack** (1). + +## Events + +### Activate +{: .no_toc } + +Raised when the MDI parent or any of its child forms becomes the active window in the application — typically right after [**Load**](#load) for the first show, and whenever activation returns to the MDI group from another window. + +Syntax: *object*\_**Activate**( ) + +### Click +{: .no_toc } + +Raised when the user single-clicks the MDI parent's frame area (i.e. the title bar's hit-test area or directly on the client-area background, with no MDI child covering the spot). + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks the MDI parent's frame area. + +Syntax: *object*\_**DblClick**( ) + +### Deactivate +{: .no_toc } + +Raised when the MDI parent loses activation to another window outside the MDI group. Activation moving between the parent and its own children does not raise **Deactivate** on the parent. + +Syntax: *object*\_**Deactivate**( ) + +### DPIChange +{: .no_toc } + +Raised when the form moves to a monitor with a different DPI scale, *but only* when the application is per-monitor DPI aware (`PROCESS_PER_MONITOR_DPI_AWARE`). The event's *NewDPI* argument carries the new effective DPI; child controls and MDI children re-scale themselves automatically. New in twinBASIC. + +Syntax: *object*\_**DPIChange**( *NewDPI* **As Long** ) + +### 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** ) + +### Initialize +{: .no_toc } + +Raised once, before the underlying window is created and before any of the form's child controls (or MDI children) exist. Useful for setting initial values on form-level fields. The form's controls cannot be referenced from this event. + +Syntax: *object*\_**Initialize**( ) + +### LinkClose +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently raised in twinBASIC. + +### LinkError +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently raised in twinBASIC. + +### LinkExecute +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently raised in twinBASIC. + +### LinkOpen +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's DDE feature; not currently raised in twinBASIC. + +### Load +{: .no_toc } + +Raised after the MDI parent's window and all aligned child controls (toolbars, status bars, menus) have been created, just before the form first appears on screen. The classic place to populate menus dynamically and perform any initialisation that needs the controls to exist. **Default event.** + +Syntax: *object*\_**Load**( ) + +### MouseDown +{: .no_toc } + +Raised when the user presses any mouse button over the MDI parent's client area (i.e. not over an MDI child). + +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 MDI parent's client area. + +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 MDI parent's client area. + +Syntax: *object*\_**MouseUp**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseWheel +{: .no_toc } + +Raised when the mouse wheel turns over the MDI parent's client area. New in twinBASIC. + +Syntax: *object*\_**MouseWheel**( *Delta* **As Integer**, *Horizontal* **As Boolean** ) + +### 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** ) + +### QueryUnload +{: .no_toc } + +Raised before the form unloads, giving the application a chance to confirm or cancel the close. Setting *Cancel* to non-zero keeps the form (and all its open MDI children) open. When the MDI parent is closing, **QueryUnload** is raised on every open MDI child *before* it is raised on the parent — any child cancelling stops the cascade. + +Syntax: *object*\_**QueryUnload**( *Cancel* **As Integer**, *UnloadMode* **As Integer** ) + +*Cancel* +: Set to non-zero (any non-zero value, conventionally **1**) to cancel the close. + +*UnloadMode* +: A member of [**QueryUnloadConstants**](../../VBRUN/Constants/QueryUnloadConstants) identifying what triggered the close — the close button, code, Windows shutdown, or the MDI parent closing. + +### Resize +{: .no_toc } + +Raised when the MDI parent is resized — by the user, by code, by the OS following a [**WindowState**](#windowstate) change, or by initial layout during the first show. The event fires on the parent only; MDI children receive their own **Resize** events when the client-area resize cascades to them. + +Syntax: *object*\_**Resize**( ) + +### Terminate +{: .no_toc } + +Raised after the form's window has been destroyed and the class instance is about to be released. The controls and MDI children are no longer accessible at this point. + +Syntax: *object*\_**Terminate**( ) + +### Unload +{: .no_toc } + +Raised after [**QueryUnload**](#queryunload) approves and before the form's window is destroyed. Setting *Cancel* to non-zero keeps the form open and prevents the unload. + +Syntax: *object*\_**Unload**( *Cancel* **As Integer** ) + +*Cancel* +: Set to non-zero (any non-zero value, conventionally **1**) to cancel the unload. diff --git a/docs/Reference/VB/todo.md b/docs/Reference/VB/todo.md index ddb0926..c78aff0 100644 --- a/docs/Reference/VB/todo.md +++ b/docs/Reference/VB/todo.md @@ -3,9 +3,13 @@ title: General TODO List for /tB/Packages/VB/ nav_exclude: true redirect_from: - /tB/Packages/VB/DriveListBox - - /tB/Packages/VB/MDIForm - - /tB/Packages/VB/Printer - /tB/Packages/VB/Menu + - /tB/Packages/VB/OptionButton + - /tB/Packages/VB/PictureBox + - /tB/Packages/VB/Printer + - /tB/Packages/VB/Report + - /tB/Packages/VB/Shape + - /tB/Packages/VB/VScrollBar --- > [!WARNING]