# Oversigt over KDE's arkitektur

Bernd Gehrmann

    bernd@kdevelop.org

2001 2002 Bernd Gehrmann
&FDLNotice;

Denne dokumentation giver en oversigt over KDE-udviklingsmiljøet.

KDE arkitektur udvikling programmering

## Biblioteksstruktur

### Bibliotek ordnede efter navn

tdecore

  Biblioteket tdecore er det grundlæggende programskelet for alle KDE-baserede programmer. Det giver adgang til konfigurationssystemet, håndtering af kommandolinjen, indlæsning og håndtering af ikoner, visse særlige slags interproceskommunikation, filhåndtering og diverse andre værktøjer.

tdeui

  Biblioteket `tdeui` sørger for mange grafiske komponenter og standarddialoger som Qt ikke har eller som har flere funktioner end de tilsvarende i Qt. Det indeholder også flere grafiske kontroller som er delklasser af dem i Qt, men er bedre integrerede med KDE-desktoppen derved at de respekterer brugerindstillinger.

tdeio

  Biblioteket `tdeio` indeholder funktioner for asynkron, netværkstransparent I/O og adgang til håndtering af Mime-typer. Det sørger også for KDE's fildialog og dets hjælpeklasser.

kjs

  Biblioteket `kjs` sørger for en implementering af Javascript.

tdehtml

  Biblioteket `tdehtml` indeholder TDEHTML-delen, en HTML-søgekomponent, DOM-grænseflade og tolk, inklusive grænseflade til Java og Javascript.

### Grupperede klasser

Centralt programskelet: klasser som næsten alle programmer har brug for.

- TDEApplication

  Initierer og styrer et KDE-program.

- TDEUniqueApplication

  Sørger for at kun en instans af et program kan køre samtidigt.

- TDEAboutData

  Indeholder information for dialogen Om.

- TDECmdLineArgs

  Behandling af kommandolinjeflag.

Konfigurationsindstillinger: adgang til KDE's hierarkiske konfigurationsdatabase, globale indstillinger og programressourcer.

- TDEConfig

  Giver adgang til KDE's konfigurationsdatabase.

- TDESimpleConfig

  Adgang til enkle, ikke-hierarkiske konfigurationsfiler.

- TDEDesktopFile

  Adgang til `.desktop`-filer.

- TDEGlobalSettings

  Bekvem adgang til indstillinger som ikke er programspecifikke.

Fil- og URL-håndtering: afkodning af URL'er, midlertidige filer, osv.

- KURL

  Repræsenterer og tolker URL'er.

- KTempFile

  Opretter entydige filer for midlertidig data.

- KSaveFile

  Tillader at filer gemmes atomisk.

Interproceskommunikation: DCOP-hjælpeklasser og start af underprocesser.

- TDEProcess

  Starter og styrer underprocesser.

- KShellProcess

  Starter underprocesser via en skal.

- PtyProcess

  Kommunikation med underprocesser via en pseudoterminal.

- KIPC

  Enkel IPC-mekanisme som bruger X11-klientmeddelelser.

- DCOPClient

  DCOP-meddelelser.

- KDCOPPropertyProxy

  En proxyklasse som offentliggør Qt-egenskaber via DCOP.

- KDCOPActionProxy

  En proxyklasse som offentliggør en DCOP-grænseflade for handlinger.

Værktøjsklasser: hukommelseshåndtering, regulære udtryk, strenghåndtering, tilfældige tal.

- KRegExp

  Matchning af POSIX regulære udtryk.

- KStringHandler

  En overdådig grænseflade for strenghåndtering.

- TDEZoneAllocator

  Effektiv hukommelsestildeling for store grupper af små objekter.

- KRandomSequence

  Opret pseudotilfældige tal.

Genvejstaster: klasser som hjælper med at oprette overensstemmende tastebindninger over hele desktoppen.

- TDEAccel

  Samling af genvejstaster.

- TDEStdAccel

  Let adgang til de almindelige genvejstaster.

- Samling af genvejstaster som gælder for hele systemet.

Billedbehandling: ikonindlæsning og -håndtering.

- TDEIconLoader

  Indlæser ikoner som passer med temaet.

- TDEIconTheme

  Hjælpeklasser for TDEIconLoader.

- KPixmap

  En pixmap-klasse med udvidede gittermuligheder.

- KPixmapEffect

  Pixmapeffekter såsom toning og mønster.

- KPixmapIO

  Hurtig konvertering mellem TQImage og QPixmap.

Træk og slip: træk objekter for farver og URL'er.

- KURLDrag

  Trækobjekt for URL'er.

- KColorDrag

  Trækobjekt for farver.

- KMultipleDrag

  Tillader at trækobjekter laves ud fra flere andre.

Automatisk komplettering

- TDECompletion

  Generel automatisk komplettering af strenge.

- KURLCompletion

  Automatisk komplettering af URL'er.

- KShellCompletion

  Automatisk komplettering for kørbare programmer.

Grafiske kontroller: klasser for listevisninger, linealer, farvevalg, osv.

- TDEListView

  En version af QListView som følger KDE's systemindstillinger.

- TDEListBox

  En version af QListBox som følger KDE's systemindstillinger.

- TDEIconView

  En version af QIconView som følger KDE's systemindstillinger.

- KLineEdit

  En version af QLineEdit med understøttelse for komplettering.

- KComboBox

  En version af QComboBox med understøttelse for komplettering.

- TDEFontCombo

  Et dropned-felt for at vælge skrifttyper.

- KColorCombo

  Et dropned-felt til at vælge farver.

- KColorButton

  En knap til at vælge farver.

- KURLCombo

  Et dropned-felt til at vælge filnavne og URL'er.

- KURLRequester

  En linjeeditor til at vælge filnavne og URL'er.

- KRuler

  En linealkontrol.

- KAnimWidget

  Animeringer.

- KNumInput

  En kontrol til at indtaste tal.

- KPasswordEdit

  En kontrol til at indtaste kodeord.

Dialoger: dialoger med fuldstændig funktion for valg af filer, farver og skrifttyper.

- KFileDialog

  En dialog til valg af filer.

- KColorDialog

  En dialog til valg af farver.

- TDEFontDialog

  En dialog til valg af skrifttype.

- TDEIconDialog

  En dialog til valg af ikoner.

- KKeyDialog

  En dialog til at redigere tastaturbindinger.

- KEditToolBar

  En dialog til at redigere værktøjslinjer.

- KTipDialog

  En dialog med dagens vink.

- TDEAboutDialog

  En Om-dialog.

- KLineEditDlg

  En enkel dialog til at indtaste tekst.

- KURLRequesterDlg

  En enkel dialog til at indtaste URL'er.

- KMessageBox

  En dialog til at meddele fejl og advarsler.

- KPasswordDialog

  En dialog til at indtaste kodeord.

Handlinger og grafisk XML-grænseflade

- TDEAction

  En abstraktion af en handling som kan forbindes til menulinjer og værktøjslinjer.

- TDEActionCollection

  En samling handlinger.

- KXMLGUIClient

  Et fragment af en grafisk grænseflade som består af en handling og et DOM-træ som svarer til dets plads i det grafiske grænsefladen.

- KPartManager

  Håndterer aktivering af klienter til den grafiske XML-grænseflade.

Plugin og komponenter

- KLibrary

  Repræsenterer et dynamisk indlæst bibliotek.

- KLibLoader

  Indlæsning af delte biblioteker.

- KLibFactory

  Tilvirkning af objekter for plugin.

- KServiceType

  Repræsenterer en tjenestetype.

- KService

  Repræsenterer en tjeneste.

- KMimeType

  Repræsenterer en Mime-type.

- KServiceTypeProfile

  Brugerindstillinger for tildelinger af Mime-typer.

- TDETrader

  Forespørgsler om tjenester.

## Grafik

### Lavniveaugrafik med QPainter.

#### Optegning med QPainter

Qt's lavniveau tegnemodel er baseret på de muligheder som tilbydes af X11 og andre vinduessystemer hvor en version af Qt findes. Men den udvider dem også ved at implementere yderligere funktioner såsom vilkårlige affine transformationer for tekst og billeder.

Den centrale grafiske klasse til at tegne todimensionalt med Qt er QPainter. Den kan tegne på en QPaintDevice. Der er tre mulige tegneenheder implementerede: En er TQWidget, som repræsenterer en grafisk kontrol på skærmen. Den anden er QPrinter, som repræsenterer en printer, og producerer Postscript-udskrift. Den tredje er klassen QPicture, som indspiller tegnekommandoer og kan gemme dem til disk, og derefter afspille dem. Et muligt lagringsformat for tegnekommandoer er W3C-standarden SVG.

Altså er det muligt at genbruge visningskoden som du bruger til for at vise en grafisk kontrol for udskrift, med støtte for samme funktioner. Naturligvis bruges koden i praksis i en noget anderledes sammenhæng. Tegning på en grafisk kontrol gøres næsten kun i metoden paintEvent() i en kontrolklasse.

    void MinKomponent::paintEvent()
    {
        QPainter p(this);
        // Indstil
        // Brug
    }

Når der tegnes på en printer, skal du sikre dig at bruge QPrinter::newPage() for at afslutte en side, og begynde på en ny: noget som ikke er relevant for at tegne grafiske kontroller. Ved udskrift vil du måske også bruge enhedsmetrikker for at beregne koordinater.

#### Transformationer

Normalt når QPainter bruges, tegner den i det naturlige koordinatsystemet som bruges af enheden. Det betyder at hvis du tegner en linje med længden 10 enheder, tegnes den som en vandret linje på skærmen med længden 10 billedpunkter. QPainter kan dog bruge vilkårlige affine transformationer før former og kurver rent faktisk toptegnes. En affin transformation overfører x- og y-koordinater lineært til x' og y' som følger:

QPainter::setWorldMatrix() kan bruges til at angive denne 3x3 matrix i ligningen, som har typen QWMatrix. Normalt er dette identitetsmatricen, dvs. m11 og m22 er et, og de øvrige værdier er nul. Der er basalt set tre forskellige grupper af transformationer:

- Translationer

  Disse flytter alle et objekts punkter med en fast værdi i en eller anden retning. En flytningsmatrix kan opnås ved at kalde metoden m.translate(dx, dy) med en QWMatrix. Det svarer til matricen:

- Skalering

  Disse forstørrer eller formindsker et objekts koordinater, og gør det større eller mindre uden at forvrænge det. En skaleringstransformation kan udføres for en QWMatrix ved at kalde m.scale(sx, sy). Det svarer til matricen:

  Ved at give en af parametrene en negativ værdi, kan man opnå spejling af koordinatsystemet.

- Forskydning

  En forvrængning af koordinatsystemet med to parametre. En forskydningstransformation kan udføres ved at kalde m.shear(sh, sv), hvilket svarer til matricen:

