[MOD/API] Simple Menu API

[SirNukes]

Download: https://github.com/bvbohnen/x4-projects/releases
Documentation: https://github.com/bvbohnen/x4-projects ... ctions.md


X4 Simple Menu API

This extension adds support for generating menus using mission director scripts in X4. A lua backend handles the details of interfacing with the x4 ui system.

Two types of menus are supported: options menus that are integrated with the standard x4 options, and standalone menus which will display immediately.

Additionally, a simplified interface is provided for adding options to an extension. These options are simple buttons and sliders that display in the main Extension Options menu.


Requirements

• Lua Loader API extension
  - https://github.com/bvbohnen/x4-lua-loader-api.git

Usage

• Basic extension options
  - Call Register_Option with a name, default value, widget type, and callback.
  - Callback will receive the new value whenever the player changes the option.
• Standalone menu
  - Call Create_Menu to open a new menu, closing any others.
  - Fill the menu with rows and widgets, specifying callback cues.
  - Callback cues will be signalled on player input.
  - Access through a trigger condition of your choice.
• Options menu
  - Call Register_Options_Menu to register your menu with the backend.
  - Create a cue which will make the rows and widgets as above.
  - Set the above cue as the onOpen callback target during registration.
  - Access through the "Extension Options" page of the main menu.

Examples

• Simple Option with setup and callback, enabling debug logging:

  Code: Select all

    <cue name="Reset_On_Reload" instantiate="true">
      <conditions>
        <event_cue_signalled cue="md.Simple_Menu_Options.Reloaded"/>
      </conditions>
      <actions>
        <signal_cue_instantly
          cue="md.Simple_Menu_Options.Register_Option"
          param = "table[
            $id         = 'debug_menu_api',
            $name       = 'Enable menu api debug logs',
            $mouseover  = 'Prints extra api status info to the debug log',
            $default    = 0,
            $type       = 'button',
            $callback   = OnChange,
            ]"/>
      </actions>
    </cue>
    <cue name="OnChange" instantiate="true">
      <conditions>
        <event_cue_signalled />
      </conditions>
      <actions>
        <set_value name="md.My_Extension.Globals.$DebugChance"
                    exact ="if (event.param.$value) then 100 else 0"/>
      </actions>
    </cue>
  

• Standalone menu:

  Code: Select all

    <cue name="Open_Menu" instantiate="true" namespace="this">
      <conditions>
        <event_cue_signalled/>
      </conditions>
      <actions>
        <signal_cue_instantly
          cue = "md.Simple_Menu_API.Create_Menu"
          param = "table[
            $columns = 1, 
            $title   = 'My Menu',
            $width   = 500,
            ]"/>
        <signal_cue_instantly cue="md.Simple_Menu_API.Add_Row"/>
        <signal_cue_instantly
          cue = "md.Simple_Menu_API.Make_Label"
          param = "table[$col=1, $text='Hello world']"/>
      </actions>
    </cue>
  

• Options menu:

  Code: Select all

    <cue name="Register_Options_Menu" instantiate="true" namespace="this">
      <conditions>
        <event_cue_signalled cue="md.Simple_Menu_API.Reloaded"/>
      </conditions>
      <actions>
        <signal_cue_instantly
          cue="md.Simple_Menu_API.Register_Options_Menu"
          param = "table[
            $id = 'my_unique_menu',
            $columns = 1, 
            $title = 'My Options',
            $onOpen = Build_Options_Menu
            ]"/>
      </actions>
    </cue>
  
    <cue name="Build_Options_Menu" instantiate="true" namespace="this">
      <conditions>
        <event_cue_signalled/>
      </conditions>
      <actions>            
        <signal_cue_instantly cue="md.Simple_Menu_API.Add_Row"/>
        <signal_cue_instantly
          cue="md.Simple_Menu_API.Make_Label"
          param = "table[$col=1, $text='Hello world']"/>
      </actions>
    </cue>
  

[teleportationwars]

This should get more attention.

Off the top of my head it handles:
icons, scaling, resizing, colors, edit boxes, dropdowns, buttons, partial redrawing, scrolling, fonts, sliders, checkboxes

all of which have examples and documentation like:

<!--@doc-cue
Make a "dropdown" selection cell.
Adds to the most recent row.
Note: indices start at 1.

