3. Eigenständige Programme anlegen

Wenn Sie ein Programm fertiggestellt haben, möchten Sie es sicher mit anderen Nutzern teilen. Darunter sind sicher auch Nutzer, die R-BASIC gar nicht installiert haben und dies auch nicht wollen. Es ist deswegen möglich, ein compiliertes Programm so zu 'exportieren', dass es unabhängig von der R-BASIC Entwicklungsumgebung lauffähig ist. Nach außen verhält sich ein solches 'eigenständiges Programm' (auch R-App genannt) wie ein 'normales' mit dem PC/GEOS-SDK geschriebenes Programm. Es hat z.B. ein eigenes Icon, das der Nutzer im WORLD Verzeichnis sieht und über das er das Programm starten kann.

Außerdem erstellt R-BASIC bei Bedarf ein Uni-Installer Paket, das automatisch alle Dateien enthält, die für die Verwendung des Programms notwendig sind.

^

3.1 Interne Organisation

Ein R-BASIC Programm, das unabhängig von der Entwicklungsumgebung laufen soll, besteht aus 4 Teilen:
  1. Die Binär-Datei (BIN-Datei)
    Diese Datei enthält den eigentlichen compilierten BASIC Code und befindet sich im Ordner USERDATA\R-BASIC\BIN bzw. einer seiner Unterordner.

  2. Der Launcher
    Der Launcher (deutsch: Starter) ist ein kleines SDK-Programm, dass sich im Ordner WORD oder einer seiner Unterordner befindet. Er ist die Schnittstelle zwischen Nutzer und BASIC Programm.

  3. Libraries
    Zum Ausführen eines BASIC Programms benötigt der Launcher diverse Libraries aus dem SYSTEM Ordner (z.B. die R-BASIC Runtime Library), die BASIC Library 'BasicSystemTypes', sowie gegebenenfalls die vom Programm includeten R-BASIC Libraries, die sich im Ordner 'USERDATA\RBASIC\Library\BIN' befinden.

  4. Weitere Dateien
    Möglicherweise werden weitere Dateien benötigt. Das können z.B. Hilfedateien für das Programm sein oder Dateien, die irgendwelche Daten enthalten.

Legen Sie ein eigenständiges Programms an, so passiert folgendes:

  1. R-BASIC erzeugt die BIN Datei, indem es eine Kopie des aktuellen BASIC Programms in USERDATA\R-BASIC\BIN\... ablegt. Die Kopie wird dann modifiziert, z.B. wird die Release-Nummer gesetzt.

  2. R-BASIC legt eine Kopie des Default-Launchers im WORLD Ordner ab. Diese Kopie wird dann modifiziert ('gepatcht'), z.B. werden der Name, die Tokens (einschließlich der dazugehörigen Bildchen) und der Pfad zur BIN Datei in die Datei geschrieben. Damit existiert eine eindeutige Zuordnung zwischen Launcher und BIN Datei.

  3. Wenn gewünscht, wird ein Uni-Installer Paket angelegt, das alle zur Installation des Programms auf anderen Systemen nötigen Dateien enthält.
Der oben beschriebene Prozess bewirkt auch, dass ein nachfolgendes Ändern und erneutes Compilieren ihres Programms das eben erstelle eigenständige Programm nicht beeinflusst. Weder die BIN Datei noch der Launcher werden durch den Compileprozess geändert. Sollten Sie eigene BASIC Libraries includen und compilieren Sie eine davon neu, so wird das Programm automatisch die neue Version der Library verwenden. In diesem Fall sollten Sie auch das Installationspaket mit Hilfe des Uni-InstallCreators updaten.

Es wird empfohlen, beim Anlegen des eigenständigen Programms auch ein Uni-Installer-Paket durch R-BASIC anlegen zu lassen. Dieses enthält automatisch alle benötigten Dateien (Punkte 1 bis 3) und das Einbinden weiterer Dateien (Punkt 4) wird komfortabel unterstützt. Die benötigten System-Libraries werden aus Ihrem SYSTEM Ordner in das Installer-Paket kopiert. Dadurch enthält das Paket immer die aktuellen Library-Versionen und Kompatibilitätsprobleme sind ausgeschlossen. Der Uni-Installer sorgt beim Installationsprozess automatisch dafür, dass neuere Libraries nicht mit älteren Versionen überschrieben werden.

