1// Copyright 2014 The gocui Authors. All rights reserved.
  2// Use of this source code is governed by a BSD-style
  3// license that can be found in the LICENSE file.
  4
  5/*
  6Package gocui allows to create console user interfaces.
  7
  8Create a new GUI:
  9
 10	g, err := gocui.NewGui(gocui.OutputNormal)
 11	if err != nil {
 12		// handle error
 13	}
 14	defer g.Close()
 15
 16	// Set GUI managers and key bindings
 17	// ...
 18
 19	if err := g.MainLoop(); err != nil && !gocui.IsQuit(err) {
 20		// handle error
 21	}
 22
 23Set GUI managers:
 24
 25	g.SetManager(mgr1, mgr2)
 26
 27Managers are in charge of GUI's layout and can be used to build widgets. On
 28each iteration of the GUI's main loop, the Layout function of each configured
 29manager is executed. Managers are used to set-up and update the application's
 30main views, being possible to freely change them during execution. Also, it is
 31important to mention that a main loop iteration is executed on each reported
 32event (key-press, mouse event, window resize, etc).
 33
 34GUIs are composed by Views, you can think of it as buffers. Views implement the
 35io.ReadWriter interface, so you can just write to them if you want to modify
 36their content. The same is valid for reading.
 37
 38Create and initialize a view with absolute coordinates:
 39
 40	if v, err := g.SetView("viewname", 2, 2, 22, 7); err != nil {
 41		if !gocui.IsUnknownView(err) {
 42			// handle error
 43		}
 44		fmt.Fprintln(v, "This is a new view")
 45		// ...
 46	}
 47
 48Views can also be created using relative coordinates:
 49
 50	maxX, maxY := g.Size()
 51	if v, err := g.SetView("viewname", maxX/2-30, maxY/2, maxX/2+30, maxY/2+2); err != nil {
 52		// ...
 53	}
 54
 55Configure keybindings:
 56
 57	if err := g.SetKeybinding("viewname", gocui.KeyEnter, gocui.ModNone, fcn); err != nil {
 58		// handle error
 59	}
 60
 61gocui implements full mouse support that can be enabled with:
 62
 63	g.Mouse = true
 64
 65Mouse events are handled like any other keybinding:
 66
 67	if err := g.SetKeybinding("viewname", gocui.MouseLeft, gocui.ModNone, fcn); err != nil {
 68		// handle error
 69	}
 70
 71IMPORTANT: Views can only be created, destroyed or updated in three ways: from
 72the Layout function within managers, from keybinding callbacks or via
 73*Gui.Update(). The reason for this is that it allows gocui to be
 74concurrent-safe. So, if you want to update your GUI from a goroutine, you must
 75use *Gui.Update(). For example:
 76
 77	g.Update(func(g *gocui.Gui) error {
 78		v, err := g.View("viewname")
 79		if err != nil {
 80			// handle error
 81		}
 82		v.Clear()
 83		fmt.Fprintln(v, "Writing from different goroutines")
 84		return nil
 85	})
 86
 87By default, gocui provides a basic editing mode. This mode can be extended
 88and customized creating a new Editor and assigning it to *View.Editor:
 89
 90	type Editor interface {
 91		Edit(v *View, key Key, ch rune, mod Modifier)
 92	}
 93
 94DefaultEditor can be taken as example to create your own custom Editor:
 95
 96	var DefaultEditor Editor = EditorFunc(simpleEditor)
 97
 98	func simpleEditor(v *View, key Key, ch rune, mod Modifier) {
 99		switch {
100		case ch != 0 && mod == 0:
101			v.EditWrite(ch)
102		case key == KeySpace:
103			v.EditWrite(' ')
104		case key == KeyBackspace || key == KeyBackspace2:
105			v.EditDelete(true)
106		// ...
107		}
108	}
109
110Colored text:
111
112Views allow to add colored text using ANSI colors. For example:
113
114	fmt.Fprintln(v, "\x1b[0;31mHello world")
115
116For more information, see the examples in folder "_examples/".
117*/
118package gocui