Guida allo Scripting su mirc

Dialogs

I dialogs sono una delle più "eleganti" e maneggevoli soluzioni che il mIRC abbia messo a disposizione per la problematica delle variabili. Infatti, almeno in linea generale, i dialogs vengono usati per settare delle variabili, pur non necessariamente. Se non avete gia' a mente il concetto di DIALOG (ed è difficile non saperlo ;) ), vi dico che i dialogs sono le finestre comuni a tutto l'ambiente Windows, quelle con la barra titolo i menu e i pulsanti in alto a destra (minimize, maximize, close). Chiarita molto approssimativamente l'idea di ciò che vi apprestate a fare, possiamo passare più specificatamente all'oggetto del tutorial.

Per creare una dialog table, che va scritta nella sezione "Remote scripts" e consiste nella disposizione degli oggetti in un dialog, le sue dimensioni e le proprietà di quest'ultimo e di tali oggetti, potete intraprendere 2 strade:
1) usare un dialog editor (consigliato) per mIRC come Stardust (che potete trovare sul sito http://mircstardust.cjb.net);

2) definire manualmente gli oggetti (con esito sicuramente meno felice).

size x y w h

option type (dbu, pixels)
text "text", id, x y w h, style (right, center)

edit "text", id, x y w h, style (right, center, multi, pass, read, return, hsbar, vsbar, autohs, autovs, limit N)

button "text", id, x y w h, style (default, ok, cancel)

check "text", id, x y w h, style (left, push, 3state)

radio "text", id, x y w h, style (left, push)

box "text", id, x y w h, style

combo id, x y w h, style (sort, edit, drop, size, vsbar, hsbar)

tab "text", id

item "text", id [, menuid]

item break, id [, menuid]
}
L'ordine delle righe costituenti la dialog table determinano il "tab order", ovvero la sequenza che viene seguita con il tasto TAB e la combinazione inversa SHIFT+TAB nel passare da un oggetto ad un altro nel dialog.
Del dialog in generale vanno descritte queste 3 impostazioni:
title corrisponde al titolo del dialog, quello sulla barra in alto

size è la dimensione del dialog. Per centrare il dialog assegnare a "x" e "y" il valore -1

option è il tipo di unità di misura usata nel dialog. Può essere impostata a "dbu" (dialog based units) e in questo modo la visione di ogni utente prescinderà dalla risoluzione usata; di contro può essere impostata a "pixels", per interpretare in pixels i valori considerati
All'interno di un dialog, il client deve identificare gli oggetti, e questo lo fa tramite un "id" (vedi nello schema), che DEVE essere numerico. Questo valore dà significato effettivo all'oggetto, le cui proprietà potranno essere richiamate o modificate attraverso tale "id". Passando ad analizzare i vari oggetti, vi troviamo:
text è una casella di testo non editabile, quindi un'etichetta

edit è una casella di testo editabile, a differenza dell'oggetto text

button il classico pulsante di comando (es.: "Ok", "Annulla"...)

check Check button (pulsante di opzione inclusiva). Può presentare due - o tre - stati, secondo i quali la casella risulta selezionata (checked) o deselezionata (unchecked) - o allo stato intermedio (grayed)

radio Radio button (pulsante di opzione esclusiva). Ha lo stesso funzionamento dell'oggetto check, ma in un gruppo di radio buttons (vedi group) la selezione di un oggetto esclude la contemporanea selezione di un altro oggetto contenuto nello stesso gruppo (a differenza dei checkbutton che possono essere selezionati insieme)

box hanno solitamente funzione di raggruppamento o "decorativa". :) Sono in effetti dei semplici riquadri con titolo non editabile

list l'oggetto list è un elenco sviluppato in direzione verticale

combo in pratica è l'unione di un oggetto list con un oggetto edit. E' infatti una casella di testo con annessa una listbox a discesa che appare spingendo un pulsante posto sulla destra della casella. Tuttavia la listbox può essere omessa

icon è un'immagine (jpg, bmp, ico...)

link è un collegamento ipertestuale

right allineamento a destra (anche di immagini)

center allineamento centrato

multi casella di testo multilinea

pass casella di testo password (criptata in asterischi *)

read casella di testo in sola lettura

return casella di testo con a capo automatico (in caselle di testo multilinea)

hsbar barra di scorrimento orizzontale

vsbar barra di scorrimento verticale

autohs barra di scorrimento orizzontale automatica

autovs barra di scorrimento orizzontale automatica

limit N casella di testo con numero di caratteri limitato ad N caratteri

default pulsante di comando predefinito

ok pulsante di comando con valore modale "Ok"

cancel pulsante di comando con valore modale "Annulla"

push check o radio button con aspetto di pulsante button

3state check button a 3 stati (checked, unchecked, grayed)

sort listbox ordinata alfabeticamente

