Appendice A - Guida di riferimento

 

indice Legenda

Di seguito sono elencate sia le funzioni che vengono chiamate da Idra, sia quelle che Idra mette a disposizione dell'autore del racconto; salvo diversa indicazione, le funzioni non ritornano alcun valore. I colori facilitano la lettura, come in questo esempio immaginario: 
spremi(agrume)
agrume : un frutto succoso dal sapore aspro.

Spreme l'agrume indicato e ne ritorna il succo; è consigliabile applicare questa funzione ad agrumi nel corretto stato di maturazione. 

v.spremuta = spremi(Arancia)
bevi(spremi(Limone))
Blu : parole o caratteri da riprodurre esattamente come indicati.
Verde : indica genericamente un tipo di dato o argomento, o comunque qualcosa non da prendere alla lettera.
Rosso : esempi di impiego; salvo diversa indicazione, ogni riga costituisce un esempio separato.
Magenta : nomi di file o cartelle (directory).

Dato che in JavaScript maiuscole e minuscole sono distinte, le funzioni vanno scritte esattamente come indicato, ossia quelle di Idra con l'iniziale minuscola e quelle del racconto-gioco, incluse le funzioni come Intestazione() che vengono chiamate automaticamente da Idra, con l'iniziale maiuscola.

È vivamente sconsigliato usare funzioni non documentate in questa pagina o, peggio ancora, accedere direttamente alle variabili di Idra. Non solo si rischiano inattesi effetti collaterali, ma è probabile che si possano verificare problemi con eventuali aggiornamenti o versioni successive.

 

Variabili

Le variabili di gioco sono, dal punto di vista JavaScript, delle proprietà della variabile v e vanno quindi sempre precedute da v. come in questi esempi: 

v.corda = 0
v.pagatoNoleggio = 1
v.spesa = 15000
Una variabile viene creata semplicemente usandola come appena visto; per pulizia e facilità di manutenzione, tuttavia, è consigliabile assegnare un valore iniziale a tutte le variabili di gioco nella funzione Inizia() sotto descritta, che viene chiamata automaticamente da Idra all'inizio di una nuova lettura.

Per uso temporaneo, all'interno di una funzione, si possono usare anche variabili JavaScript vere e proprie, cioè che non iniziano con v.; va però ricordato che esse non verranno salvate su disco.

 

Funzioni chiamate da Idra

Queste funzioni stanno tipicamente nel file gioco.js che descrive il racconto; esse vengono chiamate automaticamente da Idra (o comunque tramite funzioni di Idra) al momento opportuno. Non vanno mai chiamate direttamente.
 

indice Funzione di avvio

function Inizia() {
  ...
}

Obbligatoria. Viene chiamata quando il lettore sceglie di iniziare una nuova lettura; ha il compito di azzerare (o comunque preparare) le variabili di gioco e di richiamare la prima pagina per mezzo della funzione vai(). Le righe sottostanti mostrano un esempio completo: 

function Inizia() {
  v.quota = 0
  v.temperatura = 18
  vai(Aeroporto)
}

indice Funzione di pagina e relative opzioni

function Pagina123() {
  ...
}

Ogni pagina è descritta da una funzione JavaScript, che sta tipicamente nel file gioco.js; il nome della funzione, che deve iniziare con una lettera maiuscola, verrà usato per riferirsi alla pagina, ad esempio per richiamarla con la funzione vai(). Le righe sottostanti mostrano un esempio completo: 

function Aeroporto() {
  titolo("All'aeroporto")
  testo("Tutto va bene, siamo pronti al decollo.")
  continua(Decollo)
}

function OpzioniPagina(pagina) {
  ...
}

Opzionale. Imposta le caratteristiche generali della pagina, come il colore o disegno di fondo e il colore dei link. Se è presente, essa viene chiamata da Idra subito prima di mostrare una pagina, con l'argomento pagina che indica la pagina in questione; deve ritornare una stringa che sarebbe valida all'interno di un'istruzione HTML (tag) <body>, come in questo esempio completo: 

