From a524fc9d787951518b32e3fa1245f0097428556d Mon Sep 17 00:00:00 2001 From: Rodrigo Date: Tue, 23 Apr 2024 22:47:46 +0200 Subject: [PATCH] =?UTF-8?q?un=20poquito=20de=20documentaci=C3=B3n?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../com/rodalc/amarracos/main/MainActivity.kt | 15 +++++- .../rodalc/amarracos/main/PantallaInicio.kt | 15 +++++- .../rodalc/amarracos/main/PantallaVacia.kt | 1 + .../java/com/rodalc/amarracos/mus/General.kt | 52 ++++++++++++++++++- .../com/rodalc/amarracos/mus/PantallaMus.kt | 17 +++++- .../com/rodalc/amarracos/pocha/Jugador.kt | 21 ++++++++ .../rodalc/amarracos/pocha/PantallaPocha.kt | 2 +- .../java/com/rodalc/amarracos/pocha/Utils.kt | 11 ++++ .../rodalc/amarracos/storage/StateSaver.kt | 30 +++++++++++ .../com/rodalc/amarracos/storage/UndoStack.kt | 25 ++++++++- 10 files changed, 182 insertions(+), 7 deletions(-) diff --git a/app/src/main/java/com/rodalc/amarracos/main/MainActivity.kt b/app/src/main/java/com/rodalc/amarracos/main/MainActivity.kt index fa4e913..49e0e26 100644 --- a/app/src/main/java/com/rodalc/amarracos/main/MainActivity.kt +++ b/app/src/main/java/com/rodalc/amarracos/main/MainActivity.kt @@ -16,6 +16,9 @@ import com.rodalc.amarracos.mus.PantallaMus import com.rodalc.amarracos.pocha.PantallaPocha import com.rodalc.amarracos.ui.theme.AmarracosTheme +/** + * Punto de inicio de la aplicación + */ class MainActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) @@ -33,6 +36,10 @@ class MainActivity : ComponentActivity() { } } + +/** + * Función que gestiona el controlador para la navegación entre pantallas. + */ @Composable fun MyApp() { val navController = rememberNavController() @@ -47,7 +54,13 @@ fun MyApp() { } } -@Preview(showBackground = true, widthDp = 640, heightDp = 360) +/** + * Función auxiliar para Preview + */ +@Preview( + showBackground = true, + device = "id:pixel", backgroundColor = 0xFFFFFFFF +) @Composable fun GreetingPreview() { AmarracosTheme { diff --git a/app/src/main/java/com/rodalc/amarracos/main/PantallaInicio.kt b/app/src/main/java/com/rodalc/amarracos/main/PantallaInicio.kt index c6f808b..dbe9ba2 100644 --- a/app/src/main/java/com/rodalc/amarracos/main/PantallaInicio.kt +++ b/app/src/main/java/com/rodalc/amarracos/main/PantallaInicio.kt @@ -21,6 +21,11 @@ import androidx.navigation.NavController import androidx.navigation.compose.rememberNavController import com.rodalc.amarracos.ui.theme.AmarracosTheme +/** + * Primera pantalla de la aplicación, contiene el menú para navegar por ella. + * + * @param navController El controlador usado para cambiar entre pantallas. + */ @Composable fun PantallaInicio(navController: NavController) { @@ -30,6 +35,7 @@ fun PantallaInicio(navController: NavController) { horizontalAlignment = Alignment.CenterHorizontally ) { Spacer(modifier = Modifier.weight(1f)) + Box( modifier = Modifier ) { @@ -37,7 +43,6 @@ fun PantallaInicio(navController: NavController) { text = "Amarracos", fontSize = 21.sp, textAlign = TextAlign.Center - ) } Spacer(modifier = Modifier.weight(1f)) @@ -77,7 +82,13 @@ fun PantallaInicio(navController: NavController) { } } -@Preview(showBackground = true, widthDp = 640, heightDp = 360) +/** + * Función auxiliar para Preview + */ +@Preview( + showBackground = true, + device = "id:pixel", backgroundColor = 0xFFFFFFFF +) @Composable fun InicioPreview() { val navController = rememberNavController() diff --git a/app/src/main/java/com/rodalc/amarracos/main/PantallaVacia.kt b/app/src/main/java/com/rodalc/amarracos/main/PantallaVacia.kt index 66ccd49..f88987b 100644 --- a/app/src/main/java/com/rodalc/amarracos/main/PantallaVacia.kt +++ b/app/src/main/java/com/rodalc/amarracos/main/PantallaVacia.kt @@ -5,6 +5,7 @@ import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.navigation.NavController +// PANTALLA AUXILIAR, VA A SER APISONADA @Composable fun PantallaVacia(navController: NavController) { Button(onClick = { navController.navigate("pantallaInicial") }) { diff --git a/app/src/main/java/com/rodalc/amarracos/mus/General.kt b/app/src/main/java/com/rodalc/amarracos/mus/General.kt index 3248e9e..45fc6cd 100644 --- a/app/src/main/java/com/rodalc/amarracos/mus/General.kt +++ b/app/src/main/java/com/rodalc/amarracos/mus/General.kt @@ -29,6 +29,13 @@ import androidx.compose.ui.unit.dp import androidx.compose.ui.unit.sp import androidx.compose.ui.window.Dialog +/** + * Muestra un recuadro con puntos. + * + * @param puntos Los puntos. + * @param pareja El nombre de la pareja. + * @param juegos Los juegos ganados por la pareja. + */ @Composable fun MarcadorPuntos(puntos: Int, pareja: String, juegos: Int) { Column { @@ -47,6 +54,13 @@ fun MarcadorPuntos(puntos: Int, pareja: String, juegos: Int) { } } +/** + * Mesaje a mostrar cuando una pareja alcanza el máximo de puntos. + * + * @param juego La partida. + * @param ronda La ronda. + * @param ganador El ganador de la partida. + */ @Composable fun Ganan( juego: MutableState, @@ -79,9 +93,15 @@ fun Ganan( } } } - } +/** + * Mensaje a mostrar durante un órdago visto. + * + * @param juego La partida. + * @param ronda La ronda. + * @param dialog Una lambda. + */ @Composable fun Ordago(juego: MutableState, ronda: MutableState, dialog: (Boolean) -> Unit) { Box(modifier = Modifier) { @@ -120,6 +140,12 @@ fun Ordago(juego: MutableState, ronda: MutableState, dialog: (Bo } } +/** + * Muestra la cuadrícula de envites. + * + * @param juego La partida. + * @param ronda La ronda actual (para resaltarla) + */ @Composable fun Envites(juego: MutableState, ronda: Ronda) { Column { @@ -139,6 +165,12 @@ fun Envites(juego: MutableState, ronda: Ronda) { } } +/** + * La caja de texto con el valor de los envites. + * + * @param value El valor del envite. + * @param focus Si está resaltada o no. + */ @Composable fun CajaEnvite(value: Int, focus: Boolean) { Box( @@ -154,6 +186,12 @@ fun CajaEnvite(value: Int, focus: Boolean) { } +/** + * Función para realizar el conteo de puntos tras la ronda. + * + * @param juego La partida. + * @param salir Una lambda para finalizar. + */ @Composable fun Conteo(juego: MutableState, salir: (Ronda) -> Unit) { var dialogPares by remember { mutableStateOf(false) } @@ -271,6 +309,12 @@ fun Conteo(juego: MutableState, salir: (Ronda) -> Unit) { } } +/** + * Funcionalidad específica para contar los puntos de pares. + * + * @param juego La partida. + * @param dialog Un lambda para salir. + */ @Composable fun PuntosPares(juego: MutableState, dialog: (Boolean) -> Unit) { var pares1: Pares by remember { mutableStateOf(Pares.NADA) } @@ -369,6 +413,12 @@ fun PuntosPares(juego: MutableState, dialog: (Boolean) -> Unit) { } } +/** + * Funcionalidad específica para contar los puntos de juego. + * + * @param juego La partida. + * @param dialog Un lambda para salir. + */ @Composable fun PuntosJuego(juego: MutableState, dialog: (Boolean) -> Unit) { var juego1: Juego by remember { mutableStateOf(Juego.NADA) } diff --git a/app/src/main/java/com/rodalc/amarracos/mus/PantallaMus.kt b/app/src/main/java/com/rodalc/amarracos/mus/PantallaMus.kt index fab33e4..b38dcce 100644 --- a/app/src/main/java/com/rodalc/amarracos/mus/PantallaMus.kt +++ b/app/src/main/java/com/rodalc/amarracos/mus/PantallaMus.kt @@ -20,7 +20,13 @@ import androidx.compose.ui.tooling.preview.Preview import androidx.compose.ui.unit.dp import androidx.compose.ui.window.Dialog -@Preview(showBackground = true, widthDp = 640, heightDp = 360) +/** + * Gestiona la pantalla del mus. + */ +@Preview( + showBackground = true, + device = "spec:parent=pixel,orientation=landscape", backgroundColor = 0xFFFFFFFF +) @Composable fun PantallaMus() { val juego = remember { mutableStateOf(Partida()) } @@ -124,6 +130,9 @@ fun PantallaMus() { } } +/** + * Se encarga de mostrar los botones de las distintas rondas. + */ @Composable fun BototesJuego( juego: MutableState, @@ -158,6 +167,9 @@ fun BototesJuego( } } +/** + * Muestra los botones del envite no visto. + */ @Composable fun BotonesEnviteNoVisto( juego: MutableState, @@ -175,6 +187,9 @@ fun BotonesEnviteNoVisto( } } +/** + * Gestiona los envites. + */ @Composable fun Envite( juego: MutableState, diff --git a/app/src/main/java/com/rodalc/amarracos/pocha/Jugador.kt b/app/src/main/java/com/rodalc/amarracos/pocha/Jugador.kt index 7a0b911..dbcc807 100644 --- a/app/src/main/java/com/rodalc/amarracos/pocha/Jugador.kt +++ b/app/src/main/java/com/rodalc/amarracos/pocha/Jugador.kt @@ -1,8 +1,22 @@ package com.rodalc.amarracos.pocha +import com.rodalc.amarracos.pocha.Ronda.APUESTAS +import com.rodalc.amarracos.pocha.Ronda.CONTEO +import com.rodalc.amarracos.pocha.Ronda.NOMBRES import kotlinx.serialization.Serializable +/** + * Representa un jugador de la pocha, con información relevante como ID, nombre, puntos, apuesta y victorias. + * + * @property id Identificador único del jugador. + * @property nombre Nombre del jugador. + * @property puntos Puntos acumulados por el jugador. + * @property apuesta Apuesta realizada por el jugador en la ronda actual. + * @property victoria Número de manos ganadas en la ronda actual. + * + * @see Ronda + */ @Serializable data class Jugador( val id: Int, @@ -13,6 +27,13 @@ data class Jugador( ) { } +/** + * Define las rondas del juego. + * + * @property NOMBRES Ronda donde los jugadores ingresan sus nombres. + * @property APUESTAS Ronda donde los jugadores realizan sus apuestas. + * @property CONTEO Ronda final donde se cuenta el resultado. + */ enum class Ronda { NOMBRES, APUESTAS, diff --git a/app/src/main/java/com/rodalc/amarracos/pocha/PantallaPocha.kt b/app/src/main/java/com/rodalc/amarracos/pocha/PantallaPocha.kt index 8e30cb5..0e8ae51 100644 --- a/app/src/main/java/com/rodalc/amarracos/pocha/PantallaPocha.kt +++ b/app/src/main/java/com/rodalc/amarracos/pocha/PantallaPocha.kt @@ -200,7 +200,7 @@ fun PantallaPocha() { if (state == Ronda.CONTEO) { state = Ronda.APUESTAS } else { - jugadores = undoStack.pop()!! + jugadores = undoStack.pop() ?: jugadores state = Ronda.CONTEO } diff --git a/app/src/main/java/com/rodalc/amarracos/pocha/Utils.kt b/app/src/main/java/com/rodalc/amarracos/pocha/Utils.kt index ec75cf9..73c12ef 100644 --- a/app/src/main/java/com/rodalc/amarracos/pocha/Utils.kt +++ b/app/src/main/java/com/rodalc/amarracos/pocha/Utils.kt @@ -3,9 +3,20 @@ package com.rodalc.amarracos.pocha import android.content.Context import android.widget.Toast +/** + * Un objeto que limita la frecuencia de mostrar toasts en la aplicación. + * + * Este objeto asegura que los toasts no se muestren con demasiada frecuencia, limitando la frecuencia a un toast por segundo. + */ object ToastRateLimiter { private var lastToastTime = 0L + /** + * Muestra un toast con un mensaje específico si ha pasado más de un segundo desde el último toast. + * + * @param context El contexto de la aplicación o actividad. + * @param message El mensaje a mostrar en el toast. + */ fun showToast(context: Context, message: String) { val currentTime = System.currentTimeMillis() if (currentTime - lastToastTime > 1000) { // Check if more than 1 second has passed diff --git a/app/src/main/java/com/rodalc/amarracos/storage/StateSaver.kt b/app/src/main/java/com/rodalc/amarracos/storage/StateSaver.kt index c96db48..6122776 100644 --- a/app/src/main/java/com/rodalc/amarracos/storage/StateSaver.kt +++ b/app/src/main/java/com/rodalc/amarracos/storage/StateSaver.kt @@ -7,18 +7,42 @@ import kotlinx.serialization.json.Json import java.io.FileNotFoundException import java.io.IOException +/** + * Un objeto que proporciona métodos para guardar y cargar el estado de un juego. + * + * Este objeto se encarga de manejar la persistencia de datos de los jugadores en un archivo JSON. + * De momento solo tiene un archivo, para la pocha. En el futuro se generalizará. + */ object StateSaver { private var filename = "pocha.json" + /** + * Verifica si el archivo de estado existe en el contexto dado. + * + * @param context El contexto de la aplicación o actividad. + * @return true si el archivo existe, false en caso contrario. + */ fun fileExist(context: Context): Boolean { val file = context.getFileStreamPath(filename) return file != null && file.exists() } + /** + * Elimina el archivo de estado en el contexto dado. + * + * @param context El contexto de la aplicación o actividad. + * @return true si el archivo se eliminó con éxito, false en caso contrario. + */ fun deleteFile(context: Context): Boolean { return context.deleteFile(filename) } + /** + * Guarda el estado de los jugadores en un archivo JSON. + * + * @param context El contexto de la aplicación o actividad. + * @param jugadores La lista de jugadores a guardar. + */ fun savePocha(context: Context, jugadores: List) { val json = Json.encodeToString(jugadores) context.openFileOutput(filename, Context.MODE_PRIVATE).use { @@ -26,6 +50,12 @@ object StateSaver { } } + /** + * Carga el estado de los jugadores desde un archivo JSON. + * + * @param context El contexto de la aplicación o actividad. + * @return La lista de jugadores cargados, o una lista vacía si el archivo no existe o hay un error al leerlo. + */ fun loadPocha(context: Context): List { var jugadores: List? = null diff --git a/app/src/main/java/com/rodalc/amarracos/storage/UndoStack.kt b/app/src/main/java/com/rodalc/amarracos/storage/UndoStack.kt index e7579c1..fa83684 100644 --- a/app/src/main/java/com/rodalc/amarracos/storage/UndoStack.kt +++ b/app/src/main/java/com/rodalc/amarracos/storage/UndoStack.kt @@ -1,8 +1,21 @@ package com.rodalc.amarracos.storage +/** + * Implementación de una pila con parámetros genéricos para la posibilidad de deshacer acciones. + * + * @param maxCapacity La capacidad máxima de la pila. Si es 0, la pila no tiene límite de tamaño. + * @property T El tipo de elementos que la pila puede contener. + */ class UndoStack public constructor(private val maxCapacity: Int = 0) { private var stack: MutableList = mutableListOf() + /** + * Agrega un elemento a la pila. + * + * Si la pila alcanza su capacidad máxima, se eliminará el primer elemento antes de agregar el nuevo. + * + * @param element El elemento a agregar a la pila. + */ fun push(element: T) { if (maxCapacity == 0 || stack.size < maxCapacity) { stack.add(element) @@ -12,11 +25,21 @@ class UndoStack public constructor(private val maxCapacity: Int = 0) { } } + /** + * Devuelve el tamaño actual de la pila. + * + * @return El número de elementos en la pila. + */ fun size(): Int { return stack.size } + /** + * Elimina y devuelve el último elemento de la pila. + * + * @return El último elemento de la pila, o null si la pila está vacía. + */ fun pop(): T? { return if (stack.isEmpty()) null else stack.removeLast() } -} \ No newline at end of file +}