PixelUI

https://pixelui.madefor.cc/
Admin
PixelUI is a modern UI framework for ComputerCraft that enables developers to build responsive user...
Tokens:30,293
Snippets:501
Trust Score:5.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initialize and Run a PixelUI Application

Source: https://pixelui.madefor.cc/

Basic setup for creating an app instance, adding a button widget to the root frame, and starting the application loop.

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

-- Create an app instance
local app = pixelui.create()

-- Add widgets to the root frame
local root = app:getRoot()

-- Create a button
local button = app:createButton({
  x = 5,
  y = 5,
  width = 20,
  height = 3,
  label = "Click Me!",
  onClick = function()
    print("Button clicked!")
  end
})
-- Add the button to the main frame
root:addChild(button)

-- Run the app
app:run()
```

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

### Install PixelUI v2

Source: https://pixelui.madefor.cc/guides/getting-started.html

Use the wget command to download and run the installer script on a ComputerCraft computer.

```lua
-- Download the installer using wget
wget run https://raw.githubusercontent.com/Shlomo1412/PixelUI-v2/main/installer.lua
```

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

### run

Source: https://pixelui.madefor.cc/api/app.html

Starts the UI loop.

```APIDOC
## run

### Description
Starts the main UI execution loop.
```

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

### Basic Table Implementation

Source: https://pixelui.madefor.cc/api/table.html

A minimal example demonstrating how to define columns and populate a table with data.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple data table
local table = app:table({
    x = 2, y = 2,
    width = 40, height = 10,
    columns = {
        { id = "name", title = "Name", key = "name" },
        { id = "age", title = "Age", key = "age" }
    },
    data = {
        { name = "Alice", age = 25 },
        { name = "Bob", age = 30 },
        { name = "Charlie", age = 35 }
    }
})
app.root:addChild(table)

app:run()
```

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

### Complete task management example

Source: https://pixelui.madefor.cc/guides/threading.html

A full implementation demonstrating UI interaction, progress reporting, and cancellation handling.

```lua
local pixelui = require("pixelui")
local app = pixelui.create()
local root = app:getRoot()

-- Create UI elements
local progressBar = app:createProgressBar({
  x = 2,
  y = 5,
  width = root.width - 3,
  height = 3,
  label = "Processing...",
  showPercent = true
})
root:addChild(progressBar)

local statusLabel = app:createLabel({
  x = 2,
  y = 9,
  width = root.width - 3,
  height = 1,
  text = "Idle"
})
root:addChild(statusLabel)

local startBtn = app:createButton({
  x = 2,
  y = 11,
  width = 15,
  height = 3,
  label = "Start Task",
  bg = colors.green,
  fg = colors.white
})
root:addChild(startBtn)

local cancelBtn = app:createButton({
  x = 18,
  y = 11,
  width = 15,
  height = 3,
  label = "Cancel",
  bg = colors.red,
  fg = colors.white,
  disabled = true
})
root:addChild(cancelBtn)

local currentHandle = nil

startBtn.onClick = function()
  startBtn.disabled = true
  cancelBtn.disabled = false
  progressBar:setValue(0)
  
  currentHandle = app:spawnThread(function(ctx)
    for i = 1, 100 do
      ctx:setProgress(i / 100)
      ctx:setStatus("Processing item " .. i)
      ctx:sleep(0.1)
      ctx:checkCancelled()
    end
    return "Complete!"
  end, {
    name = "Processing Task",
    onMetadata = function(h, key, value)
      if key == "progress" then
        progressBar:setValue(value)
      elseif key == "status" then
        statusLabel:setText(value)
      end
    end,
    onStatus = function(h, status)
      if status == "completed" then
        statusLabel:setText("Task completed!")
        startBtn.disabled = false
        cancelBtn.disabled = true
      elseif status == "cancelled" then
        statusLabel:setText("Task cancelled")
        startBtn.disabled = false
        cancelBtn.disabled = true
      elseif status == "error" then
        statusLabel:setText("Error: " .. tostring(h:getError()))
        startBtn.disabled = false
        cancelBtn.disabled = true
      end
    end
  })
end

cancelBtn.onClick = function()
  if currentHandle then
    currentHandle:cancel()
  end
end

app:run()
```

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

### Move Cursor to Document Start

Source: https://pixelui.madefor.cc/api/textbox.html

Moves the cursor to the beginning of the document.

```lua
_moveCursorDocumentStart()
```

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

### Basic LoadingRing Implementation

Source: https://pixelui.madefor.cc/api/loadingring.html

A simple example demonstrating how to instantiate and display a basic loading ring.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple loading indicator
local loader = app:loadingring({
    x = 10, y = 5,
    width = 7, height = 3,
    color = colors.cyan,
    autoStart = true
})
app.root:addChild(loader)

app:run()
```

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

### Basic Textbox Implementation

Source: https://pixelui.madefor.cc/api/textbox.html

A simple example demonstrating how to initialize a basic text input field.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple text input
local textbox = app:textbox({
    x = 2, y = 2,
    width = 20, height = 1,
    placeholder = "Enter text...",
    onChange = function(self, text)
        -- Handle text changes
    end
})
app.root:addChild(textbox)

app:run()
```

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

### Basic Modal Dialog Example

Source: https://pixelui.madefor.cc/api/dialog.html

Demonstrates creating a simple modal dialog with a label and adding it to the application root.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple modal dialog
local dialog = app:dialog({
    x = 10, y = 5,
    width = 30, height = 10,
    title = "Confirm",
    modal = true
})

