Development/Tutorials/Using KActions (it)

Come usare le KActions e XMLGUI

Tutorial Series	Tutorial per Principianti
Previous	Tutorial 2 - KXmlGuiWindow, next=Tutorial 4 - Saving and loading
What's Next	n/a
Further Reading	None

Prefazione

Questo tutorial introduce il concetto di azione. Le azioni sono una vie unificate per l'interazione tra l'utente ed il tuo programma.

Ad esempio, se vogliamo permettere all'utente del Tutorial 2 di cancellare la casella di testo cliccando un bottone nella barra degli strumenti, da un'opzione del menu File e tramite una scorciatoia da tastiera potremmo farlo con una KAction.

KAction

Una KAction è un oggetto che contiene tutte le informazioni sull'icona e sulle scorciatoie da tastiera alle quali è associata una certa azione. L'azione è successivamente connessa con uno slot il quale svolge il compito preposto all'azione stessa (nel nostro caso cancellare l'area di testo).

Il Codice

main.cpp

#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>

#include "mainwindow.h"

int main (int argc, char *argv[])
{
  KAboutData aboutData( "tutorial3", "tutorial3",
      ki18n("Tutorial 3"), "1.0",
      ki18n("Una semplice area di testo con KAction ecc."),
      KAboutData::License_GPL,
      ki18n("Copyright (c) 2007 Developer") );
  KCmdLineArgs::init( argc, argv, &aboutData );
  KApplication app;
 
  MainWindow* window = new MainWindow();
  window->show();
  return app.exec();
}

E' cambiato molto poco in main.cpp: rispetto alla versione precedente solo il costruttore KAboutData è stato aggiornato per mostrare che ora siamo nel tutorial 3.

mainwindow.h

#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <KXmlGuiWindow>
#include <KTextEdit>

class MainWindow : public KXmlGuiWindow
{
  public:
    MainWindow(QWidget *parent=0);
	
  private:
    KTextEdit* textArea;
    void setupActions();
};

#endif

Solo una funzione void setupActions() è stata aggiunta; sarà quella che imposterà la KAction.

mainwindow.cpp

#include "mainwindow.h"

#include <KApplication>
#include <KAction>
#include <KLocale>
#include <KActionCollection>
#include <KStandardAction>

MainWindow::MainWindow(QWidget *parent)
    : KXmlGuiWindow(parent)
{
  textArea = new KTextEdit;
  setCentralWidget(textArea);

  setupActions();
}

void MainWindow::setupActions()
{
  KAction* clearAction = new KAction(this);
  clearAction->setText(i18n("Clear"));
  clearAction->setIcon(KIcon("document-new"));
  clearAction->setShortcut(Qt::CTRL + Qt::Key_W);
  actionCollection()->addAction("clear", clearAction);
  connect(clearAction, SIGNAL(triggered(bool)),
          textArea, SLOT(clear()));

  KStandardAction::quit(kapp, SLOT(quit()),
                        actionCollection());

  setupGUI();
}

Spiegazione

Questo programma compila sul codice KXmlGuiWindow del Tutorial 2. La maggior parte dei cambi sono in mainwindow.cpp, un importante modifica strutturale è data dal fatto che il costruttore per MainWindow ora chiama la funzione setupActions() al posto di setupGUI(). In setupActions() dovremo implementare il codice per la KAction e successivamente chiamare, come prima, setupGUI().

Creare l'oggetto KAction

La KAction è costruita in una serie di passaggi. Il primo è includerne la libreria (KAction) e creare un nuovo oggetto KAction:

#include <KAction>
...
KAction* clearAction = new KAction(this);

Ciò creerà un nuovo oggetto KAction chiamato clearAction.

Impostazione delle proprietà della KAction

Testo

Ora che abbiamo il nostro oggetto KAction possiamo iniziare ad impostarne le proprietà. Il codice seguente imposta il testo che sarà mostrato nel menu e sotto l'icona KAction nella barra degli strumenti.

clearAction->setText(i18n("Clear"));

Nota che il testo è stato passato tramite la funzione i18n (nome breve per internationalization, ovvero internazionalizzazione). L'uso di i18n è necessario per rendere l'interfaccia traducibile (maggiori informazioni possono essere trovate nel i18n tutorial).

Icona

