Merge pull request #818 from MihailRis/document-new-dialog-windows

Document new dialog windows

doc/en/scripting/builtins/libgui.md

@@ -9,25 +9,19 @@ print(document.some_button.text) -- where 'some_button' is an element id
 document.some_button.text = "new text"
 ```
 
-```python
+```lua
+-- Returns translated text.
 gui.str(text: str, context: str) -> str
-```
 
-Returns translated text.
+-- Returns size of the main container (window).
-
-```python
 gui.get_viewport() -> {int, int}
-```
 
-Returns size of the main container (window).
+-- Returns environment (global variables table) of the specified document.
-
-```python
 gui.get_env(document: str) -> table
 ```
 
-Returns environment (global variables table) of the specified document.
-
 ```lua
+-- Returns information about all loaded locales (res/texts/*).
 gui.get_locales_info() -> table of tables {
   name: str
  }
@@ -38,8 +32,6 @@ gui.get_locales_info() -> table of tables {
 --   }
 ```
 
-Returns information about all loaded locales (res/texts/\*).
-
 ## Frames
 
 ```lua
@@ -71,18 +63,18 @@ gui.set_active_frame(
 )
 ```
 
+## Markup
+
 ```lua
+-- Removes markup from text.
 gui.clear_markup(
     -- markup language ("md" - Markdown)
     language: str,
     -- text with markup
     text: str
 ) -> str
-```
 
-Removes markup from text.
+-- Escapes markup in text.
-
-```lua
 gui.escape_markup(
     -- markup language ("md" - Markdown)
     language: str,
@@ -91,20 +83,44 @@ gui.escape_markup(
 ) -> str
 ```
 
-Escapes markup in text.
+
+## Dialog windows
 
 ```lua
+-- Displays a message box. Doesn't stop code execution.
+gui.show_message(
+    message: string -- message (not automatically translated, use gui.str(...))
+    on_ok: function() -> nil -- called when closing
+)
+
+-- Asks for confirmation of the action. Doesn't stop code execution.
+gui.ask(
+    -- message (not automatically translated, use gui.str(...))
+    message: string,
+    -- function called on confirmation
+    on_confirm: function() -> nil,
+    -- function called on rejection/cancellation
+    [optional] on_deny: function() -> nil,
+    -- confirm button text (default: "Yes")
+    -- use an empty string for the default value if you want to specify no_text.
+    [optional] yes_text: string
+    -- reject button text (default: "No")
+    [optional] no_text: string
+)
+```
+
+## Dialog menu pages (legacy)
+
+```lua
+-- Displays a message box. Non-blocking.
 gui.alert(
     -- message (not automatically translated, use gui.str(...))
     message: str,
     -- function called on close
     on_ok: function() -> nil
 )
-```
 
-Displays a message box. **Non-blocking**.
+-- Requests confirmation from the user for an action. Non-blocking.
-
-```lua
 gui.confirm(
     -- message (does not translate automatically, use gui.str(...))
     message: str,
@@ -120,9 +136,10 @@ gui.confirm(
 )
 ```
 
-Requests confirmation from the user for an action. **Non-blocking**.
+## Documents and templates
 
 ```lua
+-- Loads a UI document with its script, returns the name of the document if successfully loaded.
 gui.load_document(
     -- Path to the xml file of the page. Example: `core:layouts/pages/main.xml`
     path: str,
@@ -130,13 +147,24 @@ gui.load_document(
     name: str
     -- Table of parameters passed to the on_open event
     args: table
-) --> str
+) -> str
+
+-- Loads a template into the layout
+gui.template(
+    -- template name in /layouts/templates without path and extension
+    name: str,
+    -- variable table (can be used in markup)
+    -- * Ex: <label>%{text}</label>
+    -- * text in this case is the value from params with the text key
+    params: table,
+    -- table, available in events as the global variable DATA
+    [optional] data: table
+) -> str
 ```
 
-Loads a UI document with its script, returns the name of the document if successfully loaded.
+## Root document
 
 ```lua
+-- Root UI document
 gui.root: Document
 ```
-
-Root UI document

doc/ru/scripting/builtins/libgui.md

@@ -91,12 +91,37 @@ gui.escape_markup(
 
 ```lua
 -- Выводит окно с сообщением. Не останавливает выполнение кода.
+gui.show_message(
+    message: string                 -- сообщение (не переводится автоматически, используйте gui.str(...))
+    on_ok: function() -> nil        -- вызывается при закрытии
+)
+
+-- Запрашивает подтверждение действия. Не останавливает выполнение кода.
+gui.ask(
+    -- сообщение (не переводится автоматически, используйте gui.str(...))
+    message: string,
+    -- функция, вызываемая при подтвержении
+    on_confirm: function() -> nil,
+    -- функция, вызываемая при отказе/отмене
+    [опционально] on_deny: function() -> nil,
+    -- текст кнопки подтвержения (по-умолчанию: "Да")
+    -- используйте пустую строку для значения по-умолчанию, если нужно указать no_text.
+    [опционально] yes_text: string
+    -- текст кнопки отказа (по-умолчанию: "Нет")
+    [опционально] no_text: string
+)
+```
+
+## Диалоговые страницы меню (устаревший подход)
+
+```lua
+-- Выводит окно с сообщением в виде страницы меню. Не останавливает выполнение кода.
 gui.alert(
     message: string,                -- сообщение (не переводится автоматически, используйте gui.str(...))
     on_ok: function() -> nil        -- вызывается при закрытии
 )
 
--- Запрашивает подтверждение действия. Не останавливает выполнение кода.
+-- Запрашивает подтверждение действия в виде страницы меню. Не останавливает выполнение кода.
 gui.confirm(
     -- сообщение (не переводится автоматически, используйте gui.str(...))
     message: string,
@@ -124,7 +149,7 @@ gui.load_document(
 
 -- Загружает шаблон в лояут
 gui.template(
-    -- имя шаблона в layouts/templates без пути и расширения 
+    -- имя шаблона в /layouts/templates без пути и расширения 
     name: string,
     -- таблица переменных (может быть использована в разметке)
     -- * Пр: <label>%{text}</label>

res/modules/internal/gui_util.lua

@@ -169,9 +169,11 @@ function gui.show_input_dialog(text, actual_callback, validator, confirm_text)
 end
 
 
-function gui.ask(text, on_yes, on_no)
+function gui.ask(text, on_yes, on_no, yes_text, no_text)
     on_yes = on_yes or function() end
     on_no = on_no or function() end
+    yes_text = yes_text == "" and "Yes" or (yes_text or "Yes")
+    no_text = no_text or "No"
 
     local id = "dialog_"..random.uuid()
 
@@ -188,11 +190,12 @@ function gui.ask(text, on_yes, on_no)
             <panel color='#507090E0' size='600' padding='16'
                    gravity='center-center' interval='4'>
                 <label margin='4'>%s</label>
-                <button onclick='DATA.on_yes()'>@Yes</button>
+                <button onclick='DATA.on_yes()'>@%s</button>
-                <button onclick='DATA.on_no()'>@No</button>
+                <button onclick='DATA.on_no()'>@%s</button>
             </panel>
         </container>
-    ]], id, string.escape_xml(text)), {on_yes=yes_callback, on_no=no_callback})
+    ]], id, string.escape_xml(text)), {on_yes=yes_callback, on_no=no_callback},
+        string.escape_xml(yes_text), string.escape_xml(no_text))
     input.add_callback("key:escape", no_callback, gui.root[id])
 end