Doc: Integrated the Rogue (state machine) example.

Reviewed-by: Kent Hansen

6 files changed, 465 insertions, 0 deletions

diff --git a/examples/statemachine/rogue/main.cpp b/examples/statemachine/rogue/main.cpp
new file mode 100644
index 0000000..0c2fb2d
--- /dev/null
+++ b/examples/statemachine/rogue/main.cpp
@@ -0,0 +1,55 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://www.qtsoftware.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtGui>
+
+#include "window.h"
+
+int main(int argv, char **args)
+{
+    QApplication app(argv, args);
+
+    Window window;
+    window.show();
+
+    return app.exec();
+}
+
diff --git a/examples/statemachine/rogue/movementtransition.h b/examples/statemachine/rogue/movementtransition.h
new file mode 100644
index 0000000..929077d
--- /dev/null
+++ b/examples/statemachine/rogue/movementtransition.h
@@ -0,0 +1,108 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://www.qtsoftware.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef MOVEMENTTRANSITION_H
+#define MOVEMENTTRANSITION_H
+
+#include <QtGui>
+
+#include "window.h"
+
+//![0]
+class MovementTransition : public QEventTransition
+{
+    Q_OBJECT
+
+public:
+    MovementTransition(Window *window) :
+        QEventTransition(window, QEvent::KeyPress) {
+        this->window = window;
+    }
+//![0]
+
+//![1]
+protected:
+    bool eventTest(QEvent *event) {
+        if (event->type() == QEvent::Wrapped &&
+            static_cast<QWrappedEvent *>(event)->event()->type() == QEvent::KeyPress) {
+            QEvent *wrappedEvent = static_cast<QWrappedEvent *>(event)->event();
+
+            QKeyEvent *keyEvent = static_cast<QKeyEvent *>(wrappedEvent);
+            int key = keyEvent->key();
+
+            return key == Qt::Key_2 || key == Qt::Key_8 || key == Qt::Key_6 ||
+                   key == Qt::Key_4;
+        }
+        return false;
+    }
+//![1]
+
+//![2]
+    void onTransition(QEvent *event) {
+        QKeyEvent *keyEvent = static_cast<QKeyEvent *>(
+            static_cast<QWrappedEvent *>(event)->event());
+
+        int key = keyEvent->key();
+        switch (key) {
+            case Qt::Key_4:
+                window->movePlayer(Window::Left);
+                break;
+            case Qt::Key_8:
+                window->movePlayer(Window::Up);
+                break;
+            case Qt::Key_6:
+                window->movePlayer(Window::Right);
+                break;
+            case Qt::Key_2:
+                window->movePlayer(Window::Down);
+                break;
+            default:
+                ;
+        }
+    }
+//![2]
+
+private:
+    Window *window;
+};
+
+#endif
+
diff --git a/examples/statemachine/rogue/rogue.pro b/examples/statemachine/rogue/rogue.pro
new file mode 100644
index 0000000..1571854
--- /dev/null
+++ b/examples/statemachine/rogue/rogue.pro
@@ -0,0 +1,11 @@
+HEADERS       = window.h \
+                movementtransition.h
+SOURCES       = main.cpp \
+                window.cpp
+
+# install
+target.path = $$[QT_INSTALL_EXAMPLES]/statemachine/rogue
+sources.files = $$SOURCES $$HEADERS *.pro
+sources.path = $$[QT_INSTALL_EXAMPLES]/statemachine/rogue
+INSTALLS += target sources
+
diff --git a/examples/statemachine/rogue/window.cpp b/examples/statemachine/rogue/window.cpp
new file mode 100644
index 0000000..39565a3
--- /dev/null
+++ b/examples/statemachine/rogue/window.cpp
@@ -0,0 +1,201 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://www.qtsoftware.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtGui>
+
+#include "window.h"
+#include "movementtransition.h"
+
+//![0]
+Window::Window()
+{
+    pX = 5;
+    pY = 5;
+//![0]
+
+    QFontDatabase database;
+    QFont font;
+    if (database.families().contains("Monospace"))
+        font = QFont("Monospace", 12);
+    else {
+        foreach (QString family, database.families()) {
+            if (database.isFixedPitch(family)) {
+                font = QFont(family, 12);
+                break;
+            }
+        }
+    }
+    setFont(font);
+
+//![1]
+    setupMap();
+    buildMachine();
+}
+//![1]
+
+void Window::setStatus(const QString &status)
+{
+    myStatus = status;
+    repaint();
+}
+
+QString Window::status() const
+{
+    return myStatus;
+}
+
+void Window::paintEvent(QPaintEvent * /* event */)
+{
+    QFontMetrics metrics(font());
+    QPainter painter(this);
+    int fontHeight = metrics.height();
+    int fontWidth = metrics.width('X');
+    int yPos = fontHeight;
+    int xPos;
+
+    painter.fillRect(rect(), Qt::black);
+    painter.setPen(Qt::white);
+
+    painter.drawText(QPoint(0, yPos), status());
+    
+    for (int y = 0; y < HEIGHT; ++y) {
+        yPos += fontHeight;
+        xPos = 0;
+
+        for (int x = 0; x < WIDTH; ++x) {
+            if (y == pY && x == pX) {
+                xPos += fontWidth;
+                continue;
+            }
+
+            painter.drawText(QPoint(xPos, yPos), map[x][y]);
+            xPos += fontWidth;
+        }
+    }
+    painter.drawText(QPoint(pX * fontWidth, (pY + 2) * fontHeight), QChar('@'));
+}
+
+QSize Window::sizeHint() const
+{
+    QFontMetrics metrics(font());
+
+    return QSize(metrics.width('X') * WIDTH, metrics.height() * (HEIGHT + 1));
+}
+
+//![2]
+void Window::buildMachine()
+{
+    machine = new QStateMachine;
+
+    QState *inputState = new QState(machine);
+    inputState->assignProperty(this, "status", "Move the rogue with 2, 4, 6, and 8");
+
+    MovementTransition *transition = new MovementTransition(this);
+    inputState->addTransition(transition);
+//![2]
+
+//![3]
+    QState *quitState = new QState(machine);
+    quitState->assignProperty(this, "status", "Really quit(y/n)?"); 
+
+    QKeyEventTransition *yesTransition = new
+        QKeyEventTransition(this, QEvent::KeyPress, Qt::Key_Y);
+    yesTransition->setTargetState(new QFinalState(machine));
+    quitState->addTransition(yesTransition);
+
+    QKeyEventTransition *noTransition =
+        new QKeyEventTransition(this, QEvent::KeyPress, Qt::Key_N);
+    noTransition->setTargetState(inputState);
+    quitState->addTransition(noTransition);
+//![3]
+
+//![4]
+    QKeyEventTransition *quitTransition =
+        new QKeyEventTransition(this, QEvent::KeyPress, Qt::Key_Q);
+    quitTransition->setTargetState(quitState);
+    inputState->addTransition(quitTransition);
+//![4]
+
+//![5]
+    machine->setInitialState(inputState);
+
+    connect(machine, SIGNAL(finished()), qApp, SLOT(quit()));
+
+    machine->start();
+}
+//![5]
+
+void Window::movePlayer(Direction direction)
+{
+    switch (direction) {
+        case Left:
+            if (map[pX - 1][pY] != '#')
+                --pX;            
+            break;
+        case Right:
+            if (map[pX + 1][pY] != '#')
+                ++pX;
+            break;
+        case Up:
+            if (map[pX][pY - 1] != '#')
+                --pY;
+            break;
+        case Down:
+            if (map[pX][pY + 1] != '#')
+                ++pY;
+            break;        
+    }
+    repaint();
+}
+
+void Window::setupMap()
+{
+    qsrand(QTime(0,0,0).secsTo(QTime::currentTime()));
+
+    for (int x = 0; x < WIDTH; ++x)
+        for (int y = 0; y < HEIGHT; ++y) {
+        if (x == 0 || x == WIDTH - 1 || y == 0 || y == HEIGHT - 1 || qrand() % 40 == 0)
+            map[x][y] = '#';
+        else
+            map[x][y] = '.';
+    }
+}
+
diff --git a/examples/statemachine/rogue/window.h b/examples/statemachine/rogue/window.h
new file mode 100644
index 0000000..bcd86bd
--- /dev/null
+++ b/examples/statemachine/rogue/window.h
@@ -0,0 +1,89 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://www.qtsoftware.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef WINDOW_H
+#define WINDOW_H
+
+#include <QWidget>
+
+class QState;
+class QStateMachine;
+class QTransition;
+
+#define WIDTH 35
+#define HEIGHT 20
+
+//![0]
+class Window : public QWidget
+{
+    Q_OBJECT
+    Q_PROPERTY(QString status READ status WRITE setStatus)
+
+public:
+    enum Direction { Up, Down, Left, Right };
+
+    Window();
+
+    void movePlayer(Direction direction);
+    void setStatus(const QString &status);
+    QString status() const;
+
+    QSize sizeHint() const;
+
+protected:
+    void paintEvent(QPaintEvent *event);
+//![0]
+
+//![1]
+private:
+    void buildMachine();
+    void setupMap();
+
+    QChar map[WIDTH][HEIGHT];
+    int pX, pY;
+
+    QStateMachine *machine;
+    QString myStatus;
+};
+//![1]
+
+#endif
+
diff --git a/examples/statemachine/statemachine.pro b/examples/statemachine/statemachine.pro
index ea3e7a8..298c0ae 100644
--- a/examples/statemachine/statemachine.pro
+++ b/examples/statemachine/statemachine.pro
@@ -3,6 +3,7 @@ SUBDIRS       = \
                 eventtransitions \
                 factorial \
                 pingpong \
+                rogue \
                 trafficlight \
                 twowaybutton