Add example multi-layout application and mouse-enabled application

CHANGELOG

@@ -1,6 +1,7 @@
 v1.4.1 (WIP)
 - Add ProgressBar widget
 - Add Application.RingBell
+- Add example multi-layout application and mouse-enabled application
 
 v1.4.0 (2020-01-16)
 - Bump version to resolve issues with "go get"

doc.go

@@ -1,7 +1,8 @@
 /*
-Package cview implements rich widgets for terminal based user interfaces. The
-widgets provided with this package are useful for data exploration and data
-entry.
+Package cview implements rich widgets for terminal based user interfaces.
+
+See the demos folder and the example application provided with the
+Application.NewApplication documentation for usage examples.
 
 Widgets
 
@@ -141,7 +142,8 @@ This package supports unicode characters including wide characters.
 Mouse Support
 
 Mouse support may be enabled by calling Application.EnableMouse before
-Application.Run.
+Application.Run. See the example application provided with the
+Application.EnableMouse documentation.
 
 Mouse events are passed to:
 

doc_test.go

@@ -0,0 +1,87 @@
+package cview
+
+import (
+	"fmt"
+
+	"github.com/gdamore/tcell"
+)
+
+// Example of an application with multiple layouts.
+func ExampleNewApplication() {
+	// Initialize application.
+	app := NewApplication()
+
+	// Create shared TextView.
+	sharedTextView := NewTextView().SetText("Widgets may be re-used between multiple layouts.").SetTextAlign(AlignCenter)
+
+	// Create main layout using Grid.
+	mainTextView := NewTextView().SetText("This is mainLayout.\n\nPress <Tab> to view aboutLayout.").SetTextAlign(AlignCenter)
+	mainLayout := NewGrid()
+	mainLayout.AddItem(mainTextView, 0, 0, 1, 1, 0, 0, false)
+	mainLayout.AddItem(sharedTextView, 1, 0, 1, 1, 0, 0, false)
+
+	// Create about layout using Grid.
+	aboutTextView := NewTextView().SetText("cview muti-layout application example\n\nhttps://git.sr.ht/~tslocum/cview").SetTextAlign(AlignCenter)
+	aboutLayout := NewGrid()
+	aboutLayout.AddItem(aboutTextView, 0, 0, 1, 1, 0, 0, false)
+	aboutLayout.AddItem(sharedTextView, 1, 0, 1, 1, 0, 0, false)
+
+	// Track the current layout.
+	currentLayout := 0
+
+	// Set an input capture function that switches between layouts when the tab
+	// key is pressed.
+	app.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if event.Key() == tcell.KeyTab {
+			if currentLayout == 0 {
+				currentLayout = 1
+
+				app.SetRoot(aboutLayout, true)
+			} else {
+				currentLayout = 0
+
+				app.SetRoot(mainLayout, true)
+			}
+
+			// Return nil to stop propagating the event to any remaining
+			// handlers.
+			return nil
+		}
+
+		// Return the event to continue propagating it.
+		return event
+	})
+
+	// Run the application.
+	if err := app.SetRoot(mainLayout, true).Run(); err != nil {
+		panic(err)
+	}
+}
+
+// Example of an application with mouse support.
+func ExampleApplication_EnableMouse() {
+	// Initialize application and enable mouse support.
+	app := NewApplication().EnableMouse()
+
+	// Create a textview.
+	tv := NewTextView().SetText("Click somewhere!")
+
+	// Set a mouse capture function which prints where the mouse was clicked.
+	app.SetMouseCapture(func(event *EventMouse) *EventMouse {
+		if event.Action()&MouseDown != 0 && event.Buttons()&tcell.Button1 != 0 {
+			x, y := event.Position()
+			fmt.Fprintf(tv, "\nYou clicked at %d,%d! Amazing!", x, y)
+
+			// Return nil to stop propagating the event to any remaining handlers.
+			return nil
+		}
+
+		// Return the event to continue propagating it.
+		return event
+	})
+
+	// Run the application.
+	if err := app.SetRoot(tv, true).Run(); err != nil {
+		panic(err)
+	}
+}