# The MIT License (MIT)
#
# Copyright (C) 2026 Scott Duensing
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

.topic ctrl.textbox
.title TextBox
.toc 1 TextBox
.index TextBox
.index Text
.index DataSource
.index DataField

.h1 TextBox

VB Equivalent: TextBox -- DVX Widget: textbox (single-line text input, max 256 chars)

A single-line text input field. Supports data binding via DataSource and DataField properties.

.h2 Type-Specific Properties

.table
  Property     Type     Description
  ----------   ------   -------------------------------------------
  Text         String   The text content of the input field.
  DataSource   String   Name of a Data control for data binding.
  DataField    String   Column name for data binding.
.endtable

Default Event: Change

.h2 Example

.code
Begin TextBox Text1
    Text = "Enter text here"
End

Sub Text1_Change ()
    Label1.Caption = "You typed: " & Text1.Text
End Sub
.endcode

.link ctrl.common.props Common Properties, Events, and Methods
.link ctrl.databinding Data Binding
.topic ctrl.textarea
.title TextArea
.toc 1 TextArea
.index TextArea
.index FindNext
.index ReplaceAll
.index GoToLine
.index CursorLine
.index LineNumbers
.index AutoIndent

.h1 TextArea

VB Equivalent: TextArea (DVX extension) -- DVX Widget: textarea (multi-line text input, default max 65536 chars)

A multi-line text editing area. This is a DVX extension with no direct VB3 equivalent (VB uses a TextBox with MultiLine=True). Supports line numbers, auto-indent, find/replace, and tab configuration.

.h2 Type-Specific Properties

.table
  Property     Type      R/W   Description
  ----------   -------   ---   -------------------------------------------
  Text         String    R/W   The full text content.
  CursorLine   Integer   R     Current cursor line number (0-based).
.endtable

.h2 Type-Specific Methods

.table
  Method                                          Description
  ------                                          -----------
  AppendText text$                                Append text to the end of the buffer and invalidate the widget.
  FindNext needle$, caseSensitive, forward        Search for text. Returns True if found.
  GetWordAtCursor()                               Returns the word under the cursor.
  GoToLine line%                                  Scroll to and position cursor at the given line.
  ReplaceAll needle$, replacement$, caseSensitive Replace all occurrences. Returns count of replacements.
  SetAutoIndent enabled                           Enable or disable automatic indentation.
  SetCaptureTabs enabled                          When True, Tab key inserts a tab/spaces instead of moving focus.
  SetShowLineNumbers show                         Show or hide the line number gutter.
  SetSyntaxMode mode$                             Activate built-in syntax highlighting. Modes: "dhs" (help source), "bas" (BASIC). Pass "" to disable.
  SetTabWidth width%                              Set the tab stop width in characters.
  SetUseTabChar useChar                           When True, Tab inserts a tab character; when False, inserts spaces.
.endtable

Default Event: Change

.h2 Example

.code
TextArea1.SetShowLineNumbers True
TextArea1.SetAutoIndent True
TextArea1.SetTabWidth 4
TextArea1.SetCaptureTabs True

' Search for text
If TextArea1.FindNext("TODO", False, True) Then
    Print "Found at line"; TextArea1.CursorLine
End If

' Replace all occurrences
Dim count As Integer
count = TextArea1.ReplaceAll("old", "new", False)
Print "Replaced"; count; "occurrences"
.endcode

.link ctrl.common.props Common Properties, Events, and Methods