3.47  text-field%

Implements: control<%>

A text-field% object is an editable text field with an optional label displayed in front of it. There are two text field styles:

• 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 on-traverse-char in top-level-window<%> ).

• 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 text% editor (with an inaccessible display). Thus, whereas text-field% provides only get-value and set-value to manipulate the text in a text field, the 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 current-text-keymap-initializer parameter.

• (new text-field% (label _) (parent _) [(callback _)] [(init-value _)] [(style _)] [(font _)] [(enabled _)] [(vert-margin _)] [(horiz-margin _)] [(min-width _)] [(min-height _)] [(stretchable-width _)] [(stretchable-height _)]) -> text-field% object
     label : string (up to 200 characters) or #f
   parent : frame%, dialog%, panel%, or pane% object
     callback = (lambda (tf e) (void)) : procedure of two arguments: a text-field% object and a control-event% object
     init-value = "" : string
     style = '(single) : list of symbols in '(single multiple hscroll password vertical-label horizontal-label deleted)
   font = normal-control-font : font% object
     enabled = #t : boolean
     vert-margin = 2 : exact integer in [0, 1000]
     horiz-margin = 2 : exact integer in [0, 1000]
     min-width = graphical minimum width : exact integer in [0, 10000]
     min-height = graphical minimum height : exact integer in [0, 10000]
     stretchable-width = #t : boolean
     stretchable-height = #t for 'multiple style, #f otherwise : boolean

  If label is not #f, it is used as the text field label. Otherwise, the text field does not display its label.

  If an ampersand (``&'') occurs in label, it is specially parsed; under Windows and X, the character following an ampersand 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 move the keyboard focus to the text field 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 label before it is displayed for the control; a double-ampersand in label 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 on-traverse-char (but not under Mac OS X).

  The 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 on-traverse-char in top-level-window<%> ). If the user presses Enter, the type of event passed to the callback is 'text-field-enter, otherwise it is 'text-field.

  If init-value is not "", the minimum width of the text item is made wide enough to show 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 'single or 'multiple; the former specifies a single-line field and the latter specifies a multiple-line field. The 'hscroll style applies only to multiple-line fields; when '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 'password style indicates that the field should draw each character of its content using a generic symbol instead of the actual character. If style includes 'vertical-label, then the text field is created with a label above the control; if style does not include 'vertical-label (and optionally includes 'horizontal-label), then the label is created to the left of the text field. If style includes 'deleted, then the text field is created as hidden, and it does not affect its parent's geometry; the text field can be made active later by calling parent's add-child method. .

  The font argument determines the font for the control. For information about the enabled argument, see window<%>. For information about the horiz-margin and vert-margin arguments, see subarea<%>. For information about the min-width, min-height, stretchable-width, and stretchable-height arguments, see area<%>.

  
  

Methods
    get-editor
    get-value
    set-value

All Methods
    accept-drop-files from window<%>
    client->screen from window<%>
    command from control<%>
    enable from window<%>
    focus from window<%>
    get-client-size from window<%>
    get-cursor from window<%>
    get-editor from text-field%
    get-font from control<%>
    get-graphical-min-size from area<%>
    get-handle from window<%>
    get-height from window<%>
    get-label from window<%>
    get-parent from area<%>
    get-plain-label from window<%>
    get-size from window<%>
    get-top-level-window from area<%>
    get-value from text-field%
    get-width from window<%>
    get-x from window<%>
    get-y from window<%>
    has-focus? from window<%>
    horiz-margin from subarea<%>
    is-enabled? from window<%>
    is-shown? from window<%>
    min-height from area<%>
    min-width from area<%>
    on-drop-file from window<%>
    on-focus from window<%>
    on-move from window<%>
    on-size from window<%>
    on-subwindow-char from window<%>
    on-subwindow-event from window<%>
    on-superwindow-enable from window<%>
    on-superwindow-show from window<%>
    popup-menu from window<%>
    refresh from window<%>
    screen->client from window<%>
    set-cursor from window<%>
    set-label from window<%>
    set-value from text-field%
    show from window<%>
    stretchable-height from area<%>
    stretchable-width from area<%>
    vert-margin from subarea<%>