Documentation‎ > ‎Entries‎ > ‎

gnocl::entry

A widget which allows the user to input a small amount of text.

Synopsis

gnocl::entry [-option value...]

Screenshot

Options

-align float (default:0)  from 0 (left) to 1 (right)
The input location of the entry values can be set from left, as with Alphanumeric fields, or right as per number only entries. A value of 0.5 will cause the text to be positioned centrally in the widget.


NOTE: The effect is reversed for RTL writing systems.
-data string
User defined data which can be retrieved via the cget subcommand.
-editable boolean (default: true)
Whether the the entry is editable.
-hasFocus 1
This sets the focus to the widget. To unset the focus it must be set to another widget.
-heightGroup string (default: "")
The -heightGroup option can be an arbitrary string. All widgets with the same heightGroup request the same height. If packed with the fill flag set, they will have nevertheless different heights.
-maxLength integer (default: -1)
Maximum length of entry value (-1 means not limited).
-name string
Name of the widget, can be used to set options in an rc file.
-onActivate  string (default: "")
Tcl command which is executed if the Enter is pressed in the entry. Before evaluation the following percent strings are substituted:

%w    widget name
%t      text contents of the entry widget buffer
%d     data associated with this widget instance. Returns value set by the -data option otherwise returns an empty string.
-onBackspace  string (default: "")
Tcl command which is executed if the Backspace is pressed in the entry. Before evaluation the following percent strings are substituted:

%w    widget name
-onChanged string (default: "")
Tcl command which is executed if the value of the entry is changed via the GUI. Before evaluation the following percent strings are substituted:

%w    widget name
%v    value of the active item
NOTE: This command is not called if the value is changed via the option -value.
-onCopy  string (default: "")
Tcl command which is executed if a copy to clipboard event occurs in the entry. Before evaluation the following percent strings are substituted:

%w    widget name
%t      text contents of the entry widget buffer
-onCursor  string (default: "")
Tcl command which is executed if the whenever the cursor is moved within in the entry. Before evaluation the following percent strings are substituted:

%w    widget name
%t      text contents of the entry widget buffer
-onCut  string (default: "")
Tcl command which is executed if a cut to clipboard event occurs in the entry. Before evaluation the following percent strings are substituted:

%w    widget name
%t      text contents of the entry widget buffer
-onDel  string (default: "")
Tcl command which is executed if the Delete key  is pressed in the entry. Before evaluation the following percent strings are substituted:

%w    widget name
%t      text contents of the entry widget buffer
-onInsert  string (default: "")
Tcl command which is executed whenever text is inserted into the widget. Before evaluation the following percent strings are substituted:

%w    widget name
%g      widget glade/builder name
%t      text contents of the entry widget buffer
-onIconPress  string (default: "")
Tcl command which is executed whenever one of the embedded icons is clicked. Before evaluation the following percent strings are substituted:

%w    widget name
%g     widget glade/builder name
%t      type of event, ie, one of : buttonPress, button2Press, button3Press or buttonRelease.
%p     icon position, either primary or seconday..
-onKeyPress  string (default: "")

Tcl script which is executed if a key is pressed inside the widget. Before evaluation the following percent strings are substituted: 

%w     widget name
%k      keycode
%K      keycode as symbol
%a      character
%s      state of buttons and modifiers (bitmask)
%g
     glade/builder name
%e     event type, ie. "key_press_event"
The %e substitution string is typically used in conjunction with the gnocl::signalStop command to effectively inhibit further execution of the active event. This functionality is particularly valuable when scripts require the validation of keyboard values.
-onKeyRelease

type: string (default: "")

Tcl script which is executed if a key is released inside the widget. Before evaluation the following percent strings are substituted:

%w     widget name
%k      keycode
%K      keycode as symbol
%a      character
%s      state of buttons and modifiers (bitmask)
%g
     glade/builder name
%e     event type, ie. "key_release_event"

