Merge pull request #445 from GriffinRichards/api-windows

Add message boxes and user input windows to API

CHANGELOG.md

@@ -14,6 +14,7 @@ The **"Breaking Changes"** listed below are changes that have been made in the d
 - Add Copy/Paste for metatiles in the Tileset Editor.
 - Add ability to set the opacity of the scripting overlay.
 - Add ability to get/set map header properties and read tile pixel data via the API.
+- Add ability to display message boxes and user input windows via the API.
 - Add button to copy the full metatile label to the clipboard in the Tileset Editor.
 - Add option to not open the most recent project on launch.
 - Add color picker to palette editor for taking colors from the screen.

docsrc/manual/scripting-capabilities.rst

@@ -1229,9 +1229,74 @@ These are some miscellaneous functions that can be very useful when building cus
 
    :param string message: the message to log
 
-
 .. js:function:: map.error(message)
 
    Logs a message to the Porymap log file with the prefix ``[ERROR]``.
 
    :param string message: the message to log
+
+.. js:function:: map.showMessage(text, informativeText, detailedText)
+
+   Displays a message box with an "Information" icon and an ``OK`` button. Execution stops while the window is open.
+
+   :param string text: the main message text
+   :param string informativeText: smaller text below the main message. Defaults to ``""``
+   :param string detailedText: text hidden behind a "Show Details" box. Defaults to ``""``
+
+.. js:function:: map.showWarning(text, informativeText, detailedText)
+
+   Displays a message box with a "Warning" icon and an ``OK`` button. Execution stops while the window is open.
+
+   :param string text: the main message text
+   :param string informativeText: smaller text below the main message. Defaults to ``""``
+   :param string detailedText: text hidden behind a "Show Details" box. Defaults to ``""``
+
+.. js:function:: map.showError(text, informativeText, detailedText)
+
+   Displays a message box with a "Critical" icon and an ``OK`` button. Execution stops while the window is open.
+
+   :param string text: the main message text
+   :param string informativeText: smaller text below the main message. Defaults to ``""``
+   :param string detailedText: text hidden behind a "Show Details" box. Defaults to ``""``
+
+.. js:function:: map.showQuestion(text, informativeText, detailedText)
+
+   Displays a message box with a "Question" icon and a ``Yes`` and a ``No`` button. Execution stops while the window is open.
+
+   :param string text: the main message text
+   :param string informativeText: smaller text below the main message. Defaults to ``""``
+   :param string detailedText: text hidden behind a "Show Details" box. Defaults to ``""``
+   :returns boolean: ``true`` if ``Yes`` was selected, ``false`` if ``No`` was selected or if the window was closed without selection
+
+.. js:function:: map.getInputText(title, label, default)
+
+   Displays a text input dialog with an ``OK`` and a ``Cancel`` button. Execution stops while the window is open.
+
+   :param string title: the text in the window title bar
+   :param string label: the text adjacent to the input entry area
+   :param string default: the text in the input entry area when the window is opened. Defaults to ``""``
+   :returns {input, ok}: ``input`` will be the input text and ``ok`` will be ``true`` if ``OK`` was selected. ``input`` will be ``""`` and ``ok`` will be ``false`` if ``Cancel`` was selected or if the window was closed without selection.
+
+.. js:function:: map.getInputNumber(title, label, default, min, max, decimals, step)
+
+   Displays a number input dialog with an ``OK`` and a ``Cancel`` button. Execution stops while the window is open.
+
+   :param string title: the text in the window title bar
+   :param string label: the text adjacent to the input entry area
+   :param number default: the number in the input entry area when the window is opened. Defaults to ``0``
+   :param number min: the minimum allowable input value. Defaults to ``-2147483648``
+   :param number max: the maximum allowable input value. Defaults to ``2147483647``
+   :param number decimals: the number of decimals used for the input number. Defaults to ``0``
+   :param number step: the increment by which the input number will change when the spinner is used. Defaults to ``1``
+   :returns {input, ok}: ``input`` will be the input number and ``ok`` will be ``true`` if ``OK`` was selected. ``input`` will be ``default`` and ``ok`` will be ``false`` if ``Cancel`` was selected or if the window was closed without selection.
+
+.. js:function:: map.getInputItem(title, label, items, default, editable)
+
+   Displays a text input dialog with an items dropdown and an ``OK`` and a ``Cancel`` button. Execution stops while the window is open.
+
+   :param string title: the text in the window title bar
+   :param string label: the text adjacent to the input entry area
+   :param array items: an array of text items that will populate the dropdown
+   :param number default: the index of the item to select by default. Defaults to ``0``
+   :param boolean editable: whether the user is allowed to enter their own text instead. Defaults to ``false``
+   :returns {input, ok}: ``input`` will be the input text and ``ok`` will be ``true`` if ``OK`` was selected. ``input`` will be the text of the item at ``default`` and ``ok`` will be ``false`` if ``Cancel`` was selected or if the window was closed without selection.