function OpzioniPagina(pag) {
  if (pag == Tempesta) {
    return 'background="fulmini.jpg"'
  } else {
    return 'bgcolor="#ffffcc"'
  }
}

function Intestazione(pagina) {
  ...
}

Opzionale. Consente di inserire elementi all'inizio di ciascuna pagina. Se è presente, essa viene chiamata da Idra subito prima di chiamare la funzione di pagina vera e propria, con l'argomento pagina che indica la pagina in questione; può essere usata per mettere un'intestazione generica o un semplice stacco o decorazione, come in questo esempio completo che (poiché ignora l'argomento pagina) varrà per tutte le pagine: 

function Intestazione(pag) {
  testo('<img src="decoro.jpg">') 
}

function PiePagina(pagina) {
  ...
}

Opzionale. Consente di inserire elementi alla fine di ciascuna pagina. Se è presente, essa viene chiamata da Idra subito dopo aver chiamato la funzione di pagina vera e propria, con l'argomento pagina che indica la pagina in questione; può essere usata per mettere un piè di pagina generico, come in questo esempio completo che (poiché ignora l'argomento pagina) varrà per tutte le pagine: 

function PiePagina(pag) {
  testo("<hr>")
  MostraInventario()
  testo("Hai raggiunto finora ", v.punti, " punti.") 
}

indice Pagina di Informazioni

function Informazioni() {
  ...
}

Obbligatoria (a meno di non togliere il link da ctrl.html). Viene chiamata direttamente dal frame ctrl.html quando il lettore fa clic su "Informazioni sul gioco". Non è di una funzione di pagina, ma solitamente richiama una pagina temporanea facendo uso di mostra() come nell'esempio incluso in gioco.js, oppure la produce direttamente con le funzioni speciali apriPagina() e chiudiPagina() come nell'esempio completo sotto riportato. In ogni caso si dovrà usare ridisegna() per tornare alla pagina precedentemente mostrata. 

function Informazioni() {
  apriPagina('bgcolor="#ccff66"')
  testo("<br>L'Ufficio Informazioni &egrave; chiuso per la pausa pranzo.")
  continua("ridisegna()")
  chiudiPagina()
}

Funzioni di Idra

Queste funzioni sono gli strumenti che l'autore ha a disposizione per svolgere le principali operazioni, come la costruzione di una pagina (incluse le scelte a disposizione del lettore) o il passaggio da una pagina all'altra. Esse risiedono nel file idra.js, che è bene non modificare.
 

indice Funzioni di creazione pagina

Ogni pagina è descritta da una funzione JavaScript, per cui in questo manuale il termine "pagina" si riferisce alla funzione stessa; quest'ultima crea il contenuto della pagina vera e propria facendo uso delle seguenti funzioni di Idra:
  
titolo(stringa)
stringa : una stringa da usare come titolo della pagina.

Scrive un titolo centrato, in grassetto e con un carattere più grande, terminando con uno stacco di paragrafo. Può anche essere chiamata più volte nella stessa pagina, in quanto non svolge alcun lavoro particolare. 

titolo("Sulla mongolfiera")   

testo(espressione)
testo(espressione1, espressione2, espressione3, ...	)
espressione : un elemento stampabile: stringa, variabile o altro.

Scrive uno o più elementi nella pagina; ciascun elemento può essere una stringa di testo, una variabile di gioco (di cui verrà mostrato il contenuto) o, in genere, qualsiasi oggetto stampabile secondo la sintassi di JavaScript. Se il testo contiene istruzioni HTML, ad esempio <b> per il grassetto o <img> per un'immagine, esse verranno eseguite dal browser. 

testo("Sotto la navicella si stende l'oceano Pacifico.")
testo(v.temperatura - 20)
testo("L'altimetro segna: ", v.quota)
testo("A questa quota fa <b>veramente</b> freddo.<br>")
testo('<img src = "nuvole.jpg">')

