### Install QUI Go Package

Source: https://github.com/qbradq/qui/blob/main/README.md

Installs the QUI library using the Go toolchain. This command fetches the latest version of the QUI package and its dependencies.

```bash
go get github.com/qbradq/qui
```

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

### Initialize QUI Application in Go

Source: https://github.com/qbradq/qui/blob/main/README.md

Demonstrates the basic setup for a QUI application. It involves initializing a theme, creating a root widget, and setting up a Master controller for event handling and rendering within a q2d application loop.

```go
package main

import (
	"github.com/qbradq/qui"
	"github.com/qbradq/q2d"
)

func main() {
	// 1. Initialize Theme
	qui.InitTheme(q2d.FontThin)

	// 2. Create Root Widget
	root := qui.NewContainer(qui.LayoutVertical,
		qui.NewLabel("Hello, QUI!"),
		qui.NewButton("Click Me", func() {
			println("Button Clicked!")
		}),
	)

	// 3. Create Master Controller
	master := qui.NewMaster(root, qui.DefaultTheme)

	// 4. In your Game Loop:
	// - Pass events to master.Event(e)
	// - Call master.Layout(size) when window resizes
	// - Call master.Draw(img) to render
}
```

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

### Create and Configure QUI Widgets in Go

Source: https://github.com/qbradq/qui/blob/main/README.md

Provides code examples for creating and configuring various QUI widgets in Go. This includes labels, buttons, containers for layout, text entry fields, scrollable lists, and windows.

```go
// Label Example
label := qui.NewLabel("This is a label")
labelWithIcon := qui.NewLabel("Label with Icon")
labelWithIcon.Icon = qui.IconFile // Set an icon

// Button Example
btn := qui.NewButton("Submit", func() {
    println("Form submitted")
})

// Container Examples
// Vertical Container
vBox := qui.NewContainer(qui.LayoutVertical,
    qui.NewLabel("Top"),
    qui.NewLabel("Bottom"),
)

// Horizontal Container
hBox := qui.NewContainer(qui.LayoutHorizontal,
    qui.NewButton("Left", nil),
    qui.NewButton("Right", nil),
)

// Entry Examples
// Text Entry
nameEntry := qui.NewEntry("John Doe", qui.EntryText)

// Password Entry
passEntry := qui.NewEntry("", qui.EntryPassword)

// Integer Entry
ageEntry := qui.NewEntry("25", qui.EntryInteger)

// List Example
items := []qui.ListItem{
    {Text: "Item 1"},
    {Text: "Item 2", Icon: qui.IconFolder},
    {Text: "Item 3"},
}

list := qui.NewList(items, func(index int) {
    println("Selected item:", index)
})

// Window Example
content := qui.NewLabel("Window Content")
win := qui.NewWindow("My Window", content)

// Optional: Handle close
win.OnClose = func() {
    println("Window closed")
}
```

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

### Theme Customization in Go with Qui UI

Source: https://context7.com/qbradq/qui/llms.txt

Provides examples of initializing themes, generating themes from a single color or custom values, and applying themes globally or to specific widgets. It covers setting background, text, and accent colors, as well as fonts.

```go
// Initialize default dark theme
qui.InitTheme(basicfont.Face7x13)

// Generate theme from single color
blueTheme := qui.GenerateThemeFromColor(
    q2d.Color{0, 120, 255, 255},
    basicfont.Face7x13,
)

// Generate custom theme with full control
customTheme := qui.GenerateTheme(
    q2d.Color{20, 20, 20, 255},     // Background
    q2d.Color{240, 240, 240, 255},  // Text color
    q2d.Color{0, 150, 255, 255},    // Complement/Primary
    basicfont.Face7x13,
)

// Apply theme globally
qui.DefaultTheme = customTheme

// Apply theme to specific widget
button := qui.NewButton("Themed", nil)
button.SetTheme(blueTheme)

// Apply theme to Master (affects all widgets)
master := qui.NewMaster(root, customTheme)

// Theme controls: background colors, text color, button colors,
// border color, primary/secondary accent colors, font, spacing, padding
```

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

### Create Scrolled Container with Large Content in Go

Source: https://context7.com/qbradq/qui/llms.txt

Explains how to create a scrolled container to manage content that exceeds the viewport size. The example shows generating extensive content and wrapping it within a scrolled container, setting its dimensions, and highlights its features like scrollbars and mouse wheel support.

```go
// Create large content
largeContent := qui.NewContainer(qui.LayoutVertical)
for i := 0; i < 50; i++ {
    largeContent.Add(qui.NewLabel(fmt.Sprintf("Line %d", i)))
}

// Wrap in scrolled container
scrolled := qui.NewScrolledContainer(largeContent)
scrolled.Width = 300
scrolled.Height = 200

// Scrolled container features: automatic horizontal/vertical scrollbars,
// draggable scrollbar thumbs, mouse wheel support, clips content to viewport,
// scrollbars only appear when content exceeds viewport size
```

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

