diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Entry.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/Entry.pod | 693 |
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 - |