Package: gtk

Class gtk-entry

Superclasses

gtk-widget, g-initially-unowned, gtk-buildable, gtk-editable, gtk-cell-editable, g-object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

Direct Slots

activates-default
The activates-default property of type :boolean (Read / Write)
Whether to activate the default widget (such as the default button in a dialog) when Enter is pressed.
Default value: nil
attributes
The attributes property of type pango-attr-list (Read / Write)
A list of Pango attributes to apply to the text of the entry. This is mainly useful to change the size or weight of the text.
Since 3.6
buffer
The buffer property of type gtk-entry-buffer (Read / Write / Construct)
Text buffer object which actually stores entry text.
caps-lock-warning
The caps-lock-warning property of type :boolean (Read / Write)
Whether password entries will show a warning when Caps Lock is on. Note that the warning is shown using a secondary icon, and thus does not work if you are using the secondary icon position for some other purpose.
Default value: true
completion
The completion property of type gtk-entry-completion (Read / Write)
The auxiliary completion object to use with the entry.
cursor-position
The cursor-position property of type :int (Read)
The current position of the insertion cursor in chars.
Allowed values: [0,65535]
Default value: 0
editable
The editable property of type :boolean (Read / Write)
Whether the entry contents can be edited.
Default value: true
enable-emoji-completion
The enable-emoji-completion property of type :boolean (Read / Write)
Whether to suggest Emoji replacements.
Default value: nil
Since 3.22
has-frame
The has-frame property of type :boolean (Read / Write)
Nil removes outside bevel from entry.
Default value: true
im-module
The im-module property of type :string (Read / Write)
Which IM (input method) module should be used for this entry. See gtk-im-context. Setting this to a non-nil value overrides the system-wide IM module setting. See the gtk-settings gtk-im-module property.
Default value: nil
inner-border
The inner-border property of type gtk-border (Read / Write)
Sets the text area's border between the text and the frame.
Warning: The inner-border property has been deprecated since version 3.4 and should not be used in newly written code. Use the standard border and padding CSS properties through objects like gtk-style-context and gtk-css-provider; the value of this style property is ignored.
input-hints
The input-hints property of type gtk-input-hints (Read / Write)
Additional hints (beyond the input-purpose property) that allow input methods to fine-tune their behaviour.
Since 3.6
input-purpose
The input-purpose property of type gtk-input-purpose (Read / Write)
The purpose of this text field. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. Note that setting the purpose to :password or :pin is independent from setting the visibility property.
Default value: :free-form
Since 3.6
invisible-char
The invisible-char property of type :uint (Read / Write)
The invisible character is used when masking entry contents in "password mode". When it is not explicitly set with the invisible-char property, GTK+ determines the character to use from a list of possible candidates, depending on availability in the current font. This style property allows the theme to prepend a character to the list of candidates.
Default value: "*"
invisible-char-set
The invisible-char-set property of type :boolean (Read / Write)
Whether the invisible char has been set for the gtk-entry.
Default value: nil
max-length
The max-length property of type :int (Read / Write)
Maximum number of characters for this entry. Zero if no maximum.
Allowed values: [0,65535]
Default value: 0
max-width-chars
The max-width-chars property of type :int (Read / Write) The desired maximum width of the entry, in characters. If this property is set to -1, the width will be calculated automatically.
Allowed values: >= -1
Default value: -1
Since 3.12
overwrite-mode
The overwrite-mode property of type :boolean (Read / Write)
If text is overwritten when typing in the gtk-entry.
Default value: nil
placeholder-text
The placeholder-text property of type :string (Read / Write)
The text that will be displayed in the gtk-entry when it is empty and unfocused.
Default value: nil
populate-all
If populate-all is true, the "populate-popup" signal is also emitted for touch popups.
Default value: nil
Since 3.8
primary-icon-activatable
The primary-icon-activatable property of type :boolean (Read / Write)
Whether the primary icon is activatable. GTK+ emits the "icon-press" and "icon-release" signals only on sensitive, activatable icons. Sensitive, but non-activatable icons can be used for purely informational purposes.
Default value: true
primary-icon-gicon
The primary-icon-gicon property of type g-icon (Read / Write)
The g-icon to use for the primary icon for the entry.
primary-icon-name
The primary-icon-name property of type :string (Read / Write)
The icon name to use for the primary icon for the entry.
Default value: nil
primary-icon-pixbuf
The primary-icon-pixbuf property of type gdk-pixbuf (Read / Write)
A pixbuf to use as the primary icon for the entry.
primary-icon-sensitive
The primary-icon-sensitive property of type :boolean (Read / Write)
Whether the primary icon is sensitive. An insensitive icon appears grayed out. GTK+ does not emit the "icon-press" and "icon-release" signals and does not allow DND from insensitive icons. An icon should be set insensitive if the action that would trigger when clicked is currently not available.
Default value: true
primary-icon-stock
The primary-icon-stock property of type :string (Read / Write)
The stock ID to use for the primary icon for the entry.
Warning: The primary-icon-stock property has been deprecated since version 3.10 and should not be used in newly-written code. Use the primary-icon-name property instead.
Default value: nil
primary-icon-storage-type
The primary-icon-storage-type property of type gtk-image-type (Read)
The representation which is used for the primary icon of the entry.
Default value: :empty
primary-icon-tooltip-markup
The primary-icon-tooltip-markup property of type :string (Read / Write)
The contents of the tooltip on the primary icon, which is marked up with the Pango text markup language. Also see the function gtk-entry-set-icon-tooltip-markup.
Default value: nil
primary-icon-tooltip-text
The primary-icon-tooltip-text property of type :string (Read / Write)
The contents of the tooltip on the primary icon. Also see the function gtk-entry-set-icon-tooltip-text.
Default value: nil
progress-fraction
The progress-fraction property of type :double (Read / Write)
The current fraction of the task that is been completed.
Allowed values: [0,1]
Default value: 0
progress-pulse-step
The progress-pulse-step property of type :double (Read / Write)
The fraction of total entry width to move the progress bouncing block for each call to the function gtk-entry-progress-pulse.
Allowed values: [0,1]
Default value: 0.1
scroll-offset
The scroll-offset property of type :int (Read)
Number of pixels of the entry scrolled off the screen to the left.
Allowed values: >= 0
Default value: 0
secondary-icon-activatable
The secondary-icon-activatable property of type :boolean (Read / Write)
Whether the secondary icon is activatable. GTK+ emits the "icon-press" and "icon-release" signals only on sensitive, activatable icons. Sensitive, but non-activatable icons can be used for purely informational purposes.
Default value: true
secondary-icon-gicon
The secondary-icon-gicon property of type g-icon (Read / Write)
The g-icon to use for the secondary icon for the entry.
secondary-icon-name
The secondary-icon-name property of type :string (Read / Write)
The icon name to use for the secondary icon for the entry.
Default value: nil
secondary-icon-pixbuf
The secondary-icon-pixbuf property of type gdk-pixbuf (Read / Write)
An pixbuf to use as the secondary icon for the entry.
secondary-icon-sensitive
The secondary-icon-sensitive property of type :boolean (Read / Write)
Whether the secondary icon is sensitive. An insensitive icon appears grayed out. GTK+ does not emit the "icon-press" and "icon-release" signals and does not allow DND from insensitive icons. An icon should be set insensitive if the action that would trigger when clicked is currently not available.
Default value: true
secondary-icon-stock
The secondary-icon-stock property of type :string (Read / Write)
The stock ID to use for the secondary icon for the entry.
Warning: The secondary-icon-stock property has been deprecated since version 3.10 and should not be used in newly-written code. Use the secondary-icon-name property instead.
Default value: nil
secondary-icon-storage-type
The secondary-icon-storage-type property of type gtk-image-type (Read)
The representation which is used for the secondary icon of the entry.
Default value: :empty
secondary-icon-tooltip-markup
The secondary-icon-tooltip-markup property of type :string (Read / Write)
The contents of the tooltip on the secondary icon, which is marked up with the Pango text markup language. Also see the function gtk-entry-set-icon-tooltip-markup.
Default value: nil
secondary-icon-tooltip-text
The secondary-icon-tooltip-text property of type :string (Read / Write)
The contents of the tooltip on the secondary icon. Also see the function gtk-entry-set-icon-tooltip-text.
Default value: nil
selection-bound
The selection-bound property of type :int (Read)
The position of the opposite end of the selection from the cursor in chars.
Allowed values: [0,65535]
Default value: 0
shadow-type
The shadow-type property of type gtk-shadow-type (Read / Write)
Which kind of shadow to draw around the entry when "has-frame" is set to true.
Warning: The shadow-type property has been deprecated since version 3.20 and should not be used in newly-written code. Use CSS to determine the style of the border; the value of this style property is ignored.
Default value: :in
show-emoji-icon
The show-emoji-icon property of type :boolean (Read / Write)
Whether to show an icon for Emoji.
Default value: nil
Since 3.22
tabs
The tabs property of type pango-tab-array (Read / Write)
A list of tabstop locations to apply to the text of the entry.
Since 3.10
text
The text property of type :string (Read / Write)
The contents of the entry.
Default value: ""
text-length
The text-length property of type :uint (Read)
The length of the text in the gtk-entry.
Allowed values: <= 65535
Default value: 0
truncate-multiline
The truncate-multiline property of type :boolean (Read / Write)
When true, pasted multi-line text is truncated to the first line.
Default value: nil
visibility
The visibility property of type :boolean (Read / Write)
Nil displays the "invisible char" instead of the actual text (password mode).
Default value: true
width-chars
The width-chars property of tpye :int (Read / Write)
Number of characters to leave space for in the entry.
Allowed values: >= -1
Default value: -1
xalign
The xalign property of type :float (Read / Write)
The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts.
Allowed values: [0,1]
Default value: 0

