skeleton

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 4, 2025 License: GPL-3.0 Imports: 6 Imported by: 0

README

Skeleton

Skeleton is a Go library built on top of the Bubble Tea framework designed to simplify the development of multi-tab terminal user interface (TUI) applications.

Skeleton Go Version Skeleton Go Report Card Skeleton Licence

Skeleton

Features

  • Multi-tab Support: Easily create and manage multiple tabs in your terminal application, similar to browser tabs.
  • Dynamic Widgets: Add and update widgets on the screen, such as battery status, time, or any other information.
  • Simple Integration: Build complex TUI applications with a straightforward and modular approach.
  • Customizable: You can customize every aspect of the tabs and widgets, including key bindings and appearance.
  • Realtime Updates: Updates itself instantly every time the terminal is resized, appearance changes, widgets changes, content changes, etc.
  • Responsive Design: Automatically adjusts the layout based on the terminal size.

Tutorial

Skeleton leverages Bubble Tea's architecture to provide a framework for multi-tab TUI applications. This tutorial assumes you have a working knowledge of Go and Bubble Tea.

For a complete example code, you can refer to the source code on GitHub.

Getting Started

First, you'll need to install Skeleton. Use the following command to get it:

go get github.com/termkit/skeleton
Example Usage

Let's walk through an example of how to use Skeleton to create a basic multi-tab application.

1. Define the Models

We'll start by defining a simple model for our tabs. Each tab will be represented by a tinyModel struct:

package main

import (
	"fmt"
	"strings"

	"github.com/termkit/skeleton"
	"github.com/charmbracelet/bubbles/key"
	tea "github.com/charmbracelet/bubbletea"
)

// -----------------------------------------------------------------------------
// Tiny Model
// The Tiny Model is a sub-model for the tabs. It's a simple model that just shows the title of the tab.

// tinyModel is a sub-model for the tabs
type tinyModel struct {
	skeleton *skeleton.Skeleton
	title    string
}

// newTinyModel returns a new tinyModel
func newTinyModel(skeleton *skeleton.Skeleton, title string) *tinyModel {
	return &tinyModel{
		skeleton: skeleton,
		title:    title,
	}
}

func (m tinyModel) Init() tea.Cmd {
	return nil
}
func (m tinyModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	return m, nil
}
func (m tinyModel) View() string {
	verticalCenter := m.skeleton.GetTerminalHeight()/2 - 3
	requiredNewLines := strings.Repeat("\n", verticalCenter)
	return fmt.Sprintf("%s%s | %d x %d", requiredNewLines, m.title, m.skeleton.GetTerminalWidth(), m.skeleton.GetTerminalHeight())
}
2. Set Up the Application

Initialize Skeleton, add pages, and configure widgets:

// -----------------------------------------------------------------------------
// Main Program
func main() {
	s := skeleton.NewSkeleton()

	// Add tabs (pages)
	s.AddPage("first", "First Tab", newTinyModel(s, "First"))
	s.AddPage("second", "Second Tab", newTinyModel(s, "Second"))
	s.AddPage("third", "Third Tab", newTinyModel(s, "Third"))

	// Set up key bindings ( Optional | Defaults: ctrl+left, ctrl+right )
	//To switch next page
	s.KeyMap.SwitchTabRight = key.NewBinding(
		key.WithKeys("shift+right"))

	// To switch previous page
	s.KeyMap.SwitchTabLeft = key.NewBinding(
		key.WithKeys("shift+left"))

	// Add a widget to entire screen
	s.AddWidget("battery", "Battery %92")
	s.AddWidget("time", time.Now().Format("15:04:05"))

	// Update the time widget every second
	go func() {
		time.Sleep(time.Second)
		for {
			s.UpdateWidgetValue("time", time.Now().Format("15:04:05"))
			time.Sleep(time.Second)
		}
	}()

	p := tea.NewProgram(s)
	if err := p.Start(); err != nil {
		panic(err)
	}
}
Understanding the Code

  1. Model Definition: tinyModel represents the content of each tab. It uses the Skeleton instance to query terminal dimensions and display information.

  2. Application Setup: The main function initializes Skeleton, adds pages, and sets up widgets. The time widget updates every second to reflect the current time.

Examples

The examples directory contains several demonstration applications. See examples for more details.

Skeleton in the Wild

Some programs that use Skeleton in production:

  • gama - Manage your GitHub Actions from Terminal with great UI 🧪

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

License

Distributed under the GNU GENERAL PUBLIC LICENSE Version 3 or later. See LICENSE for more information.

Contact & Author

