ui: C toggles --cleared; f -> F; UI tweaks

You can now toggle showing only cleared items in the accounts and
register screens, with C (like the command-line flag).

The f key has been changed to F for consistency (we don't have this as a
command-line flag, though we could, though Ledger uses it for something
different).

Screen titles have been tweaked, eg switching the cyan and yellow.

Screen help has been squeezed to fit better in 80 columns.

doc/manual.md

@@ -2220,77 +2220,94 @@ Flags:
 ...
 ```
 
-Currently there are two screens:
+##### Keys
+
+Generally the cursor keys navigate; `right` (or `enter`) goes deeper, `left` returns to the previous screen,
+`up`/`down`/`page up`/`page down`/`home`/`end` move up and down through lists.
+
+`g` gets the latest data and reloads the screen (and any previous screens). There may be a noticeable pause.
+
+`q` quits the application.
+
+Some screens have additional key bindings, described below.
 
 ##### Accounts screen
 
-This is the screen shown at startup by default.
+This is normally the first screen displayed.
-It shows a scrollable list of accounts and their balances - all accounts, or just the matched accounts if you specified a query on the command line.
+It lists accounts and their balances, like hledger's balance command.
-`f` toggles flat mode on and off.
+By default, it shows all accounts and their latest ending balances.
-You can limit the depth of accounts displayed, to see less detail, by pressing `-`.
+if you specify a query on the command line, it shows just the matched accounts and the balances from matched transactions.
-`+` (or `=`) increases the depth limit again.
+
-Or, press a number key to set a specific depth limit, eg `1` to see just top level accounts.
+When not in flat mode, indentation indicates the account hierarchy. `F` toggles flat mode on and off.
-Use the cursor keys to move up or down, and cursor right (or enter) to view an account's transaction register.
+
+By default, all subaccounts are displayed.
+To see less detail, set a depth limit by pressing a number key, `1` to `9`.
+Or, adjust the depth limit by pressing `-` or `+` (`=` also works).
+`0` removes the depth limit.
+
+`C` toggles cleared mode. In cleared mode, the accounts and balances
+are derived only from transactions which are marked cleared (*).
+
+Press `right` or `enter` to view an account's transactions register.
 
 ##### Register screen
 
-This screen shows a register of transactions affecting a particular account -
+This screen lists all transactions affecting a particular account (like a check register).
-all transactions, or just the matched ones if there was a query on the command line.
+In cleared mode (press `C`) it lists only transactions which are marked cleared.
+It does not otherwise filter by query.
 
-You can reach the register screen by pressing cursor right or enter on
+Note this screen shows transactions, not postings (unlike hledger's
-the accounts screen, or jump directly to it at startup by specifying
+register command). This means:
-an account with `--register ACCTREGEX` on the command line.
-The cursor left key returns to the accounts screen.
 
-The register screen shows transactions (like the register in
+- Each line represents a whole transaction.
-hledger-web, and other accounting systems), rather than postings
-(like hledger's register command). This means:
 
-- It shows transactions affecting a selected current account, rather
+- For each transaction, it shows the other account(s) involved, in
-  than postings matching a pattern. Each line represents a whole transaction.
+  abbreviated form. (If there are both real and virtual postings, it
+  shows only the accounts affected by real postings.)
 
-- It lists the other account(s) involved in the transaction, in
+- It shows the overall change to the current account's balance from
-  abbreviated form. (As an exception, if both real and virtual
+  each transaction; positive for an inflow to this account, negative
-  postings are involved, only the accounts affected by real postings
-  are listed.)
-
-- The amount field shows the overall effect of the transaction on the
-  current account; positive for an inflow to this account, negative
   for an outflow.
 
-- When possible, the balance field shows the current account's
+- When no query other than a date limit is in effect, it shows the
-  historic balance as of the transaction date, rather than a running
+  current account's historic balance as of the transaction date.
-  total starting from 0.
+  Otherwise it shows a running total starting from zero.  Eg, these
-
+  will show historic balances:
-    Specifically, the register shows historic balances when no query
-  other than a date limit is in effect. Eg:
 
     ```
     $ hledger-ui
