diff --git a/collects/scribblings/gui/canvas-class.scrbl b/collects/scribblings/gui/canvas-class.scrbl index 83ac0735..d8d5e74d 100644 --- a/collects/scribblings/gui/canvas-class.scrbl +++ b/collects/scribblings/gui/canvas-class.scrbl @@ -7,22 +7,24 @@ 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]]{ +@defconstructor[([parent (or/c (is-a/c frame%) (is-a/c dialog%) + (is-a/c panel%) (is-a/c pane%))] + [style (listof (symbols/c no-focus transparent no-autoclear + deleted gl resize-corner hscroll vscroll + combo control-border border)) null] + [paint-callback ((is-a/c button%) (is-a/c dc<%>) . -> . any) 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) _graphical-minimum-width] + [min-height (integer-in 0 10000) _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} @@ -86,52 +88,44 @@ The @scheme[gl-config] argument determines properties of an OpenGL @WindowKWs[] @SubareaKWs[] @AreaKWs[] - - } @defmethod[(with-gl-context [thunk (-> any)]) any]{ -@spec{ - Passes the given thunk to -@method[gl-context<%> call-as-current] % +@method[gl-context<%> call-as-current] of the result of -@method[dc<%> get-gl-context] % +@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[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] % +@method[gl-context<%> swap-buffers] on the result of -@method[dc<%> get-gl-context] % +@method[dc<%> get-gl-context] for this canvas's DC as returned by @method[canvas<%> get-dc]. The -@method[gl-context<%> swap-buffers] % +@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. @@ -141,37 +135,33 @@ This method is called only when manual 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. - - -}} +See also +@method[canvas% init-manual-scrollbars]. +} @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.) +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. + @MonitorMethod[@elem{The value of the canvas's scrollbar} @elem{the user scrolling} @elem{@method[canvas% on-scroll]} @elem{scrollbar value}] See also @@ -179,125 +169,83 @@ See also @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. - - -}} +See also +@method[canvas% init-manual-scrollbars]. +} @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. - - -}} +See also +@method[canvas% init-manual-scrollbars]. +} @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. - - -}} +See also +@method[canvas% init-manual-scrollbars]. +} @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. +See also +@method[canvas% init-manual-scrollbars]. - -}} +} @defmethod[(get-virtual-size) - two \IntsIn{0}{10000}]{ -@spec{ - + (value (integer-in 0 10000) (integer-in 0 10000))]{ 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. @@ -306,23 +254,20 @@ The @scheme[h-value] and @scheme[v-value] arguments each specify a fraction 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])))}. + @scheme[c], and @scheme[(> v c)], then scrolling to @scheme[p] + sets the view start to @scheme[(floor (* p (- v 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 @@ -341,11 +286,7 @@ See also 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 +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. @@ -359,9 +300,7 @@ 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)] @@ -370,7 +309,6 @@ See also [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 @@ -388,9 +326,6 @@ See also 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 @@ -404,108 +339,77 @@ 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 + 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]. +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|. + + +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{ + (values (integer-in 0 10000) (integer-in 0 10000))]{ -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. +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])}. +@method[canvas% init-manual-scrollbars]), the result is @scheme[(values 0 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. +@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 index 058699c3..47e865a3 100644 --- a/collects/scribblings/gui/canvas-intf.scrbl +++ b/collects/scribblings/gui/canvas-intf.scrbl @@ -25,13 +25,13 @@ The @scheme[canvas<%>] interface is implemented by two classes: @defmethod[(on-char [ch (is-a/c key-event%)]) void?]{ -@spec{ +@methspec{ Called when the canvas receives a keyboard event. See also @|mousekeydiscuss|. } -@impl{ +@methimpl{ Does nothing. @@ -41,14 +41,14 @@ Does nothing. @defmethod[(on-event [event (is-a/c mouse-event%)]) void?]{ -@spec{ +@methspec{ Called when the canvas receives a mouse event. See also @|mousekeydiscuss|, noting in particular that certain mouse events can get dropped. } -@impl{ +@methimpl{ Does nothing. @@ -58,7 +58,7 @@ Does nothing. @defmethod[(on-paint) void?]{ -@spec{ +@methspec{ Called when the canvas is exposed or resized so that the image in the canvas can be repainted. @@ -71,7 +71,7 @@ When @method[dc<%> get-clipping-region] does not change. } -@impl{ +@methimpl{ Does nothing. @@ -81,7 +81,7 @@ Does nothing. @defmethod[(on-tab-in) void?]{ -@spec{ +@methspec{ Called when the keyboard focus enters the canvas via keyboard navigation events. The @@ -94,7 +94,7 @@ See also @xmethod[top-level-window<%> on-traverse-char] . } -@impl{ +@methimpl{ Does nothing. @@ -104,18 +104,15 @@ 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 @@ -123,32 +120,15 @@ Gets or sets the canvas's minimum width for geometry management, based @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 + @tech{graphical minimum 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 @@ -156,39 +136,19 @@ Gets or sets the canvas's minimum height for geometry management, @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 + @tech{graphical minimum 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 @@ -196,21 +156,12 @@ Sets the color used to ``erase'' the canvas content before canvas is delayed by other activity.) If the canvas was created with the @indexed-scheme['transparent] style, - @|MismatchExn|}. + @|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]. @@ -219,11 +170,10 @@ 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 @@ -232,10 +182,5 @@ Under Mac OS X, enables or disables space for a resize tab at the 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 index 267be9b7..29df8036 100644 --- a/collects/scribblings/gui/check-box-class.scrbl +++ b/collects/scribblings/gui/check-box-class.scrbl @@ -13,19 +13,20 @@ Whenever a check box is clicked by the user, the check box's value is -@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]]{ +@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 check-box) (is-a/c control-event%) . -> . any) (lambda (c e) (void))] + [style (listof (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) _graphical-minimum-width] + [min-height (integer-in 0 10000) _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] @@ -34,7 +35,7 @@ Creates a check box with a string or bitmap label. @bitmaplabeluse[label] The @scheme[callback] procedure is called (with the event type @indexed-scheme['check-box]) whenever the user clicks the check box. -\DeletedStyleNote{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. @@ -47,46 +48,34 @@ If @scheme[value] is true, it is passed to @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.) +Sets the check box's state. (The control's callback procedure is +@italic{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/windowing.scrbl b/collects/scribblings/gui/windowing.scrbl index 517f9a20..7c538e1c 100644 --- a/collects/scribblings/gui/windowing.scrbl +++ b/collects/scribblings/gui/windowing.scrbl @@ -19,6 +19,15 @@ The windowing toolbox. @require["button-class.scrbl"] @include-class[button%] +@require["canvas-class.scrbl"] +@include-class[canvas%] + +@require["canvas-intf.scrbl"] +@include-class[canvas<%>] + +@require["check-box-class.scrbl"] +@include-class[check-box%] + @require["control-intf.scrbl"] @include-class[control<%>]