FlexLove

https://mikefreno.github.io/FlexLove/
Admin
FlexLove is a powerful Lua UI framework providing CSS-like flexbox and grid layouts, 9-patch...
Tokens:36,389
Snippets:594
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install FlexLove using Git

Source: https://mikefreno.github.io/FlexLove/index.html

Instructions for cloning the FlexLove repository and copying the necessary files into your project directory.

```bash
git clone https://github.com/mikefreno/FlexLove.git
cp -r FlexLove/modules your-project/
cp FlexLove/FlexLove.lua your-project/Copy
```

--------------------------------

### FlexLove.beginFrame

Source: https://mikefreno.github.io/FlexLove/api.html

Begins a new immediate mode frame. This should be called at the start of each frame when using immediate mode.

```APIDOC
## FlexLove.beginFrame

### Description
Begin a new immediate mode frame.

### Method
function FlexLove.beginFrame()

### Endpoint
N/A (Function call)
```

--------------------------------

### Begin New Frame

Source: https://mikefreno.github.io/FlexLove/api.html

Starts a new frame for immediate mode rendering. This should be called at the beginning of each frame.

```typescript
function FlexLove.beginFrame()
```

--------------------------------

### Text Editor Get Selection Method

Source: https://mikefreno.github.io/FlexLove/api.html

Retrieves the start and end positions of the current text selection, or nil if none.

```lua
(method) TextEditor:getSelection()
  -> number?
  2. number?
```

--------------------------------

### Get Registered Themes

Source: https://mikefreno.github.io/FlexLove/api.html

Returns a list of all theme names that have been registered with the system.

```lua
function Theme.getRegisteredThemes()
  -> table<string>

```

--------------------------------

### Move Cursor to Line Start

Source: https://mikefreno.github.io/FlexLove/api.html

Moves the cursor to the beginning of the current line.

```typescript
(method) TextEditor:moveCursorToLineStart()
```

--------------------------------

### textAlign

Source: https://mikefreno.github.io/FlexLove/api.html

Sets the alignment of the text content. Defaults to START.

```APIDOC
## textAlign
```
TextAlign?
```

Alignment of the text content (default: START)
```

--------------------------------

### FlexLove.getMode

Source: https://mikefreno.github.io/FlexLove/api.html

Gets the current mode of FlexLove (immediate or retained).

```APIDOC
## FlexLove.getMode

### Description
Get the current mode of FlexLove.

### Method
function FlexLove.getMode()
  -> "immediate"|"retained"

### Response
#### Success Response (200)
- **mode** ("immediate"|"retained") - The current mode of FlexLove.
```

--------------------------------

### Get Selection Rectangles for Rendering

Source: https://mikefreno.github.io/FlexLove/api.html

Calculates the bounding boxes for the current text selection, used for visual highlighting. Takes start and end positions as input.

```typescript
(method) TextEditor:_getSelectionRects(selStart: number, selEnd: number)
  -> table
```

--------------------------------

### Get Theme Font

Source: https://mikefreno.github.io/FlexLove/api.html

Retrieves the path for a named font from the active theme. For example, 'default' or 'heading'.

```lua
function Theme.getFont(fontName: string)
  -> string?

```

--------------------------------

### Text Editor Get Text Method

Source: https://mikefreno.github.io/FlexLove/api.html

Retrieves the entire text content currently held by the editor.

```lua
(method) TextEditor:getText()
  -> string
```

--------------------------------

### Create a Simple Fade Animation

Source: https://mikefreno.github.io/FlexLove/api.html

Use this function to create a basic fade animation. Specify the duration, starting opacity, and ending opacity.

```lua
function Animation.fade(duration: number, fromOpacity: number, toOpacity: number)
  -> Animation
```

--------------------------------

### _handleTextClick

Source: https://mikefreno.github.io/FlexLove/api.html

Handles mouse clicks on text to set cursor position or start selection.

```APIDOC
## _handleTextClick
```
(method) Element:_handleTextClick(mouseX: number, mouseY: number, clickCount: number)
```

Handle mouse click on text (set cursor position or start selection)
@_param_ `mouseX` — Mouse X coordinate
@_param_ `mouseY` — Mouse Y coordinate
@_param_ `clickCount` — Number of clicks (1=single, 2=double, 3=triple)
```

--------------------------------

### Move Cursor to Start of Text

Source: https://mikefreno.github.io/FlexLove/api.html

Moves the cursor to the very beginning of the text buffer.

```typescript
(method) TextEditor:moveCursorToStart()
```

--------------------------------

### Create a Simple Scale Animation

Source: https://mikefreno.github.io/FlexLove/api.html

Use this function to create a basic scale animation. Specify the duration and the starting and ending scale dimensions.

```lua
function Animation.scale(duration: number, fromScale: table, toScale: table)
  -> Animation
```

--------------------------------

### Get Current Mode

Source: https://mikefreno.github.io/FlexLove/api.html

Retrieves the current operating mode of FlexLove, which can be 'immediate' or 'retained'.

```typescript
function FlexLove.getMode()
  -> "immediate"|"retained"
```

```typescript
return #1:
    | "immediate"
    | "retained"
```

--------------------------------

### Get Theme Component

Source: https://mikefreno.github.io/FlexLove/api.html

Retrieves a specific component from the active theme. Optionally specify a state like 'hover' or 'disabled'.

```lua
function Theme.getComponent(componentName: string, state?: string)
  -> ThemeComponent?

```

--------------------------------

### Text Editor Get Selected Text Method

Source: https://mikefreno.github.io/FlexLove/api.html

Returns the currently selected text, or nil if no text is selected.

```lua
(method) TextEditor:getSelectedText()
  -> string?
```

--------------------------------

### Initialize and Draw with FlexLove

Source: https://mikefreno.github.io/FlexLove/index.html

Demonstrates initializing FlexLove with a theme and drawing a UI with a button. The `love.draw` function uses a callback for game content that will be blurred and another for content drawn after GUI elements.