Engin Açıkgöz

Stargazers over time

Stargazers over time

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AddPageMsg added in v0.1.3 

type AddPageMsg struct {
	// Key is unique key of the page, it is used to identify the page
	Key string

	// Title is the title of the page, it is used to show the title on the header
	Title string

	// Page is the page model, it is used to show the content of the page
	Page tea.Model
}

AddPageMsg adds a new page to the Skeleton.

type DeletePageMsg added in v0.2.0 

type DeletePageMsg struct {
	// Key is unique key of the page to be deleted
	Key string
}

DeletePageMsg is sent when a page is deleted

type HeaderSizeMsg 

type HeaderSizeMsg struct {
	NotEnoughToHandleHeaders bool
}

type IAMActivePage 

type IAMActivePage struct{}

IAMActivePage is a message to trigger the update of the active page.

type Skeleton 

type Skeleton struct {

	// KeyMap responsible for the key bindings
	KeyMap *keyMap
	// contains filtered or unexported fields
}

Skeleton is a helper for rendering the Skeleton of the terminal.

func NewSkeleton 

func NewSkeleton() *Skeleton

NewSkeleton returns a new Skeleton.

func (*Skeleton) AddPage 

func (s *Skeleton) AddPage(key string, title string, page tea.Model) *Skeleton

AddPage adds a new page to the Skeleton.

func (*Skeleton) AddWidget 

func (s *Skeleton) AddWidget(key string, value string) *Skeleton

AddWidget adds a new widget to the Skeleton.

func (*Skeleton) DeleteAllWidgets 

func (s *Skeleton) DeleteAllWidgets() *Skeleton

DeleteAllWidgets deletes all the widgets.

func (*Skeleton) DeletePage 

func (s *Skeleton) DeletePage(key string) *Skeleton

DeletePage deletes the page by the given key.

func (*Skeleton) DeleteWidget 

func (s *Skeleton) DeleteWidget(key string) *Skeleton

DeleteWidget deletes the Value by the given key.

func (*Skeleton) GetActivePage 

func (s *Skeleton) GetActivePage() string

GetActivePage returns the active page key.

func (*Skeleton) GetBorderColor 

func (s *Skeleton) GetBorderColor() string

GetBorderColor returns the border color of the Skeleton.

func (*Skeleton) GetPagePosition 

func (s *Skeleton) GetPagePosition() lipgloss.Position

GetPagePosition returns the position of the page.

func (*Skeleton) GetTerminalHeight 

func (s *Skeleton) GetTerminalHeight() int

GetTerminalHeight returns the height of the terminal.

func (*Skeleton) GetTerminalViewport 

func (s *Skeleton) GetTerminalViewport() *viewport.Model

GetTerminalViewport returns the viewport.

func (*Skeleton) GetTerminalWidth 

func (s *Skeleton) GetTerminalWidth() int

GetTerminalWidth returns the width of the terminal.

func (*Skeleton) GetWidgetBorderColor 

func (s *Skeleton) GetWidgetBorderColor() string

GetWidgetBorderColor returns the border color of the Widget.

func (*Skeleton) IAMActivePageCmd 

func (s *Skeleton) IAMActivePageCmd() tea.Cmd

IAMActivePageCmd returns the IAMActivePage command.

func (*Skeleton) Init 

func (s *Skeleton) Init() tea.Cmd

func (*Skeleton) IsTabLocked added in v0.2.0 

func (s *Skeleton) IsTabLocked(key string) bool

IsTabLocked checks if a specific tab is locked

func (*Skeleton) IsTabsLocked 

func (s *Skeleton) IsTabsLocked() bool

IsTabsLocked returns the tabs (headers) are locked or not.

func (*Skeleton) LockTab added in v0.2.0 

func (s *Skeleton) LockTab(key string) *Skeleton

LockTab locks a specific tab by its key

func (*Skeleton) LockTabs 

func (s *Skeleton) LockTabs() *Skeleton

LockTabs locks the tabs (headers). It prevents switching tabs. It is useful when you want to prevent switching tabs.

func (*Skeleton) LockTabsToTheLeft added in v0.2.0 

func (s *Skeleton) LockTabsToTheLeft() *Skeleton

LockTabsToTheLeft locks all tabs to the left of the current tab

func (*Skeleton) LockTabsToTheRight added in v0.2.0 

func (s *Skeleton) LockTabsToTheRight() *Skeleton

LockTabsToTheRight locks all tabs to the right of the current tab

func (*Skeleton) SetActivePage 

func (s *Skeleton) SetActivePage(key string) *Skeleton

