[WiP] <RetVar/IF> open custom menu: title=<Var/String> description=<Var/String> optio

[Ogerboss]

[skip|else] if [not]|while [not]| <RetVar> = open custom menu: title=<Var/String> description=<Var/String> option array=<Var/Array>


START|[skip|else] if [not]|while [not]| = The possible 'Conditional' statements that can be used with this command.
<RetVar> = The return value, indicating the player's choice. The object type depends on the specifications the scripter made while defining the custom menu and can be any object/value, except NULL.
title=<Var/String> = The headline that appears in the upper left of the menu window.
description=<Var/String> = The hint message that will appear below on the headline, but right-aligned.
option array=<Var/Array> = An array object, that contains the custom menu that you want to show the user.

This command can be used to get input from a user in an interactive way without spamming his logbook with incoming questions. For a general overview of custom menus functionality and their internal structure see this topic.
To use it, first employ the predefined commands to set up a custom menu for the option array argument containing all the choices, information and options you need or build it by hand, if you know how the custom menus are set up. Then use this command to show the custom menu on the screen. If your menu contains any value selection lines, their return values will be stored in the variables you designated when adding the choice to the menu.
The <RetVar> of the custom menu itself will have the specified value for the selected item, when the player closes the menu properly by making his selection. Keep in mind that he can also close the menu abnormally by hitting the escape-key, in this case the return value seems to be -1 (as integer?) if the custom menu had at least one valid choice. Otherwise the return value seems to be not clearly defined.

Please keep in mind that it works as a pop-up, so if intend to show these menus not only on user-request, think about implementing a check for save environments to avoid frustated users, that lost a battle due to your pop-up.


Command Location:

»» Other
<RetVar/IF> open custom menu: title=<Var/String> description=<Var/String> option array=<Var/String>

tbd:
-check return value for aborting the menu
-linking to further articles

Examples necessary or just linking to the general discussion with examples (in future...)?

[mark_a_condren]