The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Fl-0.99.15
River stage zero No dependents
1 ++
/ Fl::Input

NAME

Fl::Input - Text Input Widget

Synopsis

    use Fl;
    my $input = Fl::Input->new(0, 0, 100, 200, 'Hello, World!');

Description

The Fl::Input class represents a widget that displays a single line of text and lets the user edit it.

Normally it is drawn with an inset box and a white background. The text may contain any characters, and will correctly display any UTF text, using ^X notation for unprintable control characters. It assumes the font can draw any characters of the used scripts, which is true for standard fonts under MSWindows and Mac OS X. Characters can be input using the keyboard or the character palette/map. Character composition is done using dead keys and/or a compose key as defined by the operating system.

Keyboard and Mouse Bindings

Mouse button 1 Moves the cursor to this point. Drag selects characters. Double click selects words. Triple click selects all line. Shift+click extends the selection. When you select text it is automatically copied to the selection buffer.
Mouse button 2 Insert the selection buffer at the point clicked. You can also select a region and replace it with the selection buffer by selecting the region with mouse button 2.
Mouse button 3 Currently acts like button 1.
Backspace Deletes one character to the left, or deletes the selected region.
Delete Deletes one character to the right, or deletes the selected region. Combine with Shift for equivalent of ^X (copy+cut).
Enter May cause the callback, see when().
Windows/Linux Mac

Function

^A Command-A

Selects all text in the widget.

^C Command-C

Copy the current selection to the clipboard.

^I ^I

Insert a tab.

^J ^J

Insert a Line Feed.
(Similar to literal 'Enter' character)

^L ^L

Insert a Form Feed.

^M ^M

Insert a Carriage Return.

^V,
Shift-Insert 		Command-V