Param: Table with the following items
* col, colspan, id, echo
- Standard api args
* scaling, width, height, x, y, mouseOverText
- Standard widget properties
* cellBGColor, uiTriggerID
- Standard cell properties
* options
- List of tables describing each option.
- Each subtable has these fields:
* text = ""
- String, option text.
* icon = ""
- String, icon name.
* id
- Optional string or number, identifier of the option.
- Returned to callbacks to indicate option selected.
- Defaults to the option's list index (1-based).
* displayremoveoption = false
- Bool, if true the option will show an 'x' that the player can
click to remove it from the dropdown list.
* onDropDownActivated
- Cue to call when the player activates the dropdown.
* onDropDownConfirmed
- Cue to call when the player selects an option.
* onDropDownRemoved
- Cue to call when the player removes an option.
* startOption = ""
- String or number, id of the initially selected option.
- Updateable
* active = true
- Bool, if the widget is active.
* bgColor = Helper.defaultButtonBackgroundColor
- Color of background.
* highlightColor = Helper.defaultButtonHighlightColor
- Color when highlighted.
* optionColor = Helper.color.black
- Color of the options.
* optionWidth, optionHeight = 0
- Dimensions of the options.
* allowMouseOverInteraction = false
* textOverride = ""
* text2Override = ""
* text
- TextProperty
* text2
- TextProperty
* icon
- IconProperty
* hotkey
- HotkeyProperty


onDropDownActivated event returns:
* row, col, echo, event, id

onDropDownConfirmed event returns:
* row, col, echo, event, id
* option_id
- String or number, id of the selected option.

onDropDownRemoved event returns:
* row, col, echo, event, id
* option_id
- String or number, id of the removed option.

-->

it even has error handling.

[Shuulo]

This should be pinned IMO

[spin1/2]

Hello,

is it possible to show a picture in one col only?

thx for your help and work

[SirNukes]

is it possible to show a picture in one col only?

Not that I know of. Cells can stretch across a row, but not down a column.

[spin1/2]

is it possible to show a picture in one col only?

Not that I know of. Cells can stretch across a row, but not down a column.

Sorry, my question wasnt correct. I think there are a posiiblity to show pictures in the backround of the window. Can I show pictures in single Cells as well?
There isnt such a "widget" in your API Function.md.

thx for help

[SirNukes]

I think there are a posiiblity to show pictures in the backround of the window. Can I show pictures in single Cells as well?

The Icon widget handles simple picture display in a single cell.

As a heads up, if you put in a large picture and don't specify the widget height/width, it may be too large for the table which will lead to a blank menu and error message in the log.

[spin1/2]

Hey, me again

I dont know if this is a stupid question:
Is it possible t use text from the t-folder. I dont know how to address "page/t id" in your text widget.

thx for your help

[SirNukes]

I dont know if this is a stupid question:
Is it possible t use text from the t-folder. I dont know how to address "page/t id" in your text widget.

It's exactly the same as normal, using braces:
https://www.egosoft.com:8444/confluence ... sOperators

[kuertee]

Hi, thanks for this mod.

Is it possible to have fractional increments for "slidercell"?

[kuertee]

Hi, thanks for this mod. Is it possible to have fractional increments for "slidercell"?

Never mind. I found it: "step" argument.

[kuertee]

Hi, I'm trying to create an Extension Options for my mod, and I'm using the Simple Menu API as shown in the Options menu example in the original post above (and in the read-me).
I.e.:

Spoiler

Show

Code: Select all

		<cue name="StartSMO" instantiate="true" namespace="this">
			<conditions>
				<event_cue_signalled cue="md.Simple_Menu_Options.Reloaded"/>
			</conditions>
			<actions>
				<debug_text text="namespace" />
				<signal_cue_instantly cue="md.Simple_Menu_API.Register_Options_Menu"
					param="table[
						$id = 'kuertee_npc_reactions_mod_options_menu',
						$columns = 1,
						$title = {111820,688850},
						$onOpen = Build_Options_Menu
					]" />
			</actions>
		</cue>
		<cue name="Build_Options_Menu" instantiate="true" namespace="this">
			<conditions>
				<event_cue_signalled />
			</conditions>
			<actions>
				<debug_text text="namespace" />
			</actions>
		</cue>

However, it looks like my menu registration is occurring twice as shown by the error below.

Code: Select all

[Scripts] 448509.12 *** Context:md.kuertee_npc_reactions_config.StartSMO<inst:10c4095>: StartSMO
[Scripts] 448509.88 *** Context:md.kuertee_npc_reactions_config.StartSMO<inst:10bdf44>: StartSMO
[General] 448509.88 ======================================
[=ERROR=] 448509.88 Simple Menu API: command "Register_Options_Menu" produced error: ...ons\sn_mod_support_apis\lua_simple_menu_options_menu.txt:354: Submenu id conflicts with prior registered id: kuertee_npc_reactions_mod_options_menu
[General] 448509.88 ======================================

Experienced these errors? Any ideas/guesses on why they occur?

EDIT 2: removed this:

Spoiler

Show

[strike]EDIT: And it looks like my OnChange callback is occurring at load of the game before I interact with sliders.[/strike]

[SirNukes]

Um... if md.Simple_Menu_Options.Reloaded were being signaled twice, you would also be seeing duplicate id errors for the stock menus. If it is just an error for your setup, I would look to multiple copies of your cue being active.

