Billard Timer - Dokumentation

Durchstoß Programm :
Programm Version :
Dokumentation :
Datum :
Autor :
EMail :
Infos :


Grüße an :
Billard Timer - MIDlet
1.2.0 (d)
1.0.6 (d)
01.07.2008
Marcus Siegmund

http://www.gnartsch.de/Billard/index.htm


1. PBF Mainz 1993 e.V



Inhaltsverzeichnis




1. Über "Billard Timer"

1.1. Über dieses Dokument

Diese Dokument dient als Bedienungsanleitung für ‚Billard Timer’. Es erklärt die Installation sowie die Benutzung der Java-Applikation auf dem mobilen Gerät.

1.2. Über das Programm

‚Billard Timer’ ist konzipiert als praktisches Hilfsmittel zur genauen persönlichen Abrechnung der Spielkosten für Billardtische. ‚Billard Timer’ ist eine Java-Applikation (MIDlet), welche auf allen Java-fähigen Handys laufen sollte. Eine Gewähr kann dafür allerdings nicht gegeben werden.

BillardTimer kann jederzeit beendet werden um z.B. ein Telefonat zu führen, zu SMS'en, etc. Die Daten werden automatisch gespeichert und stehen beim nächsten Start wieder zur Verfügung.

1.2.1 Nutzungsbedingungen

Die Software darf kostenlos ohne Einhaltung spezieller Nutzungsbedingungen genutzt werden.

Es wird keine Garantie für die korrekte Funktionsweise oder Haftung für entstandene Kosten - sei es durch Fehlverhalten der Software, Onlineaktivität oder durch irgendeinen anderen Umstand herbeigeführten Schaden - gewährt.

1.3. Einsatzgebiet

‚Billard Timer’ berechnet die jeweiligen Tischkosten minutengenau. Sollte die Abrechnung der Gesamttischkosten nach einem anderen Schema erfolgen, so ist dies mit diesem Programm derzeit nicht möglich. Die Kosten werden gleichmäßig auf alle an einer Sitzung teilnehmenden Spieler aufgeteilt.

Allgemein gilt der Grundsatz: für die Richtigkeit der Abrechnung, korrekte Funktionsweise wird aus rechtlichen Gründen keine Garantie übernommen ! Auch für Datenverlust oder ähnliches kann keine Haftung übernommen werden.

1.4. Copyright

1.5. Newsletter

Gibt's keinen. Einfach hin und wieder mal nachschauen, ob sich was getan hat.
Oder im Programme-Menü auf dem Handy das Programm wählen und Menüpunkt 'Update' aufrufen.
Letzteres funktioniert aber nur, wenn man das Programm auch direkt über die Handy-Internet-Verbindung installiert hat.

1.6. Über den Autor


2. Hinweise

2.1. Systemvorraussetzungen

2.1.1. Mobiles Gerät (z.B. Java-fähiges Handy)

Ein Java-fähiges Handy oder ein kompatibles Gerät wird benötigt um das Programm ablaufen zu lassen. Da dieses Programm auf dem J2ME-Standard aufbaut unter Benutzung der Java-Standards MIDP 1.0 und CLDC 1.0, dürfte es auf allen gängigen Java-fähigen Handy laufen, oder eben auch nicht. Egal.

Denkbar wäre auch ein Einsatz auf anderen mobilen Geräten, die diese beiden Standards (MIDP und CLDC oder CDC) erfüllen. Ein Blick in das Handbuch des Gerätes sollte darüber Aufschluß geben.

2.1.1.1. Referenzgerät

Diese Applikation wurde entwickelt auf folgendem Gerät

2.1.1.2. Testgeräte

Auf folgenden Geräten wurde die Applikation bis dato erfolgreich eingesetzt. Mit eurer Rückmeldung wird die Liste hoffentlich länger werden.

2.1.1.3. Nicht kompatible Geräte

Folgende Geräte verweigern zur Zeit noch den Dienst.

2.1.2. PC