- Rotation

  Dette roterer et objekt. En rotationstransformation kan udføres ved at kalde m.rotate(alfa). Bemærk at vinklen skal angives i grader, ikke som en matematisk vinkel! Tilsvarende matrix er:

  Bemærk at rotation er ækvivalent med en kombination af skalering og forskydning.

Her er nogle billeder som viser effekten af de grundlæggende transformationer for vores maskot:

a) Normal | b) Roteret 30 grader | c) Forskudt med 0,4 | d) Spejlet

Transformationer kan kombineres ved at multiplicere grundlæggende matricer. Bemærk at matrixoperationer ikke i almindelighed kommutative, og derfor afhænger den kombinerede effekt af en sammensætning af rækkefølgen som matricerne multipliceres med.

#### Angiv stregegenskaber

Fremvisning af linjer, kurver og polygonkanter kan ændres ved at angive en særlig pen med QPainter::setPen(). Argumentet til denne funktion er et QPen-objekt. Egenskaberne som opbevares i det er en stil, en farve, en sammenføjningsstil og en slutstil.

Pennestilen er et medlem af nummereringstypen TQt::PenStyle. og kan have en af følgende værdier:

Sammenføjningsstilen er et medlem af nummereringstypen TQt::PenJoinStyle. Den angiver hvordan forbindelsen mellem flere linjer som sættes sammen tegnes. Den kan have en af følgende værdier:

a) MiterJoin | c) BevelJoin | b) RoundJoin

Slutstilen er et medlem af nummereringstypen TQt::PenCapStyle og angiver hvordan linjernes endepunkter tegnes. Den antager en værdi fra følgende tabel:

a) FlatCap | b) SquareCap | c) RoundCap

#### Angiv udfyldningsegenskaber

Udfyldningsstilen for polygoner, cirkler eller rektangler kan ændres ved at angive en særlig pensel med QPainter::setBrush(). Denne funktions argument er et QBrush-objekt. Pensler kan laves på fire forskellige måder:

- QBrush::QBrush(): dette laver en pensel som ikke udfylder former.

- QBrush::QBrush(BrushStyle): dette laver en sort pensel, med et af de fordefinerede mønstre som vises nedenfor.

- QBrush::QBrush(const TQColor &, BrushStyle): dette laver en farvet pensel, med et af de fordefinerede mønstre som vises nedenfor.

- QBrush::QBrush(const TQColor &, const QPixmap): dette laver en farvet pensel, med det egne mønster som angives som anden parameter.

En standardpenselstil fra nummereringstypen TQt::BrushStyle. Her er et billede af alle fordefinerede mønstre:

Yderligere en måde at indstille en pensels opførsel er at bruge funktionen QPainter::setBrushOrigin().

#### Farve

Farver har betydning både når kurvor tegnes, og når former udfyldes. Farver repræsenteres af klassen TQColor i Qt. Qt understøtter ikke avancerede grafikfunktioner såsom ICC-farveprofiler og farvekorrektion. Farver laves oftest ved at angive deres røde, grønne og blå komponenter, eftersom RGB-modellen er måden som billedpunkter sammensættes en billedskærm.

Det er også muligt at bruge farvetone, mætning og værdi. Denne HSV-repræsentation er den som bruges i GTK's farvedialog, f.eks. i GIMP. Der svarer farvetonen til en vinkel i farvehjulet, mens farvemætningen svarer til afstanden fra cirklens midte. Værdien vælges med en separat glider.

#### Øvrige indstillinger

Normalt når du tegner på en tegneenhed, så erstatter billedpunkterne dem som var der tidligere. Det betyder at hvis du udfylder et vist område med rød farve, og derefter udfylder samme område med blå farve, så er kun den blå farven synlig. Qt's billedmodel tillader ikke gennemsigtighed, dvs. en måde at blande forgrunden som tegnes med baggrunden. Der er dog en enkel måde at kombinere baggrund og forgrund med Booleske operationer. Metoden QPainter::setRasterOp() angiver operationen som bruges, som kommer fra nummereringstypen RasterOp.

Standardværdien er CopyROP, som ignorerer baggrunden. Et andet populært valg er XorROP. Hvis du tegner en sort linje med denne operationen på et farvet billede, så inverteres området som dækkes. Denne effekt bruges for eksempel til at oprette gummibåndsmarkeringer i billedbehandlingsprogrammer, som er kendte under navnet "vandrende myrer".

#### Tegn grafiske primitiver

I det følgende giver vi en liste over de grundlæggende grafiske elementer som understøttes af QPainter. De fleste af dem findes i flere overbelastede versioner som har forskellige antal argumenter. Metoder som håndterer rektangler, har for eksempel oftest en QRect som argument, eller et sæt med fire heltal.

- Tegn et enkelt punkt: drawPoint().

- Tegn linjer: drawLine(), drawLineSegments() og drawPolyLine().

- Tegn og udfyld rektangler: drawRect(), drawRoundRect(), fillRect() og eraseRect().

- Tegn og udfyld i cirkler, ellipser og dele af dem: drawEllipse(), drawArc(), drawPie og drawChord().

- Tegn og udfyld generelle polygoner: drawPolygon().

- Tegn Bezierkurvor: drawQuadBezier() [drawCubicBezier i Qt 3.0].

#### Tegn pixmaps og billeder

Qt sørger for to meget forskellige klasser til at repræsentere billeder.

QPixmap svarer direkte til pixmapsobjekter i X11. En pixmap er et objekt på serversiden og kan, med et moderne grafikkort, til og med opbevares direkte i kortets hukommelse. Det gør det meget effektivt at overføre en pixmap til skærmen. En pixmap virker også som en svarende til grafiske kontroller udenfor skærmen. QPixmap-klassen er en delklasse til QPaintDevice, så det er muligt at tegne på den med en QPainter. Elementære tegneoperationer accelereres ofte af moderne grafik. Derfor er et almindeligt brugsmønster at bruge en pixmap til dobbeltbuffering. Dette betyder at i stedet for at tegne direkte på en grafisk kontrol, tegner man på et tilfældigt pixmapobjekt og bruger funktionen bitBlt til at overføre det til kontrollen. For komplekse gentegninger, hjælper dette med at undgå flimmer.

I modsætning til dette, er der TQImage-objekter på klientsiden. Deres hovedopgave er at give direkte adgang til billedpunkterne i billederne. Det gør dem nyttige til billedhåndtering, og ting såsom at indlæse og gemme til disk (Metoden load() for QPixmap bruger TQImage som et mellemtrin). På den anden siden, så bliver optegning af et billede på en grafisk kontrol en ganske krævende handling, eftersom det indebærer en overførsel til X-serveren, hvilket kan tage en vis tid, især for store billeder og fjernservere. Afhængig af farvedybden, kan konvertering fra TQImage til QPixmap også kræve brug af dithering.

#### Tegn tekst

Tekst kan tegnes med en af de overbelastede varianter af metoden QPainter::drawText(). Disse tegner en TQString, enten ved et given punkt eller inde i en given rektangel, med skrifttypen som indstilles med QPainter::setFont(). Der er også en parameter som tager en ELLER-kombination af visse flag fra nummereringstyperne TQt::AlignmentFlags og TQt::TextFlags.

Begyndende i version 3.0, håndterer Qt fuldstændig tekstlayout også for sprog som skrives fra højre til venstre.

En mere avanceret måde at vise opmarkeret tekst, er klassen QSimpleRichText. Objekter fra klassen kan laves med et tekststykke som bruger en delmængde af HTML-mærkerne, som er ganske omfattende og til og med tilbyder tabeller. Tekststilen kan indstilles ved at bruge QStyleSheet (mærkernes dokumentation findes også her). Så snart tekstobjektet er lavet, kan det tegnes op på en grafisk kontrol eller en anden tegneenhed med metoden QSimpleRichText::draw().

### Struktureret grafik med QCanvas

QPainter tilbyder en kraftfuld tegnemodel til at tegne på grafiske kontroller og pixmaps. Den kan dog være omstændelig at bruge. Hver gang kontrollen modtager en tegnebegivenhed, skal den analysere QPaintEvent::region() eller QPaintEvent::rect() for det som skal tegnes om. Derefter skal den indstille en QPainter, og tegne alle objekter som overlapper dette område. Tænk for eksempel på et vektortegneprogram som tillader at objekter såsom polygoner, cirkler og grupper af dem at trækkes omkring. Hver gang objekterne flyttes en lille smule, aktiverer kontrolles musebegivenhedshåndtering en tegnebegivenhed for hele området som dækkes af objekternes gamle sted og deres nye sted. At regne de nødvendige omtegninger ud, og at udføre dem på en effektiv måde, kan være svært, og kan også være i konflikt med programkodens objektorienterede struktur.

Som et alternativ indeholder Qt klassen QCanvas, hvor man tilføjer grafiske objekter, såsom polygoner, tekst eller pixmaps. Man kan også oprette yderligere objekter ved at oprette en delklasse af QCanvasItem eller en af dens mere specialiserede delklasser. En dug kan vises på skærmen ved en eller flere kontroller fra klassen QCanvasView, som man skal oprette en delklasse af for at håndtere interaktion med brugeren. Qt sørger for al omtegning af objekter i visningen, det være sig de forårsages af at kontrollen vises, nye objekter laves eller ændres, eller andre grunde. Ved at bruge dobbeltbuffering, kan dette gøres på en effektiv og flimmerfri måde.

Objekter på dugen kan overlappe hinanden. I dette tilfælde, så afhænger det der ses af z-rækkefølgen, som kan tildeles med QCanvasItem::setZ(). Objekter kan også gøres synlige eller usynlige. Man kan også sørge for en baggrund som skal tegnes "bagved" alle objekter, og en forgrund. For at associere musebegivenheder med objekter på dugen, findes metoden QCanvas::collisions(), som returnerer en liste med objekter som overlappar med et givet punkt. Her viser vi et skærmaftryk af en dugvisning i arbejde:

Her optegnes rudemønstret i baggrunden. Desuden findes et QCanvasText-objekt og en violet QCanvasPolygon. Sommerfuglen er en QCanvasPixmap. Den har gennemsigtige områder, så du kan se underliggende objekt gennem den.

En vejledning om hvordan QCanvas bruges til at skrive spil baserede på småfigurer findes her.

### 3D-grafik med OpenGL

#### Lavniveaugrænseflade

De-facto standarden for at optegne 3D-grafik nu for tiden er OpenGL. Implementeringer af standarden levereres med Microsoft Windows, Mac OS X og XFree86, og de understøtter ofte funktioner for hardwareacceleration som tilbydes af moderne grafikkort. OpenGL selv håndterer kun optegning på et angivet område i rammebufferen gennem en GL-sammenhæng, og har ingen interaktion med værktøjskassen eller miljøet.

