winman

package module
v0.0.0-...-2f50ef9 Latest Latest
Warning

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

 Go to latest Published: Nov 6, 2020 License: MIT Imports: 4 Imported by: 0

README

Winman - go Window Manager for terminal UIs

Go Report Godoc Reference

Winman is a basic yet powerful window manager in go for terminal-based user interfaces that plugs into tview.

Screenshot

It supports floating windows that can be dragged, resized and maximized. Windows can have buttons on the title bar, for example to close them, help commands or maximize / minimize.

Windows can also be modal, meaning that other windows don't receive input while a modal window is on top. You can control whether the user can drag or resize windows around the screen.

Windows can overlap each other by setting their Z-index. Any tview.Primitive can be added to a window, thus you can combine with any other existing tview widget! Check tview for a complete list of available widgets you can use.

Installation

go get github.com/r3ap3r2004/winman

Hello world

package main

import (
	"github.com/r3ap3r2004/winman"
	"github.com/rivo/tview"
)

func main() {

	app := tview.NewApplication()
	wm := winman.NewWindowManager()

	content := tview.NewTextView().
		SetText("Hello, world!").       // set content of the text view
		SetTextAlign(tview.AlignCenter) // align text to the center of the text view

	window := wm.NewWindow(). // create new window and add it to the window manager
					Show().                   // make window visible
					SetRoot(content).         // have the text view above be the content of the window
					SetDraggable(true).       // make window draggable around the screen
					SetResizable(true).       // make the window resizable
					SetTitle("Hi!").          // set the window title
					AddButton(&winman.Button{ // create a button with an X to close the application
			Symbol:  'X',
			OnClick: func() { app.Stop() }, // close the application
		})

	window.SetRect(5, 5, 30, 10) // place the window

	// now, execute the application:
	if err := app.SetRoot(wm, true).EnableMouse(true).Run(); err != nil {
		panic(err)
	}
}

hello world

Documentation

Refer to https://pkg.go.dev/github.com/r3ap3r2004/winman for the package's documentation. The demos directory contains a showcase demonstrating the different aspects of this library

Dependencies

This package works with tview and its dependencies.

Your Feedback

Add your issue here on GitHub. Feel free to get in touch if you have any questions.

Author(s)

This package is written and maintained by Javier Peletier (@jpeletier) - Epic Labs

Documentation

Overview

Package winman implements a basic yet powerful window manager that can be used with tview (github.com/rivo/tview).

It supports floating windows that can be dragged, resized and maximized. Windows can have buttons on the title bar, for example to close them, help commands or maximize / minimize.

Windows can also be modal, meaning that other windows don't receive input while a modal window is on top.

You can control whether the user can drag or resize windows around the screen.

Windows can overlap each other by setting their Z-index

Any tview.Primitive can be added to a window.

Index

Constants

View Source 
const (
	// ButtonLeft will set the button to be drawn on the left
	ButtonLeft = iota
	// ButtonRight will set the button to be drawn on the right
	ButtonRight
)
View Source 
const WindowZBottom = 0

WindowZBottom is used with SetZ to move a window to the bottom

View Source 
const WindowZTop = -1

WindowZTop is used with SetZ to move a window to the top

Variables

View Source 
var MinWindowHeight = 3

MinWindowHeight sets the minimum height a window can have as part of a window manager

View Source 
var MinWindowWidth = 3

MinWindowWidth sets the minimum width a window can have as part of a window manager

Functions

This section is empty.

Types

type Button 

type Button struct {
	Symbol rune // icon for the button

	Alignment ButtonSide // alignment of the button, left or right
	OnClick   func()     // callback to be invoked when the button is clicked
	// contains filtered or unexported fields
}

Button represents a button on the window title bar

type ButtonSide 

type ButtonSide int16

ButtonSide determines the alignment of a window button

type ClipRegion 

type ClipRegion struct {
	tcell.Screen
	// contains filtered or unexported fields
}

ClipRegion implements tcell.Screen and only allows setting content within a defined region

func NewClipRegion 

func NewClipRegion(screen tcell.Screen, x, y, width, height int) *ClipRegion

NewClipRegion Creates a new clipped screen with the given rectangular coordinates

func (*ClipRegion) Clear 

func (cr *ClipRegion) Clear()

Clear clears the clipped region

func (*ClipRegion) Fill 

func (cr *ClipRegion) Fill(ch rune, style tcell.Style)

Fill implements tcell.Screen.Fill

func (*ClipRegion) InRect 

func (cr *ClipRegion) InRect(x, y int) bool

InRect returns true if the given coordinates are within this clipped region

func (*ClipRegion) SetCell 

func (cr *ClipRegion) SetCell(x int, y int, style tcell.Style, ch ...rune)

SetCell is an older API, and will be removed. Please use SetContent instead; SetCell is implemented in terms of SetContent.

func (*ClipRegion) SetContent 

func (cr *ClipRegion) SetContent(x int, y int, mainc rune, combc []rune, style tcell.Style)

