Package: gtk

Class gtk:entry

Superclasses

Documented Subclasses

None

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 the Enter key is pressed.
Default value: false
attributes
The attributes property of type pango:attr-list (Read / Write)
The list of Pango attributes to apply to the text of the text entry. This is mainly useful to change the size or weight of the text. The start-index and end-index fields of the pango:attribute structure must refer to the text of the gtk:entry-buffer object, for example, without the preedit string.
buffer
The buffer property of type gtk:entry-buffer (Read / Write / Construct)
The entry buffer which actually stores the text for the text entry.
completion
The completion property of type gtk:entry-completion (Read / Write)
The auxiliary completion object to use with the entry. Deprecated 4.10
enable-emoji-completion
The enable-emoji-completion property of type :boolean (Read / Write)
Whether to suggest Emoji replacements.
Default value: false
extra-menu
The extra-menu property of type g:menu-model (Read / Write)
The menu model whose contents will be appended to the context menu.
has-frame
The has-frame property of type :boolean (Read / Write)
False removes outside bevel from the text entry.
Default value: true
im-module
The im-module property of type :string (Read / Write)
The IM (Input Method) module that should be used for the text entry. See the gtk:im-context documentation. Setting this to a non-nil value overrides the system-wide IM module setting. See the gtk-im-module setting.
Default value: nil
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.
input-purpose
The input-purpose property of type gtk:input-purpose (Read / Write)
The purpose of the text entry. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. Note that setting the purpose to the :password or :pin values is independent from setting the visibility property.
Default value: :free-form
invisible-char
The invisible-char property of type :uint (Read / Write)
The invisible character is used when masking the text entry contents in "password mode".
Default value: (char-code #*)
invisible-char-set
The invisible-char-set property of type :boolean (Read / Write)
Whether the invisible char has been set for the text entry.
Default value: false
max-length
The max-length property of type :int (Read / Write)
The maximum number of characters for the text entry. Zero if no maximum.
Allowed values: [0,65535]
Default value: 0
overwrite-mode
The overwrite-mode property of type :boolean (Read / Write)
Whether text is overwritten when typing in the text entry.
Default value: false
placeholder-text
The placeholder-text property of type :string (Read / Write)
The text that will be displayed in the text entry when it is empty and unfocused.
Default value: nil
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 icon to use as the primary icon for the text entry.
primary-icon-name
The primary-icon-name property of type :string (Read / Write)
The icon name from the current icon theme to use as the primary icon for the text entry.
Default value: nil
primary-icon-paintable
The primary-icon-paintable property of type gdk:paintable (Read / Write)
The paintable to use as the primary icon for the text 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 drag and drop 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-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 text 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 gtk:entry-icon-tooltip-markup function.
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.
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 text entry width to move the progress bouncing block for each call to the gtk:entry-progress-pulse function.
Allowed values: [0,1]
Default value: 0.0
scroll-offset
The scroll-offset property of type :int (Read)
The number of pixels of the text 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 icon to use as the secondary icon for the text entry.
secondary-icon-name
The secondary-icon-name property of type :string (Read / Write)
The icon name from the current icon theme to use as the secondary icon for the text entry.
Default value: nil
secondary-icon-paintable
The secondary-icon-paintable property of type gdk:paintable (Read / Write)
The paintable to use as the secondary icon for the text 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 drag and drop 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-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 text 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 gtk:entry-icon-tooltip-markup function.
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.
Default value: nil
show-emoji-icon
The show-emoji-icon property of type :boolean (Read / Write)
Whether to show an icon for Emoji.
Default value: false
tabs
The tabs property of type pango:tab-array (Read / Write)
The list of tabstop locations to apply to the text of the text entry.
text-length
The text-length property of type :uint (Read)
The length of the text in the text 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: false
visibility
The visibility property of type :boolean (Read / Write)
False displays the "invisible char" instead of the actual text (password mode).
Default value: true

Details

The gtk:entry widget is a single line text entry. 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.

Figure: GtkEntry

When using a text entry for passwords and other sensitive information, it can be put into "password mode" using the gtk:entry-visibility function. In this mode, entered text is displayed using an 'invisible' character. By default, GTK picks the best invisible character that is available in the current font, but it can be changed with the gtk:entry-invisible-char function.

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

Additionally, the gtk:entry widget can show icons at either side of the text 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 gtk:entry-set-icon-from-gicon function or one of the various other functions that set an icon from an icon name or a paintable. 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 gtk:entry-set-icon-drag-source function. To set a tooltip on an icon, use the gtk:entry-icon-tooltip-text function or the corresponding function for markup.

Note that functionality or information that is only available by clicking on an icon in an text 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 such functionality is also available by other means, such as the context menu of the text entry.

CSS nodes

entry[.flat][.warning][.error]
├── text[.readonly]
├── image.left
├── image.right
╰── [progress[.pulse]]    
The gtk:entry implementation has a main node with the name entry. Depending on the properties of the text entry, the .read-only and .flat style classes may appear. The .warning and .error style classes may also be used with entries.

When the text entry shows icons, it adds subnodes with the name image and the .left or .right style class, depending on where the icon appears.

When the text entry shows progress, it adds a subnode with the name progress. The node has the .pulse style class when the shown progress is pulsing.

For all the subnodes added to the text node in various situations, see the gtk:text widget.

GtkEntry as GtkBuildable

The gtk:entry implementation of the gtk:buildable interface supports a custom <attributes> element, which supports any number of <attribute> elements. The <attribute> element has attributes named "name", "value", "start" and "end" and allows you to specify pango:attribute values for this label.

An example of a UI definition fragment specifying Pango attributes:
<object class="GtkEntry">
  <attributes>
    <attribute name="weight" value="PANGO_WEIGHT_BOLD"/>
    <attribute name="background" value="red" start="5" end="10"/>
  </attributes>
</object>    
The start and end attributes specify the range of characters to which the Pango attribute applies. If start and end are not specified, the attribute is applied to the whole text. Note that specifying ranges does not make much sense with translatable attributes. Use markup embedded in the translatable content instead.

Accessibility

The gtk:entry implementation uses the :text-box role of the gtk:accessible-role enumeration.

Signal Details

The "activate" signal
lambda (entry)    :action      
entry
The gtk:entry widget on which the signal is emitted.
A keybinding signal which gets emitted when the user activates the text entry. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control activation programmatically. The default bindings for this signal are all forms of the Enter key.
The "icon-press" signal
lambda (entry pos)    :run-last      
entry
The gtk:entry widget on which the signal is emitted.
pos
The position of the clicked icon as a gtk:entry-icon-position value.
The signal is emitted when an activatable icon is clicked.
The "icon-release" signal
lambda (entry pos)    :run-last      
entry
The gtk:entry widget on which the signal is emitted.
pos
The position of the clicked icon as a gtk:entry-icon-position value.
The signal is emitted on the button release from a mouse click over an activatable icon.
 

Returned by

Slot Access Functions

Inherited Slot Access Functions

See also

2024-11-26