```lua
local FlexLove = require("FlexLove")

-- (Optional) Initialize with a theme and immediate mode
FlexLove.init({
  theme = "space",
  immediateMode = true
})

function love.update(dt)
  FlexLove.update(dt)
end

function love.draw()
    FlexLove.draw(function()
        -- Game content (will be blurred by backdrop blur)
        local button = FlexLove.new({
        width = "20vw",
        height = "10vh",
        backgroundColor = Color.new(0.2, 0.2, 0.8, 1),
        text = "Click Me",
        textSize = "md",
        themeComponent = "button",
        onEvent = function(element, event)
            print("Button clicked!")
    end
    })
    end, function()
        -- This is drawn AFTER all GUI elements - no backdrop blur
        SomeMetaComponent:draw()
    end)
end
```

--------------------------------

### FlexLove Initialization: Immediate vs Retained Mode

Source: https://mikefreno.github.io/FlexLove/examples.html

Demonstrates how to initialize FlexLove in either retained mode (default) or immediate mode. Immediate mode is faster for prototyping.

```lua
-- Retained Mode (default) - elements persist between frames
FlexLove.init({
  baseScale = { width = 1920, height = 1080 }
})

-- Immediate Mode - elements recreated each frame
FlexLove.init({
  baseScale = { width = 1920, height = 1080 },
  immediateMode = true
})Copy
```

--------------------------------

### Initialize FlexLöve with a Theme

Source: https://mikefreno.github.io/FlexLove/examples.html

Initialize FlexLöve by requiring the library and calling init with baseScale and a theme name like "space" or "metal".

```lua
local FlexLove = require("FlexLove")

-- Initialize with a built-in theme
FlexLove.init({
  baseScale = { width = 1920, height = 1080 },
  theme = "space"  -- Options: "space", "metal"
})
```

--------------------------------

### Create Basic Vertical Flex Window

Source: https://mikefreno.github.io/FlexLove/examples.html

Use FlexLove.new with positioning = "flex" and flexDirection = "vertical" to create a main window with vertical spacing.

```lua
-- Create a main window with vertical flex layout
local window = FlexLove.new({
  x = "10%",
  y = "10%",
  width = "80%",
  height = "80%",
  themeComponent = "framev3",
  positioning = "flex",
  flexDirection = "vertical",
  gap = 20,
  padding = { horizontal = 20, vertical = 20 }
})

-- Add a title
FlexLove.new({
  parent = window,
  text = "Advanced Layout Example",
  textAlign = "center",
  textSize = "3xl",
  width = "100%"
})
```

--------------------------------

### Set Text Selection Range

Source: https://mikefreno.github.io/FlexLove/api.html

Defines the selected range of text within the element. Requires start and end positions (inclusive).

```lua
(method) Element:setSelection(startPos: number, endPos: number)

```

--------------------------------

### FlexLove.init

Source: https://mikefreno.github.io/FlexLove/api.html

Initializes the FlexLove library with a configuration object. This must be called before using other FlexLove functions.

```APIDOC
## FlexLove.init

### Description
Initialize the FlexLove library with a configuration object.

### Method
function FlexLove.init(config: { baseScale: { width: number?, height: number? }?, theme: (string|ThemeDefinition)?, immediateMode: boolean?, stateRetentionFrames: number?, maxStateEntries: number?, autoFrameManagement: boolean? })

### Parameters
#### Path Parameters
- **config** (table) - Required - Configuration object with optional properties:
  - **baseScale** (table) - Optional - Base scale for UI elements. Contains `width` and `height`.
  - **theme** (string|ThemeDefinition) - Optional - The theme to use for the UI.
  - **immediateMode** (boolean) - Optional - Enable immediate mode.
  - **stateRetentionFrames** (number) - Optional - Number of frames to retain state.
  - **maxStateEntries** (number) - Optional - Maximum number of state entries.
  - **autoFrameManagement** (boolean) - Optional - Enable automatic frame management.
```

--------------------------------

### Batch Element Creation in FlexLove

Source: https://mikefreno.github.io/FlexLove/examples.html

Illustrates the correct way to create UI elements in FlexLove by creating them once in `love.load` rather than repeatedly in `love.draw` to avoid performance issues.

```lua
-- ❌ Bad: Creating elements in love.draw() (retained mode)
function love.draw()
  local button = FlexLove.new({ ... })  -- DON'T DO THIS
end

-- ✅ Good: Create once, reuse
local button
function love.load()
  button = FlexLove.new({ ... })
end

function love.draw()
  FlexLove.draw()  -- Just draw existing elements
endCopy
```

--------------------------------

### Create New Theme

Source: https://mikefreno.github.io/FlexLove/api.html

Initializes a new Theme object from a provided definition table.

```lua
function Theme.new(definition: any)
  -> Theme

```

--------------------------------

### TextEditor:getSelection

Source: https://mikefreno.github.io/FlexLove/api.html

Retrieves the start and end positions of the current text selection.

```APIDOC
## TextEditor:getSelection

### Description
Get selection range.

### Method
`TextEditor:getSelection()`

### Returns
* `number?` - Start position
* `number?` - End position
(Returns nil if no selection)
```

--------------------------------

### Initialize Element

Source: https://mikefreno.github.io/FlexLove/api.html

Constructor for creating a new Element instance. Requires properties and dependencies.

```lua
function Element.new(props: ElementProps, deps: table)
  -> Element

```

--------------------------------

### Use Multiple Sliders in a Settings Window

Source: https://mikefreno.github.io/FlexLove/examples.html

Demonstrates how to create a settings window and populate it with multiple slider controls for different parameters. Requires the `createSlider` function to be defined.

```lua
-- Create settings window
local settingsWindow = FlexLove.new({
  x = "10%",
  y = "10%",
  width = "80%",
  height = "80%",
  themeComponent = "framev3",
  positioning = "flex",
  flexDirection = "vertical",
  gap = 20,
  padding = { horizontal = "5%", vertical = "3%" }
})

-- Title
FlexLove.new({
  parent = settingsWindow,
  text = "Settings",
  textAlign = "center",
  textSize = "3xl"
})

-- Create sliders for different settings
createSlider(settingsWindow, "Volume", 0, 100, 75)
createSlider(settingsWindow, "Brightness", 0, 100, 50)
createSlider(settingsWindow, "Sensitivity", 10, 200, 100)
```

--------------------------------

### TextEditor:setSelection

Source: https://mikefreno.github.io/FlexLove/api.html

Sets the text selection range by specifying the start and end positions.

```APIDOC
## setSelection

### Description
Set selection range.

### Method
TextEditor:setSelection(startPos: number, endPos: number)

### Parameters
#### Path Parameters
- **startPos** (number) - Start position (inclusive)
- **endPos** (number) - End position (inclusive)
```

