Container option that sets the container as focused.

CHANGELOG.md

@@ -43,6 +43,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - containers can register into separate focus groups and specific keyboard keys
   can be configured to move the focus within each focus group.
 - widgets can now request keyboard events exclusively when focused.
+- users can now set a `container` as focused using a new `container.Focused`
+  option.
 
 #### Updates to the `button` widget
 

container/focus_test.go

@@ -541,7 +541,7 @@ func TestFocusTrackerNextAndPrevious(t *testing.T) {
 		wantProcessed int
 	}{
 		{
-			desc: "initially the root is focused",
+			desc: "initially the root is focused by default",
 			container: func(ft *faketerm.Terminal) (*Container, error) {
 				return New(
 					ft,
@@ -554,6 +554,49 @@ func TestFocusTrackerNextAndPrevious(t *testing.T) {
 			},
 			wantFocused: contLocA,
 		},
+		{
+			desc: "focus root explicitly",
+			container: func(ft *faketerm.Terminal) (*Container, error) {
+				return New(
+					ft,
+					Focused(),
+					SplitVertical(
+						Left(),
+						Right(),
+					),
+					KeyFocusNext(keyNext),
+				)
+			},
+			wantFocused: contLocA,
+		},
+		{
+			desc: "focus can be set to a container other than root",
+			container: func(ft *faketerm.Terminal) (*Container, error) {
+				return New(
+					ft,
+					SplitVertical(
+						Left(Focused()),
+						Right(),
+					),
+					KeyFocusNext(keyNext),
+				)
+			},
+			wantFocused: contLocB,
+		},
+		{
+			desc: "option Focused used on multiple containers, the last one takes effect",
+			container: func(ft *faketerm.Terminal) (*Container, error) {
+				return New(
+					ft,
+					SplitVertical(
+						Left(Focused()),
+						Right(Focused()),
+					),
+					KeyFocusNext(keyNext),
+				)
+			},
+			wantFocused: contLocC,
+		},
 		{
 			desc: "keyNext does nothing when only root exists",
 			container: func(ft *faketerm.Terminal) (*Container, error) {

container/options.go

@@ -1033,3 +1033,14 @@ func KeyFocusGroupsPrevious(key keyboard.Key, groups ...FocusGroup) Option {
 		return nil
 	})
 }
+
+// Focused moves the keyboard focus to this container.
+// If not specified, termdash will start with the root container focused.
+// If specified on multiple containers, the last container with this option
+// will be focused.
+func Focused() Option {
+	return option(func(c *Container) error {
+		c.focusTracker.setActive(c)
+		return nil
+	})
+}