Kontextsensitive Hilfe wird beschrieben, indem der im Code der Benutzerschnittstelle deklarierten Kontext-ID eine Beschreibung sowie eine Liste von Links zu verwandten Themen in der Onlinehilfefunktion zugeordnet wird. Diese Zuordnungen werden innerhalb einer XML-Datei durchgeführt. Für jedes Plug-in können Sie eine beliebige Anzahl von XML-Dateien mit Zuordnungen für Kontexthilfen erstellen. Beschreibung und Links jeder Kontext-ID werden innerhalb der <Kontext>elemente der XML-Datei bereitgestellt. Jedes Kontextelement kann über ein optionales <Beschreibungs>element verfügen, in dem das Benutzerschnittstellenobjekt beschrieben wird, sowie über <Themen>elemente, die Links zur Onlinedokumentation bereitstellen.
Ab Version 3.1 können Kontextelemente optional den zur Darstellung der Informationen der Kontexthilfe in der Hilfesicht verwendeten Standardtitel überschreiben.
<contexts> <context id="panic_button" title="Panic Button Title"> <description>This is the panic button.</description> <topic href="tasks/pushing_the_panic_button.htm" label="Pushing the panic button"/> <topic href="reference/panic_button.htm" label="Panic Button Reference"/> </context> ... </contexts>
Sobald die Kontexte in der XML-Datei (oder den XML-Dateien) beschrieben wurden, können Sie in Ihrem Plug-in-Manifest auf die Kontextdateien verweisen. Beachten Sie, dass im obigen Beispiel die Kontext-ID nicht vollständig qualifiziert ist. Dies ist zulässig, solange die Kontextdatei in dem Manifest des Plug-ins, das die Kontext-ID definiert hat, ergänzt wird. In anderen Worten: die Kontext-ID wird zur ID des Plug-ins aufgelöst, das die XML-Datei ergänzt hat.
Zur Ergänzung von Kontextdateien verwendet ein Plug-in den Erweiterungspunkt org.eclipse.help.contexts.
<extension point="org.eclipse.help.contexts"> <contexts name="myContextHelp.xml" /> </extension>
Sie können auch aus anderen Plug-ins auf Kontextdateien verweisen, indem Sie das Attribut plugin aufnehmen. Hierdurch können Sie die gesamte Dokumentation (einschließlich der kontextsensitiven Hilfe) in einem gemeinsamen Plug-in zusammenfassen und dann aus dem Plug-in für den Benutzerschnittstellencode oder einem anderen zugehörigen Plug-in auf dieses Plug-in verweisen.
<extension point="org.eclipse.help.contexts"> <contexts name="myContextHelp.xml" plugin="com.example.helpExample" /> </extension>
Wie Sie sehen, haben Sie einen großen Spielraum, wenn es darum geht, Ihre Kontexte in eine oder mehrere Dateien in einem oder mehreren Plug-ins zu organisieren. Wesentlich ist nur, dass die Kontext-IDs der Dateien korrekt aufgelöst werden. Wenn Sie eine Kontext-ID nicht vollständig qualifizieren, müssen Sie die Kontext-XML-Dateien in dem Plug-in ergänzen, das die Kontext-IDs deklariert hat. Wenn Sie vollständig qualifizierte Kontext-IDs verwenden, haben Sie völlige Freiheit, was die Position Ihrer XML-Dateien und die Wahl des Plug-ins, das die Kontext ergänzt, angeht.
Eine weitere Flexibilitätsstufe ergibt sich dadurch, dass die kontextsensitive Hilfe für dieselbe Kontext-ID aus unterschiedlichen Plug-ins ergänzt werden kann. Dies ist beispielsweise dann hilfreich, wenn es Plug-ins für verschiedene Dokumentationsgruppen gibt, die in der Konfiguration eines Benutzers installiert werden können, jedoch nicht installiert werden müssen. Auf diese Weise kann jedes Dokumentations-Plug-in seine Kontexte unabhängig deklarieren. Für den Endbenutzer wird der zusammengeführte Inhalt der kontextsensitiven Hilfe aller Plug-ins angezeigt, die Kontexte für die ID des Fensterobjekts ergänzen.
Bitte beachten Sie, dass die vollständig qualifizierte Kontext-ID für das Fensterobjekt verwendet werden muss, da keines der Dokumentations-Plug-ins die Kontext-ID deklariert hat. Wenn mehrere Plug-ins kontextsensitive Hilfe für dieselbe Kontext-ID bereitstellen, wird zunächst der Inhalt angezeigt, der in dem Plug-in definiert ist, das den Kontext deklariert hat (das Plug-in für die Benutzerschnittstelle). Die Reihenfolge, in der zusätzliche Beschreibungen und Links angehängt werden, kann nicht garantiert werden.