ValidatedEntry.py
Provides ValidatedEntry, a subclass of gtk.Entry which validates
input.
Usage: create an instance of ValidatedEntry, specifying the function
to validate input. E.g.:
: def money(text):
: "validate input to be monetary value"
: ...
:
: money_entry = ValidatedEntry(money)
Validation functions must accept one argument, the text to be
validated, and must return one of:
1: the input is valid.
0: the input is invalid and should not be displayed.
-1: the input is partially valid and will be displayed (and by
default with a different background color).
Three module-level variables are defined for the convenience of
validation function writers: VALID (1), INVALID (0), PARTIAL (-1).
There is one public method, isvalid(), which will return True if the
current text is valid.
Note: care should be taken when implementing validation functions to
allow empty strings to be VALID or at least PARTIAL. An empty string
should never be INVALID.
Note: the hooks for calling the validation function are implemented by
connecting the object to handlers for the gtk.Editable "insert-text"
and "delete-text" signals. These handlers are connected to instances
in the constructor, so will, by default, be called before other
handlers connected to the widgets for "*-text" signals. When input is
INVALID, stop_emission() is called, so later handlers for "*-text"
signals will not be called.
See the doc string for ValidatedEntry.__init__ for more details.
| Class | ValidatedEntry | No class docstring; 4/5 methods documented |
| Function | v_nonemptystring | VALID: non-empty string after stripping whitespace |
| Function | v_int | VALID: any postive or negative integer |
| Function | v_float | VALID: any postive or negative floating point |
| Function | v_phone | VALID: any phone number of the form: \+?345656343456. |
| Function | v_ip | Undocumented |
| Function | v_ucs2_name | Undocumented |
| Function | empty_valid | empty_valid is a factory function returning a validation function. |
| Function | bounded | bounded is a factory function returning a validation function |
empty_valid is a factory function returning a validation function.
All of the validation functions in this module return PARTIAL for
empty strings which, in effect, forces non-empty input. There may
be a case where, e.g., you want money input to be optional, but
v_money will not consider empty input VALID. Instead of writing
another validation function you can instead use empty_valid(). By
wrapping a validation function with empty_valid(), input (after
stripping), if empty, will be considered VALID. E.g.:
ventry = ValidatedEntry(empty_valid(v_money))
It is recommended that all your validation functions treat empty
input as PARTIAL, for consistency across all validation functions
and for use with empty_valid().
bounded is a factory function returning a validation function
providing bounded input. E.g., you may want an entry that accepts
integers, but within a range, say, a score on a test graded in
whole numbers from 0 to 100:
score_entry = ValidatedEntry(bounded(v_int, int, 0, 100))
Arguments:
vfunc: A validation function.
conv: A callable that accepts a string argument (the text in
the entry) and returns a value to be compared to minv
and maxv.
minv: None or a value of the same type returned by conv. If
None, there is no minimum value enforced. If a value,
it will be the minimum value considered VALID.
maxv: None or a value of the same type returned by conv. If
None, there is no maximum value enforced. If a value,
it will be the maximum value considered VALID.
One or both of minv/maxv must be specified.
The function returned will call vfunc on entry input and if vfunc
returns VALID, the input will be converted by conv and compared to
minv/maxv. If the converted value is within the bounds of
minv/maxv then VALID will be returned, else PARTIAL will be
returned.