bar

Documentation

Overview

Package bar allows a user to create a go binary that follows the i3bar protocol.

Index

• Constants
• type Button
• type ErrorEvent
• type Event
• type Module
• type Output
• type RefresherModule
• type Segment
  • func ErrorSegment(e error) *Segment
  • func PangoSegment(text string) *Segment
  • func TextSegment(text string) *Segment
  • func (s *Segment) Align(align TextAlignment) *Segment
  • func (s *Segment) Background(background color.Color) *Segment
  • func (s *Segment) Border(border color.Color) *Segment
  • func (s *Segment) Click(e Event)
  • func (s *Segment) Clone() *Segment
  • func (s *Segment) Color(color color.Color) *Segment
  • func (s *Segment) Content() (text string, isPango bool)
  • func (s *Segment) Error(err error) *Segment
  • func (s *Segment) GetAlignment() (TextAlignment, bool)
  • func (s *Segment) GetBackground() (color.Color, bool)
  • func (s *Segment) GetBorder() (color.Color, bool)
  • func (s *Segment) GetColor() (color.Color, bool)
  • func (s *Segment) GetError() error
  • func (s *Segment) GetMinWidth() (interface{}, bool)
  • func (s *Segment) GetPadding() (int, bool)
  • func (s *Segment) GetShortText() (string, bool)
  • func (s *Segment) HasClick() bool
  • func (s *Segment) HasSeparator() (bool, bool)
  • func (s *Segment) IsUrgent() (bool, bool)
  • func (s *Segment) MinWidth(minWidth int) *Segment
  • func (s *Segment) MinWidthPlaceholder(placeholder string) *Segment
  • func (s *Segment) OnClick(fn func(Event)) *Segment
  • func (s *Segment) Padding(padding int) *Segment
  • func (s *Segment) Pango(content string) *Segment
  • func (s *Segment) Segments() []*Segment
  • func (s *Segment) Separator(separator bool) *Segment
  • func (s *Segment) ShortText(shortText string) *Segment
  • func (s *Segment) Text(content string) *Segment
  • func (s *Segment) Urgent(urgent bool) *Segment
• type Segments
  • func (s Segments) Segments() []*Segment
• type Sink
  • func (s Sink) Error(e error) bool
  • func (s Sink) Output(o Output)
• type TextAlignment
• type TimedOutput

Constants

const (
	// AlignStart aligns text to the start of the module, which is left for LTR languages.
	AlignStart = TextAlignment("left")
	// AlignCenter aligns text to the middle of the module.
	AlignCenter = TextAlignment("center")
	// AlignEnd aligns text to the end of the module, which is right for LTR languages.
	AlignEnd = TextAlignment("right")
)

Types

type Button

type Button int

Button represents an X11 mouse button.

const (
	// ButtonLeft is the left mouse button.
	ButtonLeft Button = 1
	// ButtonRight is the right mouse button.
	ButtonRight Button = 3
	// ButtonMiddle is the middle mouse button, sometimes the scroll-wheel.
	ButtonMiddle Button = 2
	// ButtonBack is the "back" button, usually on the side.
	ButtonBack Button = 8
	// ButtonForward is the "forward" button, usually next to the back button.
	ButtonForward Button = 9

	// ScrollUp on the mouse wheel.
	ScrollUp Button = 4
	// ScrollDown on the mouse wheel.
	ScrollDown Button = 5
	// ScrollLeft or tilt left on the mouse wheel.
	ScrollLeft Button = 6
	// ScrollRight or tilt right on the mouse wheel.
	ScrollRight Button = 7
)

type ErrorEvent

type ErrorEvent struct {
	Error error
	Event
}

ErrorEvent represents a mouse event that triggered the error handler. This is fired when an error segment is right clicked. The default handler for ErrorEvents simply shows an i3-nagbar with the full error text.

Since the Event that triggered the error handler is also embedded, error handlers have information about the position of the module and can choose to display more contextual messages than a simple bar across the entire screen.

type Event

type Event struct {
	Button  Button `json:"button"`
	X       int    `json:"relative_x,omitempty"`
	Y       int    `json:"relative_y,omitempty"`
	Width   int    `json:"width,omitempty"`
	Height  int    `json:"height,omitempty"`
	ScreenX int    `json:"x,omitempty"`
	ScreenY int    `json:"y,omitempty"`
}

