####################################################################################
####                        MsgBox Version 1.62  
####                 Messagebox zum Info-Anzeige aus Scripten
####                                
####              Das New-Tuxwetter-Team: SnowHead und Worschter
####################################################################################

Was ist die Messagebox?
----------------------------------
Die MessageBox dient beim Ausfhren von Scripten zur Anzeige von Informationen auf dem
Bildschirm und zur Abfrage von Entscheidungen des Nutzers ber bis zu drei frei beschrift-
bare Tasten. Die Nummer der gedrckten Taste (1..16) oder 0 bei Timeout ohne gedrckte
Taste wird als Returnwert zurckgegeben und kann vom Script ber die Variable "$?" ausge-
wertet werden.


Installation
----------------------------------
Es wird nur die Datei "msgbox" 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 "msgbox" nicht erforderlich.


Anwendung
----------------------------------
Der Aufruf der MessageBox erfolgt ber die Ausfhrung von "msgbox" mit entsprechenden Pa-
rametern. Im Folgenden werden nun die mglichen Parameter beschrieben.
Das wichtigste ist natrlich der anzuzeigende Text. Dieser kann entweder ber die Kommando-
zeile oder aus einer Datei bergeben werden. Die Art der Textanzeige (Message oder Popup)
wird ber die Schlsselwrter "msg=" fr Message und "popup=" fr Popup festgelegt.
Um nun einen Text von der Kommandozeile als Popup anzuzeigen, erfolgt der Aufruf in dieser
Form:

  msgbox popup="Auszugebender Text"
  
fr eine Message entsprechend:

  msgbox msg="Auszugebender Text"
  
Der Text mu dabei in Hochkommas stehen. Soll der anzuzeigende Text aus einer Datei ausgele-
sen werden, mu der Aufruf fr ein Popup

  msgbox popup=Dateiname
  
und fr eine Message

  msgbox msg=Dateiname
  
lauten. Die Erkennung, da es sich um eine Datei handelt, erfolgt am Zeichen "/" am Anfang des
Dateinamens. Dieser Dateiname kann in Hochkommas gesetzt werden, es ist aber nicht zwingend er-
forderlich.
Wird ein Text als Message angezeigt, ist das an dem OK-Button am unteren Fensterrand erkennbar.
Bei einem Popup wird dieser Button nicht angezeigt. Beide Anzeigearten lassen sich jedoch durch
Bettigen der Tasten "HOME" oder "OK" auf der Fernbedienung schlieen.

Das Verhalten der Messagebox kann ber einige zutzliche Parameter gesteuert werden:

  title="Fenstertitel"
  
Der in Hochkommas gestellte Text wird als Titel fr die angezeigte Box verwendet. Wird die-
ser Parameter nicht angegeben, verwendet das msgbox den Titel "Information". Um Platz zu spa-
ren kann die Titelzeile auch komplett ausgeschaltet werden. Das geschieht mit dem Parameter
title="none" (Kleinschreibung beachten!).

  size=nn

Die Zahl "nn" wird als Fontgre fr den anzuzeigenden Text verwendet. Je grer diese Zahl 
ist, um so weniger Text pat natrlich auf die volle Bildschirmbreite. Die Fenstergre der 
Box wird dabei automatisch entsprechend der Zeilenlnge und der Zeilenanzahl gesetzt. Ohne
Parameter wird standardmig die Fontgre 36 verwendet.

  timeout=nn
  
Mit diesem Parameter kann festgelegt werden, nach welcher Zeit sich die Box von selbst wieder
schlieen soll, wenn sie nicht durch einen Tastendruck auf der Fernbedienung geschlossen wird.
Ohne Parameter schliet sich die Box bei einer Message nach 5 Minuten und bei einem Popup nach
der Timeoutzeit, welche in den Neutrino-Einstellungen fr die Info-Zeile festgelegt wurde. Diese
Zeit wird durch einen beliebigen tastendruck (auer OK und HOME) neu gestartet.

In der Funktion als MessageBox ("msg=...") knnen bis zu 16 Tasten angezeigt und die Auswahl
des Nutzers abgefragt werden. Anzahl und Beschriftung der Tasten werden ber den Parameter

  select="Label 1[,Label 2[,...]]" 