rinvio(espressione, azione)
espressione : un elemento stampabile: stringa, variabile o altro.
azione : un nome di pagina (senza parentesi) oppure una stringa contenente istruzioni JavaScript.

Crea un rinvio (link) all'interno del testo, senza stacco di alcun genere; viene normalmente usata frammista alle istruzioni testo() e può come queste contenere istruzioni HTML, ad esempio per inserire un'immagine cliccabile invece che del testo. A seconda del tipo del secondo parametro, il risultato del clic sarà il passaggio alla pagina indicata o l'esecuzione delle istruzioni JavaScript specificate. 

rinvio("togliere gas", Atterra)
rinvio('<img src = "cade.jpg">', Crash)
rinvio("dare gas", "v.quota = 4000; vai(AltaQuota)")

scelta(espressione, azione)
scelta(condizione, espressione, azione)
espressione : un elemento stampabile: stringa, variabile o altro.
azione : un nome di pagina (senza parentesi) oppure una stringa contenente istruzioni JavaScript.
condizione : una variabile o un'espressione logica vera (o diversa da zero) o falsa (o zero).

Nel primo caso (due soli argomenti) è identica alla funzione rinvio(), tranne per la presentazione che avviene su una linea separata e preceduta da un pallino; viene spesso usata per la costruzione di menu di scelte. Se invece è chiamata con tre argomenti, la scelta viene mostrata solo se la condizione indicata è vera. 

scelta("Decidete di gettare l'ancora", Ancoraggio)
scelta('Urlate "Aiuto!" a pieni polmoni', "v.sos = 1")
scelta(v.sos, '<img src = "elicottero.jpg">', Soccorso)
scelta(v.zavorre > 0, "Buttate una zavorra", "v.zavorre -=1; vai(Risale)")

continua(azione)
continua(condizione, azione1, azione2)
azione : un nome di pagina (senza parentesi) oppure una stringa contenente istruzioni JavaScript.
condizione : una variabile o un'espressione logica vera (diversa da zero, se è un valore) o falsa (zero).

Mostra la scelta "Continua". Nel primo caso (un solo argomento) in risposta a un clic esegue l'azione indicata; se invece si forniscono tre argomenti, esegue l'azione1 se la condizione è vera, l'azione2 se la condizione è falsa. 

continua(Pagina18)
continua("v.passeggero = 1; vai(Pagina67)")
continua(v.autorizzato, Decolla, RestaFermo)
continua(dado() > 5, BelTempo, "v.brutto = 1; vai(Nuvoloni)")

indice Funzioni di cambio pagina

vai(pagina)
pagina : un nome di pagina (senza parentesi).

Presenta la pagina indicata, che diventa la pagina corrente. Prima di mostrarla viene chiamata la funzione OpzioniPagina(), se esiste; durante la presentazione vengono chiamate nell'ordine la funzione Intestazione(), se esiste, poi la funzione di pagina indicata, infine la funzione PiePagina(), se esiste. Non va chiamata direttamente da una funzione di pagina, ma solo come effetto di una scelta (o rinvio). 

vai(Pagina112)
vai(Vulcano)

mostra(pagina)
mostra(pagina, opzioni)
pagina : un nome di pagina (senza parentesi).
opzioni : una stringa contenente opzioni valide per un'istruzione HTML (tag) <body>.

Presenta la pagina indicata senza marcarla come pagina corrente; non viene chiamata la funzione OpzioniPagina() ma, allo stesso scopo, si può fornire direttamente una stringa di opzioni. Non vengono chiamate né Intestazione() né PiePagina(); non va chiamata direttamente da una funzione di pagina, ma solo come effetto di una scelta (o rinvio). La funzione mostra() si usa per pagine provvisorie, in cui non si devono modificare i valori delle variabili. Una successiva chiamata alla funzione ridisegna() ripristinerà la pagina corrente memorizzata dall'ultima vai() eseguita in precedenza. 

mostra(Mappa)

