From 92aa2fc780ce30c607090678d4ea1868761d82bc Mon Sep 17 00:00:00 2001 From: Ryan Culpepper Date: Sun, 15 Nov 2009 13:05:34 +0000 Subject: [PATCH] unstable/gui/notify: added partial docs svn: r16782 --- collects/macro-debugger/view/frame.ss | 5 + collects/unstable/gui/notify.ss | 12 +- collects/unstable/scribblings/gui.scrbl | 6 +- .../unstable/scribblings/gui/notify.scrbl | 110 ++++++++++++++++++ 4 files changed, 124 insertions(+), 9 deletions(-) create mode 100644 collects/unstable/scribblings/gui/notify.scrbl diff --git a/collects/macro-debugger/view/frame.ss b/collects/macro-debugger/view/frame.ss index 301bcf4727..04c0745547 100644 --- a/collects/macro-debugger/view/frame.ss +++ b/collects/macro-debugger/view/frame.ss @@ -25,6 +25,11 @@ unstable/gui/notify) (provide macro-stepper-frame-mixin) +(define-syntax override/return-false + (syntax-rules () + [(override/return-false m ...) + (begin (define/override (m) #f) ...)])) + (define (macro-stepper-frame-mixin base-frame%) (class* base-frame% (stepper-frame<%>) (init-field config) diff --git a/collects/unstable/gui/notify.ss b/collects/unstable/gui/notify.ss index b73efc59e3..099a5b7c33 100644 --- a/collects/unstable/gui/notify.ss +++ b/collects/unstable/gui/notify.ss @@ -4,24 +4,18 @@ scheme/list scheme/class scheme/gui) -(provide define/listen - field/notify +(provide field/notify notify-methods connect-to-pref connect-to-pref/readonly - override/return-false notify-box% notify-box/pref + notify-box/pref/readonly menu-option/notify-box menu-group/notify-box check-box/notify-box choice/notify-box) -(define-syntax override/return-false - (syntax-rules () - [(override/return-false m ...) - (begin (define/override (m) #f) ...)])) - (define-for-syntax (mk-init name) (format-id name "init-~a" (syntax-e name))) (define-for-syntax (mk-get name) @@ -76,6 +70,7 @@ (with-syntax ([init-name (mk-init #'name)]) #'(define/override (init-name) (notify-box/pref/readonly pref)))])) +#| (define-syntax (define/listen stx) (syntax-case stx () [(define/listen name value) @@ -93,6 +88,7 @@ (for-each (lambda (listener) (listener new-value)) listeners)) (define/public-final (listen-name listener) (set! listeners (cons listener listeners)))))])) +|# (define notify-box% (class object% diff --git a/collects/unstable/scribblings/gui.scrbl b/collects/unstable/scribblings/gui.scrbl index aaa4d74da7..b8792b7311 100644 --- a/collects/unstable/scribblings/gui.scrbl +++ b/collects/unstable/scribblings/gui.scrbl @@ -3,4 +3,8 @@ scribble/manual (for-label scribble/base)) -@title[#:tag "unstable-gui"]{GUI libraries} +@title[#:style '(toc) #:tag "unstable-gui"]{GUI libraries} + +@local-table-of-contents[] + +@include-section["gui/notify.scrbl"] diff --git a/collects/unstable/scribblings/gui/notify.scrbl b/collects/unstable/scribblings/gui/notify.scrbl new file mode 100644 index 0000000000..ef0eb83b63 --- /dev/null +++ b/collects/unstable/scribblings/gui/notify.scrbl @@ -0,0 +1,110 @@ +#lang scribble/manual +@(require (for-label unstable/gui/notify + scheme/contract + scheme/class + scheme/base)) + +@title[#:tag "gui-notify"]{Notify-boxes} + +@defmodule[unstable/gui/notify] + +@defclass[notify-box% object% ()]{ + +A notify-box contains a mutable cell. The notify-box notifies its +listeners when the contents of the cell is changed. + +@defconstructor[([value any/c])]{ + Creates a notify-box with the initial value @scheme[value]. +} +@defmethod[(get) any/c]{ + Gets the value currently stored in the notify-box. +} +@defmethod[(set [v any/c]) void?]{ + Updates the value stored in the notify-box and notifies the listeners. +} +@defmethod[(listen [listener (-> any/c any)]) void?]{ + Adds a callback to be invoked on the new value when the notify-box's + contents change. +} +@defmethod[(remove-listener [listener (-> any/c any)]) void?]{ + Removes a previously-added callback. +} +@defmethod[(remove-all-listeners) void?]{ + Removes all previously registered callbacks. +} +} + +@defproc[(notify-box/pref + [proc (case-> (-> any/c) (-> any/c void?))]) + (is-a?/c notify-box%)]{ + +Creates a notify-box with an initial value of @scheme[(proc)] that +invokes @scheme[proc] on the new value when the notify-box is updated. + +Useful for making a notify-box tied to a preference or parameter. +} + +@defproc[(notify-box/pref/readonly [proc (-> any/c)]) + (is-a?/c notify-box%)]{ + +Creates a notify-box with an initial value of @scheme[(proc)]. + +Useful for making a notify-box that takes its initial value from a +preference or parameter but does not update the preference or +parameter. +} + +@defproc[(menu-option/notify-box + [parent (or/c (is-a?/c menu%) (is-a?/c popup-menu%))] + [label label-string?] + [notify-box (is-a?/c notify-box%)]) + (is-a?/c checkable-menu-item%)]{ + +Creates a @scheme[checkable-menu-item%] tied to @scheme[notify-box]. The menu item is +checked whenever @scheme[(send notify-box get)] is true. Clicking the +menu item toggles the value of @scheme[notify-box] and invokes its listeners. +} + +@defproc[(check-box/notify-box + [parent (or/c (is-a?/c frame%) (is-a?/c dialog%) + (is-a?/c panel%) (is-a?/c pane%))] + [label label-string?] + [notify-box (is-a?/c notify-box%)]) + (is-a?/c check-box%)]{ + +Creates a @scheme[check-box%] tied to @scheme[notify-box]. The +check-box is checked whenever @scheme[(send notify-box get)] is +true. Clicking the check box toggles the value of @scheme[notify-box] +and invokes its listeners. +} + +@defproc[(choice/notify-box + [parent (or/c (is-a?/c frame%) (is-a?/c dialog%) + (is-a?/c panel%) (is-a?/c pane%))] + [label label-string?] + [choices (listof label-string?)] + [notify-box (is-a?/c notify-box%)]) + (is-a?/c choice%)]{ + +Creates a @scheme[choice%] tied to @scheme[notify-box]. The choice +control has the value @scheme[(send notify-box get)] selected, and +selecting a different choice updates @scheme[notify-box] and invokes +its listeners. + +If the value of @scheme[notify-box] is not in @scheme[choices], either +initially or upon an update, an error is raised. +} + +@defproc[(menu-group/notify-box + [parent (or/c (is-a?/c menu%) (is-a?/c popup-menu%))] + [labels (listof label-string?)] + [notify-box (is-a?/c notify-box%)]) + (listof (is-a?/c checkable-menu-item%))]{ + +Returns a list of @scheme[checkable-menu-item%] controls tied to +@scheme[notify-box]. A menu item is checked when its label is +@scheme[(send notify-box get)]. Clicking a menu item updates +@scheme[notify-box] to its label and invokes @scheme[notify-box]'s +listeners. +} +