summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/Entry.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Entry.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Entry.pod693
1 files changed, 0 insertions, 693 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Entry.pod b/Master/tlpkg/tlperl/lib/Tk/Entry.pod
deleted file mode 100644
index 1b6dbf15482..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Entry.pod
+++ /dev/null
@@ -1,693 +0,0 @@
-# Copyright (c) 1990-1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Entry - Create and manipulate Entry widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-S< >I<$entry> = I<$parent>-E<gt>B<Entry>(?I<options>?);
-
-=head1 STANDARD OPTIONS
-
-B<-background> B<-highlightbackground> B<-insertontime> B<-selectforeground>
-B<-borderwidth> B<-highlightcolor> B<-insertwidth> B<-takefocus>
-B<-cursor> B<-highlightthickness> B<-justify> B<-textvariable>
-B<-exportselection> B<-insertbackground> B<-relief> B<-xscrollcommand>
-B<-font> B<-insertborderwidth> B<-selectbackground>
-B<-foreground> B<-insertofftime> B<-selectborderwidth>
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Command-Line Name: B<-disabledbackground>
-
-=item Database Name: B<disabledBackground>
-
-=item Database Class: B<DisabledBackground>
-
-Specifies the background color to use when the entry is disabled. If
-this option is the empty string, the normal background color is used.
-
-=item Command-Line Name: B<-disabledforeground>
-
-=item Database Name: B<disabledForeground>
-
-=item Database Class: B<DisabledForeground>
-
-Specifies the foreground color to use when the entry is disabled. If
-this option is the empty string, the normal foreground color is used.
-
-=item Name: B<invalidCommand>
-
-=item Class: B<InvalidCommand>
-
-=item Switch: B<-invalidcommand>
-
-=item Alias: B<-invcmd>
-
-Specifies a script to eval when B<validateCommand> returns 0.
-Setting it to <undef> disables this feature (the default). The best use
-of this option is to set it to I<bell>. See B<Validation>
-below for more information.
-
-=item Command-Line Name: B<-readonlybackground>
-
-=item Database Name: B<readonlyBackground>
-
-=item Database Class: B<ReadonlyBackground>
-
-Specifies the background color to use when the entry is read-only. If
-this option is the empty string, the normal background color is used.
-
-=item Name: B<show>
-
-=item Class: B<Show>
-
-=item Switch: B<-show>
-
-If this option is specified, then the true contents of the entry
-are not displayed in the window.
-Instead, each character in the entry's value will be displayed as
-the first character in the value of this option, such as ``*''.
-This is useful, for example, if the entry is to be used to enter
-a password.
-If characters in the entry are selected and copied elsewhere, the
-information copied will be what is displayed, not the true contents
-of the entry.
-
-=item Name: B<state>
-
-=item Class: B<State>
-
-=item Switch: B<-state>
-
-Specifies one of three states for the entry: B<normal>, B<disabled>, or
-B<readonly>. If the entry is B<readonly>, then the value may not be changed
-using widget commands and no insertion cursor will be displayed, even
-if the input focus is in the widget; the contents of the widget may
-still be selected. If the entry is B<disabled>, the value may not be
-changed, no insertion cursor will be displayed, the contents will not
-be selectable, and the entry may be displayed in a different color,
-depending on the values of the B<-disabledforeground> and
-B<-disabledbackground> options.
-
-=item Name: B<validate>
-
-=item Class: B<Validate>
-
-=item Switch: B<-validate>
-
-Specifies the mode in which validation should operate: B<none>,
-B<focus>, B<focusin>, B<focusout>, B<key>, or B<all>.
-It defaults to B<none>. When you want validation, you must explicitly
-state which mode you wish to use. See B<Validation> below for more.
-
-=item Name: B<validateCommand>
-
-=item Class: B<ValidateCommand>
-
-=item Switch: B<-validatecommand>
-
-=item Alias: B<-vcmd>
-
-Specifies a script to eval when you want to validate the input into
-the entry widget. Setting it to C<undef> disables this feature (the default).
-This command must return a valid boolean value. If it returns 0 (or
-the valid boolean equivalent) then it means you reject the new edition
-and it will not occur and the B<invalidCommand> will be evaluated if it
-is set. If it returns 1, then the new edition occurs.
-See B<Validation> below for more information.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies an integer value indicating the desired width of the entry window,
-in average-size characters of the widget's font.
-If the value is less than or equal to zero, the widget picks a
-size just large enough to hold its current text.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Entry> method creates a new window (given by the
-$entry argument) and makes it into an entry widget.
-Additional options, described above, may be specified on the
-command line or in the option database
-to configure aspects of the entry such as its colors, font,
-and relief. The B<entry> command returns its
-$entry argument. At the time this command is invoked,
-there must not exist a window named $entry, but
-$entry's parent must exist.
-
-An entry is a widget that displays a one-line text string and
-allows that string to be edited using methods described below, which
-are typically bound to keystrokes and mouse actions.
-When first created, an entry's string is empty.
-A portion of the entry may be selected as described below.
-If an entry is exporting its selection (see the B<exportSelection>
-option), then it will observe the standard X11 protocols for handling the
-selection; entry selections are available as type B<STRING>.
-Entries also observe the standard Tk rules for dealing with the
-input focus. When an entry has the input focus it displays an
-I<insertion cursor> to indicate where new characters will be
-inserted.
-
-Entries are capable of displaying strings that are too long to
-fit entirely within the widget's window. In this case, only a
-portion of the string will be displayed; methods described below
-may be used to change the view in the window. Entries use
-the standard B<xScrollCommand> mechanism for interacting with
-scrollbars (see the description of the B<-xscrollcommand> option
-for details). They also support scanning, as described below.
-
-=head1 VALIDATION
-
-Validation of entry widgets is derived from part of the patch written by
-jhobbs@cs.uoregon.edu. This works by setting the B<validateCommand>
-option to a callback which will be evaluated according to the B<validate>
-option as follows:
-
-=over 4
-
-=item B<none>
-
-Default. This means no validation will occur.
-
-=item B<focus>
-
-B<validateCommand> will be called when the entry receives or
-loses focus.
-
-=item B<focusin>
-
-B<validateCommand> will be called when the entry receives focus.
-
-=item B<focusout>
-
-B<validateCommand> will be called when the entry loses focus.
-
-=item B<key>
-
-B<validateCommand> will be called when the entry is edited.
-
-=item B<all>
-
-B<validateCommand> will be called for all above conditions.
-
-=back
-
-The B<validateCommand> and B<invalidCommand> are called with the following
-arguments:
-
-=over 4
-
-=item * The proposed value of the entry. If you are configuring the
-entry widget to have a new textvariable, this will be the value of that
-textvariable.
-
-=item * The characters to be added (or deleted). This will be C<undef>
-if validation is due to focus, explcit call to validate or if change
-is due to C<-textvariable> changing.
-
-=item * The current value of entry i.e. before the proposed change.
-
-=item * index of char string to be added/deleted, if any. -1 otherwise
-
-=item * type of action. 1 == INSERT, 0 == DELETE,
--1 if it's a forced validation or textvariable validation
-
-=back
-
-In general, the B<textVariable> and B<validateCommand> can be
-dangerous to mix. If you try set the B<textVariable>
-to something that the B<validateCommand> will not accept it will
-be set back to the value of the entry widget.
-Using the B<textVariable> for read-only purposes will never cause problems.
-
-The B<validateCommand> will turn itself off by setting
-B<validate> to B<none> when an error occurs, for example
-when the B<validateCommand> or B<invalidCommand> encounters
-an error in its script while evaluating, or
-B<validateCommand> does not return a valid boolean value.
-
-With the perl/Tk version B<validate> option is supposed to be
-"suspended" while executing the B<validateCommand> or the B<invalidCommand>.
-This is experimental but in theory either callback can "correct" the
-value of the widget, and override the proposed change. (B<validateCommand>
-should still return false to inhibit the change from happening when
-it returns.)
-
-=head1 WIDGET METHODS
-
-The B<Entry> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-Many of the additional methods for entries take one or more indices as
-arguments. An index specifies a particular character in the entry's
-string, in any of the following ways:
-
-=over 4
-
-=item I<number>
-
-Specifies the character as a numerical index, where 0 corresponds
-to the first character in the string.
-
-=item B<anchor>
-
-Indicates the anchor point for the selection, which is set with the
-B<selectionFrom> and B<selectionAdjust> methods.
-
-=item B<end>
-
-Indicates the character just after the last one in the entry's string.
-This is equivalent to specifying a numerical index equal to the length
-of the entry's string.
-
-=item B<insert>
-
-Indicates the character adjacent to and immediately following the
-insertion cursor.
-
-=item B<sel.first>
-
-Indicates the first character in the selection. It is an error to
-use this form if the selection isn't in the entry window.
-
-=item B<sel.last>
-
-Indicates the character just after the last one in the selection.
-It is an error to use this form if the selection isn't in the
-entry window.
-
-=item B<@>I<number>
-
-In this form, I<number> is treated as an x-coordinate in the
-entry's window; the character spanning that x-coordinate is used.
-For example, ``B<@0>'' indicates the left-most character in the
-window.
-
-=back
-
-Abbreviations may be used for any of the forms above, e.g. ``B<e>''
-or ``B<sel.f>''. In general, out-of-range indices are automatically
-rounded to the nearest legal value.
-
-The following additional methods are available for entry widgets:
-
-=over 4
-
-=item I<$entry>-E<gt>B<bbox>(I<index>)
-
-Returns a list of four numbers describing the bounding box of the
-character given by I<index>.
-The first two elements of the list give the x and y coordinates of
-the upper-left corner of the screen area covered by the character
-(in pixels relative to the widget) and the last two elements give
-the width and height of the character, in pixels.
-The bounding box may refer to a region outside the visible area
-of the window.
-
-=item I<$entry>-E<gt>B<cget>(?I<option>?)
-
-Returns the current value of the configuration option given
-by I<option>.
-I<Option> may have any of the values accepted by the B<entry>
-command.
-
-=item I<$entry>-E<gt>B<configure>(?I<option>?, ?I<value, option, value, ...>?)
-
-Query or modify the configuration options of the widget.
-If no I<option> is specified, returns a list describing all of
-the available options for $entry (see L<Tk::configure> for
-information on the format of this list). If I<option> is specified
-with no I<value>, then the command returns a list describing the
-one named option (this list will be identical to the corresponding
-sublist of the value returned if no I<option> is specified). If
-one or more I<option-value> pairs are specified, then the command
-modifies the given widget option(s) to have the given value(s); in
-this case the command returns an empty string.
-I<Option> may have any of the values accepted by the B<entry>
-command.
-
-=item I<$entry>-E<gt>B<delete>(I<first, >?I<last>?)
-
-Delete one or more elements of the entry.
-I<First> is the index of the first character to delete, and
-I<last> is the index of the character just after the last
-one to delete.
-If I<last> isn't specified it defaults to I<first>+1,
-i.e. a single character is deleted.
-This method returns an empty string.
-
-=item I<$entry>-E<gt>B<get>
-
-Returns the entry's string.
-
-=item I<$entry>-E<gt>B<icursor>(I<index>)
-
-Arrange for the insertion cursor to be displayed just before the character
-given by I<index>. Returns an empty string.
-
-=item I<$entry>-E<gt>B<index>(I<index>)
-
-Returns the numerical index corresponding to I<index>.
-
-=item I<$entry>-E<gt>B<insert>(I<index, string>)
-
-Insert the characters of I<string> just before the character
-indicated by I<index>. Returns an empty string.
-
-=item I<$entry>->B<scan>(I<option, args>)
-
-=item I<$entry>->B<scan>I<Option>(I<args>)
-
-This method is used to implement scanning on entries. It has
-two forms, depending on I<Option>:
-
-=over 8
-
-=item I<$entry>->B<scanMark>(I<x>)
-
-Records I<x> and the current view in the entry widget; used in
-conjunction with later B<scanDragto> methods. Typically this
-method is associated with a mouse button press in the widget. It
-returns an empty string.
-
-=item I<$entry>->B<scanDragto>(I<x>)
-
-This method computes the difference between its I<x> argument
-and the I<x> argument to the last B<scanMark> method for
-the widget. It then adjusts the view left or right by 10 times the
-difference in x-coordinates. This method is typically associated
-with mouse motion events in the widget, to produce the effect of
-dragging the entry at high speed through the widget. The return
-value is an empty string.
-
-=back
-
-=item I<$entry>->B<selection>(I<option, arg>)
-
-=item I<$entry>->B<selection>I<Option>(I<arg>)
-
-This method is used to adjust the selection within an entry. It
-has several forms, depending on I<Option>:
-
-=over 8
-
-=item I<$entry>-E<gt>B<selectionAdjust>(I<index>)
-
-Locate the end of the selection nearest to the character given by
-I<index>, and adjust that end of the selection to be at I<index>
-(i.e including but not going beyond I<index>). The other
-end of the selection is made the anchor point for future
-B<selectionTo> methods. If the selection
-isn't currently in the entry, then a new selection is created to
-include the characters between I<index> and the most recent
-selection anchor point, inclusive.
-Returns an empty string.
-
-=item I<$entry>-E<gt>B<selectionClear>
-
-Clear the selection if it is currently in this widget. If the
-selection isn't in this widget then the method has no effect.
-Returns an empty string.
-
-=item I<$entry>-E<gt>B<selectionFrom>(I<index>)
-
-Set the selection anchor point to just before the character
-given by I<index>. Doesn't change the selection.
-Returns an empty string.
-
-=item I<$entry>-E<gt>B<selectionPresent>
-
-Returns 1 if there is are characters selected in the entry,
-0 if nothing is selected.
-
-=item I<$entry>-E<gt>B<selectionRange>(I<start, >I<end>)
-
-Sets the selection to include the characters starting with
-the one indexed by I<start> and ending with the one just
-before I<end>.
-If I<end> refers to the same character as I<start> or an
-earlier one, then the entry's selection is cleared.
-
-=item I<$entry>-E<gt>B<selectionTo>(I<index>)
-
-If I<index> is before the anchor point, set the selection
-to the characters from I<index> up to but not including
-the anchor point.
-If I<index> is the same as the anchor point, do nothing.
-If I<index> is after the anchor point, set the selection
-to the characters from the anchor point up to but not including
-I<index>.
-The anchor point is determined by the most recent B<selectionFrom>
-or B<selectionAdjust> method in this widget.
-If the selection isn't in this widget then a new selection is
-created using the most recent anchor point specified for the widget.
-Returns an empty string.
-
-=back
-
-=item I<$entry>-E<gt>B<validate>
-
-This command is used to force an evaluation of the B<validateCommand>
-independent of the conditions specified by the B<validate> option. It
-returns 0 or 1.
-
-=item I<$entry>-E<gt>B<xview>(I<args>)
-
-This command is used to query and change the horizontal position of the
-text in the widget's window. It can take any of the following
-forms:
-
-=over 8
-
-=item I<$entry>-E<gt>B<xview>
-
-Returns a list containing two elements.
-Each element is a real fraction between 0 and 1; together they describe
-the horizontal span that is visible in the window.
-For example, if the first element is .2 and the second element is .7,
-20% of the entry's text is off-screen to the left, the middle 50% is visible
-in the window, and 30% of the text is off-screen to the right.
-These are the same values passed to scrollbars via the B<-xscrollcommand>
-option.
-
-=item I<$entry>-E<gt>B<xview>(I<index>)
-
-Adjusts the view in the window so that the character given by I<index>
-is displayed at the left edge of the window.
-
-=item I<$entry>-E<gt>B<xviewMoveto>(I<fraction>)
-
-Adjusts the view in the window so that the character I<fraction> of the
-way through the text appears at the left edge of the window.
-I<Fraction> must be a fraction between 0 and 1.
-
-=item I<$entry>-E<gt>B<xviewScroll>(I<number, what>)
-
-This method shifts the view in the window left or right according to
-I<number> and I<what>.
-I<Number> must be an integer.
-I<What> must be either B<units> or B<pages> or an abbreviation
-of one of these.
-If I<what> is B<units>, the view adjusts left or right by
-I<number> average-width characters on the display; if it is
-B<pages> then the view adjusts by I<number> screenfuls.
-If I<number> is negative then characters farther to the left
-become visible; if it is positive then characters farther to the right
-become visible.
-
-=back
-
-=back
-
-=head1 DEFAULT BINDINGS
-
-Tk automatically creates class bindings for entries that give them
-the following default behavior.
-In the descriptions below, ``word'' refers to a contiguous group
-of letters, digits, or ``_'' characters, or any single character
-other than these.
-
-=over 4
-
-=item [1]
-
-Clicking mouse button 1 positions the insertion cursor
-just before the character underneath the mouse cursor, sets the
-input focus to this widget, and clears any selection in the widget.
-Dragging with mouse button 1 strokes out a selection between
-the insertion cursor and the character under the mouse.
-
-=item [2]
-
-Double-clicking with mouse button 1 selects the word under the mouse
-and positions the insertion cursor at the beginning of the word.
-Dragging after a double click will stroke out a selection consisting
-of whole words.
-
-=item [3]
-
-Triple-clicking with mouse button 1 selects all of the text in the
-entry and positions the insertion cursor before the first character.
-
-=item [4]
-
-The ends of the selection can be adjusted by dragging with mouse
-button 1 while the Shift key is down; this will adjust the end
-of the selection that was nearest to the mouse cursor when button
-1 was pressed.
-If the button is double-clicked before dragging then the selection
-will be adjusted in units of whole words.
-
-=item [5]
-
-Clicking mouse button 1 with the Control key down will position the
-insertion cursor in the entry without affecting the selection.
-
-=item [6]
-
-If any normal printing characters are typed in an entry, they are
-inserted at the point of the insertion cursor.
-
-=item [7]
-
-The view in the entry can be adjusted by dragging with mouse button 2.
-If mouse button 2 is clicked without moving the mouse, the selection
-is copied into the entry at the position of the mouse cursor.
-
-=item [8]
-
-If the mouse is dragged out of the entry on the left or right sides
-while button 1 is pressed, the entry will automatically scroll to
-make more text visible (if there is more text off-screen on the side
-where the mouse left the window).
-
-=item [9]
-
-The Left and Right keys move the insertion cursor one character to the
-left or right; they also clear any selection in the entry and set
-the selection anchor.
-If Left or Right is typed with the Shift key down, then the insertion
-cursor moves and the selection is extended to include the new character.
-Control-Left and Control-Right move the insertion cursor by words, and
-Control-Shift-Left and Control-Shift-Right move the insertion cursor
-by words and also extend the selection.
-Control-b and Control-f behave the same as Left and Right, respectively.
-Meta-b and Meta-f behave the same as Control-Left and Control-Right,
-respectively.
-
-=item [10]
-
-The Home key, or Control-a, will move the insertion cursor to the
-beginning of the entry and clear any selection in the entry.
-Shift-Home moves the insertion cursor to the beginning of the entry
-and also extends the selection to that point.
-
-=item [11]
-
-The End key, or Control-e, will move the insertion cursor to the
-end of the entry and clear any selection in the entry.
-Shift-End moves the cursor to the end and extends the selection
-to that point.
-
-=item [12]
-
-The Select key and Control-Space set the selection anchor to the position
-of the insertion cursor. They don't affect the current selection.
-Shift-Select and Control-Shift-Space adjust the selection to the
-current position of the insertion cursor, selecting from the anchor
-to the insertion cursor if there was not any selection previously.
-
-=item [13]
-
-Control-/ selects all the text in the entry.
-
-=item [14]
-
-Control-\ clears any selection in the entry.
-
-=item [15]
-
-The F16 key (labelled Copy on many Sun workstations) or Meta-w
-copies the selection in the widget to the clipboard, if there is a selection.
-
-=item [16]
-
-The F20 key (labelled Cut on many Sun workstations) or Control-w
-copies the selection in the widget to the clipboard and deletes
-the selection.
-If there is no selection in the widget then these keys have no effect.
-
-=item [17]
-
-The F18 key (labelled Paste on many Sun workstations) or Control-y
-inserts the contents of the clipboard at the position of the
-insertion cursor.
-
-=item [18]
-
-The Delete key deletes the selection, if there is one in the entry.
-If there is no selection, it deletes the character to the right of
-the insertion cursor.
-
-=item [19]
-
-The BackSpace key and Control-h delete the selection, if there is one
-in the entry.
-If there is no selection, it deletes the character to the left of
-the insertion cursor.
-
-=item [20]
-
-Control-d deletes the character to the right of the insertion cursor.
-
-=item [21]
-
-Meta-d deletes the word to the right of the insertion cursor.
-
-=item [22]
-
-Control-k deletes all the characters to the right of the insertion
-cursor.
-
-=item [23]
-
-Control-t reverses the order of the two characters to the right of
-the insertion cursor.
-
-If the entry is disabled using the B<-state> option, then the entry's
-view can still be adjusted and text in the entry can still be selected,
-but no insertion cursor will be displayed and no text modifications will
-take place.
-
-The behavior of entries can be changed by defining new bindings for
-individual widgets or by redefining the class bindings.
-
-=back
-
-=head1 KEYWORDS
-
-entry, widget
-
-=cut
-