--------------------------------

### Initialize FlexLove

Source: https://mikefreno.github.io/FlexLove/api.html

Initializes the FlexLove library. Configuration options include base scale, theme, and mode settings.

```typescript
function FlexLove.init(config: { baseScale: { width: number?, height: number? }?, theme: (string|ThemeDefinition)?, immediateMode: boolean?, stateRetentionFrames: number?, maxStateEntries: number?, autoFrameManagement: boolean? })
```

--------------------------------

### TextEditor:_getCursorScreenPosition

Source: https://mikefreno.github.io/FlexLove/api.html

Internal method to get the cursor's screen position for rendering.

```APIDOC
## _getCursorScreenPosition

### Description
Get cursor screen position for rendering (handles multiline text).

### Method
TextEditor:_getCursorScreenPosition()

### Returns
- **number** - Cursor X position relative to content area
- **number** - Cursor Y position relative to content area
```

--------------------------------

### Text Editor Initialize Method

Source: https://mikefreno.github.io/FlexLove/api.html

Initializes the TextEditor with a reference to its parent element.

```lua
(method) TextEditor:initialize(element: table)
```

--------------------------------

### Get State Count

Source: https://mikefreno.github.io/FlexLove/api.html

Returns the total number of states currently managed by FlexLove.

```typescript
function FlexLove.getStateCount()
  -> number
```

--------------------------------

### Create New TextEditor Instance

Source: https://mikefreno.github.io/FlexLove/api.html

Initializes a new TextEditor instance with configuration and dependencies. Ensure all required dependencies are provided.

```typescript
function TextEditor.new(config: TextEditorConfig, deps: table)
  -> TextEditor: table
```

--------------------------------

### getCursorPosition

Source: https://mikefreno.github.io/FlexLove/api.html

Gets the current cursor position within the element's text buffer.

```APIDOC
## getCursorPosition

### Description
Get cursor position.

### Method
Element:getCursorPosition()

### Returns
- **position** (number) - Character index (0-based) of the cursor.
```

--------------------------------

### Theme.new

Source: https://mikefreno.github.io/FlexLove/api.html

Creates a new theme instance from a provided definition object.

```APIDOC
## new

### Description
Creates a new theme instance.

### Parameters
* `definition` (any) - Required - The theme definition object

### Returns
* `Theme` - The newly created Theme object
```

--------------------------------

### Get State Statistics

Source: https://mikefreno.github.io/FlexLove/api.html

Retrieves statistics about the current state management, useful for debugging purposes.

```typescript
function FlexLove.getStateStats()
  -> table
```

--------------------------------

### FlexLove.new

Source: https://mikefreno.github.io/FlexLove/api.html

Creates a new UI element with the specified properties.

```APIDOC
## FlexLove.new

### Description
Create a new UI element.

### Method
function FlexLove.new(props: ElementProps)
  -> Element

### Parameters
#### Path Parameters
- **props** (ElementProps) - Required - Properties for the new element.

### Response
#### Success Response (200)
- **Element** - The newly created UI element.
```

--------------------------------

### Element.new

Source: https://mikefreno.github.io/FlexLove/api.html

Creates a new Element with specified properties and dependencies.

```APIDOC
## new
```
function Element.new(props: ElementProps, deps: table)
  -> Element
```
@_param_ `deps` — Required dependency table (provided by FlexLove)
```

--------------------------------

### Get Font for Text Rendering

Source: https://mikefreno.github.io/FlexLove/api.html

Retrieves the font object used for rendering text within the editor.

```typescript
(method) TextEditor:_getFont()
  -> (love.Font)?

```

--------------------------------

### transition

Source: https://mikefreno.github.io/FlexLove/api.html

Configures transition settings for animations.

```APIDOC
## transition
```
TransitionProps
```

Transition settings for animations
```

--------------------------------

### transition

Source: https://mikefreno.github.io/FlexLove/api.html

Configures transition settings for animations.

```APIDOC
## transition
```
TransitionProps?
```

Transition settings for animations
```

--------------------------------

### Get Color RGBA Components

Source: https://mikefreno.github.io/FlexLove/api.html

Returns the Red, Green, Blue, and Alpha components of a Color object.

```lua
(method) Color:toRGBA()
  -> r: number
  2. g: number
  3. b: number
  4. a: number
```

--------------------------------

### Show Element

Source: https://mikefreno.github.io/FlexLove/api.html

Makes the element visible, equivalent to setting its opacity to 1.

```lua
(method) Element:show()

```

--------------------------------

### Get Animation Interpolation Data

Source: https://mikefreno.github.io/FlexLove/api.html

Retrieves interpolation data for an animation. This method is typically for internal use.

```lua
(method) Animation:interpolate()
  -> table
```

--------------------------------

### TextEditor:initialize

Source: https://mikefreno.github.io/FlexLove/api.html

Initializes the TextEditor with a reference to its parent element.

```APIDOC
## TextEditor:initialize

### Description
Initialize TextEditor with parent element reference.

### Method
`TextEditor:initialize(element: table)`

### Parameters
* `element` (table) - The parent Element instance.
```

--------------------------------

### Input Event Delta X Property

Source: https://mikefreno.github.io/FlexLove/api.html

The change in the X-coordinate since the drag started. Only applicable for drag events.

```lua
number?
```

--------------------------------

### Load Theme from File

Source: https://mikefreno.github.io/FlexLove/api.html

Loads a theme definition from a specified Lua file path. This can be a theme name or a direct path.

```lua
function Theme.load(path: string)
  -> Theme

```

--------------------------------

### TextEditor.new

Source: https://mikefreno.github.io/FlexLove/api.html

Creates a new instance of the TextEditor.

```APIDOC
## new

### Description
Create a new TextEditor instance.

### Method
TextEditor.new(config: TextEditorConfig, deps: table)

### Parameters
#### Path Parameters
- **deps** (table) - Dependencies {Context, StateManager, Color, utils}

### Returns
- **TextEditor** - instance
```

--------------------------------

### Text Editor Get Cursor Position Method

Source: https://mikefreno.github.io/FlexLove/api.html

Retrieves the current cursor's character index (0-based).

```lua
(method) TextEditor:getCursorPosition()
  -> number
```