Qt tilbyder den grafiske komponent QGLWidget, som indkapsler et vindue med tilhørende GL-sammenhæng. Egentlig bruges det ved at oprette en delklasse af det og omimplementere nogle metoder.

- I stedet for at implementere paintEvent(), og bruge QPainter til at tegne kontrollens indhold, overskrider man paintGL() og bruger GL-kommandoer til at optegne en scene. QGLWidget tager sig af at gøre sin GL-sammenhæng til den aktuelle inden paintGL() kaldes, og tømmer den bagefter.

- Den virtuelle metode initializeGL() kaldes en gang inden den første gang inden resizeGL() eller paintGL() kaldes. Dette kan bruges til at oprette visningslister for objekter, og udføre alle initieringer.

- I stedet for at omimplementere resizeEvent(), overskrider man resizeGL(). Dette kan bruges til at indstille visningsområdet på en passende måde.

- I stedet for at kalde update() når scenens tilstand er ændret, for eksempel hvis du animerer den med et ur, skal man kalde updateGL(). Dette aktiverer en omtegning.

I almindelighed opfører QGLWidget sig som en hvilken som helst anden grafisk kontrol, dvs. man kan for eksempel håndtere musebegivenheder som sædvanligt, ændre størrelse på kontrollen og kombinere den med andre i et layout.

Qt indeholder nogle eksempler på brug af QGLWidget i `demo`-eksemplerne. En samling vejledninger findes her, og mere information samt en OpenGL-reference findes på OpenGL's hjemmeside.

#### Højniveau-grænseflade

OpenGL er en grænseflade på ganske lavt niveau for at tegne 3D-grafik. På samme måde som QCanvas giver programmøren en grænseflade på højere niveau som håndterer objekter og deres egenskaber, er der også grænseflade på højere niveau for 3D-grafik. En af de mest populære er Open Inventor. Oprindelig var det en teknologi som udvikledes af SGI, men i dag er der også en implementering med åben kildekode, Coin, som komplementeres af en værktøjsbinding til Qt, som hedder SoQt.

Det grundlæggende begreb i Open Inventor er en scene. En scene kan indlæses fra disken, og gemmes i et særligt format, nært beslægtet med VRML. En scene består af en samling objekter som kaldes knuder. Inventor sørger allerede for en omfattende samling med genbrugelige knuder, såsom kuber, cylindre og gitre. Desuden er der lyskilder, materiale, kameraer, osv. Knuder repræsenteres af C++ klasser, og kan kombineres og delklasser kan laves.

En introduktion til Inventor findes her (du kan generelt erstatte alle SoXt som nævnes i artiklen med SoQt).

## Brugergrænseflade

### Handlingsmønstret

### Definition af menuer og værktøjslinjer i XML

#### Indledning

Mens handlingsmønstret tillader at handlinger som aktiveres af brugeren kapsles ind i et objekt, som kan "forbindes" til et sted i menulinjerne eller værktøjslinjerne, løser det ikke i sig selv problemet med at oprette selve menuerne. I særdeleshed skal du bygge alle sammenhængsafhængige menuer i C++ kode, og udtrykkelig indsætte handlingerne i en vis rækkefølge, med hensyn taget til stilguiden for standardhandlinger. Det gør det rigtigt svært at lade brugeren indstille menuerne eller ændre genvejstaster så de passer til hans behov, uden at ændre kildekoden.

Dette problem løses med en samling klasser som kaldes `grafisk XML-grænseflade`. I grunden adskiller de handlingerne (kodede i C++) fra deres udseende i menulinjer og værktøjslinjer (kodede i XML). Uden at ændre nogen kildekode, kan menuer nemt indstilles ved at justere en XML-fil. Desuden hjælper det til at sikre at standardhandlinger (såsom Fil Åbn eller Hjælp Om) vises på de steder som foreslås af stilguiden. Grafiske XML-grænseflader er særligt vigtige for modulære programmer, hvor valgmulighederne i menulinjerne kan komme fra mange forskellige plugin eller dele.

KDE's klasse for topniveauvindue, TDEMainWindow, arver KXMLGUIClient, og understøtter derfor grafiske XML-grænseflader fra begyndelsen. Alle handlinger som laves inde i det skal have klientens `actionCollection()` som forælder. Et kald til `createGUI()` bygger siden hele sættet af menuer og værktøjslinjer som defineres af programmets XML-fil (almindeligvis med endelsen `ui.rc`).

#### Et eksempel: Menuen i Kview

I det følgende bruger vi KDE's billedfremviser Kview som eksempel. Den har en `ui.rc`-fil som hedder `kviewui.rc`, som installeres med et fragment fra `Makefile.am`

    rcdir = $(kde_datadir)/kview
    rc_DATA = kviewui.rc

Her er et uddrag fra filen `kviewui.rc`. For enkelhedens skyld, viser vi kun definitionen for menuen View.

    <!DOCTYPE kpartgui>
    <kpartgui name="kview">
      <MenuBar>
        <Menu name="view" >
          <Action name="zoom50" />
          <Action name="zoom100" />
          <Action name="zoom200" />
          <Action name="zoomMaxpect" />
          <Separator/>
          <Action name="fullscreen" />
        </Menu>
      </MenuBar>
    </kpartgui>

Den tilsvarende del til at oprette dette i C++ er:

    KStdAction::zoomIn    ( this, TQ_SLOT(slotZoomIn()), actionCollection() );
      KStdAction::zoomOut   ( this, TQ_SLOT(slotZoomOut()), actionCollection() );
      KStdAction::zoom      ( this, TQ_SLOT(slotZoom()), actionCollection() );
      new TDEAction           ( i18n("&Half size"), ALT+Key_0,
                              this, TQ_SLOT(slotHalfSize()),
                              actionCollection(), "zoom50" );
      new TDEAction           ( i18n("&Normal size"), ALT+Key_1,
                              this, TQ_SLOT(slotDoubleSize()),
                              actionCollection(), "zoom100" );
      new TDEAction           ( i18n("&Double size"), ALT+Key_2,
                              this, TQ_SLOT(slotDoubleSize()),
                              actionCollection(), "zoom200" );
      new TDEAction           ( i18n("&Fill Screen"), ALT+Key_3,
                              this, TQ_SLOT(slotFillScreen()),
                              actionCollection(), "zoomMaxpect" );
      new TDEAction           ( i18n("Fullscreen &Mode"), CTRL+SHIFT+Key_F,
                              this, TQ_SLOT(slotFullScreen()),
                              actionCollection(), "fullscreen" );

Menuen View som laves af denne definition af den grafiske grænseflade ser ud som det vises på dette skærmaftryk:

XML-filen begynder med en dokumenttypedeklaration. DTD'en for kpartgui findes i tdelibs-kildekoden i `tdeui/kpartgui.dtd`. Det yderste element i filen indeholder programmets instansnavn som en egenskab. Det kan også indeholde et versionsnummer på formen "version=2". Dette er nyttigt når du udgiver nye versioner af et program med ændret menustruktur, f.eks. med flere funktioner. Hvis du hæver versionsnummeret i filen `ui.rc`, sørger KDE for at alle indstillede versioner af filen kasseres og at den nye fil bruges i stedet.

Næste linje, `<MenuBar>`, indeholder en deklaration af en menulinje. Du kan også indsætte så mange `<ToolBar>`-deklarationer som helst, for at oprette nogle værktøjslinjer. Menuen indeholder en undermenu, med navnet "view". Dette navn er allerede fordefineret, og derfor vil den oversatte version af ordet "View" blive vist. Hvis du deklarerer undermenuer, skal du udtrykkelig tilføje titlen. Kview har for eksempel en undermenu med titlen "Image", som deklareres som følger:

    <Menu name="image" >
       <text>&amp;Image</text>
       ...
    </Menu>

I KDE's automatiske byggeskelet, plukkes sådanne titler automatisk ud og placeres i programmets `.po`-fil, så de håndteres af oversættere. Bemærk at du skal skrive markeringen af genvejstasten "&" på en form som følger XML-syntaksen "&amp;".

Lad os vende tilbage til eksemplet. Kview's menu Vis indeholder et antal egne handlinger `zoom50`, `zoom100`, `zoom200`, `zoomMaxpect` og `fullscreen`, deklarerede med elementet `<Action>`. Skillelinjen i skærmaftrykkene svarer til elementet `<Separator>`.

Du bemærker at visse menupunkter ikke har et tilsvarende element i XML-filen. De er standardhandlinger. Standardhandlinger laves af klassen KStdAction. Når du laver sådanne handlinger i dit program (som i C++ eksemplet ovenfor), indsættes de automatisk på en foreskreven plads, og muligvis med en ikon og en genvejstast. Du kan slå disse steder i filen op i `tdeui/ui_standards.rc` i tdelibs-kildekoden.

#### Et eksempel: Værktøjslinjer i Konqueror

For beskrivelsen af værktøjslinjer, skifter vi til Konquerors definition af grafisk grænseflade. Dette uddrag definerer stedlinjen, som indeholder indtastningsfeltet for URL'er.

    <ToolBar name="locationToolBar" fullWidth="true" newline="true" >
      <text>Location Toolbar</text>
      <Action name="clear_location" />
      <Action name="location_label" />
      <Action name="toolbar_url_combo" />
      <Action name="go_url" />
    </ToolBar>

Det første vi bemærker er at der er mange flere egenskaber end for menulinjer. De omfatter:

- `fullWidth`: Fortæller den grafiske XML-grænsefladen at værktøjslinjen har samme bredde som topniveauvinduet. Hvis dette er "false", optager værktøjslinjen kun så meget plads som nødvendigt, og yderligere værktøjslinjer placeres på samme linje.

- `newline`: Dette hører sammen med ovenstående valgmulighed. Hvis newline er "true", så placeres værktøjslinjen på en ny linje. Ellers kan den placeres i en linje sammen med den foregående værktøjslinje.

- `noEdit`: Normalt kan værktøjslinjer indstilles af brugeren, f.eks. med Indstillinger Indstil værktøjslinjer i Konqueror. Sættes dette til "true", markeres værktøjslinjen så den ikke kan redigeres. Det er vigtigt for værktøjslinjer som fyldes op med objekter når programmet kører, f.eks. Konqueror's bogmærkeværktøjslinje.

- `iconText`: Beder den grafiske XML-grænseflade om at vise handlingens tekst før ikonen. Normalt vises teksten kun som et værktøjsvink når musemarkøren holdes over ikonen et stykke tid. Mulige værdier for egenskaben er "icononly" (viser kun ikonen), "textonly" (viser kun teksten), "icontextright" (viser teksten til højre for ikonen) og "icontextbottom" (viser teksten under ikonen).