Die Software kann wahlweise unter Zuhilfenahme eines PC’s auf dem mobilen Gerät installiert werden.
Alternativ kann die Software auch direkt vom mobilen Gerät aus installiert werden durch Aufbau einer direkten Internetverbindung (z.B. WAP über GPRS).

2.1.3. Verbindungsmöglichkeit zwischen PC und mobilen Gerät

Abhängig von der Ausstattung der beiden Geräte kann die Installation über eine Infrarotverbindung, Bluetooth oder mittels eines speziellen Datenkabels erfolgen, welches man beim Hersteller des mobilen Gerätes erwerben kann.

2.1.4. Installationssoftware

Es wird eine Installationssoftware benötigt, welche das Programmpaket auf dem mobilen Gerät installiert.
Dies könnte z.B. die ‚Nokia PC Suite’ sein oder ein vergleichbares Produkt von einem anderen Hersteller.

2.1.5 Installation direkt über das Handy

Zur Installation über das Handy ist nichts weiter erforderlich, als auf dem Handy z.B. eine GPRS - Verbindung mit dem Internet herzustellen. Dies wird von den meisten Modellen unterstützt. Je noch Modell muß man an geeigneter Stelle (z.B. im integrierten WebBrowser oder über ein spezielles WAP-Dienste Menü) die Adresse eingeben, an der die Software im Internet zu finden ist.

Im Moment wäre dies z.B. folgende Addresse: http://www.1pbf-mainz.de/wap/bt/index.htm

2.2. Kompatibilität mit vorherigen Versionen

Sollte ‚Billard Timer’ bereits installiert sein, so überprüfen sie in diesem Abschnitt unbedingt die Kompatibilität ihrer Version mit der aktuellen Version !

Vergleichen sie dazu in der folgenden Tabelle die Versionen des internen Datenformats der beiden Versionen. Sind diese identisch, so kann ein Update ohne Datenverlust erfolgen.

Anderenfalls müssen Sie mit Datenverlusten rechnen (dies betrifft nur die Daten des Programms ‚Billard Timer’ selbst !). In diesem Fall sollten Sie das Update nicht aufspielen bevor sie die aktuellen Spielerkosten abgerechnet haben.

Programmversion Internes Datenformat
0.8.0-0.8.9 0.8
0.9.0-0.9.9 0.9
1.0.0-1.0.6 1.0

Ist die bereits installierte Version kompatibel mit der neuen Version, so kann die neue Version aufgespielt werden mit Übernahme der aktuellen Daten, die intern im Handy gespeichert sind. Um dies zu erreichen, darf ‚Billard Timer’ vor dem Update nicht vom mobilen Gerät gelöscht werden ! Durch das Löschen des Programms gehen sonst alle internen Daten verloren.

Ist die bereits installierte Version NICHT kompatibel mit der neuen Version, so wird der Datenbestand nicht oder nur teilweise übernommen. In diesem Falle empfiehlt es sich, das Programm erst vom mobilen Gerät zu löschen und eine Neuinstallation vorzunehmen, oder nach dem Update im Menü ‚Information’ einen ‚RESET’ auszuführen. In beiden Fällen werden alle Daten gelöscht und die Standardeinstellungen wiederhergestellt.


3. Installation via PC

Sollten sie zu der Personengruppe gehören, die wegen Speichermangel regelmäßig Java-Programme von ihrem mobilen Gerät entfernen, um sie später wieder mal aufzuspielen oder nur sehr ungern auf der Handy-Mäusetastatur herumtippen, so ist ein Abstecher nach Abschnitt ‚4. Persönliche Anpassungen als Standardeinstellungen definieren’ empfohlen, um bei erneuten Aufspielen des Programms erneutes Eingeben des Datenbestandes zu vermeiden. Die dort durchzuführenden Aktionen sollten für das computertechnisch etwas erfahrenere Publikum kein Hexenwerk darstellen, jedoch ist auf exakte Einhaltung der Regeln zu achten !

3.1. Erstinstallation