-    $ hledger-ui -b 'this month'
+    $ hledger-ui --begin 'this month'
     $ hledger-ui --register checking date:2015/10
     ```
 
-    whereas the following would revert to showing a running total
+    while these will show a running total, since the queries are not just date limits:
-    instead, since they are not just date-limited:
 
     ```
     $ hledger-ui checking
-    $ hledger-ui -b 'this month' --cleared
+    $ hledger-ui --begin 'this month' desc:market
-    $ hledger-ui --register checking desc:market
+    $ hledger-ui --register checking --cleared
     ```
 
+Press `right` or `enter` to view the selected transaction in full detail.
+
 ##### Transaction screen
 
-Pressing cursor right or enter on a transaction in the register screen
+This screen shows a single transaction, as a general journal entry,
-will display the transaction in full, as a general journal entry
+similar to hledger's print command and journal format (hledger_journal(5)).
-(similar to `hledger print`).
-This shows more detail, such as the cleared status, transaction code,
-comments and tags, and the individual account postings.
 
-You can use the cursor up/down keys to step through all transactions
+The transaction's date(s) and any cleared flag, transaction code,
-listed in the previous account register screen. Cursor left returns to
+description, comments, along with all of its account postings are
-that screen.
+shown.  Simple transactions have two postings, but there can be more
+(or in certain cases, fewer).
+
+`up` and `down` will step through all transactions listed in the
+previous account register screen.  In the title bar, the numbers in
+parentheses show your position within that account register. They will
+vary depending on which account register you came from (remember most
+transactions appear in multiple account registers). The #N number
+preceding them is the transaction's position within the complete
+unfiltered journal, which is a more stable id (at least until the next
+reload).
 
 ##### Error screen
 

hledger-ui/Hledger/UI/AccountsScreen.hs

@@ -23,7 +23,7 @@ import qualified Data.Vector as V
 import Graphics.Vty as Vty
 import Brick
 import Brick.Widgets.List
--- import Brick.Widgets.Border
+import Brick.Widgets.Border (borderAttr)
 -- import Brick.Widgets.Center
 
 import Hledger
@@ -104,6 +104,7 @@ drawAccountsScreen _st@AppState{aopts=uopts, ajournal=j, aScreen=AccountsScreen{
       toplabel = files
               <+> str " accounts"
               <+> borderQueryStr querystr
+              <+> cleared
               <+> borderDepthStr mdepth
               <+> str " ("
               <+> cur
@@ -117,6 +118,9 @@ drawAccountsScreen _st@AppState{aopts=uopts, ajournal=j, aScreen=AccountsScreen{
                      -- f:fs  -> (withAttr ("border" <> "bold") $ str $ takeFileName f) <+> str (" (& " ++ show (length fs) ++ " included files)")
       querystr = query_ $ reportopts_ $ cliopts_ uopts
       mdepth = depth_ $ reportopts_ $ cliopts_ uopts
+      cleared = if (cleared_ $ reportopts_ $ cliopts_ uopts)
+                then str " with " <+> withAttr (borderAttr <> "query") (str "cleared") <+> str " txns"
+                else str ""
       cur = str (case l^.listSelectedL of
                   Nothing -> "-"
                   Just i -> show (i + 1))
@@ -124,9 +128,10 @@ drawAccountsScreen _st@AppState{aopts=uopts, ajournal=j, aScreen=AccountsScreen{
 
       bottomlabel = borderKeysStr [
          -- ("up/down/pgup/pgdown/home/end", "move")
-         ("-+=1234567890", "adjust depth limit")
+         ("-=1234567890", "depth")
-        ,("f", "flat/tree mode")
+        ,("F", "flat?")
-        ,("right/enter", "show register")
+        ,("C", "cleared?")
+        ,("right/enter", "register")
         ,("g", "reload")
         ,("q", "quit")
         ]
@@ -200,7 +205,6 @@ drawAccountsItem (acctwidth, balwidth) selected (indent, _fullacct, displayacct,
 handleAccountsScreen :: AppState -> Vty.Event -> EventM (Next AppState)
 handleAccountsScreen st@AppState{
    aScreen=scr@AccountsScreen{asState=(l,selacct)}
-  ,aopts=UIOpts{cliopts_=copts@CliOpts{reportopts_=ropts}}
   ,ajournal=j
   } e = do
     d <- liftIO getCurrentDay
@@ -240,15 +244,8 @@ handleAccountsScreen st@AppState{
         Vty.EvKey (Vty.KChar '8') [] -> continue $ reload j d $ setDepth 8 st'
         Vty.EvKey (Vty.KChar '9') [] -> continue $ reload j d $ setDepth 9 st'
         Vty.EvKey (Vty.KChar '0') [] -> continue $ reload j d $ setDepth 0 st'
-        Vty.EvKey (Vty.KChar 'f') [] -> continue $ reload j d $ st''
+        Vty.EvKey (Vty.KChar 'F') [] -> continue $ reload j d $ stToggleFlat st'
-          where
+        Vty.EvKey (Vty.KChar 'C') [] -> continue $ reload j d $ stToggleCleared st'
-            st'' = st'{
-              aopts=(aopts st'){
-                 cliopts_=copts{
-                    reportopts_=toggleFlatMode ropts
-                    }
-                 }
-              }
         Vty.EvKey (Vty.KLeft) []     -> continue $ popScreen st'
         Vty.EvKey (k) [] | k `elem` [Vty.KRight, Vty.KEnter] -> do
           let
@@ -264,6 +261,10 @@ handleAccountsScreen st@AppState{
                                  -- continue =<< handleEventLensed st' someLens ev
 handleAccountsScreen _ _ = error "event handler called with wrong screen type, should not happen"
 
+stToggleFlat :: AppState -> AppState
+stToggleFlat st@AppState{aopts=uopts@UIOpts{cliopts_=copts@CliOpts{reportopts_=ropts}}} =
+  st{aopts=uopts{cliopts_=copts{reportopts_=toggleFlatMode ropts}}}
+
 -- | Toggle between flat and tree mode. If in the third "default" mode, go to flat mode.
 toggleFlatMode :: ReportOpts -> ReportOpts
 toggleFlatMode ropts@ReportOpts{accountlistmode_=ALFlat} = ropts{accountlistmode_=ALTree}

hledger-ui/Hledger/UI/RegisterScreen.hs

@@ -19,8 +19,7 @@ import qualified Data.Vector as V
 import Graphics.Vty as Vty
 import Brick
 import Brick.Widgets.List
--- import Brick.Widgets.Border
+import Brick.Widgets.Border (borderAttr)
--- import Brick.Widgets.Border.Style
 -- import Brick.Widgets.Center
 -- import Text.Printf
 
@@ -90,10 +89,11 @@ initRegisterScreen d st@AppState{aopts=opts, ajournal=j, aScreen=s@RegisterScree
 initRegisterScreen _ _ = error "init function called with wrong screen type, should not happen"
 
 drawRegisterScreen :: AppState -> [Widget]
-drawRegisterScreen AppState{ -- aopts=_uopts@UIOpts{cliopts_=_copts@CliOpts{reportopts_=_ropts@ReportOpts{query_=querystr}}},
+drawRegisterScreen AppState{aopts=uopts -- @UIOpts{cliopts_=_copts@CliOpts{reportopts_=_ropts@ReportOpts{query_=querystr}}
-                             aScreen=RegisterScreen{rsState=(l,acct)}} = [ui]
+                           ,aScreen=RegisterScreen{rsState=(l,acct)}} = [ui]
   where
     toplabel = withAttr ("border" <> "bold") (str acct)
+            <+> cleared
             <+> str " transactions"
             -- <+> borderQueryStr querystr -- no, account transactions report shows all transactions in the acct ?
             -- <+> str " and subs"
@@ -102,6 +102,9 @@ drawRegisterScreen AppState{ -- aopts=_uopts@UIOpts{cliopts_=_copts@CliOpts{repo
             <+> str "/"
             <+> total
             <+> str ")"
+    cleared = if (cleared_ $ reportopts_ $ cliopts_ uopts)
+              then withAttr (borderAttr <> "query") (str " cleared")
+              else str ""
     cur = str $ case l^.listSelectedL of
                  Nothing -> "-"
                  Just i -> show (i + 1)
@@ -157,8 +160,9 @@ drawRegisterScreen AppState{ -- aopts=_uopts@UIOpts{cliopts_=_copts@CliOpts{repo
 
         bottomlabel = borderKeysStr [
            -- ("up/down/pgup/pgdown/home/end", "move")
-           ("left", "return to accounts")
+           ("left", "back")
-          ,("right/enter", "show transaction")
+          ,("C", "cleared?")
+          ,("right/enter", "transaction")
           ,("g", "reload")
           ,("q", "quit")
           ]
@@ -205,6 +209,8 @@ handleRegisterScreen st@AppState{
         Right j' -> continue $ reload j' d st
         Left err -> continue $ screenEnter d ES.screen{esState=err} st
 
+    Vty.EvKey (Vty.KChar 'C') [] -> continue $ reload j d $ stToggleCleared st
+
     Vty.EvKey (Vty.KLeft) []     -> continue $ popScreen st
 
     Vty.EvKey (k) [] | k `elem` [Vty.KRight, Vty.KEnter] -> do

hledger-ui/Hledger/UI/Theme.hs

@@ -69,8 +69,8 @@ themesList = [
               ("error", currentAttr `withForeColor` red),
               (borderAttr       , white `on` black & dim),
               (borderAttr <> "bold", white `on` black & bold),
-              (borderAttr <> "query", yellow `on` black & bold),
+              (borderAttr <> "query", cyan `on` black & bold),
-              (borderAttr <> "depth", cyan `on` black & bold),
+              (borderAttr <> "depth", yellow `on` black & bold),
               (borderAttr <> "keys", white `on` black & bold),
               -- ("normal"                , black `on` white),
               ("list"                  , black `on` white),      -- regular list items

hledger-ui/Hledger/UI/TransactionScreen.hs

@@ -51,12 +51,15 @@ drawTransactionScreen AppState{ -- aopts=_uopts@UIOpts{cliopts_=_copts@CliOpts{r
     -- datedesc = show (tdate t) ++ " " ++ tdescription t
     toplabel =
       str "Transaction "
-      -- <+> withAttr ("border" <> "bold") (str $ 
+      -- <+> withAttr ("border" <> "bold") (str $ "#" ++ show (tindex t))
+      -- <+> str (" ("++show i++" of "++show (length nts)++" in "++acct++")")
+      <+> (str $ "#" ++ show (tindex t))
+      <+> str " ("
       <+> withAttr ("border" <> "bold") (str $ show i)
-      <+> str (" of "++show (length nts)++" in "++acct)
+      <+> str (" of "++show (length nts)++" in "++acct++")")
     bottomlabel = borderKeysStr [
-       ("left", "return to register")
+       ("left", "back")
-      ,("up/down", "prev/next transaction")
+      ,("up/down", "prev/next")
       ,("g", "reload")
       ,("q", "quit")
       ]
@@ -86,6 +89,8 @@ handleTransactionScreen st@AppState{
         Right j' -> continue $ reload j' d st
         Left err -> continue $ screenEnter d ES.screen{esState=err} st
 
+    -- Vty.EvKey (Vty.KChar 'C') [] -> continue $ reload j d $ stToggleCleared st
+
     Vty.EvKey (Vty.KUp) []       -> continue $ reload j d st{aScreen=s{tsState=((iprev,tprev),nts,acct)}}
     Vty.EvKey (Vty.KDown) []     -> continue $ reload j d st{aScreen=s{tsState=((inext,tnext),nts,acct)}}
 

hledger-ui/Hledger/UI/UIUtils.hs

@@ -14,6 +14,8 @@ module Hledger.UI.UIUtils (
  ,borderQueryStr
  ,borderDepthStr
  ,borderKeysStr
+ --
+ ,stToggleCleared
  ) where
 
 import Control.Lens ((^.))
@@ -31,9 +33,20 @@ import Graphics.Vty as Vty
 
 import Hledger.UI.UITypes
 import Hledger.Data.Types (Journal)
+import Hledger.UI.UIOptions
+import Hledger.Cli.CliOptions
+import Hledger.Reports.ReportOptions
 import Hledger.Utils (applyN)
 -- import Hledger.Utils.Debug
 
+stToggleCleared :: AppState -> AppState
+stToggleCleared st@AppState{aopts=uopts@UIOpts{cliopts_=copts@CliOpts{reportopts_=ropts}}} =
+  st{aopts=uopts{cliopts_=copts{reportopts_=toggleCleared ropts}}}
+
+-- | Toggle between showing all and showing only cleared items.
+toggleCleared :: ReportOpts -> ReportOpts
+toggleCleared ropts = ropts{cleared_=not $ cleared_ ropts}
+
 -- | Regenerate the content for the current and previous screens, from a new journal and current date.
 reload :: Journal -> Day -> AppState -> AppState
 reload j d st@AppState{aScreen=s,aPrevScreens=ss} =
@@ -171,7 +184,8 @@ borderKeysStr :: [(String,String)] -> Widget
 borderKeysStr keydescs =
   hBox $
   intersperse sep $
-  [withAttr (borderAttr <> "keys") (str keys) <+> str ": " <+> str desc | (keys, desc) <- keydescs]
+  [withAttr (borderAttr <> "keys") (str keys) <+> str ":" <+> str desc | (keys, desc) <- keydescs]
   where
-    sep = str " | "
+    -- sep = str " | "
-    -- sep = "  "
+    sep = str " "
+

hledger-ui/hledger-ui.1.md

@@ -107,77 +107,96 @@ The following common hledger options should also work:
 `-B --cost`
 : show amounts in their cost price's commodity
 
+# KEYS
+
+Generally the cursor keys navigate; `right` (or `enter`) goes deeper, `left` returns to the previous screen,
+`up`/`down`/`page up`/`page down`/`home`/`end` move up and down through lists.
+
+`g` gets the latest data and reloads the screen (and any previous screens). There may be a noticeable pause.
+
+`q` quits the application.
+
+Some screens have additional key bindings, described below.
+
 # SCREENS
 
 ## Accounts screen
 
-This is the screen shown at startup by default.
+This is normally the first screen displayed.
-It shows a scrollable list of accounts and their balances - all accounts, or just the matched accounts if you specified a query on the command line.
+It lists accounts and their balances, like hledger's balance command.
-`f` toggles flat mode on and off.
+By default, it shows all accounts and their latest ending balances.
-You can limit the depth of accounts displayed, to see less detail, by pressing `-`.
+if you specify a query on the command line, it shows just the matched accounts and the balances from matched transactions.
-`+` (or `=`) increases the depth limit again.
+
-Or, press a number key to set a specific depth limit, eg `1` to see just top level accounts.
+When not in flat mode, indentation indicates the account hierarchy. `F` toggles flat mode on and off.
-Use the cursor keys to move up or down, and cursor right (or enter) to view an account's transaction register.
+
+By default, all subaccounts are displayed.
+To see less detail, set a depth limit by pressing a number key, `1` to `9`.
+Or, adjust the depth limit by pressing `-` or `+` (`=` also works).
+`0` removes the depth limit.
+
+`C` toggles cleared mode. In cleared mode, the accounts and balances
+are derived only from transactions which are marked cleared (*).
+
+Press `right` or `enter` to view an account's transactions register.
 
 ## Register screen
 
-This screen shows a register of transactions affecting a particular account -
+This screen lists all transactions affecting a particular account (like a check register).
-all transactions, or just the matched ones if there was a query on the command line.
+In cleared mode (press `C`) it lists only transactions which are marked cleared.
+It does not otherwise filter by query.
 
-You can reach the register screen by pressing cursor right or enter on
+Note this screen shows transactions, not postings (unlike hledger's
-the accounts screen, or jump directly to it at startup by specifying
+register command). This means:
-an account with `--register ACCTREGEX` on the command line.
-The cursor left key returns to the accounts screen.
 
-The register screen shows transactions (like the register in
+- Each line represents a whole transaction.
-hledger-web, and other accounting systems), rather than postings
-(like hledger's register command). This means:
 
-- It shows transactions affecting a selected current account, rather
+- For each transaction, it shows the other account(s) involved, in
-  than postings matching a pattern. Each line represents a whole transaction.
+  abbreviated form. (If there are both real and virtual postings, it
+  shows only the accounts affected by real postings.)
 
-- It lists the other account(s) involved in the transaction, in
+- It shows the overall change to the current account's balance from
-  abbreviated form. (As an exception, if both real and virtual
+  each transaction; positive for an inflow to this account, negative
-  postings are involved, only the accounts affected by real postings
-  are listed.)
-
-- The amount field shows the overall effect of the transaction on the
-  current account; positive for an inflow to this account, negative
   for an outflow.
 
-- When possible, the balance field shows the current account's
+- When no query other than a date limit is in effect, it shows the
-  historic balance as of the transaction date, rather than a running
+  current account's historic balance as of the transaction date.
-  total starting from 0.
+  Otherwise it shows a running total starting from zero.  Eg, these
-
+  will show historic balances:
-    Specifically, the register shows historic balances when no query
-  other than a date limit is in effect. Eg:
 
     ```
     $ hledger-ui
