docs for ewoc.el

[Thien-Thi Nguyen]

below is a texinfo @node for ewoc.el, written w/ the operating
assumption that it should go into lispref/display.texi right before
@node Fringes.  is there is a better place for it?  what do you think?

thi


_________________________________________
@node Abstract Display
@section Abstract Display

  Generally, to display an object in a buffer, you must decide on its
representation, as either text or image, and insert that representation in
the buffer.  When the object changes, you must update its representation
appropriately.  The common infrastructure of these tasks is the focus of the
@code{ewoc-} set of functions, which altogether form a utility to maintain a
view of a list of objects in a buffer.

  These functions define and pass around an @dfn{ewoc}, which is a data
structure encapsulating @dfn{header} and @dfn{footer} (strings); a
@dfn{pretty-printer} function that is responsible for inserting object
representations in the buffer; and an ordered set of @dfn{nodes}, with one
node per object in your list.

  To define an ewoc, use @code{ewoc-create}.  To get an ewoc's buffer, header
and footer, use @code{ewoc-buffer} and @code{ewoc-get-hf}, respectively.  To
change the header and/or footer, use @code{ewoc-set-hf}.

@defun ewoc-create pretty-printer &optional header footer
This constructs and returns a new ewoc, with no data elements.
@var{pretty-printer} should be a function that tkaes one argument,
a data element, and inserts at point a string representation of it,
using @code{insert} (and not @code{insert-before-markers}).
@end defun

@defun ewoc-buffer ewoc
@defunx ewoc-get-hf ewoc
These return, respectively, the buffer where @var{ewoc} was created,
and its header and footer as a cons cell @code{(header . footer)}.
@end defun

@defun ewoc-set-hf ewoc header footer
This sets the header and footer of @var{ewoc} to @var{header} and @var{footer}
(both strings).
@end defun

  To add nodes, use the @code{ewoc-enter-FOO} functions.  To refer to a node's
neighbor, use @code{ewoc-prev} and @code{ewoc-next}.  To refer to a node by a
modulo index into the ewoc, use @code{ewoc-nth}.  To access a node's data, use
@code{ewoc-data}.

@defun ewoc-enter-first ewoc data
@defunx ewoc-enter-last ewoc data
These construct a new node encapsulating @var{data}, adding it to @var{ewoc}
at the beginning or end, respectively, of the set of ordered nodes.
@end defun

@defun ewoc-enter-before ewoc node data
@defunx ewoc-enter-after ewoc node data
These construct a new node encapsulating @var{data}, adding it to @var{ewoc}
before or after @var{node}, respectively.
@end defun

@defun ewoc-prev ewoc node
@defunx ewoc-next ewoc node
These return the previous and next node, respectively, of @var{node}
in @var{ewoc}.
@end defun

@defun ewoc-nth ewoc n
This returns the node in @var{ewoc} found at zero-based index @var{n}.
A negative @var{n} means count from the end.  @code{ewoc-nth} returns
@code{nil} if there are less than @var{n} elements.
@end defun

@defun ewoc-data node
This extracts the data encapsulated by @var{node} and returns it.
@end defun

  To find out which node (if any) point is at in an ewoc, use
@code{ewoc-locate}.  If you already have a node, to find its start position,
use @code{ewoc-location}.  To move point from the start of one representation
to another, use the @code{ewoc-goto-FOO} functions.

@defun ewoc-locate ewoc &optional pos guess
This determines which node in @var{ewoc} point (or @var{pos} if specified) is
within and returns that node.  If @var{ewoc} is empty, it returns @code{nil}.
If @var{pos} is before the first node or after the last node, it returns that
node.  Optional third arg @var{guess} should be a node that is likely to be
near @var{pos}.
@end defun

@defun ewoc-location node
This returns the start position of @var{node}.
@end defun

@defun ewoc-goto-prev ewoc arg
@defunx ewoc-goto-next ewoc arg
These move point to the previous or next, respectively, @var{arg}th node
in @var{ewoc}.  @code{ewoc-goto-prev} does not move if it is already at the
first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next} moves past
the last node, returning @code{nil}.  Excepting this special case, these
functions return the node moved to.
@end defun

@defun ewoc-goto-node ewoc node
This moves point to the start of @var{node} in @var{ewoc}.
@end defun

  To completely recompute and redisplay the representations of all nodes in an
ewoc, use @code{ewoc-refresh}.  For only a few, use @code{ewoc-invalidate}.
To delete nodes, use @code{ewoc-filter}.  To form a list of data elements
satisfying a certain predicate, use @code{ewoc-collect}.  To map a function
over all nodes, use @code{ewoc-map}.

@defun ewoc-refresh ewoc
This deletes the region bounded by the header end and the footer beginning in
@var{ewoc}, i.e., all the data elements' representations, and then calls the
pretty-printer function for each node, in order.
@end defun

@defun ewoc-invalidate ewoc &rest nodes
This is similar to @code{ewoc-refresh}, except that only @var{nodes} in
@var{ewoc} are updated instead of the entire set.
@end defun

@defun ewoc-filter ewoc predicate &rest args
This calls @var{predicate} for each data element in @var{ewoc} and
removes those nodes for which @var{predicate} returns @code{nil}.
If any @var{args} are given they will be passed to @var{predicate}.
@end defun

@defun ewoc-collect ewoc predicate &rest args
This calls @var{predicate} for each data element in @var{ewoc}
and returns a list of those elements for which @var{predicate}
returns address@hidden  The elements in the list are ordered
as in the buffer.  If more than two arguments are
given the remaining arguments will be passed to @var{predicate}.
@end defun

@defun ewoc-map map-function ewoc &rest args
This calls @var{map-function} for each data element in @var{ewoc} and
updates those nodes for which @var{map-function} returns address@hidden
If more than two arguments are given, the remaining
arguments will be passed to @var{map-function}.
@end defun