Generale #

Gli Eventi permettono di interagire con le operazioni eseguite dal sistema, vengono lanciati eventi in tutte le parti di OpenLab Studio, nei plugin, nel Dock, nel Dock Connector, etc. Ad ogni evento possono essere agganciati più EvenetHandler. Gli eventi vengono gestiti dall’ EventsManager che permette di aggiungere, rimuovere, lanciare, disabilitare/abilitare eventi.

Il sistema di eventi funziona tramite un dizionario che associa un nome ad una lista di EventHandler. Questo permette operare sugli eventi in modo globale, ad esempio aggiungendo un evento questo potrà essere richiamato/intercettato ovunque.

Regole per i nomi degli eventi #

Il nome di ogni evento dovrebbe sempre contenere l’ambito, più univoco possibile, ad esempio un evento in modo da non creare conflitti o aggiugere un evento ad uno chiamato in un ambito non desiderato. Ad esempio creare un evento OnNavViewOpenedRemove per la classe NavTabSystemTree, il nome potrebbe essere questo OpenLabStudio.ui.OnNavViewOpenedRemove.
L’ambito dovrebbe contenere il namespace e, la classe o il metodo in cui è contenuto l’evento, può anche contenere entrambi.

Gestione degli eventi #

Tramite l’EventsManager gli eventi possono essere creati, rimossi, disabilitati/abilitati, lanciati etc.

Creare un evento #

La creazione di un evento viene fatta tramite il metodo createEvent. Questo metodo  accetta come argomento il nome dell’evento oppure il nome e un EventHandlerda aggiungere subito all’evento.

L’EventHandler prende come primo argomento un oggetto che rappresenta il sender cioè un riferimento a chi lancia l’evento, come secondo argomento prendere un istanza di EventArgs con la quale è possibile trasportare dati all’interno dell’EventHandler, il funzionamento sarà chiarito meglio nel paragrafo Lanciare un evento

Di seguito viene creato un evento vuoto.

OLS.eventsManager.createEvent("test");

Nell’esempio di seguito viene creato un evento e aggiunto subito un EventHandler

OLS.eventsManager.createEvent("test", (sender, e) => {
    log.info("YEAAAAAA");
});

Se l’evento con il nome indicato esiste già viene lanciata un eccezione EventJustExistException

Rimuovere un evento #

per rimuover un evento usare il metodo removeEvent, se l’evento non esiste viene lanciata un eccezione EventNotFoundException

OLS.eventsManager.removeEvent("test");

Disabilitare/abilitare un evento #

Disabilitando un evento non verranno eseguiti gli EventHandler quando verrà lanciato l’evento. Tutti gli altri accessi all’evento rimangono disponibili. Il metodo disableEventprende come argomenti il nome dell’evento e un valore booleano che abilita o disabilita l’evento.

OLS.eventsManager.disableEvent("test", true);

Lanciare un evento #

Quando si lancia un evento, tramite il metodo fireEvent, vengono eseguiti tutti gli EventHandler di quell’evento uno dopo l’altro in orgine di inserimento. Questo metodo prende come argomento il nome dell’evento da lanciare, il sender e i dati da passare agli event handlers.

Il sender è di tipo Objecte serve a passare agli event handlers un riferimento a chi ha lanciato l’evento, nel esempio di seguito viene usato thisper passare come riferimento la classe in cui c’è il metodo che lancia l’evento.

EventArgs data = new EventArgs();
OLS.eventsManager.fireEvent("test", this, data);

Passare dati agli event handlers #

Per passare dati dal sender agli event handlers viene usata un istanza di EventArgs. Questa è una classe vuota, impementandola può essere passato qualsiasi dato all’interno.

public class TestEventArgs : EventArgs
{
    public string Data = "";
}

TestEventArgs d = new TestEventArgs();
d.Data = "HelloWorld";
OLS.eventsManager.fireEvent("test", this, d);

Aggiungere un event handler ad un evento #

Per aggiungere un event handler ad un evento si usa il metodo addEventHandler. E’ possibile specificare che l’evento venga creato se non esiste.

OLS.eventsManager.addEventHandler("test1", (sender, data) => {
   log.info("Hello World test 1");
});