festgelegt. Dabei knnen 1 bis 16 Tasten mit den entsprechenden Texten (z.B. "Label 1") erzeugt
werden. Die einzelnen Label-Bezeichner knnen von beliebig vielen Kommas angefhrt und auch ge-
folgt werden. Ausgewertet werden nur die nichtleeren Bereiche zwischen zwei Kommas.
Die Breite der Tasten und damit auch des gesamten Fensters richtet sich nach der lngsten Tas-
tenbezeichnung und der Anzahl der Tasten. Ohne Angabe des "select="-Parameters wird eine Taste 
mit dem Label "OK" erzeugt.

Da bei der bergabe aus Scripten fr den Paramter "select=" bei leeren Variablen auch zwei Kom-
mas aufeinanderfolgen knnen, werden solche bergaben normalerweise ignoriert. Also wrden bei
einem Parameter "select=Eintrag1,,Eintrag3" zwei Buttons angezeigt werden. Im Normalfall wrde
bei Auswahl von "Eintrag3" als Rckgabewert "2" bergeben werden. Soll jedoch die Zuordnung zu
den Variablen erhalten bleiben, kann mit dem Parameter

  absolute=1
  
festgelegt werden, da als Rckgabewert die absolute Position des Eintrages in der Select-Liste
zurckgegeben wird. Bei "Eintrag3" wre das also "3". Der Defaultwert fr "absolute" ist "0".

Um die sinnvollste Taste bereits beim Start selektieren zu knnen, kann mit dem Parameter

  default=n
  
die Nummer der Taste (1..16) bergeben werden, welche unmittelbar nach Anzeige der Messagebox
selektiert sein soll und nur noch mit OK besttigt werden braucht. Dabei ist zu beachten, da
bei "absolute=1" auch der Defaultwert absolut abgegeben werden mu.

Um anzugeben, wieviel Tasten in einer Zeile angezeigt werden sollen, wird der Parameter

  order=n
  
bergeben. Sind zum Beispiel 12 Tasten vereinbart und order wird mit 4 angegeben, werden 3 Reihen
zu je vier Tasten erzeugt. Dabei ist jedoch das maximal ausfllbare Bildschirmformat zu berck-
sichtigen. Bei mehreren Zeilen kann zustzlich zu den Links-/Rechts-Tasten mit den Hoch-/Runter-
Tasten zwischen den Zeilen navigiert werden.

Um die gewhlte Taste im Script leichter auswerten zu knnen, kann zustzlich zum oben beschrie-
benen Rckgabewert auch der Text der gewhlten Taste ber die Konsole ausgegeben werden. Das wird
mit dem Parameter

  echo=n
  
geregelt. Ist n=1, wird statt der Versionsmeldung am Programmstart am Ende des Programms der Label
der gewhlten Taste auf der Konsole ausgegeben. In diesem Fall ist die Auswertung des Ergebnisses
abweichend zu der oben beschriebenen Aufrufsyntax statt ber "$?" in der Form

  auswahl=`msgbox .... echo=1`
  
mglich. Der Label der gewhlten Taste kann dann ber $auswahl ausgewertet werden. Bei Timeout oder
Abbruch bleibt $auswahl leer.

ber die Mute-Taste der Fernbedienung kann die MessageBox zeitweilig ausgeblendet werden. Einmal
Drcken der Mute-Taste blendet die Box aus, ein weiterer Druck auf Mute blendet sie wieder ein.

  hide=n
  
Was nach dem Ausblenden der MessageBox angezeigt wird, hngt vom Parameter "hide" ab. Bei 0 wird
der Druck auf die Mute-Taste ignoriert und die Box wird nicht ausgeblendet, bei 1 wird ein gelsch-
ter Bildschirm angezeigt (nur das Fernsehbild ist zu sehen), bei 2 wird der Bildschirminhalt ange-
zeigt, welcher vor dem Start der Messagebox zu sehen war (Mens usw.). Defaultwert ist "1".
Wurde als Textparameter eine Datei bergeben, wird diese vor dem Einblenden neu eingelesen. Somit
werden whrend des Ausblendens in dieser Datei vorgenommene nderungen nach dem Einblenden aktuell
angezeigt. Whrend die Box ausgeblendet ist, werden alle Tastendrcke auer der Mute-Taste ignoriert.
Um aus dem Script heraus berprfen zu knnen, ob die MessageBox ausgeblendet ist, wird von der Mes-
sageBox fr die Zeit, in der sie ausgeblendet ist, die Flagdatei "/tmp/.msgbox_hidden" erzeugt.

