Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Thursday, March 14, 2019
 
 

ttk_entry (1t)

Name

ttk_entry - Editable text field widget

Synopsis

ttk::entry pathName ?options?

Description

ttk::entry(1t)                 Tk Themed Widget                 ttk::entry(1t)



______________________________________________________________________________

NAME
       ttk::entry - Editable text field widget

SYNOPSIS
       ttk::entry pathName ?options?
______________________________________________________________________________

DESCRIPTION
       An  ttk::entry  widget  displays a one-line text string and allows that
       string to be edited by the user.  The value of the string may be linked
       to a Tcl variable with the -textvariable option.  Entry widgets support
       horizontal scrolling with the standard -xscrollcommand option and xview
       widget command.

STANDARD OPTIONS
       -class                -cursor              -style
       -takefocus            -xscrollcommand

       See the ttk_widget manual entry for details on the standard options.

WIDGET-SPECIFIC OPTIONS
       Command-Line Name:-exportselection
       Database Name:  exportSelection
       Database Class: ExportSelection

              A  boolean  value  specifying  whether or not a selection in the
              widget should be linked to the X selection.  If the selection is
              exported,  then  selecting in the widget deselects the current X
              selection, selecting outside the  widget  deselects  any  widget
              selection,  and  the  widget will respond to selection retrieval
              requests when it has a selection.

       Command-Line Name:-invalidcommand
       Database Name:  invalidCommand
       Database Class: InvalidCommand

              A script template  to  evaluate  whenever  the  -validatecommand
              returns 0.  See VALIDATION below for more information.

       Command-Line Name:-justify
       Database Name:  justify
       Database Class: Justify

              Specifies  how the text is aligned within the entry widget.  One
              of left, center, or right.

       Command-Line Name:-show
       Database Name:  show
       Database Class: 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 "*" or a bullet.  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  con-
              tents of the entry.

       Command-Line Name:-state
       Database Name:  state
       Database Class: State

              Compatibility option; see ttk::widget(n) for details.  Specifies
              one of three states for the entry, normal,  disabled,  or  read-
              only.  See WIDGET STATES, below.

       Command-Line Name:-textvariable
       Database Name:  textVariable
       Database Class: Variable

              Specifies the name of a global variable whose value is linked to
              the entry widget's  contents.   Whenever  the  variable  changes
              value, the widget's contents are updated, and vice versa.

       Command-Line Name:-validate
       Database Name:  validate
       Database Class: Validate

              Specifies  the  mode  in  which validation should operate: none,
              focus, focusin, focusout, key, or all.  Default is none, meaning
              that validation is disabled.  See VALIDATION below.

       Command-Line Name:-validatecommand
       Database Name:  validateCommand
       Database Class: ValidateCommand

              A  script template to evaluate whenever validation is triggered.
              If set to the empty string (the  default),  validation  is  dis-
              abled.   The script must return a boolean value.  See VALIDATION
              below.

       Command-Line Name:-width
       Database Name:  width
       Database Class: Width

              Specifies an integer value indicating the desired width  of  the
              entry window, in average-size characters of the widget's font.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | runtime/tk-8     |
       +---------------+------------------+
       |Stability      | Uncommitted      |
       +---------------+------------------+
NOTES
       A portion of the entry may be selected as described below.  If an entry
       is exporting its selection (see the -exportselection option),  then  it
       will  observe  the  standard  X11 protocols for handling the selection;
       entry selections are available as type STRING.   Entries  also  observe
       the  standard Tk rules for dealing with the input focus.  When an entry
       has the input focus it displays an insert 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;  commands described below may be used to
       change the view in the window.  Entries use the  standard  -xscrollcom-
       mand  mechanism for interacting with scrollbars (see the description of
       the -xscrollcommand option for details).

INDICES
       Many of the entry widget commands take one or  more  indices  as  argu-
       ments.   An  index  specifies  a  particular  character  in the entry's
       string, in any of the following ways:

       number Specifies the character as a numerical  index,  where  0  corre-
              sponds to the first character in the string.

       @number
              In  this  form,  number  is  treated  as  an x-coordinate in the
              entry's window;  the character  spanning  that  x-coordinate  is
              used.   For  example,  "@0" indicates the left-most character in
              the window.

       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.

       insert Indicates the character adjacent to  and  immediately  following
              the insert cursor.

       sel.first
              Indicates  the first character in the selection.  It is an error
              to use this form if the selection is not in the entry window.

       sel.last
              Indicates the character just after the last one  in  the  selec-
              tion.   It  is an error to use this form if the selection is not
              in the entry window.

       Abbreviations may be used for any of  the  forms  above,  e.g.  "e"  or
       "sel.l".  In general, out-of-range indices are automatically rounded to
       the nearest legal value.