SetContent sets the contents of the given cell location. If the coordinates are out of range, then the operation is ignored.

The first rune is the primary non-zero width rune. The array that follows is a possible list of combining characters to append, and will usually be nil (no combining characters.)

The results are not displayed until Show() or Sync() is called.

Note that wide (East Asian full width) runes occupy two cells, and attempts to place character at next cell to the right will have undefined effects. Wide runes that are printed in the last column will be replaced with a single width space on output.

func (*ClipRegion) ShowCursor 

func (cr *ClipRegion) ShowCursor(x int, y int)

ShowCursor is used to display the cursor at a given location. If the coordinates -1, -1 are given or are otherwise outside the dimensions of the screen, the cursor will be hidden.

type Manager 

type Manager struct {
	*tview.Box

	sync.Mutex
	// contains filtered or unexported fields
}

Manager represents a Window Manager primitive

func NewWindowManager 

func NewWindowManager() *Manager

NewWindowManager returns a ready to use window manager

func (*Manager) AddWindow 

func (wm *Manager) AddWindow(window Window) *Manager

AddWindow adds the given window to the window manager

func (*Manager) Center 

func (wm *Manager) Center(window Window) *Manager

Center centers the given window relative to the window manager

func (*Manager) Draw 

func (wm *Manager) Draw(screen tcell.Screen)

Draw draws this primitive onto the screen. implements tview.Primitive.Draw

func (*Manager) Focus 

func (wm *Manager) Focus(delegate func(p tview.Primitive))

Focus is called when this primitive receives focus implements tview.Primitive.Focus

func (*Manager) GetZ 

func (wm *Manager) GetZ(window Window) int

GetZ returns the z index of the given window returns -1 if the given window is not part of this manager

func (*Manager) HasFocus 

func (wm *Manager) HasFocus() bool

HasFocus returns whether or not this primitive has focus. implements tview.Focusable

func (*Manager) MouseHandler 

func (wm *Manager) MouseHandler() func(action tview.MouseAction, event *tcell.EventMouse, setFocus func(p tview.Primitive)) (consumed bool, capture tview.Primitive)

MouseHandler returns the mouse handler for this primitive. implements tview.Primitive.MouseHandler

func (*Manager) NewWindow 

func (wm *Manager) NewWindow() *WindowBase

NewWindow creates a new (hidden) window and adds it to this window manager

func (*Manager) RemoveWindow 

func (wm *Manager) RemoveWindow(window Window) *Manager

RemoveWindow removes the given window from this window manager

func (*Manager) SetZ 

func (wm *Manager) SetZ(window Window, newZ int) *Manager

SetZ moves the given window to the given z index The special constants WindowZTop and WindowZBottom can be used

func (*Manager) Window 

func (wm *Manager) Window(z int) Window

Window returns the window at the given z index

func (*Manager) WindowCount 

func (wm *Manager) WindowCount() int

WindowCount returns the number of windows managed by this window manager

type Rect 

type Rect struct {
	X int // x coordinate
	Y int // y coordinate
	W int // width
	H int // height
}

Rect represents rectangular coordinates

func NewRect 

func NewRect(x, y, w, h int) Rect

NewRect instantiates a new Rect with the given coordinates

func (Rect) Contains 

func (r Rect) Contains(x, y int) bool

Contains returns true if the given coordinates are within this rectangle

func (*Rect) Rect 

func (r *Rect) Rect() (int, int, int, int)

Rect returns the four coordinates of the rectangle: x, y, width and height

func (Rect) String 

func (r Rect) String() string

String implements Stringer

type Stack 

type Stack []interface{}

Stack represents a stack of unique items

func (Stack) Find 

func (s Stack) Find(f func(item interface{}) bool) interface{}

Find searches the stack top down for an item that meets the custom criteria specified by the passed function

func (Stack) IndexOf 

func (s Stack) IndexOf(searchItem interface{}) int

IndexOf searches the stack for the given item and returns its index

func (Stack) Item 

func (s Stack) Item(i int) interface{}

Item returns the given item from the stack returns nil if the index is out of bounds

func (*Stack) Move 

func (s *Stack) Move(item interface{}, targetIndex int)

Move finds an item in the stack and places it at the given index, shifting items up or down to make space

func (*Stack) Pop 

func (s *Stack) Pop() interface{}

Pop pops the stack returning and removing the topmost element

func (*Stack) Push 

func (s *Stack) Push(newItem interface{})

Push puts an element on the stack if the item is already in the stack, this operation does nothing

func (*Stack) Remove 

func (s *Stack) Remove(item interface{})

Remove removes the given item from the stack if the item does not exist, this function does nothing

type Window 

