From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Thien-Thi Nguyen Newsgroups: gmane.emacs.devel Subject: docs for ewoc.el Date: Wed, 17 May 2006 13:06:36 +0200 Message-ID: Reply-To: ttn@gnu.org NNTP-Posting-Host: main.gmane.org X-Trace: sea.gmane.org 1147863951 8031 80.91.229.2 (17 May 2006 11:05:51 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 17 May 2006 11:05:51 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed May 17 13:05:48 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1FgJqV-0007qy-O9 for ged-emacs-devel@m.gmane.org; Wed, 17 May 2006 13:05:40 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FgJqV-0004XM-A6 for ged-emacs-devel@m.gmane.org; Wed, 17 May 2006 07:05:39 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1FgJq7-0004Rt-7t for emacs-devel@gnu.org; Wed, 17 May 2006 07:05:15 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1FgJq4-0004Qx-NR for emacs-devel@gnu.org; Wed, 17 May 2006 07:05:14 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FgJq4-0004Qu-Hs for emacs-devel@gnu.org; Wed, 17 May 2006 07:05:12 -0400 Original-Received: from [151.37.244.66] (helo=surf.glug.org) by monty-python.gnu.org with esmtp (Exim 4.52) id 1FgJsu-0001in-FB for emacs-devel@gnu.org; Wed, 17 May 2006 07:08:09 -0400 Original-Received: from ttn by surf.glug.org with local (Exim 3.35 #1 (Debian)) id 1FgJrQ-0003gX-00 for ; Wed, 17 May 2006 13:06:36 +0200 Original-To: emacs-devel@gnu.org X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:54628 Archived-At: 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 non-@code{nil}. 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 non-@code{nil}. If more than two arguments are given, the remaining arguments will be passed to @var{map-function}. @end defun