Details

The gtk-entry widget is a single line text entry widget. A fairly large set of key bindings are supported by default. If the entered text is longer than the allocation of the widget, the widget will scroll so that the cursor position is visible.



When using an entry for passwords and other sensitive information, it can be put into "password mode" using the generic function gtk-entry-visibility. In this mode, entered text is displayed using a 'invisible' character. By default, GTK+ picks the best invisible character that is available in the current font, but it can be changed with the generic function gtk-entry-invisible-char. GTK+ displays a warning when Caps Lock or input methods might interfere with entering text in a password entry. The warning can be turned off with the caps-lock-warning property.

gtk-entry has the ability to display progress or activity information behind the text. To make an entry display such information, use the generic functions gtk-entry-progress-fraction or gtk-entry-progress-pulse-step.

Additionally, gtk-entry can show icons at either side of the entry. These icons can be activatable by clicking, can be set up as drag source and can have tooltips. To add an icon, use the function gtk-entry-set-icon-from-gicon or one of the various other functions that set an icon from a stock ID, an icon name or a pixbuf. To trigger an action when the user clicks an icon, connect to the "icon-press" signal. To allow DND operations from an icon, use the function gtk-entry-set-icon-drag-source. To set a tooltip on an icon, use the function gtk-entry-set-icon-tooltip-text or the corresponding function for markup.

