Plugin System

What are PixelUI Plugins?

PixelUI plugins are modular extensions that add new functionality to the framework. They can include:

Custom Widgets: New UI components with unique functionality
Themes: Complete visual styling packages
Animations: Custom transition and motion effects
Utilities: Helper functions and tools for development

Why Use Plugins?

Plugins allow you to:

Extend functionality without modifying core code
Share components with the community
Maintain clean, modular applications
Leverage community-created solutions

Installing Plugins

-- Download and place plugin file in plugins directory
-- /your-project/plugins/awesome-widget.lua

local PixelUI = require("pixelui")

-- Load the plugin
PixelUI.loadPlugin("awesome-widget")

-- Plugin is now available for use
local myWidget = PixelUI.awesomeWidget({
    x = 10, y = 5,
    text = "Hello from plugin!"
})

-- Using the built-in plugin manager
local PixelUI = require("pixelui")

-- Install from repository
PixelUI.plugins.install("awesome-widget")

-- Or install from URL
PixelUI.plugins.installFromUrl("https://example.com/plugin.lua")

-- List installed plugins
local plugins = PixelUI.plugins.list()
for name, info in pairs(plugins) do
    print(name .. " v" .. info.version)
end

Create the Plugin File

Create a new file hello-widget.lua in your plugins directory:

-- hello-widget.lua
-- A simple "Hello World" widget plugin

local HelloWidget = {}

-- Plugin metadata
HelloWidget.info = {
    name = "HelloWidget",
    version = "1.0.0",
    description = "A simple hello world widget",
    author = "Your Name",
    type = "widget"
}

-- Widget constructor
function HelloWidget.new(parent, x, y, options)
    options = options or {}
    
    local widget = {
        x = x or 1,
        y = y or 1,
        text = options.text or "Hello, World!",
        color = options.color or colors.white,
        backgroundColor = options.backgroundColor or colors.black,
        visible = true
    }
    
    -- Render function
    function widget:render(terminal)
        if not self.visible then return end
        
        terminal.setCursorPos(self.x, self.y)
        terminal.setTextColor(self.color)
        terminal.setBackgroundColor(self.backgroundColor)
        terminal.write(self.text)
    end
    
    -- Update text
    function widget:setText(newText)
        self.text = newText
    end
    
    -- Event handlers
    function widget:onClick(x, y)
        self.text = "Clicked!"
        return true
    end
    
    return widget
end

-- Register the plugin
return HelloWidget

Using Your Plugin

-- main.lua
local PixelUI = require("pixelui")

-- Initialize PixelUI
PixelUI.init()

-- Load your plugin
PixelUI.loadPlugin("hello-widget")

-- Create the widget
local hello = PixelUI.helloWidget(nil, 5, 3, {
    text = "Hello from my plugin!",
    color = colors.yellow,
    backgroundColor = colors.blue
})

-- Add to render loop
PixelUI.addWidget(hello)

-- Run the application
PixelUI.run()

Important Notes

Plugin names should be unique within your application
Always include proper metadata in your plugins
Test your plugins thoroughly before sharing
Follow naming conventions: use camelCase for function names

Required Components

Component	Type	Required	Description
info	table	Yes	Plugin metadata including name, version, description
new	function	Yes	Constructor function that creates widget instances
init	function	No	Optional initialization function called when plugin loads
cleanup	function	No	Optional cleanup function called when plugin unloads

Metadata Properties

Property	Type	Description
name	string	Unique plugin identifier
version	string	Plugin version (semantic versioning recommended)
description	string	Brief description of plugin functionality
author	string	Plugin author name
type	string	Plugin type: "widget", "theme", "animation", "utility"
dependencies	table	List of required plugins or libraries

Documentation in Progress

This documentation is currently being expanded. More sections including Widget Plugins, Theme Plugins, Advanced Topics, and Community resources are coming soon!

In the meantime, you can:

Explore the Plugin Gallery for examples
Check out the Plugin Repository
Join our community for support and discussions

Quick Start

Plugin Overview Getting Started

Extend PixelUI with powerful, reusable components that integrate seamlessly into any application.

What are PixelUI Plugins?

Installation Setup

Installing Plugins

Your First Plugin Tutorial

Create a simple "Hello World" widget plugin to understand the basic structure.

Create the Plugin File

Using Your Plugin

Plugin Structure Reference

Required Components

Metadata Properties