Documentation: Ported Processing "Input" examples

docs/examples/clock.md

@@ -0,0 +1,80 @@
+# Clock
+
+This example displays the current time as an analog clock using sine and cosine functions to position the clock hands.
+
+It demonstrates:
+
+- reading the current time with `second()`, `minute()`, and `hour()`
+- using trigonometric functions (`sin()` and `cos()`) to position elements in circular patterns
+- the `map()` function to convert time values to angles
+- drawing multiple elements at different scales
+- using `HALF_PI` to rotate angle calculations
+
+From here, you can try:
+
+- adding a digital time display alongside the analog clock
+- creating a 12-hour vs 24-hour clock toggle
+- adding decorative elements like numbers around the clock face
+- animating the transition between hour, minute, and second hands
+
+![animation of an analog clock displaying the current time](/assets/examples/clock.gif "An analog clock with moving hour, minute, and second hands")
+
+```lua
+require("L5")
+
+local cx, cy
+local secondsRadius
+local minutesRadius
+local hoursRadius
+local clockDiameter
+
+function setup()
+    size(640, 360)
+    windowTitle("Clock")
+    describe("Display the current time")
+
+    stroke(255)
+
+    local radius = min(width, height) / 2
+    secondsRadius = radius * 0.72
+    minutesRadius = radius * 0.60
+    hoursRadius = radius * 0.50
+    clockDiameter = radius * 1.8
+
+    cx = width / 2
+    cy = height / 2
+end
+
+function draw()
+    background(0)
+
+    -- Draw the clock background
+    fill(80)
+    noStroke()
+    ellipse(cx, cy, clockDiameter, clockDiameter)
+
+    -- Angles for sin() and cos() start at 3 o'clock;
+    -- subtract HALF_PI to make them start at the top
+    local s = map(second(), 0, 60, 0, TWO_PI) - HALF_PI
+    local m = map(minute() + map(second(), 0, 60, 0, 1), 0, 60, 0, TWO_PI) - HALF_PI
+    local h = map(hour() + map(minute(), 0, 60, 0, 1), 0, 24, 0, TWO_PI * 2) - HALF_PI
+
+    -- Draw the hands of the clock
+    stroke(255)
+    strokeWeight(1)
+    line(cx, cy, cx + cos(s) * secondsRadius, cy + sin(s) * secondsRadius)
+    strokeWeight(2)
+    line(cx, cy, cx + cos(m) * minutesRadius, cy + sin(m) * minutesRadius)
+    strokeWeight(4)
+    line(cx, cy, cx + cos(h) * hoursRadius, cy + sin(h) * hoursRadius)
+
+    -- Draw the minute ticks
+    strokeWeight(2)
+    for a = 0, 354, 6 do
+        local angle = radians(a)
+        local x = cx + cos(angle) * secondsRadius
+        local y = cy + sin(angle) * secondsRadius
+        point(x, y)
+    end
+end
+```

docs/examples/constrain.md

@@ -0,0 +1,62 @@
+# Constrain
+
+This example demonstrates constraining a shape's movement within a bounded area. A circle follows the mouse with easing applied, keeping it within a rectangular box.
+
+It demonstrates:
+
+- the `constrain()` function to limit values within a range
+- smooth motion with easing
+- mouse tracking with gradual animation
+- using `abs()` to check for minimum movement thresholds
+- different drawing modes with `ellipseMode()` and `rectMode()`
+
+From here, you can try:
+
+- creating multiple constrained objects that interact with each other
+- using different easing values to create different speeds
+- constraining to circular or other shaped boundaries
+- adding keyboard controls to move the constrained object
+
+![animation of a circle following the mouse within a bounded box](/assets/examples/constrain.gif "A white circle that follows the mouse while staying constrained within a rectangular boundary")
+
+```lua
+require("L5")
+
+local mx = 0
+local my = 0
+local easing = 0.05
+local radius = 24
+local edge = 100
+local inner = edge + radius
+
+function setup()
+    size(640, 360)
+    windowTitle("Constrain")
+    describe(" Move the mouse across the screen to move the circle. The program constrains the circle to its box.")
+
+    noStroke()
+    ellipseMode(RADIUS)
+    rectMode(CORNERS)
+end
+
+function draw()
+    background(51)
+
+    -- Change the position of the drawn ellipse to the position of the mouse with easing
+    if (abs(mouseX - mx) > 0.1) then
+        mx = mx + (mouseX - mx) * easing
+    end
+
+    if (abs(mouseY - my) > 0.1) then
+        my = my + (mouseY - my) * easing
+    end
+
+    -- Constrain the position of the ellipse to the inner rectangle
+    mx = constrain(mx, inner, width - inner)
+    my = constrain(my, inner, height - inner)
+    fill(76)
+    rect(edge, edge, width - edge, height - edge)
+    fill(255)
+    ellipse(mx, my, radius, radius)
+end
+```

