braille

Documentation

Overview

Package braille provides a canvas that uses braille characters.

This is inspired by https://github.com/asciimoo/drawille.

The braille patterns documentation: http://www.alanwood.net/unicode/braille_patterns.html

The use of braille characters gives additional points (higher resolution) on the canvas, each character cell now has eight pixels that can be set independently. Specifically each cell has the following pixels, the axes grow right and down.

Each cell:

X→ 0 1  Y
  ┌───┐ ↓
  │● ●│ 0
  │● ●│ 1
  │● ●│ 2
  │● ●│ 3
  └───┘

When using the braille canvas, the coordinates address the sub-cell points rather then cells themselves. However all points in the cell still share the same cell options.

Example (AppliedToTerminal)

// When working with a terminal directly:
ft, err := faketerm.New(image.Point{3, 3})
if err != nil {
	panic(err)
}

// The widget can create a braille canvas with the same or smaller area:
braille, err := New(ft.Area())
if err != nil {
	panic(err)
}

// After setting / clearing / toggling of pixels on the braille canvas, it
// can be applied to the terminal.
if err := braille.SetPixel(image.Point{0, 0}); err != nil {
	panic(err)
}
if err := braille.Apply(ft); err != nil {
	panic(err)
}

Example (CopiedToCanvas)

// Given a parent canvas the widget receives from the infrastructure:
parent, err := canvas.New(image.Rect(0, 0, 3, 3))
if err != nil {
	panic(err)
}

// The widget can create a braille canvas with the same or smaller area:
braille, err := New(parent.Area())
if err != nil {
	panic(err)
}

// After setting / clearing / toggling of pixels on the braille canvas, it
// can be copied back to the parent canvas.
if err := braille.SetPixel(image.Point{0, 0}); err != nil {
	panic(err)
}
if err := braille.CopyTo(parent); err != nil {
	panic(err)
}

Index

• Constants
• type Canvas
  • func New(ar image.Rectangle) (*Canvas, error)
  • func (c *Canvas) Apply(t terminalapi.Terminal) error
  • func (c *Canvas) Area() image.Rectangle
  • func (c *Canvas) CellArea() image.Rectangle
  • func (c *Canvas) Clear() error
  • func (c *Canvas) ClearPixel(p image.Point, opts ...cell.Option) error
  • func (c *Canvas) CopyTo(dst *canvas.Canvas) error
  • func (c *Canvas) SetAreaCellOpts(cellArea image.Rectangle, opts ...cell.Option) error
  • func (c *Canvas) SetCellOpts(cellPoint image.Point, opts ...cell.Option) error
  • func (c *Canvas) SetPixel(p image.Point, opts ...cell.Option) error
  • func (c *Canvas) Size() image.Point
  • func (c *Canvas) TogglePixel(p image.Point, opts ...cell.Option) error

Examples

• Package (AppliedToTerminal)
• Package (CopiedToCanvas)

Constants

const (
	// ColMult is the resolution multiplier for the width, i.e. two pixels per cell.
	ColMult = 2

	// RowMult is the resolution multiplier for the height, i.e. four pixels per cell.
	RowMult = 4
)

Types

type Canvas

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

Canvas is a canvas that uses the braille patterns. It is two times wider and four times taller than a regular canvas that uses just plain characters, since each cell now has 2x4 pixels that can be independently set.

The braille canvas is an abstraction built on top of a regular character canvas. After setting and toggling pixels on the braille canvas, it should be copied to a regular character canvas or applied to a terminal which results in setting of braille pattern characters. See the examples for more details.

The created braille canvas can be smaller and even misaligned relatively to the regular character canvas or terminal, allowing the callers to create a "view" of just a portion of the canvas or terminal.

func New

func New(ar image.Rectangle) (*Canvas, error)

New returns a new braille canvas for the provided area.

func (*Canvas) Apply

func (c *Canvas) Apply(t terminalapi.Terminal) error

Apply applies the canvas to the corresponding area of the terminal. Guarantees to stay within limits of the area the canvas was created with.

func (*Canvas) Area

func (c *Canvas) Area() image.Rectangle

Area returns the area of the braille canvas in pixels. This will be zero-based area that is two times wider and four times taller than the area used to create the braille canvas.

func (*Canvas) CellArea

func (c *Canvas) CellArea() image.Rectangle

CellArea returns the area of the underlying cell canvas in cells.

func (*Canvas) Clear

func (c *Canvas) Clear() error

Clear clears all the content on the canvas.

func (*Canvas) ClearPixel

func (c *Canvas) ClearPixel(p image.Point, opts ...cell.Option) error

ClearPixel turns off pixel at the specified point. The provided cell options will be applied to the entire cell (all of its pixels). This method is idempotent.

func (*Canvas) CopyTo

func (c *Canvas) CopyTo(dst *canvas.Canvas) error

CopyTo copies the content of this canvas onto the destination canvas. This canvas can have an offset when compared to the destination canvas, i.e. the area of this canvas doesn't have to be zero-based.

func (*Canvas) SetAreaCellOpts

func (c *Canvas) SetAreaCellOpts(cellArea image.Rectangle, opts ...cell.Option) error

SetAreaCellOpts is like SetCellOpts, but sets the specified options on all the cells within the provided area.

func (*Canvas) SetCellOpts

func (c *Canvas) SetCellOpts(cellPoint image.Point, opts ...cell.Option) error

SetCellOpts sets options on the specified cell of the braille canvas without modifying the content of the cell. Sets the default cell options if no options are provided. This method is idempotent.

func (*Canvas) SetPixel

func (c *Canvas) SetPixel(p image.Point, opts ...cell.Option) error

SetPixel turns on pixel at the specified point. The provided cell options will be applied to the entire cell (all of its pixels). This method is idempotent.

func (*Canvas) Size

func (c *Canvas) Size() image.Point

Size returns the size of the braille canvas in pixels.

func (*Canvas) TogglePixel

func (c *Canvas) TogglePixel(p image.Point, opts ...cell.Option) error

TogglePixel toggles the state of the pixel at the specified point, i.e. it either sets or clear it depending on its current state. The provided cell options will be applied to the entire cell (all of its pixels).