####################################################################################
####                           input Version 1.24 
####              Eingabemaske fr Benutzereingaben in Scripten
####                                
####              Das New-Tuxwetter-Team: SnowHead und Worschter
####################################################################################

Was ist input?
----------------------------------
Input ist ein Editor, welcher aus Scripten heraus aufgerufen werden kann, und das Ergeb-
nis der Eingaben durch den Nutzer ber die Kommandozeile an das Script zurckgibt.
Dabei ist beim Aufruf sowohl die Festlegung des Aussehens der Eingabemaske als auch des
Typs der zu editierenden Daten mglich. Die zu editierenden Felder knnen bei Bedarf
auch mit Defaultwerten vorbelegt werden.

Installation
----------------------------------
Es wird nur die Datei "input" bentigt. Abhngig vom Image-Typ ist diese entweder in
/bin/ (bei JFFS-Only) oder /var/bin/ (bei CRAMFS und SQUASHFS) zu kopieren und mit den
Rechten 755 zu versehen. Nun kann sie aus eigenen Scripten heraus verwendet werden. Eine
spezielle Busybox ist fr die Verwendung von "input" nicht erforderlich.


Anwendung
----------------------------------
Der Aufruf der Eingabemaske erfolgt ber die Ausfhrung von "input" mit entsprechenden Kom-
mandozeilenparametern. Wichtig dabei ist, da das aufrufende Script ber die Plugin-Verwal-
tung von Neutrino gestartet wurde, und in der .cfg des Scriptes die Eintrge "needfb=1" und
"needrc=1" stehen. Anderenfalls wrde Neutrino parallel zum Editor auf die Tastendrcke der
Fernbedienung reagieren. Beim Aufruf aus dem FlexMen ist das Script mit den Zeichen "&" oder
"" vor dem Anzeigenamen aufzurufen. Im Folgenden werden die mglichen Parameter beschrieben.
Die Aufrufzeile sieht so aus:

input l='Layout' [t='Title'] [d='Default'] [k=Keys] [f=Frames] [c=Columns] [o=Timeout] [m=Mask] [h=BreakOnHelp]

Layout:
Der Layoutstring, welcher festlegt, welche Felder an welcher Stelle und in welchem Format
editierbar sein sollen. Eingabefelder werden durch "#" fr reine Zifferneingaben und "@"
fr alphanumerische Eingaben definiert. Alle anderen Zeichen werden auf dem Bildschirm zwar
dargestellt, sind aber nicht editierbar.
In einer Zeile knnen maximal 25 Zeichen dargestellt werden. Ist der Layoutstring lnger als
der Parameter "c" oder lnger als 25 Zeichen, werden die nchsten Zeichen auf einer weiteren 
Zeile dargestellt. Damit ist die Darstellunge mehrzeiliger Eingabemasken mglich.

Title:
Die berschrift des Editorfensters. Wird dieser Parameter nicht bergeben, wird standardmig
der Text "Eingabe" verwendet.

Default:
Die Editorfelder knnen vorbelegt werden. Dabei werden die Zeichen des Defaultstrings der
Reihe nach den Eingabefeldern zugewiesen. Der Defaulstring enthlt also keine Fllzeichen
wie der Formatstring sondern nur die reinen Daten.

Keys:
Dieser Parameter kann 0 oder 1 sein. Bei 1 wird im Editorfenster die Tastenbelegung fr die
Eingabe von alphanumerischen Zeichen zustzlich mit angezeigt. Mit 0 wird diese Anzeige un-
terdrckt. Defaultwert ist 0.

Frames:
Dieser Parameter kann 0 oder 1 sein. Bei 1 werden Rahmen um die Eingabefelder gezeichnet, 
bei 0 werden diese Felder ohne Rahmen dargestellt. Defaultwert ist 1.

Columns:
Mit diesem Parameter wird die Anzahl der Zeichen pro Zeile festgelegt. Somit knnen auch
schmalere Fenster mehrzeilig dargestellt werden. Zulssig sind Werte von 1 bis 25.
Defaultwert ist 25.

Timeout:
Gerade fr PIN-Abfragen kann dieser Parameter verwendet werden. Er legt die Zeit fest, nach
welcher der Eingabedialog abgebrochen werden soll, wenn keine Taste gedrckt wurde. Damit
knnen Eingaben automatisch abgebrochen werden, wenn der Nutzer nicht reagiert. Dieser Timeout
wird mit dem ersten Drcken einer Taste unterbrochen, da dann ja ein Nutzer da ist. Das heit
nach dem ersten Drcken einer Taste wird die Eingabe nicht mehr angebrochen, wenn innerhalb der
Timeout-Zeit keine weitere Taste gedrckt wurde. Ein Wert von 0 fr diesen Parameter deaktiviert
den Timeout gnzlich. Defaultwert ist 0.

Mask:
Dieser Parameter kann 0 oder 1 sein. Bei 1 werden in numerischen Eingabefeldern nicht die
eingegebenen Zahlen angezeigt, sondern das Zeichen "*". Das kann fr die verdeckte Eingabe
von PIN-Nummern verwendet werden. Defaultwert ist 0.

