437 lines
20 KiB
HTML
437 lines
20 KiB
HTML
<HTML><HEAD><TITLE>Tk Built-In Commands - entry manual page</TITLE></HEAD>
|
|
<BODY bgcolor = #c3c3ff>
|
|
<H2><IMG ALIGN=BOTTOM SRC="./Img/ManPageBlue.gif"> entry</H2>
|
|
<I>Create and manipulate entry widgets</I><P><IMG ALIGN=TOP SRC="./Img/line-red.gif">
|
|
<H3><A NAME="M2">SYNOPSIS</A></H3>
|
|
(<B>entry</B><I> widget-name </I>?<I>options</I>?)<BR>
|
|
<H3><A NAME="M3">STANDARD OPTIONS</A></H3>
|
|
<PRE>
|
|
<B><A HREF="options.n.html#M:background">:background</A></B> <B><A HREF="options.n.html#M:borderwidth">:borderwidth</A></B>
|
|
<B><A HREF="options.n.html#M:cursor">:cursor</A></B> <B><A HREF="options.n.html#M:exportselection">:exportselection</A></B>
|
|
<B><A HREF="options.n.html#M:font">:font</A></B> <B><A HREF="options.n.html#M:foreground">:foreground</A></B>
|
|
<B><A HREF="options.n.html#M:highlightbackground">:highlightbackground</A></B> <B><A HREF="options.n.html#M:highlightcolor">:highlightcolor</A></B>
|
|
<B><A HREF="options.n.html#M:highlightthickness">:highlightthickness</A></B> <B><A HREF="options.n.html#M:insertbackground">:insertbackground</A></B>
|
|
<B><A HREF="options.n.html#M:insertborderwidth">:insertborderwidth</A></B> <B><A HREF="options.n.html#M:insertofftime">:insertofftime</A></B>
|
|
<B><A HREF="options.n.html#M:insertontime">:insertontime</A></B> <B><A HREF="options.n.html#M:insertwidth">:insertwidth</A></B>
|
|
<B><A HREF="options.n.html#M:justify">:justify</A></B> <B><A HREF="options.n.html#M:relief">:relief</A></B>
|
|
<B><A HREF="options.n.html#M:selectbackground">:selectbackground</A></B> <B><A HREF="options.n.html#M:selectborderwidth">:selectborderwidth</A></B>
|
|
<B><A HREF="options.n.html#M:selectforeground">:selectforeground</A></B> <B><A HREF="options.n.html#M:takefocus">:takefocus</A></B>
|
|
<B><A HREF="options.n.html#M:textvariable">:textvariable</A></B> <B><A HREF="options.n.html#M:xscrollcommand">:xscrollcommand</A></B>
|
|
</PRE>
|
|
<H3><A NAME="M26">WIDGET-SPECIFIC OPTIONS</A></H3>
|
|
<DL>
|
|
<P>
|
|
<DT><I>Name</I>: <B>show</B>
|
|
<DT><I>Class</I>: <B>Show</B>
|
|
<DT><I>Option keyword</I>: <B><A NAME="M27">:show</A></B>
|
|
<DT><I>STklos slot name</I>: <B>show</B>
|
|
<DD>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.
|
|
<P>
|
|
<P>
|
|
<DT><I>Name</I>: <B>state</B>
|
|
<DT><I>Class</I>: <B>State</B>
|
|
<DT><I>Option keyword</I>: <B><A NAME="M28">:state</A></B>
|
|
<DT><I>STklos slot name</I>: <B>state</B>
|
|
<DD>Specifies one of two states for the entry: <B>normal</B> or <B>disabled</B>.
|
|
If the entry is disabled then the value may not be changed using widget
|
|
procedures and no insertion cursor will be displayed, even if the input focus is
|
|
in the widget.
|
|
<P>
|
|
<P>
|
|
<DT><I>Name</I>: <B>width</B>
|
|
<DT><I>Class</I>: <B>Width</B>
|
|
<DT><I>Option keyword</I>: <B><A NAME="M29">:width</A></B>
|
|
<DT><I>STklos slot name</I>: <B>width</B>
|
|
<DD>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.
|
|
<P>
|
|
</DL>
|
|
<H3><A NAME="M30">DESCRIPTION</A></H3>
|
|
The <B>entry</B> procedure creates a new window (given by the
|
|
<I>widget-name</I> argument) and makes it into an entry widget.
|
|
Additional options, described above, may be specified on the
|
|
procedure line or in the option database
|
|
to configure aspects of the entry such as its colors, font,
|
|
and relief. The <B>entry</B> procedure returns its
|
|
<I>widget-name</I> argument. At the time this procedure is invoked,
|
|
there must not exist a window named <I>widget-name</I>, but
|
|
<I>widget-name</I>'s parent must exist.
|
|
<P>
|
|
An entry is a widget that displays a one-line text string and
|
|
allows that string to be edited using widget procedures 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</B>
|
|
option), then it will observe the standard X11 protocols for handling the
|
|
selection; entry selections are available as type <B>STRING</B>.
|
|
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</I> to indicate where new characters will be
|
|
inserted.
|
|
<P>
|
|
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; procedures described below
|
|
may be used to change the view in the window. Entries use
|
|
the standard <B>xScrollCommand</B> mechanism for interacting with
|
|
scrollbars (see the description of the <B>xScrollCommand</B> option
|
|
for details). They also support scanning, as described below.
|
|
|
|
<H3><A NAME="M31">WIDGET PROCEDURE</A></H3>
|
|
The <B>entry</B> procedure creates a new STk procedure whose
|
|
name is <I>widget-name</I>. This
|
|
procedure may be used to invoke various
|
|
operations on the widget. It has the following general form:
|
|
<PRE>(<I>widget-name option </I>?<I>arg arg ...</I>?)</PRE>
|
|
<I>Option</I> and the <I>arg</I>s
|
|
determine the exact behavior of the procedure.
|
|
<P>
|
|
Many of the widget procedures 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:
|
|
<P>
|
|
<DL>
|
|
<DT><A NAME="M32"><I>number</I></A><DD>
|
|
Specifies the character as a numerical index, where 0 corresponds
|
|
to the first character in the string.
|
|
<P>
|
|
<DT><A NAME="M33"><B>anchor</B></A><DD>
|
|
Indicates the anchor point for the selection, which is set with the
|
|
<B>select from</B> and <B>select adjust</B> widget procedures.
|
|
<P>
|
|
<DT><A NAME="M34"><B>end</B></A><DD>
|
|
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.
|
|
<P>
|
|
<DT><A NAME="M35"><B>insert</B></A><DD>
|
|
Indicates the character adjacent to and immediately following the
|
|
insertion cursor.
|
|
<P>
|
|
<DT><A NAME="M36"><B>sel.first</B></A><DD>
|
|
Indicates the first character in the selection. It is an error to
|
|
use this form if the selection isn't in the entry window.
|
|
<P>
|
|
<DT><A NAME="M37"><B>sel.last</B></A><DD>
|
|
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.
|
|
<P>
|
|
<DT><A NAME="M38"><B>@</B><I>number</I></A><DD>
|
|
In this form, <I>number</I> is treated as an x-coordinate in the
|
|
entry's window; the character spanning that x-coordinate is used.
|
|
For example, ``<B>@0</B>'' indicates the left-most character in the
|
|
window.
|
|
<P>
|
|
</DL>
|
|
<P>
|
|
Abbreviations may be used for any of the forms above, e.g. ``<B>e</B>''
|
|
or ``<B>sel.f</B>''. In general, out-of-range indices are automatically
|
|
rounded to the nearest legal value.
|
|
<P>
|
|
The following procedures are possible for entry widgets:
|
|
<P>
|
|
<DL>
|
|
<DT><A NAME="M39">(<I>widget-name '</I><B>bbox </B><I>index</I>)</A><DD>
|
|
Returns a list of four numbers describing the bounding box of the
|
|
character given by <I>index</I>.
|
|
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.
|
|
<P>
|
|
<DT><A NAME="M40">(<I>widget-name '</I><B>cget</B> <I>option</I>)</A><DD>
|
|
Returns the current value of the configuration option given
|
|
by <I>option</I>.
|
|
<I>Option</I> may have any of the values accepted by the <B>entry</B>
|
|
procedure.
|
|
<P>
|
|
<DT><A NAME="M41">(<I>widget-name '</I><B>configure</B> ?<I>option</I>? ?<I>value option value ...</I>?)</A><DD>
|
|
Query or modify the configuration options of the widget.
|
|
If no <I>option</I> is specified, returns a list describing all of
|
|
the available options for <I>widget-name</I> (see <B>Tk_ConfigureInfo</B> for
|
|
information on the format of this list). If <I>option</I> is specified
|
|
with no <I>value</I>, then the procedure 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</I> is specified). If
|
|
one or more <I>option-value</I> pairs are specified, then the procedure
|
|
modifies the given widget option(s) to have the given value(s); in
|
|
this case the procedure returns an empty string.
|
|
<I>Option</I> may have any of the values accepted by the <B>entry</B>
|
|
procedure.
|
|
<P>
|
|
<DT><A NAME="M42">(<I>widget-name '</I><B>delete </B><I>first</I>)</A><DD>
|
|
<DT><A NAME="M43">(<I>widget-name '</I><B>delete </B><I>first </I><I>last</I>)</A><DD>
|
|
Delete one or more elements of the entry.
|
|
<I>First</I> is the index of the first character to delete, and
|
|
<I>last</I> is the index of the character just after the last
|
|
one to delete.
|
|
If <I>last</I> isn't specified it defaults to <I>first</I>+1,
|
|
i.e. a single character is deleted.
|
|
This procedure returns an empty string.
|
|
<P>
|
|
<DT><A NAME="M44">(<I>widget-name '</I><B>get</B>)</A><DD>
|
|
Returns the entry's string.
|
|
<P>
|
|
<DT><A NAME="M45">(<I>widget-name '</I><B>icursor </B><I>index</I>)</A><DD>
|
|
Arrange for the insertion cursor to be displayed just before the character
|
|
given by <I>index</I>. Returns an empty string.
|
|
<P>
|
|
<DT><A NAME="M46">(<I>widget-name '</I><B>index</B><I> index</I>)</A><DD>
|
|
Returns the numerical index corresponding to <I>index</I>.
|
|
<P>
|
|
<DT><A NAME="M47">(<I>widget-name '</I><B>insert </B><I>index string</I>)</A><DD>
|
|
Insert the characters of <I>string</I> just before the character
|
|
indicated by <I>index</I>. Returns an empty string.
|
|
<P>
|
|
<DT><A NAME="M48">(<I>widget-name '</I><B>scan</B> <I>option args</I>)</A><DD>
|
|
This procedure is used to implement scanning on entries. It has
|
|
two forms, depending on <I>option</I>:
|
|
<P>
|
|
<P>
|
|
<DL>
|
|
<DT><A NAME="M49">(<I>widget-name '</I><B>scan 'mark </B><I>x</I>)</A><DD>
|
|
Records <I>x</I> and the current view in the entry window; used in
|
|
conjunction with later <B>scan dragto</B> procedures. Typically this
|
|
procedure is associated with a mouse button press in the widget. It
|
|
returns an empty string.
|
|
<P>
|
|
<DT><A NAME="M50">(<I>widget-name '</I><B>scan 'dragto </B><I>x</I>)</A><DD>
|
|
This procedure computes the difference between its <I>x</I> argument
|
|
and the <I>x</I> argument to the last <B>scan mark</B> procedure for
|
|
the widget. It then adjusts the view left or right by 10 times the
|
|
difference in x-coordinates. This procedure is typically associated
|
|
with mouse motion events in the widget, to produce the effect of
|
|
dragging the entry at high speed through the window. The return
|
|
value is an empty string.
|
|
<P>
|
|
</DL>
|
|
<DT><A NAME="M51">(<I>widget-name '</I><B>selection </B><I>option arg</I>)</A><DD>
|
|
This procedure is used to adjust the selection within an entry. It
|
|
has several forms, depending on <I>option</I>:
|
|
<P>
|
|
<P>
|
|
<DL>
|
|
<DT><A NAME="M52">(<I>widget-name '</I><B>selection 'adjust </B><I>index</I>)</A><DD>
|
|
Locate the end of the selection nearest to the character given by
|
|
<I>index</I>, and adjust that end of the selection to be at <I>index</I>
|
|
(i.e including but not going beyond <I>index</I>). The other
|
|
end of the selection is made the anchor point for future
|
|
<B>select to</B> procedures. If the selection
|
|
isn't currently in the entry, then a new selection is created to
|
|
include the characters between <I>index</I> and the most recent
|
|
selection anchor point, inclusive.
|
|
Returns an empty string.
|
|
<P>
|
|
<DT><A NAME="M53">(<I>widget-name '</I><B>selection 'clear</B>)</A><DD>
|
|
Clear the selection if it is currently in this widget. If the
|
|
selection isn't in this widget then the procedure has no effect.
|
|
Returns an empty string.
|
|
<P>
|
|
<DT><A NAME="M54">(<I>widget-name '</I><B>selection 'from </B><I>index</I>)</A><DD>
|
|
Set the selection anchor point to just before the character
|
|
given by <I>index</I>. Doesn't change the selection.
|
|
Returns an empty string.
|
|
<P>
|
|
<DT><A NAME="M55">(<I>widget-name '</I><B>selection 'present</B>)</A><DD>
|
|
Returns <B>#t</B> if there is are characters selected in the entry,
|
|
<B>#f</B> if nothing is selected.
|
|
<P>
|
|
<DT><A NAME="M56">(<I>widget-name '</I><B>selection 'range </B><I>start</I> <I>end</I>)</A><DD>
|
|
Sets the selection to include the characters starting with
|
|
the one indexed by <I>start</I> and ending with the one just
|
|
before <I>end</I>.
|
|
If <I>end</I> refers to the same character as <I>start</I> or an
|
|
earlier one, then the entry's selection is cleared.
|
|
<P>
|
|
<DT><A NAME="M57">(<I>widget-name '</I><B>selection 'to </B><I>index</I>)</A><DD>
|
|
If <I>index</I> is before the anchor point, set the selection
|
|
to the characters from <I>index</I> up to but not including
|
|
the anchor point.
|
|
If <I>index</I> is the same as the anchor point, do nothing.
|
|
If <I>index</I> is after the anchor point, set the selection
|
|
to the characters from the anchor point up to but not including
|
|
<I>index</I>.
|
|
The anchor point is determined by the most recent <B>select from</B>
|
|
or <B>select adjust</B> procedure 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.
|
|
<P>
|
|
</DL>
|
|
<DT><A NAME="M58">(<I>widget-name '</I><B>xview </B><I>args</I>)</A><DD>
|
|
This procedure 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:
|
|
<P>
|
|
<P>
|
|
<DL>
|
|
<DT><A NAME="M59">(<I>widget-name '</I><B>xview</B>)</A><DD>
|
|
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 .6,
|
|
20% of the entry's text is off-screen to the left, the middle 40% is visible
|
|
in the window, and 40% of the text is off-screen to the right.
|
|
These are the same values passed to scrollbars via the <B>:xscrollcommand</B>
|
|
option.
|
|
<P>
|
|
<DT><A NAME="M60">(<I>widget-name '</I><B>xview</B> <I>index</I>)</A><DD>
|
|
Adjusts the view in the window so that the character given by <I>index</I>
|
|
is displayed at the left edge of the window.
|
|
<P>
|
|
<DT><A NAME="M61">(<I>widget-name '</I><B>xview 'moveto</B><I> fraction</I>)</A><DD>
|
|
Adjusts the view in the window so that the character <I>fraction</I> of the
|
|
way through the text appears at the left edge of the window.
|
|
<I>Fraction</I> must be a fraction between 0 and 1.
|
|
<P>
|
|
<DT><A NAME="M62">(<I>widget-name '</I><B>xview 'scroll </B><I>number what</I>)</A><DD>
|
|
This procedure shifts the view in the window left or right according to
|
|
<I>number</I> and <I>what</I>.
|
|
<I>Number</I> must be an integer.
|
|
<I>What</I> must be either <B>units</B> or <B>pages</B> or an abbreviation
|
|
of one of these.
|
|
If <I>what</I> is <B>units</B>, the view adjusts left or right by
|
|
<I>number</I> average-width characters on the display; if it is
|
|
<B>pages</B> then the view adjusts by <I>number</I> screenfuls.
|
|
If <I>number</I> is negative then characters farther to the left
|
|
become visible; if it is positive then characters farther to the right
|
|
become visible.
|
|
<P>
|
|
</DL>
|
|
</DL>
|
|
<H3><A NAME="M63">DEFAULT BINDINGS</A></H3>
|
|
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.
|
|
<OL>
|
|
<LI>
|
|
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.
|
|
<LI>
|
|
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.
|
|
<LI>
|
|
Triple-clicking with mouse button 1 selects all of the text in the
|
|
entry and positions the insertion cursor before the first character.
|
|
<LI>
|
|
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.
|
|
<LI>
|
|
Clicking mouse button 1 with the Control key down will position the
|
|
insertion cursor in the entry without affecting the selection.
|
|
<LI>
|
|
If any normal printing characters are typed in an entry, they are
|
|
inserted at the point of the insertion cursor.
|
|
<LI>
|
|
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.
|
|
<LI>
|
|
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).
|
|
<LI>
|
|
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.
|
|
<LI>
|
|
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.
|
|
<LI>
|
|
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.
|
|
<LI>
|
|
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.
|
|
<LI>
|
|
Control-/ selects all the text in the entry.
|
|
<LI>
|
|
Control-\ clears any selection in the entry.
|
|
<LI>
|
|
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.
|
|
<LI>
|
|
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.
|
|
<LI>
|
|
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.
|
|
<LI>
|
|
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.
|
|
<LI>
|
|
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.
|
|
<LI>
|
|
Control-d deletes the character to the right of the insertion cursor.
|
|
<LI>
|
|
Meta-d deletes the word to the right of the insertion cursor.
|
|
<LI>
|
|
Control-k deletes all the characters to the right of the insertion
|
|
cursor.
|
|
<LI>
|
|
Control-w deletes the word to the left of the insertion cursor.
|
|
<LI>
|
|
Control-t reverses the order of the two characters to the right of
|
|
the insertion cursor.
|
|
</OL>
|
|
<P>
|
|
If the entry is disabled using the <B>:state</B> 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.
|
|
<P>
|
|
The behavior of entries can be changed by defining new bindings for
|
|
individual widgets or by redefining the class bindings.
|
|
|
|
<P><IMG ALIGN=TOP SRC="./Img/line-red.gif">
|
|
<A HREF=./STk-hlp.html><IMG ALIGN=BOTTOM SRC="./Img/RefBookBlue.gif"> Back to the <B>STk</B> main page</A>
|
|
</BODY></HTML>
|