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

.section Widgets
.topic widget.textinput
.title TextInput / TextArea
.toc 0 Input Widgets
.toc 0 TextInput / TextArea
.index TextInput
.index TextArea
.index wgtTextInput
.index wgtTextArea
.index wgtPasswordInput
.index wgtMaskedInput

.h2 TextInput / TextArea

Single-line text input, password input, masked input, and multi-line text area with optional syntax colorization, line numbers, find/replace, and gutter decorators.

Header: widgets/textInpt.h

.h3 Creation

.table
  Macro                            Description
  -----                            -----------
  wgtTextInput(parent, maxLen)     Create a single-line text input. maxLen is the maximum number of characters.
  wgtPasswordInput(parent, maxLen) Create a password input (characters displayed as bullets).
  wgtMaskedInput(parent, mask)     Create a masked input field. The mask string defines the input format.
  wgtTextArea(parent, maxLen)      Create a multi-line text area.
.endtable

.h3 API Functions (TextArea-specific)

.index wgtTextAreaSetColorize
.index wgtTextAreaGoToLine
.index wgtTextAreaSetAutoIndent
.index wgtTextAreaSetShowLineNumbers
.index wgtTextAreaFindNext
.index wgtTextAreaReplaceAll

.table
  Function                                                    Description
  --------                                                    -----------
  void wgtTextAreaAppendText(w, text)                         Append text to the end of the buffer and invalidate the widget.
  void wgtTextAreaSetColorize(w, fn, ctx)                     Set a syntax colorization callback. The callback receives each line and fills a color index array.
  void wgtTextAreaGoToLine(w, line)                           Scroll to and place the cursor on the given line number.
  void wgtTextAreaSetAutoIndent(w, enable)                    Enable or disable automatic indentation on newline.
  void wgtTextAreaSetShowLineNumbers(w, show)                 Show or hide line numbers in the gutter.
  void wgtTextAreaSetCaptureTabs(w, capture)                  When true, Tab key inserts a tab/spaces instead of moving focus.
  void wgtTextAreaSetTabWidth(w, width)                       Set the tab stop width in characters.
  void wgtTextAreaSetUseTabChar(w, useChar)                   When true, insert literal tab characters; when false, insert spaces.
  bool wgtTextAreaFindNext(w, needle, caseSens, fwd)          Search for the next occurrence. Returns true if found.
  int32_t wgtTextAreaReplaceAll(w, needle, repl, caseSens)    Replace all occurrences. Returns the number of replacements made.
  void wgtTextAreaSetLineDecorator(w, fn, ctx)                Set a gutter line decorator callback. Returns a color and receives the line number.
  int32_t wgtTextAreaGetCursorLine(w)                         Get the current cursor line number.
  void wgtTextAreaSetGutterClickCallback(w, fn)               Set a callback for gutter clicks (e.g. for breakpoint toggling).
  int32_t wgtTextAreaGetWordAtCursor(w, buf, bufSize)         Copy the word under the cursor into buf. Returns its length.
  void wgtTextAreaSetSyntaxColors(w, colors, count)           Set the color palette used by the colorizer.
.endtable

.h3 API Struct (wgtRegisterApi "textinput")

The combined "textinput" API exposes all four constructors plus the TextArea functions. The designer uses per-type APIs registered under the names "textbox" (single-line) and "textarea" (multi-line), each exposing only a create slot.

.h3 Properties (BASIC Interface)

TextBox has no widget-specific properties. Text is managed via the generic "Text" property. TextArea exposes:

.table
  Property     Type       Access       Description
  --------     ----       ------       -----------
  CursorLine   Integer    Read-only    Current cursor line number (0-based).
.endtable

.h3 Methods (BASIC Interface, TextArea)

.table
  Method                                            Description
  ------                                            -----------
  FindNext needle$, caseSensitive, forward          Search for the next occurrence. Returns True if found.
  GetWordAtCursor()                                 Returns the word under the cursor.
  GoToLine line%                                    Scroll to and position the cursor on a line.
  ReplaceAll needle$, replacement$, caseSensitive   Replace all occurrences. Returns the count.
  SetAutoIndent enabled                             Enable or disable automatic indentation on newline.
  SetCaptureTabs enabled                            When True, Tab inserts whitespace instead of moving focus.
  SetShowLineNumbers show                           Show or hide line numbers in the gutter.
  SetSyntaxMode mode$                               Activate built-in syntax highlighting (e.g. "dhs", "bas"; "" to disable).
  SetTabWidth width%                                Set the tab stop width in characters.
  SetUseTabChar useChar                             When True, Tab inserts a literal tab; when False, spaces.
.endtable

.h3 Events

.table
  Callback     Description
  --------     -----------
  onChange     Fires when the text content changes.
  onKeyPress   Fires on each key press (ASCII value).
  onValidate   Called before committing a change. Return false to cancel.
.endtable

.h3 Default Event

"Change" for both TextBox (basName: TextBox) and TextArea (basName: TextArea).