[Scripts] 448509.12 *** Context:md.kuertee_npc_reactions_config.StartSMO<inst:10c4095>: StartSMO
[Scripts] 448509.88 *** Context:md.kuertee_npc_reactions_config.StartSMO<inst:10bdf44>: StartSMO
Doesn't that indicate there are two copies of StartSMO? The indentation of your code block suggests it is nested under some higher cue.

[kuertee]

scrapped 'coz I created a new post about the same error.
but here's this original post:

Spoiler

Show

... snipped ...Doesn't that indicate there are two copies of StartSMO? The indentation of your code block suggests it is nested under some higher cue.

Yeah, I thought the same, but, unfortunately, no. Here's a SublimeText search of the folder for "StartSMO"

Code: Select all

Searching 17 files for "StartSMO" (regex)
E:\games\Steam\steamapps\common\X4 Foundations\extensions\kuertee_npc_reactions\md\kuertee_npc_reactions_config.xml:
    8  			</actions>
    9  		</cue>
   10: 		<cue name="StartSMO" instantiate="true" namespace="this">
   11  			<conditions>
   12  				<event_cue_signalled cue="md.Simple_Menu_Options.Reloaded"/>
1 match in 1 file

And the saved file I test it from doesn't have my mod or SMO extensions data in it.

EDIT: And in regards to indentation, I use tabs rather than spaces. And StartSMO is a child of the top-level "cues".

Spoiler

Show

Code: Select all

<?xml version="1.0" encoding="utf-8"?>
<mdscript name="kuertee_npc_reactions_config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="md.xsd">
	<cues>
		<cue name="Config" namespace="this" version="1">
			<delay exact="5s" />
			<actions>
				<debug_text text="namespace + ' ' + md.kuertee_npc_reactions.NPCReactions" />
			</actions>
		</cue>
		<cue name="StartSMO" instantiate="true" namespace="this">

[kuertee]

And ... I'm finding that I'm might be missing something somewhere. Mind checking out this bit of code quickly?

To step through the code ...
1. I register my Options Menu like this:

Spoiler

Show

Code: Select all

<cue name="StartSMO" instantiate="true">
			<conditions>
				<event_cue_signalled cue="md.Simple_Menu_Options.Reloaded"/>
			</conditions>
			<actions>
				<debug_text text="''" />
				<signal_cue_instantly cue="md.Simple_Menu_API.Register_Options_Menu"
					param="table[
						$id = 'kuertee_npc_reactions_mod_options_menu',
						$columns = 2,
						$title = 'kuertee: NPC reactions',
						$onOpen = Build_Options_Menu
					]" />
			</actions>
		</cue>

2. I build one row with 2 columns.
The 1st column is a "Make_Text" with the text "row 1, col 1".
The 2nd column is a "Make_Slider"

Spoiler

Show

Code: Select all

<cue name="Build_Options_Menu" instantiate="true">
			<conditions>
				<event_cue_signalled />
			</conditions>
			<actions>
				<debug_text text="''" />
				<signal_cue_instantly cue="md.Simple_Menu_API.Add_Row"/>
				<!-- <signal_cue_instantly cue="md.Simple_Menu_API.Make_Text" param="table[$col=1, $text='row 1, col 1']"/> -->
				<signal_cue_instantly
					cue = "md.Simple_Menu_API.Make_Slider"
					param = "table[
					$col = 1,
					$id = 'slider_1',
					$text = 'slider_1',
					$min = 0,
					$max = 5,
					$step = 0.25,
					$default = 0.25,
					$suffix='%',
					$onSliderCellChanged = OnSMOInputChange
				]"/>
			</actions>
		</cue>

The errors that I get are:

Spoiler

Show

Code: Select all

[Scripts] 448659.66 *** Context:md.kuertee_npc_reactions_config.Build_Options_Menu<inst:83f5e9>: 
[General] 448659.66 ======================================
[=ERROR=] 448659.66 E:/games/Steam/steamapps/common/X4 Foundations/.../helper.lua(4480): createDescriptor(): Invalid slidercell descriptor. Error: No text information given.
[General] 448659.66 ======================================
[General] 448659.66 ======================================
[=ERROR=] 448659.66 E:/games/Steam/steamapps/common/X4 Foundations/(): (from presentation 'ui/widget/presentations/widget_fullscreen/widget_fullscreen.bgf') CreateTable(): invalid parameters - table content parameter is invalid. Erroroutput: Invalid value for column content for row 1 and column 3. Content element is missing (nil).

So ... thinking that Make_Slider requires to 2 columns and that I don't need to populate column 1 with the slider's name, I remove the Make_Text for column 1 and set the column for Make_Slider to "$col=2".
But I get a similar error - but for column 2 instead of column 3.

