nvim

README

Fyne-Nvim

This go package contains a custom neovim widget for the fyne framework.

Table of Contents

• Get Started
  • Usage as a Widget
• Developer Notes
  • Contributions
  • Project Structure
  • Resources

Get Started

To install the application :

go install github.com/yesoer/fyne-nvim/cmd/fynenvim@latest

To add it to your own project :

go get github.com/yesoer/fyne-nvim

Usage as a Widget

Using the fyne neovim widget in your project is pretty straight forward, as can be seen from the cmd/fynenvim/main.go :

package main

import (
	"fmt"

	"fyne.io/fyne/v2"
	"fyne.io/fyne/v2/app"
	nvim "github.com/yesoer/fyne-nvim"
)

func main() {
	a := app.New()
	w := a.NewWindow("Fyne NeoVim Example")
	w.Resize(fyne.NewSize(900, 600))

	nvim := nvim.New("./")
	nvim.Resize(fyne.NewSize(900, 600))
	w.SetContent(nvim)
	w.Canvas().Focus(nvim)

	fmt.Println("show and run")
	w.ShowAndRun()
}

Developer Notes

Contributions

When confused, no worries, just publish what you have. A not perfectly structured contribution is still far better than nothing.

Code Style

For formatting this project uses go fmt. There is a github action for it to ensure nothing gets merged not following the style but I'd like to not flood the commit history with such commits, so ideally you'd configure your environment accordingly/run go fmt before pushing.

Apart from that if you have anything you're unsure about you may refer to the fyne code style though as of now I do not intend to follow it down to the smallest detail.

Branch Naming

Branch names should look like this type>/<name>

<type> is one of the following (extend if needed) :

type	when to use
feat	any new features
maintenance	any work on docs, git workflows, tests etc.
refactor	when refactoring existing parts of the application
fix	bug fixes
test	testing environments/throwaway branches

<name> is a short description of what you are doing, words should be seperated using '-'.

Commit Messages

More specific distinction happens in commit messages which should be structured as follows :

<type>(<scope>): <subject>

• type Must be one of the following:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing or correcting existing tests
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

• scope refers to the part of the software, which usually will be best identified by the package name.

• subject gives a short idea of what was done/what the intend of the commit is.

As for the commit body there is no mandatory structure as of now.

Other Tips/Notes on Contributing

Issues and Pull Requests for now will not have any set guidelines.

Check out Code Review Comments for commmon code review topics around golang.

Project Structure

Maybe this description helps you getting started and understanding the project. Don't be afraid to ask for more information.

location	Description
cmd/	Contains the fynenvim executable code
nvim.go	Implements the widget interface i.e. is the center of this project
render.go	Implements the renderer for our widget as required for custom widgets
input.go	Using the mappings from keymap.go this forwards inputs from Fyne to Neovim
output.go	Provides functions to write runes etc. to the textgrid which visualizes Neovim. Should only be used from the handler in events.go, as they are not implemented for concurrent use.
events.go	Process the events received from Neovim (uses output.go to forward visual changes to Fyne)

Resources

• Neovim UI Event Docs
• Neovim UI API Docs
• Fyne Custom Widget Docs with a more detailed example on github

To me the fyne terminal project was very helpful as well.

Documentation

Index

• Constants
• Variables
• type NeoVim
  • func New(pth string) *NeoVim
  • func (n *NeoVim) ChangeVisualGridSize(targetRow, targetCol int)
  • func (n *NeoVim) ClearGrid()
  • func (n *NeoVim) CreateRenderer() fyne.WidgetRenderer
  • func (n *NeoVim) FocusGained()
  • func (n *NeoVim) FocusLost()
  • func (n *NeoVim) HandleNvimEvent(event []interface{})
  • func (n *NeoVim) MoveGridCursor(oldRow, oldCol, newRow, newCol int)
  • func (n *NeoVim) Resize(s fyne.Size)
  • func (n *NeoVim) ScrollGrid(top, bot, left, right, rows int)
  • func (n *NeoVim) Tapped(ev *fyne.PointEvent)
  • func (n *NeoVim) TypedKey(e *fyne.KeyEvent)
  • func (n *NeoVim) TypedRune(r rune)
  • func (n *NeoVim) TypedShortcut(s fyne.Shortcut)
  • func (n *NeoVim) WriteGridLine(row, col int, cells []interface{})