--------------------------------

### Handle Touch Events with FlexLove

Source: https://mikefreno.github.io/FlexLove/examples.html

This snippet shows how to implement touch event handling for mobile support. It tracks touch position and state changes.

```lua
local touchState = {
  touchPos = { x = 0, y = 0 },
  isTouching = false
}

-- Touchable area
local touchArea = FlexLove.new({
  width = "100%",
  height = "100%",
  backgroundColor = "#4a5568",
  borderRadius = 8,
  onEvent = function(_, event) 
    if event.type == "touch" then
      touchState.isTouching = true
      touchState.touchPos.x = event.x
      touchState.touchPos.y = event.y
      print("Touch started at:", event.x, event.y)
    elseif event.type == "touchmoved" then
      touchState.touchPos.x = event.x
      touchState.touchPos.y = event.y
    elseif event.type == "touchreleased" then
      touchState.isTouching = false
      print("Touch ended")
    end
  end
})
Copy
```

--------------------------------

### Get Scrollbar at Position

Source: https://mikefreno.github.io/FlexLove/api.html

Internal method to determine which scrollbar, if any, is located at the given mouse coordinates. It delegates to the ScrollManager.

```typescript
(method) Element:_getScrollbarAtPosition(mouseX: number, mouseY: number)
  -> table|nil
```

--------------------------------

### Create Schedule-Style Grid Layout

Source: https://mikefreno.github.io/FlexLove/examples.html

Build a schedule-like grid by defining rows and columns, then populating cells with headers and data. Includes interactive data cells.

```lua
local Color = FlexLove.Color
local Theme = FlexLove.Theme

-- Example data
local columnHeaders = { "Mon", "Tue", "Wed" }
local rowHeaders = { "Task A", "Task B", "Task C" }

-- Calculate grid dimensions: +1 for header row and column
local numRows = #rowHeaders + 1
local numColumns = #columnHeaders + 1

local scheduleGrid = FlexLove.new({
  parent = window,
  positioning = "grid",
  gridRows = numRows,
  gridColumns = numColumns,
  columnGap = 2,
  rowGap = 2,
  height = "80%",
  alignItems = "stretch"
})

local accentColor = Theme.getColor("primary")
local textColor = Theme.getColor("text")

-- Top-left corner cell (empty)
FlexLove.new({ parent = scheduleGrid })

-- Column headers
for _, header in ipairs(columnHeaders) do
  FlexLove.new({
    parent = scheduleGrid,
    text = header,
    textColor = textColor,
    textAlign = "center",
    backgroundColor = Color.new(0, 0, 0, 0.3),
    border = { top = true, right = true, bottom = true, left = true },
    borderColor = accentColor,
    textSize = 12
  })
end

-- Data rows
for i, rowHeader in ipairs(rowHeaders) do
  -- Row header
  FlexLove.new({
    parent = scheduleGrid,
    text = rowHeader,
    backgroundColor = Color.new(0, 0, 0, 0.3),
    textColor = textColor,
    textAlign = "center",
    border = { top = true, right = true, bottom = true, left = true },
    borderColor = accentColor,
    textSize = 10
  })

  -- Data cells
  for j = 1, #columnHeaders do
    FlexLove.new({
      parent = scheduleGrid,
      text = tostring((i * j) % 5),
      textAlign = "center",
      border = { top = true, right = true, bottom = true, left = true },
      borderColor = Color.new(0.5, 0.5, 0.5, 1.0),
      textSize = 12,
      themeComponent = "buttonv2",
      onEvent = function(elem, event) 
        if event.type == "click" then
          local newValue = (tonumber(elem.text) + 1) % 10
          elem:updateText(tostring(newValue))
        end
      end
    })
  end
end
```

--------------------------------

### theme

Source: https://mikefreno.github.io/FlexLove/api.html

Specifies the theme name to be used for styling (e.g., 'space', 'metal'). Defaults to the theme set by flexlove.init().

```APIDOC
## theme
```
string?
```

Theme name to use (e.g., “space”, “metal”). Defaults to theme from flexlove.init()
```

--------------------------------

### Set Text Selection Range

Source: https://mikefreno.github.io/FlexLove/api.html

Defines the selected text range by specifying the start and end positions. Both positions are inclusive.

```typescript
(method) TextEditor:setSelection(startPos: number, endPos: number)
```

--------------------------------

### Switch Theme with Button

Source: https://mikefreno.github.io/FlexLove/examples.html

Creates a button that cycles through predefined themes when clicked. Ensure themes are defined in the 'themes' table.

```lua
local themes = { "space", "metal" }
local themeIndex = 1

-- Create theme toggle button
FlexLove.new({
  themeComponent = "buttonv2",
  text = "Switch Theme",
  onEvent = function(_, event)
    if event.type == "release" then
      themeIndex = (themeIndex % #themes) + 1
      FlexLove.setTheme(themes[themeIndex])
      print("Switched to:", themes[themeIndex])
    end
  end
})Copy
```

--------------------------------

### Theme.load

Source: https://mikefreno.github.io/FlexLove/api.html

Loads a theme from a specified Lua file path.

```APIDOC
## load

### Description
Load a theme from a Lua file.

### Parameters
* `path` (string) - Required - Path to theme definition file (e.g., “space” or “mytheme”)

### Returns
* `Theme` - The loaded Theme object
```

--------------------------------

### Text Editor Delete Text Method

Source: https://mikefreno.github.io/FlexLove/api.html

Deletes text within a specified range (inclusive start and end positions).

```lua
(method) TextEditor:deleteText(startPos: number, endPos: number)
```

--------------------------------

### Color.new

Source: https://mikefreno.github.io/FlexLove/api.html

Creates a new Color instance.

```APIDOC
## Color.new

### Description
Creates a new color instance with the specified RGBA components.

### Method
`Color.new(r?: number, g?: number, b?: number, a?: number) -> Color`

### Parameters
* **r** (number, optional) - Red component (0-1).
* **g** (number, optional) - Green component (0-1).
* **b** (number, optional) - Blue component (0-1).
* **a** (number, optional) - Alpha component (0-1).

### Returns
A `Color` object.
```

--------------------------------

### Get Element at Position

Source: https://mikefreno.github.io/FlexLove/api.html

