Document how to prevent screen artifacts when using SetBackgroundTransparent

Resolves #45.

CHANGELOG

@@ -1,3 +1,6 @@
+v1.5.3 (WIP)
+- Document how to prevent screen artifacts when using SetBackgroundTransparent
+
 v1.5.2 (2020-12-04)
 - Handle input events before executing queued update functions
 - Fix WindowManager background not being drawn

box.go

@@ -336,7 +336,11 @@ func (b *Box) GetBackgroundColor() tcell.Color {
 }
 
 // SetBackgroundTransparent sets the flag indicating whether or not the box's
-// background is transparent.
+// background is transparent. The screen is not cleared before drawing the
+// application. Overlaying transparent widgets directly onto the screen may
+// result in artifacts. To resolve this, add a blank, non-transparent Box to
+// the bottom layer of the interface via Panels, or set a handler via
+// SetBeforeDrawFunc which clears the screen.
 func (b *Box) SetBackgroundTransparent(transparent bool) {
 	b.l.Lock()
 	defer b.l.Unlock()

doc.go

@@ -168,7 +168,11 @@ You can use the Escape() function to insert brackets automatically where needed.
 
 Setting the background color of a primitive to tcell.ColorDefault will use the
 default terminal background color. To enable transparency (allowing one or more
-primitives to display behind a primitive) call SetBackgroundTransparent.
+primitives to display behind a primitive) call SetBackgroundTransparent. The
+screen is not cleared before drawing the application. Overlaying transparent
+widgets directly onto the screen may result in artifacts. To resolve this, add
+a blank, non-transparent Box to the bottom layer of the interface via Panels,
+or set a handler via SetBeforeDrawFunc which clears the screen.
 
 Styles
 

go.mod

@@ -3,11 +3,11 @@ module gitlab.com/tslocum/cview
 go 1.12
 
 require (
-	github.com/gdamore/tcell/v2 v2.0.1-0.20201109052606-7d87d8188c8d
+	github.com/gdamore/tcell/v2 v2.1.0
 	github.com/lucasb-eyer/go-colorful v1.0.3
 	github.com/mattn/go-runewidth v0.0.9
 	github.com/rivo/uniseg v0.2.0
 	gitlab.com/tslocum/cbind v0.1.4
-	golang.org/x/sys v0.0.0-20201202213521-69691e467435 // indirect
+	golang.org/x/sys v0.0.0-20201214210602-f9fddec55a1e // indirect
 	golang.org/x/text v0.3.4 // indirect
 )

go.sum

@@ -1,8 +1,8 @@
 github.com/gdamore/encoding v1.0.0 h1:+7OoQ1Bc6eTm5niUzBa0Ctsh6JbMW6Ra+YNuAtDBdko=
 github.com/gdamore/encoding v1.0.0/go.mod h1:alR0ol34c49FCSBLjhosxzcPHQbf2trDkoo5dl+VrEg=
 github.com/gdamore/tcell/v2 v2.0.0-dev/go.mod h1:vSVL/GV5mCSlPC6thFP5kfOFdM9MGZcalipmpTxTgQA=
-github.com/gdamore/tcell/v2 v2.0.1-0.20201109052606-7d87d8188c8d h1:C1FQEuzw5kUUveSXpZp3v0+qOR+VEnzHsQ7K6n39LsM=
-github.com/gdamore/tcell/v2 v2.0.1-0.20201109052606-7d87d8188c8d/go.mod h1:vSVL/GV5mCSlPC6thFP5kfOFdM9MGZcalipmpTxTgQA=
+github.com/gdamore/tcell/v2 v2.1.0 h1:UnSmozHgBkQi2PGsFr+rpdXuAPRRucMegpQp3Z3kDro=
+github.com/gdamore/tcell/v2 v2.1.0/go.mod h1:vSVL/GV5mCSlPC6thFP5kfOFdM9MGZcalipmpTxTgQA=
 github.com/lucasb-eyer/go-colorful v1.0.3 h1:QIbQXiugsb+q10B+MI+7DI1oQLdmnep86tWFlaaUAac=
 github.com/lucasb-eyer/go-colorful v1.0.3/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/mattn/go-runewidth v0.0.7/go.mod h1:H031xJmbD/WCDINGzjvQ9THkh0rPKHF+m2gUSrubnMI=
@@ -14,8 +14,8 @@ gitlab.com/tslocum/cbind v0.1.4 h1:cbZXPPcieXspk8cShoT6efz7HAT8yMNQcofYWNizis4=
 gitlab.com/tslocum/cbind v0.1.4/go.mod h1:RvwYE3auSjBNlCmWeGspzn+jdLUVQ8C2QGC+0nP9ChI=
 golang.org/x/sys v0.0.0-20190626150813-e07cf5db2756/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201013132646-2da7054afaeb/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20201202213521-69691e467435 h1:25AvDqqB9PrNqj1FLf2/70I4W0L19qqoaFq3gjNwbKk=
-golang.org/x/sys v0.0.0-20201202213521-69691e467435/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20201214210602-f9fddec55a1e h1:AyodaIpKjppX+cBfTASF2E1US3H2JFBj920Ot3rtDjs=
+golang.org/x/sys v0.0.0-20201214210602-f9fddec55a1e/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3 h1:cokOdA+Jmi5PJGXLlLllQSgYigAEfHXJAERHVMaCc2k=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=