Constants

const GLOBAL_GRID = 1

As long as multigrid isn't used there will only be one grid

const MIN_COLS = 13

const MIN_ROWS = 1

According to https://neovim.io/doc/user/options.html it seems that neovim is supposed to have at least 12 columns and 1 row In practice the neovim client didn't work with less than 13x1

Variables

var RGBA_SENTINEL = color.RGBA{255, 255, 255, 0}

The sentinel value for Fg, Bg and Special to indicate that the coloris not set i.e. the default color should be used

Types

type NeoVim

type NeoVim struct {
	// Widget requirements
	widget.BaseWidget

	// Additional fields
	// It is standard in a Fyne widget to export the fields which define
	// behaviour (just like the primitives defined in the canvas package).
	Engine *nvim.Nvim
	// contains filtered or unexported fields
}

func New

func New(pth string) *NeoVim

Create a new NeoVim widget with the given path

func (*NeoVim) ChangeVisualGridSize

func (n *NeoVim) ChangeVisualGridSize(targetRow, targetCol int)

Changes the size of the textgrid, creating or removing rows and columns as needed TODO: One may consider only downsizing rows/cols if the difference is significant

func (*NeoVim) ClearGrid

func (n *NeoVim) ClearGrid()

Substitutes all runes with ' '

func (*NeoVim) CreateRenderer

func (n *NeoVim) CreateRenderer() fyne.WidgetRenderer

CreateRenderer implements fyne.Widget

func (*NeoVim) FocusGained

func (n *NeoVim) FocusGained()

FocusGained implements fyne.Focusable FocusGained is a hook called by the focus handling logic after this object gained the focus.

func (*NeoVim) FocusLost

func (n *NeoVim) FocusLost()

FocusGained implements fyne.Focusable FocusLost is a hook called by the focus handling logic after this object lost the focus.

func (*NeoVim) HandleNvimEvent

func (n *NeoVim) HandleNvimEvent(event []interface{})

Handles events for the NeoVim instance Currently only the following event groups are handled: - Global Events - Grid Events (line-based) For the documentation of the events see: https://neovim.io/doc/user/ui.html The go client calls this function sequentially for each event, so we don't have to worry about preserving order

func (*NeoVim) MoveGridCursor

func (n *NeoVim) MoveGridCursor(oldRow, oldCol, newRow, newCol int)

Recovers the previous locations colors on horizontal movement and updates the cursor position

func (*NeoVim) Resize

func (n *NeoVim) Resize(s fyne.Size)

Override resize to adjust the textgrid

func (*NeoVim) ScrollGrid

func (n *NeoVim) ScrollGrid(top, bot, left, right, rows int)

Moves the displayed text up/down/lef/right

func (*NeoVim) Tapped

func (n *NeoVim) Tapped(ev *fyne.PointEvent)

Tapped implements fyne.Tappable Tapped makes sure we ask for focus if user taps us.

func (*NeoVim) TypedKey

func (n *NeoVim) TypedKey(e *fyne.KeyEvent)

FocusGained implements fyne.Focusable TypedKey is a hook called by the input handling logic on key events if this object is focused.

func (*NeoVim) TypedRune

func (n *NeoVim) TypedRune(r rune)

FocusGained implements fyne.Focusable TypedRune is a hook called by the input handling logic on text input events if this object is focused.

func (*NeoVim) TypedShortcut

func (n *NeoVim) TypedShortcut(s fyne.Shortcut)

TypedShortcut implements fyne.Shortcutable TypedShortcut handle the registered shortcut TODO : There are other shortcuts e.g. SelectAll (Cmd+A)

func (*NeoVim) WriteGridLine

func (n *NeoVim) WriteGridLine(row, col int, cells []interface{})

Writes a line of text (as defined by neovims ui events) to the textgrid