4. Einbinden von Hilfedateien

^

4.1 Überblick

R-BASIC stellt Ihnen das GEOS-weite Hilfesystem zur Verfügung. Damit können Sie Hilfedateien schreiben und einbinden, die sich in ihrer Handhabung nicht von den Hilfedateien der PC/GEOS-SDK-Programme unterscheiden.

Das Grundprinzip des GEOS Hilfesystems

Hilfedateien haben ein spezielles Format und befinden sich grundsätzlich im Ordner USERDATA\HELP. Jede Hilfedatei wird über ihren Namen angesprochen. In der Hilfedatei befinden sich die einzelnen Hilfeseiten. Jede Hilfeseite hat einen internen Namen, der als "Help Context" bezeichnet wird. Wenn ein Programm wünscht, eine bestimmte Hilfeseite zu öffnen, muss es dem Hilfesystem den Dateinamen (Help File) und den Help Context mitteilen. Das Hilfesystem öffnet dann die entsprechende Seite in der Hilfedatei und zeigt sie an. Beim Erstellen der Datei können Sie Verweise ("Hyperlinks") auf andere Hilfeseiten der gleichen Datei oder auch von anderen Hilfedateien festlegen. Damit kann der Nutzer zwischen den verschiedenen Hilfeseiten navigieren. Ein Hyperlink auf eine bestimmte Stelle innerhalb einer Seite (z.B. ans Seitenende) ist leider nicht möglich.

^

4.2 Ansprechen der Hilfe in R-BASIC

Tabelle

Um das Hilfesystem von GEOS nutzen zu können, müssen Sie nur die Hilfedatei (Help File) und die aufzurufende Hilfeseite (Help Context) festlegen. Dazu stehen Ihnen die Instancevariablen helpFile$ und helpContext$ zur Verfügung. Den Rest erledigt das System. Beispielsweise kann über die Taste F1 automatisch die Hilfe aufgerufen werden. HelpFile$ und helpContext$ sind für alle GenericClass-Objekte definiert.

Um zu verstehen, wie sie diese Instancevariablen am besten einsetzten, müssen Sie verstehen, wie das Hilfesystem arbeitet.

So arbeitet das Hilfesystem

Nehmen wir an, die haben einen Dialog offen, der über einen "Hilfe" Button verfügt. Klicken Sie auf den Button oder drücken Sie "F1", so wird das Hilfesystem von GEOS aktiviert. Diese sucht zuerst im Dialogobjekt nach einer Hilfedatei und einem HelpContext. Wenn der Programmierer im Dialog weder einen Wert für helpContext$ noch einen für helpFile$ definiert haben, wendet sich das System an das Parent-Objekt des Dialogs, dann an dessen Parent usw., bis hin zum Application-Objekt.

Nehmen wir weiterhin an, der Programmierer hat dem Dialog einen helpContext$ gegeben, aber keinen Wert für helpFile$ festgelegt. Dann durchsucht das System die Parent-Objekt nur noch nach dem Namen der Hilfedatei (helpFile$). Sobald das System HelpFile und HelpContext zusammen hat, zeigt es die entsprechende Hilfeseite an.

helpFile$

Syntax UI- Code: helpFile$ = "FileName"

Lesen: <stringVar> = <obj> . helpFile$

Schreiben: <obj>.helpFile$ = "Text"

HelpFile$ ordnet einem Objekt eine Hilfedatei zu. Da das GEOS Hilfesystem den Objekttree aufwärts (in Richtung der Parents) durchsucht, ist diese Hilfedatei auch für alle Children des Objekts gültig. Deswegen wird dem Application Objekt mit helpFile$ eine Hilfedatei zugeordnet. Die Instancevariable helpFile$ ist aber für alle GenericClass Objekte zulässig. Häufig wird sie für Groups, Dialoge und Buttons verwendet, wenn diese eine Hilfedatei nutzen sollen, die von der im Applicationobjekt definierten "Haupthilfe" abweicht.