extsel listbox a selezione multipla

size listbox ad altezza auto-adattata

edit combobox con casella di testo editabile

drop combobox con listbox a discesa

noborder immagine senza bordo

top immagine allineata in alto

bottom immagine allineata in alto
Importante: un dialog DEVE avere un pulsante di comando con valore "Ok" o "Annulla".
Le proprietà sopra elencate non sono valide per tutti gli oggetti. Le seguenti invece sono universali:
disable oggetto disablitato

hide oggetto invisibile

group oggetto di un gruppo. E' importante per i gruppi di opzioni determinati da oggetti radio dato che delimita l'ambito del gruppo in cui agisce la modalità di esclusione delle selezioni

result oggetto che restituisce il valore di ritorno di un dialog modale su un comando "Ok"

/dialog -m name table

/dialog -t name text

/dialog -s name x y w h

-r centra il dialog;

-bp interpreta le misure come dbu o pixels;

-n annulla l'impostazione in primo piano del dialog;

-c clicka il pulsante "Annulla";

Potete accostare ad esempio al -m anche il -d, che apre il dialog sul desktop (cioè come finestra indipendente dal mIRC) e quindi sfruttare anche le opzioni di minimizza/ripristina assicurate dalle opzioni -i e -e.

title il titolo del dialog

modal per sapere se il dialog è modale o meno (tramite $true e $false)

table il nome della dialog table usata nel dialog

ok l'id del pulsante "Ok", se esiste

cancel l'id del pulsante "Annulla", se esiste

result l'id del pulsante con valore di ritorno, se esiste

focus l'id dell'oggetto correntemente focalizzato

tab l'id della tab correntemente attiva

active per sapere se il dialog è attivo o meno (tramite $true e $false)

dialog -mv MioDialog MiaTable

return $dialog(MioDialog).active

}
Con l'identificatore $MioEsempio verrà aperto un dialog e successivamente ci verrà restituito $true se il dialog appena aperto è attivo (lo è certamente :) ) o $false se non lo è.

edit viene azionato quando il testo di un editbox o di un combobox viene modificato

sclick scaturisce dal click del tasto sinistro del mouse su un oggetto (anche questo non è un evento esteso a tutti gli oggetti)

dclick scaturisce dal doppio click del tasto sinistro su una combobox o una listbox

menu evento azionato dalla selezione della voce di un oggetto item
La sintassi dell'evento ON DIALOG è:
on 1:dialog:name:event:id: { }
Nota: per il sottoevento "init" il valore "id" è sempre 0.
on 1:dialog:name:init:0: { }
Esempi sull'evento ON DIALOG
Un esempio sull'evento specifico "sclick":
on 1:dialog:MioDialog:sclick:5: { echo -a E' stato premuto il tasto con id 5 del dialog $dname }
Possiamo anche convenientemente manovrare un solo evento scrivendo un sistema di /if dipendenti da $did, che è l'id dell'oggetto dell'evento. Esemplifichiamo per dare l'idea:
on 1:dialog:MioDialog:sclick:*: {

if ($did == 1) echo -a Hai spinto il tasto con id 1

if ($did == 2) echo -a Hai spinto il tasto con id 2

if ($did == 3) echo -a Hai spinto il tasto con id 3

if ($did == 4) echo -a Hai spinto il tasto con id 4

if ($did == 5) echo -a Hai spinto il tasto con id 5

}
Che è equivalente a:
on 1:dialog:MioDialog:sclick:1: { echo -a Hai spinto il tasto con id 1 }

on 1:dialog:MioDialog:sclick:2: { echo -a Hai spinto il tasto con id 2 }

on 1:dialog:MioDialog:sclick:3: { echo -a Hai spinto il tasto con id 3 }

on 1:dialog:MioDialog:sclick:4: { echo -a Hai spinto il tasto con id 4 }

on 1:dialog:MioDialog:sclick:5: { echo -a Hai spinto il tasto con id 5 }
Ora possiamo passare all'azione sugli oggetti di un dialog, ma mi preme anticipare alcuni importanti suggerimenti, per semplificare la vostra creazione e contemporaneamente allargarne l'efficienza. In questo breve passaggio vi esporrò alcuni utili consigli per creare un ottimo dialog nel caso voi vogliate usarlo come sistema di settaggio di variabili. Nel caso invece decidiate di usarlo come un "pannello di controllo", beh questa spiegazione non riguarda minimamente le vostre intenzioni. :)
Bene, i consigli che vi do sono questi:

1) munite il dialog SEMPRE di un pulsante "Ok" e un pulsante "Annulla". Ciò perché l'utente potrebbe anche voler annullare i cambiamenti fatti alle impostazioni di un dialog e di conseguenza delle variabili che esso definisce;