Note that functionality or information that is only available by clicking on an icon in an entry may not be accessible at all to users which are not able to use a mouse or other pointing device. It is therefore recommended that any such functionality should also be available by other means, e. g. via the context menu of the entry.

Style Property Details

icon-prelight
The icon-prelight style property of type :boolean (Read)
The prelight style property determines whether activatable icons prelight on mouseover.
Warning: The icon-prelight style property has been deprecated since version 3.20 and should not be used in newly-written code. Use CSS to control the appearance of prelighted icons; the value of this style property is ignored.
Default value: true
inner-border
The inner-border style property of type gtk-border (Read)
Sets the text area's border between the text and the frame.
Warning: The inner-border style property has been deprecated since version 3.4 and should not be used in newly written code. Use the standard border and padding CSS properties through objects like gtk-style-context and gtk-css-provider; the value of this style property is ignored.
invisible-char
The invisible-char style property of type :uint (Read)
The invisible character is used when masking entry contents in "password mode". When it is not explicitly set with the invisible-char property, GTK+ determines the character to use from a list of possible candidates, depending on availability in the current font. This style property allows the theme to prepend a character to the list of candidates.
Default value: 0
progress-border
The progress-border style property of type gtk-border (Read)
The border around the progress bar in the entry.
Warning: The progress-border style property has been deprecated since version 3.4 and should not be used in newly written code. Use the standard margin CSS property through objects like gtk-style-context and gtk-css-provider; the value of this style property is ignored.

Signal Details

The "activate" signal
 lambda (entry)    : Action      
A keybinding signal which gets emitted when the user activates the entry. Applications should not connect to it, but may emit it with the g-signal-emit-by-name function if they need to control activation programmatically. The default bindings for this signal are all forms of the Enter key.
entry
The gtk-entry object on which the signal is emitted.
The "backspace" signal
 lambda (entry)    : Action      
The "backspace" signal is a keybinding signal which gets emitted when the user asks for it. The default bindings for this signal are Backspace and Shift-Backspace.
entry
The gtk-entry object which received the signal.
The "copy-clipboard" signal
 lambda (entry)    : Action      