Startet der Nutzer nach Installation des Programms den Launcher, so liest dieser die BIN Datei und führt das eigentliche BASIC Programm aus. Da der Launcher ein PC/GEOS-SDK Programm ist, greifen hier die systemweiten Kompatibilitätschecks (z.B. auf fehlende oder inkompatible Libraries) und auch die Installation der Programm-Token (Icon Bildchen) läuft genau wie bei einem mit dem PC/GEOS-SDK geschriebenen Programm automatisch ab.

^

3.2 Der Dialog zum Programm anlegen

Bild

LongName des Programms
Der 'LongName' ist der unter PC/GEOS sichtbare 'lange' Dateiname. In den meisten Fällen ist er identisch mit dem Namen ihrer R-BASIC Programm Datei. Sie können bei Bedarf aber einen abweichenden Namen spezifizieren - entweder hier oder über die Instancevariable LongName$ des Application Objekts. Der LongName wird sowohl für den Launcher als auch für die BIN Datei verwendet.

Name des Installationspakets
Häufig soll das Installationspakt nicht exakt genauso heißen wie das Programm. Heißt ihr Programm z.B. 'SuperGame', könnte das Installationspaket 'SuperGame Version 1.0' oder 'SuperGame Version 1.1' heißen. Beim Upgrade von Version 1.0 auf 1.1 hat der Nutzer dann nicht zwei Supergames in seinem World Ordner.

Versionsnummer des Programms
Die Versionsnummer des Programms wird über den Menüpunkt 'Programm' 'Versionsnummer' eingestellt. Der letzte der drei Werte wird bei jedem Compilervorgang automatisch hochgezählt. Der Uni-Installer stellt über die Versionsnummer des Programms sicher, dass niemals eine ältere Programmversion eine neuere überschreibt.

Pfad zur compilierten Datei
Hier wird die BIN Datei abgelegt. Es wird empfohlen, dass Sie sich unter R-BASIC\BIN einen Unterordner erstellen, der ihrem Namen entspricht und diesen verwenden. Dort werden dann alle ihre BIN Dateien abgelegt und Sie können bei Bedarf hier auch weitere für ihre Programme benötigte Dateien unterbringen (z.B. Spiele Levels), ohne dass Sie befürchten müssen, dass es zu Namenüberschneidungen mit den Programmen anderer Programmierer kommt.

Über den Menüpunkt 'Optionen' - 'BASIC Optionen' - 'Default Programmpfade' können Sie einen Startwert setzen, der für alle neuen Projekte automatisch übernommen wird.

Pfad zum Launcher / Installationspaket anlegen in
Diese Einträge sollten selbsterklärend sein. Auch hier können Sie über den Menüpunkt 'Optionen' - 'BASIC Optionen' - 'Default Programmpfade' einen Startwert setzen, der für alle neuen Projekte automatisch übernommen wird.

Zusätzliche Dateien im Installer
Hier erscheinen automatisch alle über das Schlüsselwort INCLUDE eingebundenen R-BASIC und SDK-Libraries. Dazu kommt die Library 'BasicSystemTypes'. Sollte eine Library weitere Libraries includen, so erscheinen diese hier auch automatisch. Zusätzlich können Sie weitere Dateien zur Liste hinzufügen, z.B. Hilfedateien, Grafikdateien oder andere Daten-Dateien. Alle in dieser Liste enthaltenen Dateien werden automatisch in das Installationspaket übernommen.

Hinweis: Um dem Löschen von wichtigen Dateien (z.B. Fonts) beim deinstallieren des Pakets vorzubeugen, sind alle in dieser Liste vereinbarten Dateien als 'Beim Installieren nicht löschen' markiert. Wenn Sie das nicht wollen, können Sie das Paket anschließend mit der Uni-Install-Creator Applikation bearbeiten.

Optionen

  • Installer anlegen. R-BASIC wird nach erfolgreichem Erstellen des eigenständigen Programms alle benötigten Dateien in ein Uni-Installer Paket schreiben. Das Paket ist danach sofort einsetzbar, Sie können es aber mit dem Uni-Install Creator noch modifizieren.

Installer Info Texte
Erlaubt die Eingabe der Informationstexte, die der Uni-Installer dem Nutzer präsentiert.

