En esta página

Sudoku SCXML

Muestra cómo utilizar un archivo JavaScript independiente con SCXML.

Ejecución del ejemplo

Puedes ejecutar el ejemplo desde:

Funcionalidades del Sudoku

Captura de pantalla del ejemplo de Sudoku

Nuestro sudoku incluye las siguientes características:

  • Al inicio y al finalizar la partida, el sudoku entra en el estado « idle ». En ese estado, los jugadores pueden ver si su última partida ha finalizado con éxito o no. A continuación, la máquina de estados se encuentra en uno de los dos estados secundarios del estado « idle »: « solved » o « unsolved », respectivamente. En el estado « idle », los jugadores también pueden elegir la cuadrícula de sudoku que desean resolver. La cuadrícula está desactivada y se ignora la interacción del usuario.
  • Cuando los jugadores hacen clic en el botón « Start », el sudoku pasa al estado « playing » y queda listo para la interacción del usuario en el tablero.
  • Cuando el juego se encuentra en el estado « playing » y los jugadores hacen clic en el botón « Stop », el juego finaliza y pasa al estado secundario « unsolved » del estado « idle ». Si los jugadores han resuelto correctamente el rompecabezas actual, el juego finaliza automáticamente y pasa al estado secundario « solved » del estado « idle », lo que indica que se ha completado con éxito.
  • El tablero consta de 81 botones, dispuestos en una cuadrícula de 9x9. Los botones con valores iniciales asignados permanecen desactivados durante el juego. Los jugadores solo pueden interactuar con los botones que inicialmente están vacíos. Cada clic en un botón aumenta su valor en uno.
  • Durante la partida, el botón « Undo » está disponible para facilitar la tarea a los jugadores.

Parte SCXML: Descripción de la lógica interna

El archivo sudoku.scxml describe la estructura interna de los estados en los que puede encontrarse el juego de sudoku, define las transiciones entre estados y activa las funciones de script adecuadas cuando se producen dichas transiciones. Además, se comunica con la parte de la interfaz gráfica de usuario (GUI) enviando eventos, escuchando los eventos que se avecinan y reaccionando ante ellos.

Utilizamos el modelo de datos de ECMAScript:

<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
       name="Sudoku" datamodel="ecmascript">

Declaramos las siguientes variables:

    <datamodel>
        <data id="initState"/>
        <data id="currentState" expr="[[]]"/>
        <data id="undoStack"/>
    </datamodel>
VariableDescripción
initStateAlmacena el estado inicial de la partida actual. Es una matriz bidimensional de 9x9 casillas que contienen los números iniciales del sudoku. El valor cero significa que la casilla está vacía inicialmente.
currentStateAlmacena el estado actual de la partida en curso. Es similar a la variable « initState » y, inicialmente, contiene el mismo contenido. Sin embargo, cuando los jugadores empiezan a introducir los números en las casillas vacías, esta variable se actualiza en consecuencia, mientras que la variable « initState » permanece sin cambios.
undoStackAlmacena el historial de los movimientos de los jugadores. Es una lista de las coordenadas de las casillas en las que se ha pulsado por última vez. Cada nueva modificación durante una partida añade un par de coordenadas x e y a esa lista.

Las variables anteriores se comparten con las funciones auxiliares de script definidas en el archivo sudoku.js:

    <script src="sudoku.js"/>

Llamamos a algunas de las funciones definidas allí al realizar transiciones o en respuesta a los eventos enviados por la interfaz gráfica de usuario.

Todos los estados posibles mencionados anteriormente se definen en un estado raíz game.

    <state id="game">
        <onentry>
            <raise event="restart"/>
        </onentry>
        <state id="idle">
            ...
            <state id="unsolved"/>
            <state id="solved"/>
        </state>
        <state id="playing">
            ...
        </state>
        ...
    </state>

Cuando se inicia el ejemplo del sudoku, la máquina de estados entra en el estado « game » y permanece en él hasta que la aplicación se cierra. Al entrar en este estado, generamos internamente el evento « restart ». Este evento también se genera cada vez que los jugadores modifican la cuadrícula actual del sudoku o cuando inician la partida pulsando el botón « Start ». No queremos enviarlo cuando hayan terminado la partida actual, ya que queremos seguir mostrando la cuadrícula completada de la última partida. Por lo tanto, este evento se genera desde tres contextos diferentes y se captura internamente una vez en una transición sin destino del estado « game »:

        <transition event="restart">
            <script>
                restart();
            </script>
            <raise event="update"/>
        </transition>