aggiorna()
Ridisegna la pagina corrente, ossia l'ultima che è stata presentata con una chiamata alla funzione vai(), rieseguendo le istruzioni contenute nella pagina. È normalmente usata per mostrare il nuovo aspetto della pagina dopo il cambiamento del contenuto di una o più variabili. 
scelta(! v.luce, "Accendi la torcia", "v.luce = 1; aggiorna()")

ridisegna()
Ridisegna la pagina corrente, ossia l'ultima che è stata presentata con una chiamata alla funzione vai(), senza eseguire le istruzioni contenute nella pagina. È normalmente usata per uscire da pagine provvisorie o informative richiamate con la funzione mostra() senza rischiare di modificare qualcosa rieseguendo la pagina corrente. 
scelta("Torna al gioco", "ridisegna()")

apriPagina()
apriPagina(opzioni)
chiudiPagina()
opzioni : una stringa contenente opzioni valide per un'istruzione HTML (tag) <body>.

L'uso combinato di apriPagina() e chiudiPagina(), con in mezzo le istruzioni di presentazione testo, è del tutto equivalente alla funzione mostra(). Questa coppia di funzioni può essere utile ai programmatori esperti per realizzare una versione personalizzata di mostra(), come in questo esempio completo (che non va chiamato da una funzione di pagina, ma ad esempio da un link in ctrl.html): 

apriPagina('background="drago.jpg"')
testo("Hai trovato finora ", v.tesori, " tesori.")
continua("ridisegna()")
chiudiPagina()

indice Funzioni varie

dado()
dado(facce)
facce : numero di facce del dado.

Ritorna un numero intero pseudocasuale compreso tra 1 e 6 (incluso) oppure tra 1 e facce (incluso) nel caso che quest'ultimo argomento sia fornito. È importante usare solo questa funzione invece della Math.random() di JavaScript, altrimenti le variabili potrebbero essere alterate in modo inaspettato. 

if (dado() == 1) { testo("Sfortunato oggi, eh?") }
continua(dado() > 2, Sano, Malato)
v.probabile = dado(100)

pagina()
Ritorna la pagina corrente, come funzione; se la si vuole conservare in una variabile, la si deve convertire in stringa con nomePagina(). Da notare che la pagina corrente può essere diversa da quella mostrata al lettore, se quest'ultima è stata richiamata con mostra(). 
if (pagina() == Palude) { ... }

nomePagina(pagina)
pagina : un nome di pagina (senza parentesi).

Ritorna una stringa contenente il nome della pagina (funzione) indicata; è utile ad esempio per ricordare una pagina in una variabile. Un programmatore esperto potrebbe anche includere informazioni extra nel nome della pagina, per esempio il tipo di sfondo desiderato (Pagina25s4), estraendo poi nella funzione opzioniPagina() questa informazione (s4) dalla stringa ricavata con nomePagina(). 

v.segno = nomePagina(pagina())
if (nomePagina(p) == "Lago") { ... }

opzioniCookie(nome, giorni)
nome : una stringa da usare come nome per il cookie.
giorni : durata in giorni del cookie su disco.

Imposta nome e durata del cookie usato per salvare la situazione su disco; si usa tipicamente nella funzione Inizia(). Il nome è soggetto alle stesse limitazioni dei nomi delle variabili; non è di solito necessario cambiarlo, in quanto i cookie vengono distinti anche in base all'indirizzo della pagina (o alla directory, se sul proprio computer). Se non si usa questa funzione, il cookie si chiamerà Dati e durerà 60 giorni. 

opzioniCookie("Situazione", 120)

levaSpaziAttorno(stringa)
stringa : una qualsiasi stringa.

Ritorna una stringa priva degli eventuali spazi in testa e in coda; se riceve una stringa di soli spazi, ritorna una stringa nulla (""). Può essere utile, ad esempio, per ripulire stringhe scritte dal lettore in un eventuale campo di input; è usata a questo scopo dal debugger. 

v.nome = levaSpaziAttorno(parent.area.document.miaForm.mioCampo.value)

 


 «--  Precedente 1 2 3 4 5 6 7 A B Indice Successivo  --»