MessageBox Functions

Window & MessageBox

The Window object (and its child, the MessageBoxWindow) add a group of variables to the mix that allow definition of the windows' behavior:

title	The text in the title bar of the window. The same LG Localization options apply as for text and tooltip_text
title_color	Text color of the title
scribble_title_align	Same as scribble_text_align, but for the title text
window_is_movable	Allow window dragging yes/no
title_xoffset title_yoffset	Same as the text_offsets, but for the title text

You should see the Window object as a generic Object that will draw a window frame and react on mouse events for dragging, but if you use a Window just with the text and title properties set, it's more or less just a MessageBox. Instead you should create a child of the Window object and draw the UI of your window in the Draw or DrawGUI events. At least, that's the thought behind the Window object.

For MessageBoxes, there is a helper class available that allows quick creation of messages to the user.

There are two ways, to create a MessageBox:

• Using the MessageBox struct class with the constructor
• Using any of the predefined msg_show_* functions

The MessageBox class

This struct class creates a MessageBoxWindow and adds text and buttons to it.
All the add_* methods are chainable, so you can define your MessageBox in one go.

msgbox = new MessageBox(MessageBoxWindow, "popup_instances", "=warnings/title", "=warnings/server_error_retry_yn")
    .add_yes(function() {
        network_connect_to_server();
     })
    .add_no(function() {
        global._server_avail = false;
     })
   .show();

From this example you see, that for the title and text parameters the same rules (starting with =) apply to have string automatically resolved through LG Localization.

---

NOTE: Below you will find the docs for the add_* functions, which create standard buttons like Yes, No, OK, Cancel,... etc.
Of course, even standard buttons need to be localized, so these functions all use the strings that come with raptor in the project template.

The template contains a default locale_en.json and a locale_de.json that hold all those standard button texts.
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/*"

---

MessageBox (constructor)

/// @function		MessageBox(window_object, layer_name, message_title, message_text)
/// @description	Create a new messagebox window with a specified window object
/// @param {object} window_object	the object to create 			
/// @param {string} layer_name		the layer where the object shall be created
/// @param {string} message_title	title bar text
/// @param {string} message_text	text to show
/// @returns {struct}			the messagebox struct

show

/// @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

add_button

/// @function		add_button(button_object, button_text, on_click_callback)
/// @description	add any custom button to the window
/// @param {object}	button_object
/// @param {string}	button_text (LG resolvable)
/// @param {function	on_click_callback
/// @param {enum=msgbox_key.none} hotkey
/// @returns {struct}	'self' for command chaining

add_*

This is a group of identical shortcut functions that add a standard button with localized text.
As they are all the same, only the description of the add_yes function is shown here.

Available are:

• add_yes
• add_no
• add_ok
• add_cancel
• add_continue

/// @function		add_yes(yes_button_object, on_yes_callback)
/// @description	add a yes-button to the window
/// @param {object}	yes_button_object 			
/// @param {function}	on_yes_callback
/// @param {enum=msgbox_key.none} hotkey
/// @returns {struct}	'self' for command chaining

The msg_* functions

The second way of using the MessageBox functions is to use the premade wrappers for standard MessageBoxes, which are easy to use and they do nothing else behind the scenes, than calling new MessageBox(...) and add all the buttons for you, to have that window showing up as a one-liner.

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