brick-2.9: A declarative terminal user interface library

Safe Haskell | None
Language | Haskell2010

Brick.Widgets.Edit

Contents

- Constructing an editor
- Reading editor contents
- Handling events
- Editing text
- Lenses for working with editors
- Rendering editors
- Attributes
- UTF-8 decoding of editor pastes

Description

This module provides a basic text editor widget. You'll need to embed an `Editor` in your application state and transform it with `handleEditorEvent` when relevant events arrive. To get the contents of the editor, just use `getEditContents`. To modify it, use the `TextZipper` interface with `applyEdit`.

The editor's `handleEditorEvent` function handles a set of basic input events that should suffice for most purposes; see the source for a complete list.

Bear in mind that the editor provided by this module is intended to provide basic input support for brick applications but it is not intended to be a replacement for your favorite editor such as Vim or Emacs. It is also not suitable for building sophisticated editors. If you want to build your own editor, I suggest starting from scratch.

Synopsis

- data Editor t n
- editor :: GenericTextZipper a => n -> Maybe Int -> a -> Editor a n
- editorText :: n -> Maybe Int -> Text -> Editor Text n
- getEditContents :: Monoid t => Editor t n -> [t]
- getCursorPosition :: Editor t n -> (Int, Int)
- handleEditorEvent :: (Eq n, DecodeUtf8 t, Eq t, GenericTextZipper t) => BrickEvent n e -> EventM n (Editor t n) ()
- applyEdit :: (TextZipper t -> TextZipper t) -> Editor t n -> Editor t n
- editContentsL :: forall t1 n t2 f. Functor f => (TextZipper t1 -> f (TextZipper t2)) -> Editor t1 n -> f (Editor t2 n)
- renderEditor :: (Ord n, Show n, Monoid t, TextWidth t, GenericTextZipper t) => ([t] -> Widget n) -> Bool -> Editor t n -> Widget n
- editAttr :: AttrName
- editFocusedAttr :: AttrName
- class DecodeUtf8 t where
  - decodeUtf8 :: ByteString -> Either String t

# Documentation

data Editor t n Source #

Editor state. Editors support the following events by default:

- Mouse clicks: change cursor position
- Meta-<: go to beginning of file
- Meta->: go to end of file
- Ctrl-a, Home: go to beginning of line
- Ctrl-e, End: go to end of line
- Ctrl-d, Del: delete character at cursor position
- Meta-d: delete word at cursor position
- Backspace: delete character prior to cursor position
- Ctrl-k: delete all from cursor to end of line
- Ctrl-u: delete all from cursor to beginning of line
- Ctrl-t: transpose character before cursor with the one at cursor position
- Meta-b: move one word to the left
- Ctrl-b: move one character to the left
- Meta-f: move one word to the right
- Ctrl-f: move one character to the right
- Arrow keys: move cursor
- Enter: break the current line at the cursor position
- Paste: Bracketed Pastes from the terminal will be pasted, provided the incoming data is UTF-8-encoded.

#### Instances

Instances details

(Show t, Show n) => Show (Editor t n) Source # |
Instance details Defined in Brick.Widgets.Edit Methods showsPrec :: Int -> Editor t n -> ShowS Source # show :: Editor t n -> String Source # showList :: [Editor t n] -> ShowS Source #
Named (Editor t n) n Source # |
Instance details Defined in Brick.Widgets.Edit Methods getName :: Editor t n -> n Source #

# Constructing an editor

editor Source #

Arguments

:: GenericTextZipper a |
=> n | The editor's name (must be unique)
-> Maybe Int | The limit on the number of lines in the editor (`Nothing` means no limit)
-> a | The initial content
-> Editor a n |

Construct an editor over generic text values

editorText Source #

Arguments

:: n | The editor's name (must be unique)
-> Maybe Int | The limit on the number of lines in the editor (`Nothing` means no limit)
-> Text | The initial content
-> Editor Text n |

Construct an editor over `Text` values

# Reading editor contents

getEditContents :: Monoid t => Editor t n -> [t] Source #

Get the contents of the editor.

getCursorPosition :: Editor t n -> (Int, Int) Source #

Get the cursor position of the editor (row, column).

# Handling events

handleEditorEvent :: (Eq n, DecodeUtf8 t, Eq t, GenericTextZipper t) => BrickEvent n e -> EventM n (Editor t n) () Source #

# Editing text

applyEdit Source #

Arguments

:: (TextZipper t -> TextZipper t) | The `TextZipper` editing transformation to apply
-> Editor t n |
-> Editor t n |

Apply an editing operation to the editor's contents.

This is subject to the restrictions of the underlying text zipper; for example, if the underlying zipper has a line limit configured, any edits applied here will be ignored if they edit text outside the line limit.

# Lenses for working with editors

editContentsL :: forall t1 n t2 f. Functor f => (TextZipper t1 -> f (TextZipper t2)) -> Editor t1 n -> f (Editor t2 n) Source #

# Rendering editors

renderEditor Source #

Arguments

:: (Ord n, Show n, Monoid t, TextWidth t, GenericTextZipper t) |
=> ([t] -> Widget n) | The content drawing function
-> Bool | Whether the editor has focus. It will report a cursor position if and only if it has focus.
-> Editor t n | The editor.
-> Widget n |

Turn an editor state value into a widget. This uses the editor's name for its scrollable viewport handle and the name is also used to report mouse events.

# Attributes

editAttr :: AttrName Source #

The attribute assigned to the editor when it does not have focus.

editFocusedAttr :: AttrName Source #

The attribute assigned to the editor when it has focus. Extends `editAttr`.

# UTF-8 decoding of editor pastes

class DecodeUtf8 t where Source #

Values that can be constructed by decoding bytestrings in UTF-8 encoding.

Methods

decodeUtf8 :: ByteString -> Either String t Source #

Decode a bytestring assumed to be text in UTF-8 encoding. If the decoding fails, return `Left`. This must not raise exceptions.

#### Instances

Instances details

DecodeUtf8 Text Source # |
Instance details Defined in Brick.Widgets.Edit Methods decodeUtf8 :: ByteString -> Either String Text Source #
DecodeUtf8 String Source # |
Instance details Defined in Brick.Widgets.Edit Methods decodeUtf8 :: ByteString -> Either String String Source #