dialog:addChild(app:label({
    x = 2, y = 2,
    text = "Are you sure?"
}))

app.root:addChild(dialog)

app:run()
```

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

### Basic List Implementation

Source: https://pixelui.madefor.cc/api/list.html

A simple example demonstrating how to create and add a list widget to an application.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple list widget
local list = app:list({
    x = 2, y = 2,
    width = 20, height = 8,
    items = { "Apple", "Banana", "Cherry", "Date", "Elderberry" },
    onSelect = function(self, item, index)
        -- Handle selection
    end
})
app.root:addChild(list)

app:run()
```

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

### Basic Progress Bar Implementation

Source: https://pixelui.madefor.cc/api/progressbar.html

A simple example showing how to create and add a basic progress bar to the application root.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple progress bar
local progress = app:progressbar({
    x = 2, y = 2,
    width = 30, height = 1,
    value = 50,
    min = 0,
    max = 100,
    showPercent = true
})
app.root:addChild(progress)

app:run()
```

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

### Basic TabControl Usage

Source: https://pixelui.madefor.cc/api/tabcontrol.html

A simple example demonstrating how to create a TabControl and add tabs.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple tab control
local tabs = app:tabcontrol({
    x = 2, y = 2,
    width = 40, height = 12
})

tabs:addTab({ id = "home", label = "Home" })
tabs:addTab({ id = "settings", label = "Settings" })
tabs:addTab({ id = "about", label = "About" })

app.root:addChild(tabs)

app:run()
```

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

### Basic Slider Usage

Source: https://pixelui.madefor.cc/api/slider.html

Example of creating a simple single-value slider.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple value slider
local slider = app:slider({
    x = 2, y = 2,
    width = 25, height = 1,
    min = 0,
    max = 100,
    value = 50,
    showValue = true,
    onChange = function(self, value)
        -- Handle value change
    end
})
app.root:addChild(slider)

app:run()
```

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

### Basic Toggle Implementation

Source: https://pixelui.madefor.cc/api/toggle.html

A minimal example showing how to create a basic toggle switch and handle state changes.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple toggle switch
local toggle = app:toggle({
    x = 2, y = 2,
    width = 8, height = 1,
    value = false,
    onChange = function(self, value)
        -- value is true or false
    end
})
app.root:addChild(toggle)

app:run()
```

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

### Basic Checkbox Implementation

Source: https://pixelui.madefor.cc/api/checkbox.html

A simple example showing how to create and add a checkbox to an application.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple checkbox
local checkbox = app:checkbox({
    x = 2, y = 2,
    label = "Enable feature",
    checked = false,
    onChange = function(self, checked)
        -- Handle state change
    end
})
app.root:addChild(checkbox)

app:run()
```

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

### Basic RadioButton implementation

Source: https://pixelui.madefor.cc/api/radiobutton.html

Example showing how to create and group two radio buttons.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Radio button group
local radio1 = app:radiobutton({
    x = 2, y = 2,
    label = "Option A",
    value = "a",
    group = "options",
    selected = true
})

local radio2 = app:radiobutton({
    x = 2, y = 4,
    label = "Option B",
    value = "b",
    group = "options"
})

app.root:addChild(radio1)
app.root:addChild(radio2)

app:run()
```

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

### Basic TreeView Example

Source: https://pixelui.madefor.cc/api/treeview.html

A simple implementation of a tree view with basic node addition.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple tree view
local tree = app:treeview({
    x = 2, y = 2,
    width = 25, height = 10,
    onSelect = function(self, node, index)
        -- Handle node selection
    end
})

-- Add root nodes
tree:addNode({ label = "Documents" })
tree:addNode({ label = "Pictures" })
tree:addNode({ label = "Music" })

app.root:addChild(tree)

app:run()
```

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

### Advanced RadioButton implementation

Source: https://pixelui.madefor.cc/api/radiobutton.html

Example demonstrating dynamic radio button creation with styling and change handlers.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Radio buttons with change handler and styling
local selectionLabel = app:label({
    x = 2, y = 10,
    text = "Selected: Small",
    fg = colors.white
})

local sizes = {
    { label = "Small", value = "sm" },
    { label = "Medium", value = "md" },
    { label = "Large", value = "lg" },
    { label = "Extra Large", value = "xl" }
}

for i, size in ipairs(sizes) do
    local radio = app:radiobutton({
        x = 2, y = 1 + (i * 2),
        label = size.label,
        value = size.value,
        group = "size",
        selected = (i == 1),
        focusBg = colors.blue,
        focusFg = colors.white,
        onChange = function(self, selected, value)
            if selected then
                selectionLabel:setText("Selected: " .. self.label)
            end
        end
    })
    app.root:addChild(radio)
end

app.root:addChild(selectionLabel)

app:run()
```

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

### Advanced Textbox Implementation

Source: https://pixelui.madefor.cc/api/textbox.html

An example showing password masking, validation logic, and form submission handling.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Password input with validation
local passwordBox = app:textbox({
    x = 2, y = 2,
    width = 25, height = 1,
    placeholder = "Enter password",
    mask = "*",
    maxLength = 20,
    focusBg = colors.gray,
    focusFg = colors.white
})

local strengthLabel = app:label({
    x = 2, y = 4,
    text = "",
    fg = colors.lightGray
})

