Eenvoudige hulpbladen

Hulpbladen dienen om de gebruiker te begeleiden bij het uitvoeren van complexe taken met een bepaald doel. U zou bijvoorbeeld een hulpblad kunnen raadplegen om een eenvoudig Java-programma stapsgewijs te maken, te compileren en uit te voeren. U kunt hulpbladen openen via de menuoptie Help > Hulpbladen.... Ook kunt u hulpbladen starten vanaf inleidingspagina's.

U kunt hulpbladen definiëren via het extensiepunt org.eclipse.ui.cheatsheets.cheatSheetContent. De inhoud van de hulpbladen is in afzonderlijke bestanden gedefinieerd, zodat deze eenvoudig vertaald kan worden.

Een hulpblad toevoegen

Het toevoegen van een hulpblad is vrij eenvoudig. Hieronder ziet u hoe een hulpblad wordt toegevoegd door JDT voor het bouwen van een eenvoudige Java-toepassing.

<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent">
	<cheatsheet
		name="%cheatsheet.helloworld.name"
		contentFile="$nl$/cheatsheets/HelloWorld.xml"
		id="org.eclipse.jdt.helloworld">
		<description>%cheatsheet.helloworld.desc</description>
	</cheatsheet>
	...
Net zoals voor andere workbenchaanleveringen kunt u een naam, een beschrijving en een ID opgeven voor het hulpblad. De naam en beschrijving worden afgebeeld in de lijst met hulpbladen, die u kunt bekijken via de menuoptie Help > Hulpbladen.... U kunt ook een categorie voor het hulpblad definiëren om meerdere hulpbladen in een logische groep te plaatsen. Als u geen categorie opgeeft, wordt het hulpblad afgebeeld in de categorie Overige.

Dialoogvenster met hulpbladen

Items van hulpbladen

De contentbestanden bevatten de informatie zelf van de hulpbladen. De bestanden zijn van het type XML en kunt u opgeven met het kenmerk contentFile. Het pad naar het bestand is relatief ten opzichte van de directory van de plugin. (Merk op dat de variabele $nl$ wordt gebruikt in de directorynaam, wat betekent dat het bestand zich bevindt in een specifieke directory die overeenkomt met de taal van de doelomgeving.)

De bestandsindeling omvat overzichtsgegevens over het hulpblad en een beschrijving van elke stap (een item) die door de gebruiker moet worden uitgevoerd. Een item is in feite niet meer dan een gedetailleerde beschrijving van een uit te voeren stap. Toch kan een item ook betrekking hebben op een actie die kan worden gestart om een stap namens de gebruikers uit te voeren. Hieronder volgt het eerste gedeelte van het contentbestand (HelloWorld.xml) voor het Java-hulpblad.

<?xml version="1.0" encoding="UTF-8" ?>
<cheatsheet title="Eenvoudige Java-toepassing">
	<intro
		href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm">
		<description>
			Welkom bij het Java-zelfstudieprogramma "Hallo wereld". Hiermee kunt u de bekende toepassing "Hallo wereld" opbouwen en uitproberen. U maakt een Java-project en een Java-klasse om "Hallo wereld" af te beelden als de console wordt gestart. Aan de slag!
		</description>
  </intro>
	<item
		href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm"
		title="Het perspectief Java openen">
		<action
			pluginId="org.eclipse.ui.cheatsheets"
			class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective"
			param1="org.eclipse.jdt.ui.JavaPerspective"/>
		<description>
Selecteer Venster > Perspectief openen > Java in de menubalk boven aan de workbench. Hierdoor wordt het perspectief gewijzigd voor instelling van de Eclipse-workbench voor Java-ontwikkeling. Klik op "Uitvoeren" als u wilt dat het perspectief "Java" voortaan automatisch wordt geopend.
		</description>
</item>
...

Eenvoudig Java-hulpblad

