Index | Files

package bar

import ""

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


Package Files

bar.go segment.go sink.go


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")

type Button Uses

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 Uses

type ErrorEvent struct {
    Error error

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 Uses

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 Uses

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.

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

type Output Uses

type Output interface {
    Segments() []*Segment

Output is an interface for displaying objects on the bar.

type RefresherModule Uses

type RefresherModule interface {

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 Uses

type Segment struct {
    // contains filtered or unexported fields

Segment is a single "block" of output that conforms to the i3bar protocol. See 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 Uses

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 Uses

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

func TextSegment Uses

func TextSegment(text string) *Segment

TextSegment creates a new output segment with text content.

func (*Segment) Align Uses

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

Align sets the text alignment within the segment.

func (*Segment) Background Uses

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

Background sets the background color for the segment.

func (*Segment) Border Uses

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

Border sets the border color for the segment.

func (*Segment) Click Uses

func (s *Segment) Click(e Event)

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

func (*Segment) Clone Uses

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 Uses

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

Color sets the foreground color for the segment.

func (*Segment) Content Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

MinWidth sets the minimum width for the segment.

func (*Segment) MinWidthPlaceholder Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

Segments implements bar.Output for a single Segment.

func (*Segment) Separator Uses

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

Separator controls whether this *Segment has a separator.

func (*Segment) ShortText Uses

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 Uses

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 Uses

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

Urgent sets the urgency of the segment.

type Segments Uses

type Segments []*Segment

Segments implements Output for []*Segment.

func (Segments) Segments Uses

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

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

type Sink Uses

type Sink func(Output)

Sink represents a destination for module output.

func (Sink) Error Uses

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 Uses

func (s Sink) Output(o Output)

Output updates the module's output on the bar.

type TextAlignment Uses

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 Uses

type TimedOutput interface {
    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.

Package bar imports 2 packages (graph) and is imported by 61 packages. Updated 2018-11-25. Refresh now. Tools for package owners.