Opret scripter for editorkomponenten med Javascript

Indledning

Fra og med version 2.5, understøtter Kates editorkomponenten scripter med ECMA-script, også kendt som Javascript.

Scripter kan kun bruges via den indbyggede kommandolinje. Kravet er at scriptet placeres i en mappe hvor Kate kan finde det, sammen med en valgfri .desktop-fil som definerer de tilhørende egenskaber. Den gyldige mappe hedder katepart/scripts i KDE's datamapper. Du kan finde datamapperne ved at udføre kommandoen kde-config --path data. Du har oftest i det mindste en system og en personlig datamappe. Naturligvis er scripter i systemdatamappen tilgængelige for alle brugere på systemet, mens de i den personlige mappe kun er tilgængelige for dig.

Bemærk

Denne funktion er eksperimentel, og kommer formodentlig til at ændres i den fremtidige udvikling.

Vi ved at mange vil være skuffede over at man ikke kan tilføje scripter i menuen, eller tildele dem genvejstaster. Vi er kede af dette, men en gang i fremtiden vil det formodentlig komme til at være muligt.

Det er også endnu ikke muligt at sende en argumenter til scripter. Hav tålmodighed, så kan det tilføjes i en lys fremtid.

Kates programmeringsgrænseflade for Javascript

Her angives det fuldstændige sæt funktioner og egenskaber som er tilgængelige i objekterne document og view. Desuden kan du naturligvis bruge alle standardobjekt såsom Math, String, Regex og så videre.

Når et script køres, er objektet document det nuværende dokument, og objektet view er den nuværende visning.

Bemærk

Argumenttyperne bruges naturligvis ikke i Javascript for øjeblikket, de er der kun hvor for at angive hvilken slags værdi som funktionerne forventer sig.

Globale funktioner

debug( streng) [funktion]

parametre

streng strengen der kommer som uddata

Skriver strengen ud på standardfejludskriften med kdDebug(). Et særligt udskriftsområde bruges for udskriften, som indledes med Kate (KJS Scripts):.

Programmeringsgrænsefladen document

document.attribute( linje , søjle ); [funktion]

Parametre

uint linje Linjen for positionen hvor attributten findes.
uint søjle Søjlen for positionen hvor attributten findes.

Returnerer den numeriske identifikator for dokumentpositionen [linje,søjle]. Attributten repræsenterar tekstens synlige udseende eller stil, og bruges også til at beregne syntaksfremhævningen for en bestemt del af teksten i blandet format såsom HTML eller PHP.

document.canBreakAt( Char c, uint attribut ); [funktion]

Parametre

c Tegnet der skal testes
attribut Attributten på positionen for c.

Returnerer om linjebrud er tilladt ved tegnet c med attributten attribut. Resultatet bestemmes ved at forespørge attributten som ejer fremhævningen om hvilke tegn som tillades ved linjebrud.

document.canComment( uint start_attribut, uint slut_attribut ); [funktion]

Parametre

start_attribut Attributten i begyndelsen af området som skal ændres til en kommentar.
slut_attribut Attributten i slutningen af området som skal ændres til en kommentar.

Returnerer om start_attribut og slut_attribut hører til samme syntaksfremhævningssystem. Hvis de gør det, er det fornuftigt.

Eksempel 6.5. using canComment

if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) {
    // 1,0 og 5,0 hører til samme syntaksfremhævningssystem
}

document.clear(); [funktion]

Rydder dokumentet.

document.commentStart( uint attribut ); [funktion]

Parametre

attribut Attributten for teksten som strengen commentStart skal hente.

Returnerer strengen som kræves for at starte en flerlinjekommentar for tekst med attributten, eller en tom streng hvis flerlinjekommentarer ikke understøttes for den tekst.

document.commentMarker( uint attribut ); [funktion]

Parametre

attribut Attributten for teksten som strengen commentMarker skal hente

Returnerer strengen som bruges til at markere resten af linjen som en kommentar med attributten, eller en tom streng hvis kommentarer for enkelte linjer ikke understøttes for teksten.

document.commentEnd( uint attribut ); [funktion]

Parametre

attribut Attributten for teksten som strengen commentEnd skal hente

Returnerer strengen som kræves for at afslutte en flerlinjekommentar for tekst med attributten, eller en tom streng hvis flerlinjekommentarer ikke understøttes for teksten.