docs/examples/easing.md

@@ -0,0 +1,52 @@
+# Easing
+
+This example demonstrates smooth animation by moving a shape toward the mouse position with easing. The shape doesn't jump directly to the cursor but gradually glides toward it.
+
+It demonstrates:
+
+- creating smooth, natural-looking motion
+- calculating the difference between current and target positions
+- applying easing factors to create gradual movement
+- following the mouse position without snap
+- simple animation principles
+
+From here, you can try:
+
+- varying the easing value to create different speeds and smoothness levels
+- having multiple shapes with different easing values
+- creating easing toward different target positions (not just the mouse)
+- implementing other interpolation methods like lerp or acceleration/velocity
+
+![animation of a circle smoothly following the mouse cursor](/assets/examples/easing.gif "A white circle that glides toward the mouse cursor with smooth easing")
+
+```lua
+require("L5")
+
+local x = 0
+local y = 0
+local easing = 0.05
+
+function setup()
+    size(640, 360)
+    windowTitle("Easing")
+    describe(" Move the mouse across the screen and the symbol will follow.")
+
+    noStroke()
+end
+
+function draw()
+    background(51)
+
+    -- Change the position of the drawn ellipse to the position of the mouse with easing
+
+    targetX = mouseX
+    dx = targetX - x
+    x = x + dx * easing
+
+    targetY = mouseY
+    dy = targetY - y
+    y = y + dy * easing
+
+    ellipse(x, y, 66)
+end
+```

docs/examples/index.md

@@ -1,30 +1,53 @@
-# Examples 
+# Examples
 
 ## Shapes and Colors
 
-* [Shape Primitives](shapes-and-color-shape-primitives.md) - Draw 2D shapes
-* [Color](shapes-and-color-color.md) - Add color to your sketch
+- [Shape Primitives](shapes-and-color-shape-primitives.md) - Draw 2D shapes
+- [Color](shapes-and-color-color.md) - Add color to your sketch
 
 ## Animations and Variables
 