Bei der Erstinstallation sind keine speziellen Aspekte zu beachten, daher geht es gleich weiter nach Abschnitt‚3.3. Beispielinstallation’.

3.2. Update einer vorherigen Version

Sollten sie eine vorherige Version updaten wollen, so sollten Sie unbedingt den Abschnitt ‚2.2. Kompatibilität mit vorherigen Versionen’ lesen, um Datenverluste zu vermeiden !

Bei einem Update einer kompatiblen Vorgängerversion wird der aktuelle Datenbestand beibehalten. Ist dies gewünscht, so darf die Vorgängerversion nicht vom mobilen Gerät entfernt werden, da dies zur Löschung des Datenbestandes führt.

3.3. Beispielinstallation

3.3.1 Andere Hersteller (Samsung, ...)

Bei den meisten anderen Marken erfolgt die Installation über die beigelegte Handy-Software.
Diese verfügen zumeist über ein Programm, mit dem sich Grafiken, Klingentöne, etc. zwischen PC und Handy austauschen lassen.

Hier ist die übliche Vorgehensweise, daß man die beiden Dateien 'BillardTimer.jad' und 'BillardTimer.jar' in das entsprechende Hauptverzeichnis im Handy-Browser Programm auf dem PC kopiert und das mobile Gerät synchronisiert.

Damit ist die Installation abgeschlossen.

3.3.2 Nokia

Die eigentliche Installation findet mit einem Programm statt, das man in der Regel beim Hersteller des Handy oder aus dem Internet beziehen kann.

An dieser Stelle wird eine Beispielinstallation auf ein Nokia-Handy beschrieben, unter Verwendung der Nokia PC-Suite.

Teil dieser Suite ist der Nokia Application Installer, der das Programm auf dem Handy installiert.

  1. Starten Sie den ‚Nokia Application Installer’
  2. Verbinden Sie das Handy mit dem PC via Infrarot oder Datenkabel
  3. Aktivieren sie im Menü ‚Datei’ den Punkt ‚Installation’ und wählen Sie die Datei ‚BillardTimer.jad’ aus
  4. Die Installation startet automatisch
  5. und meldet die erfolgreiche Installation (Wenn nicht müssen sie sich mit der Installationssoftware auseinandersetzen und nicht mit mir !)


Start des Installationsprogrammes

Schritt 1
Verbindungsaufbau

Schritt 2
Auswahl der Installationsdatei

Schritt 3
Installation

Schritt 4
Fertig

Schritt 5


4. Persönliche Anpassungen als Standardeinstellungen definieren

Dieses Kapitel beschreibt, wie man die Standardeinstellungen dauerhaft den persönlichen Bedürfnissen anpasst.

Dauerhaft bedeutet : die Einstellungen werden bei einem RESET der Software wiederhergestellt und werden auch bei einer Neuinstallation übernommen.

4.1. Standardeinstellungen

Regeln bei der Durchführung der Änderungen:


Beispieldatei: BillardTimer.CFG
[Config]
CURRENCY=€
CURRENCY_CENT=¢
USE_AMPM=false

[Players]
Marcus;Marcus Siegmund
Harry;Harry Potter
AEN;Alfred E. Neumann
Klausi;Klaus Kinski
Kall;Karl
DKsF;Dem Kalle sei Frau
Demi;Demi Moore

[Rates]
BT;Club Training Billard;320
BC;Club Billard;500
ST;Snooker Training;576
B;Billard;640
S;Snooker;640
K;Karambolage;750


4.2. Anpassungen vor Erstinstallation vornehmen

Bei der Erstinstallation sind keine speziellen Aspekte zu beachten, daher geht es gleich weiter zu ‚Anpassungen vornehmen’

4.3. Anpassungen bei bestehender Installation nachträglich vornehmen

Es ist möglich, die Standardeinstellungen bei einer existierenden Installation nachträglich vorzunehmen.

Diese Änderungen werden in diesem Fall nicht automatisch aktiviert, sondern erst bei einem RESET der Software (zu finden im Menü ‚Information’ des Programms) durch den Benutzer.