Spoiler

Show

Code: Select all

[Scripts] 448659.66 *** Context:md.kuertee_npc_reactions_config.Build_Options_Menu<inst:83d8d7>: 
[General] 448659.66 ======================================
[=ERROR=] 448659.66 E:/games/Steam/steamapps/common/X4 Foundations/.../helper.lua(4480): createDescriptor(): Invalid slidercell descriptor. Error: No text information given.
[General] 448659.66 ======================================
[General] 448659.66 ======================================
[=ERROR=] 448659.66 E:/games/Steam/steamapps/common/X4 Foundations/(): (from presentation 'ui/widget/presentations/widget_fullscreen/widget_fullscreen.bgf') CreateTable(): invalid parameters - table content parameter is invalid. Erroroutput: Invalid value for column content for row 1 and column 2. Content element is missing (nil).

Here's my full code. It should be easy to copy to an MD script quickly for checking.
It creates the Options Menu as expected. But row and widget creation fails as explained above.

Spoiler

Show

Code: Select all

<?xml version="1.0" encoding="utf-8"?>
<mdscript name="kuertee_npc_reactions_config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="md.xsd">
	<cues>
		<cue name="Config" namespace="this" version="1">
			<actions>
				<debug_text text="''" />
			</actions>
		</cue>
		<cue name="Text">
			<actions>
				<debug_text text="''" />
			</actions>
		</cue>
		<cue name="StartSMO" instantiate="true">
			<conditions>
				<event_cue_signalled cue="md.Simple_Menu_Options.Reloaded"/>
			</conditions>
			<actions>
				<debug_text text="''" />
				<signal_cue_instantly cue="md.Simple_Menu_API.Register_Options_Menu"
					param="table[
						$id = 'kuertee_npc_reactions_mod_options_menu',
						$columns = 2,
						$title = 'kuertee: NPC reactions',
						$onOpen = Build_Options_Menu
					]" />
			</actions>
		</cue>
		<cue name="Build_Options_Menu" instantiate="true">
			<conditions>
				<event_cue_signalled />
			</conditions>
			<actions>
				<debug_text text="''" />
				<signal_cue_instantly cue="md.Simple_Menu_API.Add_Row"/>
				<!-- <signal_cue_instantly cue="md.Simple_Menu_API.Make_Text" param="table[$col=1, $text='row 1, col 1']"/> -->
				<signal_cue_instantly
					cue = "md.Simple_Menu_API.Make_Slider"
					param = "table[
					$col = 1,
					$id = 'slider_1',
					$text = 'slider_1',
					$min = 0,
					$max = 5,
					$step = 0.25,
					$default = 0.25,
					$suffix='%',
					$onSliderCellChanged = OnSMOInputChange
				]"/>
			</actions>
		</cue>
		<cue name="OnSMOInputChange" instantiate="true">
			<conditions>
				<event_cue_signalled />
			</conditions>
			<actions>
				<debug_text text="event.param.$id + ' to: ' + event.param.$value" />
			</actions>
		</cue>
	</cues>
</mdscript>

Any help is appreciated. Thank you.

EDIT: Also, I'm still getting the double trigger of md.Simple_Menu_Options.Reloaded.

[SirNukes]

At a guess, slider cells might not accept float values. This api mostly passes the widget values straight to the egosoft ui code; I don't know what all of the limitations are.

The column count in errors will be +1 since the options menu has an automatic extra left column under the back button.

For double registration (or whatever is happening), turn on simple menu debugging (in extension options) and check which commands are being sent from md to lua. There should be two Register_Options_Menu for different stock menus, for instance.

[kuertee]

At a guess, slider cells might not accept float values. ...snipped .....

Yeah, sliders allow floats. They work when I use "md.Simple_Menu_Options.Register_Option" instead of "md.Simple_Menu_API.Make_Slider".

The column count in errors will be +1 since the options menu has an automatic extra left column under the back button.

Ahhh.... gotcha.

For double registration (or whatever is happening), turn on simple menu debugging (in extension options) ...snipped .....

Will do.

I'll check all this out tomorrow.

Thanks, again!

[SirNukes]

The api documentation (which I write down so I can forget it) says slider text fields are TextProperty type, which means you gave a string where the egosoft backend expects a table.

[kuertee]

The api documentation (which I write down so I can forget it) says slider text fields are TextProperty type, which means you gave a string where the egosoft backend expects a table.

Nice! Yes, thank you, that worked!

EDIT: And the slider themselves fit in one column, so I can make a menu with 2 columns, one for the Make_Text label and the other one for the Make_Slider.

[kuertee]

Hi again, I can confirm that on 3rd party mods ...
listeners for md.Simple_Menu_Options.Reloaded are triggered twice when games without SN Mod APIs are loaded,
but only once on games already saved with the SN Mod APIs.