De titel en de inleiding worden boven aan het hulpblad afgebeeld. Vervolgens worden de items beschreven. Het eerste item van het hulpblad beschrijft hoe u het perspectief Java kunt openen. Het kenmerk action duidt de klasse aan waarmee de actie namens de gebruiker kan worden uitgevoerd. De klasse moet IAction implementeren. Op deze manier kunt u de actieklassen hergebruiken die voor menu- of werkbalkaanleveringen zijn geschreven.

De klasse voor de actie kan optioneel ICheatSheetAction implementeren als de actie van parameters wordt voorzien of moet kunnen reageren op het hulpblad. In dit geval wordt een array met parameters en een verwijzing naar ICheatSheetManager doorgegeven aan de actie, zodat aanvullende gegevens over het hulpblad kunnen worden opgevraagd. Benodigde parameters kunt u aan de methode run van de actie doorgeven met de kenmerken paramN.

Het is raadzaam om bij acties die worden aangeroepen via hulpbladen het resultaat van de actie (geslaagd of mislukt) te laten melden als er een kans is dat de actie mislukt, bijvoorbeeld omdat de gebruiker de actie vanuit het dialoogvenster annuleert. Raadpleeg IAction.notifyResult(boolean) voor meer informatie.

Voor items hoeven geen acties te worden gedefinieerd. Als een item handmatig moet worden uitgevoerd, is een actie zelfs helemaal niet nodig. Hieronder volgt de derde stap van het Java-hulpblad, waarin de programmeercode voor de eenvoudige toepassing wordt uitgelegd. Als geen actie is opgegeven, moet in de itembeschrijving worden vermeld op welke knop moet worden gedrukt nadat de taak is voltooid.

<item
	href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm"
	title="De regel System.out.println toevoegen aan de methode main">
	<description>
Nu u de klasse HelloWorld hebt gemaakt, voegt u de volgende instructie toe aan de methode "public static void main":
System.out.println("Hallo wereld!") en slaat u de wijzigingen op. Klik vervolgens op de knop om door te gaan.
	</description>
</item>
Met behulp van aanvullende kenmerken bepaalt u of het item volledig overgeslagen kan worden en welk document moet worden geopend zodra tijdens de stap om hulp wordt gevraagd. Raadpleeg het extensiepunt org.eclipse.ui.cheatsheets.cheatSheetContent voor een beschrijving van alle beschikbare kenmerken voor hulpbladen.

Subitems

U kunt subitems definiëren om de presentatie van items verder te organiseren. In tegenstelling tot items hoeven subitems niet in een bepaalde volgorde te worden bekeken. Voor subitems kunnen ook acties worden gedefinieerd waarmee subtaken automatisch worden uitgevoerd. De beschrijving van subitemacties is hetzelfde als de beschrijving van itemacties.

Conditionele expressies en variabelen van hulpbladen

U kunt conditionele expressies gebruiken om elementen van hulpbladen te definiëren waarvan de inhoud of het gedrag afhankelijk is van bepaalde voorwaarden. U stelt een voorwaarde in via het subitemelement condition door tekenreekswaarden op te geven die per optie worden vergeleken met het kenmerk when. Voorwaarden verwijzen doorgaans naar variabelen van hulpbladen zoals in ${var}. Hierbij geldt dat var overeenkomt met de naam van de hulpbladvariabele. In enkele eenvoudige voorbeelden wordt de werking van conditionele expressies uitgelegd.

U kunt conditionele subitems gebruiken om één item uit een lijst met subitems te kiezen. Alleen het eerste subitem waarvan het kenmerk when overeenkomt met de voorwaarde, wordt opgenomen in het hulpblad. Voorbeeld:

<item ...>
	<conditional-subitem condition="${v1}">
		<subitem when="a" label="Stap voor A." />
		<subitem when="b" label="Stap voor B." />
	</conditional-subitem>
