From 6d54a1ce3f52d4d94d5913e59f8ac8413d2b1f5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wiktor=20Obr=C4=99bski?= Date: Sat, 3 Aug 2024 10:07:22 +0200 Subject: [PATCH 1/3] Show a simple tutorial for gui/journal on first use --- gui/journal.lua | 76 ++++++++++++++++++++------ internal/journal/table_of_contents.lua | 4 ++ test/gui/journal.lua | 21 +++++++ 3 files changed, 84 insertions(+), 17 deletions(-) diff --git a/gui/journal.lua b/gui/journal.lua index 9f43e16f7..6222f5370 100644 --- a/gui/journal.lua +++ b/gui/journal.lua @@ -11,7 +11,22 @@ local table_of_contents = reqscript('internal/journal/table_of_contents') local RESIZE_MIN = {w=32, h=10} -JOURNAL_PERSIST_KEY = 'journal' +local JOURNAL_PERSIST_KEY = 'journal' + +local JOURNAL_WELCOME_COPY = [=[ +Welcome to gui/journal, the chronicler's tool for Dwarf Fortress! + +Here, you can carve out notes, sketch your grand designs, or record the history of your fortress. +The text you write here is saved together with your fort. + +For guidance on navigation and hotkeys, tap the ? button in the upper right corner. +Happy digging! +]=] + +local TOC_WELCOME_COPY = [=[ +Start a line with # symbols and a space to create header. +Those headers will appear here, and you can click on them to jump to them in the text. +]=] journal_config = journal_config or json.open('dfhack-config/journal.json') @@ -24,6 +39,7 @@ JournalWindow.ATTRS { init_text=DEFAULT_NIL, init_cursor=1, save_layout=true, + show_tutorial=false, on_text_change=DEFAULT_NIL, on_cursor_change=DEFAULT_NIL, @@ -35,7 +51,7 @@ function JournalWindow:init() self.frame = frame and self:sanitizeFrame(frame) or self.frame - self:addviews({ + self:addviews{ table_of_contents.TableOfContents{ view_id='table_of_contents_panel', frame={l=0, w=toc_width, t=0, b=1}, @@ -49,7 +65,15 @@ function JournalWindow:init() on_resize_begin=self:callback('onPanelResizeBegin'), on_resize_end=self:callback('onPanelResizeEnd'), - on_submit=self:callback('onTableOfContentsSubmit') + on_submit=self:callback('onTableOfContentsSubmit'), + subviews={ + widgets.WrappedLabel{ + view_id='table_of_contents_tutorial', + frame={l=0,t=0,r=0,b=0}, + text_to_wrap=TOC_WELCOME_COPY, + visible=false + } + } }, shifter.Shifter{ view_id='shifter', @@ -60,10 +84,7 @@ function JournalWindow:init() self.subviews.table_of_contents_divider.visible = not collapsed if not colllapsed then - self.subviews.table_of_contents_panel:reload( - self.subviews.journal_editor:getText(), - self.subviews.journal_editor:getCursor() - ) + self:reloadTableOfContents() end self:ensurePanelsRelSize() @@ -106,12 +127,28 @@ function JournalWindow:init() } } } - }) + } + if self.show_tutorial then + self.subviews.journal_editor:addviews{ + widgets.WrappedLabel{ + view_id='journal_tutorial', + frame={l=0,t=1,r=0,b=0}, + text_to_wrap=JOURNAL_WELCOME_COPY + } + } + end + + self:reloadTableOfContents() +end + +function JournalWindow:reloadTableOfContents() self.subviews.table_of_contents_panel:reload( - self.init_text, + self.subviews.journal_editor:getText(), self.subviews.journal_editor:getCursor() or self.init_cursor ) + self.subviews.table_of_contents_panel.subviews.table_of_contents_tutorial.visible = + #self.subviews.table_of_contents_panel:sections() == 0 end function JournalWindow:sanitizeFrame(frame) @@ -164,9 +201,9 @@ function JournalWindow:loadConfig() local table_of_contents = copyall(journal_config.data.toc or {}) table_of_contents.width = table_of_contents.width or 20 - table_of_contents.visible = table_of_contents.visible or false + table_of_contents.visible = table_of_contents.visible or true - return window_frame, table_of_contents.visible or false, table_of_contents.width or 25 + return window_frame, table_of_contents.visible, table_of_contents.width or 25 end function JournalWindow:onPanelResizeBegin() @@ -221,10 +258,10 @@ function JournalWindow:onCursorChange(cursor) end function JournalWindow:onTextChange(text) - self.subviews.table_of_contents_panel:reload( - text, - self.subviews.journal_editor:getCursor() - ) + if self.show_tutorial then + self.subviews.journal_editor.subviews.journal_tutorial.visible = false + end + self:reloadTableOfContents() if self.on_text_change ~= nil then self.on_text_change(text) @@ -258,6 +295,7 @@ function JournalScreen:init() init_text=context.text[1], init_cursor=context.cursor[1], + show_tutorial=context.show_tutorial or false, on_text_change=self:callback('saveContext'), on_cursor_change=self:callback('saveContext') @@ -266,10 +304,14 @@ function JournalScreen:init() end function JournalScreen:loadContext() - local site_data = dfhack.persistent.getSiteData( + local site_data = self.save_on_change and dfhack.persistent.getSiteData( self.save_prefix .. JOURNAL_PERSIST_KEY ) or {} - site_data.text = site_data.text or {''} + + if not site_data.text then + site_data.text={''} + site_data.show_tutorial = true + end site_data.cursor = site_data.cursor or {#site_data.text[1] + 1} return site_data diff --git a/internal/journal/table_of_contents.lua b/internal/journal/table_of_contents.lua index 8365564a6..a37d0bb2d 100644 --- a/internal/journal/table_of_contents.lua +++ b/internal/journal/table_of_contents.lua @@ -98,6 +98,10 @@ function TableOfContents:setCursor(cursor) self.text_cursor = cursor end +function TableOfContents:sections() + return self.subviews.table_of_contents.choices +end + function TableOfContents:reload(text, cursor) if not self.visible then return diff --git a/test/gui/journal.lua b/test/gui/journal.lua index 7a2674a20..29fcc1d69 100644 --- a/test/gui/journal.lua +++ b/test/gui/journal.lua @@ -168,6 +168,8 @@ end function test.load() local journal, text_area = arrange_empty_journal() + text_area:setText(' ') + journal:onRender() expect.eq('dfhack/lua/journal', dfhack.gui.getCurFocus(true)[1]) expect.eq(read_rendered_text(text_area), '_') @@ -3047,3 +3049,22 @@ function test.fast_rewind_reset_selection() journal:dismiss() end + +function test.show_tutorials_on_first_use() + local journal, text_area, journal_window = arrange_empty_journal({w=65}) + simulate_input_keys('CUSTOM_CTRL_O') + + expect.str_find('Welcome to gui/journal', read_rendered_text(text_area)); + + simulate_input_text(' ') + + expect.eq(read_rendered_text(text_area), ' _'); + + local toc_panel = journal_window.subviews.table_of_contents_panel + expect.str_find('Start a line with\n# symbols', read_rendered_text(toc_panel)); + + simulate_input_text('\n# Section 1') + + expect.str_find('Section 1\n', read_rendered_text(toc_panel)); + journal:dismiss() +end From 36f68736f7b7ba54f5148e53beabff3412ee5f65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wiktor=20Obr=C4=99bski?= Date: Sat, 3 Aug 2024 15:05:27 +0200 Subject: [PATCH 2/3] Fix journal sections jump error when there is no sections available --- internal/journal/table_of_contents.lua | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/internal/journal/table_of_contents.lua b/internal/journal/table_of_contents.lua index a37d0bb2d..c152a3ce7 100644 --- a/internal/journal/table_of_contents.lua +++ b/internal/journal/table_of_contents.lua @@ -54,6 +54,10 @@ end function TableOfContents:previousSection() local section_cursor, section = self:currentSection() + if section == nil then + return + end + if section.line_cursor == self.text_cursor then self.subviews.table_of_contents:setSelected(section_cursor - 1) end @@ -62,10 +66,15 @@ function TableOfContents:previousSection() end function TableOfContents:nextSection() + local section_cursor, section = self:currentSection() + + if section == nil then + return + end + local curr_sel = self.subviews.table_of_contents:getSelected() - local target_sel = self.text_cursor and - self:currentSection() + 1 or curr_sel + 1 + local target_sel = self.text_cursor and section_cursor + 1 or curr_sel + 1 if curr_sel ~= target_sel then self.subviews.table_of_contents:setSelected(target_sel) From 24e5b9ff09ced7652751ad8974b26222861c0df0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wiktor=20Obr=C4=99bski?= Date: Sat, 3 Aug 2024 21:39:57 +0200 Subject: [PATCH 3/3] Polishing journal table of contents help text --- gui/journal.lua | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/gui/journal.lua b/gui/journal.lua index 6222f5370..6fb1514de 100644 --- a/gui/journal.lua +++ b/gui/journal.lua @@ -24,7 +24,14 @@ Happy digging! ]=] local TOC_WELCOME_COPY = [=[ -Start a line with # symbols and a space to create header. +Start a line with # symbols and a space to create a header. For example: + +# My section heading + +or + +## My section subheading + Those headers will appear here, and you can click on them to jump to them in the text. ]=] @@ -201,7 +208,7 @@ function JournalWindow:loadConfig() local table_of_contents = copyall(journal_config.data.toc or {}) table_of_contents.width = table_of_contents.width or 20 - table_of_contents.visible = table_of_contents.visible or true + table_of_contents.visible = table_of_contents.visible or false return window_frame, table_of_contents.visible, table_of_contents.width or 25 end