Finds the topmost element at the given X and Y coordinates. Returns the element or nil if none is found.

```typescript
function FlexLove.getElementAtPosition(x: number, y: number)
  -> Element?
```

--------------------------------

### Create True Grid Layout

Source: https://mikefreno.github.io/FlexLove/examples.html

Utilize positioning = "grid" with gridRows and gridColumns to establish a grid container. Children will automatically fill the cells.

```lua
-- Create a true grid with positioning = "grid"
local gridContainer = FlexLove.new({
  parent = window,
  positioning = "grid",
  gridRows = 3,
  gridColumns = 3,
  columnGap = 5,
  rowGap = 5,
  height = "80%",
  alignItems = "stretch"
})

-- Add grid items (auto-flow into cells)
for i = 1, 9 do
  FlexLove.new({
    parent = gridContainer,
    themeComponent = "buttonv2",
    text = "Cell " .. i,
    textAlign = "center",
    textSize = "md",
    onEvent = function(_, event) 
      if event.type == "release" then
        print("Grid cell " .. i .. " clicked")
      end
    end
  })
end
```

--------------------------------

### scaleCorners

Source: https://mikefreno.github.io/FlexLove/api.html

A scale multiplier for 9-patch corners and edges. For example, 2 means 2x size. Overrides theme settings.

```APIDOC
## scaleCorners
```
number?
```

Scale multiplier for 9-patch corners. E.g., 2 = 2x size (overrides theme setting)
```

--------------------------------

### Replace Text in a Specified Range

Source: https://mikefreno.github.io/FlexLove/api.html

Replaces a segment of text within the editor's buffer. The start and end positions are inclusive.

```typescript
(method) TextEditor:replaceText(startPos: number, endPos: number, newText: string)
```

--------------------------------

### Create a New Color Instance

Source: https://mikefreno.github.io/FlexLove/api.html

Creates a new Color object. Accepts optional RGBA values, defaulting to transparent black if not provided.

```lua
function Color.new(r?: number, g?: number, b?: number, a?: number)
  -> Color
```

--------------------------------

### EventHandler: new

Source: https://mikefreno.github.io/FlexLove/api.html

Creates a new instance of EventHandler with the provided configuration and dependencies.

```APIDOC
## new
```
function EventHandler.new(config: table, deps: table)
  -> EventHandler
```

Create a new EventHandler instance
@_param_ `config` — Configuration options
@_param_ `deps` — Dependencies {InputEvent, Context, utils}
```

--------------------------------

### Limit Layout Recalculations in FlexLove

Source: https://mikefreno.github.io/FlexLove/examples.html

Shows how to optimize layout by avoiding changes to element properties every frame. Update layout properties only when necessary.

```lua
-- Avoid changing layout properties every frame
local element = FlexLove.new({ ... })

-- ❌ Bad: Causes relayout every frame
function love.update(dt)
  element.width = math.sin(love.timer.getTime()) * 100
end

-- ✅ Good: Update only when needed
function love.update(dt)
  if someCondition then
    element.width = newWidth
  end
endCopy
```

--------------------------------

### Replace Text in Range

Source: https://mikefreno.github.io/FlexLove/api.html

Replaces a portion of the element's text with new text. Requires start and end positions (inclusive) and the replacement text.

```lua
(method) Element:replaceText(startPos: number, endPos: number, newText: string)

```

--------------------------------

### Select All Text

Source: https://mikefreno.github.io/FlexLove/api.html

Selects all the text content within the element.

```lua
(method) Element:selectAll()

```

--------------------------------

### Get Cursor Screen Position for Rendering

Source: https://mikefreno.github.io/FlexLove/api.html

Calculates the screen coordinates for rendering the cursor, accounting for multiline text. Returns X and Y positions relative to the content area.

```typescript
(method) TextEditor:_getCursorScreenPosition()
  -> number
  2. number
```

--------------------------------

### Set Active Theme

Source: https://mikefreno.github.io/FlexLove/api.html

Activates a theme, either by its name or by providing a Theme object directly.

```lua
function Theme.setActive(themeOrName: string|Theme)

```

--------------------------------

### Use Element Pooling for Dynamic Content in FlexLove

Source: https://mikefreno.github.io/FlexLove/examples.html

Demonstrates element pooling for dynamic content, where a set of elements is created once and reused to improve performance when displaying lists or frequently changing content.

```lua
-- Create a pool of reusable elements
local itemPool = {}
for i = 1, 50 do
  itemPool[i] = FlexLove.new({
    parent = scrollContainer,
    visible = false,
    text = "",
    width = "100%",
    themeComponent = "cardv2"
  })
end

-- Reuse elements instead of creating new ones
function updateList(items)
  for i, item in ipairs(items) do
    if itemPool[i] then
      itemPool[i].text = item.name
      itemPool[i].visible = true
    end
  end

  -- Hide unused elements
  for i = #items + 1, #itemPool do
    itemPool[i].visible = false
  end
endCopy
```

--------------------------------

### Animation.new

Source: https://mikefreno.github.io/FlexLove/api.html

Creates a new animation instance.

```APIDOC
## Animation.new

### Description
Creates a new animation instance with the specified properties.

### Method
`Animation.new(props: AnimationProps) -> Animation`

### Parameters
* **props** (AnimationProps) - An object containing animation properties such as duration, start, and final states.
```

--------------------------------

### Create Themed Button Component

Source: https://mikefreno.github.io/FlexLove/examples.html

Instantiate UI elements using themeComponent, such as "buttonv2", to automatically apply styling and state handling. Event handlers can be attached.

```lua
-- Create a themed button (automatic state handling)
local button = FlexLove.new({
  themeComponent = "buttonv2",
  text = "Themed Button",
  width = "20vw",
  height = "10vh",
  textAlign = "center",
  onEvent = function(elem, event) 
    if event.type == "release" then
      print("Button clicked!")
    end
  end
})

-- Available theme components:
-- "buttonv1", "buttonv2", "buttonv3"
-- "framev1", "framev2", "framev3"
-- "inputv1", "inputv2"
-- "cardv1", "cardv2"
-- "panel"
```

--------------------------------

### Create a New Animation Instance

Source: https://mikefreno.github.io/FlexLove/api.html

Initializes a new Animation object. Requires an AnimationProps object to define animation properties.

```lua
function Animation.new(props: AnimationProps)
  -> Animation
```

