--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/remotePager.urs	Thu Aug 18 12:53:17 2011 -0430
@@ -0,0 +1,78 @@
+(* How to format the control section. *)
+type formatCtl = {Width : int,
+                  (* Maximum number of page options to show. *)
+                  RangeCtl : $(mapU (transaction {} -> xbody) [First, Back, Next, Last]),
+                  (* A group of four functions taking transactions which will be used to return
+                   * an element having that transaction as onclick.  Used to format the buttons
+                   * controlling the selection of page options.  First starts the options at the
+                   * first page, Back starts the options one page lower, Next one page higher
+                   * and Last has them finish at the final page. *)
+                  PageCtl :  $(mapU (int -> transaction {} -> xbody) [Unsel, Sel]),
+                  (* Used to generate the xml bearing the page selection onclick action. Sel
+                   * is used for the currently shown page and Unsel for the others. *)
+                  WrapPageCtl : xbody -> xbody,
+                  (* The sequence of page selection controls will be wrapped by this. *)
+                  Wrap : $(mapU xbody [First, Back, Pages, Next, Last]) -> xbody
+                  (* Draws the control by placing the individual controls in the holes. *)}
+
+style firstCtl
+style backCtl
+style nextCtl
+style lastCtl
+style curPage
+style rangeCtl
+(* Default styles. *)
+
+val defaultFormat : formatCtl
+(* A reasonable default format. *)
+
+val defaultFormatLbl : $(mapU string [First, Back, Next, Last]) -> formatCtl
+(* A default format with configurable labels on the page range controls. *)
+
+type pageData = {Content : xbody, Available : int}
+(* Content and page count needed from the RPC. *)
+
+datatype response err = Good of pageData | Bad of err
+(* The RPC gives us either page information or an error code. *)
+
+functor Make(M : sig
+                 type errorMarker
+                 (* Classifies the possible error conditions returned by the rpc call. *)
+
+                 type pageGroup
+                 (* Classifies families of pages. *)
+
+                 val initPage : pageGroup -> transaction pageData
+                 (* Used once to initialize the first page and page count.
+                  * The RPC mechanism is not used and no error is possible. *)
+
+                 val getPage : pageGroup -> int -> transaction (response errorMarker)
+                 (* RPC giving the content of a requested page as well as the count
+                  * of how many pages are available.  The first page should be given
+                  * an index of 0. *)
+             end) : sig
+
+    type t
+    (* The type of remote pagers.  A remote pager is a
+     * widget which shows a list of available "pages" of
+     * information.  The user can click on a page they want
+     * displayed, which is then fetched from the server via
+     * a RPC. *)
+
+    val createFmt : formatCtl -> M.pageGroup -> transaction t
+    (* Get a remote pager widget with a custom format showing pages from the selected group. *)
+
+    val create : M.pageGroup -> transaction t
+    (* Get a remote pager widget with the default format (partly customizable via CSS). *)
+
+    val onError : t -> (M.errorMarker -> transaction {}) -> transaction {}
+    (* Allows setting an error handler.  In case of an rpc error code return, this will
+     * be called with the received error marker.  If not set, the default error handler
+     * does nothing. *)
+
+    val panelXml : t -> xbody
+    (* Returns a piece of xml holding the contents of the current page. *)
+
+    val ctlXml : t -> xbody
+    (* Returns a xml widget representing the clickable page selection controls. *)
+end