Cuando capturamos el evento « restart », llamamos a un método auxiliar del script « restart() », definido en el archivo « sudoku.js », y generamos internamente un evento adicional « update ».

function restart() {
    for (var i = 0; i < initState.length; i++)
        currentState[i] = initState[i].slice();
    undoStack = [];
}

La función restart() asigna el objeto initState a la variable currentState y borra el contenido de la variable undoStack.

El evento « update » se activa internamente cada vez que queremos notificar a la interfaz gráfica de usuario que el contenido de la cuadrícula ha cambiado y que debe actualizarse según los valores pasados. Este evento se captura en otra transición sin destino del estado « game »:

        <transition event="update">
            <send event="updateGUI">
                <param name="currentState" expr="currentState"/>
                <param name="initState" expr="initState"/>
            </send>
        </transition>

Enviamos el evento externo updateGUI, que se intercepta en el código C++. El evento updateGUI va acompañado de datos adicionales, especificados dentro de los elementos <param>. Pasamos dos parámetros, a los que se puede acceder externamente a través de los nombres currentState y initState. Los valores reales que se pasan para ellos equivalen a las variables currentState y initState del modelo de datos, respectivamente, que se especifican mediante los atributos expr.

        <state id="idle">
            <transition event="start" target="playing"/>
            <transition event="setup" target="unsolved">
                <assign location="initState" expr="_event.data.initState"/>
                <raise event="restart"/>
            </transition>
            <state id="unsolved"/>
            <state id="solved"/>
        </state>

Cuando nos encontramos en el estado « idle », reaccionamos ante dos eventos que puede enviar la parte de la interfaz gráfica de usuario (GUI): « start » y « setup ». Cada vez que recibimos el evento « start », simplemente pasamos al estado « playing ». Cuando recibimos el evento « setup », esperamos que la parte de la GUI nos haya enviado la nueva cuadrícula que hay que resolver. Se espera que el nuevo estado inicial de la cuadrícula se transmita a través del campo « initState » de _event.data. Asignamos el valor transmitido a la variable « initState » definida en nuestro modelo de datos y reiniciamos el contenido de la cuadrícula.

        <state id="playing">
            <onentry>
                <raise event="restart"/>
            </onentry>
            <transition event="tap">
                <if cond="isValidPosition()">
                    <script>
                        calculateCurrentState();
                    </script>
                    <if cond="isSolved()">
                        <raise event="solved"/>
                    </if>
                    <raise event="update"/>
                </if>
            </transition>
            ...
        </state>

Cada vez que entramos en el estado « playing », restablecemos el contenido de la cuadrícula, ya que podríamos seguir mostrando el contenido de la partida anterior. En el estado « playing », reaccionamos ante posibles eventos enviados desde la interfaz gráfica de usuario: tap, undo y stop.

El evento tap se envía cuando los jugadores pulsan una de las casillas de sudoku habilitadas. Se espera que este evento contenga datos adicionales que especifiquen las coordenadas de la casilla, las cuales se pasan a través de los campos x y y de _event.data. En primer lugar, comprobamos si las coordenadas pasadas son válidas invocando la función de script isValidPosition():

function isValidPosition() {
    var x = _event.data.x;
    var y = _event.data.y;
    if (x < 0 || x >= initState.length)
        return false;
    if (y < 0 || y >= initState.length)
        return false;
    if (initState[x][y] !== 0)
        return false;
    return true;
}

Nos aseguramos de que las coordenadas no sean negativas ni superen los límites de nuestra cuadrícula. Además, comprobamos si las coordenadas apuntan a una celda inicialmente vacía, ya que no podemos modificar las celdas proporcionadas inicialmente por la descripción de la cuadrícula.

Una vez que nos hemos asegurado de que las coordenadas pasadas son correctas, llamamos a la función de script calculateCurrentState():

function calculateCurrentState() {
    if (isValidPosition() === false)
        return;
    var x = _event.data.x;
    var y = _event.data.y;
    var currentValue = currentState[x][y];
    if (currentValue === initState.length)
        currentValue = 0;
    else
        currentValue += 1;
    currentState[x][y] = currentValue;
    undoStack.push([x, y]);
}