-* [Doodle Draw](doodle-draw.md) - Create a basic drawing program tracking mouse movements
-* [Drawing Lines](animation-and-variables-drawing-lines.md) - A drawing program demonstrating HSB colorMode
-* [Animation with Events](animation-and-variables-animation-with-events.md) - Pause and resume animation.
-* [Conditions](animation-and-variables-conditions.md) - Use if and else statements to make decisions while your sketch runs.
-* [Basic Pong](basic-pong.md) - A simple program demonstrating a basic implementation of pong with enemy AI player
-* [Walking Lines](walking-lines.md) - Animated intersecting lines
-* [10Print](10print.md) - An implementation of the classic maze-drawing algorithm
-* [Conway's Game Of Life](conways-life.md) - An implementation of the zero-player game and simulation formulated by mathematician John Conway
-* [Minimum Spanning Tree](min-span-tree.md) - An example of implementing Prim's algorithm for finding the shortest lengths to connect all randomly placed dots
+- [Doodle Draw](doodle-draw.md) - Create a basic drawing program tracking mouse movements
+- [Drawing Lines](animation-and-variables-drawing-lines.md) - A drawing program demonstrating HSB colorMode
+- [Animation with Events](animation-and-variables-animation-with-events.md) - Pause and resume animation.
+- [Conditions](animation-and-variables-conditions.md) - Use if and else statements to make decisions while your sketch runs.
+- [Basic Pong](basic-pong.md) - A simple program demonstrating a basic implementation of pong with enemy AI player
+- [Walking Lines](walking-lines.md) - Animated intersecting lines
+- [10Print](10print.md) - An implementation of the classic maze-drawing algorithm
+- [Conway's Game Of Life](conways-life.md) - An implementation of the zero-player game and simulation formulated by mathematician John Conway
+- [Minimum Spanning Tree](min-span-tree.md) - An example of implementing Prim's algorithm for finding the shortest lengths to connect all randomly placed dots
+- [Easing](easing.md) - Smooth animation with easing as a shape follows the mouse
+- [Clock](clock.md) - Display the current time as an analog clock
+- [Milliseconds](milliseconds.md) - Create time-based color patterns using elapsed milliseconds
+
+## Input and Interaction
+
+### Mouse Input
+
+- [Mouse 1D](mouse-1d.md) - Use horizontal mouse position to shift the balance between two rectangles
+- [Mouse 2D](mouse-2d.md) - Control position and size of boxes using two-dimensional mouse movement
+- [Mouse Press](mouse-press.md) - Create a crosshair that changes color when the mouse button is pressed
+- [Mouse Functions](mouse-functions.md) - Click and drag a box around the screen
+- [Mouse Signals](mouse-signals.md) - Visualize mouse input signals as real-time waveforms
+- [Storing Input](storing-input.md) - Record and display mouse position trails over time
+
+### Keyboard Input
+
+- [Keyboard](keyboard.md) - Press letter keys to create forms in different positions
+- [Keyboard Functions](keyboard-functions.md) - Interactive color typewriter with different output for uppercase and lowercase letters
+
+### Constraints and Movement
+
+- [Constrain](constrain.md) - Limit a shape's movement within a bounded area
 
 ## Imported Media
 
-* [Daily Rituals](daily-rituals.md) - One a day daily ritual generator
-* [Words](imported-media-words.md) - Load fonts and draw text
-* [Copy Image Data](imported-media-copy-image-data.md) - Paint from an image file onto the canvas
-* [Image Transparency](imported-media-image-transparency.md) - Make an image translucent on the canvas
-* [Video Player](imported-media-video.md) - Create a player for video playback and stylize in the window
+- [Daily Rituals](daily-rituals.md) - One a day daily ritual generator
+- [Words](imported-media-words.md) - Load fonts and draw text
+- [Copy Image Data](imported-media-copy-image-data.md) - Paint from an image file onto the canvas
+- [Image Transparency](imported-media-image-transparency.md) - Make an image translucent on the canvas
+- [Video Player](imported-media-video.md) - Create a player for video playback and stylize in the window
 
-## Object-Orientation 
+## Object-Orientation
 
-* [Random Robot Objects](random-robot-objects.md) - Demonstrates two different Lua patterns - classes with metatables and simple table objects
+- [Random Robot Objects](random-robot-objects.md) - Demonstrates two different Lua patterns - classes with metatables and simple table objects

docs/examples/keyboard-functions.md

@@ -0,0 +1,108 @@
+# Keyboard Functions
+
+This example creates an interactive color typewriter where different letter cases produce different sized rectangles with different colors from the HSB color space.
+
+It demonstrates:
+
+- the `keyPressed()` callback function
+- distinguishing between uppercase and lowercase keys
+- using HSB color mode for easy hue variation
+- managing state variables for continuous drawing
+- wrapping text display horizontally and vertically
+- creating visual feedback for keyboard input
+
+From here, you can try:
+
+- adding different shapes for different key categories
+- incorporating `keyReleased()` for key release events
+- creating a full text display that captures typed words
+- creating animated transitions between letters
+
+![animation of a color typewriter with varying heights](/assets/examples/keyboard-functions.gif "Colored rectangles of different heights appearing continuously as keys are typed, wrapping across the screen")
+
+```lua
+require("L5")
+
+local maxHeight = 40
+local minHeight = 20
+local letterHeight = maxHeight
+local letterWidth = 20
+
+local x = -letterWidth
+local y = 0
+
+local newletter = false
+
+local numChars = 26
+local colors = {}
+
+function setup()
+    size(640, 360)
+    windowTitle("Keyboard Functions")
+    describe("Press letter keys to create forms in time and space")
+
+    noStroke()
+    colorMode(HSB, numChars)
+    background(numChars / 2)
+
+    -- Set a hue value for each key
+    for i = 0, numChars - 1 do
+        colors[i] = color(i, numChars, numChars)
+    end
+end
+
+function draw()
+    if newletter == true then
+        -- Draw the "letter"
+        local y_pos
+        if letterHeight == maxHeight then
+            y_pos = y
+            rect(x, y_pos, letterWidth, letterHeight)
+        else
+            y_pos = y + minHeight
+            rect(x, y_pos, letterWidth, letterHeight)
+            fill(numChars / 2)
+            rect(x, y_pos - minHeight, letterWidth, letterHeight)
+        end
+        newletter = false
+    end
+end
+
+function keyPressed()
+    -- If the key is between 'A'(65) to 'Z' and 'a' to 'z'(122)
+    local keyByte = string.byte(key)
+
+    if (keyByte >= string.byte('A') and keyByte <= string.byte('Z')) or
+        (keyByte >= string.byte('a') and keyByte <= string.byte('z')) then
+        local keyIndex
+        if keyByte <= string.byte('Z') then
+            keyIndex = keyByte - string.byte('A')
+            letterHeight = maxHeight
+            fill(colors[keyIndex])
+        else
+            keyIndex = keyByte - string.byte('a')
+            letterHeight = minHeight
+            fill(colors[keyIndex])
+        end
+    else
+        fill(0)
+        letterHeight = 10
+    end
+
+    newletter = true
+
+    -- Update the "letter" position
+    x = x + letterWidth
+
+    -- Wrap horizontally
+    if x > width - letterWidth then
+        x = 0
+        y = y + maxHeight
+    end
+
+    -- Wrap vertically
+    if y > height - letterHeight then
+        y = 0
+    end
+end
+```