WIDGET COMMAND
       The following subcommands are possible for entry widgets:

       pathName bbox index
              Returns a list of four numbers describing the  bounding  box  of
              the  character  given  by  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.

       pathName delete first ?last?
              Delete one or more elements of the entry.  First is the index of
              the  first  character  to  delete,  and last is the index of the
              character just after the last one to delete.   If  last  is  not
              specified  it  defaults  to  first+1, i.e. a single character is
              deleted.  This command returns the empty string.

       pathName get
              Returns the entry's string.

       pathName icursor index
              Arrange for the insert cursor to be displayed  just  before  the
              character given by index.  Returns the empty string.

       pathName index index
              Returns the numerical index corresponding to index.

       pathName insert index string
              Insert  string  just  before  the  character indicated by index.
              Returns the empty string.

       pathName selection option arg
              This command is used to adjust the selection  within  an  entry.
              It has several forms, depending on option:

              pathName selection clear
                     Clear  the  selection  if it is currently in this widget.
                     If the selection is not in this widget then  the  command
                     has no effect.  Returns the empty string.

              pathName selection present
                     Returns  1  if  there  is  are characters selected in the
                     entry, 0 if nothing is selected.

              pathName selection range start end
                     Sets the selection to  include  the  characters  starting
                     with  the  one  indexed  by start and ending with the one
                     just before end.  If end refers to the same character  as
                     start  or  an  earlier one, then the entry's selection is
                     cleared.

       pathName validate
              Force revalidation, independent of the conditions  specified  by
              the  -validate  option.   Returns 0 if validation fails, 1 if it
              succeeds.  Sets or clears the invalid  state  accordingly.   See
              VALIDATION below for more details.

       pathName xview 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 fol-
              lowing forms:

              pathName 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  ele-
                     ment  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  -xscrollcommand
                     option.

              pathName xview index
                     Adjusts  the  view  in  the  window so that the character
                     given by index is displayed at the left edge of the  win-
                     dow.

              pathName xview moveto fraction
                     Adjusts  the  view  in  the  window so that the character
                     fraction of the way through the text appears at the  left
                     edge  of the window.  Fraction must be a fraction between
                     0 and 1.

              pathName xview scroll number what
                     This command shifts the view in the window left or  right
                     according to number and what.  Number must be an integer.
                     What must be either units or pages.  If  what  is  units,
                     the  view  adjusts  left or right by number average-width
                     characters on the display;  if it is pages then the  view
                     adjusts by number screenfuls.  If number is negative then
                     characters farther to the left become visible;  if it  is
                     positive then characters farther to the right become vis-
                     ible.

       The entry widget also supports the following generic ttk::widget widget
       subcommands (see ttk::widget(n) for details):

              cget                  configure            identify
              instate               state


VALIDATION
       The  -validate,  -validatecommand, and -invalidcommand options are used
       to enable entry widget validation.

   VALIDATION MODES
       There are two main validation modes: prevalidation, in which the -vali-
       datecommand  is  evaluated  prior  to each edit and the return value is
       used to determine whether to accept or reject the change; and revalida-
       tion,  in  which the -validatecommand is evaluated to determine whether
       the current value is valid.

       The -validate option determines when validation occurs; it may  be  set
       to any of the following values:

              none   Default.   This  means  validation  will  only occur when
                     specifically requested by the validate widget command.

              key    The  entry  will  be  prevalidated  prior  to  each  edit
                     (specifically,  whenever the insert or delete widget com-
                     mands are called).  If prevalidation fails, the  edit  is
                     rejected.

              focus  The entry is revalidated when the entry receives or loses
                     focus.

              focusin
                     The entry is revalidated when the entry receives focus.

              focusout
                     The entry is revalidated when the entry loses focus.

              all    Validation is performed for all above conditions.

       The -invalidcommand is evaluated whenever the -validatecommand  returns
       a false value.

       The  -validatecommand and -invalidcommand may modify the entry widget's
       value via the widget insert or  delete  commands,  or  by  setting  the
       linked -textvariable.  If either does so during prevalidation, then the
       edit is rejected regardless of the value returned by the  -validatecom-
       mand.

       If -validatecommand is empty (the default), validation always succeeds.

   VALIDATION SCRIPT SUBSTITUTIONS
       It is possible to perform percent substitutions on the -validatecommand
       and -invalidcommand, just as in a bind script.  The following substitu-
       tions are recognized:

              %d     Type  of action: 1 for insert prevalidation, 0 for delete
                     prevalidation, or -1 for revalidation.

              %i     Index of character string to be inserted/deleted, if any,
                     otherwise -1.

              %P     In  prevalidation, the new value of the entry if the edit
                     is accepted.  In revalidation, the current value  of  the
                     entry.

              %s     The current value of entry prior to editing.

              %S     The text string being inserted/deleted, if any, {} other-
                     wise.

              %v     The current value of the -validate option.

              %V     The validation  condition  that  triggered  the  callback
                     (key, focusin, focusout, or forced).

              %W     The name of the entry widget.

   DIFFERENCES FROM TK ENTRY WIDGET VALIDATION
       The standard Tk entry widget automatically disables validation (by set-
       ting -validate to none) if the -validatecommand or -invalidcommand mod-
       ifies the entry's value.  The Tk themed entry widget only disables val-
       idation if one of the validation scripts raises an error, or if  -vali-
       datecommand  does  not  return a valid boolean value.  (Thus, it is not
       necessary to re-enable validation after modifying the entry value in  a
       validation script).

       In  addition, the standard entry widget invokes validation whenever the
       linked -textvariable is modified; the Tk themed entry widget does not.

