http://docs.kde.org/
FöregåendeKoncept för användning i specialiserade insticksprogramNästa

Förhandsgranskningar av data, utmatning och andra resultat

Förhandsgranskning av (HTML-)utmatning

Notera

Det här avsnittet beskriver hur förhandsgranskningsfunktionalitet läggs till i insticksprogram som skapar utmatning eller HTML-utskrifter. Vi rekommenderar att du läser det separata avsnittet om förhandsgranskning av diagram innan det här avsnittet.

Att skapa en förhandsgranskning av HTML-utmatning använder nästan samma procedur som att skapa en förhandsgranskning av ett diagram. I det här fallet måste man bara försäkra sig om att preview() genererar relevanta kommandon med rk.print()/rk.results(). Det är i allmänhet en god idé att utelämna rubriksatser i förhandsgranskningen. Här är ett avkortat exempel: 

<!-- I insticksprogrammets XML-fil -->>
        <dialog label="Import CSV data" >
                <browser id="file" type="file" label="File name"/>
                <!-- [...] -->>
                <preview id="preview" mode="output"/>
        </dialog>
>

Observera specifikationen av mode="output" i elementet <preview>. 

// In the plugin's JS file
        function preview () {
                // skapa koden som används för förhandsgranskningen
                printout (true);
        }

        function printout (is_preview) {
                // genererar bara en rubrik om is_preview==false
                if (!is_preview) {
                        new Header ("This is a caption").print ();
                }
                echo ('rk.print (result)');
        }

Förhandsgranskningar av (importerad) data

Notera

Det här avsnittet beskriver hur förhandsgranskningsfunktionalitet läggs till i insticksprogram som skapar (importerar) data. Vi rekommenderar att du läser det separata avsnittet om förhandsgranskning av diagram innan det här avsnittet.

Att skapa en förhandsgranskning av importerad data (vilken typ av data som helst som rk.edit() kan hantera), liknar mycket att skapa en förhandsgranskning av diagram. Följande avkortade exemplet bör hjälpa till att illustrera hur en dataförhandsgranskning skapas: 

<!-- I insticksprogrammets XML-fil -->>
        <dialog label="Import CSV data" >
                <browser id="file" type="file" label="File name"/>
                <!-- [...] -->>
                <preview id="preview" active="true" mode="data"/>
        </dialog>
>

Observera att elementet <preview> anger mode="data" den här gången. active="true" gör helt enkelt förhandsgranskningen normalt aktiv. 

// In the plugin's JS file
        function preview () {
                // genererar koden använd för förhandsgranskning
                calculate (true);
        }

        function calculate (is_preview) {
                echo ('imported <- read.csv (file="' + getString ("file") /* [+ options] */);
                if (is_preview) {
                        echo ('preview_data <- imported\n');
                } else {
                        echo ('.GlobalEnv$' + getString ("name") + ' >- imported\n');
                }
        }

        function printout () {
                // [...]
        }

Återigen genererar funktionen preview() nästan samma R-kod som funktionen calculate(), så vi skapar hjälpfunktionen doCalculate() för att plocka ut de gemensamma delarna. Det viktigaste att observera är att importerad data måste tilldelas till objektet som heter preview_data (inne i den aktuella, lokala, omgivningen). Allt annat sker automatiskt (grovt sett anropar RKWard rk.edit(preview_data), omgivet av ett anrop till .rk.with.window.hints()).

Notera

Medan förhandsgranskningar är en utmärkt funktion, kräver de resurser. I fallet med dataförhandsgranskningar, kan det finnas fall då förhandsgranskningar kan orsaka betydande prestandaproblem. Det kan vara för import av mycket stora datamängder (som helt enkelt är för stora att öppna för redigering i RKWards editorfönster), men också för "normala" datamängder som kan importeras felaktigt, vilket skapar ett mycket stort antal rader eller kolumner. Det rekommenderas starkt att preview_data begränsas till en dimension som ger en användbar förhandsgranskning, utan risk att skapa märkbara prestandaproblem (t.ex. 50 rader och 50 kolumner bör vara mer än tillräckligt i de flesta fall).

Anpassade förhandsgranskningar

Elementet <preview> kan användas för att skapa förhandsgranskningar av godtycklig typ av "dokumentfönster" som kan anslutas till RKWards arbetsrymd. Förutom diagram och datafönster, inkluderar det HTML-filer, R-skript och fönster med objektsammanfattningar. För de senare, måste <preview mode="custom"> användas.

Om du har läst avsnitten som beskriver förhandsgranskningar av diagram och data, bör du ha en allmän idé om proceduren, men förhandsgranskningar av typen "custom" kräver något mer manuellt arbete bakom kulisserna. Den viktigaste R-funktionen att titta på här är rk.assign.preview.data(). Följande korta listning visar hur den genererade R-koden (för förhandsgranskning) skulle kunna se ut för ett insticksprogram som skapar textfilutmatning: 

## Att genereras i kodsektionen preview() i ett insticksprogram
        pdata <- rk.get.preview.data("SOMEID")
        if (is.null (pdata)) {
                outfile <- rk.get.tempfile.name(prefix="preview", extension=".txt")
                pdata <- list(filename=outfile, on.delete=function (id) {
                        unlink(rk.get.preview.data(id)$filename)
                })
                rk.assign.preview.data("SOMEID", pdata)
        }
        try ({
                cat ("This is a test", pdata$filename)
                rk.edit.files(file=pdata$filename)
        })

Här ska värdet SOMEID hämtas från egenskapen id i elementet <preview>, dvs. genom att använda getString ("preview.id") i insticksprogrammets .js-fil.