Icon
Spezifiziert das Icon, dass der Launcher im GeoManager haben soll. Wenn Sie kein AppToken im Application-Objekt spezifiziert haben, wird das oben gezeigte Standard Token verwenden. Sie können das Token hier noch einmal ändern, bevor sie das eigenständige Programm anlegen.

Klicken Sie, nachdem sie alle Einstellungen getätigt haben, auf 'Programm anlegen' und R-BASIC macht die Arbeit für Sie.

Alle Daten, die in diesem Dialog eingegeben werden, werden beim Erstellen des eigenständigen Programms im originalen R-BASIC Programm abgespeichert. Damit stehen sie wieder zur Verfügung, wenn Sie eine neue Version Ihres Programms erzeugen wollen. Eine Ausnahme bilden Werte, die im UI-Code spezifiziert wurden (z.B. LongName$ und AppToken). Diese werden, wenn sie im UI Code stehen, bei jedem Compilevorgang neu gesetzt.

^

3.3 Verwendung von eigenen Icons

Die Begriffe Token und Icon werden sowohl bei den Anwendern als auch im umgangssprachlichen Gebrauch der Programmierer nicht sauber getrennt, auch nicht in diesem Handbuch. Strenggenommen versteht man unter 'Token' eine Struktur aus 4 Buchstaben (den TokenChars) und einer 16-Bit Zahl, der Manufacturer-ID. Der Name dieser Struktur ist GeodeToken. Unter R-BASIC ist sie 7 Byte groß, weil die Zeichenkette mit einer Null abgeschlossen werden muss. Im PC/GEOS-SDK sind es nur 6 Byte. Zu jedem Token gehört ein ganzer Satz von Bildern, den 'Icons'. Jedes Icon enthält Informationen, für welchen Zweck es sich am besten eignet, z.B. als Icon im GeoManager (Kennung 'Icon'), als Mini-Bildchen für das Expressmenü (Kennung 'Tool'), für welche Bildschirmauflösung es geeignet ist, welche Farbtiefe es hat (monochrom, 16 oder 256 Farben) und noch einige mehr. Je nach konkreter Situation wählt GEOS aus den vorhandenen Bildern das passende aus. Ist kein passendes vorhanden, wählt es ein 'möglichst gut passendes'.

R-BASIC unterstützt genau zwei Icons (Bilder) pro Token: Das eigentliche Icon ist 48x30 Pixel groß, vom Typ 'Icon' und hat 16 oder 256 Farben. Es wird vom GeoManager bei der Anzeige des Programm verwendet. Das Andere ist 15x15 Pixel groß, vom Typ 'Tool' und kann ebenfalls 16 oder 265 Farben haben. Es wird z.B. für das Expressmenü benutzt. Die Verwendung von Token ohne das 15x15 Tool Icon ist möglich, aber nicht zu empfehlen. Geringfügige Abweichungen von den vorgegebenen Größen sind zulässig, sollten aber mit Bedacht eingesetzt werden.

Die Zuweisung eines Icons zu Ihrem R-BASIC Programm ist sehr einfach. Verwenden Sie im UI Code das Statement AppToken für Ihr Application-Objekt: 

Application  MyApp
  Children = MyPrimary
  AppToken = "BPdm",16600
END OBJECT
Alternativ können Sie beim Anlegen des Programms ein Token aus Ihrer TokenDB (Token Database Datei) auswählen.

Beim Compilieren des Programms merkt sich der Compiler das Token und beim Anlegen des eigenständigen Programms kopiert R-BASIC das Token einschließlich der dazugehörigen Bilder in den Launcher. Einzige Bedingung ist, dass sich das Token in Ihrer TokenDB Datei befinden muss. Verwendet nun ein Nutzer ihr R-BASIC Programm und das Token befindet sich noch nicht in seiner TokenDB, dann installiert der Launcher das Token automatisch in der TokenDB Datei des Nutzers, genauso wie es ein 'normales' PC/GEOS-SDK-Programm macht.

