doc/entryx.n

   1 '\"
   2 '\" Copyright (c) 1996-1999 Christian Werner
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .so man.macros
   8 .TH entryx n 8.0 Ck "Ck Built-In Commands"
   9 .BS
  10 '\" Note:  do not modify the .SH NAME line immediately below!
  11 .SH NAME
  12 entryx \- Create extended entry widgets
  13 .SH SYNOPSIS
  14 \fBentryx \fIpathName ?options?\fR
  15 .BE
  16
  17 .SH DESCRIPTION
  18 .PP
  19 This procedure is part of the Ck script library. It is a slightly extended
  20 version of the Tcl \fBentry\fR command which provides the following
  21 additional command line options:
  22 .TP
  23 \fB\-default \fIvalue\fR
  24 Default value for \fBinteger\fR, \fBunsigned\fR, and \fBfloat\fR modes,
  25 which is stored in entry widget on FocusOut, if the value in the widget
  26 is not a legal number. Defaults to an empty string.
  27 .TP
  28 \fB\-fieldwidth \fInumber\fR
  29 Limits the string in the entry widget to at most \fInumber\fR characters.
  30 Defaults to some ten thousand characters.
  31 .TP
  32 \fB\-initial \fIvalue\fR
  33 Initial value for the entry's string. If this option is omitted, no
  34 initial value is set.
  35 .TP
  36 \fB\-mode \fImodeName\fR
  37 Determines the additional bindings for input checking which will be
  38 bound to the entry widget. \fIModeName\fR must be one of \fBinteger\fR
  39 (for integer numbers including optional sign), \fBunsigned\fR (for
  40 integer numbers without sign), \fBfloat\fR (for
  41 floating point numbers including optional sign and fractional part,
  42 but without exponent part), \fBnormal\fR (for entries without input
  43 checking at all), \fBregexp\fR (for checking the entry's string
  44 against a regular expression), and \fBboolean\fR (for boolean values,
  45 e.g. 0 or 1, Y or N and so on).
  46 If the \fB\-mode\fR option is omitted, \fBnormal\fR is chosen as default.
  47 .TP
  48 \fB\-offvalue \fIchar\fR
  49 For mode \fBboolean\fR entry widgets only: \fIchar\fR is used for the
  50 ``false'' state of the entry. \fIChar\fR defaults to ``0''. It is always
  51 converted to upper case.
  52 .TP
  53 \fB\-onvalue \fIchar\fR
  54 For mode \fBboolean\fR entry widgets only: \fIchar\fR is used for the
  55 ``true'' state of the entry. \fIChar\fR defaults to ``1''. It is always
  56 converted to upper case.
  57 .TP
  58 \fB\-regexp \fIregExp\fR
  59 For all modes this is the regular expression which provides input filtering.
  60 This option is ignored for \fBboolean\fR mode.
  61 .TP
  62 \fB\-touchvariable \fIvarName\fR
  63 The global variable \fIvarName\fR is set to 1 whenever the user
  64 changes the entry's string. The user may reset this variable to 0
  65 at any time.
  66 .PP
  67 These options must be given at creation time of the entry. They cannot
  68 be modified later using the \fBconfigure\fR widget command.
  69 .PP
  70 After creating the entry widget, \fBentryx\fR binds procedures to
  71 do input checking using the \fBbindtags\fR mechanism to the entry widget.
  72 These procedures provide for overtype rather than insert mode and give
  73 the following behaviour:
  74 .IP [1]
  75 If mouse button 1 is pressed on the entry and the entry accepts the input
  76 focus, the input focus is set on the entry and the entry's insertion cursor
  77 is placed on the very first character.
  78 .IP [2]
  79 The Left and Right keys move the insertion cursor one character to the
  80 left or right. In \fBboolean\fR mode these keys are used for keyboard
  81 traversal, i.e. the Left key moves the focus to the previous widget in
  82 focus order, the Right key to the next widget.
  83 .IP [3]
  84 The return key moves the input focus to the next widget in focus order.
  85 .IP [4]
  86 The Home key moves the insertion cursor to the
  87 beginning of the entry. In \fBboolean\fR mode this key is ignored.
  88 .IP [5]
  89 The End key moves the insertion cursor to the
  90 end of the entry. In \fBboolean\fR mode this key is ignored.
  91 .IP [6]
  92 The Delete key deletes the character to the right of the insertion cursor.
  93 In \fBboolean\fR mode this key is ignored.
  94 .IP [7]
  95 The BackSpace key and Control-h delete the character to the left of
  96 the insertion cursor. In \fBboolean\fR mode this key is ignored.
  97 .IP [8]
  98 The space key deletes from the insertion cursor until the end of the entry,
  99 if the mode is \fBinteger\fR, \fBunsigned\fR, \fBfloat\fR or \fBregexp\fR.
 100 For \fBregexp\fR mode, the space character must not be part of the regular
 101 expression to achieve this behaviour. Otherwise it is treated as all other
 102 printable keys. In \fBboolean\fR mode this key toggles the entry's value.
 103 .IP [9]
 104 All other printable keys are checked according to the entry's mode.
 105 If allowed they overtype the character under the insertion cursor, otherwise
 106 they are ignored and the terminal's bell is rung.
 107 Lower case characters are automatically converted to upper case, if the
 108 regular expression filters denies lower case characters but allows upper
 109 case characters.
 110 .IP [10]
 111 FocusIn is bound to display the entry with the \fIreverse\fR attribute for
 112 monochrome screens or with swapped foreground and background colors on color
 113 screens; additionally, the insertion cursor is placed on the very first
 114 character in the entry.
 115 .IP [11]
 116 FocusOut is bound to restore the visual effects of FocusIn, i.e. on
 117 mononochrome screens, the \fIreverse\fR attribute is removed,
 118 on color screens, the foreground and background colors are restored to
 119 their original values. For \fBinteger\fR, \fBunsigned\fR, and \fIfloat\fR
 120 modes, the entry's value is finally checked using the \fBscan\fR Tcl command.
 121 If the value is legal it is restored into the entry as the return from the
 122 \fBscan\fR, thus giving the Tcl canonical form for the value, i.e. no leading
 123 zeros for integral values (which otherwise could be interpreted as octal
 124 numbers) and a decimal point with at least one fractional
 125 digit for floating point values (which otherwise could be interpreted as
 126 integral numbers). If the \fBscan\fR conversion fails, the value specified
 127 in the \fB\-default\fR option is stored into the entry.
 128
 129 .SH KEYWORDS
 130 entry, input