-    $ hledger-ui -b 'this month'
+    $ hledger-ui --begin 'this month'
     $ hledger-ui --register checking date:2015/10
     ```
 
-    whereas the following would revert to showing a running total
+    while these will show a running total, since the queries are not just date limits:
-    instead, since they are not just date-limited:
 
     ```
     $ hledger-ui checking
-    $ hledger-ui -b 'this month' --cleared
+    $ hledger-ui --begin 'this month' desc:market
-    $ hledger-ui --register checking desc:market
+    $ hledger-ui --register checking --cleared
     ```
 
+Press `right` or `enter` to view the selected transaction in full detail.
+
 ## Transaction screen
 
-Pressing cursor right or enter on a transaction in the register screen
+This screen shows a single transaction, as a general journal entry,
-will display the transaction in full, as a general journal entry
+similar to hledger's print command and journal format (hledger_journal(5)).
-(similar to `hledger print`).
-This shows more detail, such as the cleared status, transaction code,
-comments and tags, and the individual account postings.
 
-You can use the cursor up/down keys to step through all transactions
+The transaction's date(s) and any cleared flag, transaction code,
-listed in the previous account register screen. Cursor left returns to
+description, comments, along with all of its account postings are
-that screen.
+shown.  Simple transactions have two postings, but there can be more
+(or in certain cases, fewer).
+
+`up` and `down` will step through all transactions listed in the
+previous account register screen.  In the title bar, the numbers in
+parentheses show your position within that account register. They will
+vary depending on which account register you came from (remember most
+transactions appear in multiple account registers). The #N number
+preceding them is the transaction's position within the complete
+unfiltered journal, which is a more stable id (at least until the next
+reload).
 
 ## Error screen