Die Hilfedatei ist eine GEOS-Datei. Deswegen sind für helpFile$ bis zu 32 Zeichen zulässig.

Hinweis: Damit der Button "Inhalt" im Hilfefenster arbeiten kann, müssen Sie für das Applicationobjekt einen Namen für die Hilfedatei (helpFile$) festlegen.

helpContext$

Syntax UI- Code: helpContext$ = "ContextName"

Lesen: <stringVar> = <obj>.helpContext$

Schreiben: <obj>.helpContext$ = "Text"

HelpContext$ ordnet einem Objekt eine Hilfeseite (Help Context) zu. Da das GEOS Hilfesystem den Objekttree aufwärts (in Richtung der Parents) durchsucht, ist diese Hilfeseite auch für alle Children des Objekts gültig. Die Instancevariable helpContext$ ist für alle GenericClass Objekte zulässig. Sehr häufig wird ein Help Context für Groups, Dialoge und Buttons verwendet, um die entsprechende Hilfeseite anzuzeigen. Den Namen der Hilfedatei bezieht das System dabei sehr häufig vom Applicationobjekt.

Die Textlänge für helpContext$ ist auf 20 Zeichen begrenzt. Mehr lässt der GEOS Hilfeeditor in GeoWrite nicht zu.

Die Standardkonfiguration

Die meisten Programme verwenden nur eine einzige Hilfedatei und beim Aufruf der Hilfe wird immer die Startseite (Inhaltsverzeichnis, engl. Top Of Content, TOC) angezeigt. Das ist sehr einfach zu realisieren. Vereinbaren Sie im UI Code für das Applicationobjekt eine Hilfedatei (helpFile$) und für das Primaryobjekt den Help Context "TOC". Dadurch erscheint automatisch der "Hilfe" Button (blaues Fragezeichen) in der Titelzeile des Primaryobjekts und die Taste F1 zum Aufruf der Hilfe wird aktiviert. 
Application DemoApplication
  Children = DemoPrimary
  helpfile$ = "R-BASIC Demo Help"
END Object

Primary DemoPrimary
  Children = .....
  SizeWindowAsDesired
  helpContext$ = "TOC"
END Object
Um den automatisch erzeugten Hilfebutton aus der Titelzeile des Primary wieder zu entfernen, verwenden Sie bei bedarf den Hint PrimaryNoHelpButton.

Eigene Hilfeseiten für Dialoge

Ein sehr häufiger Fall ist, dass ein Dialog offen ist und der Nutzer Hilfe zu genau diesem Dialog benötigt. Dann kann er entweder die Taste F1 drücken oder einen speziellen "Hilfe" Button in diesem Dialog anklicken. Dieses Funktionalität lässt sich sehr einfach implementieren. Geben Sie einfach dem Dialogobjekt eine Help Context. Als Nebenwirkung erzeugt der Dialog automatisch einen Hilfebutton. Das Hilfesystem ruft dann beim Aufruf der Hilfe (F1 oder anklicken des Hilfebuttons) automatisch die dem Dialog zugeordnete Hilfeseite auf. 
Dialog HelpedDialog
  Caption$ = "Dialog mit Hilfe"
  Children = ....
  helpContext$ = "SpecialDialogHelp"
End Object
Bei Bedarf können Sie auch eine andere Hilfedatei (helpFile$) festlegen: 
Dialog HelpedDialog
  Caption$ = "Dialog mit Hilfe"
  Children = ....
  helpContext$ = "SpecialDialogHelp"
  helpFile$ = "SpecialHelpFile"
End Object
Der vom Dialog automatisch erzeugte Helpbutton hat ein Fragezeichen als Aufschrift. Um diese Aufschrift zu ändern, muss man einen Button anlegen, dessen interactionCommand Wert auf IC_HELP gesetzt ist. Dieser Button ersetzt dann den vom Dialog erzeugten Button. Zusätzlich sollten Sie dem Button die Anweisung
placeObject = REPLY_BAR
geben, falls das angebracht ist. 
Dialog HelpedDialog
  caption$ = "Dialog mit Hilfe"
  children = ... , DialogHelpButton
  dialogtype = DT_COMMAND
  helpContext$="MoreHelp"