### Create Popup and Menu Bar Systems in Go

Source: https://context7.com/qbradq/qui/llms.txt

Shows how to create a popup menu with items, icons, and click actions, and how to display it as an overlay. It also demonstrates building a menu bar with multiple dropdown menus, each containing menu items.

```go
// Create popup menu
menu := qui.NewPopupMenu(
    qui.NewMenuItem("New File", qui.IconFile, func() {
        println("New file")
    }),
    qui.NewMenuItem("Open", qui.IconFolder, func() {
        println("Open file")
    }),
    qui.NewMenuItem("Save", qui.IconNone, func() {
        println("Save")
    }),
)

// Position and show as overlay
menu.SetRect(q2d.Rectangle{100, 100, 150, 90})
master.PushOverlay(menu)

// Create menu bar
menuBar := qui.NewMenuBar()
menuBar.OverlayManager = master

fileMenu := qui.NewPopupMenu(
    qui.NewMenuItem("New", qui.IconFile, func() {}),
    qui.NewMenuItem("Open", qui.IconFolder, func() {}),
)
menuBar.AddMenu("File", fileMenu)

editMenu := qui.NewPopupMenu(
    qui.NewMenuItem("Cut", qui.IconNone, func() {}),
    qui.NewMenuItem("Copy", qui.IconNone, func() {}),
)
menuBar.AddMenu("Edit", editMenu)

// Menu items highlight on hover, execute action and close on click,
// menu bar manages multiple dropdown menus
```

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

### Create and Configure Select Dropdown in Go

Source: https://context7.com/qbradq/qui/llms.txt

Demonstrates how to create a select dropdown with options, an icon, and a callback function for option selection. It also shows how to enable the overlay manager and explains the dropdown's behavior regarding display, popup interaction, and scrolling.

```go
// Create dropdown select
options := []qui.ListItem{
    {Text: "Option 1"},
    {Text: "Option 2", Icon: qui.IconFolder},
    {Text: "Option 3"},
}

dropdown := qui.NewSelect(options, func(index int) {
    println("Selected option:", index)
})

// Must set overlay manager to enable popup
dropdown.OverlayManager = master

// Select displays current selection, opens popup list on click,
// automatically closes when option selected or clicked outside,
// supports scrolling for many options
```

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

### Initialize QUI Master Controller in Go

Source: https://context7.com/qbradq/qui/llms.txt

Sets up the default theme, creates a widget hierarchy with a label and button, initializes the Master controller, and outlines where to integrate event handling, layout, and drawing within a game loop. Requires the 'qui' and 'q2d' packages.

```go
package main

import (
    "github.com/qbradq/qui"
    "github.com/qbradq/q2d"
    "golang.org/x/image/font/basicfont"
)

func main() {
    // Initialize default theme with font
    qui.InitTheme(basicfont.Face7x13)

    // Create root widget hierarchy
    root := qui.NewContainer(qui.LayoutVertical,
        qui.NewLabel("Welcome to QUI"),
        qui.NewButton("Click Me", func() {
            println("Button clicked!")
        }),
    )

    // Create Master controller
    master := qui.NewMaster(root, qui.DefaultTheme)

    // In your game loop:
    // master.Event(mouseEvent)        // Pass input events
    // master.Layout(qui.Size{800, 600}) // Call on window resize
    // master.Draw(q2dImage)            // Render the UI
}
```

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

### Create and Configure QUI Label Widgets in Go

Source: https://context7.com/qbradq/qui/llms.txt

Illustrates how to create basic text labels, labels with icons, and labels with tooltips using the QUI library. Labels automatically adjust their size to fit content and support theming for colors and fonts.

```go
// Simple text label
label := qui.NewLabel("Hello, World!")

// Label with icon
iconLabel := qui.NewLabel("Documents")
iconLabel.Icon = qui.IconFolder

// Label with tooltip
label.Tooltip = "This is a helpful tooltip"

// Labels automatically size to fit text and icon,
// support theming for colors and fonts

```

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

### Create Tab Container with Content in Go

Source: https://context7.com/qbradq/qui/llms.txt

Demonstrates the creation of a tab container with multiple tabs, each having a title, optional icon, and associated content. The code illustrates how to define different content for each tab.

```go
// Create tabs with content
tabContainer := qui.NewTabContainer(
    qui.Tab{
        Title: "General",
        Icon: qui.IconNone,
        Content: qui.NewLabel("General Settings"),
    },
    qui.Tab{
        Title: "Advanced",
        Icon: qui.IconNone,
        Content: qui.NewLabel("Advanced Options"),
    },
    qui.Tab{
        Title: "About",
        Icon: qui.IconFile,
        Content: qui.NewLabel("About this app"),
    },
)

// Tab container manages active tab state, renders tab headers,
// switches content on tab click, supports icons in tabs
```

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

