54ab1bfbfa
It's very helpful to have a visual aid when dealing with a graphical interface toolkit. This patch adds an overview of the widgets available in the library consisting of screen shots of the main ones and the snippets used to produce them. Each widget image link back to the full documentation.
149 lines
5.5 KiB
Racket
149 lines
5.5 KiB
Racket
#lang scribble/doc
|
|
@(require "common.rkt")
|
|
|
|
@centered{@image[#:suffixes @list[".png"]]{image/text-field}}
|
|
|
|
@defclass/title[text-field% object% (control<%>)]{
|
|
|
|
A @racket[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 Return or 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 @racket[text%] editor (with an
|
|
inaccessible display). Thus, whereas @racket[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
|
|
@racket[current-text-keymap-initializer] parameter.
|
|
|
|
|
|
@defconstructor[([label (or/c label-string? #f)]
|
|
[parent (or/c (is-a?/c frame%) (is-a?/c dialog%)
|
|
(is-a?/c panel%) (is-a?/c pane%))]
|
|
[callback ((is-a?/c text-field%) (is-a?/c control-event%)
|
|
. -> . any)
|
|
(lambda (t e) (void))]
|
|
[init-value string? ""]
|
|
[style (listof (or/c 'single 'multiple 'hscroll 'password
|
|
'vertical-label 'horizontal-label
|
|
'deleted))
|
|
'(single)]
|
|
[font (is-a?/c font%) 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 #t]
|
|
[stretchable-height any/c (memq 'multiple style)])]{
|
|
|
|
If @racket[label] is not @racket[#f], it is used as the text field
|
|
label. Otherwise, the text field does not display its label.
|
|
|
|
@labelstripped[@racket[label] @elem{} @elem{move the keyboard focus to the text field}]
|
|
|
|
The @racket[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-racket['text-field-enter], otherwise it is
|
|
@indexed-racket['text-field].
|
|
|
|
If @racket[init-value] is not @racket[""], the @tech{graphical minimum size} for the
|
|
text item is made wide enough to show @racket[init-value]. Otherwise,
|
|
a built-in default width is selected. For a text field in single-line
|
|
mode, the @tech{graphical minimum size} is set to show one line, and only the
|
|
control's width is stretchable by default. For a multiple-line text field, the
|
|
@tech{graphical minimum size} shows three lines of text, and it is stretchable in both
|
|
directions by default.
|
|
|
|
The style must contain exactly one of @racket['single] or
|
|
@racket['multiple]; the former specifies a single-line field and the
|
|
latter specifies a multiple-line field. The @racket['hscroll] style
|
|
applies only to multiple-line fields; when @racket['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 @racket['password] style indicates that the
|
|
field should draw each character of its content using a generic
|
|
symbol instead of the actual character. @HVLabelNote[@racket[style]]{text field}
|
|
@DeletedStyleNote[@racket[style] @racket[parent]]{text field}.
|
|
|
|
@FontKWs[@racket[font]] @WindowKWs[@racket[enabled]] @SubareaKWs[] @AreaKWs[]
|
|
|
|
}
|
|
|
|
|
|
@defmethod[(get-editor)
|
|
(is-a?/c text%)]{
|
|
|
|
Returns the editor used to implement the text field.
|
|
|
|
For a text field, the most useful methods of a @racket[text%] object
|
|
are the following:
|
|
@itemize[
|
|
|
|
@item{@racket[(send a-text @#,method[text% get-text])] returns
|
|
the current text of the editor.}
|
|
|
|
@item{@racket[(send a-text @#,method[text% erase])] deletes all text from
|
|
the editor.}
|
|
|
|
@item{@racket[(send a-text @#,method[text% insert] _str)] inserts
|
|
@racket[_str] into the editor at the current caret position.}
|
|
|
|
]
|
|
}
|
|
|
|
|
|
@defmethod[(get-field-background) (is-a?/c color%)]{
|
|
|
|
Gets the background color of the field's editable area.}
|
|
|
|
|
|
@defmethod[(get-value)
|
|
string?]{
|
|
|
|
Returns the text currently in the text field.
|
|
|
|
}
|
|
|
|
|
|
@defmethod[(set-field-background [color (is-a?/c color%)])
|
|
void?]{
|
|
|
|
Sets the background color of the field's editable area.}
|
|
|
|
|
|
@defmethod[(set-value [val string?])
|
|
void?]{
|
|
|
|
Sets the text currently in the text field. (The control's callback
|
|
procedure is @italic{not} invoked.)
|
|
|
|
@MonitorCallback[@elem{A text field's value} @elem{the user typing into the control} @elem{value}]
|
|
|
|
}}
|