Edit.tex

\section{Edit Widgets}
\label{sec:edit}

The \fw{Edit} module provides a line-editing widget, \fw{Widget Edit}.
This widget makes it possible to edit text with some Emacs-style key
bindings.

An \fw{Edit} widget is simple to create.  You can create \fw{Edit}
widgets in two modes: single- and multi-line:

\begin{haskellcode}
 -- Single-line text editor:
 e1 <- editWidget
 -- Multi-line text editor:
 e2 <- multiLineEditWidget
\end{haskellcode}

\fw{Edit} widgets can be laid out in the usual way:

\begin{haskellcode}
 e <- editWidget
 b <- (plainText "Enter a string: ") <++> (return e)
\end{haskellcode}

To use an \fw{Edit} widget, add it to your interface and
\fw{FocusGroup}.

\fw{Edit} widgets support the following editing key bindings:

\begin{itemize}
\item \fw{Ctrl-a}, \fw{Home} -- go to the beginning of the line.
\item \fw{Ctrl-e}, \fw{End} -- go to the end of the line.
\item \fw{Ctrl-k} -- remove the text from the cursor position to the
  end of the line.
\item \fw{Ctrl-d}, \fw{Del} -- delete the character at the cursor
  position.
\item \fw{Left}, \fw{Right}, \fw{Up}, \fw{Down} -- change the cursor
  position.
\item \fw{Backspace} -- delete the character just before the cursor
  position and move the cursor position back by one character.
\item \fw{Enter} -- ``activate'' the \fw{Edit} widget if it is a
  single-line widget; if it is multi-line, insert a new line at the
  cursor position.
\end{itemize}

Note that \fw{Tab} will not be handled by \fw{Edit} widgets because it
is used to change focus.

An \fw{Edit} widget can be monitored for three events:

\begin{itemize}
\item ``Activation'' events -- triggered when the user presses
  \fw{Enter} in a single-line \fw{Edit} widget.  Handlers are
  registered with the \fw{onActivate} function.  Event handlers
  receive the \fw{Edit} widget as a parameter.
\item Text change -- when the contents of the \fw{Edit} widget change.
  Handlers are registered with the \fw{onChange} function.  Event
  handlers receive the new \fw{String} value in the \fw{Edit} widget.
\item Cursor movement -- when the cursor position within the \fw{Edit}
  widget changes.  Handlers are registered with the \fw{onCursorMove}
  function.  Event handlers receive the new cursor position as a
  parameter.
\end{itemize}

In addition to event handling, the \fw{Edit} widget API also provides
other functions.  These functions trigger the respective events
automatically.

\begin{itemize}
\item \fw{setEditText}, \fw{getEditText} -- change the current text
  content of the \fw{Edit} widget.
\item \fw{getEditCursorPosition}, \fw{setEditCursorPosition} --
  manipulate the cursor position within the \fw{Edit} widget.
\item \fw{getEditLineLimit}, \fw{setEditLineLimit} -- manipulate the
  limit on the number of lines that the text widget may hold.  Takes
  \fw{Maybe Int} where \fw{Nothing} indicates no limit.
  \fw{setEditLineLimit \$ Just 0} is a no-op.
\end{itemize}

\subsubsection{Wide Character Support}

Some characters, such as those from some Asian character sets, require
two columns instead of one when displayed in a terminal.  The
\fw{Edit} widget supports such characters with one caveat: when a wide
character straddles the left or right viewing boundary of an \fw{Edit}
widget, an indicator (\fw{\$}) will be displayed in its place to
indicate that a wide character lies on the boundary and can be
revealed by scrolling further in the appropriate direction.  Such
indicators are only visual and do not affect the underlying text, so
e.g. calls to \fw{getEditText} will return the text as expected.

\subsubsection{Growth Policy}

Single-line \fw{Edit} widgets -- those created by \fw{editWidget} --
grow only horizontally and are always one row high.  Multi-line edit
widgets -- those created by \fw{multi\-Line\-Edit\-Widget} -- always
grow in both dimensions.  To manage this behavior, you can use one of
the ``fixed'' family of widgets to control their sizes (see Section
\ref{sec:fixed}).