>&chalk; è infinitamente estensibile. Gli strumenti, i filtri, ampie parti dell'interfaccia utente e anche gli spazi di colori sono plugin. &chalk; riconosce sei tipi di plugin: </para>
>&chalk; stesso è costituito da tre librerie stratificate e una cartella con alcune classi comuni di supporto: chalkcolor, chalkimage e chalkui. All'interno di &chalk;, gli oggetti possono essere identificati da un <classname
>, cioè una combinazione di una stringa univoca non tradotta (usata per esempio nei salvataggi) e una stringa tradotta per l'uso nell'interfaccia utente. </para
>Due parole sulla compatibilità: &chalk; è ancora in fase di sviluppo. Da &chalk; 1.5 a 1.6 non ci si attendono molti cambiamenti nell'API, ma potrebbe essercene qualcuno. Da &chalk; 1.6 a 2.0 ci sposteremo da &Qt;3 a &Qt;4, da &kde;3 a &kde;4, da <command
>: ci si attendono molti cambiamenti. Se sviluppi un plugin per &chalk; e scegli di farlo nel deposito Subversion di &chalk;, molto probabilmente ti aiuteremo nel trasferimento. Questi cambiamenti potrebbero rendere obsolete parti di questo documento. Controlla sempre l'ultima documentazione dell'API o i file di intestazione installati sul tuo sistema. </para>
>La libreria chalkimage carica i plugin di filtraggio e delle operazioni di disegno, ed è responsabile del lavoro con i dati delle immagini: cambio dei pixel, composizione e disegno. Anche i pennelli, tavolozze, sfumature e motivi sono caricati da libchalkimage. È nostro obiettivo dichiarato rendere libchalkimage indipendente da &koffice;, ma attualmente condividiamo il codice di caricamento delle sfumature con &koffice;. </para
>Non è facile al momento aggiungere nuovi tipi di risorse come pennelli, tavolozze, sfumature o motivi a &chalk; (aggiungere nuovi pennelli, tavolozze, sfumature o motivi è invece ovviamente facile). &chalk; segue le linee guida del progetto Create (<ulink url="http://create.freedesktop.org/"
>). Aggiungere il supporto per il formato dei pennelli di Photoshop richiede modifiche a libchalkimage; aggiungere nuovi file di dati per i pennelli di Gimp, no. </para
>. Un esempio di filtro è la maschera di contrasto.</para
></listitem>
<listitem
><para
>Le operazioni di disegno sono l'insieme di operazioni che gli strumenti di disegno come la mano libera e il cerchio hanno a disposizione. Esempi di operazioni sono la penna, l'aerografo o la gomma. Le operazioni dovrebbero estendere la classe di base <classname
>KisPaintop</classname
>. Esempi di nuove operazioni potrebbero essere un gessetto, un pennello a olio, o un complesso pennello programmabile.</para
>La libreria libchalkui carica i plugin degli strumenti e di vista. Questa libreria è un componente di &koffice;, ma contiene anche un certo numero di widget utili alle applicazioni grafiche. Forse dovremo dividere questa libreria in chalkpart e chalkui nel rilascio 2.0. Per ora, chi scrive script non ha accesso alla libreria e chi scrive plugin può usarla solo quando scrive plugin per strumenti o di vista. <classname
> o una delle classi di base degli strumenti specializzati come <classname
>KisToolPaint</classname
>, <classname
>KisToolNonPaint</classname
> o <classname
>KisToolFreehand</classname
>. Un nuovo strumento potrebbe essere uno strumento di selezione degli oggetti in primo piano. Gli strumenti di disegno (inclusi gli strumenti che disegnano sulla selezione) possono usare qualsiasi operazione di disegno per determinare in che modo vengono cambiati i pixel.</para
></listitem>
<listitem
><para
>I plugin di vista sono normali componenti KPart che usano <command
> per infilarsi nell'interfaccia utente di &chalk;. Le opzioni dei menu, le finestre, le barre degli strumenti, insomma qualsiasi tipo di estensione all'interfaccia utente può essere un plugin di vista. In effetti, importanti funzionalità come il supporto per gli script di &chalk; sono scritte come plugin di vista.</para
>. I filtri leggono e scrivono i dati delle immagini in uno qualsiasi della miriade di formati di immagine esistenti. Un esempio di un nuovo filtro di importazione ed esportazione di &chalk; potrebbe essere un filtro PDF. I filtri vengono caricati dalle librerie di &koffice;. </para>
>I plugin si scrivono in C++ e possono usare tutta l'API di &kde;, &Qt; e &chalk;. Solo i plugin di vista dovrebbero usare l'API di &koffice;. Non preoccuparti: le API di &chalk; sono piuttosto chiare e ben documentate (per essere software libero) e scrivere il tuo primo filtro è veramente facile. </para
>Se non vuoi usare il C++, puoi scrivere degli script in Python o Ruby; questa è però tutta un'altra cosa, però, e al momento non puoi scrivere strumenti, spazi di colori, operazioni o filtri di importazione ed esportazione come script. </para
>La tua distribuzione dovrebbe avere installato i file di intestazione di rilievo con &chalk; stesso, o potrebbe averli divisi in un pacchetto per sviluppatori di &koffice; o &chalk;. Puoi trovare la documentazione dell'API pubblica di &chalk; a <ulink url="http://koffice.org/developer/apidocs/chalk/html/"
>&kde; 3.x e quindi &koffice; 1.5 e 1.6 usano <command
>automake</command
>; &kde; 4.0 e &koffice; 2.0 usano <command
>cmake</command
>. Questa esercitazione descrive come creare plugin con <command
>automake</command
>. </para
><para
>I plugin sono moduli di &kde; e dovrebbero essere segnalati come tali nei loro <filename
>Makefile.am</filename
>. I filtri, gli strumenti, le operazioni di disegno, gli spazi di colori e i filtri di importazione ed esportazione richiedono dei file <literal role="extension"
>.desktop</literal
>; i plugin di vista richiedono inoltre un file <application
>. Il modo più semplice di cominciare è scaricare il progetto plugin di chalk dal deposito Subversion di &koffice; e usarlo come base per il proprio progetto. Abbiamo intenzione di preparare uno pacchetto di base per i plugin di &chalk; per KDevelop, ma non ne abbiamo ancora avuto il tempo. </para>
> Questo è il makefile per un plugin di filtro. Sostituisci <replaceable
>LIBRARYNAME</replaceable
> con il nome del tuo progetto, e sei a posto. </para
><para
>Se il tuo è un plugin di vista, dovrai probabilmente installare anche un file <literal role="extension"
>.rc</literal
> con le voci per le barre dei menu e degli strumenti. Allo stesso modo, potresti dover installare cursori ed icone. Tutto questo si può fare attraverso le solite magie per <filename
>I filtri di importazione ed esportazione usano l'infrastruttura di filtraggio generica di &koffice; e vanno discussi a parte. </para>
</sect4>
<sect4 id="d-p-c-a-boilerplate">
<title
>Codice da riutilizzare</title>
<para
>Hai anche bisogno di un po' di codice comune chiamato dall'infrastruttura dei componenti di &kde; per avviare il plugin: un file di intestazione e uno di implementazione. </para
KisToolRegistry * r = dynamic_cast<KisToolRegistry*>( parent );
r -> add(new KisToolStarFactory());
}
}
ToolStar::~ToolStar()
{
}
#include "tool_star.moc"
</programlisting>
</para>
</sect4>
<sect4 id="d-p-c-a-registries">
<title
>Registri</title>
<para
>Gli strumenti sono caricati dal registro degli strumenti e si registrano con esso. I plugin come strumenti, filtri e operazioni di disegno vengono caricati una sola volta: i plugin di vista vengono caricati per ogni vista creata. Nota che generalmente noi registriamo delle fabbriche. Per esempio, con gli strumenti, si crea una nuova istanza di uno strumento per ogni puntatore (mouse, penna, gomma), e viene creata una nuova operazione di disegno ogni volta che uno strumento riceve un evento di mouse premuto. </para>
<para
>I filtri chiamano il registro dei filtri: <programlisting
>Ricordati che questo vuol dire che un plugin di vista sarà creato per ogni vista creata dall'utente: dividere una vista significa ricaricare tutti i plugin. </para>
>. I file binari dei plugin di &chalk; 1.6 probabilmente saranno incompatibili con i plugin 1.5 e richiederanno il numero di versione 3. I plugin di &chalk; 2.0 richiederanno il numero di versione 3. Sì, effettivamente non è del tutto logico. </para>
>Implementare uno spazio di colori è piuttosto facile. Il principio generale è che gli spazi di colori lavorano con un semplice array di byte. L'interpretazione di questi byte è lasciata allo spazio di colori. Per esempio, un pixel in grigio a 16 bit consiste di quattro byte: due byte per il valore del grigio e due per il valore alfa. Sei libero di usare una struttura per lavorare con lo schema di memorizzazione di un pixel nell'implementazione del tuo spazio di colori, ma la rappresentazione non viene esportata. L'unico modo in cui il resto di &chalk; può capire di quali canali e di quale tipo consistano i pixel del tuo spazio di colori è attraverso la classe <classname
>Questa classe definisce i canali che costituiscono un singolo pixel in un certo spazio di colori. Un canale ha le seguenti importanti caratteristiche: </para>
<itemizedlist>
<listitem
><para
>un nome da visualizzare nell'interfaccia utente</para
></listitem>
<listitem
><para
>una posizione: il byte dove cominciano i byte che rappresentano questo canale nel pixel.</para
></listitem>
<listitem
><para
>un tipo: colore, alfa, sostanza o substrato. Il colore è il semplice colore, alfa è la trasparenza, la sostanza è una rappresentazione della quantità di pigmento o cose simili, il substrato è la rappresentazione della tela (nota che questo potrebbe essere rifattorizzato in men che non si dica).</para
></listitem>
<listitem
><para
>un tipo di valore: byte, corto, intero, a virgola mobile o altro.</para
></listitem>
<listitem
><para
>dimensione: il numero di byte presi da questo canale</para
></listitem>
<listitem
><para
>colore: una rappresentazione <classname
>QColor</classname
> di questo canale per la visualizzazione nell'interfaccia utente, per esempio con istogrammi.</para
></listitem>
<listitem
><para
>un'abbreviazione da usare nell'interfaccia quando non c'è molto spazio</para
>Un plugin per spazi di colori può supportare qualsiasi sottoinsieme di queste possibili operazioni di composizione, ma l'insieme deve sempre includere "OVER" (lo stesso che "NORMAL") e "COPY". Il resto è più o meno opzionale, anche se ovviamente più ce n'è meglio è. </para>
>I metodi nella classe puramente virtuale <classname
>KisColorSpace</classname
> possono essere divisi in un certo numero di gruppi: conversione, identificazione e manipolazione. </para
><para
>Tutte le classi devono poter convertire un pixel da e in RGB a 8 bit (per esempio, un <classname
>QColor</classname
>), e preferibilmente anche in e da L*a*b a 16 bit. Inoltre, c'è un metodo per convertire in qualsiasi spazio di colori da quello attuale. </para
><para
>Gli spazi di colori sono descritti dal vettore <classname
>KisChannelInfo</classname
>, il numero di canali, il numero di byte in un singolo pixel, se supporta le immagini ad alto raggio dinamico (<foreignphrase lang="en"
>High Dynamic Range</foreignphrase
>, HDR) e altro. </para
><para
>La manipolazione è, per esempio, la combinazione di due pixel in uno nuovo: bitBlt, oscuramento o convoluzione dei pixel. </para
><para
>Consulta la documentazione dell'API per una descrizione completa di tutti i metodi che devi implementare in uno spazio di colori. </para
><para
><classname
>KisAbstractColorSpace</classname
> implementa molti dei metodi virtuali di <classname
>KisColorSpace</classname
> usando funzioni della libreria <command
>lcms</command
>. Oltre a <classname
>KisAbstractColorSpace</classname
> ci sono classi di base per gli spazi di colori a 8 e 16 bit interi e 16 e 32 bit a virgola mobile che definiscono operazioni comuni per spostarsi tra profondità in bit. </para>
>I filtri sono plugin che esaminano i pixel in un livello e ci effettuano modifiche. Sebbene &chalk; usi un'efficiente interfaccia a memoria affiancata per memorizzare i pixel, gli autori di filtri non devono preoccuparsi di ciò. Quando scrivi un plugin di filtraggio per l'API grafica di &Java;, Photoshop o Gimp, devi fare attenzione ai bordi dei riquadri e <quote
>Nota che è teoricamente facile sostituire l'attuale interfaccia di memorizzazione affiancata dei dati delle immagini con un'altra, ma quelle interfacce non sono al momento veri plugin, per motivi di prestazioni.</para
>&chalk; usa gli iteratori per leggere e scrivere i valori dei pixel. In alternativa, puoi leggere un blocco di pixel in memoria temporanea, lavorarci e riscriverlo in blocco. Però ciò non è necessariamente più efficiente, e potrebbe anche essere più lento che usare gli iteratori; potrebbe semplicemente essere più comodo. Vedi la documentazione dell'API. </para
>Le immagini di &chalk; sono composte di livelli, dei quali ci sono al momento quattro tipi: livelli di disegno, di gruppo, di regolazione (che contengono un filtro applicato dinamicamente ai livelli inferiori) e di parte. I filtri operano sempre nei livelli di disegno. Questi contengono dispositivi di disegno, della classe <classname
>. Un dispositivo di disegno, a sua volta, permette l'accesso ai pixel. </para
><para
>I <classname
>PaintDevice</classname
> sono generalmente passati come puntatori condivisi. Un puntatore condiviso tiene conto dei posti in cui il dispositivo è attualmente in uso e lo elimina quando non viene più usato da nessuna parte. Riconosci la versione a puntatore condiviso di un dispositivo di disegno dal su suffisso <literal
>SP</literal
>. Ricordati solo che non devi mai eliminare esplicitamente un <classname
>KisPaintDeviceSP</classname
>. </para
><para
>Diamo un'occhiata a un semplicissimo filtro, uno che inverta ogni pixel. Il codice del filtro è nella cartella <filename class="directory"
> La funzione riceve due dispositivi di disegno, un oggetto di configurazione (che non viene usato in questo semplice filtro) e un <varname
>rect</varname
>. Il <varname
>rect</varname
> descrive l'area del dispositivo di disegno su cui il filtro dovrebbe avere effetto. Quest'area è descritta da interi, vale a dire senza precisione sotto il livello dei pixel. </para
><para
>Il dispositivo di disegno <varname
>src</varname
> è per leggere, il dispositivo <varname
>dst</varname
> è per scrivere. Questi parametri potrebbero anche puntare allo stesso dispositivo di disegno, o a due diversi (nota: nel futuro potrebbe diventare in un solo dispositivo). </para
><para
>Adesso, diamo un'occhiata al codice una riga alla volta: </para>
>Questo crea un iteratore per leggere i pixel esistenti. &chalk; ha tre tipi di iteratori: orizzontali, verticali e rettangolari. L'iteratore rettangolare prende il percorso più efficiente nei dati dell'immagine, ma non garantisce nulla sulla posizione del prossimo pixel restituito. Ciò vuol dire che non puoi essere sicuro che il prossimo pixel che recupererai sarà di fianco al pixel che hai appena ricevuto. Gli iteratori di linea orizzontale e verticale garantiscono la posizione dei pixel che restituiscono. </para
>(2) Creiamo l'iteratore di destinazione con <literal
>write</literal
> impostato a <literal
>true</literal
>. Ciò vuol dire che se il dispositivo di disegno di destinazione è più piccolo del rettangolo che scriviamo, sarà automaticamente ingrandito per adattarsi a ogni pixel su cui iteriamo. Nota che qui abbiamo un errore potenziale: se <varname
>dst</varname
> e <varname
>src</varname
> non sono lo stesso dispositivo, è possibile che i pixel restituiti dagli iteratori non corrispondano. Per ogni posizione dell'iteratore, <varname
>src</varname
> potrebbe, per esempio, essere a 165200, mentre <varname
>dst</varname
> potrebbe essere a 208, e quindi la copia potrebbe distorcere l'immagine. </para
></callout>
<callout arearefs="invert3"
><para
>Se vuoi sapere se un pixel è selezionato, usa il metodo <methodname
>isSelected</methodname
>. Però l'essere selezionato non è una proprietà binaria di un pixel, un pixel può essere selezionato a metà, appena o quasi del tutto. Puoi ottenere anche questo valore dall'iteratore. Le selezioni sono in realtà un dispositivo di disegno a maschera con un'intervallo tra 0 e 255, dove 0 è completamente non selezionato e 255 completamente selezionato. L'iteratore ha due metodi: <methodname
>isSelected()</methodname
> e <methodname
>selectedNess()</methodname
>. Il primo restituisce vero se un pixel è selezionato a qualsiasi livello (cioè se il valore della maschera è maggiore o uguale a 1), l'altro restituisce il valore della maschera. </para
></callout>
<callout arearefs="invert4"
><para
>Come notato sopra, questo <literal
>memcpy</literal
> può essere un brutto problema. <methodname
>rawData()</methodname
> restituisce l'array di byte che è lo stato attuale del pixel; <methodname
>oldRawData()</methodname
> lo restituisce come era prima che creassimo l'iteratore. Tuttavia, qui potremmo stare copiando il pixel sbagliato. In pratica, non capiterà spesso, a meno che <varname
>dst</varname
> esista già e non sia allineato a <varname
>src</varname
>. </para
></callout>
<callout arearefs="invert5"
><para
>Però è giusto: invece di cercare di capire quale canale rappresenta un byte, usiamo una funzione fornita da tutti gli spazi di colori per invertire il pixel attuale. Gli spazi di colori hanno molte operazioni sui pixel che puoi usare. </para
></callout>
</calloutlist>
<para
>Questo non è tutto quello che c'è per la creazione dei filtri. I filtri hanno altre due componenti importanti: un oggetto e un widget di configurazione; i due interagiscono molto da vicino. Il widget di configurazione crea un oggetto di configurazione, ma può anche essere riempito con un oggetto di configurazione preesistente. Gli oggetti di configurazione possono rappresentarsi come XML ed essere creati da XML. Questo è quello che rende possibili i livelli di regolazione. </para>
<sect3 id="developers-plugins-filters-iterators">
<title
>Iteratori</title>
<para
>Ci sono tre tipi di iteratori: </para>
<itemizedlist>
<listitem
><para
>Linee orizzontali</para
></listitem>
<listitem
><para
>Linee verticali</para
></listitem>
<listitem
><para
>Iteratori rettangolari</para
></listitem>
</itemizedlist>
<para
>Gli iteratori a linea orizzontale e verticale hanno un metodo per spostare l'iteratore alla prossima riga o colonna: <methodname
>nextRow()</methodname
> e <methodname
>nextCol()</methodname
>. Usare questi è molto più veloce che creare un nuovo iteratore per ogni riga o colonna. </para
>Gli iteratori di &chalk; sono a prova di thread, quindi è possibile dividere il lavoro in thread diversi. Tuttavia, le versioni future di &chalk; useranno il metodo <methodname
> per determinare se il tuo filtro può essere applicato a pezzi dell'immagine (cioè se tutti i pixel possono essere modificati indipendentemente, invece che essere cambiati da qualche valore determinato da tutti i pixel dell'immagine) e eseguire automaticamente in thread il filtro. </para>
> è una struttura usata per salvare le impostazioni dei filtri sul disco, per esempio livelli di regolazione. Il plugin di scripting usa la mappa delle proprietà in fondo a <classname
> per rendere possibile la scrittura di filtri con script. I filtri possono fornire un widget personalizzato che &chalk; visualizzerà nella galleria dei filtri, nella finestra di anteprima dei filtri o la scheda delle opzioni degli strumenti dello strumento di disegno con filtri. </para>
>La maggior parte dei filtri può essere modificata dall'utente. Puoi creare un widget di configurazione che &chalk; userà ovunque sia usato il filtro. Per esempio: </para>
>Usa &Qt; Designer per creare un widget di base, e fanne una sottoclasse per il tuo filtro</para
></listitem>
<listitem
><para
>Usa uno dei semplici widget che mostrano un certo numero di cursori per gli elenchi di numeri interi, a virgola mobile o valori booleani. Questi sono utili se, come nella schermata sopra, il filtro può essere configurato con un certo numero di cursori per gli elenchi di numeri interi, a virgola mobile o valori booleani. Vedi la documentazione dell'API di <classname
>Scrivi un widget a mano. Non è raccomandato, e se lo fai e vuoi che il tuo filtro diventi parte di un rilascio ufficiale di &chalk;, ti chiederò di ripetere il tuo widget scritto a mano con un widget di &Qt; Designer.</para
>C'è ovviamente molto di più su come scrivere filtri interessanti, ma con queste spiegazioni, la documentazione dell'API e l'accesso al codice sorgente dovresti poter cominciare. Non esitare a contattare gli sviluppatori di &chalk; su IRC o sulla mailing list. </para>
>Gli strumenti compaiono nella raccolta di strumenti di &chalk;. Ciò vuol dire che c'è un limite a quanti nuovi strumenti ci possono essere: ragiona piuttosto se un'operazione di disegno non potrebbe essere abbastanza per il tuo obiettivo. Gli strumenti possono usare il mouse (o la tavoletta) e la tastiera in modi complessi, cosa che le operazioni di disegno non possono fare. Questo è il motivo per cui Duplica è uno strumento, ma l'aerografo è un'operazione di disegno. </para
>Fai attenzione ai dati statici nello strumento: viene creata una nuova istanza dello strumento per ogni dispositivo di input: mouse, pennino, gomma, aerografo, qualsiasi cosa. Gli strumenti vengono divisi in gruppi logici: </para>
<itemizedlist>
<listitem
><para
>strumenti per disegnare forme (cerchio, rettangolo)</para
></listitem>
<listitem
><para
>strumenti per disegnare a mano libera (pennello)</para
></listitem>
<listitem
><para
>strumenti di trasformazione che cambiano la geometria di un livello</para
></listitem>
<listitem
><para
>strumenti di riempimento (come il riempimento a secchio o le sfumature)</para
></listitem>
<listitem
><para
>strumenti di visualizzazione (che non cambiano nessun pixel, ma modificano il modo in cui vedi la tela, come l'ingrandimento)</para
></listitem>
<listitem
><para
>strumenti di selezione (che cambiano la maschera di selezione)</para
></listitem>
</itemizedlist>
<para
>L'interfaccia degli strumenti è descritta nella documentazione dell'API di <classname
>KisTool</classname
>. Ci sono tre sottoclassi: <classname
>KisToolPaint</classname
>, <classname
>KisToolNonPaint</classname
> e <classname
>KisToolShape</classname
> (che in realtà è una sottoclasse di <classname
>KisToolPaint</classname
>) che specializzano <classname
>KisTool</classname
> per le operazioni di disegno (cioè cambiare i pixel), non di disegno e di disegno di forme. </para
>Uno strumento ho un widget di opzioni, esattamente come i filtri. Attualmente, i widget di opzioni vengono visualizzati in una scheda in una finestra agganciata. Potremmo cambiarlo in una striscia sotto il menu principale (che sostituirebbe la barra degli strumenti) per &chalk; 2.0, ma per ora progetta il widget di opzioni per stare nella scheda. Come sempre, è meglio usare &Qt; Designer per il widget di opzioni. </para
>Il costruttore imposta il nome interno (che non va tradotto) e la chiamata alla classe superiore imposta il nome visibile. Carichiamo anche l'immagine del cursore e impostiamo un certo numero di variabili. </para>
> viene chiamato quando lo strumento viene selezionato. Non è un metodo di <classname
>KisTool</classname
>, ma di <classname
>KisCanvasObserver</classname
>. Gli osservatori della tela ricevono un avviso ogni volta che qualcosa cambia nella visualizzazione, il che può essere utile per gli strumenti. </para
>) sono chiamati da &chalk; quando il dispositivo di input (mouse, pennino, gomma, eccetera) viene premuto, spostato o rilasciato. Nota che avrai eventi di spostamento anche se il pulsante del mouse non viene premuto. Gli eventi non sono i normali eventi &Qt;, ma eventi sintetici di &chalk; perché noi usiamo dei trucchetti di basso livello per avere abbastanza eventi da disegnare una linea liscia. Come impostazione predefinita, le librerie come &Qt; (e GTK) scartano gli eventi se hanno troppo da fare per gestirli, mentre noi invece li vogliamo tutti. </para>
> è essenziale: qui noi creiamo l'azione che sarà immessa nella raccolta degli strumenti in modo che gli utenti possano selezionare lo strumento. Assegniamo anche una chiave per la scorciatoia. Nota che abbiamo usato dei trucchi: ricorda che abbiamo creato un'istanza dello strumento per ogni dispositivo di input. Ciò vuol anche dire che chiamiamo <methodname
>setup()</methodname
> per ogni dispositivo di input e che un'azione con lo stesso nome viene aggiunta diverse volte alla raccolta di azioni. Però tutto sembra funzionare, e allora perché preoccuparsi? </para>
> viene chiamato per creare il widget di opzioni che &chalk; mostrerà nella scheda. Siccome c'è uno strumento per dispositivo di input per vista, lo stato di uno strumento può essere mantenuto nello strumento stesso. Questo metodo viene chiamato una sola volta: il widget di opzioni viene memorizzato e recuperato la prossima volta che lo strumento viene attivato. </para>
>Le operazioni di disegno sono uno dei tipi più innovativi di plugin di &chalk; (oltre agli spazi di colori). Un'operazione di disegno definisce come gli strumenti cambiano i pixel che toccano. L'aerografo, la matita e il pennello sono tutte operazioni. Però potresti (con molta fatica) creare un'operazione che legga le definizioni XML dei pennelli di Corel Painter e usi quelle per decidere come disegnare. </para
>Le operazioni di disegno sono avviate quando uno strumento di disegno riceve un evento <literal
>mouseDown</literal
> e sono eliminate quando viene ricevuto un evento <literal
>mouseUp</literal
>. Nel frattempo, l'operazione può tenere a mente le posizioni precedenti e altri dati, come i livelli di pressione se l'utente usa una tavoletta. </para
><para
>Lo scopo fondamentale di un'operazione di disegno è cambiare i pixel alla posizione del cursore di uno strumento di disegno. Questo si può fare in una sola volta, oppure l'operazione può richiedere di essere eseguita a intervalli regolari, usando un timer. La prima possibilità sarebbe utile per un'operazione simile a una matita, la seconda per un aerografo. </para
>Le operazioni di disegno possono avere un piccolo widget di configurazione che viene messo in una barra degli strumenti. Perciò i widget di configurazione delle operazioni devono avere una disposizione orizzontale di oggetti non più alti di un pulsante della barra. Altrimenti, l'aspetto di &chalk; non sarà granché. </para
>Diamo un'occhiata a un semplice plugin per un'operazione di disegno, uno che dia qualche segno di intelligenza programmatrice. Innanzi tutto, nel file di intestazione, è definita una fabbrica. Questa fabbrica crea un'operazione quando lo strumento attivo ne ha bisogno: </para>
> con i nomi pubblico e privato dell'operazione (assicurati che il nome privato dell'operazione non collida con un'altra) e potrebbe a scelta restituire un oggetto pixmap. &chalk; potrà in questo caso mostrare il pixmap insieme al nome per l'identificazione visiva della tua operazione. Per esempio, un'operazione per il coltello da pittore avrebbe l'immagine di questo oggetto. </para
> è la cosa più importante per le operazioni. Questo metodo riceve due parametri: la posizione attuale (in numeri a virgola mobile, non pixel interi) e un oggetto <classname
>KisPaintInformation</classname
> che contiene la pressione, l'inclinazione X e Y, il vettore di movimento e che in futuro potrebbe venire esteso con altre informazioni. </para>
<programlisting
>if (!m_painter->device()) return;
KisBrush *brush = m_painter->brush();
</programlisting>
<para
>Un <classname
>KisBrush</classname
> è la rappresentazione di un file di pennello di Gimp: cioè una maschera, sia una sola o una serie di maschere. In realtà noi non useremo il pennello qui, se non per determinare il <quote
// Split the coordinates into integer plus fractional parts. The integer
// is where the dab will be positioned and the fractional part determines
// the sub-pixel positioning.
Q_INT32 x, y;
double xFraction, yFraction;
splitCoordinate(pt.x(), &x, &xFraction);
splitCoordinate(pt.y(), &y, &yFraction);
KisPaintDeviceSP dab = new KisPaintDevice(colorSpace, "smeary dab");
Q_CHECK_PTR(dab);
</programlisting>
<para
>Non cambiamo direttamente i pixel di un dispositivo di disegno: invece, creiamo un piccolo dispositivo di disegno, una copia, e ricomporla sul dispositivo di disegno attuale. </para>
<programlisting
>m_painter->setPressure(info.pressure);
</programlisting>
<para
>Come dai commenti, la prossima sezione di codice fa del lavoro che serve a creare la copia. In questo caso, disegnamo un certo numero di linee. Quando questa operazione sarà finita, la lunghezza, posizione e spessore delle linee dipenderanno dalla pressione e dal carico di disegno, e avremo creato un pennello oleoso e pesante. Purtroppo non c'è ancora stato tempo per completarla. </para>
<programlisting
>// Compute the position of the tufts. The tufts are arranged in a line
// perpendicular to the motion of the brush, i.e, the straight line between
// the current position and the previous position.
for (int i = 0; i < (NUMBER_OF_TUFTS / 2); ++i) {
// Compute the positions on the new vector.
vl = currentPointVector + i * brushVector;
KisPoint pl = vl.toKisPoint();
dab->setPixel(pl.roundX(), pl.roundY(), kc);
vr = currentPointVector - i * brushVector;
KisPoint pr = vr.toKisPoint();
dab->setPixel(pr.roundX(), pr.roundY(), kc);
}
vr = vr - vl;
vr.normalize();
</programlisting>
<para
>Infine eseguiamo blt sulla copia per metterla sul dispositivo di disegno originale e dire al disegnatore che abbiamo sporcato un rettangolino del dispositivo. </para>
<programlisting
>if (m_source->hasSelection()) {
m_painter->bltSelection(x - 32, y - 32, m_painter->compositeOp(), dab.data(),
m_source->selection(), m_painter->opacity(), x - 32, y -32, 64, 64);
}
else {
m_painter->bitBlt(x - 32, y - 32, m_painter->compositeOp(), dab.data(), m_painter->opacity(), x - 32, y -32, 64, 64);
}
m_painter->addDirtyRect(QRect(x -32, y -32, 64, 64));
>Tutto qui: le operazioni di disegno sono facili! </para>
</sect2>
<sect2 id="developers-plugins-viewplugins">
<title
>Plugin di vista</title>
<para
>I plugin di vista sono i più strani del gruppo: un plugin di vista è un normale componente KPart che può fornice un po' di interfaccia utente e qualche funzionalità. Per esempio, la scheda degli istogrammi è un plugin di vista, come la finestra di rotazione. </para>
>&chalk; funziona con l'architettura standard di filtraggio dei file di &koffice;. C'è un'esercitazione, un po' vecchia ma ancora utile, a <ulink url="http://koffice.org/developer/filters/oldfaq.php"
>. Probabilmente è meglio lavorare con la squadra di &chalk; se sviluppi filtri per file e fare lo sviluppo nell'albero dei filtri di &koffice;. Nota che puoi provare i tuoi filtri senza avviare &chalk; usando il programma <command
>Il problema principale con i filtri di importazione è ovviamente far leggere al tuo codice i dati del disco. Il codice riutilizzabile per chiamarlo è abbastanza semplice: </para>
>Nota: dovremmo davvero trovare un modo di permettere a &chalk; di mantenere aperto un file e leggere i dati solo quando servono, invece che copiare tutti i contenuti nella rappresentazione grafica interna. Però questo vorrebbe dire avere delle interfacce di gestione dei dati che comprendono i file TIFF e tutto il resto, e questo al momento non è implementato. L'ideale sarebbe se alcuni filtri potessero implementare una classe temporaneamente battezzata <classname
>Questo dovrebbe essere un filtro di importazione, perciò se non viene chiamato per convertire in un'immagine di &chalk;, c'è qualcosa che non va.</para
>, perché i documenti di &chalk; hanno bisogno di un trattamento speciale. In realtà non sarebbe una cattiva idea controllare che il risultato della chiamata non sia zero, perché in tal caso l'importazione non riuscirà.</para
>Se chiamiamo questo filtro dall'interfaccia, proviamo a ottenere la vista. Se la vista c'è, il codice di conversione può provare ad aggiornare la barra di avanzamento.</para
></callout>
<callout arearefs="import4"
><para
>Il filtro ha il nome del nostro file di input.</para
></callout>
<callout arearefs="import5"
><para
><classname
>KisDoc</classname
> deve essere preparato per un'importazione. Certe impostazioni sono inizializzate e l'annullamento delle azioni viene disattivato, altrimenti potresti annullare l'aggiunta di livelli effettuata dal filtro di importazione, e quello sarebbe un comportamento indesiderato.</para
></callout>
<callout arearefs="import6"
><para
>Si è scelto di implementare il codice di importazione in una classe a parte che viene istanziata qui. Puoi anche mettere tutto il codice nel metodo, ma sarebbe un po' disordinato.</para
></callout>
<callout arearefs="import7"
><para
>L'importatore restituisce un codice di stato che posso usare per impostare lo stato del filtro di importazione. &koffice; pensa a mostrare i messaggi di errore.</para
></callout>
<callout arearefs="import8"
><para
>Se la creazione di <classname
>KisImage</classname
> è riuscita, impostiamo l'immagine attuale del documento alla nostra immagine appena creata. A questo punto abbiamo finito: <literal