document.editBegin(); [funktion]

Start en redigeringsgruppe. Alle handlinger som udføres inden kaldet editEnd() grupperes som en handling at fortryde.

document.editEnd(); [funktion]

Afslut en redigeringsgruppe.

document.highlightMode; [egenskab:skrivebeskyttet]

Navnet på dokumentets fremhævningstilstand, såsom JavaScript eller C++. Hvis ingen syntaksfremhævningstilstand er indstillet for dokumentet, er værdien None. Bemærk at du skal bruge det engelske navn hvis det adskiller sig fra det oversatte.

document.indentMode; [egenskab:skrivebeskyttet]

Navn på dokumentets indrykningstilstand, såsom normal eller cstyle. Husk at hvis ingen indrykningstilstand er indstillet er værdien none.

document.indentWidth; [egenskab:skrivebeskyttet]

Indstiller indrykningsbredden sat for dokumentet. Dette bruges kun hvis du indrykker med mellemrum.

document.insertLine( uint linje, streng tekst ); [funktion]

Parametre

linje dokumentets linjenummer
tekst tekst at indsætte

Indsætter en ny linje med teksten tekst på linjen linje.

document.insertText( uint linje, uint søjle, streng tekst ); [funktion]

Parametre

linje linjenummeret
søjle søjlen
tekst teksten som skal indsættes

Indsætter teksten tekst på linjen linje og søjlen søjle.

document.length(); [funktion]

Returnerer dokumentets størrelse i byte.

document.lines(); [funktion]

Returnerer antal linjer i dokumentet.

document.mixedIndent; [egenskab:skrivebeskyttet]

En boolesk værdi som angiver om indstillingen for blandet indrykning er aktiv for dokumentet. Hvis dette er tilfældet, optimeres indrykningen til at indeholde en blanding af tabulatortegn og mellemrum, ligesom den som bruges af editoren Emacs.

document.removeLine( uint linje ); [funktion]

Parametre

linje linjenummer

Fjerner dokumentlinjen linje.

document.removeText( uint startlinje, uint startsøjle, uint slutlinje, uint slutsøjle ); [funktion]

Parametre

startlinje angiver startlinjen
startsøjle angiver startsøjlen
slutlinje angiver slutlinjen
slutsøjle angiver slutsøjlen

Fjerner tekstområdet fra linjen startlinje og søjlen startsøjle frem til linjen slutlinje og søjlen slutsøjle.

document.setText( streng tekst ); [funktion]

Parametre

tekst dokumentets tekst

Ændrer hele dokumentets indhold til tekst.

document.spaceIndent; [egenskab:skrivebeskyttet]

En boolesk værdi som angiver om indrykning med mellemrum er aktiv for dokumentet. Hvis dette er tilfældet, indrykkes dokumentet med indentWidth mellemrum pr niveau, ellers sker indrykning med et tabulatortegn pr niveau.

document.textFull(); [funktion]

Returnerer hele dokumentets tekst. Hvis teksten omfatter flere linjer er linjebrudstegnet \n.

document.textLine( uint linje ); [funktion]

Parametre

linje linjen

Returnerer teksten på linjen linje.

document.textRange( uint startlinje, uint startsøjle, uint slutlinje, uint slutsøjle ); [funktion]

Parametre

startlinje angiver startlinjen
startsøjle angiver startsøjlen
slutlinje angiver slutlinjen
slutsøjle angiver slutsøjlen

Returnerer det angivne tekstområde. Hvis området omfatter flere linjer er linjebrydningstegnet \n.

Programmeringsgrænsefladen view

view.clearSelection(); [funktion]

Afmarkerer al tekst.

view.cursorColumn(); [funktion]

Returnerer den nuværende markørsøjle (tabulatortegn ekspanderes).

view.cursorColumnReal(); [funktion]

Returnerer den nuværende rigtige markørsøjle (tabulatortegn regnes som et tegn).

view.cursorLine(); [funktion]

Får nuværende markørs linje tilbage.

view.hasSelection(); [funktion]

Returnerer true hvis visningen indeholder markeret tekst, ellers false.

view.removeSelectedText(); [funktion]

Fjerner den markerede tekst, hvis visningen har en markering.

view.selectAll(); [funktion]

Markerer al tekst.

view.selection(); [funktion]

Returnerer den markerede tekst. Hvis markeringen omfatter flere linjer er linjebrudstegnet \n.