DEFAULT BINDINGS
       The entry widget's default bindings enable the following behavior.   In
       the descriptions below, "word" refers to a contiguous group of letters,
       digits, or "_" characters, or any single character other than these.

        o  Clicking mouse button 1 positions the insert 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 down strokes out a selection between the insert cur-
           sor and the character under the mouse.

        o  Double-clicking with mouse button 1  selects  the  word  under  the
           mouse  and  positions  the  insert  cursor  at the end of the word.
           Dragging after a double click strokes out a selection consisting of
           whole words.

        o  Triple-clicking  with mouse button 1 selects all of the text in the
           entry and positions the insert cursor at the end of the line.

        o  The ends of the selection can be adjusted by  dragging  with  mouse
           button  1  while  the  Shift key is down.  If the button is double-
           clicked before dragging then the  selection  will  be  adjusted  in
           units of whole words.

        o  Clicking mouse button 1 with the Control key down will position the
           insert cursor in the entry without affecting the selection.

        o  If any normal printing characters are typed in an entry,  they  are
           inserted at the point of the insert cursor.

        o  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.

        o  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).

        o  The Left and Right keys move the insert cursor one character to the
           left or right;  they also clear any selection  in  the  entry.   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 char-
           acter.   Control-Left  and  Control-Right move the insert cursor by
           words, and  Control-Shift-Left  and  Control-Shift-Right  move  the
           insert  cursor  by  words and also extend the selection.  Control-b
           and Control-f behave the same as Left and Right, respectively.

        o  The Home key and Control-a move the insert cursor to the  beginning
           of  the  entry  and  clear  any selection in the entry.  Shift-Home
           moves the insert cursor to the beginning of the entry  and  extends
           the selection to that point.

        o  The  End key and Control-e move the insert 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.

        o  Control-/ selects all the text in the entry.

        o  Control-\ clears any selection in the entry.

        o  The standard Tk <<Cut>>, <<Copy>>, <<Paste>>, and <<Clear>> virtual
           events operate on the selection in the expected manner.

        o  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 insert cursor.

        o  The BackSpace key and Control-h delete the selection, if  there  is
           one in the entry.  If there is no selection, it deletes the charac-
           ter to the left of the insert cursor.

        o  Control-d deletes the character to the right of the insert cursor.

        o  Control-k deletes all the characters to the right of the  insertion
           cursor.

WIDGET STATES
       In  the  disabled state, the entry cannot be edited and the text cannot
       be selected.  In the readonly state, no insert cursor is displayed  and
       the  entry  cannot  be edited (specifically: the insert and delete com-
       mands have no effect).  The disabled state is the same as readonly, and
       in addition text cannot be selected.

       Note  that  changes to the linked -textvariable will still be reflected
       in the entry, even if it is disabled or readonly.

       Typically, the text is "grayed-out" in the disabled state, and  a  dif-
       ferent background is used in the readonly state.

       The  entry  widget  sets  the  invalid state if revalidation fails, and
       clears it whenever validation succeeds.

SEE ALSO
       ttk::widget(n), entry(n)

KEYWORDS
       entry, widget, text field


       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source        was        downloaded        from         https://source-
       forge.net/projects/tcl/files/Tcl/8.6.7/tk8.6.7-src.tar.gz/download

       Further information about this software can be found on the open source
       community website at https://www.tcl.tk/.



Tk                                    8.5                       ttk::entry(1t)