--------------------------------

### List of Available Event Types in FlexLove

Source: https://mikefreno.github.io/FlexLove/examples.html

This is a reference list of all event types supported by FlexLove, categorized by input method (mouse, keyboard, touch) and focus.

```text
-- Mouse events
"press"         -- Mouse button pressed
"release"       -- Mouse button released
"drag"          -- Mouse moved while pressed
"mousemoved"    -- Mouse position changed
"mouseenter"    -- Mouse entered element bounds
"mouseleave"    -- Mouse left element bounds
"wheel"         -- Mouse wheel scrolled

-- Keyboard events
"keypressed"    -- Key pressed (includes key name)
"keyreleased"   -- Key released
"textinput"     -- Text character entered

-- Touch events (mobile)
"touch"         -- Touch started
"touchmoved"    -- Touch position changed
"touchreleased" -- Touch ended

-- Focus events
"focus"         -- Element gained focus
"blur"          -- Element lost focusCopy
```

--------------------------------

### units

Source: https://mikefreno.github.io/FlexLove/api.html

Provides original unit specifications for responsive behavior.

```APIDOC
## units
```
table
```

Original unit specifications for responsive behavior
```

--------------------------------

### Handle Keyboard Input and Text Fields

Source: https://mikefreno.github.io/FlexLove/examples.html

Creates an input field that captures text input, handles backspace and return keys for text manipulation and submission, and allows blurring to remove focus. Uses `inputv2` theme component.

```lua
local keyState = {
  lastKey = "",
  textInput = ""
}

-- Input field with keyboard handling
local inputField = FlexLove.new({
  themeComponent = "inputv2",
  text = keyState.textInput,
  width = "50%",
  onEvent = function(elem, event)
    if event.type == "textinput" then
      keyState.textInput = keyState.textInput .. event.text
      keyState.lastKey = event.text
      elem.text = keyState.textInput
    elseif event.type == "keypressed" then
      keyState.lastKey = event.key

      if event.key == "backspace" then
        keyState.textInput = keyState.textInput:sub(1, -2)
        elem.text = keyState.textInput
      elseif event.key == "return" then
        print("Submitted:", keyState.textInput)
        keyState.textInput = ""
        elem.text = ""
      elseif event.key == "escape" then
        elem:blur()  -- Remove focus
      end
    end
  end
})
```

--------------------------------

### Handle Mouse Events with Hover and Click

Source: https://mikefreno.github.io/FlexLove/examples.html

Sets up an area to track mouse position, detect enter/leave events for hover effects, and log click coordinates. Changes background color on hover.

```lua
local inputState = {
  mousePos = { x = 0, y = 0 },
  isHovered = false,
  hoverCount = 0
}

-- Create hoverable area
local hoverArea = FlexLove.new({
  width = "30%",
  height = "100%",
  backgroundColor = "#4a5568",
  borderRadius = 8,
  onEvent = function(elem, event)
    if event.type == "mousemoved" then
      inputState.mousePos.x = event.x
      inputState.mousePos.y = event.y
    elseif event.type == "mouseenter" then
      inputState.isHovered = true
      inputState.hoverCount = inputState.hoverCount + 1
      elem.backgroundColor = "#48bb78"  -- Green on hover
    elseif event.type == "mouseleave" then
      inputState.isHovered = false
      elem.backgroundColor = "#4a5568"  -- Back to gray
    elseif event.type == "release" then
      print("Clicked at:", event.x, event.y)
    end
  end
})

-- Display mouse position
FlexLove.new({
  text = "Mouse: (" .. inputState.mousePos.x .. ", " .. inputState.mousePos.y .. ")",
  textAlign = "left"
})
```

--------------------------------

### Image Fit Modes

Source: https://mikefreno.github.io/FlexLove/api.html

Defines how an image should be resized to fit its container. Defaults to 'fill'.

```string
("contain"|"cover"|"fill"|"none"|"scale-down")?

```

--------------------------------

### EventHandler: initialize

Source: https://mikefreno.github.io/FlexLove/api.html

Initializes the EventHandler with a reference to its parent element.

```APIDOC
## initialize
```
(method) EventHandler:initialize(element: Element)
```

Initialize EventHandler with parent element reference
@_param_ `element` — The parent element
```

--------------------------------

### placeholder

Source: https://mikefreno.github.io/FlexLove/api.html

Sets the placeholder text to display when the element is empty. Defaults to nil.

```APIDOC
## placeholder
```
string?
```

Placeholder text when empty (default: nil)
```

--------------------------------

### Selection Color

Source: https://mikefreno.github.io/FlexLove/api.html

Sets the background color for selected text. Defaults to nil, using theme or default colors.

```Color
Color?

```

--------------------------------

### minTextSize

Source: https://mikefreno.github.io/FlexLove/api.html

Sets the minimum text size in pixels for auto-scaling.

```APIDOC
## minTextSize
```
number?
```

Minimum text size in pixels for auto-scaling
```

--------------------------------

### 9-Patch Scaling Algorithm

Source: https://mikefreno.github.io/FlexLove/api.html

Specifies the algorithm for scaling 9-patch corners: 'nearest' for sharp or 'bilinear' for smooth. Overrides theme settings. Optional.

```string
("bilinear"|"nearest")?

```

--------------------------------

### focus

Source: https://mikefreno.github.io/FlexLove/api.html

Sets the keyboard focus to the current element, making it ready to receive input.

```APIDOC
## focus

### Description
Focus this element for keyboard input.

### Method
Element:focus()
```

--------------------------------

### Theme Definition Components

Source: https://mikefreno.github.io/FlexLove/api.html

Maps component names to their respective ThemeComponent definitions.

```lua
table<string, ThemeComponent>

```

--------------------------------

### themeComponent

Source: https://mikefreno.github.io/FlexLove/api.html

Specifies a theme component to apply (e.g., 'panel', 'button', 'input'). If nil, no specific theme component is applied.

```APIDOC
## themeComponent
```
string?
```

Theme component to use (e.g., “panel”, “button”, “input”). If nil, no theme is applied
```

--------------------------------

### FlexLove.getStateStats

Source: https://mikefreno.github.io/FlexLove/api.html

Retrieves statistics about the current state, useful for debugging.