passwordBox.onChange = function(self, text)
    local len = #text
    if len == 0 then
        strengthLabel:setText("")
    elseif len < 6 then
        strengthLabel:setText("Weak")
        strengthLabel.fg = colors.red
    elseif len < 10 then
        strengthLabel:setText("Medium")
        strengthLabel.fg = colors.yellow
    else
        strengthLabel:setText("Strong")
        strengthLabel.fg = colors.green
    end
end

passwordBox.onSubmit = function(self, text)
    -- Handle form submission
end

app.root:addChild(passwordBox)
app.root:addChild(strengthLabel)

app:run()
```

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

### Get Content Offset

Source: https://pixelui.madefor.cc/api/window.html

Returns the content offset.

```lua
getContentOffset()
```

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

### animate

Source: https://pixelui.madefor.cc/api/app.html

Starts an animation sequence.

```APIDOC
## animate

### Description
Starts an animation based on the provided options.

### Parameters
- **options** (PixelUI.AnimationOptions) - Required - Configuration options for the animation.

### Returns
- **PixelUI.AnimationHandle** - A handle to control the animation.
```

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

### Get Selection Text

Source: https://pixelui.madefor.cc/api/textbox.html

Returns the text currently selected.

```lua
getSelectionText()
```

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

### Move Cursor to Line Start

Source: https://pixelui.madefor.cc/api/textbox.html

Moves the cursor to the beginning of the current line.

```lua
_moveCursorLineStart()
```

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

### Advanced TabControl Usage

Source: https://pixelui.madefor.cc/api/tabcontrol.html

An example showing custom styling, event handling, and adding content to tab bodies.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Tab control with dynamic content and styling
local tabs = app:tabcontrol({
    x = 2, y = 2,
    width = 45, height = 15,
    tabBg = colors.gray,
    tabFg = colors.white,
    selectedTabBg = colors.blue,
    selectedTabFg = colors.white,
    tabSpacing = 1,
    tabPadding = 2,
    onSelect = function(self, tabId, index)
        -- Handle tab selection
    end
})

-- Add tabs with custom content renderers
local homeTab = tabs:addTab({
    id = "home",
    label = "Home",
    closable = false
})

local settingsTab = tabs:addTab({
    id = "settings",
    label = "Settings",
    closable = true,
    onClose = function(tab)
        -- Confirm before closing
        return true
    end
})

-- Get tab body frame for adding content
local homeBody = tabs:getTabBody("home")
if homeBody then
    homeBody:addChild(app:label({
        x = 2, y = 2,
        text = "Welcome to the Home tab!"
    }))
end

app.root:addChild(tabs)

app:run()
```

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

### getFocus

Source: https://pixelui.madefor.cc/api/app.html

Gets the currently focused widget.

```APIDOC
## getFocus

### Description
Returns the widget that currently has focus.

### Returns
- **PixelUI.Widget?** - The focused widget or nil.
```

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

### Get Selected Node

Source: https://pixelui.madefor.cc/api/treeview.html

Retrieves the currently selected node.

```lua
getSelectedNode()
```

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

### Advanced Modal Dialog Example

Source: https://pixelui.madefor.cc/api/dialog.html

Demonstrates a complex dialog with custom backdrop colors, escape handling, and interactive elements like checkboxes and a close button.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Modal dialog with backdrop and escape handling
local dialog = app:dialog({
    x = 10, y = 5,
    width = 35, height = 12,
    title = "Settings Dialog",
    modal = true,
    backdropColor = colors.black,
    backdropPixelColor = colors.gray,
    closeOnBackdrop = false,
    closeOnEscape = true,
    draggable = true,
    closable = true
})

dialog:addChild(app:checkbox({
    x = 2, y = 2,
    label = "Enable notifications"
}))

dialog:addChild(app:checkbox({
    x = 2, y = 4,
    label = "Auto-save"
}))

local saveBtn = app:button({
    x = 2, y = 7,
    width = 10, height = 1,
    label = "Save",
    onClick = function()
        dialog:close()
    end
})
dialog:addChild(saveBtn)

app.root:addChild(dialog)

app:run()
```

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

### Get Title Bar

Source: https://pixelui.madefor.cc/api/window.html

Returns the current title bar component.

```lua
getTitleBar()
```

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

### Get Content Size

Source: https://pixelui.madefor.cc/api/textbox.html

Returns the total size of the text content.

```lua
_getContentSize()
```

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

### Get Widget Size

Source: https://pixelui.madefor.cc/api/widget.html

Retrieves the current width and height of the widget.

```lua
getSize()
```

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

### Slide a Widget Animation

Source: https://pixelui.madefor.cc/guides/animations.html

Moves a widget into view by starting from an off-screen position.

```lua
-- Slide widget in from left
app:animate({
  duration = 0.5,
  easing = "easeOutQuad",
  update = function(progress)
    widget.x = -20 + (25 * progress)  -- Start off-screen
  end
})
```

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

### ComboBox Get Selected Item

Source: https://pixelui.madefor.cc/api/combobox.html

Retrieves the currently selected item.

```lua
getSelectedItem()
```

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

### app:animate(options)

Source: https://pixelui.madefor.cc/guides/animations.html

Creates and starts a new animation. The function accepts an options table to define the animation behavior, including duration, easing, and update callbacks.

```APIDOC
## app:animate(options)

### Description
Starts an animation sequence. The animation progresses over the specified duration, calling the update function each frame.

### Parameters
- **options** (table) - Required
  - **duration** (number) - Optional - Duration in seconds (default: 1.0)
  - **easing** (string|function) - Optional - Easing function name or custom function (default: "linear")
  - **update** (function) - Required - Called each frame with (progress, rawProgress)
  - **onComplete** (function) - Optional - Called when animation finishes
  - **onCancel** (function) - Optional - Called if animation is cancelled