type Window interface {
	tview.Primitive
	// IsModal defines this window as modal. When a window is modal, input cannot go to other windows
	IsModal() bool

	// HasFocus returns true when this window has the focus
	HasFocus() bool

	// IsMaximized returns true when the window is maximized and takes all the space available to the
	// Window Manager
	IsMaximized() bool

	// IsResizable returns true when the window can be resized by the user
	IsResizable() bool

	// IsDraggable returns true when the window can be moved by the user by dragging
	// the title bar
	IsDraggable() bool

	// IsVisible returns true when the window has to be drawn and can receive focus
	IsVisible() bool

	// HasBorder returns true if the window must have a border
	HasBorder() bool
}

Window interface defines primitives that can be managed by the Window Manager

type WindowBase 

type WindowBase struct {
	*tview.Box

	Draggable bool //whether this window can be dragged around with the mouse
	Resizable bool // whether this window is user-resizable
	Modal     bool // whether this window is modal
	Visible   bool // whether this window is rendered
	// contains filtered or unexported fields
}

WindowBase defines a basic window

func NewWindow 

func NewWindow() *WindowBase

NewWindow creates a new window

func (*WindowBase) AddButton 

func (w *WindowBase) AddButton(button *Button) *WindowBase

AddButton adds a new window button to the title bar

func (*WindowBase) ButtonCount 

func (w *WindowBase) ButtonCount() int

ButtonCount returns the number of buttons in the window title bar

func (*WindowBase) Draw 

func (w *WindowBase) Draw(screen tcell.Screen)

Draw draws this primitive on to the screen

func (*WindowBase) Focus 

func (w *WindowBase) Focus(delegate func(p tview.Primitive))

Focus is called when this primitive receives focus.

func (*WindowBase) GetButton 

func (w *WindowBase) GetButton(i int) *Button

GetButton returns the given button

func (*WindowBase) GetRoot 

func (w *WindowBase) GetRoot() tview.Primitive

GetRoot returns the primitive that represents the main content of the window

func (*WindowBase) HasBorder 

func (w *WindowBase) HasBorder() bool

HasBorder returns true if this window has a border windows without border cannot be resized or dragged by the user

func (*WindowBase) HasFocus 

func (w *WindowBase) HasFocus() bool

HasFocus returns whether or not this primitive has focus.

func (*WindowBase) Hide 

func (w *WindowBase) Hide() *WindowBase

Hide hides this window

func (*WindowBase) IsDraggable 

func (w *WindowBase) IsDraggable() bool

IsDraggable returns true if this window can be dragged by the user

func (*WindowBase) IsMaximized 

func (w *WindowBase) IsMaximized() bool

IsMaximized returns true if this window is maximized

func (*WindowBase) IsModal 

func (w *WindowBase) IsModal() bool

IsModal returns true if this window is modal

func (*WindowBase) IsResizable 

func (w *WindowBase) IsResizable() bool

IsResizable returns true if the user may resize this window

func (*WindowBase) IsVisible 

func (w *WindowBase) IsVisible() bool

IsVisible returns true if this window is rendered and may get focus

func (*WindowBase) Maximize 

func (w *WindowBase) Maximize() *WindowBase

Maximize signals the window manager to resize this window to the maximum size available

func (*WindowBase) MouseHandler 

func (w *WindowBase) MouseHandler() func(action tview.MouseAction, event *tcell.EventMouse, setFocus func(p tview.Primitive)) (consumed bool, capture tview.Primitive)

MouseHandler returns a mouse handler for this primitive

func (*WindowBase) Restore 

func (w *WindowBase) Restore() *WindowBase

Restore restores the window to the size it had before maximizing

func (*WindowBase) SetBorder 

func (w *WindowBase) SetBorder(show bool) *WindowBase

SetBorder sets the flag indicating whether or not the box should have a border.

func (*WindowBase) SetDraggable 

func (w *WindowBase) SetDraggable(draggable bool) *WindowBase

SetDraggable sets if this window can be dragged by the user

func (*WindowBase) SetModal 

func (w *WindowBase) SetModal(modal bool) *WindowBase

SetModal makes this window modal. A modal window captures all input

func (*WindowBase) SetResizable 

func (w *WindowBase) SetResizable(resizable bool) *WindowBase

SetResizable sets if this window can be resized

func (*WindowBase) SetRoot 

func (w *WindowBase) SetRoot(root tview.Primitive) *WindowBase

SetRoot sets the main content of the window

func (*WindowBase) SetTitle 

func (w *WindowBase) SetTitle(text string) *WindowBase

SetTitle sets the window title

func (*WindowBase) Show 

func (w *WindowBase) Show() *WindowBase

Show makes the window visible

type WindowEdge 

type WindowEdge int16

WindowEdge enumerates the different window edges and corners 

const (
	EdgeNone WindowEdge = iota
	EdgeTop
	EdgeRight
	EdgeBottom
	EdgeLeft
	EdgeBottomRight
	EdgeBottomLeft
)

Different window edges

Source Files

View all Source files

Directories

Path Synopsis
demos
helloworld
showcase
Demo code for the Form primitive.
 Demo code for the Form primitive.

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.