- `hidden`: Hvis dette er "true", så vises værktøjslinjen ikke fra begyndelsen, og skal aktiveres af et menupunkt.

- `position`: Standardværdien for denne egenskab er "top", hvilket betyder at værktøjslinjen placeres under menulinjen. For programmer med mange værktøjer, såsom grafikprogram, kan det være interessant at erstatte dette med "left" (venstre), "right" (højre) eller "bottom" (under).

#### Dynamiske menuer

XML kan naturligvis kun indeholde en statisk beskrivelse af en brugergrænseflade. Ofte er der menuer som ændres under kørsel. Konqueror's menu Sted indeholder for eksempel et sæt punkter Åbn med ..., med programmer som kan indlæse en fil med en given Mime-type. Hver gang dokumentet som vises ændres, opdateres listen med menupunkter. Den grafiske XML-grænseflade er forberedt på at håndtere sådanne tilfælde med begrebet handlingslister. En handlingsliste deklareres som et objekt i XML-filen, men består af flere handlinger som forbindes til menuen når programmet kører. Ovenstående eksempel implementeres med følgende deklaration i Konqueror's XML-fil:

    <Menu name="file">
      <text>&amp;Location</text>
      ...
      <ActionList name="openwith">
      ...
    </Menu>

Funktionen `KXMLGUIClient::plugActionList()` bruges derefter for at tilføje handlinger som skal vises, mens funktionen `KXMLGuiClient::unplugActionList()` fjerner alle forbundne handlinger. Rutinen som er ansvarlig for at udføre opdateringerne ser ud som følger:

    void MainWindow::updateOpenWithActions()
    {
        unplugActionList("openwith");
        openWithActions.clear();
        for ( /* Løkke for relevante tjenester */ ) {
            TDEAction *action = new TDEAction( ...);
            openWithActions.append(action);
        }
        plugActionList("openwith", openWithActions);
    }

Bemærk at i modsætning til statiske handlinger, så laves disse ikke med handlingssamlingen som forælder, og du har selv ansvaret for at de fjernes. Den nemmeste måde at opnå dette er ved at bruge `openWithActions.setAutoDelete(true)` i eksemplet ovenfor.

#### Sammenhængsafhængige menuer

Eksemplerne ovenfor indeholder kun klasser hvor et hovedvindues menulinje og værktøjslinjer laves. I de tilfælde er processen som laver beholdarne helt skjult for dig inde i kaldet af funktionen `createGUI()` (medmindre du har egne beholdere). Der er dog tilfælde hvor du vil oprette andre beholdere og befolke dem med grafiske grænsefladedefinitioner fra XML-filen. Et sådant eksempel er sammenhængsafhængige menuer. For at få en peger til en sammenhængsafhængig menu, skal du bede klientens tilvirker om det:

    void MainWindow::popupRequested()
    {
        TQWidget *w = factory()->container("context_popup", this);
        QPopupMenu *popup = static_cast<QPopupMenu *>(w);
        popup->exec(QCursor::pos());
    }

Metoden `KXMLGUIFactory::container()` som bruges ovenfor, ser efter om den finder en beholder i XML-filen med det angivne navn. Altså kan en mulig definition se ud på følgende måde:

    ...
    <Menu name="context_popup">
      <Action name="file_add"/>
      <Action name="file_remove"/>
    </Menu>
    ...

### Sørg for indbygget hjælp

At gøre et program let og intuitivt at bruge omfatter en stor mængde funktioner, som ofte kaldes indbygget hjælp. Indbygget hjælp har flere, delvis modstridende, mål: på den ene siden skal den give brugeren svar på spørgsmål "Hvordan kan jeg udføre en vis opgave?", på den anden side skal den hjælpe brugeren med at udforske programmet og finde funktioner som han endnu ikke kender til. Det er vigtigt at indse at dette kun kan opnås ved at tilbyde flere hjælpeniveauer:

- Værktøjsvink er små etiketter som dukker op over grænsefladeelementer når musen bliver der hvor et længere stykke tid. De er særligt vigtige for værktøjslinjer, hvor ikonerne ikke altid er nok til for at forklare formålet med en knap.

- "Hvad er dette?" hjælp er ofte en længere og mere udførlig forklaring af en kontrol eller et menupunkt. Den er også mere kluntet at bruge. I dialoger kan den vises på to forskellige måder: enten ved at trykke på Shift F1, eller ved at klikke på spørgsmålstegnet i navnelisten (understøttelse for dette afhænger af vindueshåndteringen). Musemarkøren ændres så til en pil med et spørgsmålstegn, og et hjælpevindue vises når der klikkes på et element i brugergrænsefladen. "Hvad er dette ?" hjælp for menuer aktiveres oftest med en knap i værktøjslinjen som indeholder en pil og et spørgsmålstegn.

- Problemet med denne metode er at brugeren ikke kan se om en grafisk kontrol sørger for hjælp eller ej. Når brugeren aktiverer knappen med spørgsmålstegn og ikke får noget hjælpevindue ved klik på et element i brugergrænsefladen, bliver han meget snart frustreret.

  Fordelen med "Hvad er dette?" hjælpevinduer som de tilbydes af Qt og KDE, er at de kan indeholde formateret tekst, dvs. de kan indeholde forskellige skrifttyper, tekst i fed type og kursiv stil, og til og med billeder og tabeller.

  Et eksempel på "Hvad er dette?" hjælp:

- Endelig skal alle programmer have en håndbog. En håndbog vises normalt i Hjælpecentralen ved at bruge menuen Hjælp. Det betyder at et helt nyt program dukker op og afleder brugeren fra arbejdet. Følgelig skal det kun være nødvendigt at rådspørge håndbogen om andre funktioner, når værktøjsvink og hvad er dette hjælp, ikke rækker til. Naturligvis har en håndbog fordelen at den ikke forklarer enkelte isolerede aspekter af brugergrænsefladen. Den kan i stedet forklare visse af programmets aspekter i en større sammenhæng. Håndbøger for KDE skrives ved brug af DocBook-opmarkeringssproget.

Fra programmørens synvinkel, tilbyder Qt en enkel grænseflade for indbygget hjælp. For at tildele et værktøjsvink til en grafisk kontrol, bruges klassen QToolTip.

    QToolTip::add(w, i18n("This widget does something."))

Hvis menulinjerne og værktøjslinjerne laves som handlingsmønstre, hentes strengen som bruges som værktøjsvink fra det første argument i konstruktoren TDEAction.

    action = new TDEAction(i18n("&Delete"), "editdelete",
                         SHIFT+Key_Delete, actionCollection(), "del")

Her er det også muligt at tildele en tekst som vises i statuslinjen når det tilsvarende menupunkt markeres:

    action->setStatusText(i18n("Deletes the marked file"))

Programmeringsgrænsefladen for "Hvad er dette?" er meget lignende. Brug følgende kode i dialoger:

    QWhatsThis::add(w, i18n("<qt>This demonstrates <b>Qt</b>'s"
                            " rich text engine.<ul>"
                            "<li>Foo</li>"
                            "<li>Bar</li>"
                            "</ul></qt>"))

For menupunkter, brug

    action->setWhatsThis(i18n("Deletes the marked file"))

Starten af Hjælpecentralen er indkapslet i klassen TDEApplication. For at vise håndbogen for programmet, bruges blot

    tdeApp->invokeHelp()

Dette viser den første side med indholdsfortegnelsen. Når du kun vil vise et vist afsnit af håndbogen, kan du give yderligere et argument til `invokeHelp()`, som afgør ankeret som søgeren hopper til.

## Komponenter og tjenester

### KDE-tjenester

#### Hvad er KDE-tjenester?

Begrebet tjeneste er en central idé i KDE's modulære arkitektur. Der er ingen strikt teknisk implementering koblet til benævnelsen: tjenester kan være plugin i form af delte biblioteker, eller programmer som styres via DCOP. Ved at påstå at være af en vis tjenestetype, lover en tjeneste at implementere visse programmeringsgrænseflader eller funktioner. I C++ sprogbrug, kan man forestille sig en tjenestetype som en abstrakt klasse, og en tjeneste som en implementering af grænsefladen.

Fordelen ved denne opdeling er åbenbar: Et program som udnytter en tjenestetype behøver ikke kende til mulige implementeringer af den. Den bruger kun programmeringsgrænsefladen som hører sammen med tjenestetypen. På denne måde kan tjenesten som bruges ændres uden at påvirke programmet. Desuden kan brugeren indstille hvilke tjenester han foretrækker til bestemte funktioner.

Nogle eksempler:

- HTML-fremvisningskomponenten som bruges i Konqueror er en indlejret komponent som implementerer tjenestetypen `KParts/ReadOnlyPart` og `Browser/View`.

- I de seneste versioner af KDevelop, er størstedelen af funktionerne pakkede i plugin med tjenestetypen `KDevelop/Part`. Ved opstart, indlæses alle tjenester af denne type, så du kan udvide det integrerede udviklingsmiljø på en meget smidig måde.

- Konqueror kan vise miniaturer af billeder, HTML-sider, PDF- og tekstfiler, hvis det aktiveres. Denne formåen kan udvides. Hvis du vil vise forhåndsvisningsbilleder af egne datafiler af en vis Mime-type, kan du implementere en tjeneste med tjenestetypen ThumbCreator.

Naturligvis karakteriseres en tjeneste ikke kun af tjenestetypen som den implementerer, men også af nogle egenskaber. For eksempel så gør en ThumbCreator ikke kun krav på at den implementerer C++ klassen med typen ThumbCreator, den har også en liste med Mime-typer som den er ansvarlig for. På samme måde har KDevelop-dele programsproget de understøtter som en egenskab. Når et program beder om en tjenestetype, kan den også angive begrænsninger for tjenestens egenskaber. I eksemplet ovenfor, når KDevelop indlæser plugin for et Java-projekt, spørger det kun efter plugin som har egenskaben Java som programmeringssprog. KDE indeholder en fuldstændig CORBA-lignende handler, med et komplekst forespørgselssprog, til dette formål.

#### Definition af tjenestetyper

Nye tjenestetyper tilføjes ved at installere en beskrivelse af dem i mappen `TDEDIR/share/servicetypes`. I det automatiske byggeskelet, kan det gøres med dette fragment fra `Makefile.am`:

    kde_servicetypesdir_DATA = tdeveloppart.desktop
    EXTRA_DIST = $(kde_servicetypesdir_DATA)

Definitionen `tdeveloppart.desktop` for en part til KDevelop ser ud som følger:

    [Desktop Entry]
    Type=ServiceType
    X-TDE-ServiceType=KDevelop/Part
    Name=KDevelop Part

    [PropertyDef::X-KDevelop-Scope]
    Type=TQString

    [PropertyDef::X-KDevelop-ProgrammingLanguages]
    Type=QStringList

    [PropertyDef::X-KDevelop-Args]
    Type=TQString

