MessageBox Functions - Grisgram/gml-raptor GitHub Wiki

MessageBox_Configuration

Like many other modules of raptor, the MessageBox also has a configuration script, where you set the desired values for your game. It is named MessageBox_Configuration and can be found in the _GAME_SETUP_ folder of the project template, like all the other configuration scripts.

There's only a handful of settings, you can adapt, and for many games, the predefined values will work just fine.

Setting	Default	Description
`MESSAGEBOX_LAYER`	"MessageBox"	The layer, where the MessageBox shall appear
`MESSAGEBOX_WINDOW`	MessageBoxWindow	The Window object to use
`MESSAGEBOX_BUTTON`	TextButton	Object type to use for buttons
`MESSAGEBOX_TEXT_LABEL`	Label	Object type to use for text
`MESSAGEBOX_INNER_MARGIN`	32	The inner space from the window border to the text at all four sides
`MESSAGEBOX_BUTTON_SPACE`	12	The space between two buttons of the MessageBox
`MESSAGEBOX_BUTTON_MIN_WIDTH` `MESSAGEBOX_BUTTON_MIN_HEIGHT`	128 40	Set the minimum size of buttons in the MessageBox
`MESSAGEBOX_FONT`	undefined	If left undefined, the `scribble_default_font` will be used, which should have been set in the `onGameStart` function. You may enter any font name here as a string, even dynamically baked fonts at runtime. It is also ok, to name a Font Asset here

The MessageBox Class

This struct class creates a MESSAGEBOX_WINDOW and adds text and buttons to it.

There are two ways, how you can create a MessageBox:

Option 1: Using the MessageBox struct class with the constructor
Option 2: Using any of the predefined msg_show_* functions

Option 1 - The MessageBox constructor

// Create a MessageBox of type MESSAGEBOX_WINDOW on the layer "popup_instances", with the specified title and text
msgbox = new MessageBox(MESSAGEBOX_WINDOW, MESSAGEBOX_LAYER, "=warnings/title", "=warnings/server_error_retry_yn")
    .add_yes(function() {
        network_connect_to_server();
     }, "vk_enter")
    .add_no(function() {
        global._server_avail = false;
     }, "vk_escape")
   .show();

In this example, you see, that for the 'title' and 'text' parameters, the same rules apply as for all other raptor text properties. They must start with = to have the string automatically resolved through LG Localization.

You can also see, that there are add_yes and add_no functions invoked. Here is a list of all add_* functions available for standard buttons:

add_yes
add_no
add_ok
add_cancel
add_continue
add_retry
add_ignore
add_save

All these functions take two arguments: The callback to invoke, when this button gets pressed, and an optional hotkey, to also support keyboard input. You can specify any key-string in GameMaker-syntax. See GameMaker documentation for Keyboard Input.

The add_button function

You are not restricted to use standard buttons only in a MessageBox. There is one function available, that allows you to add any button. You may even use a ButtonObject different from the MESSAGEBOX_BUTTON set in the configuration.

/// @function		add_button(button_object, button_text, on_click_callback, hotkey = "")
/// @description	add any custom button to the window

It works like the other add_* functions, but you must also specify a button object and a text string.

Tip

The template contains default locale_en.json and a locale_de.json files, that hold all those standard button texts in english and german.
You should not delete or remove those standard button strings from these files if you plan to use the MessageBox functions of raptor!

You find the button strings in the json at "=global_words/buttons/*"

Other MessageBox functions

show

You have seen this one in the code example above.

/// @function		show()
/// @description	Displays the MessageBox on the specified layer in the constructor
/// @returns {struct}	'self' for command chaining

close

/// @function		close()
/// @description	Closes the MessageBox

Option 2: The msg_* functions

The second way to use the MessageBox functions is through the premade wrappers for standard MessageBoxes. These are easy to use, and they do nothing else behind the scenes besides calling new MessageBox(...) and adding all the buttons for you. This allows you to get a MessageBox window to show up in one line of code.

msg_show_ok

/// @function		msg_show_ok(title, text, ok_callback = undefined)
/// @description	Show a MessageBox with only an OK button
/// @param {string} title	title bar text
/// @param {string} text	text to show
/// @param {func}   ok_callback	Optional. Callback when OK is clicked
/// @returns {struct}		The MessageBox struct

msg_show_ok_cancel

/// @function		msg_show_ok_cancel(title, text, ok_callback = undefined, cancel_callback = undefined)
/// @description	Show a MessageBox with OK and Cancel buttons
/// @param {string} title	    title bar text
/// @param {string} text	    text to show
/// @param {func}   ok_callback	    Optional. Callback when OK is clicked
/// @param {func}   cancel_callback Optional. Callback when Cancel is clicked
/// @returns {struct}		    The MessageBox struct

msg_show_yes_no

/// @function		msg_show_yes_no(title, text, yes_callback = undefined, no_callback = undefined)
/// @description	Show a MessageBox with Yes and No buttons
/// @param {string} title	 title bar text
/// @param {string} text	 text to show
/// @param {func}   yes_callback Optional. Callback when Yes is clicked
/// @param {func}   no_callback	 Optional. Callback when No is clicked
/// @returns {struct}		 The MessageBox struct

msg_show_yes_no_cancel

/// @function		msg_show_yes_no_cancel(title, text, 
///                        yes_callback = undefined, no_callback = undefined, cancel_callback = undefined)
/// @description	Show a MessageBox with Yes and No buttons
/// @param {string} title	    title bar text
/// @param {string} text	    text to show
/// @param {func}   yes_callback    Optional. Callback when Yes is clicked
/// @param {func}   no_callback	    Optional. Callback when No is clicked
/// @param {func}   cancel_callback Optional. Callback when Cancel is clicked
/// @returns {struct}		 The MessageBox struct

msg_show_retry_ignore

/// @function		msg_show_retry_ignore(title, text, 
///                         retry_callback = undefined, ignore_callback = undefined)
/// @description	Show a MessageBox with Yes and No buttons
/// @param {string} title	    title bar text
/// @param {string} text	    text to show
/// @param {func}   retry_callback  Optional. Callback when Yes is clicked
/// @param {func}   ignore_callback Optional. Callback when No is clicked
/// @returns {struct}		 The MessageBox struct

msg_show_save_cancel

/// @function		msg_show_save_cancel(title, text, 
///                         save_callback = undefined, cancel_callback= undefined)
/// @description	Show a MessageBox with Yes and No buttons
/// @param {string} title	    title bar text
/// @param {string} text	    text to show
/// @param {func}   save_callback   Optional. Callback when Yes is clicked
/// @param {func}   cancel_callback Optional. Callback when No is clicked
/// @returns {struct}		 The MessageBox struct