| Programmer's Guide |
|
|
|
| Example Sessions | Beispielsessions
|
| This sessions are intended to be taken in interactive Python. The following code is always assumed to be executed beforehand:
| Diese Sessions sind als interaktive Python-Sitzungen gemeint. Der folgende Code wird stets als vorher ausgeführt verstanden:
>>> import Tkinter
>>> import ventry
>>> tk = Tkinter.Tk() |
| VEntries must be
initialised after creation. This reason is explained in Sect.
Concepts below. The following code must be executed in order to make the
VEntry entry created during the session working:
| VEntries müssen nach Erzeugung
initialisiert werden. Der Grund ist in Abschn.
Konzepte weiter unten erklärt. Der folgende Code muß in der Session ausgeführt werden, um das erzeugte
VEntry entry arbeitsfähig zu machen:
>>> entry.initialise() |
| Non-validating Entry | Nicht-validierendes Eingabefeld |
| There is no sense to use
ventry for this purpose, but it is the simplest example around:
| Es ist nicht sinnvoll
ventry für diesen Zweck zu benutzen, aber es ist das einfachstmögliche Beispiel:
>>> entry = ventry.VEntry(tk)
>>> entry.pack() 
|
| To retrieve the input value, use:
| Um den eingegebenen Wert zu erhalten, benutze man:
>>> value = entry.get() |
| This returns the
essential value put in, i.e., not the internal string, but a converted value. For the entry here, it's just a string. But when using other converters, the return value will be a conversion of the string.
| Dies gibt den
tatsächlichen eingegebenen Wert zurück, d.h. nicht den internen String, sondern einen konvertierten Wert. Für das Eingabefeld hier wird es schlicht ein String sein. Doch wenn andere Konverter benutzt werden, wird der Rückgabewert eine Konversion des Strings sein.
|
| To set the value of the entry to some value, call the
.set() function:
| Um den Wert des Entries auf einen bestimmten Wert zu setzen, rufen Sie die
.set()-Funktion auf:
>>> entry.set(1)
True 
|
| The return value is
True, when the value could be verified,
False otherwise. The
value of the
VEntry will be changed only, if the value given could be verified. The
string of the entry will always be set to the formatted value supplied, maybe leaving the
VEntry in an state with invalid input (orange background).
| Der Rückgabewert ist
True, wenn der Wert verifiziert werden konnte, andernfalls
False. Der
Wert des
VEntry's wird nur geändert werden, wenn der Wert verifiziert werden konnte. Der
String des Eingabefeldes wird immer auf den formatierten gegebenen Wert gesetzt werden, u.U. das
VEntry in einem Zustand mit ungültiger Eingabe (oranger Hintergrund) hinterlassend.
|
| To withdraw the
VEntry from the screen, use one of the following calls:
| Um das
VEntry vom Bildschirm wegzunehmen, benutze man einen der folgenden Aufrufe:
>>> entry.pack_forget()
>>> entry.grid_forget()
>>> entry.destroy() |
| Integer Entry | Ganzzahlen-Eingabefeld |
| This
VEentry will accept all input which is
eval's as an
int or
long. Note that a valid initial value
must be supplied:
| Dieses
VEntry wird jede Eingabe akzeptieren, welche als ein
int oder
long eval'ed. Beachten Sie daß ein gültiger Initialwert mitgegeben werden
muß:
>>> entry = ventry.VEntry(tk, validate=ventry.int, initial=42)
>>> entry.pack() 
|
| The following validators are currently available (I coded only what I needed):
- ventry.number accepts all numbers, irrespective of what type (int, long or float).
- ventry.int accepts int and long integers. This means, you can type in also "1234L" or "5678l" (with small L).
- ventry.string accepts everything.
- ventry.number_none is suitable for input of either a number or "None" to signal missing input number. However, the input "" is not allowed.
Validators are at the same time the converters of the
VEntry. I.e., a validator
string makes sense, as it converts to string output, equivalently to the number output of
number. The converted value can be retrieved by:
| Die folgenden Validatoren sind im Moment verfügar (Ich habe nur kodiert, was ich brauchte):
- ventry.number akzeptiert alle Zahlen, unabhängig von ihrem Typ (int, long oder float).
- ventry.int akzeptiert int und long Integers. Daß heißt, Sie können "1234L" oder "5678l" (mit kleinem L) eingeben.
- ventry.string akzeptiert alles.
- ventry.number_none ist geeignet zur Eingabe entweder einer Zahl oder von "None", um eine fehlende Zahl zu signalisieren. Nichtsdestotrotz ist die Eingabe "" nicht erlaubt.
Validatoren sind gleichzeitig auch die Konverter des
VEntry's. D.h., daß ein Validator
string sinnvoll ist, da er nach String-Output konvertiert, äquivalent zur Zahlenausgabe von
number. Der konvertierte Wert kann abgerufen werden durch:
>>> entry.get()
42 |
| For this entry, the return value is cast to an int, namely, 42.
The initial value is specified by the
initial argument. The given value will be converted to a display string by the
formatter of the
VEntry. There is an example session dedicated to formatters below. Here, it can be said that the task of the formatter is, at its name says, to format values to strings if the
VEntry is set to some value. More important, arbitrary values can be specified as the
initial value, as long as they are
valid values. The default formatter,
str, can format any value.
Formatter and
converter are different. Only the converter decides, which strings are valid input and which are not. Thus not all values formattable by the formatter must necessarily be valid.
| Für dieses Eingabefeld wird der Rückgabewert in ein Int konvertiert, nämlich 42.
Der anfängliche Wert wird mit dem
initial-Argument spezifiziert. Der angegebene Wert wird durch den
Formatierer des
VEntries zu einem Anzeigestring konvertiert. Unten ist eine den Formatierern gewidmete Beispielsession zu finden. Hier kann gesagt werden, daß es die Aufgabe eines Formatierers ist, wie sein Name sagt, Werte zu Strings zu formatieren, wenn das
VEntry auf einen bestimmten Wert gesetzt wird. Wichtiger ist, daß beliebige Werte als
initial-Argument angegeben werden können, so lange sie
gültige Werte sind. Der Default-Formatierer,
str, kann alle Werte formatieren.
Formatierer und
Konverter sind verschieden. Nur der Konverter entscheidet, welche Strings gültige Eingabe sind und welche nicht. daher müssen nicht alle Werte, die durch den Formatierer formatiert werden können, gültige sein.
|
| Formatters | Formatierer |
| Let's assume that we have some formatting function:
| Angenommen wir haben eine bestimmte Formatierungsfunktion:
>>> def eformatter(number):
... return '%.3e' % number |
| Then this function can be used in order to format values the VEntry is set to, via the
formatter constructor argument:
| Dann kann diese Funktion mit dem
formatter-Konstruktorargument dazu benutzt werden, um Werte, auf die das VEntry gesetzt wird, zu formatieren:
>>> entry = ventry.VEntry(tk, initial=82.7, formatter=eformatter)
>>> entry.pack() 
|
| A callable object can be used as a formatter, if it returns
always strings, and accepts call with one argument.
| Ein rufbares Objekt kann als Formatierer benutzt werden, wenn es
stets Strings zurückliefert, und Aufruf mit einem Argument akzeptiert.
|
| Named VEntries | Benannte VEntries |
| Named VEntries are derived from
VEntry. The constructor and the
.grid() methods are overwritten, and the
.pack() methods become unavailable.
.set() and
.get() can be used as before.
Named VEntries are placed by
.grid() call and consome two cells, one for the label and one for the entry. The alignment can be either horizontal or vertical. To create an horizonally aligned grid of two entries, execute:
| Benannte VEntries sind von
VEntry abgeleitet. Der Konstruktor und die
.grid()-Methoden sind überschrieben, und die
.pack()-Methoden sind nicht länger verfügbar.
.set() und
.get() können wie zuvor benutzt werden.
Named VEntries werden durch
.grid() plaziert und verbrauchen zwei Zellen, eine für das Label und eine für das Eingabefeld. Die Ausrichtung kann entweder horizontal oder vertikal sein. Um ein Gitter aus zwei Eingabefeldern zu erzeugen, führe man aus:
>>> entry1 = ventry.NamedVEntry(tk, column=0, row=0, name='A Name:')
>>> entry2 = ventry.NamedVEntry(tk, name='Another Name:')
>>> entry2.grid(column=0, row=1) 
|
| In the first case, the
NamedVEntry is
.grid()'ed automatically. In the second case, it is placed manually after creation.
| Im ersten Fall wird das
NamedVEntry automatisch ge
grid()'ed. Im zweiten Fall wird es nach Erzeugung manuell plaziert.
|
| To create two labeles entries side by side, use:
| Um zwei beschriftete Eingabefelder Seite an Seite zu erzeugen, benutze man:
>>> entry1 = ventry.NamedVEntry(tk, column=0, row=0, mode='vertical', name='An Entry:')
>>> entry2 = ventry.NamedVEntry(tk, column=1, row=0, mode='vertical', name='Another Entry:') 
|
| The
mode for horizontal alignment is
'horizontal'.
| Der
mode für horizontale Ausrichtung ist
'horizontal'.
|
| Callbacks | Rückrufe |
| The entry can perform callbacks on any value change. The first callback will be done at initialisation time, therefore the initialisation is separated from the creation. All subsequent calls will occur on user input, and by default also on
.set() call, but this can be inhibited explicitly.
| Das Eingabefeld kann Rückrufe bei jeder Wertänderung durchführen. Der erste Rückruf wird zum Initialisationszeitpunkt durchgeführt, weshalb Initialisation und Erzeugung voneinander getrennt sind. Alle nachfolgenden Aufrufe werden bei Nutzerinput auftreten, und per Default auch bei
.set()-Aufruf, aber dies kann explizit verhindert werden.
|
| First, we need the callback function itself:
| Zunächst benötigen wir die Rückruf-Funktion selbst:
>>> def callback():
... print "Current value =", entry.get() |
| The callback function must be callable without arguments, and its return value is meaningless. When the value is changed by the user via input or by the program via
.set(), the callback function will be called and will output in this example the current value of the entry.
Note, that here
entry is not defined when it is already coded. As Python is an interpreter language, the body of the function will be executed on function call, thus this is valid. It is usual to do so. In classes, one will code statements which refer to
self.entry without
entry being defined when the code is written, but being defined in local scope on execution of the code.
Now let's define the
VEntry with callback to
callback:
| Die Rückruf-Funktion muß ohne Argumente rufbar sein, und ihr Rückgabewert ist bedeutungslos. Wenn der Wert durch den Nutzer via Input oder durch das Programm via
.set() geändert wird, so wird die Rückruffunktion aufgerufen werden und wird in diesem Beispiel den aktuellen Wert des Eingabefeldes ausgeben.
Man beachte, daß hier
entry nicht definiert ist, wenn es bereits kodiert wird. Da Python eine Interpretersprache ist, wird der Körper der Funktion erst dann ausgeführt werden, wenn die Funktion aufgerufen wird, also ist dies gültig. Es ist üblich dies zu tun. In Klassen wird man Statements, welche auf
self.entry Bezug nehmen, kodieren, ohne daß
entry definiert ist, wenn der Code geschrieben wird, aber so daß es im local Scope definiert ist, wenn der Code ausgeführt wird.
Lassen Sie uns nun das
VEntry mit Rückruf von
callback definieren:
>>> entry = ventry.VEntry(tk, hook_update = callback)
>>> entry.pack() |
| That's all. For
NamedVEntries, it's completely the same. The callback will be executed on initialisation time, on value change and on
.set(), if to
.set() is not passed the argument
callback as
False. Passing
False to
.set() is intended to break infinite callback circles.
| Das ist alles. Für
NamedVEntries ist es völlig dasselbe. Der Rückruf wird zum Initialisierungszeitpunkt, bei Wertänderung und bei
.set()-Aufruf ausgeführt werden, beim
.set()-Aufruf ausschließlich, wenn nicht
False als
callback-Argument übergeben wird. Die Übergabe von
False an
.set() ist dazu gedacht, um unendliche Rückrufkreise zu durchbrechen.
>>> entry.set(2, callback = False) |
| If callback at initialisation time is not intended, one can use the following code:
| Wenn Rückruf zum Initialisierungszeitpunkt unerwünscht ist, kann man folgenden Code verwenden:
>>> entry.initialise(callback = False) |
| Advanced Options | Fortgeschrittene Optionen |
| You can supply arbitrary
Tkinter.Entry initialisation arguments to the constructor of
VEntry. Example:
| Sie können dem
VEntry-Konstruktor beliebige
Tkinter.Entry-Initialiserungs-Argumente übergeben. Beispiel:
>>> entry = ventry.VEntry(tk, width = 3)
>>> entry.pack() 
|
| For the
NamedVEntry, you can even specify what kind of
label to use, i.e, you can pass in your own widgets:
| Für das
NamedVEntry können Sie sogar bestimmen, welche Art von
Label benutzt werden soll, d.h., Sie können Ihre eigenen Widgets übergeben:
>>> radio = Tkinter.Radiobutton(tk, text = 'An Option:')
>>> entry = ventry.NamedVEntry(tk, column = 0, row = 0, label = radio) 
|
| Note that this case is the only one where you can leave out
name for
NamedVEntry.
| Beachten Sie daß dies der einzige Fall ist, in dem Sie
name für das
NamedVEntry weglassen können.
|
| Concepts | Konzepte |
| The Value of the VEntry | Der Wert des VEntries |
| Because in VEntries, also invalid input is permitted, the value must be stored independently from the input string and cannot be retrieved directly from the string at any time.
The value is therefore updated everytimes valid input occurs, and code retrieving the value in invalid input state, will see the last valid input.
| Da in VEntries auch ungültige Eingaben erlaubt sind, muß der Wert unabhängig von Eingabestring gespeichert werden, und kann nicht jederzeit direkt von String abgeleitet werden.
Der Wert wird daher jedesmal, wenn gültige Eingabe auftritt, erneuert, und Code, welcher den Wert im ungültigen Eingabezustand abruft, wird die letzte gültige Eingabe sehen.
|
| Initialisation of the VEntry | Initialisierung des VEntries |
| Here the concept is, that the VEntry must be operational according to its validator type from initialisation time on. I.e., it must deliver valid values. E.g., a VEntry of int type always has to have integer value. Thus, a valid initialisation value is necessary. Also, it is straightforward to raise an exception on invalid initialisation values.
| Hier ist das Konzept, daß das VEntry vom Initialisierungszeitpunkt an betriebsfähig entsprechend seinem Validator sein muß. D.h., es muß gültige Werte liefern. Ein VEntry von int-Typ z.B. muß Integer-Wert haben. Daher ist ein gültiger Initialisierungswert notwendig. Es ist auch straightforward, bei ungültigen Initialisierungswerten eine Ausnahme zu werfen.
|
| Conversion of Input String and Validity | Konvertierung des Eingabestrings und Gültigkeit |
| Because validation and conversion occurs always bound tigthly together, in ventry both is done by the same function. Therefore this function returns an instance of
Validity, containing both the validity and optionally the converted value of the input string, and is doing both jobs: validation and conversion. Often conversion is done by
eval() call, exception catching and type checking. Thus both tasks can be easily bundled together, avoiding double checking and overhead.
| Da Validierung und Konvertierung immer eng beieinander liegen, wird in ventry beides von derselben Funktion erledigt. Daher gibt diese Funktion eine Instanz von
Validity zurück, welche sowohl die Gültigkeit als auch optional den konvertierten Wert enthält. Oft wird Konvertierung druch
eval()-Aufruf, Ausnahmenabfang und Typprüfung erreicht. Daher können beide Aufgaben leicht gebündelt werden, was doppelte Prüfung und Overhead vermeidet.
|
| Setting of the Value | Setzen des Werts
|
| The conversion of a value to a corresponding input string is ambiguous. It creates programming overhead, to put the conversion code outside of ventry, as usually the conversion is unique for a single VEntry instance, and does not change between calls from different parts of the surrounding program. Thus, the
formatter is introduced as a function formatting arbitrary values to input strings to be set in the entry field. This function is independent of the validation concept, and serves only for the single purpose, to format values. After having done its job, the resulting string will be due to validation again, and the procedure is, to treat the formatted string retrieved from the formatter the same way as user input is treated. The string will be feed to the validator in order to obtain the new value and state, and the original value given to the formatter itself is not used thereby.
| Die Konvertierung eines Wertes zu einem zugehörigen Eingabestring ist uneindeutig. Den Konvertierungscode außerhalb von ventry zu plazieren, erzeugt Programmier-Overhead, da gewöhnlicherweise die Konvertierung für eine einzelne VEntry-Instanz eindeutig ist, und sich zwischen verschiedenen Aufrufen aus dem umgebenden Programm nicht ändert. Daher wird der
Formatter als eine Funktion eingeführt, welche beliebige Werte zu Eingabestrings konvertiert, welche im Eingabefeld gesetzt werden können. Diese Funktion ist unabhängig vom Validierungskonzept, und dient allein diesem einzigen Zweck, Werte zu formatieren. Nachdem sie ihre Arbeit getan hat, wird der resultierende String der Validierung unterzogen, und das Vorgehen ist, den vom Formatierer erhaltenen formatierten String genauso zu behandeln wie Nutzerinput behandelt wird. Der String wird dem Validator zugeführt werden um den neuen Wert und Zustand zu erhalten, und der Originalwert selbst, welcher dem Formatierer übergeben wurde, wird dabei nicht benutzt.
Maintained since: 8/09
$Last changed: 9/09$