diff --git a/docs/Reference/AppGlobalClassProject/App/index.md b/docs/Reference/AppGlobalClassProject/App/index.md new file mode 100644 index 0000000..2b0b5b2 --- /dev/null +++ b/docs/Reference/AppGlobalClassProject/App/index.md @@ -0,0 +1,12 @@ +--- +nav_exclude: true +#parent: AppGlobalClassProject Package +permalink: /tB/Packages/AppGlobalClassProject/App +--- + +> [!WARNING] +> +> Pardon, we have not documented this class yet. + +# Path + diff --git a/docs/Reference/AppGlobalClassProject/index.md b/docs/Reference/AppGlobalClassProject/index.md new file mode 100644 index 0000000..3a85200 --- /dev/null +++ b/docs/Reference/AppGlobalClassProject/index.md @@ -0,0 +1,10 @@ +--- +title: AppGlobalClassProject Package +parent: Reference Section +permalink: /tB/Packages/AppGlobalClassProject +nav_order: 20 +--- + +# AppGlobalClassProject Package + +This package exposes the global `App` object. diff --git a/docs/Reference/AppGlobalClassProject/todo.md b/docs/Reference/AppGlobalClassProject/todo.md new file mode 100644 index 0000000..98d1372 --- /dev/null +++ b/docs/Reference/AppGlobalClassProject/todo.md @@ -0,0 +1,12 @@ +--- +title: General TODO List for /tB/Packages/AppGlobalClassProject/ +nav_exclude: true +redirect_from: +--- + +> [!WARNING] +> +> Pardon, we have not documented this class yet. + + + diff --git a/docs/Reference/Attributes.md b/docs/Reference/Attributes.md index 9f893d9..6ff5a74 100644 --- a/docs/Reference/Attributes.md +++ b/docs/Reference/Attributes.md @@ -1,6 +1,7 @@ --- title: Attributes parent: Reference Section +nav_order: 6 permalink: /tB/Core/Attributes --- diff --git a/docs/Reference/Controls.md b/docs/Reference/Controls.md index 553ce9b..24ebda5 100644 --- a/docs/Reference/Controls.md +++ b/docs/Reference/Controls.md @@ -1,6 +1,7 @@ --- title: Controls parent: Reference Section +nav_order: 7 permalink: /tB/Controls --- diff --git a/docs/Reference/Glossary.md b/docs/Reference/Glossary.md index 4b7e7ff..7171ae2 100644 --- a/docs/Reference/Glossary.md +++ b/docs/Reference/Glossary.md @@ -1,6 +1,7 @@ --- title: Glossary parent: Reference Section +nav_order: 99 permalink: /tB/Gloss --- diff --git a/docs/Reference/VB/CheckBox/index.md b/docs/Reference/VB/CheckBox/index.md new file mode 100644 index 0000000..fbe4cf1 --- /dev/null +++ b/docs/Reference/VB/CheckBox/index.md @@ -0,0 +1,496 @@ +--- +title: CheckBox +parent: VB Package +permalink: /tB/Packages/VB/CheckBox +has_toc: false +--- + +# CheckBox class +{: .no_toc } + +A **CheckBox** is a Win32 native control that displays a small box, optionally followed by a text caption, used to give the user a choice between two values such as *Yes*/*No*, *True*/*False*, or *On*/*Off*. It can also be put into a third, indeterminate (grey) state from code, typically to mean "not applicable" or "mixed". + +The control is normally placed on a **Form** or **UserControl** at design time. The default property is [**Value**](#value) and the default event is [**Click**](#click). + +```tb +Private Sub Form_Load() + Check1.Caption = "I &agree to the terms" + Check1.Value = vbUnchecked +End Sub + +Private Sub Check1_Click() + cmdContinue.Enabled = (Check1.Value = vbChecked) +End Sub +``` + +* TOC +{:toc} + +## Three-state behaviour + +[**Value**](#value) is typed as [**CheckBoxConstants**](../VBRUN/Constants/CheckBoxConstants): + +| Constant | Value | Meaning | +|------------------|-------|--------------------------------------------------------| +| **vbUnchecked** | 0 | The check box is cleared. | +| **vbChecked** | 1 | The check box is selected. | +| **vbGrayed** | 2 | The check box is in an indeterminate (grey) state. | + +Clicking an unchecked or grey check box selects it; clicking a checked or grey check box clears it. The grey state is reachable only from code — assign **vbGrayed** to **Value** to display it. Assigning a negative number raises run-time error 380 (*Invalid property value*). + +```tb +Check1.Value = vbGrayed ' show the indeterminate state +``` + +## Caption and mnemonics + +The text shown next to (or, with [**Alignment**](#alignment) `tbRightJustify`, before) the box comes from [**Caption**](#caption). An ampersand in the caption marks the next character as a keyboard mnemonic: pressing **Alt+** that character moves the focus to the check box and toggles its value. Use `&&` to display a literal ampersand. + +```tb +Check1.Caption = "Use && in folder names" ' renders as: Use & in folder names +``` + +## Graphical style + +When [**Style**](#style) is **vbButtonGraphical**, the check box is owner-drawn and displays the bitmaps assigned to [**Picture**](#picture), [**DownPicture**](#downpicture), and [**DisabledPicture**](#disabledpicture) instead of the standard square. [**PictureAlignment**](#picturealignment), [**Padding**](#padding), and [**PictureDpiScaling**](#picturedpiscaling) control how the picture is positioned relative to the caption. + +## Data binding + +Setting [**DataSource**](#datasource) and [**DataField**](#datafield) connects the control's [**Value**](#value) to a field of a **Data** control's recordset. The bound field is read as a **Boolean**: a non-zero/`True` value sets [**Value**](#value) to **vbChecked**, zero/`False` sets it to **vbUnchecked**. Assigning a non-Boolean field value raises run-time error 13 (*Type mismatch*). + +## Properties + +### Alignment +{: .no_toc } + +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). + +### Appearance +{: .no_toc } + +Determines how the control's border is drawn by the OS. A member of [**AppearanceConstants**](../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). + +### BackColor +{: .no_toc } + +The background colour, as an **OLE_COLOR**. Defaults to the system 3-D face colour. + +### Caption +{: .no_toc } + +The text displayed next to the check box. An ampersand marks the next character as a mnemonic; `&&` produces a literal ampersand. The string is read directly from the underlying window — assigning to **Caption** is reflected immediately. + +Syntax: *object*.**Caption** [ = *string* ] + +### CausesValidation +{: .no_toc } + +Determines whether the previously focused control's [**Validate**](#validate) event runs before this control receives the focus. **Boolean**, default **True**. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../VBRUN/Constants/ControlTypeConstants) value identifying this control as a check box. Always **vbCheckBox**. + +### DataField +{: .no_toc } + +The name of the field, in the recordset of the bound [**DataSource**](#datasource), whose value is mirrored by [**Value**](#value). **String**. + +### DataSource +{: .no_toc } + +A reference to a **Data** control (or other **DataSource** provider) whose recordset supplies the value for [**DataField**](#datafield). Set with **Set**. + +### DisabledPicture +{: .no_toc } + +A **StdPicture** drawn instead of [**Picture**](#picture) when the control is disabled and [**Style**](#style) is **vbButtonGraphical**. + +### DownPicture +{: .no_toc } + +A **StdPicture** drawn instead of [**Picture**](#picture) while the control is in the depressed state, when [**Style**](#style) is **vbButtonGraphical**. + +### DragIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor while the control is being drag-and-dropped (see [**Drag**](#drag) and [**DragMode**](#dragmode)). + +### DragMode +{: .no_toc } + +Whether the control should drag itself when the user holds the mouse over it. A member of [**DragModeConstants**](../VBRUN/Constants/DragModeConstants): **vbManual** (0, default — call [**Drag**](#drag) from code) or **vbAutomatic** (1). + +### Enabled +{: .no_toc } + +Determines whether the control accepts user input. A disabled check box shows its current value but is dimmed and ignores keyboard and mouse interaction. **Boolean**, default **True**. + +### Font +{: .no_toc } + +The **StdFont** used to render [**Caption**](#caption). The convenience properties **FontName**, **FontSize**, **FontBold**, **FontItalic**, **FontStrikethru**, and **FontUnderline** read or write the corresponding members of this object. + +### ForeColor +{: .no_toc } + +The text colour for the caption, as an **OLE_COLOR**. Defaults to the system button-text colour. + +### Height +{: .no_toc } + +The control's height, in twips by default (or in the container's **ScaleMode** units). **Single**. + +### HelpContextID +{: .no_toc } + +A **Long** identifying a topic in the application's help file, retrieved when the user presses **F1** while the control has focus. + +### hWnd +{: .no_toc } + +The Win32 window handle for the underlying button, as a **LongPtr**. Read-only. Useful for passing to API functions. + +### Index +{: .no_toc } + +When the control is part of a control array, the **Long** zero-based index of this instance within the array. Read-only at run time. + +### Left +{: .no_toc } + +The horizontal distance from the left edge of the container to the left edge of the control. **Single**. + +### MaskColor +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### MouseIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor when [**MousePointer**](#mousepointer) is **vbCustom** and the pointer is over the control. + +### MousePointer +{: .no_toc } + +The mouse cursor shown when the pointer is over the control. A member of [**MousePointerConstants**](../VBRUN/Constants/MousePointerConstants). + +### Name +{: .no_toc } + +The unique design-time name of the control on its parent form. Read-only at run time. + +### OLEDropMode +{: .no_toc } + +How the control responds to OLE drops. A restricted member of [**OLEDropConstants**](../VBRUN/Constants/OLEDropConstants): **vbOLEDropNone** or **vbOLEDropManual**. Automatic-drop mode is not supported on a CheckBox. + +### Opacity +{: .no_toc } + +The control's opacity as a percentage (0–100, default 100). Values outside the range are clamped on **Initialize**. Requires Windows 8 or later for child controls. + +### Padding +{: .no_toc } + +The number of pixels of empty space inserted between the picture and the caption (when [**PictureAlignment**](#picturealignment) is **vbAlignLeft** or **vbAlignRight**) or between the caption and the corresponding edge (when **vbAlignTop** or **vbAlignBottom**). **Long**, default 2. Only meaningful when [**Style**](#style) is **vbButtonGraphical**. + +### Parent +{: .no_toc } + +A reference to the [**Form**](Form) (or **UserControl**) that contains this control. Read-only. + +### Picture +{: .no_toc } + +A **StdPicture** drawn on the control when [**Style**](#style) is **vbButtonGraphical**. Assigning **Nothing** restores an empty picture rather than removing the bitmap surface. + +### PictureAlignment +{: .no_toc } + +How [**Picture**](#picture) is positioned relative to the caption when [**Style**](#style) is **vbButtonGraphical**. A member of [**AlignConstants**](../VBRUN/Constants/AlignConstants): **vbAlignNone**, **vbAlignTop** (default), **vbAlignBottom**, **vbAlignLeft**, **vbAlignRight**. + +### PictureDpiScaling +{: .no_toc } + +When **True**, scales [**Picture**](#picture), [**DownPicture**](#downpicture), and [**DisabledPicture**](#disabledpicture) by the current DPI factor before drawing. **Boolean**, default **False**. + +### RightToLeft +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. Use [**Alignment**](#alignment) to flip the caption to the left of the box. + +### 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. + +### TabIndex +{: .no_toc } + +The position of the control in the form's TAB-key navigation order. **Long**. + +### TabStop +{: .no_toc } + +Whether the user can reach the control by pressing the **TAB** key. **Boolean**, default **True**. A disabled control is skipped regardless of this setting. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the control. Ignored by the framework. + +### ToolTipText +{: .no_toc } + +A multi-line **String** displayed as a tooltip when the user hovers over the control. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the control. **Single**. + +### TransparencyKey +{: .no_toc } + +An **OLE_COLOR** that, when set, becomes fully transparent in the rendered control. Default `-1` disables the effect. Requires Windows 8 or later for child controls. + +### UseMaskColor +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### Value +{: .no_toc } + +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. + +Assigning a value that differs from the current one raises a [**Click**](#click) event. + +### Visible +{: .no_toc } + +Whether the control is shown. **Boolean**, default **True**. + +### VisualStyles +{: .no_toc } + +Whether the OS theme engine should be used when drawing the control. **Boolean**. + +### WhatsThisHelpID +{: .no_toc } + +A **Long** identifying a "What's This?" help-pop-up topic in the application's help file. See [**ShowWhatsThis**](#showwhatsthis). + +### Width +{: .no_toc } + +The control's width. **Single**. + +## Methods + +### Drag +{: .no_toc } + +Begins, completes, or cancels a manual drag-and-drop operation. Typically called from a [**MouseDown**](#mousedown) handler when [**DragMode**](#dragmode) is **vbManual**. + +Syntax: *object*.**Drag** [ *Action* ] + +*Action* +: *optional* A member of [**DragConstants**](../VBRUN/Constants/DragConstants): **vbCancel** (0), **vbBeginDrag** (1, default), or **vbEndDrag** (2). + +### Move +{: .no_toc } + +Repositions and optionally resizes the control in a single call. + +Syntax: *object*.**Move** *Left* [, *Top* [, *Width* [, *Height* ] ] ] + +*Left* +: *required* A **Single** giving the new horizontal position. + +*Top*, *Width*, *Height* +: *optional* New values for the corresponding properties. Omitted values are left unchanged. + +### OLEDrag +{: .no_toc } + +Initiates an OLE drag operation from the control, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject**. + +Syntax: *object*.**OLEDrag** + +### Refresh +{: .no_toc } + +Forces an immediate repaint of the control. + +Syntax: *object*.**Refresh** + +### SetFocus +{: .no_toc } + +Moves the input focus to the control. The control must be both [**Visible**](#visible) and [**Enabled**](#enabled), or run-time error 5 (*Invalid procedure call or argument*) is raised. + +Syntax: *object*.**SetFocus** + +### ShowWhatsThis +{: .no_toc } + +Displays the topic identified by [**WhatsThisHelpID**](#whatsthishelpid) as a "What's This?" pop-up. + +Syntax: *object*.**ShowWhatsThis** + +### ZOrder +{: .no_toc } + +Brings the control to the front or back of its sibling stack. + +Syntax: *object*.**ZOrder** [ *Position* ] + +*Position* +: *optional* A member of [**ZOrderConstants**](../VBRUN/Constants/ZOrderConstants): **vbBringToFront** (0, default) or **vbSendToBack** (1). + +## Events + +### Click +{: .no_toc } + +Raised after [**Value**](#value) changes — whether the user clicked the box, pressed the access key, or assigned a different value in code. **Default event.** + +Syntax: *object*\_**Click**( ) + +### 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**( ) + +### KeyDown +{: .no_toc } + +Raised when the user presses any key while the control has focus. + +Syntax: *object*\_**KeyDown**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### KeyPress +{: .no_toc } + +Raised when the user types a character that produces an ANSI keystroke. + +Syntax: *object*\_**KeyPress**( *KeyAscii* **As Integer** ) + +### KeyUp +{: .no_toc } + +Raised when the user releases a key while the control has focus. + +Syntax: *object*\_**KeyUp**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### LostFocus +{: .no_toc } + +Raised when the control loses the input focus. + +Syntax: *object*\_**LostFocus**( ) + +### MouseDown +{: .no_toc } + +Raised when the user presses any mouse button over the control. + +Syntax: *object*\_**MouseDown**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseMove +{: .no_toc } + +Raised when the cursor moves over the control. + +Syntax: *object*\_**MouseMove**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseUp +{: .no_toc } + +Raised when the user releases a mouse button over the control. + +Syntax: *object*\_**MouseUp**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### OLECompleteDrag +{: .no_toc } + +Raised on the source control when the OLE drag operation finishes, indicating which effect (copy, move, none) the destination accepted. + +Syntax: *object*\_**OLECompleteDrag**( *Effect* **As Long** ) + +### OLEDragDrop +{: .no_toc } + +Raised on the destination control when the user drops data on it. + +Syntax: *object*\_**OLEDragDrop**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### OLEDragOver +{: .no_toc } + +Raised on the destination control while an OLE drag passes over it. + +Syntax: *object*\_**OLEDragOver**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### OLEGiveFeedback +{: .no_toc } + +Raised on the source control during a drag so the application can adjust the cursor or other visual feedback. + +Syntax: *object*\_**OLEGiveFeedback**( *Effect* **As Long**, *DefaultCursors* **As Boolean** ) + +### OLESetData +{: .no_toc } + +Raised on the source control when the destination requests data in a format that was registered but not yet supplied. + +Syntax: *object*\_**OLESetData**( *Data* **As DataObject**, *DataFormat* **As Integer** ) + +### OLEStartDrag +{: .no_toc } + +Raised on the source control at the start of an OLE drag, so the application can populate the **DataObject** and choose the allowed effects. + +Syntax: *object*\_**OLEStartDrag**( *Data* **As DataObject**, *AllowedEffects* **As Long** ) + +### Validate +{: .no_toc } + +Raised when the focus is moving to another control whose [**CausesValidation**](#causesvalidation) is **True**. Setting *Cancel* to **True** keeps the focus on this control. + +Syntax: *object*\_**Validate**( *Cancel* **As Boolean** ) + +{% include VBA-Attribution.md %} diff --git a/docs/Reference/VB/CheckMark/index.md b/docs/Reference/VB/CheckMark/index.md new file mode 100644 index 0000000..2690360 --- /dev/null +++ b/docs/Reference/VB/CheckMark/index.md @@ -0,0 +1,345 @@ +--- +title: CheckMark +parent: VB Package +permalink: /tB/Packages/VB/CheckMark/ +has_toc: false +--- + +# CheckMark class +{: .no_toc } + +A **CheckMark** is a windowless control that draws a single check glyph — checked, unchecked, or grey — that scales to fill its rectangle. Unlike [**CheckBox**](../CheckBox), it has no caption, no font, and cannot take focus or receive keyboard input; it is essentially the box from a check-box rendered at whatever size the layout requires. This makes it especially useful inside reports and other dense layouts where the fixed-size system check would look out of place, but it is also available on a **Form** or **UserControl**. + +The default property is [**Value**](#value) and the default event is [**Click**](#click). + +```tb +Private Sub Form_Load() + Check1.Value = vbUnchecked +End Sub + +Private Sub Check1_Click() + Debug.Print "Check is now: " & Check1.Value +End Sub +``` + +* TOC +{:toc} + +## Three-state behaviour + +[**Value**](#value) is typed as [**CheckBoxConstants**](../../VBRUN/Constants/CheckBoxConstants): + +| Constant | Value | Meaning | +|------------------|-------|--------------------------------------------------------| +| **vbUnchecked** | 0 | The check is cleared. | +| **vbChecked** | 1 | The check is selected. | +| **vbGrayed** | 2 | The check is in an indeterminate (grey) state. | + +A user click toggles **Value** between **vbChecked** and **vbUnchecked** only. The grey state is reachable from code — assign **vbGrayed** to **Value** to display it. + +```tb +Check1.Value = vbGrayed ' show the indeterminate state +``` + +## Drawing modes + +[**VisualStyles**](#visualstyles) selects how the glyph is rendered: + +- **VisualStyles = False** (default) — drawn with the GDI **DrawFrameControl** primitive. Honours [**Appearance**](#appearance): **vbAppear3d** uses the classic raised/sunken look, **vbAppearFlat** uses a single-pixel outline. A disabled check, or one in the **vbGrayed** state, is drawn over the dotted three-state pattern. +- **VisualStyles = True** — drawn through the OS theme engine (UXTHEME), so the glyph picks up the current visual-style theme. **Appearance** is ignored in this mode. + +## Background + +[**BackStyle**](#backstyle) controls whether the rectangle behind the glyph is filled before the glyph is drawn: + +- **vbBFTransparent** (default) — only the glyph is painted; whatever the container draws shows through. +- **vbBFOpaque** — the rectangle is filled with [**BackColor**](#backcolor) first. + +## Properties + +### Anchors +{: .no_toc } + +The **Anchors** object that determines which sides of the control follow the corresponding sides of its container as the container is resized. Read-only — set the individual sides through the returned object. + +### Appearance +{: .no_toc } + +How the glyph is shaded when [**VisualStyles**](#visualstyles) is **False**. A member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppear3d** (default) or **vbAppearFlat**. Ignored when [**VisualStyles**](#visualstyles) is **True**. + +### BackColor +{: .no_toc } + +The background colour, as an **OLE_COLOR**. Defaults to the system 3-D face colour. Used only when [**BackStyle**](#backstyle) is **vbBFOpaque**. + +### BackStyle +{: .no_toc } + +Whether the control fills its rectangle before drawing the glyph. A member of **BackFillStyleConstants**: **vbBFTransparent** (default) or **vbBFOpaque**. + +### Container +{: .no_toc } + +The immediate container (a **Form**, **Frame**, **PictureBox**, or other container control) that hosts this **CheckMark**. Assigning a new value with **Set** moves the control to a different container. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a check mark. Always **vbCheckMark**. + +### Dock +{: .no_toc } + +Whether the control fills one edge of, or the entire interior of, its container. A member of **DockModeConstants**, default **vbDockNone**. + +### 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 reacts to mouse input. A disabled **CheckMark** still shows its current value but is drawn dimmed and ignores clicks. **Boolean**, default **True**. + +### Height +{: .no_toc } + +The control's height, in twips by default (or in the container's **ScaleMode** units). **Single**. + +### 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 control that is not part of an array raises run-time error 343 (*Object not an array*). Read-only at run time. + +### Left +{: .no_toc } + +The horizontal distance from the left edge of the container to the left edge of the control. **Single**. + +### 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. + +### Parent +{: .no_toc } + +A reference to the **Form** (or **UserControl**) that contains this control. Read-only. + +### TabIndex +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. The control is not focusable, so the property has no effect at run time. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the control. Ignored by the framework. + +### ToolTipText +{: .no_toc } + +A multi-line **String** displayed as a tooltip when the user hovers over the control. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the control. **Single**. + +### Value +{: .no_toc } + +The current state of the check. **Default property.** + +Syntax: *object*.**Value** [ = *value* ] + +*value* +: A member of [**CheckBoxConstants**](../../VBRUN/Constants/CheckBoxConstants): **vbUnchecked** (0), **vbChecked** (1), or **vbGrayed** (2). + +A user click toggles **Value** between **vbChecked** and **vbUnchecked** only; **vbGrayed** is settable from code. + +### Visible +{: .no_toc } + +Whether the control is shown. **Boolean**, default **True**. + +### VisualStyles +{: .no_toc } + +When **True**, the glyph is drawn through the OS theme engine; when **False** (default), it is drawn with **DrawFrameControl** and obeys [**Appearance**](#appearance). **Boolean**. + +### WhatsThisHelpID +{: .no_toc } + +A **Long** identifying a "What's This?" help-pop-up topic in the application's help file. See [**ShowWhatsThis**](#showwhatsthis). + +### Width +{: .no_toc } + +The control's width. **Single**. + +## Methods + +### Drag +{: .no_toc } + +Begins, completes, or cancels a manual drag-and-drop operation. Typically called from a [**MouseDown**](#mousedown) handler when [**DragMode**](#dragmode) is **vbManual**. + +Syntax: *object*.**Drag** [ *Action* ] + +*Action* +: *optional* A member of [**DragConstants**](../../VBRUN/Constants/DragConstants): **vbCancel** (0), **vbBeginDrag** (1, default), or **vbEndDrag** (2). + +### Move +{: .no_toc } + +Repositions and optionally resizes the control in a single call. + +Syntax: *object*.**Move** *Left* [, *Top* [, *Width* [, *Height* ] ] ] + +*Left* +: *required* A **Single** giving the new horizontal position. + +*Top*, *Width*, *Height* +: *optional* New values for the corresponding properties. Omitted values are left unchanged. + +### OLEDrag +{: .no_toc } + +Initiates an OLE drag operation from the control, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject**. + +Syntax: *object*.**OLEDrag** + +### Refresh +{: .no_toc } + +Forces an immediate repaint of the control. + +Syntax: *object*.**Refresh** + +### ShowWhatsThis +{: .no_toc } + +Displays the topic identified by [**WhatsThisHelpID**](#whatsthishelpid) as a "What's This?" pop-up. + +Syntax: *object*.**ShowWhatsThis** + +### ZOrder +{: .no_toc } + +Brings the control to the front or back of its sibling stack. + +Syntax: *object*.**ZOrder** [ *Position* ] + +*Position* +: *optional* A member of [**ZOrderConstants**](../../VBRUN/Constants/ZOrderConstants): **vbBringToFront** (0, default) or **vbSendToBack** (1). + +## Events + +### Click +{: .no_toc } + +Raised when the user clicks the control with the left mouse button — after [**Value**](#value) has toggled between **vbChecked** and **vbUnchecked**. **Default event.** + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks the control. + +Syntax: *object*\_**DblClick**( ) + +### DragDrop +{: .no_toc } + +Raised on the destination control when a manual drag operation ends over it. + +Syntax: *object*\_**DragDrop**( *Source* **As Control**, *X* **As Single**, *Y* **As Single** ) + +### DragOver +{: .no_toc } + +Raised on the control under the cursor while a manual drag operation is in progress. + +Syntax: *object*\_**DragOver**( *Source* **As Control**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### 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/ComboBox/index.md b/docs/Reference/VB/ComboBox/index.md new file mode 100644 index 0000000..38532a6 --- /dev/null +++ b/docs/Reference/VB/ComboBox/index.md @@ -0,0 +1,563 @@ +--- +title: ComboBox +parent: VB Package +permalink: /tB/Packages/VB/ComboBox/ +has_toc: false +--- + +# ComboBox class +{: .no_toc } + +A **ComboBox** is a Win32 native control that combines an edit field with a drop-down list of items, letting the user either type a value or pick one from the list. The control is normally placed on a **Form** or **UserControl** at design time. The default property is [**Text**](#text) and the default event is [**Change**](#change). + +```tb +Private Sub Form_Load() + With Combo1 + .AddItem "Apple" + .AddItem "Banana" + .AddItem "Cherry" + .ListIndex = 0 + End With +End Sub + +Private Sub Combo1_Click() + Debug.Print "Picked: " & Combo1.Text +End Sub +``` + +* TOC +{:toc} + +## Style + +[**Style**](#style) selects one of three Win32 combo-box variants ([**ComboBoxConstants**](../../VBRUN/Constants/ComboBoxConstants)): + +| Constant | Value | Layout | +|---------------------------|-------|--------------------------------------------------------------------------| +| **vbComboDropdown** | 0 | Editable text + drop-down button + drop-down list. The default. | +| **vbComboSimple** | 1 | Editable text + a permanently visible list (no drop-down button). | +| **vbComboDropdownList** | 2 | Drop-down list only — the user must pick a value; typing is disabled. | + +Changing **Style** at run time recreates the underlying window (the existing list contents and selection are preserved). [**Sorted**](#sorted) and [**IntegralHeight**](#integralheight) recreate the window the same way. + +## Editing the list + +Items are held inside the OS combo-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 +Combo1.Sorted = True +Combo1.AddItem "Cherry" +Combo1.AddItem "Apple" ' Inserted at index 0 — Combo1.NewIndex = 0 +Combo1.ItemData(Combo1.NewIndex) = 42 +``` + +## Selection and text + +[**ListIndex**](#listindex) is the index of the selected item, or `-1` when nothing is selected. Setting it from code highlights the corresponding item and raises [**Click**](#click) (only if the value actually changes). [**TopIndex**](#topindex) controls which item appears at the top of the drop-down portion when it is open. + +[**Text**](#text) reads or writes the editable area, except in **vbComboDropdownList** mode where there is no edit field — there, assigning a string searches the list with an exact, case-insensitive match and selects that item if found, doing nothing otherwise. Reading **Text** in any mode returns the current display text. + +For the styles that have an edit area (**vbComboDropdown** and **vbComboSimple**), [**SelStart**](#selstart), [**SelLength**](#sellength), and [**SelText**](#seltext) reflect or modify the user's text selection. Reading or writing any of these in **vbComboDropdownList** mode raises run-time error 380. + +## OLE drag-and-drop + +[**OLEDragMode**](#oledragmode) controls source-side drags (only meaningful for the styles with an edit area — when set to **vbOLEDragAutomatic**, dragging selected text in the edit area starts an OLE drag with that text as the data). [**OLEDropMode**](#oledropmode) controls drop-target behaviour and is restricted to **vbOLEDropNone** or **vbOLEDropManual**. + +## Properties + +### Appearance +{: .no_toc } + +Determines how the control's border is drawn by the OS. A member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). + +### BackColor +{: .no_toc } + +The colour of the edit area and the list background, as an **OLE_COLOR**. Defaults to the system window-background 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**. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a combo box. Always **vbComboBox**. + +### 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 combo box shows its current text but is dimmed and ignores keyboard and mouse interaction. **Boolean**, default **True**. + +### Font +{: .no_toc } + +The **StdFont** used to render text in the edit area and the drop-down list. The convenience properties **FontName**, **FontSize**, **FontBold**, **FontItalic**, **FontStrikethru**, and **FontUnderline** read or write the corresponding members of this object. Changing the font may resize the control vertically when [**IntegralHeight**](#integralheight) is **True**. + +### ForeColor +{: .no_toc } + +The text colour, as an **OLE_COLOR**. Defaults to the system window-text colour. + +### Height +{: .no_toc } + +The control's height, in twips by default (or in the container's **ScaleMode** units). For **vbComboDropdown** and **vbComboDropdownList** this is the height of the closed control (the drop-down portion is sized separately — see [**MaxDropDownItems**](#maxdropdownitems)). For **vbComboSimple** it is the total height including the always-visible list. **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 combo 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. Read-only at run time. + +### IntegralHeight +{: .no_toc } + +When **True** (default), the OS adjusts the control's height so that the visible portion of the list shows whole items rather than partial ones. When **False**, the control honours [**Height**](#height) exactly. **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. + +```tb +Combo1.AddItem "Apple" +Combo1.ItemData(Combo1.NewIndex) = customerID +``` + +### 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* ] + +### ListCount +{: .no_toc } + +The number of items in the list, as a **Long**. Read-only. + +### ListIndex +{: .no_toc } + +The zero-based index of the selected item, or `-1` if nothing is selected. **Long**. Assigning a value that differs from the current one selects that item and raises [**Click**](#click). + +### Locked +{: .no_toc } + +When **True**, the user can scroll and select within the control but cannot type into the edit area or change the selection with the keyboard or mouse wheel. **Boolean**, default **False**. Has no effect when [**Style**](#style) is **vbComboDropdownList** (where there is no edit area to lock). + +### MaxDropDownItems +{: .no_toc } + +The maximum number of items shown in the drop-down portion when the user opens it. **Long**, default `0` — when zero, the OS chooses a height (typically eight items). + +### 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. + +### 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's edit area can act 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 selected text in the edit area starts an OLE drag with that text as the data, and the drop effect **vbDropEffectMove** clears the selection). + +### 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 ComboBox. + +### 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** (or **UserControl**) that contains this control. Read-only. + +### RightToLeft +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### SelLength +{: .no_toc } + +The number of characters selected in the edit area. **Long**. Reading or writing this property when [**Style**](#style) is **vbComboDropdownList** raises run-time error 380. + +### SelStart +{: .no_toc } + +The zero-based position of the first selected character in the edit area, or the caret position when no text is selected. **Long**. Reading or writing this property when [**Style**](#style) is **vbComboDropdownList** raises run-time error 380. + +### SelText +{: .no_toc } + +The text currently selected in the edit area. Assigning a string replaces the selection with that string and positions the caret immediately after the inserted text. **String**. Reading or writing this property when [**Style**](#style) is **vbComboDropdownList** raises run-time error 380. + +### 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 combo-box variants. A member of [**ComboBoxConstants**](../../VBRUN/Constants/ComboBoxConstants): **vbComboDropdown** (0, default), **vbComboSimple** (1), or **vbComboDropdownList** (2). See [Style](#style) above for the layout 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 shown in the edit area, or the text of the selected item when [**Style**](#style) is **vbComboDropdownList**. **Default property.** + +Syntax: *object*.**Text** [ = *string* ] + +For **vbComboDropdown** and **vbComboSimple**, assigning a value writes it directly to the edit area and raises [**Change**](#change) if the new value differs from the current one. For **vbComboDropdownList**, assigning a value searches the list (case-insensitive, exact match) and selects the matching item if found; if no item matches, the assignment has no visible effect. + +### 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 drop-down (or always-visible) list. Assigning a value scrolls the list so that item is at the top. **Long**. + +### TransparencyKey +{: .no_toc } + +An **OLE_COLOR** that, when set, becomes fully transparent in the rendered control. Default `-1` disables the effect. Requires Windows 8 or later for child controls. + +### Visible +{: .no_toc } + +Whether the control is shown. **Boolean**, default **True**. + +### VisualStyles +{: .no_toc } + +Whether the OS theme engine should be used when drawing the control. **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). + +### WheelScrollEvent +{: .no_toc } + +When **True** (default), mouse-wheel notifications over the drop-down list 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**. + +## Methods + +### AddItem +{: .no_toc } + +Inserts a new item into the list and stores the resulting position in [**NewIndex**](#newindex). + +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. Ignored when [**Sorted**](#sorted) is **True**. + +### Clear +{: .no_toc } + +Removes every item from the list and clears [**ListIndex**](#listindex). + +Syntax: *object*.**Clear** + +### Drag +{: .no_toc } + +Begins, completes, or cancels a manual drag-and-drop operation. + +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. Items below it shift up by one. + +Syntax: *object*.**RemoveItem** *Index* + +*Index* +: *required* A **Long** zero-based position. + +### 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 + +### Change +{: .no_toc } + +Raised when the text in the edit area changes — whether the user typed into it or code assigned a different value to [**Text**](#text). Not raised in **vbComboDropdownList** mode (where there is no edit area). **Default event.** + +Syntax: *object*\_**Change**( ) + +### Click +{: .no_toc } + +Raised after [**ListIndex**](#listindex) changes — whether the user picked an item from the list or code assigned a different value to [**ListIndex**](#listindex). Assigning the current value again does not raise **Click**. + +Syntax: *object*\_**Click**( ) + +### CloseUp +{: .no_toc } + +Raised when the drop-down portion closes — either because the user picked an item, clicked elsewhere, or pressed **Esc**. Not raised in **vbComboSimple** mode (the list is always visible). + +Syntax: *object*\_**CloseUp**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks an item in the always-visible list (**vbComboSimple** mode). + +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** ) + +### DropDown +{: .no_toc } + +Raised when the user opens the drop-down portion. Not raised in **vbComboSimple** mode (the list is always visible). + +Syntax: *object*\_**DropDown**( ) + +### GotFocus +{: .no_toc } + +Raised when the control receives the input focus. + +Syntax: *object*\_**GotFocus**( ) + +### 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**( ) + +### 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** ) + +### Scroll +{: .no_toc } + +Raised when the drop-down (or always-visible) list is scrolled — by the scroll bar, the keyboard, or the mouse wheel. Wheel-driven scrolling can be silenced by setting [**WheelScrollEvent**](#wheelscrollevent) to **False**. + +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/CommandButton/index.md b/docs/Reference/VB/CommandButton/index.md new file mode 100644 index 0000000..caf1fb0 --- /dev/null +++ b/docs/Reference/VB/CommandButton/index.md @@ -0,0 +1,472 @@ +--- +title: CommandButton +parent: VB Package +permalink: /tB/Packages/VB/CommandButton/ +has_toc: false +--- + +# CommandButton class +{: .no_toc } + +A **CommandButton** is a Win32 native push-button control used to trigger an action — a click-handler runs every time the user presses it. The control is normally placed on a **Form** or **UserControl** at design time. The default property is [**Value**](#value) and the default event is [**Click**](#click). + +```tb +Private Sub Form_Load() + cmdOK.Caption = "&OK" + cmdOK.Default = True ' Enter triggers it + cmdCancel.Caption = "Cancel" + cmdCancel.Cancel = True ' Esc triggers it +End Sub + +Private Sub cmdOK_Click() + Unload Me +End Sub +``` + +* TOC +{:toc} + +## Triggering a click + +A **CommandButton** raises [**Click**](#click) every time the user presses it — by left-clicking, by pressing **Space** or **Enter** while it has focus, by typing the **Alt+** access key marked in the [**Caption**](#caption), by pressing **Esc** when [**Cancel**](#cancel) is **True**, or by pressing **Enter** anywhere on the form when [**Default**](#default) is **True**. Code can fire the same event by assigning **True** to [**Value**](#value): + +```tb +cmdOK.Value = True ' raises cmdOK_Click +``` + +[**Value**](#value) is reset to **False** immediately after the click handler returns, so reading it almost always returns **False**. + +## Cancel and Default + +[**Cancel**](#cancel) and [**Default**](#default) are mutually-form-exclusive — at most one button on a form can have either set to **True**. Assigning **True** to **Cancel** or **Default** on one button automatically clears the same property on whatever button held it before. Setting **Default = True** also gives the button the bold "default push-button" border. + +## Caption and mnemonics + +The text on the button face comes from [**Caption**](#caption). An ampersand in the caption marks the next character as a keyboard mnemonic: pressing **Alt+** that character moves the focus to the button and raises [**Click**](#click) (provided no other control on the form competes for the same access key). Use `&&` to display a literal ampersand. + +```tb +cmdSave.Caption = "&Save && Close" ' renders as: Save & Close +``` + +## Graphical style + +When [**Style**](#style) is **vbButtonGraphical**, the button is owner-drawn and displays the bitmaps assigned to [**Picture**](#picture), [**DownPicture**](#downpicture), and [**DisabledPicture**](#disabledpicture) alongside the caption. [**PictureAlignment**](#picturealignment), [**Padding**](#padding), and [**PictureDpiScaling**](#picturedpiscaling) control how the picture is positioned. Changing **Style** at run time recreates the underlying window. + +## Properties + +### Appearance +{: .no_toc } + +Determines how the control's border is drawn by the OS. A member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). + +### BackColor +{: .no_toc } + +The background colour, as an **OLE_COLOR**. Defaults to the system 3-D face colour. Honoured only when [**Style**](#style) is **vbButtonGraphical** — the standard Win32 button always paints with the theme colour. + +### Cancel +{: .no_toc } + +When **True**, this button is fired by the **Esc** key from anywhere on its form. **Boolean**, default **False**. Only one **CommandButton** on a form can hold this property — assigning **True** to a second button automatically clears it on the previous one. + +### Caption +{: .no_toc } + +The text displayed on the button. An ampersand marks the next character as a mnemonic; `&&` produces a literal ampersand. The string is read directly from the underlying window — assigning to **Caption** is reflected immediately. + +Syntax: *object*.**Caption** [ = *string* ] + +### CausesValidation +{: .no_toc } + +Determines whether the previously focused control's **Validate** event runs before this control receives the focus. **Boolean**, default **True**. **CommandButton** itself does not raise **Validate**. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a command button. Always **vbCommandButton**. + +### Default +{: .no_toc } + +When **True**, this button is fired by the **Enter** key from anywhere on its form (unless another control is currently consuming **Enter**). The button also displays the bold "default push-button" border. **Boolean**, default **False**. Only one **CommandButton** on a form can hold this property — assigning **True** to a second button automatically clears it on the previous one. + +### DisabledPicture +{: .no_toc } + +A **StdPicture** drawn instead of [**Picture**](#picture) when the control is disabled and [**Style**](#style) is **vbButtonGraphical**. + +### DownPicture +{: .no_toc } + +A **StdPicture** drawn instead of [**Picture**](#picture) while the control is in the depressed state, when [**Style**](#style) is **vbButtonGraphical**. + +### DragIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor while the control is being drag-and-dropped (see [**Drag**](#drag) and [**DragMode**](#dragmode)). + +### DragMode +{: .no_toc } + +Whether the control should drag itself when the user holds the mouse over it. A member of [**DragModeConstants**](../../VBRUN/Constants/DragModeConstants): **vbManual** (0, default — call [**Drag**](#drag) from code) or **vbAutomatic** (1). + +### Enabled +{: .no_toc } + +Determines whether the control accepts user input. A disabled button shows its caption but is dimmed and ignores keyboard and mouse interaction (including its mnemonic and any **Cancel**/**Default** behaviour). **Boolean**, default **True**. + +### Font +{: .no_toc } + +The **StdFont** used to render [**Caption**](#caption). The convenience properties **FontName**, **FontSize**, **FontBold**, **FontItalic**, **FontStrikethru**, and **FontUnderline** read or write the corresponding members of this object. + +### ForeColor +{: .no_toc } + +The text colour for the caption, as an **OLE_COLOR**. Defaults to the system button-text colour. Honoured only when [**Style**](#style) is **vbButtonGraphical**. + +### Height +{: .no_toc } + +The control's height, in twips by default (or in the container's **ScaleMode** units). **Single**. + +### HelpContextID +{: .no_toc } + +A **Long** identifying a topic in the application's help file, retrieved when the user presses **F1** while the control has focus. + +### hWnd +{: .no_toc } + +The Win32 window handle for the underlying button, as a **LongPtr**. Read-only. Useful for passing to API functions. + +### Index +{: .no_toc } + +When the control is part of a control array, the **Long** zero-based index of this instance within the array. Read-only at run time. + +### Left +{: .no_toc } + +The horizontal distance from the left edge of the container to the left edge of the control. **Single**. + +### MaskColor +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### MouseIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor when [**MousePointer**](#mousepointer) is **vbCustom** and the pointer is over the control. + +### MousePointer +{: .no_toc } + +The mouse cursor shown when the pointer is over the control. A member of [**MousePointerConstants**](../../VBRUN/Constants/MousePointerConstants). + +### Name +{: .no_toc } + +The unique design-time name of the control on its parent form. Read-only at run time. + +### OLEDropMode +{: .no_toc } + +How the control responds to OLE drops. A restricted member of [**OLEDropConstants**](../../VBRUN/Constants/OLEDropConstants): **vbOLEDropNone** or **vbOLEDropManual**. Automatic-drop mode is not supported on a CommandButton. + +### Opacity +{: .no_toc } + +The control's opacity as a percentage (0–100, default 100). Values outside the range are clamped on **Initialize**. Requires Windows 8 or later for child controls. + +### Padding +{: .no_toc } + +The number of pixels of empty space inserted between the picture and the caption (when [**PictureAlignment**](#picturealignment) is **vbAlignLeft** or **vbAlignRight**) or between the caption and the corresponding edge (when **vbAlignTop** or **vbAlignBottom**). **Long**, default 2. Only meaningful when [**Style**](#style) is **vbButtonGraphical**. + +### Parent +{: .no_toc } + +A reference to the **Form** (or **UserControl**) that contains this control. Read-only. + +### Picture +{: .no_toc } + +A **StdPicture** drawn on the button when [**Style**](#style) is **vbButtonGraphical**. Assigning **Nothing** restores an empty picture rather than removing the bitmap surface. + +### PictureAlignment +{: .no_toc } + +How [**Picture**](#picture) is positioned relative to the caption when [**Style**](#style) is **vbButtonGraphical**. A member of [**AlignConstants**](../../VBRUN/Constants/AlignConstants): **vbAlignNone**, **vbAlignTop** (default), **vbAlignBottom**, **vbAlignLeft**, **vbAlignRight**. + +### PictureDpiScaling +{: .no_toc } + +When **True**, scales [**Picture**](#picture), [**DownPicture**](#downpicture), and [**DisabledPicture**](#disabledpicture) by the current DPI factor before drawing. **Boolean**, default **False**. + +### RightToLeft +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### Style +{: .no_toc } + +Selects between the standard Win32 push-button appearance and an owner-drawn graphical button. A member of [**ButtonConstants**](../../VBRUN/Constants/ButtonConstants): **vbButtonStandard** (0, default) or **vbButtonGraphical** (1). Changing **Style** at run time recreates the underlying window. + +### TabIndex +{: .no_toc } + +The position of the control in the form's TAB-key navigation order. **Long**. + +### TabStop +{: .no_toc } + +Whether the user can reach the control by pressing the **TAB** key. **Boolean**, default **True**. A disabled control is skipped regardless of this setting. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the control. Ignored by the framework. + +### ToolTipText +{: .no_toc } + +A multi-line **String** displayed as a tooltip when the user hovers over the control. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the control. **Single**. + +### TransparencyKey +{: .no_toc } + +An **OLE_COLOR** that, when set, becomes fully transparent in the rendered control. Default `-1` disables the effect. Requires Windows 8 or later for child controls. + +### UseMaskColor +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### Value +{: .no_toc } + +A trigger for raising [**Click**](#click) from code. **Default property.** + +Syntax: *object*.**Value** [ = *boolean* ] + +Assigning **True** raises [**Click**](#click) and resets **Value** to **False** immediately after the handler returns; assigning **False** does nothing. Reading **Value** therefore returns **False** in almost every situation. + +```tb +cmdOK.Value = True ' equivalent to a user click +``` + +### 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**. + +### WhatsThisHelpID +{: .no_toc } + +A **Long** identifying a "What's This?" help-pop-up topic in the application's help file. See [**ShowWhatsThis**](#showwhatsthis). + +### Width +{: .no_toc } + +The control's width. **Single**. + +## Methods + +### Drag +{: .no_toc } + +Begins, completes, or cancels a manual drag-and-drop operation. Typically called from a [**MouseDown**](#mousedown) handler when [**DragMode**](#dragmode) is **vbManual**. + +Syntax: *object*.**Drag** [ *Action* ] + +*Action* +: *optional* A member of [**DragConstants**](../../VBRUN/Constants/DragConstants): **vbCancel** (0), **vbBeginDrag** (1, default), or **vbEndDrag** (2). + +### Move +{: .no_toc } + +Repositions and optionally resizes the control in a single call. + +Syntax: *object*.**Move** *Left* [, *Top* [, *Width* [, *Height* ] ] ] + +*Left* +: *required* A **Single** giving the new horizontal position. + +*Top*, *Width*, *Height* +: *optional* New values for the corresponding properties. Omitted values are left unchanged. + +### OLEDrag +{: .no_toc } + +Initiates an OLE drag operation from the control, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject**. + +Syntax: *object*.**OLEDrag** + +### Refresh +{: .no_toc } + +Forces an immediate repaint of the control. + +Syntax: *object*.**Refresh** + +### SetFocus +{: .no_toc } + +Moves the input focus to the control. The control must be both [**Visible**](#visible) and [**Enabled**](#enabled), or run-time error 5 (*Invalid procedure call or argument*) is raised. + +Syntax: *object*.**SetFocus** + +### ShowWhatsThis +{: .no_toc } + +Displays the topic identified by [**WhatsThisHelpID**](#whatsthishelpid) as a "What's This?" pop-up. + +Syntax: *object*.**ShowWhatsThis** + +### ZOrder +{: .no_toc } + +Brings the control to the front or back of its sibling stack. + +Syntax: *object*.**ZOrder** [ *Position* ] + +*Position* +: *optional* A member of [**ZOrderConstants**](../../VBRUN/Constants/ZOrderConstants): **vbBringToFront** (0, default) or **vbSendToBack** (1). + +## Events + +### Click +{: .no_toc } + +Raised every time the button is pressed — by mouse click, by **Space** or **Enter** while focused, by the **Alt+** access key in the [**Caption**](#caption), by **Esc** when [**Cancel**](#cancel) is **True**, by **Enter** when [**Default**](#default) is **True**, or by an assignment of **True** to [**Value**](#value). **Default event.** + +Syntax: *object*\_**Click**( ) + +### 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**( ) + +### KeyDown +{: .no_toc } + +Raised when the user presses any key while the control has focus. + +Syntax: *object*\_**KeyDown**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### KeyPress +{: .no_toc } + +Raised when the user types a character that produces an ANSI keystroke. + +Syntax: *object*\_**KeyPress**( *KeyAscii* **As Integer** ) + +### KeyUp +{: .no_toc } + +Raised when the user releases a key while the control has focus. + +Syntax: *object*\_**KeyUp**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### LostFocus +{: .no_toc } + +Raised when the control loses the input focus. + +Syntax: *object*\_**LostFocus**( ) + +### MouseDown +{: .no_toc } + +Raised when the user presses any mouse button over the control. + +Syntax: *object*\_**MouseDown**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseMove +{: .no_toc } + +Raised when the cursor moves over the control. + +Syntax: *object*\_**MouseMove**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseUp +{: .no_toc } + +Raised when the user releases a mouse button over the control. + +Syntax: *object*\_**MouseUp**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### OLECompleteDrag +{: .no_toc } + +Raised on the source control when the OLE drag operation finishes, indicating which effect (copy, move, none) the destination accepted. + +Syntax: *object*\_**OLECompleteDrag**( *Effect* **As Long** ) + +### OLEDragDrop +{: .no_toc } + +Raised on the destination control when the user drops data on it. + +Syntax: *object*\_**OLEDragDrop**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### OLEDragOver +{: .no_toc } + +Raised on the destination control while an OLE drag passes over it. + +Syntax: *object*\_**OLEDragOver**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### OLEGiveFeedback +{: .no_toc } + +Raised on the source control during a drag so the application can adjust the cursor or other visual feedback. + +Syntax: *object*\_**OLEGiveFeedback**( *Effect* **As Long**, *DefaultCursors* **As Boolean** ) + +### OLESetData +{: .no_toc } + +Raised on the source control when the destination requests data in a format that was registered but not yet supplied. + +Syntax: *object*\_**OLESetData**( *Data* **As DataObject**, *DataFormat* **As Integer** ) + +### OLEStartDrag +{: .no_toc } + +Raised on the source control at the start of an OLE drag, so the application can populate the **DataObject** and choose the allowed effects. + +Syntax: *object*\_**OLEStartDrag**( *Data* **As DataObject**, *AllowedEffects* **As Long** ) diff --git a/docs/Reference/VB/Data/index.md b/docs/Reference/VB/Data/index.md new file mode 100644 index 0000000..6ad5c19 --- /dev/null +++ b/docs/Reference/VB/Data/index.md @@ -0,0 +1,504 @@ +--- +title: Data +parent: VB Package +permalink: /tB/Packages/VB/Data/ +has_toc: false +--- + +# Data class +{: .no_toc } + +A **Data** control is a Win32 native control that opens a DAO database and exposes a single recordset to other controls on the form through data binding. It draws a strip of four arrow-shaped buttons — **Move-First**, **Move-Previous**, **Move-Next**, **Move-Last** — with a centred [**Caption**](#caption) between them, and lets the user step through the recordset with the mouse. The control is normally placed on a **Form** or **UserControl** at design time. Setting [**DatabaseName**](#databasename) and [**RecordSource**](#recordsource) is enough to populate it; the recordset opens automatically the first time the control is created. The default event is [**Validate**](#validate); the control has no usable default property. + +```tb +Private Sub Form_Load() + With Data1 + .DatabaseName = App.Path & "\biblio.mdb" + .RecordSource = "Authors" + .Caption = "Authors" + End With + Set Text1.DataSource = Data1 + Text1.DataField = "Author" +End Sub + +Private Sub Data1_Reposition() + Me.Caption = "Author " & (Data1.Recordset.AbsolutePosition + 1) +End Sub +``` + +* TOC +{:toc} + +## Connecting to a database + +[**DefaultType**](#defaulttype) selects the database engine ([**DatabaseTypeConstants**](../../VBRUN/Constants/DatabaseTypeConstants)): + +| Constant | Value | Engine | +|----------------|-------|------------------------------------------------------| +| **vbUseJet** | 2 | Microsoft Jet (the classic VB6 default). | +| **vbUseODBC** | 1 | An ODBC data source. | +| **vbUseACE** | 3 | The Microsoft Access ACE engine. New in twinBASIC. | + +[**DatabaseName**](#databasename) gives the path to the database file (for Jet/ACE) or the DSN (for ODBC); [**Connect**](#connect) is the connection string. The Jet-flavoured default `"Access 2000;"` is rewritten to `"MS Access;"` before the database is opened, matching the VB6 behaviour. [**Exclusive**](#exclusive) and [**ReadOnly**](#readonly) are passed through to **OpenDatabase**, and [**Options**](#options) is the DAO option bit-mask. [**DefaultCursorType**](#defaultcursortype) is consulted only when **DefaultType** is **vbUseODBC**. + +[**RecordSource**](#recordsource) is the table name (or SQL statement) opened against the database, and [**RecordsetType**](#recordsettype) chooses between table, dynaset, and snapshot ([**RecordsetTypeConstants**](../../VBRUN/Constants/RecordsetTypeConstants)). Calling [**Refresh**](#refresh) reopens the recordset using the current values of these properties — typically after one of them is changed at run time. + +The opened objects are exposed read-only as [**Database**](#database) and read/write as [**Recordset**](#recordset). Assigning a new value to **Recordset** disconnects from the current database, adopts the new recordset, and re-binds every dependent control. + +## Bound controls + +Other controls become *data-bound* by setting their **DataSource** to this **Data** control and their **DataField** to the name of a field in [**Recordset**](#recordset). A bound control reads its value from that field whenever the current record changes, and writes user edits back into the field as part of the next save. The **Data** control mediates both directions, raising [**Reposition**](#reposition) after the bound controls have re-synced and [**Validate**](#validate) before any operation that would discard pending edits. + +```tb +' At design time you would normally set these in the property sheet, +' but they can also be assigned in code: +Set txtTitle.DataSource = Data1 +txtTitle.DataField = "Title" +Set chkInPrint.DataSource = Data1 +chkInPrint.DataField = "InPrint" +``` + +## Navigation and end-of-file behaviour + +The four buttons step through the recordset with **MoveFirst**, **MovePrevious**, **MoveNext**, and **MoveLast**. [**BOFAction**](#bofaction) controls what happens when the user moves past the first record ([**DataBOFconstants**](../../VBRUN/Constants/DataBOFconstants)): **vbMoveFirst** (default) snaps back to the first record; **vbBOF** lets the recordset sit on the BOF marker. [**EOFAction**](#eofaction) controls what happens past the last record ([**DataEOFConstants**](../../VBRUN/Constants/DataEOFConstants)): **vbMoveLast** (default), **vbEOF**, or **vbAddNew** — which clears every bound control and starts a new record. + +## The validate / save cycle + +Whenever the control is about to leave the current record — through a navigation button, a programmatic move, **Refresh**, **Update**, **Delete**, or unloading the form — it fires [**Validate**](#validate) with an *Action* argument from [**DataValidateConstants**](../../VBRUN/Constants/DataValidateConstants) and a *Save* flag indicating whether bound controls hold unsaved edits. Setting *Action* to **vbDataActionCancel** (0) cancels the operation and keeps the current record. If *Save* is non-zero on return and the operation proceeds, the bound controls are flushed back into the recordset before the move occurs. + +[**Reposition**](#reposition) is raised after a successful move, with the bound controls already showing the new record. [**UpdateControls**](#updatecontrols) re-pulls the current record into the bound controls without firing **Reposition**, and [**UpdateRecord**](#updaterecord) is reserved for explicit save-without-move (currently unimplemented). + +## Properties + +### Appearance +{: .no_toc } + +Determines how the control's border is drawn by the OS. A member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). + +### BackColor +{: .no_toc } + +The fill colour of the band behind the [**Caption**](#caption), as an **OLE_COLOR**. Defaults to the system window-background colour. + +### BOFAction +{: .no_toc } + +Controls what happens when the user moves past the start of the recordset. A member of [**DataBOFconstants**](../../VBRUN/Constants/DataBOFconstants): **vbMoveFirst** (0, default — snap back to the first record) or **vbBOF** (1 — let the recordset sit on the beginning-of-file marker, leaving bound controls cleared). + +### Caption +{: .no_toc } + +The text drawn in the band between the navigation buttons. **String**, default `"Data"`. The string is read directly from the underlying window — assigning to **Caption** is reflected immediately. + +Syntax: *object*.**Caption** [ = *string* ] + +### CausesValidation +{: .no_toc } + +Determines whether the previously focused control's **Validate** event runs before this control receives the focus. **Boolean**, default **True**. This refers to the *previous* control's validation; for the **Data** control's own [**Validate**](#validate) event, see the [validate / save cycle](#the-validate--save-cycle) section above. + +### Connect +{: .no_toc } + +The connection string passed to **OpenDatabase**. **String**, default `"Access 2000;"`. The default value is rewritten to `"MS Access;"` before the database is opened, matching the VB6 behaviour. Used together with [**DatabaseName**](#databasename), [**Exclusive**](#exclusive), [**ReadOnly**](#readonly), and [**Options**](#options). + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a Data control. Always **vbDataControl**. + +### Database +{: .no_toc } + +The currently open DAO database. Read-only — assign to [**Recordset**](#recordset) or call [**Refresh**](#refresh) to change it. + +### DatabaseName +{: .no_toc } + +The path to the database file (for **vbUseJet** and **vbUseACE**) or the DSN (for **vbUseODBC**). **String**. Combined with [**Connect**](#connect), [**Exclusive**](#exclusive), [**ReadOnly**](#readonly), and [**Options**](#options) to open the database the first time the control is realised, or whenever [**Refresh**](#refresh) is called. + +### DefaultCursorType +{: .no_toc } + +The cursor driver to use when [**DefaultType**](#defaulttype) is **vbUseODBC**. A member of [**DefaultCursorTypeConstants**](../../VBRUN/Constants/DefaultCursorTypeConstants): **vbUseDefaultCursor** (0, default), **vbUseODBCCursor** (1), or **vbUseServersideCursor** (2). Ignored for Jet and ACE connections. + +### DefaultType +{: .no_toc } + +The database engine to use. A member of [**DatabaseTypeConstants**](../../VBRUN/Constants/DatabaseTypeConstants): **vbUseJet** (2, default), **vbUseODBC** (1), or **vbUseACE** (3 — new in twinBASIC, uses the Access ACE engine). Read once when the recordset is opened. + +### 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 **Data** control still shows its caption but draws the navigation buttons dimmed and ignores keyboard and mouse interaction. **Boolean**, default **True**. + +### EOFAction +{: .no_toc } + +Controls what happens when the user moves past the end of the recordset. A member of [**DataEOFConstants**](../../VBRUN/Constants/DataEOFConstants): **vbMoveLast** (0, default — snap back to the last record), **vbEOF** (1 — sit on the end-of-file marker), or **vbAddNew** (2 — clear all bound controls and start a new record ready for editing). + +### Exclusive +{: .no_toc } + +When **True**, the database is opened with exclusive access (no other process or **Data** control can open it). **Boolean**, default **False**. + +### Font +{: .no_toc } + +The **StdFont** used to render [**Caption**](#caption). The convenience properties **FontName**, **FontSize**, **FontBold**, **FontItalic**, **FontStrikethru**, and **FontUnderline** read or write the corresponding members of this object. + +### ForeColor +{: .no_toc } + +The text colour for the caption, as an **OLE_COLOR**. Defaults to the system window-text colour. A disabled control draws the caption in the system grey-text colour instead. + +### Height +{: .no_toc } + +The control's height, in twips by default (or in the container's **ScaleMode** units). **Single**. + +### hWnd +{: .no_toc } + +The Win32 window handle for the underlying control, as a **LongPtr**. Read-only. Useful for passing to API functions. + +### Index +{: .no_toc } + +When the control is part of a control array, the **Long** zero-based index of this instance within the array. Read-only at run time. + +### Left +{: .no_toc } + +The horizontal distance from the left edge of the container to the left edge of the control. **Single**. + +### MouseIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor when [**MousePointer**](#mousepointer) is **vbCustom** and the pointer is over the control. + +### MousePointer +{: .no_toc } + +The mouse cursor shown when the pointer is over the control. A member of [**MousePointerConstants**](../../VBRUN/Constants/MousePointerConstants). + +### Name +{: .no_toc } + +The unique design-time name of the control on its parent form. Read-only at run time. + +### Negotiate +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### 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 **Data** control. + +### Options +{: .no_toc } + +A bit-mask of DAO **OpenRecordset** options (e.g. `dbReadOnly`, `dbAppendOnly`, `dbDenyWrite`). **Long**, default `0`. Read once when the recordset is opened. + +### Parent +{: .no_toc } + +A reference to the **Form** (or **UserControl**) that contains this control. Read-only. + +### ReadOnly +{: .no_toc } + +When **True**, the database is opened read-only and edits to bound fields are prevented. **Boolean**, default **False**. Note that this is a reserved word in twinBASIC and must be referenced through a member access (`Data1.ReadOnly`) or escaped (`[ReadOnly]`) in declarations. + +### Recordset +{: .no_toc } + +The DAO recordset currently driving the bound controls. **Object** (a `DAO.Recordset` at run time). + +Syntax: *object*.**Recordset** [ = *recordset* ] + +Reading **Recordset** returns the open recordset, or **Nothing** if the control has not yet connected. Setting **Recordset** with **Set** detaches from the current database, adopts the supplied recordset (and its parent database), copies its [**DatabaseName**](#databasename), [**Connect**](#connect), [**ReadOnly**](#readonly), [**RecordsetType**](#recordsettype), and [**RecordSource**](#recordsource) values back onto the control, re-binds every dependent field, and raises [**Reposition**](#reposition). + +### RecordsetType +{: .no_toc } + +The kind of recordset to open. A member of [**RecordsetTypeConstants**](../../VBRUN/Constants/RecordsetTypeConstants): **vbRSTypeTable** (0), **vbRSTypeDynaset** (1, default), or **vbRSTypeSnapShot** (2). Read once when the recordset is opened. + +### RecordSource +{: .no_toc } + +The table name, query name, or SQL statement that supplies the recordset. **String**. Read once when the recordset is opened. + +### RightToLeft +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### TabIndex +{: .no_toc } + +The position of the control in the form's TAB-key navigation order. **Long**. + +### TabStop +{: .no_toc } + +Whether the user can reach the control by pressing the **TAB** key. **Boolean**, default **True**. A disabled control is skipped regardless of this setting. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the control. Ignored by the framework. + +### ToolTipText +{: .no_toc } + +A multi-line **String** displayed as a tooltip when the user hovers over the control. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the control. **Single**. + +### 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 navigation buttons. **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 control's width. **Single**. + +## Methods + +### Drag +{: .no_toc } + +Begins, completes, or cancels a manual drag-and-drop operation. Typically called from a [**MouseDown**](#mousedown) handler when [**DragMode**](#dragmode) is **vbManual**. + +Syntax: *object*.**Drag** [ *Action* ] + +*Action* +: *optional* A member of [**DragConstants**](../../VBRUN/Constants/DragConstants): **vbCancel** (0), **vbBeginDrag** (1, default), or **vbEndDrag** (2). + +### Move +{: .no_toc } + +Repositions and optionally resizes the control in a single call. + +Syntax: *object*.**Move** *Left* [, *Top* [, *Width* [, *Height* ] ] ] + +*Left* +: *required* A **Single** giving the new horizontal position. + +*Top*, *Width*, *Height* +: *optional* New values for the corresponding properties. Omitted values are left unchanged. + +### OLEDrag +{: .no_toc } + +Initiates an OLE drag operation from the control, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject**. + +Syntax: *object*.**OLEDrag** + +### Refresh +{: .no_toc } + +Saves any pending edits in bound controls, closes the current recordset, and reopens it from the current values of [**DatabaseName**](#databasename), [**Connect**](#connect), [**RecordSource**](#recordsource), [**RecordsetType**](#recordsettype), [**Exclusive**](#exclusive), [**ReadOnly**](#readonly), and [**Options**](#options). Bound controls are then re-synced and [**Reposition**](#reposition) is raised. + +Syntax: *object*.**Refresh** + +### SetFocus +{: .no_toc } + +Moves the input focus to the control. The control must be both [**Visible**](#visible) and [**Enabled**](#enabled), or run-time error 5 (*Invalid procedure call or argument*) is raised. + +Syntax: *object*.**SetFocus** + +### ShowWhatsThis +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +Displays the topic identified by [**WhatsThisHelpID**](#whatsthishelpid) as a "What's This?" pop-up. + +Syntax: *object*.**ShowWhatsThis** + +### UpdateControls +{: .no_toc } + +Re-reads the values of the current record into every bound control, discarding any unsaved edits. Useful as a manual "revert" when validation has rejected an edit. Does not raise [**Reposition**](#reposition). + +Syntax: *object*.**UpdateControls** + +### UpdateRecord +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. In VB6 this saves bound-control edits to the recordset without firing [**Validate**](#validate). Until it is implemented, force a save by calling **Recordset.Update** directly, or trigger a navigation/refresh that goes through the [validate / save cycle](#the-validate--save-cycle). + +Syntax: *object*.**UpdateRecord** + +### 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 + +### 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** ) + +### Error +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently raised in twinBASIC. In VB6 this event is raised when an asynchronous DAO operation fails outside of a code path the application can intercept; it is not needed for synchronous errors that surface through normal `On Error` handling. + +Syntax: *object*\_**Error**( *DataErr* **As Integer**, *Response* **As Integer** ) + +### Initialize +{: .no_toc } + +Raised once, immediately after the underlying window is created and before the recordset is opened. Useful for setting [**DatabaseName**](#databasename), [**RecordSource**](#recordsource), or [**Connect**](#connect) from code in time for the first connection. New in twinBASIC — VB6 had no equivalent on the **Data** control. + +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** ) + +### MouseWheel +{: .no_toc } + +Raised when the mouse wheel turns over the control. 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** ) + +### Reposition +{: .no_toc } + +Raised after the current record has changed — through a navigation button, a programmatic move on [**Recordset**](#recordset), an assignment to **Recordset**, or [**Refresh**](#refresh) — and after every bound control has been re-synced to the new record. The point at which to update derived UI such as a "Record *n* of *m*" caption. + +Syntax: *object*\_**Reposition**( ) + +### Resize +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently raised in twinBASIC. + +Syntax: *object*\_**Resize**( ) + +### Validate +{: .no_toc } + +Raised before any operation that would leave the current record — a navigation button, a programmatic move, **Update**, **Delete**, **Refresh**, **Find**, an **AddNew**, an explicit close, or unloading the form. **Default event.** + +Syntax: *object*\_**Validate**( *Action* **As Integer**, *Save* **As Integer** ) + +*Action* +: A member of [**DataValidateConstants**](../../VBRUN/Constants/DataValidateConstants) identifying the operation that triggered validation. Setting *Action* to **vbDataActionCancel** (0) cancels the operation and keeps the current record. + +*Save* +: Non-zero on entry when bound controls hold unsaved edits. Set it to zero before returning to discard those edits without writing them back; leave it non-zero to flush them into the recordset before the operation proceeds. diff --git a/docs/Reference/VB/DirListBox/index.md b/docs/Reference/VB/DirListBox/index.md new file mode 100644 index 0000000..920da82 --- /dev/null +++ b/docs/Reference/VB/DirListBox/index.md @@ -0,0 +1,486 @@ +--- +title: DirListBox +parent: VB Package +permalink: /tB/Packages/VB/DirListBox/ +has_toc: false +--- + +# DirListBox class +{: .no_toc } + +A **DirListBox** is a Win32 native list control that displays the directory tree for a single path: the ancestors of the current folder are shown above (each with a closed-folder icon, indented by depth), and the immediate subdirectories of the current folder appear below (each with an open-folder icon at full indent). Double-clicking an entry navigates into it, raising a [**Change**](#change) event. The control is normally placed on a **Form** or **UserControl** at design time alongside a [**DriveListBox**](../DriveListBox) and a [**FileListBox**](../FileListBox), wiring their **Change** events together to drive a complete file picker. The default property is [**Path**](#path) and the default event is [**Change**](#change). + +```tb +Private Sub Form_Load() + Drive1.Drive = "C:\" + Dir1.Path = Drive1.Drive + File1.Path = Dir1.Path +End Sub + +Private Sub Drive1_Change() + Dir1.Path = Drive1.Drive +End Sub + +Private Sub Dir1_Change() + File1.Path = Dir1.Path +End Sub +``` + +* TOC +{:toc} + +## Path, ListIndex, and PathSelected + +The control is built around three closely-related properties: + +- [**Path**](#path) — the absolute path of the *current* directory. Set it from code (or by double-clicking an entry) to navigate the list. Defaults to [**App.Path**](../../AppGlobalClassProject/App#path) when the control is first created. +- [**ListIndex**](#listindex) — which entry the user has *selected*. `-1` selects the current folder itself (the deepest of the ancestor entries); `0` and up select successive subdirectories. Selecting an entry is independent of navigating to it — the selection just moves the highlight. +- [**PathSelected**](#pathselected) — the absolute path that would become **Path** if the selected entry were activated. For an ancestor entry it walks back up the tree; for a subdirectory it concatenates **Path** and the entry's name. + +Activating an entry — by double-clicking, or by an external caller assigning **Path** — runs the navigation, repopulates the list, and raises [**Change**](#change). Setting **Path** to its current value is a no-op (no event). + +## List, ListCount, and NewIndex + +[**ListCount**](#listcount) is the number of subdirectories of the current folder (it does *not* include the ancestor entries shown above). [**List**](#list) is indexed from zero through `ListCount - 1` and returns the *full path* of the corresponding subdirectory — handy when iterating from code: + +```tb +Dim i As Long +For i = 0 To Dir1.ListCount - 1 + Debug.Print Dir1.List(i) +Next +``` + +[**NewIndex**](#newindex) tracks the position the most recent entry (ancestor or subdirectory) was inserted at while the list was being populated; it is rarely useful at run time but is read by some compatibility code. + +[**TopIndex**](#topindex) controls vertical scrolling within the subdirectory portion of the list. Wheel and scroll-bar interactions raise [**Scroll**](#scroll) when [**WheelScrollEvent**](#wheelscrollevent) is **True**. + +## Properties + +### 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) to choose between a flat single-line border and a sunken client edge. + +### BackColor +{: .no_toc } + +The background colour, as an **OLE_COLOR**. Defaults to the system window-background colour. Used as the fill behind every list item except the selected one (which paints with the system highlight colour). + +### BorderStyle +{: .no_toc } + +A member of [**ControlBorderStyleConstants**](../../VBRUN/Constants/ControlBorderStyleConstants): **vbNoBorder** (0) or **vbFixedSingleBorder** (1, default). Combined with [**Appearance**](#appearance): a 3-D appearance plus single border yields the standard sunken client edge; flat appearance plus single border yields a one-pixel outline. + +### CausesValidation +{: .no_toc } + +Determines whether the previously focused control's [**Validate**](#validate) event runs before this control receives the focus. **Boolean**, default **True**. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a directory list box. Always **vbDirListBox**. + +### 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 directory 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 directory names. 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**. + +### 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 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. 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. **Boolean**. Changing this at run time recreates the underlying window. + +### 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 full path of the subdirectory at the given index. Read-only. + +Syntax: *object*.**List**( *Index* ) + +*Index* +: *required* A **Long** zero-based position, from `0` to `ListCount - 1`. The ancestor entries shown above the current folder are not addressable through **List**. + +### ListCount +{: .no_toc } + +The number of subdirectories of the current [**Path**](#path), as a **Long**. Read-only. The ancestor entries shown above the current folder are not counted. + +### ListIndex +{: .no_toc } + +The zero-based index of the selected entry within the subdirectory portion of the list, or `-1` to select the current folder itself. Reading or writing values below `-1` shifts further up the ancestor stack. **Long**. Assigning a value that differs from the current one selects that entry and raises [**Click**](#click). + +### 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. + +### NewIndex +{: .no_toc } + +The zero-based index at which the most recent list-population step inserted an entry, or `-1` if the list is empty. **Long**, read-only. + +### OLEDragMode +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. (VB6's own implementation of automatic drag was non-functional on this control.) + +### 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 DirListBox. + +### 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** (or **UserControl**) that contains this control. Read-only. + +### Path +{: .no_toc } + +The absolute path of the current directory. **Default property.** + +Syntax: *object*.**Path** [ = *string* ] + +Reading **Path** returns the path the list is currently displaying — drive plus joined ancestor names. Setting **Path** repopulates the list to show the new directory and its subdirectories, raising [**Change**](#change) if the new value differs from the current one. Assigning a path that does not exist (or is not a directory) raises run-time error 76 (*Path not found*). + +The **DriveListBox** and **DirListBox** controls accept each other's "drive [volume label]" formatting at this property — `Dir1.Path = Drive1.Drive` does the right thing without manual stripping. + +### PathSelected +{: .no_toc } + +The absolute path that the currently-selected entry refers to. **String**, read-only. For [**ListIndex**](#listindex) `-1` (the current folder) this is the same as [**Path**](#path); for an ancestor entry it walks back up the tree; for a subdirectory it returns **Path** plus the subdirectory's name. This is the value the control assigns to **Path** when the user double-clicks the selected entry. + +### TabIndex +{: .no_toc } + +The position of the control in the form's TAB-key navigation order. **Long**. + +### TabStop +{: .no_toc } + +Whether the user can reach the control by pressing the **TAB** key. **Boolean**, default **True**. A disabled control is skipped regardless of this setting. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the control. Ignored by the framework. + +### ToolTipText +{: .no_toc } + +A multi-line **String** displayed as a tooltip when the user hovers over the control. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the control. **Single**. + +### TopIndex +{: .no_toc } + +The zero-based index of the subdirectory shown at the top of the visible area. Assigning a value scrolls the list so that subdirectory is at the top, and raises [**Scroll**](#scroll) when the value actually changes. **Long**. + +### TransparencyKey +{: .no_toc } + +An **OLE_COLOR** that, when set, becomes fully transparent in the rendered control. Default `-1` disables the effect. Requires Windows 8 or later for child controls. + +### Visible +{: .no_toc } + +Whether the control is shown. **Boolean**, default **True**. + +### VisualStyles +{: .no_toc } + +Whether the OS theme engine should be used when drawing the control. **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). + +### 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**. + +## Methods + +### Drag +{: .no_toc } + +Begins, completes, or cancels a manual drag-and-drop operation. Typically called from a [**MouseDown**](#mousedown) handler when [**DragMode**](#dragmode) is **vbManual**. + +Syntax: *object*.**Drag** [ *Action* ] + +*Action* +: *optional* A member of [**DragConstants**](../../VBRUN/Constants/DragConstants): **vbCancel** (0), **vbBeginDrag** (1, default), or **vbEndDrag** (2). + +### Move +{: .no_toc } + +Repositions and optionally resizes the control in a single call. + +Syntax: *object*.**Move** *Left* [, *Top* [, *Width* [, *Height* ] ] ] + +*Left* +: *required* A **Single** giving the new horizontal position. + +*Top*, *Width*, *Height* +: *optional* New values for the corresponding properties. Omitted values are left unchanged. + +### OLEDrag +{: .no_toc } + +Initiates an OLE drag operation from the control, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject**. + +Syntax: *object*.**OLEDrag** + +### Refresh +{: .no_toc } + +Re-reads the contents of the current [**Path**](#path) from disk and repaints the control. Useful when the directory has been modified outside the application — the control does not watch the file system on its own. Does not raise [**Change**](#change). + +Syntax: *object*.**Refresh** + +### SetFocus +{: .no_toc } + +Moves the input focus to the control. The control must be both [**Visible**](#visible) and [**Enabled**](#enabled), or run-time error 5 (*Invalid procedure call or argument*) is raised. + +Syntax: *object*.**SetFocus** + +### ShowWhatsThis +{: .no_toc } + +Displays the topic identified by [**WhatsThisHelpID**](#whatsthishelpid) as a "What's This?" pop-up. + +Syntax: *object*.**ShowWhatsThis** + +### ZOrder +{: .no_toc } + +Brings the control to the front or back of its sibling stack. + +Syntax: *object*.**ZOrder** [ *Position* ] + +*Position* +: *optional* A member of [**ZOrderConstants**](../../VBRUN/Constants/ZOrderConstants): **vbBringToFront** (0, default) or **vbSendToBack** (1). + +## Events + +### Change +{: .no_toc } + +Raised after [**Path**](#path) has changed — whether the user double-clicked an entry or code assigned a different value to **Path**. Not raised for assignments that match the current value, and not raised during the initial population that occurs before [**Initialize**](#initialize). **Default event.** + +Syntax: *object*\_**Change**( ) + +### Click +{: .no_toc } + +Raised after [**ListIndex**](#listindex) changes — whether the user clicked a different entry, used the keyboard to move the selection, or code assigned a different value to [**ListIndex**](#listindex). Also raised when the selection is cancelled (e.g. by clicking the empty area below the last entry). + +Syntax: *object*\_**Click**( ) + +### 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 initial path ([**App.Path**](../../AppGlobalClassProject/App#path)) has been loaded. New in twinBASIC — VB6 had no equivalent on this control. + +Syntax: *object*\_**Initialize**( ) + +### KeyDown +{: .no_toc } + +Raised when the user presses any key while the control has focus. + +Syntax: *object*\_**KeyDown**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### KeyPress +{: .no_toc } + +Raised when the user types a character that produces an ANSI keystroke. + +Syntax: *object*\_**KeyPress**( *KeyAscii* **As Integer** ) + +### KeyUp +{: .no_toc } + +Raised when the user releases a key while the control has focus. + +Syntax: *object*\_**KeyUp**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### LostFocus +{: .no_toc } + +Raised when the control loses the input focus. + +Syntax: *object*\_**LostFocus**( ) + +### MouseDown +{: .no_toc } + +Raised when the user presses any mouse button over the control. + +Syntax: *object*\_**MouseDown**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseMove +{: .no_toc } + +Raised when the cursor moves over the control. + +Syntax: *object*\_**MouseMove**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseUp +{: .no_toc } + +Raised when the user releases a mouse button over the control. + +Syntax: *object*\_**MouseUp**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### OLECompleteDrag +{: .no_toc } + +Raised on the source control when the OLE drag operation finishes, indicating which effect (copy, move, none) the destination accepted. + +Syntax: *object*\_**OLECompleteDrag**( *Effect* **As Long** ) + +### OLEDragDrop +{: .no_toc } + +Raised on the destination control when the user drops data on it. + +Syntax: *object*\_**OLEDragDrop**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### OLEDragOver +{: .no_toc } + +Raised on the destination control while an OLE drag passes over it. + +Syntax: *object*\_**OLEDragOver**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### OLEGiveFeedback +{: .no_toc } + +Raised on the source control during a drag so the application can adjust the cursor or other visual feedback. + +Syntax: *object*\_**OLEGiveFeedback**( *Effect* **As Long**, *DefaultCursors* **As Boolean** ) + +### OLESetData +{: .no_toc } + +Raised on the source control when the destination requests data in a format that was registered but not yet supplied. + +Syntax: *object*\_**OLESetData**( *Data* **As DataObject**, *DataFormat* **As Integer** ) + +### OLEStartDrag +{: .no_toc } + +Raised on the source control at the start of an OLE drag, so the application can populate the **DataObject** and choose the allowed effects. + +Syntax: *object*\_**OLEStartDrag**( *Data* **As DataObject**, *AllowedEffects* **As Long** ) + +### 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/FileListBox/index.md b/docs/Reference/VB/FileListBox/index.md new file mode 100644 index 0000000..40840d4 --- /dev/null +++ b/docs/Reference/VB/FileListBox/index.md @@ -0,0 +1,592 @@ +--- +title: FileListBox +parent: VB Package +permalink: /tB/Packages/VB/FileListBox/ +has_toc: false +--- + +# FileListBox class +{: .no_toc } + +A **FileListBox** is a Win32 native list control that displays the files in a single directory, filtered by a wildcard pattern and a set of file-attribute toggles. It is normally placed on a **Form** or **UserControl** at design time and paired with a [**DriveListBox**](../DriveListBox) and a [**DirListBox**](../DirListBox) to make a complete file picker — wire their **Change** events through to **FileListBox.Path** and let the user pick a name from the list. The default property is [**FileName**](#filename) and the default event is [**Click**](#click). + +```tb +Private Sub Form_Load() + Drive1.Drive = "C:\" + Dir1.Path = Drive1.Drive + File1.Path = Dir1.Path + File1.Pattern = "*.txt;*.log" +End Sub + +Private Sub Drive1_Change() + Dir1.Path = Drive1.Drive +End Sub + +Private Sub Dir1_Change() + File1.Path = Dir1.Path +End Sub + +Private Sub File1_DblClick() + OpenFile File1.PathWithBackslash & File1.FileName +End Sub +``` + +* TOC +{:toc} + +## Path and Pattern + +[**Path**](#path) is the directory whose files are listed. It defaults to [**App.Path**](../../AppGlobalClassProject/App#path) when the control is first created. Setting it from code reloads the list, raises [**PathChange**](#pathchange), and trims any trailing backslash (except for a drive root). Setting a bare drive specifier without a backslash — `"C:"` — is silently rejected; use `"C:\"`. Assigning a path that does not exist raises run-time error 76 (*Path not found*). [**PathWithBackslash**](#pathwithbackslash) returns the same value with a trailing backslash always present, which is convenient when concatenating with [**FileName**](#filename). + +[**Pattern**](#pattern) is one or more wildcard masks separated by semicolons (`"*.txt;*.doc"`). Each mask is matched case-insensitively using the **Like** operator; a file is shown if it matches *any* mask. The default is `"*.*"`. Setting **Pattern** reloads the list and raises [**PatternChange**](#patternchange) when the new value differs from the previous one. + +## File-attribute filters + +Five **Boolean** properties decide which files are included after the pattern matches: + +| Property | Meaning when **True** (default in **bold**) | +|-------------------------------|-----------------------------------------------------------------------------------| +| [**Archive**](#archive) | **Include files with the archive bit set.** | +| [**Hidden**](#hidden) | Include hidden files. | +| [**Normal**](#normal) | **Include files with no special attributes.** | +| [**ReadOnly**](#readonly) | **Include read-only files.** | +| [**System**](#system) | Include system files. | + +A file passes if every attribute it carries is permitted. **Normal** is the odd one out: it gates files that carry *no* attribute at all, so setting **Normal = False** with the others left at their defaults restricts the list to files that explicitly have one of the included attributes. Changing any of these reloads the list and raises [**PatternChange**](#patternchange) — the event is shared with [**Pattern**](#pattern), matching the VB6 behaviour even though the name is misleading. + +## Selecting files + +[**MultiSelect**](#multiselect) chooses among single-, simple-, and extended-selection ([**MultiSelectConstants**](../../VBRUN/Constants/MultiSelectConstants)). Changing it recreates the underlying window (the path, pattern, and current selection are restored automatically). + +[**ListIndex**](#listindex) gives or sets the focused entry (`-1` for none), and [**FileName**](#filename) returns its text. [**Selected**](#selected) reads or writes the selection state of any individual item; [**SelCount**](#selcount) counts how many items are currently selected; [**SelectedIndices**](#selectedindices) returns them as a **Collection**: + +```tb +Dim idx As Variant +For Each idx In File1.SelectedIndices() + Debug.Print File1.PathWithBackslash & File1.List(idx) +Next +``` + +## OLE drag and drop + +When [**OLEDragMode**](#oledragmode) is set to **vbOLEDragAutomatic**, dragging the selected entry (or entries, in multi-select mode) starts an OLE drag whose data is the corresponding full path or paths. [**OLEDropMode**](#oledropmode) controls drop-target behaviour and is restricted to **vbOLEDropNone** or **vbOLEDropManual**. + +## Properties + +### 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) to choose between a flat single-line border and a sunken client edge. + +### Archive +{: .no_toc } + +When **True** (default), files with the archive attribute are included in the list. **Boolean**. Changing this reloads the list and raises [**PatternChange**](#patternchange). + +### BackColor +{: .no_toc } + +The background colour, as an **OLE_COLOR**. Defaults to the system window-background colour. + +### BorderStyle +{: .no_toc } + +A member of [**ControlBorderStyleConstants**](../../VBRUN/Constants/ControlBorderStyleConstants): **vbNoBorder** (0) or **vbFixedSingleBorder** (1, default). Combined with [**Appearance**](#appearance): a 3-D appearance plus single border yields the standard sunken client edge; flat appearance plus single border yields a one-pixel outline. + +### CausesValidation +{: .no_toc } + +Determines whether the previously focused control's [**Validate**](#validate) event runs before this control receives the focus. **Boolean**, default **True**. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a file list box. Always **vbFileListBox**. + +### 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 file list box still shows its contents but is dimmed and ignores keyboard and mouse interaction. **Boolean**, default **True**. + +### FileName +{: .no_toc } + +The name of the file at the current [**ListIndex**](#listindex), without any leading path. **Default property.** + +Syntax: *object*.**FileName** [ = *string* ] + +Reading **FileName** returns the text of the highlighted entry, or an empty string when [**ListIndex**](#listindex) is `-1`. Setting **FileName** searches the list for an exact, case-insensitive match and selects that entry if found; if no entry matches, the assignment has no visible effect. + +### Font +{: .no_toc } + +The **StdFont** used to render file names. 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**. + +### 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 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. + +### Hidden +{: .no_toc } + +When **True**, files with the hidden attribute are included in the list. **Boolean**, default **False**. Changing this reloads the list and raises [**PatternChange**](#patternchange). + +### 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. 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. **Boolean**. Changing this at run time recreates the underlying window. + +### 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. Read-only. + +Syntax: *object*.**List**( *Index* ) + +*Index* +: *required* A **Long** zero-based item position. + +### ListCount +{: .no_toc } + +The number of files currently shown 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). + +### 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 current path, pattern, top-index, and focused item are restored, but multi-item selections are not. + +### Name +{: .no_toc } + +The unique design-time name of the control on its parent form. Read-only at run time. + +### Normal +{: .no_toc } + +When **True** (default), files with no attribute bits set are included in the list. When **False**, only files that explicitly carry one of the other included attributes are shown. **Boolean**. Changing this reloads the list and raises [**PatternChange**](#patternchange). + +### 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 entry starts an OLE drag whose **Text** data is the full path of the selected file, or a list of paths 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 FileListBox. + +### 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** (or **UserControl**) that contains this control. Read-only. + +### Path +{: .no_toc } + +The directory whose files are listed. **String**. Defaults to [**App.Path**](../../AppGlobalClassProject/App#path) when the control is first created. + +Syntax: *object*.**Path** [ = *string* ] + +Reading **Path** returns the directory currently shown — without a trailing backslash (except for a drive root, which is always returned as `"C:\"`). Setting **Path** reloads the list and raises [**PathChange**](#pathchange) when the new value differs from the current one. A bare drive specifier with no backslash (`"C:"`) is silently rejected; use `"C:\"`. Assigning a path that does not exist raises run-time error 76 (*Path not found*). + +### PathWithBackslash +{: .no_toc } + +The same value as [**Path**](#path), but always with a trailing backslash. **String**, read-only. Convenient for concatenating with [**FileName**](#filename) to build a full path. + +### Pattern +{: .no_toc } + +The wildcard mask, or semicolon-separated list of masks, used to filter the file list. **String**, default `"*.*"`. + +Syntax: *object*.**Pattern** [ = *string* ] + +A file is shown if it matches *any* of the masks (case-insensitively, using the **Like** operator). Setting an empty string is treated as `"*.*"`. Changing **Pattern** reloads the list and raises [**PatternChange**](#patternchange) when the new value differs from the current one. + +```tb +File1.Pattern = "*.txt;*.log" ' .txt or .log files +``` + +### ReadOnly +{: .no_toc } + +When **True** (default), files with the read-only attribute are included in the list. **Boolean**. Changing this reloads the list and raises [**PatternChange**](#patternchange). Note that **ReadOnly** is a reserved word in twinBASIC and must be referenced through a member access (`File1.ReadOnly`) or escaped (`[ReadOnly]`) in declarations. + +### SelCount +{: .no_toc } + +The number of items currently selected, as a **Long**. Read-only. Equal to `0` or `1` when [**MultiSelect**](#multiselect) is **vbMultiSelectNone**. + +### Selected +{: .no_toc } + +The selection state of an individual item. + +Syntax: *object*.**Selected**( *Index* ) [ = *boolean* ] + +*Index* +: *required* A **Long** zero-based item position. + +Reading **Selected(*Index*)** returns **True** when that item is selected. Assigning a value that differs from the current one updates the selection and raises [**Click**](#click); in single-select mode (**vbMultiSelectNone**) assigning **True** focuses the item, and assigning **False** has no observable effect. + +### System +{: .no_toc } + +When **True**, files with the system attribute are included in the list. **Boolean**, default **False**. Changing this reloads the list and raises [**PatternChange**](#patternchange). + +### TabIndex +{: .no_toc } + +The position of the control in the form's TAB-key navigation order. **Long**. + +### TabStop +{: .no_toc } + +Whether the user can reach the control by pressing the **TAB** key. **Boolean**, default **True**. A disabled control is skipped regardless of this setting. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the control. Ignored by the framework. + +### ToolTipText +{: .no_toc } + +A multi-line **String** displayed as a tooltip when the user hovers over the control. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the control. **Single**. + +### TopIndex +{: .no_toc } + +The zero-based index of the item shown at the top of the visible area. Assigning a value scrolls the list so that item is at the top, and raises [**Scroll**](#scroll) when the value actually changes. **Long**. + +### TransparencyKey +{: .no_toc } + +An **OLE_COLOR** that, when set, becomes fully transparent in the rendered control. Default `-1` disables the effect. Requires Windows 8 or later for child controls. + +### Visible +{: .no_toc } + +Whether the control is shown. **Boolean**, default **True**. + +### VisualStyles +{: .no_toc } + +Whether the OS theme engine should be used when drawing the control. **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). + +### 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**. + +## Methods + +### Drag +{: .no_toc } + +Begins, completes, or cancels a manual drag-and-drop operation. Typically called from a [**MouseDown**](#mousedown) handler when [**DragMode**](#dragmode) is **vbManual**. + +Syntax: *object*.**Drag** [ *Action* ] + +*Action* +: *optional* A member of [**DragConstants**](../../VBRUN/Constants/DragConstants): **vbCancel** (0), **vbBeginDrag** (1, default), or **vbEndDrag** (2). + +### Move +{: .no_toc } + +Repositions and optionally resizes the control in a single call. + +Syntax: *object*.**Move** *Left* [, *Top* [, *Width* [, *Height* ] ] ] + +*Left* +: *required* A **Single** giving the new horizontal position. + +*Top*, *Width*, *Height* +: *optional* New values for the corresponding properties. Omitted values are left unchanged. + +### OLEDrag +{: .no_toc } + +Initiates an OLE drag operation from the control, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject**. + +Syntax: *object*.**OLEDrag** + +### Refresh +{: .no_toc } + +Re-reads the contents of the current [**Path**](#path) from disk and repaints the control. Useful when the directory has been modified outside the application — the control does not watch the file system on its own. Does not raise [**PathChange**](#pathchange) or [**PatternChange**](#patternchange). + +Syntax: *object*.**Refresh** + +### 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 File1.SelectedIndices() + Debug.Print File1.PathWithBackslash & File1.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 selection is cancelled. **Default event.** + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks an entry. Unlike [**DirListBox**](../DirListBox), the **FileListBox** does *not* navigate on double-click — typically the application listens for **DblClick** to open the file the user has chosen. + +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 initial list of files has been loaded from [**App.Path**](../../AppGlobalClassProject/App#path). New in twinBASIC — VB6 had no equivalent on this control. + +Syntax: *object*\_**Initialize**( ) + +### KeyDown +{: .no_toc } + +Raised when the user presses any key while the control has focus. + +Syntax: *object*\_**KeyDown**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### KeyPress +{: .no_toc } + +Raised when the user types a character that produces an ANSI keystroke. + +Syntax: *object*\_**KeyPress**( *KeyAscii* **As Integer** ) + +### KeyUp +{: .no_toc } + +Raised when the user releases a key while the control has focus. + +Syntax: *object*\_**KeyUp**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### LostFocus +{: .no_toc } + +Raised when the control loses the input focus. + +Syntax: *object*\_**LostFocus**( ) + +### MouseDown +{: .no_toc } + +Raised when the user presses any mouse button over the control. + +Syntax: *object*\_**MouseDown**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseMove +{: .no_toc } + +Raised when the cursor moves over the control. + +Syntax: *object*\_**MouseMove**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseUp +{: .no_toc } + +Raised when the user releases a mouse button over the control. + +Syntax: *object*\_**MouseUp**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### OLECompleteDrag +{: .no_toc } + +Raised on the source control when the OLE drag operation finishes, indicating which effect (copy, move, none) the destination accepted. + +Syntax: *object*\_**OLECompleteDrag**( *Effect* **As Long** ) + +### OLEDragDrop +{: .no_toc } + +Raised on the destination control when the user drops data on it. + +Syntax: *object*\_**OLEDragDrop**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### OLEDragOver +{: .no_toc } + +Raised on the destination control while an OLE drag passes over it. + +Syntax: *object*\_**OLEDragOver**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### OLEGiveFeedback +{: .no_toc } + +Raised on the source control during a drag so the application can adjust the cursor or other visual feedback. + +Syntax: *object*\_**OLEGiveFeedback**( *Effect* **As Long**, *DefaultCursors* **As Boolean** ) + +### OLESetData +{: .no_toc } + +Raised on the source control when the destination requests data in a format that was registered but not yet supplied. + +Syntax: *object*\_**OLESetData**( *Data* **As DataObject**, *DataFormat* **As Integer** ) + +### OLEStartDrag +{: .no_toc } + +Raised on the source control at the start of an OLE drag, so the application can populate the **DataObject** and choose the allowed effects. 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** ) + +### PathChange +{: .no_toc } + +Raised after [**Path**](#path) has changed — typically because code assigned a new value to it. Not raised for assignments that match the current value. + +Syntax: *object*\_**PathChange**( ) + +### PatternChange +{: .no_toc } + +Raised after [**Pattern**](#pattern) has changed *or* after one of the file-attribute filter properties — [**Archive**](#archive), [**Hidden**](#hidden), [**Normal**](#normal), [**ReadOnly**](#readonly), [**System**](#system) — has changed. Not raised for pattern assignments that match the current value. The shared event matches the VB6 behaviour even though the name is misleading. + +Syntax: *object*\_**PatternChange**( ) + +### 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/Form/index.md b/docs/Reference/VB/Form/index.md new file mode 100644 index 0000000..688cb37 --- /dev/null +++ b/docs/Reference/VB/Form/index.md @@ -0,0 +1,1002 @@ +--- +title: Form +parent: VB Package +permalink: /tB/Packages/VB/Form/ +has_toc: false +redirect_from: + - /tB/Packages/VB/Form +--- + +# Form class +{: .no_toc } + +A **Form** is a top-level Win32 window that hosts the controls, menus, and drawing surface of a single twinBASIC user interface. Each form designed in the IDE becomes its own class derived from **Form** — its controls become members of that class, its event handlers become methods on it, and the file's name becomes the class name. Code outside the form normally instantiates it implicitly through the global default-instance reference (`MyForm.Show`) or explicitly with `New MyForm`. The default property is [**Controls**](#controls) and the default event is [**Load**](#load). + +```tb +' In Form1's code-behind: +Private Sub Form_Load() + Caption = "Welcome" + Me.MinWidth = 4000 ' twips, ≈ 2 inches + Me.MinHeight = 3000 +End Sub + +Private Sub Form_QueryUnload(Cancel As Integer, UnloadMode As Integer) + If MsgBox("Quit?", vbYesNo) = vbNo Then Cancel = 1 +End Sub + +' In a startup module: +Sub Main() + Form1.Show vbModal +End Sub +``` + +* TOC +{:toc} + +## Lifecycle + +A form goes through six distinct events from creation to destruction: + +| Event | When | +|----------------------------------|-------------------------------------------------------------------------------------| +| [**Initialize**](#initialize) | Before the underlying window exists. The form's controls are not yet created. | +| [**Load**](#load) | After the window and all controls have been created, before the form first appears. | +| [**Activate**](#activate) | When the form becomes the active window in the application. | +| [**Deactivate**](#deactivate) | When another form (or another application's window) takes activation away. | +| [**QueryUnload**](#queryunload) | Before unload. Setting *Cancel* to non-zero keeps the form open. | +| [**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. | + +Closing a form goes through both **QueryUnload** *and* **Unload**, so either can veto. The *UnloadMode* argument of **QueryUnload** ([**QueryUnloadConstants**](../../VBRUN/Constants/QueryUnloadConstants)) reports whether the user clicked the close button, code called **Unload**, Windows is shutting down, the MDI parent is closing, and so on. + +## Showing the form + +[**Show**](#show) makes the form visible. It accepts an optional [**FormShowConstants**](../../VBRUN/Constants/FormShowConstants) argument: **vbModeless** (default — the call returns immediately and the user can interact with other forms) or **vbModal** (the call blocks until the form is closed, and other forms in the application become unresponsive). MDI child forms cannot be shown modally; attempting to do so raises run-time error 404. + +```tb +dlgOptions.Show vbModal, Me ' modal, owned by the calling form +``` + +[**Hide**](#hide) and [**Close**](#close) reverse the effect: **Hide** just clears [**Visible**](#visible); **Close** runs the full unload sequence (**QueryUnload** then **Unload** then **Terminate**). The classic `Unload ` statement is the language-level equivalent of **Close**. + +[**StartUpPosition**](#startupposition) ([**StartUpPositionConstants**](../../VBRUN/Constants/StartUpPositionConstants)) is read at the first **Show** to decide where the form lands; afterwards the user (or code through [**Move**](#move) and [**WindowState**](#windowstate)) controls position. + +## Window appearance + +[**BorderStyle**](#borderstyle) ([**FormBorderStyleConstants**](../../VBRUN/Constants/FormBorderStyleConstants)) chooses between sizable, fixed, dialog, tool, and borderless frames. [**Caption**](#caption) is the title-bar text. [**ControlBox**](#controlbox), [**MaxButton**](#maxbutton), and [**MinButton**](#minbutton) toggle the system menu and resize buttons. [**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; [**ShowInTaskbar**](#showintaskbar) decides whether the form shows up in the taskbar and Alt-Tab list. + +[**Opacity**](#opacity) and [**TransparencyKey**](#transparencykey) drive Windows' layered-window features for translucent forms and cut-out shapes. + +## Drawing surface + +A **Form** is itself a graphics surface — code can draw lines, shapes, and text directly on it. The coordinate system is governed by [**ScaleMode**](#scalemode) (default **vbTwips** — the classic VB6 behaviour) and the [**ScaleLeft**](#scaleleft) / [**ScaleTop**](#scaletop) / [**ScaleWidth**](#scalewidth) / [**ScaleHeight**](#scaleheight) properties, which together describe the form's logical drawing rectangle. Setting **ScaleMode** to **vbUser** lets the four **Scale\*** properties define an arbitrary rectangle; the [**Scale**](#scale) method does this in a single call. + +The drawing primitives are [**Cls**](#cls), [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), [**PaintPicture**](#paintpicture), and the **Print** statement (`Form1.Print "Hello"`) — all use [**ForeColor**](#forecolor), [**FillColor**](#fillcolor), [**FillStyle**](#fillstyle), [**DrawWidth**](#drawwidth), [**DrawMode**](#drawmode), and [**DrawStyle**](#drawstyle) for their pen and fill, and the form's [**Font**](#font) for text. The current pen position is tracked by [**CurrentX**](#currentx) and [**CurrentY**](#currenty); [**TextWidth**](#textwidth) and [**TextHeight**](#textheight) measure a string in the current font. [**ScaleX**](#scalex) and [**ScaleY**](#scaley) convert single coordinates between scale modes. + +[**AutoRedraw**](#autoredraw) controls whether drawn output persists across paints: when **False** (default), the [**Paint**](#paint) event must redraw on every invalidation; when **True**, the form keeps an off-screen buffer that survives invalidations and the **Paint** event is suppressed. Setting [**Picture**](#picture) puts a bitmap behind the drawing layer; [**Image**](#image) returns the rendered combined surface as a **StdPicture**. + +```tb +Private Sub Form_Paint() + Me.ScaleMode = vbPixels + Me.ForeColor = vbBlue + Me.DrawWidth = 3 + Me.Line (10, 10)-(120, 80), , B ' rectangle + Me.CurrentX = 16 : Me.CurrentY = 16 + Me.Print "Hello, twinBASIC" +End Sub +``` + +## Controls and validation + +[**Controls**](#controls) is a collection of every control on the form, indexable by name or zero-based position. **Form** is also enumerable directly — `For Each ctrl In Form1` yields the same items as `For Each ctrl In Form1.Controls`. [**Count**](#count) is shorthand for `Controls.Count`. [**ActiveControl**](#activecontrol) returns the currently focused child, or **Nothing** when no control on this form has the focus. + +[**KeyPreview**](#keypreview) routes keystrokes to the form's [**KeyDown**](#keydown), [**KeyUp**](#keyup), and [**KeyPress**](#keypress) events *before* the focused control sees them — useful for application-wide hotkey handling. [**ValidateControls**](#validatecontrols) explicitly fires the active control's **Validate** event from code; it raises run-time error 380 if the validation handler sets *Cancel*. + +## Menus and pop-ups + +Menu structures designed at form-design time appear automatically in the form's title bar. [**PopUpMenu**](#popupmenu) displays one of those 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 Form_MouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single) + If Button = vbRightButton Then PopUpMenu mnuContext +End Sub +``` + +## Properties + +### ActiveControl +{: .no_toc } + +The control on this form that currently has the input focus, as a **Control** object, or **Nothing** when no control on this form is focused. Read-only. + +### 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 } + +Determines how the control's border is drawn by the OS. A member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). + +> [!NOTE] +> Retained for VB6 compatibility; the property has no observable effect on a form. + +### AutoRedraw +{: .no_toc } + +Whether drawing performed on the form persists across invalidations. **Boolean**, default **False**. + +When **False**, drawing primitives — [**Cls**](#cls), [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), [**PaintPicture**](#paintpicture), and **Print** — paint directly to the screen and the form must redraw them in its [**Paint**](#paint) event whenever the affected area is invalidated. When **True**, the form keeps an off-screen bitmap, drawing primitives paint into it (and immediately to the screen), the bitmap survives invalidations, and the **Paint** event is suppressed. Reading [**Image**](#image) returns this bitmap. + +### BackColor +{: .no_toc } + +The background colour of the form's client area, as an **OLE_COLOR**. Defaults to the system 3-D face colour. Used as the fill colour for [**Cls**](#cls) and as the canvas behind [**Picture**](#picture). + +### BorderStyle +{: .no_toc } + +The window-frame style. A member of [**FormBorderStyleConstants**](../../VBRUN/Constants/FormBorderStyleConstants): **vbBSNone**, **vbFixedSingle**, **vbSizable** (default), **vbFixedDialog**, **vbFixedToolWindow**, **vbSizableToolWindow**, **vbSizableNoTitleBar** (new in twinBASIC), or **vbSizableToolWindowNoTitleBar** (new in twinBASIC). Run-time changes are accepted but only take effect after another change to the window — typically reassigning [**Caption**](#caption). + +### Caption +{: .no_toc } + +The title-bar text. **String**. + +Syntax: *object*.**Caption** [ = *string* ] + +Setting **Caption** updates the title bar immediately and re-syncs the title-bar style flags (so it can revive a title bar that was hidden because the previous **Caption** was empty). + +### ClipControls +{: .no_toc } + +Whether child controls are clipped out of the form's drawing region during paint. **Boolean**, default **True**. Read-only at run time — set at design time. + +### ControlBox +{: .no_toc } + +Whether the form's title bar shows the system menu (and, with it, the close button). **Boolean**, default **True**. Setting it at run time re-syncs the title-bar style flags. + +### 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. + +```tb +Dim ctrl As Control +For Each ctrl In Me.Controls + ctrl.Enabled = False +Next +``` + +### Count +{: .no_toc } + +The number of controls in [**Controls**](#controls), as a **Long**. Read-only. Equivalent to `Me.Controls.Count`. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a form. Always **vbForm**. + +### CurrentX +{: .no_toc } + +The horizontal pen position, in [**ScaleMode**](#scalemode) units, used by drawing primitives that omit a starting coordinate (for example, **Print** and the rectangle form of [**Line**](#line)). **Double**. + +### CurrentY +{: .no_toc } + +The vertical pen position, in [**ScaleMode**](#scalemode) units, used by drawing primitives that omit a starting coordinate. **Double**. + +### 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. + +### DrawMode +{: .no_toc } + +The raster operation that drawing primitives apply 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. + +### DrawStyle +{: .no_toc } + +The pen line pattern used by drawing primitives. A member of [**DrawStyleConstants**](../../VBRUN/Constants/DrawStyleConstants): **vbSolid** (default), **vbDash**, **vbDot**, **vbDashDot**, **vbDashDotDot**, **vbInvisible**, or **vbInsideSolid**. + +### DrawWidth +{: .no_toc } + +The pen width in pixels for drawing primitives. **Long**, default `1`. Widths greater than 1 force [**DrawStyle**](#drawstyle) back to **vbSolid** (a Win32 GDI limitation). + +### Enabled +{: .no_toc } + +Determines whether the form accepts user input. A disabled form ignores keyboard and mouse input and dims its controls. **Boolean**, default **True**. + +### FillColor +{: .no_toc } + +The fill colour for closed shapes drawn by [**Circle**](#circle) and the rectangle form of [**Line**](#line). **OLE_COLOR**, default `0` (black). Used only when [**FillStyle**](#fillstyle) is not **vbFSTransparent**. + +### FillStyle +{: .no_toc } + +The fill pattern for closed shapes. A member of [**FillStyleConstants**](../../VBRUN/Constants/FillStyleConstants): **vbFSSolid**, **vbFSTransparent** (default), **vbHorizontalLine**, **vbVerticalLine**, **vbUpwardDiagonal**, **vbDownwardDiagonal**, **vbCross**, or **vbDiagonalCross**. + +### Font +{: .no_toc } + +The **StdFont** used by the **Print** statement and other text drawing on this form. The convenience properties **FontName**, **FontSize**, **FontBold**, **FontItalic**, **FontStrikethru**, and **FontUnderline** read or write the corresponding members of this object. + +### FontTransparent +{: .no_toc } + +When **True** (default), text drawn on the form has a transparent background, leaving the underlying drawing visible behind it. When **False**, text is drawn over an opaque rectangle filled with [**BackColor**](#backcolor). **Boolean**. + +### ForeColor +{: .no_toc } + +The pen colour used by [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), and the text drawn by **Print**. **OLE_COLOR**. + +### hDC +{: .no_toc } + +The Win32 device context handle for the form, as a **LongPtr**. Read-only. Returns `0` when the underlying window has not yet been created. Useful for passing to GDI API calls. + +### HasDC +{: .no_toc } + +Whether the form keeps a private device context (`CS_OWNDC`) for its drawing surface. **Boolean**, default **True**. Read-only at run time — set at design time. + +### Height +{: .no_toc } + +The form's outer height, in twips by default (or in the container's **ScaleMode** units). **Double**. Setting it resizes the window. 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 form, as a **LongPtr**. Read-only. Useful for passing to API functions. + +### 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 clears the icon to the default Windows application icon. + +### Image +{: .no_toc } + +Returns the rendered drawing surface as a **StdPicture**. Read-only. Most useful when [**AutoRedraw**](#autoredraw) is **True** — the returned picture is the persistent off-screen buffer. + +### KeyPreview +{: .no_toc } + +When **True**, the form's [**KeyDown**](#keydown), [**KeyUp**](#keyup), and [**KeyPress**](#keypress) events fire *before* the focused control receives the same keystroke. **Boolean**, default **False**. Useful for application-wide hotkeys; events still fire on the focused control afterwards. + +### 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 — or, for an MDI child, from the left edge of the MDI parent's client area. **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. + +### MaxButton +{: .no_toc } + +Whether the title bar shows the maximise button. **Boolean**, default **True**, read-only at run time. Set at design time. + +### 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. + +### MDIChild +{: .no_toc } + +When **True**, the form is hosted as a child inside an [**MDIForm**](../MDIForm). **Boolean**, read-only — set at design time. An MDI child form cannot be shown modally. + +### MinButton +{: .no_toc } + +Whether the title bar shows the minimise button. **Boolean**, default **True**, read-only at run time. Set at design time. + +### 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 (and not over a child control with its own setting). + +### MousePointer +{: .no_toc } + +The mouse cursor shown when the pointer is over the form (and not over a child control with its own setting). 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. + +### NegotiateMenus +{: .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. A restricted member of [**OLEDropConstants**](../../VBRUN/Constants/OLEDropConstants): **vbOLEDropNone** or **vbOLEDropManual**. Automatic-drop mode is not supported on a Form. + +### 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. + +### Palette +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's 256-colour palette feature; not currently implemented in twinBASIC. + +### PaletteMode +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6's 256-colour palette feature; not currently implemented in twinBASIC. + +### Picture +{: .no_toc } + +A **StdPicture** drawn as the form's background. Painted before any drawing primitives or child controls. Assigning **Nothing** removes the background. + +### PictureDpiScaling +{: .no_toc } + +When **True**, [**Picture**](#picture) is scaled by the current DPI factor before drawing. **Boolean**, default **False**. + +### RightToLeft +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### ScaleHeight +{: .no_toc } + +The height of the logical drawing rectangle, in [**ScaleMode**](#scalemode) units. **Double**. Setting it (or [**ScaleWidth**](#scalewidth), [**ScaleLeft**](#scaleleft), or [**ScaleTop**](#scaletop)) implicitly switches **ScaleMode** to **vbUser**. + +### ScaleLeft +{: .no_toc } + +The logical horizontal coordinate of the left edge of the form's client area, in [**ScaleMode**](#scalemode) units. **Double**. Default `0`. + +### ScaleMode +{: .no_toc } + +The unit of measurement used by [**CurrentX**](#currentx), [**CurrentY**](#currenty), the drawing primitives, [**TextWidth**](#textwidth), and [**TextHeight**](#textheight). A member of [**ScaleModeConstants**](../../VBRUN/Constants/ScaleModeConstants): **vbTwips** (default), **vbPoints**, **vbPixels**, **vbCharacters**, **vbInches**, **vbMillimeters**, **vbCentimeters**, or **vbUser** (the four **Scale\*** properties define the rectangle). + +### ScaleTop +{: .no_toc } + +The logical vertical coordinate of the top edge of the form's client area, in [**ScaleMode**](#scalemode) units. **Double**. Default `0`. + +### ScaleWidth +{: .no_toc } + +The width of the logical drawing rectangle, in [**ScaleMode**](#scalemode) units. **Double**. Setting it implicitly switches **ScaleMode** to **vbUser**. + +### ShowInTaskbar +{: .no_toc } + +Whether the form appears in the Windows taskbar and Alt-Tab list. **Boolean**, default **True**. Read-only at run time — set at design time. + +### 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 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 — or, for an MDI child, from the top edge of the MDI parent's client area. **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). + +### WhatsThisButton +{: .no_toc } + +When **True**, the title bar shows a "?" help button — but only when [**MinButton**](#minbutton) is **False**, [**MaxButton**](#maxbutton) is **False**, [**ControlBox**](#controlbox) is **True**, and [**BorderStyle**](#borderstyle) is not a tool-window style. **Boolean**. + +### WhatsThisHelp +{: .no_toc } + +When **True**, [**WhatsThisMode**](#whatsthismode) and the title-bar help button enter Windows' "What's This?" cursor mode. **Boolean**, default **False**. + +### Width +{: .no_toc } + +The form's outer width, in twips by default (or in the container's **ScaleMode** units). **Double**. Setting it resizes the window. 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 + +### Circle +{: .no_toc } + +Draws a circle, ellipse, or arc on the form using [**ForeColor**](#forecolor) for the outline and [**FillColor**](#fillcolor)/[**FillStyle**](#fillstyle) for the interior. + +Syntax: *object*.**Circle** [ **Step** ] ( *X*, *Y* ), *Radius* [, [ *Color* ] [, [ *Start* ] [, [ *End* ] [, *Aspect* ] ] ] ] + +*X*, *Y* +: *required* The centre, in [**ScaleMode**](#scalemode) units. **Step** makes the centre relative to ([**CurrentX**](#currentx), [**CurrentY**](#currenty)). + +*Radius* +: *required* A **Single** giving the radius in **ScaleMode** units. + +*Color* +: *optional* An **OLE_COLOR** for the outline; defaults to [**ForeColor**](#forecolor). + +*Start*, *End* +: *optional* Angles in radians, used to draw an arc rather than a full circle. + +*Aspect* +: *optional* Ratio of vertical to horizontal radius. `1.0` is circular; values away from `1.0` produce ellipses. + +### Cls +{: .no_toc } + +Clears any drawing performed by [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), [**PaintPicture**](#paintpicture), and **Print**, repaints [**BackColor**](#backcolor), and resets [**CurrentX**](#currentx) / [**CurrentY**](#currenty) to `0`. Does not affect the [**Picture**](#picture) backdrop or child controls. + +Syntax: *object*.**Cls** + +### Close +{: .no_toc } + +Initiates the form's unload sequence — [**QueryUnload**](#queryunload), then [**Unload**](#unload), then [**Terminate**](#terminate). Either of the first two events 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 and its controls are preserved; calling [**Show**](#show) (or assigning [**Visible**](#visible) = **True**) brings it back. Equivalent to assigning **Visible** = **False**. + +Syntax: *object*.**Hide** + +### Line +{: .no_toc } + +Draws a line, or a rectangle, on the form using [**ForeColor**](#forecolor) (or an explicit colour) and [**DrawWidth**](#drawwidth)/[**DrawStyle**](#drawstyle). + +Syntax: *object*.**Line** [ [ **Step** ] ( *X1*, *Y1* ) ] -[ **Step** ] ( *X2*, *Y2* ) [, [ *Color* ] [, **B** [ **F** ] ] ] + +*X1*, *Y1* +: *optional* The start point, in [**ScaleMode**](#scalemode) units. **Step** makes the point relative to ([**CurrentX**](#currentx), [**CurrentY**](#currenty)). When omitted, drawing begins from the current pen position. + +*X2*, *Y2* +: *required* The end point, in **ScaleMode** units. **Step** makes the point relative to (*X1*, *Y1*). + +*Color* +: *optional* An **OLE_COLOR** for the line; defaults to [**ForeColor**](#forecolor). + +**B** +: *optional* Draw a rectangle whose opposite corners are (*X1*, *Y1*) and (*X2*, *Y2*) instead of a line. + +**F** +: *optional* When combined with **B**, fill the rectangle with [**ForeColor**](#forecolor) instead of [**FillColor**](#fillcolor)/[**FillStyle**](#fillstyle). + +### 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** + +### PaintPicture +{: .no_toc } + +Draws a **StdPicture** onto the form, with optional scaling and raster operations. + +Syntax: *object*.**PaintPicture** *Picture*, *X1*, *Y1* [, *Width1* [, *Height1* [, *X2* [, *Y2* [, *Width2* [, *Height2* [, *Opcode* [, *StretchQuality* ] ] ] ] ] ] ] ] + +*Picture* +: *required* A **StdPicture** to draw. + +*X1*, *Y1* +: *required* The destination upper-left corner, in [**ScaleMode**](#scalemode) units. + +*Width1*, *Height1* +: *optional* Destination size; defaults to the picture's natural size. + +*X2*, *Y2*, *Width2*, *Height2* +: *optional* The source rectangle within the picture; defaults to the whole picture. + +*Opcode* +: *optional* A raster-operation code (member of [**RasterOpConstants**](../../VBRUN/Constants/RasterOpConstants)). Defaults to **vbSrcCopy**. + +*StretchQuality* +: *optional* The interpolation method when scaling. Defaults to normal quality. + +### 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 (or its MDI parent). + +*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 [**ScaleMode**](#scalemode) units. Defaults to the current mouse position. + +*DefaultMenu* +: *optional* The **Menu** sub-item to render in bold as the default action. + +### Point +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. In VB6 this returns the **OLE_COLOR** of a single pixel of the drawing surface. + +Syntax: *object*.**Point**( *X*, *Y* ) + +### PrintForm +{: .no_toc } + +Sends a screen-shot of the form's current visual state to the default printer through the [**Printer**](../../VB/Printer/) object. + +Syntax: *object*.**PrintForm** [ *ImplicitEndDoc* [, *OutputAtCurrentPosition* ] ] + +*ImplicitEndDoc* +: *optional* When **True** (default), the print job is finalised before returning; when **False**, the form is sent as a page but the print job stays open for further output. + +*OutputAtCurrentPosition* +: *optional* When **True**, the form is rendered at the printer's current pen position rather than at the page origin. **Boolean**, default **False**. + +### PSet +{: .no_toc } + +Sets a single pixel on the form to a specified colour. + +Syntax: *object*.**PSet** [ **Step** ] ( *X*, *Y* ) [, *Color* ] + +*X*, *Y* +: *required* The pixel position, in [**ScaleMode**](#scalemode) units. **Step** makes the position relative to ([**CurrentX**](#currentx), [**CurrentY**](#currenty)). + +*Color* +: *optional* An **OLE_COLOR**; defaults to [**ForeColor**](#forecolor). + +### Refresh +{: .no_toc } + +Forces an immediate repaint of the form, raising [**Paint**](#paint) when [**AutoRedraw**](#autoredraw) is **False**. + +Syntax: *object*.**Refresh** + +### Scale +{: .no_toc } + +Sets the form's logical drawing rectangle in a single call by assigning [**ScaleLeft**](#scaleleft), [**ScaleTop**](#scaletop), [**ScaleWidth**](#scalewidth), and [**ScaleHeight**](#scaleheight). Switches [**ScaleMode**](#scalemode) to **vbUser**. Calling **Scale** with no arguments resets the rectangle to a 1-to-1 mapping with the client area in pixels. + +Syntax: *object*.**Scale** [ ( *X1*, *Y1* )-( *X2*, *Y2* ) ] + +*X1*, *Y1* +: *optional* The logical coordinate at the top-left corner. + +*X2*, *Y2* +: *optional* The logical coordinate at the bottom-right corner. + +### ScaleX +{: .no_toc } + +Converts a horizontal length from one [**ScaleMode**](#scalemode) to another. + +Syntax: *object*.**ScaleX**( *Width* [, *FromScale* [, *ToScale* ] ] ) + +*Width* +: *required* A **Single** giving the source length. + +*FromScale*, *ToScale* +: *optional* Members of [**ScaleModeConstants**](../../VBRUN/Constants/ScaleModeConstants). Default to the current **ScaleMode** when omitted. + +### ScaleY +{: .no_toc } + +Converts a vertical length from one [**ScaleMode**](#scalemode) to another. + +Syntax: *object*.**ScaleY**( *Height* [, *FromScale* [, *ToScale* ] ] ) + +*Height* +: *required* A **Single** giving the source length. + +*FromScale*, *ToScale* +: *optional* Members of [**ScaleModeConstants**](../../VBRUN/Constants/ScaleModeConstants). Default to the current **ScaleMode** when omitted. + +### SetFocus +{: .no_toc } + +Activates the form and gives input focus to the control whose [**TabIndex**](../TextBox#tabindex) is `0` (or to whichever control last held focus on this form). + +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 — the call blocks until the form is closed and the user cannot interact with other forms). + +*OwnerForm* +: *optional* For modal shows, the form that is disabled while this form is up; defaults to the currently active form. + +### TextHeight +{: .no_toc } + +Returns the height that the given string would occupy when drawn with the form's current [**Font**](#font), in [**ScaleMode**](#scalemode) units. + +Syntax: *object*.**TextHeight**( *Str* ) + +*Str* +: *required* A **String** to measure. + +### TextWidth +{: .no_toc } + +Returns the width that the given string would occupy when drawn with the form's current [**Font**](#font), in [**ScaleMode**](#scalemode) units. + +Syntax: *object*.**TextWidth**( *Str* ) + +*Str* +: *required* A **String** to measure. + +### ValidateControls +{: .no_toc } + +Fires the **Validate** event of the currently active control on this form. 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. Useful for checking pending input before saving or closing. + +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 form becomes the active window in the application — either after [**Load**](#load) for the first show, or whenever it gains activation back from another window. + +Syntax: *object*\_**Activate**( ) + +### Click +{: .no_toc } + +Raised when the user single-clicks the form's client area (i.e. not over any child control). + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks the form's client area. + +Syntax: *object*\_**DblClick**( ) + +### Deactivate +{: .no_toc } + +Raised when another window in the application takes activation away from this form. Not raised when activation moves to a window in a different application. + +Syntax: *object*\_**Deactivate**( ) + +### DPIChange +{: .no_toc } + +Raised when the form moves to a monitor with a different DPI scale, *but only* when the application is per-monitor DPI aware (`PROCESS_PER_MONITOR_DPI_AWARE`). The event's *NewDPI* argument carries the new effective DPI; child controls re-scale themselves automatically. New in twinBASIC. + +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** ) + +### GotFocus +{: .no_toc } + +Raised when the form receives the input focus and no enabled child control of the form is in a position to take it instead. A form with no focusable child controls receives focus directly. + +Syntax: *object*\_**GotFocus**( ) + +### Initialize +{: .no_toc } + +Raised once, before the underlying window is created and before any of the form's child controls exist. Useful for setting initial values on form-level fields. The form's controls cannot be referenced from this event. + +Syntax: *object*\_**Initialize**( ) + +### KeyDown +{: .no_toc } + +Raised when the user presses any key. Fires on the focused control by default; with [**KeyPreview**](#keypreview) **True**, fires on the form first. + +Syntax: *object*\_**KeyDown**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### KeyPress +{: .no_toc } + +Raised when the user types a character that produces an ANSI keystroke. Fires on the focused control by default; with [**KeyPreview**](#keypreview) **True**, fires on the form first. + +Syntax: *object*\_**KeyPress**( *KeyAscii* **As Integer** ) + +### KeyUp +{: .no_toc } + +Raised when the user releases a key. Fires on the focused control by default; with [**KeyPreview**](#keypreview) **True**, fires on the form first. + +Syntax: *object*\_**KeyUp**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### 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 form's window and all controls have been created, just before the form first appears on screen. The classic place to populate controls, attach data sources, and perform any initialisation that needs the controls to exist. **Default event.** + +Syntax: *object*\_**Load**( ) + +### LostFocus +{: .no_toc } + +Raised when the form loses the input focus. + +Syntax: *object*\_**LostFocus**( ) + +### MouseDown +{: .no_toc } + +Raised when the user presses any mouse button over the form's client area. + +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 form'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 form'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 form. 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** ) + +### Paint +{: .no_toc } + +Raised when an invalidated portion of the form needs to be redrawn. Suppressed when [**AutoRedraw**](#autoredraw) is **True** — the form's persistent off-screen buffer is blitted to the screen instead. + +Syntax: *object*\_**Paint**( ) + +### 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 open. Always raised before [**Unload**](#unload). + +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, the MDI parent, or the owner form. + +### Resize +{: .no_toc } + +Raised when the form is resized — by the user, by code, by the OS following a [**WindowState**](#windowstate) change, or by initial layout during the first show. + +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 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/TextBox/index.md b/docs/Reference/VB/TextBox/index.md new file mode 100644 index 0000000..e2251aa --- /dev/null +++ b/docs/Reference/VB/TextBox/index.md @@ -0,0 +1,11 @@ +--- +nav_exclude: true +permalink: /tB/Packages/VB/TextBox +--- + +> [!WARNING] +> +> Pardon, we have not documented this class yet. + +# TabIndex + diff --git a/docs/Reference/VB/index.md b/docs/Reference/VB/index.md new file mode 100644 index 0000000..f380fe2 --- /dev/null +++ b/docs/Reference/VB/index.md @@ -0,0 +1,10 @@ +--- +title: VB Package +parent: Reference Section +nav_order: 21 +permalink: /tB/Packages/VB +--- + +# VB Package + +These classes are in the VB built-in package, which provides the standard set of controls (CheckBox, CommandButton, ComboBox, Label, TextBox, …) and the form infrastructure that hosts them. diff --git a/docs/Reference/VB/todo.md b/docs/Reference/VB/todo.md new file mode 100644 index 0000000..ddb0926 --- /dev/null +++ b/docs/Reference/VB/todo.md @@ -0,0 +1,14 @@ +--- +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 +--- + +> [!WARNING] +> +> Pardon, we have not documented this class yet. + diff --git a/docs/Reference/VBA/index.md b/docs/Reference/VBA/index.md index e5a39bd..aa9cdf3 100644 --- a/docs/Reference/VBA/index.md +++ b/docs/Reference/VBA/index.md @@ -1,6 +1,7 @@ --- title: VBA Package parent: Reference Section +nav_order: 22 permalink: /tB/Packages/VBA redirect_from: - /tB/Modules diff --git a/docs/Reference/VBA/todo.md b/docs/Reference/VBA/todo.md deleted file mode 100644 index ff57c90..0000000 --- a/docs/Reference/VBA/todo.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: General TODO List for /tB/Modules/ -nav_exclude: true -redirect_from: ---- - -> [!WARNING] -> -> Pardon, we have not documented this module yet. - diff --git a/docs/Reference/VBRUN/index.md b/docs/Reference/VBRUN/index.md index 31d9ee9..6b31845 100644 --- a/docs/Reference/VBRUN/index.md +++ b/docs/Reference/VBRUN/index.md @@ -1,6 +1,7 @@ --- title: VBRUN Package parent: Reference Section +nav_order: 23 permalink: /tB/Packages/VBRUN ---