132 lines
3.8 KiB
Markdown
132 lines
3.8 KiB
Markdown
# texthelp -- Shared Text Editing Helper Library
|
|
|
|
Shared infrastructure for text editing widgets, built as
|
|
`texthelp.lib` (DXE3 module). Provides clipboard operations, cursor
|
|
blink management, word boundary detection, cross-widget selection
|
|
clearing, and a complete single-line text editing engine.
|
|
|
|
Used by: TextInput, TextArea, Spinner, ComboBox, AnsiTerm.
|
|
|
|
|
|
## API Reference
|
|
|
|
### Cursor Blink
|
|
|
|
```c
|
|
void wgtUpdateCursorBlink(void);
|
|
```
|
|
|
|
Toggles the global cursor blink state (`sCursorBlinkOn`) based on
|
|
`clock()` timing. Called from the event dispatch layer during paint.
|
|
Widgets that show a text cursor check `sCursorBlinkOn` to decide
|
|
whether to draw or hide the cursor.
|
|
|
|
### Selection Management
|
|
|
|
```c
|
|
void clearOtherSelections(WidgetT *except);
|
|
```
|
|
|
|
Clears text/item selections in all widgets except the specified one.
|
|
Called when a widget gains focus or starts a new selection, ensuring
|
|
only one widget has an active selection at a time.
|
|
|
|
### Word / Character Helpers
|
|
|
|
```c
|
|
bool isWordChar(char c);
|
|
```
|
|
|
|
Returns true if `c` is a word character (alphanumeric or underscore).
|
|
Used for double-click word selection and Ctrl+arrow word navigation.
|
|
|
|
```c
|
|
int32_t wordStart(const char *buf, int32_t pos);
|
|
```
|
|
|
|
Scans backward from `pos` to find the start of the current word.
|
|
|
|
```c
|
|
int32_t wordEnd(const char *buf, int32_t len, int32_t pos);
|
|
```
|
|
|
|
Scans forward from `pos` to find the end of the current word.
|
|
|
|
### Single-Line Text Editing Engine
|
|
|
|
Four functions implement the complete editing behavior shared across
|
|
TextInput, Spinner, ComboBox, and other single-line text widgets:
|
|
|
|
```c
|
|
void widgetTextEditOnKey(WidgetT *w, int32_t key, int32_t mod,
|
|
char *buf, int32_t bufSize, int32_t *pLen,
|
|
int32_t *pCursor, int32_t *pScrollOff,
|
|
int32_t *pSelStart, int32_t *pSelEnd,
|
|
char *undoBuf, int32_t *pUndoLen, int32_t *pUndoCursor);
|
|
```
|
|
|
|
Handles all keyboard input: character insertion, deletion (Backspace,
|
|
Delete), cursor movement (arrows, Home, End), word navigation
|
|
(Ctrl+arrows), selection (Shift+arrows, Ctrl+Shift+arrows, Ctrl+A),
|
|
clipboard (Ctrl+C/X/V), and undo (Ctrl+Z).
|
|
|
|
```c
|
|
void widgetTextEditMouseClick(WidgetT *w, int32_t vx, int32_t vy,
|
|
int32_t textLeftX, const BitmapFontT *font,
|
|
const char *buf, int32_t len, int32_t scrollOff,
|
|
int32_t *pCursorPos, int32_t *pSelStart, int32_t *pSelEnd,
|
|
bool wordSelect, bool dragSelect);
|
|
```
|
|
|
|
Handles mouse click positioning: converts pixel coordinates to cursor
|
|
position, handles word selection (double-click), and drag-select.
|
|
|
|
```c
|
|
void widgetTextEditDragUpdateLine(int32_t vx, int32_t leftEdge,
|
|
int32_t maxChars, const BitmapFontT *font, int32_t len,
|
|
int32_t *pCursorPos, int32_t *pScrollOff, int32_t *pSelEnd);
|
|
```
|
|
|
|
Updates cursor and selection during mouse drag operations.
|
|
|
|
```c
|
|
void widgetTextEditPaintLine(DisplayT *d, const BlitOpsT *ops,
|
|
const BitmapFontT *font, const ColorSchemeT *colors,
|
|
int32_t textX, int32_t textY, const char *buf,
|
|
int32_t visLen, int32_t scrollOff, int32_t cursorPos,
|
|
int32_t selStart, int32_t selEnd, uint32_t fg, uint32_t bg,
|
|
bool showCursor, int32_t cursorMinX, int32_t cursorMaxX);
|
|
```
|
|
|
|
Renders a single line of text with selection highlighting and cursor.
|
|
|
|
### Constants
|
|
|
|
| Name | Value | Description |
|
|
|------|-------|-------------|
|
|
| `TEXT_INPUT_PAD` | 3 | Padding inside text input border |
|
|
|
|
|
|
## Exported Symbols
|
|
|
|
Matches prefixes: `_clipboard*`, `_clearOther*`, `_isWordChar*`,
|
|
`_multiClick*`, `_widgetText*`, `_wordStart*`, `_wordEnd*`.
|
|
|
|
|
|
## Files
|
|
|
|
| File | Description |
|
|
|------|-------------|
|
|
| `textHelp.h` | Public API header |
|
|
| `textHelp.c` | Complete implementation |
|
|
| `Makefile` | Builds `bin/libs/texthelp.lib` + dep file |
|
|
|
|
|
|
## Build
|
|
|
|
```
|
|
make # builds bin/libs/texthelp.lib + texthelp.dep
|
|
make clean # removes objects, library, and dep file
|
|
```
|
|
|
|
Depends on: `libtasks.lib`, `libdvx.lib` (via texthelp.dep).
|