From 3bd4650254ebf8ce096c5bd70164ba6df4cfda2f Mon Sep 17 00:00:00 2001 From: Christian Rocha Date: Mon, 28 Oct 2024 13:38:27 -0400 Subject: [PATCH] chore: use verbs in background, foreground, and window request cmd names (#1205) * chore: use verbs in background, foreground, and window request cmd names This renames a few existing commands to make it clearer that the user is firing off a task. * WindowSize -> RequestWindowSize * ForegroundColor -> RequestForegroundColor * BackgroundColor -> RequestBackgroundColor It also expands on a few comments, and provides examples. * fix: screen tests * fix(examples): use RequestWindowSize instead of WindowSize --------- Co-authored-by: Ayman Bagabas --- color.go | 44 ++++++++++++++++++++++++------------ commands.go | 12 +++++----- examples/window-size/main.go | 2 +- screen_test.go | 2 +- 4 files changed, 38 insertions(+), 22 deletions(-) diff --git a/color.go b/color.go index 726f5ebbc3..5453718559 100644 --- a/color.go +++ b/color.go @@ -11,24 +11,24 @@ import ( // backgroundColorMsg is a message that requests the terminal background color. type backgroundColorMsg struct{} -// BackgroundColor is a command that requests the terminal background color. -func BackgroundColor() Msg { +// RequestBackgroundColor is a command that requests the terminal background color. +func RequestBackgroundColor() Msg { return backgroundColorMsg{} } // foregroundColorMsg is a message that requests the terminal foreground color. type foregroundColorMsg struct{} -// ForegroundColor is a command that requests the terminal foreground color. -func ForegroundColor() Msg { +// RequestForegroundColor is a command that requests the terminal foreground color. +func RequestForegroundColor() Msg { return foregroundColorMsg{} } // cursorColorMsg is a message that requests the terminal cursor color. type cursorColorMsg struct{} -// CursorColor is a command that requests the terminal cursor color. -func CursorColor() Msg { +// RequestCursorColor is a command that requests the terminal cursor color. +func RequestCursorColor() Msg { return cursorColorMsg{} } @@ -62,9 +62,9 @@ func SetCursorColor(c color.Color) Cmd { } } -// ForegroundColorMsg represents a foreground color message. -// This message is emitted when the program requests the terminal foreground -// color. +// ForegroundColorMsg represents a foreground color message. This message is +// emitted when the program requests the terminal foreground color with the +// [RequestForegroundColor] Cmd. type ForegroundColorMsg struct{ color.Color } // String returns the hex representation of the color. @@ -77,9 +77,25 @@ func (e ForegroundColorMsg) IsDark() bool { return isDarkColor(e.Color) } -// BackgroundColorMsg represents a background color message. -// This message is emitted when the program requests the terminal background -// color. +// BackgroundColorMsg represents a background color message. This message is +// emitted when the program requests the terminal background color with the +// [RequestBackgroundColor] Cmd. +// +// This is commonly used in [Update.Init] to get the terminal background color +// for style definitions. For that you'll want to call +// [BackgroundColorMsg.IsDark] to determine if the color is dark or light. For +// example: +// +// func (m Model) Init() (Model, Cmd) { +// return m, RequestBackgroundColor() +// } +// +// func (m Model) Update(msg Msg) (Model, Cmd) { +// switch msg := msg.(type) { +// case BackgroundColorMsg: +// m.styles = newStyles(msg.IsDark()) +// } +// } type BackgroundColorMsg struct{ color.Color } // String returns the hex representation of the color. @@ -92,8 +108,8 @@ func (e BackgroundColorMsg) IsDark() bool { return isDarkColor(e.Color) } -// CursorColorMsg represents a cursor color change message. -// This message is emitted when the program requests the terminal cursor color. +// CursorColorMsg represents a cursor color change message. This message is +// emitted when the program requests the terminal cursor color. type CursorColorMsg struct{ color.Color } // String returns the hex representation of the color. diff --git a/commands.go b/commands.go index 722c75b757..437386d8df 100644 --- a/commands.go +++ b/commands.go @@ -176,12 +176,12 @@ func SetWindowTitle(title string) Cmd { type windowSizeMsg struct{} -// WindowSize is a command that queries the terminal for its current size. It -// delivers the results to Update via a [WindowSizeMsg]. Keep in mind that -// WindowSizeMsgs will automatically be delivered to Update when the [Program] -// starts and when the window dimensions change so in many cases you will not -// need to explicitly invoke this command. -func WindowSize() Cmd { +// RequestWindowSize is a command that queries the terminal for its current +// size. It delivers the results to Update via a [WindowSizeMsg]. Keep in mind +// that WindowSizeMsgs will automatically be delivered to Update when the +// [Program] starts and when the window dimensions change so in many cases you +// will not need to explicitly invoke this command. +func RequestWindowSize() Cmd { return func() Msg { return windowSizeMsg{} } diff --git a/examples/window-size/main.go b/examples/window-size/main.go index 6ded964329..84465161de 100644 --- a/examples/window-size/main.go +++ b/examples/window-size/main.go @@ -28,7 +28,7 @@ func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) { return m, tea.Quit } - return m, tea.WindowSize() + return m, tea.RequestWindowSize() case tea.WindowSizeMsg: return m, tea.Printf("%dx%d", msg.Width, msg.Height) diff --git a/screen_test.go b/screen_test.go index 4716bb1d03..2868246786 100644 --- a/screen_test.go +++ b/screen_test.go @@ -66,7 +66,7 @@ func TestClearMsg(t *testing.T) { }, { name: "bg_fg_cur_color", - cmds: []Cmd{ForegroundColor, BackgroundColor, CursorColor}, + cmds: []Cmd{RequestForegroundColor, RequestBackgroundColor, RequestCursorColor}, expected: "\x1b[?25l\x1b[?2004h\x1b]10;?\a\x1b]11;?\a\x1b]12;?\a\rsuccess\r\n\x1b[D\x1b[2K\r\x1b[?2004l\x1b[?25h", }, {