embedded-gui docs

svn: r9389

original commit: 6fcc293c4a3422e162b06fc4264a975cadfb8570

collects/embedded-gui/info.ss

@@ -0,0 +1,3 @@
+#lang setup/infotab
+
+(define scribblings '(("scribblings/embedded-gui.scrbl" (multi-page))))

collects/embedded-gui/scribblings/aligned-pasteboard.scrbl

@@ -0,0 +1,6 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@defclass/title[aligned-pasteboard% pasteboard% (alignment-parent<%>)]{
+
+Acts as the top of an @scheme[alignment<%>] tree.}

collects/embedded-gui/scribblings/alignment-parent.scrbl

@@ -0,0 +1,22 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@definterface/title[alignment-parent<%> ()]{
+
+@defmethod[(get-pasteboard) (is-a?/c pasteboard%)]{
+
+The pasteboard that this alignment is being displayed to.}
+
+@defmethod[(add-child [child (is-a?/c alignment<%>)]) void?]{
+
+Add the given alignment as a child after the existing child.}
+
+@defmethod[(delete-child [child (is-a?/c alignment<%>)]) void?]{
+
+Deletes a child from the the alignments.}
+
+@defmethod[(is-shown?) boolean?]{
+
+True if the alignment is being shown (accounting for its parent being
+shown).}}
+

collects/embedded-gui/scribblings/alignment.scrbl

@@ -0,0 +1,51 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@definterface/title[alignment<%> (dllist<%>)]{
+
+@defmethod[(get-parent) (is-a?/c alignment-parent<%>)]{
+
+The parent of the alignment in the tree.}
+
+@defmethod[(set-min-sizes) void?]{
+
+Tells the alignment that its sizes should be calculated.}
+
+@defmethod[(align [x-offset (and/c real? (not/c negative?))]
+                  [y-offset (and/c real? (not/c negative?))]
+                  [width (and/c real? (not/c negative?))]
+                  [height  (and/c real? (not/c negative?))]) void?]{
+Tells itself to align its children on the pasteboard
+in the given rectangle defined by @scheme[width], @scheme[height] and a top
+left corner point given as offsets into the pasteboards top
+left corner.}
+
+@defmethod[(get-min-width) (and/c real? (not/c negative?))]{
+
+The minimum width this alignment must be.}
+
+@defmethod[(get-min-height) (and/c real? (not/c negative?))]{
+
+The minimum height this alignment must be.}
+
+@defmethod*[([(stretchable-width) boolean?]
+             [(stretchable-width [value boolean?]) void?])]{
+             
+Gets/sets the property of stretchability in the x dimension.}
+
+@defmethod*[([(stretchable-height) boolean?]
+             [(stretchable-height [value boolean?]) void?])]{
+
+Gets/sets the property of stretchability in the y dimension.}
+
+@defmethod[(show/hide [show? boolean?]) void?]{
+
+Tells the alignment to show or hide its children.}
+
+@defmethod[(show [show? boolean?]) void?]{
+
+Tells the alignment that its show state is the given value
+and it should show or hide its children accordingly.}
+
+}
+

collects/embedded-gui/scribblings/button-snip.scrbl

@@ -0,0 +1,18 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@defclass/title[button-snip% snip% ()]{
+
+A clickable button with a bitmap label.
+
+@defconstructor[([images (cons/c path-string? path-string?)]
+                 [callback ((is-a?/c button-snip%) (is-a?/c event%) . -> . void?)])]{
+
+The @scheme[images] argument is a pair filenames to be load as the
+button-label image, where the first is the image for when the button
+is at rest, and the second is the image for the button while its
+pressed.
+
+The @scheme[callback] is called when the button is clicked.}
+
+}

collects/embedded-gui/scribblings/common.ss

@@ -0,0 +1,15 @@
+#lang scheme/base
+
+(require scribble/manual
+         (for-label embedded-gui
+                    scheme/base
+                    scheme/contract
+                    scheme/class
+                    scheme/gui/base))
+(provide (all-from-out scribble/manual)
+         (for-label (all-from-out embedded-gui
+                                  scheme/base
+                                  scheme/contract
+                                  scheme/class
+                                  scheme/gui/base)))
+

collects/embedded-gui/scribblings/containers.scrbl

@@ -0,0 +1,14 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@title[#:tag "containers" #:style 'toc]{Containers}
+
+@local-table-of-contents[]
+
+@include-section["aligned-pasteboard.scrbl"]
+@include-section["alignment.scrbl"]
+@include-section["alignment-parent.scrbl"]
+@include-section["stretchable-snip.scrbl"]
+@include-section["horizontal-alignment.scrbl"]
+@include-section["vertical-alignment.scrbl"]
+@include-section["dllist.scrbl"]

collects/embedded-gui/scribblings/control-snips.scrbl

@@ -0,0 +1,14 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@title[#:tag "control-snips" #:style 'toc]{Control Snips}
+
+To allow the buttons to be pushed, the editor in which they appear
+must forward clicks to them properly.
+
+@local-table-of-contents[]
+
+@include-section["snip-wrapper.scrbl"]
+@include-section["text-button-snip.scrbl"]
+@include-section["button-snip.scrbl"]
+@include-section["toggle-button-snip.scrbl"]

collects/embedded-gui/scribblings/controls.scrbl

@@ -0,0 +1,13 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@title[#:tag "controls" #:style 'toc]{Controls}
+
+@local-table-of-contents[]
+
+@include-section["embedded-text-button.scrbl"]
+@include-section["embedded-button.scrbl"]
+@include-section["embedded-toggle-button.scrbl"]
+@include-section["embedded-message.scrbl"]
+@include-section["vline.scrbl"]
+@include-section["hline.scrbl"]

collects/embedded-gui/scribblings/dllist.scrbl

@@ -0,0 +1,30 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@definterface/title[dllist<%> ()]{
+
+Defines a doubly-linked.
+
+@defmethod*[([(next) (is-a?/c dllist<%>)]
+             [(next [new-next (is-a?/c dllist<%>)]) void?])]{
+
+Gets/sets the next field to be the given dllist.}
+
+@defmethod*[([(prev) (is-a?/c dllist<%>)]
+             [(prev [new-prev (is-a?/c dllist<%>)]) void?])]{
+
+Gets/sets the previous item in the list.}
+
+@defmethod[(for-each [f ((is-a?/c dllist<%>) . -> . void?)]) void?]{
+
+Applies @scheme[f] to every element of the dllist.}
+
+@defmethod[(map-to-list [f ((is-a?/c dllist<%>) . -> . any/c)]) 
+           (listof any/c)]{
+
+Creates a Scheme list by applying @scheme[f] to every element
+of @this-obj[].}
+
+}
+
+

collects/embedded-gui/scribblings/embedded-button.scrbl

@@ -0,0 +1,18 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@defclass/title[embedded-button% snip-wrapper% (alignment<%>)]{
+
+A clickable button with a bitmap label.
+
+@defconstructor[([images (cons/c path-string? path-string?)]
+                 [callback ((is-a?/c button-snip%) (is-a?/c event%) . -> . void?)])]{
+
+The @scheme[images] argument is a pair filenames to be load as the
+button-label image, where the first is the image for when the button
+is at rest, and the second is the image for the button while its
+pressed.
+
+The @scheme[callback] is called when the button is clicked.}
+
+}

collects/embedded-gui/scribblings/embedded-gui.scrbl

@@ -0,0 +1,130 @@
+#lang scribble/doc
+@(require "common.ss"
+          (for-label framework))
+
+@title{@bold{Embedded GUI}: Widgets within @scheme[editor<%>]}
+
+@defmodule[embedded-gui]
+
+The @schememodname[embedded-gui] library provides a class hierarchy
+for creating graphical boxes within @scheme[editor<%>] objects with
+geometry management that mirrors that of @scheme[vertical-panel%] and
+@scheme[horizontal-panel%].
+
+@table-of-contents[]
+
+@include-section["containers.scrbl"]
+@include-section["controls.scrbl"]
+@include-section["control-snips.scrbl"]
+
+@; ----------------------------------------------------------------------
+
+@section{Helpers}
+
+@defmixin[stretchable-editor-snip-mixin (editor-snip%) (stretchable-snip<%>)]{
+
+ Extends an editor snip the @scheme[stretchable-snip<%>] interface,
+ which allows it to be stretched to fit an
+ @scheme[alignment-parent<%>]'s allotted width. Stretchable snips are
+ useful as the snip of a @scheme[snip-wrapper%] }
+
+
+@defclass[stretchable-editor-snip% editor-snip% (stretchable-editor-snip-mixin editor-snip%)]{
+
+ @defconstructor[([stretchable-width boolean? #t]
+                  [stretchable-height boolean? #t])]{
+
+ Creates a stretchable snip with the given initial stretchability.}}
+
+
+@defproc[(fixed-width-label-snip [possible-labels (listof string?)])
+         (subclass?/c snip%)]{
+
+ Returns a subclass of @scheme[snip%] that takes a single
+ initialization argument. The argument provided when instantiating the
+ class must be a member of @scheme[possible-labels]; the given label
+ is displayed by the snip, but the snip is sized to match the longest
+ of the labels in @scheme[possible-labels].
+
+ In other words, the resulting class helps align multiple GUI elements
+t   hat are labeled from a particular set of strings.}
+
+
+@definterface[tabbable-text<%> ()]{
+
+ An interface for tabbing between embedded @scheme[text%]s.
+
+ @defmethod[(set-caret-owner) void?]{
+
+ Moves the caret into the @scheme[tabbable-text<%>].}
+
+ @defmethod[(set-ahead) void?]{
+
+ Called when tabbing ahead.}
+
+ @defmethod[ (set-back) void?]{
+
+ Called when tabbing backward.}}
+
+
+@defmixin[tabbable-text-mixin (editor:keymap<%>) (tabbable-text<%>)]{
+
+  Adds the @scheme[tabbable-text<%>] interface to an
+  @scheme[editor:text%] class, where instantiation installs key
+  bindings to tab ahead and backward}
+
+
+@defproc[(set-tabbing [a-text (is-a?/c tabbable-text<%>)] ...)
+          void?]{
+
+Sets the tabbing order of @scheme[tabbable-text<%>]s by setting each
+text's @method[tabbable-text<%> set-ahead] and
+@method[tabbable-text<%> set-back] thunks to point to it's neighbor in
+the argument list.}
+
+
+@defmixin[grey-editor-snip-mixin (editor-snip%) ()]{
+
+ Gives an @scheme[editor-snip%] a colored background indicating that
+ is disabled. The editor is not disabled by the mixin however, and
+ must be locked separately.}
+
+@defmixin[grey-editor-mixin (editor<%>) ()]{
+
+ Gives an @scheme[editor<%>] a colored background indicating that is
+ disabled. The editor is not disabled by the mixin however, and must be
+ locked separately.}
+
+
+@defmixin[single-line-text-mixin (editor:keymap<%>) ()]{
+
+ Restricts a text to one line by overriding its key bindings to do
+ nothing on enter.}
+
+
+@defmixin[cue-text-mixin (text%) ()]{
+
+ Gives a @scheme[text%] an instantiation argument of a string that is
+ displayed in the @scheme[text%] initially in grey; the text
+ disappears when the text gets focus. This technique is useful for
+ labeling texts without needing to take up space.}
+
+
+@defclass[cue-text% (cue-text-mixin text%) ()]{
+
+ @defconstructor[([cue-text string? ""]
+                  [color string? "gray"]
+                  [behavior (listof (one-of/c 'on-focus 'on-char)) '(on-focus)])]{
+
+  Creates an instance with the given initial content, color, and
+  behvior for when to clear the text.}
+
+ @defmethod[(clear-cue-text) void?]{
+
+  Clears the cue text, if it's still present.}
+
+}
+
+@; ----------------------------------------------------------------------
+
+@include-section["snip-procs.scrbl"]

collects/embedded-gui/scribblings/embedded-message.scrbl

@@ -0,0 +1,11 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@defclass/title[embedded-message% snip-wrapper% ()]{
+
+A static text label.
+
+@defconstructor[([parent (is-a?/c alignment-parent<%>)]
+                 [label string?])]{
+
+Creates a static control that displays @scheme[label].}}

collects/embedded-gui/scribblings/embedded-text-button.scrbl

@@ -0,0 +1,13 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@defclass/title[embedded-text-button% snip-wrapper% (alignment<%>)]{
+
+A button with a text label.
+
+@defconstructor[([label string?]
+                 [callback ((is-a?/c text-button-snip%) (is-a?/c event%) . -> . void?)])]{
+
+The @scheme[callback] is called when the button is clicked.}
+
+}

collects/embedded-gui/scribblings/embedded-toggle-button.scrbl

@@ -0,0 +1,28 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@defclass/title[embedded-toggle-button% snip-wrapper% (alignment<%>)]{
+
+A @scheme[check-box%]-like control that a user can toggle between
+checked and unchecked states.
+
+@defconstructor[([images-off (cons/c path-string? path-string?)]
+                 [images-on (cons/c path-string? path-string?)]
+                 [turn-on ((is-a?/c toggle-button-snip%) (is-a?/c event%) . -> . void?)]
+                 [turn-off ((is-a?/c toggle-button-snip%) (is-a?/c event%) . -> . void?)]
+                 [state (symbols 'on 'off) 'on])]{
+
+The @scheme[images-off] argument is a pair filenames to be load as the
+button-label image, where the first is the image for when the button
+is at rest, and the second is the image for the button while its
+pressed---in both cases when the button is not checked by the
+user.  The @scheme[images-on] argument similarly determines the images
+for then the button is checked.
+
+The @scheme[turn-on] and @scheme[turn-off] callbacks are invoked when
+the button changes to checked or unchecked, respectively.
+
+The @scheme[state] argument determines whether the button is initially
+checked.}
+
+}

collects/embedded-gui/scribblings/hline.scrbl

@@ -0,0 +1,11 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@defclass/title[hline% snip-wrapper% (alignment<%>)]{
+
+Displays a horizontal line across the region that is inserted into.
+
+@defconstructor[([parent (is-a?/c alignment-parent<%>)])]{
+}
+}
+

collects/embedded-gui/scribblings/horizontal-alignment.scrbl

@@ -0,0 +1,12 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@defclass/title[horizontal-alignment% dllist<%> (alignment<%> alignment-parent<%>)]{
+
+@defconstructor[([parent (is-a?/c alignment-parent<%>)]
+                 [show? boolean? #t]
+                 [after (or/c (is-a?/c alignment<%>) false/c) #f])]{
+
+Inserts a new horizontal-alignment container into
+@scheme[parent]---optionally after a given container also in
+@scheme[parent]. The new container can be initially shown or hidden.}}

collects/embedded-gui/scribblings/snip-procs.scrbl

@@ -0,0 +1,62 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@title[#:tag "snip-related-functions"]{Snip Functions}
+
+@defproc[(snip-width [snip (is-a?/c snip%)]) real?]{
+
+The width of a snip in the parent pasteboard.}
+
+@defproc[(snip-height [snip (is-a?/c snip%)]) real?]{
+
+The height of a snip in the parent pasteboard.}
+
+@defproc[(snip-min-width [snip (is-a?/c snip%)]) real?]{
+
+The minimum width of the snip}
+
+@defproc[(snip-min-height [snip (is-a?/c snip%)]) real?]{
+
+The minimum height of the snip.}
+
+@defproc[(snip-parent [snip (is-a?/c snip%)]) (is-a?/c pasteboard%)]{
+
+The pasteboard that contains the snip.}
+
+@defproc[(fold-snip [f ((is-a?/c snip%) any/c . -> . any/c)]
+                    [init-acc any/c]
+                    [snip (is-a?/c snip%)])
+          any/c]{
+
+Applies @scheme[f] to all snips in the parent of @scheme[snip], 
+starting with @scheme[snip].}
+
+@defproc[(for-each-snip [f ((is-a?/c snip%) . -> . any/c)]
+                        [first-snip (is-a?/c snip%)] 
+                        [more list?] ...)
+         void?]{
+
+Applies the function to each snip in the parent of
+@scheme[first-snip], starting with @scheme[first-snip]. If
+@scheme[more] lists are supplied, they are used for extra arguments to
+@scheme[f], just like extra lists provided to @scheme[for-each].}
+
+@defproc[(map-snip [f ((is-a?/c snip%) . -> . any/c)]
+                   [first-snip (is-a?/c snip%)] 
+                   [more list?] ...)
+         void?]{
+
+Applies the function to each snip in the parent of
+@scheme[first-snip], starting with @scheme[first-snip], and
+accumulates the results into a list. If @scheme[more] lists are
+supplied, they are used for extra arguments to @scheme[f], just like
+extra lists provided to @scheme[map].}
+
+
+@defproc[(stretchable-width? [snip (is-a?/c snip%)]) boolean?]{
+
+True if the snip can be resized in the X dimension.}
+
+@defproc[(stretchable-height? [snip (is-a?/c snip%)]) boolean?]{
+
+True if the snip can be resized in the Y dimension.}

collects/embedded-gui/scribblings/snip-wrapper.scrbl

@@ -0,0 +1,12 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@defclass/title[snip-wrapper% dllist<%> (alignment<%>)]{
+
+Adapts an arbitrary @scheme[snip<%>] to work in an alignment
+container.
+
+@defconstructor[([parent (is-a?/c alignment-parent<%>)]
+                 [snip (is-a?/c snip%)])]{
+
+Adds @scheme[snip] to @scheme[parent].}}

collects/embedded-gui/scribblings/stretchable-snip.scrbl

@@ -0,0 +1,30 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@definterface/title[stretchable-snip<%> ()]{
+
+Must be implemented by any snip class whose objects will be
+stretchable when inserted into an @scheme[aligned-pasteboard<%>]
+within a @scheme[snip-wrapper%].
+
+@defmethod[(get-aligned-min-width) (and/c real? (not/c negative?))]{
+
+The minimum width that the snip can be resized to.}
+
+@defmethod[(get-aligned-min-height) (and/c real? (not/c negative?))]{
+
+The minimum height that the snip can be resized to.}
+
+@defmethod*[([(stretchable-width) boolean?]
+             [(stretchable-width [stretch? boolean?]) void?])]{
+
+Gets/sets whether or not the snip can be stretched in the X
+dimension.}
+
+@defmethod*[([(stretchable-height) boolean?]
+             [(stretchable-height [stretch? boolean?]) void?])]{
+
+Gets/sets whether or not the snip can be stretched in the Y
+dimension.}
+
+}

collects/embedded-gui/scribblings/text-button-snip.scrbl

@@ -0,0 +1,13 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@defclass/title[text-button-snip% snip% ()]{
+
+A button with a text label.
+
+@defconstructor[([label string?]
+                 [callback ((is-a?/c text-button-snip%) (is-a?/c event%) . -> . void)])]{
+
+The @scheme[callback] is called when the button is clicked.}
+
+}

collects/embedded-gui/scribblings/toggle-button-snip.scrbl

@@ -0,0 +1,28 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@defclass/title[toggle-button-snip% snip% ()]{
+
+A @scheme[check-box%]-like control that a user can toggle between
+checked and unchecked states.
+
+@defconstructor[([images-off (cons/c path-string? path-string?)]
+                 [images-on (cons/c path-string? path-string?)]
+                 [turn-on ((is-a?/c toggle-button-snip%) (is-a?/c event%) . -> . void?)]
+                 [turn-off ((is-a?/c toggle-button-snip%) (is-a?/c event%) . -> . void?)]
+                 [state (symbols 'on 'off) 'on])]{
+
+The @scheme[images-off] argument is a pair filenames to be load as the
+button-label image, where the first is the image for when the button
+is at rest, and the second is the image for the button while its
+pressed---in both cases when the button is not checked by the
+user.  The @scheme[images-on] argument similarly determines the images
+for then the button is checked.
+
+The @scheme[turn-on] and @scheme[turn-off] callbacks are invoked when
+the button changes to checked or unchecked, respectively.
+
+The @scheme[state] argument determines whether the button is initially
+checked.}
+
+}

collects/embedded-gui/scribblings/vertical-alignment.scrbl

@@ -0,0 +1,12 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@defclass/title[vertical-alignment% dllist<%> (alignment<%> alignment-parent<%>)]{
+
+@defconstructor[([parent (is-a?/c alignment-parent<%>)]
+                 [show? boolean? #t]
+                 [after (or/c (is-a?/c alignment<%>) false/c) #f])]{
+
+Inserts a new vertical-alignment container into
+@scheme[parent]---optionally after a given container also in
+@scheme[parent]. The new container can be initially shown or hidden.}}

collects/embedded-gui/scribblings/vline.scrbl

@@ -0,0 +1,11 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@defclass/title[vline% snip-wrapper% (alignment<%>)]{
+
+Displays a vertical line across the region that is inserted into.
+
+@defconstructor[([parent (is-a?/c alignment-parent<%>)])]{
+}
+}
+