Um das Verhalten bei bereits Angezeigten Mens oder Meldungen zu steuern, dient der Parameter

  refresh=n
  
Mit n=0 werden vor dem Start der MessageBox angezeigte Mens oder Infos gelscht (nur die Messa-
geBox ist sichtbar) und beim Beenden der MessageBox der Bildschirm gelscht.
Mit n=1 blendet sich die MessageBox ber bereits angezeigte Infos ein, lscht den Bildschirm beim
Beenden aber komplett.
Mit n=2 werden vor dem Start der MessageBox angezeigte Mens oder Infos gelscht (nur die Messa-
geBox ist sichtbar), die vorher abgezeigten Infos aber beim Beenden der Messagebox wiederhergestellt.
n=3 kombiniert 1 und 2, die MessageBox blendet sich ber vorher angezeigte Infos ein und stellt beim
Beenden den Bildschirmzustand wieder her, welcher vor dem Start der MessageBox aktuell war.
Dieser Parameter kann entfallen, in diesem Fall wird standardmig mit refresh=3 gearbeitet.

Normalerweise wird die MessageBox auf dem Bildschirm seit der Version 2.60 jede Sekunde aufgefrischt.
Sollte das bie bestimmten Anwendungen stren, kann dieser zyklische Refresh ausgeschaltet werden.
Dazu wird der Parameter

  cyclic=0
  
bergeben. Damit wird die Box nur noch ein Mal beim Aufruf und der nderung des Inhaltes einer ange-
zeigten Datei dargestellt. Der Defaultwert fr cyclic ist 1.

Formatierung des bergebenen Textes
-----------------------------------
Um die Darstellung des Textes ansprechender gestalten zu knnen, werden bestimmte Formatsteuer-
zeichen im bergebenen Text untersttzt. Allen Steuerzeichen gemeinsam ist der Beginn mit dem
Zeichen "~". Dieses kommt im normalen Text nicht vor und leitet daher immer einen Formatierungs-
befehl ein. Folgende Formatierungen knnen ausgefhrt werden:

  ~l    Diese Zeile auf Links-Anschlag schieben
  ~c    Diese Zeile zentrieren
  ~r    Diese Zeile auf Rechtsanschlag schieben
  ~t    Tabulator
  ~Tnnn nachfolgenden Text auf absoluter Position nnn beginnen (nur im Messagetext zulssig)
  ~s    Separator (eine waagerechte Linie ber die gesamte Textbreite auf Zeilenmitte
  ~R    nachfolgenden Text rot darstellen, gilt bis zum Zeilenende oder einem neuen Farbbefehl
  ~G    nachfolgenden Text grn darstellen, gilt bis zum Zeilenende oder einem neuen Farbbefehl
  ~B    nachfolgenden Text blau darstellen, gilt bis zum Zeilenende oder einem neuen Farbbefehl
  ~Y    nachfolgenden Text gelb darstellen, gilt bis zum Zeilenende oder einem neuen Farbbefehl
  ~F    nachfolgenden Text blinkend darstellen, gilt bis zum Zeilenende oder einem neuen Farbbefehl
  ~S    nachfolgenden Text in Standardfarbe darstellen


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:

  ~n    neue Zeile (nur von der Kommandozeile)
  ~a    
  ~o    
  ~u    
  ~A    
  ~O    
  ~U    
  ~z    
  ~d     (degree)
  
  
Die Wirkung der Formatierungen kann man sich anhand des beiliegenden Beispieltextes anschauen.
Die Datei "msgbox.txt" nach /tmp/ kopieren und anschlieend ber Telnet eingeben:

  msgbox title="Beispieltext anzeigen" msg=/tmp/msgbox.txt
  
Der Parameter "title" kann hier natrlich auch weggelassen werden. ;-) Aber denkt bitte daran,
da bei einem Aufruf ber Telnet Neutrino auch weiterhin auf die Fernbedienung reagiert. Das 
ist kein Fehler der Messagbox. Bei einem Aufruf aus einem Script heraus, welches ber die Plug-
in-Verwaltung gestartet wurde, tritt dieser Effekt dann nicht mehr auf.

Wird "msgbox" 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