Dabei gehen allerdings alle Daten des Programms (Spieler, Tarife, Kosten, etc.) verloren.

Aus technischen Gründen ist es NICHT möglich, die aktuelle Konfiguration aus dem mobilen Gerät auszulesen und zu sichern.

Nehmen Sie die Änderungen wie im folgenden Abschnitt beschrieben vor und installieren Sie die Software mit den neuen Standardeinstellungen auf das mobile Gerät.

Fehlt der Menüpunkt 'RESET', so liegt das daran, daß keine Konfigurationsdatei gefunden werden konnte. Zum Schutz der eigenen Einstellungen ist ein RESET somit nicht möglich.

4.4. Anpassungen vornehmen

4.4.1. Persönliche Konfigurationsdatei editieren

4.4.2. JAR-Archiv umbenennen

4.4.3. ZIP-Archiv entpacken

4.4.4. Persönliche Konfigurationsdatei dem ZIP-Archiv hinzufügen

4.4.5. ZIP-Archiv aktualisieren

4.4.6. JAR-Archiv aktualisieren

4.4.7. JAD-Datei aktualisieren


Beispieldatei : BillardTimer.JAD
MIDlet-Version: 1.0.0 MIDlet-Name: Billard Timer MIDlet-Jar-Size: 65047 MIDlet-Jar-URL: BillardTimer.JAR MIDlet-1: BillardMIDlet,/Res/Billard8.PNG,my.Billard.BillardMIDlet MIDlet-Vendor: Marcus Siegmund MIDlet-Description: Billard Timer (c) 2004/09/30



5. Benutzeroberfläche

Die Abbildungen zu diesem Kapitel sind zu Dokumentationszwecken einem Emulationsprogramm (mit englischsprachigen Standardmenüs) entnommen und Erscheinen auf einem realen Gerät in einem anderen Maßstab.

Zudem kann sich die Darstellungsweise und Benutzerführung in den Menüs je nach Gerätes (und Hersteller) unterscheiden.

Ausgangspunkt für alle beschriebene Aktionen soll das Hauptmenü sein. Das Erscheinungsbild und die Anordnung der verschiedenen Menüpunkte kann je nach verwendetem Gerät unterschiedlich sein, weshalb die Beschreibung der Menüs, etc. allgemein gehalten ist.

Hauptmenü             Menü-Optionen Hauptmenü

Das Haupmenü (siehe oben links) bietet mit seinen Menüoptionen (oben rechts) Zugang zu allen wichtigen Funktionen der Applikation.

5.1. Anzeigen und Menüs

5.1.1. Beispielbildschirme

Startbildschirm

Splashscreen

Abbildung 1
Startmeldung

Abbildung 2
Hauptmenü

Abbildung 3
Menü Hauptmenü

Abbildung 4
Spielerliste

Abbildung 5
Menü Spielerliste

Abbildung 6
Spieler Anzeigen

Abbildung 7
Spieler Ändern

Abbildung 8
Spieler Neu

Abbildung 9
Tarifliste

Abbildung 10
Menü Tarifliste

Abbildung 11
Tarif Anzeigen

Abbildung 12
Tarif Ändern

Abbildung 13
Tarif Neu

Abbildung 14
Sitzungsliste leer

Abbildung 15
Sitzungsliste

Abbildung 16
Menü Sitzungsliste

Abbildung 17
Sitzung Details (1)

Abbildung 18
Sitzung Details (2)

Abbildung 19
Menü Sitzungsdetails

Abbildung 20
Sitzung Mitspieler

Abbildung 21
Sitzung Tarif

Abbildung 22
Spielerkosten

Abbildung 23
Programmmenü

Abbildung 24
Menü Programmmenü

Abbildung 25
Informationen

Abbildung 26
RESET durchführen ?

Abbildung 27
RESET OK

Abbildung 28
Konfiguration fehlt

Abbildung 29
Endemeldung

Abbildung 30
Screensaver

Abbildung 31
   


5.1.2. Menüstruktur

