Primitives

WARNING: This is work in progress and therefore incomplete!

How to Implement Your Own Primitive

In some rare cases, you may need functionality that tview does not offer. If it's something that you believe may be needed by others as well, consider opening an issue with a feature request. (Definitely do that before sending me pull requests.) If it's a reasonable request, it's likely that I will add it to tview.

If your request is very specific to your application, however, and existing primitives such as TextView are not sufficient to achieve what you want to do, you may need to write your own Primitive.

Alternatives

Before you start writing your own Primitive, you should know that there are alternatives. It is likely that you only need direct access to tcell's Screen during certain points of a primitive's lifecycle. This can be achieved without having to fully implement the Primitive interface.

Hooking Into a Primitive's Draw() Function

All of tview's primitives inherit from Box. And Box provides a function SetDrawFunc() which lets you install a callback function that is called after the Box has been drawn.

SetDrawFunc() gives you a tcell.Screen object and the coordinates of the Box. In the following example, we want our box to have a horizontal line and some text in its center:

tview.NewBox().
  SetBorder(true).
  SetDrawFunc(func(screen tcell.Screen, x int, y int, width int, height int) (int, int, int, int) {
    // Draw a horizontal line across the middle of the box.
    centerY := y + height/2
    for cx := x + 1; cx < x+width-1; cx++ {
      screen.SetContent(cx, centerY, tview.GraphicsHoriBar, nil, tcell.StyleDefault.Foreground(tcell.ColorWhite))
    }

    // Write some text along the horizontal line.
    tview.Print(screen, " Center Line ", x+1, centerY, width-2, tview.AlignCenter, tcell.ColorYellow)

    // Space for other content.
    return x + 1, centerY + 1, width - 2, height - (centerY + 1 - y)
  })

TODO: Insert screenshot (boxwithcenterline.png)

This also works for other primitives, and that's where the return values come into play. They dictate where the other content of the primitive will be placed. Here is the same example but for a TextView:

tview.NewTextView().
  SetText("This is the text view's content").
  SetTextAlign(tview.AlignCenter)
textView.SetBorder(true).
  SetDrawFunc(func(screen tcell.Screen, x int, y int, width int, height int) (int, int, int, int) {
    // Draw a horizontal line across the middle of the box.
    centerY := y + height/2
    for cx := x + 1; cx < x+width-1; cx++ {
      screen.SetContent(cx, centerY, tview.GraphicsHoriBar, nil, tcell.StyleDefault.Foreground(tcell.ColorWhite))
    }

    // Write som text along the horizontal line.
    tview.Print(screen, " Center Line ", x+1, centerY, width-2, tview.AlignCenter, tcell.ColorYellow)

    // Space for other content.
    return x + 1, centerY + 1, width - 2, height - (centerY + 1 - y)
  })

TODO: Insert screenshot (textviewwithcenterline.png)

Hooking Into the Application's Draw() Function

If what you need to do affects all primitives, you can also get access to tcell.Screen when the entire Application is redrawn. There are two functions for this:

• SetBeforeDrawFunc(): The provided callback function is invoked just before the Application draws its root Primitive. This allows you to draw onto the screen "underneath" any primitives.
• SetAfterDrawFunc(): The provided callback function is invoked after the Application has drawn its root Primitive. This is useful if you need to draw something on top of all primitives.

Hooking Into Key Events

In addition to drawing, you can also intercept all key events. Again, this can be done on the Box level or on the Application level:

• Application.SetInputCapture(): The provided callback function is invoked when a key is pressed. Whatever key event you return will be passed on to the default Application handling.
• Box.SetInputCapture(): Same as Application.SetInputCapture() but on a primitive level. The callback function is invoked when the primitive has focus and a key is pressed.

For example, if you want to cause the application to shut down upon Ctrl-Q in addition to tview's default Ctrl-C, you can achieve that in the following way:

app.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
  if event.Key() == tcell.KeyCtrlQ {
    app.Stop()
  }
  return event
})

Writing Primitives

If none of this is enough to achieve your goals, you can write your own Primitive. Please note that the Primitive interface may be subject to changes (e.g. I might add mouse interaction in the future).

TODO