Qualora l'azione dovesse comparire nella barra degli strumenti, sarebbe carino che fosse descritta da un'icona adeguata. Il codice seguente imposta l'icona alla standard document-new del tema corrente di KDE tramite una chiamata delle funzione setIcon():

clearAction->setIcon(KIcon("document-new"));

Scorciatoie da Tastiera

Impostare una scorciatoia da tastiera per eseguire la nostra azione è egualmente semplice:

clearAction->setShortcut(Qt::CTRL + Qt::Key_W);

Questa riga associa all'azione la combinazione di tasti Ctrl+W.

Aggiuta alla Collezione

Per poter essere resa accessibile dal framework XMLGUI (spiegato in dettaglio successivamente) la KAction deve essere aggiunta all action collection (la "collezione di azioni") dell'applicazione. L'accesso all'action collection è eseguito con la funzione eponima (actionCollection()) in questo modo:

actionCollection()->addAction("clear", clearAction);

Qui, la KAction clearAction è aggiunta alla collezione con il nome clear. Questo nome (clear) è utilizzato dal framework XMLGUI per fare riferimento a questa azione, pertanto non necessità di essere tradotto in quanto il suo uso è solo interno. Per rendere agevole la comprensione del codice ad altri sviluppatori, poi, si consiglia di utilizzare nomi inglesi.

Connessione dell'azione

Ora che l'azione è completamente impostata, è necessario che sia connessa a qualcosa di utile. In questo caso (siccome vogliamo cancellare l'area di testo) la connettiamo con il metodo clear() di KTextEdit (il quale, nessuna sorpresa in ciò, cancella la KTextEdit!)

connect( clearAction, SIGNAL( triggered(bool) ), 
         textArea, SLOT( clear() ) );

Tutto quello che è stato descritto fin'ora è analogo a quanto sarebbe stato fatto con le Qt usando una QAction.

KStandardAction

Per azioni che probabilmente appariranno in quasi tutte le applicazioni KDE, quali 'esci', 'salva' e 'carica' esistono delle KAction precaricate, accessibili tramite KStandardAction.