```APIDOC
## FlexLove.getStateStats

### Description
Get state statistics (for debugging).

### Method
function FlexLove.getStateStats()
  -> table

### Response
#### Success Response (200)
- **stats** (table) - A table containing state statistics.
```

--------------------------------

### Text Editor Handle Text Input Method

Source: https://mikefreno.github.io/FlexLove/api.html

Processes character input, inserting the provided text into the editor.

```lua
(method) TextEditor:handleTextInput(text: string)
```

--------------------------------

### Text Editor Focus Method

Source: https://mikefreno.github.io/FlexLove/api.html

Sets the focus to this text editor element, enabling keyboard input.

```lua
(method) TextEditor:focus()
```

--------------------------------

### theme

Source: https://mikefreno.github.io/FlexLove/api.html

Specifies the theme component to use for rendering.

```APIDOC
## theme
```
string?
```

Theme component to use for rendering
```

--------------------------------

### TextEditor:selectAll

Source: https://mikefreno.github.io/FlexLove/api.html

Selects all the text currently in the editor.

```APIDOC
## selectAll

### Description
Select all text.

### Method
TextEditor:selectAll()
```

--------------------------------

### Theme.get

Source: https://mikefreno.github.io/FlexLove/api.html

Retrieves a specific theme by its name. Returns nil if the theme is not found.

```APIDOC
## get

function Theme.get(themeName: string)
  -> Theme|nil

Get a theme by name
@_param_ `themeName` — Name of the theme
@_return_ — Returns theme or nil if not found
```

--------------------------------

### Create New Element

Source: https://mikefreno.github.io/FlexLove/api.html

Creates a new element with the specified properties. Returns the created element.

```typescript
function FlexLove.new(props: ElementProps)
  -> Element
```

--------------------------------

### FlexLove.resize

Source: https://mikefreno.github.io/FlexLove/api.html

Resizes the FlexLove UI. This should be called when the window or container size changes.

```APIDOC
## FlexLove.resize

### Description
Resize the FlexLove UI.

### Method
function FlexLove.resize()

### Endpoint
N/A (Function call)
```

--------------------------------

### Input Event New Function

Source: https://mikefreno.github.io/FlexLove/api.html

Creates a new InputEvent instance with the specified properties.

```lua
function InputEvent.new(props: InputEventProps)
  -> InputEvent
```

--------------------------------

### scalingAlgorithm

Source: https://mikefreno.github.io/FlexLove/api.html

Specifies the scaling algorithm for 9-patch corners: 'nearest' (sharp/pixelated) or 'bilinear' (smooth). Overrides theme settings.

```APIDOC
## scalingAlgorithm
```
("bilinear"|"nearest")?
```

Scaling algorithm for 9-patch corners: “nearest” (sharp/pixelated) or “bilinear” (smooth) (overrides theme setting)
```

--------------------------------

### Theme.getRegisteredThemes

Source: https://mikefreno.github.io/FlexLove/api.html

Returns a list of all theme names that have been registered with the system.

```APIDOC
## getRegisteredThemes

### Description
Get all registered theme names.

### Returns
* `table<string>` - Array of theme names
```

--------------------------------

### objectFit

Source: https://mikefreno.github.io/FlexLove/api.html

Determines how the image should be resized to fit its container. Options include 'contain', 'cover', 'fill', 'none', 'scale-down'. Defaults to 'fill'.

```APIDOC
## objectFit
```
("contain"|"cover"|"fill"|"none"|"scale-down")?
```

Image fit mode (default: “fill”)
```

--------------------------------

### Animation.scale

Source: https://mikefreno.github.io/FlexLove/api.html

Creates a simple scale animation.

```APIDOC
## Animation.scale

### Description
Creates a simple scale animation.

### Method
`Animation.scale(duration: number, fromScale: table, toScale: table) -> Animation`

### Parameters
* **duration** (number) - The duration of the scale animation.
* **fromScale** (table) - An object with `width` and `height` properties representing the starting scale.
* **toScale** (table) - An object with `width` and `height` properties representing the ending scale.

### Returns
An `Animation` object representing the scale animation.
```

--------------------------------

### Text Editor Has Selection Method

Source: https://mikefreno.github.io/FlexLove/api.html

Checks if there is any text currently selected in the editor.

```lua
(method) TextEditor:hasSelection()
  -> boolean
```

--------------------------------

### FlexLove.keypressed

Source: https://mikefreno.github.io/FlexLove/api.html

Handles a key press event. This function should be called when a key is pressed.

```APIDOC
## FlexLove.keypressed

### Description
Handle a key press event.

### Method
function FlexLove.keypressed(key: string, scancode: string, isrepeat: boolean)

### Parameters
#### Path Parameters
- **key** (string) - Required - The key that was pressed.
- **scancode** (string) - Required - The scancode of the key.
- **isrepeat** (boolean) - Required - Whether the key press is a repeat.
```

--------------------------------

### FlexLove.textinput

Source: https://mikefreno.github.io/FlexLove/api.html

Handles text input events. This function should be called when text is entered.

```APIDOC
## FlexLove.textinput

### Description
Handle text input events.

### Method
function FlexLove.textinput(text: string)

### Parameters
#### Path Parameters
- **text** (string) - Required - The text that was input.
```

--------------------------------

### Theme.getComponent

Source: https://mikefreno.github.io/FlexLove/api.html

Retrieves a specific component from the currently active theme. Supports optional state filtering.

```APIDOC
## getComponent

### Description
Get a component from the active theme.

### Parameters
* `componentName` (string) - Required - Name of the component (e.g., “button”, “panel”)
* `state` (string) - Optional - Optional state (e.g., “hover”, “pressed”, “disabled”)

### Returns
* `ThemeComponent?` - Returns component or nil if not found
```

--------------------------------

### getScaledContentPadding

Source: https://mikefreno.github.io/FlexLove/api.html

Retrieves the scaled content padding for the current theme state.

```APIDOC
## getScaledContentPadding

### Description
Get the current state’s scaled content padding. Returns the contentPadding for the current theme state, scaled to the element’s size.

### Method
Element:getScaledContentPadding()

### Returns
- **padding** (table|nil) - An object with `left`, `top`, `right`, `bottom` properties, or nil if no content padding is set.
```

--------------------------------

### Animation.fade

Source: https://mikefreno.github.io/FlexLove/api.html

Creates a simple fade animation.