### Returns
- **handle** (object) - An animation handle object with a :cancel() method.
```

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

### Get Selection Indices

Source: https://pixelui.madefor.cc/api/textbox.html

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

```lua
_getSelectionIndices()
```

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

### Get Text Content

Source: https://pixelui.madefor.cc/api/label.html

Retrieves the current text content of the label.

```lua
getText()
```

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

### Get Autocomplete Index from Point

Source: https://pixelui.madefor.cc/api/textbox.html

Determines the autocomplete suggestion index from a point.

```lua
_autocompleteIndexFromPoint()
```

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

### Advanced TreeView Example

Source: https://pixelui.madefor.cc/api/treeview.html

A complex tree view with nested nodes, custom styling, and scrollbar configuration.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Hierarchical tree with nested nodes
local infoLabel = app:label({
    x = 30, y = 2,
    text = "Select a file",
    fg = colors.lightGray
})

local tree = app:treeview({
    x = 2, y = 2,
    width = 25, height = 12,
    indentWidth = 2,
    highlightBg = colors.blue,
    highlightFg = colors.white,
    scrollbar = { enabled = true },
    onSelect = function(self, node, index)
        if node then
            infoLabel:setText("File: " .. node.label)
        end
    end,
    onToggle = function(self, node, expanded)
        -- Handle expand/collapse
    end
})

-- Build file tree structure
local docs = tree:addNode({ label = "Documents", expanded = true })
tree:addChildNode(docs, { label = "report.txt", data = { size = 1024 } })
tree:addChildNode(docs, { label = "notes.md", data = { size = 512 } })

local pics = tree:addNode({ label = "Pictures", expanded = false })
tree:addChildNode(pics, { label = "photo1.png" })
tree:addChildNode(pics, { label = "photo2.png" })

app.root:addChild(tree)
app.root:addChild(infoLabel)

app:run()
```

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

### Get Step for Nudge

Source: https://pixelui.madefor.cc/api/slider.html

Internal method to calculate the step size for nudge operations.

```lua
_getStepForNudge()
```

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

### Advanced Toggle Customization

Source: https://pixelui.madefor.cc/api/toggle.html

A customized toggle example featuring labels, specific track colors, and easing animations.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Customized toggle with labels and colors
local statusLabel = app:label({
    x = 2, y = 5,
    text = "Status: OFF",
    fg = colors.white
})

local toggle = app:toggle({
    x = 2, y = 2,
    width = 10, height = 1,
    value = false,
    labelOn = "ON",
    labelOff = "OFF",
    showLabel = true,
    trackColorOn = colors.green,
    trackColorOff = colors.red,
    thumbColor = colors.white,
    transitionDuration = 0.2,
    transitionEasing = pixelui.easings.easeOutQuad,
    onChange = function(self, value)
        statusLabel:setText("Status: " .. (value and "ON" or "OFF"))
    end
})

app.root:addChild(toggle)
app.root:addChild(statusLabel)

app:run()
```

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

### Get Line Count

Source: https://pixelui.madefor.cc/api/textbox.html

Returns the total number of lines in the text content.

```lua
getLineCount()
```

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

### Item and Selection Accessors

Source: https://pixelui.madefor.cc/api/list.html

Methods to get or set items, selection index, and selection callbacks.

```lua
getItems()
```

```lua
setItems()
```

```lua
getSelectedItem()
```

```lua
setSelectedIndex()
```

```lua
getSelectedIndex()
```

```lua
setOnSelect()
```

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

### Get Value

Source: https://pixelui.madefor.cc/api/slider.html

Retrieves the current value of the slider.

```lua
getValue()
```

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

### Begin Resize

Source: https://pixelui.madefor.cc/api/window.html

Initiates a resize operation.

```lua
_beginResize()
```

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

### Get Minimized Height

Source: https://pixelui.madefor.cc/api/window.html

Returns the fixed height for the minimized state.

```lua
getMinimizedHeight()
```

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

### Advanced Range Slider

Source: https://pixelui.madefor.cc/api/slider.html

Example of a range slider with custom formatting and dynamic label updates.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Range slider with custom formatting
local rangeLabel = app:label({
    x = 2, y = 5,
    text = "Range: $0 - $100",
    fg = colors.white
})

local slider = app:slider({
    x = 2, y = 2,
    width = 30, height = 1,
    min = 0,
    max = 1000,
    range = true,
    lowerValue = 200,
    upperValue = 800,
    step = 50,
    showValue = true,
    formatValue = function(self, lower, upper)
        return string.format("$%d - $%d", lower, upper)
    end,
    onChange = function(self, lower, upper)
        rangeLabel:setText(string.format("Range: $%d - $%d", lower, upper))
    end
})

app.root:addChild(slider)
app.root:addChild(rangeLabel)

app:run()
```

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

### Basic ComboBox Usage

Source: https://pixelui.madefor.cc/api/combobox.html

Demonstrates creating a simple dropdown with basic configuration.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple dropdown selection
local combo = app:combobox({
    x = 2, y = 2,
    width = 15, height = 1,
    items = { "Small", "Medium", "Large" },
    placeholder = "Select size",
    onChange = function(self, item, index)
        -- Handle selection change
    end
})
app.root:addChild(combo)

