Show a simple tutorial for gui/journal on first use

gui/journal.lua

@@ -11,7 +11,29 @@ 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 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.
+]=]
 
 journal_config = journal_config or json.open('dfhack-config/journal.json')
 
@@ -24,6 +46,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 +58,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 +72,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 +91,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 +134,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)
@@ -166,7 +210,7 @@ function JournalWindow:loadConfig()
     table_of_contents.width = table_of_contents.width or 20
     table_of_contents.visible = table_of_contents.visible or false
 
-    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 +265,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 +302,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 +311,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

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)
@@ -98,6 +107,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

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