-onOverwrite  string (default: "")
Tcl command which is executed whenever the overwrite setting of the entry is changed. Before evaluation the following percent strings are substituted:

%w    widget name
%t      text contents of the entry widget buffer
-onPaste string (default: "")
Tcl command which is executed whenever a paste from clipboard event occurs  in the entry. Before evaluation the following percent strings are substituted:

%w    widget name
%t      text contents of the entry widget buffer
-onPopulatePopup  string (default: "")
Tcl script which is executed prior to the display of the defaut widget popup menu allowing the controlling script to add items and submenus to the popup. This command is used in conjunction with the widget popup command. Before evaluation the following percent strings are substituted:
%w   widget name
%g    widget glade name
-onRealize string (default: "")
Tcl command which is executed in the global scope if the widget has been realized. Before evaluation the following percent strings are substituted:

%w    widget name
-onShowHelp string (default: "")
Tcl command which is executed in the global scope if the "show-help" signal is received, which is normally the case if the user presses F1 or Ctrl-F1. Before evaluation the following percent strings are substituted:

%w    widget name
%h    help type: either "whatsThis" or "tooltip"
-primaryIcon percent-string  (default = "")
Image to be shown at leftmost side of the entry area, can be either a file (prefix "%/") or a stock item (prefix "%#").
-secondaryIcon percent-string  (default = "")
Image to be shown at rightmost side of the entry area, can be either a file (prefix "%/") or a stock item (prefix "%#").
-sensitive boolean (default: 1)
Whether or not the item is sensitive to user input.
-sizeGroup string (default: "")
The -sizeGroup option can be an arbitrary string. All widgets with the same sizeGroup request the same size. If packed with the fill flag set, they will have nevertheless different sizes.
-tooltip string
Message that appear next to this widget when the mouse pointer is held over it for a short amount of time.
-textVisible boolean (default: true)
Whether the text is visible.
-value string (default: "")
Text of the entry.
-variable string (default: "")
The name of a global variable which is changed whenever the entry is changed
-visible boolean (default: 1)
Whether or not the item is visible.
-widthChars integer
Size of the widget in characters.
-widthGroup string (default: "")
The -widthGroup options can be an arbitrary string. All widgets with the same widthGroup request the same width. If packed with the fill flag set, they will have nevertheless different widths.

Description

A entry widget lets the user input some text.

Commands

id cget option
Returns the value for one option. The option may have any of the values accepted by configure.
id configure [-option value...]
Configures the widget. Option may have any of the values accepted on creation of the widget.
id delete
Deletes the widget and the associated tcl command.
id onChanged
Executes the command given by the -onChanged option.
id wordList subCommand string [-split]
Manipulate the entry completion list for this widget. Specifiying the -split option will result in strings containing spaces to be treated as lists of individual words. Duplicated items in the list are not permitted. All new words are prepended to the list.

SubCommand

add [wordlist]

Add the words contained in the list to those already in the completion list, default = ""

clear
Clear all words from the completion list.

delete
[word]

Delete the specified word from the completion list.

get

Returns a list of all words in the completion buffer.

Popup Menu Items

id popup item widgetId
Add single item to the popup menu. See gnocl::menuItem for more details on creating menu items.
id popup separator
Add a horizontal line to the popup menu in order to cluster related commands together.
id popup subMenu widgetId submenuId
Attach a submenu to the popupmenu item specified by widgetId.

Example

# the next line restarts using tclsh \
exec tclsh "$0" "$@"

package require Gnocl


set ent1 [gnocl::entry ]
gnocl::window -child $ent1

# simple alpha validation
$ent1 configure -onKeyPress {
    if {![string is alpha %K] } {
        gnocl::signalStop %w %e
    }
}

# press return
$ent1 configure -onActivate {
    puts %t
}

# add some items to the completion wordlist
$ent1 wordList add [list red orange yellow green blue indigo violet]

gnocl::mainLoop

Comments