Nødvendige ændringer, når du benytter 3.1-mekanismer og API'er

I dette afsnit beskrives de ændringer, der er nødvendige, hvis du forsøger at ændre din 3.0-plugin, så den kan benytte 3.1-mekanismer og -API'er.

Platformsunderstøttelse af fortryd/gentag

Eclipse 3.1 indeholder en ny infrastruktur, som definerer funktioner, der ikke kan udføres, og en fælles funktionshistorik, som holder styr på funktioner, der er udført, fortrudt og udført igen. De forskellige fortrydstrukturer, som add-on plugins leverer, skal efterhånden overføres til platformsunderstøttelsen, så disse strukturers klienter i højere grad kan integreres med platformen og stille de funktioner, der kan fortrydes, til rådighed for fortrydfunktioner i andre plugin-oversigter og -editorer. Der er flere grundlæggende oplysninger i Undoable operations-dokumentationen vedrørende tilføjelse af fortrydunderstøttelse i en plugin. Plugins, som allerede definerer fortrydunderstøttelse eller bruger en anden struktur, kan overføres til den nye fortrydunderstøttelse trinvist, som beskrevet nedenfor.

Overfør plugin-specifikke funktionsklasser (kommando) til IUndoableOperation

Plugins, som allerede definerer klasser, der beskriver deres fortrydbare funktioner, skal tilføje en implementering til grænsefladen IUndoableOperation til deres funktions/kommandoklasser. Plugins kan om nødvendigt stadig benytte ældre strukturer til administration af historik (kommandostak), men ved at stille en grænseflade til rådighed for IUndoableOperation kan en plugins klienter bruge samme funktioner i platformens funktionshistorik, og blande og matche fortrydbare funktioner fra forskellige plugins. Denne strategi svarer til den, der blev brugt af SDK-teksteditorerne ved overførsel til den nye funktionsstruktur. Hvis det ikke er muligt at tilknytte grænsefladen direkte vha. mapping, kan indpakninger bruges til at tilknytte IUndoableOperation-protokollen vha. mapping til ældre fortrydobjekter. Denne strategi bruges af Platform/JDT-refactoring-understøttelsen. Overførsel af funktions/kommandoklasserne til IUndoableOperation er et vigtigt trin, fordi det tillader, at funktioner, der kan fortrydes, fra forskellige strukturer udnyttes af andre plugins, uden at nogen af plugins'ene er overført fuldstændigt.

Overfør kommandostakke med IOperationHistory

Når først fortrydbare funktioner eller kommandoer udtrykkes i IUndoableOperation, kan plugins, der definerer en fortryd-historik (kommandostak) med henblik på at holde styr på funktioner, der kan fortrydes og gentages, overføres til platformsfunktionshistorikken ved at definere en IUndoContext, som repræsenterer deres fortryd-historik. Fortryd-historik, som tidligere blev administreret lokalt, kan flettes ind i den fælles funktionshistorik ved at definere en entydig fortrydkontekst for hver del eller for hvert modelobjekt, hvor den relevante fortryd-kontekst tilføjes til hver funktion, og funktionen derefter tilføjes til platformsfunktionshistorikken. Du kan implementere fortrydhistorikker med en mere globalt omfang ved at definere en entydig fortrydkontekst, som repræsenterer fortrydintervallet, og ved at tildele konteksten til hver enkelt funktion og derefter tilføje funktionen til platformsfunktionshistorikken. Der er flere eksempler i Undoable operations-dokumentationen på oprettelse af fortrydkontekster, tildeling af dem og tilføjelse af funktioner til platformsfunktionshistorikken.

Definér fortrydbare funktioner globalt for arbejdsbænken

Plugins, som vil have, at deres funktioner kan fortrydes fra arbejdsbænkoversigterne, f.eks. Navigator eller Package Explorer, skal tildele arbejdsbænkfortrydkonteksten til deres funktioner. Der er flere oplysninger i Undoable operations-dokumentationen om denne fortrydkontekst, og hvordan den kan hentes af såvel arbejdsbænken som hovedløse plugins.

Behandlere til fortryd/gentagfunktioner på platformen

Plugins, som ikke definerer en fortrydinfrastruktur eller fortrydbare funktioner, men som gerne vil give adgang til platformens fortrydhistorik, skal overveje at ændre målet for de globale behandlere til fortryd- og gentagfunktioner med de nye fælles behandlere til fortryd- og gentagfunktioner. Der skal tilknyttes en fortrydkontekst til de funktionsbehandlere, hvis fortryd- og gentaghistorik skal vises. Plugins kan bruge deres lokalt definerede fortryd-kontekster til at vise en "delvis lokal" fortryd- og gentaghistorik. Arbejdsbænkens fortrydkontekst kan bruges til at vise fortryd- og gentaghistorik for hele arbejdsbænken. Dokumentationen om fotrydbare funktioner har et fyldestgørende eksempel herpå.

Overfør tekstfunktioner til behandlere til fælles funktioner

Det er lidt anderledes at overføre fortryd- og -gentagfunktioner i en teksteditor end det er at udføre en almindelig ændring af målet for de globale behandlere for fortryd/gentagfunktionerne. AbstractTextEditor-strukturen definerer almindelige tekstfunktioner ved hjælp af en TextOperationAction, der er gjort parametrisk. Disse funktioner gemmes lokalt i strukturen og bruges til at afsende forskellige kommandoer til en editors tekstfunktionsmål. For at fortrydelse af tekst skal kunne fungere korrekt, afhænger teksteditorstrukturen af tilstedeværelsen af tekstfunktioner, der har de korrekte id'er (ITextEditorActionConstants.REDO og ITextEditorActionConstants.UNDO).