app:run()
```

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

### Create a Basic PixelUI Application

Source: https://pixelui.madefor.cc/api/app.html

Initializes a simple application with a black background and a label widget.

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

-- Create a simple application
local app = pixelui.app({
    background = colors.black
})

-- Add widgets to root frame
app.root:addChild(app:label({
    text = "Hello PixelUI!",
    x = 2, y = 2,
    fg = colors.white
}))

-- Start the application
app:run()
```

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

### Get RadioButton group

Source: https://pixelui.madefor.cc/api/radiobutton.html

Method to retrieve the current group identifier.

```lua
getGroup()
```

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

### Begin Interaction

Source: https://pixelui.madefor.cc/api/slider.html

Internal method to initialize a user interaction.

```lua
_beginInteraction()
```

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

### Get Backdrop Color

Source: https://pixelui.madefor.cc/api/dialog.html

Retrieves the currently set backdrop color.

```lua
getBackdropColor()
```

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

### Configuration Methods

Source: https://pixelui.madefor.cc/api/list.html

Methods for setting visual properties and configuration.

```lua
setPlaceholder()
```

```lua
setHighlightColors()
```

```lua
setScrollbar()
```

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

### Get Selection Range

Source: https://pixelui.madefor.cc/api/textbox.html

Retrieves the range object for the current selection.

```lua
_getSelectionRange()
```

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

### Create a basic window in PixelUI

Source: https://pixelui.madefor.cc/api/window.html

Initializes a simple floating window with a label and adds it to the application root.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple floating window
local window = app:window({
    x = 5, y = 3,
    width = 30, height = 12,
    title = "My Window",
    bg = colors.gray
})

window:addChild(app:label({
    x = 2, y = 2,
    text = "Window content here"
}))

app.root:addChild(window)

app:run()
```

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

### Get Selection Length

Source: https://pixelui.madefor.cc/api/textbox.html

Returns the length of the current text selection.

```lua
getSelectionLength()
```

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

### Initialize MsgBox

Source: https://pixelui.madefor.cc/api/msgbox.html

Methods for initializing and configuring the MsgBox component.

```lua
new()
```

```lua
setMessage()
```

```lua
getMessage()
```

```lua
setOnResult()
```

```lua
_createButtonEntry()
```

```lua
setButtons()
```

```lua
_handleButtonSelection()
```

```lua
setButtonAlign()
```

```lua
setAutoClose()
```

```lua
setButtonGap()
```

```lua
_updateLayout()
```

```lua
setSize()
```

```lua
setBorder()
```

```lua
setTitleBar()
```

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

### Get Overlay Height

Source: https://pixelui.madefor.cc/api/textbox.html

Calculates the height of the current overlay elements.

```lua
_getOverlayHeight()
```

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

### Get Cursor Position

Source: https://pixelui.madefor.cc/api/textbox.html

Returns the current cursor position as a coordinate.

```lua
getCursorPosition()
```

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

### Get Widget Constraints

Source: https://pixelui.madefor.cc/api/widget.html

Retrieves the current size constraints of the widget.

```lua
getConstraints()
```

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

### Styling and Display Methods

Source: https://pixelui.madefor.cc/api/progressbar.html

Methods for configuring labels, percentage visibility, colors, and rendering.

```lua
setLabel()
```

```lua
setShowPercent()
```

```lua
setColors()
```

```lua
draw()
```

```lua
handleEvent()
```

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

### new()

Source: https://pixelui.madefor.cc/api/window.html

Creates a new instance of a PixelUI.Window.

```APIDOC
## new()

### Description
Creates a new instance of the Window widget.

### Signature
`new()`
```

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

### Get Inner Height

Source: https://pixelui.madefor.cc/api/treeview.html

Internal method to calculate total content height.

```lua
_getInnerHeight()
```

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

### Bring to Front

Source: https://pixelui.madefor.cc/api/window.html

Brings the window to the front of the stack.

```lua
bringToFront()
```

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

### Set Title

Source: https://pixelui.madefor.cc/api/window.html

Sets the window title.

```lua
setTitle()
```

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

### Get Cursor from Point

Source: https://pixelui.madefor.cc/api/textbox.html

Calculates the cursor position based on a screen point.

```lua
_cursorFromPoint()
```

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

### Window Configuration Methods

Source: https://pixelui.madefor.cc/api/window.html

Methods to configure window behavior and properties.

```APIDOC
## setDraggable(boolean)
Sets whether the window can be dragged.

## isDraggable()
Returns true if the window is draggable.

## setResizable(boolean)
Sets whether the window can be resized.

## isResizable()
Returns true if the window is resizable.

## setClosable(boolean)
Sets whether the window shows a close button.

## isClosable()
Returns true if the window is closable.

## setMaximizable(boolean)
Sets whether the window shows a maximize button.

## isMaximizable()
Returns true if the window is maximizable.

## setMinimizable(boolean)
Sets whether the window shows a minimize button.

## isMinimizable()
Returns true if the window is minimizable.
```

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

### new()

Source: https://pixelui.madefor.cc/api/textbox.html

Initializes a new instance of the PixelUI.TextBox widget.

```APIDOC
## new()

### Description
Creates and returns a new instance of the TextBox widget.

