Corso di Interfacce Utente - A.A. 2002-2003

PROGETTO DI RECUPERO - DOCUMENTO 2

Descrizione del programma che implementa l'applicazione

Introduzione

Il programma e' composto da 5 classi java (contenute in 5 file):

PairOfDouble implementa una coppia di coordinate double, e' usata per rappresentare punti e vettori
SteadyCircle implementa un cerchio, e' usata per i buchi, e' super-classe di MovingCircle
MovingCircle implementa un cerchio mobile, e' usata per la pallina, e' sotto-classe di SteadyCircle
SteadyBlock implementa un rettangolo, e' usata per gli ostacoli, e' super-classe di WorkEnv
WorkEnv implementa l'ambiente di lavoro con i buchi, gli ostacoli, la pallina ecc., essendo anche una rettangolo e' sotto-classe di SteadyBlock

Nel seguito sono documentate le variabili e funzioni pubbliche di queste 5 classi.

Nota: non tutte le funzioni vi saranno utili per sviluppare l'interfaccia, comunque qui per completezza sono state documentate tutte.

classe PairOfDouble

Le istanze di questa classe sono coppie di coordinate che rappresentano a seconda del contesto punti oppure vettori nel piano. I punti servono per le posizioni. i vettori servono per le velocita'.

Elementi appartenenti alla classe (static)

Funzioni relative al calcolo di distanze:

double squaredDistance(PairOfDouble p1, PairOfDouble p2)
Restituisce la distanza al quadrato fra due punti p1 e p2.
double distance(PairOfDouble p1, PairOfDouble p2)
Restituisce la distanza fra due punti p1 e p2.

Costruttori:

PairOfDouble(double x0, double y0)
Crea un punto o un vettore con coordinate o componenti x0, y0.
PairOfDouble(PairOfDouble p)
Crea un punto o un vettore come copia di un dato punto o vettore p.

Elementi appartenenti ad ogni oggetto istanza della classe

Variabili che descrivono lo stato interno:

double x, y;
Coordinate del punto oppure componenti del vettore.

Funzioni che agiscono sul punto o vettore:

double length()
Restituisce la lunghezza di questo vettore, ovvero la distanza di questo punto dall'origine.
void normalize()
Normalizza il vettore per renderlo un versore.
void scale(double f)
Scala questo punto o vettore secondo il fattore di scala f.
void scale(PairOfDouble f)
Scala questo punto o vettore secondo fattori di scala sulla x e sulla y espressi dalla coppia f (cioe' f.x ed f.y).
void translate(PairOfDouble p)
Trasla questo punto o vettore secondo il vettore di traslazione p.

classe SteadyCircle

Le istanze di questa classe sono cerchi fermi. Serve direttamente per rappresentare i buchi. Un cerchio fermo e' caratterizzato da:

posizione (quella del suo centro)
raggio

Elementi appartenenti alla classe (static)

Costruttori:

SteadyCircle(PairOfDouble c, double r)
SteadyCircle(double cx, double cy, double r)
Creano un cerchio con centro e raggio assegnati.

Elementi appartenenti ad ogni oggetto istanza della classe

Funzioni relative alla posizione (del centro) di questo cerchio:

void setCenter(double x1, double y1) void setCenter(PairOfDouble c1)
Assegnano la posizione del centro.
PairOfDouble getCenter()
Restituisce la posizione del centro.

Funzioni relative al raggio di questo cerchio:

boolean setRadius(double r)
Assegna il raggio, che non deve essere negativo, ritorna true se ha successo, false se fallimento.
double getRadius()
Restituisce il raggio.

classe MovingCircle

Le istanze di questa classe sono cerchi mobili. Serve per rappresentare la pallina. E' sotto-classe di SteadyCircle da cui eredita tutte le caratteristiche. In piu' e' caratterizzata da:

direzione della velocita'
intensita' della velocita'
una "storia" che descrive che cosa e' successo al cerchio mobile nel precedente passo di simulazione

Elementi appartenenti alla classe (static)

Costante che la massima intensita' della velocita' come fattore moltiplicativo rispetto al raggio del cerchio mobile:

double MAX_SPEED = 0.5;

Costanti che definiscono i possibili valori della storia per un cerchio mobile:

int OBSTACLE;
ha urtato un ostacolo ed e' rimbalzato.
int BORDER;
ha urtato una parete dell'ambiente di lavoro ed e' rimbalzato.
int PLAIN;
non ha urtato nulla.

Non appena la pallina cade in un buco viene distrutta, percio' non e' necessario un valore di storia per descrivere questo caso.

Costruttori:

MovingCircle(double x0, double y0, double r0, double v0, double vx0, double vy0)
MovingCircle(PairOfDouble c0, double r0, PairOfDouble v0, double vy0)
Creano cerchio mobile di raggio r0 con centro in posizione c0=(x0,y0) e con velocita' di intensita' v0 diretta secondo il versore di v0=(vx0, vy0).

Elementi appartenenti ad ogni oggetto istanza della classe

Variabili che descrivono lo stato interno sono private, accessibili in lettura e scrittura solo tramite funzioni.

Funzioni relative alla velocita' di questo cerchio mobile:

boolean setSpeed(double s)
Assegna l'intensita' della velocita'. Se s e' nell'intervallo di velocita' ammissibili per questo cerchio, la assegna e restituisce true. Altrimenti la tronca alla minima (se minore) o alla massima (se maggiore) velocita' ammissibile, la assegna e restituisce false.
double getSpeed()
Restituisce l'intensita' della velocita' della pallina.
void setDirection(double vx1, double vy1) void setDirection(PairOfDouble sv1)
Assegnano la direzione della velocita'. Il vettore puo' avere lunghezza non unitaria, viene automaticamente normalizzato per renderlo un versore.
PairOfDouble getDirection()
Restituisce la direzione della velocita', che e' un versore cioe' un vettore di lunghezza unitaria.

Funzioni relative alla storia di questo cerchio mobile (che cosa gli e' accaduto nell'ultimo passo di simulazione. I valori ammissibili della storia sono MovingCircle.OBSTACLE, MovingCircle.BORDER, MovingCircle.PLAIN (non eiste un valore per il caso "caduto in un buco) perche' le palline cadute non esistono piu'):

void setHistory(int h) assegna la storia.
int getHistory() restituisce la storia.

classe SteadyBlock

Un'istanza di questa classe e' un rettangolo fermo. Serve direttamente per rappresentare gli ostacoli. Un rettangolo fermo e' caratterizzato da:

punto di ancoraggio (l'angolo di coordinate x ed y minime)
larghezza
altezza

Elementi appartenenti alla classe (static)

Costanti che definiscono le possibili posizioni di un punto rispetto al rettangolo, sono maschere binarien che si possono combinare con operatori bit a bit (es. nord-est si ottiene con NORTH|EAST):

byte CENTER all'interno del rettangolo
byte EAST nel semipiano con x maggiori della massima x del rettangolo
byte WEST nel semipiano con x minori della minima x del rettangolo
byte SOUTH nel semipiano con y minori della minima y del rettangolo
byte NORTH nel semipiano con y maggiori della massima y del rettangolo

Costruttori:

SteadyBlock(double x0, double y0, double w, double h)
Crea un nuovo rettangolo con punto di ancoraggio (x0,y0), larghezza w ed altezza h
SteadyBlock(PairOfDouble a0, double w, double h)
Crea un nuovo rettangolo con punto di ancoraggio a0, larghezza w ed altezza h

Elementi appartenenti ad ogni oggetto istanza della classe

Variabili che rappresentano il contorno dell'ambiente di lavoro sono private, accessibili solo attraverso le funzioni.

Funzioni relative al punto di ancoraggio (angolo di x ed y minime) di questo rettangolo:

void setAnchor(double x1, double y1)
void setAnchor(PairOfDouble a1)
Assegnano il punto di ancoraggio.
PairOfDouble getAnchor()
Restituisce il punto di ancoraggio.

Funzioni relative a larghezza ed altezza di questo rettangolo:

boolean setWidth(double w)
Assegna la larghezza, che non deve essere negativa, ritorna true se ha successo, false se fallimento.
boolean setHeight(double h)
Assegna l'altezza, che non deve essere negativa, ritorna true se ha successo, false se fallimento.
public boolean setSize(PairOfDouble s)
public boolean setSize(double w, double h)
Assegnano contemporaneamente larghezza e altezza, con gli stessi vinvoli sopra citati.
double getWidth()
double getHeight()
PairOfDouble getSize()
Restituiscono rispettivamente larghezza, altezza, e un vettore avente per componenti larghezza ed altezza.

Altre funzioni relative alla geometria del rettangolo:

double getMinX()
double getMinY()
double getMaxX()
double getMaxY()
Restituiscono le coordinate x ed y minime e massime del rettangolo.
boolean setBoundary(double x0, double y0, double x1, double y1)
Assegna le coordinate x ed y minime (x0,y0) e massime (x1,y1), fallisce e restituisce false se qualche coorinata minima e' maggiore di una massima, se ha successo restituisce true.

Funzioni relative al calcolo di distanze:

double outsideDistance(PairOfDouble p)
Restituisce la distanza tra un punto p e questo rettangolo, assumento che fuori sia vuoto e dentro sia pieno (la distanza e' zero se p sta dentro il rettangolo).
double insideDistance(PairOfDouble p)
Restituisce la distanza tra un punto p e questo rettangolo, assumento che dentro sia vuoto e fuori sia pieno (la distanza e' zero se p sta fuori dal rettangolo).
byte classifyPosition(PairOfDouble p)
Classifica la posizione del punto p rispetto a questo rettangolo, restituisce un "or" di punti cardinali, es. NORTH|EAST per dire che p sta a nord-est.

classe WorkEnv

Un'istanza di questa classe e' un ambiente di lavoro. E' sotto-classe di SteadyBlock da cui eredita tutte le caratteristiche. Queste caratteristiche ereditate descrivono la geometria dell'area di lavoro, che e' un rettangolo. In piu' e' caratterizzato da:

Un certo numero di buchi contenuti nell'area di lavoro.
Un certo numero di ostacoli contenuti nell'area di lavoro.
Una pallina mobile.

WorkEnv usa oggetti della classe java Vector per memorizzare i buchi e gli ostacoli contenuti nell'area di lavoro.

Elementi appartenenti alla classe (static)

Costruttore:

WorkEnv(double x0, double y0, double w, double h)
Crea un ambiente di lavoro dato il punto di aggancio, larghezza ed altezza (come per la super-classe). Per difetto l'ambiente creato non ha nessun buco, nessun ostacolo, e la pallina non e' presente.

Elementi appartenenti ad ogni oggetto istanza della classe

Variabili che rappresentano l'ambiente di lavoro sono private, accessibili solo attraverso le funzioni.

Funzioni per gestire gli ostacoli presenti nell'area di lavoro:

boolean addObstacle(SteadyBlock b)
Aggiunge un ostacolo, che deve essere situato dentro l'area di lavoro. Due ostacoli possono essere (parzialmente) sovrapposti: la loro unione forma un ostacolo piu' grande. Un ostacolo puo' coprire (parzialmente) un buco. Restituisce true se ha successo, false se fallisce.
boolean removeObstacle(SteadyBlock b)
Rimuove una ostacolo dall'ambiente di lavoro, se e' presente. Restituisce true se ha successo, false se fallisce.
numObstacles()
restituisce il numero di ostacoli presenti.
SteadyBlock getObstacle(int i)
Restituisce l'i-esimo ostacolo presente.

Funzioni per gestire i buchi presenti nell'area di lavoro:

boolean addHole(SteadyCircle h)
Aggiunge un buco. Un buco puo' sovrapporsi ad un altro (formeranno un buco piu' grande). Un buco deve essere completamente contenuto nell'area di lavoro. Un buco puo' essere (parzialmente) coperto da un ostacolo. Restituisce true se ha successo, false se fallisce.
boolean removeHole(SteadyCircle h)
Rimuove un buco dall'ambiente di lavoro, se e' presente. Restituisce true se il buco e' presente, altrimenti restituisce false.
int numHoles()
Restituisce il numero di buchi presenti in questo ambiente di lavoro.
SteadyCircle getHole(int i)
Restituisce l'i-esimo buco presente.

Funzioni relative al rettangolo che definisce l'area di lavoro e a sue sotto-aree:

boolean insideArea(SteadyCircle obst, double x0, double y0, double x1, double y1)
boolean outsideArea(SteadyCircle obst, double x0, double y0, double x1, double y1)
Controllano se un ostacolo e' dentro / fuori il rettangolo di diagonale (x0,y0)-(x1,y1).
boolean insideArea(SteadyBlock hole, double x0, double y0, double x1, double y1)
boolean outsideArea(SteadyBlock hole, double x0, double y0, double x1, double y1)
Controllano se un buco e' dentro / fuori il rettangolo di diagonale (x0,y0)-(x1,y1).
void emptyArea(double x0, double y0, double x1, double y1)
Svuota la sotto-area di diagonale (x0,y0)-(x1,y1) cancellando tutti gli ostacoli e i buchi che hanno intersezione non vuota con tale area.
boolean fillArea(double x0, double y0, double x1, double y1, double minO, double maxO, int percentO, double minH, double maxH, int percentH)
Riempie la sotto-area di diagonale (x0,y0)-(x1,y1) con una miscela di ostacoli e buchi, secondo le percentuali assegnate. Sono dati anche il min e max lato di un ostacolo e il min e max raggio di un buco. La sotto-area deve essere vuota e la somma delle percentuali corrispondenti deve valere 100. La funzione restituisce true se ha successo, false se fallisce.
boolean isEmptyArea(double x0, double y0, double x1, double y1)
Controlla se la sotto-area di diagonale (x0,y0)-(x1,y1) e' vuota da ostacoli e buchi.

Funzioni relative alla pallina e alla simulazione:

MovingCircle getBall()
Restituisce la pallina.
addBall(MovingCircle b)
Aggiunge la pallina se questa cade interamente nell'area di lavoro e se non c'e' gia' una pallina. Restituisce true se successo, false se fallimento.
removeBall()
Togolie la pallina se e' presente. Restituisce true se successo, false se fallimento.
PairOfDouble nextCenter()
Restituisce la posizione della pallina nella prossima unita' di tempo, cioe' dopo un passo di simulazione.
byte getHitWalls()
Restituisce tutti gli urti che la pallina ha con i muri dell'ambiente di lavoro, il risultato puo' essere una combinazione in "or" bit a bit, es: SOUTH|EAST.
boolean hitObstacle(int i)
Controlla se la pallina urta l'i-esimo ostacolo presente nell'ambiente di lavoro.
boolean fallIntoHole(int i) Controlla se la pallina cade dentro l'i-esimo buco presente nell'ambiente di lavoro. La pallina cade nel buco se il suo baricentro cade internamente al buco ed il raggio della pallina) e' minore di quello del buco.
boolean moveOneStep()
Avanza di un'unita' di tempo, cioe' di un passo, nella simulazione. Gestisce automaticamente eventuali urti e cadute. Restituisce false se la pallina non e' presente, quindi non e' possibile eseguire la simulazione.

Funzioni relative agli attrattori:

void attract(PairOfDouble a, int percent)
Attrae la direzione della velocita' della pallina verso il punto a con percentuale di attrazione assegnata (tra 0 e 100). Con percentuale 0 la velocita' restera' invariata, con percentuale 100 la velocita' andra' a dirigersi esattamente verso il punto.
void attract(byte whichWall, int percent)
Attrae la direzione della velocita' della pallina verso la parete whichWall dell'ambiente di lavoro (che deve essere uno dei quattro punti cardinali) con percentuale di attrazione assegnata (tra 0 e 100). Con percentuale 0 la velocita' restera' invariata, con percentuale 100 la velocita' andra' a dirigersi esattamente verso il muro.

Funzioni di lettura:

SteadyBlock loadObstacle(FileInputStream in)
Legge da file un ostacolo, senza ancora aggiungerlo all'ambiente di lavoro. Non controlla se sia un ostacolo corretto (questo controllo e' fatto dalla funzione che aggiunge poi l'ostacolo all'ambiente di lavoro). Restituisce l'ostacolo letto se tutto ok, oppure null se errore.
SteadyCircle loadHole(FileInputStream in)
Legge da file un buco, senza ancora aggiungerlo all'ambiente di lavoro. Non controlla se sia un buco corretto (questo controllo e' fatto dalla funzione che aggiunge poi il buco all'ambiente di lavoro). Restituisce il buco se tutto ok, oppure null se errore.

Funzioni di scrittura:

boolean writeObstacle(OutputStream out, Outcome t)
Scrive su file un ostacolo.
boolean writeHole(OutputStream out, ParticleType pt)
Scrive su file un buco
boolean writeWorkEnv(OutputStream out)
Funzione di test che scrive l'ambiente.