</item>
Welk subitem uit het bovenstaande item wordt gekozen, hangt af van de waarde van de variabele v1. Als de waarde van de variabele a is, wordt het eerste subitem opgenomen. Als de waarde van de variabele b is, wordt het tweede subitem opgenomen. Als de waarde van de variabele iets anders is, treedt een fout op.

Conditionele acties zijn vergelijkbaar met conditionele subitems. Het element perform-when geeft een voorwaarde aan voor het uitvoeren van één actie uit een lijst met acties. De voorwaarde wordt op dezelfde manier beschreven met een tekenreeks (vaak een variabele). De actie waarvan het kenmerk when overeenkomt met de voorwaarde, wordt uitgevoerd. Voorbeeld:

<item ...>
	<perform-when condition="${v1}">
		<action when="a" class="com.example.actionA" pluginId-"com.example" />
		<action when="b" class="com.example.actionB" pluginId-"com.example" />
	</perform-when>
</item>
De actie die moet worden uitgevoerd, wordt bepaald op basis van de waarde van de variabele v1 variabele. Als de waarde van de variabele iets anders is dan a of b, treedt een fout op.

Herhaalde subitems

Herhaalde subitems beschrijven een subitem dat kan worden uitgebreid in 0, 1 of meer vergelijkbare substappen. De substappen worden van elkaar onderscheiden met de speciale variabele ${this}. Deze variabele wordt vervangen door de waarden uit het kenmerk values. De waarde van dit kenmerk bestaat uit een reeks tekenreeksen die van elkaar gescheiden zijn door middel van een komma. Aan het kenmerk values kunt u ook een variabele toewijzen die een lijst met waarden oplevert. Voorbeeld:

<item ...>
	<repeated-subitem values="${v1}">
		<subitem label="Stap ${this}" />
	</repeated-subitem>
</item>
Als de waarde van de variabele 1,b,drie is, worden op het hulpblad drie subitems afgebeeld die alle een uniek label hebben ("Stap 1", "Stap b", "Stap drie"). De variabele kan worden gebruikt in het label of de waarde van de actieparameter. Ook kan de variabele tijdens het uitvoeren van de actie worden opgevraagd via ICheatSheetManager.

Listeners van hulpbladen

Soms wilt u andere onderdelen van de gebruikersinterface wijzigen wanneer een hulpblad actief is. U hebt bijvoorbeeld een editor die speciale annotaties afbeeldt wanneer een hulpblad begeleiding biedt voor een bewerkingstaak. U kunt dan een listener opgeven als een kenmerk van het hulpblad. Het listenerkenmerk moet de volledig gekwalificeerde naam zijn van de Java-klasse die een subklasse is van CheatSheetListener. Listeners ontvangen een melding en een ICheatSheetEvent wanneer een wijziging optreedt in de levensloop van een hulpblad (bijv. openen, sluiten of voltooien).

Kenmerken aanleveren voor bestaande hulpbladen

U kunt de extensie org.eclipse.ui.cheatsheets.cheatSheetItemExtension gebruiken om kenmerken aan te leveren voor bestaande hulpbladen. Het doel van dit extensiepunt is om plugins aanvullende knoppen te laten toevoegen voor hulp bij bepaalde stappen. De aanvullende knoppen worden naast het Help-pictogram afgebeeld.

U kunt deze methode toepassen door een kenmerk op te geven in de definitie van een item in het XML-bestand van een hulpblad. De naam van het kenmerk wordt vergeleken met andere kenmerken die zijn aangeleverd in extensies van org.eclipse.ui.cheatsheets.cheatSheetItemExtension. Raadpleeg de documentatie van extensiepunten voor meer informatie.

Verwante onderwerpen

Werken met hulpbladen
Samengestelde hulpbladen maken
Richtlijnen voor auteurs
Extensiepunt org.eclipse.ui.cheatsheets.cheatSheetContent
Specificatie van contentbestand voor hulpblad