README
¶
DevTUI
Interactive Terminal User Interface library for Go applications development (principal tui in GoDEV App)
Quick Start
DevTUI uses specialized handler interfaces that require minimal implementation (1-3 methods vs 8 in previous versions). Choose the handler type that matches your use case:
package main
import (
"fmt"
"time"
"sync"
"github.com/cdvelop/devtui"
)
// HandlerEdit - For interactive input fields (3 methods)
type HostHandler struct {
currentHost string
}
func (h *HostHandler) Label() string { return "Host Configuration" }
func (h *HostHandler) Value() string { return h.currentHost }
func (h *HostHandler) Change(newValue any, progress ...func(string)) error {
h.currentHost = newValue.(string)
// Success message via progress callback
if len(progress) > 0 {
progress[0]("Host configured successfully: " + h.currentHost)
}
return nil
}
// HandlerExecution - For action buttons (2 methods)
type DeployHandler struct{}
func (d *DeployHandler) Label() string { return "Deploy to Production" }
func (d *DeployHandler) Execute(progress ...func(string)) error {
if len(progress) > 0 {
progress[0]("Starting deployment...")
// Deployment logic here
progress[0]("Deployment completed successfully")
}
return nil
}
// HandlerDisplay - For read-only information (2 methods)
type HelpHandler struct{}
func (h *HelpHandler) Label() string { return "DevTUI Help" }
func (h *HelpHandler) Content() string {
return "Navigation:\n• Tab/Shift+Tab: Switch tabs\n• Left/Right: Navigate fields\n• Enter: Edit/Execute"
}
// HandlerWriter - For simple logging (1 method)
type LogWriter struct{}
func (w *LogWriter) Name() string { return "ApplicationLog" }
func main() {
tui := devtui.NewTUI(&devtui.TuiConfig{
AppName: "MyApp",
ExitChan: make(chan bool),
})
// Method chaining with optional timeout configuration
tab := tui.NewTabSection("Server", "Configuration")
tab.NewEditHandler(&HostHandler{currentHost: "localhost"}).WithTimeout(5*time.Second)
tab.NewExecutionHandler(&DeployHandler{}).WithTimeout(30*time.Second)
tab.NewDisplayHandler(&HelpHandler{}).Register()
// Writer registration
writer := tab.NewWriterHandler(&LogWriter{}).Register()
writer.Write([]byte("Application started"))
var wg sync.WaitGroup
wg.Add(1)
go tui.Start(&wg)
wg.Wait()
}
New Specialized Interfaces
HandlerEdit - Interactive Input Fields
type HandlerEdit interface {
Label() string // Field label (e.g., "Server Port", "Host Configuration")
Value() string // Current/initial value (e.g., "8080", "localhost")
Change(newValue any, progress ...func(string)) error
}
HandlerExecution - Action Buttons
type HandlerExecution interface {
Label() string // Button label (e.g., "Deploy to Production", "Build Project")
Execute(progress ...func(string)) error
}
HandlerDisplay - Read-only Information
type HandlerDisplay interface {
Label() string // Display label (e.g., "Help", "Status")
Content() string // Display content (e.g., "help\n1-..\n2-...", "executing deploy wait...")
}
HandlerWriter - Simple Logging
type HandlerWriter interface {
Name() string // Writer identifier (e.g., "webBuilder", "ApplicationLog")
}
HandlerTrackerWriter - Advanced Logging with Message Updates
type HandlerTrackerWriter interface {
Name() string
MessageTracker
}
type MessageTracker interface {
GetLastOperationID() string
SetLastOperationID(id string)
}
Method Chaining API
Timeout Configuration
// Synchronous execution (default)
tab.NewEditHandler(handler).Register() // timeout = 0
tab.NewEditHandler(handler) // Auto-register, timeout = 0
// Asynchronous execution with timeout
tab.NewEditHandler(handler).WithTimeout(5*time.Second) // 5 seconds
tab.NewEditHandler(handler).WithTimeout(100*time.Millisecond) // 100ms (ideal for tests)
tab.NewExecutionHandler(deployHandler).WithTimeout(30*time.Second) // 30 seconds for deployment
Writer Registration
// Basic writer (always creates new lines)
writer := tab.NewWriterHandler(&LogWriter{}).Register()
writer.Write([]byte("Log message"))
// Advanced writer with message tracking
writer := tab.NewWriterHandler(&BuildLogWriter{}).Register()
writer.Write([]byte("Build started")) // Creates new message
writer.Write([]byte("Build completed")) // Updates existing message
Key Improvements Over Previous Version
| Feature | Old API | New API | Improvement |
|---|---|---|---|
| Methods Required | 8 methods (FieldHandler + WritingHandler) | 1-3 methods | 60-85% reduction |
| Interface Complexity | Single complex interface | Specialized interfaces | Much more intuitive |
| Boilerplate Code | High (7-8 methods for simple use cases) | Minimal (1-3 methods) | ~75% less code |
| API Clarity | Mixed responsibilities | Clear separation by purpose | Self-documenting |
| Timeout Config | Manual in each handler | Method chaining | Cleaner configuration |
Usage Examples
Complete Server Management Example
// Edit handlers for configuration
type PortHandler struct{ port string }
func (p *PortHandler) Label() string { return "Server Port" }
func (p *PortHandler) Value() string { return p.port }
func (p *PortHandler) Change(newValue any, progress ...func(string)) error {
p.port = newValue.(string)
if len(progress) > 0 {
progress[0]("Port updated: " + p.port)
}
return nil
}
// Action handlers
type StartServerHandler struct{}
func (s *StartServerHandler) Label() string { return "Start Server" }
func (s *StartServerHandler) Execute(progress ...func(string)) error {
if len(progress) > 0 {
progress[0]("Starting server...")
time.Sleep(2*time.Second)
progress[0]("Server started successfully")
}
return nil
}
// Display handlers for status
type StatusHandler struct{}
func (s *StatusHandler) Label() string { return "Server Status" }
func (s *StatusHandler) Content() string { return "Status: Running\nPID: 12345\nUptime: 2h 30m" }
// Usage
tui := devtui.NewTUI(&devtui.TuiConfig{AppName: "ServerManager", ExitChan: make(chan bool)})
tab := tui.NewTabSection("Server", "Management")
tab.NewEditHandler(&PortHandler{port: "8080"}).WithTimeout(2*time.Second)
tab.NewExecutionHandler(&StartServerHandler{}).WithTimeout(10*time.Second)
tab.NewDisplayHandler(&StatusHandler{}).Register()
// Writer for logs
logWriter := tab.NewWriterHandler(&ServerLogWriter{}).Register()
logWriter.Write([]byte("Server management initialized"))
Progress Callback Usage
All handlers receive optional progress callbacks for real-time feedback:
func (h *DeployHandler) Execute(progress ...func(string)) error {
if len(progress) > 0 {
progressCallback := progress[0]
progressCallback("Initiating deployment...")
time.Sleep(500 * time.Millisecond)
progressCallback("Uploading files...")
time.Sleep(1 * time.Second)
progressCallback("Restarting services...")
time.Sleep(500 * time.Millisecond)
progressCallback("Deployment completed successfully")
}
return nil
}
Each progress call updates the same message line, providing smooth real-time feedback.
Navigation
- Tab/Shift+Tab: Switch between tabs
- Left/Right: Navigate fields within tab
- Enter: Edit/Execute
- Esc: Cancel edit
- Ctrl+C: Exit
Migration from v1.x
The new API is a complete redesign. See Migration Guide for upgrading existing code.
Documentation
- API Reference - Complete interface specifications
- Migration Guide - Update existing handlers
Documentation
¶
Index ¶
- type ColorStyle
- type DevTUI
- func (t *DevTUI) AddTabSections(sections ...*tabSection) *DevTUI
- func (h *DevTUI) ContentView() string
- func (t *DevTUI) GetTotalTabSections() int
- func (h *DevTUI) HandleKeyboard(msg tea.KeyMsg) (bool, tea.Cmd)
- func (h *DevTUI) Init() tea.Cmd
- func (t *DevTUI) NewTabSection(title, footer string) *tabSection
- func (h *DevTUI) Print(messages ...any)
- func (t *DevTUI) ReturnFocus() error
- func (h *DevTUI) Start(args ...any)
- func (h *DevTUI) Update(msg tea.Msg) (tea.Model, tea.Cmd)
- func (h *DevTUI) View() string
- type EditHandlerTracker
- type HandlerDisplay
- type HandlerEdit
- type HandlerExecution
- type HandlerTrackerWriter
- type HandlerWriter
- type MessageTracker
- type ShortcutsHandler
- type TuiConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ColorStyle ¶
type DevTUI ¶
type DevTUI struct {
*TuiConfig
// contains filtered or unexported fields
}
DevTUI mantiene el estado de la aplicación
func NewTUI ¶
NewTUI creates a new DevTUI instance and initializes it.
Usage Example:
config := &TuiConfig{
AppName: "MyApp",
TabIndexStart: 0,
ExitChan: make(chan bool),
Color: nil, // or your *ColorStyle
LogToFile: func(err any) { fmt.Println(err) },
}
tui := NewTUI(config)
// Configure your sections and fields:
tui.NewTabSection("My Section", "Description").
NewField("Field1", "value", true, nil)
// Start the TUI:
var wg sync.WaitGroup
wg.Add(1)
go tui.Run(&wg)
wg.Wait()
func (*DevTUI) AddTabSections ¶ added in v0.0.9
AddTabSections adds one or more tabSections to the DevTUI If a tab with title "DEFAULT" exists, it will be replaced by the first tab section Deprecated: Use NewTabSection and append to tabSections directly
func (*DevTUI) ContentView ¶
ContentView renderiza los mensajes para una sección de contenido
func (*DevTUI) GetTotalTabSections ¶ added in v0.0.9
GetTotalTabSections returns the total number of tab sections
func (*DevTUI) HandleKeyboard ¶ added in v0.0.10
HandleKeyboard processes keyboard input and updates the model state returns whether the update function should continue processing or return early
func (*DevTUI) NewTabSection ¶ added in v0.0.43
NewTabSection creates and initializes a new tabSection with the given title and footer NewTabSection creates a new tab section and automatically adds it to the TUI
Example:
tab := tui.NewTabSection("BUILD", "Press enter to compile")
func (*DevTUI) ReturnFocus ¶
func (*DevTUI) Start ¶ added in v0.0.93
Start initializes and runs the terminal UI application.
It accepts optional variadic arguments of any type. If a *sync.WaitGroup is provided among these arguments, Start will call its Done() method before returning.
The method runs the UI using the internal tea engine, and handles any errors that may occur during execution. If an error occurs, it will be displayed on the console and the application will wait for user input before exiting.
Parameters:
- args ...any: Optional arguments. Can include a *sync.WaitGroup for synchronization.
type EditHandlerTracker ¶ added in v0.0.116
type EditHandlerTracker interface {
HandlerEdit
MessageTracker
}
EditHandlerTracker combines HandlerEdit with MessageTracker for advanced edit handlers that need message tracking capabilities.
type HandlerDisplay ¶ added in v0.0.117
type HandlerDisplay interface {
Name() string // Identificador para logging: "HelpDisplay", "StatusMonitor"
Label() string // Display label (e.g., "Help", "Status")
Content() string // Display content (e.g., "help\n1-..\n2-...", "executing deploy wait...")
}
HandlerDisplay defines the interface for read-only information display handlers. These handlers show static or dynamic content without user interaction.
type HandlerEdit ¶ added in v0.0.117
type HandlerEdit interface {
Name() string // Identificador para logging: "ServerPort", "DatabaseURL"
Label() string // Field label (e.g., "Server Port", "Host Configuration")
Value() string // Current/initial value (e.g., "8080", "localhost")
Change(newValue any, progress ...func(string)) error // Sin return string - usar Value() si no hay error
}
HandlerEdit defines the interface for interactive fields that accept user input. These handlers allow users to modify values through text input.
type HandlerExecution ¶ added in v0.0.117
type HandlerExecution interface {
Name() string // Identificador para logging: "DeployProd", "BuildProject"
Label() string // Button label (e.g., "Deploy to Production", "Build Project")
Execute(progress ...func(string)) error
}
HandlerExecution defines the interface for action buttons that execute operations. These handlers trigger business logic when activated by the user.
type HandlerTrackerWriter ¶ added in v0.0.117
type HandlerTrackerWriter interface {
Name() string
MessageTracker
}
HandlerTrackerWriter defines the interface for advanced writers that can update existing lines. These writers support message tracking and can modify previously written content.
type HandlerWriter ¶ added in v0.0.103
type HandlerWriter interface {
Name() string // Writer identifier (e.g., "webBuilder", "ApplicationLog")
}
HandlerWriter defines the interface for basic writers that create new lines for each write. These writers are suitable for simple logging or output display.
type MessageTracker ¶ added in v0.0.116
MessageTracker provides optional interface for message tracking control. Handlers can implement this to control message updates and operation tracking.
type ShortcutsHandler ¶ added in v0.0.96
type ShortcutsHandler struct {
// contains filtered or unexported fields
}
ShortcutsHandler - Shows keyboard navigation instructions
func NewShortcutsHandler ¶ added in v0.0.96
func NewShortcutsHandler() *ShortcutsHandler
func (*ShortcutsHandler) Content ¶ added in v0.0.118
func (h *ShortcutsHandler) Content() string
func (*ShortcutsHandler) Label ¶ added in v0.0.96
func (h *ShortcutsHandler) Label() string
func (*ShortcutsHandler) Name ¶ added in v0.0.103
func (h *ShortcutsHandler) Name() string
type TuiConfig ¶
type TuiConfig struct {
AppName string // app name eg: "MyApp"
TabIndexStart int // is the index of the tab section to start default 0
ExitChan chan bool // global chan to close app eg: make(chan bool)
/*// *ColorStyle style for the TUI
// if nil it will use default style:
type ColorStyle struct {
Foreground string // eg: #F4F4F4
Background string // eg: #000000
Highlight string // eg: #FF6600
Lowlight string // eg: #666666
}*/
Color *ColorStyle
LogToFile func(messages ...any) // function to write log error
TestMode bool // only used in tests to enable synchronous behavior
}
Source Files
Directories