Sono molto semplici da usare. Una volta che la libreria è stata inclusa (#include <KStandardAction>), semplicemente fornitele cosa volete che sia fatto dalla vostra funzione e che KActionCollection aggiungerle. Il tutto è più chiaro con un esempio:

KStandardAction::quit(kapp, SLOT(quit()), actionCollection());

Questo crea una KAction con icona testo e scorciatoia corrette e la aggiunge anche al menu File.

Aggiungere l'azione a menu e barre degli strumenti

Al momento la nuovo azione "Clear" è stata creata ma non è ancora associata con nessun menu nè alcuna barra degli strumenti. Per farlo si usa una tecnologia KDE denominata XMLGUI, la quale crea automaticamente cose carine quali barre degli strumenti spostabili.

Note

In una futura versione di KDE4, XMLGUI potrà essere sostituita da un nuovo framework, chiamato liveui. Attualmente XMLGUI è l'unico (corretto) modo per creare l'interfaccia grafica.

Definire il tuo menu Aiuto

Il menu Aiuto è fondamentale, è grazie ad esso che tutti i menu 'Aiuto' di KDE si assomigliano. Se vuoi implementare un tuo help menu, vai qui e cerca spiegazioni su showAboutApplication().

XMLGUI

La funzione setupGUI() in KXmlGuiWindow dipende dal sistema XMLGUI il quale costruisce la GUI, creata da XMLGUI decodificando un file XML che descrive l'interfaccia.

La regola per il nome di questo file XML è nomeapplicazioneui.rc, dove nomeapplicazione è il nome che hai impostato in KAboutData (nel nostro caso, tutorial3). Così, nel nostro esempio, il file sarà chiamato tutorial3ui.rc, e verrà collocato nella cartella principale del progetto. La collocazione ultima del file sarà gestita da CMake.

Vedi anche developer.kde.org che fornisce ancora informazioni valide per KDE4, per quanto faccia riferimento alla versione di KDE3.

Il file nomeapplicazioneui.rc

Poiché la descrizione dell'interfaccia è definita tramite XML, il layout deve seguire delle regole precise. Questo tutorial non si soffermerà con dovizia di particolari su questa tematica, ma per maggiori informazioni si consulti la dettagliata descrizione di XMLGUI (qui è disponibile un tutorial più vecchio, in inglese: [1]).

tutorial3ui.rc

<?xml version="1.0" encoding="UTF-8"?>
<gui name="tutorial3"
     version="1"
     xmlns="http://www.kde.org/standards/kxmlgui/1.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.kde.org/standards/kxmlgui/1.0
                         http://www.kde.org/standards/kxmlgui/1.0/kxmlgui.xsd" >

  <MenuBar>
    <Menu name="file" >
      <Action name="clear" />
    </Menu>
  </MenuBar>

  <ToolBar name="mainToolBar" >
    <text>Main Toolbar</text>
    <Action name="clear" />
  </ToolBar>

</gui>

La tag <Toolbar> ti permette di descrivere la composizione della barra degli strumenti, che è la barra in cima alla finestra che normalmente riporta delle icone (da non confondersi con la barra dei menu!). Qui le è assegnato il nome univoco di mainToolBar ed il nome, visibile all'utente, di Main Toolbar con la tag <text>. L'azione clear è aggiunta alla barra usando la tag <Action>, dove il parametro nome per questa tag è la stringa passata a KActionCollection per mezzo della funzione addAction() in mainwindow.cpp.

Oltre a comparire nella barra degli strumenti, un'azione può comparire anche nella barra dei menu. Qui l'azione è aggiutna al menu File della MenuBar (Barra dei Menu) nello stesso modo in cui era stata aggiunta alla barra degli strumenti.

Modifica l'attributo 'version' della tag <gui> se modifichi il file .rc rispetto all'ultima installazione per forzare l'aggiornamento della cache di sistema. Assicurati che il numero di versione sia un intero, se usi numeri decimali non funzionerà, ma non sarà riportato alcun errore! Nota: L'attributo version DEVE essere un numero intero, e per tanto non può contenere punti od altri caratteri che non siano cifre!

Alcune note sull'interazione tra il codice ed il file .rc: I Menu appaiono automaticamente e dovrebberi avere una tag figlia <text/> a meno che facciano riferimento a menu strandard. Le azioni devono essere create manualmente e aggiunte nell'actionCollection() usando il nome nel file .rc. Le azioni possono essere nascoste o disabilitate, i menu no.

CMake

Infine, tutorial3ui.rc deve essere collocato in un posto in cui KDE possa trovarlo (non basta semplicemente lasciarlo nella cartella dei sorgenti!). Questo significa che il progetto ha bisogno di essere installato da qualche parte.

CMakeLists.txt

project(tutorial3)

find_package(KDE4 REQUIRED)
include_directories(${KDE4_INCLUDES})

set(tutorial3_SRCS 
  main.cpp
  mainwindow.cpp
)

kde4_add_executable(tutorial3 ${tutorial3_SRCS})

target_link_libraries(tutorial3 ${KDE4_KDEUI_LIBS})

install(TARGETS tutorial3 DESTINATION ${BIN_INSTALL_DIR})
install(FILES tutorial3ui.rc 
        DESTINATION  ${DATA_INSTALL_DIR}/tutorial3)

Questo file è quasi identico a quello per il tutorial2, ma con due linee in più alla fine: esse descrivono dove devono essere installati i file. Inizialmente il target tutorial3 è installato in BIN_INSTALL_DIR poi il file tutorial3ui.rc, che come abbiamo visto descrive il layout dell'interfaccia, è installato nella cartella dei dati dell'applicazione.

Make, Install ed Esegui

Se non hai accesso in scrittura alla tua cartella di installazione di KDE4, puoi installare l'applicazione in una sottocartella della tua cartella home.

Per informare CMake su dove installare il programma, imposta la variabile DCMAKE_INSTALL_PREFIX. Probabilmente vorrai installare i tuoi programmi in una cartella locale solo per dei test (è probabilmente fastidioso dover installare questi tutorial nella tua cartella di KDE), pertanto possono risultare utili questi parametri:

mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
make install
$HOME/bin/tutorial3

che creeranno una struttura di cartelle simile a quella di KDE nella tua cartella home ed installeranno gli eseguibili in $HOME/bin/tutorial3. Nota che puoi anche voler aggiungere tale percorso alla tua variabile globale $PATH per eseguire i tuoi programmi senza doverti spostare nella cartella degli eseguibili.

Continuiamo

Ora puoi proseguire con salvataggio e caricamento.