Graphics.Vty.Widgets.Edit

This module provides a text-editing widget. Edit widgets can operate in single- and multi-line modes.

Edit widgets support the following special keystrokes:

• Arrow keys to navigate the text
• Enter - Activate single-line edit widgets or insert new lines into multi-line widgets
• Home / Control-a - Go to beginning of the current line
• End / Control-e - Go to end of the current line
• Control-k - Remove text from the cursor to the end of the line, or remove the line if it is empty
• Del / Control-d - delete the current character
• Backspace - delete the previous character

Edit widgets may be configured with a line limit which limits the number of lines of text the widget will store. It does not provide any limit control on the length of its lines, though.

Edit widgets support multi-column characters. (For some information, see http://www.unicode.org/reports/tr11/.) When the edit widget scrolling reaches a point where a wide character cannot be drawn because it is bisected by the editing window's boundary, it will be replaced with an indicator ("$") until the scrolling window is moved enough to reveal the character. This is done to preserve the relative alignment of all of the rows in the widget in the presence of characters of different widths. Note that this is a visual aid only and does not affect the underlying text content of the widget.

Documentation

data Edit

Instances

Show Edit

editWidget :: IO (Widget Edit)

Construct a text widget for editing a single line of text. Single-line edit widgets will send activation events when the user presses Enter (see onActivate).

multiLineEditWidget :: IO (Widget Edit)

Construct a text widget for editing multi-line documents. Multi-line edit widgets never send activation events, since the Enter key inserts a new line at the cursor position.

getEditText :: Widget Edit -> IO Text

Get the current contents of the edit widget. This returns all of the lines of text in the widget, separated by newlines.

getEditCurrentLine :: Widget Edit -> IO Text

Get the contents of the current line of the edit widget (the line on which the cursor is positioned).

setEditText :: Widget Edit -> Text -> IO ()

Set the contents of the edit widget. Newlines will be used to break up the text in multiline widgets. If the edit widget has a line limit, only those lines within the limit will be set. If the edit widget has a line length limit, lines will be truncated.

setEditRewriter :: Widget Edit -> (Char -> Char) -> IO ()

Set the function which rewrites all characters at rendering time. Defaults to id. Does not affect text stored in the editor.

setCharFilter :: Widget Edit -> (Char -> Bool) -> IO ()

Set the function which allows typed characters in the edit widget. Defaults to const True, allowing all characters. For example, setting the filter to (elem "0123456789") will only allow numbers in the edit widget.

getEditCursorPosition :: Widget Edit -> IO (Int, Int)

Get the edit widget's current cursor position (row, column).

setEditCursorPosition :: (Int, Int) -> Widget Edit -> IO ()

Set the cursor position to the specified row and column. Invalid cursor positions will be ignored.

setEditLineLimit :: Widget Edit -> Maybe Int -> IO ()

Set the limit on the number of lines for the edit widget. Nothing indicates no limit, while Just indicates a limit of the specified number of lines.

getEditLineLimit :: Widget Edit -> IO (Maybe Int)

Get the current line limit, if any, for the edit widget.

setEditMaxLength :: Widget Edit -> Maybe Int -> IO ()

Set the maximum length of the contents of an edit widget. Applies to every line of text in the editor. Nothing indicates no limit, while Just indicates a limit of the specified number of characters.

getEditMaxLength :: Widget Edit -> IO (Maybe Int)

Get the current maximum length, if any, for the edit widget.

applyEdit :: (TextZipper Text -> TextZipper Text) -> Widget Edit -> IO ()

Apply an editing transformation to the edit widget's text. If the transformation modifies the text or the cursor, the appropriate event handlers will be notified. If a line limit is in effect and the transformation violates it, the transformation will be ignored.

onActivate :: Widget Edit -> (Widget Edit -> IO ()) -> IO ()

Register handlers to be invoked when the edit widget has been ''activated'' (when the user presses Enter while the widget is focused). These handlers will only be invoked when a single-line edit widget is activated; multi-line widgets never generate these events.

onChange :: Widget Edit -> (Text -> IO ()) -> IO ()

Register handlers to be invoked when the edit widget's contents change. Handlers will be passed the new contents.

onCursorMove :: Widget Edit -> ((Int, Int) -> IO ()) -> IO ()

Register handlers to be invoked when the edit widget's cursor position changes. Handlers will be passed the new cursor position, relative to the beginning of the text (position (0, 0)).