TextBox class

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 or UserControl at design time. The default property is Text and the default-designer event is Change.

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

Single-line and multi-line modes

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 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 decides whether horizontal, vertical, both, or no scroll bars are shown.

Changing MultiLine, ScrollBars, or HideSelection at run time recreates the underlying window --- the contents, current MaxLength, PasswordChar, and Locked state are preserved across the recreate.

Password masking

When 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 still returns the real characters. Setting PasswordChar back to an empty string restores normal display.

Password masking is a single-line edit feature --- assigning PasswordChar while MultiLine is True has no visible effect on the displayed text.

txtPassword.PasswordChar = "•"      ' display a bullet for each character

Cue banner

TextHint sets a placeholder string that appears, in a dimmed colour, while 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 to True to keep it visible even when the empty control has focus (until the user starts typing).

Selection

SelStart, SelLength, and 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. Assigning SelStart or SelLength scrolls the caret into view; assigning 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 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 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 handler for more elaborate validation.

OLE drag-and-drop

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 controls drop-target behaviour: vbOLEDropNone ignores drops, vbOLEDropManual raises OLEDragOver and 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 and DataField connects the control's Text to a field of a 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 is written back when the row is saved. Modifying Text --- either by user input or by code --- sets DataChanged and marks the recordset row as dirty.

Properties

Alignment

Horizontal alignment of the text within the control.

Syntax: object.Alignment [ = value ]

value

A member of AlignmentConstants: vbLeftJustify (0, default), vbRightJustify (1), or vbCenter (2). Centred and right-aligned text require 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

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

Determines how the control's border is drawn by the OS. A member of AppearanceConstants: vbAppearFlat or vbAppear3d (default). Only meaningful when BorderStyle is vbFixedSingleBorder --- chooses between a sunken 3-D edge and a thin flat border.

BackColor

The background colour of the edit area, as an OLE_COLOR. Defaults to the system window-background colour.

BorderStyle

Whether the text box is drawn with a border. A member of ControlBorderStyleConstants: vbNoBorder (0) or vbFixedSingleBorder (1, default). The exact appearance of the border depends on Appearance.

CausesValidation

Determines whether the previously focused control's Validate event runs before this control receives the focus. Boolean, default True.

Container

The control that hosts this text box --- typically the form, a Frame, or a PictureBox. Read with Get, change with Set. Setting Container at run time re-parents the text box.

ControlType

A read-only ControlTypeConstants value identifying this control as a text box. Always vbTextBox.

DataChanged

A run-time-only Boolean that becomes True when Text has been modified since the last save, and is cleared once the change has been written back to the recordset.

DataField

The name of the field, in the recordset of the bound DataSource, whose value is mirrored by Text. String.

DataFormat

INFO

Reserved for compatibility with VB6; not currently implemented in twinBASIC.

A StdDataFormat that converts between the raw recordset value and the displayed text.

DataMember

INFO

Reserved for compatibility with VB6; not currently implemented in twinBASIC.

When the DataSource exposes more than one recordset, the name of the member to bind to.

DataSource

A reference to a Data control (or other DataSource provider) whose recordset supplies the value for DataField. Set with Set.

Dock

Where the text box is docked within its container. A member of DockModeConstants: vbDockNone (default), vbDockLeft, vbDockTop, vbDockRight, vbDockBottom, or vbDockFill. Docked text boxes ignore Anchors.

DragIcon

A StdPicture used as the mouse cursor while the control is being drag-and-dropped (see Drag and DragMode).

DragMode

Whether the control should drag itself when the user holds the mouse over it. A member of DragModeConstants: vbManual (0, default --- call Drag from code) or vbAutomatic (1).

Enabled

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

The StdFont used to render the text. The convenience properties FontName, FontSize, FontBold, FontItalic, FontStrikethru, and FontUnderline read or write the corresponding members of this object.

FontBold

Shortcut for Font.Bold. Boolean.

FontItalic

Shortcut for Font.Italic. Boolean.

FontName

Shortcut for Font.Name. String.

FontSize

Shortcut for Font.Size --- the point size. Single.

FontStrikethru

Shortcut for Font.Strikethrough. Boolean.

FontUnderline

Shortcut for Font.Underline. Boolean.

ForeColor

The text colour, as an OLE_COLOR. Defaults to the system window-text colour.

Height

The control's height, in twips by default (or in the container's ScaleMode units). Single.

HelpContextID

A Long identifying a topic in the application's help file, retrieved when the user presses F1 while the control has focus.

HideSelection

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

The Win32 window handle for the underlying edit control, as a LongPtr. Read-only. Useful for passing to API functions.

Index

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

The horizontal distance from the left edge of the container to the left edge of the control. Single.

LinkItem

INFO

Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC.

LinkMode

INFO

Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC.

A member of LinkModeConstants.

LinkTimeout

INFO

Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC.

LinkTopic

INFO

Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC.

Locked

When True, the user can scroll, select, and copy text but cannot modify it. Boolean, default False. Distinct from 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

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

A StdPicture used as the mouse cursor when MousePointer is vbCustom and the pointer is over the control.

MousePointer

The mouse cursor shown when the pointer is over the control. A member of MousePointerConstants.

MultiLine

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

The unique design-time name of the control on its parent form. Read-only at run time.

NumbersOnly

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 handler for additional validation.

OLEDragMode

Whether the control's selected text can act as an automatic OLE drag source. A member of OLEDragConstants: vbOLEDragManual (0, default --- call OLEDrag from code) or vbOLEDragAutomatic (1).

