15.3.723  src/lib/x-kit/widget/old/text/string-editor.api

## string-editor.api
#
# Compare to:
#     src/lib/x-kit/widget/old/text/scrollable-string-editor.api
#
#
#     "The [string_editor package] provides a simple string editing wdiget.
#      As the user types, the corresponding characters are entered at the
#      cursor position.  The backspace character ("\h") can be used to
#      erase the character preceding the cursor.  The entire string can
#      be deleted by typing "\X".  The user can reposition the cursor
#      by clicking the mouse on the desired character.  If the insertion
#      or deletion of a character would cause the cursor to move off the
#      window, the widget shifts the window's view appropriately."
#
#         -- p32, Gansner+Reppy's 1993 eXene widget manual,
#            http://mythryl.org/pub/exene/1993-widgets.ps
#
# The widget initially places the cursor
# at the end of the given string.
#
# The widget fixes its height preference
# at the height of the font.  Horizontally,
# it sets a best_size of the length of
# the string or min_length, whichever is
# larger.  It will expand indefinitely,
# but will not contract below min_length.
# Whenever the widget's string goes from
# fitting to not fitting within the widget's
# window, or vice versa, it requests that its
# parent resize it.
#
# The widget does not provide the user the ability
# to move the widget's window over the text.  It
# does provide the shift_window function, which
# the application can use to provide this service.
#

# Compiled by:
#     src/lib/x-kit/widget/xkit-widget.sublib



# This api is implemented in:
#
#     src/lib/x-kit/widget/old/text/string-editor.pkg

stipulate
    package wg =  widget;                               # widget                is from   src/lib/x-kit/widget/old/basic/widget.pkg
    package xc =  xclient;                              # xclient               is from   src/lib/x-kit/xclient/xclient.pkg
herein

    api String_Editor {

        String_Editor;

        make_string_editor
            :
            wg::Root_Window
            ->
            {
              foreground:     Null_Or( xc::Rgb ),               # Black by default.
              background:     Null_Or( xc::Rgb ),               # White by default.
              initial_string: String,
              min_length:     Int
            }
            ->
            String_Editor;

        set_string:    String_Editor -> String -> Void;
        get_string:    String_Editor -> String;
        shift_window:  String_Editor -> Int -> Void;            # Shift window over string. (Negative => to left.)

        as_widget:     String_Editor -> wg::Widget;
    };

end;