Unten abgebildet ist die Struktur der Menüs ausgehend vom Hauptmenü.
Der Pfeil bedeutet, daß man mit dem entsprechenden Menüpunkt in einen vorherigen Bildschirm zurückkommt.

5.2. Typische Aufgaben

Zu den ersten Aufgaben gehört es, die Liste der verfügbaren Tarife und die Liste möglicher Mitspieler einzugeben. Sollte dies nicht schon wie in Kapitel 4. Persönliche Anpassungen als Standardeinstellungen definieren geschehen sein (was vorzuziehen wäre weil es einige Vorteile mit sich bringt !), so kann dies auch direkt mit der Applikation auf dem mobilen Gerät nachgeholt werden. Es lohnt sich von Anfang an alle Angaben auf einen Schlag zu erfassen, um nicht immer wieder irgendetwas/irgendwen nachtragen zu müssen.

An dieser Stelle werden alle Schritte besprochen, welche zum Bedienen des Programmes notwendig sind.

5.2.1. Tarife anpassen

Um letztendlich eine Abrechnung der Tischkosten zu erreichen, sind zunächst die möglichen Tarife zuerfassen, welche in den besuchten Spiellokalen gängig und relevant sind.

Dazu öffne man über das Menü des Hauptmenüs die 'Tarifliste'. Bereits vorhandene Tarife können angezeigt, editiert und gelöscht werden oder man wählt 'Neu' um einen neuen Tarif zu erstellen.

Jeder Tarif besteht aus folgenden Informationen:

Das Kürzel identifiziert den Tarif und muß daher eindeutig sein.
Als Name kann ein beliebiger Text eingetragen werden.
Der Stundenpreis ist praktischerweise in Cent einzugeben, nicht in Euro !

5.2.2. Spieler anpassen

Um die Kosten den Mitspielern anrechnen zu können, müssen diese ebenfalls erfaßt werden.

Dazu öffne man über das Menü des Hauptmenüs die 'Spielerliste'.
Bereits vorhandene Spieler können angezeigt, editiert und gelöscht werden oder man wählt 'Neu' um einen neuen Spieler zu erstellen.
Die Spieler werden automatisch nach Häufigkeit in Spielaktivitäten sortiert. Dieser Zähler kann bei Bedarf für alle Spieler über 'Zähler zurücksetzen' auf Null zurückgestellt werden.

An dieser Stelle kann man unter folgenden Optionen wählen:

Jeder Spieler besteht aus folgenden Informationen:

Das Kürzel identifiziert den Tarif und muß daher eindeutig sein.
Als Name kann ein beliebiger Text eingetragen werden.

Zu jedem Mitspieler existiert ein Zähler, welcher erfaßt, wie häufig der Spieler an Sitzungen teilgenommen hat und entsprechend weiter vorne in der internen Liste platziert. Neue Mitspieler werden dementsprechend automatisch hinten an die Liste angehängt und müssen sich in der Liste quasi weiter 'vorarbeiten' um nach vorne zu gelangen.

5.2.3. Sitzungen verwalten

Als Sitzung wird ein durchgehender Zeitabschnitt bezeichnet mit genau einem Tarif, optionaler Tischnummer und fester Mitspielerliste.
Ändern sich während einer Sitzung die Bedingungen (Mitspieler verläßt die Siztung oder ein neuer Spieler tritt dem Spiel bei oder der Tarif ändert sich), so ist die laufende Sitzung zu beenden und eine neue zu starten.

Die Liste der Sitzungen kann über das Hauptmenü mit der Option 'Sitzungsliste' eingesehen werden.

Angezeigt wird die Liste aller Sitzungen mit Zeitdauer, Anzahl der Spieler und Kosten pro Spieler für diese Sitzung (in Euro) bis zum aktuellen Zeitpunkt. Weiterhin wird die Gesamtdauer aller Sitzungen sowie die Gesamtkosten angezeigt. Neue Einträge erscheinen in der Liste zuerst, alte Einträge an deren Ende.