End Object
...
Button DialogHelpButton
  Caption$ = "Hilf mir"
  interactionCommand = IC_HELP
  placeObject = REPLY_BAR
End Object

Direkter Aufruf spezieller Hilfeseiten

Insbesondere in einem "Hilfe" Menü oder auch in einem Dialog kann der Wunsch bestehen, mehrere konkrete Hilfeseiten direkt aufzurufen. Das lässt sich sehr einfach über Buttons realisieren, denen als ActionHandler das Schlüsselwort "BringUpHelp" zugewiesen wird. Diese Buttons sollten einen eigen Help Context und ggf. eine eigene Hilfedatei zugeordnet bekommen. 
Dialog HelpedDialog
  caption$ = "Dialog mit mehr Hilfen"
  children = ... , HelpButton1, HelpButton2
  dialogtype = DT_COMMAND
End Object
...
Button HelpButton1
  Caption$ = "Hilfe Thematisch"
  ActionHandler = BringUpHelp
  helpContext$ = "ThemaHelp"
End Object

Button HelpButton2
  Caption$ = "Spezielle Hilfe"
  ActionHandler = BringUpHelp
  helpContext$ = "HelpSpecial"
  helpFile$ = "Help File 2"
End Object

^

4.3 Unterstützung für "Virtual Desktop"

Wenn Sie das Programm "Virtual Desktop" von Jens-Michael Groß installiert haben, möchten Sie vielleicht die dort verfügbare Funktionalität "BubbleHelp" auch für ihre R-BASIC Programme einsetzen. J.-M. Groß hat die BubbleHelp Funktion über die Help Contexte realisiert. Um z.B. einem Button die Bubble-Hilfe "Öffnet die Dateiauswahl" zu geben, verwenden Sie helpContext$ mit drei führenden $-Zeichen. 
Button FileSelectButton
  Caption$ = "Wählen"
  helpContext$ = "$$$Öffnet die Dateiauswahl"
End Object
Virtual Desktop erkennt an den führenden $$$, dass es sich um eine Bubble-Hilfe handelt. Der Text hinter den $$$ kann bis zu 35 Zeichen lang sein.

Sie können BASIC Programme, denen Sie auf diese Weise eine BubbleHelp Funktionalität gegeben haben, problemlos an User verteilen, die Virtual Desktop nicht installiert haben. Sie laufen dort ohne Einschränkung.

^

4.4 Erstellen von Hilfedateien

Hilfedateien werden einfach mit GeoWrite erstellt. Dazu muss zuerst der Hilfeeditor freigeschaltet werden. Sie erkennen am Vorhandensein des Menüs "Hilfe-Editor", dass der Hilfeeditor bereits aktiviert ist.

So schalten Sie den Hilfeeditor frei

Wenn Sie noch kein Hilfe-Editor Menü haben, gehen Sie folgendermaßen vor:
  1. Starten Sie GEOS und stellen Sie sicher, dass GeoWrite nicht läuft. Fahren Sie GEOS dann herunter.

  2. Fertigen Sie eine Sicherheitskopie ihrer GEOS.INI an und öffnen Sie sie mit einem Texteditor (nicht mit MSWord oder sowas!). Suchen Sie die Kategorie [configure] und tragen darunter die Zeile
    helpeditor = true
    ein. Wenn die Kategorie [configure] noch nicht existiert müssen Sie sie anlegen. Dieser Schritt stellt sicher, das man in GeoWrite den Hilfeeditor zuschalten kann. Speichern Sie die GEOS.INI und starten Sie GEOS und dann GeoWrite.

  3. Wählen Sie in GeoWrite im Menü "Optionen" den Punkt "Benutzerebene ändern". Klicken Sie auf "Feineinstellung" und aktivieren Sie das Kontrollkästchen "Hilfe-Editor". Wundern Sie sich bitte nicht, dass jetzt keine Benutzerebene mehr selektiert ist. Mehrfach OK klicken nicht vergessen.

  4. Wählen Sie "Konfiguration speichern" aus dem Optionen-Menü.

  5. Sollte das Hilfe-Editor Menü jetzt noch nicht zu sehen sein, schließen Sie bitte GeoWrite und starten Sie GEOS neu.