The "copy-clipboard" signal is a keybinding signal which gets emitted to copy the selection to the clipboard. The default bindings for this signal are Ctrl-c and Ctrl-Insert.
entry
The gtk-entry object which received the signal.
The "cut-clipboard" signal
 lambda (entry)    : Action      
The "cut-clipboard" signal is a keybinding signal which gets emitted to cut the selection to the clipboard. The default bindings for this signal are Ctrl-x and Shift-Delete.
entry
The gtk-entry object which received the signal.
The "delete-from-cursor" signal
 lambda (entry type count)    : Action      
The "delete-from-cursor" signal is a keybinding signal which gets emitted when the user initiates a text deletion. If the type is :chars of the gtk-delete-type enumeration, GTK+ deletes the selection if there is one, otherwise it deletes the requested number of characters. The default bindings for this signal are Delete for deleting a character and Ctrl-Delete for deleting a word.
entry
The gtk-entry object which received the signal.
type
The granularity of the deletion, as a gtk-delete-type enumeration.
count
The number of type units to delete.
The "icon-press" signal
 lambda (entry icon-pos event)    : Run Last      
The "icon-press" signal is emitted when an activatable icon is clicked.
entry
The gtk-entry object on which the signal is emitted.
icon-pos
The position of type gtk-entry-icon-position of the clicked icon.
event
The button press event.
The "icon-release" signal
 lambda (entry icon-pos event)    : Run Last      
The "icon-release" signal is emitted on the button release from a mouse click over an activatable icon.
entry
The gtk-entry object on which the signal is emitted.
icon-pos
The position of the clicked icon.
event
The button release event.
The "insert-at-cursor" signal
 lambda (entry string)    : Action      
The "insert-at-cursor" signal is a keybinding signal which gets emitted when the user initiates the insertion of a fixed string at the cursor. This signal has no default bindings.
entry
The gtk-entry object which received the signal.
string
The string to insert.
The "insert-emoji" signal
 lambda (entry)    : Action      
The "insert-emoji" signal is a keybinding signal which gets emitted to present the Emoji chooser for the entry. The default bindings for this signal are Ctrl-. and Ctrl-;
entry
The gtk-entry object which received the signal.
Since 3.22

The "move-cursor" signal
 lambda (entry step count extend-selection)    : Action      
The "move-cursor" signal is a keybinding signal which gets emitted when the user initiates a cursor movement. If the cursor is not visible in entry, this signal causes the viewport to be moved instead. Applications should not connect to it, but may emit it with the g-signal-emit-by-name function if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifer does not. There are too many key combinations to list them all here.
  • Arrow keys move by individual characters/lines.
  • Ctrl-arrow key combinations move by words/paragraphs.
  • Home/End keys move to the ends of the buffer.
entry
The gtk-entry object which received the signal.
step
The granularity of the move, as a gtk-movement-step.
count
The number of step units to move.
extend-selection
True if the move should extend the selection.
The "paste-clipboard" signal
 lambda (entry)    : Action      
The "paste-clipboard" signal is a keybinding signal which gets emitted to paste the contents of the clipboard into the text view. The default bindings for this signal are Ctrl-v and Shift-Insert.
entry
The gtk-entry object which received the signal.
The "populate-popup" signal
 lambda (entry menu)    : Run Last      
The "populate-popup" signal gets emitted before showing the context menu of the entry. If you need to add items to the context menu, connect to this signal and append your menuitems to the menu. If the populate-all property is true, this signal will also be emitted to populate touch popups. In this case, widget will be a different container, e. g. a gtk-toolbar. The signal handler should not make assumptions about the type of widget.
entry
The gtk-entry object on which the signal is emitted.
menu
The menu that is being populated.
The "preedit-changed" signal
 lambda (entry preedit)    : Action      
If an input method is used, the typed text will not immediately be committed to the buffer. So if you are interested in the text, connect to this signal.
entry
The gtk-entry object which received the signal.
preedit
The current preedit string.
The "toggle-overwrite" signal
 lambda (entry)    : Action      
The "toggle-overwrite" signal is a keybinding signal which gets emitted to toggle the overwrite mode of the entry. The default bindings for this signal is Insert.
entry
The gtk-entry object which received the signal.
 

Slot Access Functions

Inherited Slot Access Functions

See also

2014-6-8