### QUI Button Widget Functionality in Go

Source: https://context7.com/qbradq/qui/llms.txt

Demonstrates creating buttons with text and callbacks, adding icons, setting tooltips for user guidance, and applying custom themes. It highlights the expected visual feedback (hover, pressed states) and callback execution on click. Dependencies include 'qui' and 'q2d'.

```go
// Create button with text and callback
submitBtn := qui.NewButton("Submit Form", func() {
    println("Form submitted")
})

// Button with icon
iconBtn := qui.NewButton("Save", func() {
    // Save operation
})
iconBtn.Icon = qui.IconFile

// Tooltip support
submitBtn.Tooltip = "Click to submit the form"

// Custom theme for specific button
blueTheme := qui.GenerateThemeFromColor(
    q2d.Color{0, 100, 255, 255},
    basicfont.Face7x13,
)
submitBtn.SetTheme(blueTheme)

// Expected behavior: Visual feedback on hover (lighter color),
// pressed state (darker color), executes callback on click
```

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

### QUI Container Layout System in Go

Source: https://context7.com/qbradq/qui/llms.txt

Illustrates how to create UI layouts using QUI containers with vertical, horizontal, and nested arrangements. It shows how to enable stretching for children to fill available space and how the 'Fill' property makes a widget expand. Uses the 'qui' package.

```go
// Vertical layout
vContainer := qui.NewContainer(qui.LayoutVertical,
    qui.NewLabel("Top Item"),
    qui.NewLabel("Middle Item"),
    qui.NewLabel("Bottom Item"),
)

// Horizontal layout
hContainer := qui.NewContainer(qui.LayoutHorizontal,
    qui.NewButton("Left", nil),
    qui.NewButton("Center", nil),
    qui.NewButton("Right", nil),
)

// Nested layouts
complexLayout := qui.NewContainer(qui.LayoutVertical,
    qui.NewLabel("Header"),
    qui.NewContainer(qui.LayoutHorizontal,
        qui.NewButton("Action 1", nil),
        qui.NewButton("Action 2", nil),
    ),
)

// Container with stretch (children fill width/height)
stretchContainer := qui.NewContainer(qui.LayoutVertical)
stretchContainer.Stretch = true
stretchContainer.Add(qui.NewLabel("Full Width"))

// Fill property - widget expands to fill available space
fillWidget := qui.NewLabel("I expand")
fillWidget.Fill = true
```

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

### Customize QUI Theme in Go

Source: https://github.com/qbradq/qui/blob/main/README.md

Shows how to customize the appearance of QUI widgets by generating themes from a base color or by manually defining colors. The generated theme can be applied globally or to specific widgets.

```go
// Generate a theme from a base color (e.g., Blue)
baseColor := q2d.Color{0, 0, 255, 255}
newTheme := qui.GenerateThemeFromColor(baseColor, basicfont.Face7x13)

// Apply to a specific widget
// widget.SetTheme(newTheme) // Assuming 'widget' is a variable holding a QUI widget

// Or set as global default (before Master creation or in Master)
qui.DefaultTheme = newTheme
```

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

### Create and Manage Window Widget in Go

Source: https://context7.com/qbradq/qui/llms.txt

Illustrates the creation of a window widget with custom title and content, including labels and buttons. It covers configuring window properties like header, frame, and closability, setting a close callback, positioning and sizing the window, and adding it to the overlay system.

```go
// Create window with title and content
content := qui.NewContainer(qui.LayoutVertical,
    qui.NewLabel("Window Content"),
    qui.NewButton("OK", nil),
)

window := qui.NewWindow("My Window", content)

// Configure window
window.ShowHeader = true  // Show title bar (default true)
window.ShowFrame = true   // Show border (default true)
window.Closable = true    // Show close button (default true)

// Close callback
window.OnClose = func() {
    println("Window closed")
}

// Position and size
window.SetRect(q2d.Rectangle{100, 100, 400, 300})

// Add to overlay system
master.PushOverlay(window)

// Window is draggable by header, close button in top-right,
// manages its own overlay lifecycle
```

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

### QUI List Widget Configuration in Go

Source: https://context7.com/qbradq/qui/llms.txt

Details the creation of a list widget with predefined items, including text and icons. It shows how to specify a callback function executed when an item is selected and outlines features like automatic scrollbars, hover highlighting, keyboard navigation, and selection indication. Uses the 'qui' package.

