# Some useful building blocks

# Building blocks for your Freewheeling Apps
Freewheeling apps consist of 4 kinds of things:
  - a small number of functions you can define that get automatically called
    for you as appropriate,
  - a wide variety of primitives that you can call but not modify,
  - tests that start with `test_` and run on startup or after any change you
    make to the app's code, and
  - any other function you can define and call at will.

Apps can be composed of a wide variety of building blocks that you
can use in your functions, including a small number of functions that get
automatically called for you as appropriate.

The rest of this document will summarize what is available to you in the first
two categories.

## Functions that get automatically called
* `App.initialize_globals()` -- called before running each test and also
  before the app starts up. As the name suggests, use this to initialize all
  your global variables to something consistent. I also find it useful to be
  able to see all my global variables in one place, and avoid defining
  top-level variables anywhere else (unless they're constants and never going
  to be modified).

## Functions you can implement that will get automatically called

* `App.initialize(arg)` -- called when app starts up after
  `App.initialize_globals`. Provides in `arg` an array of words typed in if
  you ran it from a terminal window.

* `on.initialize(arg)` -- called when app starts up. Provides in `arg` an
  array of words typed in if you ran it from a terminal window.

* `App.quit()` -- called before the app shuts down.

* `on.quit()` -- called before the app shuts down.

* `App.focus(start?)` -- called when the app starts or stops receiving

* `on.save_settings()` -- called after on.quit and should return a table which
  will be saved to disk.
* `on.load_settings(settings)` -- called when app starts up, before
  `on.initialize`. Provides in `settings` the table that was saved to disk the
  last time the app shut down.
* `on.focus(start?)` -- called when the app starts or stops receiving

* `App.resize(w,h)` -- called when you resize the app window. Provides new

* `on.resize(w,h)` -- called when you resize the app window. Provides new

* `App.filedropped(file)` -- called when a file icon is dragged and dropped on

* `on.file_drop(file)` -- called when a file icon is dragged and dropped on

* `App.draw()` -- called to draw on the window, around 30 times a second.

* `on.code_change()` -- called when you make changes to the app using
  [driver.love](https://git.sr.ht/~akkartik/driver.love), any time you hit
  `f4` inside driver.love, after a definition is created or modified.
* `on.draw()` -- called to draw on the window, around 30 times a second.

* `App.update(dt)` -- called after every call to `on.draw`. Make changes to

* `on.update(dt)` -- called after every call to `on.draw`. Make changes to

* `App.mousepressed(x,y, mouse_button)` -- called when you press down on a
  mouse button. Provides in `x` and `y` the point on the screen at which the
  click occurred, and in `mouse_button` an integer id of the mouse button
  pressed.

* `on.mouse_press(x,y, mouse_button)` -- called when you press down on a mouse
  button. Provides in `x` and `y` the point on the screen at which the click
  occurred, and in `mouse_button` an integer id of the mouse button pressed.

* `App.mousereleased(x,y, mouse_button)` -- called when you release a mouse

* `on.mouse_release(x,y, mouse_button)` -- called when you release a mouse

* `App.wheelmoved(dx,dy)` -- called when you use the scroll wheel on a mouse
  that has it. Provides in `dx` and `dy` an indication of how fast the wheel
  is being scrolled. Positive values for `dx` indicate movement to the right.
  Positive values for `dy` indicate upward movement.

* `on.mouse_wheel_move(dx,dy)` -- called when you use the scroll wheel on a
  mouse that has it. Provides in `dx` and `dy` an indication of how fast the
  wheel is being scrolled. Positive values for `dx` indicate movement to the
  right. Positive values for `dy` indicate upward movement.

* `App.keychord_press(chord, key)` -- called when you press a key-combination.

* `on.keychord_press(chord, key)` -- called when you press a key-combination.

* `App.textinput(t)` -- called when you press a key combination that yields

* `on.text_input(t)` -- called when you press a key combination that yields

* `App.keyrelease(key)` -- called when you press a key on the keyboard.

* `on.key_release(key)` -- called when you press a key on the keyboard.

  App.screen.draw = love.graphics.draw