### Signature
`new()`
```

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

### Get Absolute Rectangle

Source: https://pixelui.madefor.cc/api/widget.html

Retrieves the absolute screen coordinates and dimensions of the widget.

```lua
getAbsoluteRect()
```

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

### Get Inner Metrics

Source: https://pixelui.madefor.cc/api/label.html

Retrieves the internal dimensions and layout metrics of the label.

```lua
_getInnerMetrics()
```

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

### Lifecycle and Execution Methods

Source: https://pixelui.madefor.cc/api/app.html

Core methods for rendering, stepping, running, and stopping the UI loop. Available since version 0.1.0.

```lua
render()
```

```lua
step(event)
```

```lua
run()
```

```lua
stop()
```

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

### Begin Drag

Source: https://pixelui.madefor.cc/api/window.html

Initiates a drag operation.

```lua
_beginDrag()
```

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

### Get Visible Title Bar Height

Source: https://pixelui.madefor.cc/api/window.html

Returns the height of the visible title bar.

```lua
_getVisibleTitleBarHeight()
```

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

### Advanced LoadingRing Configuration

Source: https://pixelui.madefor.cc/api/loadingring.html

A customized loading ring with trail effects and interactive start/stop controls.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Customized loading ring with trail effect
local loader = app:loadingring({
    x = 10, y = 5,
    width = 9, height = 5,
    segmentCount = 8,
    thickness = 2,
    color = colors.blue,
    trailColor = colors.lightBlue,
    speed = 1.5,
    direction = 1,
    fadeSteps = 4,
    autoStart = true
})

-- Control loading state
local btn = app:button({
    x = 2, y = 12,
    width = 15, height = 1,
    label = "Stop/Start",
    onClick = function()
        if loader:isAnimating() then
            loader:stop()
        else
            loader:start()
        end
    end
})

app.root:addChild(loader)
app.root:addChild(btn)

app:run()
```

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

### Get Range Values

Source: https://pixelui.madefor.cc/api/slider.html

Retrieves the current lower and upper bounds in range mode.

```lua
getRangeValues()
```

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

### Create UI Widgets

Source: https://pixelui.madefor.cc/api/app.html

Methods to instantiate various UI components like frames, windows, buttons, and input controls.

```lua
createFrame(config)
```

```lua
createWindow(config)
```

```lua
createDialog(config)
```

```lua
createMsgBox(config)
```

```lua
createButton(config)
```

```lua
createLabel(config)
```

```lua
createCheckBox(config)
```

```lua
createToggle(config)
```

```lua
createTextBox(config)
```

```lua
createComboBox(config)
```

```lua
createTabControl(config)
```

```lua
createContextMenu(config)
```

```lua
createList(config)
```

```lua
createTable(config)
```

```lua
createTreeView(config)
```

```lua
createChart(config)
```

```lua
createRadioButton(config)
```

```lua
createProgressBar(config)
```

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

### Create an advanced window with controls and events

Source: https://pixelui.madefor.cc/api/window.html

Configures a window with interactive features like resizing, dragging, and custom title bar styling, along with event handlers.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Feature-rich window with all controls
local window = app:window({
    x = 5, y = 3,
    width = 35, height = 15,
    title = "Advanced Window",
    draggable = true,
    resizable = true,
    closable = true,
    maximizable = true,
    minimizable = true,
    hideBorderWhenMaximized = true,
    bg = colors.black,
    border = { color = colors.gray }
})

-- Configure title bar
window:setTitleBar({
    enabled = true,
    height = 1,
    bg = colors.blue,
    fg = colors.white,
    align = "center"
})

-- Add window content
window:addChild(app:label({
    x = 2, y = 2,
    text = "Drag the title bar to move"
}))

window:addChild(app:label({
    x = 2, y = 4,
    text = "Drag corners to resize"
}))

-- Handle window events
window.onClose = function()
    return true  -- Allow close
end

window.onMaximize = function()
    -- Handle maximize
end

app.root:addChild(window)

app:run()
```

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

### Basic FreeDraw Usage

Source: https://pixelui.madefor.cc/api/freedraw.html

Demonstrates creating a simple drawing surface with a black background and text.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Custom drawing surface
local canvas = app:freedraw({
    x = 2, y = 2,
    width = 20, height = 10,
    clear = true,
    onDraw = function(self, ctx)
        ctx.fill(colors.black)
        ctx.write(1, 1, "Custom Draw", colors.white)
    end
})
app.root:addChild(canvas)

app:run()
```

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

### Basic Label Usage

Source: https://pixelui.madefor.cc/api/label.html

Creates a simple text label with basic color styling.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple text label
local label = app:label({
    x = 2, y = 2,
    text = "Hello World!",
    fg = colors.yellow,
    bg = colors.black
})
app.root:addChild(label)

app:run()
```

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

### Initialize LoadingRing

Source: https://pixelui.madefor.cc/api/loadingring.html

Constructor and internal lifecycle methods for the LoadingRing widget.

```lua
new()
```

```lua
_cancelTick()
```

```lua
_scheduleTick()
```

```lua
start()
```

```lua
stop()
```

```lua
setSpeed()
```

```lua
setDirection()
```

```lua
setSegments()
```

```lua
setThickness()
```

```lua
setRadius()
```

```lua
setColor()
```

```lua
setSecondaryColor()
```

```lua
setTertiaryColor()
```

```lua
setTrailColor()
```

```lua
setTrailPalette()
```

```lua
setFadeSteps()
```

```lua
_computeTrailColors()
```

```lua
draw()
```

```lua
handleEvent()
```

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

### Create an Advanced PixelUI Application

Source: https://pixelui.madefor.cc/api/app.html

Configures an application with custom borders, animation intervals, and background thread management.

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

-- Create application with custom window and border
local app = pixelui.app({
    background = colors.gray,
    rootBorder = {
        color = colors.lightGray,
        sides = { "top", "bottom", "left", "right" },
        thickness = 2
    },
    animationInterval = 0.05
})

-- Create a frame with child widgets
local mainFrame = app:frame({
    x = 2, y = 2,
    width = 30, height = 10,
    bg = colors.black
})
app.root:addChild(mainFrame)

-- Spawn a background thread
app:spawnThread(function(ctx)
    for i = 1, 10 do
        ctx:setMetadata("progress", i * 10)
        ctx:sleep(0.5)
        if ctx:shouldCancel() then return end
    end
end, {
    name = "BackgroundTask",
    onStatus = function(handle, status)
        -- Handle thread status changes
    end
})

app:run()
```

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