Foruden de sædvanlige indgange, demonstrerer dette eksempel hvordan man angiver at en tjeneste har visse egenskaber. Hver definition af en egenskab svarer til en gruppe `[PropertyDef::name]` i konfigurationsfilen. I gruppen, angiver indgangen `Type` egenskabens type. Mulige typer er alt som kan opbevares i en QVariant.

#### Definition af delte bibliotekstjenester

Tjenestedefinitioner opbevares i mappen `TDEDIR/share/services`:

    kde_servicesdir_DATA = kdevdoxygen.desktop
    EXTRA_DIST = $(kde_servicesdir_DATA)

Indholdet i følgende eksempelfil, `kdevdoxygen.desktop`, angiver pluginnet `KDevDoxygen` med tjenestetypen `KDevelop/Part`:

    [Desktop Entry]
    Type=Service
    Comment=Doxygen
    Name=KDevDoxygen
    ServiceTypes=KDevelop/Part
    X-TDE-Library=libkdevdoxygen
    X-KDevelop-ProgrammingLanguages=C,C++,Java
    X-KDevelop-Scope=Project

Foruden de almindelige deklarationer, er en vigtig indgang `X-TDE-Library`. Den indeholder navnet på libtool-biblioteket (uden filendelsen `.la`). Det fastlægger også navnet på det eksporterede symbol i biblioteket som returnerer objekttilvirkeren (med det indledende præfiks `init_`). I ovenstående eksempel, skal biblioteket indeholde følgende funktion:

    extern "C" {
        void *init_libkdevdoxygen()
        {
            return new DoxygenFactory;
        }
    };

Typen for tilvirkningsklassen DoxygenFactory afhænger af den specifikke tjenestetype som tjenesten implementerer. I vort eksempel med et KDevelop-plugin, skal tilvirkeren være en KDevFactory (som arver KLibFactory). Et mere almindeligt eksempel er KParts::Factory som antages at oprette objekterne KParts::ReadOnlyPart eller i de fleste tilfælde den generiske KLibFactory.

#### Brug af delte bibliotekstjenester

For at kunne bruge en delt bibliotekstjeneste i et program, skal du skaffe et KService-objekt som repræsenterer den. Dette beskrives i afsnittet om Mime-typer (og i et afsnit om handleren som endnu ikke er skrevet :-)

