Brick.Main

Documentation

data App s e

The library application abstraction. Your application's operations are represented here and passed to one of the various main functions in this module. An application is in terms of an application state type s and an application event type e. In the simplest case e is vty's Event type, but you may define your own event type, permitted that it has a constructor for wrapping Vty events, so that Vty events can be handled by your event loop.

Constructors

App

Fields

appDraw :: s -> [Widget]

This function turns your application state into a list of widget layers. The layers are listed topmost first.

appChooseCursor :: s -> [CursorLocation] -> Maybe CursorLocation

This function chooses which of the zero or more cursor locations reported by the rendering process should be selected as the one to use to place the cursor. If this returns Nothing, no cursor is placed. The rationale here is that many widgets may request a cursor placement but your application state is what you probably want to use to decide which one wins.

appHandleEvent :: s -> e -> EventM (Next s)

This function takes the current application state and an event and returns an action to be taken and a corresponding transformed application state. Possible options are continue, suspendAndResume, and halt.

appStartEvent :: s -> EventM s

This function gets called once just prior to the first drawing of your application. Here is where you can make initial scrolling requests, for example.

appAttrMap :: s -> AttrMap

The attribute map that should be used during rendering.

appLiftVtyEvent :: Event -> e

The event constructor to use to wrap Vty events in your own event type. For example, if the application's event type is Event, this is just id.

defaultMain

Arguments

:: App s Event

The application.

-> s

The initial application state.

-> IO s

The default main entry point which takes an application and an initial state and returns the final state returned by a halt operation.

customMain

Arguments

:: IO Vty

An IO action to build a Vty handle. This is used to build a Vty handle whenever the event loop begins or is resumed after suspension.

-> Chan e

An event channel for sending custom events to the event loop (you write to this channel, the event loop reads from it).

-> App s e

The application.

-> s

The initial application state.

-> IO s

The custom event loop entry point to use when the simpler ones don't permit enough control.

simpleMain

Arguments

:: Widget

The widget to draw.

-> IO ()

A simple main entry point which takes a widget and renders it. This event loop terminates when the user presses any key, but terminal resize events cause redraws.

resizeOrQuit :: s -> Event -> EventM (Next s)

An event-handling function which continues execution of the event loop only when resize events occur; all other types of events trigger a halt. This is a convenience function useful as an appHandleEvent value for simple applications using the Event type that do not need to get more sophisticated user input.

Event handler functions

continue :: s -> EventM (Next s)

Continue running the event loop with the specified application state.

halt :: s -> EventM (Next s)

Halt the event loop and return the specified application state as the final state value.

suspendAndResume :: IO s -> EventM (Next s)

Suspend the event loop, save the terminal state, and run the specified action. When it returns an application state value, restore the terminal state, redraw the application from the new state, and resume the event loop.

lookupViewport :: Name -> EventM (Maybe Viewport)

Given a viewport name, get the viewport's size and offset information from the most recent rendering. Returns Nothing if no such state could be found, either because the name was invalid or because no rendering has occurred (e.g. in an appStartEvent handler).

Viewport scrolling

viewportScroll :: Name -> ViewportScroll

Build a viewport scroller for the viewport with the specified name.

data ViewportScroll

A viewport scrolling handle for managing the scroll state of viewports.

vScrollBy :: ViewportScroll -> Int -> EventM ()

Scroll the viewport vertically by the specified number of rows or columns depending on the orientation of the viewport.

vScrollPage :: ViewportScroll -> Direction -> EventM ()

Scroll the viewport vertically by one page in the specified direction.

vScrollToBeginning :: ViewportScroll -> EventM ()

Scroll vertically to the beginning of the viewport.

vScrollToEnd :: ViewportScroll -> EventM ()

Scroll vertically to the end of the viewport.

hScrollBy :: ViewportScroll -> Int -> EventM ()

Scroll the viewport horizontally by the specified number of rows or columns depending on the orientation of the viewport.

hScrollPage :: ViewportScroll -> Direction -> EventM ()

Scroll the viewport horizontally by one page in the specified direction.

hScrollToBeginning :: ViewportScroll -> EventM ()

Scroll horizontally to the beginning of the viewport.

hScrollToEnd :: ViewportScroll -> EventM ()

Scroll horizontally to the end of the viewport.

Cursor management functions

neverShowCursor :: s -> [CursorLocation] -> Maybe CursorLocation

Ignore all requested cursor positions returned by the rendering process. This is a convenience function useful as an appChooseCursor value when a simple application has no need to position the cursor.

showFirstCursor :: s -> [CursorLocation] -> Maybe CursorLocation

Always show the first cursor, if any, returned by the rendering process. This is a convenience function useful as an appChooseCursor value when a simple program has zero or more widgets that advertise a cursor position.

showCursorNamed :: Name -> [CursorLocation] -> Maybe CursorLocation

Show the cursor with the specified name, if such a cursor location has been reported.