Paste the clipboard.
(Macs keyboards don't have "Insert" keys, but if they did, Shift-Insert would work)

^X,
Shift-Delete 		Command-X,
Shift-Delete

Cut.
Copy the selection to the clipboard and delete it. (If there's no selection, Shift-Delete acts like Delete)

^Z Command-Z

Undo.
This is a single-level undo mechanism, but all adjacent deletions and insertions are concatenated into a single "undo". Often this will undo a lot more than you expected.

Shift-^Z Shift-Command-Z

Redo.
Currently same behavior as ^Z. Reserved for future multilevel undo/redo.

Arrow Keys Arrow Keys

Standard cursor movement.
Can be combined with Shift to extend selection.

Home Command-Up,
Command-Left

Move to start of line.
Can be combined with Shift to extend selection.

End Command-Down,
Command-Right

Move to end of line.
Can be combined with Shift to extend selection.

Ctrl-Home Command-Up,
Command-PgUp,
Ctrl-Left

Move to top of document/field.
In single line input, moves to start of line. In multiline input, moves to start of top line. Can be combined with Shift to extend selection.

Ctrl-End Command-End,
Command-PgDn,
Ctrl-Right

Move to bottom of document/field.
In single line input, moves to end of line. In multiline input, moves to end of last line. Can be combined with Shift to extend selection.

Ctrl-Left Alt-Left

Word left.
Can be combined with Shift to extend selection.

Ctrl-Right Alt-Right

Word right.
Can be combined with Shift to extend selection.

Ctrl-Backspace Alt-Backspace

Delete word left.

Ctrl-Delete Alt-Delete

Delete word right.

Methods

Fl::Input inherits from Fl::Widget. On top of that, it exposes the following methods...

new(...)

    my $text_a = Fl::Input->new(0, 0, 250, 500, 'Important Stuff');
    my $text_b = Fl::Input->new(0, 0, 250, 500);

The constructor creates a new widget using the given position, size, and label.

The widget's boxtype is FL_DOWN_BOX by default.

The destructor removes the widget.

copy(...)

Put the current selection into the clipboard.

    my $ok = $input->copy(1); # into clipboard #1

This function copies the current selection between mark() and position() into the specified clipboard. This does not replace the old clipcoard contents if position() and mark() are equal.

Clipboard 0 maps to the current text selection and clipboard 1 maps to the OS's cut/paste clipboard.

Returns a true value if the selection was copied sucessfully.

See also Fl::copy(...).

copy_cuts()

Copys the yank buffer to the clipboard.

    $input->copy_cuts();

This method copies all the previous contiguous cuts from the undo information to the clipboard. This functions implements the ^K shortcut key.

Returns a false value if the clipboard is unchanged.

cursor_color(...)

Gets or sets the color of hte cursor.

    my $color = $input->cursor_color();
    $input->cursor_color(FL_RED);

The default color is FL_BLACK.

cut(...)

Deletes text from the widget without storing it in the clipboard.

    $input->cut();

Deletes the current selection.

    $input->cut(24);

Deletes the next N bytes (here, 24) rounded to characters before or after the cursor. Negative numbers will cut characters to the left of the cursor.

    $input->cut(20, 25);

Deletes all characters between indexs $a and $b (here, 20 and 25).

To use the clipboard, you may call copy() first or copy_cuts() after this call.

Returns 0 if no data was cut.

index(...)

Returns the character at index <$i>.

    my $chr = $input->index(10);

Returns the UTF-8 character at $i as a UTF-32/UCS-4 character code.

input_type(...)

Gets or sets the input field's type.

    my $type = $input->input_type();
    $input->input_type($type);

Cinsert(...)>

Inserts text at the cursor position.

    $input->insert("new text!");

This function inserts the string at the cursor position() and moves the new position mark to the end of the inserted text.

mark(...)

Gets or sets the current selection mark.

    my $m = $input->mark();
    $input->input_type($m);

When a value is provided, this behaves the same as setting position()...

    $input->mark(3);
    $input->position($input->position(), 3);

...so the two above lines should have the same effect.

maximum_size(...)

Gets or sets the maximum length of the input field in characters.

    $input->maximum_size(256);

This is different than the buffer size since one character can be more than a single byte in UTF-8 encoding.

position(...)

    my $p = $input->posiiton();

Returns the position of the text cursor as an index in the range 0..size().

    $input->position($p + 2);

Sets the curosr position and mark.

The above example is the same as callingposition($p + 2, $p + 2).

    $input->position($p + 2, 10);

Sets the index for both the cursor and mark.

The input widget maintains two pointers into the string. The position is where the cursor is. The mark is the other end of the selected text. If they are equal then there is no selection. Changing this does not affect the clipboard. Use copy() to do that.

The return value is zero if no positions were changed.

readonly(...)

Gets or sets the read-only state of the input field.

    my $mod = $input->readonly();
    $input->readonly(1);

replace(...)

    $input->replace($b, $e, $text);

Deletes text from $b to $e and inserts the new string $text.

All changes to the text buffer go through this function. It deletes the region between $b and $e (either one may be less or equal to the other), and then inserts the string text at that point and moves the mark() and position() to the end of the insertion. Does the callback if when() & FL_WHEN_CHANGED and there is a change.

Set $b and $e equal to not delete anything. Set text to undef to not insert anything.

    $input->replace($b, $e, $text, $len);

$len can be zero but defaults to the length of $text. Or you can be use it to insert a portion of a string. If $len is zero, length($text) is used instead.

$b and $e are clamped to the 0..size() range, so it is safe to pass any values. $b, $e, and $len are used as numbers of bytes (not characters), where $b and $e count from 0 to size() (end of buffer).

If $b and/or $e don't point to a valid UTF-8 character boundary, they are adjusted to the previous ($b) or the next ($e) valid UTF-8 character boundary.

If the current number of characters in the buffer minus deleted characters plus inserted characters in text would overflow the number of allowed characters (maximum_size()), then only the first characters of the string are inserted, so that maximum_size() is not exceeded.

cut() and insert() are just inline functions that call replace().

shortcut(...)

Gets or sets the shortcut related to this widget.

size()

Returns the number of bytes in value().

    my $len = $input->size();

size(...)

Sets the width and height of this widget.

    $input->size(250, 300);

tab_nav(...)

Sets whether the Tab key does focus navigation, or inserts tab characters into Fl::MultilineInput.

    $input->tab_nav(!!1);

By default this flag is enabled to provide the 'normal' behavior most users expect; Tab navigates focus to the next widget. To inserting an actual Tab character, users can use Ctrl-I or copy/paste.

Disabling this flag gives the behavior where Tab inserts a tab character into the text field, in which case only the mouse can be used to navigate to the next field.

tab_nav()

Gets whether the Tab key causes focus navigation in multiline input fields or not.

    my $tab_next = $input->tab_nav();

If enabled (default), hitting Tab causes focus navigation to the next widget.

If disabled, hitting Tab inserts a tab character into the text field.

textcolor(...)

    $input->textcolor(FL_BLACK);
    my $color = $input->textcolor();

Gets or sets the input's text color.

textfont(...)

    $input->textfont(FL_COURIER_BOLD);
    my $font = $input->textfont();

Gets or sets the input's font.

textsize(...)

    $input->textsize(100);
    $input->textsize(FL_NORMAL_SIZE);

Sets the input's text size.

undo()

    $input->undo();

Undoes previous changes to the text buffer.

This call undoes a number of previous calls to replace(...).

Returns a true value if any changes were made.

value(...)

Gets or sets the widget's text.

    $input->value("Update!");
    my $text = $input->value();
    $input->value('Just part of this', 9);

This function changes the text and sets the mark and the point to the end of it. The string is copied to the internal buffer. Passing undef is the same as "".

You can use the length parameter to directly set the length if you know it already or want to put null characters in the text.

wrap(...)

    $input->wrap(1);
    my $wraps = $input->wrap();

Sets or gets word wrapping state of the input field.

Word wrap is only functional with multi-line input fields such as Fl::MultilineInput.

LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Sanko Robinson <sanko@cpan.org>