So erstellen Sie eine Hilfedatei

  1. Planen Sie ihre Hilfedatei gründlich!

  2. Öffnen Sie in GeoWrite eine neue Datei und speichern Sie sie unter einen möglichst eindeutigen Namen.

  3. Schreiben Sie das "Inhaltsverzeichnis". Das ist die Startseite, von der aus auf die wichtigsten Unterthemen gesprungen werden soll. Sie muss natürlich die Texte für die Hyperlinks zu den Unterthemen enthalten. Ein Beispiel: 
 Hilfe zu Supergame

    Spielregeln
    Copyright
    Wählen Sie für die Hyperlinks ein geeignetes Format, z.B. dunkelblau und unterstrichen.

    Diese Seite kann, wie jede andere Hilfeseite auch, Grafiken oder Bilder enthalten. Sie sollten Grafiken und Bilder aber immer in die Textebene einfügen, sonst könnten Layoutprobleme beim der Anzeige der Hilfe die Folge sein.

  1. Drücken Sie Strg-Enter um eine neue Seite zu öffnen. Es ist wichtig dass jede Hilfeseite auf einer neuen Seite beginnt.

  2. Schreiben Sie den Hilfetext, z.B.: 
 Spielregeln

 Wer gefressen wird hat verloren.
    Denken Sie bei der Formatierung daran, dass der Nutzer das Hilfefenster später in seiner Größe verändern kann. Arbeiten Sie zur Formatierung nicht mit der TAB-Taste oder Leerzeichen sondern verwenden Sie konsequent Seitenränder und Absatzeinzüge! Auch Tabulatoren sind mit Vorsicht zu genießen, da die Hilfe meist nicht so breit ist wie das Textfenster von GeoWrite. Farben und Zeichenattribute sind natürlich auch erlaubt.

  1. Jetzt müssen Sie die internen Seitennamen (Help Contexte) vereinbaren. Öffnen Sie dazu das Hilfe-Editor Menü und wählen Sie "Kontext erstellen". Erstellen Sie unbedingt einen Kontext namens TOC, der auch die Eigenschaft "TOC" aus der Auswahlliste oben bekommen sollte. TOC steht für Table of Content (Inhaltsverzeichnis) und jede Hilfedatei muss zwingend einen Kontext namens TOC haben, sonst arbeitet das Hilfesystem nicht richtig. Alle anderen Kontexte behalten die Eigenschaft "Text". Erstellen Sie weitere Kontexte mit beliebigen Namen, z.B. "Spielregeln" oder "Copyright". Leerzeichen sind zulässig, aber unpraktisch.

  2. Nun müssen Sie die vereinbarten Help Contexte den einzelnen Seiten zuordnen. Gehen Sie dazu in GeoWrite zunächst auf Ihre Seite mit dem Inhaltsverzeichnis und markieren Sie die erste Zeile oder die ersten Zeilen. Dabei gelten die folgenden Regeln:

    • Der Anfang der ersten Zeile muss mit markiert sein. Das gilt auch, wenn es sich um eine Leerzeile handelt. Leerzeilen enthalten keine Zeichen, auch keine Leerzeichen oder Sondertext wie Tabulatoren oder Grafiken.

    • Beginnt die Seite mit einer oder mehreren Leerzeilen so sollten Sie alle führenden Leerzeilen, einschließlich der ersten Zeile mit Text, markieren.

    • Der Text der ersten Zeile, die ein Zeichen enthält, wird vom Hilfesystem für das Menü "Letzte Schritte" verwendet.

    • Das Markieren der ganzen Seite ist unzulässig.

    Öffnen Sie nun wieder das Hilfe-Editor Menü und wählen Sie "Kontext setzen". Klicken Sie auf "TOC" in der Liste der Kontexte und dann auf" Anwenden".

    Markieren Sie nun die ersten Buchstaben der erste Hilfeseite und weisen Sie ihm auch einen Kontext zu. Wichtig ist hier, dass nicht aus Versehen der Seitenumbruch mit markiert ist, sonst wird der Kontext der vorhergehenden Seite zugeordnet!

    Tipp: Beginnt die erste nicht-Leerzeile mit einer Grafik so findet das Hilfesystem keinen Text für die "Letzte Schritte" Liste. Um das zu vermeiden schreiben sie den Text für die "Letzte Schritte" Liste in die allererste Zeile, setzen ihn aber auf "unsichtbar", indem Sie im Menü "Zeichen" - "Textfarbe" den Wert für "Raster (%)" auf Null setzen.

  3. Jetzt müssen Sie die Seiten verlinken. Markieren Sie auf der Seite mit dem Inhaltsverzeichnis den Link auf das erste Hilfethema. Öffnen Sie nun wieder das Hilfe-Editor Menü und wählen Sie "Hyperlink setzen". Wählen Sie einen Kontext und klicken Sie auf "Anwenden".

    Tipp: Setzen Sie hinter jeden Hyperlink, der allein auf einer Zeile steht ein einzelnes Leerzeichen, das nicht Teil des Links ist. Das verhindert, dass das Hilfesystem den Mauscursor bis an Ende der Zeile, wo gar nichts mehr steht, als "Hyperlink-Cursor" anzeigt.

  4. Nun können Sie weitere Hilfeseiten, Kontexte und Hyperlinks nach belieben in das Dokument einfügen.

  5. Zum Abschluss muss die Hilfedatei im USERDATA\HELP Ordner angelegt werden. Dazu öffnen Sie wieder das Hilfe-Editor Menü und wählen "Hilfedatei erstellen". Den Punkt "Daten komprimieren" sollten Sie aktiviert lassen. GeoWrite legt eine Kopie des aktuellen Dokuments in USERDATA\HELP ab und ändert deren Format so, dass das Hilfesystem sie verwenden kann. Die GeoWrite-Datei bleibt erhalten. So können Sie ihre Hilfedatei später beliebig erweitern oder verändern.