```APIDOC
## Animation.fade

### Description
Creates a simple fade animation.

### Method
`Animation.fade(duration: number, fromOpacity: number, toOpacity: number) -> Animation`

### Parameters
* **duration** (number) - The duration of the fade animation.
* **fromOpacity** (number) - The starting opacity value.
* **toOpacity** (number) - The ending opacity value.

### Returns
An `Animation` object representing the fade animation.
```

--------------------------------

### positioning

Source: https://mikefreno.github.io/FlexLove/api.html

Sets the layout positioning mode. Options include 'absolute', 'relative', 'flex', 'grid'. Defaults to RELATIVE.

```APIDOC
## positioning
```
Positioning?
```

Layout positioning mode: “absolute”|“relative”|“flex”|“grid” (default: RELATIVE)
```

--------------------------------

### Font Family Path

Source: https://mikefreno.github.io/FlexLove/api.html

Specifies the path to the font file, which can be relative to FlexLove or an absolute path.

```lua
string
```

--------------------------------

### Theme Component Content Sizing

Source: https://mikefreno.github.io/FlexLove/api.html

Defines an optional multiplier to adjust auto-sized content dimensions for a component.

```lua
{ width: number?, height: number? }?

```

--------------------------------

### opacity

Source: https://mikefreno.github.io/FlexLove/api.html

Sets the opacity of the element, ranging from 0 to 1. Defaults to 1.

```APIDOC
## opacity
```
number?
```

Element opacity 0-1 (default: 1)
```

--------------------------------

### text

Source: https://mikefreno.github.io/FlexLove/api.html

Specifies the text content to be displayed. Defaults to nil.

```APIDOC
## text
```
string?
```

Text content to display (default: nil)
```

--------------------------------

### Select All Text in Editor

Source: https://mikefreno.github.io/FlexLove/api.html

Selects the entire content of the text editor.

```typescript
(method) TextEditor:selectAll()
```

--------------------------------

### Theme Name Property

Source: https://mikefreno.github.io/FlexLove/api.html

Represents the name of the theme.

```lua
string

```

--------------------------------

### FlexLove.clearAllStates

Source: https://mikefreno.github.io/FlexLove/api.html

Clears all states managed by FlexLove. This is useful for resetting the UI state.

```APIDOC
## FlexLove.clearAllStates

### Description
Clear all immediate mode states.

### Method
function FlexLove.clearAllStates()

### Endpoint
N/A (Function call)
```

--------------------------------

### Previous Game Size

Source: https://mikefreno.github.io/FlexLove/api.html

Stores the dimensions of the game window from the previous frame, used for resize calculations.

```table
{ width: number, height: number }

```

--------------------------------

### width

Source: https://mikefreno.github.io/FlexLove/api.html

Sets the width of the element.

```APIDOC
## width
```
string|number
```

Width of the element
```

--------------------------------

### textSize

Source: https://mikefreno.github.io/FlexLove/api.html

Sets the font size of the text. Can be a number (pixels), a string with units (e.g., '2vh', '10%'), or a preset size ('xxs' to '4xl'). Defaults to 'md' or 12px.

```APIDOC
## textSize
```
(string|number)?
```

Font size: number (px), string with units (“2vh”, “10%”), or preset (“xxs”|“xs”|“sm”|“md”|“lg”|“xl”|“xxl”|“3xl”|“4xl”) (default: “md” or 12px)
```

--------------------------------

### TextEditor:focus

Source: https://mikefreno.github.io/FlexLove/api.html

Gives focus to the TextEditor element, allowing it to receive keyboard input.

```APIDOC
## TextEditor:focus

### Description
Focus this element for keyboard input.

### Method
`TextEditor:focus()`
```

--------------------------------

### TextEditor:_calculateWrapping

Source: https://mikefreno.github.io/FlexLove/api.html

Internal method to calculate text wrapping. Should not be called directly by users.

```APIDOC
## _calculateWrapping

### Description
Calculate text wrapping.

### Method
TextEditor:_calculateWrapping()
```

--------------------------------

### Move Cursor to Previous Word

Source: https://mikefreno.github.io/FlexLove/api.html

Moves the cursor to the beginning of the previous word.

```typescript
(method) TextEditor:moveCursorToPreviousWord()
```

--------------------------------

### Move Cursor to Next Word

Source: https://mikefreno.github.io/FlexLove/api.html

Moves the cursor to the beginning of the next word.

```typescript
(method) TextEditor:moveCursorToNextWord()
```

--------------------------------

### onFocus

Source: https://mikefreno.github.io/FlexLove/api.html

Callback function executed when the element receives focus.

```APIDOC
## onFocus
```
fun(element: Element, event: InputEvent)?
```

Callback when element receives focus
```

--------------------------------

### moveCursorToNextWord

Source: https://mikefreno.github.io/FlexLove/api.html

Moves the cursor to the beginning of the next word.

```APIDOC
## moveCursorToNextWord

### Description
Move cursor to start of next word.

### Method
Element:moveCursorToNextWord()
```

--------------------------------

### Counter with State Management

Source: https://mikefreno.github.io/FlexLove/examples.html

Implements a counter that updates its display when an increment button is pressed. State is managed in a local table.

```lua
local state = {
  counter = 0,
  isToggled = false,
  inputValue = ""
}

-- Create counter display
local counterSection = FlexLove.new({
  positioning = "flex",
  flexDirection = "horizontal",
  justifyContent = "space-between",
  alignItems = "center",
  gap = 10
})

local counterText = FlexLove.new({
  parent = counterSection,
  text = "Counter: " .. state.counter,
  textSize = "lg"
})

-- Increment button
FlexLove.new({
  parent = counterSection,
  themeComponent = "buttonv2",
  text = "Increment",
  width = "25%",
  onEvent = function(_, event)
    if event.type == "release" then
      state.counter = state.counter + 1
      counterText.text = "Counter: " .. state.counter
      print("Counter incremented to:", state.counter)
    end
  end
})Copy
```

--------------------------------

### Text Editor Handle Key Press Method

Source: https://mikefreno.github.io/FlexLove/api.html

Processes a key press event, including special keys. Handles key, scancode, and repeat status.

```lua
(method) TextEditor:handleKeyPress(key: string, scancode: string, isrepeat: boolean)
```
Tokens:
Raw