From dc520a9a4774954df1cd41eb5402327682c50f33 Mon Sep 17 00:00:00 2001
From: Jon Rafkind <rafkind@racket-lang.org>
Date: Tue, 8 Feb 2011 14:46:02 -0700
Subject: [PATCH] add documentation for the splitter mixin

original commit: 7f3f861899403f3a271b35c473878a35ed472e41
---
 collects/framework/private/panel.rkt       |  6 +++-
 collects/scribblings/framework/panel.scrbl | 34 ++++++++++++++++++++++
 2 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/collects/framework/private/panel.rkt b/collects/framework/private/panel.rkt
index 1099a2cc..364414c8 100644
--- a/collects/framework/private/panel.rkt
+++ b/collects/framework/private/panel.rkt
@@ -529,6 +529,7 @@
       (not (send this get-vertical?)))
 
     ;; insert an item into a list after some element
+    ;; FIXME: this is probably a library function somewhere
     (define/private (insert-after list before item)
       (let loop ([so-far '()]
                  [list list])
@@ -539,6 +540,7 @@
           [else (loop (cons (car list) so-far) (cdr list))])))
 
     ;; replace an element with a list of stuff
+    ;; FIXME: this is probably a library function somewhere
     (define/private (replace list at stuff)
       (let loop ([so-far '()]
                  [list list])
@@ -547,6 +549,8 @@
           [(eq? (car list) at) (append (reverse so-far) stuff (cdr list))]
           [else (loop (cons (car list) so-far) (cdr list))])))
 
+    ;; remove a canvas and merge split panels if necessary
+    ;; TODO: restore percentages
     (define/public (collapse canvas)
       (begin-container-sequence)
       (for ([child (get-children)])
@@ -571,7 +575,7 @@
       (end-container-sequence))
 
     ;; split a canvas by creating a new editor and either
-    ;; 1) adding it to the canvas if the canvas is already using the same
+    ;; 1) adding it to the panel if the panel is already using the same
     ;;   orientation as the split that is about to occur
     ;; 2) create a new panel with the orientation of the split about to
     ;;   occur and add a new editor
diff --git a/collects/scribblings/framework/panel.scrbl b/collects/scribblings/framework/panel.scrbl
index e3cd08d5..20c362e6 100644
--- a/collects/scribblings/framework/panel.scrbl
+++ b/collects/scribblings/framework/panel.scrbl
@@ -174,4 +174,38 @@
 @defclass[panel:vertical-dragable% (panel:vertical-dragable-mixin (panel:dragable-mixin vertical-panel%)) ()]{}
 @defclass[panel:horizontal-dragable% (panel:horizontal-dragable-mixin (panel:dragable-mixin horizontal-panel%)) ()]{}
 
+@definterface[panel:splitter<%> ()]{
+  A panel that implements @scheme[panel:splitter<%>]. Children can be split
+  horizonally or vertically.
+}
+
+@defmixin[panel:splitter-mixin (area-container<%> panel:dragable<%>) (splitter<%>)]{
+  This mixin allows panels to split their children either horizontally or
+  vertically. Children that are split can be further split independant of any
+  other splitting.
+
+  @defmethod[(split-vertical (canvas (instance-of (is-a?/c canvas<%>)))
+                             (maker (-> (instance-of (is-a?/c splitter<%>))
+                                        (instance-of (is-a?/c canvas<%>)))))
+                             (instance-of (is-a?/c canvas<%>))]{
+    Splits the @scheme[canvas] vertically by creating a new instance using
+    @scheme[maker]. This splitter object is passed as the argument to
+    @scheme[maker] and should be used as the @scheme[parent] field of the newly
+    created canvas.
+  }
+
+  @defmethod[(split-horizontal (canvas (instance-of (is-a?/c canvas<%>)))
+                             (maker (-> (instance-of (is-a?/c splitter<%>))
+                                        (instance-of (is-a?/c canvas<%>)))))
+                             (instance-of (is-a?/c canvas<%>))]{
+    Similar to @scheme[split-vertical] but splits horizontally.
+  }
+
+  @defmethod[(collapse (canvas (instance-of (is-a?/c canvas<%>)))) void]{
+    Removes the given @scheme[canvas] from the splitter hierarchy and collapses
+    any split panes as necessary.
+  }
+
+}
+
 @(include-previously-extracted "main-extracts.ss" #rx"^panel:")