Enkla lathundar

Lathundar är till hjälp för användaren att utföra en serie komplexa uppgifter eller nå ett visst mål. En lathund kan t.ex. användas till att leda användaren genom alla steg som krävs för att skapa, kompilera och köra ett enkelt Java-program. Lathundar startas via menyalternativet Hjälp > Lathundar... . Lathundar kan även startas från en introduktionssida.

Lathundar definieras med utökningspunkten org.eclipse.ui.cheatsheets.cheatSheetContent. Själva lathundsinnehållet definieras i en separat fil så att det enklare kan översättas till andra språk.

Tillhandahålla en lathund

Processen att bidra med en lathund är ganska rättfram. Låt oss ta en titt på en lathund som bidragits av JDT för byggande av en enkel Java-tillämpning.

<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>
	...
Mycket likt andra arbetsmiljöbidrag kan ett namn, en beskrivning och ett ID anges för lathunden. Namnet och beskrivningen visas när användaren visar listan Hjälp > Lathundar... . Du kan även definiera en kategori för lathunden om du vill placera flera lathundar i en logisk gruppering. Om ingen kategori anges visas lathunden i kategorin Övrigt.

Dialogrutan Lathundar

Lathundsobjekt

Det verkliga arbetet med lathundar görs i innehållsfilen. Innehållsfilen är en XML-fil vars namn och placering anges i attributet contentFile. Sökvägen för filen anges i förhållande till insticksprogrammets katalog. (Lägg märke till användningen av variabeln $nl$ i katalognamnet, vilket betyder att filen finns i en katalog som är specifik för målmiljöns språk.)

Filformatet självt innehåller översiktsinformation om lathunden följt av en beskrivning av varje steg (kallat ett objekt) som användaren utför. I sin enklaste form är ett objekt vara en utförlig beskrivning av det steg som användaren ska utföra. Däremot kan ett objekt även ange en åtgärd som kan köras för att utföra steget i användarens ställe. Låt oss ta en titt på den första delen i innehållsfilen (HelloWorld.xml) för Java-lathunden.

<?xml version="1.0" encoding="UTF-8" ?> 
<cheatsheet title="Simple Java Application">
	<intro 
		href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm">
		<description>
Welcome to the Hello, World Java tutorial.
It will help you build the famous "hello world" application and try it out. You will create a java project, and a java class that will print "hello world" in the console when run.
Let's get started!
		</description>
</intro>
	<item
		href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm"
		title="Open the Java Perspective">
		<action
			pluginId="org.eclipse.ui.cheatsheets"
			class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective"
			param1="org.eclipse.jdt.ui.JavaPerspective"/>
		<description>
Select Window->Open Perspective->Java in the menu bar at the top of the workbench.
Med det här ändras perspektivet så att
			Eclipse-miljön konfigureras för Java-utveckling.
You can click the "Click to Perform" button to have the "Java" perspective opened automatically.
		</description>
</item>
...

enkel java-lathund

Titeln och introduktionsinformationen visas längst upp i lathunden. Därefter beskrivs objekten. Det första objektet för den här lathunden beskriver hur man öppnar Java-perspektivet. Ännu bättre är attributet action som specificerar en klass som kan användas till att köra åtgärden i användarens ställe. Klassen måste implementera IAction. Detta är ganska bekvämt eftersom det tillåter dig återanvända de åtgärdsklasser som skrivits för meny- eller verktygsfältsbidrag.

Klassen för åtgärden kan dessutom implementera ICheatSheetAction om åtgärden använder parametrar eller måste vara medveten om lathunden och dess läge. I det här fallet skickas åtgärden som en matris av parametrar och en hänvisning till ICheatSheetManager så att den kan begära ytterligare information om lathunden. Alla nödvändiga parametrar kan skickas till åtgärdens körmetod med hjälp av paramN-attribut.

Det rekommenderas stark att åtgärder som anropas från lathunden rapporterar en lyckad/misslyckad utgång om körningen av åtgärden kan misslyckas. (Ett exempel: användaren kan avbryta åtgärden från dess dialogruta.) Se IAction.notifyResult(boolean) för mer information.

Objekt måste inte definiera åtgärder. Om objektet måste utföras manuellt av användaren behöver du inte ange någon åtgärd alls. Nedan är det tredje steget i Java-lathunden som bara talar om för användaren hur han eller hon ska koda den enkla tillämpningen. När ingen åtgärd specificeras, måste objektbeskrivningen instruera användaren att klicka på rätt knapp när åtgärden har slutförts.

<item
	href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm"
	title="Add a System.out.println line in your main method">
	<description>
Now that you have your HelloWorld class,
In the "public static void main" method, add the following statement:  System.out.println("Hello world!"); and save your changes. Press the "click when done" button below when finished.
	</description>