```go
// Create list with items
items := []qui.ListItem{
    {Text: "Item 1", Icon: qui.IconNone},
    {Text: "Item 2", Icon: qui.IconFolder},
    {Text: "Item 3", Icon: qui.IconFile},
}

list := qui.NewList(items, func(index int) {
    println("Selected:", items[index].Text)
})

// List features: automatic scrollbar when items exceed viewport,
// mouse hover highlighting, keyboard navigation (up/down arrows),
// click to select, visual selection indicator

// List is focusable - click to focus, then use arrow keys
```

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

### Create and Route QUI Events in Go

Source: https://context7.com/qbradq/qui/llms.txt

Demonstrates the creation of various event types (mouse, keyboard, scroll) and how the Master controller routes them to widgets. Events follow a specific flow: overlays, root widget tree, then focused or under-mouse widgets.

```go
// Create mouse event
mouseMove := qui.MouseEvent{
    TypeVal: qui.EventMouseMove,
    Pos:     q2d.Point{100, 150},
    Button:  0,
}

mouseClick := qui.MouseEvent{
    TypeVal: qui.EventMouseDown,
    Pos:     q2d.Point{100, 150},
    Button:  0, // 0=Left, 1=Right, 2=Middle
}

// Create keyboard event
keyEvent := qui.KeyEvent{
    TypeVal: qui.EventKeyDown,
    Key:     qui.KeyEnter,
}

// Create scroll event
scrollEvent := qui.ScrollEvent{
    TypeVal: qui.EventScroll,
    DeltaX:  0,
    DeltaY:  -1.0, // Negative = scroll up
}

// Master routes events to appropriate widgets
consumed := master.Event(mouseClick)
if consumed {
    println("Event was handled by a widget")
}

// Event flow: overlays receive events first (top to bottom),
// then root widget tree, focused widgets receive keyboard events,
// widgets under mouse receive mouse/scroll events

```

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

### Create and Control Checkbox Widget in Go

Source: https://context7.com/qbradq/qui/llms.txt

Details the creation of a checkbox widget with a label and an initial state, along with a callback for state changes. It also covers programmatic toggling of the checkbox and checking its current state.

```go
// Create checkbox
checkbox := qui.NewCheckbox("Accept Terms", false, func(checked bool) {
    println("Checkbox is now:", checked)
})

// Programmatic toggle
checkbox.Toggle()

// Check state
if checkbox.Checked {
    println("Checkbox is checked")
}

// Checkbox supports click to toggle, keyboard activation (Enter/Space),
// visual checked/unchecked icons, focus indication
```

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

### QUI Text Entry Fields in Go

Source: https://context7.com/qbradq/qui/llms.txt

Shows different types of text entry widgets available in QUI: standard text, password (masked), integer-only, and float-only. Demonstrates programmatic text manipulation (get/set) and lists supported input features like focus, cursor navigation, and text selection. Requires the 'qui' package.

```go
// Standard text entry
nameEntry := qui.NewEntry("John Doe", qui.EntryText)
nameEntry.Width = 200 // Optional fixed width

// Password entry (displays asterisks)
passwordEntry := qui.NewEntry("", qui.EntryPassword)

// Integer-only entry
ageEntry := qui.NewEntry("25", qui.EntryInteger)

// Float number entry
priceEntry := qui.NewEntry("19.99", qui.EntryFloat)

// Get/set text programmatically
nameEntry.SetText("Jane Smith")
currentName := nameEntry.GetText()

// Entry supports focus (blue border when focused), cursor navigation,
// text selection, backspace, delete, home/end keys
```

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

### Theme Struct Definition in Go

Source: https://github.com/qbradq/qui/blob/main/DESIGN.md

Defines the Theme struct used in QUI to control the visual appearance of the UI. It includes properties for colors, fonts, and spacing, allowing for customizable theming of widgets.

```go
type Theme struct {
    BackgroundColor q2d.Color
    TextColor       q2d.Color
    PrimaryColor    q2d.Color
    SecondaryColor  q2d.Color
    Font            font.Face
    Spacing         int
    // ... other properties
}
```

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

### Widget Interface Definition in Go

Source: https://github.com/qbradq/qui/blob/main/DESIGN.md

Defines the core Widget interface for all UI elements in QUI. It specifies methods for layout calculation, drawing, event handling, and minimum size determination, forming the foundation of the retained-mode GUI architecture.

```go
type Widget interface {
    // Layout calculates the size and position of the widget and its children.
    // It receives the available space constraints.
    Layout(constraints Size) Size

    // Draw renders the widget onto the q2d.Image.
    // It receives the drawing context (offset, clip).
    Draw(img *q2d.Image, ctx Context)

    // Event handles input events (mouse, keyboard).
    // Returns true if the event was consumed.
    Event(e Event) bool

    // MinSize returns the minimum size required by the widget.
    MinSize() Size
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.