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