Esta función incrementa el valor de la celda de la cuadrícula pasada y añade el nuevo movimiento al historial de la pila de deshacer.

Justo después de que la función ` calculateCurrentState() ` termine su ejecución, comprobamos si la cuadrícula ya está resuelta llamando a la función de script ` isSolved() `:

function isOK(numbers) {
    var temp = [];
    for (var i = 0; i < numbers.length; i++) {
        var currentValue = numbers[i];
        if (currentValue === 0)
            return false;
        if (temp.indexOf(currentValue) >= 0)
            return false;
        temp.push(currentValue);
    }
    return true;
}

function isSolved() {
    for (var i = 0; i < currentState.length; i++) {
        if (!isOK(currentState[i]))
            return false;

        var column = [];
        var square = [];
        for (var j = 0; j < currentState[i].length; j++) {
            column.push(currentState[j][i]);
            square.push(currentState[Math.floor(i / 3) * 3 + Math.floor(j / 3)]
                                    [i % 3 * 3 + j % 3]);
        }

        if (!isOK(column))
            return false;
        if (!isOK(square))
            return false;
    }
    return true;
}

La función ` isSolved() ` devuelve ` true ` si el tablero está correctamente resuelto. Dado que necesitamos comprobar cada fila, cada columna y cada cuadrado de 3x3, definimos la función auxiliar ` isOK() `. Esta función toma la lista de números y devuelve ` true ` si la lista pasada contiene números únicos y ningún número es igual a cero, lo que significa que no hay ninguna celda vacía. El bucle principal de isSolved() se ejecuta nueve veces. En cada iteración, construimos tres listas de números que representan una fila, una columna y un cuadrado de la cuadrícula, y llamamos a isOK() para cada una de ellas. Cuando las 27 listas están en orden, la cuadrícula está resuelta correctamente y devolvemos true.

Volviendo a nuestro archivo SCXML, en caso de que isSolved() devuelva true, generamos internamente el evento solved. La última instrucción, en caso de que el movimiento sea correcto, es generar el evento update, ya que debemos notificar a la interfaz gráfica de usuario el cambio en la cuadrícula.

        <state id="playing">
            ...
            <transition event="undo">
                <script>
                    undo();
                </script>
                <raise event="update"/>
            </transition>
            <transition event="stop" target="idle"/>
            <transition event="solved" target="solved"/>
        </state>

Cuando nos encontramos en el estado « playing », también reaccionamos al evento « undo » enviado desde la interfaz gráfica de usuario. En este caso, llamamos a la función de script « undo() » y notificamos a la interfaz gráfica de usuario la necesidad de una actualización.

function undo() {
    if (!undoStack.length)
        return;

    var lastMove = undoStack.pop();
    var x = lastMove[0];
    var y = lastMove[1];
    var currentValue = currentState[x][y];
    if (currentValue === 0)
        currentValue = initState.length;
    else
        currentValue -= 1;
    currentState[x][y] = currentValue;
}

La función undo() elimina el último movimiento del historial, si lo hubiera, y reduce en uno el valor actual de la celda descrita por las coordenadas tomadas de dicho movimiento.

El estado « playing » también está preparado para el evento « stop » enviado por la interfaz gráfica de usuario cuando los jugadores pulsan el botón « Stop ». En este caso, simplemente activamos el estado « idle ».

Además, interceptamos el evento « solved » enviado internamente y, en este caso, activamos el estado « solved ».

Parte en C++: Creación de la interfaz gráfica de usuario

La parte en C++ de la aplicación consiste en una clase ` MainWindow ` que construye la interfaz gráfica de usuario y la integra con la parte SCXML. La clase se declara en `mainwindow.h`.

class MainWindow : public QWidget
{
    Q_OBJECT

public:
    explicit MainWindow(QScxmlStateMachine *machine, QWidget *parent = nullptr);

private:
    QScxmlStateMachine *m_machine = nullptr;
    QList<QList<QToolButton *>> m_buttons;
    QToolButton *m_startButton = nullptr;
    QToolButton *m_undoButton = nullptr;
    QLabel *m_label = nullptr;
    QComboBox *m_chooser = nullptr;
};

