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 :: BrickEvent n e -> EventM n s ()

  This function handles an event and updates the current application state.

• appStartEvent :: 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 from EventM once the program exits.

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.

customMainWithDefaultVty

Arguments

:: Ord n

=> 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 customMainWithVty, except that Vty is initialized with the default configuration.

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

continueWithoutRedraw :: EventM n s ()

Continue running the event loop with the specified application state without redrawing the screen. This is faster than continue because it skips the redraw, but the drawback is that you need to be really sure that you don't want a screen redraw. If your state changed in a way that needs to be reflected on the screen, just don't call this; EventM blocks default to triggering redraws when they finish executing. This function is for cases where you know that you did something that won't have an impact on the screen state and you want to save on redraw cost.

halt :: EventM n s ()

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

suspendAndResume :: Ord n => IO s -> EventM n 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, update the application state with the returned state, and continue execution of the event handler that called this.

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.

suspendAndResume' :: Ord n => IO a -> EventM n s a

Suspend the event loop, save the terminal state, and run the specified action. When it completes, restore the terminal state, empty the rendering cache, return the result, and continue execution of the event handler that called this.

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.

makeVisible :: Ord n => n -> EventM n s ()

Request that the specified UI element be made visible on the next rendering. This is provided to allow event handlers to make visibility requests in the same way that the visible function does at rendering time.

lookupViewport :: Ord n => n -> EventM n s (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). An important consequence of this behavior is that if this function is called before a viewport is rendered for the first time, no state will be found because the renderer only knows about viewports it has rendered in the most recent rendering. As a result, if you need to make viewport transformations before they are drawn for the first time, you may need to use viewportScroll and its associated functions without relying on this function. Those functions queue up scrolling requests that can be made in advance of the next rendering to affect the viewport.

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

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

findClickedExtents :: (Int, Int) -> EventM n s [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 s 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 -> forall s. Int -> EventM n s ()

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

vScrollPage :: ViewportScroll n -> forall s. Direction -> EventM n s ()

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

vScrollToBeginning :: ViewportScroll n -> forall s. EventM n s ()

Scroll vertically to the beginning of the viewport.

vScrollToEnd :: ViewportScroll n -> forall s. EventM n s ()

Scroll vertically to the end of the viewport.

hScrollBy :: ViewportScroll n -> forall s. Int -> EventM n s ()

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

hScrollPage :: ViewportScroll n -> forall s. Direction -> EventM n s ()

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

hScrollToBeginning :: ViewportScroll n -> forall s. EventM n s ()

Scroll horizontally to the beginning of the viewport.

hScrollToEnd :: ViewportScroll n -> forall s. EventM n s ()

Scroll horizontally to the end of the viewport.

setTop :: ViewportScroll n -> forall s. Int -> EventM n s ()

Set the top row offset of the viewport.

setLeft :: ViewportScroll n -> forall s. Int -> EventM n s ()

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 s ()

Invalidate the rendering cache entry with the specified resource name.

invalidateCache :: Ord n => EventM n s ()

Invalidate the entire rendering cache.

Renderer internals (for benchmarking)

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

getRenderState :: EventM n s (RenderState n)

resetRenderState :: RenderState n -> RenderState n

renderWidget

Arguments

:: Ord n

=> Maybe AttrMap

Optional attribute map used to render. If omitted, an empty attribute map with the terminal's default attribute will be used.

-> [Widget n]

The widget layers to render, topmost first.

-> DisplayRegion

The size of the display region in which to render the layers.

-> Picture

This function provides a simplified interface to rendering a list of Widgets as a Picture outside of the context of an App. This can be useful in a testing setting but isn't intended to be used for normal application rendering. The API is deliberately narrower than the main interactive API and is not yet stable. Use at your own risk.

Consult the Vty library documentation for details on how to output the resulting Picture.