Nell’esempio precedente, se l’evento non esiste già viene lanciata un eccezione del tipo EventNotFoundException, è possibile creare l’evento se non esiste con un terzo parametro booleano

OLS.eventsManager.addEventHandler("test1", (sender, data) => { 
    log.info("Hello World test 1"); 
}, true);

Rimuovere tutti gli event handler di un evento #

Per rimuovere da  un evento tutti i suoi event handlers usare il metodo eventClear.

OLS.eventsManager.eventClear("test")

Rimuovere un event handler #

Per rimuovere un handler di un evento va usato il metodo removeEventHandler. Un event handler può essere individuato tramite la sua l’istanza o tramite il suo indice

OLS.eventManager.removeEventHandler("test", eventHandler);

// or

OLS.eventManager.removeEventHandler("test", 3);

Un esempio più esplicativo è qui

Interrompere un evento #

Quando viene lanciato un evento vengono eseguiti tutti i sui event handler, ogni event handler ritorno un valore booleano. Se il valore che ritorna è false l’esecuzione viene interrotta e gli altri handlers non eseguiti.

Nell’esempio di seguito supponiamo di aggiungere alcuni event handler ad un evento chiamato test. Il penultimo di questi event handler restituirà false interrompendo il lancio dell’evento e quindi l’esecuzione degli event handler successivi. L’interruzione dell’esecuzione  provoca il lancio di un eccezione FireEventInterruptedByEventHandlerException

OLS.eventsManager.addEventHandler("test", (sender, e) =>
{
    log.info("Handler 1");
    return true;
},true);

OLS.eventsManager.addEventHandler("test", (sender, e) =>
{
    log.info("Handler 2");
    return true;
});

OLS.eventsManager.addEventHandler("test", (sender, e) =>
{
    log.info("Handler 3");
    return false;
});

OLS.eventsManager.addEventHandler("test", (sender, e) =>
{
    log.info("Handler 4");
    return true;
});

try
{
    eventsManager.fireEvent("test", this, new EventArgs());
}catch(FireEventInterruptedByEventHandlerException ex)
{
    log.warn("Event Test interrupted by event handler");
}

Nell’esempio sopra il primo event handler crea l’evento(notare il true dopo l’implementazione dell’event handler), il penultimo event handler ritorna false. Questo bloccherà l’esecuzione quindi nel log vedremo solo i primi tre messaggi.

Esempi #

Esempio base, passaggio dati agli event handlers #

OLS.eventsManager.createEvent("test");
OLS.eventsManager.addEventHandler("test", (sender, data) =>
{
    log.info("Message: "data.Message);
    return true;
});

public class TestEventArgs : EvetArgs
{
    public string Message;
    public TestEventArgs(string message)
    {
        Message = message;
    }

}
OpenLabStudio.eventsManager.fireEvent("test", this, TestEventArgs(txtMessage.Text));

Interruzione esecuzione evento #

OLS.eventsManager.createEvent("test");
OLS.eventsManager.addEventHandler("test", (sender, e) =>
{
    log.info("1");
    return true;
});
OLS.eventsManager.addEventHandler("test", (sender, e) =>
{
    log.info("2");
    return true;
});
OLS.eventsManager.addEventHandler("test", (sender, e) =>
{
    log.info("3");
    return false;
});
OLS.eventsManager.addEventHandler("test", (sender, e) =>
{
    log.info("4");
    return true;
});

EventArgs d = new EventArgs();

try
{
    eventsManager.fireEvent("test", this, d);
}catch(FireEventInterruptedByEventHandlerException ex)
{
    errorManager.showCrashReport(ex);
}

Rimuovere un event handler #

// create handler 1
function handler1(object sender, EventArgs e){
    Console.WriteLine("handler1");
}

// create handler 2
function handler2(object sender, EventArgs e){
     Console.WriteLine("handler2");
}

int handler1Index = OLS.eventManager.addEventHandler("test",handler1,true); // add new event and it's event handler
int handler2Index = OLS.eventManager.addEventHandler("test",handler2); // add event handler

// remove handler 1
OLS.eventManager.removeEventHandler("test",handler1Index);

// remove handler 2
OLS.eventManager.removeEventHandler("test",handler2);