Brick.Main

Documentation

data App s e n

The library application abstraction. Your application's operations are provided in an App and then the App is provided to one of the various main functions in this module. An application App s e n is in terms of an application state type s, an application event type e, and a resource name type n. In the simplest case e is unused (left polymorphic or set to ()), but you may define your own event type and use customMain to provide custom events. The state type s is the type of application state to be provided by you and iteratively modified by event handlers. The resource name type n is the type of names you can assign to rendering resources such as viewports and cursor locations. Your application must define this type.

Constructors

App

Fields

• appDraw :: s -> [Widget n]

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

• appChooseCursor :: s -> [CursorLocation n] -> Maybe (CursorLocation n)

  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 -> BrickEvent n e -> EventM n (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 n 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.

defaultMain

Arguments

:: Ord n

=> App s e n

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

:: Ord n

=> Vty

The initial Vty handle to use.

-> IO Vty

An IO action to build a Vty handle. This is used to build a Vty handle whenever the event loop needs to reinitialize the terminal, e.g. on resume after suspension.

-> Maybe (BChan e)

An event channel for sending custom events to the event loop (you write to this channel, the event loop reads from it). Provide Nothing if you don't plan on sending custom events.

-> App s e n

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. Returns the final application state after the application halts.

Note that this function guarantees that the terminal input state prior to the first Vty initialization is the terminal input state that is restored on shutdown (regardless of exceptions).

customMainWithVty

Arguments

:: Ord n

=> Vty

The initial Vty handle to use.

-> IO Vty

An IO action to build a Vty handle. This is used to build a Vty handle whenever the event loop needs to reinitialize the terminal, e.g. on resume after suspension.

-> Maybe (BChan e)

An event channel for sending custom events to the event loop (you write to this channel, the event loop reads from it). Provide Nothing if you don't plan on sending custom events.

-> App s e n

The application.

-> s

The initial application state.

-> IO (s, Vty)

Like customMain, except the last Vty handle used by the application is returned without being shut down with shutdown. This allows the caller to re-use the Vty handle for something else, such as another Brick application.

simpleMain

Arguments

:: Ord n

=> Widget n

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 -> BrickEvent n e -> EventM n (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.

simpleApp :: Widget n -> App s e n

A simple application with reasonable defaults to be overridden as desired:

• Draws only the specified widget
• Quits on any event other than resizes
• Has no start event handler
• Provides no attribute map
• Never shows any cursors

Event handler functions

continue :: s -> EventM n (Next s)

Continue running the event loop with the specified application state.

halt :: s -> EventM n (Next s)

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

suspendAndResume :: IO s -> EventM n (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, empty the rendering cache, redraw the application from the new state, and resume the event loop.

Note that any changes made to the terminal's input state are ignored when Brick resumes execution and are not preserved in the final terminal input state after the Brick application returns the terminal to the user.

lookupViewport :: Ord n => n -> EventM n (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).

lookupExtent :: Eq n => n -> EventM n (Maybe (Extent n))

Given a resource name, get the most recent rendering extent for the name (if any).

findClickedExtents :: (Int, Int) -> EventM n [Extent n]

Given a mouse click location, return the extents intersected by the click. The returned extents are sorted such that the first extent in the list is the most specific extent and the last extent is the most generic (top-level). So if two extents A and B both intersected the mouse click but A contains B, then they would be returned [B, A].

clickedExtent :: (Int, Int) -> Extent n -> Bool

Did the specified mouse coordinates (column, row) intersect the specified extent?

getVtyHandle :: EventM n Vty

Get the Vty handle currently in use.

Viewport scrolling

viewportScroll :: n -> ViewportScroll n

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

data ViewportScroll n

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

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

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

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

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

vScrollToBeginning :: ViewportScroll n -> EventM n ()

Scroll vertically to the beginning of the viewport.

vScrollToEnd :: ViewportScroll n -> EventM n ()

Scroll vertically to the end of the viewport.

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

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

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

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

hScrollToBeginning :: ViewportScroll n -> EventM n ()

Scroll horizontally to the beginning of the viewport.

hScrollToEnd :: ViewportScroll n -> EventM n ()

Scroll horizontally to the end of the viewport.

setTop :: ViewportScroll n -> Int -> EventM n ()

Set the top row offset of the viewport.

setLeft :: ViewportScroll n -> Int -> EventM n ()

Set the left column offset of the viewport.

Cursor management functions

neverShowCursor :: s -> [CursorLocation n] -> Maybe (CursorLocation n)

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 n] -> Maybe (CursorLocation n)

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 :: Eq n => n -> [CursorLocation n] -> Maybe (CursorLocation n)

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

Rendering cache management

invalidateCacheEntry :: Ord n => n -> EventM n ()

Invalidate the rendering cache entry with the specified resource name.

invalidateCache :: Ord n => EventM n ()

Invalidate the entire rendering cache.

Renderer internals (for benchmarking)

renderFinal :: AttrMap -> [Widget n] -> DisplayRegion -> ([CursorLocation n] -> Maybe (CursorLocation n)) -> RenderState n -> (RenderState n, Picture, Maybe (CursorLocation n), [Extent n])

getRenderState :: EventM n (RenderState n)

resetRenderState :: RenderState n -> RenderState n