diff --git a/docs/Reference/Controls.md b/docs/Reference/Controls.md index 24ebda5..6d17b65 100644 --- a/docs/Reference/Controls.md +++ b/docs/Reference/Controls.md @@ -7,6 +7,61 @@ permalink: /tB/Controls # Controls -> [!WARNING] -> Work in Progress +The standard set of UI control classes that ship with twinBASIC lives in the **VB** built-in package — see [VB Package](Packages/VB) for the package landing page. The classes below are grouped by purpose; each entry links to the per-class reference. +## Forms and host classes + +These classes are *containers* rather than controls in the strict sense — they host other controls and back the form/control designer in the IDE. + +- [Form](Packages/VB/Form/) — top-level window hosting controls, menus, and a drawing surface. +- [MDIForm](Packages/VB/MDIForm/) — top-level MDI parent that hosts MDI-child [Form](Packages/VB/Form/) instances inside a recessed client area. +- [UserControl](Packages/VB/UserControl/) — base class for designing a reusable ActiveX control in twinBASIC. +- [PropertyPage](Packages/VB/PropertyPage/) — container backing a single tab of a COM property-page dialog (the **(Custom)** popup on an ActiveX control's property browser). +- [Report](Packages/VB/Report/) — top-level window specialised for banded report layout, print preview, and printing. + +## Buttons and toggles + +- [CommandButton](Packages/VB/CommandButton/) — push-button used to trigger an action. +- [CheckBox](Packages/VB/CheckBox/) — two- or three-state check box with an optional text caption. +- [CheckMark](Packages/VB/CheckMark/) — windowless check glyph that scales to fill its rectangle; no caption, no focus. +- [OptionButton](Packages/VB/OptionButton/) — radio-button; option buttons sharing a container form a mutually-exclusive group. + +## Text and value input + +- [TextBox](Packages/VB/TextBox/) — single-line or multi-line edit control, with optional password masking and digit-only input. +- [ComboBox](Packages/VB/ComboBox/) — edit field combined with a drop-down list of items. +- [ListBox](Packages/VB/ListBox/) — vertically-scrolling list of items, optionally multi-column and multi-select. +- [HScrollBar](Packages/VB/HScrollBar/) — stand-alone horizontal scroll bar. +- [VScrollBar](Packages/VB/VScrollBar/) — stand-alone vertical scroll bar. + +## File-system browsing + +These three controls are normally wired up together to build a complete file picker. + +- DriveListBox — drive picker. *Not yet documented.* +- [DirListBox](Packages/VB/DirListBox/) — directory-tree picker for a single path. +- [FileListBox](Packages/VB/FileListBox/) — file list for a single directory, filtered by wildcard and file-attribute toggles. + +## Containers + +- [Frame](Packages/VB/Frame/) — captioned container that groups related controls and scopes [OptionButton](Packages/VB/OptionButton/) groups. +- [MultiFrame](Packages/VB/MultiFrame/) — layout container that arranges a set of [Frame](Packages/VB/Frame/) controls in a horizontal or vertical strip. +- [PictureBox](Packages/VB/PictureBox/) — Win32 native control combining picture display, a drawing surface, and a child-control container. + +## Display-only + +- [Label](Packages/VB/Label/) — windowless lightweight read-only text display, used for captions, status text, and keyboard mnemonics. +- [Image](Packages/VB/Image/) — windowless lightweight picture display; the small, efficient alternative to [PictureBox](Packages/VB/PictureBox/). +- [Line](Packages/VB/Line/) — windowless single straight line between two endpoints. +- [Shape](Packages/VB/Shape/) — windowless geometric primitive (rectangle, oval, circle, star, arrow, …) with configurable border, fill, and rotation. +- [QRCode](Packages/VB/QRCode/) — windowless QR-code renderer driven by a text or byte-array payload. + +## Menus + +- [Menu](Packages/VB/Menu/) — item in a Win32 native menu — top-level entry on a [Form](Packages/VB/Form/)'s or [MDIForm](Packages/VB/MDIForm/)'s menu bar, a drop-down entry, or a separator. + +## Data and external content + +- [Data](Packages/VB/Data/) — Win32 native control that opens a DAO recordset and exposes record-navigation buttons for bound controls. +- [OLE](Packages/VB/OLE/) — OLE container hosting a linked or embedded OLE Automation object (Word document, Excel sheet, …). +- [Timer](Packages/VB/Timer/) — non-visual control that raises a periodic event at a programmable interval. diff --git a/docs/Reference/VB/PropertyPage/index.md b/docs/Reference/VB/PropertyPage/index.md new file mode 100644 index 0000000..27dcd0c --- /dev/null +++ b/docs/Reference/VB/PropertyPage/index.md @@ -0,0 +1,759 @@ +--- +title: PropertyPage +parent: VB Package +permalink: /tB/Packages/VB/PropertyPage/ +has_toc: false +--- + +# PropertyPage class +{: .no_toc } + +A **PropertyPage** is a container that backs a single tab of a COM property-page dialog — the popup invoked from the **(Custom)** entry on an ActiveX control's property browser. It exposes the **IPropertyPage2** COM interface so that any host that knows how to drive ActiveX property pages (the twinBASIC IDE, classic VB6, Office, …) can place it inside its own property-sheet frame, give it the controls the user is editing, and apply the page's changes back to them. + +Designing a property page is much like designing a small dialog [**Form**](../Form): drop child controls onto it, write event handlers, and use its drawing surface freely. What sets it apart is the lifecycle, which is driven by the host rather than by the application: + +1. The host instantiates the property-page class once per dialog. +2. The host calls **IPropertyPage2.SetObjects** to hand over the selected ActiveX controls. The framework stores them in [**SelectedControls**](#selectedcontrols) and raises [**SelectionChanged**](#selectionchanged). +3. As the user edits values, the page handler sets [**Changed**](#changed) = **True** to enable the dialog's *Apply* button. +4. When the user clicks *OK* or *Apply*, the host raises [**ApplyChanges**](#applychanges) so the page can write the new values back to [**SelectedControls**](#selectedcontrols). +5. On dialog close the framework raises [**Terminate**](#terminate) and releases the class instance. + +The default property is [**Controls**](#controls); the default-designer event is [**SelectionChanged**](#selectionchanged). + +```tb +Private Sub PropertyPage_SelectionChanged() + ' Mirror the first selected control's properties into the editor controls. + txtCaption.Text = SelectedControls(0).Caption +End Sub + +Private Sub txtCaption_Change() + ' Any user edit marks the page dirty so the host enables Apply. + Me.Changed = True +End Sub + +Private Sub PropertyPage_ApplyChanges() + ' Write the editor values back to every selected control. + Dim ctl As Object + For Each ctl In SelectedControls + ctl.Caption = txtCaption.Text + Next +End Sub +``` + +* TOC +{:toc} + +## Communicating with the host + +[**SelectedControls**](#selectedcontrols) is a read-only collection of the controls the host wants this tab to edit. The host populates it before raising [**SelectionChanged**](#selectionchanged); the page keeps the references for as long as it is alive. The collection supports indexed access (`SelectedControls(0)`), enumeration (`For Each ctl In SelectedControls`), and a **Count** member. + +[**Changed**](#changed) is a two-way flag the page uses to talk to the host. Setting it to **True** enables the host's *Apply* button; the framework notifies the host immediately through **IPropertyPageSite.OnStatusChange**. Setting it to **False** clears the flag — the framework does this automatically after raising [**ApplyChanges**](#applychanges). + +[**EditProperty**](#editproperty) is declared for VB6 compatibility but is not currently raised by the runtime; pages that want to react to a per-property edit request from the host need to wait until that wiring lands. + +[**ValidateControls**](#validatecontrols) explicitly fires the focused child control's **Validate** event from code; it raises run-time error 380 if validation fails. Useful in [**ApplyChanges**](#applychanges) to refuse to apply when an editor's value is malformed. + +## Standard sizes + +The VB6 property-page dialog frame draws each tab at one of two standard sizes — small (250 × 62 dialog units) or large (250 × 110 dialog units) — chosen by the host based on the [**StandardSize**](#standardsize) of the largest page in the sheet. Assigning [**StandardSize**](#standardsize) at design time tells the host which size to request; reading it at run time returns the size the page is actually drawn at, or **StandardSizeCustom** when [**Width**](#width) and [**Height**](#height) have been changed away from either preset. The value is in **EnumStandardSize** units: **StandardSizeCustom** (0), **StandardSizeSmall** (1), or **StandardSizeLarge** (2). + +## Drawing surface + +A **PropertyPage** is a graphics surface in its own right. The full set of VB6 drawing primitives — [**Cls**](#cls), [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), [**PaintPicture**](#paintpicture), and the [**Print**](#print) statement — write to its device context, using [**ForeColor**](#forecolor), [**FillColor**](#fillcolor)/[**FillStyle**](#fillstyle), [**DrawWidth**](#drawwidth), [**DrawMode**](#drawmode), and [**DrawStyle**](#drawstyle) for the pen and fill, and [**Font**](#font) for text. The current pen position is tracked by [**CurrentX**](#currentx) and [**CurrentY**](#currenty); [**TextWidth**](#textwidth) and [**TextHeight**](#textheight) measure a string in the current font; [**ScaleX**](#scalex) and [**ScaleY**](#scaley) convert single coordinates between scale modes. + +The coordinate system is governed by [**ScaleMode**](#scalemode), [**ScaleLeft**](#scaleleft), [**ScaleTop**](#scaletop), [**ScaleWidth**](#scalewidth), and [**ScaleHeight**](#scaleheight), exactly as on a [**Form**](../Form). [**AutoRedraw**](#autoredraw) controls whether drawn output persists across paints — when **False** (default), the [**Paint**](#paint) event must redraw on every invalidation; when **True**, the page keeps an off-screen buffer that survives invalidations and the **Paint** event is suppressed. + +## Controls and containers + +[**Controls**](#controls) is the collection of every child control on this page, indexable by name or zero-based position. The page is enumerable directly (`For Each ctrl In Me`) — the [**Count**](#count) and [**\_Default**](#controls) members forward to it. + +[**ActiveControl**](#activecontrol) returns the focused child, or **Nothing** if no control on this page has the focus. [**SetFocus**](#setfocus) gives the focus to the page itself, which forwards it to the page's tab order. [**KeyPreview**](#keypreview) routes keystrokes through the page's [**KeyDown**](#keydown), [**KeyUp**](#keyup), and [**KeyPress**](#keypress) events *before* the focused control sees them — useful for handling **Escape** or page-wide hotkeys. + +## Properties + +### ActiveControl +{: .no_toc } + +The control on this page that currently has the input focus, as a **Control** object, or **Nothing** when no control on this page is focused. Read-only. + +### Appearance +{: .no_toc } + +A member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). + +> [!NOTE] +> Retained for VB6 compatibility; the property has no observable effect on a property page. + +### AutoRedraw +{: .no_toc } + +Whether drawing performed on the page persists across invalidations. **Boolean**, default **False**. + +When **False**, drawing primitives — [**Cls**](#cls), [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), [**PaintPicture**](#paintpicture), and [**Print**](#print) — paint directly to the screen and the page must redraw them in its [**Paint**](#paint) event whenever the affected area is invalidated. When **True**, the page 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. + +### BackColor +{: .no_toc } + +The background colour of the page's client area, as an **OLE_COLOR**. Defaults to the system 3-D face colour. + +### Caption +{: .no_toc } + +The text the host displays on this page's tab in the property-sheet frame. **String**. + +Syntax: *object*.**Caption** [ = *string* ] + +The framework reads the current value when the host calls **IPropertyPage2.GetPageInfo**, so changes made before the page is activated take effect; changes made afterwards are ignored by most hosts. + +### Changed +{: .no_toc } + +Whether the page has unapplied edits. **Boolean**, default **False**. + +Setting **Changed** to **True** notifies the host through **IPropertyPageSite.OnStatusChange** that the page is dirty — the host normally enables its *Apply* button as a result. The framework automatically clears the flag back to **False** before raising [**ApplyChanges**](#applychanges), so handlers do not need to reset it themselves. + +### ClipControls +{: .no_toc } + +Whether child controls are clipped out of the page's drawing region during paint. **Boolean**, default **True**. Read-only at run time — set at design time. + +### Controls +{: .no_toc } + +The collection of every control hosted by this page, 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 +``` + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a property page. Always **vbPropertyPage**. + +### Count +{: .no_toc } + +The number of controls in [**Controls**](#controls), as a **Long**. Read-only. Equivalent to `Me.Controls.Count`. + +### CurrentX +{: .no_toc } + +The horizontal pen position, in [**ScaleMode**](#scalemode) units, used by drawing primitives that omit a starting coordinate (for example, [**Print**](#print) and the rectangle form of [**Line**](#line)). **Double**. + +### CurrentY +{: .no_toc } + +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 page 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 page 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), default **vbCopyPen**. + +### 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). + +### 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**](#print) statement and other text drawing on this page. The convenience properties [**FontName**](#fontname), [**FontSize**](#fontsize), [**FontBold**](#fontbold), [**FontItalic**](#fontitalic), [**FontStrikethru**](#fontstrikethru), and [**FontUnderline**](#fontunderline) read or write the corresponding members of this object. + +### FontBold +{: .no_toc } + +Shortcut for [**Font**](#font)`.Bold`. **Boolean**. + +### FontItalic +{: .no_toc } + +Shortcut for [**Font**](#font)`.Italic`. **Boolean**. + +### FontName +{: .no_toc } + +Shortcut for [**Font**](#font)`.Name`. **String**. + +### FontSize +{: .no_toc } + +Shortcut for [**Font**](#font)`.Size` — the point size. **Single**. + +### FontStrikethru +{: .no_toc } + +Shortcut for [**Font**](#font)`.Strikethrough`. **Boolean**. + +### FontTransparent +{: .no_toc } + +When **True** (default), text drawn on the page 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**. + +### FontUnderline +{: .no_toc } + +Shortcut for [**Font**](#font)`.Underline`. **Boolean**. + +### ForeColor +{: .no_toc } + +The pen colour used by [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), and the text drawn by [**Print**](#print). **OLE_COLOR**. + +### HasDC +{: .no_toc } + +Whether the page keeps a private device context (`CS_OWNDC`) for its drawing surface. **Boolean**, always **True** on a property page. Read-only. + +### hDC +{: .no_toc } + +The Win32 device context handle for the page, as a **LongPtr**. Read-only. Returns `0` when the underlying window has not yet been created. Useful for passing to GDI API calls. + +### Height +{: .no_toc } + +The page's outer height, in twips by default (or in the calling code's **ScaleMode** units). **Double**. The host normally sizes the page itself based on [**StandardSize**](#standardsize); assigning **Height** explicitly switches to the custom size. + +### HelpContextID +{: .no_toc } + +A **Long** identifying a topic in the application's help file, retrieved when the user presses **F1** while the page has focus. + +### hWnd +{: .no_toc } + +The Win32 window handle for the page, as a **LongPtr**. Read-only. Useful for passing to API functions. + +### KeyPreview +{: .no_toc } + +When **True**, the page's [**KeyDown**](#keydown), [**KeyUp**](#keyup), and [**KeyPress**](#keypress) events fire *before* the focused control receives the same keystroke. **Boolean**, default **False**. Useful for page-wide hotkeys; events still fire on the focused control afterwards. + +### Left +{: .no_toc } + +The horizontal position of the page's outer rectangle within the host's property-sheet frame, in twips. **Double**. Set by the host through **IPropertyPage2.Activate** and **Move**; rarely assigned from user code. + +### MouseIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor when [**MousePointer**](#mousepointer) is **vbCustom** and the pointer is over the page (and not over a child control with its own setting). + +### MousePointer +{: .no_toc } + +The mouse cursor shown when the pointer is over the page (and not over a child control with its own setting). A member of [**MousePointerConstants**](../../VBRUN/Constants/MousePointerConstants). + +### Name +{: .no_toc } + +The unique design-time name of the property-page class. Read-only at run time. Also the class name of the generated property-page class. + +### OLEDropMode +{: .no_toc } + +How the page responds to OLE drops. A restricted member of [**OLEDropConstants**](../../VBRUN/Constants/OLEDropConstants): **vbOLEDropNone** or **vbOLEDropManual**. Automatic-drop mode is not supported on a property page. + +### 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 page'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 page'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 page'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**. + +### SelectedControls +{: .no_toc } + +The collection of objects the host has asked this page to edit, as a **SelectedControls** instance. Read-only. The framework populates the collection before raising [**SelectionChanged**](#selectionchanged) and clears it on [**Terminate**](#terminate). + +The returned object exposes three members: + +- `Count` **As Long** — the number of selected objects (`0` when the host has not yet called **SetObjects** or has cleared the selection). +- `Item(`*Index*`)` **As Object** — zero-based indexed access. **Default member**, so `SelectedControls(0)` returns the first object. +- `_NewEnum` — supports `For Each ctl In SelectedControls`. + +The items are returned as **Object**, so use **CallByName** or late-bound member access to read and write their properties. + +```tb +For Each ctl In SelectedControls + ctl.Caption = txtCaption.Text +Next +``` + +### StandardSize +{: .no_toc } + +The standard size of the page in the host's property-sheet frame. A member of **EnumStandardSize**: **StandardSizeCustom** (0), **StandardSizeSmall** (1 — 250 × 62 dialog units), or **StandardSizeLarge** (2 — 250 × 110 dialog units). + +Syntax: *object*.**StandardSize** [ = *value* ] + +Reading **StandardSize** compares the page's current pixel size against the small/large presets and returns **StandardSizeCustom** when neither matches. Assigning **StandardSizeSmall** or **StandardSizeLarge** resizes the page accordingly; assigning **StandardSizeCustom** is a no-op (leave the size as it is). The property is exposed only in code — VB6 surfaced it on the design-time property sheet but never in the runtime object model. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the page. Ignored by the framework. + +### Top +{: .no_toc } + +The vertical position of the page's outer rectangle within the host's property-sheet frame, in twips. **Double**. Set by the host; rarely assigned from user code. + +### Width +{: .no_toc } + +The page's outer width, in twips by default (or in the calling code's **ScaleMode** units). **Double**. The host normally sizes the page itself based on [**StandardSize**](#standardsize); assigning **Width** explicitly switches to the custom size. + +## Methods + +### Circle +{: .no_toc } + +Draws a circle, ellipse, or arc on the page 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**](#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** + +### Line +{: .no_toc } + +Draws a line, or a rectangle, on the page 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). + +### OLEDrag +{: .no_toc } + +Initiates an OLE drag operation from the page, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject**. + +Syntax: *object*.**OLEDrag** + +### PaintPicture +{: .no_toc } + +Draws a **StdPicture** onto the page, 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. + +### 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* ) + +### Print +{: .no_toc } + +Writes text to the page's drawing surface using [**Font**](#font), starting at [**CurrentX**](#currentx) / [**CurrentY**](#currenty) and advancing them as it goes. Dispatched through the VB6 **Print** statement so multiple expressions can be separated by `;` (no spacing) or `,` (tab to the next print zone). **Spc(n)** inserts *n* spaces and **Tab(n)** moves to print column *n*. Output honours [**Font**](#font), [**ForeColor**](#forecolor), and [**FontTransparent**](#fonttransparent), and — when [**AutoRedraw**](#autoredraw) is **True** — is recorded into the persistent off-screen bitmap so it survives invalidations. + +Syntax: *object*.**Print** \[ *expressionlist* ] \[ **;** \| **,** ] + +A trailing `;` or `,` suppresses the newline so the next **Print** call continues on the same line. + +### PSet +{: .no_toc } + +Sets a single pixel on the page 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 page, raising [**Paint**](#paint) when [**AutoRedraw**](#autoredraw) is **False**. + +Syntax: *object*.**Refresh** + +### Scale +{: .no_toc } + +Sets the page'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 page and gives input focus to its first focusable child control (or to whichever control last held focus on this page). + +Syntax: *object*.**SetFocus** + +### TextHeight +{: .no_toc } + +Returns the height that the given string would occupy when drawn with the page's current [**Font**](#font), in [**ScaleMode**](#scalemode) units. Embedded line breaks are honoured. + +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 page's current [**Font**](#font), in [**ScaleMode**](#scalemode) units. Returns the longest line width when *Str* contains embedded line breaks. + +Syntax: *object*.**TextWidth**( *Str* ) + +*Str* +: *required* A **String** to measure. + +### ValidateControls +{: .no_toc } + +Fires the **Validate** event of the currently active control on this page. 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 in [**ApplyChanges**](#applychanges) to refuse to apply when an editor's value is malformed. + +Syntax: *object*.**ValidateControls** + +## Events + +### ApplyChanges +{: .no_toc } + +Raised when the host calls **IPropertyPage2.Apply** — typically because the user clicked *OK* or *Apply* on the property-sheet dialog. The handler should write the page's current editor values back to every object in [**SelectedControls**](#selectedcontrols). The framework clears [**Changed**](#changed) to **False** before the handler runs. Not raised when [**Changed**](#changed) is already **False** at the time of the apply. + +Syntax: *object*\_**ApplyChanges**( ) + +### Click +{: .no_toc } + +Raised when the user single-clicks the page's client area (i.e. not over any child control). + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks the page's client area. + +Syntax: *object*\_**DblClick**( ) + +### DPIChange +{: .no_toc } + +Raised when the page moves to a monitor with a different DPI scale, *but only* when the application is per-monitor DPI aware (`PROCESS_PER_MONITOR_DPI_AWARE`). The event's *NewDPI* argument carries the new effective DPI; child controls re-scale themselves automatically. + +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** ) + +### EditProperty +{: .no_toc } + +> [!NOTE] +> Declared for VB6 compatibility; not currently raised in twinBASIC. The host's **IPropertyPage2.EditProperty** request is acknowledged but does not propagate to a managed event yet. + +When implemented, raised when the host asks the page to give focus to the editor that corresponds to the named property — typically because the user double-clicked that property in the property browser. + +Syntax: *object*\_**EditProperty**( *PropertyName* **As String** ) + +*PropertyName* +: The name of the property the host wants edited. + +### GotFocus +{: .no_toc } + +Raised when the page receives the input focus and no enabled child control of the page is in a position to take it instead. + +Syntax: *object*\_**GotFocus**( ) + +### Initialize +{: .no_toc } + +Raised once, after the page's window and all controls have been created and the page has been event-registered into its host's frame, before [**SelectionChanged**](#selectionchanged) is first raised. The classic place to populate editor controls with static data (lists of choices, default values, …) that doesn't depend on the selected objects. + +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 page 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 page 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 page first. + +Syntax: *object*\_**KeyUp**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### LostFocus +{: .no_toc } + +Raised when the page loses the input focus. + +Syntax: *object*\_**LostFocus**( ) + +### MouseDown +{: .no_toc } + +Raised when the user presses any mouse button over the page'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 page'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 page's client area. + +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** ) + +### Paint +{: .no_toc } + +Raised when an invalidated portion of the page needs to be redrawn. Suppressed when [**AutoRedraw**](#autoredraw) is **True** — the page's persistent off-screen buffer is blitted to the screen instead. + +Syntax: *object*\_**Paint**( ) + +### SelectionChanged +{: .no_toc } + +Raised after the host has called **IPropertyPage2.SetObjects** to give the page a new set of objects to edit, or to clear the selection. The handler should read [**SelectedControls**](#selectedcontrols) and mirror the common state of those objects into the page's editor controls. **Default-designer event.** + +Syntax: *object*\_**SelectionChanged**( ) + +### Terminate +{: .no_toc } + +Raised when the page is being destroyed — once when its window is unhooked from the host's property-sheet frame, and again when the class instance's last reference is released. The handler runs while [**SelectedControls**](#selectedcontrols) is still populated, giving it a final chance to read state from the edited objects before they are released. + +Syntax: *object*\_**Terminate**( ) diff --git a/docs/Reference/VB/QRCode/index.md b/docs/Reference/VB/QRCode/index.md new file mode 100644 index 0000000..2cdc92a --- /dev/null +++ b/docs/Reference/VB/QRCode/index.md @@ -0,0 +1,462 @@ +--- +title: QRCode +parent: VB Package +permalink: /tB/Packages/VB/QRCode/ +has_toc: false +--- + +# QRCode class +{: .no_toc } + +A **QRCode** is a windowless lightweight control that renders a QR code generated from its [**Payload**](#payload) — a URL, plain text, or a raw byte array. The encoding is performed in-process by the embedded `qrcodegen` library and the resulting matrix is painted directly on the parent at design time and at run time. The picture is regenerated automatically whenever any of the encoding properties changes, so a QR control can be wired up declaratively to data bindings or to other UI state with no plumbing. + +Like [**Image**](../Image), a QRCode has no `hWnd` and is not focusable. It is the right choice for embedding a scannable code in a form (login, payment, Wi-Fi credentials, contact card, app deep link, etc.) without paying for a heavy [**PictureBox**](../PictureBox). + +The default property is [**Picture**](#picture) (the read-only generated image) and the default event is [**Click**](#click). + +```tb +Private Sub Form_Load() + QRCode1.Payload = "https://www.twinbasic.com" + QRCode1.EccMode = vbQRCodegenEccHigh ' 30 % parity + QRCode1.ForeColor = vbBlue +End Sub + +Private Sub QRCode1_Click() + MsgBox "QR code clicked" +End Sub +``` + +* TOC +{:toc} + +## Windowless rendering + +A **QRCode** has no `hWnd`. The framework paints it directly onto its parent's drawing surface during the parent's paint cycle. The trade-offs are the same as for any windowless control: + +- No focus, no keyboard input, no `KeyDown` / `KeyPress` / `KeyUp` / `GotFocus` / `LostFocus` / `Validate`. +- No `hWnd` to pass to API functions, and no `SetFocus`. +- Cannot host child controls. + +For a QR code that needs any of those, host the **QRCode** inside a [**PictureBox**](../PictureBox) or [**Frame**](../Frame) and put the focusable controls next to it. + +## Encoding the payload + +The [**Payload**](#payload) property is a **Variant** that accepts either a **String** (text or URL) or a one-dimensional **Byte()** array (for binary data). The encoder picks the most compact segment mode automatically — numeric, alphanumeric, or byte — based on the contents of the string; for a byte array the byte mode is used unconditionally and the data is encoded verbatim. Empty payloads clear [**Picture**](#picture) to **Nothing**; at design time the rectangle then shows a *(no payload text)* placeholder. + +The QR code is regenerated whenever [**Payload**](#payload), [**ForeColor**](#forecolor), [**ModuleSize**](#modulesize), [**SquareModules**](#squaremodules), [**EccMode**](#eccmode), [**EccBoost**](#eccboost), [**MinVersion**](#minversion), [**MaxVersion**](#maxversion), or [**MaskType**](#masktype) changes, and the new picture becomes visible through [**Picture**](#picture). [**Refresh**](#refresh) only repaints — it does not force re-encoding. + +## Error correction + +QR codes embed a Reed-Solomon parity stream that lets the decoder recover from damage to a portion of the matrix. [**EccMode**](#eccmode) chooses how much of the matrix is dedicated to parity: + +| Constant | Value | Approx. recovery | +|---------------------------------|-------|------------------| +| **vbQRCodegenEccLow** | 0 | 7% | +| **vbQRCodegenEccMedium** | 1 | 15% | +| **vbQRCodegenEccQuartile** | 2 | 25% | +| **vbQRCodegenEccHigh** | 3 | 30% | + +When [**EccBoost**](#eccboost) is **True** (default), the encoder raises the parity level beyond the configured minimum if doing so still fits the payload in the same QR version — getting better resilience for free. + +## Version and mask + +The QR-code *version* (1 to 40) sets the matrix size: version 1 is 21 × 21 modules, version 40 is 177 × 177. [**MinVersion**](#minversion) and [**MaxVersion**](#maxversion) constrain the encoder's search; it picks the smallest version in the range that fits the payload at the chosen [**EccMode**](#eccmode). The defaults (`1` and `40`) span the full range. Values outside `1..40` are clamped, and if **MinVersion** ends up greater than **MaxVersion** it is reset to `1`. + +[**MaskType**](#masktype) selects one of eight masks applied to the matrix to break up patterns that confuse the scanner. **vbQRCodegenMaskAuto** (-1, default) picks the mask with the best penalty score; the eight named values **vbQRCodegenMask0** through **vbQRCodegenMask7** force a specific one — useful for reproducibility. + +## Module rendering + +[**ModuleSize**](#modulesize) is the pixel size of one module of the generated [**Picture**](#picture). Default `120`. The picture is rescaled down to the control's rectangle at paint time, so the choice of [**ModuleSize**](#modulesize) only matters when the picture is being saved or pulled out for use elsewhere (clipboard, drag-drop, **SavePicture**, …). + +[**SquareModules**](#squaremodules) chooses how each module is drawn in the picture: as a filled square (**True**, default) or as a filled circle (**False** — a stylistic choice that most scanners still tolerate). + +[**Square**](#square), in contrast, controls the rendering of the picture *on the control*: with **True** (default) the picture is letter-boxed and centred so it stays square regardless of the control's aspect ratio; with **False** the picture is stretched to fill the rectangle. + +## Border + +[**BorderStyle**](#borderstyle) chooses between no border (default) and a single sunken border drawn around the rectangle. When a border is present, [**Appearance**](#appearance) selects between a 3-D and a flat (monochrome) version of it. + +## OLE drag-drop + +A **QRCode** supports both ends of an OLE drag-drop operation: + +- [**OLEDragMode**](#oledragmode) controls the source side. With **vbOLEDragAutomatic**, holding the mouse over the control and beginning a drag automatically picks up the current [**Picture**](#picture) into the resulting **DataObject** — handy for dragging the generated QR onto another picture display or out to a file in Explorer. With **vbOLEDragManual** (default) drags must be initiated by calling [**OLEDrag**](#oledrag) from a [**MouseDown**](#mousedown) handler. +- [**OLEDropMode**](#oledropmode) controls the destination side. With **vbOLEDropManual** the [**OLEDragOver**](#oledragover) and [**OLEDragDrop**](#oledragdrop) events fire so the application can decide what to do — for example, set [**Payload**](#payload) to the dropped text. **vbOLEDropAutomatic** is not supported on a **QRCode** and assigning it raises run-time error 5 (*Invalid procedure call or argument*). + +## Data binding + +Setting [**DataSource**](#datasource) and [**DataField**](#datafield) connects the control to a field of a [**Data**](../Data) control's recordset. Binding is asymmetric: + +- *Inbound* (recordset → control): non-null, non-empty field values are interpreted as text and assigned to [**Payload**](#payload); the QR is then re-encoded and repainted. Null and empty values clear [**Picture**](#picture) to **Nothing**. +- *Outbound* (control → recordset): the current QR [**Picture**](#picture) is serialised as a byte array and written back to the bound field — useful for storing a snapshot of the rendered code, but note that what comes out of the binding is not the same as what went in. + +## Properties + +### Anchors +{: .no_toc } + +The set of edges of the parent that the control's corresponding edges follow when the parent resizes. Read-only — assign individual `.Left`, `.Top`, `.Right`, `.Bottom` flags through the returned **Anchors** object. + +### Appearance +{: .no_toc } + +The style of the border, as a member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). Only meaningful when [**BorderStyle**](#borderstyle) is **vbFixedSingleBorder**. + +### BorderStyle +{: .no_toc } + +The style of border drawn around the rectangle. A member of [**ControlBorderStyleConstants**](../../VBRUN/Constants/ControlBorderStyleConstants): **vbNoBorder** (0, default) or **vbFixedSingleBorder** (1). + +### Container +{: .no_toc } + +The control that hosts this **QRCode** — typically the form, a [**Frame**](../Frame), a [**PictureBox**](../PictureBox), or a **UserControl**. Read with **Get**, change with **Set**. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying the underlying control kind. Always **vbImage** — the QRCode shares its control-type tag with [**Image**](../Image). + +### DataChanged +{: .no_toc } + +Whether the bound [**Picture**](#picture) has been written to since the last save or refresh from the [**DataSource**](#datasource). **Boolean**. Setting **DataChanged** = **True** also marks the bound recordset as dirty. + +### DataField +{: .no_toc } + +The name of the field, in the recordset of the bound [**DataSource**](#datasource), whose value drives [**Payload**](#payload). **String**. + +### DataFormat +{: .no_toc } + +A **StdDataFormat** that converts between the raw recordset value and the displayed payload, when the application needs custom handling. Set with **Set**. + +### DataMember +{: .no_toc } + +When the [**DataSource**](#datasource) exposes more than one recordset, the name of the member to bind to. **String**. + +### DataSource +{: .no_toc } + +A reference to a [**Data**](../Data) control (or other **DataSource** provider) whose recordset supplies the value for [**DataField**](#datafield). Set with **Set**. + +### Dock +{: .no_toc } + +Where the control is docked within its container. A member of [**DockModeConstants**](../../VBRUN/Constants/DockModeConstants): **vbDockNone** (default), **vbDockLeft**, **vbDockTop**, **vbDockRight**, **vbDockBottom**, or **vbDockFill**. Docked controls ignore [**Anchors**](#anchors). + +### DragIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor while the control is being drag-and-dropped (see [**Drag**](#drag) and [**DragMode**](#dragmode)). + +### DragMode +{: .no_toc } + +Whether the control should drag itself (the manual VB-drag form, distinct from OLE drag) when the user holds the mouse over it. A member of [**DragModeConstants**](../../VBRUN/Constants/DragModeConstants): **vbManual** (0, default — call [**Drag**](#drag) from code) or **vbAutomatic** (1). + +### EccBoost +{: .no_toc } + +When **True** (default), the encoder is allowed to raise the actual parity level above [**EccMode**](#eccmode) when the payload still fits the same QR version at the higher level. **Boolean**. Set to **False** for reproducible output across payloads of varying length. + +### EccMode +{: .no_toc } + +The minimum error-correction level used when encoding. A member of **QRCodegenEccConstants** (defined in the VB package): + +| Constant | Value | Approx. recovery | +|----------------------------|-------|------------------| +| **vbQRCodegenEccLow** | 0 | 7% | +| **vbQRCodegenEccMedium** | 1 | 15% | +| **vbQRCodegenEccQuartile** | 2 | 25% | +| **vbQRCodegenEccHigh** | 3 | 30% | + +Default **vbQRCodegenEccLow**. Out-of-range values are clamped. + +### Enabled +{: .no_toc } + +Determines whether the control accepts mouse input. A disabled **QRCode** still paints normally but does not raise mouse events. **Boolean**, default **True**. + +### ForeColor +{: .no_toc } + +The colour of the dark modules in the generated QR code, as an **OLE_COLOR**. Default **vbBlack**. The light modules are always transparent — the control's parent shows through them, so place the **QRCode** over a contrasting background. + +### Height +{: .no_toc } + +The control's height, in twips by default (or in the container's **ScaleMode** units). **Double**. + +### Index +{: .no_toc } + +When the control is part of a control array, the **Long** zero-based index of this instance within the array. Reading **Index** on a non-array instance raises run-time error 343 (*Object not an array*). Read-only at run time. + +### Left +{: .no_toc } + +The horizontal distance from the left edge of the container to the left edge of the control. **Double**. + +### MaskType +{: .no_toc } + +The mask applied to the encoded matrix to break up patterns that confuse the scanner. A member of **QRCodegenMaskConstants** (defined in the VB package): **vbQRCodegenMaskAuto** (-1, default — pick the mask with the lowest penalty score) or one of **vbQRCodegenMask0** … **vbQRCodegenMask7** (force the corresponding numbered mask). Out-of-range values fall back to **vbQRCodegenMaskAuto**. + +### MaxVersion +{: .no_toc } + +The largest QR version the encoder is allowed to choose. **Long**, default `40`. Clamped to `1..40`. If [**MinVersion**](#minversion) exceeds **MaxVersion** at encode time, **MinVersion** is reset to `1`. + +### MinVersion +{: .no_toc } + +The smallest QR version the encoder is allowed to choose. **Long**, default `1`. The encoder picks the smallest version in `MinVersion..MaxVersion` that fits the payload at the requested [**EccMode**](#eccmode). Clamped to `1..40`. + +### ModuleSize +{: .no_toc } + +The pixel size of one QR module in the generated [**Picture**](#picture). **Long**, default `120`. The picture is scaled to the control's rectangle at paint time, so a larger **ModuleSize** only matters when the picture is being captured or saved at its native resolution. + +### MouseIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor when [**MousePointer**](#mousepointer) is **vbCustom** and the pointer is over the control. + +### MousePointer +{: .no_toc } + +The mouse cursor shown when the pointer is over the control. A member of [**MousePointerConstants**](../../VBRUN/Constants/MousePointerConstants). + +### Name +{: .no_toc } + +The unique design-time name of the control on its parent form. Read-only at run time. + +### OLEDragMode +{: .no_toc } + +Whether an OLE drag is started automatically when the user begins dragging the control. A member of [**OLEDragConstants**](../../VBRUN/Constants/OLEDragConstants): **vbOLEDragManual** (0, default — application calls [**OLEDrag**](#oledrag)) or **vbOLEDragAutomatic** (1 — the framework picks up the current [**Picture**](#picture) into the resulting **DataObject** automatically). + +### OLEDropMode +{: .no_toc } + +How the control responds to OLE drops landing on it. A restricted member of [**OLEDropConstants**](../../VBRUN/Constants/OLEDropConstants): **vbOLEDropNone** (0, default) or **vbOLEDropManual** (1). Automatic drop is not supported on a **QRCode**; assigning **vbOLEDropAutomatic** raises run-time error 5 (*Invalid procedure call or argument*). + +### Parent +{: .no_toc } + +A reference to the [**Form**](../Form) (or **UserControl**) that ultimately contains the control. Read-only. + +### Payload +{: .no_toc } + +The data encoded in the QR code. **Variant**, default `"https://www.twinbasic.com"`. + +Syntax: *object*.**Payload** [ = *value* ] + +Accepts a **String** for text or URL payloads, or a one-dimensional **Byte()** array for arbitrary binary data. The encoder picks the most compact segment mode automatically — numeric, alphanumeric, or byte — based on the contents of the string. Assigning an empty value clears [**Picture**](#picture) to **Nothing**. + +### Picture +{: .no_toc } + +The generated QR code, as a **StdPicture**. **Default property.** Read-only — produced by the encoder from [**Payload**](#payload) and the other encoding properties. Returns **Nothing** when [**Payload**](#payload) is empty. + +### Square +{: .no_toc } + +Whether the generated picture is rendered with a 1:1 aspect ratio inside the control's rectangle (**True**, default — picture is centred and letter-boxed) or stretched to fill it (**False**). **Boolean**. + +### SquareModules +{: .no_toc } + +Whether each module of the encoded matrix is drawn in the picture as a filled square (**True**, default) or as a filled circle (**False**). **Boolean**. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the control. Ignored by the framework. + +### ToolTipText +{: .no_toc } + +A multi-line **String** displayed as a tooltip when the user hovers over the control. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the control. **Double**. + +### Visible +{: .no_toc } + +Whether the control is shown. **Boolean**, default **True**. Hidden **QRCode**s skip the paint pass entirely at run time, except in the IDE designer where they always render so the developer can position them. + +### 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, in twips by default (or in the container's **ScaleMode** units). **Double**. + +## Methods + +### Drag +{: .no_toc } + +Begins, completes, or cancels a manual VB-style drag operation. Distinct from OLE drag — see [**OLEDrag**](#oledrag). + +Syntax: *object*.**Drag** [ *Action* ] + +*Action* +: *optional* A member of [**DragConstants**](../../VBRUN/Constants/DragConstants): **vbCancel** (0), **vbBeginDrag** (1, default), or **vbEndDrag** (2). + +### Move +{: .no_toc } + +Repositions and optionally resizes the control in a single call. + +Syntax: *object*.**Move** *Left* [, *Top* [, *Width* [, *Height* ] ] ] + +*Left* +: *required* A **Single** giving the new horizontal position. + +*Top*, *Width*, *Height* +: *optional* New values for the corresponding properties. Omitted values are left unchanged. + +### OLEDrag +{: .no_toc } + +Initiates an OLE drag operation from the control, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject** (or, if the source has already been pre-populated, kicks off the drag immediately). + +Syntax: *object*.**OLEDrag** + +### Refresh +{: .no_toc } + +Forces an immediate repaint of the control's rectangle on the parent's drawing surface. Does *not* re-encode the QR — for that, reassign [**Payload**](#payload) (or any of the encoding properties) which triggers regeneration automatically. + +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 **QRCode** to the front or back of the windowless-sibling stack within its container. + +Syntax: *object*.**ZOrder** [ *Position* ] + +*Position* +: *optional* A member of [**ZOrderConstants**](../../VBRUN/Constants/ZOrderConstants): **vbBringToFront** (0, default) or **vbSendToBack** (1). + +## Events + +### Click +{: .no_toc } + +Raised when the user single-clicks the control's rectangle. **Default event.** + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks the control's rectangle. + +Syntax: *object*\_**DblClick**( ) + +### DragDrop +{: .no_toc } + +Raised on the destination control when a manual VB-style drag operation ends over it. + +Syntax: *object*\_**DragDrop**( *Source* **As Control**, *X* **As Single**, *Y* **As Single** ) + +### DragOver +{: .no_toc } + +Raised on the control under the cursor while a manual VB-style drag operation is in progress. + +Syntax: *object*\_**DragOver**( *Source* **As Control**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### Initialize +{: .no_toc } + +Raised once, after the control has been wired into its container's paint cycle but before it is first painted. Useful for last-minute setup that depends on container state. + +Syntax: *object*\_**Initialize**( ) + +### MouseDown +{: .no_toc } + +Raised when the user presses any mouse button over the control. + +Syntax: *object*\_**MouseDown**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseMove +{: .no_toc } + +Raised when the cursor moves over the control. + +Syntax: *object*\_**MouseMove**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseUp +{: .no_toc } + +Raised when the user releases a mouse button over the control. + +Syntax: *object*\_**MouseUp**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### OLECompleteDrag +{: .no_toc } + +Raised on the source control when the OLE drag operation finishes, indicating which effect (copy, move, none) the destination accepted. + +Syntax: *object*\_**OLECompleteDrag**( *Effect* **As Long** ) + +### OLEDragDrop +{: .no_toc } + +Raised on the destination control when the user drops data on it. + +Syntax: *object*\_**OLEDragDrop**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### OLEDragOver +{: .no_toc } + +Raised on the destination control while an OLE drag passes over it. + +Syntax: *object*\_**OLEDragOver**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### OLEGiveFeedback +{: .no_toc } + +Raised on the source control during a drag so the application can adjust the cursor or other visual feedback. + +Syntax: *object*\_**OLEGiveFeedback**( *Effect* **As Long**, *DefaultCursors* **As Boolean** ) + +### OLESetData +{: .no_toc } + +Raised on the source control when the destination requests data in a format that was registered but not yet supplied. + +Syntax: *object*\_**OLESetData**( *Data* **As DataObject**, *DataFormat* **As Integer** ) + +### OLEStartDrag +{: .no_toc } + +Raised on the source control at the start of an OLE drag, so the application can populate the **DataObject** and choose the allowed effects. Also raised automatically when [**OLEDragMode**](#oledragmode) is **vbOLEDragAutomatic** and the user begins a drag. + +Syntax: *object*\_**OLEStartDrag**( *Data* **As DataObject**, *AllowedEffects* **As Long** ) diff --git a/docs/Reference/VB/Report/index.md b/docs/Reference/VB/Report/index.md new file mode 100644 index 0000000..b12f330 --- /dev/null +++ b/docs/Reference/VB/Report/index.md @@ -0,0 +1,921 @@ +--- +title: Report +parent: VB Package +permalink: /tB/Packages/VB/Report/ +has_toc: false +--- + +# Report class +{: .no_toc } + +A **Report** is a top-level Win32 window — much like a [**Form**](../Form/) — specialised for rendering the print preview of a banded report. Each report designed in the IDE becomes its own class derived from **Report**: its sections (report header / page header / detail / page footer / report footer) and the controls placed in them become members of that class. At run time, code assigns a recordset to [**Recordset**](#recordset), calls [**Show**](#show), and the framework iterates the recordset, evaluates expressions on the controls, and paints the resulting pages into a built-in preview window with a navigation toolbar at the bottom. [**PrintReport**](#printreport) sends the same pages to the printer. The default property is [**Controls**](#controls) and the default event is [**Load**](#load). + +```tb +' In the report's code-behind (rptSales): +Private Sub Report_Load() + Set Me.Recordset = OpenSalesRecordset() + Me.Caption = "Sales for " & FormatDateTime(Now, vbLongDate) +End Sub + +' In a startup module: +Sub Main() + rptSales.Show vbModal ' opens the preview window +End Sub +``` + +* TOC +{:toc} + +## Sections + +A report is composed of up to five sections, laid out vertically on each page: + +| Section | Painted | +|------------------|----------------------------------------------------------------| +| **ReportHeader** | Once, at the top of the first page. | +| **PageHeader** | At the top of every page that follows the report header. | +| **Detail** | Once per record in [**Recordset**](#recordset). | +| **PageFooter** | At the bottom of every page. | +| **ReportFooter** | Once, at the end of the last page after the final detail row. | + +Sections are designed in the IDE — each is a container that holds [**Label**](../Label/), [**Image**](../Image/), [**QRCode**](../QRCode/), and other controls. A section's `KeepTogether` property prevents it from splitting across a page break; its `BackStyle` and back colour control the section background; the framework picks an alternating-row colour for the detail section automatically when the section requests it. + +## Recordset binding + +[**Recordset**](#recordset) accepts any object that exposes the classic ADO/DAO surface — `EOF`, `MoveNext`, and a `Fields` collection indexable by name. The framework wraps non-tB recordsets transparently. `Recordset` may also be left **Nothing**, in which case the detail section is rendered exactly once with no field data. + +A control in a section opts into binding by setting its `DataField` to a recordset field name; the framework reads that field for each detail row and writes it back into the control's value (or [**Caption**](../Label/#caption) for [**Label**](../Label/)s, **Payload** for [**QRCode**](../QRCode/)). For richer cases, prefix `DataField` with `=` to make it an *expression* — any twinBASIC expression that mixes recordset fields, the report's own [**Page**](#page) / [**Pages**](#pages) / [**Caption**](#caption), and standard library calls. A label whose **DataField** is `="Page " & Report.Page & " of " & Report.Pages` updates itself as each page is rendered. + +When **DataField** is empty and a [**Label**](../Label/)'s [**Caption**](../Label/#caption) contains `%`-placeholders, those placeholders are converted to an expression automatically — see [Caption placeholders](#caption-placeholders) below. Setting `DataFieldAggregate` on a Label additionally accumulates the expression's value across rows for running totals. + +## Caption placeholders + +Inside a Label that has no **DataField**, the following `%` placeholders in the [**Caption**](../Label/#caption) are recognised and replaced at render time: + +| Placeholder | Replaced with | +|-------------|------------------------------------------------------------------------| +| `%p` | The current [**Page**](#page) number. | +| `%P` | The total [**Pages**](#pages) count. | +| `%d` | The current date, formatted as `vbShortDate`. | +| `%D` | The current date, formatted as `vbLongDate`. | +| `%t` | The current time, formatted as `vbShortTime`. | +| `%T` | The current time, formatted as `vbLongTime`. | +| `%i` | The report's [**Caption**](#caption). | + +Use `%%` to embed a literal `%`. A caption with no recognised placeholder is left untouched. + +## Built-in preview toolbar + +The bottom strip of the report window is a fixed toolbar with three groups of controls: + +- **Record selectors** — first / previous / next / last buttons around a page-number readout. +- **Zoom controls** — minus / plus buttons around a percentage readout. +- **Print button** — sends the report to the default printer (calls [**PrintReport**](#printreport) with `ShowDialog := False`). + +The toolbar always paints; it cannot be hidden. The plus and minus buttons step [**ZoomPercent**](#zoompercent) by [**ZoomStep**](#zoomstep) (default `10`) and switch [**ZoomAutoFit**](#zoomautofit) to **vbZoomAutoFitNever**. Scroll bars appear automatically when the zoomed page does not fit the available area; the mouse wheel scrolls vertically and **Shift+Wheel** scrolls horizontally. + +## Zoom and page sizing + +[**PixelsReportWidth**](#pixelsreportwidth) and [**PixelsReportHeight**](#pixelsreportheight) define the page size *between the margins*; [**PixelsLeftMargin**](#pixelsleftmargin), [**PixelsRightMargin**](#pixelsrightmargin), [**PixelsTopMargin**](#pixelstopmargin), and [**PixelsBottomMargin**](#pixelsbottommargin) define the margins. All five values are in *scaled pixels* (1 px ≈ 1/96 inch at 100% DPI). The defaults — `300` × `900` for the page and `96/2.54` (≈ 1 cm) for each margin — are placeholders rather than a real paper size; the IDE designer's [**ChangePageSize**](#changepagesize) helper writes the values for the standard paper sizes. + +### ZoomAutoFitConstants + +[**ZoomPercent**](#zoompercent) is the rendering zoom (`100` = 1 logical pixel per screen pixel). [**ZoomAutoFit**](#zoomautofit) ([**ZoomAutoFitConstants**](#zoomautofitconstants)) selects whether the framework also recomputes [**ZoomPercent**](#zoompercent) on every paint to fit the current window: + +| Constant | Value | Meaning | +|---------------------------|-------|----------------------------------------------------------------------| +| **vbZoomAutoFit** | 0 | Recalculate zoom on every paint to maximise the page in the window. | +| **vbZoomAutoFitOnce** | 1 | Recalculate once, on the first paint, then leave [**ZoomPercent**](#zoompercent) alone. | +| **vbZoomAutoFitNever** | 2 | Honour whatever [**ZoomPercent**](#zoompercent) is currently set to. | + +Clicking the toolbar's plus or minus button automatically switches [**ZoomAutoFit**](#zoomautofit) to **vbZoomAutoFitNever** so the user's manual zoom sticks. + +## Drawing inside sections + +Every section's repaint raises [**BeforePaintSection**](#beforepaintsection) on the report, with the [**Section**](#beforepaintsection) being drawn as the argument. During this event, [**hDC**](#hdc) returns the metafile device context that the section is being recorded into — drawing primitives ([**Line**](#line), [**Circle**](#circle), [**PSet**](#pset), [**PaintPicture**](#paintpicture), [**Print**](#print), and direct GDI calls through [**hDC**](#hdc)) write straight into that section's image. Outside the event, [**hDC**](#hdc) returns the report window's own DC, suitable for screen drawing only. + +```tb +Private Sub Report_BeforePaintSection(Section As ControlsSection) + If Section.SectionType = PageHeader Then + Me.Line (0, 0)-(Me.PixelsReportWidth, 0), vbBlack + End If +End Sub +``` + +## Coordinate units + +A report mixes three coordinate systems: + +- **Window dimensions** — [**Width**](#width), [**Height**](#height), [**Left**](#left), and [**Top**](#top) describe the report window itself, in twips (the size of the on-screen frame, including the toolbar). +- **Client constraints** — [**MinWidth**](#minwidth), [**MinHeight**](#minheight), [**MaxWidth**](#maxwidth), and [**MaxHeight**](#maxheight) constrain the *client area* of the window during interactive resize, in twips. +- **Page dimensions** — [**PixelsReportWidth**](#pixelsreportwidth), [**PixelsReportHeight**](#pixelsreportheight), and the margin properties describe the *printed page*, in scaled pixels. + +The graphics primitives inherited from the form-style drawing surface ([**Cls**](#cls), [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), [**Print**](#print), …) use the report's own [**ScaleMode**](#scalemode) and [**Scale\***](#scaleleft) properties for their coordinate inputs. + +## Printing + +[**PrintReport**](#printreport) iterates from page 1 to the last page through the [**Printer**](../../VB/Printer) object, sending each cached metafile as one printed page. + +```tb +rptSales.PrintReport ShowDialog:=False +``` + +The print dialog is not yet supported in this beta; calling **PrintReport** with **ShowDialog := True** raises run-time error 5. Paper size is currently locked to A4 — a message box reminds the user of this on each print job. + +## Properties + +### Appearance +{: .no_toc } + +Determines how the report'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 report window. + +### AutoRedraw +{: .no_toc } + +Whether drawing performed on the report's window persists across invalidations. **Boolean**, default **False**. Reports normally rely on per-section painting through [**BeforePaintSection**](#beforepaintsection), so this property is rarely useful; it is provided for parity with [**Form**](../Form/). + +### BackColor +{: .no_toc } + +The background colour of the report window's drawing surface, as an **OLE_COLOR**. Defaults to the system 3-D face colour. Most of the window is occupied by the page preview (which uses [**PaperColor**](#papercolor)) and the toolbar, so this colour is only visible briefly during paint. + +### BorderStyle +{: .no_toc } + +The window-frame style. A member of [**FormBorderStyleConstants**](../../VBRUN/Constants/FormBorderStyleConstants): **vbBSNone**, **vbFixedSingle**, **vbSizable** (default), **vbFixedDialog**, **vbFixedToolWindow**, **vbSizableToolWindow**, **vbSizableNoTitleBar**, or **vbSizableToolWindowNoTitleBar**. + +### Caption +{: .no_toc } + +The title-bar text. **String**. Also returned by the `%i` [caption placeholder](#caption-placeholders) and reachable from a `=Report.Caption` expression in a label's `DataField`. + +### ChangePageSize +{: .no_toc } + +> [!NOTE] +> Design-time helper. Selecting a value from the IDE property grid sets [**PixelsReportWidth**](#pixelsreportwidth) and [**PixelsReportHeight**](#pixelsreportheight) to the corresponding paper size; the property itself has no run-time effect and always reads back as blank. + +A member of **ReportSizeConstants**: blank (default), **A4 Portrait**, **A4 Landscape**, **A3 Portrait**, **A3 Landscape**, **A5 Portrait**, **A5 Landscape**, **Letter Portrait**, **Letter Landscape**, **Tabloid Portrait**, **Tabloid Landscape**, **Legal Portrait**, **Legal Landscape**, **Statement Portrait**, **Statement Landscape**, **Executive Portrait**, **Executive Landscape**. + +### ClipControls +{: .no_toc } + +Whether child controls are clipped out of the report window's drawing region during paint. **Boolean**, default **True**. Read-only at run time — set at design time. + +### ControlBox +{: .no_toc } + +Whether the title bar shows the system menu (and, with it, the close button). **Boolean**, default **True**. + +### Controls +{: .no_toc } + +The collection of every control hosted by this report's sections, 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. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this object as a report. Always **vbReport**. + +### Count +{: .no_toc } + +The number of controls in [**Controls**](#controls), as a **Long**. Read-only. Equivalent to `Me.Controls.Count`. + +### CurrentX +{: .no_toc } + +The horizontal pen position used by drawing primitives that omit a starting coordinate, in [**ScaleMode**](#scalemode) units. **Double**. + +### CurrentY +{: .no_toc } + +The vertical pen position used by drawing primitives that omit a starting coordinate, in [**ScaleMode**](#scalemode) units. **Double**. + +### DpiScaleFactorX +{: .no_toc } + +The horizontal DPI scale factor of the monitor the report window is currently on, as a **Double**. `1.0` at 96 DPI, `1.25` at 120 DPI, and so on. Read-only. + +### DpiScaleFactorY +{: .no_toc } + +The vertical DPI scale factor of the monitor the report window 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. + +### 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 report window accepts user input. A disabled report ignores keyboard and mouse input — including the toolbar buttons. **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**](#print) statement and other text drawing on this report. 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 report 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**](#print). **OLE_COLOR**. + +### hDC +{: .no_toc } + +The Win32 device context handle currently relevant to drawing, as a **LongPtr**. Read-only. Inside a [**BeforePaintSection**](#beforepaintsection) handler, returns the metafile DC that the section is being recorded into; outside the event, returns the report window's own DC. Returns `0` when the underlying window has not yet been created. + +### HasDC +{: .no_toc } + +Whether the report window 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 report window's outer height, in twips. **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 report has focus. + +### hWnd +{: .no_toc } + +The Win32 window handle for the report, 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**. + +### Image +{: .no_toc } + +Returns the rendered drawing surface as a **StdPicture**. Read-only. Most useful when [**AutoRedraw**](#autoredraw) is **True**. + +### KeyPreview +{: .no_toc } + +When **True**, the report's [**KeyDown**](#keydown), [**KeyUp**](#keyup), and [**KeyPress**](#keypress) events fire *before* the focused control receives the same keystroke. **Boolean**, default **False**. + +### Left +{: .no_toc } + +The horizontal position of the report window's outer rectangle, in twips, 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**. + +### 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 report window's *client area*, in twips. **Double**, default `0` (no limit). Honoured during interactive resizing. + +### MaxWidth +{: .no_toc } + +The maximum width of the report window's *client area*, in twips. **Double**, default `0` (no limit). Honoured during interactive resizing. + +### MDIChild +{: .no_toc } + +When **True**, the report is hosted as a child inside an [**MDIForm**](../MDIForm/). **Boolean**, read-only — set at design time. An MDI child report 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 report window's *client area*, in twips. **Double**, default `0` (no limit). Honoured during interactive resizing. + +### MinWidth +{: .no_toc } + +The minimum width of the report window'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 report. + +### MousePointer +{: .no_toc } + +The mouse cursor shown when the pointer is over the report. A member of [**MousePointerConstants**](../../VBRUN/Constants/MousePointerConstants). + +### Moveable +{: .no_toc } + +Whether the user can drag the report window by its title bar. **Boolean**, default **True**. + +### Name +{: .no_toc } + +The unique design-time name of the report. Read-only at run time. Also the class name of the generated report class. + +### Opacity +{: .no_toc } + +The report window's opacity as a percentage (0–100, default 100). Values outside the range are clamped on **Initialize**. Values below 100 cause the window to become a layered window. + +### Page +{: .no_toc } + +The current page number being previewed (1-based). **Long**. Setting **Page** scrolls the preview to that page. Assigning `-1` jumps to the last page (rendering and caching all intermediate pages first). Reachable from a `=Report.Page` expression in a label's **DataField**, or via the `%p` [caption placeholder](#caption-placeholders). + +### Pages +{: .no_toc } + +The total number of pages in the report. **Long**. Initialised to `999` and revised down once the framework has rendered enough pages to know the actual count. Reachable from a `=Report.Pages` expression in a label's **DataField**, or via the `%P` [caption placeholder](#caption-placeholders). + +### PaperColor +{: .no_toc } + +The colour of the simulated paper behind the rendered page in the preview. **OLE_COLOR**, default **vbWhite**. + +> [!NOTE] +> This affects the *preview* only — it does not change the colour sent to the printer. + +### Picture +{: .no_toc } + +A **StdPicture** drawn as the report window'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**. + +### PixelsBottomMargin +{: .no_toc } + +The bottom page margin, in scaled pixels. **Double**, default `96 / 2.54` (≈ 1 cm). Stored in the form file as `BottomMargin`. + +### PixelsLeftMargin +{: .no_toc } + +The left page margin, in scaled pixels. **Double**, default `96 / 2.54` (≈ 1 cm). Stored in the form file as `LeftMargin`. + +### PixelsReportHeight +{: .no_toc } + +The page content height (between the top and bottom margins), in scaled pixels. **Double**, default `900`. Stored in the form file as `ReportHeight`. + +### PixelsReportWidth +{: .no_toc } + +The page content width (between the left and right margins), in scaled pixels. **Double**, default `300`. Stored in the form file as `ReportWidth`. + +### PixelsRightMargin +{: .no_toc } + +The right page margin, in scaled pixels. **Double**, default `96 / 2.54` (≈ 1 cm). Stored in the form file as `RightMargin`. + +### PixelsTopMargin +{: .no_toc } + +The top page margin, in scaled pixels. **Double**, default `96 / 2.54` (≈ 1 cm). Stored in the form file as `TopMargin`. + +### Recordset +{: .no_toc } + +The data source iterated for the detail section. Set with **Set**. + +Syntax: **Set** *object*.**Recordset** = *value* + +*value* +: Any object with `EOF`, `MoveNext`, and a `Fields` collection (a tB **ITbRecordset** is used directly; other recordsets are wrapped transparently). May be **Nothing**, in which case the detail section is rendered exactly once with no field data. + +Assigning **Recordset** does not by itself reset paging — call `Page = 1` (or **Refresh**) to start the preview at the new first page. + +### RecordNum +{: .no_toc } + +The 1-based ordinal of the record currently being processed by the detail section. **Long**. Updated by the framework as it iterates the recordset; useful inside expressions and [**BeforePaintSection**](#beforepaintsection) handlers. + +### 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 report window'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**. + +### ScaleTop +{: .no_toc } + +The logical vertical coordinate of the top edge of the report window'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**. + +### ShowInTaskbar +{: .no_toc } + +Whether the report window 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 report window'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. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the report. Ignored by the framework. + +### Top +{: .no_toc } + +The vertical position of the report window's outer rectangle, in twips, 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 report window sits in the always-on-top z-order layer. **Boolean**, read-only. + +### TransparencyKey +{: .no_toc } + +An **OLE_COLOR** that, when set, becomes fully transparent in the rendered report window — clicks pass through to whatever is underneath, and the corresponding pixels do not paint. Default `-1` disables the effect. + +### Visible +{: .no_toc } + +Whether the report window is shown. **Boolean**, default **True**. Setting **Visible** to **True** when the report was hidden is equivalent to calling [**Show**](#show) **vbModeless**; setting it to **False** is equivalent to calling [**Hide**](#hide). + +### Width +{: .no_toc } + +The report window's outer width, in twips. **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 report is visible. + +### ZoomAutoFit +{: .no_toc } + +Selects how [**ZoomPercent**](#zoompercent) is updated automatically. A member of **ZoomAutoFitConstants** (see [Zoom and page sizing](#zoom-and-page-sizing)): **vbZoomAutoFit** (0, default), **vbZoomAutoFitOnce** (1), or **vbZoomAutoFitNever** (2). The toolbar's plus and minus buttons switch this to **vbZoomAutoFitNever**. + +### ZoomPercent +{: .no_toc } + +The current rendering zoom, as a percentage. **Double**, default `100`. When [**ZoomAutoFit**](#zoomautofit) is **vbZoomAutoFit** or **vbZoomAutoFitOnce**, the framework recomputes this value before painting; the toolbar's plus and minus buttons add or subtract [**ZoomStep**](#zoomstep). + +### ZoomStep +{: .no_toc } + +The amount by which [**ZoomPercent**](#zoompercent) changes for each click of the toolbar's plus or minus button. **Long**, default `10`. + +## Methods + +### Circle +{: .no_toc } + +Draws a circle, ellipse, or arc on the current drawing surface (see [**hDC**](#hdc)) 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. + +### Close +{: .no_toc } + +Initiates the report window'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. + +Syntax: *object*.**Close** + +### Cls +{: .no_toc } + +Clears any drawing performed by [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), [**PaintPicture**](#paintpicture), and [**Print**](#print) on the current drawing surface, repaints [**BackColor**](#backcolor), and resets [**CurrentX**](#currentx) / [**CurrentY**](#currenty) to `0`. + +Syntax: *object*.**Cls** + +### Hide +{: .no_toc } + +Hides the report window without unloading it. The class instance and its sections 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 current drawing surface (see [**hDC**](#hdc)) 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. 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*). + +**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 report window 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. + +### PaintPicture +{: .no_toc } + +Draws a **StdPicture** onto the current drawing surface, 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. + +### Print +{: .no_toc } + +Writes text to the current drawing surface using [**Font**](#font), starting at [**CurrentX**](#currentx) / [**CurrentY**](#currenty) and advancing them as it goes. Inside a [**BeforePaintSection**](#beforepaintsection) handler the text lands on the section being painted; outside it, the text is drawn directly on the report window. + +Syntax: *object*.**Print** \[ *expressionlist* ] \[ **;** \| **,** ] + +A trailing `;` or `,` suppresses the newline so the next **Print** call continues on the same line. **Print** is the language-level statement, not a function call — multiple expressions can be separated by `;` (no spacing) or `,` (tab to the next print zone), and **Spc(n)** / **Tab(n)** insert spaces or move to a column. + +> [!NOTE] +> To send a report to the printer, use [**PrintReport**](#printreport) — not **Print**. + +### PrintReport +{: .no_toc } + +Sends every page of the report to the [**Printer**](../../VB/Printer) object. Iterates from page 1 to the last page, generating each cached metafile in turn. + +Syntax: *object*.**PrintReport** [ *ShowDialog* [, *Range* [, *PageFrom* [, *PageTo* ] ] ] ] + +*ShowDialog* +: *optional* When **True** (default), display the standard print dialog before printing. **Not yet supported** — calling **PrintReport** with **ShowDialog := True** raises run-time error 5. + +*Range* +: *optional* A member of **PageRangeConstants**: **rptRangeAllPages** (0, default) or **rptRangeFromTo** (1). + +*PageFrom*, *PageTo* +: *optional* When *Range* is **rptRangeFromTo**, the inclusive page range to print. + +> [!NOTE] +> The printer paper size is currently locked to A4 in this beta. + +### PSet +{: .no_toc } + +Sets a single pixel on the current drawing surface 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 report window. + +Syntax: *object*.**Refresh** + +### Scale +{: .no_toc } + +Sets the report window'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 report window and gives input focus to the control whose **TabIndex** is `0` (or to whichever control last held focus). + +Syntax: *object*.**SetFocus** + +### Show +{: .no_toc } + +Makes the report window 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 report is closed). + +*OwnerForm* +: *optional* For modal shows, the form that is disabled while the report is up; defaults to the currently active form. + +### TextHeight +{: .no_toc } + +Returns the height that the given string would occupy when drawn with the report'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 report's current [**Font**](#font), in [**ScaleMode**](#scalemode) units. + +Syntax: *object*.**TextWidth**( *Str* ) + +*Str* +: *required* A **String** to measure. + +### ZOrder +{: .no_toc } + +Brings the report window 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 report window 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**( ) + +### BeforePaintSection +{: .no_toc } + +Raised once for each section as it is rendered, before the framework draws the controls in that section. Inside the handler, [**hDC**](#hdc) returns the metafile device context the section is being recorded into, so any drawing primitives ([**Line**](#line), [**Circle**](#circle), [**Print**](#print), …) or direct GDI calls write straight into the section. + +Syntax: *object*\_**BeforePaintSection**( *Section* **As ControlsSection** ) + +*Section* +: The section currently being painted. Inspect *Section*`.SectionType` (**ReportHeader**, **PageHeader**, **Detail**, **PageFooter**, or **ReportFooter**) to discriminate. + +### Click +{: .no_toc } + +Raised when the user single-clicks the report window's client area (i.e. not over the toolbar or any child control). + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks the report window's client area. + +Syntax: *object*\_**DblClick**( ) + +### Deactivate +{: .no_toc } + +Raised when another window in the application takes activation away from this report. Not raised when activation moves to a window in a different application. + +Syntax: *object*\_**Deactivate**( ) + +### DPIChange +{: .no_toc } + +Raised when the report window moves to a monitor with a different DPI scale, *but only* when the application is per-monitor DPI aware (`PROCESS_PER_MONITOR_DPI_AWARE`). The event's *NewDPI* argument carries the new effective DPI. + +Syntax: *object*\_**DPIChange**( *NewDPI* **As Long** ) + +### GotFocus +{: .no_toc } + +Raised when the report window receives the input focus and no enabled child control of the report is in a position to take it instead. + +Syntax: *object*\_**GotFocus**( ) + +### Initialize +{: .no_toc } + +Raised once, before the underlying window is created and before any of the report's controls exist. Useful for setting initial values on report-level fields. + +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 report 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 report 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 report first. + +Syntax: *object*\_**KeyUp**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### Load +{: .no_toc } + +Raised after the report's window and all section controls have been created, just before the report first appears on screen. The classic place to assign [**Recordset**](#recordset) and perform any initialisation that needs the controls to exist. **Default event.** + +Syntax: *object*\_**Load**( ) + +### LostFocus +{: .no_toc } + +Raised when the report window loses the input focus. + +Syntax: *object*\_**LostFocus**( ) + +### MouseDown +{: .no_toc } + +Raised when the user presses any mouse button over the report window'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 report window'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 report window's client area. + +Syntax: *object*\_**MouseUp**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### QueryUnload +{: .no_toc } + +Raised before the report unloads, giving the application a chance to confirm or cancel the close. Setting *Cancel* to non-zero keeps the report 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. + +### Resize +{: .no_toc } + +Raised when the report window 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 report 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 report window is destroyed. Setting *Cancel* to non-zero keeps the report 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/Shape/index.md b/docs/Reference/VB/Shape/index.md new file mode 100644 index 0000000..45bab32 --- /dev/null +++ b/docs/Reference/VB/Shape/index.md @@ -0,0 +1,322 @@ +--- +title: Shape +parent: VB Package +permalink: /tB/Packages/VB/Shape/ +has_toc: false +--- + +# Shape class +{: .no_toc } + +A **Shape** is a windowless lightweight control that draws one of a fixed set of geometric primitives — rectangle, square, oval, circle, rounded rectangle, rounded square, five-pointed star, or an arrow pointing in any of the four cardinal directions — directly on its container. It exists purely for visual presentation: backgrounds, decorative artwork, panel dividers, highlighting, and any other place where a heavy [**PictureBox**](../PictureBox/) would be overkill. + +A **Shape** has no interaction surface — no focus, no caption, and no mouse, keyboard, or drag events. The shape kind and its appearance are chosen entirely through properties; the only event raised by the control is [**Initialize**](#initialize). The default property is [**Shape**](#shape) and the default event is [**Initialize**](#initialize). + +```tb +Private Sub Form_Load() + shpPanel.Shape = vbShapeRoundedRectangle + shpPanel.BorderColor = vbBlack + shpPanel.BorderWidth = 2 + shpPanel.FillStyle = vbFSSolid + shpPanel.FillColor = RGB(240, 240, 240) + shpPanel.BackStyle = vbBFOpaque +End Sub +``` + +* TOC +{:toc} + +## Windowless rendering + +A **Shape** has no `hWnd`. The framework paints it onto its parent's drawing surface during the parent's paint cycle, so the control is cheap — no Win32 window is created on its behalf and no per-instance overhead beyond a small piece of state. The trade-offs are the same as for any windowless control: + +- No focus, no keyboard input, no `KeyDown` / `KeyPress` / `KeyUp` / `GotFocus` / `LostFocus` / `Validate`. +- No mouse events of any kind — to make a region clickable, place a transparent [**Label**](../Label/) on top. +- No `hWnd` to pass to API functions, and no `SetFocus`. +- Cannot host child controls. + +For anything that needs those, use [**PictureBox**](../PictureBox/) or a custom **UserControl** instead. + +## Shape kinds + +[**Shape**](#shape) chooses which primitive is drawn, as a member of [**ShapeConstants**](../../VBRUN/Constants/ShapeConstants): + +| Constant | Value | Drawn as | +|-------------------------------|-------|-----------------------------------------------------------------------------| +| **vbShapeRectangle** | 0 | Rectangle filling the control's bounds. | +| **vbShapeSquare** | 1 | Square inscribed in the bounds — the shorter side determines the size, the longer side is centred. | +| **vbShapeOval** | 2 | Ellipse filling the bounds. | +| **vbShapeCircle** | 3 | Circle inscribed in the bounds — the shorter side determines the diameter. | +| **vbShapeRoundedRectangle** | 4 | Rectangle with rounded corners; corner radius from [**RoundedCornerSize**](#roundedcornersize). | +| **vbShapeRoundedSquare** | 5 | Square inscribed in the bounds, with rounded corners. | +| **vbShapeStar** | 6 | Regular star polygon; configured through [**VariationA**](#variationa), [**VariationB**](#variationb), and [**VariationC**](#variationc). | +| **vbShapeArrowLeft** | 7 | Left-pointing arrow. | +| **vbShapeArrowRight** | 8 | Right-pointing arrow. | +| **vbShapeArrowUp** | 9 | Up-pointing arrow. | +| **vbShapeArrowDown** | 10 | Down-pointing arrow. | + +For **vbShapeCircle**, **vbShapeSquare**, and **vbShapeRoundedSquare**, the drawn primitive is square: the shorter of the control's width and height is used and the primitive is centred along the longer axis. The control's bounding rectangle is unchanged. + +## Stars and arrows + +Stars and arrows are parameterised through the three **Variation** properties, all **Long** with a sentinel default of `-1` that selects the built-in default geometry: + +For **vbShapeStar**: + +- [**VariationA**](#variationa) — number of points, clamped to the inclusive range `2`–`30`. Default `5`. +- [**VariationB**](#variationb) — inner-radius factor controlling how "thin" the star's arms are. Larger values produce thinner arms. Default chosen so the inner radius is half the outer radius. +- [**VariationC**](#variationc) — vertex-spread divisor, an integer from `1` to `12`. Lower values produce closely-bunched points; higher values produce a more conventional star. Default `12` (effectively a divisor of `2`). + +For **vbShapeArrowLeft**, **vbShapeArrowRight**, **vbShapeArrowUp**, **vbShapeArrowDown**: + +- [**VariationA**](#variationa) — arrowhead "height" along the arrow's axis, as a percentage (`0`–`100`) of the control's cross-axis dimension. Default `30` (i.e. `0.30`). +- [**VariationB**](#variationb) — arrowhead "depth" along the arrow's tip-to-tail axis, as a percentage (`0`–`100`) of the control's axis dimension. Default `50` (i.e. `0.50`). + +[**VariationC**](#variationc) is unused for arrows. + +## Background, fill, and gradients + +A **Shape** is painted in three logical layers: + +1. The control's background, governed by [**BackStyle**](#backstyle) and [**BackColor**](#backcolor). When [**BackStyle**](#backstyle) is **vbBFTransparent** (default), pixels outside the drawn shape but inside the control's bounding rectangle show whatever the parent painted underneath. When **vbBFOpaque**, those pixels are filled with [**BackColor**](#backcolor). +2. The interior of the shape, governed by [**FillStyle**](#fillstyle), [**FillColor**](#fillcolor), and (for gradients) [**FillColorAlt**](#fillcoloralt). +3. The shape's outline, governed by [**BorderStyle**](#borderstyle), [**BorderColor**](#bordercolor), and [**BorderWidth**](#borderwidth). + +[**FillStyle**](#fillstyle) is a member of [**FillStyleConstantsEx**](../../VBRUN/Constants/FillStyleConstantsEx): + +| Constant | Value | Interior | +|---------------------------|-------|----------------------------------------------------------------| +| **vbFSSolid** | 0 | Filled with [**FillColor**](#fillcolor). | +| **vbFSTransparent** | 1 | No fill (default — the shape's interior shows through). | +| **vbHorizontalLine** | 2 | Horizontal hatch in [**FillColor**](#fillcolor). | +| **vbVerticalLine** | 3 | Vertical hatch in [**FillColor**](#fillcolor). | +| **vbUpwardDiagonal** | 4 | `/`-direction diagonal hatch. | +| **vbDownwardDiagonal** | 5 | `\`-direction diagonal hatch. | +| **vbCross** | 6 | Orthogonal cross-hatch. | +| **vbDiagonalCross** | 7 | Diagonal cross-hatch. | +| **vbGradientNS** | 8 | Vertical gradient from [**FillColor**](#fillcolor) (top) to [**FillColorAlt**](#fillcoloralt) (bottom). | +| **vbGradientWE** | 9 | Horizontal gradient from [**FillColor**](#fillcolor) (left) to [**FillColorAlt**](#fillcoloralt) (right). | + +The gradient styles (**vbGradientNS**, **vbGradientWE**) use the Win32 `GradientFill` GDI primitive, which does not respect the world transform applied for rotation: when [**Angle**](#angle) is non-zero, the gradient styles fall back to a solid fill of [**FillColor**](#fillcolor). The hatch and gradient styles are clipped to the shape's outline using a GDI region matching the shape kind. + +## Border + +The outline is drawn with a Win32 GDI pen: + +- [**BorderColor**](#bordercolor) — the pen colour (defaults to the system window-text colour). +- [**BorderWidth**](#borderwidth) — the pen width in pixels (default `1`). +- [**BorderStyle**](#borderstyle) — the pen pattern, as a member of [**BorderStyleConstants**](../../VBRUN/Constants/BorderStyleConstants): **vbTransparent** (0 — no outline), **vbBSSolid** (1, default), **vbBSDash** (2), **vbBSDot** (3), **vbBSDashDot** (4), **vbBSDashDotDot** (5), or **vbBSInsideSolid** (6). + +As with [**Line**](../Line/), GDI forces a solid pen whenever [**BorderWidth**](#borderwidth) is greater than `1` — dashed and dotted patterns are only honoured at width `1`. + +## Rotation + +[**Angle**](#angle) rotates the rendered shape around the control's top-left point, in degrees, anti-clockwise. `0` (default) is the natural orientation; `90` is a quarter turn anti-clockwise; values between `0` and `360` give arbitrary rotations. The control's bounding rectangle on the parent does not change — large rotation angles can therefore push the visible shape outside the rectangle. The rendered pixels are bounded only by the parent's clip, not by the **Shape**'s own rectangle. + +Gradient fill styles do not honour rotation — see [Background, fill, and gradients](#background-fill-and-gradients). + +## Draw mode + +[**DrawMode**](#drawmode) selects the raster operation that combines the drawn pixels with the destination. A member of [**DrawModeConstants**](../../VBRUN/Constants/DrawModeConstants): **vbCopyPen** (default — opaque drawing) or one of the XOR / AND / NOT / merge variants. Non-default modes are mainly useful for "rubber-band" feedback drawn over an existing background — the same XOR applied twice cancels itself out, restoring the original pixels. + +## Properties + +### Anchors +{: .no_toc } + +The set of edges of the parent that the **Shape**'s corresponding edges follow when the parent resizes. Read-only — assign individual `.Left`, `.Top`, `.Right`, `.Bottom` flags through the returned **Anchors** object. + +### Angle +{: .no_toc } + +The rotation of the rendered shape, in degrees, anti-clockwise around the control's top-left corner. **Double**, default `0`. See [Rotation](#rotation) for the details and the gradient-fill caveat. + +### BackColor +{: .no_toc } + +The colour painted into the **Shape**'s bounding rectangle (outside the shape's own outline) when [**BackStyle**](#backstyle) is **vbBFOpaque**. **OLE_COLOR**, defaults to the system window-background colour. Has no effect when [**BackStyle**](#backstyle) is **vbBFTransparent**. + +### BackStyle +{: .no_toc } + +Whether the bounding rectangle around the shape is filled with [**BackColor**](#backcolor) or left transparent. A member of [**BackFillStyleConstants**](../../VBRUN/Constants/BackFillStyleConstants): **vbBFTransparent** (0, default) or **vbBFOpaque** (1). + +### BorderColor +{: .no_toc } + +The colour of the shape's outline, as an **OLE_COLOR**. Defaults to the system window-text colour. + +### BorderStyle +{: .no_toc } + +The pen pattern used for the outline. A member of [**BorderStyleConstants**](../../VBRUN/Constants/BorderStyleConstants): **vbTransparent** (0), **vbBSSolid** (1, default), **vbBSDash** (2), **vbBSDot** (3), **vbBSDashDot** (4), **vbBSDashDotDot** (5), or **vbBSInsideSolid** (6). Forced to **vbBSSolid** by Win32 whenever [**BorderWidth**](#borderwidth) is greater than `1`. + +### BorderWidth +{: .no_toc } + +The outline pen width, in pixels. **Long**, default `1`. Widths greater than `1` ignore [**BorderStyle**](#borderstyle) and always draw solid. + +### Container +{: .no_toc } + +The control that hosts this **Shape** — typically the form, a [**Frame**](../Frame/), or a **UserControl**. Read with **Get**, change with **Set**. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control. Always **vbShape**. This constant is shared with the [**Line**](../Line/) control — both are windowless geometric primitives. + +### Dock +{: .no_toc } + +Where the **Shape** is docked within its container. A member of [**DockModeConstants**](../../VBRUN/Constants/DockModeConstants): **vbDockNone** (default), **vbDockLeft**, **vbDockTop**, **vbDockRight**, **vbDockBottom**, or **vbDockFill**. Docked shapes ignore [**Anchors**](#anchors). + +### DrawMode +{: .no_toc } + +The raster operation that the shape drawing applies when combining its pixels 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. + +### FillColor +{: .no_toc } + +The primary colour used to fill the shape's interior. **OLE_COLOR**, defaults to the system scrollbar colour. Used as the only colour for solid and hatched fills, and as the start colour for gradient fills. Has no effect when [**FillStyle**](#fillstyle) is **vbFSTransparent**. + +### FillColorAlt +{: .no_toc } + +The secondary colour used as the end of a gradient fill. **OLE_COLOR**, defaults to `vbWhite`. Used only when [**FillStyle**](#fillstyle) is **vbGradientNS** or **vbGradientWE**. + +### FillStyle +{: .no_toc } + +The pattern used to fill the shape's interior, as a member of [**FillStyleConstantsEx**](../../VBRUN/Constants/FillStyleConstantsEx). Default **vbFSTransparent** (1) — the interior is not painted and shows through to the underlying parent pixels. See [Background, fill, and gradients](#background-fill-and-gradients) for the full table and the caveat for gradients combined with rotation. + +### Height +{: .no_toc } + +The control's height, in twips by default (or in the container's **ScaleMode** units). **Double**. + +### Index +{: .no_toc } + +When the **Shape** is part of a control array, the **Long** zero-based index of this instance within the array. Reading **Index** on a non-array instance raises run-time error 343 (*Object not an array*). Read-only at run time. + +### Left +{: .no_toc } + +The horizontal distance from the left edge of the container to the left edge of the control. **Double**. + +### Name +{: .no_toc } + +The unique design-time name of the **Shape** on its parent form. Read-only at run time. + +### Parent +{: .no_toc } + +A reference to the [**Form**](../Form/) (or **UserControl**) that ultimately contains the **Shape**. Read-only. + +### RoundedCornerSize +{: .no_toc } + +The radius, in the container's **ScaleMode** units, of the corner arc drawn when [**Shape**](#shape) is **vbShapeRoundedRectangle** or **vbShapeRoundedSquare**. **Long**, default `20`. Ignored for other shape kinds. + +### Shape +{: .no_toc } + +The geometric primitive drawn by the control. **Default property.** + +Syntax: *object*.**Shape** [ = *value* ] + +*value* +: A member of [**ShapeConstants**](../../VBRUN/Constants/ShapeConstants). See [Shape kinds](#shape-kinds) for the full table. + +When accessed through the default-property path (e.g. `Shape1 = vbShapeOval`), the value is read and written as a **Long** matching the underlying enum. + +### TabIndex +{: .no_toc } + +> [!NOTE] +> Inherited from the windowless-control base class but has no effect: a **Shape** does not accept focus and is skipped by TAB-key navigation regardless of this value. + +### TabStop +{: .no_toc } + +> [!NOTE] +> Inherited from the windowless-control base class but has no effect: a **Shape** does not accept focus and cannot be reached by the TAB key. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the **Shape**. Ignored by the framework. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the control. **Double**. + +### VariationA +{: .no_toc } + +First geometry parameter for the star and arrow shape kinds. **Long**, default `-1` (which selects the built-in default for the current shape). See [Stars and arrows](#stars-and-arrows) for the meaning per shape. + +### VariationB +{: .no_toc } + +Second geometry parameter for the star and arrow shape kinds. **Long**, default `-1`. See [Stars and arrows](#stars-and-arrows). + +### VariationC +{: .no_toc } + +Third geometry parameter, used only by **vbShapeStar**. **Long**, default `-1`. See [Stars and arrows](#stars-and-arrows). + +### Visible +{: .no_toc } + +Whether the **Shape** is drawn. **Boolean**, default **True**. + +### Width +{: .no_toc } + +The control's width, in twips by default (or in the container's **ScaleMode** units). **Double**. + +## Methods + +### Move +{: .no_toc } + +Repositions and optionally resizes the **Shape** in a single call. + +Syntax: *object*.**Move** *Left* [, *Top* [, *Width* [, *Height* ] ] ] + +*Left* +: *required* A **Single** giving the new horizontal position. + +*Top*, *Width*, *Height* +: *optional* New values for the corresponding properties. Omitted values are left unchanged. + +### Refresh +{: .no_toc } + +Forces an immediate repaint of the **Shape**'s bounding rectangle on the parent's drawing surface. + +Syntax: *object*.**Refresh** + +### ZOrder +{: .no_toc } + +Brings the **Shape** to the front or back of the windowless-sibling stack within its container. + +Syntax: *object*.**ZOrder** [ *Position* ] + +*Position* +: *optional* A member of [**ZOrderConstants**](../../VBRUN/Constants/ZOrderConstants): **vbBringToFront** (0, default) or **vbSendToBack** (1). + +## Events + +### Initialize +{: .no_toc } + +Raised once, after the **Shape** has been wired into its container's paint cycle but before it is first painted. Useful for last-minute setup that depends on container state. **Default event.** + +Syntax: *object*\_**Initialize**( ) diff --git a/docs/Reference/VB/TextBox/index.md b/docs/Reference/VB/TextBox/index.md index e2251aa..00915f3 100644 --- a/docs/Reference/VB/TextBox/index.md +++ b/docs/Reference/VB/TextBox/index.md @@ -1,11 +1,712 @@ --- -nav_exclude: true -permalink: /tB/Packages/VB/TextBox +title: TextBox +parent: VB Package +permalink: /tB/Packages/VB/TextBox/ +has_toc: false --- -> [!WARNING] -> -> Pardon, we have not documented this class yet. +# TextBox class +{: .no_toc } -# TabIndex +A **TextBox** is a Win32 native edit control that lets the user enter and edit text. It can be configured as a single-line field (default) or a multi-line editor with optional scroll bars, can mask its content for password entry, restrict input to digits, and display a placeholder "cue banner" when empty. +The control is normally placed on a [**Form**](../Form) or **UserControl** at design time. The default property is [**Text**](#text) and the default-designer event is [**Change**](#change). + +```tb +Private Sub Form_Load() + Text1.MultiLine = True + Text1.ScrollBars = vbVertical + Text1.TextHint = "Type your message here..." +End Sub + +Private Sub Text1_Change() + lblCount.Caption = Len(Text1.Text) & " characters" +End Sub +``` + +* TOC +{:toc} + +## Single-line and multi-line modes + +[**MultiLine**](#multiline) selects between the single-line edit (the default) and a multi-line editor: + +- **Single-line.** The control accepts a single row of text. Pressing **Enter** does not insert a newline — it is handled by the form's default button, if any. [**ScrollBars**](#scrollbars) and most line-wrapping settings are ignored. +- **Multi-line.** The control accepts and displays multiple lines, with line wrapping based on the client width. **Enter** inserts a line break inside the control. [**ScrollBars**](#scrollbars) decides whether horizontal, vertical, both, or no scroll bars are shown. + +Changing [**MultiLine**](#multiline), [**ScrollBars**](#scrollbars), or [**HideSelection**](#hideselection) at run time recreates the underlying window — the contents, current [**MaxLength**](#maxlength), [**PasswordChar**](#passwordchar), and [**Locked**](#locked) state are preserved across the recreate. + +## Password masking + +When [**PasswordChar**](#passwordchar) is set to a non-empty string, the first character of that string is displayed in place of each character the user types. Reading [**Text**](#text) still returns the real characters. Setting [**PasswordChar**](#passwordchar) back to an empty string restores normal display. + +Password masking is a single-line edit feature — assigning [**PasswordChar**](#passwordchar) while [**MultiLine**](#multiline) is **True** has no visible effect on the displayed text. + +```tb +txtPassword.PasswordChar = "•" ' display a bullet for each character +``` + +## Cue banner + +[**TextHint**](#texthint) sets a placeholder string that appears, in a dimmed colour, while [**Text**](#text) is empty — useful for hinting at the expected content without occupying it. By default the hint is hidden as soon as the control receives the focus; set [**TextHintAlways**](#texthintalways) to **True** to keep it visible even when the empty control has focus (until the user starts typing). + +## Selection + +[**SelStart**](#selstart), [**SelLength**](#sellength), and [**SelText**](#seltext) read and modify the user's text selection. Reading any of them when no selection is active returns the caret position and an empty [**SelText**](#seltext). Assigning [**SelStart**](#selstart) or [**SelLength**](#sellength) scrolls the caret into view; assigning [**SelText**](#seltext) replaces the current selection with the assigned string and positions the caret immediately after the inserted text. + +By default the selection is hidden whenever the control loses focus. Set [**HideSelection**](#hideselection) to **False** to keep the highlight visible even when another control has the focus — useful when the application needs to draw the user's attention to a particular range of text after a search or validation. + +## Numbers only + +When [**NumbersOnly**](#numbersonly) is **True**, the edit control silently rejects any keystroke that is not a decimal digit. Sign characters, decimal separators, and thousand separators are *not* accepted — the property is a thin wrapper around the OS **ES_NUMBER** style and provides only digit filtering. Use a [**KeyPress**](#keypress) handler if you need more elaborate validation. + +## OLE drag-and-drop + +[**OLEDragMode**](#oledragmode) controls source-side drags. When set to **vbOLEDragAutomatic**, dragging selected text in the edit area starts an OLE drag whose payload is the selected text; if the destination accepts the drop with **vbDropEffectMove**, the selected range is removed from the box. + +[**OLEDropMode**](#oledropmode) controls drop-target behaviour: **vbOLEDropNone** ignores drops, **vbOLEDropManual** raises [**OLEDragOver**](#oledragover) and [**OLEDragDrop**](#oledragdrop) so the application can decide what to do, and **vbOLEDropAutomatic** lets the framework insert dropped text at the caret position without raising those events. + +## Data binding + +Setting [**DataSource**](#datasource) and [**DataField**](#datafield) connects the control's [**Text**](#text) to a field of a [**Data**](../Data) control's recordset. The bound value is read as a string on each row change (a **Null** field becomes an empty string), and the current [**Text**](#text) is written back when the row is saved. Modifying [**Text**](#text) — either by user input or by code — sets [**DataChanged**](#datachanged) and marks the recordset row as dirty. + +## Properties + +### Alignment +{: .no_toc } + +Horizontal alignment of the text within the control. + +Syntax: *object*.**Alignment** [ = *value* ] + +*value* +: A member of [**AlignmentConstants**](../../VBRUN/Constants/AlignmentConstants): **vbLeftJustify** (0, default), **vbRightJustify** (1), or **vbCenter** (2). Centred and right-aligned text require [**MultiLine**](#multiline) to be **True** when the platform's edit control does not natively support those alignments in single-line mode; tB supports them in both modes. + +### Anchors +{: .no_toc } + +The set of edges of the parent that the text box's corresponding edges follow when the parent resizes. Read-only — assign individual `.Left`, `.Top`, `.Right`, `.Bottom` flags through the returned **Anchors** object. + +### Appearance +{: .no_toc } + +Determines how the control's border is drawn by the OS. A member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). Only meaningful when [**BorderStyle**](#borderstyle) is **vbFixedSingleBorder** — chooses between a sunken 3-D edge and a thin flat border. + +### BackColor +{: .no_toc } + +The background colour of the edit area, as an **OLE_COLOR**. Defaults to the system window-background colour. + +### BorderStyle +{: .no_toc } + +Whether the text box is drawn with a border. A member of [**ControlBorderStyleConstants**](../../VBRUN/Constants/ControlBorderStyleConstants): **vbNoBorder** (0) or **vbFixedSingleBorder** (1, default). The exact appearance of the border depends on [**Appearance**](#appearance). + +### CausesValidation +{: .no_toc } + +Determines whether the previously focused control's [**Validate**](#validate) event runs before this control receives the focus. **Boolean**, default **True**. + +### Container +{: .no_toc } + +The control that hosts this text box — typically the form, a [**Frame**](../Frame), or a [**PictureBox**](../PictureBox). Read with **Get**, change with **Set**. Setting **Container** at run time re-parents the text box. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a text box. Always **vbTextBox**. + +### DataChanged +{: .no_toc } + +A run-time-only **Boolean** that becomes **True** when [**Text**](#text) has been modified since the last save, and is cleared once the change has been written back to the recordset. + +### DataField +{: .no_toc } + +The name of the field, in the recordset of the bound [**DataSource**](#datasource), whose value is mirrored by [**Text**](#text). **String**. + +### DataFormat +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +A **StdDataFormat** that converts between the raw recordset value and the displayed text. + +### DataMember +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +When the [**DataSource**](#datasource) exposes more than one recordset, the name of the member to bind to. + +### DataSource +{: .no_toc } + +A reference to a [**Data**](../Data) control (or other **DataSource** provider) whose recordset supplies the value for [**DataField**](#datafield). Set with **Set**. + +### Dock +{: .no_toc } + +Where the text box is docked within its container. A member of [**DockModeConstants**](../../VBRUN/Constants/DockModeConstants): **vbDockNone** (default), **vbDockLeft**, **vbDockTop**, **vbDockRight**, **vbDockBottom**, or **vbDockFill**. Docked text boxes ignore [**Anchors**](#anchors). + +### DragIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor while the control is being drag-and-dropped (see [**Drag**](#drag) and [**DragMode**](#dragmode)). + +### DragMode +{: .no_toc } + +Whether the control should drag itself when the user holds the mouse over it. A member of [**DragModeConstants**](../../VBRUN/Constants/DragModeConstants): **vbManual** (0, default — call [**Drag**](#drag) from code) or **vbAutomatic** (1). + +### Enabled +{: .no_toc } + +Determines whether the control accepts user input. A disabled text 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 the text. The convenience properties [**FontName**](#fontname), [**FontSize**](#fontsize), [**FontBold**](#fontbold), [**FontItalic**](#fontitalic), [**FontStrikethru**](#fontstrikethru), and [**FontUnderline**](#fontunderline) read or write the corresponding members of this object. + +### FontBold +{: .no_toc } + +Shortcut for [**Font**](#font)`.Bold`. **Boolean**. + +### FontItalic +{: .no_toc } + +Shortcut for [**Font**](#font)`.Italic`. **Boolean**. + +### FontName +{: .no_toc } + +Shortcut for [**Font**](#font)`.Name`. **String**. + +### FontSize +{: .no_toc } + +Shortcut for [**Font**](#font)`.Size` — the point size. **Single**. + +### FontStrikethru +{: .no_toc } + +Shortcut for [**Font**](#font)`.Strikethrough`. **Boolean**. + +### FontUnderline +{: .no_toc } + +Shortcut for [**Font**](#font)`.Underline`. **Boolean**. + +### 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). **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. + +### HideSelection +{: .no_toc } + +When **True** (default), the selection highlight is hidden whenever the control loses the focus; when **False**, the highlight remains visible after focus moves elsewhere. **Boolean**. Changing this at run time recreates the underlying window. + +### hWnd +{: .no_toc } + +The Win32 window handle for the underlying edit control, as a **LongPtr**. Read-only. Useful for passing to API functions. + +### Index +{: .no_toc } + +When the control is part of a control array, the **Long** zero-based index of this instance within the array. Reading **Index** on a non-array instance raises run-time error 343 (*Object not an array*). Read-only at run time. + +### Left +{: .no_toc } + +The horizontal distance from the left edge of the container to the left edge of the control. **Single**. + +### LinkItem +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkMode +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +A member of [**LinkModeConstants**](../../VBRUN/Constants/LinkModeConstants). + +### LinkTimeout +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkTopic +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### Locked +{: .no_toc } + +When **True**, the user can scroll, select, and copy text but cannot modify it. **Boolean**, default **False**. Distinct from [**Enabled**](#enabled) — a locked text box is still drawn normally and continues to raise focus and mouse events, whereas a disabled one is dimmed and ignores input entirely. + +### MaxLength +{: .no_toc } + +The maximum number of characters the user can type into the control. **Long**, default `0` — when zero, the OS imposes its own limit (typically 32 767 characters for single-line, much larger for multi-line). Setting **MaxLength** below the current text length does not truncate what is already there, but blocks further typing until the user deletes enough characters. + +### 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). + +### MultiLine +{: .no_toc } + +When **True**, the control accepts multiple lines of text, displays line wrapping, and routes **Enter** to insert a line break. When **False** (default), the control holds a single line. **Boolean**. Changing this at run time recreates the underlying window. + +### Name +{: .no_toc } + +The unique design-time name of the control on its parent form. Read-only at run time. + +### NumbersOnly +{: .no_toc } + +When **True**, the edit control rejects keystrokes other than the decimal digits **0**–**9**. **Boolean**, default **False**. Does not validate code-assigned values, sign characters, decimal points, or thousand separators — use a [**KeyPress**](#keypress) handler for richer filtering. + +### OLEDragMode +{: .no_toc } + +Whether the control's selected text 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). + +### OLEDropMode +{: .no_toc } + +How the control responds to OLE drops. A member of [**OLEDropConstants**](../../VBRUN/Constants/OLEDropConstants): **vbOLEDropNone**, **vbOLEDropManual**, or **vbOLEDropAutomatic** (which inserts the dropped text at the caret without raising [**OLEDragDrop**](#oledragdrop)). + +### Opacity +{: .no_toc } + +The control's opacity as a percentage (0–100, default 100). Values outside the range are clamped on **Initialize**. Requires Windows 8 or later for child controls. + +### Parent +{: .no_toc } + +A reference to the [**Form**](../Form) (or **UserControl**) that ultimately contains this control. Read-only. Distinct from [**Container**](#container), which returns the immediate parent. + +### PasswordChar +{: .no_toc } + +A **String** whose first character is displayed in place of each typed character, masking the contents on screen. **String**, default empty (no masking). Reading [**Text**](#text) still returns the real characters. Effective in single-line mode only. + +### RightToLeft +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. + +### ScrollBars +{: .no_toc } + +Which scroll bars the multi-line text box displays. A member of [**ScrollBarConstants**](../../VBRUN/Constants/ScrollBarConstants): **vbSBNone** (0, default), **vbHorizontal** (1), **vbVertical** (2), or **vbBoth** (3). Ignored when [**MultiLine**](#multiline) is **False**. Changing this at run time recreates the underlying window. + +When the vertical scroll bar is enabled in a wrapping multi-line box, the horizontal scroll bar disables word wrap — lines extend past the right edge instead of wrapping. + +### SelLength +{: .no_toc } + +The number of characters currently selected. **Long**. Setting it extends or shrinks the selection from [**SelStart**](#selstart) and scrolls the caret into view. + +### SelStart +{: .no_toc } + +The zero-based position of the start of the selection, or the caret position when no text is selected. **Long**. Setting it clears the existing selection, moves the caret to the new position, and scrolls the caret into view. + +### SelText +{: .no_toc } + +The text currently selected. Assigning a string replaces the selection with that string and positions the caret immediately after the inserted text. **String**. + +### TabFocusAutoSelect +{: .no_toc } + +When **True** (default), the entire contents of the text box are automatically selected when the user moves focus to it with the **TAB** key. **Boolean**. The parent form's `TabFocusAutoSelect` property must also be **True** for this setting to take effect — when the form-level switch is **False**, the per-control value is ignored. + +### 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 control. **String**. **Default property.** + +Syntax: *object*.**Text** [ = *string* ] + +Assigning a value that differs from the current one raises a [**Change**](#change) event and refreshes the display. Assigning the same value is a no-op. In multi-line mode, line breaks are stored using the platform's native newline encoding (`vbCrLf` on Windows). + +### TextHint +{: .no_toc } + +A placeholder **String** displayed in a dimmed colour when [**Text**](#text) is empty — the Win32 *cue banner*. Default empty (no cue). The hint disappears as soon as the user starts typing. + +### TextHintAlways +{: .no_toc } + +When **True**, [**TextHint**](#texthint) is also shown while the empty control has the input focus; when **False** (default), the hint disappears the moment the control is focused. **Boolean**. + +### ToolTipText +{: .no_toc } + +A multi-line **String** displayed as a tooltip when the user hovers over the control. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the control. **Single**. + +### TransparencyKey +{: .no_toc } + +An **OLE_COLOR** that, when set, becomes fully transparent in the rendered control. Default `-1` disables the effect. Requires Windows 8 or later for child controls. + +### Visible +{: .no_toc } + +Whether the control is shown. **Boolean**, default **True**. + +### 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 a multi-line text box raise the [**Scroll**](#scroll) event; when **False**, the wheel still scrolls the contents 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). + +### LinkExecute +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkPoke +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkRequest +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkSend +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### 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 + +### Change +{: .no_toc } + +Raised whenever [**Text**](#text) changes — either through user input or by code assigning a new value. Not raised during [**Initialize**](#initialize); the very first text load from the serialized form does not produce a **Change** event. **Default-designer event.** + +Syntax: *object*\_**Change**( ) + +### Click +{: .no_toc } + +Raised when the user clicks the control with any mouse button. Issued from the [**MouseUp**](#mouseup) handler when the mouse-down was captured by this control and the click did not come from a double-click. + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks the control. Suppresses the synthetic [**Click**](#click) that would otherwise fire from the second [**MouseUp**](#mouseup). + +Syntax: *object*\_**DblClick**( ) + +### DragDrop +{: .no_toc } + +Raised on the destination control when a manual drag operation ends over it. + +Syntax: *object*\_**DragDrop**( *Source* **As Control**, *X* **As Single**, *Y* **As Single** ) + +### DragOver +{: .no_toc } + +Raised on the control under the cursor while a manual drag operation is in progress. + +Syntax: *object*\_**DragOver**( *Source* **As Control**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### GotFocus +{: .no_toc } + +Raised when the control receives the input focus. + +Syntax: *object*\_**GotFocus**( ) + +### Initialize +{: .no_toc } + +Raised once, after the underlying window has been created and [**Text**](#text), [**Locked**](#locked), [**MaxLength**](#maxlength), [**TextHint**](#texthint), and [**PasswordChar**](#passwordchar) have been applied from the serialized data. [**Change**](#change) does not fire for this initial text load. + +Syntax: *object*\_**Initialize**( ) + +### KeyDown +{: .no_toc } + +Raised when the user presses any key while the control has focus. + +Syntax: *object*\_**KeyDown**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### KeyPress +{: .no_toc } + +Raised when the user types a character that produces an ANSI keystroke. + +Syntax: *object*\_**KeyPress**( *KeyAscii* **As Integer** ) + +### KeyUp +{: .no_toc } + +Raised when the user releases a key while the control has focus. + +Syntax: *object*\_**KeyUp**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### LinkClose +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkError +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkNotify +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LinkOpen +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC. + +### LostFocus +{: .no_toc } + +Raised when the control loses the input focus. + +Syntax: *object*\_**LostFocus**( ) + +### MouseDown +{: .no_toc } + +Raised when the user presses any mouse button over the control. + +Syntax: *object*\_**MouseDown**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseMove +{: .no_toc } + +Raised when the cursor moves over the control. While [**OLEDragMode**](#oledragmode) is **vbOLEDragAutomatic**, **MouseMove** also tracks whether the cursor is over selected text so that the IBeam cursor switches to a pointer ahead of an auto-drag. + +Syntax: *object*\_**MouseMove**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseUp +{: .no_toc } + +Raised when the user releases a mouse button over the control. + +Syntax: *object*\_**MouseUp**( *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### MouseWheel +{: .no_toc } + +Raised when the user rotates the mouse wheel while the control has focus or the cursor is over it. New in twinBASIC — there is no equivalent VB6 event. + +Syntax: *object*\_**MouseWheel**( *Delta* **As Integer**, *Horizontal* **As Boolean** ) + +*Delta* +: A positive or negative scroll delta in units of `WHEEL_DELTA` (120). + +*Horizontal* +: **True** for a horizontal-wheel rotation, **False** for the standard vertical wheel. + +### OLECompleteDrag +{: .no_toc } + +Raised on the source control when the OLE drag operation finishes, indicating which effect (copy, move, none) the destination accepted. + +Syntax: *object*\_**OLECompleteDrag**( *Effect* **As Long** ) + +### OLEDragDrop +{: .no_toc } + +Raised on the destination control when the user drops data on it (when [**OLEDropMode**](#oledropmode) is **vbOLEDropManual**). + +Syntax: *object*\_**OLEDragDrop**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single** ) + +### OLEDragOver +{: .no_toc } + +Raised on the destination control while an OLE drag passes over it. + +Syntax: *object*\_**OLEDragOver**( *Data* **As DataObject**, *Effect* **As Long**, *Button* **As Integer**, *Shift* **As Integer**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### OLEGiveFeedback +{: .no_toc } + +Raised on the source control during a drag so the application can adjust the cursor or other visual feedback. + +Syntax: *object*\_**OLEGiveFeedback**( *Effect* **As Long**, *DefaultCursors* **As Boolean** ) + +### OLESetData +{: .no_toc } + +Raised on the source control when the destination requests data in a format that was registered but not yet supplied. + +Syntax: *object*\_**OLESetData**( *Data* **As DataObject**, *DataFormat* **As Integer** ) + +### OLEStartDrag +{: .no_toc } + +Raised on the source control at the start of an OLE drag, so the application can populate the **DataObject** and choose the allowed effects. Also raised automatically when [**OLEDragMode**](#oledragmode) is **vbOLEDragAutomatic** and the user begins a drag from a non-empty selection. + +Syntax: *object*\_**OLEStartDrag**( *Data* **As DataObject**, *AllowedEffects* **As Long** ) + +### Scroll +{: .no_toc } + +Raised when a multi-line text box is scrolled — by the scroll bar (including thumb-track dragging), the keyboard, or the mouse wheel. Wheel-driven scrolling can be silenced by setting [**WheelScrollEvent**](#wheelscrollevent) to **False**. New in twinBASIC — there is no equivalent VB6 event. + +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/Timer/index.md b/docs/Reference/VB/Timer/index.md new file mode 100644 index 0000000..9fc2881 --- /dev/null +++ b/docs/Reference/VB/Timer/index.md @@ -0,0 +1,141 @@ +--- +title: Timer +parent: VB Package +permalink: /tB/Packages/VB/Timer/ +has_toc: false +--- + +# Timer class +{: .no_toc } + +A **Timer** is a non-visual Win32 control that raises a [**Timer**](#timer) event at a programmable interval. Drop one onto a [**Form**](../Form/) (or **UserControl**) at design time, set [**Interval**](#interval) to the desired millisecond period, set [**Enabled**](#enabled) to **True**, and handle the [**Timer**](#timer) event. Timers are invisible at run time — they appear only as icons in the designer. + +The default property is [**Enabled**](#enabled) and the default event is [**Timer**](#timer). + +```tb +Private Sub Form_Load() + Timer1.Interval = 1000 ' fire once per second + Timer1.Enabled = True +End Sub + +Private Sub Timer1_Timer() + lblClock.Caption = Format$(Now, "hh:mm:ss") +End Sub +``` + +* TOC +{:toc} + +## Starting and stopping + +Two properties between them decide whether the [**Timer**](#timer) event fires: + +- [**Enabled**](#enabled) is the master switch. While it is **False**, the timer is dormant regardless of [**Interval**](#interval). +- [**Interval**](#interval) is the period between events, in milliseconds. Setting it to `0` stops events from firing even while [**Enabled**](#enabled) remains **True**. + +Either property can be flipped from inside the [**Timer**](#timer) handler itself — a one-shot timer disables itself on the first tick: + +```tb +Private Sub tmrStartup_Timer() + tmrStartup.Enabled = False ' fire only once + LoadInitialData +End Sub +``` + +Assigning a negative value to [**Interval**](#interval) raises run-time error 380 (*Invalid property value*). + +## Accuracy and resolution + +The control wraps Win32's per-window timer queue, which is driven by the standard message pump. Two consequences follow: + +- **Resolution is coarse.** The OS quantises timer ticks to the system clock-tick period — typically ~15.6 ms on desktop Windows. Intervals shorter than that are silently rounded up. For sub-millisecond pacing use a multimedia timer or `QueryPerformanceCounter` directly. +- **Ticks can be skipped under load.** If the message pump is blocked when a tick is due, no events queue up — the runtime delivers a single [**Timer**](#timer) event when the pump catches up, *not* one for each missed period. Long-running work inside the handler therefore lengthens the next interval rather than producing a backlog. + +For periodic UI updates (a clock, a progress animation, a poll for external state) the **Timer** is exactly the right tool. For precise wall-clock pacing, audio scheduling, or anything that must keep up under heavy CPU load, it is not. + +## Control arrays + +A control array of timers lets one handler service several periodic tasks while keeping a single shared code path. The array is declared at design time on the first item; further items are added at run time with **Load** and removed with **Unload**, exactly as for a windowed control. Inside the shared [**Timer**](#timer) handler, [**Index**](#index) identifies which timer fired. + +```tb +Private Sub tmrPoll_Timer(Index As Integer) + Select Case Index + Case 0: RefreshStatus + Case 1: PollPrinterQueue + Case 2: TrimLogFile + End Select +End Sub +``` + +[**Index**](#index) raises run-time error 343 (*Object not an array*) when read on a timer that is not part of a control array. + +## Properties + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a timer. Always **vbTimer**. + +### Enabled +{: .no_toc } + +The master switch for the timer. While **False**, the timer is dormant and the [**Timer**](#timer) event does not fire regardless of [**Interval**](#interval). **Boolean**, default **True**. **Default property.** + +Syntax: *object*.**Enabled** [ = *boolean* ] + +### Index +{: .no_toc } + +When the timer is part of a control array, the **Long** zero-based index of this instance within the array. Read-only at run time. Raises run-time error 343 (*Object not an array*) on a timer that is not part of an array. + +### Interval +{: .no_toc } + +The period between [**Timer**](#timer) events, in milliseconds. **Long**, default `0`. + +Syntax: *object*.**Interval** [ = *value* ] + +*value* +: A non-negative **Long** giving the interval in milliseconds. Setting `0` stops events from firing. Negative values raise run-time error 380 (*Invalid property value*). + +The effective resolution is the OS clock-tick period (~15.6 ms on desktop Windows); shorter intervals are silently rounded up. See [Accuracy and resolution](#accuracy-and-resolution). + +### Left +{: .no_toc } + +The horizontal position of the timer icon in the designer, in the container's **ScaleMode** units. **Single**. The runtime value has no visual effect — the timer is invisible — but it is preserved so the designer can place the icon back where it was. + +### Name +{: .no_toc } + +The unique design-time name of the timer on its parent form. **String**, read-only at run time. + +### Parent +{: .no_toc } + +A reference to the [**Form**](../Form/) (or **UserControl**) that contains this timer. Read-only. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the timer. Ignored by the framework. Inherited from the base control class. Useful for control arrays — e.g. holding the name of the operation a poll-timer is responsible for. + +### Top +{: .no_toc } + +The vertical position of the timer icon in the designer. Counterpart to [**Left**](#left); like [**Left**](#left), it has no visual effect at run time. + +## Events + +### Timer +{: .no_toc } + +Raised every [**Interval**](#interval) milliseconds while [**Enabled**](#enabled) is **True** and [**Interval**](#interval) is greater than zero. **Default event.** + +Syntax: *object*\_**Timer**( ) + +For a timer that is part of a control array, the handler receives the array [**Index**](#index) of the timer that fired: + +Syntax: *object*\_**Timer**( *Index* **As Integer** ) + +The event is delivered through the normal Win32 message pump — see [Accuracy and resolution](#accuracy-and-resolution) for the implications. diff --git a/docs/Reference/VB/UserControl/index.md b/docs/Reference/VB/UserControl/index.md new file mode 100644 index 0000000..afdde73 --- /dev/null +++ b/docs/Reference/VB/UserControl/index.md @@ -0,0 +1,1118 @@ +--- +title: UserControl +parent: VB Package +permalink: /tB/Packages/VB/UserControl/ +has_toc: false +--- + +# UserControl class +{: .no_toc } + +A **UserControl** is the base class for designing a reusable ActiveX control in twinBASIC. Each control designed in the IDE becomes its own class derived from **UserControl** — its child controls become members of that class, its event handlers become methods on it, and the file's name becomes the COM class name registered with the runtime. Hosts that embed the control (the twinBASIC IDE, classic VB6, Office, any other ActiveX container) talk to it through the standard ActiveX control interfaces, while the design-time code-behind talks to it as a regular twinBASIC class. + +A **UserControl** is not directly visible at run time as a property of an outer form. The host wraps it in an **Extender** object that adds the standard container properties (**Top**, **Left**, **Width**, **Height**, **Name**, **Visible**, **TabIndex**, …) and the user code reaches the extender through [**Extender**](#extender). The inner **UserControl** keeps a graphics surface, a private property bag, and the lifecycle events through which the host loads and saves the control's persistent state. + +The default-designer event is [**Initialize**](#initialize) — double-clicking the control surface in the IDE adds a `UserControl_Initialize` handler. + +```tb +' In MyMonthView's code-behind: +Private mFirstDay As Date + +Private Sub UserControl_InitProperties() + mFirstDay = Date ' first time the host instantiates a fresh control +End Sub + +Private Sub UserControl_ReadProperties(PropBag As PropertyBag) + mFirstDay = PropBag.ReadProperty("FirstDay", Date) +End Sub + +Private Sub UserControl_WriteProperties(PropBag As PropertyBag) + PropBag.WriteProperty "FirstDay", mFirstDay, Date +End Sub + +Public Property Get FirstDay() As Date + FirstDay = mFirstDay +End Property + +Public Property Let FirstDay(ByVal Value As Date) + mFirstDay = Value + PropertyChanged "FirstDay" ' tells the host the design surface is dirty + UserControl.Refresh +End Property +``` + +* TOC +{:toc} + +## Lifecycle + +A user control instance goes through up to seven distinct events from creation to destruction. The host drives the sequence: + +| Event | When | +|----------------------------------------|-----------------------------------------------------------------------------------------------------| +| [**Initialize**](#initialize) | Before the underlying window exists. Child controls are not yet created. | +| [**InitProperties**](#initproperties) | Once, for a brand-new instance with no saved property bag (a fresh drop on a design surface). | +| [**ReadProperties**](#readproperties) | Once, for an instance reloaded from a property bag (every load after the first save). | +| [**Resize**](#resize) | When the host first sizes the control, and on every subsequent size change. | +| [**Show**](#show) / [**Hide**](#hide) | When the host changes the container's visibility — typically as the host's design view / run view changes. | +| [**WriteProperties**](#writeproperties)| When the host asks the control to persist its state — design-time saves, host-driven serialisation. | +| [**Terminate**](#terminate) | After the window has been destroyed and the class instance is about to be released. | + +For each instance, exactly one of **InitProperties** or **ReadProperties** runs after [**Initialize**](#initialize), depending on whether the host had a saved property bag. [**WriteProperties**](#writeproperties) is only raised when [**PropertyChanged**](#propertychanged) has been called at least once since the last save, so handlers that never mark themselves dirty are never asked to write. + +## Persistent properties + +Public read/write members are exposed to the host as design-time properties automatically. Persistent storage goes through the [**PropertyBag**](../../VBRUN/PropertyBag/) object handed to [**ReadProperties**](#readproperties) and [**WriteProperties**](#writeproperties); the property bag interns string keys and a small set of variant-friendly types. Calling [**PropertyChanged**](#propertychanged) (optionally with the property name) sets the host's *dirty* flag so the host knows to call [**WriteProperties**](#writeproperties) at the next save. + +```tb +Public Property Let Caption(ByVal Value As String) + Label1.Caption = Value + PropertyChanged "Caption" +End Property +``` + +## Host integration + +[**Extender**](#extender) returns the host's wrapper around this control — usually an object exposing **Top**, **Left**, **Width**, **Height**, **Name**, **Visible**, **TabIndex**, **TabStop**, **Container**, **Parent**, and any host-specific extras. [**Parent**](#parent) is shorthand for `Extender.Parent` — the form (or sheet, or page) that ultimately hosts the control. [**ParentControls**](#parentcontrols) is a live enumerator over every sibling control on that parent, useful for design-time inspection. + +[**Ambient**](#ambient) exposes the host's ambient properties (the colours, font, locale, and design/run-mode flags the host wants child controls to honour). Changes to any of those raise the [**AmbientChanged**](#ambientchanged) event with the name of the affected property. + +[**Verbs**](#verbs) and [**VerbInvoked**](#verbinvoked) let the control register host-invokable commands (entries that appear on the host's context menu for the control). [**PropertyPages**](#propertypages) registers the **CLSID**s of additional [**PropertyPage**](../PropertyPage) classes that the host should offer through the property browser. + +## Drawing surface + +A **UserControl** is a graphics surface in its own right. The full set of VB6 drawing primitives — [**Cls**](#cls), [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), [**PaintPicture**](#paintpicture), and the [**Print**](#print) statement — write to its device context, using [**ForeColor**](#forecolor), [**FillColor**](#fillcolor)/[**FillStyle**](#fillstyle), [**DrawWidth**](#drawwidth), [**DrawMode**](#drawmode), and [**DrawStyle**](#drawstyle) for the pen and fill, and [**Font**](#font) for text. The current pen position is tracked by [**CurrentX**](#currentx) and [**CurrentY**](#currenty); [**TextWidth**](#textwidth) and [**TextHeight**](#textheight) measure a string in the current font; [**ScaleX**](#scalex) and [**ScaleY**](#scaley) convert single coordinates between scale modes. + +The coordinate system is governed by [**ScaleMode**](#scalemode), [**ScaleLeft**](#scaleleft), [**ScaleTop**](#scaletop), [**ScaleWidth**](#scalewidth), and [**ScaleHeight**](#scaleheight), exactly as on a [**Form**](../Form). [**AutoRedraw**](#autoredraw) controls whether drawn output persists across paints — when **False** (default), the [**Paint**](#paint) event must redraw on every invalidation; when **True**, the control keeps an off-screen buffer that survives invalidations and the **Paint** event is suppressed. + +[**BackStyle**](#backstyle) chooses between an opaque background (the default — **BackColor** fills the surface) and a transparent one (the background is left untouched so that whatever is behind the control shows through). Transparent **UserControl**s are commonly windowless ([**Windowless**](#windowless) = **True**) so that mouse hit-testing follows the painted shape rather than the bounding rectangle. + +## Windowless mode + +Setting [**Windowless**](#windowless) to **True** asks the host to embed the control without giving it its own **HWND**. The control's painting goes through `IViewObject::Draw`, mouse hit-testing through `IViewObjectEx::QueryHitPoint`, and so on; the [**HitTest**](#hittest) event raises for each hit-test request so the control can refine which pixels register as "hits". Many hosts support windowless activation (the twinBASIC IDE, Office); some hosts do not — the framework transparently falls back to a windowed mode at activation time when that happens. + +[**hWnd**](#hwnd) returns `0` while the control is windowless-activated. [**PreKeyEvents**](#prekeyevents) — and the [**PreKeyDown**](#prekeydown) / [**PreKeyUp**](#prekeyup) events — are not available on a windowless **UserControl**. + +## Children and focus + +The **UserControl** can host child controls dropped onto it at design time. [**Controls**](#controls) is the collection of every such child, indexable by control name or zero-based position. The control is enumerable directly (`For Each ctrl In UserControl`) — [**Count**](#count) and [**InternalEnumerator**](#internalenumerator) forward to it. [**ContainedControls**](#containedcontrols) enumerates the same collection but as raw `IUnknown` references for low-level COM work. + +[**ActiveControl**](#activecontrol) returns the focused child, or **Nothing** when no control on this surface has the focus. [**SetFocus**](#setfocus) gives the focus to the **UserControl** itself, which forwards it to its tab order. [**KeyPreview**](#keypreview) routes keystrokes through the **UserControl**'s [**KeyDown**](#keydown), [**KeyUp**](#keyup), and [**KeyPress**](#keypress) events *before* the focused child sees them — useful for handling **Escape**, **Tab**, or container-wide hotkeys. + +[**EnterFocus**](#enterfocus) and [**ExitFocus**](#exitfocus) fire when the focus enters or leaves the **UserControl** as a whole (the control itself or any descendant); [**GotFocus**](#gotfocus) and [**LostFocus**](#lostfocus) fire only when the **UserControl**'s own window — and no child — holds the focus. + +## Properties + +### AccessKeys +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. In VB6 the string lists single-character access keys that, pressed with **Alt**, raise [**AccessKeyPress**](#accesskeypress) on the **UserControl**. + +### ActiveControl +{: .no_toc } + +The control on this surface that currently has the input focus, as a **Control** object, or **Nothing** when no child on this control is focused. Read-only. + +### Alignable +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. In VB6 a **True** value told the host that the control honoured its container's **Align** property (so that it could be docked to a form edge). + +### Ambient +{: .no_toc } + +A snapshot of the host's [**AmbientProperties**](../../VBRUN/AmbientProperties/). Read-only. Returns a live pass-through wrapper around the host's `IDispatch`, so each member access reads the current ambient value. Changes to any ambient property raise [**AmbientChanged**](#ambientchanged) with the property's name. + +### Appearance +{: .no_toc } + +A member of [**AppearanceConstants**](../../VBRUN/Constants/AppearanceConstants): **vbAppearFlat** or **vbAppear3d** (default). Only meaningful when [**BorderStyle**](#borderstyle) is **vbFixedSingleBorder** — controls whether the border is drawn flat or 3-D. + +### AutoRedraw +{: .no_toc } + +Whether drawing performed on the control persists across invalidations. **Boolean**, default **False**. + +When **False**, drawing primitives — [**Cls**](#cls), [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), [**PaintPicture**](#paintpicture), and [**Print**](#print) — paint directly to the screen and the control must redraw them in its [**Paint**](#paint) event whenever the affected area is invalidated. When **True**, the control 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 control's surface, as an **OLE_COLOR**. Defaults to the system 3-D face colour. Has no visible effect when [**BackStyle**](#backstyle) is **vbBFTransparent**. + +### BackStyle +{: .no_toc } + +Whether the control's background is opaque or transparent. A member of [**BackFillStyleConstants**](../../VBRUN/Constants/BackFillStyleConstants): **vbBFTransparent** (0) or **vbBFOpaque** (1, default). Setting **BackStyle** to **vbBFTransparent** stops the framework from clearing the surface to [**BackColor**](#backcolor) on each paint — useful when the control wants to draw a non-rectangular shape over whatever is behind it. Typically used with [**Windowless**](#windowless) = **True**. + +### BorderStyle +{: .no_toc } + +The border drawn around the control. A member of [**ControlBorderStyleConstants**](../../VBRUN/Constants/ControlBorderStyleConstants): **vbNoBorder** (0, default) or **vbFixedSingleBorder** (1). Combined with [**Appearance**](#appearance) to choose flat or 3-D framing. + +### CanGetFocus +{: .no_toc } + +Whether the **UserControl** can take the input focus. **Boolean**, default **True**. Set at design time. A control that returns **False** is skipped over by the host's **TAB** navigation; useful for purely decorative controls. + +### ClipBehavior +{: .no_toc } + +How the framework clips the control to its assigned **Region** during paint. A member of **VbClipBehavior**: **vbClipNone** (0) or **vbClipUseRegion** (1, default). Only meaningful when the control supplies a non-rectangular **Region** to the host (typically through [**Windowless**](#windowless) hit-testing). + +### ContainedControls +{: .no_toc } + +A live enumerator over the child controls hosted by this **UserControl**, returned as raw `IUnknown` references rather than the typed **Control** objects exposed through [**Controls**](#controls). Read-only. Mostly useful for low-level COM scenarios. + +### ContainerHwnd +{: .no_toc } + +The Win32 window handle of the host container that frames this **UserControl**, as a **LongPtr**. Read-only. Returns `0` when the control is hosted by an object that does not expose a window (or before activation has happened). + +### ControlContainer +{: .no_toc } + +Whether the **UserControl** acts as a container that can host other ActiveX controls dropped onto it at design time. **Boolean**, read-only at run time. Set at design time. Setting **ControlContainer** to **True** tells the host to enumerate this control's children when walking the form's control collection. + +### Controls +{: .no_toc } + +The collection of every child control hosted by this **UserControl**, indexable by control name or zero-based position. Read-only — controls are added to the collection by the runtime, not by user code. + +```tb +Dim ctrl As Control +For Each ctrl In UserControl.Controls + ctrl.Enabled = False +Next +``` + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a user control. Always **vbUserControl**. + +### Count +{: .no_toc } + +The number of controls in [**Controls**](#controls), as a **Long**. Read-only. Equivalent to `UserControl.Controls.Count`. + +### CurrentX +{: .no_toc } + +The horizontal pen position, in [**ScaleMode**](#scalemode) units, used by drawing primitives that omit a starting coordinate (for example, [**Print**](#print) and the rectangle form of [**Line**](#line)). **Double**. + +### CurrentY +{: .no_toc } + +The vertical pen position, in [**ScaleMode**](#scalemode) units, used by drawing primitives that omit a starting coordinate. **Double**. + +### DataBindingBehavior +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. In VB6 this declared whether the control could be data-bound, and if so, whether it supported simple or complex binding. + +### DataMembers +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. Part of VB6's complex data-binding source-of-data interface. + +### DataSourceBehavior +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. In VB6 this declared whether the control could *provide* a data source for other controls to bind to. + +### DefaultCancel +{: .no_toc } + +Whether this **UserControl** acts as the **Cancel** button of its host form. **Boolean**, default **False**. Set at design time. When **True**, pressing **Escape** while focus is on the form raises [**AccessKeyPress**](#accesskeypress) on the control with the **Escape** key code. + +### DpiScale +{: .no_toc } + +The current DPI scale factor of the monitor the control 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. + +### DrawMode +{: .no_toc } + +The raster operation that drawing primitives apply when combining the pen with the destination. A member of [**DrawModeConstants**](../../VBRUN/Constants/DrawModeConstants), default **vbCopyPen**. + +### 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). + +### EditAtDesignTime +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. In VB6 a **True** value let the user activate the control's UI at design time through the **(Edit)** verb on the right-click menu. + +### Enabled +{: .no_toc } + +Determines whether the control accepts user input. A disabled control is dimmed and ignores keyboard and mouse interaction. **Boolean**, default **True**. + +### EventsFrozen +{: .no_toc } + +Whether the host has temporarily suspended event delivery to the control. **Boolean**, read-only. The host raises `IOleControl::FreezeEvents(TRUE)` during sensitive operations (for example, switching design view to run view) so that the control does not raise events while its surroundings are inconsistent. + +### Extender +{: .no_toc } + +The host's extender wrapper around this **UserControl**, as an **Object**. Read-only. The extender is the object the host exposes to user code as the control on the form — it provides standard container properties (**Top**, **Left**, **Width**, **Height**, **Name**, **Visible**, **TabIndex**, **TabStop**, **Container**, **Parent**, **DragMode**, **DragIcon**, …) plus whatever host-specific extras it likes. Returns **Nothing** when no extender is available (the control has not yet been embedded, or the host is too primitive to provide one). + +### 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**](#print) statement and other text drawing on this control. The convenience properties [**FontBold**](#fontbold), [**FontItalic**](#fontitalic), [**FontName**](#fontname), [**FontSize**](#fontsize), [**FontStrikethru**](#fontstrikethru), and [**FontUnderline**](#fontunderline) read or write the corresponding members of this object. + +### FontBold +{: .no_toc } + +Shortcut for [**Font**](#font)`.Bold`. **Boolean**. + +### FontItalic +{: .no_toc } + +Shortcut for [**Font**](#font)`.Italic`. **Boolean**. + +### FontName +{: .no_toc } + +Shortcut for [**Font**](#font)`.Name`. **String**. + +### FontSize +{: .no_toc } + +Shortcut for [**Font**](#font)`.Size` — the point size. **Single**. + +### FontStrikethru +{: .no_toc } + +Shortcut for [**Font**](#font)`.Strikethrough`. **Boolean**. + +### FontTransparent +{: .no_toc } + +When **True** (default), text drawn on the control 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**. + +### FontUnderline +{: .no_toc } + +Shortcut for [**Font**](#font)`.Underline`. **Boolean**. + +### ForceResizeToContainer +{: .no_toc } + +Whether the control automatically resizes itself to fill the host's container area regardless of any explicit size assigned in the designer. **Boolean**, read-only at run time. Set at design time. Useful for full-pane controls that should always span the available space. + +### ForeColor +{: .no_toc } + +The pen colour used by [**Circle**](#circle), [**Line**](#line), [**PSet**](#pset), and the text drawn by [**Print**](#print). **OLE_COLOR**. + +### ForwardFocus +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. In VB6 a **True** value told the host to forward focus from the **UserControl**'s shell window into its first child control whenever the host activated the **UserControl**. + +### FormDesignerId +{: .no_toc } + +A unique GUID-formatted **String** associating a designed code-behind class with a specific designer file. Read-only at run time — set by the IDE. + +### HasDC +{: .no_toc } + +Whether the control keeps a private device context (`CS_OWNDC`) for its drawing surface. **Boolean**, default **True**. Read-only at run time — set at design time. + +### HitBehavior +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. In VB6 this chose between bounding-rectangle hit-testing and pixel-perfect (region-based or paint-based) hit-testing for windowless controls. + +### hDC +{: .no_toc } + +The Win32 device context handle for the control, as a **LongPtr**. Read-only. Returns `0` when the underlying window has not yet been created. Useful for passing to GDI API calls. + +### hWnd +{: .no_toc } + +The Win32 window handle for the control, as a **LongPtr**. Read-only. Returns `0` while the control is windowless-activated ([**Windowless**](#windowless) = **True**). Useful for passing to API functions. + +### Hyperlink +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. In VB6 the property returned an **Hyperlink** object that let the control navigate the host's browser when one was available. + +### 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. + +### 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. Returns `0` and sets `HRESULT` to `0x800A0157` (*Object not an array*) for controls not in an array. + +### InvisibleAtRuntime +{: .no_toc } + +Whether the **UserControl** is hidden at run time. **Boolean**, read-only at run time. Set at design time. Useful for controls that exist only to provide a host-side service (timers, data sources) and have no visual presence. + +### KeyPreview +{: .no_toc } + +When **True**, the **UserControl**'s [**KeyDown**](#keydown), [**KeyUp**](#keyup), and [**KeyPress**](#keypress) events fire *before* the focused child receives the same keystroke. **Boolean**, default **False**. Useful for control-wide hotkeys; events still fire on the focused child afterwards. + +### Left +{: .no_toc } + +The horizontal position of the **UserControl** inside its host container, in the host's coordinate units. **Double**. Usually controlled by the host (or by the developer through the extender's **Move** method) rather than assigned directly. + +### MaskColor +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. In VB6 the colour was used as a transparency key for the bitmap supplied to **MaskPicture**. + +### MaskPicture +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. In VB6 the picture was used together with **MaskColor** to give the **UserControl** a non-rectangular shape. + +### 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 **UserControl** class. Read-only at run time. Also the class name of the generated user-control class. The host's extender exposes its own **Name** that identifies the instance on the form — the inner **UserControl**'s **Name** identifies the *class*. + +### 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. + +### Parent +{: .no_toc } + +The form (or other host object) that contains this **UserControl**, as an **Object**. Read-only. Equivalent to `Extender.Parent`. + +### ParentControls +{: .no_toc } + +A live collection of every sibling control on the host's parent — useful at design time for inspecting or coordinating with other controls on the same surface. Read-only. Supports indexed access (`ParentControls(0)`), enumeration (`For Each ctl In ParentControls`), and a **Count** member. Its **ParentControlsType** property toggles between the *extender*-wrapped view (the default — items are the host's extender objects) and the *raw* view (items are the inner `IUnknown` of each control). + +### PictureDpiScaling +{: .no_toc } + +> [!NOTE] +> The framework recognises this name on **Form** and on most intrinsic controls but does not currently expose it on **UserControl**. The drawing pipeline always renders **Picture** at its natural pixel size. + +### Picture +{: .no_toc } + +A **StdPicture** drawn as the control's background. Painted before any drawing primitives or child controls. Assigning **Nothing** removes the background. + +### PreKeyEvents +{: .no_toc } + +Whether the [**PreKeyDown**](#prekeydown) and [**PreKeyUp**](#prekeyup) events are raised for descendants of this **UserControl**. **Boolean**, read-only at run time — set at design time. Not available when [**Windowless**](#windowless) is **True**. + +### PropertyPages +{: .no_toc } + +An array of **String** **CLSID**s identifying the [**PropertyPage**](../PropertyPage) classes the host should offer through the **(Custom)** entry on the property browser. Read at the host's `ISpecifyPropertyPages::GetPages` call. Order matters — the array order is the tab order in the property-sheet dialog. + +```tb +Private Sub UserControl_Initialize() + ReDim PropertyPages(0 To 1) + PropertyPages(0) = "{}" + PropertyPages(1) = "{}" +End Sub +``` + +### Public +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. In VB6 this declared whether the **UserControl** class was visible outside its own project; in twinBASIC the **Public** modifier on the class declaration plays the same role. + +### 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 control'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 control'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**. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the control. Ignored by the framework. + +### Top +{: .no_toc } + +The vertical position of the **UserControl** inside its host container, in the host's coordinate units. **Double**. Usually controlled by the host. + +### Verbs +{: .no_toc } + +An array of **String** names registered with the host's `IOleObject::EnumVerbs` enumerator — each entry appears on the host's right-click menu for this control. Invoking one raises [**VerbInvoked**](#verbinvoked) with the verb's name. + +```tb +Private Sub UserControl_Initialize() + ReDim Verbs(0 To 1) + Verbs(0) = "Re&fresh" + Verbs(1) = "&Configure..." +End Sub + +Private Sub UserControl_VerbInvoked(ByVal Verb As String) + Select Case Verb + Case "Re&fresh" : DoRefresh + Case "&Configure...": ShowConfigDialog + End Select +End Sub +``` + +### Width +{: .no_toc } + +The control's width, in twips by default (or in the calling code's **ScaleMode** units). **Double**. Setting it resizes the control and raises [**Resize**](#resize). On a designer, the host's extender is updated through a round-trip so the design-time grid reflects the new size. + +### Height +{: .no_toc } + +The control's height. **Double**. Setting it resizes the control and raises [**Resize**](#resize). + +### Windowless +{: .no_toc } + +Whether the control supports windowless activation. **Boolean**, default **False**. Read-only at run time — set at design time. See [Windowless mode](#windowless-mode). + +## Methods + +### AsyncRead +{: .no_toc } + +> [!NOTE] +> Declared for VB6 compatibility; not currently implemented in twinBASIC. In VB6 this would start an asynchronous fetch from a host-supplied URL and raise [**AsyncReadComplete**](#asyncreadcomplete) when the data arrived. + +Syntax: *object*.**AsyncRead** *Target*, *AsyncType*, [, *PropertyName* [, *AsyncReadOptions* ] ] + +### CancelAsyncRead +{: .no_toc } + +> [!NOTE] +> Declared for VB6 compatibility; not currently implemented in twinBASIC. Companion to [**AsyncRead**](#asyncread). + +Syntax: *object*.**CancelAsyncRead** [ *Property* ] + +### CanPropertyChange +{: .no_toc } + +> [!NOTE] +> Declared for VB6 compatibility; not currently implemented in twinBASIC. In VB6 this returned **True** if the named property of the **DataSource** was writable — used by data-bound controls before pushing edited values back to the source. + +Syntax: *object*.**CanPropertyChange**( *PropertyName* ) + +### Circle +{: .no_toc } + +Draws a circle, ellipse, or arc on the control 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**](#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** + +### DataMemberChanged +{: .no_toc } + +> [!NOTE] +> Declared for VB6 compatibility; not currently implemented in twinBASIC. Companion to the data-source behaviour. + +Syntax: *object*.**DataMemberChanged** *DataMember* + +### InternalEnumerator +{: .no_toc } + +Returns the `IUnknown` enumerator backing `For Each` over the **UserControl**'s [**Controls**](#controls). Read-only. Exposed as the [Enumerator] member so that `For Each ctl In UserControl` walks the children directly. + +### Line +{: .no_toc } + +Draws a line, or a rectangle, on the control 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). + +### OLEDrag +{: .no_toc } + +Initiates an OLE drag operation from the control, raising the [**OLEStartDrag**](#olestartdrag) event so the application can populate the **DataObject**. + +Syntax: *object*.**OLEDrag** + +### PaintPicture +{: .no_toc } + +Draws a **StdPicture** onto the control, 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. + +### 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* ) + +### PopUpMenu +{: .no_toc } + +> [!NOTE] +> Declared for VB6 compatibility; not currently implemented on **UserControl** in twinBASIC. A **UserControl** has no menu structure of its own — invoke a host pop-up through the extender or the parent form's [**PopUpMenu**](../Form/#popupmenu). + +Syntax: *object*.**PopUpMenu** *Menu* [, *Flags* [, *X* [, *Y* [, *DefaultMenu* ] ] ] ] + +### Print +{: .no_toc } + +Writes text to the control's drawing surface using [**Font**](#font), starting at [**CurrentX**](#currentx) / [**CurrentY**](#currenty) and advancing them as it goes. Dispatched through the VB6 **Print** statement so multiple expressions can be separated by `;` (no spacing) or `,` (tab to the next print zone). **Spc(n)** inserts *n* spaces and **Tab(n)** moves to print column *n*. Output honours [**Font**](#font), [**ForeColor**](#forecolor), and [**FontTransparent**](#fonttransparent), and — when [**AutoRedraw**](#autoredraw) is **True** — is recorded into the persistent off-screen bitmap so it survives invalidations. + +Syntax: *object*.**Print** \[ *expressionlist* ] \[ **;** \| **,** ] + +A trailing `;` or `,` suppresses the newline so the next **Print** call continues on the same line; without a trailing separator, the pen advances to the start of the next line. + +### PropertyChanged +{: .no_toc } + +Notifies the host that one of the **UserControl**'s persistent properties has changed, marking the design surface (or property bag) dirty so that the host will call [**WriteProperties**](#writeproperties) the next time it saves. + +Syntax: *object*.**PropertyChanged** [ *PropertyName* ] + +*PropertyName* +: *optional* The name of the property that changed, as a **String**. When supplied, the framework also fires the COM **IPropertyNotifySink::OnChanged** event with the matching **DispId** so that data-bound containers can refresh themselves. Omit for a generic "something changed" notification. + +### PSet +{: .no_toc } + +Sets a single pixel on the control 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 control, raising [**Paint**](#paint) when [**AutoRedraw**](#autoredraw) is **False**. + +Syntax: *object*.**Refresh** + +### Scale +{: .no_toc } + +Sets the control'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 **UserControl** and gives input focus to its first focusable child (or to whichever control last held focus on this surface). + +Syntax: *object*.**SetFocus** + +### Size +{: .no_toc } + +Sets the **UserControl**'s extent in a single call, expressed in twips. The framework converts to HIMETRIC, calls `IOleObject::SetExtent` on the host, and updates the design surface when running in design mode. + +Syntax: *object*.**Size** *Width*, *Height* + +*Width*, *Height* +: *required* The new dimensions in twips. + +### TextHeight +{: .no_toc } + +Returns the height that the given string would occupy when drawn with the control's current [**Font**](#font), in [**ScaleMode**](#scalemode) units. Embedded line breaks are honoured. + +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 control's current [**Font**](#font), in [**ScaleMode**](#scalemode) units. Returns the longest line width when *Str* contains embedded line breaks. + +Syntax: *object*.**TextWidth**( *Str* ) + +*Str* +: *required* A **String** to measure. + +### ValidateControls +{: .no_toc } + +> [!NOTE] +> Declared for VB6 compatibility; not currently implemented in twinBASIC. In VB6 this fired the focused child's **Validate** event from code; on a **UserControl** the host normally drives validation through the form-level [**ValidateControls**](../Form/#validatecontrols). + +Syntax: *object*.**ValidateControls** + +## Events + +### AccessKeyPress +{: .no_toc } + +> [!NOTE] +> Declared for VB6 compatibility; only partially implemented in twinBASIC. The runtime currently raises this event when the host calls `IOleControl::OnMnemonic` with the **Escape**, **Return**, or **Execute** keys — typically because [**DefaultCancel**](#defaultcancel) (or a default-button equivalent) routed a default-action keystroke to the control. + +Syntax: *object*\_**AccessKeyPress**( *KeyAscii* **As Integer** ) + +### AmbientChanged +{: .no_toc } + +Raised when the host changes one of the ambient properties exposed through [**Ambient**](#ambient) — typically when its [**Font**](#font), colours, locale, or run/design mode flag shifts. The *PropertyName* argument names the ambient property that changed. + +Syntax: *object*\_**AmbientChanged**( *PropertyName* **As String** ) + +*PropertyName* +: A **String** identifying the ambient property — for example, `"BackColor"`, `"Font"`, `"LocaleID"`, `"UserMode"`. + +### AsyncReadComplete +{: .no_toc } + +> [!NOTE] +> Declared for VB6 compatibility; not currently raised in twinBASIC. Companion to [**AsyncRead**](#asyncread). + +Syntax: *object*\_**AsyncReadComplete**( *AsyncProp* **As AsyncProperty** ) + +### AsyncReadProgress +{: .no_toc } + +> [!NOTE] +> Declared for VB6 compatibility; not currently raised in twinBASIC. Companion to [**AsyncRead**](#asyncread). + +Syntax: *object*\_**AsyncReadProgress**( *AsyncProp* **As AsyncProperty** ) + +### Click +{: .no_toc } + +Raised when the user single-clicks the control's surface (i.e. not over any child control). + +Syntax: *object*\_**Click**( ) + +### DblClick +{: .no_toc } + +Raised when the user double-clicks the control's surface. + +Syntax: *object*\_**DblClick**( ) + +### DPIChange +{: .no_toc } + +Raised when the control moves to a monitor with a different DPI scale, *but only* when the application is per-monitor DPI aware (`PROCESS_PER_MONITOR_DPI_AWARE`). The event's *NewDPI* argument carries the new effective DPI; child controls re-scale themselves automatically. New in twinBASIC. + +Syntax: *object*\_**DPIChange**( *NewDPI* **As Long** ) + +### DragDrop +{: .no_toc } + +> [!NOTE] +> Declared for VB6 compatibility; not currently raised on a **UserControl**. Manual drag-and-drop is handled by the host's extender rather than the inner **UserControl**. + +Syntax: *object*\_**DragDrop**( *Source* **As Control**, *X* **As Single**, *Y* **As Single** ) + +### DragOver +{: .no_toc } + +> [!NOTE] +> Declared for VB6 compatibility; not currently raised on a **UserControl**. See [**DragDrop**](#dragdrop). + +Syntax: *object*\_**DragOver**( *Source* **As Control**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### EnterFocus +{: .no_toc } + +Raised when the input focus moves into the **UserControl** — either the **UserControl** itself or any of its descendants. Fires before any child's **GotFocus**. + +Syntax: *object*\_**EnterFocus**( ) + +### ExitFocus +{: .no_toc } + +Raised when the input focus leaves the **UserControl** — i.e. moves out to a control that is not a descendant. Fires after the leaving child's **LostFocus**. + +Syntax: *object*\_**ExitFocus**( ) + +### GetDataMember +{: .no_toc } + +> [!NOTE] +> Declared for VB6 compatibility; not currently raised in twinBASIC. Companion to [**DataMembers**](#datamembers). + +Syntax: *object*\_**GetDataMember**( *DataMember* **As String**, *Data* **As Object** ) + +### GotFocus +{: .no_toc } + +Raised when the **UserControl**'s own window receives the input focus and no enabled child is in a position to take it instead. + +Syntax: *object*\_**GotFocus**( ) + +### Hide +{: .no_toc } + +Raised when the host hides the container — typically as it switches from a run view to a design view, or as it makes a containing tab inactive. + +Syntax: *object*\_**Hide**( ) + +### HitTest +{: .no_toc } + +Raised for each `IViewObjectEx::QueryHitPoint` request from the host when the control is windowless. Setting *HitResult* to a non-zero **HitResult** value tells the host whether the given pixel is "hit" for mouse-routing purposes — useful for non-rectangular windowless controls. + +Syntax: *object*\_**HitTest**( *X* **As Single**, *Y* **As Single**, *HitResult* **As Integer** ) + +### Initialize +{: .no_toc } + +Raised once, before the underlying window is created and before any of the control's children exist. Useful for setting initial values on form-level fields. The control's children cannot be referenced from this event. **Default-designer event.** + +Syntax: *object*\_**Initialize**( ) + +### InitProperties +{: .no_toc } + +Raised once on the first ever activation of a brand-new **UserControl** instance — before a property bag exists for it. The classic place to assign initial values to persistent properties. Not raised on subsequent loads; on those, [**ReadProperties**](#readproperties) runs instead. + +Syntax: *object*\_**InitProperties**( ) + +### KeyDown +{: .no_toc } + +Raised when the user presses any key with focus on the **UserControl**. Fires on the focused child by default; with [**KeyPreview**](#keypreview) **True**, fires on the **UserControl** 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 child by default; with [**KeyPreview**](#keypreview) **True**, fires on the **UserControl** first. + +Syntax: *object*\_**KeyPress**( *KeyAscii* **As Integer** ) + +### KeyUp +{: .no_toc } + +Raised when the user releases a key. Fires on the focused child by default; with [**KeyPreview**](#keypreview) **True**, fires on the **UserControl** first. + +Syntax: *object*\_**KeyUp**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### LostFocus +{: .no_toc } + +Raised when the **UserControl**'s own window loses the input focus. + +Syntax: *object*\_**LostFocus**( ) + +### MouseDown +{: .no_toc } + +Raised when the user presses any mouse button over the control's surface. + +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's surface. + +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's surface. + +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** ) + +### Paint +{: .no_toc } + +Raised when an invalidated portion of the control needs to be redrawn. Suppressed when [**AutoRedraw**](#autoredraw) is **True** — the control's persistent off-screen buffer is blitted to the screen instead. + +Syntax: *object*\_**Paint**( ) + +### PreKeyDown +{: .no_toc } + +Raised for every key press anywhere on the **UserControl** or any of its descendants, *before* the focused child sees it — so handlers can swallow the keystroke. Requires [**PreKeyEvents**](#prekeyevents) **True**. Not raised when [**Windowless**](#windowless) is **True**. New in twinBASIC. + +Syntax: *object*\_**PreKeyDown**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### PreKeyUp +{: .no_toc } + +Raised for every key release anywhere on the **UserControl** or any of its descendants, *before* the focused child sees it. Requires [**PreKeyEvents**](#prekeyevents) **True**. Not raised when [**Windowless**](#windowless) is **True**. New in twinBASIC. + +Syntax: *object*\_**PreKeyUp**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### ReadProperties +{: .no_toc } + +Raised when the host hands the control a property bag containing previously saved state — i.e. on every load except the very first. The handler reads the values it cares about from *PropBag* and applies them to its fields. *PropBag*'s **ReadProperty** method takes a key, a default value, and a type hint. + +Syntax: *object*\_**ReadProperties**( *PropBag* **As PropertyBag** ) + +*PropBag* +: The host-supplied [**PropertyBag**](../../VBRUN/PropertyBag/) carrying the persisted values. + +### Resize +{: .no_toc } + +Raised when the **UserControl** is resized — by the host during initial layout, by user code assigning [**Width**](#width) or [**Height**](#height), or by the host responding to a designer drag. + +Syntax: *object*\_**Resize**( ) + +### Show +{: .no_toc } + +Raised when the host makes the container visible — typically as it switches from a design view to a run view, or as it makes a containing tab active. + +Syntax: *object*\_**Show**( ) + +### Terminate +{: .no_toc } + +Raised after the **UserControl**'s window has been destroyed and the class instance is about to be released. Child controls are no longer accessible at this point. + +Syntax: *object*\_**Terminate**( ) + +### VerbInvoked +{: .no_toc } + +Raised when the host invokes one of the verbs declared in [**Verbs**](#verbs) — typically because the user picked it from the host's right-click context menu. + +Syntax: *object*\_**VerbInvoked**( *Verb* **As String** ) + +*Verb* +: The name of the invoked verb, exactly as it was registered in [**Verbs**](#verbs). + +### WriteProperties +{: .no_toc } + +Raised when the host asks the control to persist its current state — design-time saves and host-driven serialisation. The handler writes each persistent value to *PropBag* through **WriteProperty**, which takes a key, the value, and (optionally) the same default the [**ReadProperties**](#readproperties) handler used so that round-trip defaults are not written. Only raised when at least one call to [**PropertyChanged**](#propertychanged) has happened since the last save. + +Syntax: *object*\_**WriteProperties**( *PropBag* **As PropertyBag** ) + +*PropBag* +: The host-supplied [**PropertyBag**](../../VBRUN/PropertyBag/) to write the persisted values into. diff --git a/docs/Reference/VB/VScrollBar/index.md b/docs/Reference/VB/VScrollBar/index.md new file mode 100644 index 0000000..292bc20 --- /dev/null +++ b/docs/Reference/VB/VScrollBar/index.md @@ -0,0 +1,392 @@ +--- +title: VScrollBar +parent: VB Package +permalink: /tB/Packages/VB/VScrollBar/ +has_toc: false +--- + +# VScrollBar class +{: .no_toc } + +A **VScrollBar** is a Win32 native vertical scroll bar exposed as a stand-alone control. Unlike the scroll bars that automatically appear inside a [**ListBox**](../ListBox), [**ComboBox**](../ComboBox), or [**TextBox**](../TextBox), a **VScrollBar** is independent of any other control — its [**Value**](#value) is whatever your code reads or writes. The typical use is to drive a numeric setting (a scroll offset, a brightness or opacity level, a colour channel, the vertical position of a custom-drawn surface) by binding the **VScrollBar**'s [**Change**](#change) and [**Scroll**](#scroll) events to whatever the value represents. + +[**HScrollBar**](../HScrollBar) is the horizontal counterpart; the two classes are identical apart from orientation. + +The default property is [**Value**](#value) and the default event is [**Change**](#change). + +```tb +Private Sub Form_Load() + vsbLevel.Min = 0 + vsbLevel.Max = 100 + vsbLevel.SmallChange = 1 + vsbLevel.LargeChange = 10 + vsbLevel.Value = 50 +End Sub + +Private Sub vsbLevel_Change() + lblLevel.Caption = "Level: " & vsbLevel.Value & "%" +End Sub + +Private Sub vsbLevel_Scroll() + lblLevel.Caption = "Level: " & vsbLevel.Value & "%" ' live update during drag +End Sub +``` + +* TOC +{:toc} + +## Range and value + +[**Min**](#min) and [**Max**](#max) define the closed range of integer values the scroll bar can represent, and [**Value**](#value) is the position within that range. Defaults are `0`, `32767`, and `0`. Assigning a [**Value**](#value) outside the current `[Min, Max]` interval raises run-time error 380 (*Invalid property value*); assigning the current value is a no-op (no [**Change**](#change) is raised). + +The two endpoints may be supplied in either order. When **Min** is greater than **Max** the scroll bar runs *inverted* — moving the thumb downward decreases [**Value**](#value), and **Max** is the lower bound of the legal range. This is convenient for, for example, a "high-at-top" volume or brightness slider: + +```tb +vsbVolume.Min = 100 ' topmost == loudest +vsbVolume.Max = 0 ' bottommost == silent +vsbVolume.Value = 75 +``` + +Changing **Min** or **Max** at run time clips the current [**Value**](#value) into the new range silently — no [**Change**](#change) event is raised for the implicit clip. + +## Increment sizes + +The scroll bar produces value changes through four kinds of user input: + +| Input | Increment per step | Event raised | +|-------------------------------------|------------------------------|------------------| +| Click an end-arrow | [**SmallChange**](#smallchange) | [**Change**](#change) | +| Click the track above or below the thumb | [**LargeChange**](#largechange) | [**Change**](#change) | +| Drag the thumb | continuous | [**Scroll**](#scroll) during drag, [**Change**](#change) on release | +| Press **Home** / **End** | jumps to **Min** / **Max** | [**Change**](#change) | + +Both [**SmallChange**](#smallchange) and [**LargeChange**](#largechange) default to `1`. [**LargeChange**](#largechange) also drives the visible height of the thumb relative to the track, so larger values produce a chunkier thumb. + +## Change versus Scroll + +The split between the two events lets the application choose how often it reacts to user input. [**Scroll**](#scroll) fires repeatedly while the user is dragging the thumb, so a handler can update a live preview as the thumb moves. [**Change**](#change) fires once each time the value settles — after the user releases the thumb, after a click on an arrow or the track, or whenever code assigns a different [**Value**](#value). Many applications wire both events to the same handler so that the bound display updates both during dragging and after. + +## Properties + +### Anchors +{: .no_toc } + +The set of edges of the parent that the scroll bar's corresponding edges follow when the parent resizes. Read-only — assign individual `.Left`, `.Top`, `.Right`, `.Bottom` flags through the returned **Anchors** object. + +### CausesValidation +{: .no_toc } + +Determines whether the previously focused control's [**Validate**](#validate) event runs before this control receives the focus. **Boolean**, default **True**. + +### Container +{: .no_toc } + +The control that hosts this scroll bar — typically the form, a [**Frame**](../Frame/), or a **UserControl**. Read with **Get**, change with **Set**. + +### ControlType +{: .no_toc } + +A read-only [**ControlTypeConstants**](../../VBRUN/Constants/ControlTypeConstants) value identifying this control as a vertical scroll bar. Always **vbVScrollBar**. + +### Dock +{: .no_toc } + +Where the scroll bar is docked within its container. A member of [**DockModeConstants**](../../VBRUN/Constants/DockModeConstants): **vbDockNone** (default), **vbDockLeft**, **vbDockTop**, **vbDockRight**, **vbDockBottom**, or **vbDockFill**. Docked scroll bars ignore [**Anchors**](#anchors). + +### DragIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor while the control is being drag-and-dropped (see [**Drag**](#drag) and [**DragMode**](#dragmode)). + +### DragMode +{: .no_toc } + +Whether the control should drag itself when the user holds the mouse over it. A member of [**DragModeConstants**](../../VBRUN/Constants/DragModeConstants): **vbManual** (0, default — call [**Drag**](#drag) from code) or **vbAutomatic** (1). + +### Enabled +{: .no_toc } + +Determines whether the scroll bar accepts user input. A disabled scroll bar is greyed out and does not respond to mouse or keyboard interaction. **Boolean**, default **True**. + +### Height +{: .no_toc } + +The scroll bar's height in twips (or in the container's **ScaleMode** units). **Double**. For a vertical scroll bar this is the long dimension — i.e., the length of the track. + +### HelpContextID +{: .no_toc } + +A **Long** identifying a topic in the application's help file, retrieved when the user presses **F1** while the control has focus. + +### hWnd +{: .no_toc } + +The Win32 window handle for the underlying scroll bar, as a **LongPtr**. Read-only. Useful for passing to API functions. + +### Index +{: .no_toc } + +When the scroll bar is part of a control array, the **Long** zero-based index of this instance within the array. Reading **Index** on a non-array instance raises run-time error 343 (*Object not an array*). Read-only at run time. + +### LargeChange +{: .no_toc } + +The amount [**Value**](#value) is adjusted when the user clicks the track above or below the thumb (or presses **Page Up** / **Page Down** while the scroll bar has focus). **Long**, default `1`. Also influences the visible height of the thumb: bigger values produce a taller thumb relative to the track. + +### Left +{: .no_toc } + +The horizontal distance from the left edge of the container to the left edge of the scroll bar. **Double**. + +### Max +{: .no_toc } + +The upper end of the scroll bar's value range. **Long**, default `32767`. May be set lower than [**Min**](#min) to invert the direction of travel — see [Range and value](#range-and-value). + +Syntax: *object*.**Max** [ = *value* ] + +Changing **Max** clips the current [**Value**](#value) into the new range silently if it now falls outside. + +### Min +{: .no_toc } + +The lower end of the scroll bar's value range. **Long**, default `0`. May be set higher than [**Max**](#max) to invert the direction of travel. + +Syntax: *object*.**Min** [ = *value* ] + +Changing **Min** clips the current [**Value**](#value) into the new range silently if it now falls outside. + +### MouseIcon +{: .no_toc } + +A **StdPicture** used as the mouse cursor when [**MousePointer**](#mousepointer) is **vbCustom** and the pointer is over the control. + +### MousePointer +{: .no_toc } + +The mouse cursor shown when the pointer is over the control. A member of [**MousePointerConstants**](../../VBRUN/Constants/MousePointerConstants). + +### Name +{: .no_toc } + +The unique design-time name of the control on its parent form. Read-only at run time. + +### Opacity +{: .no_toc } + +The control's opacity as a percentage (0–100, default 100). Values outside the range are clamped on **Initialize**. Requires Windows 8 or later for child controls. + +### Parent +{: .no_toc } + +A reference to the [**Form**](../Form/) (or **UserControl**) that ultimately contains this scroll bar. Read-only. + +### RightToLeft +{: .no_toc } + +> [!NOTE] +> Reserved for compatibility with VB6; not currently implemented in twinBASIC. To run the scroll bar in reverse, swap [**Min**](#min) and [**Max**](#max). + +### SmallChange +{: .no_toc } + +The amount [**Value**](#value) is adjusted when the user clicks one of the end-arrows (or presses an arrow key while the scroll bar has focus). **Long**, default `1`. + +### TabIndex +{: .no_toc } + +The position of the control in the form's TAB-key navigation order. **Long**. + +### TabStop +{: .no_toc } + +Whether the user can reach the control by pressing the **TAB** key. **Boolean**, default **True**. A disabled control is skipped regardless of this setting. + +### Tag +{: .no_toc } + +A free-form **String** the application can use to associate custom data with the control. Ignored by the framework. + +### Top +{: .no_toc } + +The vertical distance from the top of the container to the top of the scroll bar. **Double**. + +### TransparencyKey +{: .no_toc } + +An **OLE_COLOR** that, when set, becomes fully transparent in the rendered control. Default `-1` disables the effect. Requires Windows 8 or later for child controls. + +### Value +{: .no_toc } + +The scroll bar's current position within `[Min, Max]`. **Long**, default `0`. **Default property.** + +Syntax: *object*.**Value** [ = *value* ] + +*value* +: A **Long** in the closed interval `[Min, Max]` (or `[Max, Min]` for an inverted scroll bar). Values outside that interval raise run-time error 380 (*Invalid property value*). + +Assigning a value that differs from the current one moves the thumb and raises a single [**Change**](#change) event. Assigning the current value is a silent no-op. + +### Visible +{: .no_toc } + +Whether the scroll bar is shown. **Boolean**, default **True**. + +### VisualStyles +{: .no_toc } + +Whether the OS theme engine should be used when drawing the scroll bar. **Boolean**, default **True**. + +### WhatsThisHelpID +{: .no_toc } + +A **Long** identifying a "What's This?" help-pop-up topic in the application's help file. See [**ShowWhatsThis**](#showwhatsthis). + +### Width +{: .no_toc } + +The scroll bar's width in twips (or in the container's **ScaleMode** units). **Double**. For a vertical scroll bar this is the small dimension — typically the OS standard scroll-bar thickness; values larger than that simply enlarge the surrounding hit area. + +## Methods + +### Drag +{: .no_toc } + +Begins, completes, or cancels a manual drag-and-drop operation. Typically called from code when [**DragMode**](#dragmode) is **vbManual**. + +Syntax: *object*.**Drag** [ *Action* ] + +*Action* +: *optional* A member of [**DragConstants**](../../VBRUN/Constants/DragConstants): **vbCancel** (0), **vbBeginDrag** (1, default), or **vbEndDrag** (2). + +### Move +{: .no_toc } + +Repositions and optionally resizes the scroll bar in a single call. + +Syntax: *object*.**Move** *Left* [, *Top* [, *Width* [, *Height* ] ] ] + +*Left* +: *required* A **Single** giving the new horizontal position. + +*Top*, *Width*, *Height* +: *optional* New values for the corresponding properties. Omitted values are left unchanged. + +### Refresh +{: .no_toc } + +Forces an immediate repaint of the scroll bar. + +Syntax: *object*.**Refresh** + +### SetFocus +{: .no_toc } + +Moves the input focus to the scroll bar. The control must be both [**Visible**](#visible) and [**Enabled**](#enabled), or run-time error 5 (*Invalid procedure call or argument*) is raised. + +Syntax: *object*.**SetFocus** + +### ShowWhatsThis +{: .no_toc } + +Displays the topic identified by [**WhatsThisHelpID**](#whatsthishelpid) as a "What's This?" pop-up. + +Syntax: *object*.**ShowWhatsThis** + +### SyncScrollBar +{: .no_toc } + +Re-applies the current [**Min**](#min), [**Max**](#max), [**LargeChange**](#largechange), and [**Value**](#value) to the underlying Win32 scroll bar. Property assignments already do this implicitly — call **SyncScrollBar** only when external code (typically a Win32 API call) has reached around the control and changed its native state. + +Syntax: *object*.**SyncScrollBar** + +### ZOrder +{: .no_toc } + +Brings the control to the front or back of its sibling stack. + +Syntax: *object*.**ZOrder** [ *Position* ] + +*Position* +: *optional* A member of [**ZOrderConstants**](../../VBRUN/Constants/ZOrderConstants): **vbBringToFront** (0, default) or **vbSendToBack** (1). + +## Events + +### Change +{: .no_toc } + +Raised after [**Value**](#value) settles on a new value — when the user releases the thumb after a drag, when the user clicks an arrow or the track, when the user presses **Home**, **End**, or an arrow key with focus on the scroll bar, or when code assigns a different [**Value**](#value). Not raised for the continuous updates that happen during a drag — see [**Scroll**](#scroll) for that. **Default event.** + +Syntax: *object*\_**Change**( ) + +### DragDrop +{: .no_toc } + +Raised on the destination control when a manual drag operation ends over it. + +Syntax: *object*\_**DragDrop**( *Source* **As Control**, *X* **As Single**, *Y* **As Single** ) + +### DragOver +{: .no_toc } + +Raised on the control under the cursor while a manual drag operation is in progress. + +Syntax: *object*\_**DragOver**( *Source* **As Control**, *X* **As Single**, *Y* **As Single**, *State* **As Integer** ) + +### GotFocus +{: .no_toc } + +Raised when the scroll bar receives the input focus. + +Syntax: *object*\_**GotFocus**( ) + +### Initialize +{: .no_toc } + +Raised once, after the underlying window has been created and the scroll bar is wired up to its Win32 range, but before the scroll bar is first painted. Useful for last-minute setup that needs the underlying handle. + +Syntax: *object*\_**Initialize**( ) + +### KeyDown +{: .no_toc } + +Raised when the user presses any key while the control has focus. Note that the scroll bar already handles the arrow keys, **Page Up** / **Page Down**, and **Home** / **End** internally — but **KeyDown** still fires for them in addition to the resulting [**Change**](#change). + +Syntax: *object*\_**KeyDown**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### KeyPress +{: .no_toc } + +Raised when the user types a character that produces an ANSI keystroke. + +Syntax: *object*\_**KeyPress**( *KeyAscii* **As Integer** ) + +### KeyUp +{: .no_toc } + +Raised when the user releases a key while the control has focus. + +Syntax: *object*\_**KeyUp**( *KeyCode* **As Integer**, *Shift* **As Integer** ) + +### LostFocus +{: .no_toc } + +Raised when the scroll bar loses the input focus. + +Syntax: *object*\_**LostFocus**( ) + +### Scroll +{: .no_toc } + +Raised continuously while the user is dragging the thumb, once for each tick that produces a different [**Value**](#value). After the user releases the thumb, a single [**Change**](#change) event fires with the final value. Use **Scroll** when you want a live preview while the thumb is moving; use [**Change**](#change) when you want to react only to the final value. + +Syntax: *object*\_**Scroll**( ) + +### Validate +{: .no_toc } + +Raised when the focus is moving to another control whose [**CausesValidation**](#causesvalidation) is **True**. Setting *Cancel* to **True** keeps the focus on this control. + +Syntax: *object*\_**Validate**( *Cancel* **As Boolean** ) diff --git a/docs/Reference/VB/todo.md b/docs/Reference/VB/todo.md index f29dec5..0abbb29 100644 --- a/docs/Reference/VB/todo.md +++ b/docs/Reference/VB/todo.md @@ -4,9 +4,6 @@ nav_exclude: true redirect_from: - /tB/Packages/VB/DriveListBox - /tB/Packages/VB/Printer - - /tB/Packages/VB/Report - - /tB/Packages/VB/Shape - - /tB/Packages/VB/VScrollBar --- > [!WARNING]