hledger-ui's application state. This holds one or more stateful screens. As you navigate through screens, the old ones are saved in a stack. The app can be in one of several modes: normal screen operation, showing a help dialog, entering data in the minibuffer etc.

Any screen can be in one of several modes, which modifies its rendering and event handling. The mode resets to Normal when entering a new screen.

hledger-ui screen types, v1, "one screen = one module" These types aimed for maximum decoupling of modules and ease of adding more screens. A new screen requires 1. a new constructor in the Screen type, 2. a new module implementing initdrawhandle functions, 3. a call from any other screen which enters it. Each screen type has generically named initialisation, draw, and event handling functions, and zero or more uniquely named screen state fields, which hold the data for a particular instance of this screen. Note the latter create partial functions, which means that some invalid cases need to be handled, and also that their lenses are traversals, not single-value getters. data Screen = AccountsScreen { sInit :: Day -> Bool -> UIState -> UIState -- ^ function to initialise or update this screen's state ,sDraw :: UIState -> [Widget Name] -- ^ brick renderer for this screen ,sHandle :: BrickEvent Name AppEvent -> EventM Name UIState () -- ^ brick event handler for this screen -- state fields.These ones have lenses: ,_asList :: List Name AccountsScreenItem -- ^ list widget showing account names & balances ,_asSelectedAccount :: AccountName -- ^ a backup of the account name from the list widget's selected item (or "") } | RegisterScreen { sInit :: Day -> Bool -> UIState -> UIState ,sDraw :: UIState -> [Widget Name] ,sHandle :: BrickEvent Name AppEvent -> EventM Name UIState () -- ,rsList :: List Name RegisterScreenItem -- ^ list widget showing transactions affecting this account ,rsAccount :: AccountName -- ^ the account this register is for ,rsForceInclusive :: Bool -- ^ should this register always include subaccount transactions, -- even when in flat mode ? (ie because entered from a -- depth-clipped accounts screen item) } | TransactionScreen { sInit :: Day -> Bool -> UIState -> UIState ,sDraw :: UIState -> [Widget Name] ,sHandle :: BrickEvent Name AppEvent -> EventM Name UIState () -- ,tsTransaction :: NumberedTransaction -- ^ the transaction we are currently viewing, and its position in the list ,tsTransactions :: [NumberedTransaction] -- ^ list of transactions we can step through ,tsAccount :: AccountName -- ^ the account whose register we entered this screen from } | ErrorScreen { sInit :: Day -> Bool -> UIState -> UIState ,sDraw :: UIState -> [Widget Name] ,sHandle :: BrickEvent Name AppEvent -> EventM Name UIState () -- ,esError :: String -- ^ error message to show } deriving (Show)

hledger-ui screen types, v2, "more parts, but simpler parts" These types aim to be more restrictive, allowing fewer invalid states, and easier to inspect and debug. The screen types store only state, not behaviour (functions), and there is no longer a circular dependency between UIState and Screen. A new screen requires 1. a new constructor in the Screen type 2. a new screen state type if needed 3. a new case in toAccountsLikeScreen if needed 4. new cases in the uiDraw and uiHandle functions 5. new constructor and updater functions in UIScreens, and a new case in screenUpdate 6. a new module implementing draw and event-handling functions 7. a call from any other screen which enters it (eg the menu screen, a new case in msEnterScreen) 8. if it appears on the main menu: a new menu item in msNew

The various screens which a user can navigate to in hledger-ui, along with any screen-specific parameters or data influencing what they display. (The separate state types add code noise but seem to reduce partial code/invalid data a bit.)

A subset of the screens which reuse the account screen's state and logic. Such Screens can be converted to and from this more restrictive type for cleaner code.

An item in the menu screen's list of screens.

An item in the accounts screen's list of accounts and balances.

An item in the register screen's list of transactions in the current account.

Error message to use in case statements adapting to the different Screen shapes.