Med objektet KService tilgængeligt, kan du meget let indlæse biblioteket og få en peger til dets tilvirkningsobjekt.

    KService *service = ...
    TQString libName = QFile::encodeName(service->library());
    KLibFactory *factory = KLibLoader::self()->factory(libName);
    if (!factory) {
        TQString name = service->name();
        TQString errorMessage = KLibLoader::self()->lastErrorMessage();
        KMessageBox::error(0, i18n("There was an error loading service %1.\n"
                                   "The diagnostics from libtool is:\n%2")
                              .arg(name).arg(errorMessage);
    }

Fra dette øjeblik, afhænger fortsættelsen igen af tjenestetypen. For generelle plugin, laver man objekter med metoden KLibFactory::create(). Med KParts, skal tilvirkningspegeren konverteres til det mere specifikke KParts::Factory, og dets metode create() skal bruges:

    if (factory->inherits("KParts::Factory")) {
        KParts::Factory *partFactory = static_cast<KParts::Factory*>(factory);
        TQObject *obj = partFactory->createPart(parentWidget, widgetName,
                                               parent, name, "KParts::ReadOnlyPart");
        ...
    } else {
        cout << "Tjenesten implementerer ikke de rette tilvirkere" << endl;
    }

#### Definition af DCOP-tjenester

En DCOP-tjeneste implementeres oftest som et program som startes når det behøves. Det går derefter ind i en løkke og lytter efter DCOP-forbindelser. Programmet kan være interaktivt, men det kan også køre som en dæmon i baggrunden under hele eller dele af sin livstid, uden at brugeren mærker det. Et eksempel på en sådan dæmon er `tdeio_uiserver`, som implementerer vekselvirken med brugeren som fremgangsdialoger for TDEIO-biblioteket. Fordelen ved en sådan central dæmon er at f.eks. download-forløbet for flere forskellige filer kan vises i et vindue, selvom dine download startedes fra forskellige programmer.

En DCOP-tjeneste defineres på en anden måde end en tjeneste i et delt bibliotek. Naturligvis angiver den ikke et bibliotek, men i stedet et kørbart program. Desuden angiver en DCOP-tjeneste ikke linjen med tjenestetype, eftersom den startes med navn. Den indeholder yderligere to linjer med yderligere egenskaber:

`X-DCOP-ServiceType` angiver hvordan tjenesten startes. Værdien `Unique` (unik) angiver at tjenesten ikke må startes mere end én gang. Det betyder at hvis du forsøger at starte tjenesten (f.eks. via TDEApplication::startServiceByName(), kontrollerer KDE om den allerede er registreret i DCOP, og bruger tjenesten som kører. Hvis den ikke allerede er registreret, starter KDE den og venter til den er registreret. Derfor kan du med det samme sende DCOP-kald til tjenesten. I dette tilfælde, skal tjenesten implementeres som TDEUniqueApplication.

Værdien `Multi` for `X-DCOP-ServiceType` angiver at flere instanser af tjenesten kan eksistere samtidigt, så hvert forsøg på at starte tjenesten skaber en ny proces. Som en sidste mulighed kan værdien `None` (ingen) bruges. I dette tilfælde, venter starten af tjenesten ikke på at den er registreret i DCOP.

`X-TDE-StartupNotify` skal normalt angives som "false". Ellers viser aktivitetsfeltet en startbekræftelse, eller, afhængig af brugerindstillingerne, så ændres markøren.

Her er definitionen af `tdeio_uiserver`:

    [Desktop Entry]
    Type=Service
    Name=tdeio_uiserver
    Exec=tdeio_uiserver
    X-DCOP-ServiceType=Unique
    X-TDE-StartupNotify=false

#### Brug af DCOP-tjenester

En DCOP-tjeneste startes med en af flere metoder i klassen TDEApplication:

    DCOPClient *client = tdeApp->dcopClient();
    client->attach();
    if (!client->isApplicationRegistered("tdeio_uiserver")) {
        TQString error;
        if (TDEApplication::startServiceByName("tdeio_uiserver", QStringList(), &error))
            cout << "Start af TDEIO-server mislykkedes med meddelelsen " << error << endl;
    }
    ...
    QByteArray data, replyData;
    QCString replyType;
    QDataStream arg(data, IO_WriteOnly);
    arg << true;
    if (!client->call("tdeio_uiserver", "UIServer", "setListMode(bool)",
                      data, replyType, replyData))
        cout << "Kald til tdeio_uiserver mislykkedes" << endl;
    ...

Bemærk at eksemplet med et DCOP-kald som gives her udtrykkelig bruger sammensætning af argumenter. Ofte vil man i stedet bruge en prototype som laves af dcopidl2cpp, eftersom det er meget enklere, med mindre risiko for fejl.

I eksemplet som gives her, startes tjenesten "med navn", dvs. første argument til `TDEApplication::startServiceByName()` er navnet, som det angives på linjen `Name` i desktop-filen. Et alternativ er at bruge `TDEApplication::startServiceByDesktopName()`, som bruger navnet på desktop-filen som argument, dvs. i dette tilfælde `"tdeio_uiserver.desktop"`.

Alle disse kald har en liste med URL'er som andet argument, som gives til tjenesten på kommandolinjen. Det tredje argument er en peger til en TQString. Hvis starten af tjenesten mislykkes, tildeles dette argument til en oversat fejlmeddelelse.

### Mime-typer

#### Hvad er Mime-typer?

Mime-typer bruges til at beskrive type af indhold for filer eller datafragmenter. Oprindeligt indførtes de for at tillade at billeder eller lydfiler, osv. kunne sendes med e-mail (Mime betyder "Multipurpose Internet Mail Extensions"). Senere blev systemet også brugt af browsere for at afgøre hvordan data som sendtes af en web-server skulle vises for brugeren. En HTML-side har for eksempel Mime-typen "text/html", og en Postscript-fil "application/postscript". I KDE bruges denne ide mange forskellige steder:

- I Konqueror's ikonvisning, repræsenteres filer af ikoner. Hver Mime-type har en vis ikon som den hører sammen med, som vises her.

- Når man klikker på en filikon eller et filnavn i Konqueror, så vises filen enten i en indlejret visning, eller også startes et program som hører sammen med filtypen.

- Når du trækker og slipper nogle data fra et program til et andet (eller indenfor samme program), kan målet vælge kun at acceptere visse datatyper. Desuden håndteres billeddata på en anden måde end tekstdata.

- Data på klippebordet har en Mime-type. Traditionelt håndterede X-programmer kun pixmaps eller tekst, men med Qt er der ingen begrænsning af datatypen.

Det er klart fra ovenstående eksempel, at Mime-håndtering er en kompleks ting. Først skal en tildeling af filnavne til Mime-typer gøres. KDE går yderligere et skridt, og lader til og med filindhold tildeles Mime-typer, i de tilfælde hvor filnavnet ikke er tilgængeligt. Derefter skal Mime-typer tildeles programmer eller biblioteker som kan vise eller redigere en fil af en vis type, eller oprette et miniature af den.

Der er en mængde forskellige programmeringsgrænseflader til at regne ud hvad Mime-typen for data eller filer er. Generelt skal man gøre en afvejning mellem hastighed og tilforladelighed. Man kan finde en filtype ved blot at kigge på filnavnet (i de fleste tilfælde filendelsen). Filen `foo.jpg` er for eksempel normalt "image/jpeg". I de tilfælde hvor filendelsen er taget væk er dette ikke sikkert, og man skal virkelig kigge i filens indhold. Det er naturligvis langsommere, især for filer som først skal hentes via HTTP. Den indholdsbaserede metode anvender filen `TDEDIR/share/mimelnk/magic`, og er derfor svær at udvide. Men i almindelighed kan information om Mime-typer let gøres tilgængeligt for systemet, ved at installere en `.desktop`-fil, og den bliver effektivt og bekvemt tilgængelig via KDE-bibliotekerne.

#### Definition af Mime-typer

Lad os definere typen `"application/x-foo"`, for vort nye program foobar. For at gøre det, skal filen `foo.desktop` skrives, og installeres i `TDEDIR/share/mimelnk/application`. (Det er det sædvanlige sted, som kan variere mellem distributioner). Dette kan gøres ved at tilføje følgende til `Makefile.am`:

    mimedir = $(kde_mimedir)/application
    mime_DATA = foo.desktop
    EXTRA_DIST = $(mime_DATA)

Filen `foo.desktop` skal se ud som følger:

    [Desktop Entry]
    Type=MimeType
    MimeType=application/x-foo
    Icon=fooicon
    Patterns=*.foo;
    DefaultApp=foobar
    Comment=Foo Data File
    Comment[sv]=Foo-datafil

Indgangen `"Comment"` er beregnet til at oversættes. Eftersom `.desktop`-filen angiver en ikon, bør du også installere en ikon `fooicon.png`, som repræsenterer filen, f.eks. i Konqueror.

I KDE-bibliotekerne svarer en sådan typedefinition til en instans af klassen KMimeType. Brug dette som i følgende eksempel:

    KMimeType::Ptr type = KMimeType::mimeType("application/x-foo");
    cout << "Type:    " << type->name() < endl;
    cout << "Ikon:    " << type->icon() < endl;
    cout << "Kommentar: " << type->icon() < endl;
    QStringList patterns = type->patterns();
    QStringList::ConstIterator it;
    for (it = patterns.begin(); it != patterns.end(); ++it)
      cout << "Mønster: " << (*it) << endl;

#### Afgøre Mime-type for data

Den hurtige måde at afgøre filtypen er `KMimeType::findByURL()`. Den kigger efter URL'en og afgør i de fleste tilfælde typen ud fra filendelsen. Med visse protokoller (f.eks. http, man, info), bruges denne mekanisme ikke. CGI-scripter på web-servere som skrives i Perl, har for eksempel ofte endelsen `.pl`, som ville angive typen `"text/x-perl"`. Alligevel er filen som levereres af serveren udskrift fra scriptet, som normalt er HTML. I sådanne tilfælde, returnerer `KMimeType::findByURL()` Mime-typen `"application/octet-stream"` (tilgængelig via `KMimeType::defaultMimeType()`), som angiver at det mislykkedes at finde ud af typen.

    KMimeType::Ptr type = KMimeType::findByURL("/home/bernd/foobar.jpg");
    if (type->name() == KMimeType::defaultMimeType())
        cout << "Kunne ikke afgøre typen" << endl;
    else
        cout << "Type: " << type->name() << endl;

(denne metode har nogle flere argumenter, men disse er ikke dokumenterede, så glem dem hellere helt.)

Man kan ville finde ud af en Mime-type ud fra filens indhold i stedet for filnavnet. Det er tilforladeligere, men også langsommere, eftersom det kræver at en del af filen læses. Det gøres med klassen KMimeMagic, som har en anderledes fejlhåndtering:

    KMimeMagicResult *result = KMimeMagic::self()->findFileType("/home/bernd/foobar.jpg");
    if (!result || !result->isValid())
        cout << "Kunne ikke afgøre typen" << endl;
    else
        cout << "Type: " << result->mimeType() << endl;

Med en variant af denne funktion, kan du også afgøre typen for en hukommelsesstump. Det bruges for eksempel af Kate til at regne fremhævningstilstand ud:

    QByteArray array;
    ...
    KMimeMagicResult *result = KMimeMagic::self()->findBufferType(array);
    if (!result || !result->isValid())
        cout << "Kunne ikke afgøre typen" << endl;
    else
        cout << "Type: " << result->mimeType() << endl;

Naturligvis kan selv KMimeMagic kun afgøre filtypen ud fra indholdet i en lokal fil. For fjernfiler, er der yderligere en mulighed:

    KURL url("http://developer.kde.org/favicon.ico");
    TQString type = TDEIO::NetAccess::mimetype(url);
    if (type == KMimeType::defaultMimeType())
        cout << "Kunne ikke afgøre typen" << endl;
    else
        cout << "Type: " << type << endl;

Dette starter et TDEIO-job til at hente en del af filen, og kontrollere dette. Bemærk at denne funktion måske er rigtig langsom og blokerer programmet. Normalt vil man kun bruge den hvis `KMimeType::findByURL()` returnerede `"application/octet-stream"`.

På den anden side, hvis du ikke vil blokere programmet, kan du også udtrykkelig starte TDEIO-jobbet og forbinde til et af dets signaler:

    void FooClass::findType()
    {
        KURL url("http://developer.kde.org/favicon.ico");
        TDEIO::MimetypeJob *job = TDEIO::mimetype(url);
        connect( job, TQ_SIGNAL(result(TDEIO::Job*)),
                 this, TQ_SLOT(mimeResult(TDEIO::Job*)) );
    }

    void FooClass::mimeResult(TDEIO::Job *job)
    {
        if (job->error())
            job->showErrorDialog();
        else
            cout << "Mime type: " << ((TDEIO::MimetypeJob *)job)->mimetype() << endl;
    }

#### Tildel en Mime-type til et program eller tjeneste

Når et program installeres, installerer det en `.desktop`-fil, som indeholder en liste med MIME-typer som programmet kan indlæse. På samme måde gør komponenter, som en KPart, denne information tilgængelig med deres `.desktop`-tjenestefiler. Altså er der generelt flere programmer og komponenter som kan behandle en given MIME-type. Du kan skaffe en sådan liste fra klassen KServiceTypeProfile:

    KService::OfferList offers = KServiceTypeProfile::offers("text/html", "Application");
    KService::OfferList::ConstIterator it;
    for (it = offers.begin(); it != offers.end(); ++it) {
        KService::Ptr service = (*it);
        cout << "Navn: " << service->name() << endl;
    }

Returværdien fra funktionen er en liste med tjenesteudbydere. Et KServiceOffer-objekt pakker en KService::Ptr, sammen med et rangrækkefølgenummer. Listen som returneres af `KServiceTypeProfile::offers()` er ordnet efter hvad brugeren foretrækker. Brugeren kan ændre dette ved at kalde `"keditfiletype text/html"` eller vælge Redigér filtype i Konqueror's sammenhængsafhængige menu for en HTML-fil.

I eksemplet ovenfor, blev der bedt om en liste med tilbydere af programmer som understøtter `text/html`. Det omfatter, blandt andet, HTML-editorer såsom Quanta Plus. Du kan også erstatte det andet argument `"Application"` med `"KParts::ReadOnlyPart"`. I det tilfælde, får du en liste med indlejrbare komponenter til at præsentere HTML-indhold, for eksempel TDEHTML.

I de fleste tilfælde er du ikke interesseret i listen med alle tilbud om tjenester for en kombination af Mime-type og tjenestetype. Der er en bekvemmelighedsfunktion som kun giver dig de tjenestetilbud som foretrækkes mest:

    KService::Ptr offer = KServiceTypeProfile::preferredService("text/html", "Application");
    if (offer)
        cout << "Navn: " << service->name() << endl;
    else
        cout << "Ingen passende tjeneste fundet" << endl;

For endnu mere komplicerede forespørgsler, er der en fuldstændig CORBA-lignende handler.

For at køre en programtjeneste med nogle URL'er, bruges KRun:

    KURL::List urlList;
    urlList << "http://www.ietf.org/rfc/rfc1341.txt?number=1341";
    urlList << "http://www.ietf.org/rfc/rfc2046.txt?number=2046";
    KRun::run(offer.service(), urlList);

#### Diverse

I dette afsnit giver vi en liste over nogen af de programmeringsgrænseflader som på en eller anden måde hører sammen med den foregående beskrivelse.

Hent en ikon for en URL. Dette kigger efter URL'ens type, og returnerer en tilsvarende ikon.

    KURL url("ftp://ftp.kde.org/pub/incoming/wibble.c");
    TQString icon = KMimeType::iconForURL(url);

Kør en URL. Dette kigger efter URL'ens type, og starter et tilhørende program til typen som brugeren foretrækker.

    KURL url("http://dot.kde.org");
    new KRun(url);

### Netværkstransparens

#### Indledning

I internetalderen er det yderst vigtigt at desktopprogrammer kan få adgang til ressourcer via internettet: De skal kunne hente filer fra en web-server, skrive filer til en FTP-server eller læse e-mail fra en e-mail-server. Ofte kaldes muligheden for at få adgang til filer uafhængig af deres sted for netværkstransparens.

Tidligere implementeredes forskellige måder at nå dette mål. Det gamle NFS-filsystem er et forsøg på at implementere netværkstransparens på POSIX-grænsefladesniveau. Mens dette fungerer rigtigt godt i lokale, tætkoblede netværk, skalerer det ikke for ressourcer med utilforladelig og muligvis langsom adgang. Her er asynkronisme vigtig. Mens du venter på at browseren skal hente en side, skal brugergrænsefladen ikke blokeres. Desuden skal sidefremvisningen ikke begynde når hele siden er tilgængelig, men den skal opdateres regelmæssigt mens data ankommer.

I KDE-bibliotekerne implementeres netværkstransparens med TDEIO-programmeringsgrænsefladen. Det centrale begreb i arkitekturen er et I/O-job. Et job kan kopiere filer, fjerne filer og lignende ting. Så snart et job er startet, arbejder det i baggrunden og blokerer ikke programmet. Al kommunikation fra jobbet tilbage til programmet, såsom at leverere data eller fremgangsinformation, gøres integreret i Qt's begivenhedsløkke.

Baggrundsoperationer opnås ved at starte I/O-slaver til at udføre visse opgaver. I/O-slaver startes som separate processer, og kommunikation sker via Unix domæneudtag. På denne måde behøves intet flertrådssystem, og ustabile slaver kan ikke få programmet som bruger dem til at bryde sammen.

Filsteder udtrykkes med URL'er som er omfattende brugt. Men i KDE, udvider URL'er ikke kun området med tilgængelige filer udenfor det lokale filsystem. De går også i modsat retning, f.eks. kan man søge i tar-arkiver. Dette opnås ved at indlejre URL'er i hinanden. En fil i et tar-arkiv på en HTTP-server ville kunne have URL'en:

    http://www-com.physik.hu-berlin.de/~bernd/article.tgz#tar:/paper.tex

#### Brug af TDEIO

I de fleste tilfælde oprettes job ved at kalde funktioner i TDEIO-navnerummet. Disse funktioner har en eller to URL'er som argument, og muligvis også andre nødvendige parametre. Når jobbet er afsluttet, sender det signalet `result(TDEIO::Job*)`. Efter signalet er sendets, fjerner jobbet sig selv. Derfor ser et typisk brugertilfælde sådan her ud:

    void FooClass::makeDirectory()
    {
        SimpleJob *job = TDEIO::mkdir(KURL("file:/home/bernd/kiodir"));
        connect( job, TQ_SIGNAL(result(TDEIO::Job*)),
                 this, TQ_SLOT(mkdirResult(TDEIO::Job*)) );
    }

    void FooClass::mkdirResult(TDEIO::Job *job)
    {
        if (job->error())
            job->showErrorDialog();
        else
            cout << "mkdir gik godt" << endl;
    }

Afhængig af jobtypen, kan du også forbinde til andre signaler.

Her er en oversigt over de mulige funktioner:

TDEIO::mkdir(const KURL &url, int permission)

  Opretter en mappe, valgfrit med visse rettigheder.

TDEIO::rmdir(const KURL &url)

  Fjerner en mappe.

TDEIO::chmod(const KURL &url, int permissions)

  Ændrer rettigheder for en fil.

TDEIO::rename(const KURL &src, const KURL &dest, bool overwrite)

  Omdøber en fil.

TDEIO::symlink(const TQString &target, const KURL &dest, bool overwrite, bool showProgressInfo)

  Opretter et symbolsk link.

TDEIO::stat(const KURL &url, bool showProgressInfo)

  Finder nogen information om filen, såsom størrelse, ændringstid og rettigheder. Informationen kan hentes fra TDEIO::StatJob::statResult() efter jobbet er afsluttet.

TDEIO::get(const KURL &url, bool reload, bool showProgressInfo)

  Overfører data fra en URL.

TDEIO::put(const KURL &url, int permissions, bool overwrite, bool resume, bool showProgressInfo)

  Overfører data til en URL.

TDEIO::http_post(const KURL &url, const QByteArray &data, bool showProgressInfo)

  Sender data. Især for HTTP.

TDEIO::mimetype(const KURL &url, bool showProgressInfo)

  Forsøger at finde URL'ens Mime-type. Typen kan hentes fra TDEIO::MimetypeJob::mimetype() efter jobbet er afsluttet.

TDEIO::file_copy(const KURL &src, const KURL &dest, int permissions, bool overwrite, bool resume, bool showProgressInfo)

  Kopierer en enkelt fil.

TDEIO::file_move(const KURL &src, const KURL &dest, int permissions, bool overwrite, bool resume, bool showProgressInfo)

  Omdøber eller flytter en enkelt fil.

TDEIO::file_delete(const KURL &url, bool showProgressInfo)

  Sletter en enkelt fil

TDEIO::listDir(const KURL &url, bool showProgressInfo)

  Laver en liste med indholdet i en mappe. Hver gang nogle nye indgange bliver kendte, sendes signalet TDEIO::ListJob::entries().

TDEIO::listRecursive(const KURL &url, bool showProgressInfo)

  Ligner funktionen listDir(), men denne er rekursiv.

TDEIO::copy(const KURL &src, const KURL &dest, bool showProgressInfo)

  Kopierer en fil eller mappe. Mapper kopieres rekursivt.

TDEIO::move(const KURL &src, const KURL &dest, bool showProgressInfo)

  Flytter eller omdøber en fil eller mappe.

TDEIO::del(const KURL &src, bool shred, bool showProgressInfo)

  Sletter en fil eller mappe.

#### Mappeindgange

Begge jobbene TDEIO::stat() og TDEIO::listDir() returnerer deres resultater med typerne UDSEntry og UDSEntryList. Den sidste er defineret som QValueList<UDSEntry>. Forkortelsen UDS betyder "Universal directory service" (Generel mappetjeneste). Principperne bagved dette er at mappeindgangen kun indeholder information som en I/O-slave kan sørge for, ikke mere. For eksempel sørger HTTP-slaven ikke for nogen information om adgangsrettigheder eller ejere af filer. I stedet er en UDSEntry en liste med UDSAtoms. Hvert objekt sørger for en vis information. Den består af en type som opbevares i m_uds, og enten en heltalsværdi i m_long, eller en strengværdi i m_str, afhængig af typen.

Følgende typer er for øjeblikket definerede:

- UDS_SIZE (heltal) - Filens størrelse.

- UDS_USER (streng) - Brugeren som ejer filen.

- UDS_GROUP (streng): Gruppen som ejer filen.

- UDS_NAME (streng): Filnavnet.

- UDS_ACCESS (heltal) - Filens rettigheder, som f.eks. opbevares af C-biblioteksfunktionen stat() i feltet st_mode.

- UDS_FILE_TYPE (heltal): Filtypen, som f.eks. opbevares af stat() i feltet st_mode. Derfor kan du bruge almindelige makroer fra C-biblioteket, som S_ISDIR, for at kontrollere værdien. Bemærk at data som sørges for af I/O-slaver svarer til stat(), ikke lstat(), dvs. i tilfældet med symbolske link, så er filtyperne typen på filen som linket peger på, ikke selve linket.

- UDS_LINK_DEST (streng): I tilfældet med et symbolsk link, navnet på filen som udpeges.

- UDS_MODIFICATION_TIME (heltal) - Tiden (med typen time_t) da filen sidst ændredes, som f.eks. opbevares af stat() i feltet st_mtime.

- UDS_ACCESS_TIME (heltal) - Tiden da filen sidst blev brugt, som f.eks. opbevares af stat() i feltet st_atime.

- UDS_CREATION_TIME (heltal) - Tiden da filen oprettedes, som f.eks. opbevares af stat() i feltet st_ctime.

- UDS_URL (streng) - Sørger for en fils URL, hvis den ikke blot er sammensætningen af mappens URL og filnavnet.

- UDS_MIME_TYPE (streng): Filens Mime-type

- UDS_GUESSED_MIME_TYPE (streng): Mime-type for filen som gættet af slaven. Forskellen til den foregående type er at den som sørges for her ikke skal betragtes som tilforladelig (eftersom at afgøre den på en tilforladelig måde ville være for dyrt). Klassen KRun kontrollerer for eksempel udtrykkelig Mime-typen, hvis den ikke har tilforladelig information.

Selv om måden at opbevare information om filer i en UDSEntry er fleksibel og praktisk ud fra en I/O-slaves synvinkel, er det noget rod at bruge for den som skriver programmet. For eksempel for at finde ud af Mime-typen for filen, skal du løbe gennem hele indholdet og kontrollere om `m_uds` er `UDS_MIME_TYPE`. Heldigvis, er der en programmeringsgrænseflade som er meget nemmere at bruge: klassen KFileItem.

#### Synkron brug

Ofte er TDEIO's asynkrone programmeringsgrænseflade for kompleks at bruge, og derfor er implementering af fuldstændig asynkronisme ikke en prioritet. I et program som for eksempel kun kan håndtere en dokumentfil af gangen, er der alligevel ikke meget som kan gøres mens programmet henter en fil. I disse enkle tilfælde, er der en meget nemmere programmeringsgrænseflade, i form af et antal statiske funktioner i TDEIO::NetAccess. For eksempel for at kopiere en fil, bruges:

    KURL source, target;
    source = ...;
    target = ...
    TDEIO::NetAccess::copy(source, target);

Funktionen returnerer efter hele kopieringsprocessen er afsluttet. Alligevel så sørger denne metode for en fremgangsdialog, og den sikrer at programmet behandler omtegningsbegivenheder.

En særlig interessant kombination af funktioner er `download()` sammen med `removeTempFile()`. Den første henter en fil fra en given URL, og gemmer den i en midlertidig fil med et entydigt navn. Navnet opbevares som det andet argument. Hvis URL'en er lokal, hentes filen ikke, men i stedet sættes det andet argument til det lokale filnavn. Funktionen `removeTempFile()` sletter filen som angives af argumentet, hvis filen blev oprettet af den foregående nedtegning. Hvis dette ikke er tilfældet, gør den ingenting. På den måde får man et meget enkelt kodefragment til at indlæse filer, uafhængig af deres sted:

    KURL url;
    url = ...;
    TQString tempFile;
    if (TDEIO::NetAccess::download(url, tempFile) {
        // indlæse filen med navnet tempFile
        TDEIO::NetAccess::removeTempFile(tempFile);
    }

#### Metadata

Som det ses ovenfor, er grænsefladen for I/O-job ganske abstrakt og håndterer ikke nogen udbytning af information mellem programmer og I/O-slaver som er protokolspecifik. Det er ikke altid passendet. Man kan for eksempel give visse parametre til HTTP-slaven for at styre dens cacheopførsel eller sende en mængde cookies sammen med forespørgsler. Til dette behov er et begreb med metadata indført. Når et job oprettes, kan man indstille det ved at tilføje metadata til det. Hvert metadataobjekt består af et par med nøgle og værdi. For eksempel for at forhindre HTTP-slaven fra at hente en URL fra cachen, kan du bruge:

    void FooClass::reloadPage()
    {
        KURL url("http://www.kdevelop.org/index.html");
        TDEIO::TransferJob *job = TDEIO::get(url, true, false);
        job->addMetaData("cache", "reload");
        ...
    }

Samme teknik bruges i den anden retning, dvs. til kommunikation fra slaven til programmet. Metoden `Job::queryMetaData()` spørger efter værdien af en vis nøgle som levereres af slaven. For HTTP-slaven, er et sådant eksempel nøglen `"modified"` (ændret), som indeholder datoen da URL'en sidst blev ændret (i form af en streng). Et eksempel på hvordan det kan bruges er følgende:

    void FooClass::printModifiedDate()
    {
        KURL url("http://developer.kde.org/documentation/kde2arch/index.html");
        TDEIO::TransferJob *job = TDEIO::get(url, true, false);
        connect( job, TQ_SIGNAL(result(TDEIO::Job*)),
                 this, TQ_SLOT(transferResult(TDEIO::Job*)) );
    }

    void FooClass::transferResult(TDEIO::Job *job)
    {
        TQString mimetype;
        if (job->error())
            job->showErrorDialog();
        else {
            TDEIO::TransferJob *transferJob = (TDEIO::TransferJob*) job;
            TQString modified = transferJob->queryMetaData("modified");
            cout << "Seneste ændring: " << modified << endl;
    }

#### Skemalægning

Når TDEIO-programmeringsgrænsefladen bruges, behøver du oftest ikke håndtere detaljerne med at starte I/O-slaver og kommunikere med dem. Det normale brugstilfælde er at starte et job med nogle parametre, og håndtere signalerne som jobbet sender.

Bagved scenen er scenariet meget mere kompliceret. Når du opretter et job, lægges det i en kø. Når programmet går tilbage til begivenhedsløkken, tildeles TDEIO slaveprocesser for jobbene i køen. For det første job som startes, er dette trivielt: en I/O-slave for en passende protokol startes. Efter jobbet (såsom en download fra en HTTP-server) er afsluttet, tages det dog ikke væk med det samme. I stedet tilføjes det til en gruppe med ledige slaver og fjernes efter en vis tid uden aktivitet (for øjeblikket tre minutter). Hvis en ny forespørgsel for samme værtsmaskine og protokol ankommer, genbruges slaven. Den åbenbare fordel er at ved en serie job med samme værtsmaskine, sparer man omkostningen ved at oprette nye processer, og muligvis også at gå gennem adgangskontrol.

Naturligvis er genbrug kun mulig når den eksisterende slave allerede har afsluttet sit tidligere job. Hvis en ny forespørgsel ankommer mens en eksisterende slaveproces stadigvæk kører, skal en ny proces startes og bruges. Med brugen i eksemplerne ovenfor af programmeringsgrænsefladen, er der ingen begrænsning på at oprette nye slaveprocesser: hvis man starter en serie download af 20 forskellige filer i række, laver TDEIO 20 slaveprocesser. Dette system til at tildele slaver til job kaldes direkte. Det er ikke altid det mest passende system, eftersom det kan behøve meget hukommelse og give høj belastning både på klient- og servermaskine.

Så der er en anden måde. Man kan skemalægge job. Hvis man gør det, laves kun et begrænset antal (for øjeblikket tre) slaveprocesser for en protokol. Hvis du opretter flere job endnu det, så tilføjes de i en kø og behandles når en slaveprocess bliver ledig. Det gøres på følgende måde:

    KURL url("http://developer.kde.org/documentation/kde2arch/index.html");
    TDEIO::TransferJob *job = TDEIO::get(url, true, false);
    TDEIO::Scheduler::scheduleJob(job);

En tredje mulighed er forbindelsesorienteret. For eksempel for IMAP-slaven, giver det ikke mening at starte flere processer for samme server. Kun en IMAP-forbindelse af gangen skal opretholdes. I dette tilfælde skal programmet udtrykkelig håndtere slavebegrebet. Det skal tildele en slave for en vis forbindelse og derefter tildele alle job som skal gå til samme forbindelse til samme slave. Dette kan igen nemt opnås ved at bruge TDEIO::Scheduler:

    KURL baseUrl("imap://bernd@albert.physik.hu-berlin.de");
    TDEIO::Slave *slave = TDEIO::Scheduler::getConnectedSlave(baseUrl);

    TDEIO::TransferJob *job1 = TDEIO::get(KURL(baseUrl, "/INBOX;UID=79374"));
    TDEIO::Scheduler::assignJobToSlave(slave, job1);

    TDEIO::TransferJob *job2 = TDEIO::get(KURL(baseUrl, "/INBOX;UID=86793"));
    TDEIO::Scheduler::assignJobToSlave(slave, job2);

    ...

    TDEIO::Scheduler::disconnectSlave(slave);

Du kan kun afbryde slaven efter alle job som blev tildelt den er garanteret at være afsluttet.

#### Definition af en I/O-slave

I det følgende beskriver vi hvordan du kan tilføje en ny I/O-slave til systemet. På lignende måde som tjenester, annonceres I/O-slaver for systemet ved at installere en lille konfigurationsfil. Følgende fragment af Makefile.am installerer FTP-protokollen:

    protocoldir = $(kde_servicesdir)
    protocol_DATA = ftp.protocol
    EXTRA_DIST = $(mime_DATA)

Indholdet i filen ftp.protocol er følgende:

    [Protocol]
    exec=tdeio_ftp
    protocol=ftp
    input=none
    output=filesystem
    listing=Name,Type,Size,Date,Access,Owner,Group,Link,
    reading=true
    writing=true
    makedir=true
    deleting=true
    Icon=ftp

Indgangen `"protocol"` angiver hvilken protokol som slaven har ansvar for. `"exec"` er (i modsætning til hvad man naivt kan forvente sig) navnet på biblioteket som implementerer slaven. Når det er meningen at slaven skal starte, startes programmet `"tdeinit"`, som derefter indlæser biblioteket i sit adresserum. I praksis kan du betragte slaven som kører som en separat proces, også selvom den er implementeret som et bibliotek. Fordelen ved denne mekanisme er at det sparer meget hukommelse, og reducerer tiden som behøves til linkning under kørsel.

Linjerne "input" og "output" bruges ikke for øjeblikket.

De tilbageværende linjer i filen `.protocol` angiver hvilke muligheder slaven har. Generelt er de funktioner som slaven skal implementere meget enklere end de funktioner som TDEIO-programmeringsgrænsefladen sørger for programmet. Grunden til dette er at komplekse job skemalægges som en følge af deljob. For eksempel for at få en liste over en mappe rekursivt, startes et job for topniveaumappen. For hver undermappe som rapporteres tilbage, startes nye underjob. Skemalægning i TDEIO sikrer at ikke for mange job er aktive samtidigt. På lignende måde, for at kopiere en fil med en protokol som ikke understøtter kopiering direkte (såsom `FTP`-protokollen), kan TDEIO læse kildefilen og derefter skrive data til målfilen. For at dette skal virke, skal `.protocol` annoncere handlingerne som slaven understøtter.

Eftersom slaver indlæses som delte biblioteker, men udgør fuldstændige programmer, ser deres kodeskelet noget anderledes ud sammenlignet med normale delte biblioteks-plugin. Funktionen som kaldes for at starte slaven kaldes `kdemain()`. Denne funktion gør en del initieringer, og går derefter ind i en begivenhedsløkke og venter på forespørgsler fra programmet som bruger den. Dette ser ud som følger:

    extern "C" { int kdemain(int argc, char **argv); }

    int kdemain(int argc, char **argv)
    {
        TDELocale::setMainCatalogue("tdelibs");
        TDEInstance instance("tdeio_ftp");
        (void) TDEGlobal::locale();

        if (argc != 4) {
            fprintf(stderr, "Usage: tdeio_ftp protocol "
                            "domain-socket1 domain-socket2\n");
            exit(-1);
        }

        FtpSlave slave(argv[2], argv[3]);
        slave.dispatchLoop();
        return 0;
    }

#### Implementering af en I/O-slave

Slaver implementeres som delklasser til TDEIO::SlaveBase (FtpSlave i eksemplet ovenfor). På den måde svarer handlingerne i `.protocol` til visse virtuelle funktioner i TDEIO::SlaveBase som implementeringen af slaven skal omimplementere. Her er en liste med mulige handlinger og tilsvarende virtuelle funktioner:

læse: Læser data fra en URL

  void get(const KURL &url)

skrive: Skriver data til en URL og opretter filen hvis den ikke findes endnu.

  void put(const KURL &url, int permissions, bool overwrite, bool resume)

flytte: Omdøber filen.

  void rename(const KURL &src, const KURL &dest, bool overwrite)

slette: Fjerner en fil eller mappe.

  void del(const KURL &url, bool isFile)

liste: Giver en liste med indholdet i en mappe.

  void listDir(const KURL &url)

oprette mappe: Opretter en mappe.

  void mkdir(const KURL &url, int permissions)

Desuden er der funktioner som kan omimplementeres, og ikke er på listen i filen `.protocol`. For disse handlinger, afgør TDEIO automatisk om de understøttes eller ej (dvs. standardimplementationen returnerer en fejl).

Leverer information om en fil, ligner C-funktionen stat().

  void stat(const KURL &url)

Ændrer adgangsrettigheder for en fil.

  void chmod(const KURL &url, int permissions)

Afgør Mime-type for en fil.

  void mimetype(const KURL &url)

Kopierer en fil.

  copy(const KURL &url, const KURL &dest, int permissions, bool overwrite)

Opretter et symbolsk link.

  void symlink(const TQString &target, const KURL &dest, bool overwrite)

Alle disse implementationer skal slutte af med et af to kald: Hvis handlingen lykkedes, skal de kalde `finished()`. Hvis en fejl opstod, skal de kalde `error()` med en fejlkode som første argument og en streng som andet. Mulige fejlkoder er på listen som nummereringstypen TDEIO::Error. Det andet argument er oftest URL'en det drejer sig om. Den bruges f.eks. i `TDEIO::Job::showErrorDialog()` for at parametrisere fejlmeddelelsen som er læsbart af brugeren.

For slaver som svarer til netværksprotokoller, kan det være interessant at omimplementere metoden `SlaveBase::setHost()`. Den kaldes for at fortælle slaveprocessen om værtsmaskine og port, og brugernavn og kodeord der skal bruges for at logge på. Generelt kan metadata som angives af programmet hentes med `SlaveBase::metaData()`. Du kan kontrollere om metadata med en vis nøgle findes med `SlaveBase::hasMetaData()`.

#### Kommunikation tilbage til programmet

Diverse handlinger som implementeres i en slave, behøver en måde at sende data tilbage til programmet som bruger slaveprocessen.

- `get()` sender datablokke. Det gøres med `data()`, som bruger argumentet QByteArray. Du behøver naturligvis ikke sende al data på en gang. Hvis du sender en stor fil, så kald `data()` med mindre datablokke, så programmet kan behandle dem. Kald `finished()` når overførslen er klar.

- `listDir()` rapporterer information om indgangene i en mappe. Kald `listEntries()` med en TDEIO::UDSEntryList som argument, for dette formål. På tilsvarende måde som `data()`, kan du kalde den flere gange. Når du er klar, så kald `listEntry()` med det andet argument sat til true. Du kan også kalde `totalSize()` for at rapportere det totale antal mappeindgange, hvis det er kendt.

- `stat()` rapporterer information om en fil, såsom størrelse, Mime-type, etc. Sådan information pakkes i en TDEIO::UDSEntry, som beskrives nedenfor. Brug `statEntry()` for at sende et sådant objekt til programmet.

- `mimetype()` kalder `mimeType()` med et strengargument.

- `get()` og `copy()` vil måske sørge for fremgangsinformation. Dette gøres med metoderne `totalSize()`, `processedSize()` og `speed()`. Den totale størrelse og den behandlede størrelse rapporteres som byte, og hastigheden som byte pr sekund.

- Du kan sende vilkårlige nøgle/værdipar af metadata med `setMetaData()`.

#### Kommunikation med brugeren

Ind imellem skal en slave kommunikere med brugeren. Eksempler kan være informative meddelelser, dialoger til godkendelseskontrol og bekræftelsesdialoger når en fil er ved at blive overskrevet.

- `infoMessage()`: Dette er for informativ tilbagemelding, såsom meddelelsen "Henter data fra <værtsmaskine>" fra HTTP-slaven, som ofte vises i programmets statuslinje. På programsiden, svarer metoden til signalet `TDEIO::Job::infoMessage()`.

- `warning()`: Viser en advarsel i et meddelelsesfelt med `KMessageBox::information()`. Hvis et meddelelsesfelt stadigvæk vises fra et tidligere kald af warning() fra samme underproces, sker der ingenting.

- `messageBox()`: Denne er endnu udførligere end den tidligere metode. Den tillader at et meddelelsesfelt med tekst og titel og nogle knapper vises. Se nummereringstypen SlaveBase::MessageBoxType som reference.

- `openPassDlg()`: Viser en dialog til at indtaste brugernavn og kodeord.

## Licenser

&underFDL; &underGPL;