README
¶
barlib
A simple but flexible library for implementing efficient, fast, responsive, and error-tolerant i3status replacements in Go.
- Very flexible immediate-mode API.
- Per-module error handling and error recovery with proper cleanup.
- Multiple blocks per module with custom event handling.
- Memory/CPU efficency.
- Bar stop/continue handling.
- Aligned ticks across all modules with customizable global base tick rate (so the bar sleeps for as long as possible between updates).
- Update coalescing (so the bar updates all at once when multiple modules update at around the same time).
- Implements i3bar protocol version 1 for i3 v4.3+.
Usage
See example_test.go for basic barlib usage, and i3status-custom for example modules I use myself.
Documentation
¶
Overview ¶
Package barlib is a simple but flexible library which allows you to implement efficient, fast, responsive, and error-tolerant i3status replacements in Go.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Main ¶
Main runs the status bar with the provided modules.
Do not use the Block/Event Name field from the modules; this is used internally to differentiate between instantiated modules for events. Use the Event Instance field for handling click events on different blocks differently.
Example ¶
package main
import (
"fmt"
"strconv"
"time"
"github.com/BurntSushi/xgb/xproto"
"github.com/pgaskin/barlib"
"github.com/pgaskin/barlib/barproto"
)
type Example struct {
Text string
Rate time.Duration
}
func (c Example) Run(i barlib.Instance) error {
var (
count int64
paused bool
)
for ticker, isEvent := i.Tick(c.Rate), false; ; {
i.Update(isEvent, func(render barlib.Renderer) {
var color uint32
if paused {
color = 0xFFFF00FF
} else {
color = 0x00FF00FF
}
render(barproto.Block{
Instance: "text",
FullText: c.Text + " ",
Separator: false,
Color: color,
})
switch {
case count < 0:
color = 0x000088FF
case count > 0:
color = 0x008800FF
default:
color = 0x880000FF
}
render(barproto.Block{
Instance: "count",
FullText: strconv.FormatInt(count, 10),
MinWidthString: "0000",
Align: "center",
Separator: true,
Background: color,
BorderLeft: 4,
BorderRight: 4,
Border: color,
})
})
select {
case <-i.Stopped():
i.Debug("stopped=%t", i.IsStopped())
case <-ticker:
if !paused {
count += 1
}
case event := <-i.Event():
switch event.Instance {
case "text":
switch event.Button {
case 1:
paused = !paused
case 2:
return fmt.Errorf("fake error")
case 3:
count = 0
case 4:
i.Tick(c.Rate)
case 5:
i.Tick(c.Rate / 2)
}
case "count":
switch event.Button {
case 1:
if event.Modifiers&xproto.ModMaskShift != 0 {
count--
} else {
count++
}
case 2:
return fmt.Errorf("fake error")
case 3:
count = 0
case 4:
count++
case 5:
count--
}
}
isEvent = true
}
}
}
func main() {
barlib.Main(time.Second/4,
Example{
Text: "A",
Rate: time.Second,
},
Example{
Text: "B",
Rate: time.Second,
},
Example{
Text: "C",
Rate: time.Second / 2,
},
)
}
Output:
Types ¶
type Instance ¶
type Instance interface {
// Tick returns a divided ticker channel, which tries to synchronize ticks
// for all instances to reduce bar updates (the bar waits for a short period
// of time after each tick before re-rendering the bar -- this is currently
// 25ms). The provided duration is not exact must be a multiple of the bar's
// base tick rate. If zero, the ticker does not tick. The returned channel
// has a buffer size of 1 (i.e., missed ticks will trigger as soon as
// possible, but only one missed tick at a time).
Tick(interval time.Duration) <-chan uint64
// TickReset updates the interval for a divided ticker channel.
TickReset(s <-chan uint64, interval time.Duration)
// Update builds and submits an update for the bar. The renderer must only
// be used within the function. If now is true, the new bar will be drawn
// immediately instead of attempting to coalesce draws. The Block.Name field
// is used internally and will be overridden.
Update(now bool, fn func(render Renderer))
// IsStopped checks whether the bar is currently stopped. This is just a
// hint, and doesn't need to be followed.
IsStopped() bool
// Event gets the event channel. Up to 16 events are buffered.
Event() <-chan barproto.Event
// Stopped gets a channel which notifies when IsStopped changes. The buffer
// size is 1 since the actual value is read from IsStopped.
Stopped() <-chan struct{}
// Debug writes debug logs.
Debug(format string, a ...any)
}
Instance provides per-instance functions to interact with the bar.
type Module ¶
type Module interface {
// Run contains the main loop for the module, running indefinitely and
// returning an error if a fatal error occurs.
Run(Instance) error
}
Module is a single immediate-mode status bar module with its own main loop and state. The struct implementing Module should contain stateless read-only configuration, and all state should be contained within Run.
type ModuleFunc ¶
ModuleFunc wraps a function in a Module.
func (ModuleFunc) Run ¶
func (fn ModuleFunc) Run(instance Instance) error
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package barproto implements the i3bar protocol.
|
Package barproto implements the i3bar protocol. |
|
Package i3status-custom is a subset of my personal i3status configuration.
|
Package i3status-custom is a subset of my personal i3status configuration. |
|
Package pulseaudio is a pure-Go client for the PulseAudio native protocol.
|
Package pulseaudio is a pure-Go client for the PulseAudio native protocol. |
|
Package redshift is a minimal pure-go implementation of color temperature shifting using gamma ramps with support for X11.
|
Package redshift is a minimal pure-go implementation of color temperature shifting using gamma ramps with support for X11. |
|
Package xob is a pure-go package for drawing X11 overlay bars.
|
Package xob is a pure-go package for drawing X11 overlay bars. |
Click to show internal directories.
Click to hide internal directories.