From d913915068c30c2118b593f7323584b996200d8e Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Thu, 9 Aug 2007 17:21:12 +0000 Subject: [PATCH] towards MrEd documentation via Scribble svn: r7066 --- collects/scribble/manual.ss | 26 +- collects/scribblings/gui.ss | 11 + .../scribblings/gui/area-container-intf.scrbl | 274 +++++++++ .../gui/area-container-window-intf.scrbl | 8 + collects/scribblings/gui/area-intf.scrbl | 187 ++++++ collects/scribblings/gui/blurbs.ss | 291 +++++++++ collects/scribblings/gui/button-class.scrbl | 49 ++ collects/scribblings/gui/canvas-class.scrbl | 511 ++++++++++++++++ collects/scribblings/gui/canvas-intf.scrbl | 241 ++++++++ .../scribblings/gui/check-box-class.scrbl | 92 +++ .../gui/checkable-menu-item-class.scrbl | 74 +++ collects/scribblings/gui/choice-class.scrbl | 65 ++ .../gui/clipboard-client-class.scrbl | 86 +++ collects/scribblings/gui/clipboard-intf.scrbl | 161 +++++ .../scribblings/gui/combo-field-class.scrbl | 105 ++++ collects/scribblings/gui/common.ss | 10 + .../scribblings/gui/control-event-class.scrbl | 66 +++ collects/scribblings/gui/control-intf.scrbl | 44 ++ collects/scribblings/gui/cursor-class.scrbl | 94 +++ collects/scribblings/gui/dialog-class.scrbl | 117 ++++ collects/scribblings/gui/dialog-funcs.scrbl | 504 ++++++++++++++++ collects/scribblings/gui/event-class.scrbl | 51 ++ .../scribblings/gui/eventspace-funcs.scrbl | 237 ++++++++ collects/scribblings/gui/frame-class.scrbl | 340 +++++++++++ collects/scribblings/gui/gauge-class.scrbl | 85 +++ .../gui/group-box-panel-class.scrbl | 40 ++ .../gui/grow-box-spacer-pane-class.scrbl | 22 + collects/scribblings/gui/gui.scrbl | 17 + .../gui/horizontal-pane-class.scrbl | 28 + .../gui/horizontal-panel-class.scrbl | 34 ++ .../scribblings/gui/key-event-class.scrbl | 430 ++++++++++++++ .../gui/labelled-menu-item-intf.scrbl | 132 +++++ collects/scribblings/gui/list-box-class.scrbl | 303 ++++++++++ .../scribblings/gui/list-control-intf.scrbl | 137 +++++ collects/scribblings/gui/menu-bar-class.scrbl | 63 ++ collects/scribblings/gui/menu-class.scrbl | 49 ++ .../scribblings/gui/menu-item-class.scrbl | 45 ++ .../gui/menu-item-container-intf.scrbl | 50 ++ collects/scribblings/gui/menu-item-intf.scrbl | 69 +++ collects/scribblings/gui/message-class.scrbl | 53 ++ collects/scribblings/gui/miscwin-funcs.scrbl | 445 ++++++++++++++ .../scribblings/gui/mouse-event-class.scrbl | 365 ++++++++++++ collects/scribblings/gui/pane-class.scrbl | 36 ++ collects/scribblings/gui/panel-class.scrbl | 42 ++ .../scribblings/gui/popup-menu-class.scrbl | 87 +++ .../scribblings/gui/radio-box-class.scrbl | 196 ++++++ .../scribblings/gui/scroll-event-class.scrbl | 104 ++++ .../gui/selectable-menu-item-intf.scrbl | 116 ++++ .../gui/separator-menu-item-class.scrbl | 19 + collects/scribblings/gui/slider-class.scrbl | 87 +++ collects/scribblings/gui/subarea-intf.scrbl | 80 +++ collects/scribblings/gui/subwindow-intf.scrbl | 10 + .../scribblings/gui/system-menu-funcs.scrbl | 126 ++++ .../scribblings/gui/tab-panel-class.scrbl | 166 ++++++ .../scribblings/gui/text-field-class.scrbl | 139 +++++ collects/scribblings/gui/timer-class.scrbl | 109 ++++ .../gui/top-level-window-intf.scrbl | 362 ++++++++++++ .../scribblings/gui/vertical-pane-class.scrbl | 27 + .../gui/vertical-panel-class.scrbl | 34 ++ collects/scribblings/gui/window-intf.scrbl | 558 ++++++++++++++++++ collects/scribblings/gui/windowing.scrbl | 67 +++ .../scribblings/reference/contracts.scrbl | 2 +- collects/scribblings/scribble/manual.scrbl | 23 +- 63 files changed, 8388 insertions(+), 13 deletions(-) create mode 100644 collects/scribblings/gui.ss create mode 100644 collects/scribblings/gui/area-container-intf.scrbl create mode 100644 collects/scribblings/gui/area-container-window-intf.scrbl create mode 100644 collects/scribblings/gui/area-intf.scrbl create mode 100644 collects/scribblings/gui/blurbs.ss create mode 100644 collects/scribblings/gui/button-class.scrbl create mode 100644 collects/scribblings/gui/canvas-class.scrbl create mode 100644 collects/scribblings/gui/canvas-intf.scrbl create mode 100644 collects/scribblings/gui/check-box-class.scrbl create mode 100644 collects/scribblings/gui/checkable-menu-item-class.scrbl create mode 100644 collects/scribblings/gui/choice-class.scrbl create mode 100644 collects/scribblings/gui/clipboard-client-class.scrbl create mode 100644 collects/scribblings/gui/clipboard-intf.scrbl create mode 100644 collects/scribblings/gui/combo-field-class.scrbl create mode 100644 collects/scribblings/gui/common.ss create mode 100644 collects/scribblings/gui/control-event-class.scrbl create mode 100644 collects/scribblings/gui/control-intf.scrbl create mode 100644 collects/scribblings/gui/cursor-class.scrbl create mode 100644 collects/scribblings/gui/dialog-class.scrbl create mode 100644 collects/scribblings/gui/dialog-funcs.scrbl create mode 100644 collects/scribblings/gui/event-class.scrbl create mode 100644 collects/scribblings/gui/eventspace-funcs.scrbl create mode 100644 collects/scribblings/gui/frame-class.scrbl create mode 100644 collects/scribblings/gui/gauge-class.scrbl create mode 100644 collects/scribblings/gui/group-box-panel-class.scrbl create mode 100644 collects/scribblings/gui/grow-box-spacer-pane-class.scrbl create mode 100644 collects/scribblings/gui/gui.scrbl create mode 100644 collects/scribblings/gui/horizontal-pane-class.scrbl create mode 100644 collects/scribblings/gui/horizontal-panel-class.scrbl create mode 100644 collects/scribblings/gui/key-event-class.scrbl create mode 100644 collects/scribblings/gui/labelled-menu-item-intf.scrbl create mode 100644 collects/scribblings/gui/list-box-class.scrbl create mode 100644 collects/scribblings/gui/list-control-intf.scrbl create mode 100644 collects/scribblings/gui/menu-bar-class.scrbl create mode 100644 collects/scribblings/gui/menu-class.scrbl create mode 100644 collects/scribblings/gui/menu-item-class.scrbl create mode 100644 collects/scribblings/gui/menu-item-container-intf.scrbl create mode 100644 collects/scribblings/gui/menu-item-intf.scrbl create mode 100644 collects/scribblings/gui/message-class.scrbl create mode 100644 collects/scribblings/gui/miscwin-funcs.scrbl create mode 100644 collects/scribblings/gui/mouse-event-class.scrbl create mode 100644 collects/scribblings/gui/pane-class.scrbl create mode 100644 collects/scribblings/gui/panel-class.scrbl create mode 100644 collects/scribblings/gui/popup-menu-class.scrbl create mode 100644 collects/scribblings/gui/radio-box-class.scrbl create mode 100644 collects/scribblings/gui/scroll-event-class.scrbl create mode 100644 collects/scribblings/gui/selectable-menu-item-intf.scrbl create mode 100644 collects/scribblings/gui/separator-menu-item-class.scrbl create mode 100644 collects/scribblings/gui/slider-class.scrbl create mode 100644 collects/scribblings/gui/subarea-intf.scrbl create mode 100644 collects/scribblings/gui/subwindow-intf.scrbl create mode 100644 collects/scribblings/gui/system-menu-funcs.scrbl create mode 100644 collects/scribblings/gui/tab-panel-class.scrbl create mode 100644 collects/scribblings/gui/text-field-class.scrbl create mode 100644 collects/scribblings/gui/timer-class.scrbl create mode 100644 collects/scribblings/gui/top-level-window-intf.scrbl create mode 100644 collects/scribblings/gui/vertical-pane-class.scrbl create mode 100644 collects/scribblings/gui/vertical-panel-class.scrbl create mode 100644 collects/scribblings/gui/window-intf.scrbl create mode 100644 collects/scribblings/gui/windowing.scrbl diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss index 2111e096a4..f66c6be1b3 100644 --- a/collects/scribble/manual.ss +++ b/collects/scribble/manual.ss @@ -93,11 +93,13 @@ [(_ x) (add-scheme-index 'x (scheme x))])) (define (add-scheme-index s e) - (let ([k (if (and (pair? s) - (eq? (car s) 'quote)) - (cadr s) - s)]) - (index* (list (format "~s" k)) (list e) e))) + (let ([k (cond + [(and (pair? s) + (eq? (car s) 'quote)) + (format "~s" (cadr s))] + [(string? s) s] + [else (format "~s" s)])]) + (index* (list k) (list e) e))) (provide schemeblock SCHEMEBLOCK schemeblock0 SCHEMEBLOCK0 @@ -177,6 +179,20 @@ ;; ---------------------------------------- + (provide method xmethod) + + (define-syntax method + (syntax-rules () + [(_ a b) + (scheme b)])) + + (define-syntax xmethod + (syntax-rules () + [(_ a b) + (elem (scheme b) " in " (scheme a))])) + + ;; ---------------------------------------- + (provide margin-note) (define (margin-note . c) diff --git a/collects/scribblings/gui.ss b/collects/scribblings/gui.ss new file mode 100644 index 0000000000..2eb7875ab3 --- /dev/null +++ b/collects/scribblings/gui.ss @@ -0,0 +1,11 @@ + +(module gui mzscheme + (require "to-html.ss" + (prefix gui: "gui/gui.scrbl")) + + (provide build) + + (define (build) + (to-html #t #f + (list gui:doc) + (list "gui")))) diff --git a/collects/scribblings/gui/area-container-intf.scrbl b/collects/scribblings/gui/area-container-intf.scrbl new file mode 100644 index 0000000000..12decb2ceb --- /dev/null +++ b/collects/scribblings/gui/area-container-intf.scrbl @@ -0,0 +1,274 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@definterface[area-container<%> (area<%>)]{ + +An @scheme[area-container<%>] is a container @scheme[area<%>]. + +All @scheme[area-container<%>] classes accept the following named + instantiation arguments: +@itemize{ + + @item{@indexed-scheme[border] --- default is @scheme[0]; passed to +@method[area-container<%> border]} + @item{@indexed-scheme[spacing] --- default is @scheme[0]; passed to +@method[area-container<%> spacing]} + @item{@indexed-scheme[alignment] --- default is class-specific, such as + @scheme['(center top)] for @scheme[vertical-panel%]; the list + elements are passed to +@method[area-container<%> set-alignment]} +} + + + + +@defmethod[(get-children) + list of @scheme[subarea<%>] objects]{ +@spec{ + +Returns a list of the container's non-deleted children. (The non-deleted + children are the ones currently managed by the container; deleted + children are generally hidden.) The order of the children in the list + is significant. For example, in a vertical panel, the first child in + the list is placed at the top of the panel. + +}} + +@defmethod[(change-children [filter procedure of one argument, a list of \scmintf{subarea} objects, that returns a list of \scmintf{subarea} objects]) + void?]{ +@spec{ + +Takes a filter procedure and changes the container's list of non-deleted + children. The filter procedure takes a list of children areas and + returns a new list of children areas. The new list must consist of + children that were created as subareas of this area (i.e., +@method[area-container<%> change-children] cannot be used to change the parent of a subarea). + +After the set of non-deleted children is changed, the container computes + the sets of newly deleted and newly non-deleted children. Newly deleted + windows are hidden. Newly non-deleted windows are shown. + +Since non-window areas cannot be hidden, non-window areas cannot be + deleted. If the filter procedure removes non-window subareas, + an exception is raised and the set of non-deleted children is not changed. + +}} + +@defmethod[(place-children [info list of list containing two \IntsIn{0}{10000} and two booleans] + [width (integer-in 0 10000)] + [height (integer-in 0 10000)]) + list of list containing four \IntsIn{0}{10000}]{ +@spec{ + +Called to place the children of a container. See @|geomdiscuss| + for more information. + +}} + +@defmethod[(container-size [info list of list containing two \IntsIn{0}{10000} and two booleans]) + two \IntsIn{0}{10000}]{ +@spec{ + +Called to determine the minimum size of a container. See + @|geomdiscuss| for more information. + +}} + +@defmethod[(add-child [child (is-a/c subwindow<%>)]) + void?]{ +@spec{ + +Add the given subwindow to the set of non-deleted children. See also +@method[area-container<%> change-children]. + +}} + +@defmethod[(delete-child [child (is-a/c subwindow<%>)]) + void?]{ +@spec{ + +Removes the given subwindow from the list of non-deleted children. See also +@method[area-container<%> change-children]. + +}} + +@defmethod[(after-new-child [child (is-a/c subarea<%>)]) + void?]{ +@spec{ + +This method is called after a new containee area is created with this + area as its container. The new child is provided as an argument to + the method. + +} +@impl{ + +Does nothing. + + + +}} + +@defmethod*[([(border) + (integer-in 0 1000)] + [(border [margin (integer-in 0 1000)]) + void?])]{ +@spec{ + +Gets or sets the border margin for the container in pixels. This + margin is used as an inset into the panel's client area before the + locations and sizes of the subareas are computed. + +} +@impl{ +First case: + + +Returns the current border margin. + + + +Second case: + + +Sets the border margin. + + + +}} + +@defmethod*[([(spacing) + (integer-in 0 1000)] + [(spacing [spacing (integer-in 0 1000)]) + void?])]{ +@spec{ + +Gets or sets the spacing, in pixels, used between subareas in the + container. For example, a vertical panel inserts this spacing between + each pair of vertically aligned subareas (with no extra space at the + top or bottom). + +} +@impl{ +First case: + + +Returns the current spacing. + + + +Second case: + + +Sets the spacing. + + + +}} + +@defmethod[(set-alignment [horiz-align (symbols/c right center left)] + [vert-align (symbols/c bottom center top)]) + void?]{ +@spec{ + +Sets the alignment specification for a container, which determines how + it positions its children when the container has leftover space (when + a child was not stretchable in a particular dimension). + +When the container's horizontal alignment is @scheme['left], the + children are left-aligned in the container and whitespace is inserted + to the right. When the container's horizontal alignment is + @scheme['center], each child is horizontally centered in the + container. When the container's horizontal alignment is + @scheme['right], leftover whitespace is inserted to the left. + +Similarly, a container's vertical alignment can be @scheme['top], + @scheme['center], or @scheme['bottom]. + +}} + +@defmethod[(get-alignment) + two symbols]{ +@spec{ + +Returns the container's current alignment specification. See +@method[area-container<%> set-alignment] for more information. + +}} + +@defmethod[(reflow-container) + void?]{ +@spec{ + +When a container window is not shown, changes to the container's set + of children do not necessarily trigger the immediate re-computation + of the container's size and its children's sizes and positions. + Instead, the recalculation is delayed until the container is shown, + which avoids redundant computations between a series of changes. The +@method[area-container<%> reflow-container] method forces the immediate recalculation of the container's and its + children's sizes and locations. + +Immediately after calling the +@method[area-container<%> reflow-container] method, +@method[window<%> get-size], +@method[window<%> get-client-size], +@method[window<%> get-width], +@method[window<%> get-height], +@method[window<%> get-x], and +@method[window<%> get-y] report the manager-applied sizes and locations for the container and + its children, even when the container is hidden. A + container implementation can call functions such as +@method[window<%> get-size] at any time to obtain the current state of a window (because the + functions do not trigger geometry management). + +See also +@method[area-container<%> container-flow-modified]. + +}} + +@defmethod[(container-flow-modified) + void?]{ +@spec{ + +Call this method when the result changes for an overridden flow-defining method, such as +@method[area-container<%> place-children]. The call notifies the geometry manager that the placement of the + container's children needs to be recomputed. + +The +@method[area-container<%> reflow-container]method only recomputes child positions when the geometry manager + thinks that the placement has changed since the last computation. + +}} + +@defmethod[(begin-container-sequence) + void?]{ +@spec{ + +Suspends geometry management in the container's top-level window + until +@method[area-container<%> end-container-sequence] is called. The +@method[area-container<%> begin-container-sequence] and +@method[area-container<%> end-container-sequence] methods are used to bracket a set of container modifications so that + the resulting geometry is computed only once. A container sequence also + delays show and hide actions by +@method[area-container<%> change-children], as well as the on-screen part of showing via +@method[window<%> show] until the sequence is complete. Sequence begin and end commands may + be nested arbitrarily deep. + +}} + +@defmethod[(end-container-sequence) + void?]{ +@spec{ + +See +@method[area-container<%> begin-container-sequence]. + +} +@impl{ + + + + +}}} + diff --git a/collects/scribblings/gui/area-container-window-intf.scrbl b/collects/scribblings/gui/area-container-window-intf.scrbl new file mode 100644 index 0000000000..86e3e97b36 --- /dev/null +++ b/collects/scribblings/gui/area-container-window-intf.scrbl @@ -0,0 +1,8 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@definterface[area-container-window<%> (area-container<%> window<%>)]{ + + +} + diff --git a/collects/scribblings/gui/area-intf.scrbl b/collects/scribblings/gui/area-intf.scrbl new file mode 100644 index 0000000000..9facdb3066 --- /dev/null +++ b/collects/scribblings/gui/area-intf.scrbl @@ -0,0 +1,187 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@definterface[area<%> ()]{ + +An @scheme[area<%>] object is either a window or a windowless + container for managing the position and size of other areas. An + @scheme[area<%>] can be a container, a containee, or both. The only + areas without a parent are top-level windows. + +All @scheme[area<%>] classes accept the following named instantiation + arguments: +@itemize{ + + @item{@indexed-scheme[min-width] --- default is the initial graphical minimum width; passed to +@method[area<%> min-width]} + @item{@indexed-scheme[min-height] --- default is the initial graphical minimum height; passed to +@method[area<%> min-height]} + @item{@indexed-scheme[stretchable-width] --- default is class-specific; passed to +@method[area<%> stretchable-width]} + @item{@indexed-scheme[stretchable-height] --- default is class-specific; passed to +@method[area<%> stretchable-height]} +} + + + +@defmethod[(get-parent) + (or/c (is-a/c area-container<%>) false/c)]{ +@spec{ + +Returns the area's parent. A top-level window may have no parent (in + which case @scheme[#f] is returned), or it may have another top-level + window as its parent. + +}} + +@defmethod[(get-top-level-window) + @scheme[frame%] or @scheme[dialog%] object]{ +@spec{ + +Returns the area's closest frame or dialog ancestor. For a frame or + dialog area, the frame or dialog itself is returned. + +}} + +@defmethod*[([(min-width) + (integer-in 0 10000)] + [(min-width [w (integer-in 0 10000)]) + void?])]{ +@spec{ + +Gets or sets the area's minimum width (in pixels) for geometry + management. + +The minimum width is ignored when it is smaller than the area's + \DefinedElsewhere{minimum graphical width}, or when it is smaller + than the width reported by +@method[area-container<%> container-size] if the area is a container. See @|geomdiscuss| for more information. + +An area's initial minimum width is its graphical minimum width. See + also +@method[area<%> get-graphical-min-size] . + +} +@impl{ +First case: + + +Returns the current minimum width (in pixels). + + + +Second case: + + +Sets the minimum width (in pixels); if @scheme[w] is smaller than the + internal hard minimum, @|MismatchExn|}. + + + +}} + +@defmethod*[([(min-height) + (integer-in 0 10000)] + [(min-height [h (integer-in 0 10000)]) + void?])]{ +@spec{ + +Gets or sets the area's minimum height for geometry management. + +The minimum height is ignored when it is smaller than the area's + \DefinedElsewhere{minimum graphical height}, or when it is smaller + than the height reported by +@method[area-container<%> container-size] if the area is a container. See @|geomdiscuss| for more information. + +An area's initial minimum height is its graphical minimum height. See + also +@method[area<%> get-graphical-min-size] . + +} +@impl{ +First case: + + +Returns the current minimum height (in pixels). + + + +Second case: + + +Sets the minimum height (in pixels); if @scheme[h] is smaller than the + internal hard minimum, @|MismatchExn|}. + + + +}} + +@defmethod[(get-graphical-min-size) + two \IntsIn{0}{10000}]{ +@spec{ + +Returns the area's graphical minimum size as two values: the minimum + width and the minimum height (in pixels). + +See @|geomdiscuss| for more information. Note that the return value + {\em does not} depend on the area's +@method[area<%> min-width] and +@method[area<%> min-height] settings. + +}} + +@defmethod*[([(stretchable-width) + boolean?] + [(stretchable-width [stretch? any/c]) + void?])]{ +@spec{ + +Gets or sets the area's horizontal stretchability for geometry + management. See @|geomdiscuss| for more information. + +} +@impl{ +First case: + + +Returns the current horizontal stretchability. + + + +Second case: + + +Sets the horizontal stretchability. + + + +}} + +@defmethod*[([(stretchable-height) + boolean?] + [(stretchable-height [stretch? any/c]) + void?])]{ +@spec{ + +Gets or sets the area's vertical stretchability for geometry + management. See @|geomdiscuss| for more information. + +} +@impl{ +First case: + + +Returns the current vertical stretchability. + + + +Second case: + + +Sets the vertical stretchability. + + + + +}}} + diff --git a/collects/scribblings/gui/blurbs.ss b/collects/scribblings/gui/blurbs.ss new file mode 100644 index 0000000000..4dfad30a9d --- /dev/null +++ b/collects/scribblings/gui/blurbs.ss @@ -0,0 +1,291 @@ +#reader(lib "reader.ss" "scribble") +(module blurbs mzscheme + (require (lib "struct.ss" "scribble") + (lib "manual.ss" "scribble") + (lib "scheme.ss" "scribble") + (lib "decode.ss" "scribble")) + + (provide (all-defined-except p)) + + (define (p . l) + (decode-paragraph l)) + + (define (itemstyleinfo) + @elem{The @scheme[style] argument is reserved for future use.}) + + (define (labelsimplestripped where what) + @elem{If @litchar{&} occurs in @|where|, it is specially parsed; + under Windows and X, the character + following @litchar{&} is underlined in the displayed control to + indicate a keyboard mnemonic. (Under Mac OS X, mnemonic underlines are + not shown.) The mnemonic is meaningless for a @|what| (as far as + @method[top-level-window<%> on-traverse-char] is concerned), + but it is supported for consistency with other control types. A + programmer may assign a meaning to the mnemonic, e.g., by overriding + @method[top-level-window<%> on-traverse-char].}) + + (define (labelstripped where detail what) + @elem{If @litchar{&} occurs in @|where|@|detail|, it + is specially parsed; under Windows and X, the character following + @litchar{&} is underlined in the displayed control to indicate a + keyboard mnemonic. (Under Mac OS X, mnemonic underlines are not shown.) + The underlined mnemonic character must be a letter or a digit. The + user can @|what| by typing the mnemonic when the control's + top-level-window contains the keyboard focus. The user must also hold + down the Meta or Alt key if the keyboard focus is currently in a + control that handles normal alphanumeric input. The ampersand itself + is removed from @|where| before it is displayed for the control; a + double-ampersand in @|where| is converted to a single ampersand + (with no mnemonic underlining). Under Mac OS X, a parenthesized + mnemonic character is removed (along with any surrounding space) + before the label is displayed, since a parenthesized mnemonic is + often used for non-Roman languages. Finally, any text after a tab + character is removed on all platforms. Mnemonic keyboard events are handled + by @method[top-level-window<%> on-traverse-char] (but not under + Mac OS X).}) + + (define (bitmapuseinfo pre what thing then detail) + @elem{@|pre| @|what| is @|thing|, @|then| the bitmap@|detail| + must be valid (see @xmethod[bitmap% ok?]) and not installed + in a @scheme[bitmap-dc%] object; otherwise, @|MismatchExn|. If the + bitmap has a mask (see @xmethod[bitmap% get-loaded-mask]) + that is the same size as the bitmap, then the mask is used for the + label; furthermore, in contrast to the limitations of + @xmethod[dc% draw-bitmap], non-monochrome label masks work + consistently on all platforms.}) + + (define-syntax bitmaplabeluse + (syntax-rules () + [(_ id) @bitmapuseinfo["If" (scheme id) "a bitmap" "then" ""]])) + (define-syntax bitmaplabelusearray + (syntax-rules () + [(_ id) @bitmapuseinfo["If" (scheme id) "a list of bitmaps" "then" "s"]])) + (define-syntax bitmaplabeluseisbm + (syntax-rules () + [(_ id) @bitmapuseinfo["Since" (scheme id) "a bitmap" "" ""]])) + + (define bitmapiforiglabel + @elem{The bitmap label is installed only + if the control was originally created with a bitmap label.}) + + (define (NotDCRelated) + @elem{A path is not connected to any particular @scheme[dc<%>] object, so + setting a @scheme[dc<%>] origin or scale does not affect path + operations. Instead, a @scheme[dc<%>]'s origin and scale apply at the + time that the path is drawn or used to set a region.}) + + (define (popupmenuinfo what other more) + (make-splice + (list* + @p{Pops up the given @scheme[popup-menu%] object at the specified + coordinates (in this window's coordinates), and returns after + handling an unspecified number of events; the menu may still be + popped up when this method returns. If a menu item is selected from + the popup-menu, the callback for the menu item is called. (The + eventspace for menu item's callback is the @|what|'s eventspace.)} + + @p{While the menu is popped up, its target is set to the @|other|. See + @method[popup-menu% get-popup-target] + for more information.} + + (if (string=? more "") + null + @p{@|more|})))) + + (define insertcharundos + @elem{Multiple calls to the character-inserting method are grouped together + for undo purposes, since this case of the method is typically used + for handling user keystrokes. However, this undo-grouping feature + interferes with the undo grouping performed by + @method[editor<%> begin-edit-sequence] and + @method[editor<%> end-edit-sequence], so the string-inserting + method should be used instead during undoable edit sequences.}) + + (define (insertscrolldetails what) + @elem{@|what| editor's display is scrolled to show the new selection @techlink{position}.}) + + (define (insertdetails what) + @elem{If @scheme[end] is + not @scheme['same], then the region from @scheme[start] to @scheme[end] is + replaced with the text. @insertmovedetails[@scheme[end]]. If @scheme[scroll-ok?] is not @scheme[#f] + @insertscrolldetails[@elem{and @scheme[start] is the same as the + current caret @techlink{position}, then the}]}) + + (define (insertmovedetails what) + @elem{If the insertion @techlink{position} is before +or equal to the selection's start/end @techlink{position}, then the selection's +start/end @techlink{position} is incremented by @|what|.}) + + (define OVD + @elem{The result is only valid when the editor is displayed (see + @secref["tb:miaoverview"]).}) + + (define (FCAX c details) + @elem{@|c|alling this method may force the recalculation of @techlink{location} +information@|details|, even if the editor currently has delayed refreshing (see +@method[editor<%> refresh-delayed?]).}) + + (define FCA (FCAX "C" "")) + (define FCAMW (FCAX "C" " if a maximum width is set for the editor")) + (define (FCAME) (FCAX @elem{For @scheme[text%] objects, c} " if a maximum width is set for the editor")) + + (define EVD + @elem{If the editor is not displayed and the editor has a + maximum width, line breaks are calculated as for + @method[text% line-start-position] (which handles specially + the case of no display when the editor has a maximum width).}) + + (define (LineToPara what) + @elem{See also @method[text% paragraph-start-position], which + operates on paragraphs (determined by explicit newline characters) + instead of lines (determined by both explicit newline + characters and automatic line-wrapping).}) + + (define admindiscuss @secref["mr:editoradministrators"]) + (define ateoldiscuss @secref["mr:editoreol"]) + (define textdiscuss @secref["mr:editorflattened"]) + (define clickbackdiscuss @secref["mr:editorclickback"]) + (define stylediscuss @secref["mr:editorstyles"]) + (define timediscuss @secref["mr:editorcutandpastetime"]) + (define filediscuss @secref["mr:editorfileformat"]) + (define editordatadiscuss @secref["mr:editordata"]) + (define snipclassdiscuss @secref["mr:editorsnipclasses"]) + (define togglediscuss @secref["mr:styledeltatoggle"]) + (define drawcaretdiscuss @secref["mr:drawcaretinfo"]) + (define eventspacediscuss @secref["mr:eventspaceinfo"]) + (define lockdiscuss @secref["mr:lockinfo"]) + (define mousekeydiscuss @secref["mr:mouseandkey"]) + (define globaleditordatadiscuss @secref["mr:globaleditordata"]) + + (define geomdiscuss @secref["mr:containeroverview"]) + + (define mrprefsdiscuss @secref["mr:mredprefs"]) + + (define seesniporderdiscuss + @elem{See @secref["mr:tb:miaoverview"] for information about snip order in pasteboards.}) + + (define (clipboardtypes) + @elem{The @scheme[format] string is typically four capital letters. (Under + Mac OS X, only four characters for @scheme[format] are ever used.) For + example, @scheme["TEXT"] is the name of the UTF-8-encoded string format. New + format names can be used to communicate application- and + platform-specific data formats.}) + + (define PrintNote + (make-splice + (list + @p{Be sure to use the following methods to start/end drawing:} + @itemize{@item{@method[dc<%> start-doc]} + @item{@method[dc<%> start-page]} + @item{@method[dc<%> end-page]} + @item{@method[dc<%> end-doc]}} + @p{Attempts to use a drawing method outside of an active page raises an exception.}))) + + (define SeeMzParam @elem{(see @secref["mz:parameters"])}) + + (define DrawSizeNote @elem{Restrictions on the magnitude of + drawing coordinates are described with @scheme[dc<%>].}) + + (define LineNumbering @elem{Lines are numbered starting with @scheme[0].}) + (define ParagraphNumbering @elem{Paragraphs are numbered starting with @scheme[0].}) + + (define (italicptyStyleNote) + @elem{The @scheme[style] argument is provided for future extensions. Currently, @scheme[style] must be the empty list.}) + + (define (HVLabelNote what) + @elem{If @scheme[style] includes @scheme['vertical-label], then the #1 is + created with a label above the control; if @scheme[style] does not include + @scheme['vertical-label] (and optionally includes @scheme['horizontal-label]), then the + label is created to the left of the @|what|.}) + + (define (DeletedStyleNote what) + @elem{If @scheme[style] includes @scheme['deleted], then the @|what| is created as hidden, + and it does not affect its parent's geometry; the @|what| can be made active later by calling + @scheme[parent]'s @method[area-container<%> add-child] method.}) + + (define (InStyleListNote) + @elem{The editor's style list must contain @scheme[style], otherwise + the style is not changed. See also @xmethod[style-list% convert].}) + + (define (FontKWs) @elem{The @scheme[font] argument determines the font for the control.}) + (define (FontLabelKWs) @elem{The @scheme[font] argument determines the font for the control content, + and @scheme[label-font] determines the font for the control label.}) + + (define (WindowKWs) @elem{For information about the @scheme[enabled] argument, see @scheme[window<%>].}) + (define (SubareaKWs) @elem{For information about the @scheme[horiz-margin] and @scheme[vert-margin] + arguments, see @scheme[subarea<%>].}) + (define (AreaContKWs) @elem{For information about the @scheme[border], @scheme[spacing], and @scheme[alignment] + arguments, see @scheme[area-container<%>].}) + + (define (AreaKWs) @elem{For information about the + @scheme[min-width], @scheme[min-height], @scheme[stretchable-width], and + @scheme[stretchable-height] arguments, see @scheme[area<%>].}) + + (define MismatchExn @elem{an @scheme[exn:fail:contract] exception is raised}) + + (define AFM @elem{Adobe Font Metrics}) + + (define (MonitorMethod what by-what method whatsit) + @elem{@|what| can be changed + by @|by-what|, and such changes do not go through this method; use @|method| to + monitor @|whatsit| changes.}) + + (define (MonitorCallbackX a b c d) + (MonitorMethod a b @elem{the @|d|callback procedure (provided as an initialization argument)} c)) + + (define (MonitorCallback a b c) + (MonitorCallbackX a b c "control")) + + (define (Unmonitored what by-what the-what method) + @elem{@|what| can be changed + by @|by-what|, and such changes do not go through this method. A program + cannot detect when @|the-what| except by polling @|method|.}) + + (define OnInsertNote + (MonitorMethod @elem{The content of an editor} + @elem{the system in response to other method calls} + @elem{@xmethod[text% on-insert] or @xmethod[pasteboard% on-insert]} + @elem{content additions})) + + (define OnDeleteNote + (MonitorMethod @elem{The content of an editor} + @elem{the system in response to other method calls} + @elem{@xmethod[text% on-delete] or @xmethod[pasteboard% on-delete]} + @elem{content deletions})) + + (define OnSelectNote + (MonitorMethod @elem{The selection in a pasteboard} + @elem{the system in response to other method calls} + @elem{@method[pasteboard% on-select]} + @elem{selection})) + + (define OnMoveNote + (MonitorMethod @elem{Snip @techlink{location}s in a pasteboard} + @elem{the system in response to other method calls} + @elem{@method[pasteboard% on-move-to]} + @elem{snip @techlink{position}})) + + (define (colorName name name2 r g b) + name) + + (define (Resource s) + @elem{@to-element[`(quote ,(string->symbol (string-append "MrEd:" s)))] + preference}) + (define (ResourceFirst s) ; fixme -- add index + (Resource s)) + + (define (edsnipsize a b c) + @elem{An @scheme[editor-snip%] normally stretches to wrap around the size + of the editor it contains. This method #1 of the snip + (and if the editor is #2, #3).}) + (define (edsnipmax n) + (edsnipsize @elem{limits the @|n|} + @elem{larger} + @elem{only part of the editor is displayed})) + (define (edsnipmin a b) + (edsnipsize @elem{sets the minimum @|a|} + "smaller" + @elem{the editor is @|b|-aligned in the snip})) + + ) + diff --git a/collects/scribblings/gui/button-class.scrbl b/collects/scribblings/gui/button-class.scrbl new file mode 100644 index 0000000000..b3aaf2af53 --- /dev/null +++ b/collects/scribblings/gui/button-class.scrbl @@ -0,0 +1,49 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + + +@defclass[button% object% (control<%>)]{ + +Whenever a button is clicked by the user, the buttons's callback + procedure is invoked. A callback procedure is provided as an + initialization argument when each button is created. + +@defconstructor[[label (or/c label-string? (is-a/c bitmap%))] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [callback ((is-a/c button%) (is-a/c control-event%) . -> . any) (lambda (b e) (void))] + [style (symbols/c deleted border) null] + [font (is-a/c font%) @scheme[normal-control-font]] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 2] + [horiz-margin (integer-in 0 1000) 2] + [min-width (integer-in 0 10000) @italic{graphical minimum width}] + [min-height (integer-in 0 10000) @italic{graphical minimum height}] + [stretchable-width any/c #f] + [stretchable-height any/c #f]]{ + +Creates a button with a string or bitmap label. + label + +@labelstripped[(scheme label) @elem{ (when @scheme[label] is a string)} @elem{effectively click the button}] + +The @scheme[callback] procedure is called (with the event type +@indexed-scheme['button]) whenever the user clicks the button. + +If @scheme[style] includes @scheme['border], the button is drawn with +a special border that indicates to the user that it is the default +action button (see @method[top-level-window<%> +on-traverse-char]). \DeletedStyleNote{button} + +@FontKWs[] @WindowKWs[] @SubareaKWs[] @AreaKWs[]} + + +@defmethod[#:mode 'add + (set-label [label (is-a/c bitmap%)]) + void?]{ +@impl{ + +Sets the bitmap label for a bitmap button. @bitmaplabeluseisbm[label] + @|bitmapiforiglabel| + +}}} + diff --git a/collects/scribblings/gui/canvas-class.scrbl b/collects/scribblings/gui/canvas-class.scrbl new file mode 100644 index 0000000000..83ac07355a --- /dev/null +++ b/collects/scribblings/gui/canvas-class.scrbl @@ -0,0 +1,511 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[canvas% object% (canvas<%>)]{ + +A @scheme[canvas%] object is a general-purpose window for drawing + and handling events. + + + + +@defconstructor[[parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [style (symbols/c no-focus transparent no-autoclear deleted gl resize-corner hscroll vscroll combo control-border border) null] + [paint-callback procedure of two arguments: a @scheme[canvas%] object and a @scheme[dc<%>] object void] + [label (or/c label-string? false/c) #f] + [gl-config (or/c (is-a/c gl-config%) false/c) #f] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 0] + [horiz-margin (integer-in 0 1000) 0] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #t] + [stretchable-height any/c #t]]{ + +The @scheme[style] argument indicates one or more of the following styles: +@itemize{ + + @item{@scheme['border] --- gives the canvas a thin border} + + @item{@scheme['control-border] --- gives the canvas a border that is + like a @scheme[text-field%] control} + + @item{@scheme['combo] --- gives the canvas a combo button that is like + a @scheme[combo-field%] control; this style is intended for use + with @scheme['control-border] and not with @scheme['hscroll] or + @scheme['vscroll]} + + @item{@scheme['hscroll] --- enables horizontal scrolling (initially visible but inactive)} + + @item{@scheme['vscroll] --- enables vertical scrolling (initially visible but inactive)} + + @item{@scheme['resize-corner] --- leaves room for a resize control at the canvas's + bottom right when only one scrollbar is visible} + + @item{@scheme['gl] --- {\em obsolete} (every canvas is an OpenGL context where supported)} + + @item{@scheme['deleted] --- creates the canvas as initially hidden and without affecting + @scheme[parent]'s geometry; the canvas can be made active + later by calling @scheme[parent]'s @method[area-container<%> add-child] + method} + + @item{@scheme['no-autoclear] --- prevents automatic erasing of the + canvas before calls to +@method[canvas% on-paint]} + @item{@scheme['transparent] --- the canvas is automatically ``erased'' + before an update using it's parent window's background; the result is + undefined if this flag is combined with @scheme['no-autoclear]} + + @item{@scheme['no-focus] --- prevents the canvas from accepting the + keyboard focus when the canvas is clicked, or when the +@method[window<%> focus] method is called} + + +} + +The @scheme['hscroll] and @scheme['vscroll] styles create a + canvas with an initially inactive scrollbar. The scrollbars are + activated with either +@method[canvas% init-manual-scrollbars] or +@method[canvas% init-auto-scrollbars], and they can be hidden and re-shown with +@method[canvas% show-scrollbars]. + +The @scheme[paint-callback] argument is called by the default +@method[canvas% on-paint] method, using the canvas and the DC returned by +@method[canvas<%> get-dc] as the argument. + +The @scheme[label] argument names the canvas for +@method[window<%> get-label], but it is not displayed with the canvas. + +The @scheme[gl-config] argument determines properties of an OpenGL + context for this canvas, as obtained through the canvas's drawing + context. See also +@method[canvas<%> get-dc] and +@xmethod[dc<%> get-gl-context]. + + +@WindowKWs[] @SubareaKWs[] @AreaKWs[] + + + +} + +@defmethod[(with-gl-context [thunk (-> any)]) + any]{ +@spec{ + +Passes the given thunk to +@method[gl-context<%> call-as-current] % +of the result of +@method[dc<%> get-gl-context] % +for this canvas's DC as returned by +@method[canvas<%> get-dc]. + +The +@method[gl-context<%> call-as-current] % +method acquires a re-entrant lock, so nested calls to +@method[canvas% with-gl-context] on different threads or OpenGL contexts can block or deadlock. + + +}} + +@defmethod[(swap-gl-buffers) + void?]{ +@spec{ + +Calls +@method[gl-context<%> swap-buffers] % +on the result of +@method[dc<%> get-gl-context] % +for this canvas's DC as returned by +@method[canvas<%> get-dc]. + +The +@method[gl-context<%> swap-buffers] % +method acquires a re-entrant lock, so nested calls to +@method[canvas% with-gl-context] on different threads or OpenGL contexts can block or deadlock. + + +}} + +@defmethod[(on-scroll [event (is-a/c scroll-event%)]) + void?]{ +@spec{ + +Called when the user changes one of the canvas's scrollbars. A + @scheme[scroll-event%] argument provides information about the + scroll action. + +This method is called only when manual + scrollbars are changed, not automatic scrollbars; for automatic scrollbars, + the +@method[canvas<%> on-paint] method is called, instead. + +}} + +@defmethod[(get-scroll-pos [which (symbols/c vertical horizontal)]) + (integer-in 0 10000)]{ +@spec{ + +Gets the current value of a manual scrollbar. The result is always + @scheme[0] if the scrollbar is not active or it is automatic. + +See also +@method[canvas% init-manual-scrollbars]. + +} +@impl{ + +The @scheme[which] argument is either @scheme['horizontal] or + @scheme['vertical], indicating that the value of the horizontal or + vertical scrollbar should be returned, respectively. + + + +}} + +@defmethod[(set-scroll-pos [which (symbols/c vertical horizontal)] + [value (integer-in 0 10000)]) + void?]{ +@spec{ + +Sets the current value of a manual scrollbar. (This method has no + effect on automatic scrollbars.) + +@MonitorMethod[@elem{The value of the canvas's scrollbar} @elem{the user scrolling} @elem{@method[canvas% on-scroll]} @elem{scrollbar value}] + +See also +@method[canvas% init-manual-scrollbars] and +@method[canvas% scroll]. + +} +@impl{ + +The @scheme[which] argument is either @scheme['horizontal] or + @scheme['vertical], indicating whether to set the value of the + horizontal or vertical scrollbar set, respectively. + + + +}} + +@defmethod[(get-scroll-range [which (symbols/c vertical horizontal)]) + (integer-in 0 10000)]{ +@spec{ + +Gets the current maximum value of a manual scrollbar. The result is + always @scheme[0] if the scrollbar is not active or it is automatic. + +See also +@method[canvas% init-manual-scrollbars]. + +} +@impl{ + +The @scheme[which] argument is either @scheme['horizontal] or + @scheme['vertical], indicating whether to get the maximum value of the + horizontal or vertical scrollbar, respectively. + + + +}} + +@defmethod[(set-scroll-range [which (symbols/c vertical horizontal)] + [value (integer-in 0 10000)]) + void?]{ +@spec{ + +Sets the current maximum value of a manual scrollbar. (This method has + no effect on automatic scrollbars.) + +See also +@method[canvas% init-manual-scrollbars]. + +} +@impl{ + +The @scheme[which] argument is either @scheme['horizontal] or + @scheme['vertical], indicating whether to set the maximum value of the + horizontal or vertical scrollbar, respectively. + + + +}} + +@defmethod[(get-scroll-page [which (symbols/c vertical horizontal)]) + (integer-in 1 10000)]{ +@spec{ + +Get the current page step size of a manual scrollbar. The result is + @scheme[0] if the scrollbar is not active or it is automatic. + +See also +@method[canvas% init-manual-scrollbars]. + +} +@impl{ + +The @scheme[which] argument is either @scheme['horizontal] or + @scheme['vertical], indicating whether to get the page step size of + the horizontal or vertical scrollbar, respectively. + + + +}} + +@defmethod[(set-scroll-page [which (symbols/c vertical horizontal)] + [value (integer-in 1 10000)]) + void?]{ +@spec{ + +Set the current page step size of a manual scrollbar. (This method has + no effect on automatic scrollbars.) + +See also +@method[canvas% init-manual-scrollbars]. + +} +@impl{ + +The @scheme[which] argument is either @scheme['horizontal] or + @scheme['vertical], indicating whether to set the page step size of + the horizontal or vertical scrollbar, respectively. + + + +}} + +@defmethod[(get-virtual-size) + two \IntsIn{0}{10000}]{ +@spec{ + +Gets the size in device units of the scrollable canvas area (as + opposed to the client size, which is the area of the canvas currently + visible). This is the same size as the client size (as returned by +@method[window<%> get-client-size]) unless scrollbars are initialized as automatic (see +@method[canvas% init-auto-scrollbars]). + +}} + +@defmethod[(scroll [h-value (or/c (real-in 0.0 1.0) false/c)] + [v-value (or/c (real-in 0.0 1.0) false/c)]) + void?]{ +@spec{ + +Sets the values of automatic scrollbars. (This method has no effect on + manual scrollbars.) + +} +@impl{ + +If either argument is @scheme[#f], the scrollbar value is not changed in + the corresponding direction. + +The @scheme[h-value] and @scheme[v-value] arguments each specify a fraction + of the scrollbar's movement. A @scheme[0.0] value sets the scrollbar to + its left/top, while a @scheme[1.0] value sets the scrollbar to its + right/bottom. A @scheme[0.5] value sets the scrollbar to its middle. In + general, if the canvas's virtual size is @scheme[v], its client size is + @scheme[c], and @scheme[(> @scheme[v] \var{c])}, then scrolling to @scheme[p] + sets the view start to @scheme[(floor (* @scheme[p] (- \var{v] @scheme[c])))}. + +See also +@method[canvas% init-auto-scrollbars] and +@method[canvas% get-view-start]. + + + +}} + +@defmethod[(init-auto-scrollbars [horiz-pixels (or/c (integer-in 1 10000) false/c)] + [vert-pixels (or/c (integer-in 1 10000) false/c)] + [h-value (real-in 0.0 1.0)] + [v-value (real-in 0.0 1.0)]) + void?]{ +@spec{ + +Enables and initializes automatic scrollbars for the canvas. A + horizontal or vertical scrollbar can be activated only in a canvas + that was created with the @indexed-scheme['hscroll] or + @indexed-scheme['vscroll] style flag, respectively. + +With automatic scrollbars, the programmer specifies the desired + virtual size of the canvas, and the scrollbars are automatically + handled to allow the user to scroll around the virtual area. The + scrollbars are not automatically hidden if they are unneeded; see +@method[canvas% show-scrollbars]. + +See also +@method[canvas% init-manual-scrollbars] for information about manual scrollbars. The horizontal and vertical + scrollbars are always either both manual or both automatic, but they + are independently enabled. Automatic scrollbars can be + re-initialized as manual, and vice-versa. + +} +@impl{ + +Initializes the scrollbars and resets the canvas's virtual size to the + given values. If either @scheme[horiz-pixels] or @scheme[vert-pixels] is + @scheme[#f], the scrollbar is not enabled in the corresponding + direction, and the canvas's virtual size in that direction is the + same as its client size. + +The @scheme[h-value] and @scheme[v-value] arguments specify the initial + values of the scrollbars as a fraction of the scrollbar's range. A + @scheme[0.0] value initializes the scrollbar to its left/top, while a + @scheme[1.0] value initializes the scrollbar to its right/bottom. + +See also +@method[canvas% on-scroll] and +@method[canvas% get-virtual-size]. + + + +}} + +@defmethod[(init-manual-scrollbars [h-length (or/c (integer-in 0 10000) false/c)] + [v-length (or/c (integer-in 0 10000) false/c)] + [h-page (integer-in 1 10000)] + [v-page (integer-in 1 10000)] + [h-value (integer-in 0 10000)] + [v-value (integer-in 0 10000)]) + void?]{ +@spec{ + +Enables and initializes manual scrollbars for the canvas. A + horizontal or vertical scrollbar can be activated only in a canvas + that was created with the @indexed-scheme['hscroll] or + @indexed-scheme['vscroll] style flag, respectively. + +With manual scrollbars, the programmer is responsible for managing all + details of the scrollbars, and the scrollbar state has no effect on + the canvas's virtual size. Instead, the canvas's virtual size is the + same as its client size. + +See also +@method[canvas% init-auto-scrollbars] for information about automatic scrollbars. The horizontal and vertical + scrollbars are always either both manual or both automatic, but they + are independently enabled. Automatic scrollbars can be re-initialized + as manual, and vice-versa. + +} +@impl{ + +The @scheme[h-length] and @scheme[v-length] arguments specify the length of + each scrollbar in scroll steps (i.e., the maximum value of each + scrollbar). If either is @scheme[#f], the scrollbar is disabled in the +corresponding direction. + +The @scheme[h-page] and @scheme[v-page] arguments set the number of + scrollbar steps in a page, i.e., the amount moved when pressing above + or below the value indicator in the scrollbar control. + +The @scheme[h-value] and @scheme[v-value] arguments specify the initial + values of the scrollbars. + +If @scheme[h-value] is greater than @scheme[h-length] or @scheme[v-value] is + greater than @scheme[v-length], @|MismatchExn|}. (The page step may be + larger than the total size of a scrollbar.) + + +See also +@method[canvas% on-scroll] and +@method[canvas% get-virtual-size]. + + + +}} + +@defmethod[(show-scrollbars [show-horiz? any/c] + [show-vert? any/c]) + void?]{ +@spec{ + +Shows or hides scrollbar. The horizontal scrollbar can be shown only + if the canvas was created with the @scheme['hscroll] style, and the + vertical scrollbar can be shown only if the canvas was created with + the @scheme['vscroll] style. See also +@method[canvas% init-auto-scrollbars] and +@method[canvas% init-manual-scrollbars]. + +} +@impl{ + +Shows or hides the scrollbars as indicated by @scheme[show-horiz?]\ and + @scheme[show-vert?]. If @scheme[show-horiz?]\ is true and the canvas + was not created with the @scheme['hscroll] style, @|MismatchExn|}. + Similarly, if @scheme[show-vert?]\ is true and the canvas + was not created with the @scheme['vscroll] style, @|MismatchExn|}. + + + +}} + +@defmethod[(get-view-start) + two \IntsIn{0}{10000}]{ +@spec{ + +Get the location at which the visible portion of the canvas starts, + based on the current values of the horizontal and vertical scrollbars + if they are initialized as automatic (see +@method[canvas% init-auto-scrollbars] ). Combined with +@method[window<%> get-client-size], an application can efficiently redraw only the visible portion of + the canvas. The values are in pixels. + +If the scrollbars are disabled or initialized as manual (see +@method[canvas% init-manual-scrollbars]), the result is @scheme[(values \scmc{0] @scheme[0])}. + +}} + +@defmethod*[([(accept-tab-focus) + boolean?] + [(accept-tab-focus [on? any/c]) + void?])]{ +@spec{ + +\index{keyboard focus!navigation} +Gets or sets whether tab-focus is enabled for the canvas (assuming + that the canvas is not created with the @scheme['no-focus] style). When + tab-focus is enabled, the canvas can receive the keyboard focus when + the user navigates among a frame or dialog's controls with the Tab and + arrow keys. By default, tab-focus is disabled. + +When tab-focus is enabled for a canvas, Tab, arrow, and Enter keyboard + events are consumed by a frame's default +@method[top-level-window<%> on-traverse-char] method. (In addition, a dialog's default method consumes Escape key + events.) Otherwise, +@method[top-level-window<%> on-traverse-char] allows the keyboard events to be propagated to the canvas. + +} +@impl{ +First case: + + +Returns @scheme[#t] if tab-focus is enabled for the canvas, @scheme[#f] + otherwise. + + + +Second case: + + +Enables or disables tab-focus for the canvas. + + + +}} + +@defmethod[#:mode 'override + (on-paint) + void?]{ +@impl{ + +Calls the procedure supplied as the @scheme[paint-callback] argument when + the @scheme[canvas%] was created. + + + + + +}}} + diff --git a/collects/scribblings/gui/canvas-intf.scrbl b/collects/scribblings/gui/canvas-intf.scrbl new file mode 100644 index 0000000000..058699c328 --- /dev/null +++ b/collects/scribblings/gui/canvas-intf.scrbl @@ -0,0 +1,241 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@definterface[canvas<%> (subwindow<%>)]{ + +A canvas is a subwindow onto which graphics and text can be drawn. Canvases also + receive mouse and keyboard events. + +To draw onto a canvas, get its device context (see +@method[canvas<%> get-dc]). + +The @scheme[canvas<%>] interface is implemented by two classes: +@itemize{ + + @item{@scheme[canvas%] --- a canvas for arbitrary drawing and + event handling} + + @item{@scheme[editor-canvas%] --- a canvas for displaying + @scheme[editor<%>] objects} + +} + + + + +@defmethod[(on-char [ch (is-a/c key-event%)]) + void?]{ +@spec{ + +Called when the canvas receives a keyboard event. See also + @|mousekeydiscuss|. + +} +@impl{ + +Does nothing. + + + +}} + +@defmethod[(on-event [event (is-a/c mouse-event%)]) + void?]{ +@spec{ + +Called when the canvas receives a mouse event. See also + @|mousekeydiscuss|, noting in particular that certain mouse events + can get dropped. + +} +@impl{ + +Does nothing. + + + +}} + +@defmethod[(on-paint) + void?]{ +@spec{ + +Called when the canvas is exposed or resized so that the image in the + canvas can be repainted. + +When +@method[canvas<%> on-paint] is called in response to a system expose event and only a portion of + the canvas is newly exposed, any drawing operations performed by +@method[canvas<%> on-paint] are clipped to the newly-exposed region; however, the clipping region + as reported by +@method[dc<%> get-clipping-region] does not change. + +} +@impl{ + +Does nothing. + + + +}} + +@defmethod[(on-tab-in) + void?]{ +@spec{ + +Called when the keyboard focus enters the canvas via keyboard + navigation events. The +@method[window<%> on-focus] method is also called, as usual for a focus change. When the keyboard + focus leaves a canvas due to a navigation event, only +@method[window<%> on-focus] is called. + +See also +@xmethod[canvas% accept-tab-focus] and +@xmethod[top-level-window<%> on-traverse-char] . + +} +@impl{ + +Does nothing. + + + +}} + +@defmethod[(get-dc) + (is-a/c dc<%>)]{ +@spec{ + +Gets the canvas's device context. See +@scheme[dc<%>] for more information about drawing. + +}} + +@defmethod*[([(min-client-width) + (integer-in 0 10000)] + [(min-client-width [w (integer-in 0 10000)]) + void?])]{ +@spec{ + +Gets or sets the canvas's minimum width for geometry management, based + on the canvas's client size rather than its full size. The client + width is obtained or changed via +@xmethod[area<%> min-width], adding or subtracting border and scrollbar sizes as appropriate. + +The minimum width is ignored when it is smaller than the canvas's + \DefinedElsewhere{minimum graphical width}. See @|geomdiscuss| for + more information. + +} +@impl{ +First case: + + +Returns the current minimum client width (in pixels). + + + +Second case: + + +Sets the minimum client width (in pixels). + + + +}} + +@defmethod*[([(min-client-height) + (integer-in 0 10000)] + [(min-client-height [h (integer-in 0 10000)]) + void?])]{ +@spec{ + +Gets or sets the canvas's minimum height for geometry management, + based on the client size rather than the full size. The client height + is obtained or changed via +@xmethod[area<%> min-height], adding or subtracting border and scrollbar sizes as appropriate. + +The minimum height is ignored when it is smaller than the canvas's + \DefinedElsewhere{minimum graphical height}. See @|geomdiscuss| for + more information. + +} +@impl{ +First case: + + +Returns the current minimum client height (in pixels). + + + +Second case: + + +Sets the minimum client height (in pixels). + + + +}} + +@defmethod[(warp-pointer [x (integer-in 0 10000)] + [y (integer-in 0 10000)]) + void?]{ +@spec{ + +Moves the cursor to the given location on the canvas. + +}} + +@defmethod[(set-canvas-background [color (is-a/c color%)]) + void?]{ +@spec{ + +Sets the color used to ``erase'' the canvas content before +@method[canvas<%> on-paint] is called. (This color is typically associated with the canvas at a + low level, so that it is used even when a complete refresh of the + canvas is delayed by other activity.) + +If the canvas was created with the @indexed-scheme['transparent] style, + @|MismatchExn|}. + +} +@impl{ + +Sets the canvas's background. + + + +}} + +@defmethod[(get-canvas-background) + (or/c (is-a/c color%) false/c)]{ +@spec{ + +Returns the color currently used to ``erase'' the canvas content before +@method[canvas<%> on-paint] is called. See also +@method[canvas<%> set-canvas-background]. + +The result is @scheme[#f] if the canvas was created with the + @indexed-scheme['transparent] style, otherwise it is always a + @scheme[color%] object. + +}} + +@defmethod[(set-resize-corner [on? any/c]) + void?]{ +@spec{ + +Under Mac OS X, enables or disables space for a resize tab at the + canvas's lower-right corner when only one scrollbar is visible. This + method has no effect under Windows or X, and it has no effect when + both or no scrollbars are visible. The resize corner is disabled by + default, but it can be enabled when a canvas is created with the + @scheme['resize-corner] style. + +} +@impl{ + + + +}}} + diff --git a/collects/scribblings/gui/check-box-class.scrbl b/collects/scribblings/gui/check-box-class.scrbl new file mode 100644 index 0000000000..267be9b731 --- /dev/null +++ b/collects/scribblings/gui/check-box-class.scrbl @@ -0,0 +1,92 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[check-box% object% (control<%>)]{ + +A check box is a labeled box which is either checked or unchecked. + +Whenever a check box is clicked by the user, the check box's value is + toggled and its callback procedure is invoked. A callback procedure + is provided as an initialization argument when each check box is + created. + + + + +@defconstructor[[label {\labelstring} or @scheme[bitmap%] object] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [callback procedure of two arguments: a @scheme[check-box%] object and a @scheme[control-event%] object @scheme[(\scmk{lambda] (@scheme[c] @scheme[e]) (void))}] + [style (symbols/c deleted) null] + [value any/c #f] + [font (is-a/c font%) @scheme[normal-control-font]] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 2] + [horiz-margin (integer-in 0 1000) 2] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #f] + [stretchable-height any/c #f]]{ + +Creates a check box with a string or bitmap label. @bitmaplabeluse[label] + +@labelstripped[(scheme label) @elem{ (when @scheme[label] is a string)} @elem{effectively click the check box}] + +The @scheme[callback] procedure is called (with the event type + @indexed-scheme['check-box]) whenever the user clicks the check box. + +\DeletedStyleNote{check box} + +If @scheme[value] is true, it is passed to +@method[check-box% set-value] so that the box is initially checked. + +@FontKWs[] @WindowKWs[] @SubareaKWs[] @AreaKWs[] + + + +} + +@defmethod[(get-value) + boolean?]{ +@spec{ + +Gets the state of the check box: @scheme[#t] if it is checked, @scheme[#f] + otherwise. + +}} + +@defmethod[#:mode 'add + (set-label [label (is-a/c bitmap%)]) + void?]{ +@spec{ + +Sets the bitmap label for a bitmap check box. + +} +@impl{ + +@bitmaplabeluseisbm[label] @|bitmapiforiglabel| + + + +}} + +@defmethod[(set-value [state any/c]) + void?]{ +@spec{ + +Sets the check box's state. (The control's callback procedure is {\em +not} invoked.) + +@MonitorCallback[@elem{The check box's state} @elem{the user clicking the control} @elem{state}] + +} +@impl{ + +If @scheme[state] is @scheme[#f], the box is + unchecked, otherwise it is checked. + + + + +}}} + diff --git a/collects/scribblings/gui/checkable-menu-item-class.scrbl b/collects/scribblings/gui/checkable-menu-item-class.scrbl new file mode 100644 index 0000000000..1ba0c201d6 --- /dev/null +++ b/collects/scribblings/gui/checkable-menu-item-class.scrbl @@ -0,0 +1,74 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[checkable-menu-item% object% (selectable-menu-item<%>)]{ + +A @scheme[checkable-menu-item%] is a string-labelled menu item that + maintains a check mark. Its parent must be a @scheme[menu%] or + @scheme[popup-menu%]. When the user selects the menu item, the + item's check mark is toggled and its callback procedure is called. + + + + +@defconstructor[[label label-string?] + [parent @scheme[menu%] or @scheme[popup-menu%] object] + [callback procedure of two arguments: a @scheme[menu-item%] object and a @scheme[control-event%] object] + [shortcut (or/c character false/c) #f] + [help-string (or/c label-string? false/c) #f] + [demand-callback procedure of one argument: a @scheme[checkable-menu-item%] object @scheme[void]] + [checked any/c #f] + [shortcut-prefix (symbols/c option shift ctl meta cmd alt) @scheme[(\iscmprocedure{get-default-shortcut-prefix])}]]{ + +Creates a new menu item in @scheme[parent]. The item is initially shown, + appended to the end of its parent, and unchecked. The @scheme[callback] + procedure is called (with the event type @indexed-scheme['menu]) when the + menu item is selected (either via a menu bar, +@xmethod[window<%> popup-menu], or +@xmethod[editor-admin% popup-menu]). + +See +@method[labelled-menu-item<%> set-label] for information about mnemonic ampersands (``\&'') in @scheme[label]. + +If @scheme[shortcut] is not @scheme[#f], the item has a shortcut. See +@method[selectable-menu-item<%> get-shortcut] for more information. The @scheme[shortcut-prefix] argument determines the +set of modifier keys for the shortcut; see +@method[selectable-menu-item<%> get-shortcut-prefix]. + +If @scheme[help] is not @scheme[#f], the item has a help string. See +@method[labelled-menu-item<%> get-help-string] for more information. + +The @scheme[demand-callback] procedure is called by the default +@method[labelled-menu-item<%> on-demand] method with the object itself. + +By default, the menu item is initially unchecked. If @scheme[checked] is + true, then +@method[checkable-menu-item% check] is called so that the menu item is initially checked. + + + +} + +@defmethod[(check [check? any/c]) + void?]{ +@spec{ + +Checks or unchecks the menu item. + +@MonitorCallbackX[@elem{A menu item's check state} @elem{the user selecting the item} @elem{check state} @elem{menu item}] + +}} + +@defmethod[(is-checked?) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the item is checked, {\#f} otherwise. + +} +@impl{ + + + +}}} + diff --git a/collects/scribblings/gui/choice-class.scrbl b/collects/scribblings/gui/choice-class.scrbl new file mode 100644 index 0000000000..d6be2ec5c0 --- /dev/null +++ b/collects/scribblings/gui/choice-class.scrbl @@ -0,0 +1,65 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[choice% object% (list-control<%>)]{ + +A choice item allows the user to select one string item from a pop-up + list of items. Unlike a list box, only the currently selection is + visible until the user pops-up the menu of choices. + +Whenever the selection of a choice item is changed by the user, the + choice item's callback procedure is invoked. A callback procedure is + provided as an initialization argument when each choice item is + created. + +See also +@scheme[list-box%]. + + + + + +@defconstructor[[label (or/c label-string? false/c)] + [choices list of {\labelstrings}] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [callback procedure of two arguments: a @scheme[choice%] object and a @scheme[control-event%] object @scheme[(\scmk{lambda] (@scheme[c] @scheme[e]) (void))}] + [style (symbols/c deleted horizontal-label vertical-label) null] + [selection nonnegative-exact-integer? 0] + [font (is-a/c font%) @scheme[normal-control-font]] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 2] + [horiz-margin (integer-in 0 1000) 2] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #f] + [stretchable-height any/c #f]]{ + +Creates a choice item. If @scheme[label] is a string, it is used as the + label for the choice item. + +@labelstripped[(scheme label) @elem{} @elem{move the keyboard focus to the choice item}] + +The @scheme[choices] list specifies the initial list of user-selectable + items for the control. The initial set of choices determines the + control's minimum graphical width (see @|geomdiscuss| for more + information). + +The @scheme[callback] procedure is called (with the event type + @indexed-scheme['choice]) when the user selects a choice item (or + re-selects the currently selected item). + +\HVLabelNote{choice item} \DeletedStyleNote{choice item} + +By default, the first choice (if any) is initially selected. If + @scheme[selection] is positive, it is passed to +@method[list-control<%> set-selection] to set the initial choice selection. Although @scheme[selection] normally + must be less than the length of @scheme[choices], it can be @scheme[0] + when @scheme[choices] is empty. + +@FontKWs[] @WindowKWs[] @SubareaKWs[] @AreaKWs[] + + + + +}} + diff --git a/collects/scribblings/gui/clipboard-client-class.scrbl b/collects/scribblings/gui/clipboard-client-class.scrbl new file mode 100644 index 0000000000..3af8376804 --- /dev/null +++ b/collects/scribblings/gui/clipboard-client-class.scrbl @@ -0,0 +1,86 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[clipboard-client% object% ()]{ + +A @scheme[clipboard-client%] object allows a program to take over + the clipboard and service requests for clipboard data. See + @scheme[clipboard<%>] for more information. + +A @scheme[clipboard-client%] object is associated to an eventspace + when it becomes the current client; see +@method[clipboard<%> set-clipboard-client] for more information. + + + + + +@defconstructor[]{ + +Creates a clipboard client that supports no data formats. + + + +} + +@defmethod[(add-type [format string]) + void?]{ +@spec{ + +Adds a new data format name to the list supported by the clipboard + client. + +} +@impl{ + +{\clipboardtypes} + + + +}} + +@defmethod[(get-types) + list of strings]{ +@spec{ + +Returns a list of names that are the data formats supported by the + clipboard client. + +}} + +@defmethod[(on-replaced) + void?]{ +@spec{ + +Called when a clipboard client is dismissed as the clipboard owner + (because the clipboard has be taken by another client or by an + external application). + +}} + +@defmethod[(get-data [format string]) + (or/c byte string false/c)]{ +@spec{ + +Called when a process requests clipboard data while this client is the + current one for the clipboard. The requested format is passed to the + method, and the result should be a byte string matching the requested + format, or @scheme[#f] if the request cannot be fulfilled. + +Only data format names in the client's list will be passed to this + method; see +@method[clipboard-client% add-type]. + +When this method is called by the clipboard, the current eventspace is + the same as the client's eventspace. If, at the point of the + clipboard request, the current eventspace is not the client's + eventspace, then current thread is guaranteed to be the handler + thread of the client's eventspace. + +} +@impl{ + +{\clipboardtypes} + +}}} + diff --git a/collects/scribblings/gui/clipboard-intf.scrbl b/collects/scribblings/gui/clipboard-intf.scrbl new file mode 100644 index 0000000000..75c061815e --- /dev/null +++ b/collects/scribblings/gui/clipboard-intf.scrbl @@ -0,0 +1,161 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@definterface[clipboard<%> ()]{ + +A single @scheme[clipboard<%>] object, @indexed-scheme[the-clipboard], + manages the content of the system-wide clipboard for cut and paste. + +Under X, a second @scheme[clipboard<%>] object, + @indexed-scheme[the-x-selection-clipboard], manages the content of the + system-wide X selection. If the @ResourceFirst{selectionAsClipboard} + preference (see @|mrprefsdiscuss|) is set to a non-zero true value, + however, then @scheme[the-clipboard] is always the same as + @scheme[the-x-selection-clipboard], and the system-wide X clipboard + is not used. + +Under Windows and Mac OS X, @scheme[the-x-selection-clipboard] is + always the same as @scheme[the-clipboard]. + +Data can be entered into a clipboard in one of two ways: by setting + the current clipboard string or byte string, or by installing a + @scheme[clipboard-client%] object. When a client is installed, + requests for clipboard data are directed to the client. + +Generic data is always retrieved from the clipboard as a byte + string. When retrieving clipboard data, a data type string specifies + the format of the data string. The availability of different + clipboard formats is determined by the current clipboard owner. + + + + +@defmethod[(set-clipboard-client [new-owner (is-a/c clipboard-client%)] + [time (and/c exact? integer?)]) + void?]{ +@spec{ + +Changes the clipboard-owning client. + +} +@impl{ + +Sets the client to @scheme[new-owner] and associates @scheme[new-owner] with + the current eventspace (as determined by +@scheme[current-eventspace]). The eventspace association is removed when the client is no longer + the current one. + +See @|timediscuss| for a discussion of the @scheme[time] argument. If + @scheme[time] is outside the platform-specific range of times, + @|MismatchExn|}. + + +}} + +@defmethod[(set-clipboard-string [new-text string] + [time (and/c exact? integer?)]) + void?]{ +@spec{ + +Changes the current clipboard contents to a text string + and releases the current clipboard client (if any). + +} +@impl{ + +Sets the clipboard contents to @scheme[new-text]. See @|timediscuss| for + a discussion of the @scheme[time] argument. If @scheme[time] is outside + the platform-specific range of times, @|MismatchExn|}. + + + +}} + +@defmethod[(set-clipboard-bitmap [new-bitmap (is-a/c bitmap%)] + [time (and/c exact? integer?)]) + void?]{ +@spec{ + +Changes the current clipboard contents to a bitmap (Windows, Mac OS X) + and releases the current clipboard client (if any). + +} +@impl{ + +Sets the clipboard contents to @scheme[new-bitmap]. See @|timediscuss| for + a discussion of the @scheme[time] argument. If @scheme[time] is outside + the platform-specific range of times, @|MismatchExn|}. + + + +}} + +@defmethod[(get-clipboard-string [time (and/c exact? integer?)]) + (or/c string false/c)]{ +@spec{ + +Gets the current clipboard contents as simple text, returning + @scheme[#f] if the clipboard does not contain any text. + +See +@method[clipboard<%> get-clipboard-data] for information on eventspaces and the current clipboard client. + +} +@impl{ + +See @|timediscuss| for a discussion of the @scheme[time] argument. If + @scheme[time] is outside the platform-specific range of times, + @|MismatchExn|}. + + +}} + +@defmethod[(get-clipboard-bitmap [time (and/c exact? integer?)]) + (or/c (is-a/c bitmap%) false/c)]{ +@spec{ + +Gets the current clipboard contents as a bitmap (Windows, Mac OS X), + returning @scheme[#f] if the clipboard does not contain a bitmap. + +See +@method[clipboard<%> get-clipboard-data] for information on eventspaces and the current clipboard client. + +} +@impl{ + +See @|timediscuss| for a discussion of the @scheme[time] argument. If + @scheme[time] is outside the platform-specific range of times, + @|MismatchExn|}. + + + +}} + +@defmethod[(get-clipboard-data [format string] + [time (and/c exact? integer?)]) + (or/c byte string false/c)]{ +@spec{ + +Gets the current clipboard contents in a specific format, returning + @scheme[#f] if the clipboard does not contain data in the requested + format. + +If the clipboard client is associated to an eventspace that is not the + current one, the data is retrieved through a callback event in the + client's eventspace. If no result is available within one second, the + request is abandoned and @scheme[#f] is returned. + +} +@impl{ + +{\clipboardtypes} + +See @|timediscuss| for a discussion of the @scheme[time] argument. If + @scheme[time] is outside the platform-specific range of times, + @|MismatchExn|}. + + + + +}}} + diff --git a/collects/scribblings/gui/combo-field-class.scrbl b/collects/scribblings/gui/combo-field-class.scrbl new file mode 100644 index 0000000000..6b16b4a490 --- /dev/null +++ b/collects/scribblings/gui/combo-field-class.scrbl @@ -0,0 +1,105 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[combo-field% text-field% ()]{ + +A @scheme[combo-field%] object is a @scheme[text-field%] + object that also resembles a @scheme[choice%] object, because it + has a small popup button to the right of the text field. By default, + clicking the button pops up a menu, and selecting a menu item copies + the item into the text field. + + + + +@defconstructor[[label (or/c label-string? false/c)] + [choices list of {\labelstrings}] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [callback procedure of two arguments: a @scheme[combo-field%] object and a @scheme[control-event%] object @scheme[(\scmk{lambda] (@scheme[cf] @scheme[e]) (void))}] + [init-value string ""] + [style (symbols/c deleted horizontal-label vertical-label) null] + [font (is-a/c font%) @scheme[normal-control-font]] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 2] + [horiz-margin (integer-in 0 1000) 2] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #t] + [stretchable-height any/c #f]]{ + +If @scheme[label] is not @scheme[#f], it is used as the combo label. + Otherwise, the combo does not display its label. + +@labelstripped[(scheme label) @elem{} @elem{move the keyboard focus to the combo}] + +The @scheme[choices] list specifies the initial list of items for the + combo's popup menu. The +@method[combo-field% append] method adds a new item to the menu with a callback to install the + appended item into the combo's text field. The +@method[combo-field% get-menu] method returns the combo's menu to allow arbitrary other operations. + This menu might not be used at all if +@method[combo-field% on-popup] is overridden. + +The @scheme[callback] procedure is called when the user changes the text + in the combo or presses the Enter key (and Enter is not handled by + the combo's frame or dialog; see +@xmethod[top-level-window<%> on-traverse-char] ). If the user presses Enter, the type of event passed to the callback + is @indexed-scheme['text-field-enter], otherwise it is + @indexed-scheme['text-field]. + +If @scheme[init-value] is not @scheme[""], the minimum width of the text item + is made wide enough to show @scheme[init-value]. Otherwise, a built-in + default width is selected. + +\HVLabelNote{combo} \DeletedStyleNote{combo}. + +@FontKWs[] @WindowKWs[] @SubareaKWs[] @AreaKWs[] + + + +} + +@defmethod[(get-menu) + (is-a/c popup-menu%)]{ +@spec{ + +Returns the @scheme[popup-menu%] that is used by the default +@method[combo-field% on-popup] method. This menu is initialized with the @scheme[labels] argument when + the @scheme[combo-field%] is created, and the +@method[combo-field% append] method adds a new item to the menu. + +}} + +@defmethod[(on-popup [event (is-a/c control-event%)]) + void?]{ +@spec{ + +Called when the user clicks the combo's popup button. + +} +@impl{ + +Gets a menu from +@method[combo-field% get-menu], sets its minimum width to match the combo control's width, and + then pops up the menu. + + + +}} + +@defmethod[(append [l label-string?]) + void?]{ +@spec{ + +Adds a new item to the combo's popup menu. The given label is used for + the item's name, and the item's callback installs the label into the + combo's text field. + +} +@impl{ + + + + +}}} + diff --git a/collects/scribblings/gui/common.ss b/collects/scribblings/gui/common.ss new file mode 100644 index 0000000000..c3c00ca54b --- /dev/null +++ b/collects/scribblings/gui/common.ss @@ -0,0 +1,10 @@ + +(module common mzscheme + (require (lib "manual.ss" "scribble") + "blurbs.ss" + (only "../reference/mz.ss" AllUnix exnraise)) + (provide (all-from (lib "manual.ss" "scribble")) + (all-from "blurbs.ss") + (all-from "../reference/mz.ss"))) + + diff --git a/collects/scribblings/gui/control-event-class.scrbl b/collects/scribblings/gui/control-event-class.scrbl new file mode 100644 index 0000000000..1232a17138 --- /dev/null +++ b/collects/scribblings/gui/control-event-class.scrbl @@ -0,0 +1,66 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[control-event% event% ()]{ + +A @scheme[control-event%] object contains information about a + control event. An instance of @scheme[control-event%] is always + provided to a control or menu item callback procedure. + + + + +@defconstructor[[event-type (symbols/c tab-panel menu-popdown-none menu-popdown radio-box slider text-field-enter text-field list-box-dclick list-box choice check-box button)] + [time-stamp (and/c exact? integer?) 0]]{ + +The @scheme[event-type] argument is one of the following: +@itemize{ +@item{@scheme['button] --- for @scheme[button%] clicks} +@item{@scheme['check-box] --- for @scheme[check-box%] toggles} +@item{@scheme['choice] --- for @scheme[choice%] item selections} +@item{@scheme['list-box] --- for @scheme[list-box%] selections and deselections} +@item{@scheme['list-box-dclick] --- for @scheme[list-box%] double-clicks} +@item{@scheme['text-field] --- for @scheme[text-field%] changes} +@item{@scheme['text-field-enter] --- for single-line @scheme[text-field%] Enter event} +@item{@scheme['menu] --- for @scheme[selectable-menu-item<%>] callbacks} +@item{@scheme['slider] --- for @scheme[slider%] changes} +@item{@scheme['radio-box] --- for @scheme[radio-box%] selection changes} +@item{@scheme['menu-popdown] --- for @scheme[popup-menu%] callbacks (item selected)} +@item{@scheme['menu-popdown-none] --- for @scheme[popup-menu%] callbacks (no item selected)} +@item{@scheme['tab-panel] --- for @scheme[tab-panel%] tab changes} +} + +This value is extracted out of a @scheme[control-event%] object with + the +@method[control-event% get-event-type] method. + +See the corresponding @scheme[get-] and @scheme[set-] methods for + information about @scheme[time-stamp]. + + + +} + +@defmethod[(get-event-type) + (symbols/c radio-box slider menu text-field-enter text-field list-box-dclick list-box choice check-box button)]{ +@spec{ + +Returns the type of the control event. See +@scheme[control-event%] for information about each event type symbol. + +}} + +@defmethod[(set-event-type [type (symbols/c radio-box slider menu text-field-enter text-field list-box-dclick list-box choice check-box button)]) + void?]{ +@spec{ + +Sets the type of the event. See +@scheme[control-event%] for information about each event type symbol. + +} +@impl{ + + + +}}} + diff --git a/collects/scribblings/gui/control-intf.scrbl b/collects/scribblings/gui/control-intf.scrbl new file mode 100644 index 0000000000..f56f7c49dd --- /dev/null +++ b/collects/scribblings/gui/control-intf.scrbl @@ -0,0 +1,44 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@definterface[control<%> (subwindow<%>)]{ + +The @scheme[control<%>] interface is implemented by the built-in + control window classes: +@itemize{ +@item{@scheme[message%]} +@item{@scheme[button%]} +@item{@scheme[check-box%]} +@item{@scheme[slider%]} +@item{@scheme[gauge%]} +@item{@scheme[text-field%]} +@item{@scheme[radio-box%]} +@item{@scheme[choice%]} +@item{@scheme[list-box%]} +} + + + +@defmethod[(command [event (is-a/c control-event%)]) + void?]{ +@spec{ + +Calls the control's callback function, passing on the given + @scheme[control-event%] object. + +}} + +@defmethod[(get-font) + (is-a/c font%)]{ +@spec{ + +Returns the font used for the control, which is optionally supplied + when a control is created. + +} +@impl{ + + + +}}} + diff --git a/collects/scribblings/gui/cursor-class.scrbl b/collects/scribblings/gui/cursor-class.scrbl new file mode 100644 index 0000000000..0fb8c4dad0 --- /dev/null +++ b/collects/scribblings/gui/cursor-class.scrbl @@ -0,0 +1,94 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[cursor% object% ()]{ + +A cursor is a small icon that indicates the location of the mouse + pointer. The bitmap image typically indicates the current mode or + meaning of a mouse click at its current location. + +A cursor is assigned to each window (or the window may use its parent's + cursor; see +@method[window<%> set-cursor] for more information), and the pointer image is changed to match the + window's cursor when the pointer is moved over the window. Each + cursor object may be assigned to many windows. + + + + +@defconstructor*/make[([[image (is-a/c bitmap%)] + [mask (is-a/c bitmap%)] + [hot-spot-x (integer-in 0 15) 0] + [hot-spot-y (integer-in 0 15) 0]] + [[id (symbols/c size-nw/se size-ne/sw size-e/w size-n/s blank watch ibeam hand cross bullseye arrow)]])]{ +First case: + + +Creates a cursor using an image bitmap and a mask bitmap. Both + bitmaps must have depth 1 and size 16 by 16 pixels. + +The @scheme[hot-spot-x] and @scheme[hot-spot-y] arguments determine the + focus point of the cursor within the cursor image, relative to its + top-left corner. + +If the cursor is created successfully, +@method[cursor% ok?] returns @scheme[#t], otherwise the cursor object cannot be assigned to a + window. + + + +Second case: + + +Creates a cursor using a stock cursor, specified as one of the following: +@itemize{ + + @item{@scheme['arrow] --- the default cursor} + + @item{@scheme['bullseye] --- concentric circles} + + @item{@scheme['cross] --- a crosshair} + + @item{@scheme['hand] --- an open hand} + + @item{@scheme['ibeam] --- a vertical line, indicating that clicks + control a text-selection caret} + + @item{@scheme['watch] --- a watch or hourglass, indicating that + the user must wait for a computation to complete} + + @item{@scheme['arrow+watch] --- the default cursor with a watch or + hourglass, indicating that some computation is in progress, but the + cursor can still be used} + + @item{@scheme['blank] --- invisible} + + @item{@scheme['size-e/w] --- arrows left and right} + + @item{@scheme['size-n/s] --- arrows up and down} + + @item{@scheme['size-ne/sw] --- arrows up-right and down-left} + + @item{@scheme['size-nw/se] --- arrows up-left and down-right} + +} + + + +} + +@defmethod[(ok?) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the cursor is can be assigned to a window, + @scheme[#f] otherwise. + +} +@impl{ + + + + +}}} + diff --git a/collects/scribblings/gui/dialog-class.scrbl b/collects/scribblings/gui/dialog-class.scrbl new file mode 100644 index 0000000000..0fccf5c2a6 --- /dev/null +++ b/collects/scribblings/gui/dialog-class.scrbl @@ -0,0 +1,117 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[dialog% object% (top-level-window<%>)]{ + +A dialog is a top-level window that is @defterm{modal}: while the + dialog is shown, all other top-level windows in the dialog's + eventspace are disabled. + + + + +@defconstructor[[label label-string?] + [parent (or/c @scheme[frame%] or @scheme[dialog%] object false/c) #f] + [width (or/c (integer-in 0 10000) false/c) #f] + [height (or/c (integer-in 0 10000) false/c) #f] + [x (or/c (integer-in 0 10000) false/c) #f] + [y (or/c (integer-in 0 10000) false/c) #f] + [style (symbols/c no-sheet resize-border no-caption) null] + [enabled any/c #t] + [border (integer-in 0 1000) 0] + [spacing (integer-in 0 1000) 0] + [alignment two-element list: @scheme['left], @scheme['center], or @scheme['right] and @scheme['top], @scheme['center], or @scheme['bottom] '(center top)] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #t] + [stretchable-height any/c #t]]{ + +The @scheme[label] string is used as the dialog's title in its title bar. + If the dialog's label is changed (see +@method[window<%> set-label] ), the title bar is updated. + +The @scheme[parent] argument can be @scheme[#f] or an existing frame. Under + Windows, if @scheme[parent] is an existing frame, the new dialog is + always on top of its parent. Under Windows and X, a dialog is + iconized when its parent is iconized. + +If @scheme[parent] is @scheme[#f], then the eventspace for the new dialog is + the current eventspace, as determined by +@scheme[current-eventspace] . Otherwise, @scheme[parent]'s eventspace is the new dialog's eventspace. + +If the @scheme[width] or @scheme[height] argument is not @scheme[#f], it + specifies an initial size for the dialog (in pixels) assuming that it + is larger than the minimum size, otherwise the minimum size is + used. Under Windows and Mac OS X (and with some X window + managers) dialogs are not resizeable. + +If the @scheme[x] or @scheme[y] argument is not @scheme[#f], it specifies an + initial location for the dialog. Otherwise, if no location is set + before the dialog is shown, it is centered (with respect @scheme[parent] + if not @scheme[#f], the screen otherwise). + +The @scheme[style] flags adjust the appearance of the dialog on some + platforms: +@itemize{ + + @item{@scheme['no-caption] --- omits the title bar for the dialog + (Windows)} + + @item{@scheme['resize-border] --- adds a resizeable border + around the window (Windows) or grow box in the bottom right corner + (Mac OS X)} + + @item{@scheme['no-sheet] --- uses a movable window for the dialog, + even if a parent window is provided (Mac OS X)} + +} + +Even if the dialog is not shown, a few notification events may be + queued for the dialog on creation. Consequently, the new dialog's + resources (e.g., memory) cannot be reclaimed until some events are + handled, or the dialog's eventspace is shut down. + +@WindowKWs[] @AreaContKWs[] @AreaKWs[] + + + +} + +@defmethod[#:mode 'auto-super + (show [show? any/c]) + void?]{ +@impl{ + +If @scheme[show?]\ is true, the dialog is shown and all frames (and other + dialogs) in the eventspace become disabled until the dialog is + closed. If @scheme[show?]\ is false, the dialog is hidden and other + frames and dialogs are re-enabled (unless a different, pre-existing + dialog is still shown). + +If @scheme[show?]\ is true, the method does not immediately return. Instead, + it loops with @scheme[yield] until the dialog is found to be hidden + between calls to @scheme[yield]. An internal semaphore is used with + @scheme[yield] to avoid a busy-wait, and to ensure that the @scheme[show] + method returns as soon as possible after the dialog is hidden. + + + +}} + +@defmethod[#:mode 'override + (on-subwindow-char [receiver (is-a/c window<%>)] + [event (is-a/c key-event%)]) + boolean?]{ +@impl{ + +Returns the result of +\scmline{(or (send @scheme[this] +@method[top-level-window<%> on-system-menu-char] @scheme[event]) \\ +\>(send @scheme[this] +@method[top-level-window<%> on-traverse-char] @scheme[event]))} + + + + +}}} + diff --git a/collects/scribblings/gui/dialog-funcs.scrbl b/collects/scribblings/gui/dialog-funcs.scrbl new file mode 100644 index 0000000000..59f782fe64 --- /dev/null +++ b/collects/scribblings/gui/dialog-funcs.scrbl @@ -0,0 +1,504 @@ +#reader(lib "docreader.ss" "scribble") +@require["common.ss"] + +@title{Dialogs} + + +These functions get input from the user and/or display + messages. + + + +@defproc[(get-file [message (or/c string false/c) #f] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) false/c) #f] + [directory (or/c path false/c) #f] + [filename (or/c path false/c) #f] + [extension (or/c string false/c) #f] + [style (listof (symbols/c enter-packages packages)) null] + [filters (listof (list/c string? string?)) @scheme['(("Any" "*.*"))]]) + (or/c path false/c)]{ + +Obtains a file pathname from the user via the platform-specific + standard (modal) dialog, using @scheme[parent] as the parent window if + it is specified, and using @scheme[message] as a message at the top of + the dialog if it is not @scheme[#f]. + +The result is @scheme[#f] if the user cancels the dialog, the selected + pathname otherwise. The returned pathname may or may not exist, + although the style of the dialog is directed towards selecting + existing files. + +If @scheme[directory] is not @scheme[#f], it is used as the starting + directory for the file selector (otherwise the starting directory is + chosen automatically in a platform-specific manner, usually based on + the current directory and the user's interactions in previous calls + to @scheme[get-file], @scheme[put-file], etc.). If + @scheme[filename] is not @scheme[#f], it is used as the default filename + when appropriate, and it should @italic{not} contain a directory path + prefix. + +Under Windows, if @scheme[extension] is not @scheme[#f], the returned path + will use the extension if the user does not supply one; the + @scheme[extension] string should not contain a period. The extension is + ignored on other platforms. + +The @scheme[style] list can contain @scheme['common], a + platform-independant version of the dialog is used instead of a + native dialog. Under Mac OS X, if the @scheme[style] list + contains @scheme['packages], a user is allowed to select a package + directory, which is a directory with a special suffix (e.g., + ``.app'') that the Finder normally displays like a file. If the list + contains @scheme['enter-packages], a user is allowed to select a file + within a package directory. If the list contains both + @scheme['packages] and @scheme['enter-packages], the former is ignored. + +Under Windows and X, @scheme[filters] determines a set of filters from + which the user can choose in the dialog. Each element of the + @scheme[filters] list contains two strings: a description of the filter + as seen by the user, and a filter pattern matched against file names. + +See also @scheme[path-dialog%]. + + +} + +@defproc[(get-file-list [message (or/c string false/c) #f] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) false/c) #f] + [directory (or/c path false/c) #f] + [filename (or/c path false/c) #f] + [extension (or/c string false/c) #f] + [style null? null] + [filters (listof (list/c string? string?)) @scheme['(("Any" "*.*"))]]) + (or/c list of paths false/c)]{ +Like +@scheme[get-file], except that the user can select multiple files, and the + result is either a list of file paths of @scheme[#f]. + +} + +@defproc[(put-file [message (or/c string false/c) #f] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) false/c) #f] + [directory (or/c path false/c) #f] + [filename (or/c path false/c) #f] + [extension (or/c string false/c) #f] + [style (listof (symbols/c enter-packages packages)) null] + [filters (listof (list/c string? string?)) @scheme['(("Any" "*.*"))]]) + (or/c path false/c)]{ + +Obtains a file pathname from the user via the platform-specific + standard (modal) dialog, using @scheme[parent] as the parent window if + it is specified, and using @scheme[message] as a message at the top of + the dialog if it is not @scheme[#f]. + +The result is @scheme[#f] if the user cancels the dialog, the selected + pathname otherwise. The returned pathname may or may not exist, + although the style of the dialog is directed towards creating a new + file. + +If @scheme[directory] is not @scheme[#f], it is used as the starting + directory for the file selector (otherwise the starting directory is + chosen automatically in a platform-specific manner, usually based on + the current directory and the user's interactions in previous calls + to @scheme[get-file], @scheme[put-file], etc.). If + @scheme[filename] is not @scheme[#f], it is used as the default filename + when appropriate, and it should @italic{not} contain a directory path + prefix. + +Under Windows, if @scheme[extension] is not @scheme[#f], the returned path + will gets a default extension if the user does not supply one. If + @scheme[extension] is the empty string, then the extension is derived + from the user's @scheme[filters] choice if the corresponding pattern is + of the form @scheme[(string-append "*." extension)]; if the pattern is + @scheme["*.*"], then no default extension is added. Finally, if + @scheme[extension] is any string other than the empty string, + @scheme[extension] is used as the default extension when the user's + @scheme[filters] choice has the pattern @scheme["*.*"]. Meanwhile, the + @scheme[filters] argument has the same format and auxiliary role as for +@scheme[get-file]. In particular, if the only pattern in @scheme[filters] + is @scheme[(string-append "*." extension)], then the result pathname is guaranteed + to have an extenson mapping @scheme[extension]. + +Under Mac OS X, if @scheme[extension] is not @scheme[#f] + and @scheme[filters] contains the single + pattern @scheme[(string-append "*." extension)], then the result pathname is + guaranteed to have an extenson mapping @scheme[extension]. Otherwise, + @scheme[extension] and @scheme[filters] are ignored. + +The @scheme[extension] argument is ignored under X, and @scheme[filters] + can be used to specify glob-patterns. + +The @scheme[style] list is treated as for +@scheme[get-file]. + +See also @scheme[path-dialog%]. + + + +} + +@defproc[(get-directory [message (or/c string false/c) #f] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) false/c) #f] + [directory (or/c path false/c) #f] + [style (listof (symbols/c enter-packages)) null]) + (or/c path false/c)]{ + +Obtains a directory pathname from the user via the platform-specific + standard (modal) dialog, using @scheme[parent] as the parent window if + it is specified. + +If @scheme[directory] is not @scheme[#f], it is used on some platforms as + the starting directory for the directory selector (otherwise the + starting directory is chosen automatically in a platform-specific + manner, usually based on the current directory and the user's + interactions in previous calls to @scheme[get-file], + @scheme[put-file], etc.). + +The @scheme[style] argument is treated as for +@scheme[get-file], except that only @scheme['common] or @scheme['enter-packages] can be +specified. The latter + matters only under Mac OS X, where @scheme['enter-packages] + enables the user to select package directory or a directory within a + package. A package is a directory with a special suffix (e.g., + ``.app'') that the Finder normally displays like a file. + +See also @scheme[path-dialog%]. + + +} + +@defproc[(message-box [title label-string?] + [message string] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) false/c) #f] + [style (listof (symbols/c stop caution yes-no ok-cancel ok)) '(ok)]) + (symbols/c no yes cancel ok)]{ +See also @scheme[message-box/custom]. + + + +Displays a message to the user in a (modal) dialog, using + @scheme[parent] as the parent window if it is specified. The dialog's + title is @scheme[title]. The @scheme[message] string can be arbitrarily + long, and can contain explicit linefeeds or carriage returns for + breaking lines. + +The style must include exactly one of the following: +@itemize{ + + @item{@scheme['ok] --- the dialog only has an ``OK'' button and always + returns @scheme['ok].} + + @item{@scheme['ok-cancel] --- the message dialog has ``Cancel'' and + ``OK'' buttons. If the user clicks ``Cancel'', the result is + @scheme['cancel], otherwise the result is @scheme['ok].} + + @item{@scheme['yes-no] --- the message dialog has ``Yes'' and ``No'' + buttons. If the user clicks ``Yes'', the result is @scheme['yes], + otherwise the result is @scheme['no]. Note: instead of a + ``Yes''/``No'' dialog, best-practice GUI design is to use + @scheme[message-box/custom] and give the buttons meaningful + labels, so that the user does not have to read the message text + carefully to make a selection.} + +} + +In addition, @scheme[style] can contain @scheme['caution] to make the + dialog use a caution icon instead of the application (or generic + ``info'') icon. Alternately, it can contain @scheme['stop] to make the + dialog use a stop icon. If @scheme[style] contains both @scheme['caution] + and @scheme['stop], then @scheme['caution] is ignored. + +The class that implements the dialog provides a @scheme[get-message] + method that takes no arguments and returns the text of the message as + a string. (The dialog is accessible through the +@scheme[get-top-level-windows] function.) + + + + +} + +@defproc[(message-box/custom [title label-string?] + [message string] + [button1-label (or/c label-string? (is-a/c bitmap%) false/c)] + [button2-label (or/c label-string? (is-a/c bitmap%) false/c)] + [button3-label (or/c label-string? (is-a/c bitmap%) false/c)] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) false/c) #f] + [style (listof (symbols/c stop caution number-order + disallow-close no-default + default=3 default=2 default=1)) + '(no-default)] + [close-result any/c #f]) + (one-of/c 1 2 3 close-result)]{ + +Displays a message to the user in a (modal) dialog, using + @scheme[parent] as the parent window if it is specified. The dialog's + title is @scheme[title]. The @scheme[message] string can be arbitrarily + long, and can contain explicit linefeeds or carriage returns for + breaking lines. + +The dialog contains up to three buttons for the user to click. The + buttons have the labels @scheme[button1-label], + @scheme[button2-label], and @scheme[button3-label], where @scheme[#f] for a + label indicates that the button should be hidden. + +If the user clicks the button labelled @scheme[button1-label], a @scheme[1] + is returned, and so on for @scheme[2] and @scheme[3]. If the user closes + the dialog some other way---which is only allowed when @scheme[style] + does not contain @scheme['disallow-close]---then the result is the + value of @scheme[close-result]. For example, the user can usually close + a dialog by typing an Escape. Often, @scheme[2] is an appropriate value + for @scheme[close-result], especially when Button 2 is a ``Cancel'' + button. + +If @scheme[style] does not include @scheme['number-order], the order of + the buttons is platform-specific, and labels should be assigned to + the buttons based on their role: +@itemize{ + + @item{Button 1 is the normal action, and it is usually the default + button. For example, if the dialog has an ``OK'' button, it is this + one. Under Windows and X, this button is leftmost; under + Mac OS X, it is rightmost. Use this button for dialogs that + contain only one button.} + + @item{Button 2 is next to Button 1, and it often plays the role of + ``Cancel'' (even when the default action is to cancel, such as when + confirming a file replacement).} + + @item{Button 3 tends to be separated from the other two (under + Mac OS X, it is left-aligned in the dialog). Use this button only + for three-button dialogs.} + +} +Despite the above guidelines, any combination of visible buttons is + allowed in the dialog. + +If @scheme[style] includes @scheme['number-order], then the buttons are + displayed in the dialog left-to-right with equal spacing between all + buttons, though aligned within the dialog (centered or right-aligned) + in a platform-specific manner. Use @scheme['number-order] sparingly. + +The @scheme[style] list must contain exactly one of @scheme['default=1], + @scheme['default=2], @scheme['default=3], and @scheme['no-default] to + determine which button (if any) is the default. The default button is + ``clicked'' when the user types Return. If @scheme['default=]@scheme[n] + is supplied but button @scheme[n] has no label, then it is equivalent to + @scheme['no-default]. + +In addition, @scheme[style] can contain @scheme['caution] to make the + dialog use a caution icon instead of the application (or generic + ``info'') icon. Alternately, it can contain @scheme['stop] to make the + dialog use a stop icon. If @scheme[style] contains both @scheme['caution] + and @scheme['stop], then @scheme['caution] is ignored. + +The class that implements the dialog provides a @scheme[get-message] + method that takes no arguments and returns the text of the message as + a string. (The dialog is accessible through the +@scheme[get-top-level-windows] function.) + + + +} + +@defproc[(message+check-box [title label-string?] + [message string] + [check-label label-string?] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) false/c) #f] + [style (listof (symbols/c checked stop caution yes-no ok-cancel ok)) '(ok)]) + (symbols/c no yes cancel ok)]{ + +See also @scheme[message+check-box/custom]. + +Like @scheme[message-box], except that + +@itemize{ + @item{the dialog contains a check box whose label is @scheme[check-label];} + @item{the result is two values: the @scheme[message-box] result, and a + boolean indicating whether the box was checked; and} + @item{@scheme[style] can contain @scheme['checked] to indicate that the check box + should be initially checked.} +}} + +@defproc[(message+check-box/custom [title label-string?] + [message string] + [check-label label-string?] + [button1-label (or/c label-string? (is-a/c bitmap%) false/c)] + [button2-label (or/c label-string? (is-a/c bitmap%) false/c)] + [button3-label (or/c label-string? (is-a/c bitmap%) false/c)] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) false/c) #f] + [style (listof (symbols/c checked stop caution number-order + disallow-close no-default + default=3 default=2 default=1)) + '(no-default)] + [close-result any/c #f]) + (one-of/c 1 2 3 close-result)]{ + +Like @scheme[message-box/custom], except that +@itemize{ + @item{the dialog contains a check box whose label is @scheme[check-label];} + @item{the result is two values: the @scheme[message-box] result, and a + boolean indicating whether the box was checked; and} + @item{@scheme[style] can contain @scheme['checked] to indicate that the check box + should be initially checked.} +} + + + + +} + +@defproc[(get-text-from-user [title string] + [message (or/c string false/c)] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) false/c) #f] + [init-val string ""] + [style (listof (symbols/c password)) null]) + (or/c string false/c)]{ + +Gets a text string from the user via a modal dialog, using + @scheme[parent] as the parent window if it is specified. The dialog's + title is @scheme[title]. The dialog's text field is labelled with + @scheme[message] and initialized to @scheme[init-val] (but @scheme[init-val] + does not determine the size of the dialog). + +The result is @scheme[#f] if the user cancels the dialog, the + user-provided string otherwise. + +If @scheme[style] includes @scheme['password], the dialog's text field + draws each character of its content using a generic symbol, instead + of the actual character. + + + +} + +@defproc[(get-choices-from-user [title string] + [message (or/c string false/c)] + [choices (listof string?)] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) false/c) #f] + [init-choices (listof nonnegative-exact-integer?) null] + [style (listof (symbols/c extended multiple single)) '(single)]) + (or/c list of {\NNInts} false/c)]{ + +Gets a list box selection from the user via a modal dialog, using + @scheme[parent] as the parent window if it is specified. The dialog's + title is @scheme[title]. The dialog's list box is labelled with + @scheme[message] and initialized by selecting the items in + @scheme[init-choices]. + +The style must contain exactly one of @indexed-scheme['single], + @indexed-scheme['multiple], or @indexed-scheme['extended]. The styles have + the same meaning as for creating a @scheme[list-box%] object. (For + the single-selection style, only the last selection in + @scheme[init-choices] matters.) + +The result is @scheme[#f] if the user cancels the dialog, the + list of selections otherwise. + + + +} + +@defproc[(get-color-from-user [message (or/c string false/c) #f] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) false/c) #f] + [init-color (or/c (is-a/c color%) false/c) #f] + [style null? null]) + (or/c (is-a/c color%) false/c)]{ + +Lets the user select a color though the platform-specific + (modal) dialog, using @scheme[parent] as the parent window if it is + specified. The @scheme[message] string is displayed as a prompt in the + dialog if possible. If @scheme[init-color] is provided, the dialog is + initialized to the given color. + +@italicptyStyleNote[] + +The result is @scheme[#f] if the user cancels the dialog, the selected + color otherwise. + + + +} + +@defproc[(get-font-from-user [message (or/c string false/c) #f] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) false/c) #f] + [init-font (or/c (is-a/c font%) false/c) #f] + [style null? null]) + (or/c (is-a/c font%) false/c)]{ + +Lets the user select a font though the platform-specific + (modal) dialog, using @scheme[parent] as the parent window if it is + specified. The @scheme[message] string is displayed as a prompt in the + dialog if possible. If @scheme[init-font] is provided, the dialog is + initialized to the given font. + +@italicptyStyleNote[] + +The result is @scheme[#f] if the user cancels the dialog, the selected + font otherwise. + + + +} + +@defproc[(get-ps-setup-from-user [message (or/c string false/c) #f] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) false/c) #f] + [init-setup (or/c (is-a/c ps-setup%) false/c) #f] + [style null? null]) + (or/c (is-a/c ps-setup%) false/c)]{ + +Lets the user select a PostScript configuration though a (modal) + dialog, using @scheme[parent] as the parent window if it is + specified. The @scheme[message] string is displayed as a prompt in the + dialog. If @scheme[init-setup] is provided, the dialog is initialized to + the given configuration, otherwise the current configuration from +@scheme[current-ps-setup] is used. + +@italicptyStyleNote[] + +The result is @scheme[#f] if the user cancels the dialog, , a + @scheme[ps-setup%] object that encapsulates the selected PostScript + configuration otherwise. + + + +} + +@defproc[(get-page-setup-from-user [message (or/c string false/c) #f] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) false/c) #f] + [init-setup (or/c (is-a/c ps-setup%) false/c) #f] + [style null? null]) + (or/c (is-a/c ps-setup%) false/c)]{ + +Like +@scheme[get-ps-setup-from-user], but the dialog configures page layout for native printing + with @scheme[printer-dc%]. A dialog is shown only if +@scheme[can-get-page-setup-from-user?] returns @scheme[#t], otherwise no dialog is shown and the result + is @scheme[#f]. + +The @scheme[parent] argument is used as the parent window for a dialog if + it is specified. The @scheme[message] string might be displayed as a + prompt in the dialog. If @scheme[init-setup] is provided, the dialog is + initialized to the given configuration, otherwise the current + configuration from +@scheme[current-ps-setup] is used. + +@italicptyStyleNote[] + +The result is @scheme[#f] if the user cancels the dialog, a + @scheme[ps-setup%] object that encapsulates the selected + configuration otherwise. + + + +} + +@defproc[(can-get-page-setup-from-user?) + boolean?]{ +Returns @scheme[#t] if the current platform (Mac OS X) supports a + page-layout dialog for use with @scheme[printer-dc%] printing, and + if the page-layout dialog is different from the print-job dialog that + is automatically shown when a @scheme[printer-dc%] is + created. Returns @scheme[#f] if no separate page-layout dialog is + needed (Windows and Unix). + +} \ No newline at end of file diff --git a/collects/scribblings/gui/event-class.scrbl b/collects/scribblings/gui/event-class.scrbl new file mode 100644 index 0000000000..378611fee6 --- /dev/null +++ b/collects/scribblings/gui/event-class.scrbl @@ -0,0 +1,51 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[event% object% ()]{ + +An @scheme[event%] object contains information about a control, +keyboard, mouse, or scroll event. See also +@scheme[control-event%], +@scheme[key-event%], +@scheme[mouse-event%], and +@scheme[scroll-event%]. + + + +@defconstructor[[time-stamp (and/c exact? integer?) 0]]{ + +See the corresponding @scheme[get-] and @scheme[set-] methods for + information about @scheme[time-stamp]. + + + +} + +@defmethod[(get-time-stamp) + (and/c exact? integer?)]{ +@spec{ + +Returns the time, in milliseconds, when the event occurred. This time + is compatible with times reported by MzScheme's + @scheme[current-milliseconds] procedure. + +}} + +@defmethod[(set-time-stamp [time (and/c exact? integer?)]) + void?]{ +@spec{ + +Set the time, in milliseconds, when the event occurred. See also + MzScheme's @scheme[current-milliseconds]. + +If the supplied value is outside the platform-specific range of time + values, @|MismatchExn|}. + +} +@impl{ + + + + +}}} + diff --git a/collects/scribblings/gui/eventspace-funcs.scrbl b/collects/scribblings/gui/eventspace-funcs.scrbl new file mode 100644 index 0000000000..fa2addc3d7 --- /dev/null +++ b/collects/scribblings/gui/eventspace-funcs.scrbl @@ -0,0 +1,237 @@ +#reader(lib "docreader.ss" "scribble") +@require["common.ss"] + +@title{Eventspaces} + + + + + +@defproc[(make-eventspace) + eventspace]{ +Creates and returns a new eventspace value. The new eventspace is + created as a child of the current eventspace. The eventspace is used + by making it the current eventspace with the + @scheme[current-eventspace] parameter. + +See @|eventspacediscuss| for more information about eventspaces. + +} + +@defparam[current-eventspace e eventspace?]{ + +A parameter @|SeeMzParam| that determines the current eventspace. + +See @|eventspacediscuss| for more information about eventspaces. + +} + + +@defproc[(eventspace? [v any/c]) + boolean?]{ + +Returns @scheme[#t] if @scheme[v] is an eventspace value or @scheme[#f] + otherwise. + +See @|eventspacediscuss| for more information about eventspaces. +} + + +@defparam[event-dispatch-handler handler (eventspace? . -> . any)]{ + +A parameter @|SeeMzParam| that determines the current event + dispatch handler. The event dispatch handler is called by an + eventspace's handler thread for every queue-based event to be + processed in the eventspace. The only argument to the handler is the + eventspace in which an event should be dispatched. The event dispatch + handler gives the programmer control over the timing of event + dispatching, but not the order in which events are dispatched within + a single eventspace. + +An event dispatch handler must ultimately call the primitive event + dispatch handler. If an event dispatch handler returns without + calling the primitive handler, then the primitive handler is called + directly by the eventspace handler thread. +} + +@defproc[(check-for-break) + boolean?]{ +Inspects the event queue of the current eventspace, searching for a + Shift-Ctl-C (X, Windows) or Cmd-. (Mac OS X) key combination. Returns + @scheme[#t] if such an event was found (and the event is dequeued) or + @scheme[#f] otherwise. + +} + +@defproc[(get-top-level-windows) + (listof (or/c (is-a/c frame%) (is-a/c dialog%)))]{ +Returns a list of visible top-level frames and dialogs in the current + eventspace. + +} + +@defproc[(get-top-level-focus-window) + (or/c @scheme[frame%] or @scheme[dialog%] object false/c)]{ +Returns the top level window in the current eventspace that has the + keyboard focus (or contains the window with the keyboard focus), or + @scheme[#f] if no window in the current eventspace has the focus. + +} + +@defproc[(get-top-level-edit-target-window) + (or/c @scheme[frame%] or @scheme[dialog%] object false/c)]{ +Returns the top level window in the current eventspace that is visible + and most recently had the keyboard focus (or contains the window that + had the keyboard focus), or @scheme[#f] if there is no visible window + in the current eventspace. + +} + +@defproc*[([(special-control-key [on? any/c]) + void?] + [(special-control-key) + boolean?])]{ + +Enables or disables special Control key handling (Mac OS X). When Control + is treated as a special key, the system's key-mapper is called + without Control for keyboard translations. For some languages, + Control key presses must be seen by the system translation, so this + mode should be turned off, but the default is on. + +If @scheme[on?] is provided and @scheme[#f], Control is passed to the system +translation as normal. This setting affects all windows and +eventspaces. + +If no argument is provided, the result is @scheme[#t] if Control is +currently treated specially, @scheme[#f] otherwise. + +} + +@defproc*[([(special-option-key [on? any/c]) + void?] + [(special-option-key) + boolean?])]{ +Enables or disables special Option key handling (Mac OS X). When + Option is treated as a special key, the system's key-mapper is called + without Option for keyboard translations. By default, Option is not + special. + +If @scheme[on?] is provided @scheme[#f], Option is passed to the + system translation as normal. This setting affects all windows and + eventspaces. + +If no argument is provided, the result is @scheme[#t] if Option is + currently treated specially, @scheme[#f] otherwise. +} + +@defproc[(queue-callback [callback (-> any)] + [high-priority? any/c #t]) + void?]{ +Installs a procedure to be called via the current eventspace's event + queue. The procedure is called once in the same way and under the + same restrictions that a callback is invoked to handle a method. + +A second (optional) boolean argument indicates whether the callback + has a high or low priority in the event queue. See + @|eventspacediscuss| for information about the priority of events. + +} + +@defproc*[([(yield) + boolean?] + [(yield [v (or/c (one-of/c 'wait) evt?)]) + any/c])]{ +\index{pause}\index{wait} +Yields control to event dispatching. See + @secref["mr:eventspaceinfo"] for details. + +A handler procedure invoked by the system during a call to + @scheme[yield] can itself call @scheme[yield], creating + an additional level of nested (but single-threaded) event handling. + +See also +@scheme[sleep/yield] . + +If no argument is provided, @scheme[yield] dispatches an unspecified + number of events, but only if the current thread is the current + eventspace's handler thread (otherwise, there is no effect). The + result is @scheme[#t] if any events may have been handled, + @scheme[#f] otherwise. + +If @scheme[v] is @indexed-scheme['wait], and @scheme[yield] is called + in the handler thread of an eventspace, then @scheme[yield] starts + processing events in that eventspace until + +@itemize{ + + @item{no top-level windows in the eventspace are visible;} + + @item{no timers in the eventspace are running;} + + @item{no callbacks are queued in the eventspace; and} + + @item{no @scheme[menu-bar%] has been created for the eventspace + with @scheme['root] (i.e., creating a @scheme['root] menu bar + prevents an eventspace from ever unblocking).} + +} + +When called in a non-handler thread, @scheme[yield] returns + immediately. In either case, the result is @scheme[#t]. + +Evaluating @scheme[(yield 'wait)] is thus similar to + @scheme[(yield (current-eventspace))], except that it is + sensitive to whether the current thread is a handler thread, instead + of the value of the @scheme[current-eventspace] parameter. + +If @scheme[v] is an event in MzScheme's sense (not to be confused with a + GUI event), @scheme[yield] blocks on @scheme[v] in the same way as + MzScheme's \Mzhyperref{@scheme[sync]}{mz:sync}, except that it may + start a @scheme[sync] on @scheme[v] multiple times (but it will complete + a @scheme[sync] on @scheme[v] at most one time). If the current thread + is the current eventspace's handler thread, events are dispatched + until a @scheme[v] sync succeeds on a MrEd event boundary. For other + threads, calling @scheme[yield] with a MzScheme event is + equivalent to calling @scheme[sync]. In either case, the result is + the same that of @scheme[sync]; however, if a wrapper procedure is + associated with @scheme[v] via @scheme[handle-evt], it is not called in + tail position with respect to the @scheme[yield]. + +Always use @scheme[(yield @scheme[v])] instead of a busy-wait loop. +} + +@defproc[(sleep/yield [secs (and/c real? (not/c negative?))]) + void?]{ +Blocks for at least the specified number of seconds, handling events + meanwhile if the current thread is the current eventspace's handler + thread (otherwise, @scheme[sleep/yield] is equivalent to + @scheme[sleep]). + +} + +@defproc[(eventspace-shutdown? [e eventspace]) + boolean?]{ +Returns @scheme[#t] if the given eventspace has been shut down by its + custodian, @scheme[#f] otherwise. Attempting to create a new window, + timer, or explicitly queued event in a shut-down eventspace raises + the @scheme[exn:misc] exception. + +Attempting to use certain methods of windows and timers in a shut-down + eventspace also raises the @scheme[exn:misc] exception, but the +@xmethod[area<%> get-top-level-window] and +@xmethod[top-level-window<%> get-eventspace] methods work even after the area's eventspace is shut down. + +} + +@defproc[(eventspace-handler-thread [e eventspace]) + (or/c thread false/c)]{ +Returns the handler thread of the given eventspace. If the handler + thread has terminated (e.g., because the eventspace was shut down), the + result is @scheme[#f]. + + + + + + +} \ No newline at end of file diff --git a/collects/scribblings/gui/frame-class.scrbl b/collects/scribblings/gui/frame-class.scrbl new file mode 100644 index 0000000000..260c46817e --- /dev/null +++ b/collects/scribblings/gui/frame-class.scrbl @@ -0,0 +1,340 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[frame% object% (top-level-window<%>)]{ + +A frame is a top-level container window. It has a title bar (which + displays the frame's label), an optional menu bar, and an optional + status line. + +Under Windows, both Multiple Document Interface (MDI) and Single + Document Interface (SDI) frames are supported. + + + + +@defconstructor[[label label-string?] + [parent (or/c (is-a/c frame%) false/c) #f] + [width (or/c (integer-in 0 10000) false/c) #f] + [height (or/c (integer-in 0 10000) false/c) #f] + [x (or/c (integer-in -10000 10000) false/c) #f] + [y (or/c (integer-in -10000 10000) false/c) #f] + [style (symbols/c metal float hide-menu-bar toolbar-button mdi-child mdi-parent no-system-menu no-caption no-resize-border) null] + [enabled any/c #t] + [border (integer-in 0 1000) 0] + [spacing (integer-in 0 1000) 0] + [alignment two-element list: @scheme['left], @scheme['center], or @scheme['right] and @scheme['top], @scheme['center], or @scheme['bottom] '(center top)] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #t] + [stretchable-height any/c #t]]{ + +The @scheme[label] string is displayed in the frame's title bar. If the + frame's label is changed (see +@method[window<%> set-label] ), the title bar is updated. + +The @scheme[parent] argument can be @scheme[#f] or an existing frame. Under + Windows, if @scheme[parent] is an existing frame, the new frame is + always on top of its parent. Also, the @scheme[parent] frame may be an + MDI parent frame from a new MDI child frame. Under Windows and X (for + many window managers), a frame is iconized when its parent is iconized. + +If @scheme[parent] is @scheme[#f], then the eventspace for the new frame is + the current eventspace, as determined by +@scheme[current-eventspace] . Otherwise, @scheme[parent]'s eventspace is the new frame's eventspace. + +If the @scheme[width] or @scheme[height] argument is not @scheme[#f], it + specifies an initial size for the frame (in pixels) assuming that it + is larger than the minimum size, otherwise the minimum size is used. + +If the @scheme[x] or @scheme[y] argument is not @scheme[#f], it specifies an + initial location for the frame. Otherwise, a location is selected + automatically (tiling frames and dialogs as they are created). + +The @scheme[style] flags adjust the appearance of the frame on some + platforms: +@itemize{ + + @item{@scheme['no-resize-border] --- omits the resizeable border + around the window (Windows, X MWM) or grow box in the bottom right + corner (Mac OS X)} + + @item{@scheme['no-caption] --- omits the title bar for the frame + (Windows, X MWM) + + (X Gnome, X KDE: the frame decoration is omitted completely when + @scheme['no-resize-border] and @scheme['no-caption] are combined.)} + + @item{@scheme['no-system-menu] --- omits the system menu + (Windows)} + + @item{@scheme['mdi-child] --- creates the frame as a MDI + (multiple document interface) child frame, mutually exclusive with + @scheme['mdi-parent] (Windows)} + + @item{@scheme['mdi-parent] --- creates the frame as a MDI + (multiple document interface) parent frame, mutually exclusive with + @scheme['mdi-child] (Windows)} + + @item{@scheme['toolbar-button] --- includes a toolbar button on the + frame's title bar (Mac OS X); a click on the toolbar button triggers + a call to +@method[frame% on-toolbar-button-click]} + @item{@scheme['hide-menu-bar] --- hides the menu bar and dock when + the frame is active (Mac OS X)} + + @item{@scheme['float] --- causes the frame to stay in front of all + other non-floating windows (Windows and Mac OS X always, X when + combined with @scheme['no-caption]); under Mac OS X, a floating + frame shares the focus with an active non-floating frame; when this + style is combined with @scheme['no-caption], then showing the frame + does not cause the keyboard focus to shift to the window, and under + X, clicking the frame does not move the focus} + + @item{@scheme['metal] --- draws the frame with a brushed-metal + background (Mac OS X); this style is ignored when + @scheme['no-caption] is specified} + +} +If the @scheme['mdi-child] style is specified, the @scheme[parent] must be + a frame with the @scheme['mdi-parent] style, otherwise @|MismatchExn|}. + +Even if the frame is not shown, a few notification events may be + queued for the frame on creation. Consequently, the new frame's + resources (e.g., memory) cannot be reclaimed until some events are + handled, or the frame's eventspace is shut down. + +@WindowKWs[] @AreaContKWs[] @AreaKWs[] + + + +} + +@defmethod[(create-status-line) + void?]{ +@impl{ + +Creates a status line at the bottom of the frame. The width of the + status line is the whole width of the frame (adjusted automatically + when resizing), and the height and text size are platform-specific. + +See also +@method[frame% set-status-text]. + + + +}} + +@defmethod[(get-menu-bar) + (or/c (is-a/c menu-bar%) false/c)]{ +@spec{ + +Returns the frame's menu bar, or @scheme[#f] if none has been created + for the frame. + +}} + +@defmethod[(set-icon [icon (is-a/c bitmap%)] + [mask (is-a/c bitmap%) #f] + [which (symbols/c both large small) 'both]) + void?]{ +@spec{ + +Sets the large or small icon bitmap for this frame. Future changes to + the bitmap do not affect the frame's icon. + +The icon is used in a platform-specific way: +@itemize{ + + @item{Windows --- the small icon is used for the frame's icon (in the + top-left) and in the task bar, and the large icon is used for + the Atl-Tab task switcher.} + + @item{Mac OS X --- both icons are ignored.} + + @item{X --- many window managers use the small icon in the same way + as Windows, and others use the small icon when iconifying the + frame; the large icon is ignored.} + +} + +The bitmap for either icon can be any size, but most platforms scale + the small bitmap to 16 by 16 pixels and the large bitmap to 32 by 32 + pixels. + +If a mask bitmap is not provided, then the entire (rectangular) bitmap + is used as an icon. + +If a mask bitmap is provided, the mask must be monochrome. In the mask + bitmap, use black pixels to indicate the icon's region and use white + pixels outside the icon's region. In the icon bitmap, use black + pixels for the region outside the icon. + +}} + +@defmethod[(set-status-text [text string]) + void?]{ +@spec{ + +Sets the frame's status line text and redraws the status line. See + also +@method[frame% create-status-line]. + +}} + +@defmethod[(has-status-line?) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the frame's status line has been created, + @scheme[#f] otherwise. See + also +@method[frame% create-status-line]. + +}} + +@defmethod[(iconize [iconize? any/c]) + void?]{ +@spec{ + +Iconizes (\first{minimizes}) or deiconizes (restores) the frame. Deiconizing + brings the frame to the front. + +@Unmonitored[@elem{A frame's iconization} @elem{the user} @elem{a frame has been iconized} @elem{@method[frame% is-iconized?]}] + +}} + +@defmethod[(is-iconized?) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the frame is iconized (minimized), @scheme[#f] otherwise. + +}} + +@defmethod[(maximize [maximize? any/c]) + void?]{ +@spec{ + +Maximizes or restores the frame under Windows and Mac OS X; the + frame's show state is not affected. Under Windows, an iconized frame + cannot be maximized or restored. + +@MonitorMethod[@elem{A window's maximization} @elem{the user} @elem{@method[window<%> on-size]} @elem{size}] + +} +@impl{ + +If @scheme[maximize?] is @scheme[#f], the window is restored, otherwise + it is maximized. + + + +}} + +@defmethod[(is-maximized?) + boolean?]{ +@spec{ + +Under Windows and Mac OS X, returns @scheme[#t] if the frame is maximized, +@scheme[#f] otherwise. Under X, the result is always @scheme[#f]. + +}} + +@defmethod[(on-mdi-activate [active? any/c]) + void?]{ +@spec{ + +Called under Windows when a MDI-child frame becomes the active frame + within its parent (in which case the argument is @scheme[#t]), or when + the child frame ceases to be the active frame (in which case the + argument is @scheme[#f]). + + +MDI activation is different from keyboard-focus activation. If the + parent frame is the frontmost top-level frame, so that the MDI child + gets or loses the keyboard focus, then a separate +@method[top-level-window<%> on-activate] notification is sent to the MDI-child frame. + +}} + +@defmethod[(on-menu-char [event (is-a/c key-event%)]) + boolean?]{ +@spec{ + +If the frame has a menu bar with keyboard shortcuts, and if the key +event includes a Control, Alt, Option, Meta, Command, Shift, or +Function key, then +@method[frame% on-menu-char] attempts to match the given event to a menu item. If a match is found, + @scheme[#t] is returned, otherwise @scheme[#f] is returned. + +When the match corresponds to a complete shortcut combination, the + menu item's callback is called (before +@method[frame% on-menu-char] returns). + +If the event does not correspond to a complete shortcut combination, + the event may be handled anyway if it corresponds to a mnemonic in the + menu bar (i.e., an underlined letter in a menu's title, which is + installed by including an ampersand in the menu's label). If a + mnemonic match is found, the keyboard focus is moved to the menu bar + (selecting the menu with the mnemonic), and @scheme[#t] is returned. + +}} + +@defmethod[#:mode 'override + (on-subwindow-char [receiver (is-a/c window<%>)] + [event (is-a/c key-event%)]) + boolean?]{ +@impl{ + +Returns the result of +\scmline{(or (send @scheme[this] +@method[frame% on-menu-char] @scheme[event]) \\ +\>(send @scheme[this] +@method[top-level-window<%> on-system-menu-char] @scheme[event])\\ +\>(send @scheme[this] +@method[top-level-window<%> on-traverse-char] @scheme[event]))} + + + +}} + +@defmethod[(on-toolbar-button-click) + void?]{ +@spec{ + +Under Mac OS X, called when the user clicks the toolbar button on a + frame created with the @indexed-scheme['toolbar-button] style. + +}} + +@defmethod*[([(modified) + boolean?] + [(modified [modified? any/c]) + void?])]{ +@spec{ + +Gets or sets the frame's modification state as reflected to the user. + Under Mac OS X, the modification state is reflected as a dot in the + frame's close button. Under Windows and X, the modification state is + reflected by an asterisk at the end of the frame's displayed title. + +} +@impl{ +First case: + + +Returns the current displayed modification state. + + + +Second case: + + +Sets the displayed modification state. + + + + +}}} + diff --git a/collects/scribblings/gui/gauge-class.scrbl b/collects/scribblings/gui/gauge-class.scrbl new file mode 100644 index 0000000000..9b123a2c32 --- /dev/null +++ b/collects/scribblings/gui/gauge-class.scrbl @@ -0,0 +1,85 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[gauge% object% (control<%>)]{ + +A gauge is a horizontal or vertical bar for displaying the output + value of a bounded integer quantity. Each gauge has an adjustable + range, and the gauge's current value is always between 0 and its + range, inclusive. Use +@method[gauge% set-value] to set the value of the gauge. + + + + +@defconstructor[[label (or/c label-string? false/c)] + [range (integer-in 1 10000)] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [style (symbols/c deleted horizontal-label vertical-label vertical horizontal) '(horizontal)] + [font (is-a/c font%) @scheme[normal-control-font]] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 2] + [horiz-margin (integer-in 0 1000) 2] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c \#t {\rm for} @scheme['horizontal] {\rm style}, \#f {\rm for} @scheme['vertical]] + [stretchable-height any/c \#t {\rm for} @scheme['vertical] {\rm style}, \#f {\rm for} @scheme['horizontal]]]{ + +If @scheme[label] is a string, it is used as the gauge label; otherwise + the gauge does not display a label. + +@labelstripped[(scheme label) @elem{gauge}] + +The @scheme[range] argument is an integer specifying the maximum value of + the gauge (inclusive). The minimum gauge value is always @scheme[0]. + +The @scheme[style] list must include either @scheme['horizontal], + specifying a horizontal gauge, or @scheme['vertical], specifying + a vertical gauge. \HVLabelNote{gauge} \DeletedStyleNote{gauge} + +@FontKWs[] @WindowKWs[] @SubareaKWs[] @AreaKWs[] + + + +} + +@defmethod[(set-range [range (integer-in 1 10000)]) + void?]{ +@spec{ + +Sets the range (maximum value) of the gauge. + +}} + +@defmethod[(get-range) + (integer-in 1 10000)]{ +@spec{ + +Returns the range (maximum value) of the gauge. + +}} + +@defmethod[(set-value [pos (integer-in 0 10000)]) + void?]{ +@spec{ + +Sets the gauge's current value. If the specified value is larger than + the gauge's range, @|MismatchExn|}. + +}} + +@defmethod[(get-value) + (integer-in 0 10000)]{ +@spec{ + +Returns the gauge's current value. + +} +@impl{ + + + + + +}}} + diff --git a/collects/scribblings/gui/group-box-panel-class.scrbl b/collects/scribblings/gui/group-box-panel-class.scrbl new file mode 100644 index 0000000000..86290dde18 --- /dev/null +++ b/collects/scribblings/gui/group-box-panel-class.scrbl @@ -0,0 +1,40 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[group-box-panel% vertical-panel% ()]{ + +A group-box panel arranges its subwindows in a single column, but also + draws an optional label at the top of the panel and a border around + the panel content. + +Unlike most panel classes, a group-box panel's horizontal and vertical + margins default to @scheme[2]. + + + + +@defconstructor[[label label-string?] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [style (symbols/c deleted) null] + [font (is-a/c font%) @scheme[small-control-font]] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 2] + [horiz-margin (integer-in 0 1000) 2] + [border (integer-in 0 1000) 0] + [spacing (integer-in 0 1000) 0] + [alignment two-element list: @scheme['left], @scheme['center], or @scheme['right] and @scheme['top], @scheme['center], or @scheme['bottom] '(center top)] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #t] + [stretchable-height any/c #t]]{ + +Creates a group pane whose title is @scheme[label]. + +\DeletedStyleNote{group panel} + +@FontKWs[] @WindowKWs[] @SubareaKWs[] @AreaKWs[] + + + +}} + diff --git a/collects/scribblings/gui/grow-box-spacer-pane-class.scrbl b/collects/scribblings/gui/grow-box-spacer-pane-class.scrbl new file mode 100644 index 0000000000..16c41c87d6 --- /dev/null +++ b/collects/scribblings/gui/grow-box-spacer-pane-class.scrbl @@ -0,0 +1,22 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[grow-box-spacer-pane% pane% ()]{ + +A @scheme[grow-box-spacer-pane%] object is intended for use as a + lightweight spacer in the bottom-right corner of a frame, rather than + as a container. Under Mac OS X, a + @scheme[grow-box-spacer-pane%] has the same width and height as the + grow box that is inset into the bottom-right corner of a frame. Under + Windows and X, a @scheme[grow-box-spacer-pane%] has zero width and + height. Unlike all other container types, a + @scheme[grow-box-spacer-pane%] is unstretchable by default. + + + + + +@defconstructor/auto-super[[#f unknown]]{ +Passes all arguments to @scheme[super-init]. +}} + diff --git a/collects/scribblings/gui/gui.scrbl b/collects/scribblings/gui/gui.scrbl new file mode 100644 index 0000000000..327f304443 --- /dev/null +++ b/collects/scribblings/gui/gui.scrbl @@ -0,0 +1,17 @@ +#reader(lib "docreader.ss" "scribble") +@require["common.ss"] + +@title{PLT Scheme GUI Reference} + +This manual describes MrEd. + +@bold{This reference describes a potential future version of PLT Scheme. + It does not match the current implementation.} + +@table-of-contents[] + +@include-section["windowing.scrbl"] + +@;------------------------------------------------------------------------ + +@index-section["mred-index"] diff --git a/collects/scribblings/gui/horizontal-pane-class.scrbl b/collects/scribblings/gui/horizontal-pane-class.scrbl new file mode 100644 index 0000000000..1f2eaad59c --- /dev/null +++ b/collects/scribblings/gui/horizontal-pane-class.scrbl @@ -0,0 +1,28 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[horizontal-pane% pane% ()]{ + +A horizontal pane arranges its subwindows in a single row. See also + @scheme[pane%]. + + + + +@defconstructor[[parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [vert-margin (integer-in 0 1000) 0] + [horiz-margin (integer-in 0 1000) 0] + [border (integer-in 0 1000) 0] + [spacing (integer-in 0 1000) 0] + [alignment two-element list: @scheme['left], @scheme['center], or @scheme['right] and @scheme['top], @scheme['center], or @scheme['bottom] '(left center)] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #t] + [stretchable-height any/c #t]]{ + +@SubareaKWs[] @AreaContKWs[] @AreaKWs[] + + + +}} + diff --git a/collects/scribblings/gui/horizontal-panel-class.scrbl b/collects/scribblings/gui/horizontal-panel-class.scrbl new file mode 100644 index 0000000000..e6dfbac925 --- /dev/null +++ b/collects/scribblings/gui/horizontal-panel-class.scrbl @@ -0,0 +1,34 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[horizontal-panel% panel% ()]{ + +A horizontal panel arranges its subwindows in a single row. See also + @scheme[panel%]. + + + + +@defconstructor[[parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [style (symbols/c deleted border) null] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 0] + [horiz-margin (integer-in 0 1000) 0] + [border (integer-in 0 1000) 0] + [spacing (integer-in 0 1000) 0] + [alignment two-element list: @scheme['left], @scheme['center], or @scheme['right] and @scheme['top], @scheme['center], or @scheme['bottom] '(left center)] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #t] + [stretchable-height any/c #t]]{ + +If the @scheme['border] style is specified, the window is created with + a thin border (only in this case, the client size of the panel may be + less than its total size). \DeletedStyleNote{panel} + +@WindowKWs[] @SubareaKWs[] @AreaContKWs[] @AreaKWs[] + + + +}} + diff --git a/collects/scribblings/gui/key-event-class.scrbl b/collects/scribblings/gui/key-event-class.scrbl new file mode 100644 index 0000000000..1a09fb3c0e --- /dev/null +++ b/collects/scribblings/gui/key-event-class.scrbl @@ -0,0 +1,430 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[key-event% event% ()]{ + +A @scheme[key-event%] object contains information about a key press + or release event. Key events are primarily processed by +@xmethod[window<%> on-subwindow-char] and +@xmethod[canvas<%> on-char]. + +For a key-press event, a virtual key code is provided by +@method[key-event% get-key-code]. For a key-release event, +@method[key-event% get-key-code] reports @scheme['release], and a virtual key code is provided by +@method[key-event% get-key-release-code]. + +See also @|mousekeydiscuss|. + + + +@defconstructor[[key-code character or symbol \#{\TTBackslash}nul] + [shift-down any/c #f] + [control-down any/c #f] + [meta-down any/c #f] + [alt-down any/c #f] + [x (and/c exact? integer?) 0] + [y (and/c exact? integer?) 0] + [time-stamp (and/c exact? integer?) 0] + [caps-down any/c #f]]{ + +See the corresponding @scheme[get-] and @scheme[set-] methods for + information about @scheme[key-code], @scheme[shift-down], + @scheme[control-down], @scheme[meta-down], @scheme[alt-down], @scheme[x], + @scheme[y], @scheme[time-stamp], @scheme[caps-down]. + +The release key code, as returned by +@method[key-event% get-key-release-code], is initialized to @scheme['press]. + + +} + +@defmethod[(get-control-down) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the Control key was down for the event. + +Under Mac OS X, if a control-key press is combined with a mouse button + click, the event is reported as a right-button click and +@method[key-event% get-control-down] for the event reports @scheme[#f]. + +}} + +@defmethod[(set-control-down [down? any/c]) + void?]{ +@spec{ + +Sets whether the Control key was down for the event. + +Under Mac OS X, if a control-key press is combined with a mouse button + click, the event is reported as a right-button click and +@method[key-event% get-control-down] for the event reports @scheme[#f]. + +}} + +@defmethod[(get-shift-down) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the Shift key was down for the event. + +}} + +@defmethod[(set-shift-down [down? any/c]) + void?]{ +@spec{ + +Sets whether the Shift key was down for the event. + +}} + +@defmethod[(get-alt-down) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the Option (Mac OS X) key was down for + the event. When the Alt key is pressed in Windows, it is reported as + a Meta press (see +@method[key-event% get-meta-down]). + +}} + +@defmethod[(set-alt-down [down? any/c]) + void?]{ +@spec{ + +Sets whether the Option (Mac OS X) key was down for the event. + When the Alt key is pressed in Windows, it is reported as + a Meta press (see +@method[key-event% set-meta-down]). + +}} + +@defmethod[(get-meta-down) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the Meta (X), Alt (Windows), or Command (Mac OS X) + key was down for the event. + +}} + +@defmethod[(set-meta-down [down? any/c]) + void?]{ +@spec{ + +Sets whether the Meta (X), Alt (Windows), or Command (Mac OS X) key was + down for the event. + +}} + +@defmethod[(get-caps-down) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the Caps Lock key was on for the event. + +}} + +@defmethod[(set-caps-down [down? any/c]) + void?]{ +@spec{ + +Sets whether the Caps Lock key was on for the event. + +}} + +@defmethod[(get-key-code) + character or symbol]{ +@spec{ + +Gets the virtual key code for the key event. The virtual key code is + either a character or a special key symbol, one of the following: +@itemize{ +@item{@indexed-scheme['start]} +@item{@indexed-scheme['cancel]} +@item{@indexed-scheme['clear]} +@item{@indexed-scheme['shift]} +@item{@indexed-scheme['control]} +@item{@indexed-scheme['menu]} +@item{@indexed-scheme['pause]} +@item{@indexed-scheme['capital]} +@item{@indexed-scheme['prior]} +@item{@indexed-scheme['next]} +@item{@indexed-scheme['end]} +@item{@indexed-scheme['home]} +@item{@indexed-scheme['left]} +@item{@indexed-scheme['up]} +@item{@indexed-scheme['right]} +@item{@indexed-scheme['down]} +@item{@indexed-scheme['escape]} +@item{@indexed-scheme['select]} +@item{@indexed-scheme['print]} +@item{@indexed-scheme['execute]} +@item{@indexed-scheme['snapshot]} +@item{@indexed-scheme['insert]} +@item{@indexed-scheme['help]} +@item{@indexed-scheme['numpad0]} +@item{@indexed-scheme['numpad1]} +@item{@indexed-scheme['numpad2]} +@item{@indexed-scheme['numpad3]} +@item{@indexed-scheme['numpad4]} +@item{@indexed-scheme['numpad5]} +@item{@indexed-scheme['numpad6]} +@item{@indexed-scheme['numpad7]} +@item{@indexed-scheme['numpad8]} +@item{@indexed-scheme['numpad9]} +@item{@indexed-scheme['numpad-enter]} +@item{@indexed-scheme['multiply]} +@item{@indexed-scheme['add]} +@item{@indexed-scheme['separator]} +@item{@indexed-scheme['subtract]} +@item{@indexed-scheme['decimal]} +@item{@indexed-scheme['divide]} +@item{@indexed-scheme['f1]} +@item{@indexed-scheme['f2]} +@item{@indexed-scheme['f3]} +@item{@indexed-scheme['f4]} +@item{@indexed-scheme['f5]} +@item{@indexed-scheme['f6]} +@item{@indexed-scheme['f7]} +@item{@indexed-scheme['f8]} +@item{@indexed-scheme['f9]} +@item{@indexed-scheme['f10]} +@item{@indexed-scheme['f11]} +@item{@indexed-scheme['f12]} +@item{@indexed-scheme['f13]} +@item{@indexed-scheme['f14]} +@item{@indexed-scheme['f15]} +@item{@indexed-scheme['f16]} +@item{@indexed-scheme['f17]} +@item{@indexed-scheme['f18]} +@item{@indexed-scheme['f19]} +@item{@indexed-scheme['f20]} +@item{@indexed-scheme['f21]} +@item{@indexed-scheme['f22]} +@item{@indexed-scheme['f23]} +@item{@indexed-scheme['f24]} +@item{@indexed-scheme['numlock]} +@item{@indexed-scheme['scroll]} +@item{@indexed-scheme['wheel-up] --- \index{wheel on mouse} mouse wheel up one notch} +@item{@indexed-scheme['wheel-down] --- mouse wheel down one notch} +@item{@indexed-scheme['release] --- indicates a key-release event} +@item{@indexed-scheme['press] --- indicates a key-press event; usually only from @scheme[get-key-release-code]} +} +The special key symbols attempt to capture useful keys that have no + standard ASCII representation. A few keys have standard + representations that are not obvious: +@itemize{ + + @item{@scheme[#{\TTBackslash]space} --- the space bar} + + @item{@scheme[#{\TTBackslash]return} --- the Enter or Return key (on all + platforms), but not necessarily the Enter key near the numpad + (which is reported as @scheme['numpad-enter] if the platform + distinguishes the two Enter keys)} + + @item{@scheme[#{\TTBackslash]tab} --- the tab key} + + @item{@scheme[#{\TTBackslash]backspace} --- the backspace key} + + @item{@scheme[#{\TTBackslash]rubout} --- the delete key} + +} +If a suitable special key symbol or ASCII representation is not + available, @scheme[#{\TTBackslash]nul} (the null character) is + reported. + +Under X, a @scheme['wheel-up] or @scheme['wheel-down] event may be sent + to a window other than the one with the keyboard focus, because X + generates wheel events based on the location of the mouse pointer. + +Under Windows, when the Control key is pressed without Alt, the key + code for ASCII characters is downcased, roughly cancelling the effect + of the Shift key. Under Mac OS X, the key code is computed without + Caps Lock effects when the Control or Command key is pressed; in the + case of Control, Caps Lock is used normally if special handling is + disabled for the Control key via +@scheme[special-control-key]. Under X, the key code is computed with Caps Lock effects when the + Control key is pressed without Alt. + +See also +@method[key-event% get-other-shift-key-code]. + +}} + +@defmethod[(set-key-code [code character or symbol]) + void?]{ +@spec{ + +Sets the virtual key code for the event, either a character or one + of the special symbols listed with +@method[key-event% get-key-code]. + +}} + +@defmethod[(get-key-release-code) + character or symbol]{ +@spec{ + +Gets the virtual key code for a key-release event; the result is + @scheme['press] for a key-press event. See +@method[key-event% get-key-code] for the list of virtual key codes. + +}} + +@defmethod[(set-key-release-code [code character or symbol]) + void?]{ +@spec{ + +Sets the virtual key code for a release event, either a character or + one of the special symbols listed with +@method[key-event% get-key-code]. See also +@method[key-event% get-key-release-code]. + +}} + +@defmethod[(get-other-shift-key-code) + (or/c character, symbol, false/c)]{ +@spec{ + +Since keyboard mappings vary, it is sometimes useful in key mappings + for a program to know the result that the keyboard would have + produced for an event if the Shift key had been toggled differently. The +@method[key-event% get-other-shift-key-code] produces that other mapping, + returning @scheme[#f] if the alternate mapping is + unavailable, otherwise returning the same kind of result as +@method[key-event% get-key-code]. + +The +@method[key-event% get-other-altgr-key-code] method provides the same information with respect to the AltGr key + (i.e., Alt combined with Control) under Windows and X, or the Option + key under Mac OS X. The +@method[key-event% get-other-shift-altgr-key-code] method reports a mapping for in tha case that both Shift and AltGr/Option + were different from the actual event. + +The +@method[key-event% get-other-shift-key-code], +@method[key-event% get-other-altgr-key-code], and +@method[key-event% get-other-shift-altgr-key-code] results all report key mappings where Caps Lock is off, independent +of whether Caps Lock was on for the actual event. The +@method[key-event% get-other-caps-key-code] method reports a mapping for in that case that the Caps Lock state + was treated opposite as for the +@method[key-event% get-key-code] result. (Caps Lock normally has either no effect or the same effect + as Shift, so further combinations involving Caps Lock and other + modifier keys would not normally produce further alternatives.) + +Alternate mappings are not available for all events. Under Windows, + alternate mappings are reported when they produce ASCII letters, + ASCII digits, and ASCII symbols. Under Mac OS X, alternate mappings are + available only when the Command key is pressed. Under X, alternate + mappings are usually available. + +}} + +@defmethod[(set-other-shift-key-code [code (or/c character, symbol, false/c)]) + void?]{ +@spec{ + +Sets the key code produced by +@method[key-event% get-other-shift-key-code]. + +}} + +@defmethod[(get-other-altgr-key-code) + (or/c character, symbol, false/c)]{ +@spec{ + +See +@method[key-event% get-other-shift-key-code]. + +}} + +@defmethod[(set-other-altgr-key-code [code (or/c character, symbol, false/c)]) + void?]{ +@spec{ + +Sets the key code produced by +@method[key-event% get-other-altgr-key-code]. + +}} + +@defmethod[(get-other-shift-altgr-key-code) + (or/c character, symbol, false/c)]{ +@spec{ + +See +@method[key-event% get-other-shift-key-code]. + +}} + +@defmethod[(set-other-shift-altgr-key-code [code (or/c character, symbol, false/c)]) + void?]{ +@spec{ + +Sets the key code produced by +@method[key-event% get-other-shift-altgr-key-code]. + +}} + +@defmethod[(get-other-caps-key-code) + (or/c character, symbol, false/c)]{ +@spec{ + +See +@method[key-event% get-other-shift-key-code]. + +}} + +@defmethod[(set-other-caps-key-code [code (or/c character, symbol, false/c)]) + void?]{ +@spec{ + +Sets the key code produced by +@method[key-event% get-other-caps-key-code]. + +}} + +@defmethod[(get-x) + (and/c exact? integer?)]{ +@spec{ + +Returns the x-position of the mouse at the time of the event, in the + target's window's (client-area) coordinate system. + +}} + +@defmethod[(set-x [pos (and/c exact? integer?)]) + void?]{ +@spec{ + +Sets the x-position of the mouse at the time of the event in the + target's window's (client-area) coordinate system. + +}} + +@defmethod[(get-y) + (and/c exact? integer?)]{ +@spec{ + +Returns the y-position of the mouse at the time of the event in the + target's window's (client-area) coordinate system. + +}} + +@defmethod[(set-y [pos (and/c exact? integer?)]) + void?]{ +@spec{ + +Sets the y-position of the mouse at the time of the event in the + target's window's (client-area) coordinate system. + +} +@impl{ + + + + + +}}} + diff --git a/collects/scribblings/gui/labelled-menu-item-intf.scrbl b/collects/scribblings/gui/labelled-menu-item-intf.scrbl new file mode 100644 index 0000000000..5911db0635 --- /dev/null +++ b/collects/scribblings/gui/labelled-menu-item-intf.scrbl @@ -0,0 +1,132 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@definterface[labelled-menu-item<%> (menu-item<%>)]{ + +A @scheme[labelled-menu-item<%>] object is a @scheme[menu-item<%>] with + a string label (i.e., any menu item other than a separator). More + specifically, it is an instance of either @scheme[menu-item%] (a + plain menu item), @scheme[checkable-menu-item%] (a checkable menu + item), or @scheme[menu%] (a submenu). + + + +@defmethod[(get-label) + label-string?]{ +@spec{ + +Returns the item's label. + +See also +@method[labelled-menu-item<%> set-label] and +@method[labelled-menu-item<%> get-plain-label]. + + +}} + +@defmethod[(set-label [label label-string?]) + void?]{ +@spec{ + +Sets the menu item's label. If the item has a shortcut, the shortcut + is not affected. + +If the label contains an ampersand (``\&'') and the window is a + control, the label is parsed specially; under Windows and X, the + character following an ampersand is underlined in the displayed menu + to indicate a keyboard mnemonic. Pressing the Alt key with an + underlined character from a menu's name in the menu bar causes the + menu to be selected (via @method[frame% on-menu-char]). When + a menu has the focus, the mnemonic characters are used for navigation + without Alt. A double-ampersand in the label is replaced by a literal + (non-navigation) ampersand. Under Mac OS X, ampersands in the + label are parsed in the same way as for X and Windows, but no + mnemonic underline is displayed. + +An ampersand is always preserved in the label returned by +@method[labelled-menu-item<%> get-label], but never preserved in the label returned by +@method[labelled-menu-item<%> get-plain-label]. + +For historical reasons, if a label contains a tab character, then the + tab and all remaining characters are hidden in the displayed menu. + +}} + +@defmethod[(get-plain-label) + label-string?]{ +@spec{ + +Like +@method[labelled-menu-item<%> get-label], except that ampersands in the label are removed as described in +@method[labelled-menu-item<%> set-label]. + + +}} + +@defmethod[(get-help-string) + (or/c label-string? false/c)]{ +@spec{ + +Returns the help string for the menu item, or @scheme[#f] if the item + has no help string. + +When an item has a @scheme[help], the string may be used to + display help information to the user. + +}} + +@defmethod[(set-help-string [help (or/c label-string? false/c)]) + void?]{ +@spec{ + +Sets the help string for the menu item. Use @scheme[#f] to remove + the help string for an item. + +}} + +@defmethod[(enable [enabled? any/c]) + void?]{ +@spec{ + +Enables or disables the menu item. If the item is a submenu (or menu in + a menu bar), the entire menu is disabled, but each submenu item's +@method[labelled-menu-item<%> is-enabled?] method returns @scheme[#f] only if the item is specifically disabled (in + addition to the submenu). + +}} + +@defmethod[(is-enabled?) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the menu item is enabled, @scheme[#f] otherwise. + +See also +@method[labelled-menu-item<%> enable]. + +}} + +@defmethod[(on-demand) + void?]{ +@spec{ + +Normally called when the user clicks on the menu bar containing the + item (before the user sees any menu items), just before the popup + menu containing the item is popped up, or just before inspecting the + menu bar containing the item for a shortcut key binding. + +A +@xmethod[menu-item-container<%> on-demand] method can be overridden in such a way that the container does not + call the +@method[labelled-menu-item<%> on-demand] method of its items. + +} +@impl{ + +Calls the @scheme[demand-callback] procedure that was provided when the + object was created. + + + +}}} + diff --git a/collects/scribblings/gui/list-box-class.scrbl b/collects/scribblings/gui/list-box-class.scrbl new file mode 100644 index 0000000000..3a6abf6210 --- /dev/null +++ b/collects/scribblings/gui/list-box-class.scrbl @@ -0,0 +1,303 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[list-box% object% (list-control<%>)]{ + +A list box allows the user to select one or more string items from a + scrolling list. A list box is either a single-selection control (if + an item is selected, the previous selection is removed) or a + multiple-selection control (clicking an item toggles the item on or + off independently of other selections). + +Whenever the user changes the selection in a list box, the list box's + callback procedure is called. A callback procedure is provided as an + initialization argument when each list box is created. + +\newcommand{\lbnumnote}[0]{List box items are indexed from +@scheme[0].} + +{\lbnumnote} + +See also +@scheme[choice%]. + + + + +@defconstructor[[label (or/c label-string? false/c)] + [choices list of {\labelstrings}] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [callback procedure of two arguments: a @scheme[list-box%] object and a @scheme[control-event%] object @scheme[(\scmk{lambda] (@scheme[lb] @scheme[e]) (void))}] + [style (symbols/c deleted horizontal-label vertical-label extended multiple single) '(single)] + [selection (or/c nonnegative-exact-integer? false/c) #f] + [font (is-a/c font%) @scheme[view-control-font]] + [label-font (is-a/c font%) @scheme[normal-control-font]] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 2] + [horiz-margin (integer-in 0 1000) 2] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #t] + [stretchable-height any/c #t]]{ + +If @scheme[label] is not @scheme[#f], it is used as the list box label. + Otherwise, the list box will not display its + label. + +@labelstripped[(scheme label) @elem{} @elem{move the keyboard focus to the list box}] + +The @scheme[choices] list specifies the initial list of items + to appear in the list box. + +The @scheme[callback] procedure is called when the user changes the list + box selection, by either selecting, re-selecting, deselecting, or + double-clicking an item. The type of the event provided to the + callback is @indexed-scheme['list-box-dclick] when the user double-clicks + on an item, or @indexed-scheme['list-box] otherwise. + +The @scheme[style] specification must include exactly one of the + following: +@itemize{ + + @item{@scheme['single] --- Creates a single-selection list.} + + @item{@scheme['multiple] --- Creates a multiple-selection list + where a single click deselects other items and selects a new + item. Use this style for a list when single-selection is common, but + multiple selections are allowed.} + + @item{@scheme['extended] --- Creates a multiple-selection list where a + single click extends or contracts the selection by toggling the + clicked item. Use this style for a list when multiple selections are + the rule rather than the exception.} + +} +The @scheme['multiple] and @scheme['extended] styles determine a + platform-independent interpretation of unmodified mouse clicks, but + dragging, shift-clicking, control-clicking, etc. have + platform-standard interpretations. Whatever the platform-specific + interface, the user can always select disjoint sets of items or + deselect items (and leave no items selected). On some platforms, the + user can deselect the (sole) selected item in a @scheme['single] list + box. + +\HVLabelNote{list box} \DeletedStyleNote{list box} + +If @scheme[selection] is an integer, it is passed to +@method[list-control<%> set-selection] to set the initial selection. The @scheme[selection] must be less than + the length of @scheme[choices]. + +@FontLabelKWs[] @WindowKWs[] @SubareaKWs[] @AreaKWs[] + + + +} + +@defmethod[#:mode 'add + (append [item string] + [data value]) + void?]{ +@impl{ + +Adds a new item to the list box with an associated ``data'' object. + The @scheme[data] object is not displayed in the list box; it is + provided merely as a convenience for use with +@method[list-box% get-data], possibly allowing a programmer to avoid managing a separate + item-to-data mapping in addition to the list box control. + + + +}} + +@defmethod[(delete [n nonnegative-exact-integer?]) + void?]{ +@spec{ + +Deletes a choice from the list box. Selected items that are not + deleted remain selected, and no other items are selected. + +} +@impl{ + +Deletes the item indexed by @scheme[n]. {\lbnumnote} If @scheme[n] is equal + to or larger than the number of items in the control, @|MismatchExn|}. + + +}} + +@defmethod[(get-data [n nonnegative-exact-integer?]) + value]{ +@spec{ + +Returns the data value associated with a list box item, or @scheme[#f] + if there is no associated data. See also +@method[list-box% append] and +@method[list-box% set-data]. + +} +@impl{ + +Returns the data for the item indexed by @scheme[n]. {\lbnumnote} If + @scheme[n] is equal to or larger than the number of choices, + @|MismatchExn|}. + + + +}} + +@defmethod[(get-selections) + list of {\Ints}]{ +@spec{ + +Returns a list of indices for all currently selected items. + {\lbnumnote} + +For single-selection lists, the result is always either @scheme[null] or + a list containing one number. + +}} + +@defmethod[(number-of-visible-items) + positive-exact-integer?]{ +@spec{ + +Returns the maximum number of items in the list box that are visible + to the user with the control's current size (rounding down if the + exact answer is fractional, but returning at least @scheme[1]). + +}} + +@defmethod[(is-selected? [n nonnegative-exact-integer?]) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the item matching the specifies index is + selected, @scheme[#f] otherwise. + +@MonitorCallback[@elem{A list box's selection} @elem{the user clicking the control} @elem{selection}] + +} +@impl{ + +Returns @scheme[#t] if the item index by @scheme[n] is + selected. {\lbnumnote} If @scheme[n] is equal to or larger than the + number of choices, @|MismatchExn|}. + + + +}} + +@defmethod[(set [choices list of {\labelstrings}]) + void?]{ +@spec{ + +Clears the list box and installs a new list of items. + +}} + +@defmethod[(set-data [n nonnegative-exact-integer?] + [data value]) + void?]{ +@spec{ + +Sets the associated data for a list box choice item. See also +@method[list-box% append]. + +} +@impl{ + +Sets the associated data for item indexed by @scheme[n]. {\lbnumnote} If + @scheme[n] is equal to or larger than the number of choices, + @|MismatchExn|}. + + + +}} + +@defmethod[(set-string [n nonnegative-exact-integer?] + [label label-string?]) + void?]{ +@spec{ + +Changes an item in the list box. + +} +@impl{ + +Sets the item indexed by @scheme[n]. {\lbnumnote} If @scheme[n] is equal to + or larger than the number of choices, @|MismatchExn|}. + + + +}} + +@defmethod[(get-first-visible-item) + nonnegative-exact-integer?]{ +@spec{ + +Reports the index of the item currently scrolled to the top of the + list box. {\lbnumnote} + +}} + +@defmethod[(set-first-visible-item [n nonnegative-exact-integer?]) + void?]{ +@spec{ + +Scrolls the list box so that the specified item is at the top of the + list box display. + +@Unmonitored[@elem{A list box's scroll position} @elem{the user clicking the control} @elem{the scroll position + changes} @elem{@method[list-box% get-first-visible-item]}] + +} +@impl{ + +Shows the item indexed by @scheme[n] at the list box's top. {\lbnumnote} + If @scheme[n] is equal to or larger than the number of choices, + @|MismatchExn|}. + + + +}} + +@defmethod[(select [n nonnegative-exact-integer?] + [select? any/c #t]) + void?]{ +@spec{ + +Selects or deselects an item. For selection in a single-selection list + box, if a different choice is currently selected, it is automatically + deselected. For selection in a multiple-selection list box, other + selections are preserved, unlike +@method[list-control<%> set-selection]. + +@MonitorCallback[@elem{A list box's selection} @elem{the user clicking the control} @elem{selection}] + +The control's callback procedure is {\em not} invoked. + +} +@impl{ + +If @scheme[select?] is @scheme[#f], the item indexed by @scheme[n] is + deselected; otherwise it is selected. {\lbnumnote} If @scheme[n] is + equal to or larger than the number of choices, @|MismatchExn|}. + + + +}} + +@defmethod[(get-label-font) + (is-a/c font%)]{ +@spec{ + +Returns the font used for the control's label, which is optionally + supplied when a list box is created. + +} +@impl{ + + + +}}} + diff --git a/collects/scribblings/gui/list-control-intf.scrbl b/collects/scribblings/gui/list-control-intf.scrbl new file mode 100644 index 0000000000..d57d3834c5 --- /dev/null +++ b/collects/scribblings/gui/list-control-intf.scrbl @@ -0,0 +1,137 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@definterface[list-control<%> (control<%>)]{ + +A list control gives the user a list of string items to choose from. + There are two built-in classes that implement + @scheme[list-control<%>]: +@itemize{ + + @item{@scheme[choice%] --- presents the list in a popup menu (so + the user can choose only one item at a time)} + + @item{@scheme[list-box%] --- presents the list in a scrolling box, + allowing the use to choose one item (if the style includes + @scheme['single]) or any number of items} + +} +In either case, the set of user-selectable items can be changed + dynamically. + + + + +@defmethod[(append [item string]) + void?]{ +@spec{ + +Adds a new item to the list of user-selectable items. The current + selection is unchanged (unless the list control is an empty choice + control, in which case the new item is selected). + +}} + +@defmethod[(clear) + void?]{ +@spec{ + +Removes all user-selectable items from the control. + +}} + +@defmethod[(find-string [s string]) + (or/c nonnegative-exact-integer? false/c)]{ +@spec{ + +Finds a user-selectable item matching the given string. If no matching + choice is found, @scheme[#f] is returned, otherwise the index of the + matching choice is returned (items are indexed from @scheme[0]). + +}} + +@defmethod[(get-selection) + (or/c nonnegative-exact-integer? false/c)]{ +@spec{ + +Returns the index of the currently selected item (items are indexed + from @scheme[0]). If the choice item currently contains no choices or no + selections, @scheme[#f] is returned. If multiple selections are + allowed and multiple items are selected, the index of the first + selection is returned. + +}} + +@defmethod[(get-string-selection) + (or/c immutable {\labelstring} false/c)]{ +@spec{ + +Returns the currently selected item. If the control currently + contains no choices, @scheme[#f] is returned. If multiple selections + are allowed and multiple items are selected, the first selection is + returned. + +}} + +@defmethod[(get-number) + nonnegative-exact-integer?]{ +@spec{ + +Returns the number of user-selectable items in the control (which is + also one more than the greatest index in the list control). + +}} + +@defmethod[(set-selection [n nonnegative-exact-integer?]) + void?]{ +@spec{ + +Selects the item specified by the given index (items are indexed from + @scheme[0]). If the given index larger than the greatest index in the + list control, @|MismatchExn|}. + +In a list box control, all other items are deselected, even if multiple + selections are allowed in the control. See also +@xmethod[list-box% select]. + +The control's callback procedure is {\em not} invoked when this method +is called. + +@MonitorCallback[@elem{The list control's selection} @elem{the user clicking the control} @elem{selection}] + +}} + +@defmethod[(set-string-selection [s string]) + void?]{ +@spec{ + +Selects the item that matches the given string. If no match + is found in the list control, @|MismatchExn|}. + +In a list box control, all other items are deselected, even if multiple + selections are allowed in the control. See also +@xmethod[list-box% select]. + +The control's callback procedure is {\em not} invoked when this method +is called. + +@MonitorCallback[@elem{The list control's selection} @elem{the user clicking the control} @elem{selection}] + +}} + +@defmethod[(get-string [n nonnegative-exact-integer?]) + immutable {\labelstring}]{ +@spec{ + +Returns the item for the given index (items are indexed from + @scheme[0]). If the provided index is larger than the greatest index in + the list control, @|MismatchExn|}. + +} +@impl{ + + + + +}}} + diff --git a/collects/scribblings/gui/menu-bar-class.scrbl b/collects/scribblings/gui/menu-bar-class.scrbl new file mode 100644 index 0000000000..c943fd8711 --- /dev/null +++ b/collects/scribblings/gui/menu-bar-class.scrbl @@ -0,0 +1,63 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[menu-bar% object% (menu-item-container<%>)]{ + +A @scheme[menu-bar%] object is created for a particular + @scheme[frame%] object. A frame can have at most one menu bar; + @|MismatchExn|} when a new menu bar is created for a frame that + already has a menu bar. + + + +@defconstructor[[parent @scheme[frame%] object or @scheme['root]] + [demand-callback procedure of one argument: a @scheme[menu-bar%] object @scheme[void]]]{ + +Creates a menu bar in the specified frame. The menu bar is initially + empty. If @indexed-scheme['root] is supplied as @scheme[parent], the menu + bar becomes active only when no other frames are shown. A + @scheme['root] @scheme[parent] is allowed only when + @scheme[current-eventspace-has-menu-root?] returns + @scheme[#t], and only if no such menu bar has been created before, + otherwise @|MismatchExn|}. + +The @scheme[demand-callback] procedure is called by the default +@method[menu-item-container<%> on-demand] method with the object itself. + + + +} + +@defmethod[(get-frame) + (is-a/c frame%)]{ +@spec{ + +Returns the menu bar's frame. + +}} + +@defmethod[(enable [enable? any/c]) + void?]{ +@spec{ + +Enables or disables the menu bar (i.e., all of its menus). Each + menu's +@method[labelled-menu-item<%> is-enabled?] method returns @scheme[#f] only if the menu is specifically disabled (in + addition to the menu bar). + +}} + +@defmethod[(is-enabled?) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the menu bar is enabled, @scheme[#f] otherwise. + +} +@impl{ + + + + +}}} + diff --git a/collects/scribblings/gui/menu-class.scrbl b/collects/scribblings/gui/menu-class.scrbl new file mode 100644 index 0000000000..75f26d129d --- /dev/null +++ b/collects/scribblings/gui/menu-class.scrbl @@ -0,0 +1,49 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[menu% object% (menu-item-container<%> labelled-menu-item<%>)]{ + +A @scheme[menu%] object is a submenu within a @scheme[menu%] or + @scheme[popup-menu%], or as a top-level menu in a + @scheme[menu-bar%]. + + + + +@defconstructor[[label label-string?] + [parent @scheme[menu%], @scheme[popup-menu%], or @scheme[menu-bar%] object] + [help-string (or/c label-string? false/c) #f] + [demand-callback procedure of one argument: a @scheme[menu%] object @scheme[void]]]{ + +Creates a new menu with the given label. + +If @scheme[label] contains an ampersand (``\&''), it is handled + specially; under Windows, the character following an ampersand is + underlined in the displayed menu title to indicate a keyboard + mnemonic. Pressing and releasing the Alt key switches to + menu-selection mode in the menu bar where mnemonic characters are + used for navigation. An Alt combination might select a specific menu + via @method[frame% on-menu-char]. A double-ampersand in + @scheme[label] is replaced by a literal (non-navigation) + ampersand. Under X and Mac OS X, ampersands in the label are parsed + in the same way as for Windows, but no mnemonic underline is + displayed. + +If @scheme[help] is not @scheme[#f], the menu has a help string. See +@method[labelled-menu-item<%> get-help-string] for more information. + +The @scheme[demand-callback] procedure is called by the default +@method[menu-item-container<%> on-demand] method with the object itself. + +\index{``About'' boxes} \index{``Help'' menus} +If the menu has the label ``Help'' in a menu bar, it is treated + specially on some platforms. Under Mac OS X, the items of a + ``Help'' menu are folded into the standard help menu. In addition, + under Mac OS X, if the name of the first item in the ``Help'' + menu starts with ``About'', then the menu item is duplicated as the + first item under the Apple menu. + + + +}} + diff --git a/collects/scribblings/gui/menu-item-class.scrbl b/collects/scribblings/gui/menu-item-class.scrbl new file mode 100644 index 0000000000..78bcdfa866 --- /dev/null +++ b/collects/scribblings/gui/menu-item-class.scrbl @@ -0,0 +1,45 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[menu-item% object% (selectable-menu-item<%>)]{ + +A @scheme[menu-item%] is a plain string-labelled menu item. Its + parent must be a @scheme[menu%] or @scheme[popup-menu%]. When the + user selects the menu item, its callback procedure is called. + + + + +@defconstructor[[label label-string?] + [parent @scheme[menu%] or @scheme[popup-menu%] object] + [callback procedure of two arguments: a @scheme[menu-item%] object and a @scheme[control-event%] object] + [shortcut (or/c character false/c) #f] + [help-string (or/c label-string? false/c) #f] + [demand-callback procedure of one argument: a @scheme[menu-item%] object @scheme[void]] + [shortcut-prefix (symbols/c option shift ctl meta cmd alt) @scheme[(\iscmprocedure{get-default-shortcut-prefix])}]]{ + +Creates a new menu item in @scheme[parent]. The item is initially shown, + appended to the end of its parent. The @scheme[callback] procedure is + called (with the event type @indexed-scheme['menu]) when the user selects + the menu item (either via a menu bar, +@xmethod[window<%> popup-menu], or +@xmethod[editor-admin% popup-menu]). + +See +@method[labelled-menu-item<%> set-label] for information about mnemonic ampersands (``\&'') in @scheme[label]. + +If @scheme[shortcut] is not @scheme[#f], the item has a shortcut. See +@method[selectable-menu-item<%> get-shortcut] for more information. The @scheme[shortcut-prefix] argument determines the +set of modifier keys for the shortcut; see +@method[selectable-menu-item<%> get-shortcut-prefix]. + +If @scheme[help] is not @scheme[#f], the item has a help string. See +@method[labelled-menu-item<%> get-help-string] for more information. + +The @scheme[demand-callback] procedure is called by the default +@method[menu-item-container<%> on-demand] method with the object itself. + + + +}} + diff --git a/collects/scribblings/gui/menu-item-container-intf.scrbl b/collects/scribblings/gui/menu-item-container-intf.scrbl new file mode 100644 index 0000000000..61af56acf0 --- /dev/null +++ b/collects/scribblings/gui/menu-item-container-intf.scrbl @@ -0,0 +1,50 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@definterface[menu-item-container<%> ()]{ + +A @scheme[menu-item-container<%>] object is a @scheme[menu%], + @scheme[popup-menu%], or @scheme[menu-bar%]. + + + + +@defmethod[(get-items) + list of @scheme[menu-item<%>] objects]{ +@spec{ + +Returns a list of the items in the menu, popup menu, or menu bar. The + order of the items in the returned list corresponds to the order as + the user sees them in the menu or menu bar. + +}} + +@defmethod[(on-demand) + void?]{ +@spec{ + +Called when the user clicks on the container as a menu bar (before the + user sees any menu items), just before the container as a popup menu + is popped up, or just before inspecting the menu bar containing the + item for a shortcut key binding. + +If the container is not a menu bar or a popup menu, this method is + normally called via the +@method[menu-item-container<%> on-demand] method of the container's owning menu bar or popup menu, because the + default implementation of the method chains to the +@method[labelled-menu-item<%> on-demand] method of its items. However, the method can be overridden in a + container such that it does not call the +@method[labelled-menu-item<%> on-demand] method of its items. + +} +@impl{ + +Calls the @scheme[demand-callback] procedure that was provided when the + object was created, then calls the +@method[labelled-menu-item<%> on-demand] method of the contained items. + + + + +}}} + diff --git a/collects/scribblings/gui/menu-item-intf.scrbl b/collects/scribblings/gui/menu-item-intf.scrbl new file mode 100644 index 0000000000..8d0b128b55 --- /dev/null +++ b/collects/scribblings/gui/menu-item-intf.scrbl @@ -0,0 +1,69 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@definterface[menu-item<%> ()]{ + +A @scheme[menu-item<%>] object is an element within a @scheme[menu%], + @scheme[popup-menu%], or @scheme[menu-bar%]. Operations that + affect the parent --- such as renaming the item, deleting the item, or + adding a check beside the item --- are accomplished via the + \scmintf{menu-item} object. + +A menu item is either a @scheme[separator-menu-item%] object (merely + a separator), of a @scheme[labelled-menu-item<%>] object; the latter + is more specifically an instance of either @scheme[menu-item%] (a + plain menu item), @scheme[checkable-menu-item%] (a checkable menu + item), or @scheme[menu%] (a submenu). + + + + +@defmethod[(get-parent) + @scheme[menu%], @scheme[popup-menu%], or @scheme[menu-bar%] object]{ +@spec{ + +Returns the menu, popup menu, or menu bar containing the item. The + parent for a menu item is specified when the menu item is created, + and it cannot be changed. + +}} + +@defmethod[(delete) + void?]{ +@spec{ + +Removes the item from its parent. If the menu item is already deleted, +@method[menu-item<%> delete] has no effect. + +See also +@method[menu-item<%> restore]. + + +}} + +@defmethod[(restore) + void?]{ +@spec{ + +Adds a deleted item back into its parent. The item is always restored + to the end of the parent, regardless of its original position. If the + item is not currently deleted, +@method[menu-item<%> restore] has no effect. + +}} + +@defmethod[(is-deleted?) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the menu item is deleted from its parent, + @scheme[#f] otherwise. + +} +@impl{ + + + + +}}} + diff --git a/collects/scribblings/gui/message-class.scrbl b/collects/scribblings/gui/message-class.scrbl new file mode 100644 index 0000000000..820b963046 --- /dev/null +++ b/collects/scribblings/gui/message-class.scrbl @@ -0,0 +1,53 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[message% object% (control<%>)]{ + +A message control is a static line of text or a static bitmap. The + text or bitmap corresponds to the message's label (see +@method[window<%> set-label]). + + + + +@defconstructor[[label {\labelstring}, @scheme[bitmap%] object, @scheme['app], @scheme['caution], or @scheme['stop]] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [style (symbols/c deleted) null] + [font (is-a/c font%) @scheme[normal-control-font]] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 2] + [horiz-margin (integer-in 0 1000) 2] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #f] + [stretchable-height any/c #f]]{ + +Creates a string or bitmap message initially showing @scheme[label]. + @bitmaplabeluse[label] An @indexed-scheme['app], @indexed-scheme['caution], + or @indexed-scheme['stop] symbol for @scheme[label] indicates an icon; + @scheme['app] is the application icon (Windows and Mac OS X) or a + generic ``info'' icon (X), @scheme['caution] is a caution-sign icon, + and @scheme['stop] a stop-sign icon. + +@labelstripped[(scheme label) @elem{message}] + +\DeletedStyleNote{message} + +@FontKWs[] @WindowKWs[] @SubareaKWs[] @AreaKWs[] + + + +} + +@defmethod[#:mode 'add + (set-label [label (is-a/c bitmap%)]) + void?]{ +@impl{ + +Sets the bitmap label for a bitmap message. + @bitmaplabeluseisbm[label] @|bitmapiforiglabel| + + + +}}} + diff --git a/collects/scribblings/gui/miscwin-funcs.scrbl b/collects/scribblings/gui/miscwin-funcs.scrbl new file mode 100644 index 0000000000..3fea5f88b8 --- /dev/null +++ b/collects/scribblings/gui/miscwin-funcs.scrbl @@ -0,0 +1,445 @@ +#reader(lib "docreader.ss" "scribble") +@require["common.ss"] +@require[(lib "struct.ss" "scribble")] + +@define[(atable . l) + (make-table #f (map (lambda (i) + (map (lambda (e) + (make-flow (list (make-paragraph (list e))))) + i)) + l))] +@define[(tline l r) (list (hspace 2) l (hspace 1) 'rarr (hspace 1) r)] + + +@title{Miscellaneous} + +@defproc[(bell) + void?]{ + +Rings the system bell. + + + +} + +@defproc[(play-sound [filename path] + [async? any/c]) + boolean?]{ + +Plays a sound file. If @scheme[async?] is false, the function does not + return until the sound completes. Otherwise, it returns immediately. + The result is @scheme[#t] if the sound plays successfully, @scheme[#f] + otherwise. + +Under Windows, only @file{.wav} files are supported. + +Under X, the function invokes an external sound-playing program; + looking for a few known programs (@exec{aplay}, @exec{play}, + @exec{esdplay}, @exec{sndfile-play}, @exec{audioplay}). In addition, a + play command can be defined through the @ResourceFirst{playcmd} + preference (see @|mrprefsdiscuss|). The preference can hold a + program name, or a format string containing a single @litchar{~a} + where the filename should be substituted---and used as a shell + command. (Don't use @litchar{~s}, since the string that is used + with the format string will be properly quoted and wrapped in double + quotes.) A plain command name is usually better since execution is + faster. The command's output is discarded, unless it returns an + error code---in this case the last part of the error output is + shown. + +Under Mac OS X, Quicktime is used to play sounds; most sound + formats (.wav, .aiff, .mp3) are supported in recent versions of + Quicktime. In order to play .wav files, Quicktime 3.0 (compatible + with OS 7.5 and up) is required. + + + +} + +@defproc[(begin-busy-cursor) + void?]{ + +Changes the cursor to a watch cursor for all windows in the current eventspace. +Use +@scheme[end-busy-cursor] to revert the cursor back to its previous state. Calls to +@scheme[begin-busy-cursor] and +@scheme[end-busy-cursor] can be nested arbitrarily. + +The cursor installed by +@scheme[begin-busy-cursor] overrides any window-specific cursors installed with +@method[window<%> set-cursor]. + +See also +@scheme[is-busy?]. + + + +} + +@defproc[(end-busy-cursor) + void?]{ + +See +@scheme[begin-busy-cursor]. + + + +} + +@defproc[(is-busy?) + boolean?]{ + +Returns @scheme[#t] if a busy cursor has been installed with +@scheme[begin-busy-cursor] and not removed with +@scheme[end-busy-cursor]. + + + +} + +@defproc[(hide-cursor-until-moved) + void?]{ + +Hides the cursor until the user moves the mouse or clicks the mouse + button. (For some platforms, the cursor is not hidden if it is over + a window in a different eventspace or application.) + + + +} + +@defproc[(send-message-to-window [x (integer-in -10000 10000)] + [y (integer-in -10000 10000)] + [message any/c]) + any/c]{ + +@index['("drag-and-drop")]{Finds} the frontmost top-level window at + (@scheme[x], @scheme[y]) in global coordinates. If a window is there, + this function calls the window's @method[top-level-window<%> + on-message] method, providing @scheme[message] as the method's + argument; the result of the function call is the result returned by + the method. If no MrEd window is at the given coordinates, or if it + is covered by a non-MrEd window at (@scheme[x], @scheme[y]), + @scheme[#f] is returned. + + + +} + +@defproc[(get-resource [section string] + [entry string] + [value (boxof exact-integer?)] + [file (or/c path false/c) #f]) + boolean?]{ + +Gets a resource value from the resource database. The resource value + is keyed on the combination of @scheme[section] and @scheme[entry]. The + return value is @scheme[#t] is a value is found, @scheme[#f] if it is + not. The type of the value initially in the @scheme[value] box + determines the way that the resource is interpreted, and @scheme[value] + is filled with a new value of the same type if one is found. + +If @scheme[file] is @scheme[#f], platform-specific resource files + are read, as determined by @scheme[find-graphical-system-path] + with @indexed-scheme['setup-file]. (Under X, when @scheme[file] is + @scheme[#f], the user's @file{.Xdefaults} file is also read, or the + file specified by the @file{XENVIRONMENT} environment variable.) + +The format of a resource entry depends on the platform. Windows + resources use the standard @file{.ini} format. X and Mac OS X + resources use the standard X resource format, where each entry + consists of a @scheme[section].@scheme[entry] resource name, a colon, and + the resource value, terminated by a newline. Section and entry names are + case-sensitive. + +@index['("registry")]{@index['("Windows registry")]{Under}} Windows, if + @scheme[section] is one of the following strings, then @scheme[file] + is ignored, and @scheme[entry] is used as a resource path: + +@itemize{ + + @item{@indexed-scheme["HKEY_CLASSES_ROOT"]} + @item{@indexed-scheme["HKEY_CURRENT_CONFIG"]} + @item{@indexed-scheme["HKEY_CURRENT_USER"]} + @item{@indexed-scheme["HKEY_LOCAL_MACHINE"]} + @item{@indexed-scheme["HKEY_USERS"]} + +} + +In that case, the @scheme[entry] argument is parsed as a resource entry +path, followed by a backslash, followed by a value name. To get the +``default'' value for an entry, use the empty name. For example, the +following expression gets a command line for starting a browser: + +@schemeblock[ +(let ([b (box "")]) + (get-resource "HKEY_CLASSES_ROOT" + "htmlfile\\shell\\open\\command\\" b) + (unbox b)) +] + +See also @scheme[write-resource].} + + +@defproc[(label->plain-label [label string]) + string]{ + +Strips shortcut ampersands from @scheme[label], removes parenthesized + ampersand--character combinations along with any surrounding space, + and removes anything after a tab. Overall, it returns the label as it would + appear on a button on a platform without support for menmonics. + +} + +@defproc[(write-resource [section string] + [entry string] + [value (or/c string? exact-integer?)] + [file (or/c path false/c) #f]) + boolean?]{ + +Writes a resource value to the specified resource database. The + resource value is keyed on the combination of @scheme[section] and + @scheme[entry], with the same special handling of @scheme[entry] for + under Windows as for @scheme[get-resource]. + +If @scheme[file] is @scheme[#f], the platform-specific resource + database is read, as determined by + @scheme[find-graphical-system-path] with + @indexed-scheme['setup-file]. + +The return value is @scheme[#t] if the write succeeds, @scheme[#f] + otherwise. (A failure indicates that the resource file cannot be + written.) + +If @scheme[value] is an integer outside a platform-specific range, + @|MismatchExn|. + +See also @scheme[get-resource].} + + +@defproc[(get-default-shortcut-prefix) + (listof (symbols/c option shift ctl meta cmd alt))]{ +Returns an immutable list specifying the default prefix for menu +shortcuts. See also +@xmethod[selectable-menu-item<%> get-shortcut-prefix]. + +Under Windows, the default is @scheme['(ctl)]. Under Mac OS X, the +default is @scheme['(cmd)]. Under X, the default is normally +@scheme['(ctl)], but the default can be changed through the +@Resource{defaultMenuPrefix} low-level preference (see +@|mrprefsdiscuss|).} + +@defproc[(find-graphical-system-path [what (symbols/c x-display setup-file init-file)]) + (or/c path false/c)]{ + +Finds a platform-specific (and possibly user- or machine-specific) + standard filename or directory. See also @scheme[find-system-path]. + +The result depends on @scheme[what], and a @scheme[#f] result is only + possible when @scheme[what] is @scheme['x-display]: + +@itemize{ + + @item{@scheme['init-file] returns the path to the user-specific + initialization file (containing Scheme code). The directory part of + the path is the same path as returned for @scheme['init-dir] by + MzScheme's @scheme[find-system-path]. The file name is + platform-specific: + @itemize{ + + @item{@|AllUnix|: @indexed-file{.mredrc}} + @item{Windows: @indexed-file{mredrc.ss}} + + }} + + @item{@scheme['setup-file] returns the path to the file + containing resources used by @scheme[get-resource]; obsolete.} + + @item{@scheme['x-display] returns a ``path'' whose string identifies + the X display if specified by either the @Flag{display} flag or the + @envvar{DISPLAY} environment variable when MrEd starts under X. For + other platforms, or when neither @Flag{display} nor @envvar{DISPLAY} + was specified, the result is @scheme[#f].} + +} + + + +} + +@defproc[(graphical-read-eval-print-loop [eval-eventspace eventspace #f] + [redirect-ports? any/c @scheme[(not @scheme[eval-eventspace])]]) + void?]{ + +Similar to MzScheme's @scheme[read-eval-print-loop], except that none of + @scheme[read-eval-print-loop]'s configuration parameters are used (such + as @scheme[current-read]) and the interaction occurs in a GUI window + instead of using the current input and output ports. + +Expressions entered into the graphical read-eval-print loop can be + evaluated in an eventspace (and thread) that is distinct from the one + implementing the @scheme[graphical-read-eval-print-loop] + window (i.e., the current eventspace when + @scheme[graphical-read-eval-print-loop] is called). + +If no eventspace is provided, or if @scheme[#f] is provided, an + evaluation eventspace is created using @scheme[(make-eventspace)] + with a new custodian; the eventspace and its threads are be shut down + when the user closes the @scheme[graphical-read-eval-print-loop] + window. If an eventspace is provided, closing the window performs no + shut-down actions on eventspace. + +When @scheme[redirect-ports?] is true, the following parameters are + initialized in the created eventspace's handler thread: +@itemize{ + + @item{@scheme[current-output-port] --- writes to the frame} + @item{@scheme[current-error-port] --- writes to the frame} + @item{@scheme[current-input-port] --- always returns @scheme[eof]} + +} + +The keymap for the read-eval-print loop's editor is initialized by + calling the current keymap initializer procedure, which is determined + by the +@scheme[current-text-keymap-initializer] parameter. + + +} + +@defthing[the-clipboard (is-a/c clipboard<%>)]{ + +See @scheme[clipboard<%>]. + + +} + +@defthing[the-x-selection-clipboard (is-a/c clipboard<%>)]{ + +See @scheme[clipboard<%>]. + + +} + +@defproc[(get-window-text-extent [string string] + [font (is-a/c font%)]) + (values nonnegative-exact-integer? + nonnegative-exact-integer?)]{ + +Returns the pixel size of a string drawn as a window's label or value +when drawn with the given font. + +See also @method[dc<%> get-text-extent]. +} + +@defproc[(get-panel-background) + (is-a/c color%)]{ + +Returns the background color of a panel (usually some shade of gray) + for the current platform. + +} + +@defproc*[([(file-creator-and-type [filename path] + [creator-string (lambda (s) (and (bytes? s) + (= 4 (bytes-length s))))] + [type-bytes (lambda (s) (and (bytes? s) + (= 4 (bytes-length s))))]) + void?] + [(file-creator-and-type [filename path]) + (values (lambda (s) (and (bytes? s) + (= 4 (bytes-length s)))) + (lambda (s) (and (bytes? s) + (= 4 (bytes-length s)))))])]{ + +Gets or sets the creator and type of a file in Mac OS X. + +The get operation always returns @scheme[#"????"] and @scheme[#"????"] for + Unix or Windows. The set operation has no effect under Unix or + Windows. +} + +@defproc[(send-event [receiver-bytes (lambda (s) (and (bytes? s) + (= 4 (bytes-length s))))] + [event-class-bytes (lambda (s) (and (bytes? s) + (= 4 (bytes-length s))))] + [event-id-bytes (lambda (s) (and (bytes? s) + (= 4 (bytes-length s))))] + [direct-arg-v any/c (void)] + [argument-list list null]) + any/c]{ + +Sends an AppleEvent or raises @scheme[exn:fail:unsupported]. + +The @scheme[receiver-bytes], @scheme[event-class-bytes], and +@scheme[event-id-bytes] arguments specify the signature of the +receiving application, the class of the AppleEvent, and the ID of +the AppleEvent. + +The @scheme[direct-arg-v] value is converted (see below) and passed as +the main argument of the event; if @scheme[direct-argument-v] is +@|void-const|, no main argument is sent in the event. The +@scheme[argument-list] argument is a list of two-element lists +containing a typestring and value; each typestring is used ad the +keyword name of an AppleEvent argument for the associated converted +value. + +The following types of MzScheme values can be converted to AppleEvent +values passed to the receiver: + +@atable[ +(tline @elem{@scheme[#t] or @scheme[#f]} @elem{Boolean}) +(tline @elem{small integer} @elem{Long Integer}) +(tline @elem{inexact real number} @elem{Double}) +(tline @elem{string} @elem{Characters}) +(tline @elem{list of convertible values} @elem{List of converted values}) +(tline @scheme[#(file _pathname)] @elem{Alias (file exists) or FSSpec (does not exist)}) +(tline @scheme[#(record (_typestring _v) ...)] @elem{Record of keyword-tagged values}) +] + +If other types of values are passed to @scheme[send-event] for + conversion, the @exnraise[exn:fail:unsupported]. + +The @scheme[send-event] procedure does not return until the receiver +of the AppleEvent replies. The result of @scheme[send-event] is the +reverse-converted reply value (see below), or the @exnraise[exn:fail] +if there is an error. If there is no error or return value, +@scheme[send-event] returns @|void-const|. + +The following types of AppleEvent values can be reverse-converted into +a MzScheme value returned by @scheme[send-event]: + +@atable[ +(tline @elem{Boolean} @elem{@scheme[#t] or @scheme[#f]}) +(tline @elem{Signed Integer} @elem{integer}) +(tline @elem{Float, Double, or Extended} @elem{inexact real number}) +(tline @elem{Characters} @elem{string}) +(tline @elem{List of reverse-convertible values} @elem{list of reverse-converted values}) +(tline @elem{Alias or FSSpec} @scheme[#(file _pathname)]) +(tline @elem{Record of keyword-tagged values} @scheme[#(record (_typestring _v) ...)]) +] + +If the AppleEvent reply contains a value that cannot be + reverse-converted, the @exnraise[exn:fail]. + +} + +@defproc[(make-namespace-with-mred [flag (symbols/c empty initial mred) 'mred]) + namespace]{ + +Like @scheme[make-namespace], but the @scheme[(lib "mred.ss" + "mred")] module of the current namespace is attached. In addition, by + default, the namespace is initialized by importing the @file{mred.ss} + module and MzLib's @indexed-file{class.ss} module into the + namespace's top-level environment. + + +The @scheme['initial] and @scheme['empty] flags control the namespace + creation in the same way as for @scheme[make-namespace], except that + the @file{mred.ss} module is attached to the created namespace (along + with the transitive closure of its imports). The @scheme['mred] flag + is like @scheme['initial], but also imports the @file{mred.ss} module + and MzLib's @indexed-file{class.ss} module into the namespace's + top-level environment. + +} \ No newline at end of file diff --git a/collects/scribblings/gui/mouse-event-class.scrbl b/collects/scribblings/gui/mouse-event-class.scrbl new file mode 100644 index 0000000000..166e14ae70 --- /dev/null +++ b/collects/scribblings/gui/mouse-event-class.scrbl @@ -0,0 +1,365 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[mouse-event% event% ()]{ + +A @scheme[mouse-event%] object encapsulates a mouse event. + Mouse events are primarily processed by +@xmethod[window<%> on-subwindow-event] and +@xmethod[canvas<%> on-event]. + +See also @|mousekeydiscuss|. + + + + +@defconstructor[[event-type (symbols/c motion right-up right-down middle-up middle-down left-up left-down leave enter)] + [left-down any/c #f] + [middle-down any/c #f] + [right-down any/c #f] + [x (and/c exact? integer?) 0] + [y (and/c exact? integer?) 0] + [shift-down any/c #f] + [control-down any/c #f] + [meta-down any/c #f] + [alt-down any/c #f] + [time-stamp (and/c exact? integer?) 0] + [caps-down any/c #f]]{ + +Creates a mouse event for a particular type of event. The event types + are: +@itemize{ +@item{@scheme['enter] --- mouse pointer entered the window} +@item{@scheme['leave] --- mouse pointer left the window} +@item{@scheme['left-down] --- left mouse button pressed} +@item{@scheme['left-up] --- left mouse button released} +@item{@scheme['middle-down] --- middle mouse button pressed} +@item{@scheme['middle-up] --- middle mouse button released} +@item{@scheme['right-down] --- right mouse button pressed (Mac OS X: click with control key pressed)} +@item{@scheme['right-up] --- right mouse button released (Mac OS X: release with control key pressed)} +@item{@scheme['motion] --- mouse moved, with or without button(s) pressed} +} + +See the corresponding @scheme[get-] and @scheme[set-] methods for + information about @scheme[left-down], @scheme[middle-down], + @scheme[right-down], @scheme[x], @scheme[y], @scheme[shift-down], + @scheme[control-down], @scheme[meta-down], @scheme[alt-down], + @scheme[time-stamp], and @scheme[caps-down]. + + + +} + +@defmethod[(get-control-down) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the Control key was down for the event. + +Under Mac OS X, if a control-key press is combined with a mouse button + click, the event is reported as a right-button click and +@method[mouse-event% get-control-down] for the event reports @scheme[#f]. + +}} + +@defmethod[(set-control-down [down? any/c]) + void?]{ +@spec{ + +Sets whether the Control key was down for the event. + +Under Mac OS X, if a control-key press is combined with a mouse button + click, the event is reported as a right-button click and +@method[mouse-event% get-control-down] for the event reports @scheme[#f]. + +}} + +@defmethod[(get-shift-down) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the Shift key was down for the event. + +}} + +@defmethod[(set-shift-down [down? any/c]) + void?]{ +@spec{ + +Sets whether the Shift key was down for the event. + +}} + +@defmethod[(get-alt-down) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the Option (Mac OS X) key was down for + the event. When the Alt key is pressed in Windows, it is reported as + a Meta press (see +@method[mouse-event% get-meta-down]). + +}} + +@defmethod[(set-alt-down [down? any/c]) + void?]{ +@spec{ + +Sets whether the Option (Mac OS X) key was down for the event. + When the Alt key is pressed in Windows, it is reported as + a Meta press (see +@method[mouse-event% set-meta-down]). + +}} + +@defmethod[(get-meta-down) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the Meta (X), Alt (Windows), or Command (Mac OS X) + key was down for the event. + +}} + +@defmethod[(set-meta-down [down? any/c]) + void?]{ +@spec{ + +Sets whether the Meta (X), Alt (Windows), or Command (Mac OS X) key was + down for the event. + +}} + +@defmethod[(get-caps-down) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the Caps Lock key was on for the event. + +}} + +@defmethod[(set-caps-down [down? any/c]) + void?]{ +@spec{ + +Sets whether the Caps Lock key was on for the event. + +}} + +@defmethod[(get-event-type) + (symbols/c motion right-up right-down middle-up middle-down left-up left-down leave enter)]{ +@spec{ + +Returns the type of the event; see +@scheme[mouse-event%] for information about each event type. See also +@method[mouse-event% set-event-type] . + +}} + +@defmethod[(set-event-type [event-type (symbols/c motion right-up right-down middle-up middle-down left-up left-down leave enter)]) + void?]{ +@spec{ + +Sets the type of the event; see +@scheme[mouse-event%] for information about each event type. See also +@method[mouse-event% get-event-type] . + +}} + +@defmethod[(get-left-down) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the left mouse button was down (but not pressed) during the event. + +}} + +@defmethod[(set-left-down [down? any/c]) + void?]{ +@spec{ + +Sets whether the left mouse button was down (but not pressed) during the event. + +}} + +@defmethod[(get-middle-down) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the middle mouse button was down (but not pressed) for the event. + Under Mac OS X, a middle-button click is impossible. + +}} + +@defmethod[(set-middle-down [down? any/c]) + void?]{ +@spec{ + +Sets whether the middle mouse button was down (but not pressed) for + the event. Under Mac OS X, a middle-button click is impossible. + +}} + +@defmethod[(get-right-down) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the right mouse button was down (but not pressed) + for the event. Under Mac OS X, a control-click combination is treated as + a right-button click. + +}} + +@defmethod[(set-right-down [down? any/c]) + void?]{ +@spec{ + +Sets whether the right mouse button was down (but not pressed) for the + event. Under Mac OS X, a control-click combination by the user is + treated as a right-button click. + +}} + +@defmethod[(get-x) + (and/c exact? integer?)]{ +@spec{ + +Returns the x-position of the mouse at the time of the event, in the + target's window's (client-area) coordinate system. + +}} + +@defmethod[(set-x [pos (and/c exact? integer?)]) + void?]{ +@spec{ + +Sets the x-position of the mouse at the time of the event in the + target's window's (client-area) coordinate system. + +}} + +@defmethod[(get-y) + (and/c exact? integer?)]{ +@spec{ + +Returns the y-position of the mouse at the time of the event in the + target's window's (client-area) coordinate system. + +}} + +@defmethod[(set-y [pos (and/c exact? integer?)]) + void?]{ +@spec{ + +Sets the y-position of the mouse at the time of the event in the + target's window's (client-area) coordinate system. + +}} + +@defmethod[(button-down? [button (symbols/c any right middle left) 'any]) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the event is for a button press, @scheme[#f] + otherwise. + +} +@impl{ + +If @scheme[button] is not @scheme['any], then @scheme[#t] is only returned + if it is a press event for a specific button. + + +}} + +@defmethod[(button-up? [button (symbols/c any right middle left) 'any]) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the event is for a button release, @scheme[#f] + otherwise. (As noted in @|mousekeydiscuss|, button release events are + sometimes dropped.) + +} +@impl{ + +If @scheme[button] is not @scheme['any], then @scheme[#t] is only returned + if it is a release event for a specific button. + + +}} + +@defmethod[(dragging?) + boolean?]{ +@spec{ + +Returns @scheme[#t] if this was a dragging event (motion while a button + is pressed), @scheme[#f] otherwise. + +}} + +@defmethod[(entering?) + boolean?]{ +@spec{ + +Returns @scheme[#t] if this event is for the mouse entering a window, + @scheme[#f] otherwise. + +When the mouse button is up, an enter/leave event notifies a window + that it will start/stop receiving mouse events. When the mouse button + is down, however, the window receiving the mouse-down event receives + all mouse events until the button is released; enter/leave events are + not sent to other windows, and are not reliably delivered to the + click-handling window (since the window can detect movement out of + its region via +@method[mouse-event% get-x] and +@method[mouse-event% get-y]). See also @|mousekeydiscuss|. + +}} + +@defmethod[(leaving?) + boolean?]{ +@spec{ + +Returns @scheme[#t] if this event is for the mouse leaving a window, + @scheme[#f] otherwise. + +See +@method[mouse-event% entering?] for information about enter and leave events while the mouse button is + clicked. + +}} + +@defmethod[(button-changed? [button (symbols/c any right middle left) 'any]) + boolean?]{ +@spec{ + +Returns @scheme[#t] if this was a mouse button press or release event, + @scheme[#f] otherwise. See also +@method[mouse-event% button-up?] and +@method[mouse-event% button-down?]. + +} +@impl{ + +If @scheme[button] is not @scheme['any], then @scheme[#t] is only returned + if it is a release event for a specific button. + + + +}} + +@defmethod[(moving?) + boolean?]{ +@spec{ + +Returns @scheme[#t] if this was a moving event (whether a button is + pressed is not), @scheme[#f] otherwise. + +} +@impl{ + + + +}}} + diff --git a/collects/scribblings/gui/pane-class.scrbl b/collects/scribblings/gui/pane-class.scrbl new file mode 100644 index 0000000000..12443972eb --- /dev/null +++ b/collects/scribblings/gui/pane-class.scrbl @@ -0,0 +1,36 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[pane% object% (area-container<%> subarea<%>)]{ + +A pane is a both a container and a containee area. It serves only + as a geometry management device. A @scheme[pane%] + cannot be hidden or disabled like a @scheme[panel%] object. + +A @scheme[pane%] object has a degenerate placement strategy for + managing its children; it places them all in the upper left corner + and does not stretch any of them. The @scheme[horizontal-pane%] and + @scheme[vertical-pane%] classes provide useful geometry management. + +See also @scheme[grow-box-spacer-pane%]. + + + + +@defconstructor[[parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [vert-margin (integer-in 0 1000) 0] + [horiz-margin (integer-in 0 1000) 0] + [border (integer-in 0 1000) 0] + [spacing (integer-in 0 1000) 0] + [alignment two-element list: @scheme['left], @scheme['center], or @scheme['right] and @scheme['top], @scheme['center], or @scheme['bottom] '(center center)] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #t] + [stretchable-height any/c #t]]{ + +@SubareaKWs[] @AreaContKWs[] @AreaKWs[] + + + +}} + diff --git a/collects/scribblings/gui/panel-class.scrbl b/collects/scribblings/gui/panel-class.scrbl new file mode 100644 index 0000000000..40dc68978b --- /dev/null +++ b/collects/scribblings/gui/panel-class.scrbl @@ -0,0 +1,42 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[panel% object% (area-container-window<%> subwindow<%>)]{ + +A panel is a both a container and a containee window. It serves mainly + as a geometry management device, but the @scheme['border] creates a + container with a border. Unlike a @scheme[pane%] object, a @scheme[panel%] + object can be hidden or disabled. + +A @scheme[panel%] object has a degenerate placement strategy for + managing its children; it places them all in the upper left corner + and does not stretch any of them. The @scheme[horizontal-panel%] + and @scheme[vertical-panel%] classes provide useful geometry + management. + + + + +@defconstructor[[parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [style (symbols/c deleted border) null] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 0] + [horiz-margin (integer-in 0 1000) 0] + [border (integer-in 0 1000) 0] + [spacing (integer-in 0 1000) 0] + [alignment two-element list: @scheme['left], @scheme['center], or @scheme['right] and @scheme['top], @scheme['center], or @scheme['bottom] '(center center)] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #t] + [stretchable-height any/c #t]]{ + +If the @scheme['border] style is specified, the window is created with + a thin border (only in this case, the client size of the panel may be + less than its total size). \DeletedStyleNote{panel} + +@WindowKWs[] @SubareaKWs[] @AreaContKWs[] @AreaKWs[] + + + +}} + diff --git a/collects/scribblings/gui/popup-menu-class.scrbl b/collects/scribblings/gui/popup-menu-class.scrbl new file mode 100644 index 0000000000..9c3053b844 --- /dev/null +++ b/collects/scribblings/gui/popup-menu-class.scrbl @@ -0,0 +1,87 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[popup-menu% object% (menu-item-container<%>)]{ + +A @scheme[popup-menu%] object is created without a + parent. Dynamically display a @scheme[popup-menu%] with +, +@xmethod[window<%> popup-menu], or +@xmethod[editor-admin% popup-menu]. + +A popup menu is {\em not} a control. A @scheme[choice%] control, + however, displays a single value that the user selects from a popup + menu. A @scheme[choice%] control's popup menu is built into the + control, and it is not accessible to the programmer. + + + + +@defconstructor[[title (or/c label-string? false/c) #f] + [popdown-callback procedure of two arguments: a @scheme[popup-menu%] object and a @scheme[control-event%] object @scheme[(\scmk{lambda] (@scheme[m] @scheme[e]) (void))}] + [demand-callback procedure of one argument: a @scheme[popup-menu%] object @scheme[void]] + [font (is-a/c font%) @scheme[normal-control-font]]]{ + +If @scheme[title] is not @scheme[#f], it is used as a displayed title at + the top of the popup menu. + +If @scheme[title] contains an ampersand (``\&''), it is handled + specially, the same as for @scheme[menu%] titles. A popup menu + mnemonic is not useful, but it is supported for consistency with + other menu labels. + +The @scheme[popdown-callback] procedure is invoked when a popup menu is + dismissed. If the popup menu is dismissed without an item being + selected, @scheme[popdown-callback] is given a @scheme[control-event%] + object with the event type @indexed-scheme['menu-popdown-none]. If the + popup menu is dismissed via an item selection, the item's callback is + invoked first, and then @scheme[popdown-callback] is given a + @scheme[control-event%] object with the event type + @indexed-scheme['menu-popdown]. + +The @scheme[demand-callback] procedure is called by the default +@method[menu-item-container<%> on-demand] method with the object itself. + +The @scheme[font] argument determines the font for the popup menu's + items. + + + +} + +@defmethod[(get-popup-target) + (or/c (or/c (is-a/c window<%>) (is-a/c editor<%>)) false/c)]{ +@spec{ + +Returns the context in which the popup menu is currently displayed, or + @scheme[#f] if it is not popped up in any window. + +The context is set before the +@method[menu-item-container<%> on-demand] method is called, and it is not removed until after the popup-menu's + callback is invoked. (Consequently, it is also set while an item + callback is invoked, if the user selected an item.) + +}} + +@defmethod[(get-font) + (is-a/c font%)]{ +@spec{ + +Returns the font used for the popup menu's items, which is optionally + supplied when a popup menu is created. + +}} + +@defmethod[(set-min-width [width (integer-in 0 10000)]) + void?]{ +@spec{ + +Sets the popup menu's minimum width in pixels. + +} +@impl{ + + + +}}} + diff --git a/collects/scribblings/gui/radio-box-class.scrbl b/collects/scribblings/gui/radio-box-class.scrbl new file mode 100644 index 0000000000..316db42b89 --- /dev/null +++ b/collects/scribblings/gui/radio-box-class.scrbl @@ -0,0 +1,196 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[radio-box% object% (control<%>)]{ + + +A @scheme[radio-box%] control allows the user to select one of + number of mutually exclusive items. The items are displayed as a + vertical column or horizontal row of labelled @defterm{radio + buttons}. Unlike a @scheme[list-control<%>], the set of items in a + @scheme[radio-box%] cannot be changed dynamically. + +Whenever the user changes the selected radio button, the radio box's + callback procedure is invoked. A callback procedure is provided as an + initialization argument when each radio box is created. + + + + +@defconstructor[[label (or/c label-string? false/c)] + [choices list of {\labelstrings} or @scheme[bitmap%] objects] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [callback procedure of two arguments: a @scheme[radio-box%] object and a @scheme[control-event%] object @scheme[(\scmk{lambda] (@scheme[rb] @scheme[e]) (void))}] + [style (symbols/c deleted horizontal-label vertical-label vertical horizontal) '(vertical)] + [selection nonnegative-exact-integer? 0] + [font (is-a/c font%) @scheme[normal-control-font]] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 2] + [horiz-margin (integer-in 0 1000) 2] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #f] + [stretchable-height any/c #f]]{ + +Creates a radio button set with string or bitmap labels. The + @scheme[choices] list specifies the radio button labels; the list of + choices must be homogeneous, either all strings or all bitmaps. + +@labelstripped[(scheme label) @elem{} @elem{move the keyboard focus to the radio box}] + +Each string in @scheme[choices] can also contain an ampersand, which + creates a mnemonic for clicking the corresponding radio button. As + for @scheme[label], a double ampersand is converted to a single + ampersand. + +@bitmaplabelusearray[choices] + +If @scheme[label] is a string, it is used as the label for the radio + box. Otherwise, the radio box does not display its + label. + +The @scheme[callback] procedure is called (with the event type + @indexed-scheme['radio-box]) when the user changes the radio button + selection. + +The @scheme[style] argument must include either @scheme['vertical] for a + collection of radio buttons vertically arranged, or + @scheme['horizontal] for a horizontal arrangement. + \HVLabelNote{radio box} \DeletedStyleNote{radio box} + +By default, the first radio button is initially selected. If + @scheme[selection] is positive, it is passed to +@method[radio-box% set-selection] to set the initial radio button selection. + +@FontKWs[] @WindowKWs[] @SubareaKWs[] @AreaKWs[] + + + +} + +@defmethod*[#:mode 'override + ([(enable [enable? any/c]) + void?] + [(enable [n nonnegative-exact-integer?] + [enable? any/c]) + void?])]{ +@impl{ +First case: + + +If @scheme[enable?] is @scheme[#f], the entire radio box is disabled, + otherwise it is enabled. + + + +Second case: + + +If @scheme[enable?] is @scheme[#f], the @scheme[n]th radio button is disabled, + otherwise it is enabled (assuming the entire radio box is + enabled). Radio buttons are numbered from @scheme[0]. + If @scheme[n] is equal to or larger than the number of radio buttons in + the radio box, @|MismatchExn|}. + + + +}} + +@defmethod*[#:mode 'override + ([(is-enabled?) + boolean?] + [(is-enabled? [n nonnegative-exact-integer?]) + boolean?])]{ +@impl{ +First case: + + +Returns @scheme[#f] if the entire radio box is disabled, + @scheme[#t] otherwise. + + + +Second case: + + +Returns @scheme[#f] if @scheme[n]th radio button is disabled (independent of + disabling the entire radio box), @scheme[#t] otherwise. Radio buttons + are numbered from @scheme[0]. If @scheme[n] is equal to or larger than the + number of radio buttons in the radio box, @|MismatchExn|}. + + + +}} + +@defmethod[(get-selection) + nonnegative-exact-integer?]{ +@spec{ + +Gets the position of the selected radio button. Radio buttons are + numbered from @scheme[0]. + +}} + +@defmethod[(get-number) + nonnegative-exact-integer?]{ +@spec{ + +Returns the number of radio buttons in the radio box. + +}} + +@defmethod[(set-selection [n nonnegative-exact-integer?]) + void?]{ +@spec{ + +Sets the selected radio button by position. (The control's callback + procedure is {\em not} invoked.) Radio buttons are numbered from + @scheme[0]. + +@MonitorCallback[@elem{A radio box's selection} @elem{the user clicking the control} @elem{selection}] + +} +@impl{ + +If @scheme[n] is equal to or larger than the number of radio buttons in + the radio box, @|MismatchExn|}. + + + +}} + +@defmethod[(get-item-label [n nonnegative-exact-integer?]) + string]{ +@spec{ + +Gets the label of a radio button by position. Radio buttons are + numbered from @scheme[0]. + +} +@impl{ + +If @scheme[n] is equal to or larger than the number of radio buttons in + the radio box, @|MismatchExn|}. + + + +}} + +@defmethod[(get-item-plain-label [n nonnegative-exact-integer?]) + string]{ +@spec{ + +Like +@method[radio-box% get-item-label], except that the label must be a string and ampersands in the label + are removed. + +} +@impl{ + +If @scheme[n] is equal to or larger than the number of radio buttons in + the radio box, @|MismatchExn|}. + + + +}}} + diff --git a/collects/scribblings/gui/scroll-event-class.scrbl b/collects/scribblings/gui/scroll-event-class.scrbl new file mode 100644 index 0000000000..2f03262a1b --- /dev/null +++ b/collects/scribblings/gui/scroll-event-class.scrbl @@ -0,0 +1,104 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[scroll-event% event% ()]{ + +A @scheme[scroll-event%] object contains information about a scroll + event. An instance of @scheme[scroll-event%] is always provided to +@method[canvas% on-scroll]. + +See +@method[scroll-event% get-event-type] for a list of the scroll event types. + + + + +@defconstructor[[event-type (symbols/c thumb page-down page-up line-down line-up bottom top) 'thumb] + [direction (symbols/c vertical horizontal) 'vertical] + [position (integer-in 0 10000) 0] + [time-stamp (and/c exact? integer?) 0]]{ + +See the corresponding @scheme[get-] and @scheme[set-] methods for + information about @scheme[event-type], @scheme[direction], @scheme[position], + and @scheme[time-stamp]. + + + +} + +@defmethod[(get-event-type) + (symbols/c thumb page-down page-up line-down line-up bottom top)]{ +@spec{ + +Returns the type of the event, one of the following: +@itemize{ +@item{@scheme['top] --- user clicked a scroll-to-top button} +@item{@scheme['bottom] --- user clicked a scroll-to-bottom button} +@item{@scheme['line-up] --- user clicked an arrow to scroll up or left one step} +@item{@scheme['line-down] --- user clicked an arrow to scroll down or right one step} +@item{@scheme['page-up] --- user clicked an arrow to scroll up or left one page} +@item{@scheme['page-down] --- user clicked an arrow to scroll down or right one page} +@item{@scheme['thumb] --- user dragged the scroll position indicator} +} + +}} + +@defmethod[(set-event-type [type (symbols/c thumb page-down page-up line-down line-up bottom top)]) + void?]{ +@spec{ + +Sets the type of the event. See +@method[scroll-event% get-event-type] for information about each event type. + +}} + +@defmethod[(get-position) + (integer-in 0 10000)]{ +@spec{ + +Returns the position of the scrollbar after the action triggering the + event. See also +@method[scroll-event% set-position]. + +}} + +@defmethod[(set-position [position (integer-in 0 10000)]) + void?]{ +@spec{ + +Records the position of the scrollbar after the action triggering the + event. (The scrollbar itself is unaffected). See also +@method[scroll-event% get-position]. + +}} + +@defmethod[(get-direction) + (symbols/c vertical horizontal)]{ +@spec{ + +Gets the identity of the scrollbar that was modified by the event, + either the horizontal scrollbar or the vertical scrollbar, as + @scheme['horizontal] or @scheme['vertical], respectively. See + also +@method[scroll-event% set-direction]. + +}} + +@defmethod[(set-direction [direction (symbols/c vertical horizontal)]) + void?]{ +@spec{ + +Sets the identity of the scrollbar that was modified by the event, + either the horizontal scrollbar or the vertical scrollbar, as + @scheme['horizontal] or @scheme['vertical], respectively. See + also +@method[scroll-event% get-direction]. + +} +@impl{ + + + + +}}} + diff --git a/collects/scribblings/gui/selectable-menu-item-intf.scrbl b/collects/scribblings/gui/selectable-menu-item-intf.scrbl new file mode 100644 index 0000000000..741a67175f --- /dev/null +++ b/collects/scribblings/gui/selectable-menu-item-intf.scrbl @@ -0,0 +1,116 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@definterface[selectable-menu-item<%> (labelled-menu-item<%>)]{ + +A @scheme[selectable-menu-item<%>] object is a + @scheme[labelled-menu-item<%>] that the user can select. It may also + have a keyboard shortcut; the shortcut is displayed in the menu, and + the default +@method[frame% on-subwindow-char] method in the menu's frame dispatches to the menu item when the + shortcut key combination is pressed. + + + +@defmethod[(get-shortcut) + character, symbol, @scheme[#f]]{ +@spec{ + +Gets the keyboard shortcut character or virtual key for the menu + item. This character or key is combined with the shortcut prefix, + which is reported by +@method[selectable-menu-item<%> get-shortcut-prefix]. + +If the menu item has no shortcut, @scheme[#f] is returned. + +The shortcut part of a menu item name is not included in the label + returned by +@method[labelled-menu-item<%> get-label]. + +For a list of allowed key symbols, see +@xmethod[key-event% get-key-code] . + +}} + +@defmethod[(set-shortcut [shortcut (or/c character, symbol, false/c)]) + void?]{ +@spec{ + +Sets the keyboard shortcut character for the menu item. See +@method[selectable-menu-item<%> get-shortcut] for more information. + +If the shortcut character is set to @scheme[#f], then menu item has no + keyboard shortcut. + +}} + +@defmethod[(get-shortcut-prefix) + (symbols/c option shift ctl meta cmd alt)]{ +@spec{ + +Returns a list of symbols that indicates the keyboard prefix used for the menu + item's keyboard shortcut. The allowed symbols for the list are the following: +@itemize{ +@item{@scheme['alt] --- Meta (Windows and X only)} +@item{@scheme['cmd] --- Command (Mac OS X only)} +@item{@scheme['meta] --- Meta (X only)} +@item{@scheme['ctl] --- Control} +@item{@scheme['shift] --- Shift} +@item{@scheme['opt] --- Option (Mac OS X only)} +} +Under X, at most one of @scheme['alt] and @scheme['meta] can be + supplied; the only difference between @scheme['alt] and @scheme['meta] + is the key combination's display in a menu. + +The default shortcut prefix is available from +@scheme[get-default-shortcut-prefix] . + +The shortcut key, as determined by +@method[selectable-menu-item<%> get-shortcut], matches a key event using either the normally reported key code or +the other-Shift/AltGr key code (as produced by +@xmethod[key-event% get-other-shift-key-code], etc.). When the shortcut key is a key-code symbol or an ASCII letter or +digit, then the shortcut matches only the exact combination of +modifier keys listed in the prefix. For character shortcuts other than +ASCII letters and digits, however, then the shortcut prefix merely +determines a minimum set of modifier keys, because additional +modifiers may be needed to access the character; an exception is that, +under Windows or X, the Alt/Meta key press must match the prefix +exactly (i.e., included or not). In all +cases, the most precise match takes precedence; see +@xmethod[keymap% map-function] for more information on match ranking. + +An empty list can be used for a shortcut prefix. However, the default +@xmethod[frame% on-menu-char] method checks for menu shortcuts only when the key event includes +either a non-Shift modifer or a Function key. Thus, an empty shortcut +prefix is normally useful only if the shortcut key is a Function key. + +}} + +@defmethod[(set-shortcut-prefix [prefix (symbols/c option shift ctl meta cmd alt)]) + void?]{ +@spec{ + +Sets a list of symbols to indicates the keyboard prefix used for the menu + item's keyboard shortcut. + +See +@method[selectable-menu-item<%> get-shortcut-prefix] for more information. + +}} + +@defmethod[(command [event (is-a/c control-event%)]) + void?]{ +@spec{ + +Invoke's the menu item's callback procedure, which is supplied when an + instance of +@scheme[menu-item%] or +@scheme[checkable-menu-item%] is created. + +} +@impl{ + + + +}}} + diff --git a/collects/scribblings/gui/separator-menu-item-class.scrbl b/collects/scribblings/gui/separator-menu-item-class.scrbl new file mode 100644 index 0000000000..052a370a2d --- /dev/null +++ b/collects/scribblings/gui/separator-menu-item-class.scrbl @@ -0,0 +1,19 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[separator-menu-item% object% (menu-item<%>)]{ + +A separator is an unselectable line in a menu. Its parent must be a + @scheme[menu%] or @scheme[popup-menu%]. + + + + +@defconstructor[[parent @scheme[menu%] or @scheme[popup-menu%] object]]{ + +Creates a new separator in the menu. + + + +}} + diff --git a/collects/scribblings/gui/slider-class.scrbl b/collects/scribblings/gui/slider-class.scrbl new file mode 100644 index 0000000000..fe87f1e90d --- /dev/null +++ b/collects/scribblings/gui/slider-class.scrbl @@ -0,0 +1,87 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[slider% object% (control<%>)]{ + +A @scheme[slider] object is a panel item with a handle that the user can + drag to change the control's value. Each slider has a fixed minimum + and maximum value. + +Whenever the user changes the value of a slider, its callback + procedure is invoked. A callback procedure is provided as an + initialization argument when each slider is created. + + + + +@defconstructor[[label (or/c label-string? false/c)] + [min-value (integer-in -10000 10000)] + [max-value (integer-in -10000 10000)] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [callback procedure of two arguments: a @scheme[slider%] object and a @scheme[control-event%] object @scheme[(\scmk{lambda] (@scheme[s] @scheme[e]) (void))}] + [init-value (integer-in -10000 10000) @scheme[min-value]] + [style (symbols/c deleted horizontal-label vertical-label plain vertical horizontal) '(horizontal)] + [font (is-a/c font%) @scheme[normal-control-font]] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 2] + [horiz-margin (integer-in 0 1000) 2] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c \#t {\rm for} @scheme['horizontal] {\rm style}, \#f {\rm for} @scheme['vertical]] + [stretchable-height any/c \#t {\rm for} @scheme['vertical] {\rm style}, \#f {\rm for} @scheme['horizontal]]]{ + +If @scheme[label] is a string, it is used as the label for the slider. + Otherwise, the slider does not display its + label. + +@labelstripped[(scheme label) @elem{} @elem{move the keyboard focus to the slider}] + +The @scheme[min-value] and @scheme[max-value] arguments specify the range of + the slider, inclusive. The @scheme[init-value] argument optionally + specifies the slider's initial value. If the sequence + [@scheme[min-value], @scheme[initial-value], @scheme[maximum-value]] is not + increasing, @|MismatchExn|}. + +The @scheme[callback] procedure is called (with the event type + @indexed-scheme['slider]) when the user changes the slider's value. + +The @scheme[style] argument must include either @scheme['vertical] for a + vertical slider, or @scheme['horizontal] for a horizontal slider. If + @scheme[style] includes @scheme['plain], the slider does not display + numbers for its range and current value to the user. + \HVLabelNote{slider} \DeletedStyleNote{slider} + +@FontKWs[] @WindowKWs[] @SubareaKWs[] @AreaKWs[] + + + +} + +@defmethod[(get-value) + (integer-in -10000 10000)]{ +@spec{ + +Gets the current slider value. + +}} + +@defmethod[(set-value [value (integer-in -10000 10000)]) + void?]{ +@spec{ + +Sets the value (and displayed position) of the slider. (The control's + callback procedure is {\em not} invoked.) + +@MonitorCallback[@elem{A slider's value} @elem{the user clicking the control} @elem{value}] + +} +@impl{ + +If @scheme[value] is outside the slider's minimum and maximum range, + @|MismatchExn|}. + + + + +}}} + diff --git a/collects/scribblings/gui/subarea-intf.scrbl b/collects/scribblings/gui/subarea-intf.scrbl new file mode 100644 index 0000000000..3841a3654d --- /dev/null +++ b/collects/scribblings/gui/subarea-intf.scrbl @@ -0,0 +1,80 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@definterface[subarea<%> (area<%>)]{ + +A @scheme[subarea<%>] is a containee @scheme[area<%>]. + +All @scheme[subarea<%>] classes accept the following named + instantiation arguments: +@itemize{ + + @item{@indexed-scheme[horiz-margin] --- default is @scheme[2] for + @scheme[control<%>] classes and @scheme[group-box-panel%], + @scheme[0] for others; passed to +@method[subarea<%> horiz-margin]} + @item{@indexed-scheme[vert-margin] --- default is @scheme[2] for + @scheme[control<%>] classes and @scheme[group-box-panel%], + @scheme[0] for others; passed to +@method[subarea<%> vert-margin]} +} + + + + +@defmethod*[([(horiz-margin) + (integer-in 0 1000)] + [(horiz-margin [margin (integer-in 0 1000)]) + void?])]{ +@spec{ + +Gets or sets the area's horizontal margin, which is added both to the + right and left, for geometry management. See @|geomdiscuss| for more + information. + +} +@impl{ +First case: + + +Returns the current horizontal margin. + + + +Second case: + + +Sets the horizontal margin. + + + +}} + +@defmethod*[([(vert-margin) + (integer-in 0 1000)] + [(vert-margin [margin (integer-in 0 1000)]) + void?])]{ +@spec{ + +Gets or sets the area's vertical margin, which is added both to the + right and left, for geometry management. See @|geomdiscuss| for more + information. + +} +@impl{ +First case: + + +Returns the current vertical margin. + + + +Second case: + + +Sets the vertical margin. + + + +}}} + diff --git a/collects/scribblings/gui/subwindow-intf.scrbl b/collects/scribblings/gui/subwindow-intf.scrbl new file mode 100644 index 0000000000..324f961633 --- /dev/null +++ b/collects/scribblings/gui/subwindow-intf.scrbl @@ -0,0 +1,10 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@definterface[subwindow<%> (subarea<%> window<%>)]{ + +A @scheme[subwindow<%>] is a containee window. + + +} + diff --git a/collects/scribblings/gui/system-menu-funcs.scrbl b/collects/scribblings/gui/system-menu-funcs.scrbl new file mode 100644 index 0000000000..52afb9afa6 --- /dev/null +++ b/collects/scribblings/gui/system-menu-funcs.scrbl @@ -0,0 +1,126 @@ +#reader(lib "docreader.ss" "scribble") +@require["common.ss"] + +@title{System Menus} + + +@defproc[(current-eventspace-has-standard-menus?) + boolean?]{ +Returns @scheme[#t] for Mac OS X when the current eventspace is the + initial one, since that eventspace is the target for the standard + application menus. For any other system or eventspace, the result is + @scheme[#f]. + +This procedure is intended for use in deciding whether to include a + @onscreen{Quit}, @onscreen{About}, and @onscreen{Preferences} menu + item in a frame's menu. Under Mac OS X, the application + @onscreen{Quit} menu triggers a call to a frame's +@method[top-level-window<%> on-exit] method, the @onscreen{About} menu item is controlled by + @scheme[application-about-handler], and the + @onscreen{Preferences} menu item is controlled by + @scheme[application-preferences-handler]. + +} + +@defproc[(current-eventspace-has-menu-root?) + boolean?]{ +Returns @scheme[#t] for Mac OS X when the current eventspace is the + initial one, since that eventspace can supply a menu bar to be active + when no frame is visible. For any other system or eventspace, the + result is @scheme[#f]. + +This procedure is intended for use in deciding whether to create a + @scheme[menu-bar%] instance with @scheme['root] as its parent. + +} + +@defproc*[([(application-about-handler) + (-> any)] + [(application-about-handler [handler-thunk (-> any)]) + void?])]{ + +When the current eventspace is the initial eventspace, this +procedure retrieves or installs a thunk that is called when the +user selects the application @onscreen{About} menu item in Mac OS +X. The thunk is always called in the initial eventspace's +handler thread (as a callback). + +The default handler displays a generic PLT Scheme dialog. + +If the current eventspace is not the initial eventspace, this +procedure returns @scheme[void] (when called with zero arguments) +or has no effect (when called with a handler). + +} + +@defproc*[([(application-preferences-handler) + (or/c (-> any) false/c)] + [(application-preferences-handler [handler-thunk (or/c (-> any) false/c)]) + void?])]{ +When the current eventspace is the initial eventspace, this procedure + retrieves or installs a thunk that is called when the user selects + the application @onscreen{Preferences} menu item in Mac OS X. The + thunk is always called in the initial eventspace's handler thread (as + a callback). If the handler is set to @scheme[#f], the + @onscreen{Preferences} item is disabled. + +The default handler is @scheme[#f]. + +If the current eventspace is not the initial eventspace, this +procedure returns @scheme[void] (when called with zero arguments) +or has no effect (when called with a handler). +} + +@defproc*[([(application-quit-handler) + (-> any)] + [(application-quit-handler [handler-thunk (-> any)]) + void?])]{ +When the current eventspace is the initial eventspace, this procedure + retrieves or installs a thunk that is called when the user requests + that the application quit (e.g., through the @onscreen{Quit} menu + item in Mac OS X, or when shutting down the machine in Windows). The + thunk is always called in the initial eventspace's handler thread (as + a callback). If the result of the thunk is @scheme[#f], then the + operating system is explicitly notified that the application does not + intend to quit (under Windows). + +The default handler queues a call to the + @method[top-level-window<%> can-exit?] method of the most + recently active frame in the initial eventspace (and then calls the + frame's @method[top-level-window<%> on-exit] method if the + result is true). The result is @scheme[#t] if the eventspace is + left with no open frames after + @method[top-level-window<%> on-exit] returns, @scheme[#f] + otherwise. + + +If the current eventspace is not the initial eventspace, this +procedure returns @scheme[void] (when called with zero arguments) +or has no effect (when called with a handler). +} + +@defproc*[([(application-file-handler) + (path? . -> . any)] + [(application-file-handler [handler-proc (path? . -> . any)]) + void?])]{ +When the current eventspace is the initial eventspace, this procedure + retrieves or installs a procedure that is called under Mac OS X + and Windows when the application is running and user double-clicks an + application-handled file or drags a file onto the application's + icon. The procedure is always called in the initial eventspace's + handler thread (as a callback), and the argument is a filename. + +The default handler queues a callback to the +@method[window<%> on-drop-file] method of the most-recently activated frame in the main eventspace (see +@scheme[get-top-level-edit-target-window]), if + drag-and-drop is enabled for that frame. + +When the application is @italic{not} running and user double-clicks an + application-handled file or drags a file onto the application's icon, + the filename is provided as a command-line argument to the + application. + +If the current eventspace is not the initial eventspace, this +procedure returns @scheme[void] (when called with zero arguments) +or has no effect (when called with a handler). +} \ No newline at end of file diff --git a/collects/scribblings/gui/tab-panel-class.scrbl b/collects/scribblings/gui/tab-panel-class.scrbl new file mode 100644 index 0000000000..33b09c28d5 --- /dev/null +++ b/collects/scribblings/gui/tab-panel-class.scrbl @@ -0,0 +1,166 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[tab-panel% vertical-panel% ()]{ + +A tab panel arranges its subwindows in a single column, but also + includes a horizontal row of tabs at the top of the panel. See + also @scheme[panel%]. + +The @scheme[tab-panel%] class does not implement the virtual + swapping of the panel content when a new tab is selected. Instead, it + merely invokes a callback procedure to indicate that a user changed + the tab selection. + + + + +@defconstructor[[choices list of {\labelstrings}] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [callback procedure of two arguments: a @scheme[tab-panel%] object and a @scheme[control-event%] object @scheme[(\scmk{lambda] (@scheme[tp] @scheme[e]) (void))}] + [style (symbols/c deleted no-border) null] + [font (is-a/c font%) @scheme[normal-control-font]] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 0] + [horiz-margin (integer-in 0 1000) 0] + [border (integer-in 0 1000) 0] + [spacing (integer-in 0 1000) 0] + [alignment two-element list: @scheme['left], @scheme['center], or @scheme['right] and @scheme['top], @scheme['center], or @scheme['bottom] '(center top)] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #t] + [stretchable-height any/c #t]]{ + +Creates a tab pane, where the + @scheme[choices] list specifies the tab labels. + +Each string in @scheme[choices] can contain an ampersand, which (in the + future) may create a mnemonic for clicking the corresponding tab. A + double ampersand is converted to a single ampersand. + +The @scheme[callback] procedure is called (with the event type + @indexed-scheme['tab-panel]) when the user changes the tab selection. + +If the @scheme[style] list includes @scheme['no-border], no border is + drawn around the panel content. \DeletedStyleNote{tab panel} + +@FontKWs[] @WindowKWs[] @SubareaKWs[] @AreaKWs[] + + + +} + +@defmethod[(append [choice label-string?]) + void?]{ +@spec{ + +Adds a tab to the right end of panel's top row of tabs. + +} +@impl{ + +The label string @scheme[choice] can contain an ampersand, which (in the + future) may create a mnemonic for clicking the new tab. A double + ampersand is converted to a single ampersand. + + + +}} + +@defmethod[(delete [n nonnegative-exact-integer?]) + void?]{ +@spec{ + +Deletes an existing tab. + +} +@impl{ + +If @scheme[n] is equal to or larger than the number of tabs on the panel, + @|MismatchExn|}. + + + +}} + +@defmethod[(get-selection) + (or/c nonnegative-exact-integer? false/c)]{ +@spec{ + +Returns the index (counting from 0) of the currently selected tab. + If the panel has no tabs, the result is @scheme[#f]. + +}} + +@defmethod[(set-selection [n nonnegative-exact-integer?]) + void?]{ +@spec{ + +Sets the currently selected tab by index (counting from 0). + +} +@impl{ + +If @scheme[n] is equal to or larger than the number of tabs in the panel, + @|MismatchExn|}. + + + +}} + +@defmethod[(get-number) + nonnegative-exact-integer?]{ +@spec{ + +Returns the number of tabs on the panel. + +}} + +@defmethod[(get-item-label [n nonnegative-exact-integer?]) + string]{ +@spec{ + +Gets the label of a tab by position. Tabs are numbered from @scheme[0]. + +} +@impl{ + +If @scheme[n] is equal to or larger than the number of tabs in the panel, + @|MismatchExn|}. + + + +}} + +@defmethod[(set-item-label [n nonnegative-exact-integer?] + [label label-string?]) + string]{ +@spec{ + +Sets the label of a tab by position. Tabs are numbered from @scheme[0]. + +} +@impl{ + +Set the label for tab @scheme[n] to @scheme[label]. If @scheme[n] is equal to + or larger than the number of tabs in the panel, @|MismatchExn|}. + + + +}} + +@defmethod[(set [choices list of {\labelstrings}]) + void?]{ +@spec{ + +Removes all tabs from the panel and installs tabs with the given + labels. + +} +@impl{ + + + + +}}} + diff --git a/collects/scribblings/gui/text-field-class.scrbl b/collects/scribblings/gui/text-field-class.scrbl new file mode 100644 index 0000000000..c6afe30b16 --- /dev/null +++ b/collects/scribblings/gui/text-field-class.scrbl @@ -0,0 +1,139 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[text-field% object% (control<%>)]{ + +A @scheme[text-field%] object is an editable text field with an + optional label displayed in front of it. There are two text field + styles: +@itemize{ + + @item{A single line of text is visible, and a special control event + is generated when the user presses Enter (when the text field has the + focus) and the event is not handled by the text field's frame or + dialog (see +@xmethod[top-level-window<%> on-traverse-char] ).} + + @item{Multiple lines of text are visible, and Enter is not handled + specially.} + +} + +Whenever the user changes the content of a text field, its callback + procedure is invoked. A callback procedure is provided as an + initialization argument when each text field is created. + +The text field is implemented using a @scheme[text%] editor (with an + inaccessible display). Thus, whereas @scheme[text-field%] provides + only +@method[text-field% get-value] and +@method[text-field% set-value] to manipulate the text in a text field, the +@method[text-field% get-editor] returns the field's editor, which provides a vast collection of + methods for more sophisticated operations on the text. + +The keymap for the text field's editor is initialized by calling the + current keymap initializer procedure, which is determined by the +@scheme[current-text-keymap-initializer] parameter. + + + + +@defconstructor[[label (or/c label-string? false/c)] + [parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [callback procedure of two arguments: a @scheme[text-field%] object and a @scheme[control-event%] object @scheme[(\scmk{lambda] (@scheme[tf] @scheme[e]) (void))}] + [init-value string ""] + [style (symbols/c deleted horizontal-label vertical-label password hscroll multiple single) '(single)] + [font (is-a/c font%) @scheme[normal-control-font]] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 2] + [horiz-margin (integer-in 0 1000) 2] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #t] + [stretchable-height any/c \#t {\rm for} @scheme['multiple] {\rm style}, \#f {\rm otherwise}]]{ + +If @scheme[label] is not @scheme[#f], it is used as the text field label. + Otherwise, the text field does not display its + label. + +@labelstripped[(scheme label) @elem{} @elem{move the keyboard focus to the text field}] + +The @scheme[callback] procedure is called when the user changes the text + in the text field or presses the Enter key (and Enter is not handled by + the text field's frame or dialog; see +@xmethod[top-level-window<%> on-traverse-char] ). If the user presses Enter, the type of event passed to the callback + is @indexed-scheme['text-field-enter], otherwise it is + @indexed-scheme['text-field]. + +If @scheme[init-value] is not @scheme[""], the minimum width of the text item + is made wide enough to show @scheme[init-value]. Otherwise, a built-in + default width is selected. For a text field in single-line mode, the + minimum height is set to show one line and only the control's width + is stretchable. For a multiple-line text field, the minimum height + shows three lines of text and is stretchable in both directions. + +The style must contain exactly one of @scheme['single] or + @scheme['multiple]; the former specifies a single-line field and + the latter specifies a multiple-line field. The @scheme['hscroll] + style applies only to multiple-line fields; when + @scheme['hscroll] is specified, the field has a horizontal + scrollbar and autowrapping is disabled; otherwise, the field has no + horizontal scrollbar and autowrapping is enabled. A multiple-line text + field always has a vertical scrollbar. The @scheme['password] + style indicates that the field should draw each character of + its content using a generic symbol instead of the actual character. + \HVLabelNote{text field} \DeletedStyleNote{text field}. + +@FontKWs[] @WindowKWs[] @SubareaKWs[] @AreaKWs[] + + + +} + +@defmethod[(get-value) + string]{ +@spec{ + +Returns the text currently in the text field. + +}} + +@defmethod[(set-value [val string]) + void?]{ +@spec{ + +Sets the text currently in the text field. (The control's callback + procedure is {\em not} invoked.) + +@MonitorCallback[@elem{A text field's value} @elem{the user typing into the control} @elem{value}] + +}} + +@defmethod[(get-editor) + (is-a/c text%)]{ +@spec{ + +Returns the editor used to implement the text field. + +For a text field, the most useful methods of a @scheme[text%] object + are the following: +@itemize{ + + @item{@scheme[(send @scheme[a-text] @method[text% get-text])] returns + the current text of the editor.} + + @item{@scheme[(send @scheme[a-text] @method[text% erase])] deletes all text from + the editor.} + + @item{@scheme[(send @scheme[a-text] @method[text% insert] \var{string])} + inserts @scheme[str] into the editor at the current caret position.} + +} + +} +@impl{ + + + +}}} + diff --git a/collects/scribblings/gui/timer-class.scrbl b/collects/scribblings/gui/timer-class.scrbl new file mode 100644 index 0000000000..936bce33d7 --- /dev/null +++ b/collects/scribblings/gui/timer-class.scrbl @@ -0,0 +1,109 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[timer% object% ()]{ + +A @scheme[timer%] object encapsulates an event-based alarm. To use a + timer, either instantiate it with a @scheme[timer-callback] thunk to perform the alarm-based action, to derive a new class and override the +@method[timer% notify] method to perform the alarm-based action. Start a timer with +@method[timer% start] and stop it with +@method[timer% stop]. Supplying an initial @scheme[interval] (in milliseconds) when creating + a timer also starts the timer. + +Timers have a relatively high priority in the event queue. Thus, if + the timer delay is set low enough, repeated notification for a timer + can preempt user activities (which might be directed at stopping the + timer). For timers with relatively short delays, call +@scheme[yield] within the +@method[timer% notify] procedure to allow guaranteed event processing. + +See @secref["mr:eventspaceinfo"] for more information + about event priorities. + + + + + +@defconstructor[[notify-callback (-> any) @scheme[void]] + [interval (or/c (integer-in 0 1000000000) false/c) #f] + [just-once? any/c #f]]{ + +Creates a timer. + +The @scheme[notify-callback] thunk is called by the default +@method[timer% notify] method when the timer expires. + +If @scheme[interval] is @scheme[#f] (the default), the timer is not + started; in that case, +@method[timer% start] must be called explicitly. If @scheme[interval] is a number (in + milliseconds), then +@method[timer% start] is called with @scheme[interval] and @scheme[just-once?]. + + + +} + +@defmethod[(notify) + void?]{ +@spec{ + +Called (on an event boundary) when the timer's alarm expires. + +} +@impl{ + +Calls the @scheme[notify-callback] procedure that was provided when the + object was created. + + + + +}} + +@defmethod[(interval) + (integer-in 0 1000000000)]{ +@spec{ + +Returns the number of milliseconds between each timer expiration + (when the timer is running). + +}} + +@defmethod[(start [msec (integer-in 0 1000000000)] + [just-once? any/c #f]) + void?]{ +@spec{ + +Starts (or restarts) the timer. If the timer is already running, its + alarm time is not changed. + +} +@impl{ + +The timer's alarm expires after @scheme[msec] milliseconds, at which point +@method[timer% notify] is called (on an event boundary). If @scheme[just-once?]\ is @scheme[#f], + the timer expires {\em every} @scheme[msec] milliseconds until the timer is + explicitly stopped;\footnote{More precisely, the timer expires @scheme[msec] + milliseconds after +@method[timer% notify] returns each time} otherwise, the timer expires only once. + + + +}} + +@defmethod[(stop) + void?]{ +@spec{ + +Stops the timer. A stopped timer never calls +@method[timer% notify]. If the timer has expired but the call to +@method[timer% notify] has not yet been dispatched, the call is removed from the event queue. + +} +@impl{ + + + + +}}} + diff --git a/collects/scribblings/gui/top-level-window-intf.scrbl b/collects/scribblings/gui/top-level-window-intf.scrbl new file mode 100644 index 0000000000..1b56e07a46 --- /dev/null +++ b/collects/scribblings/gui/top-level-window-intf.scrbl @@ -0,0 +1,362 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@definterface[top-level-window<%> (area-container-window<%>)]{ + +A top-level window is either a @scheme[frame%] or @scheme[dialog%] + object. + + + + +@defmethod[(get-eventspace) + eventspace]{ +@spec{ + +Returns the window's eventspace. + +}} + +@defmethod[#:mode 'pubment + (on-close) + void?]{ +@spec{ + +Called just before the window is closed (e.g., by the window manager). + This method is {\em not}\/ called by +@method[window<%> show] . + +See also +@method[top-level-window<%> can-close?]. + +}} + +@defmethod[#:mode 'pubment + (can-close?) + boolean?]{ +@spec{ + +Called just before the window might be closed (e.g., by the window + manager). If @scheme[#f] is returned, the window is not\/ + closed, otherwise +@method[top-level-window<%> on-close] is called and the window is closed (i.e., the window is hidden, + like calling +@method[window<%> show] with @scheme[#f]). + +This method is {\em not}\/ called by +@method[window<%> show] . + + +}} + +@defmethod[(on-exit) + void?]{ +@spec{ + +Called by the default application quit handler (as determined by the + @scheme[application-quit-handler] parameter) when the + operating system requests that the application shut down (e.g., when + the \OnScreen{Quit} menu item is selected in the main application + menu under Mac OS X). In that case, this method is called for the + most recently active top-level window in the initial eventspace, but + only if the window's +@method[top-level-window<%> can-exit?] method first returns true. + +} +@impl{ + +Calls +@method[top-level-window<%> on-close] and then +@method[top-level-window<%> show] to hide the window. + + + +}} + +@defmethod[(can-exit?) + boolean?]{ +@spec{ + +Called before +@method[top-level-window<%> on-exit] to check whether an exit is allowed. See +@method[top-level-window<%> on-exit] for more information. + +} +@impl{ + +Calls +@method[top-level-window<%> can-close?] and returns the result. + + + +}} + +@defmethod[(on-activate [active? any/c]) + void?]{ +@spec{ + +Called when a window is @defterm{activated} or + @defterm{deactivated}. A top-level window is activated when the + keyboard focus moves from outside the window to the window or one of + its children. It is deactivated when the focus moves back out of the + window. Under Mac OS X, a child of a floating frames can have the + focus instead of a child of the active non-floating frame; in other + words, floating frames act as an extension of the active non-frame + for keyboard focus. + +The method's argument is @scheme[#t] when the window is activated, + @scheme[#f] when it is deactivated. + +}} + +@defmethod[(on-message [message value]) + value]{ +@spec{ + +\index{drag-and-drop} +A generic message method, usually called by +@scheme[send-message-to-window]. + +If the method is invoked by +@scheme[send-message-to-window], then it is invoked in the thread where +@scheme[send-message-to-window] was called (which is possibly {\em not\/} the handler thread of the + window's eventspace). + +} +@impl{ + +Returns void. + + + +}} + +@defmethod[(get-focus-window) + (or/c (is-a/c window<%>) false/c)]{ +@spec{ + +\index{keyboard focus} +Returns the window that has the keyboard focus, either the top-level + window or one of its children. If neither the window nor any of its + children has the focus, @scheme[#f] is returned. + +See also +@method[top-level-window<%> get-edit-target-window] and +@method[top-level-window<%> get-focus-object]. + +}} + +@defmethod[(get-focus-object) + (or/c (or/c (is-a/c window<%>) (is-a/c editor<%>)) false/c)]{ +@spec{ + +\index{keyboard focus} +Like +@method[top-level-window<%> get-focus-window], but if an editor canvas has the focus and it also displays an + editor, the editor is returned instead of the canvas. Further, if the + editor's focus is delegated to an embedded editor, the embedded + editor is returned. + +See also +@method[top-level-window<%> get-edit-target-object]. + +}} + +@defmethod[(get-edit-target-window) + (or/c (is-a/c window<%>) false/c)]{ +@spec{ + +\index{keyboard focus!last active} +Returns the window that most recently had the keyboard focus, either + the top-level window or one of its currently-shown children. If + neither the window nor any of its currently-shown children has even + owned the keyboard focus, @scheme[#f] is returned. + +See also +@method[top-level-window<%> get-focus-window] and +@method[top-level-window<%> get-edit-target-object]. + +}} + +@defmethod[(get-edit-target-object) + (or/c (or/c (is-a/c window<%>) (is-a/c editor<%>)) false/c)]{ +@spec{ + +\index{keyboard focus!last active} +Like +@method[top-level-window<%> get-edit-target-window], but if an editor canvas had the focus and it also displays an + editor, the editor is returned instead of the canvas. Further, if the + editor's focus is delegated to an embedded editor, the embedded + editor is returned. + +See also +@method[top-level-window<%> get-focus-object]. + +}} + +@defmethod[(center [direction (symbols/c both vertical horizontal) 'both]) + void?]{ +@spec{ + +Centers the window on the screen if it has no parent. If it has a + parent, the window is centered with respect to its parent's location. + +} +@impl{ + +If @scheme[direction] is @scheme['horizontal], the window is centered + horizontally. If @scheme[direction] is @scheme['vertical], the + window is centered vertically. If @scheme[direction] is + @scheme['both], the window is centered in both directions. + + + +}} + +@defmethod[(move [x (integer-in -10000 10000)] + [y (integer-in -10000 10000)]) + void?]{ +@spec{ + +Moves the window to the given position on the screen. + +@MonitorMethod[@elem{A window's position} @elem{the user dragging the window} @elem{@method[window<%> on-move]} @elem{position}] + +}} + +@defmethod[(resize [width (integer-in 0 10000)] + [height (integer-in 0 10000)]) + void?]{ +@spec{ + +Sets the size of the window (in pixels), but only if the given size is + larger than the window's minimum size. + +@MonitorMethod[@elem{A window's size} @elem{the user} @elem{@method[window<%> on-size]} @elem{size}] + +}} + +@defmethod[(on-traverse-char [event (is-a/c key-event%)]) + boolean?]{ +@spec{ + +\index{keyboard focus!navigation} +Attempts to handle the given keyboard event as a navigation event, such + as a Tab key event that moves the keyboard focus. If the event is + handled, @scheme[#t] is returned, otherwise @scheme[#f] is returned. + +} +@impl{ + +The following rules determine, in order, whether and how @scheme[event] +is handled: +@itemize{ + +@item{ +If the window that currently owns the focus specifically handles the + event, then @scheme[#f] is returned. The following describes window + types and the keyboard events they specifically handle: +@itemize{ + + @item{@scheme[editor-canvas%] --- tab-exit is disabled (see +@method[editor-canvas% allow-tab-exit]): all keyboard events, except alphanumeric key events when the Meta + (X) or Alt (Windows) key is pressed; when tab-exit is enabled: + all keyboard events except Tab, Enter, Escape, and alphanumeric + Meta/Alt events.} + + @item{@scheme[canvas%] --- when tab-focus is disabled (see +@method[canvas% accept-tab-focus]): all keyboard events, except alphanumeric key events when the Meta + (X) or Alt (Windows) key is pressed; when tab-focus is enabled: + no key events} + + @item{@scheme[text-field%], @scheme['single] style --- arrow key + events and alphanumeric key events when the Meta (X) or Alt + (Windows) key is not pressed (and all alphanumeric events under + Mac OS X)} + + @item{@scheme[text-field%], @scheme['multiple] style --- all + keyboard events, except alphanumeric key events when the Meta (X) or + Alt (Windows) key is pressed} + + @item{@scheme[choice%] --- arrow key events and alphanumeric key + events when the Meta (X) or Alt (Windows) key is not pressed} + + @item{@scheme[list-box%] --- arrow key events and alphanumeric key + events when the Meta (X) or Alt (Windows) key is not pressed} + +}} + +@item{ +If @scheme[event] is a Tab or arrow key event, the keyboard focus is + moved within the window and @scheme[#t] is returned. Across platforms, + the types of windows that accept the keyboard focus via navigation + may vary, but @scheme[text-field%] windows always accept the focus, + and @scheme[message%], @scheme[gauge%], and @scheme[panel%] + windows never accept the focus.} + +@item{ +If @scheme[event] is a Space key event and the window that currently + owns the focus is a @scheme[button%], @scheme[check-box%], or + @scheme[radio-box%] object, the event is handled in the same way as + a click on the control and @scheme[#t] is returned.} + +@item{ +If @scheme[event] is an Enter key event and the current top-level window + contains a border button, the button's callback is invoked and + @scheme[#t] is returned. (The @scheme['border] style for a + @scheme[button%] object indicates to the user that pressing Enter + is the same as clicking the button.) If the window does not contain a + border button, @scheme[#t] is returned if the window with the current + focus is not a text field or editor canvas.} + +@item{ +In a dialog, if @scheme[event] is an Escape key event, the event is + handled the same as a click on the dialog's close box (i.e., the + dialog's +@method[top-level-window<%> can-close?] and +@method[top-level-window<%> on-close] methods are called, and the dialog is hidden) and @scheme[#t] is + returned.} + +@item{ +If @scheme[event] is an alphanumeric key event and the current top-level + window contains a control with a mnemonic matching the key (which is + installed via a label that contains ``\&''; see + @method[window<%> get-label] for more information), then the + keyboard focus is moved to the matching control. Furthermore, if the + matching control is a @scheme[button%], @scheme[check-box%], or + @scheme[radio-box%] button, the keyboard event is handled in the + same way as a click on the control.} + +@item{ +Otherwise, @scheme[#f] is returned.} + +} + + + +}} + +@defmethod[(on-system-menu-char [event (is-a/c key-event%)]) + boolean?]{ +@spec{ + +Checks whether the given event pops open the system menu in the + top-left corner of the window (Windows only). If the window's system + menu is opened, @scheme[#t] is returned, otherwise @scheme[#f] is + returned. + +}} + +@defmethod[#:mode 'auto-super + (show [show any/c]) + void?]{ +@impl{ + +If the window is already shown, it is moved front of other top-level + windows. If the window is iconized (frames only), it is deiconized. + + + + +}}} + diff --git a/collects/scribblings/gui/vertical-pane-class.scrbl b/collects/scribblings/gui/vertical-pane-class.scrbl new file mode 100644 index 0000000000..e7ed82ee8f --- /dev/null +++ b/collects/scribblings/gui/vertical-pane-class.scrbl @@ -0,0 +1,27 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[vertical-pane% pane% ()]{ + +A vertical pane arranges its subwindows in a single column. See also @scheme[pane%]. + + + + +@defconstructor[[parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [vert-margin (integer-in 0 1000) 0] + [horiz-margin (integer-in 0 1000) 0] + [border (integer-in 0 1000) 0] + [spacing (integer-in 0 1000) 0] + [alignment two-element list: @scheme['left], @scheme['center], or @scheme['right] and @scheme['top], @scheme['center], or @scheme['bottom] '(center top)] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #t] + [stretchable-height any/c #t]]{ + +@SubareaKWs[] @AreaContKWs[] @AreaKWs[] + + + +}} + diff --git a/collects/scribblings/gui/vertical-panel-class.scrbl b/collects/scribblings/gui/vertical-panel-class.scrbl new file mode 100644 index 0000000000..f64a8b0378 --- /dev/null +++ b/collects/scribblings/gui/vertical-panel-class.scrbl @@ -0,0 +1,34 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@defclass[vertical-panel% panel% ()]{ + +A vertical panel arranges its subwindows in a single column. See + also @scheme[panel%]. + + + + +@defconstructor[[parent (or/c (is-a/c frame%) (is-a/c dialog%) (is-a/c panel%) (is-a/c pane%))] + [style (symbols/c deleted border) null] + [enabled any/c #t] + [vert-margin (integer-in 0 1000) 0] + [horiz-margin (integer-in 0 1000) 0] + [border (integer-in 0 1000) 0] + [spacing (integer-in 0 1000) 0] + [alignment two-element list: @scheme['left], @scheme['center], or @scheme['right] and @scheme['top], @scheme['center], or @scheme['bottom] '(left center)] + [min-width (integer-in 0 10000) {\rm graphical minimum width}] + [min-height (integer-in 0 10000) {\rm graphical minimum height}] + [stretchable-width any/c #t] + [stretchable-height any/c #t]]{ + +If the @scheme['border] style is specified, the window is created with + a thin border (only in this case, the client size of the panel may be + less than its total size). \DeletedStyleNote{panel} + +@WindowKWs[] @SubareaKWs[] @AreaContKWs[] @AreaKWs[] + + + +}} + diff --git a/collects/scribblings/gui/window-intf.scrbl b/collects/scribblings/gui/window-intf.scrbl new file mode 100644 index 0000000000..02a2a4109b --- /dev/null +++ b/collects/scribblings/gui/window-intf.scrbl @@ -0,0 +1,558 @@ +#reader(lib "defreader.ss" "scribble") +@require["common.ss"] + +@definterface[window<%> (area<%>)]{ + +A @scheme[window<%>] object is an @scheme[area<%>] with a graphical + representation that can respond to events. + +All @scheme[window<%>] classes accept the following named instantiation + arguments: +@itemize{ + + @item{@indexed-scheme[enabled] --- default is @scheme[#t]; passed to +@method[window<%> enable] if @scheme[#f]} + +} + + + + +@defmethod[(on-focus [on? any/c]) + void?]{ +@spec{ + +\index{keyboard focus!notification} +Called when a window receives or loses the keyboard focus. If the + argument is @scheme[#t], the keyboard focus was received, otherwise it + was lost. + +Note that under X, keyboard focus can move to the menu bar + when the user is selecting a menu item. + +} +@impl{ + +Does nothing. + + + +}} + +@defmethod[(on-size [width (integer-in 0 10000)] + [height (integer-in 0 10000)]) + void?]{ +@spec{ + +Called when the window is resized. The window's new size (in pixels) + is provided to the method. The size values are for the entire window, + not just the client area. + +} +@impl{ + +Does nothing. + + + +}} + +@defmethod[(on-move [x (integer-in -10000 10000)] + [y (integer-in -10000 10000)]) + void?]{ +@spec{ + +Called when the window is moved. (For windows that are not top-level + windows, ``moved'' means moved relative to the parent's top-left + corner.) The new position is provided to the method. + +} +@impl{ + +Does nothing. + + + +}} + +@defmethod[(on-subwindow-char [receiver (is-a/c window<%>)] + [event (is-a/c key-event%)]) + boolean?]{ +@spec{ + +Called when this window or a child window receives a keyboard event. + The +@method[window<%> on-subwindow-char] method of the receiver's top-level window is called first (see +@method[area<%> get-top-level-window]); if the return value is @scheme[#f], then the +@method[window<%> on-subwindow-char] method is called for the next child in the path to the receiver, and + so on. Finally, if the receiver's +@method[window<%> on-subwindow-char] method returns @scheme[#f], the event is passed on to the receiver's + normal key-handling mechanism. + +BEWARE: The default +@xmethod[frame% on-subwindow-char] and +@xmethod[dialog% on-subwindow-char] methods consume certain keyboard events (e.g., arrow keys, Enter) used + for navigating within the window. Because the top-level window gets + the first chance to handle the keyboard event, some events never + reach the ``receiver'' child unless the default frame or dialog + method is overridden. + +} +@impl{ + +The @scheme[event] argument is the event that was generated for the + @scheme[receiver] window. Returns @scheme[#f]. + + + +}} + +@defmethod[(on-subwindow-event [receiver (is-a/c window<%>)] + [event (is-a/c mouse-event%)]) + boolean?]{ +@spec{ + +Called when this window or a child window receives a mouse event. + The +@method[window<%> on-subwindow-event] method of the receiver's top-level window is called first (see +@method[area<%> get-top-level-window]); if the return value is @scheme[#f], the +@method[window<%> on-subwindow-event] method is called for the next child in the path to the receiver, and + so on. Finally, if the receiver's +@method[window<%> on-subwindow-event] method returns @scheme[#f], the event is passed on to the + receiver's normal mouse-handling mechanism. + +} +@impl{ + +The @scheme[event] argument is the event that was generated for the + @scheme[receiver] window. Returns @scheme[#f]. + + + +}} + +@defmethod[(client->screen [x (integer-in -10000 10000)] + [y (integer-in -10000 10000)]) + two \IntsIn{-10000}{10000}]{ +@spec{ + +\index{global coordinates} +Converts local window coordinates to screen coordinates. + +}} + +@defmethod[(enable [enable? any/c]) + void?]{ +@spec{ + +Enables or disables a window so that input events are ignored. (Input + events include mouse events, keyboard events, and close-box clicks, + but not focus or update events.) When a window is disabled, input + events to its children are also ignored. + +@MonitorMethod[@elem{The enable state of a window} @elem{enabling a parent window} @elem{@method[window<%> on-superwindow-enable]} @elem{enable state}] + + +} +@impl{ + +If @scheme[enable?] is true, the window is enabled, otherwise it is + disabled. + + + +}} + +@defmethod[(is-enabled?) + boolean?]{ +@spec{ + +Returns @scheme[#t] if the window is enabled when all of its ancestors + are enabled, @scheme[#f] otherwise. + +}} + +@defmethod[(on-superwindow-enable [enabled? any/c]) + void?]{ +@spec{ + +Called via the event queue whenever the enable state of a window has + changed, either through a call to the window's +@method[window<%> enable] method, or through the enabling/disabling of one of the window's + ancestors. The method's argument indicates whether the window is now + enabled or not. + +This method is not called when the window is initially created; it is + called only after a change from the window's initial enable + state. Furthermore, if an enable notification event is queued for the + window and it reverts its enabled state before the event is + dispatched, then the dispatch is canceled. + +If the enable state of a window's ancestor changes while the window is + deleted (e.g., because it was removed with +@method[area-container<%> delete-child]), then no enable events are queued for the deleted window. But if + the window is later re-activated into an enable state that is + different from the window's state when it was de-activated, then an + enable event is immediately queued. + +}} + +@defmethod[(get-width) + (integer-in 0 10000)]{ +@spec{ + +Returns the window's current total width (in pixels). + +See also +@method[area-container<%> reflow-container]. + +}} + +@defmethod[(get-height) + (integer-in 0 10000)]{ +@spec{ + +Returns the window's total height (in pixels). + +See also +@method[area-container<%> reflow-container]. + +}} + +@defmethod[(get-x) + (integer-in -10000 10000)]{ +@spec{ + +Returns the position of the window's left edge in its + parent's coordinate system. + +See also +@method[area-container<%> reflow-container]. + +}} + +@defmethod[(get-y) + (integer-in -10000 10000)]{ +@spec{ + +Returns the position of the window's top edge in its + parent's coordinate system. + +See also +@method[area-container<%> reflow-container]. + +}} + +@defmethod[(get-label) + (or/c {\labelstring}, @scheme[bitmap%] object, @scheme['app], @scheme['caution], @scheme['stop], false/c)]{ +@spec{ + +Gets a window's label, if any. Control windows generally display their + label in some way. Frames and dialogs display their label as a window + title. Panels do not display their label, but the label can be used + for identification purposes. Messages, buttons, and check boxes can + have bitmap labels (only when they are created with bitmap labels), + but all other windows have string labels. In addition, a message + label can be an icon symbol @scheme['app], @scheme['caution], or + @scheme['stop]. + +The label string may contain ampersands (``\&''), which serve as + keyboard navigation annotations for controls under Windows and X. The + ampersands are not part of the displayed label of a control; instead, + ampersands are removed in the displayed label (under all platforms), + and any character preceding an ampersand is underlined (Windows and + X) indicating that the character is a mnemonic for the + control. Double ampersands are converted into a single ampersand + (with no displayed underline). See also + @method[top-level-window<%> on-traverse-char]. + +If the window does not have a label, @scheme[#f] is returned. + +}} + +@defmethod[(set-label [l label-string?]) + void?]{ +@spec{ + +Sets a window's label. The window's natural minimum size might be + different after the label is changed, but the window's minimum size + is not recomputed. + +See +@method[window<%> get-label] for more information. + +} +@impl{ + +If the window was not created with a label, or if the window was + created with a non-string label, @scheme[l] is ignored. + + + +}} + +@defmethod[(get-plain-label) + (or/c string false/c)]{ +@spec{ + +Like +@method[window<%> get-label], except that ampersands in the label are removed. If the window has + no label or the window's + label is not a string, @scheme[#f] is returned. + + +}} + +@defmethod[(get-handle) + exact integer]{ +@spec{ + +Returns an exact integer representing a handle to the window in the +current platform's GUI toolbox. Cast this number from a C \cpp{long} +to a platform-specific C type: +@itemize{ + + @item{Windows: \cpp{HWND}} + + @item{Mac OS X: \cpp{WindowRef} for a @scheme[top-level-window<%>] object, + \cpp{ControlRef} for other windows} + + @item{X: \cpp{Widget*}} + +} +Some windows may not have a representation in the platform's GUI level, + in which case the result of this method is @scheme[0]. + +}} + +@defmethod[(get-size) + two \IntsIn{0}{10000}]{ +@spec{ + +Gets the current size of the entire window in pixels, not counting + horizontal and vertical margins. (Under X, this size does not include + a title bar or borders for a frame/dialog.) See also +@method[window<%> get-client-size]. + +The geometry is returned as two values: width and height (in pixels). + +See also +@method[area-container<%> reflow-container]. + +}} + +@defmethod[(get-client-size) + two \IntsIn{0}{10000}]{ +@spec{ + +Gets the interior size of the window in pixels. For a container, the + interior size is the size available for placing subwindows (including + the border margin). For a canvas, this is the visible drawing + area. + +The client size is returned as two values: width and height (in pixels). + +See also +@method[area-container<%> reflow-container]. + + +}} + +@defmethod[(refresh) + void?]{ +@spec{ + +Enqueues an event to repaint the window. + +}} + +@defmethod[(screen->client [x (integer-in -10000 10000)] + [y (integer-in -10000 10000)]) + two \IntsIn{-10000}{10000}]{ +@spec{ + +\index{global coordinates} +Converts global coordinates to window local coordinates. + +}} + +@defmethod[(focus) + void?]{ +@spec{ + +\index{keyboard focus!setting} +Moves the keyboard focus to the window, relative to its top-level + window, if the window ever accepts the keyboard focus. + If the focus is in the window's top-level window, then the + focus is immediately moved to this window. Otherwise, the focus is + not immediately moved, but when the window's top-level window gets + the keyboard focus, the focus is delegated to this window. + +See also +@method[window<%> on-focus]. + +Note that under X, keyboard focus can move to the menu bar + when the user is selecting a menu item. + +@MonitorMethod[@elem{The current keyboard focus window} @elem{the user} @elem{@method[window<%> on-focus]} @elem{focus}] + +}} + +@defmethod[(has-focus?) + boolean?]{ +@spec{ + +Indicates whether the window currently has the keyboard focus. See + also +@method[window<%> on-focus]. + +}} + +@defmethod[(popup-menu [menu (is-a/c popup-menu%)] + [x (integer-in 0 10000)] + [y (integer-in 0 10000)]) + void?]{ +@spec{ + +\popupmenuinfo{window}{window}{} + +} +@impl{ + +The @scheme[menu] is popped up within the window at position + (@scheme[x], @scheme[y]). + + + +}} + +@defmethod[(set-cursor [cursor (or/c (is-a/c cursor%) false/c)]) + void?]{ +@spec{ + +Sets the window's cursor. Providing @scheme[#f] instead of a cursor + value removes the window's cursor. + +If a window does not have a cursor, it uses the cursor of its parent. + Frames and dialogs start with the standard arrow cursor, and text + fields start with an I-beam cursor. All other windows are created + without a cursor. + +}} + +@defmethod[(get-cursor) + (or/c (is-a/c cursor%) false/c)]{ +@spec{ + +Returns the window's cursor, or @scheme[#f] if this window's cursor + defaults to the parent's cursor. See +@method[window<%> set-cursor] for more information. + +}} + +@defmethod[(show [show? any/c]) + void?]{ +@spec{ + +Shows or hides a window. + +@MonitorMethod[@elem{The visibility of a window} @elem{the user clicking the window's close box, for example} @elem{@method[window<%> on-superwindow-show] or @method[top-level-window<%> on-close]} @elem{visibility}] + +} +@impl{ + +If @scheme[show?] is @scheme[#f], the window is hidden. Otherwise, the +window is shown. + + + +}} + +@defmethod[(is-shown?) + boolean?]{ +@spec{ + +Indicates whether the window is currently shown or not (when + all of its ancestors are also shown). + +The result is @scheme[#t] if this window is shown when its ancestors are + shown, or @scheme[#f] if this window remains hidden when its ancestors + are shown. + +}} + +@defmethod[(on-superwindow-show [shown? any/c]) + void?]{ +@spec{ + +Called via the event queue whenever the visibility of a window has + changed, either through a call to the window's +@method[window<%> show], through the showing/hiding of one of the window's ancestors, or + through the activating or deactivating of the window or its ancestor + in a container (e.g., via +@method[area-container<%> delete-child]). The method's argument indicates whether the window is now + visible or not. + +This method is not called when the window is initially created; it is + called only after a change from the window's initial + visibility. Furthermore, if a show notification event is queued for + the window and it reverts its visibility before the event is + dispatched, then the dispatch is canceled. + +}} + +@defmethod[(on-drop-file [pathname path]) + void?]{ +@spec{ + +\index{drag-and-drop} +Called when the user drags a file onto the window.\footnote{Under X, + drag-and-drop is supported via the XDND protocol.} Drag-and-drop + must first be enabled for the window with +@method[window<%> accept-drop-files]. + +Under Mac OS X, when the application is running and user + double-clicks an application-handled file or drags a file onto the + application's icon, the main thread's application file handler is + called (see +@scheme[application-file-handler]). The default handler calls the +@method[window<%> on-drop-file] method of the most-recently activated frame if drag-and-drop is + enabled for that frame, independent of the frame's eventspace (but + the method is called in the frame's eventspace's handler + thread). When the application is not running, the filenames are + provided as command-line arguments. + +}} + +@defmethod*[([(accept-drop-files) + boolean?] + [(accept-drop-files [accept-files? any/c]) + void?])]{ +@spec{ + +\index{drag-and-drop} +Enables or disables drag-and-drop dropping for the window, + or gets the enable + state. Dropping is initially disabled. See also +@method[window<%> on-drop-file]. + +} +@impl{ +First case: + + +Returns @scheme[#t] if file-dropping is enabled, @scheme[#f] otherwise. + + + +Second case: + + +Enables file-dropping if @scheme[accept-files?] is true, disables + file-dropping otherwise. + + + + +}}} + diff --git a/collects/scribblings/gui/windowing.scrbl b/collects/scribblings/gui/windowing.scrbl new file mode 100644 index 0000000000..b27f78f244 --- /dev/null +++ b/collects/scribblings/gui/windowing.scrbl @@ -0,0 +1,67 @@ +#reader(lib "docreader.ss" "scribble") +@require["common.ss"] + +@title[#:tag "mr:windowing" #:style 'toc]{Windowing Toolbox} + +The windowing toolbox. + +@local-table-of-contents[] + +@include-section["dialog-funcs.scrbl"] +@include-section["eventspace-funcs.scrbl"] +@include-section["system-menu-funcs.scrbl"] +@include-section["miscwin-funcs.scrbl"] + +@;{ +@require["button-class.scrbl"] +@require["canvas-intf.scrbl"] +@require["canvas-class.scrbl"] +@require["check-box-class.scrbl"] +@require["list-control-intf.scrbl"] +@require["choice-class.scrbl"] +@require["control-event-class.scrbl"] +@require["scroll-event-class.scrbl"] +@require["cursor-class.scrbl"] +@require["dialog-class.scrbl"] +@require["event-class.scrbl"] +@require["top-level-window-intf.scrbl"] +@require["frame-class.scrbl"] +@require["gauge-class.scrbl"] +@require["control-intf.scrbl"] +@require["key-event-class.scrbl"] +@require["list-box-class.scrbl"] +@require["menu-item-intf.scrbl"] +@require["separator-menu-item-class.scrbl"] +@require["labelled-menu-item-intf.scrbl"] +@require["selectable-menu-item-intf.scrbl"] +@require["menu-item-class.scrbl"] +@require["checkable-menu-item-class.scrbl"] +@require["menu-item-container-intf.scrbl"] +@require["menu-class.scrbl"] +@require["popup-menu-class.scrbl"] +@require["menu-bar-class.scrbl"] +@require["message-class.scrbl"] +@require["mouse-event-class.scrbl"] +@require["panel-class.scrbl"] +@require["horizontal-panel-class.scrbl"] +@require["vertical-panel-class.scrbl"] +@require["tab-panel-class.scrbl"] +@require["group-box-panel-class.scrbl"] +@require["pane-class.scrbl"] +@require["horizontal-pane-class.scrbl"] +@require["vertical-pane-class.scrbl"] +@require["grow-box-spacer-pane-class.scrbl"] +@require["area-container-window-intf.scrbl"] +@require["radio-box-class.scrbl"] +@require["slider-class.scrbl"] +@require["text-field-class.scrbl"] +@require["combo-field-class.scrbl"] +@require["timer-class.scrbl"] +@require["area-intf.scrbl"] +@require["area-container-intf.scrbl"] +@require["subarea-intf.scrbl"] +@require["window-intf.scrbl"] +@require["subwindow-intf.scrbl"] +@require["clipboard-intf.scrbl"] +@require["clipboard-client-class.scrbl"] +} diff --git a/collects/scribblings/reference/contracts.scrbl b/collects/scribblings/reference/contracts.scrbl index e642f700f8..01ddb252e4 100644 --- a/collects/scribblings/reference/contracts.scrbl +++ b/collects/scribblings/reference/contracts.scrbl @@ -117,7 +117,7 @@ Like @scheme[=].} -@defproc[(real-in [n real?][m meal?]) flat-contract?]{ +@defproc[(real-in [n real?][m real?]) flat-contract?]{ Returns a flat contract that requires the input to be a real number between @scheme[n] and @scheme[m], inclusive.} diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index 6e025a1421..395a7eb6cf 100644 --- a/collects/scribblings/scribble/manual.scrbl +++ b/collects/scribblings/scribble/manual.scrbl @@ -109,13 +109,6 @@ module whose language is @scheme[lang].} a single line and wrapped with its enclosing paragraph, independent of the formatting of @scheme[datum].} -@defform[(indexed-scheme datum ...)]{ - -A combination of @scheme[scheme] and @scheme[as-index], with the -special case that if a single @scheme[datum] is provided and it is a -@scheme[quote] form, then the quote is removed from the key (so that -it's sorted using its unquoted form).} - @defform[(schemeresult datum ...)]{Like @scheme[scheme], but typeset as a REPL value (i.e., a single color with no hyperlinks).} @@ -504,6 +497,22 @@ the link.} @; ------------------------------------------------------------------------ @section{Indexing} +@defform[(indexed-scheme datum ...)]{ + +A combination of @scheme[scheme] and @scheme[as-index], with the +following special cases when a single @scheme[datum] is provided: + + @itemize{ + + @item{If @scheme[datum] is a @scheme[quote] form, then the quote is + removed from the key (so that it's sorted using its unquoted + form).} + + @item{If @scheme[datum] is a string, then quotes are removed from the + key (so that it's sorted using the string content).} + +}} + @defproc[(idefterm [pre-content any/c] ...) element?]{Combines @scheme[as-index] and @scheme[defterm]. The content normally should be plural, rather than singular. Consider using @scheme[deftech],