SetActivePage sets the active page by the given key.

func (*Skeleton) SetActiveTabBorderColor 

func (s *Skeleton) SetActiveTabBorderColor(color string) *Skeleton

SetActiveTabBorderColor sets the active tab border color of the Skeleton.

func (*Skeleton) SetActiveTabTextColor 

func (s *Skeleton) SetActiveTabTextColor(color string) *Skeleton

SetActiveTabTextColor sets the active tab color of the Skeleton.

func (*Skeleton) SetBorderColor 

func (s *Skeleton) SetBorderColor(color string) *Skeleton

SetBorderColor sets the border color of the Skeleton.

func (*Skeleton) SetInactiveTabBorderColor 

func (s *Skeleton) SetInactiveTabBorderColor(color string) *Skeleton

SetInactiveTabBorderColor sets the idle tab border color of the Skeleton.

func (*Skeleton) SetInactiveTabTextColor 

func (s *Skeleton) SetInactiveTabTextColor(color string) *Skeleton

SetInactiveTabTextColor sets the idle tab color of the Skeleton.

func (*Skeleton) SetPagePosition 

func (s *Skeleton) SetPagePosition(position lipgloss.Position) *Skeleton

SetPagePosition sets the position of the page.

func (*Skeleton) SetTabLeftPadding 

func (s *Skeleton) SetTabLeftPadding(padding int) *Skeleton

SetTabLeftPadding sets the left padding of the Skeleton.

func (*Skeleton) SetTabRightPadding 

func (s *Skeleton) SetTabRightPadding(padding int) *Skeleton

SetTabRightPadding sets the right padding of the Skeleton.

func (*Skeleton) SetTerminalViewportHeight 

func (s *Skeleton) SetTerminalViewportHeight(height int)

SetTerminalViewportHeight sets the height of the viewport.

func (*Skeleton) SetTerminalViewportWidth 

func (s *Skeleton) SetTerminalViewportWidth(width int)

SetTerminalViewportWidth sets the width of the viewport.

func (*Skeleton) SetWidgetBorderColor 

func (s *Skeleton) SetWidgetBorderColor(color string) *Skeleton

SetWidgetBorderColor sets the border color of the Widget.

func (*Skeleton) SetWidgetLeftPadding 

func (s *Skeleton) SetWidgetLeftPadding(padding int) *Skeleton

SetWidgetLeftPadding sets the left padding of the Skeleton.

func (*Skeleton) SetWidgetRightPadding 

func (s *Skeleton) SetWidgetRightPadding(padding int) *Skeleton

SetWidgetRightPadding sets the right padding of the Skeleton.

func (*Skeleton) TriggerUpdate added in v0.1.3 

func (s *Skeleton) TriggerUpdate()

func (*Skeleton) TriggerUpdateWithMsg added in v0.1.3 

func (s *Skeleton) TriggerUpdateWithMsg(msg tea.Msg)

func (*Skeleton) UnlockTab added in v0.2.0 

func (s *Skeleton) UnlockTab(key string) *Skeleton

UnlockTab unlocks a specific tab by its key

func (*Skeleton) UnlockTabs 

func (s *Skeleton) UnlockTabs() *Skeleton

UnlockTabs unlocks all tabs (both general and individual locks)

func (*Skeleton) Update 

func (s *Skeleton) Update(msg tea.Msg) (tea.Model, tea.Cmd)

func (*Skeleton) UpdatePageTitle 

func (s *Skeleton) UpdatePageTitle(key string, title string) *Skeleton

UpdatePageTitle updates the title of the page by the given key.

func (*Skeleton) UpdateWidgetValue 

func (s *Skeleton) UpdateWidgetValue(key string, value string) *Skeleton

UpdateWidgetValue updates the Value content by the given key. Adds the widget if it doesn't exist.

func (*Skeleton) View 

func (s *Skeleton) View() string

type UpdateMsg added in v0.1.3 

type UpdateMsg struct{}
var UpdateMsgInstance UpdateMsg

type Updater added in v0.1.3 

type Updater struct {
	// contains filtered or unexported fields
}

func NewUpdater added in v0.1.3 

func NewUpdater() *Updater

func (*Updater) Listen added in v0.1.3 

func (u *Updater) Listen() tea.Cmd

func (*Updater) Update added in v0.1.3 

func (u *Updater) Update()

func (*Updater) UpdateWithMsg added in v0.1.3 

func (u *Updater) UpdateWithMsg(msg any)

type WidgetSizeMsg 

type WidgetSizeMsg struct {
	NotEnoughToHandleWidgets bool
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.