Offenen (nicht beendeten) Sitzungen wird ein '*' vorangestellt.
Enthält eine Sitzung nicht benannte Spieler (durch explizites Setzen der Spieleranzahl statt Auswahl der Mitspieler aus der Spielerliste),
so wird diesen zudem ein '!' vorangestellt.

An dieser Stelle kann man unter folgenden Optionen wählen:

5.2.3.1. Sitzungsdetails

In der Detailansicht lassen sich einige Angaben direkt durch die Navigationstasten des Geräts ansteuern und ändern.

Dazu gehören :

Wenn man an dieser Stelle Änderungen durchführt, so sollte man in jedem Fall die Änderungen erst übernehmen, bevor man andere Aktionen aus dem Menü durchführt (z.B. Tarif und Mitspieler auswählen), da sonst die Angaben verloren gehen.

Die Sitzungsdetails-Ansicht bietet folgende Menü-Optionen:

5.2.4. Kostenabrechnung

Die laufenden Kosten können über das Hauptmenü mit der Option 'Spielerkosten' eingesehen werden.

Es werden die Kosten pro Spieler (identifiziert durch sein Kürzel) in Euro angezeigt, sowie die Gesamtkosten aller erfaßten Sitzungen.
Sollte eine Sitzung einen nicht identifizierten Spieler enthalten, so wird ein zusätzlicher Eintrag mit dem Kürzel '?' angezeigt zusammen mit den nicht zugeordneten Kosten.

Spielern, welche an einer noch nicht abgeschlossenen Sitzung teilnehmen, wird ein '*' vorangestellt.


Anhang

A. Glossar

A.1. Allgemeine Definitionen

A.2. Spezielle Definitionen


B. Historie

B.1. Neue Funktionen

Version Funktionalität Bemerkung
1.0.1 'Freier Tarif' hinzugefügt, um den Stundenpreis manuell angeben zu können ohne die Tarife anpassen/erweitern zu müssen. Nützlich, wenn man mal woanders spielt als im 'Hauslokal'. Tarifkürzel : ?
1.0.1 Basiskonfigurationsdatei ausgelagert zum Schutz vor unabsichtlichem Löschen persönlicher Einstellungen und Übernahme leerer Standardwerte. 'RESET' nur möglich bei Vorhandensein einer Konfigurationsdatei. siehe Datei 'BillardTimer.cfg'
1.0.2 Genereller Code-Review und Speicheroptimierung  
1.0.2 Vereinfachte Benutzerführung bei der Sitzungsverwaltung  
1.0.3 Einfach nur mal so ;-). Ach ja, da waren ja noch ein paar Bugfixes. :-(  
1.0.4 Die Spielerliste wird automatisch nach Häufigkeit der Mitspieler sortiert.  
1.0.5 Möglichkeit den internen Zähler der Mitspieler zurückzusetzen  
1.0.6 Screensaver im Hauptmenü eingefügt.  
1.1.0 eine Reihe kleinerer Schönheitskorrekturen
1.2.0 Umstrukturierung und Verbesserung der Benutzerführung

B.2. Behobene Fehler

Version Problem Bemerkung
 1.0.0 Das Programm überprüft beim Erstellen nicht auf doppeltes Vorhandensein von Spielern und Tarifen. gefixt in 1.0.2
1.0.0 'Abbrechen' funktioniert nicht beim Erstellen eines Spielers oder Tarifs. Der entsprechende Eintrag muß manuell gelöscht werden. gefixt in 1.0.2
1.0.0 Das Programm erlaubt es, Spieler und Tarife zu löschen oder das Kürzel zu verändern, die noch in Sitzungen gelistet sind, was zu Inkonsistenzen in der Abrechnung führt. gefixt in 1.0.2
1.0.2 Erstellen von Spielern, Tarifen nicht möglich gefixt in 1.0.3
1.0.4 Einige Probleme mit anderen Handytypen behoben (SELECT-Taste) gefixt in 1.0.5

B.3. Bekannte Probleme

Version Problem Bemerkung