Pmw/Pmw_1_2/doc/EntryField.html

   1
   2     <html>
   3     <head>
   4     <meta name="description" content="Pmw - a toolkit for building high-level compound widgets in Python">
   5     <meta name="content" content="python, megawidget, mega widget, compound widget, gui, tkinter">
   6     <title>Pmw.EntryField reference manual</title>
   7     </head>
   8
   9     <body bgcolor="#ffffff" text="#000000" link="#0000ee"
  10         vlink="551a8b" alink="ff0000">
  11
  12     <h1 ALIGN="CENTER">Pmw.EntryField</h1>
  13
  14 <center><IMG SRC=EntryField.gif ALT="" WIDTH=313 HEIGHT=177></center>
  15 <dl>
  16 <dt> <h3>Name</h3></dt><dd>
  17 <p>Pmw.EntryField() -
  18     entry widget with validation
  19 </p>
  20
  21
  22 </dd>
  23 <dt> <h3>Inherits</h3></dt><dd>
  24 <a href="MegaWidget.html">Pmw.MegaWidget</a><br>
  25 </dd>
  26 <dt> <h3>Description</h3></dt><dd>
  27 <p>
  28     An entry field contains an entry widget with optional validation of
  29     various kinds.  Built-in validation may be used, such as
  30     <strong>integer</strong>, <strong>real</strong>, <strong>time</strong> or <strong>date</strong>, or an external validation
  31     function may be supplied.  If valid text is entered, it will be
  32     displayed with the normal background.  If invalid text is entered,
  33     it is not displayed and the previously displayed text is restored.
  34     If partially valid text is entered, it will be displayed with a
  35     background color to indicate it is in error.  An example of
  36     partially valid <strong>real</strong> text is <strong>'-.'</strong>, which may be the first two
  37     charactes of the valid string <strong>'-.5'</strong>.  Some validators, such as
  38     <strong>date</strong>, have a relaxed interpretation of partial validity, which
  39     allows the user flexibility in how they enter the text.</p>
  40
  41 <p>    Validation is performed <em>early</em>, at each keystroke or other event
  42     which modifies the text.  However, if partially valid text is
  43     permitted, the validity of the entered text can be checked just
  44     before it is to be used, which is a form of <em>late</em> validation.</p>
  45
  46 <p>    Minimum and maximum values may be specified.  Some validators also
  47     accept other specifications, such as date and time formats and
  48     separators.</p>
  49
  50 <p></p>
  51
  52
  53 </dd>
  54 <dt> <h3>Validation function return values</h3></dt><dd>
  55 <p>
  56         Validation is performed by a function which takes as its first
  57         argument the entered text and returns one of three standard
  58         values, indicating whether the text is valid:</p>
  59
  60 <dl><dt><strong>Pmw.OK</strong></dt><dd>The text is valid.<p></p>
  61
  62 </dd>
  63 <dt><strong>Pmw.ERROR</strong></dt><dd>The text is invalid and is not acceptable for
  64             display.  In this case the entry will be restored to its
  65             previous value.<p></p>
  66
  67 </dd>
  68 <dt><strong>Pmw.PARTIAL</strong></dt><dd>The text is partially valid and is acceptable
  69             for display.  In this case the text will be displayed
  70             using the <strong>errorbackground</strong> color.<p></p>
  71 <p>        </p>
  72
  73
  74 </dd></dl>
  75
  76 </dd>
  77 <dt> <h3>Options</h3></dt><dd>
  78 Options for this megawidget and its base
  79 classes are described below.<p></p>
  80 <a name=option.command></a>
  81 <dl><dt> <strong>command
  82 </strong></dt><dd>
  83 This specifies a function to call whenever the <strong>&lt;Return&gt;</strong> key is
  84     pressed or <code>invoke()</code> is called. The default is <strong>None</strong>.</p>
  85
  86
  87 </dd></dl>
  88 <a name=option.errorbackground></a>
  89 <dl><dt> <strong>errorbackground
  90 </strong></dt><dd>
  91 Specifies the background color to use when displaying invalid or
  92     partially valid text. The default is <strong>'pink'</strong>.</p>
  93
  94
  95 </dd></dl>
  96 <a name=option.extravalidators></a>
  97 <dl><dt> <strong>extravalidators
  98 </strong></dt><dd>
  99 This is a dictionary of extra validators.  The keys are the names
 100     of validators which may be used in a future call to the
 101     <strong>validate</strong> option.  Each value in the dictionary is a tuple of
 102     (<em>validate_function</em>, <em>stringtovalue_function</em>).</p>
 103 <p>    The <em>validate_function</em> is used to implement the validation and
 104     the <em>stringtovalue_function</em> is used to convert the entry input
 105     into a value which can be compared with the minimum and maximum
 106     limits.  These functions are as described for the <strong>validate</strong>
 107     option.</p>
 108
 109 <p>    If either of these is not given as a function, it is assumed to be
 110     the name of one of the other extra validators or one of the
 111     standard validators.  The alias search is performed when the
 112     <strong>validate</strong> option is configured, not when the <strong>extravalidators</strong>
 113     option is configured or when the <strong>validate</strong> function is called.</p>
 114
 115 <p>    If the name of one of the extra validators is the same as one of
 116     the standard validators, the extra validator takes precedence. The default is <strong>{}</strong>.</p>
 117
 118
 119
 120 </dd></dl>
 121 <a name=option.invalidcommand></a>
 122 <dl><dt> <strong>invalidcommand
 123 </strong></dt><dd>
 124 This is executed when invalid text is entered and the text is
 125     restored to its previous value (that is, when the <strong>validate</strong>
 126     function returns <strong>Pmw.ERROR</strong>).  It is also called if an attempt is
 127     made to set invalid text in a call to <code>setentry()</code>.  The default
 128     is <strong>self.bell</strong>.</p>
 129
 130
 131 </dd></dl>
 132 <a name=option.labelmargin></a>
 133 <dl><dt> <strong>labelmargin
 134 </strong></dt><dd>
 135 Initialisation option. If the <strong>labelpos</strong> option is not <strong>None</strong>, this specifies the
 136         distance between the <strong>label</strong> component and the rest of the
 137         megawidget. The default is <strong>0</strong>.</p>
 138
 139
 140 </dd></dl>
 141 <a name=option.labelpos></a>
 142 <dl><dt> <strong>labelpos
 143 </strong></dt><dd>
 144 Initialisation option. Specifies where to place the <strong>label</strong> component.  If not
 145         <strong>None</strong>, it should be a concatenation of one or two of the
 146         letters <strong>'n'</strong>, <strong>'s'</strong>, <strong>'e'</strong> and <strong>'w'</strong>.  The first letter
 147         specifies on which side of the megawidget to place the label.
 148         If a second letter is specified, it indicates where on that
 149         side to place the label.  For example, if <strong>labelpos</strong> is <strong>'w'</strong>,
 150         the label is placed in the center of the left hand side; if
 151         it is <strong>'wn'</strong>, the label is placed at the top of the left
 152         hand side; if it is <strong>'ws'</strong>, the label is placed at the
 153         bottom of the left hand side.</p>
 154 <p>        If <strong>None</strong>, a label component is not created. The default is <strong>None</strong>.</p>
 155
 156
 157
 158 </dd></dl>
 159 <a name=option.modifiedcommand></a>
 160 <dl><dt> <strong>modifiedcommand
 161 </strong></dt><dd>
 162 This is called whenever the text of the entry has been changed
 163     due to user action or by a call to <code>setentry()</code>. The default is <strong>None</strong>.</p>
 164
 165
 166 </dd></dl>
 167 <a name=option.sticky></a>
 168 <dl><dt> <strong>sticky
 169 </strong></dt><dd>
 170 Initialisation option.  The default is <strong>'ew'</strong>.</p>
 171
 172
 173 </dd></dl>
 174 <a name=option.validate></a>
 175 <dl><dt> <strong>validate
 176 </strong></dt><dd>
 177 Specifies what kind of validation should be performed on the entry
 178     input text.</p>
 179 <p>    The most general way to specify the <strong>validate</strong> option is as a
 180     dictionary.  The kind of validation is specified by the
 181     <strong>'validator'</strong> dictionary field, which may be the name of one of
 182     the standard validators described below, the name of a validator
 183     supplied by the <strong>extravalidators</strong> option, a function or <strong>None</strong>.
 184     The default is <strong>None</strong>.</p>
 185
 186 <p>    Any other dictionary fields specify other restrictions on the
 187     entered values.  For all validators, the following fields may be
 188     specified:</p>
 189
 190 <dl><dt><strong>'min'</strong></dt><dd>Specifies the minimum acceptable value, or <strong>None</strong> if no
 191         minimum checking should be performed.  The default is <strong>None</strong>.<p></p>
 192
 193 </dd>
 194 <dt><strong>'max'</strong></dt><dd>Specifies the maximum acceptable value, or <strong>None</strong> if no
 195         maximum checking should be performed.  The default is <strong>None</strong>.<p></p>
 196
 197 </dd>
 198 <dt><strong>'minstrict'</strong></dt><dd>If true, then minimum checking is strictly enforced.
 199         Otherwise, the entry input may be less than <strong>min</strong>, but will be
 200         displayed using the <strong>errorbackground</strong> color.  The default is true.<p></p>
 201
 202 </dd>
 203 <dt><strong>'maxstrict'</strong></dt><dd>If true, then maximum checking is strictly enforced.
 204         Otherwise, the entry input may be more than <strong>max</strong>, but will be
 205         displayed using the <strong>errorbackground</strong> color.  The default is true.<p></p>
 206
 207 </dd></dl>
 208 <p>    If the dictionary contains a <strong>'stringtovalue'</strong> field, it overrides
 209     the normal <em>stringtovalue</em> function for the validator.  The
 210     <em>stringtovalue</em> function is described below.</p>
 211
 212 <p>    Other fields in the dictionary (apart from the core fields
 213     mentioned above) are passed on to the <em>validator</em> and
 214     <em>stringtovalue</em> functions as keyword arguments.</p>
 215
 216 <p>    If <strong>validate</strong> is not a dictionary, then it is equivalent to
 217     specifying it as a dictionary with a single <strong>'validator'</strong> field.
 218     For example, <code>validate = 'real'</code> is equivalent to /validate =
 219     {'validator' : 'real'}/ and specifies real numbers without any
 220     minimum or maximum limits and using <strong>'.'</strong> as the decimal point
 221     character.</p>
 222
 223 <p>    The standard validators accepted in the <strong>'validator'</strong> field are:</p>
 224
 225 <dl><dt><strong>'numeric'</strong></dt><dd>An integer greater than or equal to 0.  Digits
 226         only. No sign.<p></p>
 227
 228 </dd>
 229 <dt><strong>'integer'</strong></dt><dd>Any integer (negative, 0 or positive) as accepted
 230         by <code>string.atol()</code>.<p></p>
 231
 232 </dd>
 233 <dt><strong>'hexadecimal'</strong></dt><dd>Hex number (with optional leading <strong>'0x'</strong>), as accepted
 234         by <code>string.atol(text, 16)</code>.<p></p>
 235
 236 </dd>
 237 <dt><strong>'real'</strong></dt><dd>A number, with or without a decimal point and optional
 238         exponent (e or E), as accepted by <code>string.atof()</code>.  This
 239         validator accepts a <strong>'separator'</strong> argument, which specifies
 240         the character used to represent the decimal point.  The
 241         default <strong>'separator'</strong> is <strong>'.'</strong>.<p></p>
 242
 243 </dd>
 244 <dt><strong>'alphabetic'</strong></dt><dd>Consisting of the letters <strong>'a-z'</strong> and <strong>'A-Z'</strong>.
 245         In this case, <strong>'min'</strong> and <strong>'max'</strong> specify limits on the length
 246         of the text.<p></p>
 247
 248 </dd>
 249 <dt><strong>'alphanumeric'</strong></dt><dd>Consisting of the letters <strong>'a-z'</strong>, <strong>'A-Z'</strong> and <strong>'0-9'</strong>.
 250         In this case, <strong>'min'</strong> and <strong>'max'</strong> specify limits on the length
 251         of the text.<p></p>
 252
 253 </dd>
 254 <dt><strong>'time'</strong></dt><dd>Hours, minutes and seconds, in the format
 255         <strong>'HH:MM:SS'</strong>, as accepted by <code>Pmw.timestringtoseconds()</code>.
 256         This validator accepts a <strong>'separator'</strong> argument, which
 257         specifies the character used to separate the three fields.
 258         The default separator is <strong>':'</strong>.  The time may be negative.<p></p>
 259
 260 </dd>
 261 <dt><strong>'date'</strong></dt><dd>Day, month and year, as accepted by
 262         <code>Pmw.datestringtojdn()</code>.  This validator accepts a
 263         <strong>'separator'</strong> argument, which specifies the character used to
 264         separate the three fields.  The default is <strong>':'</strong>.  This
 265         validator also accepts a <strong>'format'</strong> argument, which is passed to
 266         <code>Pmw.datestringtojdn()</code> to specify the desired ordering of the
 267         fields.  The default is <strong>'ymd'</strong>.<p></p>
 268
 269 </dd></dl>
 270 <p>    If <strong>'validator'</strong> is a function, then it will be called whenever
 271     the contents of the entry may have changed due to user action or
 272     by a call to <code>setentry()</code>.  The function is called with at least
 273     one argument, the first one being the new text as modified by the
 274     user or <code>setentry()</code>.  The other arguments are keyword arguments
 275     made up of the non-core fields of the <strong>validate</strong> dictionary.</p>
 276
 277 <p>    The <em>validator</em> function should return <strong>Pmw.OK</strong>, <strong>Pmw.ERROR</strong> or
 278     <strong>Pmw.PARTIAL</strong> as described above.  It should not perform minimum
 279     and maximum checking.  This is done after the call, if it returns
 280     <strong>Pmw.OK</strong>.</p>
 281
 282 <p>    The <strong>'stringtovalue'</strong> field in the dictionary may be specified as
 283     the name of one of the standard validators, the name of a
 284     validator supplied by the <strong>extravalidators</strong> option, a function or
 285     <strong>None</strong>.</p>
 286
 287 <p>    The <em>stringtovalue</em> function is used to convert the entry input
 288     into a value which can then be compared with any minimum or
 289     maximum values specified for the validator.  If the <strong>'min'</strong> or
 290     <strong>'max'</strong> fields are specified as strings, they are converted using
 291     the <em>stringtovalue</em> function.  The <em>stringtovalue</em> function is
 292     called with the same arguments as the <em>validator</em> function.  The
 293     <em>stringtovalue</em> function for the standard number validators
 294     convert the string to a number.  Those for the standard alpha
 295     validators return the length of the string.  Those for the
 296     standard <strong>'time'</strong> and <strong>'date'</strong> validators return the number of
 297     seconds and the Julian Day Number, respectively.  See
 298     <code>Pmw.stringtoreal()</code>, <code>Pmw.timestringtoseconds()</code> and
 299     <code>Pmw.datestringtojdn()</code>.</p>
 300
 301 <p>    If the validator has been specified as a function and no
 302     <strong>'stringtovalue'</strong> field is given, then it defaults to the standard
 303     python <code>len()</code> function.</p>
 304
 305 <p>    If <strong>'validator'</strong> is <strong>None</strong>, no validation is performed.  However,
 306     minimum and maximum checking may be performed, according to the
 307     <em>stringtovalue</em> function.  For example, to limit the entry text to
 308     a maximum of five characters:</p>
 309
 310 <dl><dd><pre> Pmw.EntryField(validate = {'max' : 5})</pre></dd></dl>
 311
 312 <p>    The validator functions for each of the standard validators can
 313     be accessed as:</p>
 314 <dl><dd><pre> Pmw.numericvalidator
 315  Pmw.integervalidator
 316  Pmw.hexadecimalvalidator
 317  Pmw.realvalidator
 318  Pmw.alphabeticvalidator
 319  Pmw.alphanumericvalidator
 320  Pmw.timevalidator
 321  Pmw.datevalidator</pre></dd></dl>
 322
 323
 324 <p>    Whenever the <strong>validate</strong> option is configured, the text currently
 325     displayed in the entry widget is revalidated.  If it is not valid,
 326     the <strong>errorbackground</strong> color is set and the <strong>invalidcommand</strong>
 327     function is called.  However, the displayed text is not modified.</p>
 328
 329 <p>    The default for <strong>validate</strong> is <strong>None</strong>.</p>
 330
 331
 332
 333 </dd></dl>
 334 <a name=option.value></a>
 335 <dl><dt> <strong>value
 336 </strong></dt><dd>
 337 Initialisation option. Specifies the initial contents of the entry.
 338     If this text is invalid, it will be displayed with the
 339     <strong>errorbackground</strong> color and the <strong>invalidcommand</strong> function will be called.
 340     If both <strong>value</strong> and <strong>entry_textvariable</strong> options are specified in
 341     the constructor, <strong>value</strong> will take precedence. The default is <strong>''</strong>.</p>
 342
 343
 344 </dd></dl>
 345 </dd>
 346 <dt> <h3>Components</h3></dt><dd>
 347 Components created by this megawidget and its base
 348 classes are described below.<p></p>
 349 <a name=component.entry></a>
 350 <dl><dt> <strong>entry
 351 </strong></dt><dd>
 352 The widget where the user may enter text.  Long text may be
 353     scrolled horizontally by dragging with the middle mouse button. By default, this component is a Tkinter.Entry.</p>
 354
 355
 356 </dd></dl>
 357 <a name=component.hull></a>
 358 <dl><dt> <strong>hull
 359 </strong></dt><dd>
 360 This acts as the body for the entire megawidget.  Other components
 361     are created as children of the hull to further specialise this
 362     class. By default, this component is a Tkinter.Frame.</p>
 363
 364
 365 </dd></dl>
 366 <a name=component.label></a>
 367 <dl><dt> <strong>label
 368 </strong></dt><dd>
 369 If the <strong>labelpos</strong> option is not <strong>None</strong>, this component is
 370         created as a text label for the megawidget.  See the
 371         <strong>labelpos</strong> option for details.  Note that to set, for example,
 372         the <strong>text</strong> option of the label, you need to use the <strong>label_text</strong>
 373         component option. By default, this component is a Tkinter.Label.</p>
 374
 375
 376 </dd></dl>
 377 </dd>
 378 <a name=methods></a>
 379 <dt> <h3>Methods</h3></dt><dd>
 380 Only methods specific to this megawidget are described below.
 381 For a description of its inherited methods, see the
 382 manual for its base class
 383 <strong><a href="MegaWidget.html#methods">Pmw.MegaWidget</a></strong>.
 384 In addition, methods from the
 385 <strong>Tkinter.Entry</strong> class
 386 are forwarded by this megawidget to the
 387 <strong>entry</strong> component.
 388 <p></p>
 389 <a name=method.checkentry></a>
 390 <dl><dt> <strong>checkentry</strong>()</dt><dd>
 391 Check the validity of the current contents of the entry widget
 392     and return the result.
 393     If the text is not valid, set the background to <strong>errorbackground</strong> and
 394     call the <strong>invalidcommand</strong> function.  If there is a variable
 395     specified by the <strong>entry_textvariable</strong> option, this method should be
 396     called after the <code>set()</code> method of the variable is called.  If this
 397     is not done in this case, the entry widget background will not be
 398     set correctly.</p>
 399
 400
 401 </dd></dl>
 402 <a name=method.clear></a>
 403 <dl><dt> <strong>clear</strong>()</dt><dd>
 404 Remove all text from the entry widget.  Equivalent to <code>setentry('')</code>.</p>
 405
 406
 407 </dd></dl>
 408 <a name=method.getvalue></a>
 409 <dl><dt> <strong>getvalue</strong>()</dt><dd>
 410 Return the text displayed by the entry.</p>
 411
 412
 413 </dd></dl>
 414 <a name=method.invoke></a>
 415 <dl><dt> <strong>invoke</strong>()</dt><dd>
 416 Invoke the command specified by the <strong>command</strong> option as if the
 417     <strong>&lt;Return&gt;</strong> key had been pressed and return the result.</p>
 418
 419
 420 </dd></dl>
 421 <a name=method.setentry></a>
 422 <dl><dt> <strong>setentry</strong>(<em>text</em>)</dt><dd>
 423 Same as <code>setvalue()</code> method.</p>
 424
 425
 426 </dd></dl>
 427 <a name=method.setvalue></a>
 428 <dl><dt> <strong>setvalue</strong>(<em>text</em>)</dt><dd>
 429 Set the contents of the entry widget to <em>text</em> and carry out
 430     validation as if the text had been entered by the user.  If the
 431     text is invalid, the entry widget will not be changed and the
 432     <strong>invalidcommand</strong> function will be called.  Return the validity
 433     of <em>text</em>.</p>
 434
 435
 436 </dd></dl>
 437 <a name=method.valid></a>
 438 <dl><dt> <strong>valid</strong>()</dt><dd>
 439 Return true if the contents of the entry widget are valid.</p>
 440
 441
 442 </dd></dl>
 443 </dd>
 444 <dt> <h3>Example</h3></dt><dd>
 445 The image at the top of this manual is a snapshot
 446 of the window (or part of the window) produced
 447 by the following code.<p></p>
 448 <pre>
 449 class Demo:
 450     def __init__(self, parent):
 451         # Create and pack the EntryFields.
 452         self._any = Pmw.EntryField(parent,
 453                 labelpos = 'w',
 454                 label_text = 'Any:',
 455                 validate = None,
 456                 command = self.execute)
 457         self._real = Pmw.EntryField(parent,
 458                 labelpos = 'w',
 459                 value = '55.5',
 460                 label_text = 'Real (10.0 to 99.0):',
 461                 validate = {'validator' : 'real',
 462                         'min' : 10, 'max' : 99, 'minstrict' : 0},
 463                 modifiedcommand = self.changed)
 464         self._odd = Pmw.EntryField(parent,
 465                 labelpos = 'w',
 466                 label_text = 'Odd length:',
 467                 validate = self.custom_validate,
 468                 value = 'ABC')
 469         self._date = Pmw.EntryField(parent,
 470                 labelpos = 'w',
 471                 label_text = 'Date (in 2000):',
 472                 value = '2000/2/29',
 473                 validate = {'validator' : 'date',
 474                         'min' : '2000/1/1', 'max' : '2000/12/31',
 475                         'minstrict' : 0, 'maxstrict' : 0,
 476                         'format' : 'ymd'},
 477                 )
 478         now = time.localtime(time.time())
 479         self._date2 = Pmw.EntryField(parent,
 480                 labelpos = 'w',
 481                 label_text = 'Date (d.m.y):',
 482                 value = '%d.%d.%d' % (now[2], now[1], now[0]),
 483                 validate = {'validator' : 'date',
 484                         'format' : 'dmy', 'separator' : '.'},
 485                 )
 486         self._time = Pmw.EntryField(parent,
 487                 labelpos = 'w',
 488                 label_text = 'Time (24hr clock):',
 489                 value = '8:00:00',
 490                 validate = {'validator' : 'time',
 491                         'min' : '00:00:00', 'max' : '23:59:59',
 492                         'minstrict' : 0, 'maxstrict' : 0},
 493                 )
 494         self._comma = Pmw.EntryField(parent,
 495                 labelpos = 'w',
 496                 label_text = 'Real (with comma):',
 497                 value = '123,456',
 498                 validate = {'validator' : 'real', 'separator' : ','},
 499                 )
 500
 501         entries = (self._any, self._real, self._odd, self._date, self._date2,
 502                 self._time, self._comma)
 503
 504         for entry in entries:
 505             entry.pack(fill='x', expand=1, padx=10, pady=5)
 506         Pmw.alignlabels(entries)
 507
 508         self._any.component('entry').focus_set()
 509
 510     def changed(self):
 511         print 'Text changed, value is', self._real.getvalue()
 512
 513     def execute(self):
 514         print 'Return pressed, value is', self._any.getvalue()
 515
 516     # This implements a custom validation routine.  It simply checks
 517     # if the string is of odd length.
 518     def custom_validate(self, text):
 519         print 'text:', text
 520         if len(text) % 2 == 0:
 521           return -1
 522         else:
 523           return 1
 524
 525 </pre>
 526 </dd>
 527 </dl>
 528
 529     <center><P ALIGN="CENTER">
 530     <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5>
 531     </p></center>
 532
 533
 534     <font size=-1>
 535     <center><P ALIGN="CENTER">
 536     Pmw 1.2 -
 537      5 Aug 2003
 538      - <a href="index.html">Home</a>
 539     <br>Manual page last reviewed: 22 May 1998
 540     </p></center>
 541     </font>
 542
 543     </body>
 544     </html>
 545