La clase ` MainWindow ` contiene el puntero a ` QScxmlStateMachine *m_machine`, que es la clase de máquina de estados generada automáticamente por Qt a partir del archivo ` sudoku.scxml `. También contiene los punteros a algunos elementos de la interfaz gráfica de usuario.

MainWindow::MainWindow(QScxmlStateMachine *machine, QWidget *parent) :
    QWidget(parent),
    m_machine(machine)
{

El constructor de la clase MainWindow crea una instancia de la parte de interfaz gráfica de usuario de la aplicación y almacena el puntero a la máquina de estados pasada. Además, inicializa la parte de interfaz gráfica de usuario y la vincula a la máquina de estados conectando entre sí sus interfaces de comunicación.

            connect(button, &QToolButton::clicked, this, [this, i, j]() {
                QVariantMap data;
                data.insert(u"x"_s, i);
                data.insert(u"y"_s, j);
                m_machine->submitEvent("tap", data);
            });

En primer lugar, creamos 81 botones y conectamos su señal « clicked » a una expresión lambda que envía el evento « tap » a la máquina de estados, pasando las coordenadas del botón.

Posteriormente, añadimos algunas líneas horizontales y verticales a la cuadrícula para agrupar los botones en recuadros de 3x3.

    connect(m_startButton, &QAbstractButton::clicked, this, [this]() {
        if (m_machine->isActive("playing"))
            m_machine->submitEvent("stop");
        else
            m_machine->submitEvent("start");
    });

Creamos el botón « Start / Stop » y conectamos su señal «clicked» a una expresión lambda que envía el evento « stop » o « start », dependiendo de si la máquina se encuentra en el estado « playing » o no, respectivamente.

Creamos una etiqueta que indica si el tablero está resuelto o no, y un botón « Undo », que envía el evento « undo » cada vez que se pulsa.

    connect(m_undoButton, &QAbstractButton::clicked, this, [this]() {
        m_machine->submitEvent("undo");
    });

A continuación, creamos un cuadro combinado que se rellena con los nombres de las cuadrículas que hay que resolver. Estas cuadrículas se leen del directorio :/data de los recursos compilados de la aplicación.

    connect(m_chooser, &QComboBox::currentIndexChanged, this, [this](int index) {
        const QString sudokuFile = m_chooser->itemData(index).toString();
        const QVariantMap initValues = readSudoku(sudokuFile);
        m_machine->submitEvent("setup", initValues);
    });

    const QVariantMap initValues = readSudoku(
                m_chooser->itemData(0).toString());
    m_machine->setInitialValues(initValues);

Cada vez que los jugadores cambian la cuadrícula en el cuadro combinado, leemos el contenido de la cuadrícula y lo almacenamos en el mapa de variantes bajo la clave « initValues » como una lista de listas de variantes de tipo int, y enviamos el evento « setup » a la máquina de estados pasando el contenido de la cuadrícula. Inicialmente, leemos la primera cuadrícula disponible de la lista y la pasamos directamente a la máquina de estados de sudoku como cuadrícula inicial.

    m_machine->connectToState("playing", [this] (bool playing) {
        ...
    });

    m_machine->connectToState("solved", [this](bool solved) {
        if (solved)
            m_label->setText(tr("SOLVED !!!"));
        else
            m_label->setText(tr("unsolved"));
    });

    m_machine->connectToEvent("updateGUI", [this](const QScxmlEvent &event) {
        ...
    });

Posteriormente, nos conectamos a las señales que se envían cada vez que la máquina entra o sale de los estados « playing » o « solved », y actualizamos algunas partes de la interfaz gráfica de usuario en consecuencia. También nos conectamos al evento « updateGUI » de la máquina de estados y actualizamos los valores de todos los botones según los estados de las casillas pasadas.

#include "mainwindow.h"
#include "sudoku.h"

#include <QtWidgets/qapplication.h>

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    Sudoku machine;
    MainWindow mainWindow(&machine);

    machine.start();
    mainWindow.show();
    return app.exec();
}

En la función « main() » del archivo « main.cpp », instanciamos el objeto de aplicación « app », la máquina de estados « Sudoku » y la clase de interfaz gráfica de usuario « MainWindow ». Iniciamos la máquina de estados, mostramos la ventana principal y ejecutamos la aplicación.

Proyecto de ejemplo en code.qt.io

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.