### Create a Basic Animation in Lua

Source: https://pixelui.madefor.cc/guides/animations.html

Initializes a button and animates its horizontal position over one second using the easeOutQuad easing function.

```lua
local widget = app:createButton({
  parent = root,
  x = 5,
  y = 5,
  width = 15,
  height = 3,
  label = "Animate Me"
})

-- Animate the button moving to the right
app:animate({
  duration = 1.0,  -- 1 second
  easing = "easeOutQuad",
  update = function(progress)
    widget.x = 5 + (30 * progress)
  end,
  onComplete = function()
    print("Animation complete!")
  end
})
```

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

### Initialize Table Widget

Source: https://pixelui.madefor.cc/api/table.html

Methods used to instantiate and manage the internal state of the table widget.

```lua
new()
```

```lua
_normalizeColumns()
```

```lua
_recomputeColumnMetrics()
```

```lua
_ensureColumnsForData()
```

```lua
setColumns()
```

```lua
getColumns()
```

```lua
setData()
```

```lua
getData()
```

```lua
_refreshRows()
```

```lua
_getColumnById()
```

```lua
_applySort()
```

```lua
setSort()
```

```lua
getSort()
```

```lua
setOnSort()
```

```lua
setScrollbar()
```

```lua
setOnSelect()
```

```lua
getSelectedIndex()
```

```lua
getSelectedRow()
```

```lua
setSelectedIndex()
```

```lua
_notifySelect()
```

```lua
_getInnerMetrics()
```

```lua
_computeLayoutMetrics()
```

```lua
_getRowsVisible()
```

```lua
_clampScroll()
```

```lua
_ensureSelectionVisible()
```

```lua
_rowFromPoint()
```

```lua
_columnFromPoint()
```

```lua
_formatCell()
```

```lua
draw()
```

```lua
_handleTypeSearch()
```

```lua
_searchForPrefix()
```

```lua
onFocusChanged()
```

```lua
handleEvent()
```

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

### Configure Appearance and Behavior

Source: https://pixelui.madefor.cc/api/tabcontrol.html

Methods for customizing the renderer, empty state text, and interaction settings.

```lua
setBodyRenderer()
```

```lua
setEmptyText()
```

```lua
setTabCloseButton()
```

```lua
setTabIndicator()
```

```lua
setTabClosable()
```

```lua
setAutoShrink()
```

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

### Initialize FreeDraw

Source: https://pixelui.madefor.cc/api/freedraw.html

Constructor for creating a new FreeDraw instance.

```lua
new()
```

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

### Create a FreeDraw Widget

Source: https://pixelui.madefor.cc/guides/freedraw.html

Initializes a FreeDraw widget with custom dimensions, colors, and a drawing callback.

```lua
local canvas = app:createFreeDraw({
  x = 4,
  y = 3,
  width = 24,
  height = 9,
  bg = colors.black,
  fg = colors.white,
  border = { color = colors.lightGray },
  onDraw = function(self, ctx)
    ctx.fill(colors.black)
    for x = 1, ctx.width do
      local angle = (x / ctx.width) * math.pi * 2
      local y = math.floor(ctx.height / 2 + math.sin(angle) * (ctx.height / 3))
      ctx.pixel(x, math.max(1, math.min(ctx.height, y)), colors.cyan)
    end
    ctx.write(2, 2, "FreeDraw", colors.white)
  end
})
```

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

### Basic MsgBox Usage

Source: https://pixelui.madefor.cc/api/msgbox.html

Create a simple message box with a title and message text.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple message box
local msgbox = app:msgbox({
    x = 10, y = 5,
    width = 30, height = 8,
    title = "Info",
    message = "Operation completed!"
})

app.root:addChild(msgbox)

app:run()
```

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

### Advanced List with Styling and Scrollbar

Source: https://pixelui.madefor.cc/api/list.html

Demonstrates a list with custom colors, scrollbar configuration, and dynamic item management.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- List with scrollbar and styling
local selectionLabel = app:label({
    x = 25, y = 2,
    text = "Selected: none",
    fg = colors.white
})

local list = app:list({
    x = 2, y = 2,
    width = 20, height = 10,
    items = {},
    placeholder = "No items",
    highlightBg = colors.blue,
    highlightFg = colors.white,
    scrollbar = {
        enabled = true,
        alwaysVisible = false,
        thumbColor = colors.lightGray,
        trackColor = colors.gray
    },
    onSelect = function(self, item, index)
        selectionLabel:setText("Selected: " .. (item or "none"))
    end
})

-- Dynamically add items
for i = 1, 20 do
    list:addItem("Item " .. i)
end

-- Select first item programmatically
list:setSelectedIndex(1)

app.root:addChild(list)
app.root:addChild(selectionLabel)

app:run()
```

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

### Initialize Toggle Widget