Hilfesysteme mit mehreren Hilfedateien

Es ist möglich, einen Hyperlink auf einen Kontext in einer anderen als der aktuellen Datei zu setzen. Damit können Sie sehr umfangreiche und komplexe Hilfesystem aufbauen. Um einen Hyperlink auf einen Kontext in einer fremden Datei zu setzten, müssen Sie den Namen der Datei und den Namen des anzuspringenden Kontextes manuell vereinbaren.
  1. Öffnen Sie den Punkt "Datei definieren" im Menü "Hilfe-Editor". Tragen Sie den Namen der Hilfedatei ein und klicken Sie auf "Datei hinzufügen".

  2. Öffnen Sie den Punkt "Kontext erstellen" im Menü "Hilfe-Editor". Klicken Sie auf "• aktuelle Datei •" und wählen Sie die eben hinzugefügte Datei aus. Definieren Sie jetzt den Namen des Kontextes, den Sie in dieser Datei anspringen wollen.

  3. Markieren Sie den Hyperlinktext in ihrem Dokument und öffnen Sie den Menüpunkt "Hyperlink setzen" aus dem "Hilfe-Editor" Menü. Wählen Sie dort die gewünschte Datei sowie den gewünschten Kontext aus und klicken Sie auf "Anwenden".

  4. Erzeugen Sie die beiden betroffenen Hilfedateien (Menüpunkt "Hilfedatei erstellen"), starten Sie die zugehörige Anwendung bzw. Ihr BASIC Programm und testen Sie ihre Hilfedateien. Sollte es ein Problem geben, prüfen Sie bitte die Schreibweise (Groß/Kleinschreibung, Leerzeichen) des Dateinamens und des Kontextes.

^

Weiter...