AbstractTextEditor er overført, så den opretter de fælles funktionsbehandlere, samtidig med at den tildeler dem til TextOperationAction-tabellen med deres gamle id'er. På denne måde kan de nye fortryd- og gentag-funktionsbehandlere hentes vha. de gamle teknikker til hentning af funktionen og udførelse af en funktion. Teksteditorer i AbstractTextEditor-hierarkiet overtager denne funktionsmåde.

Editorer, som ikke overtager denne funktionsmåde fra AbstractTextEditor, bør overveje en overførsel af eventuelle eksisterende fortryd- og gentagfunktioner, så de kan benytte de nye behandlere. Editorer med ældre fortryd- og gentag-TextOperationActions understøttes stadig lokalt, fordi JFace-tekst-fortryd-administrations-API'et, som disse funktioner benyttede, stadig understøttes. Markeringerne af fortryd- og gentagfunktionerne er ikke i overensstemmelse med de nye Eclipse SDK-fortryd/gentagfunktioner, der viser navnet på den tilgængelige fortryd- eller gentagfunktion. For at du kan oprette behandlere til en fælles fortryd- og gentagfunktion, skal den fortrydkontekst, der blev brugt af tekstfremvisningsprogrammets fortrydadministrator, bruges, når du opretter funktionsbehandlerne, og disse behandlere skal angives i editorer vha. den relevante ITextEditorActionConstants-id. AbstractTextEditor.createUndoRedoActions() og AbstractTextEditor.getUndoContext() indeholder detaljerede eksempler. Editorer, som er afhængige af en EditorActionBarContributor-underklasse for at kunne tilføje til menulinjen i deres editorer, kan bruge en lignende teknik ved at oprette behandlere til fortryd- og gentagfunktioner og angive dem, når den aktive editor er angivet.

Udvidelser til hjælpen

Informationssøgning

Plugins, som bidrager med søgesider i dialogboksen Søg, skal overveje at overføre alle deres informationssøgninger til samlede søgeprogrammer. Siden 3.1 har al informationssøgning været adskilt fra den gamle arbejdsbænksøgning. Informationssøgeprogrammer udføres parallelt med, at baggrundsjob og deres resultater samles i den nye hjælpeoversigt. Der er flere oplysninger i søgehjælpen.

Dynamisk hjælp

Den nye dynamiske hjælpeoversigt arbejder med eksisterende kontekst-id'er, som er statisk tilknyttet elementer i arbejdsbænkdele og -dialogbokse. Hvis du imidlertid selv opfanger en hjælpeaktivitet og får vist hjælpen, kan den dynamiske hjælp ikke længere vise noget, du kan bruge. Du kan løse problemet ved at prøve at tilpasse den nye IContextProvider-grænseflade som beskrevet i dokumentet Dynamic Context Help.

JFace-indstillingslagre

Som i release 3.1 er den org.eclipse.jface.preference.IPreferenceStore, der returneres fra AbstractUIPlugin.getPreferenceStore(), en forekomst af org.eclipse.ui.preferences.ScopedPreferenceStore. ScopedPreferenceStore anvender API'et org.eclipse.core.runtime.preferences til at administrere indstillinger. I version 3.0 blev kompatibilitetslaget anvendt som grænseflade til en forekomst af org.eclipse.core.runtime.Preferences.

I version 3.1 er noget af flertydigheden fjernet fra IPreferenceStore, så den er mere specifik i forbindelse med de værdityper, der er sendt i indstillingsændrede aktiviteter. IPreferenceStore fra AbstractUIPlugin#getPreferenceStore fungerer på samme måde som før, men den er nu angivet mere klart.

Hvis org.eclipse.jface.util.IPropertyChangeListener tilføjes til en IPreferenceStore kan det muligvis give to typer af gamle og nye værdier - indtastede eller strengrepræsentationer. En aktivitet, der er genereret af et kald til et indtastet IPreferenceStore-API (f.eks. setValue(String, boolesk værdi), genererer en indtastet aktivitet. Det er dog også muligt, at aktiviteter bliver videreført fra de primære runtime-indstillinger, som genererer en indtastet aktivitet (f.eks. en import af indstillinger). Egenskabslyttefunktioner skal klargøres til begge. Bemærk også, at indtastede aktiviteter ikke viderefører primitive typer, så et kald til setValue(String, boolesk værdi) medfører en aktivitet, hvor oldValue og newValue er primitive Booleans.agating-typer.

putValue: IPreferenceStore.putValue(String, String-værdi) genererer ikke en ændringsaktivitet. Dette API er beregnet til at blive brugt til private indstillinger, som ingen lyttefunktion skal reagere på.

initializeDefaultPreferences. Dette API blev forældet i Eclipse 3.0, da det kun aktiveres, hvis kompatibilitetslaget bliver anvendt. Da de fleste plugins er baseret på, at AbstractUIPlugin#getPreferenceStore henter deres indstillingslager, blev dette aktiveret tidligere ved start af plugin'en. Hvis din plugin ikke selv anvender kompatibilitetslaget, bliver denne metode muligvis ikke aktiveret. Det anbefales, at du opretter en org.eclipse.core.runtime.preferences.AbstractPreferenceInitializer til håndtering af initialisering af indstillinger.