include/mainwindow.h

@@ -149,6 +149,14 @@ public:
     Q_INVOKABLE void log(QString message);
     Q_INVOKABLE void warn(QString message);
     Q_INVOKABLE void error(QString message);
+    void runMessageBox(QString text, QString informativeText, QString detailedText, QMessageBox::Icon icon);
+    Q_INVOKABLE void showMessage(QString text, QString informativeText = "", QString detailedText = "");
+    Q_INVOKABLE void showWarning(QString text, QString informativeText = "", QString detailedText = "");
+    Q_INVOKABLE void showError(QString text, QString informativeText = "", QString detailedText = "");
+    Q_INVOKABLE bool showQuestion(QString text, QString informativeText = "", QString detailedText = "");
+    Q_INVOKABLE QJSValue getInputText(QString title, QString label, QString defaultValue = "");
+    Q_INVOKABLE QJSValue getInputNumber(QString title, QString label, double defaultValue = 0, double min = INT_MIN, double max = INT_MAX, int decimals = 0, double step = 1);
+    Q_INVOKABLE QJSValue getInputItem(QString title, QString label, QStringList items, int defaultValue = 0, bool editable = false);
     Q_INVOKABLE QList<int> getMetatileLayerOrder();
     Q_INVOKABLE void setMetatileLayerOrder(QList<int> order);
     Q_INVOKABLE QList<float> getMetatileLayerOpacity();

include/scripting.h

@@ -33,6 +33,7 @@ public:
     static QJSValue position(int x, int y);
     static QJSEngine *getEngine();
     static QImage getImage(QString filepath);
+    static QJSValue dialogInput(QJSValue input, bool selectedOk);
     static void init(MainWindow *mainWindow);
     static void registerAction(QString functionName, QString actionName);
     static int numRegisteredActions();

src/mainwindow_scriptapi.cpp

@@ -785,6 +785,55 @@ void MainWindow::error(QString message) {
     logError(message);
 }
 
+void MainWindow::runMessageBox(QString text, QString informativeText, QString detailedText, QMessageBox::Icon icon) {
+    QMessageBox messageBox(this);
+    messageBox.setText(text);
+    messageBox.setInformativeText(informativeText);
+    messageBox.setDetailedText(detailedText);
+    messageBox.setIcon(icon);
+    messageBox.exec();
+}
+
+void MainWindow::showMessage(QString text, QString informativeText, QString detailedText) {
+    this->runMessageBox(text, informativeText, detailedText, QMessageBox::Information);
+}
+
+void MainWindow::showWarning(QString text, QString informativeText, QString detailedText) {
+    this->runMessageBox(text, informativeText, detailedText, QMessageBox::Warning);
+}
+
+void MainWindow::showError(QString text, QString informativeText, QString detailedText) {
+    this->runMessageBox(text, informativeText, detailedText, QMessageBox::Critical);
+}
+
+bool MainWindow::showQuestion(QString text, QString informativeText, QString detailedText) {
+    QMessageBox messageBox(this);
+    messageBox.setText(text);
+    messageBox.setInformativeText(informativeText);
+    messageBox.setDetailedText(detailedText);
+    messageBox.setIcon(QMessageBox::Question);
+    messageBox.setStandardButtons(QMessageBox::Yes | QMessageBox::No);
+    return messageBox.exec() == QMessageBox::Yes;
+}
+
+QJSValue MainWindow::getInputText(QString title, QString label, QString defaultValue) {
+    bool ok;
+    QString input = QInputDialog::getText(this, title, label, QLineEdit::Normal, defaultValue, &ok);
+    return Scripting::dialogInput(input, ok);
+}
+
+QJSValue MainWindow::getInputNumber(QString title, QString label, double defaultValue, double min, double max, int decimals, double step) {
+    bool ok;
+    double input = QInputDialog::getDouble(this, title, label, defaultValue, min, max, decimals, &ok, Qt::WindowFlags(), step);
+    return Scripting::dialogInput(input, ok);
+}
+
+QJSValue MainWindow::getInputItem(QString title, QString label, QStringList items, int defaultValue, bool editable) {
+    bool ok;
+    QString input = QInputDialog::getItem(this, title, label, items, defaultValue, editable, &ok);
+    return Scripting::dialogInput(input, ok);
+}
+
 QList<int> MainWindow::getMetatileLayerOrder() {
     if (!this->editor || !this->editor->map)
         return QList<int>();

src/scripting.cpp

@@ -262,6 +262,13 @@ QJSValue Scripting::fromTile(Tile tile) {
     return obj;
 }
 
+QJSValue Scripting::dialogInput(QJSValue input, bool selectedOk) {
+    QJSValue obj = instance->engine->newObject();
+    obj.setProperty("input", input);
+    obj.setProperty("ok", selectedOk);
+    return obj;
+}
+
 QJSEngine *Scripting::getEngine() {
     return instance->engine;
 }