Mit den Statements DocToken und ExtraToken können Sie zwei weitere Tokens definieren, die aus der TokenDB in den Launcher kopiert werden und die der Launcher bei Bedarf gemeinsam mit dem AppToken in die TokenDB des Nutzers installiert. Dabei werden die GEOS Systemfunktionen benutzt. Das bedeutet: findet der GeoManager bei der Anzeige des Programms (Launchers) das AppToken nicht in seiner TokenDB, so wird der Launcher aufgefordert, seine Token zu installieren. Er installiert dann AppToken und - falls vorhanden - DocToken und ExtraToken. Ist das AppToken bereits in der TokenDB, wird nichts installiert. DocToken und ExtraToken werden nicht extra geprüft.

Ein eigenes Icon erstellen

Die im Folgenden benannten Programme sind im Netz, unter anderem auf der R-BASIC Seite, zu finden.

Der einfachste Weg ein eigenes Icon zu erstellen ist die Verwendung des Programms 'Icon Editor'. Verwenden Sie immer die aktuellste Version des Icon Editors! Ältere Versionen enthalten diverse Bugs und sind z.T. instabil.

Wenn Sie ein selbst gezeichnetes Icon verwenden wollen, benötigen Sie eine eigene Manufacturer-ID. Es ist sehr leicht eine eigene Manufacturer-ID zu bekommen. Details dazu sind im Abschnitt 3.4 'Über die Manufacturer-ID' beschrieben. Sie sollten für jedes R-BASIC Token genau zwei Bilder erstellen (Menüpunkt 'Format', 'Format hinzufügen'): ein 48x30 Pixel großes mit den Eigenschaften: 'VGA', 'Icon' und 'Standard', sowie ein 15x15 Pixel großes mit den Eigenschaften: 'VGA', 'Werkzeug (Tool)' und 'Klein (Tiny)'.

Der Icon Editor verfügt über eine Importfunktion aus der TokenDB. Sie können also existierende Tokens importieren, ggf. ändern, ein 15x15 Tiny-Icon hinzufügen und das modifizierte Token wieder in die TokenDB exportieren. Dabei sollten Sie auf jeden Fall Ihre eigene Manufacturer-ID verwenden (und ggf. die TokenChars ändern). Ändern Sie die Tokenkennung nicht, kann es passieren, dass Ihr geändertes Icon bei anderen Nutzern nicht anzeigt wird, weil Sie das Original bereits in ihrer eigene TokenDB haben.

Bild

Um ein neues Token in die TokenDB zu exportieren, wählen Sie unter 'Datei' den Menüpunkt 'In Tokendatenbank einfügen'. Dort müssen Sie unbedingt die Auswahl 'Icon ID benutzen' treffen (1). Je nach Version des Iconeditors kann die Beschriftung der einzelnen Punkte variieren. Außerdem müssen Sie eine ID Nummer und die TokenChars (exakt 4 Buchstaben oder Ziffern) eingeben (2). Dann können Sie auf 'Ändern' klicken (3).

Als Quelle für Icons eignen sich z.B. Icon-Sammlungen. Eine große Anzahl davon ist auf der Geos-Infobase, unter 'Download Programme' - 'Icons' zu finden. Diese liegen als TokenPaks (erfordert zur Installation den 'TokenLoader') oder als Sammlung von 'Token-Dummys' vor. Dies sind kleine Programme, deren einziger Zweck darin besteht ihre Tokens in die TokenDB zu schreiben.

Eine andere Möglichkeit besteht in der Verwendung des DOS Programms ICONMAKE von Marcus Groeber. Dieses Programm erzeugt Token-Dummys aus PCX- oder ICO-Dateien, allerdings maximal mit 16 Farben. Weitere Details sowie die unterstützten Formate sind in der dazugehörigen Dokumentation beschrieben. Einmal im GeoManager angezeigt, befinden sich die Tokens dann permanent in der TokenDB und können bei Bedarf auch mit dem Icon Editor geändert bzw. um ein 15x15 'Tiny' 'Tool' Icon ergänzt werden.

Zum Erzeugen von 256 Farb-Icons eignet sich das 'Token PCX Tool'. Dieses einfache Programm liest 256-Farb PCX Dateien und erstellt daraus ein Token mit einem 48x30 und einem 15x15 Bild in der TokenDB.

^

3.4 Über die Manufacturer-ID

Was ist eine Manufacturer-ID?