view.selectionEndColumn; [egenskab:skrivebeskyttet]

Returnerer markeringens afsluttende søjle.

view.selectionEndLine; [egenskab:skrivebeskyttet]

Returnerer markeringens afsluttende linje.

view.selectionStartColumn; [egenskab:skrivebeskyttet]

Returnerer markeringens indledende søjle.

view.selectionStartLine; [egenskab:skrivebeskyttet]

Returnerer markeringens indledende linje.

view.setCursorPosition( uint linje, uint søjle ); [funktion]

Parametre

linje Angiver linjen for markøren.
søjle Angiver søjlen for markøren.

Indstiller indtastningsmarkørens position i visningen til [linje, søjle]. Dette indstiller markørens position på visuel måde, dvs. at et tabulatortegn regnes om til tabwidth afhængig af positionen på linjen. Markørens position bliver synlig. Både linje og søjle begynder på nul.

view.setCursorPositionReal( uint linje, uint søjle ); [funktion]

Parametre

linje Angiver linjen for markøren.
søjle Angiver søjlen for markøren.

Indstiller indtastningsmarkørens position i visningen til [linje, søjle]. Dette indstiller strengpositionen, dvs. at et tabulatortegn regnes som 1. Markørens position bliver synlig. Både linje og søjle begynder på nul.

view.setSelection( uint startlinje, uint startsøjle, uint slutlinje, uint slutsøjle ); [funktion]

Parametre

startlinje angiver startlinjen
startsøjle angiver startsøjlen
slutlinje angiver slutlinjen
slutsøjle angiver slutsøjlen

Opretter en markering fra linjen startlinje og søjlen startsøjle frem til linjen slutlinje og søjlen slutsøjle.

Eksempel 6.6. Et eksempelscript

Som et eksempel laver vi et lille script som laver markeringen om til store bogstaver. Det er åbenbart at vi først skal kontrollere om en markering findes. Hvis dette er tilfældet, henter vi teksten, ændrer den til store bogstaver og erstatter den med den nye. En implementering skulle kunne se sådan her ud:

if ( view.hasSelection() )
{
  // laver markeringen om til store bogstaver
  column = view.selectionStartColumn;
  line = view.selectionStartLine;

  selection = view.selection().toUpperCase();

  document.editBegin();
  view.removeSelectedText();
  document.insertText( line, column, selection );
  document.editEnd();
}

For at gruppere handlingerne sammen så de fortrydes med en enkelt aktivering af Fortryd, indkapsler vi linjerne

view.removeSelectedText()

document.insertText()

med

document.editBegin()

document.editEnd()

Eksempel 6.7. Et eksempel på en .desktop-fil

Her er et eksempel på en .desktop-fil som følger med scriptet ovenfor.

# Eksempel på en .desktop-fil
[Desktop Entry]
Encoding=UTF-8
Name=Kate Part JavaScript Uppercase
Comment=Script to uppercase the selection
X-Kate-Command=uppercase-selection
X-Kate-Help=<p>Usage: <code>uppercase-selection</code></p>

Som du kan se kan du definere tegnsættet, angive et navn, en kommentar, en hjælpetekst med X-Kate-Help og kommandolinjenavnet via X-Kate-Command. Indgangene Name, Comment og X-Kate-Help oversættes automatisk til andre sprog af KDE's oversættelsesgrupper, hvis filerne findes i KDE's SVN-arkiv.

Sæt alting sammen

Kate søger i scriptmapperne (se ovenfor) efter filerne *.js. For hver fil kontrolleres om der findes en tilsvarende .desktop-fil. I tilfældet uppercase.js ville der blive ledt efter uppercase.desktop.

Hvis en .desktop-fil ikke kan findes, registreres scriptet på kate-partens kommandolinje med filnavnet uden det afsluttende .js, så i vort tilfælde ville det være uppercase. Hvis kommandonavnet er godt, og du ikke behøver de ekstra funktioner som en .desktop-fil sørger for behøver du ikke en .desktop-fil i det hele taget.

Hvis en .desktop-fil findes, læser kate-parten navnet som scriptet skal registreres som fra indgangen X-Kate-Command i .desktop-filen, for eksempel X-Kate-Command=uppercase-selection.

forrige	hjem	næste
Brug af kodefoldning	op	Menuindgange