Added documentation for Game View.

This commit is contained in:
Alexei KADIR 2024-04-04 21:27:36 +02:00
parent b0e2050d92
commit 0094ad7af0

View File

@ -11,38 +11,74 @@ import android.view.View;
import androidx.annotation.NonNull; import androidx.annotation.NonNull;
import androidx.annotation.Nullable; import androidx.annotation.Nullable;
/**
* {@code GameView} is a class that displays the current state of the game using the {@code GameModel}.
*
* @autor Alexeï Kadir, Lyanis Souidi, Hugo Dimitrijevic
* @version 1.0
*/
public class GameView extends View implements View.OnTouchListener { public class GameView extends View implements View.OnTouchListener {
/**
* The size of a {@code Cell}, in pixels.
*/
public static final int CELL_SIZE = 96; public static final int CELL_SIZE = 96;
/**
* The width of a {@code Line}, as well as the width of the grid lines, in
* pixels.
*/
public static final int LINE_SIZE = 12; public static final int LINE_SIZE = 12;
/**
* The {@code GameModel} that represents the game.
*/
private GameModel model; private GameModel model;
/**
* The offset of the {@code GameView}, in pixels.
*/
private final Point offset; private final Point offset;
/**
* The {@code Paint} used to draw the grid, lines, and crosses.
*/
private final Paint paint; private final Paint paint;
/**
* The pointer ID of the pointer used to draw a {@code Line}. If no line is
* being drawn, this
* value is -1.
*/
private int linePointerId; private int linePointerId;
/**
* The pointer ID of the pointer used to move the {@code GameView}. If the
* {@code GameView} is
* not being moved, this value is -1.
*/
private int movementPointerId; private int movementPointerId;
/**
* The x-coordinate of the pointer used to move the {@code GameView}, in pixels.
*/
private float movementX; private float movementX;
/**
* The y-coordinate of the pointer used to move the {@code GameView}, in pixels.
*/
private float movementY; private float movementY;
/**
* The {@code GameListener} that listens to events from the {@code GameView}.
*/
private GameListener listener; private GameListener listener;
/**
* Constructs a new {@code GameView} with the specified context and attributes.
*
* @param context The context of the {@code GameView}.
* @param attributes The attributes of the {@code GameView}.
*/
public GameView(Context context, @Nullable AttributeSet attributes) { public GameView(Context context, @Nullable AttributeSet attributes) {
super(context, attributes); super(context, attributes);
@ -56,33 +92,63 @@ public class GameView extends View implements View.OnTouchListener {
this.movementPointerId = -1; this.movementPointerId = -1;
} }
/**
* Sets the {@code GameModel} that represents the game.
*
* @param model The {@code GameModel} that represents the game.
*/
public void setModel(GameModel model) { public void setModel(GameModel model) {
this.model = model; this.model = model;
} }
/**
* Sets the {@code GameListener} that listens to events from the
* {@code GameView}.
*
* @param listener The {@code GameListener} that listens to events from the
* {@code GameView}.
*/
public void setListener(GameListener listener) { public void setListener(GameListener listener) {
this.listener = listener; this.listener = listener;
} }
/**
* Applies the specified offset to the {@code GameView}.
*
* @param dx The x-coordinate of the offset, in pixels.
* @param dy The y-coordinate of the offset, in pixels.
*/
public void applyOffset(int dx, int dy) { public void applyOffset(int dx, int dy) {
this.offset.offset(dx, dy); this.offset.offset(dx, dy);
} }
/**
* Sets the offset of the {@code GameView} to the specified coordinates.
*
* @param x The x-coordinate of the offset, in pixels.
* @param y The y-coordinate of the offset, in pixels.
*/
public void setOffset(int x, int y) { public void setOffset(int x, int y) {
this.offset.x = x; this.offset.x = x;
this.offset.y = y; this.offset.y = y;
} }
/**
* Returns the offset of the {@code GameView}.
*
* @return The offset of the {@code GameView}.
*/
public Point getOffset() { public Point getOffset() {
return new Point(offset); return new Point(offset);
} }
/**
* Converts the specified pixel coordinates to a {@code Cell}.
*
* @param x The x-coordinate of the pixel, in pixels.
* @param y The y-coordinate of the pixel, in pixels.
* @return The {@code Cell} corresponding to the specified pixel coordinates.
*/
private Cell pixelToCell(float x, float y) { private Cell pixelToCell(float x, float y) {
int ox = this.offset.x + (this.getWidth() - this.model.getSize() * CELL_SIZE + CELL_SIZE) / 2; int ox = this.offset.x + (this.getWidth() - this.model.getSize() * CELL_SIZE + CELL_SIZE) / 2;
int oy = this.offset.y + (this.getHeight() - this.model.getSize() * CELL_SIZE + CELL_SIZE) / 2; int oy = this.offset.y + (this.getHeight() - this.model.getSize() * CELL_SIZE + CELL_SIZE) / 2;
@ -90,12 +156,22 @@ public class GameView extends View implements View.OnTouchListener {
return new Cell(Math.round((x - ox) / CELL_SIZE), Math.round((y - oy) / CELL_SIZE)); return new Cell(Math.round((x - ox) / CELL_SIZE), Math.round((y - oy) / CELL_SIZE));
} }
/**
* Converts the specified pixel coordinates to a {@code Cell}.
*
* @param point The pixel coordinates.
* @return The {@code Cell} corresponding to the specified pixel coordinates.
*/
private Cell pixelToCell(Point point) { private Cell pixelToCell(Point point) {
return pixelToCell(point.x, point.y); return pixelToCell(point.x, point.y);
} }
/**
* Converts the specified {@code Cell} to pixel coordinates.
*
* @param cell The {@code Cell}.
* @return The pixel coordinates corresponding to the specified {@code Cell}.
*/
private Point cellToPixel(Cell cell) { private Point cellToPixel(Cell cell) {
int ox = this.offset.x + (this.getWidth() - this.model.getSize() * CELL_SIZE + CELL_SIZE) / 2; int ox = this.offset.x + (this.getWidth() - this.model.getSize() * CELL_SIZE + CELL_SIZE) / 2;
int oy = this.offset.y + (this.getHeight() - this.model.getSize() * CELL_SIZE + CELL_SIZE) / 2; int oy = this.offset.y + (this.getHeight() - this.model.getSize() * CELL_SIZE + CELL_SIZE) / 2;
@ -103,7 +179,11 @@ public class GameView extends View implements View.OnTouchListener {
return new Point(ox + cell.x * CELL_SIZE, oy + cell.y * CELL_SIZE); return new Point(ox + cell.x * CELL_SIZE, oy + cell.y * CELL_SIZE);
} }
/**
* Draws the grid on the specified canvas.
*
* @param canvas The canvas on which to draw the grid.
*/
private void drawGrid(Canvas canvas) { private void drawGrid(Canvas canvas) {
int w = this.getWidth(); int w = this.getWidth();
int h = this.getHeight(); int h = this.getHeight();
@ -120,7 +200,11 @@ public class GameView extends View implements View.OnTouchListener {
canvas.drawLine(0, y, w, y, this.paint); canvas.drawLine(0, y, w, y, this.paint);
} }
/**
* Draws the crosses on the specified canvas.
*
* @param canvas The canvas on which to draw the crosses.
*/
private void drawCrosses(Canvas canvas) { private void drawCrosses(Canvas canvas) {
this.paint.setColor(this.getResources().getColor(R.color.cross)); this.paint.setColor(this.getResources().getColor(R.color.cross));
this.paint.setStrokeWidth(LINE_SIZE); this.paint.setStrokeWidth(LINE_SIZE);
@ -129,7 +213,12 @@ public class GameView extends View implements View.OnTouchListener {
this.drawCross(canvas, cell); this.drawCross(canvas, cell);
} }
/**
* Draws a cross on the specified canvas at the specified cell.
*
* @param canvas The canvas on which to draw the cross.
* @param cell The cell at which to draw the cross.
*/
private void drawCross(Canvas canvas, Cell cell) { private void drawCross(Canvas canvas, Cell cell) {
float size = CELL_SIZE / 4.0F; float size = CELL_SIZE / 4.0F;
@ -139,7 +228,11 @@ public class GameView extends View implements View.OnTouchListener {
canvas.drawLine(position.x - size, position.y, position.x + size, position.y, this.paint); canvas.drawLine(position.x - size, position.y, position.x + size, position.y, this.paint);
} }
/**
* Draws the input line on the specified canvas.
*
* @param canvas The canvas on which to draw the input line.
*/
private void drawInputLine(Canvas canvas) { private void drawInputLine(Canvas canvas) {
if (!this.model.hasInputLine()) if (!this.model.hasInputLine())
return; return;
@ -156,7 +249,11 @@ public class GameView extends View implements View.OnTouchListener {
canvas.drawLine(start.x, start.y, end.x, end.y, paint); canvas.drawLine(start.x, start.y, end.x, end.y, paint);
} }
/**
* Draws the lines on the specified canvas.
*
* @param canvas The canvas on which to draw the lines.
*/
private void drawLines(Canvas canvas) { private void drawLines(Canvas canvas) {
this.paint.setColor(this.getResources().getColor(R.color.line)); this.paint.setColor(this.getResources().getColor(R.color.line));
this.paint.setStrokeWidth(LINE_SIZE); this.paint.setStrokeWidth(LINE_SIZE);
@ -169,7 +266,11 @@ public class GameView extends View implements View.OnTouchListener {
} }
} }
/**
* Called when the {@code GameView} is drawn.
*
* @param canvas The canvas on which to draw the {@code GameView}.
*/
@Override @Override
protected void onDraw(@NonNull Canvas canvas) { protected void onDraw(@NonNull Canvas canvas) {
super.onDraw(canvas); super.onDraw(canvas);
@ -184,7 +285,13 @@ public class GameView extends View implements View.OnTouchListener {
this.drawInputLine(canvas); this.drawInputLine(canvas);
} }
/**
* Called when the {@code GameView} is touched.
*
* @param view The {@code View} that was touched.
* @param event The {@code MotionEvent} that describes the touch event.
* @return {@code true} if the event was handled, {@code false} otherwise.
*/
@Override @Override
public boolean onTouch(View view, MotionEvent event) { public boolean onTouch(View view, MotionEvent event) {
if (this != view) if (this != view)