Manufacturer-ID bedeutet übersetzt so viel wie 'Hersteller-Kennung' und ist eine Zahl zwischen 0 und 65535. Sie ist z.B. Teil des 'Tokens' von Programmen und kennzeichnet die Person oder die Firma, die das Programm geschrieben hat. Damit soll verhindert werden, dass zwei Programme das gleiche Token haben oder es Konflikte bei anderen Systemfunktionen, wie z.B. der Arbeit mit dem Clipboard, gibt. In einer idealen Welt hat jeder Programmierer, egal ob R-BASIC oder PC/GEOS-SDK, eine eigene Manufacturer-ID und alles ist gut.

Wann brauche ich eine eigene Manufacturer-ID?

Wahrscheinlich werden Sie erstmalig eine eigene ID benötigen, wenn Sie ein Programm veröffentlichen und ihm ein selbstgezeichnetes Icon geben wollen. Es gibt aber weitere R-BASIC Funktionen (z.B. spezielle Clipboardfunktionen), die die Verwendung einer eigenen ID erfordern. Das wird bei der Beschreibung der entsprechenden Funktion deutlich dargestellt. Zum 'Probieren' können Sie die ID 16600 verwenden. Diese ID ist für R-BASIC Beispiele reserviert.

Wie bekomme ich eine Manufacturer-ID ?

Es ist sehr einfach eine eigene Manufacturer-ID zu bekommen. Die ID's werden unter www.geos-sdk.com online verwaltet und vergeben. Melden Sie sich dort an und fordern Sie eine ID an. Sie können die gleiche ID für alle Ihre GEOS Projekte, egal ob R-BASIC Programm, Iconsammlung oder PC/GEOS-SDK Programm, verwenden. Einen entsprechenden Link, sowie weitere bzw. aktuelle Informationen erhalten Sie auch auf der R-BASIC Homepage unter www.rbettsteller.de.

Wenn ich nun aber trotzdem keine eigene ID möchte?

Solange Sie nur für sich selbst programmieren und nichts veröffentlichen, benötigen Sie keine eigene ID. Falls Sie für Ihr Programm ein Token aus der TokenDB verwenden, dass bereits eine ID hat, benötigen Sie ebenfalls keine eigene ID.

Über die ID-Bereiche sollten Sie folgendes wissen:

  • Die Null ist tabu. Das ist die ID der Standard Clipboardformate und der Standardprogramme wie GeoWrite, GeoDraw usw.. Die Verwendung der Null als eigene ID ist hochgefährlich!

  • ID's von 1 bis ca. 1000 werden von diversen älteren Programmen und von Iconsammlungen verwendet.

  • Werte unter 16384 sind von BreadBox reserviert.

  • Werte im Bereich ab 4000hex (16384 aufwärts) sind tabu. In diesem Bereich liegen die ID's der bekannten und neuen GEOS Programmierer.
Zum 'Probieren' sollten Sie daher die für R-BASIC Beispiele reservierte ID 16600 verwenden. Bedenken Sie aber, dass auch andere Programmierer auf diese Idee kommen können.

Zur FormatNummer bei eigenen Clipboardformaten mit der ID 16600:

  • Nehmen Sie keine Werte unter 100. Hier liegen die R-BASIC Beispiele.

  • Benutzen Sie einen Zufallsgenerator.
Sobald Sie für ein veröffentlichtes Programm ein selbst erstelltes Token oder eine BASIC-Funktion verwenden, die eine eigene ID erfordert, sollte Sie sich unbedingt eine ID geben lassen.

Welche Konflikte könnten auftreten?

Die Manufacturer-ID wird unter R-BASIC genau für zwei Zwecke verwendet: Zur Definition eigener Clipboardformate und zur Definition eigener Token. Es könnte also zwei Programme geben, die das gleiche Token haben. Diese beiden Programme können niemals gleichzeitig laufen. Oder es gibt Konflikte mit dem Clipboardformat, d.h. die Kennzeichnung der Daten im Clipboard ist identisch, die Daten selbst sind aber inkompatibel. Dann kann es zum Crash beim Zugriff auf das Clipboard kommen. Mit PC/GEOS-SDK-Programmen können weitere Konflikte auftreten, da z.B. die Kommunikation zwischen Programmen oder bestimmte Systemservices über die ID abgewickelt werden.

^

Weiter...