2) come conseguenza del primo punto, vi sconsiglio altamente di settare delle variabili nei singoli eventi degli oggetti modificabili, come ad es. nell'evento "sclick" di un checkbutton o "edit" di un editbox, poiché tali settaggi resterebbero in quel modo irreversibili e non potrete più fare affidamento alla combinazione Ok/Annulla descritta sopra;

3) inoltre così facendo vi complichereste la vita, cioè dovreste modificare l'evento di OGNI singolo oggetto modificabile;

4) se usate un editor che supporta un ulteriore editor degli eventi, vi conviene agire direttamente da questo, senza usare il mIRC per svilupparli. Infatti scrivere il code del dialog all'interno del dialog stesso è molto più comodo ed intuitivo;

5) in conclusione vi consiglio caldamente di utilizzare 2 eventi (sempre per quanto riguarda i dialogs di variabili), e rispettivamente: l'evento "init" per il CARICAMENTO delle variabili e quindi l'impostazione degli oggetti del dialog in base ad esse; l'evento "sclick" di un pulsante "Ok" che procederà al SALVATAGGIO delle variabili in base all'impostazione degli oggetti del dialog.

comando /set (che agisce sulle variabili) e identificatore $did() (che ottiene valori dal dialog);

comando /did (che agisce sul dialog) e variabile (che è di per sé un valore).

-t rende l'oggetto pulsante di comando predefinito (richiamato di default da INVIO);

-b disabilita l'oggetto;

-v rende l'oggetto visibile;

-h nasconde l'oggetto;

-m disabilita le editbox;

-u funziona al contrario di -c, ma non si usa con listbox e combobox;

-k abbinato -cu, mantiene le selezioni in un listbox;
-r svuota il testo dell'oggetto;

-a aggiunge il testo "text" alla fine del testo dell'oggetto;

-d cancella la linea N dell'oggetto;

-i inserisce nella linea N il testo "text";

-o sovrascrive la linea N con il testo "text";
-g imposta l'immagine di un oggetto icon;

/did -g name id [N] filename

len lunghezza del testo dell'oggetto (della linea N se specificata)

lines numero delle linee (di un listbox/combobox)

sel numero della linea selezionata (di un listbox/combobox)

seltext ha due valenze: in un editbox è la parte di testo selezionato, mentre in un listbox è il testo dell'oggetto correntemente selezionato nella lista

selstart numero del carattere da cui parte la selezione in un editbox

selend numero del carattere in cui finisce la selezione in un editbox

edited restituisce $true se il testo dell'editbox è stato modificato

state stato (unchecked = 0,checked = 1,grayed = 2) di oggetti checkbutton o radiobutton

next restituisce l'id dell'oggetto successivo ad esso secondo il tab order

prev restituisce l'id dell'oggetto precedente ad esso secondo il tab order

visible restituisce $true se l'oggetto è visibile, altrimenti $false

enabled restituisce $true se l'oggetto è abilitato, altrimenti $false
Note: negli eventi ON DIALOG e negli alias che essi richiamano il parametro "name" può essere omesso. In un combobox la linea (N) che rappresenta l'editbox è 0.
Esempi dell'identificatore $did()
Settare una variabile con il contenuto di un editbox (importante):
/set %MiaVariabile $did(MioDialog,1)
Qui invece vi propongo un esempio pratico di come settare una funzione On/Off tramite un checkbutton o un radiobutton:
/set %MiaVariabile $did(MioDialog,2).state
Quando il check è selezionato, la variabile sarà 1 (funzione On), altrimenti 0 (funzione Off).
Se poi avete una certa familiarità con i tokens, :) vi risulterà comodo in alcuni casi usare l'identificatore $didtok(), che restituisce in forma tokenizzata la lista di un listbox o di un combobox:
$didtok(name,id,C)
Se proprio non sapete cosa siano i tokens e siete curiosi di saperlo andate al livello superiore e saprete cosa sono. :)
Per utilizzare al meglio un dialog, bisogna che acquistiate sicurezza con il concetto di comando e di identificatore in una visione COMPLEMENTARE. Per dirla breve, dovrete avere l'idea di comando come l'azione che IMPOSTA, e di identificatore come l'azione che RESTITUISCE. Questa è una delle basi della progammazione basata sui dialogs e, nel caso specifico, del mIRC scripting in generale. Solo in questo modo riuscirete a gestire con enorme tranquillità in egual maniera /did e $did(), che in conclusione sono davvero le UNICHE conoscenze necessarie e sufficienti per creare un dialog. E' questione di tempo: vi renderete conto che fare un dialog è una cosa basata soprattutto sulla logica e (ciò vi rincuorerà) basata come ho detto solo ed esclusivamente su /did e $did(), almeno per un dialog per come è stato inteso all'inizio, cioè come sistema di settaggio di variabili, che è in linea di massima il tipo di dialog di più largo uso