OLEDropMode

How the control responds to OLE drops. A member of OLEDropConstants: vbOLEDropNone, vbOLEDropManual, or vbOLEDropAutomatic (which inserts the dropped text at the caret without raising OLEDragDrop).

Opacity

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

A reference to the Form (or UserControl) that ultimately contains this control. Read-only. Distinct from Container, which returns the immediate parent.

PasswordChar

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 still returns the real characters. Effective in single-line mode only.

RightToLeft

INFO

Reserved for compatibility with VB6; not currently implemented in twinBASIC.

ScrollBars

Which scroll bars the multi-line text box displays. A member of ScrollBarConstants: vbSBNone (0, default), vbHorizontal (1), vbVertical (2), or vbBoth (3). Ignored when 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

The number of characters currently selected. Long. Setting it extends or shrinks the selection from SelStart and scrolls the caret into view.

SelStart

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

The text currently selected. Assigning a string replaces the selection with that string and positions the caret immediately after the inserted text. String.

TabFocusAutoSelect

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

The position of the control in the form's TAB-key navigation order. Long.

TabStop

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

A free-form String the application can use to associate custom data with the control. Ignored by the framework.

Text

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 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

A placeholder String displayed in a dimmed colour when Text is empty --- the Win32 cue banner. Default empty (no cue). The hint disappears as soon as the user starts typing.

TextHintAlways

When True, 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

A multi-line String displayed as a tooltip when the user hovers over the control.

Top

The vertical distance from the top of the container to the top of the control. Single.

TransparencyKey

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

Whether the control is shown. Boolean, default True.

VisualStyles

Whether the OS theme engine should be used when drawing the control. Boolean, default True.

WhatsThisHelpID

A Long identifying a "What's This?" help-pop-up topic in the application's help file. See ShowWhatsThis.

WheelScrollEvent

When True (default), mouse-wheel notifications over a multi-line text box raise the Scroll event; when False, the wheel still scrolls the contents but Scroll is suppressed. Boolean. VB6 never raised Scroll for wheel events; set this to False to match that behaviour exactly.

Width

The control's width. Single.

Methods

Drag

Begins, completes, or cancels a manual drag-and-drop operation. Typically called from a MouseDown handler when DragMode is vbManual.

Syntax: object.Drag [ Action ]

Action

optional A member of DragConstants: vbCancel (0), vbBeginDrag (1, default), or vbEndDrag (2).

LinkExecute

INFO

Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC.

LinkPoke

INFO

Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC.

LinkRequest

INFO

Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC.

LinkSend

INFO

Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC.

Move

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

Initiates an OLE drag operation from the control, raising the OLEStartDrag event so the application can populate the DataObject.

Syntax: object.OLEDrag

Refresh

Forces an immediate repaint of the control.

Syntax: object.Refresh

SetFocus

Moves the input focus to the control. The control must be both Visible and Enabled, or run-time error 5 (Invalid procedure call or argument) is raised.

Syntax: object.SetFocus

ShowWhatsThis

Displays the topic identified by WhatsThisHelpID as a "What's This?" pop-up.

Syntax: object.ShowWhatsThis

ZOrder

Brings the control to the front or back of its sibling stack.

Syntax: object.ZOrder [ Position ]

Position

optional A member of ZOrderConstants: vbBringToFront (0, default) or vbSendToBack (1).

Events

Change

Raised whenever Text changes --- either through user input or by code assigning a new value. Not raised during Initialize; the very first text load from the serialized form does not produce a Change event. Default-designer event.

Syntax: object_Change( )

Click

Raised when the user clicks the control with any mouse button. Issued from the 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

Raised when the user double-clicks the control. Suppresses the synthetic Click that would otherwise fire from the second MouseUp.

Syntax: object_DblClick( )

DragDrop

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

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

Raised when the control receives the input focus.

Syntax: object_GotFocus( )

Initialize

Raised once, after the underlying window has been created and Text, Locked, MaxLength, TextHint, and PasswordChar have been applied from the serialized data. Change does not fire for this initial text load.

Syntax: object_Initialize( )

KeyDown

Raised when the user presses any key while the control has focus.

Syntax: object_KeyDown( KeyCode As Integer, Shift As Integer )

KeyPress

Raised when the user types a character that produces an ANSI keystroke.

Syntax: object_KeyPress( KeyAscii As Integer )

KeyUp

Raised when the user releases a key while the control has focus.

Syntax: object_KeyUp( KeyCode As Integer, Shift As Integer )

LinkClose

INFO

Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC.

LinkError

INFO

Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC.

LinkNotify

INFO

Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC.

LinkOpen

INFO

Reserved for compatibility with VB6 DDE; not currently implemented in twinBASIC.

LostFocus

Raised when the control loses the input focus.

Syntax: object_LostFocus( )

MouseDown

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

Raised when the cursor moves over the control. While 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

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

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

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

Raised on the destination control when the user drops data on it (when 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

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

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

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

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 is vbOLEDragAutomatic and the user begins a drag from a non-empty selection.

Syntax: object_OLEStartDrag( Data As DataObject, AllowedEffects As Long )

Scroll

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 to False. New in twinBASIC --- there is no equivalent VB6 event.

Syntax: object_Scroll( )

Validate

Raised when the focus is moving to another control whose CausesValidation is True. Setting Cancel to True keeps the focus on this control.

Syntax: object_Validate( Cancel As Boolean )