BreakOnHelp
Dieser Parameter kann 0 oder 1 sein. Bei 1 wird in Anlehnung an des LCD-Men bei Drcken der
"?"-Taste die Eingabe abgebrochen und statt des Ergebnisstrings das Zeichen "?" zurckgeliefert. 
Das kann z.B. bei der PIN-Eingabe vom Script als Aufforderung ausgewertet werden, da der User 
die PIN ndern mchte. Defaultwert ist 0.

Rckgabewert:
input gibt die editierten Felder wieder ohne Fllzeichen ber die Kommandozeile zurck. Dieser 
Datenstring kann dann vom Script ausgewertet werden. Dabei ist zu beachten, da die Kommandozeile
mehrfache Leerzeichen zusammenfasst. Also wrde ein Text "X      X" als "X X" beim Script ankom-
men. Das ist leider kommandozeilenbedingt und nicht zu verhindern.

Bedienung
----------------------------------
Mittels der Links-/Rechts-Tasten kann zwischen den einzelnen Eingabefeldern gewechselt werden.
Bei mehrzeiligen Eingabemasken kann mittels der Hoch-/Runter-Tasten auch zwischen den Zeilen
gewechselt werden.
Bei numerischen Eingabefeldern wird die Ziffer bei Druck auf eine Zifferntaste bernommen und
sofort zum nchsten Eingabefeld gewechselt. Bei alphanumerischen Feldern kann wie beim Handy
durch mehrfachen Druck der selben Taste durch die mglichen Buchstaben, Ziffern und Sonderzei-
chen geblttert werden. Der Druck auf eine andere als die bisher gedrckte Taste wird sofort
zum nchsten Feld gewechselt und der neue Wert dort bernommen. Wird in einem alphanumerischen
Feld nach Drcken einer Taste fr 3 Sekunden keine weitere Taste bettigt, geht der Editor au-
tomatisch zum nchsten Eingabefeld. Damit ist die Eingabe zweier gleicher Buchstaben hinterein-
ander mglich, ohne erst die Cursortasten benutzen zu mssen.
Die rote Taste schaltet in alphanumerischen Eingabefeldern zwischen Gro- und Kleinschreibung
um. Die gelbe Taste lscht alle Eingabefelder.
Mit der Volume-Plus-Taste wird an der aktuellen Kursorposition ein Zeichen eingefgt. Der Rest
des Eingabefeldes rckt nach rechts. Das letzte Zeichen des Feldes verschwindet.
Mit der Volume-Minus-Taste wird das Zeichen an der aktuellen Kursorposition gelscht. Der Rest
des Eingabefeldes rckt nach links.
Mit "OK" werden die nderungen bernommen und der Editor geschlossen. Die "HOME"-Taste bricht
den Vorgang ab, beendet den Editor und liefert einen Leerstring an das Script zurck.
Wenn mit dem Parameter "h=1" erlaubt, wird die Bearbeitung bei Drcken der "?"-Taste abgebrochen
und statt des Ergebnisstrings ein "?" zurckgegeben.

Beispiele
----------------------------------
Das Bild "small.png" ist ein Screenshot des Aufrufes:

  input l="####" t="PIN"

Der Editor wrde bei Eingabe von "1234" auch "1234" ber die Kommandozeile zurckliefern.
Um diesen Wert einer Variablen zuzuordnen ( in diesem Fall "$pin", sollte der Aufruf so aussehen:

  pin=`input l="####" t="PIN"`
  
Nun kann $pin wie gewohnt ausgewertet werden. Aber darauf achten: Bricht der User mit der "HOME"-
Taste ab, ist $pin leer.

Das Bild "big.png" ergibt sich mit folgendem Aufruf:

  input l='Date: ##.##.####Time: ##:##:##' t='Datum und Uhrzeit ~andern' d='27022005164523' c=16 k=1
  
Der Rckgabewert bei Drcken der "OK"-Taste wrde so aussehen: "27022005164523"


Sonderzeichen ber die Kommandozeile
------------------------------------
Da Linux keine bergabe von Sonder- und Steuerzeichen ber die Kommandozeile untersttzt, knnen
die wichtigsten Sonderzeichen ber die Nutzung des Formatsteuerzeichens sowohl aus Scripten als
auch von der Kommandozeile dargestellt werden. Aktuell werden folgende Sonder- und Steuerzeichen
untersttzt:

  ~a    
  ~o    
  ~u    
  ~A    
  ~O    
  ~U    
  ~z    
  ~d     (degree)
  
Diese Steuerzeichen werden sowohl beim Titel, dem Format als auch dem Defaultstring ausgewertet.
Auch der Rckgabestring enthlt die Umlaute als Steuerzeichen. Damit ist im Script ein leichteres
Ersetzen der Umlaute bei der Auswertung mglich.

  
Wird "input" mit falschen oder vllig ohne Parameter aufgerufen, wird im Log eine Liste der
untersttzten Parameter ausgegeben.


Also, viel Spa und viel Erfolg

Das New-Tuxwetter-Team
SnowHead und Worschter