Event represents a mouse event meant for a single module.

Note: As before, name is not included because it's only required to determine which module will handle an event from i3. Once the bar receives the event, it provides only the information in this struct to individual modules.

The SegmentID is set to the Identifier of the output segment clicked, so it can be used to filter events for a module with multiple output segments.

X, Y describe event co-ordinates relative to the output segment, and Width, Height are set to the size of the output segment.

ScreenX, ScreenY are the event co-ordinates relative to the root window.

type Module

type Module interface {
	// Stream runs the main loop of a module, pushing updated outputs to
	// the provided Sink.
	// A module is considered active until Stream() returns, at which point
	// a click will restart the module by calling Stream() again.
	// The Sink passed to Stream is only valid for the one call to Stream;
	// subsequent calls may receive different instances.
	Stream(Sink)
}

Module represents a single bar module. A bar is just a list of modules.

type Output

type Output interface {
	Segments() []*Segment
}

Output is an interface for displaying objects on the bar.

type RefresherModule

type RefresherModule interface {
	Module
	Refresh()
}

RefresherModule extends module with a Refresh() method that forces a refresh of the data being displayed (e.g. a fresh HTTP request or file read). core.Module will add middle-click to refresh for modules that implement it.

type Segment

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

Segment is a single "block" of output that conforms to the i3bar protocol. See https://i3wm.org/docs/i3bar-protocol.html#_blocks_in_detail for details.

Note: Name is not included because only the bar needs to know the name in order to dispatch click events and maintain the output cache. Multiple segments can still use the identifier to map click events to output segments. The bar will map the unmodified identifier to i3bar's "instance", and set the value from the clicked segment as the SegmentID of the generated event.

See segment.go for supported methods. All fields are unexported to make sure that when setting a field, the attrSet mask is also updated.

func ErrorSegment

func ErrorSegment(e error) *Segment

ErrorSegment creates a new output segment that displays an error. On the bar itself, it's an urgent segment showing 'Error' or '!' based on available space, but the full error will be shown using i3-nagbar when the segment is right-clicked.

func PangoSegment

func PangoSegment(text string) *Segment

PangoSegment creates a new output segment with content that uses pango markup for formatting. Not all features may be supported. See https://developer.gnome.org/pango/stable/PangoMarkupFormat.html.

func TextSegment

func TextSegment(text string) *Segment

TextSegment creates a new output segment with text content.

func (*Segment) Align

func (s *Segment) Align(align TextAlignment) *Segment

Align sets the text alignment within the segment.

func (*Segment) Background

func (s *Segment) Background(background color.Color) *Segment

Background sets the background color for the segment.

func (*Segment) Border

func (s *Segment) Border(border color.Color) *Segment

Border sets the border color for the segment.

func (*Segment) Click

func (s *Segment) Click(e Event)

Click calls a previously set click handler with the given Event.

func (*Segment) Clone

func (s *Segment) Clone() *Segment

Clone makes a copy of the Segment that can be modified without the changes being reflected in the original.

func (*Segment) Color

func (s *Segment) Color(color color.Color) *Segment

Color sets the foreground color for the segment.

func (*Segment) Content

func (s *Segment) Content() (text string, isPango bool)

Content returns the text content of the segment, and whether or not it is using pango markup.

func (*Segment) Error

func (s *Segment) Error(err error) *Segment

Error associates an error with the segment. Setting an error changes event handling to display the full error text on left click, and restart the module on right/middle click. (If the module is still running, right/middle click is a no-op).

func (*Segment) GetAlignment

func (s *Segment) GetAlignment() (TextAlignment, bool)

GetAlignment returns the text alignment of this segment. The second value indicates whether it was explicitly set.

func (*Segment) GetBackground

func (s *Segment) GetBackground() (color.Color, bool)

GetBackground returns the background color of this segment. The second value indicates whether it was explicitly set.

func (*Segment) GetBorder

func (s *Segment) GetBorder() (color.Color, bool)

GetBorder returns the border color of this segment. The second value indicates whether it was explicitly set.

