Merge lines.love
[text.love.git] / reference.md
blob972ab1d368676a32864904c43d20e06383f160eb
1 # Some useful building blocks
3 Apps can be composed of a wide variety of building blocks that you
4 can use in your functions, including a small number of functions that get
5 automatically called for you as appropriate.
7 ## Variables you can read
9 * `App.screen`
10   * `width` and `height` -- integer dimensions for the app window in pixels.
11   * `flags` -- some properties of the app window. See [`flags` in `love.graphics.getMode`](https://love2d.org/wiki/love.window.getMode)
12     for details.
14 * `Version` -- the running version of LÖVE as a string, e.g. '11.4'.
15 * `Major_version` -- just the part before the period as an int, e.g. 11.
17 ## Functions that get automatically called
19 * `App.initialize_globals()` -- called before running each test and also
20   before the app starts up. As the name suggests, use this to initialize all
21   your global variables to something consistent. I also find it useful to be
22   able to see all my global variables in one place, and avoid defining
23   top-level variables anywhere else (unless they're constants and never going
24   to be modified).
26 * `App.initialize(arg)` -- called when app starts up after
27   `App.initialize_globals`. Provides in `arg` an array of words typed in if
28   you ran it from a terminal window.
29   (Based on [LÖVE](https://love2d.org/wiki/love.load).)
31 * `App.quit()` -- called before the app shuts down.
32   (Based on [LÖVE](https://love2d.org/wiki/love.quit).)
34 * `App.focus(start?)` -- called when the app starts or stops receiving
35   keypresses. `start?` will be `true` when app starts receiving keypresses and
36   `false` when keypresses move to another window.
37   (Based on [LÖVE](https://love2d.org/wiki/love.focus).)
39 * `App.resize(w,h)` -- called when you resize the app window. Provides new
40   window dimensions in `w` and `h`. Don't bother updating `App.screen.width`
41   and `App.screen.height`, that will happen automatically before calling
42   `App.resize`.
43   (Based on [LÖVE](https://love2d.org/wiki/love.resize))
45 * `App.filedropped(file)` -- called when a file icon is dragged and dropped on
46   the app window. Provides in `file` an object representing the file that was
47   dropped, that will respond to the following messages:
49     * `file:getFilename()` returning a string name
50     * `file:read()` returning the entire file contents in a single string
52   (Based on [LÖVE](https://love2d.org/wiki/love.filedropped).)
54 * `App.draw()` -- called to draw on the window, around 30 times a second.
55   (Based on [LÖVE](https://love2d.org/wiki/love.draw).)
57 * `App.update(dt)` -- called after every call to `App.draw`. Make changes to
58   your app's variables here rather than in `App.draw`. Provides in `dt` the
59   time since the previous call to `App.update`, which can be useful for things
60   like smooth animations.
61   (Based on [LÖVE](https://love2d.org/wiki/love.update).)
63 * `App.mousepressed(x,y, mouse_button)` -- called when you press down on a
64   mouse button. Provides in `x` and `y` the point on the screen at which the
65   click occurred, and in `mouse_button` an integer id of the mouse button
66   pressed.
67   `1` is the primary mouse button (the left button on a right-handed mouse),
68   `2` is the secondary button (the right button on a right-handed mouse),
69   and `3` is the middle button. Further buttons are mouse-dependent.
70   (Based on [LÖVE](https://love2d.org/wiki/love.mousepressed).)
72 * `App.mousereleased(x,y, mouse_button)` -- called when you release a mouse
73   button. Provides the same arguments as `App.mousepressed()` above.
74   (Based on [LÖVE](https://love2d.org/wiki/love.mousereleased).)
76 * `App.mousemoved(x,y, dx,dy, is_touch)` -- called any time the mouse moves.
77   (Based on [LÖVE](https://love2d.org/wiki/love.mousemoved).)
79 * `App.wheelmoved(dx,dy)` -- called when you use the scroll wheel on a mouse
80   that has it. Provides in `dx` and `dy` an indication of how fast the wheel
81   is being scrolled. Positive values for `dx` indicate movement to the right.
82   Positive values for `dy` indicate upward movement.
83   (Based on [LÖVE](https://love2d.org/wiki/love.wheelmoved).)
85 * `App.mousefocus(in_focus)` -- called when the mouse pointer moves on or off
86   the app window.
87   (Based on [LÖVE](https://love2d.org/wiki/love.mousefocus).)
89 * `App.keychord_press(chord, key)` -- called when you press a key-combination.
90   Provides in `key` a string name for the key most recently pressed ([valid
91   values](https://love2d.org/wiki/KeyConstant)). Provides in `chord` a
92   string representation of the current key combination, consisting of the key
93   with the following prefixes:
94     * `C-` if one of the `ctrl` keys is pressed,
95     * `M-` if one of the `alt` keys is pressed,
96     * `S-` if one of the `shift` keys is pressed, and
97     * `s-` if the `windows`/`cmd`/`super` key is pressed.
99 * `App.textinput(t)` -- called when you press a key combination that yields
100   (roughly) a printable character. For example, `shift` and `a` pressed
101   together will call `App.textinput` with `A`.
102   (Based on [LÖVE](https://love2d.org/wiki/love.textinput).)
104 * `App.keyreleased(key)` -- called when you press a key on the keyboard.
105   Provides in `key` a string name for the key ([valid values](https://love2d.org/wiki/KeyConstant)).
106   (Based on [LÖVE](https://love2d.org/wiki/love.keyreleased), including other
107   variants.)
109 ## Functions you can call
111 Everything in the [LÖVE](https://love2d.org/wiki/Main_Page) and
112 [Lua](https://www.lua.org/manual/5.1/manual.html) guides is available to you,
113 but here's a brief summary of the most useful primitives. Some primitives have
114 new, preferred names under the `App` namespace, often because these variants
115 are more testable. If you run them within a test you'll be able to make
116 assertions on their side-effects.
118 ### regarding the app window
120 * `width, height, flags = App.screen.size()` -- returns the dimensions and
121   some properties of the app window.
122   (Based on [LÖVE](https://love2d.org/wiki/love.window.getMode).)
124 * `App.screen.resize(width, height, flags)` -- modify the size and properties
125   of the app window. The OS may or may not act on the request.
126   (Based on [LÖVE](https://love2d.org/wiki/love.window.setMode).)
128 * `x, y, displayindex = App.screen.position()` -- returns the coordinates and
129   monitor index (if you have more than one monitor) for the top-left corner of
130   the app window.
131   (Based on [LÖVE](https://love2d.org/wiki/love.window.getPosition).)
133 * `App.screen.move(x, y, displayindex)` -- moves the app window so its
134   top-left corner is at the specified coordinates of the specified monitor.
135   The OS may or may not act on the request.
136   (Based on [LÖVE](https://love2d.org/wiki/love.window.setPosition).)
138 ### drawing to the app window
140 * `App.screen.print(text, x,y)` -- print the given `text` in the current font
141   using the current color so its top-left corner is at the specified
142   coordinates of the app window.
143   (Based on [LÖVE](https://love2d.org/wiki/love.graphics.print).)
145 * `love.graphics.getFont()` -- returns a representation of the current font.
146   (From [LÖVE](https://love2d.org/wiki/love.graphics.getFont).)
148 * `love.graphics.setFont(font)` -- switches the current font to `font`.
149   (From [LÖVE](https://love2d.org/wiki/love.graphics.setFont).)
151 * `love.graphics.newFont(filename)` -- creates a font from the given font
152   file.
153   (From [LÖVE](https://love2d.org/wiki/love.graphics.newFont), including other
154   variants.)
156 * `App.width(text)` returns the width of `text` in pixels when rendered using
157   the current font.
158   (Based on [LÖVE](https://love2d.org/wiki/Font:getWidth).)
160 * `App.color(color)` -- sets the current color based on the fields `r`, `g`,
161   `b` and `a` (for opacity) of the table `color`.
162   (Based on [LÖVE](https://love2d.org/wiki/love.graphics.setColor).)
164 * `love.graphics.line(x1,y1, x2,y2)` -- draws a line from (`x1`,`y1`) to
165   (`x2`, `y2`) in the app window using the current color, clipping data for
166   negative coordinates and coordinates outside (`App.screen.width`,
167   `App.screen.height`)
168   (From [LÖVE](https://love2d.org/wiki/love.graphics.line), including other
169   variants.)
171 * `love.graphics.rectangle(mode, x, y, w, h)` -- draws a rectangle using the
172   current color, with a top-left corner at (`x`, `y`), with dimensions `width`
173   along the x axis and `height` along the y axis
174   (though check out https://love2d.org/wiki/love.graphics for ways to scale
175   and rotate shapes).
176   `mode` is a string, either `'line'` (to draw just the outline) and `'fill'`.
177   (From [LÖVE](https://love2d.org/wiki/love.graphics.circle), including other
178   variants.)
180 * `love.graphics.circle(mode, x, y, r)` -- draws a circle using the current
181   color, centered at (`x`, `y`) and with radius `r`.
182   `mode` is a string, either `'line'` and `'fill'`.
183   (From [LÖVE](https://love2d.org/wiki/love.graphics.circle), including other
184   variants.)
186 * `love.graphics.arc(mode, x, y, r, angle1, angle2)` -- draws an arc of a
187   circle using the current color, centered at (`x`, `y`) and with radius `r`.
188   `mode` is a string, either `'line'` and `'fill'`.
189   `angle1` and `angle2` are in [radians](https://en.wikipedia.org/wiki/Radian).
190   (From [LÖVE](https://love2d.org/wiki/love.graphics.circle), including other
191   variants.)
193 There's much more I could include here; check out [the LÖVE manual](https://love2d.org/wiki/love.graphics).
195 ### text editor primitives
197 The text-editor widget includes extremely thorough automated tests to give you
198 early warning if you break something.
200 * `state = edit.initialize_state(top, left, right, font, font_height, line_height)`
201   -- returns an object that can be used to render an interactive editor widget
202   for text starting at `y=top` on the app window, between `x=left` and
203   `x=right`. Wraps long lines at word boundaries where possible, or in the
204   middle of words (no hyphenation yet) when it must.
206 * `edit.quit()` -- calling this ensures any final edits are flushed to disk
207   before the app exits.
209 * `edit.draw(state)` -- call this from `App.draw` to display the current
210   editor state on the app window as requested in the call to
211   `edit.initialize_state` that created `state`.
213 * `edit.mouse_press(state, x,y, mouse_button)` and `edit.mouse_release(x,y,
214   mouse_button)` -- call these to position the cursor or select some text.
216 * `edit.mouse_wheel_move(state, dx,dy)` -- call this to scroll the editor in
217   response to a mouse wheel.
219 * `edit.keychord_press(state, chord, key)` and `edit.key_release(state, key)`
220   -- call these to perform some standard shortcuts: insert new lines,
221   backspace/delete, zoom in/out font size, cut/copy/paste to and from the
222   clipboard, undo/redo.
224 * `edit.text_input(state, t)` -- call this to insert keystrokes into the
225   buffer.
227 * `Text.redraw_all(state)` -- call this to clear and recompute any cached
228   state as the cursor moves and the buffer scrolls.
230 * `edit.update(state, dt)` -- call this from `App.update` to periodically
231   auto-save editor contents to disk.
233 * `edit.quit(state)` -- call this from `App.quit` to ensure any final edits
234   get saved before quitting.
236 If you need more precise control, look at the comment at the top of
237 `edit.initialize_state` in edit.lua. In brief, the widget contains an array of
238 `lines`. Positions in the buffer are described in _schema-1_ locations
239 consisting of a `line` index and a code-point `pos`. We may also convert them
240 at times to _schema-2_ locations consisting of a `line`, `screen_line` and
241 `pos` that better indicates how long lines wrap. Schema-2 locations are never
242 persisted, just generated as needed from schema-1. Important schema-1
243 locations in the widget are `cursor1` describing where text is inserted or
244 deleted and `screen_top1` which specifies how far down the lines is currently
245 visible on screen.
247 Some constants that affect editor behavior:
248 * `Margin_top`, `Margin_left`, `Margin_right` are integers in pixel units that
249   affect where the editor is drawn on window (it always extends to bottom of
250   window as needed)
252 * Various color constants are represented as tables with r/g/b keys:
253   * `Text_color`, `Cursor_color`, `Highlight_color` for drawing text.
255 ### clickable buttons
257 There's a facility for rendering buttons and responding to events when they're
258 clicked. It requires setting up 3 things:
259   - a `state` table housing all buttons. Can be the same `state` variable the
260     text-editor widget uses, but doesn't have to be.
261   - specifying buttons to create in `state`. This must happen either directly
262     or indirectly within `App.draw`.
263   - responding to clicks on buttons in `state`. This must happen either
264     directly or indirectly within `App.mousepressed`.
266 The following facilities help set these things up:
268 * Clear `state` at the start of each frame:
270     ```
271     state.button_handlers = {}
272     ```
274   Don't forget to do this, or your app will get slower over time.
276 * `button` creates a single button. The syntax is:
278     ```
279     button(state, name, {x=..., y=..., w=..., h=..., bg={r,g,b},
280       icon = function({x=..., y=..., w=..., h=...}) ... end,
281       onpress1 = ...
282     })
283     ```
285   Call this either directly or indirectly from `App.draw`. It will assign a
286   rectangle with the given dimensions and trigger the provided (zero-arg)
287   `onpress1` callback when the primary mouse button is clicked within.
288   It will also optionally paint the rectangle with the specified background
289   color `bg` and a foreground described by the `icon` callback (which will
290   receive the same dimensions).
292   This way you can see everything about a button in one place. Create as many
293   buttons as you like within a single shared `state`.
295 * `mouse_press_consumed_by_any_button(state, x,y, mouse_button)`
297   Call this either directly or indirectly from `App.mousepressed`. It will
298   pass on a click to any button registered in `state`. It's also helpful to
299   ensure clicks on a button don't have other effects, so I prefer the
300   following boilerplate early in `mousepressed`:
302     ```
303     if mouse_press_consumed_by_any_button(state, x,y, mouse_button) then
304       return
305     end
306     ```
308 ### mouse primitives
310 * `App.mouse_move(x, y)` -- sets the current position of the mouse to (`x`,
311   `y`).
312   (Based on [LÖVE](https://love2d.org/wiki/love.mouse.setPosition).)
314 * `App.mouse_down(mouse_button)` -- returns `true` if the button
315   `mouse_button` is pressed. See `App.mousepressed` for `mouse_button` codes.
316   (Based on [LÖVE](https://love2d.org/wiki/love.mouse.isDown).)
318 * `App.mouse_x()` -- returns the x coordinate of the current position of the
319   mouse.
320   (Based on [LÖVE](https://love2d.org/wiki/love.mouse.getX).)
322 * `App.mouse_y()` -- returns the x coordinate of the current position of the
323   mouse.
324   (Based on [LÖVE](https://love2d.org/wiki/love.mouse.getY).)
326 ### keyboard primitives
328 * `App.is_cursor_movement(key)` -- return `true` if `key` is a cursor movement
329   key (arrow keys, page-up/down, home/end)
331 * `App.cmd_down()`, `App.ctrl_down`, `App.alt_down()`, `App.shift_down()` --
332   predicates for different modifier keys.
334 * `App.any_modifier_down()` -- returns `true` if any of the modifier keys is
335   currently pressed.
337 * `App.key_down(key)` -- returns `true` if the given key is currently pressed.
338   (Based on [LÖVE](https://love2d.org/wiki/love.keyboard.isDown).)
340 ### interacting with files
342 * `App.open_for_reading(filename)` -- returns a file handle that you can
343   [`read()`](https://www.lua.org/manual/5.1/manual.html#pdf-file:read) from.
344   Make sure `filename` is an absolute path so that your app can work reliably
345   by double-clicking on it.
346   (Based on [Lua](https://www.lua.org/manual/5.1/manual.html#pdf-io.open).)
348 * `App.open_for_writing(filename)` -- returns a file handle that you can
349   [`write()`](https://www.lua.org/manual/5.1/manual.html#pdf-file:write) to.
350   Make sure `filename` is an absolute path so that your app can work reliably
351   by double-clicking on it.
352   (Based on [Lua](https://www.lua.org/manual/5.1/manual.html#pdf-io.open).)
354 * `json.encode(obj)` -- returns a JSON string for an object `obj` that will
355   recreate `obj` when passed to `json.decode`. `obj` can be of most types but
356   has some exceptions.
357   (From [json.lua](https://github.com/rxi/json.lua).)
359 * `json.decode(obj)` -- turns a JSON string into a Lua object.
360   (From [json.lua](https://github.com/rxi/json.lua).)
362 * `App.files(dir)` -- returns an unsorted array of the files and directories
363   available under `dir`.
364   (From [LÖVE](https://love2d.org/wiki/love.filesystem.getDirectoryItems).]
366 * `App.file_info(filename)` -- returns some information about
367   `filename`, particularly whether it exists (non-`nil` return value) or not.
368   (From [LÖVE](https://love2d.org/wiki/love.filesystem.getInfo).]
370 * `App.mkdir(path)` -- creates a directory. Make sure `path` is absolute.
371   (From [LÖVE](https://love2d.org/wiki/love.filesystem.remove).]
373 * `App.remove(filename)` -- removes a file or empty directory. Definitely make
374   sure `filename` is an absolute path.
375   (From [LÖVE](https://love2d.org/wiki/love.filesystem.remove).]
377 There's much more I could include here; check out [the LÖVE manual](https://love2d.org/wiki/love.filesystem)
378 and [the Lua manual](https://www.lua.org/manual/5.1/manual.html#5.7).
380 ### desiderata
382 * `App.get_time()` -- returns the number of seconds elapsed since some
383   unspecified start time.
384   (Based on [LÖVE](https://love2d.org/wiki/love.timer.getTime).)
386 * `App.get_clipboard()` -- returns a string with the current clipboard
387   contents.
388   (Based on [LÖVE](https://love2d.org/wiki/love.system.getClipboardText).)
390 * `App.set_clipboard(text)` -- stores the string `text` in the clipboard.
391   (Based on [LÖVE](https://love2d.org/wiki/love.system.setClipboardText).)
393 * `array.find(arr, elem)` -- scan table `arr` for `elem` assuming it's
394   organized as an array (just numeric indices).
396 * `array.any(arr, f)` -- scan table `arr` for any elements satisfying
397   predicate `f`. Return first such element or `false` if none.
399 There's much more I could include here; check out [the LÖVE manual](https://love2d.org/wiki)
400 and [the Lua manual](https://www.lua.org/manual/5.1/manual.html).
402 ### writing tests
404 * `App.screen.init{width=.., height=..}` -- creates a fake screen for a test
406 * `App.screen.check(y, expected_contents, msg)` -- verifies text written to
407   the fake screen at `y`. This isn't very realistic; `y` must exactly match
408   what was displayed, and the expected contents show everything printed to
409   that `y` in chronological order, regardless of `x` coordinate. In spite of
410   these limitations, you can write lots of useful tests with this.
412 * `App.run_after_textinput(t)` -- mimics keystrokes resulting in `t` and then
413   draws one frame.
415 * `App.run_after_keychord(chord, key)` -- mimics the final `key` press
416   resulting in `chord` and then draws one frame.
418 * `App.run_after_mouse_press(x,y, mouse_button)` -- mimics a mouse press down
419   followed by drawing a frame.
421 * `App.run_after_mouse_release(x,y, mouse_button)` -- mimics a mouse release
422   up followed by drawing a frame.
424 * `App.run_after_mouse_click(x,y, mouse_button)` -- mimics a mouse press down
425   and mouse release up followed by drawing a frame.
427 * `App.wait_fake_time(t)` -- simulates the passage of time for `App.getTime()`.