</item>
Ytterligare attribut styr huruvida objektet kan hoppas över helt och vilket dokument som ska visas om använder begär hjälp under steget. Se dokumentationen för utökningspunkten org.eclipse.ui.cheatsheets.cheatSheetContent för en beskrivning av alla attribut som kan definieras i en lathund.

Underobjekt

Underobjekt kan definieras för att ytterligare organisera presentationen av ett objekt. Till skillnad från objekt, behöver inte underobjekt besökas i en viss ordning. Underobjekt kan även definiera åtgärder som automatiskt utför underåtgärden för användaren. Underobjektsåtgärder beskrivs på samma sätt som objektåtgärder.

Villkorsuttryck och lathundssvariabler

Villkorsuttryck kan användas till att definiera lathundsselement vars innehåll eller beteende beror på att ett visst villkor uppfylls. Villkor beskrivs i elementet condition för ett underobjekt med godtyckliga strängvärden som matchas med attributet when för varje val. Villkor hänvisar vanligen till lathundssvariabler med formatet ${var}, där var hänvisar till namnet på en lathundssvariabel. Några få exempel bidrar till att demonstrera hur villkorsuttryck fungerar.

.Villkorliga underobjekt kan användas till att välja ett underobjekt från en lista med möjliga underobjekt. Det är bara det första underobjekt vars when-attribut matchar villkorsattributet som tas med i lathunden. Exempel:

<item ...>
	<conditional-subitem condition="${v1}">
		<subitem when="a" label="Step for A." />
		<subitem when="b" label="Step for B." />
	</conditional-subitem>
</item>
Det här objektet specificerar två möjliga underobjekt som beror på värdet på variabeln v1. Om variabelvärdet är a, tas det första underobjektet med. Om variabelvärdet är b, tas det andra underobjektet med. Om variabeln inte är något av värdena, ses detta som ett fel.

Villkorsåtgärder påminner om villkorliga underobjekt. Elementet perform-when specificerar ett villkor som utför en åtgärd bland en lista med möjliga åtgärder. Villkoret beskrivs på samma sätt, med en godtycklig sträng som ofta hänvisar till en variabel. Åtgärden vars when-attribut matchar villkoret är den som sedan utförs. Exempel:

<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>
Den åtgärd som ska utföras väljs ut baserat på värdet på variabeln v1. Om variabelvärdet varken är a eller b, ses detta som ett fel.

Upprepade underobjekt

Upprepade underobjekt beskriver ett underobjekt som kan utökas till 0, 1 eller fler liknande understeg. Understegen individualiseras med specialvariabeln ${this}. Denna variabel ersätts av de värden som anges i attributet values. Värdeattributet är en sträng med värden som avgränsas med komman. En variabel som utökas till en lista med värden kan användas i värdeattributet. Exempel:

<item ...>
	<repeated-subitem values="${v1}">
		<subitem label="Step ${this}" />
	</repeated-subitem>
</item>
Om variabelns värde är 1,b,three, visas tre underobjekt i lathunden, där var och ett har en unik etikett ("Step 1," "Step b," "Step three"). Variabeln kan användas i etikettens eller åtgärdens paramatervärde. Den kan även nås från ICheatSheetManager under tiden som åtgärden utförs.

Lathundslyssnare

I vissa fall kan du vilja ändra andra delar av ditt UI om en lathund är aktivt. Ett exempel: du kanske har en redigerare som visar specialkommentater om en lathund leder användaren genom en redigeringsuppgift. I så fall kan du ange en lyssnare som ett attribut för lathunden. Lyssnarattributet måste vara det fullständigt kvalificerade namnet på en Java-klass som har CheatSheetListener som underklass. Lyssnare mottar meddelanden tillsammans med en ICheatSheetEvent när det uppstår ändringar i lathundens livscykel, t.ex. när det öppnas, stängs eller slutförs.

Tillhandahålla attribut till en befintlig lathund

Utökningenorg.eclipse.ui.cheatsheets.cheatSheetItemExtension kan användas till att bidra med godtyckliga attribut till en befintlig lathund. Syftet med denna utökningspunkt är att tillåta att en insticksmodul lägger till ytterligare knappar som hjälpa användaren i ett givet steg. Dessa knappar visas bredvid hjälpikonen.

Om du vill använda denna mekanism kan du definiera ett godtyckligt attribut i en objektdefinition i lathundens XML-fil. Attributnamnet matchas mot alla attribut som bidras i utökningar avorg.eclipse.ui.cheatsheets.cheatSheetItemExtension. Se utökningspunktens dokumentation för mer information.

Relaterade länkar

Arbeta med lathundar
Skapa sammansatta lathundar
Sammanställa riktlinjer
utökningspunkten org.eclipse.ui.cheatsheets.cheatSheetContent
Innehållsfilsspecifikation för lathund