The type of widgets.

A terminal screen location.

The class of types that behave like terminal locations.

A cursor location. These are returned by the rendering process.

Describes the state of a viewport as it appears as its most recent rendering.

The type of viewports that indicates the direction(s) in which a viewport is scrollable.

Orientations for vertical scroll bars.

Orientations for horizontal scroll bars.

A scroll bar renderer.

Clickable elements of a scroll bar.

The monad in which event handlers run.

The type of events.

Given a state value and an EventM that mutates that state, run the specified action and return both the resulting modified state and the result of the action itself.

Given a state value and an EventM that mutates that state, run the specified action and return resulting modified state.

The type of the rendering monad. This monad is used by the library's rendering routines to manage rendering state and communicate rendering parameters to widgets' rendering functions.

Get the current rendering context.

The rendering context. This tells widgets how to render: how much space they have in which to render, which attribute they should use to render, which bordering style should be used, and the attribute map available for rendering.

The rendering context's current drawing attribute.

The type of result returned by a widget's rendering function. The result provides the image, cursor positions, and visibility requests that resulted from the rendering process.

Given an attribute name, obtain the attribute for the attribute name by consulting the context's attribute map.

An extent of a named area: its size, location, and origin.

A template haskell function to build lenses for a record type. This function differs from the makeLenses function in that it does not require the record fields to be prefixed with underscores and it adds an L suffix to lens names to make it clear that they are lenses.

A more general version of suffixLenses that allows customization of the lens-building rules and allows customization of the suffix.

Information about how to redraw a dynamic border character when it abuts another dynamic border character.

A border character has four segments, one extending in each direction (horizontally and vertically) from the center of the character.

Widget size policies. These policies communicate how a widget uses space when being rendered. These policies influence rendering order and space allocation in the box layout algorithm for hBox and vBox.

Scrolling direction.

Return the state from the internals of the monad.

Gets specific component of the state, using a projection function supplied.

Replace the state inside the monad.

Monadic state transformer.

Maps an old state to a new state inside a state monad. The old state is thrown away.

     Main> :t modify ((+1) :: Int -> Int)
     modify (...) :: (MonadState Int a) => a ()

This says that modify (+1) acts over any Monad that is a member of the MonadState class, with an Int state.

When you're in a state monad, this function lets you operate on a part of your state. For instance, if your state was a record containing a position field, after zooming position would become your whole state (and when you modify it, the bigger structure would be modified as well).

(Your State / StateT or RWS / RWST can be anywhere in the stack, but you can't use zoom with arbitrary MonadState because it doesn't provide any methods to change the type of the state. See this issue for details.)

For the sake of the example, let's define some types first:

data Position = Position {
  _x, _y :: Int }

data Player = Player {
  _position :: Position,
  ... }

data Game = Game {
  _player :: Player,
  _obstacles :: [Position],
  ... }

concat <$> mapM makeLenses [''Position, ''Player, ''Game]

Now, here's an action that moves the player north-east:

moveNE :: State Game ()
moveNE = do
  player.position.x += 1
  player.position.y += 1

With zoom, you can use player.position to focus just on a part of the state:

moveNE :: State Game ()
moveNE = do
  zoom (player.position) $ do
    x += 1
    y += 1

You can just as well use it for retrieving things out of the state:

getCoords :: State Game (Int, Int)
getCoords = zoom (player.position) ((,) <$> use x <*> use y)

Or more explicitly:

getCoords = zoom (player.position) $ do
  x' <- use x
  y' <- use y
  return (x', y')

When you pass a traversal to zoom, it'll work as a loop. For instance, here we move all obstacles:

moveObstaclesNE :: State Game ()
moveObstaclesNE = do
  zoom (obstacles.each) $ do
    x += 1
    y += 1

If the action returns a result, all results would be combined with <> – the same way they're combined when ^. is passed a traversal. In this example, moveObstaclesNE returns a list of old coordinates of obstacles in addition to moving them:

moveObstaclesNE = do
  xys <- zoom (obstacles.each) $ do
    -- Get old coordinates.
    x' <- use x
    y' <- use y
    -- Update them.
    x .= x' + 1
    y .= y' + 1
    -- Return a single-element list with old coordinates.
    return [(x', y')]
  ...

Finally, you might need to write your own instances of Zoom if you use newtyped transformers in your monad stack. This can be done as follows:

import Lens.Micro.Mtl.Internal

type instance Zoomed (MyStateT s m) = Zoomed (StateT s m)

instance Monad m => Zoom (MyStateT s m) (MyStateT t m) s t where
    zoom l (MyStateT m) = MyStateT (zoom l m)