func (*Segment) GetColor

func (s *Segment) GetColor() (color.Color, bool)

GetColor returns the foreground color of this segment. The second value indicates whether it was explicitly set.

func (*Segment) GetError

func (s *Segment) GetError() error

GetError returns any error associated with this segment or nil if no error is associated with this segment.

func (*Segment) GetMinWidth

func (s *Segment) GetMinWidth() (interface{}, bool)

GetMinWidth returns the minimum width of this segment. The returned value will either be an int or a string, based on how it was originally set. The second value indicates whether it was explicitly set.

func (*Segment) GetPadding

func (s *Segment) GetPadding() (int, bool)

GetPadding returns the padding at the end of this segment. The second value indicates whether it was explicitly set. This maps to "separator_block_width" in i3.

func (*Segment) GetShortText

func (s *Segment) GetShortText() (string, bool)

GetShortText returns the short text of this segment. The second value indicates whether it was explicitly set.

func (*Segment) HasClick

func (s *Segment) HasClick() bool

HasClick returns whether this segment has a click handler defined. Modules can use this check to assign default handlers to segments where the user has not already assigned a click handler.

func (*Segment) HasSeparator

func (s *Segment) HasSeparator() (bool, bool)

HasSeparator returns true if the segment has a separator. The second value indicates whether it was explicitly set.

func (*Segment) IsUrgent

func (s *Segment) IsUrgent() (bool, bool)

IsUrgent returns true if this segment is marked urgent. The second value indicates whether it was explicitly set.

func (*Segment) MinWidth

func (s *Segment) MinWidth(minWidth int) *Segment

MinWidth sets the minimum width for the segment.

func (*Segment) MinWidthPlaceholder

func (s *Segment) MinWidthPlaceholder(placeholder string) *Segment

MinWidthPlaceholder sets the minimum width of the segment such that the placeholder string will fit.

func (*Segment) OnClick

func (s *Segment) OnClick(fn func(Event)) *Segment

OnClick sets a function to be called when the segment is clicked. A nil function is treated as equivalent to func(Event) {}, which means CanClick() will return true, but Click(Event) will do nothing. Nil can therefore be used to prevent module-level default handlers from being attached to a segment.

func (*Segment) Padding

func (s *Segment) Padding(padding int) *Segment

Padding sets the padding at the end of this segment. The separator (if displayed) will be centred within the padding.

func (*Segment) Pango

func (s *Segment) Pango(content string) *Segment

Pango sets the pango content of this segment. It clears any previous content and sets the markup style to pango.

func (*Segment) Segments

func (s *Segment) Segments() []*Segment

Segments implements bar.Output for a single Segment.

func (*Segment) Separator

func (s *Segment) Separator(separator bool) *Segment

Separator controls whether this *Segment has a separator.

func (*Segment) ShortText

func (s *Segment) ShortText(shortText string) *Segment

ShortText sets the shortened text, used if the default text for all segments does not fit in the bar.

func (*Segment) Text

func (s *Segment) Text(content string) *Segment

Text sets the text content of this segment. It clears any previous content and resets the markup style.

func (*Segment) Urgent

func (s *Segment) Urgent(urgent bool) *Segment

Urgent sets the urgency of the segment.

type Segments

type Segments []*Segment

Segments implements Output for []*Segment.

func (Segments) Segments

func (s Segments) Segments() []*Segment

Segments returns the list of segments as a bar.Output.

type Sink

type Sink func(Output)

Sink represents a destination for module output.

func (Sink) Error

func (s Sink) Error(e error) bool

Error is a convenience method that returns false and does nothing when given a nil error, and outputs an error segment and returns true when a non-nil error is given.

func (Sink) Output

func (s Sink) Output(o Output)

Output updates the module's output on the bar.

type TextAlignment

type TextAlignment string

TextAlignment defines the alignment of text within a block. Using TextAlignment rather than string opens up the possibility of i18n without requiring each module to know the current locale.

type TimedOutput

type TimedOutput interface {
	Output
	NextRefresh() time.Time
}

TimedOutput extends bar.Output with a hint that indicates the next time that the output segments will be different. This can be used, for example, to show elapsed duration since a fixed point in time.