suzanne.soy/gui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

a bit more gui doc work

Browse Source 
svn: r7073

original commit: 907e3a6b1caffb6e37049252915a3561417bab2a
This commit is contained in:
Matthew Flatt 2007-08-09 22:58:36 +00:00
parent f0949ef6ba
commit 198c95521b
4 changed files with 128 additions and 281 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

264
collects/scribblings/gui/canvas-class.scrbl
View File

@ -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.
}}}
}}

85
collects/scribblings/gui/canvas-intf.scrbl
View File

@ -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{
}}}
}}

51
collects/scribblings/gui/check-box-class.scrbl
View File

@ -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.
}}}
}}

9
collects/scribblings/gui/windowing.scrbl
View File

@ -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<%>]