diff --git a/doc/manual.md b/doc/manual.md index b0e11ddcc..288860239 100644 --- a/doc/manual.md +++ b/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. -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. -`f` toggles flat mode on and off. -You can limit the depth of accounts displayed, to see less detail, by pressing `-`. -`+` (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. -Use the cursor keys to move up or down, and cursor right (or enter) to view an account's transaction register. +This is normally the first screen displayed. +It lists accounts and their balances, like hledger's balance command. +By default, it shows all accounts and their latest ending balances. +if you specify a query on the command line, it shows just the matched accounts and the balances from matched transactions. + +When not in flat mode, indentation indicates the account hierarchy. `F` toggles flat mode on and off. + +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 - -all transactions, or just the matched ones if there was a query on the command line. +This screen lists all transactions affecting a particular account (like a check register). +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 -the accounts screen, or jump directly to it at startup by specifying -an account with `--register ACCTREGEX` on the command line. -The cursor left key returns to the accounts screen. +Note this screen shows transactions, not postings (unlike hledger's +register command). This means: -The register screen shows transactions (like the register in -hledger-web, and other accounting systems), rather than postings -(like hledger's register command). This means: +- Each line represents a whole transaction. -- It shows transactions affecting a selected current account, rather - than postings matching a pattern. Each line represents a whole transaction. +- For each transaction, it shows the other account(s) involved, in + 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 - abbreviated form. (As an exception, if both real and virtual - 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 +- It shows the overall change to the current account's balance from + each transaction; positive for an inflow to this account, negative for an outflow. -- When possible, the balance field shows the current account's - historic balance as of the transaction date, rather than a running - total starting from 0. - - Specifically, the register shows historic balances when no query - other than a date limit is in effect. Eg: +- When no query other than a date limit is in effect, it shows the + current account's historic balance as of the transaction date. + Otherwise it shows a running total starting from zero. Eg, these + will show historic balances: ``` $ 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 - instead, since they are not just date-limited: + while these will show a running total, since the queries are not just date limits: ``` $ hledger-ui checking - $ hledger-ui -b 'this month' --cleared - $ hledger-ui --register checking desc:market + $ hledger-ui --begin 'this month' 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 -will display the transaction in full, as a general journal entry -(similar to `hledger print`). -This shows more detail, such as the cleared status, transaction code, -comments and tags, and the individual account postings. +This screen shows a single transaction, as a general journal entry, +similar to hledger's print command and journal format (hledger_journal(5)). -You can use the cursor up/down keys to step through all transactions -listed in the previous account register screen. Cursor left returns to -that screen. +The transaction's date(s) and any cleared flag, transaction code, +description, comments, along with all of its account postings are +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 diff --git a/hledger-ui/Hledger/UI/AccountsScreen.hs b/hledger-ui/Hledger/UI/AccountsScreen.hs index 63e54f8fc..87c1e056b 100644 --- a/hledger-ui/Hledger/UI/AccountsScreen.hs +++ b/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") - ,("f", "flat/tree mode") - ,("right/enter", "show register") + ("-=1234567890", "depth") + ,("F", "flat?") + ,("C", "cleared?") + ,("right/enter", "register") ,("g", "reload") ,("q", "quit") ] @@ -199,8 +204,7 @@ 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}} + aScreen=scr@AccountsScreen{asState=(l,selacct)} ,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'' - where - st'' = st'{ - aopts=(aopts st'){ - cliopts_=copts{ - reportopts_=toggleFlatMode ropts - } - } - } + Vty.EvKey (Vty.KChar 'F') [] -> continue $ reload j d $ stToggleFlat 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 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} diff --git a/hledger-ui/Hledger/UI/RegisterScreen.hs b/hledger-ui/Hledger/UI/RegisterScreen.hs index 82582fd82..1424df923 100644 --- a/hledger-ui/Hledger/UI/RegisterScreen.hs +++ b/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.Style +import Brick.Widgets.Border (borderAttr) -- 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}}}, - aScreen=RegisterScreen{rsState=(l,acct)}} = [ui] +drawRegisterScreen AppState{aopts=uopts -- @UIOpts{cliopts_=_copts@CliOpts{reportopts_=_ropts@ReportOpts{query_=querystr}} + ,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") - ,("right/enter", "show transaction") + ("left", "back") + ,("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 diff --git a/hledger-ui/Hledger/UI/Theme.hs b/hledger-ui/Hledger/UI/Theme.hs index 950a55c9f..a86b31ff3 100644 --- a/hledger-ui/Hledger/UI/Theme.hs +++ b/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 <> "depth", cyan `on` black & bold), + (borderAttr <> "query", 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 diff --git a/hledger-ui/Hledger/UI/TransactionScreen.hs b/hledger-ui/Hledger/UI/TransactionScreen.hs index 1e97895b1..5ffc6031d 100644 --- a/hledger-ui/Hledger/UI/TransactionScreen.hs +++ b/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") - ,("up/down", "prev/next transaction") + ("left", "back") + ,("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)}} diff --git a/hledger-ui/Hledger/UI/UIUtils.hs b/hledger-ui/Hledger/UI/UIUtils.hs index 52351173b..22af49643 100644 --- a/hledger-ui/Hledger/UI/UIUtils.hs +++ b/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 = " " + -- sep = str " | " + sep = str " " + diff --git a/hledger-ui/hledger-ui.1.md b/hledger-ui/hledger-ui.1.md index 5c837c853..cc584416e 100644 --- a/hledger-ui/hledger-ui.1.md +++ b/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. -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. -`f` toggles flat mode on and off. -You can limit the depth of accounts displayed, to see less detail, by pressing `-`. -`+` (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. -Use the cursor keys to move up or down, and cursor right (or enter) to view an account's transaction register. +This is normally the first screen displayed. +It lists accounts and their balances, like hledger's balance command. +By default, it shows all accounts and their latest ending balances. +if you specify a query on the command line, it shows just the matched accounts and the balances from matched transactions. + +When not in flat mode, indentation indicates the account hierarchy. `F` toggles flat mode on and off. + +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 - -all transactions, or just the matched ones if there was a query on the command line. +This screen lists all transactions affecting a particular account (like a check register). +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 -the accounts screen, or jump directly to it at startup by specifying -an account with `--register ACCTREGEX` on the command line. -The cursor left key returns to the accounts screen. +Note this screen shows transactions, not postings (unlike hledger's +register command). This means: -The register screen shows transactions (like the register in -hledger-web, and other accounting systems), rather than postings -(like hledger's register command). This means: +- Each line represents a whole transaction. -- It shows transactions affecting a selected current account, rather - than postings matching a pattern. Each line represents a whole transaction. +- For each transaction, it shows the other account(s) involved, in + 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 - abbreviated form. (As an exception, if both real and virtual - 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 +- It shows the overall change to the current account's balance from + each transaction; positive for an inflow to this account, negative for an outflow. -- When possible, the balance field shows the current account's - historic balance as of the transaction date, rather than a running - total starting from 0. - - Specifically, the register shows historic balances when no query - other than a date limit is in effect. Eg: +- When no query other than a date limit is in effect, it shows the + current account's historic balance as of the transaction date. + Otherwise it shows a running total starting from zero. Eg, these + will show historic balances: ``` $ 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 - instead, since they are not just date-limited: + while these will show a running total, since the queries are not just date limits: ``` $ hledger-ui checking - $ hledger-ui -b 'this month' --cleared - $ hledger-ui --register checking desc:market + $ hledger-ui --begin 'this month' 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 -will display the transaction in full, as a general journal entry -(similar to `hledger print`). -This shows more detail, such as the cleared status, transaction code, -comments and tags, and the individual account postings. +This screen shows a single transaction, as a general journal entry, +similar to hledger's print command and journal format (hledger_journal(5)). -You can use the cursor up/down keys to step through all transactions -listed in the previous account register screen. Cursor left returns to -that screen. +The transaction's date(s) and any cleared flag, transaction code, +description, comments, along with all of its account postings are +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