From ad7cffca27f57e07209e9ec66f5a7f96830bab30 Mon Sep 17 00:00:00 2001 From: "Kartik K. Agaram" Date: Mon, 10 Apr 2023 00:42:56 -0700 Subject: [PATCH] editor documentation --- reference.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/reference.md b/reference.md index e7c2408..35e5b1d 100644 --- a/reference.md +++ b/reference.md @@ -182,6 +182,55 @@ assertions on their side-effects. There's much more I could include here; check out [the LÖVE manual](https://love2d.org/wiki/love.graphics). +### text editor primitives + +The text-editor widget includes extremely thorough automated tests to give you +early warning if you break something. + +* `state = edit.initialize_state(top, left, right, font_height, line_height)` -- + returns an object that can be used to render an interactive editor widgets + for text and line drawings starting at `y=top` on the app window, between + `x=left` and `x=right`. Wraps long lines at word boundaries where possible, + or in the middle of words (no hyphenation yet) when it must. + +* `edit.quit()` -- calling this ensures any final edits are flushed to disk + before the app exits. + +* `edit.draw(state)` -- Call this from `App.draw` to display the current + editor state on the app window as requested in the call to + `edit.initialize_state` that created `state`. + +* `edit.update(state, dt)` -- call this from `App.update` to periodically auto + saves editor contents to disk. + +* `edit.mouse_press(state, x,y, mouse_button)` and `edit.mouse_release(x,y, + mouse_button)` -- call these to position the cursor or select some text. + +* `edit.mouse_wheel_move(state, dx,dy)` -- call this to scroll the editor in + response to a mouse wheel. + +* `edit.keychord_press(state, chord, key)` and `edit.key_release(state, key)` + -- call these to perform some standard shortcuts: insert new lines, + backspace/delete, zoom in/out font size, cut/copy/paste to and from the + clipboard, undo/redo. + +* `edit.text_input(state, t)` -- call this to insert keystrokes into the + buffer. + +* `Text.redraw_all(state)` -- call this to clear and recompute any cached + state as the cursor moves and the buffer scrolls. + +If you need more precise control, look at the comment at the top of +`edit.initialize_state` in edit.lua. In brief, the widget contains an array of +`lines`. Positions in the buffer are described in _schema-1_ locations +consisting of a `line` index and a code-point `pos`. We may also convert them +at times to _schema-2_ locations consisting of a `line`, `screen_line` and +`pos` that better indicates how long lines wrap. Schema-2 locations are never +persisted, just generated as needed from schema-1. Important schema-1 +locations in the widget are `cursor1` describing where text is inserted or +deleted and `screen_top1` which specifies how far down the lines is currently +visible on screen. + ### mouse primitives * `App.mouse_move(x, y)` -- sets the current position of the mouse to (`x`,