Kontextsensitive Hilfe beschreiben und packen

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.

Kontextsensitive Hilfe von mehreren Plug-ins

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.