Source: https://pixelui.madefor.cc/api/toggle.html

Methods for initializing and managing the internal state of the Toggle widget.

```lua
new()
```

```lua
_cancelAnimation()
```

```lua
_setThumbProgress()
```

```lua
_animateThumb()
```

```lua
_emitChange()
```

```lua
setOnChange()
```

```lua
setValue()
```

```lua
isOn()
```

```lua
toggle()
```

```lua
setLabels()
```

```lua
setShowLabel()
```

```lua
setDisabled()
```

```lua
isDisabled()
```

```lua
setColors()
```

```lua
setTransition()
```

```lua
setKnobStyle()
```

```lua
draw()
```

```lua
handleEvent()
```

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

### Select All Text

Source: https://pixelui.madefor.cc/api/textbox.html

Selects all text within the widget.

```lua
_selectAll()
```

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

### Compute Syntax Colors

Source: https://pixelui.madefor.cc/api/textbox.html

Calculates the colors for syntax highlighting.

```lua
_computeSyntaxColors()
```

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

### PixelUI.Dialog Methods

Source: https://pixelui.madefor.cc/api/dialog.html

Methods available for interacting with and configuring a PixelUI.Dialog instance.

```APIDOC
## new()
Creates a new instance of a Dialog.

## setModal()
Sets the modal state of the dialog.

## isModal()
Returns the current modal state of the dialog.

## setBackdropColor()
Sets the color of the backdrop when the dialog is modal.

## getBackdropColor()
Returns the current backdrop color.

## setCloseOnBackdrop()
Configures whether clicking the backdrop closes the dialog.

## setCloseOnEscape()
Configures whether pressing the escape key closes the dialog.

## draw()
Draws the dialog component.

## handleEvent()
Handles input events for the dialog.

## close()
Closes the dialog instance.
```

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

### Create Free Draw

Source: https://pixelui.madefor.cc/api/app.html

Initializes a new free draw widget.

```lua
createFreeDraw(config)
```

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

### Report progress from background threads

Source: https://pixelui.madefor.cc/guides/threading.html

Use ctx:setProgress and ctx:setStatus to communicate with the UI, and handle updates via the onMetadata callback.

```lua
local progressBar = app:createProgressBar({
  x = 5,
  y = 10,
  width = 30,
  height = 3
})
root:addChild(progressBar)

local handle = app:spawnThread(function(ctx)
  for i = 1, 100 do
    -- Update progress
    ctx:setProgress(i / 100)
    ctx:setStatus("Step " .. i .. " of 100")
    
    -- Simulate work
    ctx:sleep(0.05)
  end
end, {
  name = "Work Task",
  onMetadata = function(h, key, value)
    if key == "progress" then
      progressBar:setValue(value)
    end
  end
})
```

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

### End Resize

Source: https://pixelui.madefor.cc/api/window.html

Completes the resize operation.

```lua
_endResize()
```

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

### Core Component Methods

Source: https://pixelui.madefor.cc/api/textbox.html

Standard methods for rendering, event handling, and text manipulation.

```lua
draw()
```

```lua
handleEvent()
```

```lua
setText()
```

```lua
getText()
```

```lua
setOnChange()
```

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

### Basic Notification Toast Usage

Source: https://pixelui.madefor.cc/api/notificationtoast.html

Demonstrates creating a simple notification toast that automatically hides after 3 seconds.

```lua
local pixelui = require("pixelui")
local app = pixelui.app()

-- Simple notification toast
local toast = app:notificationtoast({
    x = 2, y = 2,
    width = 30, height = 3,
    message = "File saved successfully",
    severity = "success",
    autoHide = true,
    duration = 3
})
app.root:addChild(toast)

app:run()
```

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

### Widget Creation Methods

Source: https://pixelui.madefor.cc/api/app.html

Factory methods for creating various UI components.

```APIDOC
## createFrame(config)
Creates a new `PixelUI.Frame`.

## createWindow(config)
Creates a new `PixelUI.Window`.

## createDialog(config)
Creates a new `PixelUI.Dialog`.

## createMsgBox(config)
Creates a new `PixelUI.MsgBox`.

## createButton(config)
Creates a new `PixelUI.Button`.

## createLabel(config)
Creates a new `PixelUI.Label`.

## createCheckBox(config)
Creates a new `PixelUI.CheckBox`.

## createToggle(config)
Creates a new `PixelUI.Toggle`.

## createTextBox(config)
Creates a new `PixelUI.TextBox`.

## createComboBox(config)
Creates a new `PixelUI.ComboBox`.

## createTabControl(config)
Creates a new `PixelUI.TabControl`.

## createContextMenu(config)
Creates a new `PixelUI.ContextMenu`.

## createList(config)
Creates a new `PixelUI.List`.

## createTable(config)
Creates a new `PixelUI.Table`.

## createTreeView(config)
Creates a new `PixelUI.TreeView`.

## createChart(config)
Creates a new `PixelUI.Chart`.

## createRadioButton(config)
Creates a new `PixelUI.RadioButton`.

## createProgressBar(config)
Creates a new `PixelUI.ProgressBar`.
```

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

### new()

Source: https://pixelui.madefor.cc/api/combobox.html

Creates a new instance of the ComboBox widget.

```APIDOC
## new()

### Description
Creates a new instance of the ComboBox widget.

### Signature
`new()`
```

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

### Restore Window

Source: https://pixelui.madefor.cc/api/window.html

Restores the window to its previous state.

```lua
restore()
```
Tokens:
Raw